khive-pack-session 0.9.0

Session verb pack - store/list/resume/export over the notes substrate
Documentation
# khive-pack-session

Session pack: registers the `session` note kind and five agent-facing verbs
for storing and retrieving agent-session records (transcripts or summaries)
over the notes substrate (ADR-083).

## Verbs

- `session.store(content, title?, provider?, provider_session_id?, tags?)` —
  persist a session record. `provider_session_id` is the provider-native
  continuity anchor (not a khive UUID); `(provider, provider_session_id)` is
  the strongest grouping key when both are present.
- `session.list(limit?, offset?, provider?, agent_id?, since?)` — browse
  stored sessions, newest first. `agent_id` matches the legacy
  `properties.agent_id` field and `since` is an inclusive RFC 3339 creation
  timestamp. Summaries omit `content`.
- `session.resume(id)` — fetch one session's full content by full UUID or
  8+ hex short prefix.
- `session.export(id, format?)` — serialize a session as `json` (default) or
  `markdown`.
- `session.search(query, limit?, since?, source?, cwd?)` — tenant-scoped mirror
  search. The public handler remains unavailable until transcript deletion and
  resume/export continuity support are available.

```text
request(ops="session.store(content=\"...\", provider=\"codex\", provider_session_id=\"abc\")")
request(ops="session.list(limit=20, provider=\"codex\")")
request(ops="session.list(agent_id=\"lambda:worker\", since=\"2026-08-01T00:00:00Z\")")
request(ops="session.resume(id=\"a1b2c3d4\")")
request(ops="session.export(id=\"a1b2c3d4\", format=\"markdown\")")
```

## Storage

Sessions stored through the four note verbs are `kind=session` notes on the
shared `notes` substrate. `notes.name` holds the optional title,
`notes.content` holds the verbatim payload, and `notes.properties` holds
`provider`, `provider_session_id`, and `tags`. Handlers go through the public
runtime seam (`runtime.core()`, `create_note`, `query_notes_filtered`,
`resolve_prefix`, `resolve_primary`) rather than direct SQL. The separate
session mirror has pack-owned SQL tables, a versioned identity migration,
and an FTS5 index; see [ADR-117a mirror identity](docs/api/adr117a-identity.md).

## Out of scope for this slice

The digester/summarization pipeline is cloud-side. `session.import`, tiering,
and billing are deferred; see
[ADR-083](https://github.com/ohdearquant/khive/blob/main/docs/adr/ADR-083-session-pack-t1-verbs.md).
The session mirror (transcript parsing and ingestion into `session_messages`)
is a separate, already-shipped concern — see
[ADR-080 §6](https://github.com/ohdearquant/khive/blob/main/docs/adr/ADR-080-session-pack-oss-storage-mechanism.md#6-the-session-mirror-amendment-2026-07-02).
After its startup discovery pass, the mirror caches directory listings, polls
actively growing transcripts directly, and samples cold transcripts through
fixed round-robin budgets. Quiet-tick metadata work therefore stays bounded as
the historical transcript corpus grows; directory changes prioritize their
cold files, with the ordinary bounded sweep covering filesystems where append
does not update parent-directory mtime. The priority ordering is bounded but
not fair under continuous directory churn: repeated changes can keep the
priority queue ahead of the ordinary cold sweep, while productive cold-file
metadata probes remain capped at 256 per tick.

## Where this sits

`khive-pack-session` sits in the pack tier alongside
[`khive-pack-kg`](https://crates.io/crates/khive-pack-kg) (a `REQUIRES`
dependency for the `session` note kind's substrate) and is one of the packs
loaded by default in `khive-mcp`.

## License

Apache-2.0.