larkin 0.4.1 → 0.4.2

package/dist/agent/agent-state-store.mjs

@@ -5,6 +5,7 @@ import { TargetRootLayout } from "../platform/root-layout.mjs";
 import { acquireProcessLock, inspectProcess } from "../platform/process-state.mjs";
 import { isWindows } from "../platform/secure-metadata.mjs";
 import { isCanonicalInboxTarget, targetKeyOfInboxEnvelope } from "./inbox-projection.mjs";
+import { buildStrictProviderErrorInput, classifyStrictProviderError } from "../runtime/provider-error-classifier.mjs";
 const JSON_KEYS = new Set([
     "agentState", "status", "map", "replyctx", "botIdentity", "senderProfiles", "readReceipts", "pendingReact", "runtimeDeliveries", "inboxState", "freshnessState", "documentComments", "reminders", "interactions",
 ]);
@@ -160,6 +161,14 @@ function validInboxLockOwner(value) {
         && typeof owner.processStartToken === "string" && !!owner.processStartToken
         && typeof owner.nonce === "string" && /^[0-9a-f-]{36}$/i.test(owner.nonce);
 }
+export class ContextOverflowRecoveryError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ContextOverflowRecoveryError";
+    }
+}
 export class AgentStateStore {
     paths;
     boundary;
@@ -691,6 +700,189 @@ export class AgentStateStore {
             return { status: "missing", code: "canonical_inbox_row_missing" };
         });
     }
+    /**
+     * Re-arm only the durable deliveries proven to be the context-window incident.
+     * The Inbox bytes are intentionally untouched. An optional synchronous commit
+     * hook lets RuntimeHost swap its in-memory generation while this same lock is
+     * still held. If the hook fails, the ledger is restored before the lock is
+     * released. The callback also receives a guarded rollback for post-callback
+     * commit failures before retry scheduling begins.
+     */
+    rearmContextOverflow(onCommit, expected) {
+        let lockActive = true;
+        try {
+            return this.withInboxTransaction(() => {
+                let rows;
+                try {
+                    rows = this.readNdjson("inbox");
+                }
+                catch {
+                    throw new ContextOverflowRecoveryError("canonical_inbox_malformed", "canonical Inbox is malformed");
+                }
+                if (rows.length === 0)
+                    throw new ContextOverflowRecoveryError("inbox_empty", "canonical Inbox backlog is empty");
+                const messageIds = new Set();
+                for (const row of rows) {
+                    try {
+                        targetKeyOfInboxEnvelope(row);
+                    }
+                    catch {
+                        throw new ContextOverflowRecoveryError("canonical_inbox_malformed", "canonical Inbox contains a malformed row");
+                    }
+                    if (typeof row.message_id !== "string" || !row.message_id) {
+                        throw new ContextOverflowRecoveryError("canonical_inbox_malformed", "canonical Inbox row has no message identity");
+                    }
+                    if (messageIds.has(row.message_id))
+                        throw new ContextOverflowRecoveryError("duplicate_message_id", "canonical Inbox contains duplicate message identities");
+                    messageIds.add(row.message_id);
+                }
+                const ledger = this.readJson("runtimeDeliveries", { version: 1, records: [] });
+                if (!Array.isArray(ledger.records))
+                    throw new ContextOverflowRecoveryError("canonical_inbox_malformed", "Runtime delivery ledger is malformed");
+                const ledgerRecords = ledger.records;
+                const matches = new Map();
+                const deliveryIds = new Set();
+                const inputIds = new Set();
+                for (const candidate of ledger.records) {
+                    if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                        continue;
+                    const record = candidate;
+                    if (typeof record.messageId !== "string" || !messageIds.has(record.messageId))
+                        continue;
+                    if (typeof record.deliveryId !== "string" || !record.deliveryId)
+                        throw new ContextOverflowRecoveryError("delivery_missing", "a matching Runtime delivery record has no delivery identity");
+                    if (!record.input || typeof record.input !== "object" || Array.isArray(record.input)) {
+                        throw new ContextOverflowRecoveryError("delivery_identity_invalid", "a matching Runtime delivery record has no Runtime input identity");
+                    }
+                    const input = record.input;
+                    if (typeof input.inputId !== "string" || !input.inputId.trim()
+                        || typeof input.deliveryId !== "string" || input.deliveryId !== record.deliveryId) {
+                        throw new ContextOverflowRecoveryError("delivery_identity_invalid", "a matching Runtime delivery record has malformed input identity");
+                    }
+                    if (matches.has(record.messageId))
+                        throw new ContextOverflowRecoveryError("delivery_duplicate", "a canonical Inbox row maps to multiple delivery records");
+                    if (deliveryIds.has(record.deliveryId))
+                        throw new ContextOverflowRecoveryError("delivery_duplicate", "matching Runtime delivery records share a delivery identity");
+                    if (inputIds.has(input.inputId))
+                        throw new ContextOverflowRecoveryError("duplicate_input_id", "matching Runtime delivery records share an input identity");
+                    deliveryIds.add(record.deliveryId);
+                    inputIds.add(input.inputId);
+                    matches.set(record.messageId, record);
+                }
+                if (expected?.messageId && !messageIds.has(expected.messageId)) {
+                    throw new ContextOverflowRecoveryError("delivery_missing", "the expected context-overflow message is not in canonical Inbox");
+                }
+                if (expected?.messageId) {
+                    const expectedRecord = matches.get(expected.messageId);
+                    if (!expectedRecord || (expected.deliveryId && expectedRecord.deliveryId !== expected.deliveryId)
+                        || (expected.inputId && expectedRecord.input.inputId !== expected.inputId)) {
+                        throw new ContextOverflowRecoveryError("delivery_identity_invalid", "the expected context-overflow delivery identity changed");
+                    }
+                }
+                for (const messageId of messageIds) {
+                    const record = matches.get(messageId);
+                    if (!record)
+                        throw new ContextOverflowRecoveryError("delivery_missing", "a canonical Inbox row has no Runtime delivery record");
+                    if (record.status !== "error" || record.retryable === true) {
+                        throw new ContextOverflowRecoveryError("delivery_not_terminal", "a canonical Inbox row is not backed by a non-retryable terminal Runtime error");
+                    }
+                    const reasonCategory = classifyStrictProviderError(buildStrictProviderErrorInput({
+                        reason: record.reason, errorCategory: record.errorCategory,
+                    }));
+                    if (record.retryable !== false || reasonCategory !== "context_window"
+                        || (record.errorCategory !== undefined && record.errorCategory !== "context_window")) {
+                        throw new ContextOverflowRecoveryError("delivery_not_context_window", "a Runtime delivery error is not classified as context_window");
+                    }
+                }
+                for (const candidate of ledgerRecords) {
+                    if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                        continue;
+                    const record = candidate;
+                    if (typeof record.deliveryId === "string" && deliveryIds.has(record.deliveryId)
+                        && (typeof record.messageId !== "string" || !messageIds.has(record.messageId))) {
+                        throw new ContextOverflowRecoveryError("delivery_duplicate", "a matching delivery identity is also used by an unrelated Runtime delivery record");
+                    }
+                }
+                const updatedAt = new Date().toISOString();
+                const records = ledgerRecords.map((candidate) => {
+                    if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                        return candidate;
+                    const record = candidate;
+                    if (typeof record.messageId !== "string" || !messageIds.has(record.messageId))
+                        return candidate;
+                    return { ...record, status: "pending", retryable: true, updatedAt,
+                        reason: "context-window recovery rearmed the retained Inbox delivery" };
+                });
+                const committedLedger = { ...ledger, records };
+                let restored = false;
+                const restoreUnlocked = () => {
+                    if (restored)
+                        return;
+                    const current = this.readJson("runtimeDeliveries", { version: 1, records: [] });
+                    if (!Array.isArray(current.records))
+                        throw new Error("Runtime delivery rollback found a malformed ledger");
+                    const originalMatching = ledgerRecords.filter((candidate) => {
+                        if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                            return false;
+                        const record = candidate;
+                        return typeof record.messageId === "string" && messageIds.has(record.messageId);
+                    });
+                    const originalDeliveryIds = new Set(originalMatching.flatMap((candidate) => {
+                        const deliveryId = candidate.deliveryId;
+                        return typeof deliveryId === "string" ? [deliveryId] : [];
+                    }));
+                    const currentMatching = current.records.filter((candidate) => {
+                        if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                            return false;
+                        const record = candidate;
+                        return (typeof record.deliveryId === "string" && originalDeliveryIds.has(record.deliveryId))
+                            || (typeof record.messageId === "string" && messageIds.has(record.messageId));
+                    });
+                    const matchingRestored = currentMatching.length === originalMatching.length
+                        && currentMatching.every((candidate, index) => JSON.stringify(candidate) === JSON.stringify(originalMatching[index]));
+                    if (!matchingRestored) {
+                        const unrelated = current.records.filter((candidate) => {
+                            if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                                return true;
+                            const record = candidate;
+                            return !((typeof record.deliveryId === "string" && originalDeliveryIds.has(record.deliveryId))
+                                || (typeof record.messageId === "string" && messageIds.has(record.messageId)));
+                        });
+                        const restoredRecords = [...unrelated];
+                        for (const candidate of originalMatching) {
+                            const originalIndex = ledgerRecords.indexOf(candidate);
+                            restoredRecords.splice(Math.min(originalIndex, restoredRecords.length), 0, candidate);
+                        }
+                        this.writeJson("runtimeDeliveries", { ...current, records: restoredRecords });
+                    }
+                    restored = true;
+                };
+                const rollback = () => {
+                    if (lockActive)
+                        restoreUnlocked();
+                    else
+                        this.withInboxTransaction(restoreUnlocked);
+                };
+                try {
+                    this.writeJson("runtimeDeliveries", committedLedger);
+                    onCommit?.([...messageIds], rollback);
+                }
+                catch (error) {
+                    try {
+                        rollback();
+                    }
+                    catch {
+                        throw new Error("context-window recovery ledger rollback failed");
+                    }
+                    throw error;
+                }
+                return { rearmedCount: messageIds.size, remainingPendingCount: rows.length };
+            });
+        }
+        finally {
+            lockActive = false;
+        }
+    }
     /**
      * Recoverably bridge an outbox wake into the canonical Inbox. A durable
      * Runtime ledger is authoritative after the Inbox has been drained, so a

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());

package/dist/app/session-cli.mjs

@@ -1,8 +1,19 @@
 import { loadConfig } from "../platform/config.mjs";
-import { requestSessionReset } from "./local-control.mjs";
-function parseResetArguments(args) {
-    if (args[0] !== "reset")
+import { requestSessionRecovery, requestSessionReset } from "./local-control.mjs";
+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;
+    return { runtime: candidate.runtime, state: candidate.state,
+        ...(candidate.state === "ready" ? {} : { reason: `Runtime readiness is ${String(candidate.state)}.`, nextAction: "Inspect Runtime/provider configuration, then retry." }) };
+}
+function parseSessionArguments(args) {
+    if (args[0] !== "reset" && args[0] !== "recover")
         throw new Error("unsupported session subcommand");
+    const operation = args[0];
     const values = new Map();
     let json = false;
     for (let index = 1; index < args.length; index += 1) {
@@ -13,7 +24,7 @@ function parseResetArguments(args) {
             json = true;
             continue;
         }
-        if (!["--agent", "--wait-ready"].includes(token)) {
+        if (!["--agent", "--wait-ready", "--reason"].includes(token)) {
             throw new Error(token.startsWith("-") ? `unknown flag: ${token}` : `unexpected positional: ${token}`);
         }
         if (values.has(token))
@@ -32,7 +43,12 @@ function parseResetArguments(args) {
     const waitSeconds = Number(values.get("--wait-ready") ?? "30");
     if (!Number.isFinite(waitSeconds) || waitSeconds < 0 || waitSeconds > 300)
         throw new Error("--wait-ready must be 0..300 seconds");
-    return { agentId, waitReadyMs: Math.round(waitSeconds * 1000) };
+    const reason = values.get("--reason");
+    if (operation === "recover" && reason !== "context-overflow")
+        throw new Error("--reason context-overflow is required for session recover");
+    if (operation === "reset" && reason !== undefined)
+        throw new Error("--reason is only valid for session recover");
+    return { operation, agentId, waitReadyMs: Math.round(waitSeconds * 1000), ...(reason ? { reason: reason } : {}) };
 }
 export async function runSessionCli(args, env = process.env, dependencies = {}) {
     const io = dependencies.io ?? { stdout: (value) => process.stdout.write(value), stderr: (value) => process.stderr.write(value) };
@@ -42,29 +58,46 @@ export async function runSessionCli(args, env = process.env, dependencies = {})
     };
     let parsed;
     try {
-        parsed = parseResetArguments(args);
+        parsed = parseSessionArguments(args);
     }
     catch (error) {
         return fail("invalid_arguments", error instanceof Error ? error.message : String(error));
     }
     const agentId = parsed.agentId;
     if (typeof env.LARKIN_AGENT_ID === "string" && env.LARKIN_AGENT_ID.trim()) {
-        return fail("user_authority_required", "session reset is available only from a user terminal", agentId);
+        return fail("user_authority_required", parsed.operation === "reset"
+            ? "session reset is available only from a user terminal"
+            : "session recovery is available only from a user terminal", agentId);
     }
     try {
         const loaded = loadConfig(env);
-        const result = await (dependencies.request ?? requestSessionReset)({
-            larkinHome: loaded.config.larkinHome, agentId, waitReadyMs: parsed.waitReadyMs,
-        });
-        const output = {
-            ok: result.ok, agent_id: result.agentId,
-            reset_committed: result.resetCommitted, generation_changed: result.generationChanged,
-            session_changed: result.sessionChanged, turns: result.turns, runtime_ready: result.runtimeReady,
-            channel_connected: result.channelConnected, reconnecting: result.reconnecting,
-            pending_count: result.pendingCount, ready_for_fresh_scenario: result.readyForFreshScenario,
-            inbound_observed: result.inboundObserved, ...(result.code ? { code: result.code } : {}),
-            ...(result.error ? { error: result.error } : {}), ...(result.readiness ? { readiness: result.readiness } : {}),
-        };
+        const result = parsed.operation === "recover"
+            ? await (dependencies.requestRecovery ?? requestSessionRecovery)({
+                larkinHome: loaded.config.larkinHome, agentId, reason: parsed.reason, waitReadyMs: parsed.waitReadyMs,
+            })
+            : await (dependencies.request ?? requestSessionReset)({
+                larkinHome: loaded.config.larkinHome, agentId, waitReadyMs: parsed.waitReadyMs,
+            });
+        const output = "recoveryCommitted" in result
+            ? {
+                ok: result.ok, agent_id: result.agentId, recovery_committed: result.recoveryCommitted,
+                generation_changed: result.generationChanged, session_changed: result.sessionChanged, turns: result.turns,
+                runtime_ready: result.runtimeReady, channel_connected: result.channelConnected, reconnecting: result.reconnecting,
+                pending_count: result.pendingCount, rearmed_count: result.rearmedCount, replay_status: result.replayStatus,
+                remaining_pending_count: result.remainingPendingCount, ready_for_fresh_scenario: result.readyForFreshScenario,
+                inbound_observed: result.inboundObserved, ...(result.code ? { code: result.code } : {}),
+                ...(result.error ? { error: "context-overflow recovery failed" } : {}),
+                ...(sanitizeRecoveryReadiness(result.readiness) ? { readiness: sanitizeRecoveryReadiness(result.readiness) } : {}),
+            }
+            : {
+                ok: result.ok, agent_id: result.agentId,
+                reset_committed: result.resetCommitted, generation_changed: result.generationChanged,
+                session_changed: result.sessionChanged, turns: result.turns, runtime_ready: result.runtimeReady,
+                channel_connected: result.channelConnected, reconnecting: result.reconnecting,
+                pending_count: result.pendingCount, ready_for_fresh_scenario: result.readyForFreshScenario,
+                inbound_observed: result.inboundObserved, ...(result.code ? { code: result.code } : {}),
+                ...(result.error ? { error: result.error } : {}), ...(result.readiness ? { readiness: result.readiness } : {}),
+            };
         io.stdout(`${JSON.stringify(output, null, 2)}\n`);
         return result.ok ? 0 : 1;
     }
@@ -72,7 +105,9 @@ export async function runSessionCli(args, env = process.env, dependencies = {})
         const message = error instanceof Error ? error.message : String(error);
         const output = {
             ok: false, agent_id: agentId,
-            code: /timeout/i.test(message) ? "control_timeout" : "control_unavailable", error: message,
+            code: /timeout/i.test(message) ? "control_timeout" : "control_unavailable",
+            error: parsed.operation === "recover"
+                ? (/timeout/i.test(message) ? "session recovery control timed out" : "session recovery control unavailable") : message,
         };
         io.stdout(`${JSON.stringify(output, null, 2)}\n`);
         return 1;

package/dist/feishu/host-shell.cjs

@@ -1284,7 +1284,10 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
         if (message.type === "session") {
             const record = agentStates.get(agent.agentId);
             if (record && record.state.sessions[message.runtime] !== message.sessionId) {
-                record.state.sessions[message.runtime] = message.sessionId;
+                if (message.sessionId)
+                    record.state.sessions[message.runtime] = message.sessionId;
+                else
+                    delete record.state.sessions[message.runtime];
                 saveAgentState(record);
                 log(`持久化 agent=${agent.name} runtime=${message.runtime} sessionId=${message.sessionId}`);
             }
@@ -1432,6 +1435,74 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
                     : unavailable ? "reset committed but Runtime/channel readiness is unavailable"
                         : "reset committed but readiness did not converge before timeout" };
         },
+        async recoverSession(agentId, reason, waitReadyMs = 30_000) {
+            const agent = agents.find((candidate) => candidate.agentId === agentId);
+            if (!agent)
+                throw Object.assign(new Error(`未知 Agent: ${agentId}`), { code: "unknown_agent" });
+            if (reason !== "context-overflow")
+                throw Object.assign(new Error("unsupported recovery reason"), { code: "recovery_refused" });
+            if (!runtimeHost.recoverSession)
+                throw Object.assign(new Error("Runtime session recovery 尚未就绪"), { code: "recovery_unavailable" });
+            const connectionState = (status = hostState.readStatus(agent)) => {
+                const connectedAt = Date.parse(String(status.connectedAt || ""));
+                const channelConnected = Number.isFinite(connectedAt) && connectedAt >= Date.parse(daemonStartedAt) - 1000;
+                return { channelConnected, reconnecting: (0, agent_readiness_js_1.isChannelReconnecting)(status) };
+            };
+            const readinessProjection = () => {
+                const status = hostState.readStatus(agent);
+                const turns = status.session && typeof status.session === "object"
+                    ? Math.max(0, Number(status.session.turns) || 0) : 0;
+                const runtimeReady = Boolean(status.runtimeReadiness && typeof status.runtimeReadiness === "object"
+                    && status.runtimeReadiness.state === "ready");
+                const pendingCount = stateStore(agent).withInboxTransaction(() => stateStore(agent).readNdjson("inbox").length);
+                return { turns, runtimeReady, ...connectionState(status), pendingCount };
+            };
+            const initialProjection = readinessProjection();
+            if (!initialProjection.channelConnected)
+                throw Object.assign(new Error(`Agent ${agentId} channel is not connected`), { code: "channel_unavailable", ...initialProjection });
+            if (initialProjection.reconnecting)
+                throw Object.assign(new Error(`Agent ${agentId} channel is reconnecting`), { code: "channel_reconnecting", ...initialProjection });
+            let recovery;
+            try {
+                recovery = await runtimeHost.recoverSession(agentId, reason);
+            }
+            catch (error) {
+                throw Object.assign(error instanceof Error ? error : new Error(String(error)), readinessProjection());
+            }
+            const record = agentStates.get(agentId);
+            try {
+                if (record) {
+                    if (recovery.sessionId)
+                        record.state.sessions[agent.runtime] = recovery.sessionId;
+                    else
+                        delete record.state.sessions[agent.runtime];
+                    record.store.writeJson("agentState", record.state);
+                }
+            }
+            catch (error) {
+                const projection = readinessProjection();
+                return { recoveryCommitted: true, generationChanged: recovery.generationChanged, sessionChanged: recovery.sessionChanged,
+                    ...projection, rearmedCount: recovery.rearmedCount, replayStatus: "pending", remainingPendingCount: projection.pendingCount,
+                    readyForFreshScenario: false, inboundObserved: false, code: "state_persistence_failed",
+                    error: "recovery committed but Agent session state persistence failed" };
+            }
+            const deadline = Date.now() + Math.max(0, waitReadyMs);
+            let projection = readinessProjection();
+            do {
+                projection = readinessProjection();
+                if (projection.turns === 0 && projection.runtimeReady && projection.channelConnected && !projection.reconnecting)
+                    break;
+                if (Date.now() >= deadline)
+                    break;
+                await new Promise((resolve) => setTimeout(resolve, Math.min(25, Math.max(1, deadline - Date.now()))));
+            } while (true);
+            const replayStatus = projection.pendingCount === 0 ? "consumed" : "pending";
+            const ready = projection.turns === 0 && projection.runtimeReady && projection.channelConnected && !projection.reconnecting;
+            return { recoveryCommitted: true, generationChanged: recovery.generationChanged, sessionChanged: recovery.sessionChanged,
+                ...projection, rearmedCount: recovery.rearmedCount, replayStatus, remainingPendingCount: projection.pendingCount,
+                readyForFreshScenario: ready, inboundObserved: false,
+                ...(!ready ? { code: "recovery_timeout", error: "recovery committed but Runtime/channel readiness did not converge before timeout" } : {}) };
+        },
         async start() {
             try {
                 node_fs_1.default.mkdirSync(larkinHome, { recursive: true });