@sema-agent/client-core 0.101.0 → 0.103.0

package/dist/sessionBackgroundHandoff.d.ts

@@ -0,0 +1,54 @@
+import type { AgentEvent } from '@sema-agent/sdk';
+import type { UiLanguage } from './env/uiLanguage.js';
+import { type BackgroundHandoffVerdict, type InteractiveEngineWire } from './sessionBackground.js';
+export declare const BACKGROUND_HANDOFF_ABORT_REASON = "background";
+export interface BackgroundHandoffRequest {
+    readonly wire: InteractiveEngineWire | undefined;
+    readonly sessionKey: string;
+    readonly onHandedOff: (reason: typeof BACKGROUND_HANDOFF_ABORT_REASON) => void;
+    readonly lang?: UiLanguage;
+}
+export type BackgroundHandoffOutcome = {
+    readonly kind: 'kept';
+    readonly verdict: Exclude<BackgroundHandoffVerdict, {
+        verdict: 'eligible';
+    }>;
+    readonly sentence: string;
+} | {
+    readonly kind: 'handed-off';
+    readonly run: BackgroundRun;
+    readonly hostNotified: boolean;
+    readonly sentence: string;
+};
+export interface BackgroundRun {
+    readonly taskId: string;
+    openFrames(signal?: AbortSignal): AsyncGenerator<AgentEvent>;
+    readonly settled: Promise<BackgroundRunSettlement>;
+    dispose(): void;
+}
+export type BackgroundRunSettlement = {
+    readonly runEnded: true;
+    readonly kind: 'completed' | 'failed' | 'cancelled' | 'parked';
+    readonly status: string;
+    readonly errorCode?: string;
+    readonly sentence: string;
+} | {
+    readonly runEnded: false;
+    readonly kind: 'observation-stopped';
+    readonly cause: 'window-exhausted' | 'disposed' | 'engine-ended';
+    readonly sentence: string;
+};
+export interface HandedOffRunRow {
+    readonly taskId: string;
+    readonly sessionKey: string;
+    readonly state: 'running' | 'ended' | 'unconfirmed';
+}
+export type HandedOffRunsReading = {
+    readonly kind: 'read';
+    readonly runs: readonly HandedOffRunRow[];
+} | {
+    readonly kind: 'unrecognized-wire';
+};
+export declare function handoffInteractiveRun(req: BackgroundHandoffRequest): BackgroundHandoffOutcome;
+export declare function handedOffRunsOf(wire: InteractiveEngineWire): HandedOffRunsReading;
+export declare function forgetHandedOffRun(wire: InteractiveEngineWire, taskId: string): boolean;

package/dist/sessionBackgroundHandoff.js

@@ -0,0 +1,321 @@
+import { msg, renderMessage } from './i18n/translate.js';
+import { abortableSleep } from './abortableSleep.js';
+import { REATTACH_WINDOW_MS, reattachBackoffMs } from './reattachWindow.js';
+import { terminalEventFromRunRow } from './headlessReconnectWire.js';
+import { RUN_CANCELLED_CODE } from './runCancelContext.js';
+import { readRunTerminal } from './runTerminal.js';
+import { readOwnDataNonEmptyString, readOwnDataValue } from './ownKey.js';
+import { backgroundHandoffSentence, judgeHandoff, ownSlotOf, wireStateOf, } from './sessionBackground.js';
+export const BACKGROUND_HANDOFF_ABORT_REASON = 'background';
+const HANDED_OFF_ENDED_CAP = 256;
+const isObj = (v) => (typeof v === 'object' && v !== null) || typeof v === 'function';
+function slot(o, key) {
+    try {
+        return readOwnDataValue(o, key);
+    }
+    catch {
+        return undefined;
+    }
+}
+function slotString(o, key) {
+    try {
+        return readOwnDataNonEmptyString(o, key);
+    }
+    catch {
+        return undefined;
+    }
+}
+function executionSettlementOf(ev) {
+    try {
+        const type = slot(ev, 'type');
+        if (type === 'failed') {
+            const code = slotString(ev, 'errorCode');
+            if (code === RUN_CANCELLED_CODE)
+                return { runEnded: true, kind: 'cancelled', status: 'failed' };
+            return { runEnded: true, kind: 'failed', status: 'failed', ...(code !== undefined ? { errorCode: code } : {}) };
+        }
+        if (type !== 'done' || slot(ev, 'replay') === true)
+            return undefined;
+        const read = readRunTerminal(slot(ev, 'result'));
+        if (read === null)
+            return { runEnded: true, kind: 'completed', status: 'completed' };
+        switch (read.kind) {
+            case 'completed':
+                return { runEnded: true, kind: 'completed', status: 'completed' };
+            case 'paused':
+                return { runEnded: true, kind: 'parked', status: read.flatStatus ?? 'paused' };
+            case 'failed':
+                if (read.code === RUN_CANCELLED_CODE)
+                    return { runEnded: true, kind: 'cancelled', status: 'failed' };
+                return { runEnded: true, kind: 'failed', status: 'failed', ...(read.code !== undefined ? { errorCode: read.code } : {}) };
+            case 'blocked':
+                return { runEnded: true, kind: 'failed', status: 'blocked', ...(read.code !== undefined ? { errorCode: read.code } : {}) };
+            case 'unknown':
+                return { runEnded: true, kind: 'failed', status: read.word ?? 'unknown', ...(read.code !== undefined ? { errorCode: read.code } : {}) };
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+function settlementSentence(s, lang) {
+    if (!s.runEnded)
+        return renderMessage(msg('session.background.settled.observationStopped'), lang);
+    switch (s.kind) {
+        case 'completed':
+            return renderMessage(msg('session.background.settled.completed'), lang);
+        case 'cancelled':
+            return renderMessage(msg('session.background.settled.cancelled'), lang);
+        case 'parked':
+            return renderMessage(msg('session.background.settled.parked'), lang);
+        case 'failed':
+            return renderMessage(msg('session.background.settled.failed', { code: s.errorCode ?? s.status }), lang);
+    }
+}
+function runRowOf(row) {
+    if (!isObj(row))
+        return null;
+    const status = slotString(row, 'status');
+    if (status === undefined)
+        return null;
+    const result = slot(row, 'result');
+    const errorCode = slotString(row, 'errorCode');
+    const error = slotString(row, 'error');
+    return {
+        status,
+        ...(result !== undefined ? { result } : {}),
+        ...(errorCode !== undefined ? { errorCode } : {}),
+        ...(error !== undefined ? { error } : {}),
+    };
+}
+async function readRunRow(state, taskId, sessionId, signal) {
+    try {
+        const row = await state.get(taskId, signal !== undefined ? { session: sessionId, signal } : { session: sessionId });
+        return runRowOf(row);
+    }
+    catch {
+        return null;
+    }
+}
+async function* framesEndedWith(error) {
+    throw error;
+}
+function trimHandedOff(state) {
+    let ended = 0;
+    for (const e of state.handedOff.values())
+        if (e.state === 'ended')
+            ended++;
+    if (ended <= HANDED_OFF_ENDED_CAP)
+        return;
+    for (const [taskId, e] of [...state.handedOff]) {
+        if (ended <= HANDED_OFF_ENDED_CAP)
+            break;
+        if (e.state !== 'ended')
+            continue;
+        state.handedOff.delete(taskId);
+        ended--;
+    }
+}
+function ledgerSeqOf(ev) {
+    const id = slotString(ev, 'id');
+    return id !== undefined && /^\d+$/.test(id) ? Number(id) : undefined;
+}
+async function pump(state, taskId, sessionId, signal, finish) {
+    let deadline = Date.now() + REATTACH_WINDOW_MS;
+    let attempt = 0;
+    let farthest = -1;
+    for (;;) {
+        if (signal.aborted)
+            return;
+        let progressed = false;
+        try {
+            const frames = state.events(taskId, { session: sessionId, signal });
+            for await (const ev of frames) {
+                if (signal.aborted)
+                    return;
+                const seq = ledgerSeqOf(ev);
+                if (seq !== undefined && seq > farthest) {
+                    farthest = seq;
+                    progressed = true;
+                }
+                const s = executionSettlementOf(ev);
+                if (s !== undefined) {
+                    finish(s);
+                    return;
+                }
+            }
+        }
+        catch {
+        }
+        if (signal.aborted)
+            return;
+        const row = await readRunRow(state, taskId, sessionId, signal);
+        if (signal.aborted)
+            return;
+        const synthesized = terminalEventFromRunRow(row);
+        const s = synthesized === null ? undefined : executionSettlementOf(synthesized);
+        if (s !== undefined) {
+            finish(s);
+            return;
+        }
+        if (progressed) {
+            deadline = Date.now() + REATTACH_WINDOW_MS;
+            attempt = 0;
+        }
+        if (Date.now() >= deadline) {
+            finish({ runEnded: false, kind: 'observation-stopped', cause: 'window-exhausted' });
+            return;
+        }
+        attempt++;
+        await abortableSleep(reattachBackoffMs(attempt), signal);
+    }
+}
+function startBackground(state, taskId, sessionKey, sessionId, lang) {
+    const controller = new AbortController();
+    let resolveSettled = () => { };
+    const settled = new Promise((resolve) => {
+        resolveSettled = resolve;
+    });
+    let done = false;
+    let reconciling = false;
+    const finish = (s) => {
+        if (done)
+            return;
+        done = true;
+        entry.state = s.runEnded ? 'ended' : 'unconfirmed';
+        controller.abort();
+        resolveSettled(Object.freeze({ ...s, sentence: settlementSentence(s, lang) }));
+        if (s.runEnded)
+            trimHandedOff(state);
+    };
+    const entry = {
+        taskId,
+        sessionKey,
+        state: 'running',
+        stop: (cause) => finish({ runEnded: false, kind: 'observation-stopped', cause }),
+        reconcile: () => {
+            if (entry.state !== 'unconfirmed' || reconciling || state.retired)
+                return;
+            reconciling = true;
+            void readRunRow(state, taskId, sessionId, undefined)
+                .then((row) => {
+                const synthesized = terminalEventFromRunRow(row);
+                const s = synthesized === null ? undefined : executionSettlementOf(synthesized);
+                if (s !== undefined && s.runEnded && entry.state === 'unconfirmed') {
+                    entry.state = 'ended';
+                    trimHandedOff(state);
+                }
+            })
+                .finally(() => {
+                reconciling = false;
+            });
+        },
+    };
+    state.handedOff.set(taskId, entry);
+    void pump(state, taskId, sessionId, controller.signal, finish).catch(() => finish({ runEnded: false, kind: 'observation-stopped', cause: 'window-exhausted' }));
+    const run = Object.freeze({
+        taskId,
+        openFrames(signal) {
+            try {
+                return state.events(taskId, signal !== undefined ? { session: sessionId, signal } : { session: sessionId });
+            }
+            catch (e) {
+                return framesEndedWith(e);
+            }
+        },
+        settled,
+        dispose() {
+            finish({ runEnded: false, kind: 'observation-stopped', cause: 'disposed' });
+        },
+    });
+    return run;
+}
+function snapshotHandoffRequest(req) {
+    if (!isObj(req))
+        return { readable: false, wire: undefined, sessionKey: undefined, onHandedOff: undefined, lang: undefined };
+    const wireSlot = ownSlotOf(req, 'wire');
+    const sessionKey = slotString(req, 'sessionKey');
+    const onHandedOff = slot(req, 'onHandedOff');
+    const lang = slot(req, 'lang');
+    return {
+        readable: sessionKey !== undefined && typeof onHandedOff === 'function',
+        wire: wireSlot.state === 'unreadable' ? {} : wireSlot.state === 'data' ? wireSlot.value : undefined,
+        sessionKey,
+        onHandedOff: typeof onHandedOff === 'function' ? onHandedOff : undefined,
+        lang: typeof lang === 'string' ? lang : undefined,
+    };
+}
+function keptOf(verdict, lang) {
+    const v = verdict.verdict === 'eligible' ? Object.freeze({ verdict: 'unknown', reason: 'unreadable-input' }) : verdict;
+    const sentence = backgroundHandoffSentence(v, lang) ?? renderMessage(msg('session.background.unknown'), lang);
+    return Object.freeze({ kind: 'kept', verdict: v, sentence });
+}
+export function handoffInteractiveRun(req) {
+    let snap;
+    try {
+        snap = snapshotHandoffRequest(req);
+    }
+    catch {
+        return keptOf(Object.freeze({ verdict: 'unknown', reason: 'unreadable-input' }), undefined);
+    }
+    const lang = snap.lang;
+    if (!snap.readable || snap.sessionKey === undefined || snap.onHandedOff === undefined) {
+        return keptOf(Object.freeze({ verdict: 'unknown', reason: 'unreadable-input' }), lang);
+    }
+    const judged = judgeHandoff({ wire: snap.wire, sessionKey: snap.sessionKey });
+    const { verdict, rec, state } = judged;
+    if (verdict.verdict !== 'eligible' || rec === undefined || state === undefined || rec.sessionId === undefined)
+        return keptOf(verdict, lang);
+    const taskId = verdict.taskId;
+    const sessionId = rec.sessionId;
+    rec.phase = 'handing-off';
+    try {
+        rec.tear(BACKGROUND_HANDOFF_ABORT_REASON);
+    }
+    catch {
+    }
+    rec.phase = 'handed-off';
+    const run = startBackground(state, taskId, snap.sessionKey, sessionId, lang);
+    let hostNotified = true;
+    try {
+        snap.onHandedOff(BACKGROUND_HANDOFF_ABORT_REASON);
+    }
+    catch {
+        hostNotified = false;
+    }
+    const sentence = renderMessage(msg(hostNotified ? 'session.background.handedOff' : 'session.background.hostNotNotified'), lang);
+    return Object.freeze({ kind: 'handed-off', run, hostNotified, sentence });
+}
+export function handedOffRunsOf(wire) {
+    try {
+        const state = wireStateOf(wire);
+        if (state === undefined)
+            return Object.freeze({ kind: 'unrecognized-wire' });
+        const runs = [];
+        for (const e of state.handedOff.values()) {
+            if (e.state === 'unconfirmed')
+                e.reconcile();
+            runs.push(Object.freeze({ taskId: e.taskId, sessionKey: e.sessionKey, state: e.state }));
+        }
+        return Object.freeze({ kind: 'read', runs: Object.freeze(runs) });
+    }
+    catch {
+        return Object.freeze({ kind: 'unrecognized-wire' });
+    }
+}
+export function forgetHandedOffRun(wire, taskId) {
+    try {
+        const state = wireStateOf(wire);
+        if (state === undefined || typeof taskId !== 'string')
+            return false;
+        const entry = state.handedOff.get(taskId);
+        if (entry === undefined)
+            return false;
+        entry.stop('disposed');
+        state.handedOff.delete(taskId);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/sessionMap.js

@@ -2,7 +2,10 @@ export function engineNamespaceKeyFor(baseUrl) {
     if (!baseUrl)
         return 'local';
     try {
-        return new URL(baseUrl).origin.toLowerCase();
+        const u = new URL(baseUrl);
+        if (!/^(?:https?|wss?|ftp):$/.test(u.protocol))
+            return baseUrl.toLowerCase();
+        return u.origin.toLowerCase() + u.pathname.replace(/\/+$/, '');
     }
     catch {
         return baseUrl.toLowerCase();

package/dist/sessionMemoryErase.js

@@ -245,7 +245,29 @@ const UNCONFIRMED_TEXT = {
     unreadable: 'Not confirmed: the result of this erase could not be read.',
 };
 const ERASED_TEXT = 'Erased: every memory entry recorded as coming from this session was erased or was already gone.';
-const PARTIAL_TEXT = 'Partly erased: some memory entries from this session were not erased yet.';
+const PARTIAL_ENTRIES_TEXT = 'Partly erased: some memory entries from this session were not erased yet.';
+const PARTIAL_UNKNOWN_TEXT = 'Partly erased: the engine reports this erase as not complete, and its receipt does not show whether memory entries or other stored records of them remain.';
+function partialCarriersText(kinds) {
+    return kinds === 1
+        ? 'Partly erased: every memory entry recorded as coming from this session was erased or was already gone, but 1 kind of stored record that refers to them was not confirmed removed, and trying again may not remove it.'
+        : `Partly erased: every memory entry recorded as coming from this session was erased or was already gone, but ${kinds} kinds of stored records that refer to them were not confirmed removed, and trying again may not remove them.`;
+}
+function partialTextOf(cause) {
+    if (cause === null)
+        return PARTIAL_UNKNOWN_TEXT;
+    switch (cause.kind) {
+        case 'entries_pending':
+            return PARTIAL_ENTRIES_TEXT;
+        case 'carriers_residual':
+            return partialCarriersText(cause.carriers.length);
+        case 'unknown':
+            return PARTIAL_UNKNOWN_TEXT;
+        default: {
+            const unreachable = cause;
+            return unreachable;
+        }
+    }
+}
 const RETRY_TEXT = {
     not_needed: 'Nothing more to do.',
     same_request_id: 'It is safe to try again with the same request id.',
@@ -414,7 +436,7 @@ export function sessionMemoryEraseOutcome(answer) {
             return { kind: 'erased', receipt: reading, text: ERASED_TEXT, retry: 'not_needed', retryText: RETRY_TEXT.not_needed };
         }
         const retry = memoryEraseReplayPosture(reading) === 'idempotent' ? 'same_request_id' : 'human_decision';
-        return { kind: 'partial', receipt: reading, text: PARTIAL_TEXT, retry, retryText: RETRY_TEXT[retry] };
+        return { kind: 'partial', receipt: reading, text: partialTextOf(reading.partialCause), retry, retryText: RETRY_TEXT[retry] };
     }
     if (status < 400)
         return unconfirmedBy('unclassified', signed, { status });

package/dist/settingsCredentialKeyPaths.js

@@ -1,4 +1,4 @@
-import { looksLikeKnownSecret, percentBoundaryReadingOf, queryCarriesCredential } from './displayUntrusted.js';
+import { configuredValueCarriesCredential, looksLikeKnownSecret, percentBoundaryReadingOf } from './displayUntrusted.js';
 const CREDENTIAL_WORDS = new Set([
     'key', 'keys', 'apikey', 'token', 'tokens', 'secret', 'secrets', 'password', 'passwd', 'pass', 'pwd', 'pin', 'otp',
     'auth', 'authorization', 'credential', 'credentials', 'cookie', 'cookies', 'session', 'private', 'cert', 'signature', 'salt',
@@ -74,27 +74,12 @@ function formEncodedCarriesCredential(value) {
         layer = next;
     }
 }
-function urlCarriesCredential(value) {
-    const text = value.trim();
-    if (!text.includes('://'))
-        return false;
-    let url;
-    try {
-        url = new URL(text);
-    }
-    catch {
-        return false;
-    }
-    if (url.username !== '' || url.password !== '')
-        return true;
-    return url.search.length > 1 && queryCarriesCredential(url.search.slice(1));
-}
 function stringCarriesCredential(value) {
     if (looksLikeKnownSecret(value) || formEncodedCarriesCredential(value))
         return true;
     let layer = value;
     for (let depth = 0;; depth++) {
-        if (urlCarriesCredential(layer))
+        if (configuredValueCarriesCredential(layer))
             return true;
         if (depth === FORM_READING_MAX_LAYERS)
             return false;

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;