@sema-agent/client-core 0.94.0 → 0.96.0

package/dist/resumeRefusalCopy.d.ts

@@ -1,4 +1,4 @@
-import { RESUME_CONTEXT_UNAVAILABLE } from './engineErrorCodes.js';
+import { RESUME_CONTEXT_UNAVAILABLE, CHECKPOINT_UNSUPPORTED_VERSION, CHECKPOINT_WALLTIME_AXIS_RETIRED, CHECKPOINT_CONFIG_REFUSED } from './engineErrorCodes.js';
 export declare const RESUME_REFUSAL_CODES: readonly string[];
 export interface ResumeRefusalDetail {
     code: string;
@@ -50,6 +50,8 @@ export declare function parkedResumeStartupContent(detail: ParkedResumeStartupDe
 export interface CheckpointUnsupportedVersionDetail {
     code: 'checkpoint.unsupported_version';
     retriable: true;
+    writerVersion?: string;
+    readerVersion?: string;
 }
 export declare function checkpointUnsupportedVersionFromError(err: unknown): CheckpointUnsupportedVersionDetail | null;
 export type CheckpointUnsupportedParkKind = 'tool_approval' | 'plan_review' | 'resource_park' | 'wake' | 'workflow_host';
@@ -58,3 +60,18 @@ export interface CheckpointUnsupportedVersionContext {
     readonly runId?: string;
 }
 export declare function checkpointUnsupportedVersionContent(detail: CheckpointUnsupportedVersionDetail, ctx?: CheckpointUnsupportedVersionContext): string;
+export type RefusedParkCode = typeof CHECKPOINT_UNSUPPORTED_VERSION | typeof CHECKPOINT_WALLTIME_AXIS_RETIRED | typeof CHECKPOINT_CONFIG_REFUSED;
+export interface RefusedParkFacts {
+    readonly code: RefusedParkCode;
+    readonly field?: string;
+    readonly stillPending?: boolean;
+}
+export declare function refusedParkFromError(failure: unknown): RefusedParkFacts | null;
+export interface RefusedParkContentInput {
+    readonly what: string;
+    readonly facts: RefusedParkFacts;
+    readonly lane: 'interactive' | 'print';
+    readonly runId?: string;
+}
+export declare function refusedParkContent(input: RefusedParkContentInput): string;
+export declare function refusedParkBlockedContent(taskId: string, lane?: 'interactive' | 'print'): string;

package/dist/resumeRefusalCopy.js

@@ -1,7 +1,8 @@
-import { readErrorNumber, readErrorString } from './wireFailureShape.js';
+import { readBlockedBy, readErrorNumber, readErrorString } from './wireFailureShape.js';
 import { readOwnDataNonEmptyString } from './ownKey.js';
-import { RESUME_CONTEXT_UNAVAILABLE, RESUME_PLACEMENT_MISMATCH, RESUME_PREFLIGHT_REJECTED, RESUME_POLICY_FOLD_CODE, PARKED_RESUME_STARTUP_FAILED, isStatusDerivedCoarseCode, RESUME_SESSION_NOT_FOUND, REQUEST_FIELD_CONFLICT, CHECKPOINT_UNSUPPORTED_VERSION, refusalSaysStillPending, } from './engineErrorCodes.js';
+import { RESUME_CONTEXT_UNAVAILABLE, RESUME_PLACEMENT_MISMATCH, RESUME_PREFLIGHT_REJECTED, RESUME_POLICY_FOLD_CODE, PARKED_RESUME_STARTUP_FAILED, isStatusDerivedCoarseCode, RESUME_SESSION_NOT_FOUND, REQUEST_FIELD_CONFLICT, CHECKPOINT_UNSUPPORTED_VERSION, CHECKPOINT_WALLTIME_AXIS_RETIRED, CHECKPOINT_CONFIG_REFUSED, isRefusedParkCode, refusalSaysStillPending, refusalRetriableReading, } from './engineErrorCodes.js';
 import { capForDisplay } from './fleetTaskDesc.js';
+import { engineVersionTier } from './supportFloor.js';
 import { resumeRetryLaterFromError } from './wireErrorTriage.js';
 export const RESUME_REFUSAL_CODES = Object.freeze([
     RESUME_PLACEMENT_MISMATCH,
@@ -54,22 +55,7 @@ export function resumePolicyBlockFromError(err) {
     }
     if (outer !== RESUME_POLICY_FOLD_CODE)
         return null;
-    const judge = (v) => ({
-        blockedBy: typeof v === 'string' && v.length > 0 ? { kind: 'named', code: v } : { kind: 'unreadable' },
-    });
-    try {
-        const top = o['blockedBy'];
-        if (top !== undefined)
-            return judge(top);
-        const extra = o['extra'];
-        if (typeof extra === 'object' && extra !== null && !Array.isArray(extra) && Object.hasOwn(extra, 'blockedBy')) {
-            return judge(extra['blockedBy']);
-        }
-        return { blockedBy: { kind: 'absent' } };
-    }
-    catch {
-        return { blockedBy: { kind: 'unreadable' } };
-    }
+    return { blockedBy: readBlockedBy(o) };
 }
 export function resumePolicyBlockContent(detail) {
     const b = detail.blockedBy;
@@ -87,10 +73,9 @@ export function resumePolicyBlockContent(detail) {
     ].join(' · ');
 }
 export { resumeReopenFromError, resumeReopenContent } from './hitl/suspendedReopen.js';
-const RESUME_SESSION_NOT_FOUND_TAIL = `(${RESUME_SESSION_NOT_FOUND})`;
 const REQUIRE_EXISTING_BY_STATUS = new Map([
-    [404, Object.freeze({ form: 'session_not_found', code: RESUME_SESSION_NOT_FOUND, coarse: 'not_found.resource' })],
-    [422, Object.freeze({ form: 'session_id_missing', code: REQUEST_FIELD_CONFLICT, coarse: 'request.unprocessable' })],
+    [404, Object.freeze({ form: 'session_not_found', code: RESUME_SESSION_NOT_FOUND })],
+    [422, Object.freeze({ form: 'session_id_missing', code: REQUEST_FIELD_CONFLICT })],
 ]);
 export function requireExistingSessionRefusalFromError(err) {
     if (typeof err !== 'object' || err === null)
@@ -101,15 +86,7 @@ export function requireExistingSessionRefusalFromError(err) {
         const byStatus = typeof status === 'number' ? REQUIRE_EXISTING_BY_STATUS.get(status) : undefined;
         if (byStatus === undefined)
             return null;
-        const code = o['errorCode'];
-        if (code === byStatus.code)
-            return Object.freeze({ code: RESUME_SESSION_NOT_FOUND, form: byStatus.form });
-        if (code !== byStatus.coarse)
-            return null;
-        const message = o['message'];
-        return typeof message === 'string' && message.endsWith(RESUME_SESSION_NOT_FOUND_TAIL)
-            ? Object.freeze({ code: RESUME_SESSION_NOT_FOUND, form: byStatus.form })
-            : null;
+        return o['errorCode'] === byStatus.code ? Object.freeze({ code: RESUME_SESSION_NOT_FOUND, form: byStatus.form }) : null;
     }
     catch {
         return null;
@@ -221,7 +198,15 @@ export function checkpointUnsupportedVersionFromError(err) {
     }
     if (code !== CHECKPOINT_UNSUPPORTED_VERSION || !refusalSaysStillPending(err))
         return null;
-    return { code: CHECKPOINT_UNSUPPORTED_VERSION, retriable: true };
+    const writerVersion = readErrorString(err, 'writerVersion');
+    const readerVersion = readErrorString(err, 'readerVersion');
+    const versions = writerVersion !== undefined && writerVersion !== '' && readerVersion !== undefined && readerVersion !== '' ? { writerVersion, readerVersion } : {};
+    return { code: CHECKPOINT_UNSUPPORTED_VERSION, retriable: true, ...versions };
+}
+function writerEngineIsNewer(writer, reader) {
+    if (engineVersionTier(writer) === 'unknown' || engineVersionTier(reader) !== 'engine')
+        return false;
+    return engineVersionTier(reader, writer) === 'legacy';
 }
 function checkpointUnsupportedHasRun(kind) {
     switch (kind) {
@@ -240,7 +225,23 @@ const CHECKPOINT_UNSUPPORTED_WHAT = 'This server cannot continue this parked wor
 const CHECKPOINT_UNSUPPORTED_STILL_WAITING = 'Nothing was decided or resumed and the parked work is still waiting, but sending the same request again will not by itself continue it';
 const CHECKPOINT_UNSUPPORTED_DRAIN = " — whoever operates this deployment can find such parked work before an upgrade with the server's pre-upgrade drain check";
 export function checkpointUnsupportedVersionContent(detail, ctx) {
-    void detail;
+    let writer;
+    let reader;
+    try {
+        writer = detail.writerVersion;
+        reader = detail.readerVersion;
+    }
+    catch {
+        writer = undefined;
+        reader = undefined;
+    }
+    if (writerEngineIsNewer(writer, reader)) {
+        return [
+            `This parked work was stored by a newer engine version (${String(writer)}) than this engine (${String(reader)})`,
+            CHECKPOINT_UNSUPPORTED_STILL_WAITING,
+            `Continue it on an engine at version ${String(writer)} or newer`,
+        ].join(' · ');
+    }
     let kind;
     let runId;
     try {
@@ -266,3 +267,97 @@ export function checkpointUnsupportedVersionContent(detail, ctx) {
     }
     return [CHECKPOINT_UNSUPPORTED_WHAT, CHECKPOINT_UNSUPPORTED_STILL_WAITING, outlet + CHECKPOINT_UNSUPPORTED_DRAIN].join(' · ');
 }
+const REFUSED_PARK_FIELD_TOKEN = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+export function refusedParkFromError(failure) {
+    if (typeof failure !== 'object' || failure === null)
+        return null;
+    let code;
+    let status;
+    try {
+        code = failure.errorCode;
+        status = failure.status;
+    }
+    catch {
+        return null;
+    }
+    if (typeof code !== 'string' || !isRefusedParkCode(code))
+        return null;
+    if (status !== undefined && status !== 409)
+        return null;
+    const reading = refusalRetriableReading(failure);
+    const stillPending = reading === true ? true : status === 409 && reading === false ? false : undefined;
+    const rawField = code === CHECKPOINT_CONFIG_REFUSED ? readErrorString(failure, 'field') : undefined;
+    const field = rawField !== undefined && REFUSED_PARK_FIELD_TOKEN.test(rawField) ? rawField : undefined;
+    return Object.freeze({
+        code,
+        ...(field !== undefined ? { field } : {}),
+        ...(stillPending !== undefined ? { stillPending } : {}),
+    });
+}
+function refusedParkShownRunId(runId) {
+    return typeof runId === 'string' && /^[A-Za-z0-9._:-]{1,128}$/.test(runId) ? runId : undefined;
+}
+function refusedParkWhy(code, field) {
+    switch (code) {
+        case CHECKPOINT_WALLTIME_AXIS_RETIRED:
+            return 'its run carries a wall-clock time allowance, which this engine version no longer enforces';
+        case CHECKPOINT_CONFIG_REFUSED:
+            return field === 'inheritedGate'
+                ? 'the permission-mode setting it was parked with can no longer be read'
+                : 'the engine refuses the task configuration it was parked with';
+        default:
+            return 'it was parked under conditions this engine version does not support (for example, by an earlier engine version)';
+    }
+}
+export function refusedParkContent(input) {
+    let what;
+    let lane;
+    let runId;
+    let rawCode;
+    let field;
+    let stillPending;
+    try {
+        what = input.what;
+        lane = input.lane;
+        runId = input.runId;
+    }
+    catch {
+        what = lane = runId = undefined;
+    }
+    try {
+        const facts = input.facts;
+        rawCode = facts.code;
+        field = facts.field;
+        stillPending = facts.stillPending;
+    }
+    catch {
+        rawCode = field = stillPending = undefined;
+    }
+    const code = rawCode === CHECKPOINT_WALLTIME_AXIS_RETIRED || rawCode === CHECKPOINT_CONFIG_REFUSED ? rawCode : CHECKPOINT_UNSUPPORTED_VERSION;
+    const shownWhat = typeof what === 'string' && what !== '' ? capForDisplay(what, 40) : 'parked step';
+    const why = refusedParkWhy(code, typeof field === 'string' ? field : undefined);
+    const shownRun = refusedParkShownRunId(runId);
+    const head = `This ${shownWhat} cannot be resumed by this engine version: ${why}. The same refusal comes back every time, so ` +
+        `answering it again will not help (nothing was decided and nothing was resumed).`;
+    const configMayReturn = code === CHECKPOINT_CONFIG_REFUSED && field !== 'inheritedGate' ? ' If that configuration is restored, the same answer can go through again.' : '';
+    if (lane === 'print') {
+        if (stillPending === false) {
+            return `${head} The engine ended that run (${code}); submit the work again as a new task.`;
+        }
+        const cancel = `POST /v1/runs/${shownRun ?? '<run id>'}/cancel`;
+        return `${head}${configMayReturn} The parked run still holds this session (${code}): cancel it (${cancel}), then submit the work again as a new task.`;
+    }
+    if (stillPending === false) {
+        return `${head} The engine ended that parked run, so this conversation is free: send the work again as a new message.`;
+    }
+    return `${head}${configMayReturn} The parked run keeps this conversation busy until it is cancelled.`;
+}
+export function refusedParkBlockedContent(taskId, lane = 'interactive') {
+    const runId = refusedParkShownRunId(taskId);
+    const head = `sema will not put the card for run ${runId ?? '<unknown>'} back on screen by itself: this engine version refuses to resume it.`;
+    if (lane === 'print') {
+        return `${head} Cancel the run (POST /v1/runs/${runId ?? '<run id>'}/cancel) and submit the work again as a new task.`;
+    }
+    return (`${head} To free this conversation, send a message to bring the card back and answer it — sema then offers to cancel ` +
+        `that run, after which you can send the work again as a new message.`);
+}

package/dist/retryStatus.d.ts

@@ -6,6 +6,8 @@ export type RetryStatus = {
     errClass?: BrainRetryErrClass | (string & {});
     retryAtMs?: number;
     errorStatus?: number;
+    providerCondition?: string;
+    providerConditionSource?: string;
     elapsedMs?: number;
     timeoutMs?: number;
     detail?: string;
@@ -17,6 +19,8 @@ export type RetryStatus = {
     errClass?: BrainRetryErrClass | (string & {});
     retryAtMs?: number;
     errorStatus?: number;
+    providerCondition?: string;
+    providerConditionSource?: string;
     terminal?: true;
     error: RetryStatusErrorPayload;
     elapsedMs?: number;
@@ -29,6 +33,8 @@ export type RetryStatus = {
     errClass?: BrainRetryErrClass | (string & {});
     retryAtMs?: number;
     errorStatus?: number;
+    providerCondition?: string;
+    providerConditionSource?: string;
     elapsedMs?: number;
     timeoutMs?: number;
     terminal?: never;
@@ -60,7 +66,9 @@ export interface BrainStatusPayload {
     errClass?: BrainRetryErrClass | (string & {});
     elapsedMs?: number;
     timeoutMs?: number;
+    providerCondition?: string;
+    providerConditionSource?: string;
 }
-export declare const BRAIN_STATUS_PAYLOAD_KEYS: readonly ["phase", "detail", "retryInSec", "retryInMs", "attempt", "maxRetries", "errClass", "retryAtMs", "errorStatus", "elapsedMs", "timeoutMs"];
+export declare const BRAIN_STATUS_PAYLOAD_KEYS: readonly ["phase", "detail", "retryInSec", "retryInMs", "attempt", "maxRetries", "errClass", "retryAtMs", "errorStatus", "elapsedMs", "timeoutMs", "providerCondition", "providerConditionSource"];
 export declare function mapBrainStatusToRetry(p: BrainStatusPayload, nowMs: number): RetryStatus | null;
 export {};

package/dist/retryStatus.js

@@ -20,6 +20,8 @@ export const BRAIN_STATUS_PAYLOAD_KEYS = [
     'errorStatus',
     'elapsedMs',
     'timeoutMs',
+    'providerCondition',
+    'providerConditionSource',
 ];
 const _brainStatusKeyPin = [true, true];
 void _brainStatusKeyPin;
@@ -33,6 +35,10 @@ export function mapBrainStatusToRetry(p, nowMs) {
     const cause = typeof p.errClass === 'string' && p.errClass.length > 0 ? { errClass: p.errClass } : {};
     const producerTiming = typeof p.retryAtMs === 'number' ? { retryAtMs: p.retryAtMs } : {};
     const failureStatus = typeof p.errorStatus === 'number' ? { errorStatus: p.errorStatus } : {};
+    const providerJudged = {
+        ...(typeof p.providerCondition === 'string' && p.providerCondition.length > 0 ? { providerCondition: p.providerCondition } : {}),
+        ...(typeof p.providerConditionSource === 'string' && p.providerConditionSource.length > 0 ? { providerConditionSource: p.providerConditionSource } : {}),
+    };
     const saneMs = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : undefined;
     const elapsedMs = saneMs(p.elapsedMs);
     const timeoutMs = saneMs(p.timeoutMs);
@@ -40,9 +46,10 @@ export function mapBrainStatusToRetry(p, nowMs) {
         ...(elapsedMs !== undefined ? { elapsedMs } : {}),
         ...(timeoutMs !== undefined ? { timeoutMs } : {}),
     };
-    const stalledDetail = typeof p.detail === 'string' && p.detail.length > 0 ? { detail: p.detail } : {};
+    const stalledShown = typeof p.detail === 'string' && p.detail.length > 0 ? displayUntrusted(p.detail) : '';
+    const stalledDetail = stalledShown.length > 0 ? { detail: stalledShown } : {};
     const shown = (absent) => (typeof p.detail === 'string' ? displayUntrusted(p.detail) : absent);
-    const extra = { ...counts, ...cause, ...producerTiming, ...failureStatus, ...waitProgress };
+    const extra = { ...counts, ...cause, ...producerTiming, ...failureStatus, ...providerJudged, ...waitProgress };
     switch (p.phase) {
         case 'recovered':
             return null;

package/dist/rewindArchiveCapability.d.ts

@@ -1,24 +1,15 @@
-export type RewindArchiveBit = 'on' | 'off' | 'not_reported' | 'malformed';
-export type RewindArchiveReading = {
-    kind: 'unobserved';
-} | {
-    kind: 'present';
-    conversationAnchor: RewindArchiveBit;
-    forkRestore: RewindArchiveBit;
-    codeOnly: RewindArchiveBit;
-    restoreFilesEpoch: RewindArchiveBit;
-};
+import { type RewindArchiveReading, type RewindCodeArchive } from './rewindArchiveReading.js';
+import type { RewindMode } from './rewindWireCaps.js';
+export { projectRewindArchiveCapability, rewindConversationAvailability } from './rewindArchiveReading.js';
+export type { RewindArchiveBit, RewindArchiveReading, RewindCodeArchive } from './rewindArchiveReading.js';
 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 engineRewindRefusedNow(option: RewindMode, reading?: RewindArchiveReading): boolean;
 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

@@ -1,56 +1,13 @@
 import { engineWireTarget } from './engineWireTarget.js';
-import { createEngineCapReader } from './engineCapReader.js';
-import { _wireConversationRewindJudge } from './toolHistoryMismatch.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) {
-    try {
-        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),
-        };
-    }
-    catch {
-        return undefined;
-    }
-}
-const reader = createEngineCapReader({
-    name: 'rewindArchive',
-    project: projectRewindArchiveCapability,
-    makeUnobserved: () => ({ kind: 'unobserved' }),
-});
+import { resetRewindArchiveReader, rewindArchiveReadingAt, rewindConversationAvailability, } from './rewindArchiveReading.js';
+export { projectRewindArchiveCapability, rewindConversationAvailability } from './rewindArchiveReading.js';
 export function noteEngineCapsForRewindArchive(baseUrl, caps, opts) {
-    _wireConversationRewindJudge(conversationRewindJudge);
-    reader.note(baseUrl, caps, opts);
-}
-function conversationRewindJudge(engineBaseUrl) {
-    return rewindConversationAvailability(observedRewindArchive(engineBaseUrl));
+    void baseUrl;
+    void caps;
+    void opts;
 }
 export function observedRewindArchive(baseUrl = engineWireTarget()?.baseUrl) {
-    return reader.observed(baseUrl);
+    return rewindArchiveReadingAt(baseUrl);
 }
 export function rewindCodeArchiveAvailability(reading, mode) {
     if (reading.kind !== 'present')
@@ -87,14 +44,17 @@ export function rewindArchiveDoctorDetail(reading, mode) {
             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 engineRewindRefusedNow(option, reading = observedRewindArchive()) {
+    switch (option) {
+        case 'both':
+            return rewindCodeArchiveAvailability(reading, 'both') === 'unavailable';
+        case 'code':
+            return rewindCodeArchiveAvailability(reading, 'code') === 'unavailable';
+        case 'conversation':
+            return rewindConversationAvailability(reading) === 'unavailable';
+        default:
+            return false;
+    }
 }
 export function rewindConversationDoctorDetail(reading) {
     const lane = 'rewind to a message';
@@ -127,9 +87,6 @@ export function rewindRestoreFilesEpochDetail(reading) {
             return 'the restore-files epoch bit is reported in an unreadable shape, so a rewind with code restore built from this reading leaves the key out and moves the conversation only';
     }
 }
-export function forgetRewindArchiveReading(baseUrl) {
-    reader.forget(baseUrl);
-}
 export function __resetRewindArchiveReadingsForTests() {
-    reader.__resetForTests();
+    resetRewindArchiveReader();
 }

package/dist/rewindArchiveReading.d.ts

@@ -0,0 +1,15 @@
+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 RewindCodeArchive = 'available' | 'unavailable' | 'unknown';
+export declare function projectRewindArchiveCapability(caps: unknown): RewindArchiveReading | undefined;
+export declare function rewindArchiveReadingAt(baseUrl: string | undefined): RewindArchiveReading;
+export declare function resetRewindArchiveReader(): void;
+export declare function rewindConversationAvailability(reading: RewindArchiveReading): RewindCodeArchive;

package/dist/rewindArchiveReading.js

@@ -0,0 +1,56 @@
+import { createEngineCapReader } from './engineCapReader.js';
+import { ownDataField } from './ownKey.js';
+const CAPS_KEYS = {
+    conversationAnchor: 'resumeAt',
+    forkRestore: 'rewindFiles',
+    codeOnly: 'rewindFilesTo',
+    restoreFilesEpoch: 'restoreFiles',
+};
+const _capsKeyPin = true;
+void _capsKeyPin;
+function bitOf(caps, key) {
+    const v = ownDataField(caps, key);
+    if (v === undefined)
+        return 'not_reported';
+    if (v === true)
+        return 'on';
+    if (v === false)
+        return 'off';
+    return 'malformed';
+}
+export function projectRewindArchiveCapability(caps) {
+    try {
+        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),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+const reader = createEngineCapReader({
+    name: 'rewindArchive',
+    project: projectRewindArchiveCapability,
+    makeUnobserved: () => ({ kind: 'unobserved' }),
+});
+export function rewindArchiveReadingAt(baseUrl) {
+    return reader.observed(baseUrl);
+}
+export function resetRewindArchiveReader() {
+    reader.__resetForTests();
+}
+export function rewindConversationAvailability(reading) {
+    if (reading.kind !== 'present')
+        return 'unknown';
+    if (reading.conversationAnchor === 'on')
+        return 'available';
+    if (reading.conversationAnchor === 'off')
+        return 'unavailable';
+    return 'unknown';
+}

package/dist/rewindEngineAction.d.ts

@@ -0,0 +1,21 @@
+import { type RewindArchiveReading } from './rewindArchiveCapability.js';
+import { type RewindMode, type SeamRewindSpec } from './rewindWireCaps.js';
+export type RewindRestoreOption = RewindMode | 'summarize' | 'summarize_up_to' | 'nevermind';
+export type RewindTargetPosition = 'root' | 'after-root' | 'unknown';
+export interface RewindTargetResolution {
+    readonly position: RewindTargetPosition;
+    readonly targetEntryId?: string;
+    readonly anchorUnresolved?: true;
+}
+export type RewindEngineNoneReason = 'not-an-engine-rewind' | 'no-engine-turn-to-rewind' | 'unresolved';
+export type RewindEngineAction = {
+    readonly kind: 'none';
+    readonly reason: RewindEngineNoneReason;
+} | {
+    readonly kind: 'arm';
+    readonly spec: SeamRewindSpec;
+} | {
+    readonly kind: 'reopen';
+};
+export declare function decideRewindEngineAction(option: RewindRestoreOption, resolved: RewindTargetResolution, reading?: RewindArchiveReading): RewindEngineAction;
+export declare function previewEngineRewind(option: RewindRestoreOption, resolved: RewindTargetResolution, reading?: RewindArchiveReading): RewindEngineAction['kind'];

package/dist/rewindEngineAction.js

@@ -0,0 +1,36 @@
+import { observedRewindArchive } from './rewindArchiveCapability.js';
+import { REWIND_MODES, rewindSpecForMode } from './rewindWireCaps.js';
+import { readOwnDataNonEmptyString, readOwnDataValue } from './ownKey.js';
+function modeOfOption(option) {
+    return REWIND_MODES.includes(option) ? option : undefined;
+}
+function carriesResumeAt(mode) {
+    return rewindSpecForMode(mode, 'x').resumeAt !== undefined;
+}
+function positionOf(resolved) {
+    const p = readOwnDataValue(resolved, 'position');
+    return p === 'root' || p === 'after-root' ? p : 'unknown';
+}
+export function decideRewindEngineAction(option, resolved, reading = observedRewindArchive()) {
+    const mode = modeOfOption(option);
+    if (mode === undefined)
+        return { kind: 'none', reason: 'not-an-engine-rewind' };
+    const position = positionOf(resolved);
+    const targetEntryId = readOwnDataNonEmptyString(resolved, 'targetEntryId');
+    if (!carriesResumeAt(mode)) {
+        if (targetEntryId !== undefined)
+            return { kind: 'arm', spec: rewindSpecForMode(mode, targetEntryId, reading) };
+        const unresolved = position === 'unknown' || readOwnDataValue(resolved, 'anchorUnresolved') === true;
+        return { kind: 'none', reason: unresolved ? 'unresolved' : 'no-engine-turn-to-rewind' };
+    }
+    if (position === 'root')
+        return { kind: 'reopen' };
+    if (position === 'unknown')
+        return { kind: 'none', reason: 'unresolved' };
+    return targetEntryId !== undefined
+        ? { kind: 'arm', spec: rewindSpecForMode(mode, targetEntryId, reading) }
+        : { kind: 'none', reason: 'no-engine-turn-to-rewind' };
+}
+export function previewEngineRewind(option, resolved, reading = observedRewindArchive()) {
+    return decideRewindEngineAction(option, resolved, reading).kind;
+}

package/dist/rewindWireCaps.d.ts

@@ -5,6 +5,7 @@ export interface SeamRewindSpec {
     restoreFiles?: boolean;
     rewindFilesTo?: string;
 }
-export type RewindMode = 'both' | 'conversation' | 'code';
+export declare const REWIND_MODES: readonly ["both", "conversation", "code"];
+export type RewindMode = (typeof REWIND_MODES)[number];
 export declare function rewindSpecForMode(mode: RewindMode, targetEntryId: string, reading?: RewindArchiveReading): SeamRewindSpec;
 export declare function projectRewind(pending: SeamRewindSpec | undefined): SeamRewindSpec;

package/dist/rewindWireCaps.js

@@ -1,3 +1,4 @@
+export const REWIND_MODES = Object.freeze(['both', 'conversation', 'code']);
 function restoreFilesKeyMaySend(reading) {
     if (reading === undefined)
         return true;

package/dist/ruleCompileVerdict.d.ts

@@ -1,2 +1,10 @@
-export type RuleCompileVerdict = 'compiles' | 'refused' | 'unknown';
+export type RuleCompileVerdict = {
+    readonly kind: 'compiles';
+} | {
+    readonly kind: 'refused';
+    readonly code?: string;
+    readonly message?: string;
+} | {
+    readonly kind: 'unknown';
+};
 export declare function ruleCompileVerdict(rule: string, behavior: 'deny' | 'ask'): RuleCompileVerdict;

package/dist/ruleCompileVerdict.js

@@ -1,13 +1,38 @@
 import { validatePermissionRules } from './coreValuePorts.js';
 const RULE_COMPILE_ROOT = '/';
+function issueText(issue, key) {
+    try {
+        if (typeof issue !== 'object' || issue === null || !Object.hasOwn(issue, key))
+            return undefined;
+        const v = issue[key];
+        return typeof v === 'string' && v.length > 0 ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function firstIssue(issues) {
+    try {
+        return issues[0];
+    }
+    catch {
+        return undefined;
+    }
+}
 export function ruleCompileVerdict(rule, behavior) {
+    let issues;
     try {
-        const issues = validatePermissionRules([{ rule, behavior }], { pathBases: { root: RULE_COMPILE_ROOT } });
+        issues = validatePermissionRules([{ rule, behavior }], { pathBases: { root: RULE_COMPILE_ROOT } });
         if (!Array.isArray(issues))
-            return 'unknown';
-        return issues.length === 0 ? 'compiles' : 'refused';
+            return { kind: 'unknown' };
+        if (issues.length === 0)
+            return { kind: 'compiles' };
     }
     catch {
-        return 'unknown';
+        return { kind: 'unknown' };
     }
+    const issue = firstIssue(issues);
+    const code = issueText(issue, 'code');
+    const message = issueText(issue, 'message');
+    return { kind: 'refused', ...(code !== undefined ? { code } : {}), ...(message !== undefined ? { message } : {}) };
 }