@sema-agent/client-core 0.81.0 → 0.82.0

package/dist/rewindArchiveCapability.d.ts

@@ -0,0 +1,24 @@
+export type RewindArchiveBit = 'on' | 'off' | 'not_reported' | 'malformed';
+export type RewindArchiveReading = {
+    kind: 'unobserved';
+} | {
+    kind: 'present';
+    conversationAnchor: RewindArchiveBit;
+    forkRestore: RewindArchiveBit;
+    codeOnly: RewindArchiveBit;
+    restoreFilesEpoch: RewindArchiveBit;
+};
+export type RewindArchiveMode = 'both' | 'code';
+export type RewindCodeArchive = 'available' | 'unavailable' | 'unknown';
+export declare function projectRewindArchiveCapability(caps: unknown): RewindArchiveReading | undefined;
+export declare function noteEngineCapsForRewindArchive(baseUrl: string, caps: unknown, opts?: {
+    generation?: number;
+}): void;
+export declare function observedRewindArchive(baseUrl?: string | undefined): RewindArchiveReading;
+export declare function rewindCodeArchiveAvailability(reading: RewindArchiveReading, mode: RewindArchiveMode): RewindCodeArchive;
+export declare function rewindArchiveDoctorDetail(reading: RewindArchiveReading, mode: RewindArchiveMode): string;
+export declare function rewindConversationAvailability(reading: RewindArchiveReading): RewindCodeArchive;
+export declare function rewindConversationDoctorDetail(reading: RewindArchiveReading): string;
+export declare function rewindRestoreFilesEpochDetail(reading: RewindArchiveReading): string;
+export declare function forgetRewindArchiveReading(baseUrl: string | undefined): void;
+export declare function __resetRewindArchiveReadingsForTests(): void;

package/dist/rewindArchiveCapability.js

@@ -0,0 +1,125 @@
+import { engineWireTarget } from './engineWireTarget.js';
+import { createEngineCapReader } from './engineCapReader.js';
+const CAPS_KEYS = {
+    conversationAnchor: 'resumeAt',
+    forkRestore: 'rewindFiles',
+    codeOnly: 'rewindFilesTo',
+    restoreFilesEpoch: 'restoreFiles',
+};
+const _capsKeyPin = true;
+void _capsKeyPin;
+function bitOf(caps, key) {
+    if (!Object.hasOwn(caps, key))
+        return 'not_reported';
+    const v = caps[key];
+    if (v === undefined)
+        return 'not_reported';
+    if (v === true)
+        return 'on';
+    if (v === false)
+        return 'off';
+    return 'malformed';
+}
+export function projectRewindArchiveCapability(caps) {
+    if (caps === null || typeof caps !== 'object' || Array.isArray(caps))
+        return undefined;
+    return {
+        kind: 'present',
+        conversationAnchor: bitOf(caps, CAPS_KEYS.conversationAnchor),
+        forkRestore: bitOf(caps, CAPS_KEYS.forkRestore),
+        codeOnly: bitOf(caps, CAPS_KEYS.codeOnly),
+        restoreFilesEpoch: bitOf(caps, CAPS_KEYS.restoreFilesEpoch),
+    };
+}
+const reader = createEngineCapReader({
+    name: 'rewindArchive',
+    project: projectRewindArchiveCapability,
+    makeUnobserved: () => ({ kind: 'unobserved' }),
+});
+export function noteEngineCapsForRewindArchive(baseUrl, caps, opts) {
+    reader.note(baseUrl, caps, opts);
+}
+export function observedRewindArchive(baseUrl = engineWireTarget()?.baseUrl) {
+    return reader.observed(baseUrl);
+}
+export function rewindCodeArchiveAvailability(reading, mode) {
+    if (reading.kind !== 'present')
+        return 'unknown';
+    const bits = mode === 'both' ? [reading.conversationAnchor, reading.forkRestore] : [reading.codeOnly];
+    if (bits.some((b) => b === 'off'))
+        return 'unavailable';
+    if (bits.every((b) => b === 'on'))
+        return 'available';
+    return 'unknown';
+}
+export function rewindArchiveDoctorDetail(reading, mode) {
+    const lane = mode === 'both' ? 'rewind with code restore' : 'code-only rewind';
+    if (reading.kind !== 'present') {
+        return `${lane} not observed — the engine reports it on /v1/capabilities; this process has no usable capabilities reading cached for it, so whether the code archive can be restored is unknown`;
+    }
+    if (mode === 'both' && reading.conversationAnchor === 'off') {
+        return `${lane} off on this deployment (no conversation anchors) — rewinding to a message cannot run here at all, with or without the code`;
+    }
+    const bit = mode === 'both' ? reading.forkRestore : reading.codeOnly;
+    if (mode === 'both' && bit === 'on' && reading.conversationAnchor !== 'on') {
+        return `${lane}: the file history is on, but this engine does not report conversation anchors in a readable way, so whether a rewind to a message can run is unknown`;
+    }
+    switch (bit) {
+        case 'on':
+            return `${lane} on — the engine keeps a file history for this deployment and restores the tracked set on request`;
+        case 'off':
+            return mode === 'both'
+                ? `${lane} off on this deployment (no file history store) — the working tree cannot be restored here; whether the conversation alone can be rewound is a separate reading`
+                : `${lane} off on this deployment — it needs both a file history store and conversation anchors, and the engine reports at least one missing (it does not say which)`;
+        case 'not_reported':
+            return `${lane} not reported by this engine — only newer engines advertise it, so this does not say whether the code archive can be restored`;
+        case 'malformed':
+            return `${lane} reported in a shape this reader cannot read — the value is neither true nor false, so the answer is unknown, not "no"`;
+    }
+}
+export function rewindConversationAvailability(reading) {
+    if (reading.kind !== 'present')
+        return 'unknown';
+    if (reading.conversationAnchor === 'on')
+        return 'available';
+    if (reading.conversationAnchor === 'off')
+        return 'unavailable';
+    return 'unknown';
+}
+export function rewindConversationDoctorDetail(reading) {
+    const lane = 'rewind to a message';
+    if (reading.kind !== 'present') {
+        return `${lane} not observed — the engine reports conversation anchors on /v1/capabilities; this process has no usable capabilities reading cached for it, so whether the conversation can be rewound is unknown`;
+    }
+    switch (reading.conversationAnchor) {
+        case 'on':
+            return `${lane} on — this deployment keeps conversation anchors, so the conversation can be forked back to an earlier message`;
+        case 'off':
+            return `${lane} off on this deployment (no conversation anchors) — the conversation cannot be moved back to an earlier message here`;
+        case 'not_reported':
+            return `conversation anchors not reported by this engine — only newer engines advertise them, so this does not say whether the conversation can be rewound`;
+        case 'malformed':
+            return `conversation anchors reported in a shape this reader cannot read — the value is neither true nor false, so the answer is unknown, not "no"`;
+    }
+}
+export function rewindRestoreFilesEpochDetail(reading) {
+    if (reading.kind !== 'present') {
+        return 'restore-files request spelling not observed — this process has no usable capabilities reading for this engine';
+    }
+    switch (reading.restoreFilesEpoch) {
+        case 'on':
+            return 'this engine announces the restore-files request key (tracked-set restore semantics)';
+        case 'off':
+            return 'this engine does not announce the restore-files request key; the client sends it anyway because the older spelling is rejected outright by current engines';
+        case 'not_reported':
+            return 'this engine does not report the restore-files epoch bit (older engine); the client sends the current spelling regardless';
+        case 'malformed':
+            return 'the restore-files epoch bit is reported in an unreadable shape; the client sends the current spelling regardless';
+    }
+}
+export function forgetRewindArchiveReading(baseUrl) {
+    reader.forget(baseUrl);
+}
+export function __resetRewindArchiveReadingsForTests() {
+    reader.__resetForTests();
+}

package/dist/toolRoster.d.ts

@@ -38,6 +38,7 @@ export interface ToolRosterEntryView {
     contentOrigin?: string;
     contentOriginProvenance?: string;
     family?: string;
+    mountedBy?: string;
     pathTarget?: ToolRosterPathTargetView;
     renderHints?: ToolRosterRenderHintsView;
     ruleFace?: {
@@ -52,6 +53,17 @@ export interface ToolRosterView {
     entries: readonly ToolRosterEntryView[];
 }
 export declare function projectToolRoster(manifest: unknown): ToolRosterView | undefined;
+export type HandsMountedReading = {
+    kind: 'mounted';
+    rows: number;
+} | {
+    kind: 'not-mounted';
+} | {
+    kind: 'unknown';
+    why: 'no-manifest' | 'no-roster' | 'roster-unreadable' | 'mount-condition-absent';
+};
+export declare function handsMountedFromManifest(manifest: unknown): HandsMountedReading;
+export declare function handsMountedDetail(reading: HandsMountedReading): string;
 export declare function toolRosterNames(roster: ToolRosterView | undefined): readonly string[];
 export interface ToolShim {
     name: string;

package/dist/toolRoster.js

@@ -64,6 +64,7 @@ function readEntry(raw) {
             ? { contentOriginProvenance: str(o.contentOriginProvenance) }
             : {}),
         ...(str(o.family) !== undefined ? { family: str(o.family) } : {}),
+        ...(str(o.mountedBy) !== undefined ? { mountedBy: str(o.mountedBy) } : {}),
         ...(readPathTarget(o.pathTarget) !== undefined
             ? { pathTarget: readPathTarget(o.pathTarget) }
             : {}),
@@ -119,6 +120,40 @@ export function projectToolRoster(manifest) {
         return undefined;
     return readRoster(o.tools);
 }
+export function handsMountedFromManifest(manifest) {
+    const o = obj(manifest);
+    if (o === undefined)
+        return { kind: 'unknown', why: 'no-manifest' };
+    if (!('tools' in o))
+        return { kind: 'unknown', why: 'no-roster' };
+    const roster = readRoster(o.tools);
+    if (roster === undefined)
+        return { kind: 'unknown', why: 'roster-unreadable' };
+    if (roster.entries.length > 0 && roster.entries.every((e) => e.mountedBy === undefined)) {
+        return { kind: 'unknown', why: 'mount-condition-absent' };
+    }
+    const rows = roster.entries.filter((e) => e.mountedBy === 'hands').length;
+    return rows > 0 ? { kind: 'mounted', rows } : { kind: 'not-mounted' };
+}
+export function handsMountedDetail(reading) {
+    switch (reading.kind) {
+        case 'mounted':
+            return `this run was assembled with file-and-shell tools mounted (${reading.rows} of them)`;
+        case 'not-mounted':
+            return 'this leg of the run was assembled with NO built-in file-and-shell tools — the engine reports a roster and not one row was mounted by that condition, so on this leg the model had no tool of the engine\'s own for editing files or running commands (tools mounted by other conditions, such as external servers, and sub-runs delegated to other legs are not covered by this reading)';
+        case 'unknown':
+            switch (reading.why) {
+                case 'no-manifest':
+                    return 'whether this run has file-and-shell tools is unknown — no assembly manifest was observed for it';
+                case 'no-roster':
+                    return 'whether this run has file-and-shell tools is unknown — the manifest carries no tool roster (the static half never does; only an engine-minted effective manifest reports one)';
+                case 'roster-unreadable':
+                    return 'whether this run has file-and-shell tools is unknown — the tool roster could not be read in the shape this reader knows';
+                case 'mount-condition-absent':
+                    return 'whether this run has file-and-shell tools is unknown — this engine does not report which condition mounted each tool, so an empty count here would be a fact about the reader, not about the run';
+            }
+    }
+}
 export function toolRosterNames(roster) {
     return roster?.entries.map((e) => e.name) ?? [];
 }

package/dist/wireErrorTriage.d.ts

@@ -4,6 +4,7 @@ export type TurnWireErrorVerdict = {
     status: number;
     errorCode?: string;
     message: string;
+    storedRowWhere?: string;
 } | {
     kind: 'stream-ended-without-terminal';
 } | {
@@ -17,6 +18,9 @@ export type TurnWireErrorVerdict = {
 export declare function classifyTurnWireError(err: unknown): TurnWireErrorVerdict;
 export declare function isWireTransportError(err: unknown): boolean;
 export declare function isPreStreamDrainingReject(err: unknown): boolean;
+export declare function effectiveWireErrorCode(err: unknown): string | undefined;
+export declare function corruptStoredRowWhere(err: unknown): string | undefined;
+export declare function corruptStoredRowContent(where: string): string;
 export declare function isResumeAtRejection(err: unknown): boolean;
 export declare function drainingRetryDelayMs(err: unknown, attempt: number, opts?: {
     ladder?: readonly number[];

package/dist/wireErrorTriage.js

@@ -1,5 +1,6 @@
-import { readErrorNumber, readErrorStringList } from './wireFailureShape.js';
-import { DRAINING_ERROR_CODE, RESUME_AT_ERROR_CODE_PREFIX, RESUME_RETRY_LATER_CODES, RESUME_USAGE_WINDOW_EXHAUSTED, SCENARIO_NOT_ALLOWED_ERROR_CODE, } from './engineErrorCodes.js';
+import { readErrorNumber, readErrorString, readErrorStringList } from './wireFailureShape.js';
+import { capForDisplay } from './fleetTaskDesc.js';
+import { DRAINING_ERROR_CODE, RESUME_AT_ERROR_CODE_PREFIX, RESUME_POLICY_FOLD_CODE, RESUME_RETRY_LATER_CODES, RESUME_USAGE_WINDOW_EXHAUSTED, SCENARIO_NOT_ALLOWED_ERROR_CODE, } from './engineErrorCodes.js';
 export const WIRE_NETWORK_ERROR_PATTERN = /fetch failed|ECONNREFUSED|ECONNRESET|ETIMEDOUT|EAI_AGAIN|ENOTFOUND|EHOSTUNREACH|ENETUNREACH|EPIPE|socket hang up|UND_ERR|terminated|other side closed/i;
 function wireErrorDetail(err) {
     const e = err;
@@ -13,7 +14,14 @@ export function classifyTurnWireError(err) {
     if (typeof e?.status === 'number') {
         const errorCode = typeof e.errorCode === 'string' && e.errorCode.length > 0 ? e.errorCode : undefined;
         const message = typeof e.message === 'string' && e.message.length > 0 ? e.message : String(err);
-        return { kind: 'http', status: e.status, ...(errorCode !== undefined ? { errorCode } : {}), message };
+        const storedRowWhere = corruptStoredRowWhere(err);
+        return {
+            kind: 'http',
+            status: e.status,
+            ...(errorCode !== undefined ? { errorCode } : {}),
+            message,
+            ...(storedRowWhere !== undefined ? { storedRowWhere } : {}),
+        };
     }
     const errName = typeof err === 'object' && err !== null && typeof err.name === 'string'
         ? err.name
@@ -41,9 +49,35 @@ const RESUME_AT_TEXT_COMPAT = [
     { status: 404, marker: `(${RESUME_AT_ERROR_CODE_PREFIX}unknown_event)` },
     { status: 422, marker: `(${RESUME_AT_ERROR_CODE_PREFIX}no_session)` },
 ];
+export function effectiveWireErrorCode(err) {
+    if (typeof err !== 'object' || err === null)
+        return undefined;
+    let outerRaw;
+    try {
+        outerRaw = err.errorCode;
+    }
+    catch {
+        outerRaw = undefined;
+    }
+    const outer = typeof outerRaw === 'string' && outerRaw.length > 0 ? outerRaw : undefined;
+    if (outer !== RESUME_POLICY_FOLD_CODE)
+        return outer;
+    const inner = readErrorString(err, 'blockedBy');
+    return inner !== undefined && inner.length > 0 ? inner : outer;
+}
+export function corruptStoredRowWhere(err) {
+    if (effectiveWireErrorCode(err) !== 'corrupt')
+        return undefined;
+    const where = readErrorString(err, 'where');
+    return where !== undefined && where.trim().length > 0 ? where : undefined;
+}
+export function corruptStoredRowContent(where) {
+    return `The engine could not read a stored record this session needs in order to continue. The unreadable row is ${capForDisplay(where, 200)}; whoever operates this engine has to repair or remove that row before this session can continue.`;
+}
 export function isResumeAtRejection(err) {
     const e = err;
-    if (typeof e?.errorCode === 'string' && e.errorCode.startsWith(RESUME_AT_ERROR_CODE_PREFIX))
+    const code = effectiveWireErrorCode(err);
+    if (code !== undefined && code.startsWith(RESUME_AT_ERROR_CODE_PREFIX))
         return true;
     const marker = RESUME_AT_TEXT_COMPAT.find((c) => c.status === e?.status)?.marker;
     if (marker === undefined)
@@ -62,7 +96,27 @@ export function scenarioDenyFromError(err) {
     if (typeof err !== 'object' || err === null)
         return null;
     const e = err;
-    if (e.status !== 400 || e.errorCode !== SCENARIO_NOT_ALLOWED_ERROR_CODE)
+    let status;
+    try {
+        status = e.status;
+    }
+    catch {
+        return null;
+    }
+    if (status !== 400 && status !== 409)
+        return null;
+    if (status === 409) {
+        let outer;
+        try {
+            outer = e.errorCode;
+        }
+        catch {
+            return null;
+        }
+        if (outer !== RESUME_POLICY_FOLD_CODE)
+            return null;
+    }
+    if (effectiveWireErrorCode(err) !== SCENARIO_NOT_ALLOWED_ERROR_CODE)
         return null;
     const allowlist = (readErrorStringList(err, 'allowlist') ?? []).filter((x) => x.length > 0);
     return { allowlist };

package/dist/wireFailureShape.js

@@ -7,33 +7,38 @@ function readGuarded(o, key) {
     }
 }
 function readErrorSlot(obj, key, accept) {
-    const o = obj;
-    let top;
     try {
-        top = o[key];
-    }
-    catch {
-        top = undefined;
-    }
-    if (accept(top))
-        return top;
-    let extra;
-    try {
-        extra = o['extra'];
+        const o = obj;
+        let top;
+        try {
+            top = o[key];
+        }
+        catch {
+            top = undefined;
+        }
+        if (accept(top))
+            return top;
+        let extra;
+        try {
+            extra = o['extra'];
+        }
+        catch {
+            extra = undefined;
+        }
+        if (typeof extra !== 'object' || extra === null || Array.isArray(extra))
+            return undefined;
+        let fromExtra;
+        try {
+            fromExtra = Object.hasOwn(extra, key) ? extra[key] : undefined;
+        }
+        catch {
+            fromExtra = undefined;
+        }
+        return accept(fromExtra) ? fromExtra : undefined;
     }
     catch {
-        extra = undefined;
-    }
-    if (typeof extra !== 'object' || extra === null || Array.isArray(extra))
         return undefined;
-    let fromExtra;
-    try {
-        fromExtra = Object.hasOwn(extra, key) ? extra[key] : undefined;
-    }
-    catch {
-        fromExtra = undefined;
     }
-    return accept(fromExtra) ? fromExtra : undefined;
 }
 export function readErrorNumber(o, key) {
     const v = readErrorSlot(o, key, (x) => typeof x === 'number');