@jini-ai/daemon 0.3.7 → 0.5.0

package/dist/run-lifecycle.js

@@ -4,7 +4,7 @@
  * never a product-record identifier), generalized from OD's `design.runs` service
  * (`apps/daemon/src/runtimes/runs.ts` + the terminal-decision half of
  * `apps/daemon/src/runtimes/start-chat-run.ts`, `arch/server-startserver-endgame`
- * branch — see `source-map.md` for exact line citations).
+ * branch — see `archived provenance ledger` for exact line citations).
  *
  * Scope boundary: this module owns the run *state machine* and its event
  * log — create, transition, emit, replay, cancellation-intent propagation,
@@ -132,13 +132,13 @@ function terminalStateFromEndEntry(entry) {
  * or `undefined` when there is no key or no existing mapping (a fresh start proceeds normally).
  * Pure.
  */
-export function resolveIdempotentReplayRunId(idempotencyIndex, idempotencyKey) {
+export function resolveIdempotentReplayRunId({ idempotencyIndex, idempotencyKey }) {
     if (idempotencyKey === undefined)
         return undefined;
     return idempotencyIndex.get(idempotencyKey);
 }
 /** Registers `runId` under `idempotencyKey` in `idempotencyIndex` — a no-op when no key was supplied. */
-export function registerIdempotencyKeyIfPresent(idempotencyIndex, idempotencyKey, runId) {
+export function registerIdempotencyKeyIfPresent({ idempotencyIndex, idempotencyKey, runId }) {
     if (idempotencyKey === undefined)
         return;
     idempotencyIndex.set(idempotencyKey, runId);
@@ -149,7 +149,7 @@ export function registerIdempotencyKeyIfPresent(idempotencyIndex, idempotencyKey
  * run that may have since claimed the same key (defensive; `start()`'s own locking makes that
  * race unreachable today, but the check costs nothing and documents the invariant).
  */
-export function clearIdempotencyIndexEntryIfMatching(idempotencyIndex, idempotencyKey, runId) {
+export function clearIdempotencyIndexEntryIfMatching({ idempotencyIndex, idempotencyKey, runId }) {
     if (idempotencyKey !== undefined && idempotencyIndex.get(idempotencyKey) === runId) {
         idempotencyIndex.delete(idempotencyKey);
     }
@@ -175,7 +175,7 @@ export const DEFAULT_TERMINAL_RETENTION_MS = 24 * 60 * 60 * 1000;
 export const DEFAULT_MAX_TERMINAL_RUNS = 1000;
 /**
  * Default wall-clock threshold for the slow-run notice (distinct from the crash/inactivity watchdog
- * above): how long a run may go with no `emit()` before a `'slow_running'` agent event tells the UI
+ * above): how long a run may go with no agent-event `emit()` (excluding the notice itself) before a `'slow_running'` agent event tells the UI
  * "this is taking longer than usual," without ever finishing the run. See {@link armSlowRunWatchdogIfConfigured}'s
  * doc for the full "why a second, non-terminating watchdog" rationale. 45s was picked as long enough
  * that an ordinary quiet stretch (the agent thinking between tool calls, a slow but healthy model
@@ -192,11 +192,11 @@ export const DEFAULT_SLOW_RUN_THRESHOLD_MS = 45_000;
  * where a run may have gone terminal long before this process started) schedules an immediate
  * eviction rather than a negative-delay timer. Pure.
  */
-export function computeRetentionDelayMs(terminalAt, retentionMs, now) {
+export function computeRetentionDelayMs({ terminalAt, retentionMs, now }) {
     return Math.max(0, retentionMs - (now - terminalAt));
 }
 /** The durable `'start'` entry's payload — pure field mapping, split out of `start()` so its two optional-field spreads don't count toward that method's own complexity. */
-export function buildStartPayload(runId, startInput) {
+export function buildStartPayload({ runId, startInput }) {
     return {
         runId,
         contextRef: startInput.contextRef,
@@ -209,7 +209,7 @@ export function buildStartPayload(runId, startInput) {
  * plain `{watchdog}` shape (not `Pick<RunRecord, 'watchdog'>`) purely so this function can be
  * exported without naming the private `RunRecord` type in a public signature.
  */
-export function armWatchdogIfConfigured(record, timeoutMs, onTimeout) {
+export function armWatchdogIfConfigured({ record, timeoutMs, onTimeout }) {
     if (timeoutMs === undefined)
         return;
     record.watchdog = createInactivityWatchdog({ timeoutMs, onTimeout });
@@ -224,7 +224,7 @@ export function armWatchdogIfConfigured(record, timeoutMs, onTimeout) {
  * three-line dedup. `record` is typed as a plain `{slowRunWatchdog}` shape for the same exportability
  * reason {@link armWatchdogIfConfigured} already documents.
  */
-export function armSlowRunWatchdogIfConfigured(record, timeoutMs, onTimeout) {
+export function armSlowRunWatchdogIfConfigured({ record, timeoutMs, onTimeout }) {
     if (timeoutMs === undefined)
         return;
     record.slowRunWatchdog = createInactivityWatchdog({ timeoutMs, onTimeout });
@@ -235,7 +235,7 @@ export function armSlowRunWatchdogIfConfigured(record, timeoutMs, onTimeout) {
  * (buffered live events observed during the replay, a terminal catch-up event). Pure aside from
  * calling the injected `onEvent`.
  */
-export function deliverReplayedEvents(runId, entries, onEvent) {
+export function deliverReplayedEvents({ runId, entries, onEvent }) {
     const deliveredEventIds = new Set();
     for (const entry of entries) {
         const event = toRunEvent(runId, entry);
@@ -249,7 +249,7 @@ export function deliverReplayedEvents(runId, entries, onEvent) {
  * delivered as it goes. Reused in `stream()` for both the buffered-live-event catch-up and the
  * single terminal-event catch-up, so the "don't double-deliver" bookkeeping lives in one place.
  */
-export function deliverUndeliveredEvents(events, deliveredEventIds, onEvent) {
+export function deliverUndeliveredEvents({ events, deliveredEventIds, onEvent }) {
     for (const event of events) {
         if (!deliveredEventIds.has(event.eventId)) {
             deliveredEventIds.add(event.eventId);
@@ -263,7 +263,7 @@ export function deliverUndeliveredEvents(events, deliveredEventIds, onEvent) {
  * registered behind the returned `unsubscribe`. `record` is typed as a plain `{subscribers}` shape
  * for the same exportability reason as {@link armWatchdogIfConfigured}.
  */
-export function finishStreamSubscription(record, subscriber, terminal) {
+export function finishStreamSubscription({ record, subscriber, terminal }) {
     if (terminal) {
         record.subscribers.delete(subscriber);
         return { kind: 'ok', unsubscribe: () => { } };
@@ -305,7 +305,8 @@ function buildNewRunRecord(startInput, runId, now) {
  * @complexity Per-call complexities documented on each method; the registry itself is a `Map` keyed by `runId` (O(1) lookup). Memory is bounded: non-terminal runs are O(n) in concurrently-live runs, and terminal runs are capped at `maxTerminalRuns` (each additionally bounded in retention time by `terminalRetentionMs`) rather than growing for the life of the process.
  * @overallScore 100/100
  */
-export function createRunLifecycle(input) {
+export function createRunLifecycle(requiredArgs, optionalArgs = {}) {
+    const input = { ...requiredArgs, ...optionalArgs };
     const { eventLog } = input;
     const terminalRetentionMs = input.terminalRetentionMs ?? DEFAULT_TERMINAL_RETENTION_MS;
     const maxTerminalRuns = input.maxTerminalRuns ?? DEFAULT_MAX_TERMINAL_RUNS;
@@ -352,7 +353,7 @@ export function createRunLifecycle(input) {
     }
     /** `start()`'s phase 2: appends the durable `'start'` entry, rolling back the in-memory record and idempotency-index entry on failure. */
     async function appendStartOrRollback(runId, record, startInput) {
-        const startPayload = buildStartPayload(runId, startInput);
+        const startPayload = buildStartPayload({ runId: runId, startInput: startInput });
         const startPromise = appendEvent(runId, record, 'start', startPayload).then(() => undefined);
         record.startPromise = startPromise;
         try {
@@ -361,7 +362,7 @@ export function createRunLifecycle(input) {
         }
         catch (error) {
             runs.delete(runId);
-            clearIdempotencyIndexEntryIfMatching(idempotencyIndex, startInput.idempotencyKey, runId);
+            clearIdempotencyIndexEntryIfMatching({ idempotencyIndex: idempotencyIndex, idempotencyKey: startInput.idempotencyKey, runId: runId });
             throw error;
         }
     }
@@ -412,7 +413,7 @@ export function createRunLifecycle(input) {
             return;
         record.retentionTimer = undefined;
         runs.delete(runId);
-        clearIdempotencyIndexEntryIfMatching(idempotencyIndex, record.idempotencyKey, runId);
+        clearIdempotencyIndexEntryIfMatching({ idempotencyIndex: idempotencyIndex, idempotencyKey: record.idempotencyKey, runId: runId });
     }
     /** Trims the oldest terminal records until `terminalRunOrder` is back at or under `maxTerminalRuns`. */
     function enforceTerminalCap() {
@@ -430,7 +431,7 @@ export function createRunLifecycle(input) {
      */
     function trackTerminalRun(runId, record, terminalAt) {
         terminalRunOrder.push(runId);
-        const delay = computeRetentionDelayMs(terminalAt, terminalRetentionMs, Date.now());
+        const delay = computeRetentionDelayMs({ terminalAt: terminalAt, retentionMs: terminalRetentionMs, now: Date.now() });
         const timer = setTimeout(() => evictTerminalRun(runId), delay);
         if (typeof timer.unref === 'function')
             timer.unref();
@@ -472,7 +473,7 @@ export function createRunLifecycle(input) {
      */
     async function handleInactivityTimeout(runId) {
         const record = runs.get(runId);
-        if (!record || isTerminalRunState(record.status.state)) {
+        if (!record || isTerminalRunState({ state: record.status.state })) {
             return;
         }
         try {
@@ -518,17 +519,17 @@ export function createRunLifecycle(input) {
      */
     async function handleSlowRunNotice(runId) {
         const record = runs.get(runId);
-        if (!record || isTerminalRunState(record.status.state)) {
+        if (!record || isTerminalRunState({ state: record.status.state })) {
             return;
         }
         try {
-            await lifecycle.emit(runId, {
-                event: 'agent',
-                data: {
-                    type: 'slow_running',
-                    detail: 'Still working — this turn is taking longer than usual.',
-                },
-            });
+            await lifecycle.emit({ runId: runId, input: {
+                    event: 'agent',
+                    data: {
+                        type: 'slow_running',
+                        detail: 'Still working — this turn is taking longer than usual.',
+                    },
+                } });
         }
         catch (error) {
             const context = { source: 'slow-run-notice', runId, error };
@@ -556,7 +557,7 @@ export function createRunLifecycle(input) {
     async function rehydrateOne(runId) {
         if (runs.has(runId))
             return 'skipped';
-        const replay = await eventLog.replay(runId, null);
+        const replay = await eventLog.replay({ runId: runId, afterCursor: null });
         if (replay.kind !== 'ok' || replay.entries.length === 0)
             return 'skipped';
         const { record, idempotencyKey, isTerminal } = rehydratedRunRecord(runId, replay.entries);
@@ -572,12 +573,12 @@ export function createRunLifecycle(input) {
         return isTerminal ? 'terminal' : 'non-terminal';
     }
     const lifecycle = {
-        async rehydrate() {
+        async rehydrate(_args) {
             if (hydration)
                 return hydration;
             hydration = (async () => {
                 const rehydratedNonTerminalRunIds = [];
-                for (const runId of await eventLog.listRunIds()) {
+                for (const runId of await eventLog.listRunIds({})) {
                     if (await rehydrateOne(runId) === 'non-terminal') {
                         rehydratedNonTerminalRunIds.push(runId);
                     }
@@ -590,7 +591,8 @@ export function createRunLifecycle(input) {
             })();
             return hydration;
         },
-        async start(startInput) {
+        async start(requiredArgs, optionalArgs = {}) {
+            const startInput = { ...requiredArgs, ...optionalArgs };
             // Synchronous on purpose: `resolveIdempotentReplayRunId` does no I/O, and the common case
             // (no idempotencyKey, or a fresh one) must reach `runs.set()` below in the same synchronous
             // turn as this call — not after even one microtask tick — so a caller that races `finish()`
@@ -598,7 +600,7 @@ export function createRunLifecycle(input) {
             // needs. Wrapping this check in its own `await`ed async function previously broke exactly
             // that: an `async function` always defers its continuation by a microtask even when its body
             // never itself awaits, which shifted `runs.set()` behind the racing `finish()` call.
-            const existingRunId = resolveIdempotentReplayRunId(idempotencyIndex, startInput.idempotencyKey);
+            const existingRunId = resolveIdempotentReplayRunId({ idempotencyIndex: idempotencyIndex, idempotencyKey: startInput.idempotencyKey });
             if (existingRunId !== undefined) {
                 const existing = requireRun(existingRunId);
                 await existing.startPromise;
@@ -610,17 +612,17 @@ export function createRunLifecycle(input) {
             }
             const record = buildNewRunRecord(startInput, runId, Date.now());
             runs.set(runId, record);
-            registerIdempotencyKeyIfPresent(idempotencyIndex, startInput.idempotencyKey, runId);
+            registerIdempotencyKeyIfPresent({ idempotencyIndex: idempotencyIndex, idempotencyKey: startInput.idempotencyKey, runId: runId });
             await appendStartOrRollback(runId, record, startInput);
-            armWatchdogIfConfigured(record, startInput.inactivityTimeoutMs, () => {
-                void handleInactivityTimeout(runId);
-            });
-            armSlowRunWatchdogIfConfigured(record, slowRunThresholdMs, () => {
-                void handleSlowRunNotice(runId);
-            });
+            armWatchdogIfConfigured({ record: record, timeoutMs: startInput.inactivityTimeoutMs, onTimeout: () => {
+                    void handleInactivityTimeout(runId);
+                } });
+            armSlowRunWatchdogIfConfigured({ record: record, timeoutMs: slowRunThresholdMs, onTimeout: () => {
+                    void handleSlowRunNotice(runId);
+                } });
             return { run: toPublicStatus(record), started: true };
         },
-        async get(runId) {
+        async get({ runId }) {
             await settlePendingStart(runs.get(runId));
             // Re-read rather than reusing the record above: a failed start deletes it (see `start()`'s
             // unwind), and reporting a run whose durable `'start'` entry does not exist would advertise a
@@ -628,7 +630,7 @@ export function createRunLifecycle(input) {
             const record = runs.get(runId);
             return record ? toPublicStatus(record) : undefined;
         },
-        async list(contextRef) {
+        async list(_requiredArgs, { contextRef } = {}) {
             await Promise.all(Array.from(runs.values(), settlePendingStart));
             const all = Array.from(runs.values());
             const filtered = contextRef === undefined ? all : all.filter((record) => record.contextRef === contextRef);
@@ -640,7 +642,7 @@ export function createRunLifecycle(input) {
             if (record.finishPromise) {
                 return record.finishPromise;
             }
-            if (isTerminalRunState(record.status.state)) {
+            if (isTerminalRunState({ state: record.status.state })) {
                 return toPublicStatus(record);
             }
             record.cancelRequested = true;
@@ -659,7 +661,7 @@ export function createRunLifecycle(input) {
          * happened would silently never learn about it, since a plain
          * subscribe-for-future-events registry has no memory of past firings.
          */
-        onCancelRequested(runId, listener) {
+        onCancelRequested({ runId, listener }) {
             const record = requireRun(runId);
             if (record.cancelRequested && record.lastCancelRequest) {
                 listener(record.lastCancelRequest);
@@ -667,23 +669,30 @@ export function createRunLifecycle(input) {
             record.cancelListeners.add(listener);
             return () => record.cancelListeners.delete(listener);
         },
-        async emit(runId, driverInput) {
+        async emit({ runId, input }) {
             const record = requireRun(runId);
             await record.startPromise;
-            if (record.finishPromise || isTerminalRunState(record.status.state)) {
-                throw new Error(`RunLifecycle: cannot emit "${driverInput.event}" on terminal run "${runId}" — drivers must stop emitting once finish() has been called`);
+            if (record.finishPromise || isTerminalRunState({ state: record.status.state })) {
+                throw new Error(`RunLifecycle: cannot emit "${input.event}" on terminal run "${runId}" — drivers must stop emitting once finish() has been called`);
             }
-            record.watchdog?.noteActivity();
-            record.slowRunWatchdog?.noteActivity();
-            return appendEvent(runId, record, driverInput.event, driverInput.data);
+            record.watchdog?.noteActivity({});
+            // The crash watchdog above counts ANY output (the process is alive). The slow-run notice asks
+            // a different question — "has the person seen anything new?" — so only `agent` events count.
+            // A CLI's raw stdout/stderr (e.g. Claude Code's 30 s `tool_progress` heartbeats during a long
+            // tool call) is not rendered, and letting it reset this window meant the notice could never
+            // fire during exactly the long, silent tool calls it exists for.
+            if (input.event === 'agent')
+                record.slowRunWatchdog?.noteActivity({});
+            return appendEvent(runId, record, input.event, input.data);
         },
-        async finish(finishInput) {
+        async finish(requiredArgs, optionalArgs = {}) {
+            const finishInput = { ...requiredArgs, ...optionalArgs };
             const record = requireRun(finishInput.runId);
             await record.startPromise;
             if (record.finishPromise) {
                 return record.finishPromise;
             }
-            if (isTerminalRunState(record.status.state)) {
+            if (isTerminalRunState({ state: record.status.state })) {
                 return toPublicStatus(record);
             }
             const finishing = (async () => {
@@ -697,8 +706,8 @@ export function createRunLifecycle(input) {
                 const endEntry = await eventLog.append({ runId: finishInput.runId, event: 'end', data: endPayload });
                 // Commit the in-memory terminal transition only after its durable end entry exists. Until
                 // then `finishPromise` reserves the transition and blocks emits/concurrent finishes.
-                record.watchdog?.cancel();
-                record.slowRunWatchdog?.cancel();
+                record.watchdog?.cancel({});
+                record.slowRunWatchdog?.cancel({});
                 record.status.state = finishInput.status;
                 record.status.updatedAt = endEntry.recordedAt;
                 record.status.endedAt = endEntry.recordedAt;
@@ -720,9 +729,9 @@ export function createRunLifecycle(input) {
                 }
             }
         },
-        async resume(runId) {
+        async resume({ runId }) {
             const record = requireRun(runId);
-            const eligible = isTerminalRunState(record.status.state) && record.resumable;
+            const eligible = isTerminalRunState({ state: record.status.state }) && record.resumable;
             if (!eligible) {
                 return { run: toPublicStatus(record), resumed: false };
             }
@@ -740,28 +749,32 @@ export function createRunLifecycle(input) {
             // never fires again on its own — the underlying timer is one-shot) left the notice permanently
             // dark for the rest of a resumed run's life, silently disabling a feature the run is otherwise
             // still eligible for.
-            armSlowRunWatchdogIfConfigured(record, slowRunThresholdMs, () => {
-                void handleSlowRunNotice(runId);
-            });
+            armSlowRunWatchdogIfConfigured({ record: record, timeoutMs: slowRunThresholdMs, onTimeout: () => {
+                    void handleSlowRunNotice(runId);
+                } });
             // No protocol event is emitted here: none of RunProtocolEvent's six
             // kinds represents "resumed" (extraction-plan scope decision — see
-            // source-map.md). The event log's cursor sequence continues
+            // archived provenance ledger). The event log's cursor sequence continues
             // unbroken; only RunStatus.state changes.
             return { run: toPublicStatus(record), resumed: true };
         },
-        suspendSlowRunNotice(runId) {
+        suspendSlowRunNotice({ runId }) {
             const record = runs.get(runId);
-            if (!record || isTerminalRunState(record.status.state))
+            if (!record || isTerminalRunState({ state: record.status.state }))
                 return;
-            record.slowRunWatchdog?.cancel();
+            record.slowRunWatchdog?.cancel({});
         },
-        resumeSlowRunNotice(runId) {
+        resumeSlowRunNotice({ runId }) {
             const record = runs.get(runId);
-            if (!record || isTerminalRunState(record.status.state))
+            if (!record || isTerminalRunState({ state: record.status.state }))
                 return;
-            record.slowRunWatchdog?.noteActivity();
+            // Suspension cancels permanently. Resuming must create a new window, never revive that handle.
+            record.slowRunWatchdog?.cancel({});
+            armSlowRunWatchdogIfConfigured({ record, timeoutMs: slowRunThresholdMs, onTimeout: () => {
+                    void handleSlowRunNotice(runId);
+                } });
         },
-        async waitForTerminal(runId) {
+        async waitForTerminal({ runId }) {
             const record = requireRun(runId);
             // Awaited (and *propagated*, unlike in `get`/`list`) before any waiter is registered. A run
             // whose durable start append rejects is unwound, and nothing ever calls `finish()` for it — so
@@ -769,14 +782,14 @@ export function createRunLifecycle(input) {
             // the same error that failed the start is the only honest terminal answer, and awaiting first
             // means `terminalWaiters` can only ever hold waiters for a run that really does exist.
             await record.startPromise;
-            if (isTerminalRunState(record.status.state)) {
+            if (isTerminalRunState({ state: record.status.state })) {
                 return toPublicStatus(record);
             }
             return new Promise((resolve) => {
                 record.terminalWaiters.push(resolve);
             });
         },
-        async stream(runId, onEvent, options = {}) {
+        async stream({ runId, onEvent }, options = {}) {
             const record = runs.get(runId);
             if (!record) {
                 return { kind: 'unknown-run' };
@@ -795,19 +808,19 @@ export function createRunLifecycle(input) {
             };
             record.subscribers.add(subscriber);
             try {
-                const replay = await eventLog.replay(runId, options.afterCursor ?? null);
+                const replay = await eventLog.replay({ runId: runId, afterCursor: options.afterCursor ?? null });
                 if (replay.kind !== 'ok') {
                     record.subscribers.delete(subscriber);
                     return replay;
                 }
-                const deliveredEventIds = deliverReplayedEvents(runId, replay.entries, onEvent);
-                deliverUndeliveredEvents(bufferedLiveEvents, deliveredEventIds, onEvent);
+                const deliveredEventIds = deliverReplayedEvents({ runId: runId, entries: replay.entries, onEvent: onEvent });
+                deliverUndeliveredEvents({ events: bufferedLiveEvents, deliveredEventIds: deliveredEventIds, onEvent: onEvent });
                 replaying = false;
-                const terminal = isTerminalRunState(record.status.state);
+                const terminal = isTerminalRunState({ state: record.status.state });
                 if (terminal && record.terminalEndEntry) {
-                    deliverUndeliveredEvents([toRunEvent(runId, record.terminalEndEntry)], deliveredEventIds, onEvent);
+                    deliverUndeliveredEvents({ events: [toRunEvent(runId, record.terminalEndEntry)], deliveredEventIds: deliveredEventIds, onEvent: onEvent });
                 }
-                return finishStreamSubscription(record, subscriber, terminal);
+                return finishStreamSubscription({ record: record, subscriber: subscriber, terminal: terminal });
             }
             catch (error) {
                 // Subscription is installed before durable replay to close the replay→live race. Any

package/dist/scheduler.d.ts

@@ -0,0 +1,8 @@
+/** Host timers must invoke callbacks asynchronously; cancellation must be idempotent. */
+export interface SchedulerPort {
+    schedule(args: {
+        readonly delayMs: number;
+        readonly callback: () => void;
+    }): () => void;
+}
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/scheduler.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=scheduler.js.map

package/dist/session-coordination.d.ts

@@ -0,0 +1,115 @@
+import type { RunProtocolEvent } from '@jini-ai/protocol';
+import type { SchedulerPort } from './scheduler.js';
+export interface ConversationRun {
+    readonly conversationId: string;
+    readonly runId: string;
+}
+export interface LiveRunTracker {
+    register(args: ConversationRun): void;
+    unregister(args: ConversationRun): void;
+    hasConcurrentLiveRun(args: ConversationRun): boolean;
+    concurrentLiveRunIds(args: ConversationRun): string[];
+    conversationIdForRun(args: {
+        runId: string;
+    }): string | undefined;
+}
+export declare function createLiveRunTracker(_args: Record<string, never>): LiveRunTracker;
+export interface ConversationStartLock {
+    run<T>(args: {
+        conversationId: string | undefined;
+        critical: () => Promise<T>;
+    }): Promise<T>;
+    trackedConversationCount(): number;
+}
+/** Serialize initialization only. Run execution belongs outside the critical section. */
+export declare function createConversationStartLock(_args: Record<string, never>): ConversationStartLock;
+/** Existing lifecycle port; no persistence is imported or implemented here. */
+export interface StoppingRunLifecycle {
+    onCancelRequested(args: {
+        runId: string;
+        listener: () => void;
+    }): () => void;
+    waitForTerminal(args: {
+        runId: string;
+    }): Promise<unknown>;
+}
+export declare const STOPPING_RUN_WAIT_MS = 20000;
+export declare function waitForStoppingRuns({ tracker, lifecycle, scheduler, conversationId, runId }: {
+    tracker: LiveRunTracker;
+    lifecycle: StoppingRunLifecycle;
+    scheduler: SchedulerPort;
+    conversationId: string;
+    runId: string;
+}, { timeoutMs }?: {
+    timeoutMs?: number;
+}): Promise<void>;
+export interface FailingRunLifecycle {
+    emit(args: {
+        runId: string;
+        input: {
+            event: 'error';
+            data: {
+                message: string;
+            };
+        };
+    }): Promise<unknown>;
+    finish(input: {
+        runId: string;
+        status: 'failed';
+        code: null;
+        signal: null;
+        resumable: false;
+    }): Promise<unknown>;
+}
+export declare function failRunBeforeStart({ lifecycle, runId, message }: {
+    lifecycle: FailingRunLifecycle;
+    runId: string;
+    message: string;
+}): Promise<void>;
+export interface AgentCapabilities {
+    readonly resumesSessionViaCli?: boolean;
+    readonly resumesSessionViaAcpLoad?: boolean;
+    readonly capturesSessionIdFromStream?: boolean;
+}
+export interface AgentCapabilityResolver {
+    lookup(args: {
+        agentId: string;
+    }): AgentCapabilities | undefined;
+}
+export declare function agentAcceptsHostMintedSessionId({ agentId, agents }: {
+    agentId: string;
+    agents: AgentCapabilityResolver;
+}): boolean;
+export declare function agentCarriesOwnMemory({ agentId, agents }: {
+    agentId: string;
+    agents: AgentCapabilityResolver;
+}): boolean;
+export declare function resolveHostMintedSessionId(input: {
+    conversationId: string | undefined;
+    effectiveResumeSessionId: string | null;
+    acceptsHostMintedSessionId: boolean;
+    mint: () => string;
+}): string | null;
+export declare function resolveNewSessionField({ hostMintedSessionId }: {
+    hostMintedSessionId: string | null;
+}): {
+    newSessionId?: string;
+};
+export declare function resolveResumeSessionField({ storedSessionId }: {
+    storedSessionId: string | null;
+}): {
+    resumeSessionId?: string;
+};
+export declare function extractSessionRefFromEndEvent({ event }: {
+    event: RunProtocolEvent;
+}): string | undefined;
+export declare function shouldClearSessionOnFailedResume({ event, attemptedResumeSessionId }: {
+    event: RunProtocolEvent;
+    attemptedResumeSessionId: string | null;
+}): boolean;
+export declare function wouldForcedColdStartLoseConversationContext(input: {
+    storedSessionId: string | null;
+    hasConcurrentLiveRun: boolean;
+    carriesOwnMemory: boolean;
+}): boolean;
+//# sourceMappingURL=session-coordination.d.ts.map

package/dist/session-coordination.js

@@ -0,0 +1,111 @@
+export function createLiveRunTracker(_args) {
+    const runs = new Map();
+    const conversations = new Map();
+    function unregister({ conversationId, runId }) {
+        if (conversations.get(runId) === conversationId)
+            conversations.delete(runId);
+        const ids = runs.get(conversationId);
+        ids?.delete(runId);
+        if (ids?.size === 0)
+            runs.delete(conversationId);
+    }
+    return {
+        register({ conversationId, runId }) {
+            const previous = conversations.get(runId);
+            if (previous !== undefined && previous !== conversationId)
+                unregister({ conversationId: previous, runId });
+            conversations.set(runId, conversationId);
+            const ids = runs.get(conversationId) ?? new Set();
+            ids.add(runId);
+            runs.set(conversationId, ids);
+        },
+        unregister,
+        concurrentLiveRunIds: ({ conversationId, runId }) => [...(runs.get(conversationId) ?? [])].filter(id => id !== runId),
+        hasConcurrentLiveRun({ conversationId, runId }) {
+            for (const id of runs.get(conversationId) ?? [])
+                if (id !== runId)
+                    return true;
+            return false;
+        },
+        conversationIdForRun: ({ runId }) => conversations.get(runId),
+    };
+}
+/** Serialize initialization only. Run execution belongs outside the critical section. */
+export function createConversationStartLock(_args) {
+    const tails = new Map();
+    return {
+        run({ conversationId, critical }) {
+            if (conversationId === undefined)
+                return critical();
+            const result = (tails.get(conversationId) ?? Promise.resolve()).then(critical);
+            const release = () => { if (tails.get(conversationId) === tail)
+                tails.delete(conversationId); };
+            const tail = result.then(release, release);
+            tails.set(conversationId, tail);
+            return result;
+        },
+        trackedConversationCount: () => tails.size,
+    };
+}
+export const STOPPING_RUN_WAIT_MS = 20_000;
+export async function waitForStoppingRuns({ tracker, lifecycle, scheduler, conversationId, runId }, { timeoutMs = STOPPING_RUN_WAIT_MS } = {}) {
+    const stopping = tracker.concurrentLiveRunIds({ conversationId, runId }).filter(id => {
+        let cancelled = false;
+        try {
+            lifecycle.onCancelRequested({ runId: id, listener: () => { cancelled = true; } })();
+        }
+        catch {
+            return false;
+        }
+        return cancelled;
+    });
+    if (stopping.length === 0)
+        return;
+    let cancelTimer;
+    const timedOut = new Promise(resolve => { cancelTimer = scheduler.schedule({ delayMs: timeoutMs, callback: resolve }); });
+    // Promise.resolve also captures a synchronously throwing host port, ensuring timer cleanup.
+    const ended = Promise.all(stopping.map(id => Promise.resolve().then(() => lifecycle.waitForTerminal({ runId: id })).then(() => tracker.unregister({ conversationId, runId: id }))));
+    try {
+        await Promise.race([ended, timedOut]);
+    }
+    finally {
+        cancelTimer?.();
+    }
+}
+export async function failRunBeforeStart({ lifecycle, runId, message }) {
+    try {
+        await lifecycle.emit({ runId: runId, input: { event: 'error', data: { message } } });
+    }
+    catch { /* Finishing remains mandatory. */ }
+    await lifecycle.finish({ runId, status: 'failed', code: null, signal: null, resumable: false });
+}
+export function agentAcceptsHostMintedSessionId({ agentId, agents }) {
+    const def = agents.lookup({ agentId });
+    return Boolean(def?.resumesSessionViaCli) && !def?.capturesSessionIdFromStream;
+}
+export function agentCarriesOwnMemory({ agentId, agents }) {
+    const def = agents.lookup({ agentId });
+    return Boolean(def?.resumesSessionViaCli) || Boolean(def?.resumesSessionViaAcpLoad);
+}
+export function resolveHostMintedSessionId(input) {
+    return input.conversationId !== undefined && input.effectiveResumeSessionId === null && input.acceptsHostMintedSessionId ? input.mint() : null;
+}
+export function resolveNewSessionField({ hostMintedSessionId }) {
+    return hostMintedSessionId !== null ? { newSessionId: hostMintedSessionId } : {};
+}
+export function resolveResumeSessionField({ storedSessionId }) {
+    return storedSessionId !== null ? { resumeSessionId: storedSessionId } : {};
+}
+export function extractSessionRefFromEndEvent({ event }) {
+    if (event.kind !== 'end')
+        return undefined;
+    const id = event.payload.sessionRef;
+    return typeof id === 'string' && id.length > 0 ? id : undefined;
+}
+export function shouldClearSessionOnFailedResume({ event, attemptedResumeSessionId }) {
+    return attemptedResumeSessionId !== null && event.kind === 'end' && extractSessionRefFromEndEvent({ event }) === undefined;
+}
+export function wouldForcedColdStartLoseConversationContext(input) {
+    return input.storedSessionId !== null && input.hasConcurrentLiveRun && input.carriesOwnMemory;
+}
+//# sourceMappingURL=session-coordination.js.map