@cotal-ai/connector-core 0.18.0 → 0.19.0

package/dist/agui-render.js

@@ -0,0 +1,283 @@
+/**
+ * THE FIRST RENDERER THAT CAN DISPLAY AN AG-UI FRAME.
+ *
+ * A frame carries **no text part by design** — its content is a list of AG-UI events — so every
+ * surface that renders a message as flat text draws one as `[unrenderable part kind "ag-ui.frame"]`.
+ * This is the provider that fixes that for the console family: a core {@link PartRenderer} of kind
+ * `part-renderer`, named for the part kind it draws, self-registering on import exactly as a
+ * terminal-layout provider does.
+ *
+ * **IT LANDS BEFORE ANY PRODUCER, AND THAT ORDERING IS THE POINT.** At this tip nothing in
+ * production publishes a frame: no connector constructs an emitter and every connector still writes
+ * its `tr-<name>` text mirror. So this renderer has no live traffic to draw yet, and saying that
+ * plainly matters more than it sounds, because the alternative ordering is the one that fails. A
+ * cutover shipped first would replace a mirror a human can read with a part every surface shows as a
+ * marker, and the regression would be invisible to the change that caused it. Display first, then
+ * the producer.
+ *
+ * **CORE NEVER LEARNS AG-UI.** `partsToText` resolves a renderer by the part's own kind and calls
+ * it. The knowledge of what a `TOOL_CALL_ARGS` means lives here, in the package that defined the
+ * vocabulary, which is where `AGENTS.md` requires an adapter's concepts to stay. What moved into
+ * core is only the frame's IDENTITY (`agui-kind.ts`) and the channel's NAME (`event-channel.ts`),
+ * both of which a reader needs to recognise a frame without knowing who produced it.
+ *
+ * ── WHAT IT DELIBERATELY DOES NOT DO ────────────────────────────────────────────────────────────
+ *
+ * **It does not print raw event-type tokens.** A reader wants `bash({"cmd":"ls"}) -> ok`, not
+ * `TOOL_CALL_START TOOL_CALL_ARGS TOOL_CALL_RESULT`. So the suite must not assert the token either:
+ * gating on `TOOL_CALL_ARGS` appearing in the output would fail a correct renderer, which is why the
+ * cells assert the FOLD (name, arguments, result) rather than the vocabulary.
+ *
+ * **It does not validate the frame as a schema.** `parseAguiFrame` checks the envelope and that each
+ * event's `type` is in the vocabulary, and nothing else, which is measured rather than assumed. So
+ * this renderer treats event fields as untrusted: every field access is guarded and a malformed
+ * event degrades to a named marker rather than throwing. A renderer is the wrong place to discover a
+ * producer's bug, and a very good place to make one visible.
+ *
+ * ── WHY IT ROUTES ON THE KIND AND NEVER ON SHAPE ────────────────────────────────────────────────
+ *
+ * Two formats will share one channel for exactly as long as the cutover takes: `events.<owner>.<actor>`
+ * is designed to carry frames, while the connectors that have not cut over still publish plain text
+ * parts to their own mirror. Registration is for `ag-ui.frame` ONLY, so a text part renders as the
+ * text it is and never as a degenerate frame. The two cannot be confused because the routing is on
+ * the part kind and not on a guess about shape.
+ */
+import { AGUI_EVENT_TYPE, AGUI_FRAME_KIND, isAguiFramePart, registry } from "@cotal-ai/core";
+const str = (v) => (typeof v === "string" ? v : undefined);
+/**
+ * Line prefixes. **Every one of these starts with a non-space glyph within the first three columns,
+ * and that is a requirement rather than a style choice.** Leading spaces do not establish a line
+ * start, they indent one, so a prefix of spaces alone leaves the payload's first character still the
+ * first character of the line. `CONT` therefore carries `·`, and no prefix here may be widened past
+ * three leading spaces without re-deriving {@link LINE_START_SAFE}.
+ */
+const CONT = "  · ";
+const TEXT_PREFIX = "» ";
+const THINK_PREFIX = "(thinking) ";
+const TOOL_PREFIX = "⚙ ";
+const RESULT_PREFIX = "  ↳ ";
+/**
+ * Every character markdown can read as BEGINNING a block, so {@link LINE_START_SAFE} never has to
+ * know which block: `#` heading, `>` quote, `|` table, `` ` `` and `~` fence, `=` and `-` setext
+ * underline, `-` `*` `+` bullet, `*` `_` `-` thematic break, a digit for an ordered list, `[` a link
+ * reference definition (which renders as NOTHING, so it deletes the line it is on), and a tab, which
+ * counts as up to four columns of indent and so opens code.
+ */
+const BLOCK_START_CHARS = new Set([..."#>|`~=_*+-[<0123456789", "\t"]);
+/**
+ * A line this renderer is allowed to emit: one that cannot open a block construct.
+ *
+ * **Exported so the suite asserts the invariant against the SAME expression the renderer is
+ * documented by**, rather than a second copy of it that can drift. It is a property of the emitted
+ * lines and nothing more, deliberately not a claim about what any consumer does downstream, which
+ * would be an assertion outside this module that no test here could hold up.
+ *
+ * **IT TESTS THE FIRST CHARACTER, NOT A LIST OF CONSTRUCTS, AND THAT IS THE WHOLE POINT.** The
+ * previous version enumerated the openers it knew (ATX heading, bullet, ordered list, blockquote,
+ * table row, indented code) and called them "the block-level openers". An enumeration of a syntax
+ * someone else defines is incomplete the moment it is written, and this one was: a bare `---`, `***`
+ * and a fence line all PASSED it while being a thematic break, a setext underline and a code fence.
+ * The suite stayed green because the PREFIXES stop the renderer from emitting such a line at all,
+ * which means the predicate was passing for a reason unrelated to what it claimed to check, and a
+ * weakened prefix would not have been caught by the thing whose job is to catch exactly that.
+ *
+ * So the rule is a property of one character: a line is safe when its first non-space character
+ * arrives within three columns and is not one markdown can read as beginning a block. That is
+ * stricter than the constructs strictly require (`1x` and `-x` open nothing and are refused anyway),
+ * and strictness is the correct direction here, because this constrains what THIS renderer emits and
+ * every line it emits carries a glyph prefix that is not punctuation at all.
+ */
+export const LINE_START_SAFE = (line) => {
+    if (line === "")
+        return true; // a blank line opens nothing and separates rather than nests
+    const indent = /^ */.exec(line)[0].length;
+    if (indent > 3)
+        return false; // four columns is an indented code block
+    const first = line[indent];
+    if (first === undefined)
+        return true; // spaces only, same as blank
+    return !BLOCK_START_CHARS.has(first);
+};
+/**
+ * Fold a frame's events into display lines.
+ *
+ * Deltas are ACCUMULATED rather than printed one per line: `TEXT_MESSAGE_CONTENT` arrives as a
+ * stream of fragments, and a renderer that printed each one would turn a sentence into a column.
+ * They are keyed by `messageId`/`toolCallId` so two interleaved streams do not braid into each
+ * other; the ids exist precisely because interleaving is legal.
+ */
+function renderEvents(events) {
+    const lines = [];
+    const text = new Map();
+    const reasoning = new Map();
+    const toolName = new Map();
+    const toolArgs = new Map();
+    /**
+     * Emit a payload as lines, prefixing EVERY line, not just the first.
+     *
+     * **THE STRUCTURAL INVARIANT THIS EXISTS FOR: no emitted line begins with a payload character.**
+     * Payload values are multi-line (a tool result is the common case, but pretty-printed args, a
+     * multi-paragraph message and an error body all are), and pushing one of them as a single string
+     * put its second and later lines at column 0 with nothing of the renderer's in front of them.
+     *
+     * At that point the payload is no longer inside the scaffolding, it IS scaffolding, and a consumer
+     * that reads line starts cannot tell which lines the renderer wrote. **Measured: a tool result
+     * whose second line began `- ` captured the frame's own `◂ run … finished` terminator into a list
+     * the payload had opened.** The invariant is asserted over this function's output in the suite.
+     *
+     * `cont` carries a non-space glyph for the same reason `first` does: leading spaces alone do not
+     * establish a line start, they only indent one.
+     */
+    const emit = (first, cont, body) => {
+        const [head, ...rest] = body.split("\n");
+        lines.push(first + head);
+        for (const l of rest)
+            lines.push(cont + l);
+    };
+    /** Flush an accumulator, if it has anything in it. */
+    const flush = (map, id, first, cont, suffix = "") => {
+        const acc = map.get(id);
+        if (acc !== undefined && acc.length > 0)
+            emit(first, cont, acc + suffix);
+        map.delete(id);
+    };
+    for (const e of events) {
+        // THE ELEMENT ITSELF IS UNTRUSTED, not just its fields. `events` is an array off the wire and
+        // `parseAguiFrame` does not check that each element is an object, so `null` reaches here and a
+        // bare `e.type` throws on it. The throw was not fatal (core's dispatcher turns it into a named
+        // marker) and that is exactly what made it worth guarding: the whole frame degraded to one
+        // failure line, so a single null element deleted every other event in the frame from the
+        // reader's view. Named per element instead, so one malformed event costs one line.
+        const type = typeof e === "object" && e !== null ? str(e.type) : undefined;
+        switch (type) {
+            case AGUI_EVENT_TYPE.RUN_STARTED:
+                emit("▸ ", CONT, `run ${str(e.runId) ?? "?"} started`);
+                break;
+            case AGUI_EVENT_TYPE.RUN_FINISHED: {
+                // `outcome` is optional by the real schema — a turn that merely ended says nothing more, and
+                // manufacturing "success" would assert something the source never said.
+                const outcome = str(e.outcome?.type);
+                emit("◂ ", CONT, `run ${str(e.runId) ?? "?"} finished${outcome ? ` (${outcome})` : ""}`);
+                break;
+            }
+            case AGUI_EVENT_TYPE.RUN_ERROR: {
+                const code = str(e.code);
+                emit("✗ ", CONT, `run error${code ? ` [${code}]` : ""}: ${str(e.message) ?? "(no message)"}`);
+                break;
+            }
+            case AGUI_EVENT_TYPE.TEXT_MESSAGE_START:
+                text.set(str(e.messageId) ?? "", "");
+                break;
+            case AGUI_EVENT_TYPE.TEXT_MESSAGE_CONTENT: {
+                const id = str(e.messageId) ?? "";
+                text.set(id, (text.get(id) ?? "") + (str(e.delta) ?? ""));
+                break;
+            }
+            case AGUI_EVENT_TYPE.TEXT_MESSAGE_END:
+                flush(text, str(e.messageId) ?? "", TEXT_PREFIX, TEXT_PREFIX);
+                break;
+            case AGUI_EVENT_TYPE.REASONING_MESSAGE_START:
+                reasoning.set(str(e.messageId) ?? "", "");
+                break;
+            case AGUI_EVENT_TYPE.REASONING_MESSAGE_CONTENT: {
+                const id = str(e.messageId) ?? "";
+                reasoning.set(id, (reasoning.get(id) ?? "") + (str(e.delta) ?? ""));
+                break;
+            }
+            case AGUI_EVENT_TYPE.REASONING_MESSAGE_END:
+                flush(reasoning, str(e.messageId) ?? "", THINK_PREFIX, CONT);
+                break;
+            case AGUI_EVENT_TYPE.TOOL_CALL_START: {
+                const id = str(e.toolCallId) ?? "";
+                toolName.set(id, str(e.toolCallName) ?? "?");
+                toolArgs.set(id, "");
+                break;
+            }
+            case AGUI_EVENT_TYPE.TOOL_CALL_ARGS: {
+                const id = str(e.toolCallId) ?? "";
+                toolArgs.set(id, (toolArgs.get(id) ?? "") + (str(e.delta) ?? ""));
+                break;
+            }
+            case AGUI_EVENT_TYPE.TOOL_CALL_END: {
+                const id = str(e.toolCallId) ?? "";
+                emit(TOOL_PREFIX, CONT, `${toolName.get(id) ?? "?"}(${toolArgs.get(id) ?? ""})`);
+                toolName.delete(id);
+                toolArgs.delete(id);
+                break;
+            }
+            case AGUI_EVENT_TYPE.TOOL_CALL_RESULT:
+                emit(RESULT_PREFIX, CONT, str(e.content) ?? "(no content)");
+                break;
+            case AGUI_EVENT_TYPE.CUSTOM:
+                emit("• ", CONT, `custom ${str(e.name) ?? "(unnamed)"}`);
+                break;
+            // An event whose `type` this build does not know. NAMED, never skipped — a skipped event is a
+            // hole in a transcript that still looks complete, which is `parseAguiFrame`'s own stated
+            // reason for refusing one. Here the surface is a reader rather than a parser, so it is shown.
+            default:
+                emit("• ", CONT, `unrecognised event ${JSON.stringify(type ?? null)}`);
+        }
+    }
+    // A stream that ended without its END event still has content a reader needs. Dropping it would
+    // make a truncated turn indistinguishable from a silent one, which is the exact failure the mirror
+    // had.
+    for (const id of [...text.keys()])
+        flush(text, id, TEXT_PREFIX, TEXT_PREFIX, " …");
+    for (const id of [...reasoning.keys()])
+        flush(reasoning, id, THINK_PREFIX, CONT, " …");
+    for (const id of [...toolName.keys()])
+        emit(TOOL_PREFIX, CONT, `${toolName.get(id) ?? "?"}(${toolArgs.get(id) ?? ""}) …`);
+    return lines;
+}
+/**
+ * The registered provider. `name` IS the part kind, which is how core resolves it without ever
+ * learning what the kind means.
+ */
+export const aguiFramePartRenderer = Object.freeze({
+    kind: "part-renderer",
+    name: AGUI_FRAME_KIND,
+    render(part) {
+        // Defensive rather than trusting: core resolved us by kind, but a caller can hand us anything.
+        if (!isAguiFramePart(part))
+            return `[not an AG-UI frame]`;
+        const events = part.events;
+        if (!Array.isArray(events) || events.length === 0)
+            return `[AG-UI frame carrying no events]`;
+        const lines = renderEvents(events);
+        // An events array that produced no lines is impossible today (every branch pushes), but if a
+        // future branch returns nothing this must not become the silent empty string that the whole
+        // exercise exists to remove.
+        return lines.length > 0 ? lines.join("\n") : `[AG-UI frame with ${events.length} event(s) and nothing to show]`;
+    },
+});
+/**
+ * Register the provider, once, however many copies of this module get loaded.
+ *
+ * **THIS PACKAGE LEGITIMATELY EXISTS TWICE IN ONE PROCESS, AND A BARE `register` CRASHES THERE.**
+ * Measured, not anticipated: `cotal ext add <connector>` failed with
+ * `extension already registered: part-renderer:ag-ui.frame`, and the mechanism is the extension
+ * prefix's layout. The CLI imports this module from its OWN copy of `connector-core`. Materializing
+ * an installed connector imports `connector-core` again, from the extension prefix's `node_modules`,
+ * which is a different physical file and therefore a second module instance with its own top-level
+ * evaluation. `@cotal-ai/core` is LINKED to the CLI's single copy (`ext add` writes that link on
+ * purpose), so both instances see ONE registry, and `registry.register` throws on the duplicate
+ * `kind:name`. That throw took down `ext add` for every connector.
+ *
+ * **WHY THIS IS NOT THE SILENT DEGRADE THE PROJECT REFUSES.** `register`'s refusal exists to catch
+ * TWO EXTENSIONS CLAIMING ONE NAME, which is a genuine conflict nobody can adjudicate. This is one
+ * extension arriving twice, which is not a conflict: `ag-ui.frame` is defined by this package, no
+ * other package may claim it, and every copy of this file registers a provider that draws it the
+ * same way. First one wins, deterministically, and the second is a no-op rather than a fatal error
+ * on a path a customer runs. Skipping a duplicate self-registration is a different act from
+ * swallowing a failure.
+ *
+ * It is a named function rather than a bare guard so the property is executable: a cell calls it
+ * twice and asserts the second call neither throws nor displaces the first.
+ */
+export function registerAguiFramePartRenderer() {
+    if (registry.has("part-renderer", AGUI_FRAME_KIND))
+        return;
+    registry.register(aguiFramePartRenderer);
+}
+registerAguiFramePartRenderer();
+//# sourceMappingURL=agui-render.js.map

package/dist/agui-render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agui-render.js","sourceRoot":"","sources":["../src/agui-render.ts"],"names":[],"mappings":"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"}

package/dist/agui-wal-path.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Thrown when a session that is going to publish events cannot say where its WAL belongs.
+ *
+ * A distinct type rather than a bare `Error` so a caller can tell "misconfigured launch" from
+ * "filesystem said no" without matching on message text.
+ */
+export declare class EventsStateRootMissing extends Error {
+    constructor(message: string);
+}
+/**
+ * The state root for an events-enabled session, or a loud failure.
+ *
+ * **THE FAILURE THIS PREVENTS IS SILENT, WHICH IS WHY IT IS A THROW AND NOT A DEFAULT.** The
+ * tempting fallback is `process.cwd()`. A WAL written there is not an error anyone sees: the emitter
+ * starts, frames publish, and the durable state that makes a restart safe sits in whatever directory
+ * the launch happened to begin in — a per-agent working directory that "can point at any repo". The
+ * next start resolves the real root, finds no WAL, and reads an already-published thread as VIRGIN:
+ * `E := 0`, a fresh epoch, a second frame claiming a sequence the stream has already seen. Nothing
+ * reports a problem at any point, and an absence is what a clean board looks like.
+ *
+ * `env` is a PARAMETER and the root resolves PER CALL. A module-level read would freeze whatever the
+ * environment was at first import, and none of what this path is keyed on — space, principal,
+ * thread — is process-wide.
+ */
+export declare function resolveEventsStateRoot(env: {
+    COTAL_WORKSPACE_ROOT?: string | undefined;
+}): string;
+/** The resolved locations for one `(space, principal, threadId)`. Pure: computes, touches nothing. */
+export interface EventWalLocation {
+    /** `<workspaceRoot>/.cotal/events/<h(space)>/<h(principal)>` — the lock's directory. */
+    principalDir: string;
+    /** The single-emitter-per-principal lock. One emitter per PRINCIPAL, not per thread. */
+    lockPath: string;
+    /** `<principalDir>/<h(threadId)>` — the directory holding exactly one `wal.json`. */
+    threadDir: string;
+    /** The WAL document itself. */
+    walPath: string;
+}
+/** What {@link ensureEventWalDir} returns: the location, plus the lock it actually took for it. */
+export interface HeldEventWalLocation extends EventWalLocation {
+    lock: PrincipalLock;
+}
+/**
+ * Resolve where this principal's WAL for this thread lives. Pure — no IO, no side effects.
+ *
+ * `workspaceRoot` is taken as given rather than defaulted. A default here would be a silent fallback
+ * onto whatever directory the process happened to start in, which is precisely the scattering the
+ * root exists to prevent; the caller that cannot resolve one must fail loud instead.
+ */
+export declare function eventWalLocation(opts: {
+    workspaceRoot: string;
+    space: string;
+    principal: string;
+    threadId: string;
+}): EventWalLocation;
+/** Every refusal on the lock path is one of these, so a caller never mistakes it for an I/O blip. */
+export declare class PrincipalLockError extends Error {
+    readonly path: string;
+    readonly invariant: string;
+    constructor(path: string, invariant: string, detail: string);
+}
+/** A HELD lock. It exists as an object only while this process owns the file. */
+export interface PrincipalLock {
+    readonly path: string;
+    /** Close the handle and remove the file. Idempotent: releasing twice is not an error. */
+    release(): Promise<void>;
+}
+/**
+ * Take this principal's lock and HOLD IT for the life of the process.
+ *
+ * The handle stays open deliberately. A lock released at the end of the acquiring function is a
+ * lock that was never held, and the layout comment above has claimed single-emitter exclusion since
+ * this module was written while `lockPath` was only ever COMPUTED — a path in a struct standing in
+ * for a guarantee. This is that claim made real.
+ */
+export declare function acquirePrincipalLock(lockPath: string): Promise<PrincipalLock>;
+/**
+ * Create the directory chain for a thread's WAL and make it durable: **once, before the
+ * first transition.**
+ *
+ * The WAL's own replace protocol fsyncs `wal.json` and the thread directory that holds it. That is
+ * not sufficient on its own: a newly created `<h(threadId)>/` directory's NAME is an entry in its
+ * PARENT, and `ensureDirNoSymlink` only `mkdir`s each missing component with no fsync anywhere. On a
+ * filesystem that honours the distinction, a crash after the first transition and after the publish
+ * can come back with the directory link itself lost — no WAL, no pending record — and boot then
+ * reads a thread that has already published as VIRGIN: `E := 0`, a fresh epoch, and a second frame
+ * claiming a sequence the stream has already seen.
+ *
+ * So every component from the workspace root down is fsynced, parents included, rather than the leaf
+ * alone. It runs once at emitter start; the cost is a handful of directory syncs against a session
+ * that is about to do real work.
+ *
+ * Returns the WAL path, so a caller cannot resolve the location by one route and create it by
+ * another — and the HELD principal lock with it, for the same reason. Handing back a location whose
+ * lock the caller then has to remember to take is how the lock came to be a path and nothing else.
+ */
+export declare function ensureEventWalDir(opts: {
+    workspaceRoot: string;
+    space: string;
+    principal: string;
+    threadId: string;
+}): Promise<HeldEventWalLocation>;
+//# sourceMappingURL=agui-wal-path.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agui-wal-path.d.ts","sourceRoot":"","sources":["../src/agui-wal-path.ts"],"names":[],"mappings":"AAwCA;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE;IAAE,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAAG,MAAM,CAWjG;AAaD,sGAAsG;AACtG,MAAM,WAAW,gBAAgB;IAC/B,wFAAwF;IACxF,YAAY,EAAE,MAAM,CAAC;IACrB,wFAAwF;IACxF,QAAQ,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,SAAS,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,mGAAmG;AACnG,MAAM,WAAW,oBAAqB,SAAQ,gBAAgB;IAC5D,IAAI,EAAE,aAAa,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,gBAAgB,CASnB;AAED,qGAAqG;AACrG,qBAAa,kBAAmB,SAAQ,KAAK;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM;IAAE,QAAQ,CAAC,SAAS,EAAE,MAAM;gBAAxC,IAAI,EAAE,MAAM,EAAW,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAI9E;AAED,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yFAAyF;IACzF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AA4FD;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAqCnF;AA8BD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAqBhC"}