feat: add Kimi Code harness

[zzyking]

Summary

• add Kimi Code as a read-only harness: discover, list, search, view, export, and convert from Kimi, never into it
• sessions live under ~/.kimi-code/sessions/ (or $KIMI_HOME/sessions) as state.json plus agents/main/wire.jsonl
• discovery is gated on that structure, not on directory names; other agent logs are separate conversations and are not merged
• save, delete, same-harness continue, and --with kimi are refused; the native resume command is kimi --session <id>
• unknown wire events stay in the native body, so a native text load/render round trip does not drop bookkeeping Kimi adds later

Format

state.json has two observed shapes. Schema version 2 records id and cwd. Version 1 has no version marker, uses workDir, and has no id field. The id is resolved sessionId → id → the session_* segment of an agent homedir → the directory name. createdAt is accepted as RFC3339 or epoch milliseconds.

Conversational projection:

Kimi event	Common
context.append_message (user)	user text
content.part text / think	assistant text / thinking
tool.call / tool.result	tool-use / tool-result (isError and note kept)
context.undo	rewind the last count turns

wire.jsonl is append-only, so a retried prompt is still on disk. count is in turns, not entries: one turn can append a prompt plus reminders, and a single count: 1 undo drops all of them. Logs without turn.prompt markers fall back to entry granularity.

The codec can still render a synthetic Kimi body so other harnesses can hop through Common. The store never writes ~/.kimi-code/sessions.

Provenance

The wire protocol is not a published contract. This reader is based on local Kimi Code CLI sessions (protocol 1.4 / state v1 and 1.5 / state v2) and on kimi --help. Unknown events are retained so format drift shows up as unexplained native data rather than dropped history.

Verification

• cargo fmt --all -- --check
• cargo clippy --workspace --all-targets --all-features -- -D warnings
• cargo test --workspace --all-features
• unit tests: both timestamp shapes, v1/v2 id recovery, tool-result notes, turn-granular and entry-granular undo
• integration tests: discovery without relying on directory names, read-only save/delete, unknown events on native round trip, cross-harness hop

[NishantJoshi00]

Hey @zzyking , what's the reason behind keeping it read-only?

[NishantJoshi00]

@perry-the-agent can you review this change?

[perry-the-agent]

Reviewed the Kimi harness at bd0f5b8. The implementation is well-tested and the local format/lint/test suite passes, but I found two reproducible data-loss/order issues below. I also left one documentation consistency nit.

[perry-the-agent]

note is retained only when output is a string. For a result such as {"output": {"x": 1}, "note": "truncated"} (or output: null), this branch leaves the JSON output unchanged and silently drops the note, despite the format doc saying truncation/permission annotations are preserved. Please preserve note for every output shape and add object/null regression cases.

[perry-the-agent]

This two-pass encoding reorders mixed user blocks: all text is emitted first, then all tool results. A Common message containing [ToolResult, Text] round-trips through Kimi as [Text, ToolResult], violating the codec's block-order invariant and potentially changing continuation semantics. Please emit blocks in one ordered pass (coalescing only adjacent text if needed) and add a mixed-order fixpoint test.

[perry-the-agent]

The bidirectional arrow conflicts with the table and implementation, which describe Kimi as source-only/read-only. This should be kimi --> common, like the other source-only harnesses.

[perry-the-agent]

Reviewed at bd0f5b8: #18 (review)

I found two reproducible issues: non-text Kimi tool-result notes are dropped, and mixed user blocks are reordered during a Common → Kimi round trip. I also flagged the README diagram's bidirectional arrow, which conflicts with the read-only/source-only behavior.

Verification passed: cargo fmt --all -- --check, cargo clippy --workspace --all-targets --all-features -- -D warnings, cargo test --workspace --all-features, and all 4 GitHub CI checks. No code changes made.

[zzyking]

You're right that read-only was too conservative here — I checked it against the real CLI, and Kimi does accept sessions written from outside.

Testing in an isolated KIMI_CODE_HOME (so nothing touched my real sessions), I hand-wrote a session directory — state.json plus agents/main/wire.jsonl — and Kimi picked it up:

$ kimi session list --cwd /tmp
2026-09-07 18:00  session_aaaaaaaa-...  txcript write probe

It isn't just listing a directory, either: kimi export reported a sessionFirstActivity derived from the time field I had written into the wire log, so it genuinely parses the events back.

Writing a session needs four plain file operations: the session directory, state.json, agents/main/wire.jsonl, and one appended line in ~/.kimi-code/session_index.jsonl. That last one is the only real catch — without it the session is invisible, because there's no directory-scan fallback. The workspace directory name is wd_${slug}_${sha256(workDir)[:12]}, which reproduces the existing directory names on my machine exactly.

Nothing here is compressed, schema-validated, or fails closed, so Kimi sits in the same class as claude_code and codex. I'll add save and delete along with the three review fixes above — I'll confirm shortly whether the write support lands in this PR or as a follow-up on top of it.

[zzyking]

All three findings are fixed and pushed, and the branch is rebased onto main (it was behind; the new PR title check also needed a conventional-commit prefix, so the title is updated).

• note dropped for non-string outputs — confirmed. It's now independent of the output shape: text still takes the note as a suffix, and every other shape (object, array, null) keeps its structure and carries the note beside it rather than losing it. Regression test covers object, null and array outputs, plus the no-note case so a bare structured output doesn't get wrapped.
• Mixed user blocks reordered — confirmed. Emitting all text before all tool results meant [ToolResult, Text] came back as [Text, ToolResult]. Now it's one ordered pass: adjacent text is coalesced, and a tool result flushes whatever text precedes it. The test asserts both the emitted wire order and that the order survives a full round trip back through Common.
• README diagram — right, it contradicted both the table and the store. Now kimi --> common, sitting with the other source-only harnesses.

On the read-only point from my previous comment: since Kimi turns out to be writable, save/delete will come as a follow-up PR on top of this one rather than being folded in here — this PR has already had a review pass against the reader, and the write path has its own testing surface (isolated KIMI_CODE_HOME integration coverage) that deserves separate review. Happy to reorder if you'd rather see them land together.

[zzyking]

Confirming what I said above: the write support is a follow-up, not part of this PR — #32 (feat(kimi): make the Kimi Code store writable), based on this branch.

Keeping them apart means this PR stays what it was reviewed as (the reader plus the three fixes), and the read/write change gets reviewed on its own terms. #32's diff currently includes this branch's commits, because it is stacked on it; that narrows to a single commit once this merges. Merge order is #18, then #32.

One thing worth surfacing here, since it bears on the read-only question: the probe I posted above listed at 18:00 only because that session happened to be written with an updatedAt. kimi session list renders its timestamp column from that field alone, and a session written without it lists at 1970-01-01. Every unit test was green while that was broken — only running the real CLI caught it. It's fixed in #32, and it's the kind of thing that argues for verifying against the harness rather than for refusing to write.