@cotal-ai/connector-opencode 0.24.0 → 0.26.0

package/dist/agui-map.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Maps OpenCode session records to AG-UI events.
+ *
+ * **The mapper is a transition machine over per-part state, not a pure function of a record**, for
+ * the reason §3.2 gives: the bus re-emits `message.part.updated` for one part id as it streams. It
+ * is fed from {@link OpenCodeSessionSource}, which hands over only SETTLED parts, in order, so the
+ * transitions here are the ones that survive: a part arrives once, finished.
+ *
+ * **NO USER-AUTHORED TEXT IS EMITTED, EVER (§3.2, orchestrator ruling).** OpenCode injects a peer
+ * batch by prepending it into the human's own text part, so a single part holds peer-authored and
+ * human-authored content with no boundary in the record to filter on. The unit of authorship is
+ * smaller than the smallest unit the store keeps. Content-parsing the injected header back out is
+ * ruled out and is not to be built, prototyped, or left in a comment as an option: it would fail
+ * OPEN the moment either formatter changed a character, and a boundary that depends on two
+ * formatters agreeing forever is not a boundary. So user messages map to nothing at all.
+ *
+ * **REMOVAL NEEDS NO HOOK HERE, AND THAT IS A CONSEQUENCE RATHER THAN AN OVERSIGHT.** The ruling on
+ * a reverted session is: publish only on finality, drop the per-part state for the vanished ids, log
+ * the divergence once, keep going. Because the source hands over only settled parts, this mapper
+ * holds no per-part state to drop: a part arrives once, complete, and is mapped in one shot. So the
+ * divergence log is the source's, and there is nothing here for a revert to invalidate.
+ */
+import { type AguiEvent, type RecordMapper } from "@cotal-ai/connector-core";
+import type { OpenCodeRecord } from "./agui-source.js";
+export interface OpenCodeMapperOptions {
+    /** The native session id. It is the `threadId` on every event and nothing else may claim it. */
+    threadId: string;
+    /** Mints a `runId`. Connector-minted, so every `RUN_STARTED` carries `runIdSource: "connector"`. */
+    mintRunId: () => string;
+    /** Emit `REASONING_*` for reasoning parts. Off by default (§7 Q1). */
+    reasoning?: boolean;
+    /** Arrival clock, for the records carrying no usable source stamp. Injectable for determinism. */
+    now?: () => number;
+}
+export interface OpenCodeMapper {
+    map: RecordMapper<OpenCodeRecord>;
+    /**
+     * Close the open run at a boundary the record stream cannot see: `session.idle`, which §3.2 makes
+     * the flush boundary. Returns `null` when nothing is open, so calling it twice cannot manufacture
+     * a second `RUN_FINISHED` for the bracket machine to refuse.
+     */
+    closeOpenRun: (timestamp: number, stopReason?: string) => {
+        runId: string;
+        events: AguiEvent[];
+    } | null;
+    /** The run currently open, or `null`. */
+    openRun: () => string | null;
+    /**
+     * Forget a run the emitter closed out of band. KEYED ON THE ID: the report can arrive after this
+     * mapper has already opened a newer run, and clearing unconditionally would orphan that one, whose
+     * events would then emit under no run at all and halt a session that had done nothing wrong.
+     */
+    forgetOpenRun: (runId: string) => void;
+    /** Why this session opened no runs, or `null` once one has. A silent refusal is the defect. */
+    diagnose: () => string | null;
+}
+export declare function createOpenCodeMapper(opts: OpenCodeMapperOptions): OpenCodeMapper;
+//# 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;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EACL,KAAK,SAAS,EACd,KAAK,YAAY,EAalB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,MAAM,WAAW,qBAAqB;IACpC,gGAAgG;IAChG,QAAQ,EAAE,MAAM,CAAC;IACjB,oGAAoG;IACpG,SAAS,EAAE,MAAM,MAAM,CAAC;IACxB,sEAAsE;IACtE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,kGAAkG;IAClG,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,YAAY,CAAC,cAAc,CAAC,CAAC;IAClC;;;;OAIG;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,yCAAyC;IACzC,OAAO,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAC7B;;;;OAIG;IACH,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,+FAA+F;IAC/F,QAAQ,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;CAC/B;AAoDD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,qBAAqB,GAAG,cAAc,CA4HhF"}

package/dist/agui-source.d.ts

@@ -0,0 +1,133 @@
+/**
+ * A {@link DurableSource} over an OpenCode session, read through the SDK's own
+ * `session.messages()` surface rather than the SQLite file behind it.
+ *
+ * **Why not the database.** `~/.local/share/opencode/opencode.db` is OpenCode's private store: its
+ * schema migrates, and reading it would couple this plane to internals no contract covers. The
+ * measurements in this file's comments were taken from a copy of that store because it is the only
+ * corpus large enough to answer the questions honestly; the SHIPPED read path is the API.
+ *
+ * **The cursor is the PAIR `messageId:partId`, and the pair is not decoration.** Part ids are
+ * monotonic within a message (measured: 0 inversions over 14 915 parts). They are NOT monotonic
+ * across a session: ordering every part by (message creation, message id, part id) produces 16
+ * inversions over 14 759 ordered pairs, every one of them the first part of a USER message whose id
+ * is lower than the last part of the assistant message before it, because the prompt's text part is
+ * created while the assistant's final part is still being written. Restricted to the assistant-only
+ * stream that §3.2's authorship ruling leaves us with, the count is 0 over 14 084. So a bare
+ * `part.id` cursor would be sound only for as long as an unrelated safety ruling keeps user parts
+ * out, which is a dependency nobody would remember. The pair is sound either way and costs nothing.
+ *
+ * **Removal is tolerated by construction.** The cursor is compared as an ORDER, never looked up as
+ * an identity, so a session whose parts were reverted away resumes from the same position without
+ * the record it names having to still exist. That is what makes the ruling implementable: publish
+ * on finality, and treat a later removal as a logged divergence rather than a halt.
+ */
+import type { DurableSource, SourceRead } from "@cotal-ai/connector-core";
+/** The message fields the mapper needs. Deliberately not the whole `Message`: the source hands on
+ *  identity, authorship and the turn-level completion mark, and nothing it does not read. */
+export interface OpenCodeMessageInfo {
+    id: string;
+    role: string;
+    time?: {
+        created?: number;
+        completed?: number;
+    };
+}
+/** One record: a part, plus the message that owns it. The mapper needs both, because authorship and
+ *  the turn-level finality backstop live on the message, not on the part. */
+export interface OpenCodeRecord {
+    part: OpenCodePart;
+    message: OpenCodeMessageInfo;
+}
+/**
+ * The part shape this source reads. It is a STRUCTURAL subset of the SDK's `Part` union, declared
+ * here rather than imported, for the same reason the Claude mapper declares its own entry type: the
+ * SDK's type describes what OpenCode may write, and this describes what we actually read. Importing
+ * the union would make an SDK bump a compile error in a file that does not care about the fields
+ * that changed.
+ */
+export interface OpenCodePart {
+    id: string;
+    messageID: string;
+    type: string;
+    text?: string;
+    synthetic?: boolean;
+    ignored?: boolean;
+    callID?: string;
+    tool?: string;
+    state?: {
+        status?: string;
+        input?: unknown;
+        output?: string;
+        error?: string;
+        time?: {
+            start?: number;
+            end?: number;
+        };
+    };
+    time?: {
+        start?: number;
+        end?: number;
+    };
+    cost?: number;
+    tokens?: unknown;
+}
+/** One entry of `session.messages()`: the message and its parts. */
+export interface OpenCodeMessageWithParts {
+    info: OpenCodeMessageInfo;
+    parts: OpenCodePart[];
+}
+/** Reads the whole session. Injected so the source can be exercised without a live server. */
+export type ReadSessionMessages = () => Promise<OpenCodeMessageWithParts[]>;
+/**
+ * Is this part settled, so that emitting from it now cannot be contradicted later?
+ *
+ * The question matters because parts are mutated in place long after they appear: 11 518 of 14 915
+ * carry `time_updated > time_created`, and 1 657 of the 11 298 that have a successor were updated
+ * AFTER their successor already existed, by up to 29.5 minutes. "A later part exists" therefore
+ * does NOT mean an earlier one is done, which is the design this measurement killed.
+ *
+ * The turn-level backstop is what stops a stream from wedging on a part that never gets its own end
+ * mark. It is sound in normal operation: the only parts in the corpus updated after their message
+ * reported completed are 830 rows rewritten inside a single 150 ms window, ~16 to 20 per
+ * millisecond, which is a bulk write rather than session behaviour. It matches no timestamp in the
+ * store's migration tables, so it is provably bulk and NOT attributable to a named process.
+ */
+export declare function isSettled(record: OpenCodeRecord): boolean;
+/** Serialise the ordering key. Ids carry no `:`, so the first one separates the halves. */
+export declare function cursorOf(record: OpenCodeRecord): string;
+export interface OpenCodeSessionSourceOptions {
+    /** Reads the session. */
+    read: ReadSessionMessages;
+    /**
+     * Called ONCE per read in which the cursor's own record is no longer present, with the cursor
+     * that vanished. This is the divergence a revert produces, and it is reported rather than thrown:
+     * a user pressing revert is a legitimate session action, and an emitter that died on it would
+     * fail the deliverable. Ordering makes the read itself correct without this; the callback exists
+     * so the divergence is visible instead of silent.
+     */
+    onVanished?: (cursor: string) => void;
+}
+export declare class OpenCodeSessionSource implements DurableSource<OpenCodeRecord> {
+    readonly kind = "opencode-session";
+    private readonly read0;
+    private readonly onVanished?;
+    /** The last cursor already reported as vanished. A revert leaves the cursor absent on EVERY read
+     *  until it advances past the removed region, so reporting per read would turn one divergence
+     *  into a log flood and bury the next, different one. */
+    private reportedVanished?;
+    constructor(opts: OpenCodeSessionSourceOptions);
+    read(cursor: string | undefined): Promise<SourceRead<OpenCodeRecord>>;
+    /**
+     * The contiguous run of settled records from the front, and the cursor of the last of them.
+     *
+     * **STOPPING AT THE FIRST UNSETTLED RECORD IS THE WHOLE POINT**, and it is the same rule
+     * `JsonlFileSource` applies to a half-written line: consume up to the last complete unit, leave
+     * the rest for the next read. Emitting AROUND a part that is still filling would publish frames
+     * out of the order the brackets require, and advancing past it would drop it for good, because
+     * nothing ever revisits a cursor. The cost is head-of-line blocking within a session, which is
+     * the honest price of ordered brackets rather than an oversight.
+     */
+    private settledPrefix;
+}
+//# sourceMappingURL=agui-source.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agui-source.d.ts","sourceRoot":"","sources":["../src/agui-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE1E;6FAC6F;AAC7F,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACjD;AAED;6EAC6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE;YAAE,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,GAAG,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;IACvH,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,oEAAoE;AACpE,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB;AAED,8FAA8F;AAC9F,MAAM,MAAM,mBAAmB,GAAG,MAAM,OAAO,CAAC,wBAAwB,EAAE,CAAC,CAAC;AAS5E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAazD;AAED,2FAA2F;AAC3F,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAEvD;AAgBD,MAAM,WAAW,4BAA4B;IAC3C,yBAAyB;IACzB,IAAI,EAAE,mBAAmB,CAAC;IAC1B;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC;AAED,qBAAa,qBAAsB,YAAW,aAAa,CAAC,cAAc,CAAC;IACzE,QAAQ,CAAC,IAAI,sBAAsB;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsB;IAC5C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAA2B;IACvD;;6DAEyD;IACzD,OAAO,CAAC,gBAAgB,CAAC,CAAS;gBAEtB,IAAI,EAAE,4BAA4B;IAKxC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;IAmC3E;;;;;;;;;OASG;IACH,OAAO,CAAC,aAAa;CAQtB"}

package/dist/extension.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../src/extension.ts"],"names":[],"mappings":"AAGA,OAAO,EAA2B,KAAK,SAAS,EAAuE,MAAM,gBAAgB,CAAC;AAuF9I;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAkJ/B,CAAC"}
+{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../src/extension.ts"],"names":[],"mappings":"AAGA,OAAO,EAA2B,KAAK,SAAS,EAAuE,MAAM,gBAAgB,CAAC;AAuF9I;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,EAAE,SA0L/B,CAAC"}