@jini-ai/chat 0.5.3 → 0.5.5

package/dist/core/browser/page-actions.d.ts

@@ -0,0 +1,121 @@
+/** Resolved target supplied by the host; the client never derives a path from a title. */
+export interface ResolvedPageTarget {
+    readonly slug: string;
+    readonly title: string;
+    readonly path: string;
+}
+export type PageAction = {
+    readonly type: 'navigate';
+    readonly target: ResolvedPageTarget;
+    readonly auto: boolean;
+} | {
+    readonly type: 'scroll_to' | 'highlight';
+    readonly target: ResolvedPageTarget;
+};
+export type NavigateAction = Extract<PageAction, {
+    type: 'navigate';
+}>;
+export type NonNavigateAction = Exclude<PageAction, {
+    type: 'navigate';
+}>;
+export interface DirectiveCarryingEvent {
+    readonly kind: string;
+    readonly name?: string;
+    readonly data?: unknown;
+}
+export interface SplitPageActions {
+    readonly navigate: NavigateAction | null;
+    readonly other: NonNavigateAction | null;
+}
+/** Narrows an untrusted, bare queued action. URL authorization remains a separate host policy. O(1). */
+export declare function isQueuedPageAction(args: {
+    value: unknown;
+}): args is {
+    value: PageAction;
+};
+/** Narrows an untrusted directive envelope, dropping unknown kinds. O(1). */
+export declare function isPageActionDirective(args: {
+    value: unknown;
+}): args is {
+    value: {
+        kind: 'page_action';
+        action: PageAction;
+    };
+};
+/** Preserves valid action order while ignoring unrelated events. O(events) time and output space. */
+export declare function extractPageActions({ events, directiveEventName }: {
+    events: readonly DirectiveCarryingEvent[] | undefined;
+    directiveEventName: string;
+}): PageAction[];
+/** Returns only the first navigation and first page treatment. O(actions), O(1) extra space. */
+export declare function splitPageActions({ actions }: {
+    actions: readonly PageAction[];
+}): SplitPageActions;
+export interface TargetSelectionPolicy {
+    readonly candidateSelector: string;
+    readonly excludedAncestorSelector: string;
+}
+/** Exact title match first, case-insensitive fallback; never searches excluded UI. O(candidates). */
+export declare function findTargetElement({ title, root, selection }: {
+    title: string;
+    root: Pick<ParentNode, 'querySelectorAll'>;
+    selection: TargetSelectionPolicy;
+}): Element | null;
+export interface PageActionTimerPort {
+    schedule(args: {
+        callback: () => void;
+        delayMs: number;
+    }): unknown;
+    cancel(args: {
+        handle: unknown;
+    }): void;
+}
+export interface PageActionPort {
+    allows(args: {
+        action: PageAction;
+    }): boolean;
+    navigate(args: {
+        action: NavigateAction;
+    }): boolean;
+    execute(args: {
+        action: NonNavigateAction;
+    }): boolean;
+    clearHighlight(args: Record<string, never>): void;
+}
+export interface BrowserPageActionController extends PageActionPort {
+    applyHighlight(args: {
+        element: Element;
+    }): void;
+    scrollToElement(args: {
+        element: Element;
+    }): void;
+}
+export interface BrowserPageActionsArgs {
+    readonly root: Pick<ParentNode, 'querySelectorAll'>;
+    readonly selection: TargetSelectionPolicy;
+    readonly allowPath: (args: {
+        path: string;
+    }) => boolean;
+    readonly navigate: (args: {
+        path: string;
+    }) => void;
+    readonly reducedMotion: (args: Record<string, never>) => boolean;
+    readonly scroll: (args: {
+        element: Element;
+        options: ScrollIntoViewOptions;
+    }) => void;
+    readonly timers: PageActionTimerPort;
+    readonly highlightClass: string;
+    readonly fadeAnimationName: string;
+    readonly cleanupFallbackMs: number;
+}
+/**
+ * Creates page effects with injected DOM, navigation, URL policy, scroll and timers.
+ * At most one highlight belongs to this instance; cleanup and navigation remove it.
+ * URL policy is checked before queueing, navigation or page effects. Stale timers and descendant
+ * animation events cannot remove the current highlight. Navigation paths are resolved by the host,
+ * never guessed from a title; each controller owns its mutable highlight state.
+ * @complexity Execute O(candidates); other operations O(1), with one timer/listener retained.
+ */
+export declare function createBrowserPageActions(args: BrowserPageActionsArgs): BrowserPageActionController;
+//# sourceMappingURL=page-actions.d.ts.map

package/dist/core/browser/page-actions.js

@@ -0,0 +1,113 @@
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function target(value) {
+    return record(value) && typeof value.slug === 'string' && typeof value.title === 'string' && typeof value.path === 'string';
+}
+/** Narrows an untrusted, bare queued action. URL authorization remains a separate host policy. O(1). */
+export function isQueuedPageAction(args) {
+    const { value } = args;
+    if (!record(value) || !target(value.target))
+        return false;
+    return value.type === 'navigate' ? typeof value.auto === 'boolean' : value.type === 'scroll_to' || value.type === 'highlight';
+}
+/** Narrows an untrusted directive envelope, dropping unknown kinds. O(1). */
+export function isPageActionDirective(args) {
+    const { value } = args;
+    return record(value) && value.kind === 'page_action' && isQueuedPageAction({ value: value.action });
+}
+/** Preserves valid action order while ignoring unrelated events. O(events) time and output space. */
+export function extractPageActions({ events, directiveEventName }) {
+    const actions = [];
+    for (const event of events ?? []) {
+        const envelope = { value: event.data };
+        if (event.kind === 'ext' && event.name === directiveEventName && isPageActionDirective(envelope)) {
+            actions.push(envelope.value.action);
+        }
+    }
+    return actions;
+}
+/** Returns only the first navigation and first page treatment. O(actions), O(1) extra space. */
+export function splitPageActions({ actions }) {
+    return {
+        navigate: actions.find((a) => a.type === 'navigate') ?? null,
+        other: actions.find((a) => a.type !== 'navigate') ?? null,
+    };
+}
+/** Exact title match first, case-insensitive fallback; never searches excluded UI. O(candidates). */
+export function findTargetElement({ title, root, selection }) {
+    const needle = title.trim();
+    if (!needle)
+        return null;
+    const candidates = Array.from(root.querySelectorAll(selection.candidateSelector))
+        .filter(el => !el.closest(selection.excludedAncestorSelector));
+    return candidates.find(el => (el.textContent ?? '').trim() === needle)
+        ?? candidates.find(el => (el.textContent ?? '').trim().toLowerCase() === needle.toLowerCase()) ?? null;
+}
+/**
+ * Creates page effects with injected DOM, navigation, URL policy, scroll and timers.
+ * At most one highlight belongs to this instance; cleanup and navigation remove it.
+ * URL policy is checked before queueing, navigation or page effects. Stale timers and descendant
+ * animation events cannot remove the current highlight. Navigation paths are resolved by the host,
+ * never guessed from a title; each controller owns its mutable highlight state.
+ * @complexity Execute O(candidates); other operations O(1), with one timer/listener retained.
+ */
+export function createBrowserPageActions(args) {
+    if (!Number.isFinite(args.cleanupFallbackMs) || args.cleanupFallbackMs < 0)
+        throw new Error('Invalid highlight deadline');
+    let current = null;
+    const clearHighlight = (_args) => {
+        if (!current)
+            return;
+        const old = current;
+        current = null;
+        args.timers.cancel({ handle: old.handle });
+        old.element.removeEventListener('animationend', old.onEnd);
+        old.element.classList.remove(args.highlightClass);
+    };
+    function highlight(element) {
+        if (current?.element === element)
+            return;
+        clearHighlight({});
+        const onEnd = event => {
+            if (event.target === element && event.animationName === args.fadeAnimationName)
+                clearHighlight({});
+        };
+        element.classList.add(args.highlightClass);
+        element.addEventListener('animationend', onEnd);
+        // Identity check makes even a late callback from a canceled timer harmless.
+        const handle = args.timers.schedule({ delayMs: args.cleanupFallbackMs, callback: () => {
+                if (current?.element === element && current.onEnd === onEnd)
+                    clearHighlight({});
+            } });
+        current = { element, handle, onEnd };
+    }
+    const scrollToElement = ({ element }) => {
+        args.scroll({ element, options: { behavior: args.reducedMotion({}) ? 'auto' : 'smooth', block: 'center' } });
+    };
+    return {
+        applyHighlight({ element }) { highlight(element); },
+        scrollToElement,
+        allows({ action }) { return args.allowPath({ path: action.target.path }); },
+        navigate({ action }) {
+            if (!args.allowPath({ path: action.target.path }))
+                return false;
+            clearHighlight({});
+            args.navigate({ path: action.target.path });
+            return true;
+        },
+        execute({ action }) {
+            if (!args.allowPath({ path: action.target.path }))
+                return false;
+            const element = findTargetElement({ title: action.target.title, root: args.root, selection: args.selection });
+            if (!element)
+                return false;
+            scrollToElement({ element });
+            if (action.type === 'highlight')
+                highlight(element);
+            return true;
+        },
+        clearHighlight,
+    };
+}
+//# sourceMappingURL=page-actions.js.map

package/dist/core/composer-history.d.ts

@@ -0,0 +1,54 @@
+/** Text-only prompt recall. Browsing owns a snapshot so incoming turns cannot move its cursor. */
+export interface ComposerHistoryState {
+    entries: readonly string[];
+    index: number | null;
+    draft: string | null;
+}
+export interface ComposerHistoryStoragePort {
+    read: (required: {
+        scope: string;
+    }, optional: {}) => Promise<readonly string[]>;
+    write: (required: {
+        scope: string;
+        entries: readonly string[];
+    }, optional: {}) => Promise<void>;
+}
+export interface ComposerHistoryKeyInput {
+    key: string;
+    text: string;
+    selectionStart: number;
+    selectionEnd: number;
+    shiftKey?: boolean;
+    ctrlKey?: boolean;
+    altKey?: boolean;
+    metaKey?: boolean;
+    isComposing?: boolean;
+    popupOpen?: boolean;
+    /** A DOM host can refine logical newline boundaries with measured soft-wrap boundaries. */
+    firstLine?: boolean;
+    lastLine?: boolean;
+}
+export declare function normalizeComposerHistory({ entries }: {
+    entries: readonly string[];
+}, { cap }?: {
+    cap?: number;
+}): string[];
+export declare function mergeComposerHistory({ recent, current }: {
+    recent: readonly string[];
+    current: readonly string[];
+}, { cap }?: {
+    cap?: number;
+}): string[];
+export declare function createComposerHistoryState(_required: {}, _optional?: {}): ComposerHistoryState;
+export declare function composerHistoryKeyAction(input: ComposerHistoryKeyInput, _optional?: {}): 'previous' | 'next' | 'restore' | null;
+export declare function transitionComposerHistory({ state, action, text, entries }: {
+    state: ComposerHistoryState;
+    action: 'previous' | 'next' | 'restore' | 'edit' | 'reset';
+    text: string;
+    entries: readonly string[];
+}, _optional?: {}): {
+    state: ComposerHistoryState;
+    text: string;
+    handled: boolean;
+};
+//# sourceMappingURL=composer-history.d.ts.map

package/dist/core/composer-history.js

@@ -0,0 +1,57 @@
+export function normalizeComposerHistory({ entries }, { cap = 100 } = {}) {
+    const result = [];
+    for (const text of entries) {
+        // Blank/attachment-only turns are not useful prompts; meaningful whitespace stays exact.
+        if (text.trim() && text !== result[result.length - 1])
+            result.push(text);
+    }
+    return result.slice(-Math.max(1, Math.floor(cap)));
+}
+export function mergeComposerHistory({ recent, current }, { cap = 100 } = {}) {
+    const left = normalizeComposerHistory({ entries: recent }, { cap });
+    const right = normalizeComposerHistory({ entries: current }, { cap });
+    // A mounted conversation is usually already the recent list's suffix. Do not append its
+    // entire transcript again on every streamed render; preserve nonconsecutive repetitions.
+    let overlap = Math.min(left.length, right.length);
+    while (overlap > 0 && !right.slice(0, overlap).every((text, i) => text === left[left.length - overlap + i]))
+        overlap -= 1;
+    return normalizeComposerHistory({ entries: [...left, ...right.slice(overlap)] }, { cap });
+}
+export function createComposerHistoryState(_required, _optional = {}) {
+    return { entries: [], index: null, draft: null };
+}
+export function composerHistoryKeyAction(input, _optional = {}) {
+    if (input.shiftKey || input.ctrlKey || input.altKey || input.metaKey || input.isComposing || input.popupOpen)
+        return null;
+    if (input.key === 'Escape')
+        return 'restore';
+    const start = Math.min(input.selectionStart, input.selectionEnd);
+    const end = Math.max(input.selectionStart, input.selectionEnd);
+    if (input.text.slice(start, end).includes('\n'))
+        return null;
+    const firstLine = !input.text.slice(0, end).includes('\n') && input.firstLine !== false;
+    const lastLine = !input.text.slice(start).includes('\n') && input.lastLine !== false;
+    if (input.key === 'ArrowUp' && firstLine)
+        return 'previous';
+    if (input.key === 'ArrowDown' && lastLine)
+        return 'next';
+    return null;
+}
+export function transitionComposerHistory({ state, action, text, entries }, _optional = {}) {
+    if (action === 'edit' || action === 'reset') {
+        return { state: createComposerHistoryState({}), text, handled: false };
+    }
+    if (state.index === null) {
+        if (action !== 'previous' || entries.length === 0)
+            return { state, text, handled: false };
+        const snapshot = [...entries];
+        const index = snapshot.length - 1;
+        return { state: { entries: snapshot, index, draft: text }, text: snapshot[index], handled: true };
+    }
+    if (action === 'restore' || (action === 'next' && state.index === state.entries.length - 1)) {
+        return { state: createComposerHistoryState({}), text: state.draft ?? '', handled: true };
+    }
+    const index = action === 'previous' ? Math.max(0, state.index - 1) : state.index + 1;
+    return { state: { ...state, index }, text: state.entries[index], handled: true };
+}
+//# sourceMappingURL=composer-history.js.map

package/dist/core/durable-projection.d.ts

@@ -0,0 +1,28 @@
+import type { AgentEvent } from './events.js';
+import type { ChatMessage } from './messages.js';
+/** Saved checkpoints can coalesce deltas and a completion may replay only a prefix. Keep the
+ * saved projection, merge identifiable events, and append only text beyond its saved prefix. */
+export declare function mergeRunEvents({ saved, incoming }: {
+    saved?: readonly AgentEvent[] | undefined;
+    incoming: readonly AgentEvent[];
+}, _optional?: {}): AgentEvent[];
+/** A recovered attempt stays visibly in progress until new text or tool work supersedes its marker. */
+export declare function continuingRunNotice({ events, active }: {
+    events: readonly AgentEvent[] | undefined;
+    active: boolean;
+}, _optional?: {}): string | null;
+export declare function preserveAssistantContent({ saved, incoming }: {
+    saved: string;
+    incoming: string;
+}, _optional?: {}): string;
+/** Terminal failure belongs to the message. Legacy resend instructions are display-only;
+ * changing this copy must never execute or reopen an old terminal run. */
+export declare function terminalMessageNotice({ message }: {
+    message: ChatMessage;
+}, _optional?: {}): string | null;
+/** The first answer has no earlier segment to divide, even if startup was retried. Only saved
+ * visible text can justify a Continued divider; the recovery marker still records the attempt. */
+export declare function recoveredRunEvents({ saved }: {
+    saved: readonly AgentEvent[];
+}, _optional?: {}): AgentEvent[];
+//# sourceMappingURL=durable-projection.d.ts.map

package/dist/core/durable-projection.js

@@ -0,0 +1,71 @@
+function identity(event) {
+    const wire = event;
+    if (wire.eventId !== undefined)
+        return `event:${wire.eventId}`;
+    if (wire.cursor !== undefined)
+        return `cursor:${wire.cursor}`;
+    if (event.kind === 'tool_use')
+        return `use:${event.id}`;
+    if (event.kind === 'tool_result')
+        return `result:${event.toolUseId}`;
+    return JSON.stringify(event);
+}
+function textOf(events) {
+    return events.filter((event) => event.kind === 'text').map((event) => event.text).join('');
+}
+/** Saved checkpoints can coalesce deltas and a completion may replay only a prefix. Keep the
+ * saved projection, merge identifiable events, and append only text beyond its saved prefix. */
+export function mergeRunEvents({ saved, incoming }, _optional = {}) {
+    const previous = saved ?? [];
+    const result = [...previous];
+    const keys = new Set(previous.map(identity));
+    const before = textOf(previous);
+    const after = textOf(incoming);
+    let skip = after.startsWith(before) ? before.length : after.length;
+    for (const event of incoming) {
+        if (event.kind === 'text') {
+            const text = event.text.slice(skip);
+            skip = Math.max(0, skip - event.text.length);
+            if (text)
+                result.push({ ...event, text });
+        }
+        else if (!keys.has(identity(event))) {
+            keys.add(identity(event));
+            result.push(event);
+        }
+    }
+    return result;
+}
+/** A recovered attempt stays visibly in progress until new text or tool work supersedes its marker. */
+export function continuingRunNotice({ events, active }, _optional = {}) {
+    if (!active)
+        return null;
+    const list = events ?? [];
+    const marker = list.findLastIndex((event) => event.kind === 'status' && event.code === 'run_recovering');
+    if (marker < 0)
+        return null;
+    const progressed = list.slice(marker + 1).some((event) => event.kind === 'text' || event.kind === 'tool_use' || event.kind === 'tool_result');
+    return progressed ? null : 'Continuing…';
+}
+export function preserveAssistantContent({ saved, incoming }, _optional = {}) {
+    return incoming.length >= saved.length ? incoming : saved;
+}
+/** Terminal failure belongs to the message. Legacy resend instructions are display-only;
+ * changing this copy must never execute or reopen an old terminal run. */
+export function terminalMessageNotice({ message }, _optional = {}) {
+    if (message.runStatus !== 'failed' && message.runStatus !== 'canceled')
+        return null;
+    const notice = message.events?.filter((event) => event.kind === 'status' &&
+        (event.code === 'run_terminal' || /failed|stopped|restarted|could not|not logged in|cancell?ed/i.test(event.label))).at(-1);
+    if (notice?.kind === 'status')
+        return [notice.label, notice.detail].filter(Boolean).join(' ').replace(/Send your message again to retry\.?/gi, '').trim();
+    return message.runStatus === 'failed' ? 'This turn failed.' : 'Stopped.';
+}
+/** The first answer has no earlier segment to divide, even if startup was retried. Only saved
+ * visible text can justify a Continued divider; the recovery marker still records the attempt. */
+export function recoveredRunEvents({ saved }, _optional = {}) {
+    const hasAnswer = saved.some(event => event.kind === 'text' && event.text.trim().length > 0);
+    return [...saved, ...(hasAnswer ? [{ kind: 'text', text: '\n\n---\n\nContinued\n\n' }] : []),
+        { kind: 'status', code: 'run_recovering', label: 'Continuing…' }];
+}
+//# sourceMappingURL=durable-projection.js.map

package/dist/core/durable-runs/continuation.d.ts

@@ -0,0 +1,18 @@
+import type { AgentEvent } from "../index.js";
+import type { AcceptedRunRequest, DurableRun } from "./ports.js";
+export declare const CONTINUATION_DIVIDER = "\n\n---\n\nContinued\n\n";
+export declare const UNKNOWN_MUTATION_ERROR = "This operation may already be done. Its earlier outcome is unknown; verify the current state before repeating it.";
+/** Object-key order and a new tool-use id must not turn the same mutation into a new operation. */
+export declare function canonicalToolInput({ value }: {
+    value: unknown;
+}, _optional?: {}): string;
+export declare function hasUnknownToolCall({ events, toolId, input }: {
+    events: readonly AgentEvent[];
+    toolId: string;
+    input: unknown;
+}, _optional?: {}): boolean;
+export declare function continuationRequest({ run, native }: {
+    run: DurableRun;
+    native: boolean;
+}, _optional?: {}): AcceptedRunRequest;
+//# sourceMappingURL=continuation.d.ts.map

package/dist/core/durable-runs/continuation.js

@@ -0,0 +1,61 @@
+export const CONTINUATION_DIVIDER = "\n\n---\n\nContinued\n\n";
+export const UNKNOWN_MUTATION_ERROR = "This operation may already be done. Its earlier outcome is unknown; verify the current state before repeating it.";
+/** Object-key order and a new tool-use id must not turn the same mutation into a new operation. */
+export function canonicalToolInput({ value }, _optional = {}) {
+    if (Array.isArray(value))
+        return `[${value.map((item) => canonicalToolInput({ value: item }, {})).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        const object = value;
+        return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${canonicalToolInput({ value: object[key] }, {})}`).join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+function delegatedCall(event) {
+    const input = event.input;
+    if (input && typeof input.toolId === "string" && /execute.*delegated_tool/.test(event.name))
+        return { toolId: input.toolId, input: input.input };
+    return { toolId: event.name, input: event.input };
+}
+export function hasUnknownToolCall({ events, toolId, input }, _optional = {}) {
+    const completed = new Set(events.filter((event) => event.kind === "tool_result").map((event) => event.toolUseId));
+    const canonical = canonicalToolInput({ value: input }, {});
+    return events.some((event) => {
+        if (event.kind !== "tool_use" || completed.has(event.id))
+            return false;
+        const call = delegatedCall(event);
+        return call.toolId === toolId && canonicalToolInput({ value: call.input }, {}) === canonical;
+    });
+}
+function toolHistory(events) {
+    const results = new Map(events.filter((event) => event.kind === "tool_result").map((event) => [event.toolUseId, event]));
+    return events.filter((event) => event.kind === "tool_use").map((event) => {
+        const result = results.get(event.id);
+        return JSON.stringify({ call: delegatedCall(event), result: result ?? "OUTCOME UNKNOWN: verify state before repeating" });
+    }).join("\n");
+}
+export function continuationRequest({ run, native }, _optional = {}) {
+    const original = JSON.parse(run.request.contextRef);
+    // Native sessions may have disappeared on deploy. Reconstruction includes the saved answer
+    // and tool results for every runtime; completed side effects must never be silently repeated.
+    const transcript = run.transcript.map((message) => `${message.role}: ${message.content}`).join("\n\n");
+    const prompt = [
+        "Continue the interrupted answer from the saved work below. Preserve completed work. Do not repeat completed mutations.",
+        "Calls without a result have an unknown outcome: inspect current state before any retry. Expired plans or approvals must be re-planned and re-approved; never reuse them.",
+        "A pending question may be asked again when its process was lost. The interrupted segment remains visible; append the continuation.",
+        `Accepted task:\n${String(original.prompt ?? "")}`,
+        native ? "Native session is confirmed; continue its saved task." : `Saved conversation:\n${transcript}`,
+        `Saved partial answer:\n${run.message.content}`,
+        `Saved tool calls and results:\n${toolHistory(run.message.events ?? [])}`,
+    ].join("\n\n");
+    return {
+        ...run.request,
+        contextRef: JSON.stringify({ ...original, prompt, conversationId: run.conversationId,
+            assistantMessageId: run.messageId, principalId: run.principalId,
+            recoveryMode: native ? "native" : "reconstruction", recoverySessionId: native ? run.sessionId : undefined,
+            // Old attachment claims have been consumed. Saved transcript/tool results carry their
+            // observations; attempting to claim the same ids again would fail before execution.
+            attachmentIds: [],
+        }),
+    };
+}
+//# sourceMappingURL=continuation.js.map

package/dist/core/durable-runs/ledger-contracts.d.ts

@@ -0,0 +1,53 @@
+import type { ChatMessage } from "../index.js";
+import type { DurableRunStore } from "./ports.js";
+import type { RunRef, RunProgress, RunSettlement } from "./run-contracts.js";
+export type { RunRef, RunProgress, RunSettlement } from "./run-contracts.js";
+/** {@link ChatRunLedger.unlessSettled}'s result: the write's value, or that the run had settled. */
+export type UnlessSettled<T> = {
+    readonly written: true;
+    readonly value: T;
+} | {
+    readonly written: false;
+};
+/** Internal boot recovery, never an HTTP history read. The owner comes from storage, not a client. */
+export interface InterruptedChatTurn {
+    readonly principalId: string | null;
+    readonly conversationId: string;
+    readonly message: ChatMessage;
+}
+export interface ChatRunRecoveryOptions {
+    /** True retains the row: a daemon run was adopted with bounded resolution of uncertainty.
+     * Called outside storage transactions so a daemon request cannot hold the database lock. */
+    readonly recover?: (input: InterruptedChatTurn) => Promise<boolean>;
+}
+export interface ChatRunLedger {
+    readonly durable?: DurableRunStore;
+    /**
+     * Runs `write` only while `run`'s row holds no terminal status (an unknown row, another run id, or
+     * a row still `queued`/`running` all count as unsettled), with no settle able to land in between.
+     * `write` must reach the chat database through this ledger's kernel (the same connection, on
+     * SQLite) so it joins the transaction.
+     */
+    unlessSettled<T>(required: {
+        run: RunRef;
+        write: () => Promise<T>;
+    }, optional?: {}): Promise<UnlessSettled<T>>;
+    /**
+     * Writes the run's final content, events and status — only if the row still belongs to that run
+     * and is not yet terminal. Resolves `true` when this call was the one that settled it.
+     */
+    settle(settlement: RunSettlement, optional?: {}): Promise<boolean>;
+    /**
+     * Saves what a still-running run has produced so far (content and events; the status stays), so
+     * a process that dies mid-run leaves its partial answer for {@link reconcileInterrupted} to keep.
+     * A no-op once the row is terminal or belongs to another run. Resolves `true` when it wrote.
+     */
+    checkpoint(progress: RunProgress, optional?: {}): Promise<boolean>;
+    /** Serving-only discovery of unfinished rows. The injected recovery coordinator owns adopted
+     * runs; rows it cannot adopt are canceled, preserving saved work. Returns handled rows.
+     * Export apps must not invoke discovery while a serving daemon is still alive. */
+    reconcileInterrupted(required?: {
+        now?: number;
+    }, optional?: ChatRunRecoveryOptions): Promise<number>;
+}
+//# sourceMappingURL=ledger-contracts.d.ts.map

package/dist/core/durable-runs/ledger-contracts.js

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

package/dist/core/durable-runs/policies.d.ts

@@ -0,0 +1,6 @@
+export declare const RECOVERY_LIMIT = 3;
+export declare const RECOVERY_WINDOW_MS: number;
+export declare const RUN_STALENESS_MS: number;
+export declare const SAVED_WORK_NOTICE = "The assistant stopped after making no progress. Saved work is above.";
+export declare const EXHAUSTED_NOTICE = "The assistant could not continue this answer. Saved work is above.";
+//# sourceMappingURL=policies.d.ts.map

package/dist/core/durable-runs/policies.js

@@ -0,0 +1,6 @@
+export const RECOVERY_LIMIT = 3;
+export const RECOVERY_WINDOW_MS = 5 * 60_000;
+export const RUN_STALENESS_MS = 30 * 60_000;
+export const SAVED_WORK_NOTICE = "The assistant stopped after making no progress. Saved work is above.";
+export const EXHAUSTED_NOTICE = "The assistant could not continue this answer. Saved work is above.";
+//# sourceMappingURL=policies.js.map