@sigrun/ext-gateway 0.0.0-stage → 0.1.2

package/dist/outbound/markdown.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Markdown splitting and stripping (spec §8.6): the outbound chunker's
+ * step 1 (split at paragraph, then line, then hard boundaries, with
+ * fence close-and-reopen) and the plain-format renderer's stripper
+ * (headings, emphasis, links → `text (url)`, fences → plain blocks).
+ *
+ * Pure functions over strings — no imports, no clock, no I/O.
+ */
+/**
+ * Split `text` into chunks of at most `limit` characters, preferring
+ * paragraph boundaries, then line boundaries, then hard cuts.
+ *
+ * Fence rule: a code fence cut by a split is CLOSED in the earlier
+ * chunk and REOPENED with its original info string at the head of the
+ * next. An unterminated fence in the input is treated as running to
+ * the end (the last chunk's close terminates it — every emitted chunk
+ * is well-formed on its own).
+ *
+ * Every EMITTED chunk respects the limit: the close suffix a
+ * fence-interior chunk carries ("\n```") is reserved in each fit
+ * check, and hard-split pieces shrink by the ACTUAL reopen width
+ * (info string included — "typescript" reopens 13 chars wide, so a
+ * fixed reserve under-sizes pieces).
+ *
+ * The join of the chunks is a lossless representation of the input
+ * apart from the inserted fence markers and the whitespace the
+ * paragraph/line splits consumed.
+ */
+export declare function splitMarkdown(text: string, limit: number): string[];
+/**
+ * Strip markdown to plain text (the `plain` capability's formatter):
+ * headings lose their `#` markers, emphasis markers are removed, links
+ * render as `text (url)`, and fenced code blocks become their inner
+ * lines. Structure (paragraphs, line breaks) is preserved.
+ */
+export declare function stripMarkdown(text: string): string;

package/dist/outbound/markdown.js

@@ -0,0 +1,286 @@
+/**
+ * Markdown splitting and stripping (spec §8.6): the outbound chunker's
+ * step 1 (split at paragraph, then line, then hard boundaries, with
+ * fence close-and-reopen) and the plain-format renderer's stripper
+ * (headings, emphasis, links → `text (url)`, fences → plain blocks).
+ *
+ * Pure functions over strings — no imports, no clock, no I/O.
+ */
+/**
+ * Split `text` into chunks of at most `limit` characters, preferring
+ * paragraph boundaries, then line boundaries, then hard cuts.
+ *
+ * Fence rule: a code fence cut by a split is CLOSED in the earlier
+ * chunk and REOPENED with its original info string at the head of the
+ * next. An unterminated fence in the input is treated as running to
+ * the end (the last chunk's close terminates it — every emitted chunk
+ * is well-formed on its own).
+ *
+ * Every EMITTED chunk respects the limit: the close suffix a
+ * fence-interior chunk carries ("\n```") is reserved in each fit
+ * check, and hard-split pieces shrink by the ACTUAL reopen width
+ * (info string included — "typescript" reopens 13 chars wide, so a
+ * fixed reserve under-sizes pieces).
+ *
+ * The join of the chunks is a lossless representation of the input
+ * apart from the inserted fence markers and the whitespace the
+ * paragraph/line splits consumed.
+ */
+export function splitMarkdown(text, limit) {
+    if (limit <= 0) {
+        // A zero/negative limit has no legal chunk; the caller's config
+        // validation owns that error. Hard-splitting into empty strings
+        // would loop forever, so the honest fallback is the whole text.
+        return text === "" ? [] : [text];
+    }
+    const lines = text.split("\n");
+    const chunks = [];
+    /** The chunk under construction, joined with "\n". */
+    let current = [];
+    let currentLength = 0;
+    /** Whether a code fence is currently open (independent of its info). */
+    let fenceOpen = false;
+    /** The open fence's info string (e.g. "ts"), undefined when bare. */
+    let openFence;
+    /** Reconstructed open-fence line for reopening (with info string). */
+    const fenceReopen = () => "```" + (openFence === undefined ? "" : openFence);
+    /** The close suffix a chunk ending inside an open fence carries
+     *  ("\n```") — reserved in EVERY fit check so an emitted chunk can
+     *  never exceed the limit (the reservation is pessimistic: a chunk
+     *  the input's own close line terminates simply comes out smaller). */
+    const CLOSE_COST = 4;
+    const flush = () => {
+        if (current.length === 0)
+            return;
+        let chunk = current.join("\n");
+        // A chunk that IS just the fence (re)open marker — bare or with an
+        // info string — is INTERIOR: it was armed as the head of a split
+        // chunk whose body went to the next chunk. endsWith("```") would
+        // mistake it for the input's own close line and emit an UNCLOSED
+        // marker (the lone-``` regression); the close suffix belongs here.
+        const loneMarker = fenceOpen &&
+            /^```[^`]*$/.test(chunk) &&
+            !chunk.includes("\n");
+        if (fenceOpen && (loneMarker || !chunk.endsWith("```"))) {
+            // The chunk ends INSIDE a fence: close it so the chunk stands
+            // alone (the next chunk reopens).
+            chunk += "\n```";
+        }
+        chunks.push(chunk);
+        current = [];
+        currentLength = 0;
+    };
+    /**
+     * Close the current chunk and reopen the fence when one is open —
+     * the shared split point for every path that starts a fresh chunk
+     * (line overflow, paragraph boundary, hard-split pieces).
+     */
+    const closeAndReopen = () => {
+        flush();
+        if (fenceOpen) {
+            const reopen = fenceReopen();
+            current.push(reopen);
+            currentLength = reopen.length;
+        }
+    };
+    const pushLine = (line, lineLength) => {
+        // A chunk that STARTS inside an open fence carries the reopen as
+        // its head line — the well-formed invariant (every chunk is a
+        // standalone fence) holds no matter which path emptied the chunk.
+        if (current.length === 0 && fenceOpen) {
+            const reopen = fenceReopen();
+            current.push(reopen);
+            currentLength = reopen.length;
+        }
+        const joinCost = current.length === 0 ? 0 : 1;
+        const closeCost = fenceOpen ? CLOSE_COST : 0;
+        if (currentLength + joinCost + lineLength + closeCost <= limit) {
+            current.push(line);
+            currentLength += joinCost + lineLength;
+            return;
+        }
+        // The line does not fit: split the chunk (close + reopen when a
+        // fence is open), then place the line — hard-splitting it when
+        // even a fresh chunk cannot hold reopen + line + close.
+        closeAndReopen();
+        const prefixCost = fenceOpen ? currentLength + 1 : 0;
+        if (prefixCost + lineLength + closeCost <= limit) {
+            current.push(line);
+            currentLength += (prefixCost === 0 ? 0 : 1) + lineLength;
+            return;
+        }
+        // The line alone exceeds even a fresh chunk's budget: hard-split
+        // it (the reopen prefix is dropped first — hardSplit re-arms its
+        // own reopen per piece, so every piece's overhead is accounted).
+        current = [];
+        currentLength = 0;
+        hardSplit(line);
+    };
+    /**
+     * Hard-split one overlong line into pieces sized for the fence
+     * overhead (the ACTUAL info string, not a fixed reserve). Each piece
+     * chunk carries reopen + join + piece + close when a fence is open,
+     * so the piece limit is the limit minus that overhead — and every
+     * piece chunk STARTS with the reopen (the prefix is armed per piece,
+     * never inherited from a dropped head).
+     */
+    const hardSplit = (line) => {
+        const reopen = fenceOpen ? fenceReopen() : undefined;
+        const overhead = reopen === undefined ? 0 : reopen.length + 1 + CLOSE_COST;
+        const pieceLimit = Math.max(1, limit - overhead);
+        const emit = (piece) => {
+            if (reopen === undefined) {
+                current.push(piece);
+                currentLength = piece.length;
+            }
+            else {
+                current.push(reopen, piece);
+                currentLength = reopen.length + 1 + piece.length;
+            }
+            // flush appends the close when a fence is open; the next piece
+            // re-arms its own reopen.
+            flush();
+        };
+        let start = 0;
+        for (;;) {
+            const remaining = line.length - start;
+            if (remaining <= pieceLimit) {
+                emit(line.slice(start));
+                return;
+            }
+            emit(line.slice(start, start + pieceLimit));
+            start += pieceLimit;
+        }
+    };
+    let paragraphBreak = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed === "") {
+            // A blank line: a paragraph boundary candidate — INSIDE a fence
+            // too (the split still closes and reopens, keeping every chunk
+            // well-formed; a mid-fence blank line is content, but a split
+            // point there is honest when the chunk is full).
+            if (current.length > 0)
+                paragraphBreak = true;
+            continue;
+        }
+        if (paragraphBreak) {
+            // Split at the paragraph boundary: close (+ reopen inside a
+            // fence) so the next chunk starts well-formed. Fence marker
+            // lines arrive here too — a blank line before a close marker
+            // still splits with the pair.
+            if (current.length > 0)
+                closeAndReopen();
+            paragraphBreak = false;
+        }
+        const fenceMatch = /^```(.*)$/.exec(trimmed);
+        if (fenceMatch !== null) {
+            if (!fenceOpen) {
+                // Opening a fence. The fit decision is made against the
+                // PRE-fence state (fenceOpen still false): flipping it first
+                // would make the overflow flush append a CLOSE suffix to a
+                // plain-text chunk that never opened a fence (the stray-marker
+                // regression). Only when the marker is PLACED does the fence
+                // open.
+                const info = fenceMatch[1] ?? "";
+                const bareInfo = info === "" ? undefined : info;
+                const marker = "```" + (bareInfo === undefined ? "" : bareInfo);
+                const joinCost = current.length === 0 ? 0 : 1;
+                const closeCost = CLOSE_COST;
+                if (currentLength + joinCost + marker.length + closeCost <= limit) {
+                    // The marker fits the current chunk: the fence opens in place.
+                    current.push(marker);
+                    currentLength += joinCost + marker.length;
+                }
+                else {
+                    // The marker does not fit: flush the plain-text chunk AS
+                    // PLAIN TEXT (no fence is open — no close suffix), then open
+                    // the fence at the head of the fresh chunk.
+                    flush();
+                    current.push(marker);
+                    currentLength = marker.length;
+                }
+                fenceOpen = true;
+                openFence = bareInfo;
+                continue;
+            }
+            // Closing a fence: when the current chunk is empty (or holds only
+            // the armed reopen), the PREVIOUS chunk's flush suffix already
+            // closed the fence — emitting the marker would add an empty-fence
+            // chunk, so it is dropped. Otherwise the marker lands normally,
+            // WITHOUT arming a fresh reopen when it overflows (the close is
+            // terminal: a reopened fence just to hold its own terminator is
+            // noise).
+            const onlyReopen = current.length === 1 && current[0] === fenceReopen();
+            if (current.length === 0 || onlyReopen) {
+                current = [];
+                currentLength = 0;
+            }
+            else {
+                const joinCost = current.length === 0 ? 0 : 1;
+                if (currentLength + joinCost + 3 <= limit) {
+                    current.push("```");
+                    currentLength += joinCost + 3;
+                }
+                else {
+                    // The marker does not fit: the chunk closes WITHOUT arming a
+                    // reopen (fenceOpen flips to false first, so flush's suffix
+                    // closes what stands).
+                    fenceOpen = false;
+                    flush();
+                }
+            }
+            fenceOpen = false;
+            openFence = undefined;
+            continue;
+        }
+        pushLine(line, line.length);
+    }
+    flush();
+    // An unterminated fence never emits a trailing empty reopen chunk:
+    // flush() already closed whatever chunk ended inside the fence.
+    return chunks;
+}
+/**
+ * Strip markdown to plain text (the `plain` capability's formatter):
+ * headings lose their `#` markers, emphasis markers are removed, links
+ * render as `text (url)`, and fenced code blocks become their inner
+ * lines. Structure (paragraphs, line breaks) is preserved.
+ */
+export function stripMarkdown(text) {
+    const lines = text.split("\n");
+    const out = [];
+    let inFence = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (/^```/.test(trimmed)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence) {
+            out.push(line);
+            continue;
+        }
+        out.push(stripInline(stripHeading(line)));
+    }
+    // Collapse the blank lines the fence markers consumed (a fence's
+    // open/close lines leave consecutive blanks around the block).
+    return out.join("\n");
+}
+/** Drop a heading's leading `#` run (ATX headings only). */
+function stripHeading(line) {
+    const match = /^(#{1,6})\s+(.*)$/.exec(line);
+    return match === null ? line : match[2] ?? "";
+}
+/** Strip emphasis and rewrite links on ONE line. */
+function stripInline(line) {
+    // Links first: their text may carry emphasis.
+    const text = line.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (_all, label, url) => `${label} (${url})`);
+    // Bold + italics markers (`**`, `__`, `*`, `_` pairs).
+    return text
+        .replace(/\*\*([^*]+)\*\*/g, "$1")
+        .replace(/__([^_]+)__/g, "$1")
+        .replace(/\*([^*]+)\*/g, "$1")
+        // Inline code markers.
+        .replace(/`([^`]+)`/g, "$1");
+}

package/dist/outbound/render.d.ts

@@ -0,0 +1,24 @@
+/**
+ * renderChunks (spec §8.6's three-step order, verbatim):
+ *
+ * 1. Split the markdown final at `maxMessageLength` (paragraph, line,
+ *    hard — {@link splitMarkdown}, with the fence close/reopen rule).
+ * 2. Format each chunk per `capabilities.format`: `markdown` as-is,
+ *    `native` through the adapter's `format`, `plain` through the
+ *    engine's markdown stripper.
+ * 3. A formatted chunk that STILL exceeds `maxMessageLength` (native
+ *    markup grew it) is hard-split.
+ *
+ * Empty input renders to zero chunks (the caller owns the empty-answer
+ * notice — Review Focus 4).
+ */
+import type { ChannelCapabilities } from "@sigrun/sigrun/extension";
+/**
+ * Render the markdown final into platform-ready chunks. `format` is the
+ * adapter's formatter (`ChannelContribution.format`), required only for
+ * `native` capabilities — a missing formatter on a native channel is
+ * the loader's contract violation, handled by the caller; here the
+ * chunk passes through unformatted (the honest degraded behavior for
+ * an adapter that declared native markup and shipped no renderer).
+ */
+export declare function renderChunks(markdown: string, caps: ChannelCapabilities, format?: (md: string) => string): string[];

package/dist/outbound/render.js

@@ -0,0 +1,65 @@
+/**
+ * renderChunks (spec §8.6's three-step order, verbatim):
+ *
+ * 1. Split the markdown final at `maxMessageLength` (paragraph, line,
+ *    hard — {@link splitMarkdown}, with the fence close/reopen rule).
+ * 2. Format each chunk per `capabilities.format`: `markdown` as-is,
+ *    `native` through the adapter's `format`, `plain` through the
+ *    engine's markdown stripper.
+ * 3. A formatted chunk that STILL exceeds `maxMessageLength` (native
+ *    markup grew it) is hard-split.
+ *
+ * Empty input renders to zero chunks (the caller owns the empty-answer
+ * notice — Review Focus 4).
+ */
+import { splitMarkdown, stripMarkdown } from "./markdown.js";
+/**
+ * Render the markdown final into platform-ready chunks. `format` is the
+ * adapter's formatter (`ChannelContribution.format`), required only for
+ * `native` capabilities — a missing formatter on a native channel is
+ * the loader's contract violation, handled by the caller; here the
+ * chunk passes through unformatted (the honest degraded behavior for
+ * an adapter that declared native markup and shipped no renderer).
+ */
+export function renderChunks(markdown, caps, format) {
+    if (markdown === "")
+        return [];
+    // Step 1: split at the platform's message ceiling.
+    const split = splitMarkdown(markdown, caps.maxMessageLength);
+    // Step 2 + 3: format, then hard-split whatever formatting grew.
+    const out = [];
+    for (const chunk of split) {
+        const formatted = formatChunk(chunk, caps, format);
+        if (formatted.length <= caps.maxMessageLength) {
+            out.push(formatted);
+            continue;
+        }
+        // Native markup grew the chunk past the ceiling: hard-split the
+        // FORMATTED text (no fence knowledge — the adapter's markup is
+        // opaque to the engine; closing it would be guesswork).
+        out.push(...hardSplit(formatted, caps.maxMessageLength));
+    }
+    return out;
+}
+/** Step 2 for one chunk. */
+function formatChunk(chunk, caps, format) {
+    switch (caps.format) {
+        case "markdown":
+            return chunk;
+        case "plain":
+            return stripMarkdown(chunk);
+        case "native":
+            return format === undefined ? chunk : format(chunk);
+    }
+}
+/** Hard-split one formatted string at exact `limit` boundaries. A
+ *  non-positive limit (a misconfigured adapter) degrades to length-1
+ *  pieces — never an infinite loop of empty slices. */
+function hardSplit(text, limit) {
+    const step = Math.max(1, limit);
+    const pieces = [];
+    for (let start = 0; start < text.length; start += step) {
+        pieces.push(text.slice(start, start + step));
+    }
+    return pieces;
+}

package/dist/outbound/settled.d.ts

@@ -0,0 +1,81 @@
+/**
+ * onRunSettled (spec §8.6's "which runs deliver" + the M7 access
+ * re-check): the engine's `runSettled` factory handler. ONLY ENQUEUES —
+ * the per-channel delivery workers own the platform calls.
+ *
+ * - Every key in `bindings.keysOf(conversationId)` that is not dead
+ *   gets a final (whoever started the run — ruling 4: a webui submit
+ *   into a bound conversation delivers to the chat).
+ * - Access is RE-CHECKED per delivery (M7): `meta` + `accessOf` for
+ *   the binding's user — the LINKED user for DMs, the group owner for
+ *   groups. A failed check UNBINDS the chat, logs it, and enqueues
+ *   nothing.
+ * - An answered run renders the answer's text blocks (thinking and
+ *   tool calls are never shown); an answer with NO text blocks gets
+ *   the pinned "(no text reply)" notice (Review Focus 4 — an empty
+ *   send is a platform rejection, never an honest reply).
+ * - The origin-chat streaming hand-off runs through `deps.streams`:
+ *   rendered chunks cross to the registry at this layer while the
+ *   boolean answer decides whether the origin's finals enqueue.
+ * - An unanswered run notifies the ORIGIN chat only (from
+ *   `deps.origins`): the pinned "Stopped." for an abort reason, a
+ *   short reason notice otherwise.
+ */
+import type { ChannelContribution, RunSettledEvent, SigrunHost } from "@sigrun/sigrun/extension";
+import type { SubmissionId } from "@earendil-works/pi-durable";
+import type { SessionMeta } from "@sigrun/shared/session-meta";
+import type { ChannelConfig } from "../config.js";
+import type { BindingStore } from "../state/bindings.js";
+import type { Ledger } from "../state/ledger.js";
+import { type EngineLog } from "../log.js";
+import type { IdentityStore } from "../state/identities.js";
+import type { SubmissionOrigin } from "../inbound/pipeline.js";
+/** The pinned notice for a textless answer (Review Focus 4). */
+export declare const NO_TEXT_REPLY = "(no text reply)";
+/** The pinned abort notice (spec §8.6: "An abort from /stop produces Stopped."). */
+export declare const STOPPED = "Stopped.";
+/**
+ * The streaming hand-off seam. `finalize` answers ONE question: did
+ * the stream own this conversation's origin-chat delivery? Chunks are
+ * rendered by the settled path (which knows the answer and caps) and
+ * consumed by the registry; the boolean-only fan-out decision remains
+ * independent of that delivery work. `abandon` releases unanswered runs.
+ */
+export interface Streams {
+    finalize(conversationId: number, chunks: string[]): Promise<boolean>;
+    abandon(conversationId: number): void;
+}
+/**
+ * The job-delivery metadata the settled fan-out reads. Derived from the
+ * canonical shared session-meta wire type (type-only: no runtime core
+ * dependency) so field drift fails the contract fixture's typecheck.
+ */
+export type GatewayJobMeta = Pick<SessionMeta, "owner" | "name" | "autoName" | "jobId" | "deliver">;
+/** onRunSettled's injectable dependencies. */
+export interface SettledDeps {
+    readonly host: SigrunHost;
+    /** The event bus's bridge-free document read (factory-supplied). */
+    readonly readMeta?: (conversationId: number) => Promise<GatewayJobMeta | undefined>;
+    /** The engine-wide bindings (the delivery fan-out read). */
+    readonly bindings: BindingStore;
+    /** The engine-wide identity links (the binding's user resolution). */
+    readonly identities: IdentityStore;
+    /** The ledger the finals enqueue into. */
+    readonly ledger: Ledger;
+    /** The channel id → adapter lookup (the render step's caps/format). */
+    readonly channelOf: (id: string) => ChannelContribution | undefined;
+    /** The live channel configs (the group owner read). */
+    readonly configOf: (id: string) => Promise<ChannelConfig | undefined>;
+    /** submissionId → the origin record (the unanswered notice's target). */
+    readonly origins: Map<SubmissionId, SubmissionOrigin>;
+    /** The origin-chat stream registry. */
+    readonly streams: Streams;
+    readonly log: EngineLog;
+}
+/**
+ * The settled-run handler: enqueue finals (or the empty-answer notice)
+ * for every live bound chat, and the unanswered notice for the origin
+ * chat. Never throws (the event bus's bounded handler owns isolation,
+ * but a ledger failure must not lose the rest of the fan-out).
+ */
+export declare function onRunSettled(event: RunSettledEvent, deps: SettledDeps): Promise<void>;