0006: Application timeline, and status updates suggested from Kioku mail¶
- Date: 2026-11-10
- Status: accepted
Problem¶
A job records only where it stands now: jobs.status, applied_at and one notes
field (migration 008). Changing the status overwrites it. Nothing records when an
interview was offered, who made a change (the user, an agent, an email), or which
message it came from. The vocabulary has no state for "the company has the application
and is looking at it", or for an application the user withdrew.
Replies arrive by email and are never read. The user's mail is already backed up in Kioku (three personal mailboxes, synced about every five minutes), but Kairos has no way to read it. The user has to copy each reply into a status change by hand, and mostly does not.
The CLI comes first. The web view follows later and reads the same API.
Prior art¶
| Project | Timeline | What we take | |
|---|---|---|---|
| job-ops (about 4.1k stars, self-hosted, same domain) | stage_events: from_stage, to_stage, occurred_at, metadata JSON, outcome. Stage and outcome are separate (closed + rejected / withdrawn / ghosted). |
post_application_messages: one row per message, unique on provider + account + external id. It stores the sender, domain, subject, received_at, snippet, classification label and confidence, matched_job_id and processing_status. It never stores the body. At 95% confidence or more it applies the update; from 50% to 94% it queues the message for review with a suggested job; under 50% it queues it as an orphan or ignores it. |
An append-only event table with from/to. One row per message, holding metadata only, with an idempotency key. A review inbox. |
| JobSync (MIT, Next.js + Prisma) | JobStage per job: stage_type, occurred_at, outcome, notes, plus interview fields (format, duration, interviewers). One row has is_current, enforced by a partial unique index. |
none | Interview details belong on the event, not as extra statuses. |
| ShortList (AGPL, small) | Every automatic change appears on the timeline with its source, and the user can undo it. | email + job portals | A source on every event, and undo by a compensating event. |
| ApplyTrail, jobtool | none | An LLM labels Gmail messages as applied / interview / offer / rejected. | Four labels cover most replies. Every project that skips matching ends up with duplicate applications. |
Options¶
Where the history lives
- Overwrite
jobs.statusand add more columns (interview_at,rejected_at, ...). This adds a column for every stage and still loses the order and the source. - Use an append-only
application_eventstable and keepjobs.statusas a cache of the latest event. Both are written in one transaction by one service. This is job-ops' design. Existing filters (jobs list --status) keep working. - Use events only, and derive the status by query. This is pure, but every list and filter becomes a lateral join.
Status vocabulary
- Split stage and outcome as job-ops does. This is the most precise, but it breaks the
flat
JobStatusthat the API, the CLI and the frontend already use. - Keep the flat enum and add the states that are missing:
in_review,assessmentandwithdrawn. Interview rounds stay oneinterviewstatus, and the round goes on the event (interview_kind: recruiter, technical, onsite, final).
What an email may do
- Apply high-confidence matches automatically (job-ops at 95% or more).
- Never apply anything automatically. Every match is a suggestion that the user accepts or ignores.
How Kairos reads mail
- Connect to Gmail and Graph directly with Kairos' own OAuth. This duplicates Kioku's sync, token rotation and backfill.
- Read through Kioku's MCP endpoint (
mail_search,mail_read), behind aMailSourceport, so that another source can replace it later.
Choice¶
History option 2, vocabulary option 2, email option 2 and mail option 2. Email option 2 follows the project rule that the user reviews every change. Auto-apply can become an opt-in setting later, once real messages show how accurate the matching is.
Phase 1: timeline and CLI (no mail)¶
- Migration 016,
application_events:id,owner_id,job_id(cascade),from_status,to_status,occurred_at(when it happened, which the user may backdate),recorded_at,source(manual|agent|email),interview_kind,reverts(the undone event's id) andnote. Phase 2 addsmail_suggestion_id. These are plain columns, not adetailJSONB, so each one is typed and can be queried. The table is indexed on(owner_id, job_id, occurred_at). The same migration addsjobs.status_changed_at, a cache of the latest event'soccurred_at; it orderskairos apps listand gives "days in this status".
The backfill writes an applied event at applied_at for each job that has one. A
job already past applied gets a second event into its status. Its date is unknown, so
that event is dated at migration time and says so in its note.
2. JobStatus gains in_review, assessment and withdrawn. They are strings in the
database, so no enum migration is needed. PRE_APPLICATION_STATUSES does not change.
3. ApplicationTracker service (in kairos.api.services). It is the only place that
changes the status: it writes the event, updates jobs.status, and sets applied_at
and status_changed_at, all in the DI transaction. applied_at is set while the job
is in an application status (applied through withdrawn). The first step into one
stamps it, even straight to interview or rejected; leaving those statuses clears it.
POST /jobs/{id}/apply and PATCH /jobs/{id}/status call it. Any status may follow
any other, because real processes skip steps. It refuses:
- a change to the current status (409);
- a time in the future, more than 5 minutes ahead (422);
- a time before the job's last change (422). This keeps every event's from_status
correct; undo the later change first.
The two older routes keep their behaviour. Setting the current status again only
updates the job's notes and records no event. apply on a job already past applied
keeps its status instead of moving it back to applied.
4. API: GET /api/v1/jobs/{id}/events lists the timeline, oldest first.
POST /api/v1/jobs/{id}/events records a change with to_status, occurred_at?,
note?, interview_kind? and source?, and returns 201 with a Location header.
An agent sends source=agent to the same endpoint, so it needs no separate path.
email is refused until phase 2's review writes it.
POST /api/v1/jobs/{id}/events/{event_id}/revert undoes the latest event.
GET /api/v1/applications lists jobs in an application status, latest change first,
each with its last event, and takes an optional status. All lists use cursor
pagination.
5. CLI (kairos apps):
- kairos apps list [--status interview]: the company, role, current status, days
in that status, and the last change.
- kairos apps log <job>: the timeline.
- kairos apps set <job> <status> [--at 2026-11-03] [--note ...] [--kind technical]
- kairos apps undo <job>: writes an event that reverts the latest one (reverts),
so the history keeps both events.
- jobs apply and jobs status stay and call the same service.
Phase 2: suggestions from Kioku mail¶
Built as below. It differs from the first draft of this section in four places: how mail is read, the table's name and key, the sync watermark, and where the review lives.
- Port:
MailSourceinkairos.core.interfaces. It has three methods: accounts(): each mailbox and when Kioku last synced it;page(account, cursor): message headers, newest first;read(id): the plain-text body.
The adapter is kairos.mail.kioku. It sends JSON-RPC tools/call requests over plain
HTTP to [tracking] kioku_url (default https://kioku.misoto22.com/api/v1/mcp). Kioku
answers each request on its own, with no session, and puts the result in
structuredContent, so no MCP library is needed. It authenticates through Cloudflare
Access with a service-token pair read from KAIROS_KIOKU_ACCESS_CLIENT_ID and
KAIROS_KIOKU_ACCESS_CLIENT_SECRET. Those are injected from op:// references with
op run; no value is stored in config.
Kairos pages each mailbox newest first back to a watermark and does not use Kioku's
text search. One cursor per mailbox is complete and cheap after the first run. A search
would need one query per company, and Kioku's mail_search with a query failed through
one client during the build.
7. Migration 017:
- mail_suggestions, one row per job-related message: owner_id, account,
external_id (Kioku's message id, unique with owner and account), thread_id,
sender, sender_name, subject, received_at, snippet (at most 300
characters), label, confidence, job_id, reason, state and decided_at.
label is one of acknowledged (accepted as applied), in_review, assessment,
interview, offer, rejected and other. state is one of pending,
accepted, ignored and orphan (job-related, but no job matched). The body is
never stored; Kioku keeps it.
- mail_sync_cursors: one watermark per owner and mailbox (synced_until).
- application_events.mail_suggestion_id, nullable, set null when the suggestion is
deleted.
8. Candidate filter (no LLM). Candidates are the jobs in an application status. On a
first sync, a mailbox is read back to the earliest applied_at among them, but no
more than [tracking] mail_lookback_days (default 60). A message is kept if any of
these holds:
- the sender is in a candidate's contact_emails;
- the sender's domain is a known ATS, listed in kairos/core/ats_domains.toml;
- a candidate's company name appears in the subject or the sender's name.
Messages that match nothing are dropped and not stored.
9. Classification (one LLM call per kept message). The model gets the subject,
sender and body, cut to 4,000 characters, plus the candidate jobs. It returns the
label, the matched job id (or none), a confidence and a one-line reason. The row is
keyed on external_id, so a message already stored is not classified again. Calls
are recorded in llm_usage as mail_classification.
The watermark never moves past the mailbox's own lastSyncedAt. Without that limit,
mail Kioku has not pulled in yet would be skipped for good. A sync reports each
mailbox with lastSyncedAt and flags it as stale when that is more than a day old.
10. Review (API: POST /mail-suggestions/sync, GET /mail-suggestions,
POST /mail-suggestions/{id}/accept, POST /mail-suggestions/{id}/ignore):
- kairos apps sync [--since 2026-10-01]: reads new mail, classifies it, and prints
the suggestions.
- kairos apps inbox: lists the pending and orphan ones.
- kairos apps accept <id> [--job <job>] [--status <status>]: records an email
event dated at the message's received_at, linked to the suggestion. An
acknowledged suggestion for a job already in an application status is accepted
without an event.
- kairos apps ignore <id>
The tracker's rules still apply. A message older than the job's last change cannot be
accepted until that change is undone.
The optional background loop, `[tracking] mail_sync_minutes` (default 0, off),
works like the harvest loop and only creates suggestions.
Not in scope¶
- Tasks, follow-up reminders, interviewer contacts, and "ghosted" detection (no reply in N days). These are useful later, and they can all be derived from the event table.
- Writing to the mailbox (labels, replies).
- The work mailboxes. They are disabled in Kioku, and the search covers only the accounts Kioku reports as enabled.
Prerequisites and risks¶
-
A job that was
rejected(or similar) before migration 016, with noapplied_at, still has none after it, because the date is unknown.kairos apps listdoes not depend onapplied_at. -
Kioku
personal-primary(henrycxw@gmail.com) last synced on 2026-10-15. Most applications go to that address. Kioku's sync has to recover before phase 2 is useful. A phase 2 sync must print each account'slastSyncedAtand warn when it is older than a day, because an empty result from a stale mailbox is not evidence that no reply came. - Kairos needs a Cloudflare Access service token. The build was checked with the existing
kioku-mcp-clientpair in 1Password (01 Personal Development), injected throughop run. A token issued for Kairos alone (tagsproject/kairos,provider/cloudflare,env/development) can be revoked without cutting off the other Kioku client. - Matching recruiter mail from an agency or a shared ATS address may be wrong. Because
every suggestion goes to review, a wrong match costs one
ignore.