larkin 0.3.3 → 0.4.2

package/dist/agent/inbox-projection.cjs

@@ -1,22 +1,118 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUNTIME_REDELIVERY_TARGET = exports.RUNTIME_REMINDER_TARGET = void 0;
+exports.isCanonicalInboxTarget = isCanonicalInboxTarget;
 exports.targetKeyOfInboxEnvelope = targetKeyOfInboxEnvelope;
 exports.projectInboxEnvelope = projectInboxEnvelope;
 exports.targetOfInboxEnvelope = targetOfInboxEnvelope;
 exports.projectInboxEvents = projectInboxEvents;
 exports.projectInboxCheck = projectInboxCheck;
+exports.RUNTIME_REMINDER_TARGET = "runtime:reminder";
+exports.RUNTIME_REDELIVERY_TARGET = "runtime:redelivery";
+const CHAT_TARGET_PREFIX = "chat:";
+const THREAD_TARGET_PREFIX = "thread:";
+const DOCUMENT_COMMENT_TARGET_PREFIX = "document-comment:";
+const REMINDER_MESSAGE_PREFIX = "rem_";
+const REDELIVERY_MESSAGE_PREFIX = "redeliver_";
+function hasNonemptySuffix(value, prefix) {
+    return value.startsWith(prefix) && value.length > prefix.length;
+}
+function internalTargetOfInboxEnvelope(envelope) {
+    const messageId = typeof envelope.message_id === "string" ? envelope.message_id : "";
+    const reminderKind = envelope.kind === "reminder";
+    const redeliveryKind = envelope.kind === "redelivery";
+    const reminderMarker = messageId.startsWith(REMINDER_MESSAGE_PREFIX);
+    const redeliveryMarker = messageId.startsWith(REDELIVERY_MESSAGE_PREFIX);
+    const reminderId = hasNonemptySuffix(messageId, REMINDER_MESSAGE_PREFIX);
+    const redeliveryId = hasNonemptySuffix(messageId, REDELIVERY_MESSAGE_PREFIX);
+    const hasInternalMarker = reminderKind || redeliveryKind || reminderMarker || redeliveryMarker;
+    if (!hasInternalMarker)
+        return null;
+    if (reminderKind && reminderId && !redeliveryKind && !redeliveryMarker)
+        return exports.RUNTIME_REMINDER_TARGET;
+    if (redeliveryKind && redeliveryId && !reminderKind && !reminderMarker)
+        return exports.RUNTIME_REDELIVERY_TARGET;
+    throw new Error(`Inbox internal source requires matching kind and message_id prefix; received kind=${JSON.stringify(envelope.kind ?? null)} message_id=${JSON.stringify(envelope.message_id ?? null)}`);
+}
+function isChatTarget(target) {
+    return hasNonemptySuffix(target, CHAT_TARGET_PREFIX);
+}
+function isThreadTarget(target) {
+    return hasNonemptySuffix(target, THREAD_TARGET_PREFIX);
+}
+function isDocumentCommentTarget(target) {
+    return hasNonemptySuffix(target, DOCUMENT_COMMENT_TARGET_PREFIX);
+}
+function isCanonicalInboxTarget(target) {
+    return isChatTarget(target)
+        || isThreadTarget(target)
+        || target === exports.RUNTIME_REMINDER_TARGET
+        || target === exports.RUNTIME_REDELIVERY_TARGET
+        || isDocumentCommentTarget(target);
+}
+function invalidTarget(target) {
+    return new Error(`Invalid canonical Inbox target ${JSON.stringify(target)}; expected chat:<nonempty>, thread:<nonempty>, runtime:reminder, runtime:redelivery, or document-comment:<nonempty>`);
+}
+function optionalLocator(envelope, key) {
+    const value = envelope[key];
+    if (value === undefined || value === null || value === "")
+        return "";
+    if (typeof value !== "string")
+        throw new Error(`Inbox ${key} must be a string when present; received ${JSON.stringify(value)}`);
+    return value;
+}
 function targetKeyOfInboxEnvelope(envelope) {
     if (!envelope)
-        return "runtime:unknown";
-    if (envelope.kind === "document_comment" && typeof envelope.target === "string" && envelope.target) {
-        return envelope.target;
+        throw new Error("Inbox envelope is required to derive a canonical target");
+    const internalTarget = internalTargetOfInboxEnvelope(envelope);
+    const chatId = optionalLocator(envelope, "chat_id");
+    const threadId = optionalLocator(envelope, "thread_id");
+    if (threadId && !chatId) {
+        throw new Error(`Inbox thread locator requires nonempty chat_id and thread_id; received chat_id=${JSON.stringify(chatId)} thread_id=${JSON.stringify(threadId)}`);
     }
-    if (typeof envelope.chat_id === "string" && envelope.chat_id) {
-        return typeof envelope.thread_id === "string" && envelope.thread_id
-            ? `thread:${envelope.chat_id}:${envelope.thread_id}`
-            : `chat:${envelope.chat_id}`;
+    const locatorTarget = chatId ? (threadId ? `thread:${chatId}:${threadId}` : `chat:${chatId}`) : null;
+    const hasExplicitTarget = Object.prototype.hasOwnProperty.call(envelope, "target");
+    if (hasExplicitTarget) {
+        if (typeof envelope.target !== "string" || envelope.target.length === 0)
+            throw invalidTarget(String(envelope.target));
+        const target = envelope.target;
+        if (!isCanonicalInboxTarget(target))
+            throw invalidTarget(target);
+        if (isChatTarget(target) || isThreadTarget(target)) {
+            if (internalTarget || envelope.kind === "document_comment")
+                throw new Error(`Inbox chat/thread target conflicts with source kind/message_id`);
+            if (locatorTarget && locatorTarget !== target) {
+                throw new Error(`Inbox chat/thread target conflicts with locator target ${JSON.stringify(locatorTarget)}`);
+            }
+            return target;
+        }
+        if (target === exports.RUNTIME_REMINDER_TARGET || target === exports.RUNTIME_REDELIVERY_TARGET) {
+            if (locatorTarget)
+                throw new Error(`Inbox runtime target cannot carry chat_id/thread_id locators`);
+            if (internalTarget !== target)
+                throw new Error(`Inbox target ${target} requires exact matching kind and message_id prefix`);
+            return target;
+        }
+        if (isDocumentCommentTarget(target)) {
+            if (envelope.kind !== "document_comment" || internalTarget)
+                throw new Error(`Inbox document-comment target requires kind=document_comment and no internal source`);
+            if (locatorTarget)
+                throw new Error(`Inbox document-comment target cannot carry chat_id/thread_id locators`);
+            return target;
+        }
+        throw invalidTarget(target);
     }
-    return targetOfInboxEnvelope(envelope) || "runtime:system";
+    if (envelope.kind === "document_comment") {
+        throw new Error("Inbox document_comment requires an explicit document-comment:<nonempty> target");
+    }
+    if (locatorTarget) {
+        if (internalTarget)
+            throw new Error(`Inbox internal source cannot be derived as a chat/thread target`);
+        return locatorTarget;
+    }
+    if (internalTarget)
+        throw new Error(`Inbox internal source requires an explicit ${internalTarget} target`);
+    throw new Error(`Inbox envelope has no canonical target locator (message_id=${JSON.stringify(envelope.message_id ?? null)}, kind=${JSON.stringify(envelope.kind ?? null)})`);
 }
 /** Enrich the durable local Inbox without changing the canonical Runtime envelope. */
 function projectInboxEnvelope(canonical, locators) {
@@ -32,22 +128,14 @@ function projectInboxEnvelope(canonical, locators) {
         content: locators.content !== undefined ? locators.content : (typeof canonical.content === "string" ? canonical.content : ""),
     };
 }
-/** Preserve the target/thread format consumed by the existing Agent CLI. */
+/** Return an allowlisted canonical target when the envelope is locatable. */
 function targetOfInboxEnvelope(envelope) {
-    if (!envelope)
-        return null;
-    if (envelope.kind === "document_comment") {
-        return typeof envelope.target === "string" && envelope.target ? envelope.target : null;
+    try {
+        return targetKeyOfInboxEnvelope(envelope);
     }
-    if (envelope.channel_type === "thread" && envelope.parent_channel_name) {
-        const base = envelope.parent_channel_type === "dm"
-            ? `dm:@${String(envelope.parent_channel_name)}`
-            : `#${String(envelope.parent_channel_name)}`;
-        return `${base}:${String(envelope.channel_name || "").slice(0, 8)}`;
+    catch {
+        return null;
     }
-    return envelope.channel_type === "dm"
-        ? `dm:@${String(envelope.channel_name)}`
-        : `#${String(envelope.channel_name)}`;
 }
 /** Project persisted inbox envelopes into the exact agentApi events response data shape. */
 function projectInboxEvents(envelopes) {
@@ -56,7 +144,7 @@ function projectInboxEvents(envelopes) {
         events: envelopes,
         last_seen_msgId: last ? (last.message_id || null) : null,
         last_seen_seq: last ? (last.seq ?? null) : null,
-        reply_target: targetOfInboxEnvelope(last),
+        reply_target: last ? targetKeyOfInboxEnvelope(last) : null,
         pending_notice_ids: [],
         wake_reason: null,
         has_more: false,
@@ -64,9 +152,12 @@ function projectInboxEvents(envelopes) {
 }
 /** Bounded, content-light and deterministic projection for the read-only check command. */
 function projectInboxCheck(envelopes, onlyTarget) {
+    if (onlyTarget && !isCanonicalInboxTarget(onlyTarget)) {
+        throw new Error(`Invalid canonical Inbox check target ${JSON.stringify(onlyTarget)}`);
+    }
     const byTarget = new Map();
     for (const envelope of envelopes) {
-        const target = typeof envelope.target === "string" && envelope.target ? envelope.target : targetKeyOfInboxEnvelope(envelope);
+        const target = targetKeyOfInboxEnvelope(envelope);
         if (onlyTarget && onlyTarget !== target)
             continue;
         const rows = byTarget.get(target) ?? [];

package/dist/agent/inbox-projection.mjs

@@ -1,15 +1,109 @@
+export const RUNTIME_REMINDER_TARGET = "runtime:reminder";
+export const RUNTIME_REDELIVERY_TARGET = "runtime:redelivery";
+const CHAT_TARGET_PREFIX = "chat:";
+const THREAD_TARGET_PREFIX = "thread:";
+const DOCUMENT_COMMENT_TARGET_PREFIX = "document-comment:";
+const REMINDER_MESSAGE_PREFIX = "rem_";
+const REDELIVERY_MESSAGE_PREFIX = "redeliver_";
+function hasNonemptySuffix(value, prefix) {
+    return value.startsWith(prefix) && value.length > prefix.length;
+}
+function internalTargetOfInboxEnvelope(envelope) {
+    const messageId = typeof envelope.message_id === "string" ? envelope.message_id : "";
+    const reminderKind = envelope.kind === "reminder";
+    const redeliveryKind = envelope.kind === "redelivery";
+    const reminderMarker = messageId.startsWith(REMINDER_MESSAGE_PREFIX);
+    const redeliveryMarker = messageId.startsWith(REDELIVERY_MESSAGE_PREFIX);
+    const reminderId = hasNonemptySuffix(messageId, REMINDER_MESSAGE_PREFIX);
+    const redeliveryId = hasNonemptySuffix(messageId, REDELIVERY_MESSAGE_PREFIX);
+    const hasInternalMarker = reminderKind || redeliveryKind || reminderMarker || redeliveryMarker;
+    if (!hasInternalMarker)
+        return null;
+    if (reminderKind && reminderId && !redeliveryKind && !redeliveryMarker)
+        return RUNTIME_REMINDER_TARGET;
+    if (redeliveryKind && redeliveryId && !reminderKind && !reminderMarker)
+        return RUNTIME_REDELIVERY_TARGET;
+    throw new Error(`Inbox internal source requires matching kind and message_id prefix; received kind=${JSON.stringify(envelope.kind ?? null)} message_id=${JSON.stringify(envelope.message_id ?? null)}`);
+}
+function isChatTarget(target) {
+    return hasNonemptySuffix(target, CHAT_TARGET_PREFIX);
+}
+function isThreadTarget(target) {
+    return hasNonemptySuffix(target, THREAD_TARGET_PREFIX);
+}
+function isDocumentCommentTarget(target) {
+    return hasNonemptySuffix(target, DOCUMENT_COMMENT_TARGET_PREFIX);
+}
+export function isCanonicalInboxTarget(target) {
+    return isChatTarget(target)
+        || isThreadTarget(target)
+        || target === RUNTIME_REMINDER_TARGET
+        || target === RUNTIME_REDELIVERY_TARGET
+        || isDocumentCommentTarget(target);
+}
+function invalidTarget(target) {
+    return new Error(`Invalid canonical Inbox target ${JSON.stringify(target)}; expected chat:<nonempty>, thread:<nonempty>, runtime:reminder, runtime:redelivery, or document-comment:<nonempty>`);
+}
+function optionalLocator(envelope, key) {
+    const value = envelope[key];
+    if (value === undefined || value === null || value === "")
+        return "";
+    if (typeof value !== "string")
+        throw new Error(`Inbox ${key} must be a string when present; received ${JSON.stringify(value)}`);
+    return value;
+}
 export function targetKeyOfInboxEnvelope(envelope) {
     if (!envelope)
-        return "runtime:unknown";
-    if (envelope.kind === "document_comment" && typeof envelope.target === "string" && envelope.target) {
-        return envelope.target;
+        throw new Error("Inbox envelope is required to derive a canonical target");
+    const internalTarget = internalTargetOfInboxEnvelope(envelope);
+    const chatId = optionalLocator(envelope, "chat_id");
+    const threadId = optionalLocator(envelope, "thread_id");
+    if (threadId && !chatId) {
+        throw new Error(`Inbox thread locator requires nonempty chat_id and thread_id; received chat_id=${JSON.stringify(chatId)} thread_id=${JSON.stringify(threadId)}`);
     }
-    if (typeof envelope.chat_id === "string" && envelope.chat_id) {
-        return typeof envelope.thread_id === "string" && envelope.thread_id
-            ? `thread:${envelope.chat_id}:${envelope.thread_id}`
-            : `chat:${envelope.chat_id}`;
+    const locatorTarget = chatId ? (threadId ? `thread:${chatId}:${threadId}` : `chat:${chatId}`) : null;
+    const hasExplicitTarget = Object.prototype.hasOwnProperty.call(envelope, "target");
+    if (hasExplicitTarget) {
+        if (typeof envelope.target !== "string" || envelope.target.length === 0)
+            throw invalidTarget(String(envelope.target));
+        const target = envelope.target;
+        if (!isCanonicalInboxTarget(target))
+            throw invalidTarget(target);
+        if (isChatTarget(target) || isThreadTarget(target)) {
+            if (internalTarget || envelope.kind === "document_comment")
+                throw new Error(`Inbox chat/thread target conflicts with source kind/message_id`);
+            if (locatorTarget && locatorTarget !== target) {
+                throw new Error(`Inbox chat/thread target conflicts with locator target ${JSON.stringify(locatorTarget)}`);
+            }
+            return target;
+        }
+        if (target === RUNTIME_REMINDER_TARGET || target === RUNTIME_REDELIVERY_TARGET) {
+            if (locatorTarget)
+                throw new Error(`Inbox runtime target cannot carry chat_id/thread_id locators`);
+            if (internalTarget !== target)
+                throw new Error(`Inbox target ${target} requires exact matching kind and message_id prefix`);
+            return target;
+        }
+        if (isDocumentCommentTarget(target)) {
+            if (envelope.kind !== "document_comment" || internalTarget)
+                throw new Error(`Inbox document-comment target requires kind=document_comment and no internal source`);
+            if (locatorTarget)
+                throw new Error(`Inbox document-comment target cannot carry chat_id/thread_id locators`);
+            return target;
+        }
+        throw invalidTarget(target);
     }
-    return targetOfInboxEnvelope(envelope) || "runtime:system";
+    if (envelope.kind === "document_comment") {
+        throw new Error("Inbox document_comment requires an explicit document-comment:<nonempty> target");
+    }
+    if (locatorTarget) {
+        if (internalTarget)
+            throw new Error(`Inbox internal source cannot be derived as a chat/thread target`);
+        return locatorTarget;
+    }
+    if (internalTarget)
+        throw new Error(`Inbox internal source requires an explicit ${internalTarget} target`);
+    throw new Error(`Inbox envelope has no canonical target locator (message_id=${JSON.stringify(envelope.message_id ?? null)}, kind=${JSON.stringify(envelope.kind ?? null)})`);
 }
 /** Enrich the durable local Inbox without changing the canonical Runtime envelope. */
 export function projectInboxEnvelope(canonical, locators) {
@@ -25,22 +119,14 @@ export function projectInboxEnvelope(canonical, locators) {
         content: locators.content !== undefined ? locators.content : (typeof canonical.content === "string" ? canonical.content : ""),
     };
 }
-/** Preserve the target/thread format consumed by the existing Agent CLI. */
+/** Return an allowlisted canonical target when the envelope is locatable. */
 export function targetOfInboxEnvelope(envelope) {
-    if (!envelope)
-        return null;
-    if (envelope.kind === "document_comment") {
-        return typeof envelope.target === "string" && envelope.target ? envelope.target : null;
+    try {
+        return targetKeyOfInboxEnvelope(envelope);
     }
-    if (envelope.channel_type === "thread" && envelope.parent_channel_name) {
-        const base = envelope.parent_channel_type === "dm"
-            ? `dm:@${String(envelope.parent_channel_name)}`
-            : `#${String(envelope.parent_channel_name)}`;
-        return `${base}:${String(envelope.channel_name || "").slice(0, 8)}`;
+    catch {
+        return null;
     }
-    return envelope.channel_type === "dm"
-        ? `dm:@${String(envelope.channel_name)}`
-        : `#${String(envelope.channel_name)}`;
 }
 /** Project persisted inbox envelopes into the exact agentApi events response data shape. */
 export function projectInboxEvents(envelopes) {
@@ -49,7 +135,7 @@ export function projectInboxEvents(envelopes) {
         events: envelopes,
         last_seen_msgId: last ? (last.message_id || null) : null,
         last_seen_seq: last ? (last.seq ?? null) : null,
-        reply_target: targetOfInboxEnvelope(last),
+        reply_target: last ? targetKeyOfInboxEnvelope(last) : null,
         pending_notice_ids: [],
         wake_reason: null,
         has_more: false,
@@ -57,9 +143,12 @@ export function projectInboxEvents(envelopes) {
 }
 /** Bounded, content-light and deterministic projection for the read-only check command. */
 export function projectInboxCheck(envelopes, onlyTarget) {
+    if (onlyTarget && !isCanonicalInboxTarget(onlyTarget)) {
+        throw new Error(`Invalid canonical Inbox check target ${JSON.stringify(onlyTarget)}`);
+    }
     const byTarget = new Map();
     for (const envelope of envelopes) {
-        const target = typeof envelope.target === "string" && envelope.target ? envelope.target : targetKeyOfInboxEnvelope(envelope);
+        const target = targetKeyOfInboxEnvelope(envelope);
         if (onlyTarget && onlyTarget !== target)
             continue;
         const rows = byTarget.get(target) ?? [];

package/dist/app/cli.mjs

@@ -77,7 +77,8 @@ Examples:
 
 Credentials, internal paths, serverId, activeAgent, and raw config are never exposed here.`,
     session: `Usage: larkin session reset --agent <App ID> --json [--wait-ready <seconds>]
-Atomically replace one idle, zero-backlog Agent Runtime session through authenticated local control.`,
+       larkin session recover --agent <App ID> --reason context-overflow --json [--wait-ready <seconds>]
+Reset replaces one idle, zero-backlog Runtime session. Recover is an explicit operator-only context-window recovery that preserves and replays canonical Inbox deliveries.`,
     "pi-auth": `Usage: larkin pi-auth status [--agent <App ID>] [--json]
        larkin pi-auth logout <provider> [--agent <App ID>]
 Show non-sensitive official Pi credential metadata or remove one target provider credential.`,
@@ -124,6 +125,7 @@ Usage: larkin <command>
   chats            List known chats; use free/strict <oc_id> to configure mention requirements
   config           Inspect effective config/source, edit mention inheritance, or explicitly apply runtime changes
   session reset    Replace one idle, zero-backlog Agent Runtime session for a fresh scenario
+  session recover  Explicitly recover a context-overflowed session and replay retained Inbox deliveries
   pi-auth          Show non-sensitive built-in Pi auth status or logout one provider
   comment reply    Reply to the exact cloud-document comment bound by a polled Inbox message
   telemetry        Inspect, export, import, or flush the durable OpenTelemetry trace queue

package/dist/app/local-control.mjs

@@ -15,6 +15,48 @@ const AGENT_ID = /^cli_[A-Za-z0-9]+$/;
 const OPERATION_ID = /^[A-Za-z0-9_-]{8,128}$/;
 const AUTHORIZATION = /^[A-Za-z0-9_-]{43,128}$/;
 const UNIX_SOCKET_PATH_MAX_BYTES = process.platform === "darwin" ? 103 : 107;
+function recoveryErrorText(code) {
+    switch (code) {
+        case "unknown_agent": return "unknown Agent";
+        case "agent_busy": return "Agent is not idle";
+        case "channel_unavailable": return "Runtime channel is unavailable";
+        case "channel_reconnecting": return "Runtime channel is reconnecting";
+        case "runtime_unavailable": return "Runtime readiness is unavailable";
+        case "recovery_unavailable": return "context-overflow recovery is unavailable";
+        case "recovery_staged_not_committed": return "context-overflow recovery was staged but not committed";
+        case "state_persistence_failed": return "context-overflow recovery committed but state persistence failed";
+        case "recovery_timeout": return "context-overflow recovery committed but readiness did not converge";
+        case "recovery_refused": return "context-overflow recovery was refused";
+        default: return "context-overflow recovery failed";
+    }
+}
+function sanitizeRecoveryReadiness(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const candidate = value;
+    if (!["codex", "claude", "pi"].includes(String(candidate.runtime))
+        || !["missing", "unauthenticated", "unavailable", "incompatible", "ready"].includes(String(candidate.state)))
+        return undefined;
+    const runtime = candidate.runtime;
+    const state = candidate.state;
+    return { runtime, state,
+        ...(state === "ready" ? {} : { reason: `Runtime readiness is ${state}.`, nextAction: "Inspect Runtime/provider configuration, then retry." }) };
+}
+function sanitizeSessionRecoveryResponse(response, agentId) {
+    const code = typeof response.code === "string" && /^[a-z][a-z0-9_]{0,63}$/.test(response.code) ? response.code : undefined;
+    return {
+        ok: response.ok === true, agentId, ...(code ? { code } : {}),
+        ...(code || response.error ? { error: recoveryErrorText(code) } : {}),
+        recoveryCommitted: response.recoveryCommitted === true, generationChanged: response.generationChanged === true,
+        sessionChanged: response.sessionChanged === true, turns: 0, runtimeReady: response.runtimeReady === true,
+        channelConnected: response.channelConnected === true, reconnecting: response.reconnecting === true,
+        pendingCount: Math.max(0, Number(response.pendingCount) || 0), rearmedCount: Math.max(0, Number(response.rearmedCount) || 0),
+        replayStatus: ["scheduled", "pending", "consumed", "not_started"].includes(response.replayStatus) ? response.replayStatus : "not_started",
+        remainingPendingCount: Math.max(0, Number(response.remainingPendingCount) || 0),
+        readyForFreshScenario: response.readyForFreshScenario === true, inboundObserved: false,
+        ...(sanitizeRecoveryReadiness(response.readiness) ? { readiness: sanitizeRecoveryReadiness(response.readiness) } : {}),
+    };
+}
 function socketPathsFit(root) {
     if (isWindows)
         return true; // Windows named-pipe socket paths use a much larger limit
@@ -92,7 +134,7 @@ function parseRequest(line) {
         throw new Error("invalid agent control request");
     }
     if (value.operation === "session-reset") {
-        if (value.waitReadyMs !== undefined && (!Number.isSafeInteger(value.waitReadyMs) || value.waitReadyMs < 0 || value.waitReadyMs > 300_000)) {
+        if (value.waitReadyMs !== undefined && (typeof value.waitReadyMs !== "number" || !Number.isSafeInteger(value.waitReadyMs) || value.waitReadyMs < 0 || value.waitReadyMs > 300_000)) {
             throw new Error("invalid session reset waitReadyMs");
         }
         if (Object.keys(value).some((key) => !["agentId", "authorization", "operation", "waitReadyMs"].includes(key))) {
@@ -100,6 +142,17 @@ function parseRequest(line) {
         }
         return value;
     }
+    if (value.operation === "session-recover") {
+        if (value.reason !== "context-overflow")
+            throw new Error("session recovery requires reason=context-overflow");
+        if (value.waitReadyMs !== undefined && (typeof value.waitReadyMs !== "number" || !Number.isSafeInteger(value.waitReadyMs) || value.waitReadyMs < 0 || value.waitReadyMs > 300_000)) {
+            throw new Error("invalid session recovery waitReadyMs");
+        }
+        if (Object.keys(value).some((key) => !["agentId", "authorization", "operation", "reason", "waitReadyMs"].includes(key))) {
+            throw new Error("session recovery control request 包含未知字段");
+        }
+        return value;
+    }
     if (value.operation !== undefined || !OPERATION_ID.test(String(value.operationId || ""))) {
         throw new Error("invalid agent upsert request");
     }
@@ -498,13 +551,14 @@ export function createSupervisorControlServer({ larkinHome, authorityToken, ensu
         },
     };
 }
-export function createAgentControlServer({ larkinHome, authorityToken, upsert, resetSession, maxRememberedOperations = 256, }) {
+export function createAgentControlServer({ larkinHome, authorityToken, upsert, resetSession, recoverSession, maxRememberedOperations = 256, }) {
     let socket = "";
     let socketRoot = "";
     let socketIdentity = null;
     const completed = new Map();
     const inFlight = new Map();
     const resetInFlight = new Map();
+    const recoveryInFlight = new Map();
     const agentQueues = new Map();
     const upsertConflict = (operationId, agentId) => ({
         ok: false, operationId, agentId, code: "operation_conflict", error: "operationId 已绑定其他 Agent 或操作",
@@ -564,6 +618,52 @@ export function createAgentControlServer({ larkinHome, authorityToken, upsert, r
                             return;
                         }
                         if ("operation" in request) {
+                            if (request.operation === "session-recover") {
+                                const recoveryRequest = request;
+                                let operation = recoveryInFlight.get(recoveryRequest.agentId);
+                                if (!operation) {
+                                    const executeRecovery = async () => {
+                                        try {
+                                            if (!recoverSession)
+                                                throw new Error("session recovery control unavailable");
+                                            const result = await recoverSession({ agentId: recoveryRequest.agentId, reason: recoveryRequest.reason,
+                                                waitReadyMs: recoveryRequest.waitReadyMs ?? 30_000 });
+                                            return sanitizeSessionRecoveryResponse(result, recoveryRequest.agentId);
+                                        }
+                                        catch (error) {
+                                            const code = typeof error.code === "string"
+                                                ? String(error.code)
+                                                : error instanceof RuntimePrerequisiteError && error.readiness.state === "unavailable"
+                                                    ? "runtime_unavailable" : "recovery_refused";
+                                            const projection = error;
+                                            return { ok: false, agentId: recoveryRequest.agentId, code,
+                                                error: recoveryErrorText(code), recoveryCommitted: false,
+                                                generationChanged: false, sessionChanged: false, turns: Math.max(0, Number(projection.turns) || 0),
+                                                runtimeReady: projection.runtimeReady === true, channelConnected: projection.channelConnected === true,
+                                                reconnecting: projection.reconnecting === true, pendingCount: Math.max(0, Number(projection.pendingCount) || 0),
+                                                rearmedCount: Math.max(0, Number(projection.rearmedCount) || 0), replayStatus: "not_started",
+                                                remainingPendingCount: Math.max(0, Number(projection.remainingPendingCount) || 0),
+                                                readyForFreshScenario: false, inboundObserved: false,
+                                                ...(error instanceof RuntimePrerequisiteError ? { readiness: sanitizeRecoveryReadiness(error.readiness) } : {}) };
+                                        }
+                                    };
+                                    const prior = agentQueues.get(recoveryRequest.agentId) ?? Promise.resolve();
+                                    const executing = prior.catch(() => { }).then(executeRecovery);
+                                    let queued;
+                                    queued = executing.finally(() => {
+                                        if (agentQueues.get(recoveryRequest.agentId) === queued)
+                                            agentQueues.delete(recoveryRequest.agentId);
+                                        if (recoveryInFlight.get(recoveryRequest.agentId) === queued)
+                                            recoveryInFlight.delete(recoveryRequest.agentId);
+                                    });
+                                    agentQueues.set(recoveryRequest.agentId, queued);
+                                    recoveryInFlight.set(recoveryRequest.agentId, queued);
+                                    operation = queued;
+                                }
+                                const response = await operation;
+                                connection.end(`${JSON.stringify(response)}\n`);
+                                return;
+                            }
                             const resetRequest = request;
                             let operation = resetInFlight.get(resetRequest.agentId);
                             if (!operation) {
@@ -776,6 +876,12 @@ export async function requestSessionReset({ larkinHome, agentId, waitReadyMs = 3
         request: { operation: "session-reset", agentId, waitReadyMs },
     });
 }
+export async function requestSessionRecovery({ larkinHome, agentId, reason = "context-overflow", waitReadyMs = 30_000, }) {
+    return requestAgentControl({
+        larkinHome, timeoutMs: Math.max(1_000, waitReadyMs + 1_000),
+        request: { operation: "session-recover", agentId, reason, waitReadyMs },
+    });
+}
 export function cleanupStaleAgentControlSocket(larkinHome, expectedToken) {
     const authority = secureAuthority(larkinHome);
     if (!sameSecret(authority.token, expectedToken))

package/dist/app/runtime-process.mjs

@@ -104,6 +104,10 @@ export async function main(env = process.env, overrides = {}) {
             const result = await hostShell.resetSession(request.agentId, request.waitReadyMs);
             return { ok: result.readyForFreshScenario, agentId: request.agentId, ...result };
         },
+        async recoverSession(request) {
+            const result = await hostShell.recoverSession(request.agentId, request.reason, request.waitReadyMs);
+            return { ok: result.recoveryCommitted, agentId: request.agentId, ...result };
+        },
     });
     await controlServer.start();
     await markConfigAppliedAfterRuntimeReady(env, hostShell.agents, hostShell.start());