@sema-agent/client-core 0.100.0 → 0.102.0

package/dist/supportFloor.js

@@ -51,3 +51,10 @@ export function engineSupportFloorEffective(floor) {
 export function coreVersionTier(version, floor) {
     return judgeAgainst(version, SUPPORT_FLOOR.core, floor, 'coreVersionTier').tier;
 }
+export function compareReleaseVersions(a, b) {
+    const ta = releaseTriple(a);
+    const tb = releaseTriple(b);
+    if (ta === undefined || tb === undefined)
+        return undefined;
+    return compareTriple(ta, tb);
+}

package/dist/terminationIntent.d.ts

@@ -0,0 +1,55 @@
+import type { UiLanguage } from './env/uiLanguage.js';
+export declare const TERMINATION_INTENT_TTL_MS = 60000;
+export declare const TERMINATION_INTENT_WEAK_SOURCE = "esc-abort";
+export declare const INTERRUPTED_SETTLE_BUDGET_MS = 10000;
+export declare const INTERRUPTED_SETTLE_POLL_MS = 1000;
+export type TerminationIntentSource = string;
+export interface TerminationIntentSnapshot {
+    readonly source: TerminationIntentSource;
+    readonly at: number;
+    readonly abortAt: number | null;
+}
+export interface TerminationIntentLedgerOptions {
+    readonly now: () => number;
+    readonly ttlMs?: number;
+    readonly exemptAbortReasons?: readonly string[];
+}
+export interface TerminationIntentLedger {
+    record(taskId: string | null | undefined, source: TerminationIntentSource): number;
+    snapshot(taskId: string | null | undefined): TerminationIntentSnapshot | null;
+    restoreIf(taskId: string | null | undefined, version: number, snapshot: TerminationIntentSnapshot | null): boolean;
+    rollbackIf(taskId: string | null | undefined, version: number, prior: TerminationIntentSource | null): boolean;
+    rollback(taskId: string | null | undefined, prior: TerminationIntentSource | null): void;
+    wasRecentlyTerminatedByUs(taskId: string | null | undefined): boolean;
+    sourceOf(taskId: string | null | undefined): TerminationIntentSource | null;
+    armOnAbort(signal: AbortSignal | undefined, taskId: string): void;
+    forget(taskId: string | null | undefined): void;
+    size(): number;
+}
+export declare function createTerminationIntentLedger(options: TerminationIntentLedgerOptions): TerminationIntentLedger;
+export type InterruptedRunSettleVerdict = {
+    readonly kind: 'settled';
+    readonly status: string;
+} | {
+    readonly kind: 'still-running';
+    readonly waitedMs: number;
+} | {
+    readonly kind: 'parked';
+    readonly status: string;
+} | {
+    readonly kind: 'unknown';
+};
+export interface InterruptedRunRow {
+    readonly status?: string | null;
+}
+export interface InterruptedRunSettleDeps {
+    readonly getRun?: (taskId: string, opts?: {
+        signal?: AbortSignal;
+    }) => Promise<InterruptedRunRow | null>;
+    readonly signal?: AbortSignal;
+    readonly budgetMs?: number;
+    readonly intervalMs?: number;
+    readonly now?: () => number;
+}
+export declare function awaitInterruptedRunSettle(taskId: string, deps: InterruptedRunSettleDeps): Promise<InterruptedRunSettleVerdict>;
+export declare function interruptedRunSettleRow(taskId: string, verdict: InterruptedRunSettleVerdict, lang?: UiLanguage): string | null;

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/thinkingLatch.d.ts

@@ -0,0 +1,69 @@
+import type { UiLanguage } from './env/uiLanguage.js';
+import type { EffortLevelsReading } from './liveModelCatalog.js';
+import type { ThinkingTurnProjection } from './request/taskRequest.js';
+import { type LocalSessionRecord, type OkAck, type SeatCapabilityReading } from './seatContract.js';
+import { type ThinkingLatchEvent, type ThinkingLatchRowWord, type ThinkingLatchState } from './thinkingLatchWords.js';
+export type { ThinkingLatchEvent, ThinkingLatchRowWord, ThinkingLatchState } from './thinkingLatchWords.js';
+export interface ThinkingLatchStorePort {
+    read(): boolean | undefined;
+    write(stored: boolean | undefined): void;
+}
+export interface ThinkingLatchReading {
+    readonly state: ThinkingLatchState;
+    readonly why?: 'no_port' | 'never_set' | 'unreadable' | 'malformed';
+}
+export type ThinkingLatchWriteOutcome = {
+    readonly kind: 'saved';
+    readonly previous: ThinkingLatchReading;
+    readonly state: ThinkingLatchState;
+} | {
+    readonly kind: 'unchanged';
+    readonly state: ThinkingLatchState;
+} | {
+    readonly kind: 'not_saved';
+    readonly why: 'no_port' | 'bad_event';
+    readonly previous: ThinkingLatchReading;
+} | {
+    readonly kind: 'not_saved';
+    readonly why: 'write_failed';
+    readonly attempted: ThinkingLatchState;
+    readonly now: ThinkingLatchReading;
+};
+export interface ThinkingLatchView {
+    readonly state: ThinkingLatchState;
+    readonly why?: ThinkingLatchReading['why'];
+    readonly conflict?: 'seat_cannot_carry' | 'model_cannot_think';
+}
+export type ThinkingLatchCarrier = {
+    readonly kind: 'engine';
+} | {
+    readonly kind: 'seat';
+    readonly capability: SeatCapabilityReading;
+};
+export type ThinkingLatchSentenceSubject = {
+    readonly kind: 'state';
+    readonly state: ThinkingLatchState;
+} | {
+    readonly kind: 'turn';
+    readonly projection: ThinkingTurnProjection;
+} | {
+    readonly kind: 'view';
+    readonly view: ThinkingLatchView;
+    readonly carrier?: ThinkingLatchCarrier;
+    readonly model?: string;
+} | {
+    readonly kind: 'write';
+    readonly outcome: ThinkingLatchWriteOutcome;
+} | {
+    readonly kind: 'seat_ack';
+    readonly ack: OkAck;
+};
+export declare function readThinkingLatch(port: ThinkingLatchStorePort | undefined): ThinkingLatchReading;
+export declare function writeThinkingLatch(port: ThinkingLatchStorePort | undefined, event: ThinkingLatchEvent): ThinkingLatchWriteOutcome;
+export declare function thinkingLatchView(reading: ThinkingLatchReading, ctx?: {
+    readonly carrier?: ThinkingLatchCarrier;
+    readonly model?: EffortLevelsReading;
+}): ThinkingLatchView;
+export declare function thinkingLatchSentence(subject: ThinkingLatchSentenceSubject, lang?: UiLanguage): string | undefined;
+export declare function thinkingLatchRowWordOf(reading: ThinkingLatchReading): ThinkingLatchRowWord | undefined;
+export declare function readSeatThinkingLatch(record: LocalSessionRecord | undefined, capability: SeatCapabilityReading): ThinkingLatchReading;