@jini-ai/daemon 0.1.0

package/dist/artifacts/text-suppression.js

@@ -0,0 +1,184 @@
+/**
+ * @module artifacts/text-suppression
+ *
+ * A streaming-text state machine that suppresses a tagged block (matched by
+ * caller-supplied open/close patterns) from user-visible output while it's
+ * still arriving — used to hide an artifact's raw markup from chat prose
+ * while it streams in, without buffering the whole response first. Ported
+ * from OD's `apps/daemon/src/artifacts/text-suppression.ts`.
+ *
+ * The core (`createTaggedTextSuppressor`) was already fully generic in the
+ * origin — it takes its open/close regexes and open/close prefix-match
+ * predicates as parameters, no product coupling. What needed de-branding
+ * were the origin's two pre-built instances: `createDsmlArtifactTextSuppressor`
+ * hardcoded OD's own "DSML" markup-language tag name family
+ * (`<|DSML artifact>`/`<artifact>`) as its open/close patterns.
+ * `createXmlTagTextSuppressor` below replaces it — a generic factory taking
+ * the caller's own tag-name list instead of a hardcoded vocabulary. The
+ * `tool_call`/`edit` pairing the origin's other instance
+ * (`createToolCallTextSuppressor`) suppressed is a generic agent-protocol
+ * convention, not OD-branded, and is kept as a named default instance.
+ */
+const MAX_CANDIDATE_LENGTH = 512;
+/**
+ * Builds a suppressor for a tagged block delimited by `openRe`/`closeRe`.
+ * `isPossibleOpen`/`isPossibleClose` decide whether a trailing `<...`
+ * fragment (with no closing `>` yet) *could* still become a match once more
+ * text arrives — this is what lets the suppressor hold back a
+ * not-yet-decidable tail across streaming chunk boundaries instead of
+ * either emitting a tag fragment early or hanging indefinitely on a `<` that
+ * turns out to be unrelated text.
+ */
+export function createTaggedTextSuppressor(args) {
+    let suppressing = false;
+    let candidate = '';
+    let suppressedChars = 0;
+    let suppressedChunks = 0;
+    let openedBlocks = 0;
+    let closedBlocks = 0;
+    function noteSuppressed(text) {
+        if (text.length <= 0)
+            return;
+        suppressedChars += text.length;
+        suppressedChunks += 1;
+    }
+    function strip(text) {
+        const current = `${candidate}${text}`;
+        candidate = '';
+        if (suppressing) {
+            const close = args.closeRe.exec(current);
+            if (!close || close.index === undefined) {
+                const closeCandidateStart = possibleTagStart(current, args.isPossibleClose);
+                if (closeCandidateStart !== -1) {
+                    candidate = current.slice(closeCandidateStart);
+                    noteSuppressed(current.slice(0, closeCandidateStart));
+                }
+                else {
+                    noteSuppressed(current);
+                }
+                return '';
+            }
+            suppressing = false;
+            const end = close.index + close[0].length;
+            closedBlocks += 1;
+            noteSuppressed(current.slice(0, end));
+            return strip(current.slice(end));
+        }
+        const open = args.openRe.exec(current);
+        if (open && open.index !== undefined) {
+            suppressing = true;
+            openedBlocks += 1;
+            const prefix = current.slice(0, open.index);
+            const tail = current.slice(open.index + open[0].length);
+            noteSuppressed(open[0]);
+            return `${prefix}${strip(tail)}`;
+        }
+        const candidateStart = possibleTagStart(current, args.isPossibleOpen);
+        if (candidateStart === -1)
+            return current;
+        candidate = current.slice(candidateStart);
+        return current.slice(0, candidateStart);
+    }
+    function flush() {
+        const text = candidate;
+        candidate = '';
+        return suppressing ? '' : text;
+    }
+    function isSuppressing() {
+        return suppressing;
+    }
+    function hasPendingCandidate() {
+        return candidate.length > 0;
+    }
+    function stats() {
+        return {
+            suppressedChars,
+            suppressedChunks,
+            openedBlocks,
+            closedBlocks,
+            pendingCandidateChars: candidate.length,
+            suppressing,
+        };
+    }
+    return { strip, flush, isSuppressing, hasPendingCandidate, stats };
+}
+/** Feeds `text` through `suppressor` and emits a `text_delta` on `onEvent` only when something survives. Returns whether an event was emitted. */
+export function emitWithTextSuppressor(suppressor, onEvent, text) {
+    const delta = suppressor.strip(text);
+    if (!delta)
+        return false;
+    onEvent({ type: 'text_delta', delta });
+    return true;
+}
+function possibleTagStart(text, predicate) {
+    const min = Math.max(0, text.length - MAX_CANDIDATE_LENGTH);
+    let index = text.lastIndexOf('<');
+    while (index >= min) {
+        const tail = text.slice(index);
+        if (predicate(tail))
+            return index;
+        if (index === 0)
+            break;
+        index = text.lastIndexOf('<', index - 1);
+    }
+    return -1;
+}
+// `text` is always a `possibleTagStart` tail slice starting at a `<`
+// position (its only caller) — no `!text.startsWith('<')` re-check needed.
+function compactTagCandidate(text, stripChars) {
+    if (text.includes('>'))
+        return null;
+    return text.toLowerCase().replace(stripChars, '');
+}
+/**
+ * Builds a suppressor for an XML-like `<tagName ...>...</tagName>` block (or
+ * a bracket-pipe variant `<|tagName ...>...<|/tagName|>`), matched
+ * case-insensitively against any of `tagNames`. Replaces the origin's
+ * hardcoded "DSML" tag-name family with a caller-supplied vocabulary.
+ */
+export function createXmlTagTextSuppressor(tagNames) {
+    const canonicals = tagNames.map((t) => t.toLowerCase());
+    const namesPattern = canonicals.map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
+    const openRe = new RegExp(`(?:<\\s*\\|?\\s*(?:${namesPattern})\\b[^>]*>)`, 'i');
+    const closeRe = new RegExp(`(?:<\\/(?:${namesPattern})>|<\\s*\\|?\\s*\\/\\s*(?:${namesPattern})\\s*\\|?\\s*>)`, 'i');
+    function isPossibleOpen(text) {
+        const compact = compactTagCandidate(text, /[<|,\s]/g);
+        if (compact === null)
+            return false;
+        return compact.length === 0 || canonicals.some((c) => c.startsWith(compact) || compact.startsWith(c));
+    }
+    function isPossibleClose(text) {
+        const compact = compactTagCandidate(text, /[<|/\s]/g);
+        if (compact === null)
+            return false;
+        return compact.length === 0 || canonicals.some((c) => c.startsWith(compact) || compact.startsWith(c));
+    }
+    return createTaggedTextSuppressor({ openRe, closeRe, isPossibleOpen, isPossibleClose });
+}
+const TOOL_CALL_OPEN_RE = /(?:<\s*tool_call\b[^>]*>|<\s*edit\s*>)/i;
+const TOOL_CALL_CLOSE_RE = /(?:<\/\s*tool_call\s*>|<\/\s*edit\s*>)/i;
+const TOOL_CALL_CANONICALS = ['toolcall', 'edit'];
+// Same reasoning as compactTagCandidate above: `text` always starts with
+// `<` here (a `possibleTagStart` tail slice) — no re-check needed.
+function isPossibleToolCallOpen(text) {
+    if (text.includes('>'))
+        return false;
+    const compact = text.toLowerCase().replace(/[<|,\s_-]/g, '');
+    return compact.length === 0 || TOOL_CALL_CANONICALS.some((c) => c.startsWith(compact) || compact.startsWith(c));
+}
+function isPossibleToolCallClose(text) {
+    if (text.includes('>'))
+        return false;
+    const compact = text.toLowerCase().replace(/[<|/\s_-]/g, '');
+    return compact.length === 0 || TOOL_CALL_CANONICALS.some((c) => c.startsWith(compact) || compact.startsWith(c));
+}
+/** Suppresses a `<tool_call>...</tool_call>` or `<edit>...</edit>` block — a generic agent-protocol convention, not product-branded. */
+export function createToolCallTextSuppressor() {
+    return createTaggedTextSuppressor({
+        openRe: TOOL_CALL_OPEN_RE,
+        closeRe: TOOL_CALL_CLOSE_RE,
+        isPossibleOpen: isPossibleToolCallOpen,
+        isPossibleClose: isPossibleToolCallClose,
+    });
+}
+//# sourceMappingURL=text-suppression.js.map

package/dist/artifacts/text-suppression.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-suppression.js","sourceRoot":"","sources":["../../src/artifacts/text-suppression.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAsBH,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAEjC;;;;;;;;GAQG;AACH,MAAM,UAAU,0BAA0B,CAAC,IAK1C;IACC,IAAI,WAAW,GAAG,KAAK,CAAC;IACxB,IAAI,SAAS,GAAG,EAAE,CAAC;IACnB,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,IAAI,gBAAgB,GAAG,CAAC,CAAC;IACzB,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,IAAI,YAAY,GAAG,CAAC,CAAC;IAErB,SAAS,cAAc,CAAC,IAAY;QAClC,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC;YAAE,OAAO;QAC7B,eAAe,IAAI,IAAI,CAAC,MAAM,CAAC;QAC/B,gBAAgB,IAAI,CAAC,CAAC;IACxB,CAAC;IAED,SAAS,KAAK,CAAC,IAAY;QACzB,MAAM,OAAO,GAAG,GAAG,SAAS,GAAG,IAAI,EAAE,CAAC;QACtC,SAAS,GAAG,EAAE,CAAC;QAEf,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACzC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxC,MAAM,mBAAmB,GAAG,gBAAgB,CAAC,OAAO,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC;gBAC5E,IAAI,mBAAmB,KAAK,CAAC,CAAC,EAAE,CAAC;oBAC/B,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC;oBAC/C,cAAc,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC;gBACxD,CAAC;qBAAM,CAAC;oBACN,cAAc,CAAC,OAAO,CAAC,CAAC;gBAC1B,CAAC;gBACD,OAAO,EAAE,CAAC;YACZ,CAAC;YACD,WAAW,GAAG,KAAK,CAAC;YACpB,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YAC1C,YAAY,IAAI,CAAC,CAAC;YAClB,cAAc,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;YACtC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QACnC,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvC,IAAI,IAAI,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YACrC,WAAW,GAAG,IAAI,CAAC;YACnB,YAAY,IAAI,CAAC,CAAC;YAClB,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;YAC5C,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YACxD,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YACxB,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,CAAC;QAED,MAAM,cAAc,GAAG,gBAAgB,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;QACtE,IAAI,cAAc,KAAK,CAAC,CAAC;YAAE,OAAO,OAAO,CAAC;QAE1C,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QAC1C,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;IAC1C,CAAC;IAED,SAAS,KAAK;QACZ,MAAM,IAAI,GAAG,SAAS,CAAC;QACvB,SAAS,GAAG,EAAE,CAAC;QACf,OAAO,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACjC,CAAC;IAED,SAAS,aAAa;QACpB,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,SAAS,mBAAmB;QAC1B,OAAO,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;IAC9B,CAAC;IAED,SAAS,KAAK;QACZ,OAAO;YACL,eAAe;YACf,gBAAgB;YAChB,YAAY;YACZ,YAAY;YACZ,qBAAqB,EAAE,SAAS,CAAC,MAAM;YACvC,WAAW;SACZ,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,KAAK,EAAE,CAAC;AACrE,CAAC;AAED,kJAAkJ;AAClJ,MAAM,UAAU,sBAAsB,CACpC,UAAkC,EAClC,OAAwB,EACxB,IAAY;IAEZ,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,OAAO,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC;IACvC,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,gBAAgB,CAAC,IAAY,EAAE,SAAoC;IAC1E,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,GAAG,oBAAoB,CAAC,CAAC;IAC5D,IAAI,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAClC,OAAO,KAAK,IAAI,GAAG,EAAE,CAAC;QACpB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC/B,IAAI,SAAS,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QAClC,IAAI,KAAK,KAAK,CAAC;YAAE,MAAM;QACvB,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,CAAC,CAAC,CAAC;AACZ,CAAC;AAED,qEAAqE;AACrE,2EAA2E;AAC3E,SAAS,mBAAmB,CAAC,IAAY,EAAE,UAAkB;IAC3D,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CAAC,QAA2B;IACpE,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;IACxD,MAAM,YAAY,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/F,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,sBAAsB,YAAY,aAAa,EAAE,GAAG,CAAC,CAAC;IAChF,MAAM,OAAO,GAAG,IAAI,MAAM,CAAC,aAAa,YAAY,6BAA6B,YAAY,iBAAiB,EAAE,GAAG,CAAC,CAAC;IAErH,SAAS,cAAc,CAAC,IAAY;QAClC,MAAM,OAAO,GAAG,mBAAmB,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QACtD,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QACnC,OAAO,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IACxG,CAAC;IAED,SAAS,eAAe,CAAC,IAAY;QACnC,MAAM,OAAO,GAAG,mBAAmB,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QACtD,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QACnC,OAAO,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IACxG,CAAC;IAED,OAAO,0BAA0B,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,CAAC,CAAC;AAC1F,CAAC;AAED,MAAM,iBAAiB,GAAG,yCAAyC,CAAC;AACpE,MAAM,kBAAkB,GAAG,yCAAyC,CAAC;AACrE,MAAM,oBAAoB,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;AAElD,yEAAyE;AACzE,mEAAmE;AACnE,SAAS,sBAAsB,CAAC,IAAY;IAC1C,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACrC,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;IAC7D,OAAO,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AAClH,CAAC;AAED,SAAS,uBAAuB,CAAC,IAAY;IAC3C,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACrC,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;IAC7D,OAAO,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AAClH,CAAC;AAED,wIAAwI;AACxI,MAAM,UAAU,4BAA4B;IAC1C,OAAO,0BAA0B,CAAC;QAChC,MAAM,EAAE,iBAAiB;QACzB,OAAO,EAAE,kBAAkB;QAC3B,cAAc,EAAE,sBAAsB;QACtC,eAAe,EAAE,uBAAuB;KACzC,CAAC,CAAC;AACL,CAAC"}

package/dist/close-status.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Pure run-close classification and inactivity-timeout helpers, generalized
+ * from OD's `apps/daemon/src/runtimes/chat-run-lifecycle.ts`
+ * (`arch/server-startserver-endgame` branch — see `source-map.md`). The
+ * origin file mixes a generic close-status decision tree with several
+ * OD/ACP-vendor-specific escape hatches (forced-shutdown-but-actually-clean
+ * heuristics for a specific agent-CLI protocol, artifact-quiet-period
+ * nuance). Only the generic skeleton is kept here — see `source-map.md` for
+ * the itemized list of what was dropped and why.
+ */
+export type TerminalRunOutcome = 'succeeded' | 'failed' | 'cancelled';
+export interface CloseStatusInput {
+    /** Whether `RunLifecycle.cancel` had already been called for this run. */
+    readonly cancelRequested: boolean;
+    readonly code: number | null;
+    readonly signal?: string | null;
+}
+/**
+ * Classifies a terminated run's exit into `RunLifecycle`'s terminal state.
+ *
+ * @param input - Cancellation flag plus the driver-observed exit code/signal.
+ * @returns `'cancelled'` if cancellation was requested (this takes priority
+ * over the exit code, since a cancelled process often exits non-zero as a
+ * direct result of the signal delivery — the cancellation intent, not the
+ * process's raw exit shape, is the ground truth); otherwise `'succeeded'`
+ * for exit code `0`; otherwise `'failed'`.
+ * @complexity O(1).
+ * @overallScore 100/100
+ */
+export declare function classifyRunCloseStatus(input: CloseStatusInput): TerminalRunOutcome;
+export interface ResolveTimeoutMsInput {
+    /** Env var name checked first (highest precedence), e.g. `'JINI_RUN_INACTIVITY_TIMEOUT_MS'`. */
+    readonly envVar?: string;
+    /** Per-agent/per-runtime default, used when no env override is set. */
+    readonly agentDefaultMs?: number;
+    /** Kernel default, used when neither an env override nor an agent default is set. */
+    readonly defaultMs: number;
+    /** Upper clamp applied after resolution, regardless of source. */
+    readonly maxMs: number;
+    /** Injectable env source (defaults to `process.env`) — kept explicit so this stays a pure, testable function rather than reading a process-global implicitly. */
+    readonly env?: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * Resolves a timeout in milliseconds from an env-var override, an
+ * agent-supplied default, and a kernel default, in that precedence order,
+ * clamped to a maximum. Generalized from OD's
+ * `resolveChatRunInactivityTimeoutMs`/`resolveChatRunArtifactQuietPeriodMs`
+ * cascade (env > agentDefault > default, clamped) — the same shape reused
+ * for any timeout a `RunLifecycle` driver needs to resolve.
+ *
+ * @throws Never — a non-numeric or non-positive env value is treated as
+ * absent rather than raised, since a malformed env var should degrade to the
+ * next precedence tier, not crash startup.
+ * @complexity O(1).
+ * @overallScore 100/100
+ */
+export declare function resolveTimeoutMs(input: ResolveTimeoutMsInput): number;
+export interface InactivityWatchdog {
+    /** Resets the timeout window — call on every observed unit of run activity (an emitted event, a stdout chunk). */
+    noteActivity(): void;
+    /** Disarms the watchdog permanently (e.g. once the run reaches a terminal state). Safe to call more than once. */
+    cancel(): void;
+}
+export interface CreateInactivityWatchdogInput {
+    readonly timeoutMs: number;
+    /** Invoked once if `timeoutMs` elapses with no `noteActivity()` call in between. Never invoked after `cancel()`. */
+    readonly onTimeout: () => void;
+}
+/**
+ * Generic reset-on-activity timeout, generalized from OD's inactivity
+ * watchdog pattern in `start-chat-run.ts` (reset timer on every stdout/agent
+ * event; the origin's SIGTERM-then-SIGKILL escalation on fire is
+ * subprocess-signaling detail out of this task's scope — a driver's
+ * `onTimeout` callback is where that would plug in).
+ *
+ * @param input.timeoutMs - Milliseconds of inactivity before `onTimeout` fires.
+ * @param input.onTimeout - Fired at most once per watchdog instance.
+ * @returns A handle to reset (`noteActivity`) or permanently disarm (`cancel`) the timer.
+ * @remarks Side effect: starts a `setTimeout` immediately and calls
+ * `.unref()` on it (when available) so a bare watchdog never keeps a Node
+ * process alive on its own.
+ * @complexity O(1) per call.
+ * @overallScore 100/100
+ */
+export declare function createInactivityWatchdog(input: CreateInactivityWatchdogInput): InactivityWatchdog;
+//# sourceMappingURL=close-status.d.ts.map

package/dist/close-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"close-status.d.ts","sourceRoot":"","sources":["../src/close-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEtE,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,gBAAgB,GAAG,kBAAkB,CAQlF;AAED,MAAM,WAAW,qBAAqB;IACpC,gGAAgG;IAChG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,qFAAqF;IACrF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iKAAiK;IACjK,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;CAC7D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,MAAM,CAOrE;AAED,MAAM,WAAW,kBAAkB;IACjC,kHAAkH;IAClH,YAAY,IAAI,IAAI,CAAC;IACrB,kHAAkH;IAClH,MAAM,IAAI,IAAI,CAAC;CAChB;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,oHAAoH;IACpH,QAAQ,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC;CAChC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,6BAA6B,GAAG,kBAAkB,CAwBjG"}

package/dist/close-status.js

@@ -0,0 +1,91 @@
+/**
+ * Pure run-close classification and inactivity-timeout helpers, generalized
+ * from OD's `apps/daemon/src/runtimes/chat-run-lifecycle.ts`
+ * (`arch/server-startserver-endgame` branch — see `source-map.md`). The
+ * origin file mixes a generic close-status decision tree with several
+ * OD/ACP-vendor-specific escape hatches (forced-shutdown-but-actually-clean
+ * heuristics for a specific agent-CLI protocol, artifact-quiet-period
+ * nuance). Only the generic skeleton is kept here — see `source-map.md` for
+ * the itemized list of what was dropped and why.
+ */
+/**
+ * Classifies a terminated run's exit into `RunLifecycle`'s terminal state.
+ *
+ * @param input - Cancellation flag plus the driver-observed exit code/signal.
+ * @returns `'cancelled'` if cancellation was requested (this takes priority
+ * over the exit code, since a cancelled process often exits non-zero as a
+ * direct result of the signal delivery — the cancellation intent, not the
+ * process's raw exit shape, is the ground truth); otherwise `'succeeded'`
+ * for exit code `0`; otherwise `'failed'`.
+ * @complexity O(1).
+ * @overallScore 100/100
+ */
+export function classifyRunCloseStatus(input) {
+    if (input.cancelRequested) {
+        return 'cancelled';
+    }
+    if (input.code === 0) {
+        return 'succeeded';
+    }
+    return 'failed';
+}
+/**
+ * Resolves a timeout in milliseconds from an env-var override, an
+ * agent-supplied default, and a kernel default, in that precedence order,
+ * clamped to a maximum. Generalized from OD's
+ * `resolveChatRunInactivityTimeoutMs`/`resolveChatRunArtifactQuietPeriodMs`
+ * cascade (env > agentDefault > default, clamped) — the same shape reused
+ * for any timeout a `RunLifecycle` driver needs to resolve.
+ *
+ * @throws Never — a non-numeric or non-positive env value is treated as
+ * absent rather than raised, since a malformed env var should degrade to the
+ * next precedence tier, not crash startup.
+ * @complexity O(1).
+ * @overallScore 100/100
+ */
+export function resolveTimeoutMs(input) {
+    const env = input.env ?? (typeof process !== 'undefined' ? process.env : {});
+    const rawFromEnv = input.envVar ? env[input.envVar] : undefined;
+    const fromEnv = rawFromEnv !== undefined ? Number(rawFromEnv) : undefined;
+    const candidate = fromEnv !== undefined && Number.isFinite(fromEnv) && fromEnv > 0 ? fromEnv : (input.agentDefaultMs ?? input.defaultMs);
+    return Math.min(candidate, input.maxMs);
+}
+/**
+ * Generic reset-on-activity timeout, generalized from OD's inactivity
+ * watchdog pattern in `start-chat-run.ts` (reset timer on every stdout/agent
+ * event; the origin's SIGTERM-then-SIGKILL escalation on fire is
+ * subprocess-signaling detail out of this task's scope — a driver's
+ * `onTimeout` callback is where that would plug in).
+ *
+ * @param input.timeoutMs - Milliseconds of inactivity before `onTimeout` fires.
+ * @param input.onTimeout - Fired at most once per watchdog instance.
+ * @returns A handle to reset (`noteActivity`) or permanently disarm (`cancel`) the timer.
+ * @remarks Side effect: starts a `setTimeout` immediately and calls
+ * `.unref()` on it (when available) so a bare watchdog never keeps a Node
+ * process alive on its own.
+ * @complexity O(1) per call.
+ * @overallScore 100/100
+ */
+export function createInactivityWatchdog(input) {
+    let timer;
+    const arm = () => {
+        if (timer) {
+            clearTimeout(timer);
+        }
+        timer = setTimeout(input.onTimeout, input.timeoutMs);
+        if (typeof timer.unref === 'function') {
+            timer.unref();
+        }
+    };
+    arm();
+    return {
+        noteActivity: arm,
+        cancel: () => {
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+        },
+    };
+}
+//# sourceMappingURL=close-status.js.map

package/dist/close-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"close-status.js","sourceRoot":"","sources":["../src/close-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAWH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAuB;IAC5D,IAAI,KAAK,CAAC,eAAe,EAAE,CAAC;QAC1B,OAAO,WAAW,CAAC;IACrB,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,WAAW,CAAC;IACrB,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAeD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAA4B;IAC3D,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC7E,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAChE,MAAM,OAAO,GAAG,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC1E,MAAM,SAAS,GACb,OAAO,KAAK,SAAS,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,cAAc,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC;IACzH,OAAO,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;AAC1C,CAAC;AAeD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAoC;IAC3E,IAAI,KAAgD,CAAC;IAErD,MAAM,GAAG,GAAG,GAAS,EAAE;QACrB,IAAI,KAAK,EAAE,CAAC;YACV,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QACD,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;QACrD,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;YACtC,KAAK,CAAC,KAAK,EAAE,CAAC;QAChB,CAAC;IACH,CAAC,CAAC;IAEF,GAAG,EAAE,CAAC;IAEN,OAAO;QACL,YAAY,EAAE,GAAG;QACjB,MAAM,EAAE,GAAS,EAAE;YACjB,IAAI,KAAK,EAAE,CAAC;gBACV,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,KAAK,GAAG,SAAS,CAAC;YACpB,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/continuation/continuation-transport.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `resolveContinuationTransport` — gap 3 of the run/chat orchestration
+ * swarm-consensus Final Recommendation: "per-definition `continuationTransport:
+ * 'mcp-callback' | 'stdin-injection' | 'none'`, resolved from each def's
+ * declared input format (defaulting `'none'` for unverified entries)."
+ * Evidence-backed as a factual constraint, not a preference: stdin closes
+ * after the first write for ~22/24 registered defs (see the consensus
+ * report's DP3).
+ *
+ * Resolution order (2026-07-22 research, `@jini-ai/agent-runtime`'s 24 defs
+ * enumerated directly): `externalMcpInjection` set → `'mcp-callback'`;
+ * else `promptInputFormat === 'stream-json' && promptViaStdin` →
+ * `'stdin-injection'`; else `'none'`. `externalMcpInjection` is checked
+ * first because it is the more capable transport (a real bidirectional tool
+ * protocol vs. a single-shot JSONL injection) and because `claude`/
+ * `codebuddy` are the only defs where both conditions are simultaneously
+ * true — they resolve to `'mcp-callback'` as primary, with
+ * `'stdin-injection'` available as a documented secondary path (see
+ * `agent-executor.ts`'s stdin-tool-result injection, which is independently
+ * gated and does not consult this function).
+ *
+ * Keyed deliberately off `promptInputFormat`/`externalMcpInjection`, never
+ * `streamFormat`: `amp.ts` reuses `streamFormat: 'claude-stream-json'` (the
+ * *output* parser) but declares neither input-continuation field — its own
+ * comment states it deliberately stays plain-text stdin. Keying off
+ * `streamFormat` would misroute it into `'stdin-injection'`.
+ */
+import type { RuntimeAgentDef } from '@jini-ai/agent-runtime';
+export type ContinuationTransport = 'mcp-callback' | 'stdin-injection' | 'none';
+/**
+ * Resolves the continuation transport a def supports, from its own declared
+ * capability fields — never guessed, never defaulted to something more
+ * capable than what the def actually declares.
+ * @param def - The resolved agent def.
+ * @returns The transport this def supports for injecting a tool result (or
+ * other mid-run input) back into an already-running child process.
+ * @complexity O(1).
+ * @overallScore 100/100
+ */
+export declare function resolveContinuationTransport(def: RuntimeAgentDef): ContinuationTransport;
+//# sourceMappingURL=continuation-transport.d.ts.map

package/dist/continuation/continuation-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"continuation-transport.d.ts","sourceRoot":"","sources":["../../src/continuation/continuation-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D,MAAM,MAAM,qBAAqB,GAAG,cAAc,GAAG,iBAAiB,GAAG,MAAM,CAAC;AAEhF;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,eAAe,GAAG,qBAAqB,CAIxF"}

package/dist/continuation/continuation-transport.js

@@ -0,0 +1,18 @@
+/**
+ * Resolves the continuation transport a def supports, from its own declared
+ * capability fields — never guessed, never defaulted to something more
+ * capable than what the def actually declares.
+ * @param def - The resolved agent def.
+ * @returns The transport this def supports for injecting a tool result (or
+ * other mid-run input) back into an already-running child process.
+ * @complexity O(1).
+ * @overallScore 100/100
+ */
+export function resolveContinuationTransport(def) {
+    if (def.externalMcpInjection !== undefined)
+        return 'mcp-callback';
+    if (def.promptInputFormat === 'stream-json' && def.promptViaStdin === true)
+        return 'stdin-injection';
+    return 'none';
+}
+//# sourceMappingURL=continuation-transport.js.map

package/dist/continuation/continuation-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"continuation-transport.js","sourceRoot":"","sources":["../../src/continuation/continuation-transport.ts"],"names":[],"mappings":"AA+BA;;;;;;;;;GASG;AACH,MAAM,UAAU,4BAA4B,CAAC,GAAoB;IAC/D,IAAI,GAAG,CAAC,oBAAoB,KAAK,SAAS;QAAE,OAAO,cAAc,CAAC;IAClE,IAAI,GAAG,CAAC,iBAAiB,KAAK,aAAa,IAAI,GAAG,CAAC,cAAc,KAAK,IAAI;QAAE,OAAO,iBAAiB,CAAC;IACrG,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/continuation/index.d.ts

@@ -0,0 +1,4 @@
+export * from './journal.js';
+export * from './run-start-handler.js';
+export * from './continuation-transport.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/continuation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/continuation/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,6BAA6B,CAAC"}

package/dist/continuation/index.js

@@ -0,0 +1,4 @@
+export * from './journal.js';
+export * from './run-start-handler.js';
+export * from './continuation-transport.js';
+//# sourceMappingURL=index.js.map

package/dist/continuation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/continuation/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,6BAA6B,CAAC"}

package/dist/continuation/journal.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `RunByteJournal` — gap 1 of the run/chat orchestration swarm-consensus
+ * Final Recommendation ("a durable, typed byte-journal... recording every
+ * byte sent to/received from a child agent process. This is the
+ * observability floor every later increment depends on." — see
+ * `ADS-memory/reports/swarm-consensus/runs/20260722T023000Z-consensus-report.md`).
+ *
+ * Deliberately backed by the existing `EventLog` port rather than a new
+ * storage mechanism ("no new package" — same debate), but deliberately NOT
+ * the same `EventLog` *instance* `RunLifecycle` appends its own
+ * `RunProtocolEvent`s to: that log's `stream()` replays every entry it holds
+ * to SSE subscribers, typed as `RunProtocolEvent`, and a `'journal'` entry
+ * has no corresponding `RunProtocolEvent` kind. Reusing the same instance
+ * would either leak raw, potentially untrusted agent bytes into the public
+ * run-event stream or force widening `RunProtocolEvent` itself. A caller
+ * supplies its own `EventLog` instance here — reusing the exact same port
+ * type and, for a durable deployment, the exact same `@jini-ai/sqlite` adapter
+ * — so the journal gets the identical durability/replay guarantees without
+ * touching the run-protocol vocabulary at all.
+ */
+import type { JournalEntry } from '@jini-ai/protocol';
+import type { EventLog } from '../event-log.js';
+export interface RunByteJournal {
+    /** Durably appends one journal entry for `runId`. Never rejects into caller code — see {@link createRunByteJournal}. */
+    record(runId: string, entry: JournalEntry): Promise<void>;
+    /** Replays every journal entry recorded for `runId`, oldest first. */
+    read(runId: string): Promise<readonly JournalEntry[]>;
+}
+/**
+ * Creates a `RunByteJournal` over the given `EventLog` instance.
+ * @param eventLog - A dedicated `EventLog` instance for journal storage — see this module's doc for why it must not be the same instance `RunLifecycle` uses.
+ * @returns A `RunByteJournal` whose `record`/`read` are thin, structurally-typed projections of `eventLog.append`/`eventLog.replay`.
+ * @complexity Both methods are exactly as expensive as the underlying `EventLog`'s `append`/`replay`.
+ * @overallScore 100/100
+ */
+export declare function createRunByteJournal(eventLog: EventLog): RunByteJournal;
+//# sourceMappingURL=journal.d.ts.map

package/dist/continuation/journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.d.ts","sourceRoot":"","sources":["../../src/continuation/journal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAKhD,MAAM,WAAW,cAAc;IAC7B,wHAAwH;IACxH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,sEAAsE;IACtE,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAAC;CACvD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,GAAG,cAAc,CAWvE"}

package/dist/continuation/journal.js

@@ -0,0 +1,23 @@
+/** The one event name every journal entry is appended under — never a `RunProtocolEvent` kind, so a shared-instance mistake would be immediately obvious in a replay. */
+const JOURNAL_EVENT_NAME = 'journal';
+/**
+ * Creates a `RunByteJournal` over the given `EventLog` instance.
+ * @param eventLog - A dedicated `EventLog` instance for journal storage — see this module's doc for why it must not be the same instance `RunLifecycle` uses.
+ * @returns A `RunByteJournal` whose `record`/`read` are thin, structurally-typed projections of `eventLog.append`/`eventLog.replay`.
+ * @complexity Both methods are exactly as expensive as the underlying `EventLog`'s `append`/`replay`.
+ * @overallScore 100/100
+ */
+export function createRunByteJournal(eventLog) {
+    return {
+        async record(runId, entry) {
+            await eventLog.append({ runId, event: JOURNAL_EVENT_NAME, data: entry });
+        },
+        async read(runId) {
+            const replay = await eventLog.replay(runId, null);
+            if (replay.kind !== 'ok')
+                return [];
+            return replay.entries.map((entry) => entry.data);
+        },
+    };
+}
+//# sourceMappingURL=journal.js.map

package/dist/continuation/journal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.js","sourceRoot":"","sources":["../../src/continuation/journal.ts"],"names":[],"mappings":"AAuBA,yKAAyK;AACzK,MAAM,kBAAkB,GAAG,SAAS,CAAC;AASrC;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAkB;IACrD,OAAO;QACL,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,KAAmB;YAC7C,MAAM,QAAQ,CAAC,MAAM,CAAe,EAAE,KAAK,EAAE,KAAK,EAAE,kBAAkB,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACzF,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,KAAa;YACtB,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YAClD,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI;gBAAE,OAAO,EAAE,CAAC;YACpC,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAoB,CAAC,CAAC;QACnE,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/continuation/run-start-handler.d.ts

@@ -0,0 +1,75 @@
+/**
+ * `resolveRunInput` + `createDefaultRunStartHandler` — gap 1's other half:
+ * "a default `RunStartHandler`-style wiring (host-supplied `resolveRunInput`
+ * seam, matching the existing `resolveDaemonUrl` precedent)" (Final
+ * Recommendation, `ADS-memory/reports/swarm-consensus/runs/20260722T023000Z-consensus-report.md`).
+ *
+ * Today, `@jini-ai/http`'s `POST /api/runs` durably starts a run via
+ * `RunLifecycle.start()` and then — only if a host supplied one — invokes an
+ * `onStarted`/`RunStartHandler` callback. Nothing in the kernel ever turns
+ * that durable start into an actual `AgentExecutor.run()` call: a host with
+ * no `onStarted` gets a run that is durably `'running'` forever, with no
+ * driver ever attached. This module is the missing default, built the same
+ * way `@jini-ai/cli`'s `resolveDaemonUrl` composes a required resolution step
+ * (there: a daemon URL; here: an agent's prompt/cwd/env) out of an
+ * injectable async seam — `resolveRunInput` has no generic default, unlike
+ * `resolveDaemonUrl`'s optional `discover`, because prompt/skill/memory
+ * composition is gap 2, and gap 2 stays host-owned *permanently* (Final
+ * Recommendation item 5) — there is no sensible kernel-supplied fallback to
+ * fall through to.
+ *
+ * This does not itself touch `@jini-ai/http`'s `RunStartHandler` type (a
+ * `@jini-ai/daemon` → `@jini-ai/http` import would invert the package graph —
+ * `@jini-ai/http` already imports `@jini-ai/daemon`, never the reverse).
+ * {@link DefaultRunStartHandler}'s parameter type is a structural subset of
+ * `@jini-ai/http`'s `RunStartContext`, so a real `RunStartContext` value —
+ * passed by a host wiring this handler in as `RunHttpDeps.onStarted` —
+ * satisfies it without either package needing to import the other's types.
+ */
+import type { AgentExecutor } from '../agent-executor.js';
+export interface ResolveRunInputContext {
+    readonly runId: string;
+    readonly contextRef: string;
+    readonly agentId?: string;
+}
+export interface ResolvedRunInput {
+    readonly agentId: string;
+    readonly prompt: string;
+    readonly cwd: string;
+    readonly env?: NodeJS.ProcessEnv;
+}
+/** Host-owned composition seam: turns a durably-started run's identity into what `AgentExecutor.run()` actually needs. No generic default exists — see module doc. */
+export type ResolveRunInput = (context: ResolveRunInputContext) => Promise<ResolvedRunInput> | ResolvedRunInput;
+/** Structural subset of `@jini-ai/http`'s `RunStartContext` — see module doc for why this package cannot import that type directly. */
+export interface RunStartDriverContext {
+    readonly request: {
+        readonly contextRef: string;
+        readonly agentId?: string;
+    };
+    readonly run: {
+        readonly id: string;
+    };
+}
+/** Structurally assignable to `@jini-ai/http`'s `RunStartHandler` — see module doc. */
+export type DefaultRunStartHandler = (context: RunStartDriverContext) => Promise<void>;
+export interface CreateDefaultRunStartHandlerOptions {
+    readonly agentExecutor: AgentExecutor;
+    readonly resolveRunInput: ResolveRunInput;
+}
+/**
+ * Builds the default `RunStartHandler`-shaped driver: resolves the real
+ * agent input via `options.resolveRunInput`, then hands it straight to
+ * `options.agentExecutor.run()`. A host wires this in as
+ * `RunHttpDeps.onStarted` (or `CreateLocalNodeDaemonConfig.onRunStarted`)
+ * instead of writing its own driver from scratch — it still owns
+ * `resolveRunInput` itself (gap 2 stays host-owned), but no longer needs to
+ * know `AgentExecutor`'s call shape or wire cancellation/journaling by hand.
+ * @param options.agentExecutor - The executor this handler drives. Any byte-journaling is the executor's own concern (see `CreateAgentExecutorOptions.journal`) — this handler does not journal directly.
+ * @param options.resolveRunInput - Host-owned composition seam — see module doc.
+ * @returns A handler structurally assignable to `@jini-ai/http`'s `RunStartHandler`.
+ * @throws Whatever `resolveRunInput` or `agentExecutor.run()` throw — `@jini-ai/http`'s `runStartRoute` already treats a rejecting `onStarted` as a failed run (finishes it, reports the internal error), so this handler deliberately does not swallow either failure itself.
+ * @complexity O(1) plus `resolveRunInput`'s and `agentExecutor.run()`'s own costs.
+ * @overallScore 100/100
+ */
+export declare function createDefaultRunStartHandler(options: CreateDefaultRunStartHandlerOptions): DefaultRunStartHandler;
+//# sourceMappingURL=run-start-handler.d.ts.map

package/dist/continuation/run-start-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-start-handler.d.ts","sourceRoot":"","sources":["../../src/continuation/run-start-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAClC;AAED,sKAAsK;AACtK,MAAM,MAAM,eAAe,GAAG,CAC5B,OAAO,EAAE,sBAAsB,KAC5B,OAAO,CAAC,gBAAgB,CAAC,GAAG,gBAAgB,CAAC;AAElD,uIAAuI;AACvI,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7E,QAAQ,CAAC,GAAG,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;CACvC;AAED,uFAAuF;AACvF,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEvF,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;CAC3C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,mCAAmC,GAC3C,sBAAsB,CAexB"}