Skip to content

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 Email 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

  1. Overwrite jobs.status and add more columns (interview_at, rejected_at, ...). This adds a column for every stage and still loses the order and the source.
  2. Use an append-only application_events table and keep jobs.status as 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.
  3. Use events only, and derive the status by query. This is pure, but every list and filter becomes a lateral join.

Status vocabulary

  1. Split stage and outcome as job-ops does. This is the most precise, but it breaks the flat JobStatus that the API, the CLI and the frontend already use.
  2. Keep the flat enum and add the states that are missing: in_review, assessment and withdrawn. Interview rounds stay one interview status, and the round goes on the event (interview_kind: recruiter, technical, onsite, final).

What an email may do

  1. Apply high-confidence matches automatically (job-ops at 95% or more).
  2. Never apply anything automatically. Every match is a suggestion that the user accepts or ignores.

How Kairos reads mail

  1. Connect to Gmail and Graph directly with Kairos' own OAuth. This duplicates Kioku's sync, token rotation and backfill.
  2. Read through Kioku's MCP endpoint (mail_search, mail_read), behind a MailSource port, 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)

  1. 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) and note. Phase 2 adds mail_suggestion_id. These are plain columns, not a detail JSONB, so each one is typed and can be queried. The table is indexed on (owner_id, job_id, occurred_at). The same migration adds jobs.status_changed_at, a cache of the latest event's occurred_at; it orders kairos apps list and 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.

  1. Port: MailSource in kairos.core.interfaces. It has three methods:
  2. accounts(): each mailbox and when Kioku last synced it;
  3. page(account, cursor): message headers, newest first;
  4. 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 no applied_at, still has none after it, because the date is unknown. kairos apps list does not depend on applied_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's lastSyncedAt and 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-client pair in 1Password (01 Personal Development), injected through op run. A token issued for Kairos alone (tags project/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.