@sema-agent/client-core 0.99.0 → 0.101.0

package/dist/terminationIntent.js

@@ -0,0 +1,352 @@
+import { usableClockMs } from './clockReading.js';
+import { displayUntrusted } from './displayUntrusted.js';
+import { linkedAbortSignal, readSignalAborted, readSignalReason, tryListenAbortOnce, tryUnlistenAbort } from './engineWireFor.js';
+import { msg, renderMessage } from './i18n/translate.js';
+import { abortableSleep } from './abortableSleep.js';
+import { isSdkRunParked, isSdkRunTerminal } from './terminalStatuses.js';
+export const TERMINATION_INTENT_TTL_MS = 60_000;
+export const TERMINATION_INTENT_WEAK_SOURCE = 'esc-abort';
+export const INTERRUPTED_SETTLE_BUDGET_MS = 10_000;
+export const INTERRUPTED_SETTLE_POLL_MS = 1_000;
+const MAX_ROWS = 256;
+const MAX_TRACKED_WRITES = 1024;
+const validId = (taskId) => typeof taskId === 'string' && taskId.length > 0;
+const validSource = (s) => typeof s === 'string' && s.length > 0;
+function readSnapshot(s) {
+    try {
+        if (typeof s !== 'object' || s === null)
+            return null;
+        const raw = s;
+        const source = raw.source;
+        const at = raw.at;
+        const abortAt = raw.abortAt;
+        if (!validSource(source) || usableClockMs(at) === null)
+            return null;
+        return { source, at: at, abortAt: typeof abortAt === 'number' && usableClockMs(abortAt) !== null ? abortAt : null };
+    }
+    catch {
+        return null;
+    }
+}
+export function createTerminationIntentLedger(options) {
+    if (typeof options !== 'object' || options === null || typeof options.now !== 'function') {
+        throw new TypeError('createTerminationIntentLedger: options.now must be a function returning milliseconds');
+    }
+    const readClock = options.now;
+    const ttl = typeof options.ttlMs === 'number' && Number.isFinite(options.ttlMs) && options.ttlMs > 0 ? options.ttlMs : TERMINATION_INTENT_TTL_MS;
+    const exempt = Object.freeze([...(options.exemptAbortReasons ?? ['background'])]);
+    const rows = new Map();
+    let nextVersion = 1;
+    const priors = new Map();
+    const refused = new Set();
+    const trackBounded = (m, k, v) => {
+        m.set(k, v);
+        while (m.size > MAX_TRACKED_WRITES) {
+            const oldest = m.keys().next();
+            if (oldest.done === true)
+                break;
+            m.delete(oldest.value);
+        }
+    };
+    const markRefused = (version) => {
+        if (typeof version !== 'number')
+            return;
+        refused.add(version);
+        while (refused.size > MAX_TRACKED_WRITES) {
+            const oldest = refused.values().next();
+            if (oldest.done === true)
+                break;
+            refused.delete(oldest.value);
+        }
+    };
+    const effectivePrior = (version) => {
+        if (!priors.has(version))
+            return { known: false, row: null };
+        let row = priors.get(version) ?? null;
+        for (let hops = 0; row !== null && refused.has(row.version) && priors.has(row.version) && hops < MAX_TRACKED_WRITES; hops += 1)
+            row = priors.get(row.version) ?? null;
+        return { known: true, row };
+    };
+    const clock = () => {
+        try {
+            return usableClockMs(readClock());
+        }
+        catch {
+            return null;
+        }
+    };
+    const isFresh = (now, at) => {
+        const age = now - at;
+        return age >= 0 && age < ttl;
+    };
+    const purge = (now) => {
+        for (const [taskId, row] of rows) {
+            if (isFresh(now, row.at))
+                continue;
+            if (row.abortAt !== null && isFresh(now, row.abortAt)) {
+                rows.set(taskId, { at: row.abortAt, source: TERMINATION_INTENT_WEAK_SOURCE, abortAt: row.abortAt, version: nextVersion++ });
+            }
+            else {
+                rows.delete(taskId);
+            }
+        }
+    };
+    const put = (taskId, row) => {
+        rows.delete(taskId);
+        while (rows.size >= MAX_ROWS) {
+            const oldest = rows.keys().next();
+            if (oldest.done === true)
+                break;
+            rows.delete(oldest.value);
+        }
+        rows.set(taskId, row);
+    };
+    const record = (taskId, source) => {
+        if (!validId(taskId) || !validSource(source))
+            return 0;
+        const now = clock();
+        if (now === null)
+            return 0;
+        purge(now);
+        const prev = rows.get(taskId);
+        const abortAt = prev?.abortAt ?? (source === TERMINATION_INTENT_WEAK_SOURCE ? now : null);
+        const version = nextVersion++;
+        trackBounded(priors, version, prev ?? null);
+        put(taskId, { at: now, source, abortAt, version });
+        return version;
+    };
+    const rollback = (taskId, prior) => {
+        if (!validId(taskId))
+            return;
+        const now = clock();
+        if (now === null)
+            return;
+        purge(now);
+        if (prior !== null && validSource(prior) && prior !== TERMINATION_INTENT_WEAK_SOURCE) {
+            record(taskId, prior);
+            return;
+        }
+        const row = rows.get(taskId);
+        const abortAt = row?.abortAt ?? null;
+        if (abortAt !== null && isFresh(now, abortAt)) {
+            put(taskId, { at: abortAt, source: TERMINATION_INTENT_WEAK_SOURCE, abortAt, version: nextVersion++ });
+            return;
+        }
+        rows.delete(taskId);
+    };
+    const restoreTo = (taskId, row, target, now) => {
+        if (target === null) {
+            rollback(taskId, null);
+            return;
+        }
+        const abortAt = target.abortAt === null ? row.abortAt : row.abortAt === null ? target.abortAt : Math.max(target.abortAt, row.abortAt);
+        put(taskId, { at: target.at, source: target.source, abortAt, version: target.version ?? nextVersion++ });
+        purge(now);
+    };
+    return {
+        record,
+        snapshot(taskId) {
+            if (!validId(taskId))
+                return null;
+            const now = clock();
+            if (now === null)
+                return null;
+            purge(now);
+            const row = rows.get(taskId);
+            return row === undefined ? null : Object.freeze({ source: row.source, at: row.at, abortAt: row.abortAt });
+        },
+        restoreIf(taskId, version, snapshot) {
+            if (!validId(taskId))
+                return false;
+            const now = clock();
+            if (now === null)
+                return false;
+            purge(now);
+            markRefused(version);
+            const row = rows.get(taskId);
+            if (row === undefined || row.version !== version)
+                return false;
+            const eff = effectivePrior(version);
+            restoreTo(taskId, row, eff.known ? eff.row : readSnapshot(snapshot), now);
+            return true;
+        },
+        rollbackIf(taskId, version, prior) {
+            if (!validId(taskId))
+                return false;
+            const now = clock();
+            if (now === null)
+                return false;
+            purge(now);
+            markRefused(version);
+            const row = rows.get(taskId);
+            if (row === undefined || row.version !== version)
+                return false;
+            const eff = effectivePrior(version);
+            if (eff.known)
+                restoreTo(taskId, row, eff.row, now);
+            else
+                rollback(taskId, prior);
+            return true;
+        },
+        rollback,
+        wasRecentlyTerminatedByUs(taskId) {
+            if (!validId(taskId))
+                return false;
+            const now = clock();
+            if (now === null)
+                return false;
+            purge(now);
+            return rows.has(taskId);
+        },
+        sourceOf(taskId) {
+            if (!validId(taskId))
+                return null;
+            const now = clock();
+            if (now === null)
+                return null;
+            purge(now);
+            return rows.get(taskId)?.source ?? null;
+        },
+        armOnAbort(signal, taskId) {
+            if (signal === undefined || signal === null || !validId(taskId))
+                return;
+            const onAbort = () => {
+                const read = readSignalReason(signal);
+                if (read === null)
+                    return;
+                if (typeof read.reason === 'string' && exempt.includes(read.reason))
+                    return;
+                const now = clock();
+                if (now === null)
+                    return;
+                purge(now);
+                const existing = rows.get(taskId);
+                if (existing !== undefined && existing.source !== TERMINATION_INTENT_WEAK_SOURCE) {
+                    put(taskId, { ...existing, abortAt: now });
+                    return;
+                }
+                put(taskId, { at: now, source: TERMINATION_INTENT_WEAK_SOURCE, abortAt: now, version: nextVersion++ });
+            };
+            const aborted = readSignalAborted(signal);
+            if (aborted === null)
+                return;
+            if (aborted) {
+                onAbort();
+                return;
+            }
+            tryListenAbortOnce(signal, onAbort);
+        },
+        forget(taskId) {
+            if (!validId(taskId))
+                return;
+            rows.delete(taskId);
+        },
+        size() {
+            const now = clock();
+            if (now !== null)
+                purge(now);
+            return rows.size;
+        },
+    };
+}
+function readStatus(row) {
+    try {
+        const s = row?.status;
+        return typeof s === 'string' && s.length > 0 ? s : null;
+    }
+    catch {
+        return null;
+    }
+}
+const PROBE_STOPPED = Symbol('sema.interruptedSettleProbeStopped');
+const PROBE_FAILED = Symbol('sema.interruptedSettleProbeFailed');
+const positive = (v, fallback) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : fallback);
+export async function awaitInterruptedRunSettle(taskId, deps) {
+    const getRun = deps?.getRun;
+    if (typeof getRun !== 'function')
+        return { kind: 'unknown' };
+    if (!validId(taskId))
+        return { kind: 'unknown' };
+    const budgetMs = positive(deps.budgetMs, INTERRUPTED_SETTLE_BUDGET_MS);
+    const intervalMs = positive(deps.intervalMs, INTERRUPTED_SETTLE_POLL_MS);
+    const clockNow = typeof deps.now === 'function' ? deps.now : () => performance.now();
+    const readNow = () => {
+        try {
+            const t = clockNow();
+            return Number.isFinite(t) ? t : 0;
+        }
+        catch {
+            return 0;
+        }
+    };
+    const started = readNow();
+    let sawRunning = false;
+    const isAborted = () => deps.signal?.aborted === true;
+    const budgetAc = new AbortController();
+    let budgetSpent = false;
+    let markStopped = () => { };
+    const stopped = new Promise((resolve) => {
+        markStopped = () => resolve(PROBE_STOPPED);
+    });
+    const onCallerAbort = () => markStopped();
+    const budgetTimer = setTimeout(() => {
+        budgetSpent = true;
+        budgetAc.abort();
+        markStopped();
+    }, budgetMs);
+    if (deps.signal !== undefined)
+        tryListenAbortOnce(deps.signal, onCallerAbort);
+    if (isAborted())
+        markStopped();
+    const linked = linkedAbortSignal(deps.signal, budgetAc.signal);
+    const probeSignal = linked.signal;
+    try {
+        for (;;) {
+            if (isAborted())
+                return { kind: 'unknown' };
+            if (budgetSpent)
+                break;
+            let probe;
+            try {
+                probe = Promise.resolve(getRun(taskId, { signal: probeSignal })).then((row) => row, () => PROBE_FAILED);
+            }
+            catch {
+                probe = Promise.resolve(PROBE_FAILED);
+            }
+            const outcome = await Promise.race([probe, stopped]);
+            if (isAborted())
+                return { kind: 'unknown' };
+            const status = outcome === PROBE_STOPPED || outcome === PROBE_FAILED ? null : readStatus(outcome);
+            if (status !== null) {
+                if (isSdkRunTerminal(status))
+                    return { kind: 'settled', status };
+                if (isSdkRunParked(status))
+                    return { kind: 'parked', status };
+                if (status === 'running')
+                    sawRunning = true;
+            }
+            if (budgetSpent)
+                break;
+            const left = started + budgetMs - readNow();
+            if (left <= 0)
+                break;
+            await abortableSleep(Math.min(intervalMs, left), probeSignal);
+            if (isAborted())
+                return { kind: 'unknown' };
+        }
+        if (isAborted())
+            return { kind: 'unknown' };
+        return sawRunning ? { kind: 'still-running', waitedMs: Math.max(0, readNow() - started) } : { kind: 'unknown' };
+    }
+    finally {
+        clearTimeout(budgetTimer);
+        linked.dispose();
+        if (deps.signal !== undefined)
+            tryUnlistenAbort(deps.signal, onCallerAbort);
+    }
+}
+export function interruptedRunSettleRow(taskId, verdict, lang) {
+    if (typeof verdict !== 'object' || verdict === null || verdict.kind !== 'settled')
+        return null;
+    return renderMessage(msg('session.selfHeal.row.interrupted.settled', { taskId: displayUntrusted(String(taskId), { max: 120 }) }), lang);
+}

package/dist/toolHistoryMismatch.d.ts

@@ -29,6 +29,8 @@ export interface ToolHistoryMismatchRowKey {
 }
 export declare function toolHistoryMismatchRowKey(m: ToolHistoryMismatch, consecutive: number | undefined, rewindOffered: boolean): ToolHistoryMismatchRowKey;
 export declare function readToolHistoryMismatchKey(v: object | null | undefined): ToolHistoryMismatchRowKey | undefined;
+export declare const SEMA_TOOL_HISTORY_ACCEPTED_KEY = "_sema_tool_history_accepted";
+export declare function readToolHistoryAcceptedKey(frame: object | null | undefined): true | undefined;
 export declare const TOOL_HISTORY_LEDGER_CAP = 64;
 export declare function openToolHistoryGeneration(): number;
 export interface ToolHistoryTerminalNote {
@@ -38,8 +40,14 @@ export interface ToolHistoryTerminalNote {
     runId: string | undefined;
     replay: boolean;
     mismatch: ToolHistoryMismatch | null;
+    accepted?: boolean;
+}
+export interface ToolHistoryTerminalFacts {
+    readonly consecutive: number | undefined;
+    readonly acceptedSinceMismatch: true | undefined;
 }
 export declare function noteToolHistoryTerminal(note: ToolHistoryTerminalNote): number | undefined;
+export declare function noteToolHistoryTerminalFacts(note: ToolHistoryTerminalNote): ToolHistoryTerminalFacts;
 export declare function _resetToolHistoryLedgerForTest(): void;
 export interface ToolHistoryRow {
     readonly toolUseIds?: readonly string[];

package/dist/toolHistoryMismatch.js

@@ -286,6 +286,18 @@ function ownDataMember(o, k) {
         return undefined;
     }
 }
+export const SEMA_TOOL_HISTORY_ACCEPTED_KEY = '_sema_tool_history_accepted';
+export function readToolHistoryAcceptedKey(frame) {
+    try {
+        if (typeof frame !== 'object' || frame === null)
+            return undefined;
+        const d = Object.getOwnPropertyDescriptor(frame, SEMA_TOOL_HISTORY_ACCEPTED_KEY);
+        return d !== undefined && Object.hasOwn(d, 'value') && d.value === true ? true : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 export const TOOL_HISTORY_LEDGER_CAP = 64;
 const PRIOR_RUN_IDS_CAP = 16;
 const ECHOED_SESSION_IDS_CAP = TOOL_HISTORY_LEDGER_CAP * 4;
@@ -308,16 +320,30 @@ export function openToolHistoryGeneration() {
     return toolHistoryGenerationSeq;
 }
 const fingerprintOf = (m) => `${m.kind}\u0000${m.toolUseId ?? ''}`;
+function acceptanceStep(prev, note, attributed) {
+    if (note.replay)
+        return { awaiting: prev, accepted: undefined };
+    if (note.mismatch !== null)
+        return { awaiting: true, accepted: undefined };
+    if (note.accepted === true)
+        return attributed ? { awaiting: false, accepted: prev ? true : undefined } : { awaiting: prev, accepted: undefined };
+    return { awaiting: prev, accepted: undefined };
+}
 export function noteToolHistoryTerminal(note) {
+    return noteToolHistoryTerminalFacts(note).consecutive;
+}
+export function noteToolHistoryTerminalFacts(note) {
+    const none = { consecutive: undefined, acceptedSinceMismatch: undefined };
     const { sessionId, generation, runId, replay, mismatch } = note;
     if (typeof sessionId !== 'string' || sessionId.length === 0) {
         unattributedTerminalSeq += 1;
-        return undefined;
+        return none;
     }
     if (note.sessionEchoed === true)
         rememberEchoedSession(sessionId);
     else if (!echoedSessionIds.has(sessionId))
         unattributedTerminalSeq += 1;
+    const attributed = note.sessionEchoed === true || echoedSessionIds.has(sessionId);
     const row = toolHistoryLedger.get(sessionId);
     const fingerprint = mismatch === null ? null : fingerprintOf(mismatch);
     const run = !replay && typeof runId === 'string' && runId.length > 0 ? runId : undefined;
@@ -330,25 +356,29 @@ export function noteToolHistoryTerminal(note) {
                 unattributedMark: unattributedTerminalSeq,
                 lastRunId: undefined,
                 recentRunIds: run !== undefined ? [...row.recentRunIds, run].slice(-PRIOR_RUN_IDS_CAP) : row.recentRunIds,
+                awaitingAcceptance: row.awaitingAcceptance,
             });
         }
-        return undefined;
+        return none;
     }
     if (row !== undefined)
         row.writtenGeneration = generation;
     const interrupted = row !== undefined && row.unattributedMark < unattributedTerminalSeq;
     if (run !== undefined && row !== undefined && (row.segmentRunIds.has(run) || row.recentRunIds.includes(run))) {
-        return !interrupted && row.lastRunId === run && fingerprint !== null && row.fingerprint === fingerprint ? row.segmentRunIds.size : undefined;
+        const repeated = !interrupted && row.lastRunId === run && fingerprint !== null && row.fingerprint === fingerprint ? row.segmentRunIds.size : undefined;
+        return { consecutive: repeated, acceptedSinceMismatch: undefined };
     }
+    const acceptance = acceptanceStep(row?.awaitingAcceptance ?? false, note, attributed);
     if (row !== undefined && row.fingerprint === fingerprint && !(interrupted && fingerprint !== null && run !== undefined)) {
+        row.awaitingAcceptance = acceptance.awaiting;
         if (run === undefined)
-            return undefined;
+            return { consecutive: undefined, acceptedSinceMismatch: acceptance.accepted };
         if (fingerprint !== null)
             row.segmentRunIds.add(run);
         row.lastRunId = run;
         row.recentRunIds = [...row.recentRunIds, run].slice(-PRIOR_RUN_IDS_CAP);
         touchLedgerRow(sessionId, row);
-        return fingerprint === null ? undefined : row.segmentRunIds.size;
+        return { consecutive: fingerprint === null ? undefined : row.segmentRunIds.size, acceptedSinceMismatch: acceptance.accepted };
     }
     touchLedgerRow(sessionId, {
         fingerprint,
@@ -357,8 +387,9 @@ export function noteToolHistoryTerminal(note) {
         unattributedMark: unattributedTerminalSeq,
         lastRunId: run,
         recentRunIds: run !== undefined ? [...(row?.recentRunIds ?? []), run].slice(-PRIOR_RUN_IDS_CAP) : [...(row?.recentRunIds ?? [])],
+        awaitingAcceptance: acceptance.awaiting,
     });
-    return fingerprint !== null && run !== undefined ? 1 : undefined;
+    return { consecutive: fingerprint !== null && run !== undefined ? 1 : undefined, acceptedSinceMismatch: acceptance.accepted };
 }
 function touchLedgerRow(sessionId, row) {
     toolHistoryLedger.delete(sessionId);

package/dist/toolResult.d.ts

@@ -112,21 +112,31 @@ export interface ToolResultRowFlags {
 }
 export declare function toolResultRowFlagsOf(row: object | null | undefined): ToolResultRowFlags;
 export type ToolKillCause = NonNullable<ReturnType<typeof toolKillCauseAcrossEngineIdentity>> | 'memory_pressure';
-export declare function wireOutputToBody(toolName: string, output: unknown, isError: boolean, truncated: boolean, flatten: FlattenWireOutput, structured?: unknown, leaderLedger?: boolean, killCauseOf?: () => ToolKillCause | undefined): ToolResultBody;
+export declare function wireOutputToBody(toolName: string, output: unknown, isError: boolean, truncated: boolean, flatten: FlattenWireOutput, structuredIn?: unknown, leaderLedger?: boolean, killCauseOf?: () => ToolKillCause | undefined): ToolResultBody;
 export declare function structuredToToolUseResult(structured: unknown, modelText?: string, leaderLedger?: boolean): {
     toolUseResult: unknown;
     isError?: boolean;
 } | null;
+export interface WebSearchSource {
+    readonly title: string;
+    readonly url: string;
+}
+export type WebSearchSources = readonly WebSearchSource[] & {
+    readonly droppedCount: number;
+};
+export declare function webSearchSourcesOf(toolEnd: {} | null | undefined): WebSearchSources | undefined;
 export interface EngineBgShellRegistration {
     kind: 'register';
     taskId: string;
+    toolUseId?: string;
     command: string;
     description?: string;
     receipt: string;
+    outputFile?: string;
     source: 'bash' | 'monitor';
 }
-export declare function detectEngineBgShellReceipt(toolName: string, rawInput: unknown, outputText: string | undefined, structured?: unknown): EngineBgShellRegistration | null;
-export declare function detectEngineBgShellDetach(toolName: string, rawInput: unknown, structured: unknown, outputText: string | undefined): EngineBgShellRegistration | null;
+export declare function detectEngineBgShellReceipt(toolName: string, rawInput: unknown, outputText: string | undefined, structured?: unknown, toolUseId?: string): EngineBgShellRegistration | null;
+export declare function detectEngineBgShellDetach(toolName: string, rawInput: unknown, structured: unknown, outputText: string | undefined, toolUseId?: string): EngineBgShellRegistration | null;
 export declare function todoWriteToolUseResult(rawInput: unknown, oldTodos: unknown[], isError: boolean): {
     toolUseResult: unknown;
     isError: boolean;