@cotal-ai/connector-claude-code 0.20.1 → 0.22.0

package/dist/agui-map.d.ts

@@ -0,0 +1,220 @@
+/**
+ * §3.1 — the Claude Code session JSONL → AG-UI event mapping.
+ *
+ * This is the record-shaped half of the cutover. It lives HERE and not in `connector-core` on
+ * purpose: the JSONL entry shape is Claude's, and letting it into the shared layer would be exactly
+ * the leak AGENTS.md forbids ("never let an adapter's concepts leak into the shared layers"). What
+ * IS shared — the vocabulary, the frame, the bracket machine, the durable read discipline — is
+ * imported from `connector-core` and nothing about Claude goes back the other way.
+ *
+ * ---------------------------------------------------------------------------------------------
+ * THREE THINGS THE PLAN DOES NOT SETTLE, RECORDED AS GAPS RATHER THAN DECIDED HERE.
+ *
+ * **(A) The run brackets have no vehicle, and this is a real plan defect, not a detail.** §3.1
+ * sources `RUN_STARTED` from the `UserPromptSubmit` hook and `RUN_FINISHED` from the `Stop` hook
+ * (`mcp.ts:72`, `:96`). But `[P6]`/§5.4 makes the durable plane READ A FILE, and the emitter's
+ * mapper is `(record) => events` — a hook fires in a different process at a different time and
+ * produces NO JSONL record, so there is no vehicle by which a hook-sourced event can enter a
+ * record-sourced stream. The two halves of the design were specified against different inputs.
+ *
+ * What this file does instead is stated plainly so a ruling can replace it in one function:
+ * **brackets are derived from the record stream.** A human prompt opens a run; the NEXT human
+ * prompt closes the previous one. Two consequences, both of which a reader must know:
+ *   1. `RUN_FINISHED` lags by one turn. It is emitted when the next turn starts, not when the turn
+ *      ends, so a consumer sees the finish later than the `Stop` hook would have said it.
+ *   2. **The last run of a session never closes.** There is no record after it to close it on.
+ * Neither is silently absorbed: {@link closeOpenRun} exists so the connector's `Stop` hook can shut
+ * the run at the real boundary once a vehicle is ruled, and until then the lag is honest.
+ *
+ * **(B) `origin.kind === "human"` OPENS NO RUN IN ANY AGENT-DRIVEN SESSION — MEASURED on three, and
+ * this is why the mapping smoke reads a real session rather than a fixture.** §3.1's rule is right
+ * about what it excludes (peer/mesh injections, task notifications, resumed-session summaries). The
+ * problem is what is left to select. Partitioned by CONTENT SHAPE, not just counted:
+ *
+ *   | session | user entries | `tool_result` | mesh (`origin.kind:"channel"`) | compact summary | human |
+ *   | --- | --- | --- | --- | --- | --- |
+ *   | interactive, 5938 rec | 892 | 824 | 67 | 1 | **0** |
+ *   | headless `claude -p`, 30 rec | 5 | 3 | 0 | 0 | **0** (2 prompts, `promptSource:"sdk"`) |
+ *   | agent session, 1088 rec | 90 | 86 | 4 | 0 | **0** |
+ *
+ * **`kind:"human"` occurs zero times — but so does a human.** `~/.claude/history.jsonl`, which
+ * records typed prompts through a different mechanism entirely, reports **0** for all three sessions
+ * and 0 for this worktree. The two sources agree, so zero matches is the CORRECT result on these
+ * captures and NOT evidence the rule is wrong. **The rule is unexercised here, not disproven.**
+ *
+ * **AND IT IS EXERCISED ELSEWHERE — read the mapping rationale below before reading these numbers as
+ * a defect.** That section measured a real session a person was driving and counted `kind:"human"`
+ * **44 times**, with `promptSource: "typed"`/`"queued"`, beside 3068 `kind:"channel"` injections. So
+ * the predicate does select, on a session that contains the thing it selects. The three captures
+ * here simply contain none. **Both numbers belong together; either alone misleads.**
+ *
+ * **THIS WAS A COVERAGE GAP, IT WAS RULED, AND THE RULING IS IMPLEMENTED BELOW.** It read: on
+ * agent-driven sessions no run is ever opened and the connector emits nothing, because the mapping table
+ * sent every non-`human` origin to *nothing*. The session it was derived from had a human typing 44 times alongside
+ * its 3068 mesh messages; a spawned lane seat has **0 and 67**, so the open question was **what
+ * opens a run when nobody types**.
+ *
+ * **THE RULING: run-opening and attribution are two predicates, and that row was one predicate
+ * doing both jobs.** A run opens on
+ * `origin.kind ∈ { human, channel }`, ENUMERATED and never inferred; `task-notification` is named as
+ * known-and-not-a-turn; absent `origin` gets its own enumeration over `promptSource`. Attribution
+ * rides as `cotal.turnSource` — **a field on the run, never a gate on it**. The privacy argument is
+ * untouched: a `RUN_STARTED` attributed to a peer republishes no message body, so a peer-initiated
+ * turn can be a turn without re-emitting the peer's content. See {@link ORIGIN_RULE} and
+ * {@link ABSENT_ORIGIN_RULE}, which are where this now lives.
+ *
+ * **KEEP THIS PARAGRAPH HONEST.** Its earlier form said "no run is ever opened and the connector
+ * emits nothing" and "escalated as a plan defect rather than decided here" — describing the state
+ * before the ruling, directly above code that had already implemented it. A successor read it,
+ * believed it over the code, and escalated a closed question as a live blocker; the measurement that
+ * corrected it took one run of the real mapper (**67 runs / 5217 events** on the 5938-record
+ * session, `diagnose()` → `null`). **A stale header is not a documentation defect, it is a false
+ * claim about the function beneath it.** If the rule changes again, this paragraph changes with it.
+ *
+ * **DO NOT "FIX" THIS BY TREATING ABSENT `origin` AS HUMAN.** In a Claude session `user` is also the
+ * role of a TOOL RESULT: that predicate selects **825** of the interactive session's 892 user
+ * entries, and the single non-tool-result among them is a **context-compaction summary**
+ * (`isCompactSummary`), so the true human count is 0 and the predicate over-matches by 825. It would
+ * not emit nothing — it would emit a flood, each entry opening a run, which looks like the connector
+ * working. An earlier revision of this comment recorded (B) as HEADLESS-ONLY and asserted a human
+ * turn is "a `user` entry with no `origin`"; both halves were wrong.
+ *
+ * **The rule is implemented exactly as RULED, and still not guessed at.** `promptSource` was
+ * proposed as the selector and REJECTED: it is bounded by the partition it was inferred from, and
+ * "sdk" also covers programmatic injection. It survives only inside {@link ABSENT_ORIGIN_RULE},
+ * where there is no `origin.kind` to enumerate — a second table rather than a synthetic member,
+ * because an enumeration over `origin.kind` cannot classify a record that has none. Every value
+ * outside either table **fails loud** rather than being silently treated as not-a-turn.
+ *
+ * **(C) `TOOL_CALL_RESULT.messageId` is unstated in §3.1's table** (the row names only
+ * `toolCallId`) while the real schema REQUIRES it. It is keyed the same way every other message
+ * identity here is — entry `uuid` plus block index — so it is unique, stable, and derived rather
+ * than invented at a call site. Raised as a gap in `connector-core`'s constructor doc as well.
+ * ---------------------------------------------------------------------------------------------
+ *
+ * `messageId` is `${uuid}#${blockIndex}` and NOT `message.id`. `message.id` is a provider request
+ * id: measured over a real session, 67% of them appear in more than one entry and 59% carry more
+ * than one block type, so spending it as an AG-UI message identity opens and closes one id
+ * repeatedly and collapses text and reasoning into a single message in the reference reducer. The
+ * provider id is preserved as `cotal.providerMessageId`, which is what it is good for.
+ */
+import { type AguiEvent, type RecordMapper } from "@cotal-ai/connector-core";
+/**
+ * One JSONL entry, typed to what the mapping actually reads and no further.
+ *
+ * Every field is optional because a session file carries at least seven entry types
+ * (`user`, `assistant`, `attachment`, `queue-operation`, `ai-title`, `last-prompt`, `mode`, and
+ * more will be added by a harness release we do not control). Declaring them required would make
+ * the mapper's own type a lie about a file it does not own.
+ */
+export interface ClaudeEntry {
+    type?: string;
+    uuid?: string;
+    sessionId?: string;
+    timestamp?: string;
+    isSidechain?: boolean;
+    origin?: {
+        kind?: string;
+    };
+    /**
+     * Present on every submitted prompt and absent on tool results. **Not the run-opening gate** —
+     * it is `"system"` on task-notifications and caveats too. Read ONLY where `origin` is absent, and
+     * only for the value `"sdk"`. See `ABSENT_ORIGIN_RULE`.
+     */
+    promptSource?: string;
+    /** The harness's own compaction record. A string-content `user` entry that is not a turn. */
+    isCompactSummary?: boolean;
+    isVisibleInTranscriptOnly?: boolean;
+    /**
+     * The session-level invocation marker — `"cli"` or `"sdk-cli"`, uniform across a session file.
+     * **Declared and deliberately NOT read.** It is here so the field's existence is recorded rather
+     * than rediscovered, and so a suite can drive both values against a rule that must ignore them.
+     */
+    entrypoint?: string;
+    message?: {
+        id?: string;
+        stop_reason?: string | null;
+        content?: string | ClaudeBlock[];
+    };
+}
+/** A content block. Same reasoning as above: shape-tolerant, read narrowly. */
+export interface ClaudeBlock {
+    type?: string;
+    text?: string;
+    thinking?: string;
+    /** `tool_use` */
+    id?: string;
+    name?: string;
+    input?: unknown;
+    /** `tool_result` */
+    tool_use_id?: string;
+    content?: unknown;
+    is_error?: boolean;
+}
+export interface ClaudeMapperOptions {
+    /** The native session id — `threadId` for every event. §3 forbids anything else claiming it. */
+    threadId: string;
+    /** Mints a `runId`. Connector-minted by §3.1, so every `RUN_STARTED` carries `runIdSource`. */
+    mintRunId: () => string;
+    /**
+     * Emit `REASONING_*` for `thinking` blocks. **Off by default (§7 Q1).** The `signature` is never
+     * emitted at any setting (§3.5) and is not read by this module at all.
+     */
+    reasoning?: boolean;
+    /**
+     * Arrival clock, for the entries whose `timestamp` is missing or unparseable. Injectable so the
+     * mapping is deterministic under test; those events are labelled `cotal.tsSource: "arrival"`
+     * rather than being given a real-looking number.
+     */
+    now?: () => number;
+}
+/** What {@link createClaudeMapper} returns: the mapper plus the out-of-band run close. */
+export interface ClaudeMapper {
+    map: RecordMapper<ClaudeEntry>;
+    /**
+     * Close the open run, if there is one, at a boundary the record stream cannot see — the `Stop`
+     * hook. Returns `null` when no run is open, so calling it twice is not an error and cannot
+     * manufacture a second `RUN_FINISHED` the bracket machine would refuse.
+     *
+     * It exists because gap (A) above is a gap: the durable plane has no way to hear a hook today,
+     * and this is the seam a ruling plugs into rather than a rewrite.
+     */
+    closeOpenRun: (timestamp: number, stopReason?: string) => {
+        runId: string;
+        events: AguiEvent[];
+    } | null;
+    /** The run currently open, or `null`. Read-only view for a caller that needs to know. */
+    openRun: () => string | null;
+    /**
+     * Forget a run the EMITTER closed out of band, so this mapper stops treating it as open.
+     *
+     * Two things close a run now, and they do not share state. The mapper closes one when the record
+     * stream shows a new turn beginning. The emitter closes one when a lifecycle hook says the turn
+     * ended, which is a boundary no record describes. After the second kind, the mapper still believes
+     * a run is open: it would attribute the next records to a run the stream has already finished, and
+     * the bracket machine would refuse the second terminal it eventually emitted. The emitter reports
+     * what it closed, and this is where that report lands.
+     *
+     * KEYED ON THE ID, and that is the whole safety of it. The report arrives asynchronously, so by
+     * the time it does the mapper may already have opened a NEWER run from a record that landed in
+     * between. Clearing unconditionally would orphan that one: its events would emit under no run at
+     * all, which the brackets refuse, and the session would halt on a frame it had every right to
+     * send. A run that is not the one named is left exactly as it is.
+     */
+    forgetOpenRun: (runId: string) => void;
+    /**
+     * **WHY THIS SESSION OPENED NO RUNS** — a sentence, or `null` once any run has opened.
+     *
+     * A mapper that opens zero runs is byte-indistinguishable from a session nobody prompted, and
+     * from a mapper that is simply broken. Refusing a record is a legitimate outcome; refusing it
+     * SILENTLY is not, and the silence is the defect, not the refusal. This is the production
+     * statement of that — it lives in the shipped mapper, not in a smoke summary, so the connector
+     * and any operator reading it get the same sentence the suite does.
+     *
+     * It is deliberately NOT a throw. Some sessions genuinely contain no prompt yet, and a mapper
+     * that threw on one would take down a live connector over an empty file.
+     */
+    diagnose: () => string | null;
+}
+export declare function createClaudeMapper(opts: ClaudeMapperOptions): ClaudeMapper;
+//# sourceMappingURL=agui-map.d.ts.map

package/dist/agui-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agui-map.d.ts","sourceRoot":"","sources":["../src/agui-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmGG;AACH,OAAO,EACL,KAAK,SAAS,EACd,KAAK,YAAY,EAalB,MAAM,0BAA0B,CAAC;AAElC;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3B;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6FAA6F;IAC7F,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE;QACR,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC;KAClC,CAAC;CACH;AAmHD,+EAA+E;AAC/E,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB;IACjB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,oBAAoB;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,gGAAgG;IAChG,QAAQ,EAAE,MAAM,CAAC;IACjB,+FAA+F;IAC/F,SAAS,EAAE,MAAM,MAAM,CAAC;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,0FAA0F;AAC1F,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,YAAY,CAAC,WAAW,CAAC,CAAC;IAC/B;;;;;;;OAOG;IACH,YAAY,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,KAAK;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,SAAS,EAAE,CAAA;KAAE,GAAG,IAAI,CAAC;IACxG,yFAAyF;IACzF,OAAO,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAC7B;;;;;;;;;;;;;;;OAeG;IACH,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC;;;;;;;;;;;OAWG;IACH,QAAQ,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;CAC/B;AAiBD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,mBAAmB,GAAG,YAAY,CAuP1E"}

package/dist/extension.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../src/extension.ts"],"names":[],"mappings":"AAIA,OAAO,EAA2D,KAAK,SAAS,EAAoC,MAAM,gBAAgB,CAAC;AA0D3I,eAAO,MAAM,eAAe,EAAE,SAsI7B,CAAC"}
+{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../src/extension.ts"],"names":[],"mappings":"AAIA,OAAO,EAA2D,KAAK,SAAS,EAAoC,MAAM,gBAAgB,CAAC;AA0D3I,eAAO,MAAM,eAAe,EAAE,SA4J7B,CAAC"}