trajectories 0.0.0 → 0.1.1

package/docs/cursor-native-format.md

@@ -0,0 +1,103 @@
+# Cursor native session format
+
+The Cursor adapter targets the native `AgentKv` store loaded by Cursor CLI and
+ACP. It is pinned to `cursor-agent 2026.10.01-e373342`; Cursor does not publish
+this persisted protobuf schema as a stable interchange API.
+
+## Export contract
+
+`writeCursor` emits two text files:
+
+- `cursor/<session-id>.readout.json` is the binding entrypoint. It contains all
+  SQLite `meta` rows and every content-addressed blob as base64, plus the source
+  records verbatim under `provenance.sourceRecords`.
+- `cursor/prepare-cursor.mjs` validates the runtime and blob hashes, then creates
+  new stores without replacing an existing Cursor session.
+
+The readout has format identifier `cursor-agent-sqlite-readout-v1`. It is a
+lossless logical readout of the selected store rows and blob bytes, not a copy
+of SQLite page bytes. `readCursor(raw)` reads this entrypoint before prepare.
+`readCursorNative(storeDbOrSessionDirectory, nativeSessionId?)` opens an
+existing database read-only and produces the same readout. When an ACP
+`meta.json` sidecar exists, its `cwd` is retained as provenance.
+
+Prepare writes the same store to both locations used by the tested runtime:
+
+```text
+$HOME/.cursor/chats/<md5(resolve(cwd))>/<session-id>/store.db
+$HOME/.cursor/acp-sessions/<session-id>/store.db
+$HOME/.cursor/acp-sessions/<session-id>/meta.json
+```
+
+The database has `PRAGMA user_version=1` and two tables:
+
+```sql
+CREATE TABLE blobs (id TEXT PRIMARY KEY, data BLOB);
+CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT);
+```
+
+Blob IDs are lowercase SHA-256 hashes of the raw protobuf bytes. `meta['0']` is
+the hex encoding of UTF-8 JSON metadata; `latestRootBlobId` selects the root
+conversation blob. The emitted protobuf subset contains agent turns, user
+messages, assistant messages, thinking messages, and completed MCP tool calls.
+Tool arguments use protobuf `Value`; results retain complete text and the
+source success flag. Source system and observation records remain verbatim in
+the entrypoint and are diagnosed because AgentKv has no equivalent active
+conversation step.
+
+The reader rejects unknown fields in decoded messages. It also rejects root
+state carrying compaction summaries, branches, checkpoints, or subagents.
+Those stores can still be archived as native evidence, but cannot be continued
+through this codec without choosing a branch or losing state.
+
+`prepare-cursor.mjs` requires the exact tested version by default. Setting
+`CURSOR_NATIVE_ALLOW_UNTESTED=1` is an explicit caller override; it does not
+make another version verified.
+
+## Loader verification
+
+The native probe used the official installer in an isolated home and made no
+model request. It performed this sequence:
+
+1. Export a user message, thinking step, MCP tool call with structured
+   arguments, a 4,103-character result, and an assistant message.
+2. Run the emitted prepare action with Node 22.23.1.
+3. Start the real Cursor ACP process, initialize protocol version 1, and call
+   `session/load` for the imported UUID. No `session/prompt` request is sent.
+4. Assert Cursor's `session/update` replay contains the user text,
+   completed tool content, and final assistant text.
+
+Source reasoning remains archived in the central snapshot. The destination
+writer omits it with an `untranslated-reasoning` diagnostic.
+
+The test is opt-in because it needs a Cursor executable and credential:
+
+```sh
+CURSOR_NATIVE_BIN=/path/to/cursor-agent CURSOR_API_KEY=... \
+  bun test packages/trajectories/test/cursor.test.ts
+```
+
+On 2026-10-05, the account's `cursor-agent models` output included GLM 5.2 and
+GPT-5.6 routes but no GLM 5.3 route. Cursor exposes a model selector but no
+provider selector, so the writer rejects `provider` rather than silently
+changing it. A requested GLM 5.3 run must remain blocked until Cursor lists an
+exact GLM 5.3 model ID.
+
+## Source evidence
+
+The official runtime artifacts inspected for this codec were:
+
+| Artifact | SHA-256 |
+| --- | --- |
+| Cursor install script | `dd6677f33cb7efa34809557b1c6df3a11e389b76ce4e56ce5751db13dd7260e6` |
+| `cursor-agent 2026.10.01-e373342` | `2ccc9a8e167797641448b5e5c936f006ba137a2555f117f38c5eb76a5238a233` |
+| runtime `index.js` | `39218adfc45db4c75727b3a19c61ac12ff671aa4417c94591a1b1469658c59ea` |
+| runtime chunk `4945.index.js` (AgentKv serializer/store) | `e6b1a2a2d0a7974dd9ad5920483cecbcc1c3c76a9dc1978d11a081cab62e2df6` |
+| runtime chunk `6136.index.js` (ACP storage/load/replay) | `1fd63a6a85df08cd65f82b11d8831fee053d282563f4b7727729c6d90abeecd3` |
+| `@letta-ai/trajectory` 0.4.3 Cursor decoder | `4989a4a872e83086335117f14459f04a7d71d1feee2ddfb6256be0833c28c9e6` |
+
+[Cursor's CLI reference](https://cursor.com/docs/cli/reference/parameters)
+documents `cursor-agent --resume <chat-id>`, and its
+[ACP guide](https://cursor.com/docs/cli/acp) documents session loading. The
+runtime bundle is the authoritative source for the private store schema,
+message field numbers, storage paths, and history replay behavior used here.

package/docs/deepagents-native-format.md

@@ -0,0 +1,98 @@
+# Deep Agents native checkpoint format
+
+This codec targets deepagents-code 0.1.80 (commit e4c1ffe9ee63d7854147de490ca27495ef157a7b) with deepagents 0.7.21. Deep Agents persists conversations as LangGraph checkpoints, not transcript files.
+
+## Export and prepare
+
+writeDeepAgents emits:
+
+- checkpoint.json: a validated, portable seed and the SDK entrypoint.
+- import_deepagents.py: a deterministic importer.
+
+checkpoint.json has this shape:
+
+~~~json
+{
+  "version": 1,
+  "source": "deepagents",
+  "session": {
+    "threadId": "<uuid>",
+    "checkpointNamespace": "",
+    "cwd": "/absolute/workspace",
+    "createdAt": "<ISO-8601>",
+    "model": "glm-5.3"
+  },
+  "messages": [
+    { "id": "trajectory:<thread-id>:1", "role": "human", "content": "...", "timestamp": "<ISO-8601>" },
+    {
+      "id": "trajectory:<thread-id>:2",
+      "role": "ai",
+      "content": "",
+      "reasoning": [],
+      "toolCalls": [{ "id": "...", "name": "...", "args": {} }],
+      "model": "glm-5.3",
+      "timestamp": "<ISO-8601>"
+    },
+    { "id": "trajectory:<thread-id>:3", "role": "tool", "content": "...", "toolCallId": "...", "timestamp": "<ISO-8601>" }
+  ]
+}
+~~~
+
+Each exported message has a deterministic native ID scoped by the thread. Deep Agents' ACP replay indexes persisted messages by that field, so the importer rejects a missing or duplicate ID. Database readouts from older native checkpoints may omit IDs; archive decoding and history safety validation still accept those readouts.
+
+The seed supports the root checkpoint namespace only. Reasoning, compaction state, branches, pending tool calls, and tool success status are not invented. Unsupported source records remain in the central snapshot and produce diagnostics.
+
+The returned prepare step calls:
+
+~~~text
+python3 import_deepagents.py checkpoint.json <export>/.state/sessions.db
+~~~
+
+The Python interpreter must contain the pinned Deep Agents packages. The importer sets DEEPAGENTS_HOME to the export directory and invokes the official deepagents_code.sessions.save_thread_seed API. That API creates <export>/.state/sessions.db; no database file exists before prepare runs. The importer refuses to overwrite or stamp a destination that already contains the requested thread ID.
+
+The importer then reads and replaces that checkpoint through the public get_checkpointer, aget_tuple, and aput APIs. It preserves the checkpoint payload and existing metadata while adding the required durable ACP metadata written by deepagents_acp.server.AgentServerACP._persist_session: acp_session is true and cwd is the seed workspace. This makes the converted thread eligible for native ACP session/load without constructing an agent or calling a model during prepare.
+
+Resume uses:
+
+~~~text
+env DEEPAGENTS_HOME=<export> dcode -r <thread-id>
+~~~
+
+ACP clients can instead launch the pinned CLI as a stdio server and call session/load with the same thread ID and cwd:
+
+~~~text
+env DEEPAGENTS_HOME=<export> dcode --acp --model zai:glm-5.3 --no-mcp --no-interpreter
+~~~
+
+ACP load rejects checkpoints without that marker as Resource not found and rejects a different cwd as invalid parameters. The importer does not set optional acp_mode or acp_model metadata because those fields describe ACP UI selections rather than the checkpoint's content model.
+
+## Reading
+
+readDeepAgents({ path, threadId, pythonExecutable? }) accepts either checkpoint.json or sessions.db.
+
+- For checkpoint.json, it validates every field and derives canonical records in memory.
+- For sessions.db, it delegates SQLite decoding, checkpoint ancestry, pending writes, and message reconstruction to @letta-ai/trajectory 0.4.3 and the installed LangGraph Python packages.
+
+For a database input, raw is the stable JSON readout of the selected checkpoint. It is not the SQLite bytes. It carries the thread, namespace, checkpoint ID and timestamp, cwd, model, and selected messages. Canonical source group identity remains the upstream JSON tuple [threadId, checkpointNamespace]; the native runtime selector is the bare threadId.
+
+## Z.AI GLM-5.3
+
+Deep Agents' official custom-provider path uses langchain_openai:ChatOpenAI. An isolated profile can configure:
+
+~~~toml
+[models.providers.zai]
+display_name = "Z.AI"
+class_path = "langchain_openai:ChatOpenAI"
+api_key_env = "ZAI_API_KEY"
+base_url = "https://api.z.ai/api/coding/paas/v4"
+models = ["glm-5.3"]
+
+[models.providers.zai.params]
+use_responses_api = false
+~~~
+
+Resume with --model zai:glm-5.3. The codec never copies credentials or changes the provider when the caller did not request one.
+
+## Native acceptance
+
+The pinned importer was exercised with Python 3.12.15. dcode threads list --json loaded the generated store and reported the seeded thread, cwd, checkpoint ID, and five messages. The official Letta checkpoint loader then read the same .state/sessions.db, including both tool calls, both results, and the final assistant message. A pinned dcode ACP server accepted session/load and replayed the converted messages without a prompt or model request; the same checkpoint without the marker was rejected as Resource not found. Evidence is under /root/.local/share/harness-parity-implementation-2026-10-05/evidence.

package/docs/evidence-api.md

@@ -0,0 +1,170 @@
+# Evidence inspection API
+
+Status: **skipped by the owner on 2026-10-06; not an implementation task or SDK export**.
+The design below is retained as history. The owner accepted the existing captured
+native transcript for conversion debugging and chose to skip a separate evidence
+inspection interface. Type-checking and contract review did not demonstrate a
+consumer need. Do not revive this API as an active optimization.
+The owner subsequently rejected per-capture full-snapshot persistence itself;
+[canonical-log storage](../../../docs/adr/0011-trajectories-log-authority.md) is
+the replacement target, with migration pending.
+
+Baseline: `cd23e7354fc40d630dae94151b4bb4d6d90734f9`.
+Applies the owner-invoked `addy:api-and-interface-design` skill to the evidence
+and ingestion candidates in the [Huihua/OAR assessment](research/2026-10-06-huihua-and-oar.md).
+
+## Goal and boundary
+
+Given a complete Trajectories snapshot and a canonical record position, identify
+the captured native evidence that produced that record. Preserve our own format,
+canonical identities and existing conversion/session calls. A caller can inspect
+an archived history without declaring it portable or executing any harness.
+
+This adds one proposed SDK factory, `inspectEvidence(snapshot)`, returning a
+read-only view. It does not add persisted fields to `Snapshot` or modify Letta's
+canonical schema. The snapshot already owns captured text, sidecars, identities
+and hashes. The view holds locators into that evidence rather than payload copies.
+
+## Proposed TypeScript contract
+
+```ts
+import type { Snapshot } from 'trajectories';
+
+type EvidenceArtifact =
+  | { readonly kind: 'raw'; readonly sha256: string }
+  | { readonly kind: 'attachment'; readonly name: string; readonly sha256: string };
+
+type EvidenceLocation =
+  | { readonly kind: 'utf8'; readonly startByte: number; readonly endByte: number }
+  | { readonly kind: 'json'; readonly path: readonly (string | number)[] };
+
+interface NativeEvidenceRef {
+  readonly artifact: EvidenceArtifact;
+  readonly location: EvidenceLocation;
+}
+
+interface EvidenceRecordKey {
+  readonly snapshotId: Snapshot['id'];
+  readonly canonicalIndex: number;
+  readonly recordId: string;
+}
+
+type RecordEvidence = EvidenceRecordKey & (
+  | {
+      readonly kind: 'mapped';
+      readonly references: readonly [NativeEvidenceRef, ...NativeEvidenceRef[]];
+    }
+  | {
+      readonly kind: 'unmapped';
+      readonly reason: 'synthetic' | 'ambiguous' | 'unsupported';
+    }
+);
+
+interface EvidenceView {
+  readonly snapshotId: Snapshot['id'];
+  readonly recordCount: number;
+  record(canonicalIndex: number): RecordEvidence;
+}
+
+declare function inspectEvidence(snapshot: Snapshot): EvidenceView;
+```
+
+The factory is a proposal in this document. The current package exports neither
+it nor these new types. Literal casing follows the existing SDK conventions.
+
+## Identity and location rules
+
+- `canonicalIndex` is the zero-based position in this exact snapshot's
+  `canonical.records`, including metadata. It is not a global sequence, native
+  turn id, or transport arrival order. `recordId` corroborates the record; native
+  ids and canonical ids alone cannot disambiguate every repeated observation.
+- Each result includes `snapshotId`, so a saved mapping cannot silently become
+  a mapping for a later head. The artifact digest identifies the captured content;
+  attachment names select content already retained in that snapshot.
+- `utf8` uses zero-based byte offsets in the captured string's UTF-8 encoding,
+  with an exclusive end. Both ends must be valid encoding boundaries. It does
+  not claim that a prior lossy decoding preserved an original file byte-for-byte.
+- `json.path` addresses a value within the captured JSON artifact. String steps
+  select exact own object keys; integer steps select array positions. An empty
+  path addresses the entire value. This also covers selected database rows or
+  checkpoint exports, without claiming a database image or reopening that store.
+- One native frame can support multiple canonical components; those components
+  share its reference. One canonical record can require multiple evidence refs.
+  Reference order follows captured source order, not consumer request timing.
+- Every mapped reference must exist in the captured artifact, have its expected
+  digest, and be proven to support the selected normalized record. A matching
+  native id or timestamp alone is insufficient. If proof is missing or
+  ambiguous, return `unmapped`; do not select the first plausible frame.
+
+`synthetic` describes a generated record without direct native evidence;
+`ambiguous` means available candidates cannot be distinguished;
+`unsupported` means the decoder or historical normalization cannot prove a
+mapping. These are ordinary inspection results, not exceptions or evidence of
+runtime failure. An unknown native frame still remains in captured raw history;
+it is not fabricated into a canonical conversation to make it addressable.
+
+## Validation, errors and cost
+
+The exported factory is a boundary: validate snapshot integrity once there,
+using the existing snapshot contract. Locate evidence from captured content,
+with decoder-specific verification, rather than trusting client-supplied maps.
+Internal view lookups use that validated captured generation. Caller mutation
+after construction must not redirect the view to another record or artifact.
+
+Invalid snapshots throw an `Error`, consistent with the SDK's current throwing
+strategy. `record()` throws a `RangeError` for a non-integer, negative or
+out-of-range index. Ordinary unavailable evidence uses the explicit union above.
+Consumers must not branch on diagnostic prose. This proposal does not retrofit
+new error shapes across existing SDK calls.
+
+Build or cache the native-location index once per view; repeated lookups must
+not reparse the entire transcript. Keep payloads in their original captured
+artifacts. Index cost and mapping coverage must be measured; this is not a
+constant-memory promise. Consumers can page through `recordCount` and indexed
+lookups without another public collection/list API.
+
+## Compatibility and implementation gate
+
+`Snapshot.version`, existing snapshot ids, `raw`, `attachments`, canonical record
+content/order and all current public calls retain their meaning. In particular,
+snapshot identity currently hashes canonical records and sidecars, while session
+head comparisons and acknowledgement replay depend on that identity. Persisting
+an unchecked optional map or adding a hashed sidecar would require different
+integrity/migration handling; the derived view avoids that change.
+
+The contract is shared across the existing 11 SDK codecs. Decoder coverage must
+be reported per record and per source; exposing the common API does not establish
+complete mapping coverage. Legacy SQLite search rows alone lack the whole native
+capture and are not substitutes for a `Snapshot`.
+
+Before exporting this API, demonstrate exact locations against real captured
+fixtures across supported source shapes: JSONL, JSON and selected database or
+checkpoint exports. Verify repeated ids, multiple components from one frame,
+sidecars, multibyte text, synthetic records and explicit unsupported cases.
+Changing a snapshot's canonical content while retaining the same native capture
+must not create a false mapped result. Repeated lookups must preserve identities
+and avoid repeated full parsing.
+
+Existing Pi active-context, interrupted-draft and incomplete-tool protections
+remain conversion gates. An evidence reference proves only a recorded fact.
+It does not prove that a pause stopped execution, reconcile a late effect, or
+capture a host request that never entered the native log.
+
+## Separate, unmeasured streaming candidate
+
+Skipping evidence inspection does not establish a performance result. The current
+[optimization assessment](research/2026-10-06-huihua-and-oar.md#what-remains-worth-measuring)
+keeps long-history acquisition and retained checkpoint size as measurement
+candidates, with no new public API or performance implementation in this checkpoint.
+
+Keep `readSnapshot` as the existing complete-snapshot API for the first ingestion
+prototype. Test incremental parsing internally before adding an exported stream
+or another session/state abstraction. Reading chunks and concatenating them into
+the same bulk parser is not evidence of incremental normalization.
+
+Compare the prototype against the same captured native inputs. Require identical
+canonical records, diagnostics, snapshot identities and conversion behavior;
+measure temporary memory, time and retained snapshot size. Full snapshots still
+retain complete history. Failed or cancelled acquisition must not publish a
+complete snapshot or advance a managed head. Only a demonstrated useful result
+justifies expanding the public API for cancellation or partial observation.

package/docs/fx-native-format.md

@@ -0,0 +1,87 @@
+# FX native session format
+
+Trajectories reads and writes FX's native `session.json` format. The implementation is pinned to first-party FX commit [`4d966e272cfc4296cdf703f409480088cf2e72ba`](https://github.com/vercel-labs/fx/tree/4d966e272cfc4296cdf703f409480088cf2e72ba).
+
+FX discovers sessions at `$HOME/.fx/sessions/<session-id>/session.json`. A native export therefore uses this layout relative to `WriteOptions.directory`:
+
+```text
+.fx/sessions/<session-id>/session.json
+```
+
+The generated resume vector sets `HOME` to that directory and invokes `fx [--provider P] [--model M] resume <session-id>`. FX treats provider and model as global launch options, so they precede `resume`. The public [sessions documentation](https://fx.sh/docs/using-fx/sessions) documents the profile location, `fx resume <session-id>`, and the read-only `fx session <session-id> --json` inspection command. Custom OpenAI-compatible providers and the `FX_PROVIDER`/`FX_MODEL` overrides are documented under [custom model connections](https://fx.sh/docs/configure-fx/custom-model-connections).
+
+## Written schema
+
+The writer emits the legacy top-level session schema version 1 implemented by FX's pinned [`session_json.zig`](https://github.com/vercel-labs/fx/blob/4d966e272cfc4296cdf703f409480088cf2e72ba/src/core/session/session_json.zig):
+
+```json
+{
+  "schema_version": 1,
+  "id": "<uuid>",
+  "created_at_ms": 1791187200000,
+  "updated_at_ms": 1791187200000,
+  "workspace_root": "/absolute/workspace",
+  "conversation_language": "en",
+  "history_len": 1,
+  "history": []
+}
+```
+
+Each completed turn is an `assistant` history entry containing the user text, final assistant text, and optional execution memory. Execution memory uses presentation schema version 3 from pinned [`session_codec.zig`](https://github.com/vercel-labs/fx/blob/4d966e272cfc4296cdf703f409480088cf2e72ba/src/core/session/session_codec.zig). It retains every completed batch, including parallel calls:
+
+```json
+{
+  "kind": "assistant",
+  "user": { "text": "Inspect both files", "images": [] },
+  "assistant": "Both files are inspected.",
+  "execution": {
+    "schema_version": 3,
+    "tool_steps": [{
+      "assistant": "I will inspect them.",
+      "tool_calls": [{
+        "id": "call-1",
+        "name": "read_file",
+        "arguments_json": "{\"path\":\"a.txt\"}",
+        "provider_result": null
+      }],
+      "tool_results": [{
+        "tool_call_id": "call-1",
+        "tool_name": "read_file",
+        "status": "success",
+        "output": "contents",
+        "output_bytes": 8,
+        "stored_output_bytes": 8,
+        "truncated": false,
+        "provider_native": false,
+        "created_at_ms": 1791187200000,
+        "permission_feedback": []
+      }]
+    }],
+    "files": []
+  }
+}
+```
+
+FX's pinned [`session_store.zig`](https://github.com/vercel-labs/fx/blob/4d966e272cfc4296cdf703f409480088cf2e72ba/src/core/session/session_store.zig) recognizes this legacy file, loads it through `parseLegacyExact`, and migrates it when opened for writing. This private writer boundary is version-pinned because FX does not expose a public import API for arbitrary completed history.
+
+## Reader and portability boundary
+
+`readFx` accepts legacy monolithic top-level schemas 1 and 2. It also accepts the pinned runtime's current schema 4 when given the complete native companions:
+
+```text
+session.json                         metadata header (schema 4)
+events.jsonl                        ordered conversation envelopes (schemas 1–3)
+tool-results/<artifact_ref>         exact stored tool-result bodies
+```
+
+Schema 4 is defined by pinned [`session_codec.zig`](https://github.com/vercel-labs/fx/blob/4d966e272cfc4296cdf703f409480088cf2e72ba/src/core/session/session_codec.zig), [`session_event.zig`](https://github.com/vercel-labs/fx/blob/4d966e272cfc4296cdf703f409480088cf2e72ba/src/core/session/session_event.zig), and [`session_log.zig`](https://github.com/vercel-labs/fx/blob/4d966e272cfc4296cdf703f409480088cf2e72ba/src/core/session/session_log.zig). `session.json` no longer contains history. The reader therefore requires `events.jsonl`, validates contiguous native sequence numbers and completed tool linkage, and resolves every tool result through its named artifact. A missing artifact, an unsafe path, invalid UTF-8, or a byte-count mismatch fails the read; the event preview is never substituted for an absent body.
+
+The earlier top-level schema 3 is a distinct `event_log_v1` manifest with generation IDs, byte boundaries, fingerprints, and checkpoints. It is rejected explicitly because interpreting only its manifest as schema 4 would invent history. This codec does not claim top-level schema 3 support.
+
+Schema 4 provider replay stays byte-for-byte in the `events.jsonl` attachment. The reader projects only the pinned configured-provider OpenAI chat-completions subset whose native-emitted compact replay object has no duplicate keys, contains one visible `reasoning` or `reasoning_content` string, has no opaque `reasoning_details`, matches the exact session provider binding and model, and lists `_tool_call_ids` that exactly match the following tool-call batch. That visible string becomes a canonical reasoning record. Built-in-provider replay, opaque or noncanonical bytes, unknown fields, ambiguous visible fields, source mismatches, and call-association mismatches remain archive-only and fail portability.
+
+Configured-provider binding identity, tool provenance, result completeness, committed-file presentation, file evidence, and turn summaries also stay byte-for-byte in the snapshot's raw header and attachments and are surfaced as diagnostics. Completed semantic user, assistant, tool-call, and exact stored tool-result records remain portable. A `partial` or `unknown` result preserves the complete stored artifact only; it does not claim the upstream provider's original output was complete. Images, steering, interrupted turns, context checkpoints, uncertain arguments or identities, tool images, and command replay still fail portability because canonical history cannot reproduce that active context.
+
+For every accepted schema, the reader preserves the native bytes in the surrounding snapshot and normalizes completed turns, tool calls, terminal results, status, and final replies under source type `fx`.
+
+The writer intentionally omits credentials, settings, permissions, images, provider replay, file evidence, steering, compaction state, and usage. System, reasoning, and observation records remain in the central snapshot and produce explicit `untranslated-*` writer diagnostics; the exported FX file does not install them as target instructions or provider reasoning. The snapshot attachment preserves imported replay bytes, but the writer does not claim to recreate opaque native state or provider caches. An export is refused if a turn or tool batch is incomplete.

package/docs/harness-parity-bootstrap.md

@@ -0,0 +1,78 @@
+# Harness parity bootstrap
+
+This extends the [initial inventory](./harness-support-parity.md). Execution
+remains in HarnessAgent; Trajectories has no AI SDK/runtime dependency and
+prepares history artifacts without executing them.
+
+| Surface | Before | Bootstrap |
+| --- | ---: | ---: |
+| Ledger / Trajectories CLI history readers | 16 | 18 |
+| Trajectories SDK reader/writer codecs | 6 | 11 |
+| Vercel concrete adapters plus our OMP | 11 | 11 |
+| Omakase registry names | 9 | 11 |
+| Committed compiled adapter imports | 6 | 7 |
+
+New codecs: Cursor, Deep Agents, GitHub Copilot, Cline and fx. Cline/fx also
+gain archive discovery, normalization and search ingestion. All 11 execution
+runtimes now have a history codec. Archive-only runtimes remain Droid, Gemini,
+Hermes, Kimi, Letta Code, OpenClaw and OpenHands.
+
+Registry coverage is separate from installation. This candidate includes Grok
+Build 1.0.39 in Omakase's static import map, verified in an actual compiled
+executable with Bun 1.3.14. Deep Agents, Cline, Copilot and fx are registered
+but require their adapters to be installed/included before execution through
+that binary. Cursor is named `cursor-cli` in Omakase; `grok` and `copilot-cli`
+are the legacy scanner aliases for SDK `grok-build` and `github-copilot`.
+
+The generated [implementation inventory](../evidence/harness-support-bootstrap.json)
+has source fingerprints. Run `bun scripts/parity/inventory.ts --check` from the
+package to detect stale coverage. It does not advertise model compatibility.
+
+## Verification boundaries
+
+| Target | Native store / import | Loader pin | Model continuation |
+| --- | --- | --- | --- |
+| Cursor | SQLite row/blob artifact; explicit prepare writes CLI/ACP stores | 2026.10.01-e373342 | Offline only: account lists no GLM5.3 route |
+| Deep Agents | Selected checkpoint messages/metadata; official checkpoint helper | dcode 0.1.80 | Frozen GLM ACP probe |
+| GitHub Copilot | events.jsonl + workspace.yaml | CLI 1.0.91 / SDK 1.0.16 | Frozen GLM BYOK probe |
+| Cline | Core messages/manifest + explicit index prepare; adapter history.json | Core 0.0.79 / CLI 3.0.68 | Frozen GLM public Core SDK probe |
+| fx | Legacy monolithic schemas 1/2; schema 4 manifest + event journal + tool-result artifacts | 0.0.13 at 4d966e27 | Frozen GLM native CLI probe |
+| Grok Build | Native v1 journal/summary, no synthetic user prefix | Bundled 1.0.5 / adapter 1.0.39 | Frozen HarnessAgent GLM probe |
+
+Each new codec has a real zero-inference native-loader check, distinct from
+codec/seed round trips. The 11-codec central binding check preserves user and
+assistant text, call IDs/names/arguments and unbounded tool results. It does
+not execute native preparation or inference. The older six-harness
+[36-transfer cohort](../evidence/results-2026-10-03.md) remains historical
+evidence under its own source freeze, not a new result for this candidate.
+
+Live probes in [scripts/parity](../scripts/parity/README.md) use a preserved real
+Claude Code session, withheld user/tool facts, a new native file write, matching
+empty controls and native history readback. They require a clean pushed source
+freeze, run sequentially and retain failed attempts. The
+[measured results](../evidence/harness-parity-results-2026-10-05.md) preserve all
+five cohorts. The final live run is 7/10, with three complete control/import
+pairs; retained Cline readback and a localhost Grok control repair are separate
+checks. Cursor remains offline-only.
+
+## Native history versus adapter resume state
+
+An adapter lifecycle envelope is not the native conversation. Grok's ACP
+adapter creates `acpSessionId` and `coldSession` lazily on its first turn, so an
+empty `createSession → stop` handle cannot resume an imported journal alone.
+An offline localhost turn materializes adapter-owned configuration metadata;
+the lab merges that metadata with the genuine empty handle and imported UUID,
+then calls ordinary HarnessAgent resume. `onSession` installs the native files
+before bridge startup. Captured provider input contains the original user,
+calls, full tool results and assistant, followed by the new prompt.
+
+This is a pinned prototype, not a general public adapter import API. The
+template/configuration fingerprint must match. SDK conversion never invents
+opaque adapter state or copies runtime credentials. Native history, managed
+identity and adapter lifecycle metadata retain separate responsibilities.
+
+Cursor keeps SQLite rows/blobs, not database page bytes. Deep Agents captures
+decoded messages and checkpoint metadata, not all graph channels, pending
+writes or arbitrary custom reducers. Its ACP importer requires unique message
+IDs plus the native `acp_session`/cwd markers. No codec promises permissions,
+provider caches, active approvals, workspace transfer or exactly-once effects.

package/docs/harness-support-parity.md

@@ -0,0 +1,107 @@
+# Harness support and parity
+
+Historical baseline at `104a013`. The [parity bootstrap](./harness-parity-bootstrap.md)
+records the subsequent implementation; the original fingerprints and evidence
+remain unchanged.
+
+Verified 2026-10-05. This is an inventory of implementations and existing evidence,
+not a new live compatibility test. Execution stays behind Vercel HarnessAgent.
+
+| Surface | Harnesses | Meaning |
+| --- | ---: | --- |
+| Ledger / migrated Trajectories CLI | 16 | Discover, normalize and index native history |
+| Trajectories session SDK | 6 | Read central snapshots and export another harness's native history |
+| Vercel concrete harness adapters | 10 | A runtime-specific execution adapter exists upstream |
+| Vercel adapters plus our OMP adapter | 11 | Initial execution/conversion parity target |
+| Omakase's shared agent registry | 9 | Names recognized; adapters can still be unavailable |
+| Current generated compiled import map | 6 | Adapters selected for inclusion when compiling this tree |
+
+Counts are unique native runtimes. Generic ACP, the core HarnessAgent package,
+ATIF (an interchange format), and the alternative Pi Durable backend are not
+additional harnesses. Amp, Goose and Mastra are documented as coming soon at the
+upstream checkpoint, with no concrete adapter package in that tree.
+
+## Support matrix
+
+`History` means the migrated CLI has a native reader/normalizer path. `Sessions`
+means the SDK has both a reader and a native export writer. `Adapter` means a
+concrete HarnessV1 implementation exists; it does not mean it is installed or
+live-tested here. `Map` refers to the committed build-time map, not an inspected
+deployed executable.
+
+| Harness | History | Sessions | Adapter | Omakase registry | Map |
+| --- | --- | --- | --- | --- | --- |
+| Claude Code | Yes | Yes | Vercel | Yes | Yes |
+| Codex | Yes | Yes | Vercel | Yes | Yes |
+| Pi | Yes | Yes | Vercel | Yes | Yes |
+| Oh My Pi | Yes | Yes | Ours | Yes | Yes |
+| OpenCode | Yes | Yes | Vercel | Yes | Yes |
+| Grok Build | Yes | Yes | Vercel | Yes | No |
+| Cursor | Yes | No | Vercel | Yes | Yes |
+| Deep Agents | Yes | No | Vercel | Yes | No |
+| GitHub Copilot CLI | Yes | No | Vercel | No | No |
+| Cline | No | No | Vercel | Yes | No |
+| fx | No | No | Vercel | No | No |
+| Hermes | Yes | No | None inventoried | No | No |
+| Letta Code | Yes | No | None inventoried | No | No |
+| OpenClaw | Yes | No | None inventoried | No | No |
+| Factory Droid | Yes | No | None inventoried | No | No |
+| OpenHands | Yes | No | None inventoried | No | No |
+| Kimi CLI (wire format) | Yes | No | None inventoried | No | No |
+| Gemini CLI | Yes | No | None inventoried | No | No |
+
+Aliases must be normalized when comparing inventories: Ledger `grok` is SDK
+`grok-build`; Ledger `copilot-cli` maps to the `harness-github-copilot` runtime;
+Omakase `cursor-cli` maps to Ledger `cursor`. Kimi's inventoried reader handles
+`wire.jsonl`; this does not establish compatibility with every Kimi Code release.
+
+The union is **18 harnesses**: 16 history sources plus Cline and fx. Of the 11
+execution implementations, nine have CLI history support and six have SDK
+session conversion. CLI readers do not automatically become SDK readers: the
+SDK's `Harness` union and converter are currently restricted to those six.
+
+## Recommended parity scope
+
+Make every available execution adapter eligible for central history conversion:
+**11 harnesses first**. Keep archive/search support for the other seven. This
+preserves HarnessAgent while giving Trajectories a clear, verifiable boundary.
+
+1. Complete Omakase's existing six-harness path: Grok already has conversion
+   evidence, but its adapter is absent from the generated import map. Pin and
+   integrate it, then verify a real HarnessAgent handoff before claiming coverage.
+2. Add SDK readers and writers for Cursor, Deep Agents and GitHub Copilot. Reuse
+   Ledger's decoding logic without pulling its Bun search/index engine into the
+   Node SDK. Deep Agents uses checkpoint storage; Cursor has native store formats,
+   so this requires active-context handling as well as emitting JSON.
+3. Add history readers and native writers for Cline and fx. Cline is registered
+   but missing from the map; Copilot and fx also need registry and build integration.
+4. Track history read, native export, execution availability and verified handoff
+   separately in a shared capability inventory. Derive the advertised switchable
+   set from their intersection. Keep adapter imports and execution out of the SDK.
+
+The inventory in this change documents the gap. It does not implement those
+adapters, a shared runtime registry, package upgrades or automatic service cutover.
+Generic ACP can reduce execution-adapter work for compatible agents; it does not
+create a native history reader or prove that an agent accepts imported history.
+
+## Evidence and checkpoints
+
+- Our implementation: `archeism/oh-my-ai` at
+  `f57b5b3bd6278261f10696b9207153e93e9bc9c1`, research branch. These new packages
+  and results must not be represented as already merged to main or published.
+- Original Ledger main and port attribution:
+  [`43081aef`](https://github.com/archeism/ledger/blob/43081aef54c23b4bd017b6c0e11fc42a9a1cb381/packages/core/src/scanner.ts).
+  Its scanner and the migrated scanner expose the same 16 source names.
+- Vercel main:
+  [`7c41e416` adapter documentation](https://github.com/vercel/ai/blob/7c41e416b6d5ca630cc5f72b330e6c4743f82265/content/docs/03-ai-sdk-harnesses/05-harness-adapters.mdx).
+  The frozen Git tree contains ten concrete adapter package manifests and one
+  generic ACP manifest, in addition to the core harness package.
+- Local sources: [SDK types](../src/types.ts), [CLI scanner](../legacy/src/scanner.ts),
+  [registry](../../agents/src/harness-registry.mjs), and
+  [generated map](../../agents/src/harness-import-map.generated.mjs).
+- Prior live evidence: [36/36 transfers across the six SDK harnesses](../evidence/results-2026-10-03.md).
+  This tested native CLI history continuation, not every HarnessAgent adapter or
+  arbitrary branches, compaction, in-flight tools, approvals or native state.
+- [Machine-readable audit](../evidence/harness-support-2026-10-05.json) preserves
+  source identities, derived sets and independent review. No new model runs or
+  GitHub Actions were requested for this source inventory. Skills remain unchanged.