larkin 0.2.70

package/dist/runtime/runtime-host.cjs

@@ -0,0 +1,930 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimeSessionResetError = void 0;
+exports.createRuntimeHost = createRuntimeHost;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const agent_cli_capabilities_js_1 = require("../agent/agent-cli-capabilities.cjs");
+const api_1 = require("@opentelemetry/api");
+const runtime_readiness_js_1 = require("./runtime-readiness.cjs");
+const official_lark_cli_js_1 = require("../app/official-lark-cli.cjs");
+const agent_lark_cli_workspace_js_1 = require("../app/agent-lark-cli-workspace.cjs");
+class RuntimeSessionResetError extends Error {
+    code;
+    pendingCount;
+    constructor(code, message, pendingCount = 0) {
+        super(message);
+        this.code = code;
+        this.pendingCount = pendingCount;
+        this.name = "RuntimeSessionResetError";
+    }
+}
+exports.RuntimeSessionResetError = RuntimeSessionResetError;
+const MAX_DELIVERIES = 2048;
+const now = () => new Date().toISOString();
+const isActiveDelivery = (status) => ["pending", "submitting", "accepted"].includes(status);
+function deliveryFile(agent) {
+    return agent.config.stateDir ? node_path_1.default.join(agent.config.stateDir, "runtime-deliveries.json") : null;
+}
+function readDeliveryFile(file) {
+    if (!file)
+        return { version: 1, records: [] };
+    try {
+        const stat = node_fs_1.default.lstatSync(file);
+        if (stat.isSymbolicLink() || !stat.isFile())
+            throw new Error("delivery state is not a regular file");
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(file, "utf8"));
+        return { version: 1, records: Array.isArray(parsed.records) ? parsed.records.filter((record) => Boolean(record?.deliveryId && record?.messageId && ["pending", "submitting", "accepted", "consumed", "error"].includes(record.status))) : [] };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { version: 1, records: [] };
+        throw error;
+    }
+}
+function persist(agent) {
+    const externallyConsumed = [];
+    if (agent.stateStore) {
+        agent.stateStore.withInboxTransaction(() => {
+            const external = agent.stateStore.readJson("runtimeDeliveries", { version: 1, records: [] });
+            for (const record of external.records || []) {
+                const current = agent.records.get(record.deliveryId);
+                if (current && current.status !== "consumed" && record.status === "consumed") {
+                    agent.records.set(record.deliveryId, record);
+                    externallyConsumed.push(record);
+                }
+            }
+            const records = boundedRecords(agent);
+            agent.stateStore.writeJson("runtimeDeliveries", { version: 1, records });
+        });
+        return externallyConsumed;
+    }
+    const file = deliveryFile(agent);
+    if (!file)
+        return externallyConsumed;
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true, mode: 0o700 });
+    const existing = (() => { try {
+        return node_fs_1.default.lstatSync(file);
+    }
+    catch {
+        return null;
+    } })();
+    if (existing?.isSymbolicLink())
+        throw new Error("delivery state must not be a symlink");
+    const bounded = boundedRecords(agent);
+    const temporary = node_path_1.default.join(node_path_1.default.dirname(file), `.${node_path_1.default.basename(file)}.${process.pid}.${node_crypto_1.default.randomUUID()}.tmp`);
+    node_fs_1.default.writeFileSync(temporary, `${JSON.stringify({ version: 1, records: bounded }, null, 2)}\n`, { mode: 0o600 });
+    node_fs_1.default.renameSync(temporary, file);
+    node_fs_1.default.chmodSync(file, 0o600);
+    return externallyConsumed;
+}
+function boundedRecords(agent) {
+    const records = [...agent.records.values()]
+        .sort((left, right) => left.updatedAt.localeCompare(right.updatedAt));
+    const active = records.filter((record) => isActiveDelivery(record.status));
+    if (active.length > MAX_DELIVERIES)
+        throw new Error(`runtime delivery backlog exceeds ${MAX_DELIVERIES}`);
+    const terminal = records.filter((record) => !isActiveDelivery(record.status)).slice(-(MAX_DELIVERIES - Math.min(active.length, MAX_DELIVERIES)));
+    const bounded = [...active, ...terminal].slice(-MAX_DELIVERIES);
+    agent.records = new Map(bounded.map((record) => [record.deliveryId, record]));
+    agent.byMessage = new Map(bounded.map((record) => [record.messageId, record.deliveryId]));
+    return bounded;
+}
+function createRuntimeHost(options) {
+    const managed = new Map();
+    const listeners = new Set();
+    const log = options.log ?? (() => { });
+    const telemetry = options.telemetry;
+    const retryPolicy = {
+        baseDelayMs: options.retryPolicy?.baseDelayMs ?? 250,
+        maxDelayMs: options.retryPolicy?.maxDelayMs ?? 10_000,
+        maxAttempts: options.retryPolicy?.maxAttempts ?? 6,
+        stableWindowMs: options.retryPolicy?.stableWindowMs ?? 30_000,
+    };
+    const emit = (event) => {
+        if (event.type === "delivery")
+            telemetry?.delivery(event.agentId, event.messageId, event.status);
+        for (const listener of listeners)
+            listener(event);
+    };
+    const runtimeEnv = (config, generation) => {
+        const base = {
+            LARKIN_AGENT_ID: config.agentId,
+            ...(generation ? { LARKIN_RUNTIME_OBSERVATION_GENERATION: generation } : {}),
+            LARKIN_CONFIG_DIR: process.env.LARKIN_CONFIG_DIR,
+            LARKIN_HOME: process.env.LARKIN_HOME,
+            ...(config.piDistribution ? { LARKIN_PI_DISTRIBUTION: config.piDistribution } : {}),
+            ...(process.env.HOME ? { HOME: process.env.HOME } : {}),
+            ...(process.env.SHELL ? { SHELL: process.env.SHELL } : {}),
+            ...(process.env.ZDOTDIR ? { ZDOTDIR: process.env.ZDOTDIR } : {}),
+            ...(process.env.BASH_ENV ? { BASH_ENV: process.env.BASH_ENV } : {}),
+            PATH: [config.stateDir ? node_path_1.default.join(config.stateDir, "runtime-bin") : null, process.env.PATH].filter(Boolean).join(node_path_1.default.delimiter),
+            LARKSUITE_CLI_CONFIG_DIR: config.larkConfigDir ?? process.env.LARKSUITE_CLI_CONFIG_DIR,
+        };
+        return config.larkConfigDir ? (0, agent_lark_cli_workspace_js_1.managedLarkCliEnv)(config, base) : base;
+    };
+    const assertOfficialCliReady = async (config, env) => {
+        if (!config.larkConfigDir)
+            return;
+        if (options.assertOfficialCliReady)
+            await options.assertOfficialCliReady(config, env);
+        else {
+            (0, official_lark_cli_js_1.resolveOfficialLarkCli)({ env });
+            (0, agent_lark_cli_workspace_js_1.assertAgentWorkspaceBound)(config);
+        }
+    };
+    const emitConsumed = (agent, records) => {
+        for (const record of records)
+            emit({ type: "delivery", agentId: agent.config.agentId,
+                deliveryId: record.deliveryId, messageId: record.messageId, status: "consumed" });
+    };
+    const markSessionStable = (agent, session) => {
+        if (agent.session !== session || agent.stopped)
+            return;
+        if (agent.stabilityTimer)
+            clearTimeout(agent.stabilityTimer);
+        agent.stabilityTimer = null;
+        agent.recreateAttempts = 0;
+        agent.recreateReason = null;
+    };
+    const setRecord = (agent, record, status) => {
+        record.status = status;
+        record.updatedAt = now();
+        agent.records.set(record.deliveryId, record);
+        agent.byMessage.set(record.messageId, record.deliveryId);
+        emitConsumed(agent, persist(agent));
+        return agent.records.get(record.deliveryId) ?? record;
+    };
+    const reconcileExternalConsumption = (agent) => {
+        if (agent.stateStore) {
+            agent.stateStore.withInboxTransaction(() => reconcileFile(agent, agent.stateStore.readJson("runtimeDeliveries", { version: 1, records: [] })));
+            return;
+        }
+        const file = deliveryFile(agent);
+        if (!file)
+            return;
+        let external;
+        try {
+            external = readDeliveryFile(file);
+        }
+        catch (error) {
+            log("delivery reconcile failed", String(error));
+            return;
+        }
+        reconcileFile(agent, external);
+    };
+    const reconcileFile = (agent, external) => {
+        for (const next of external.records || []) {
+            const current = agent.records.get(next.deliveryId);
+            if (current && current.status !== "consumed" && next.status === "consumed") {
+                agent.records.set(next.deliveryId, next);
+                emit({ type: "delivery", agentId: agent.config.agentId, deliveryId: next.deliveryId, messageId: next.messageId, status: "consumed" });
+            }
+        }
+    };
+    const TURN_END_RETRY_REASON = "runtime turn ended before Inbox consumption was observed";
+    /**
+     * Runtime acceptance acknowledges only the notification. At the safe turn
+     * boundary, canonical Inbox presence decides whether that same delivery
+     * identity must become retryable again. The Inbox rows and ledger update are
+     * observed under one transaction so a concurrent poll cannot be overwritten.
+     */
+    const reconcileAcceptedAtTurnEnd = (agent) => {
+        const store = agent.stateStore;
+        if (!store?.readNdjson) {
+            reconcileExternalConsumption(agent);
+            for (const record of agent.records.values()) {
+                if (record.status !== "accepted")
+                    continue;
+                emit({ type: "delivery", agentId: agent.config.agentId, deliveryId: record.deliveryId,
+                    messageId: record.messageId, status: "deferred", reason: TURN_END_RETRY_REASON });
+            }
+            return;
+        }
+        const consumed = [];
+        const deferred = [];
+        try {
+            store.withInboxTransaction(() => {
+                const inboxIds = new Set(store.readNdjson("inbox").flatMap((row) => typeof row?.message_id === "string" ? [row.message_id] : []));
+                const disk = store.readJson("runtimeDeliveries", { version: 1, records: [] });
+                let changed = false;
+                const pendingUpdates = [];
+                const records = disk.records.map((candidate) => {
+                    const current = agent.records.get(candidate.deliveryId);
+                    if (!current)
+                        return candidate;
+                    if (candidate.status === "consumed") {
+                        if (current.status !== "consumed") {
+                            agent.records.set(candidate.deliveryId, candidate);
+                            consumed.push(candidate);
+                        }
+                        return candidate;
+                    }
+                    if (current.status !== "accepted" || candidate.status !== "accepted" || !inboxIds.has(candidate.messageId)) {
+                        return candidate;
+                    }
+                    const next = { ...candidate, status: "pending", updatedAt: now(),
+                        reason: TURN_END_RETRY_REASON, retryable: true };
+                    changed = true;
+                    pendingUpdates.push(next);
+                    return next;
+                });
+                if (changed) {
+                    store.writeJson("runtimeDeliveries", { ...disk, records });
+                    for (const next of pendingUpdates) {
+                        agent.records.set(next.deliveryId, next);
+                        deferred.push(next);
+                    }
+                }
+            });
+        }
+        catch (error) {
+            log("turn-end Inbox reconciliation failed", String(error));
+            return;
+        }
+        emitConsumed(agent, consumed);
+        for (const record of deferred)
+            emit({ type: "delivery", agentId: agent.config.agentId,
+                deliveryId: record.deliveryId, messageId: record.messageId, status: "deferred", reason: TURN_END_RETRY_REASON });
+    };
+    // Production callers persist the canonical Inbox before calling deliver(). If a
+    // concurrent drain wins between that append and ledger creation, close only the
+    // record created/observed by this call under the same Inbox lock.
+    const reconcileAbsentCanonical = (agent, record) => {
+        const store = agent.stateStore;
+        if (!store?.readNdjson || !isActiveDelivery(record.status))
+            return;
+        let consumed = null;
+        try {
+            store.withInboxTransaction(() => {
+                const present = store.readNdjson("inbox")
+                    .some((row) => row?.message_id === record.messageId);
+                if (present)
+                    return;
+                const disk = store.readJson("runtimeDeliveries", { version: 1, records: [] });
+                let changed = false;
+                const records = disk.records.map((candidate) => {
+                    if (candidate.deliveryId !== record.deliveryId || !isActiveDelivery(candidate.status))
+                        return candidate;
+                    changed = true;
+                    consumed = { ...candidate, status: "consumed", updatedAt: now() };
+                    return consumed;
+                });
+                if (changed)
+                    store.writeJson("runtimeDeliveries", { ...disk, records });
+            });
+        }
+        catch (error) {
+            log("post-delivery Inbox reconciliation failed", String(error));
+            return;
+        }
+        if (consumed) {
+            agent.records.set(record.deliveryId, consumed);
+            emit({ type: "delivery", agentId: agent.config.agentId, deliveryId: record.deliveryId,
+                messageId: record.messageId, status: "consumed" });
+        }
+    };
+    const resultFor = (agent, record, result) => {
+        if (result.status === "accepted") {
+            delete record.reason;
+            delete record.retryable;
+            const finalRecord = setRecord(agent, record, "accepted");
+            if (finalRecord.status !== "consumed")
+                emit({ type: "delivery", agentId: agent.config.agentId,
+                    deliveryId: record.deliveryId, messageId: record.messageId, status: "accepted" });
+            return { status: "accepted", deliveryId: record.deliveryId };
+        }
+        const retryable = result.status === "deferred" || result.retryable;
+        record.reason = result.reason;
+        record.retryable = retryable;
+        const finalRecord = setRecord(agent, record, retryable ? "pending" : "error");
+        if (finalRecord.status === "consumed")
+            return { status: "accepted", deliveryId: record.deliveryId };
+        const status = retryable ? "deferred" : "error";
+        emit({ type: "delivery", agentId: agent.config.agentId, deliveryId: record.deliveryId, messageId: record.messageId, status, reason: result.reason });
+        return retryable
+            ? { status: "deferred", deliveryId: record.deliveryId, reason: result.reason }
+            : { status: "error", deliveryId: record.deliveryId, reason: result.reason, retryable: false };
+    };
+    const submit = async (agent, record, busy) => {
+        agent.submitting = true;
+        if (!busy)
+            agent.busy = true; // Reserve the turn before prompt() can yield.
+        try {
+            const session = await ensureSession(agent);
+            const submittingRecord = setRecord(agent, record, "submitting");
+            if (submittingRecord.status === "consumed") {
+                if (!busy)
+                    agent.busy = false;
+                return { status: "accepted", deliveryId: record.deliveryId };
+            }
+            const result = await (busy ? session.busyInput(record.input) : session.prompt(record.input));
+            if (agent.session !== session || agent.stopped) {
+                return { status: "deferred", deliveryId: record.deliveryId, reason: "runtime session replaced before input result" };
+            }
+            if (result.status !== "accepted" && !busy)
+                agent.busy = false;
+            if (result.status === "accepted")
+                markSessionStable(agent, session);
+            return resultFor(agent, record, result);
+        }
+        catch (error) {
+            if (!busy)
+                agent.busy = false;
+            const reason = error instanceof Error ? error.message : String(error);
+            record.reason = reason;
+            record.retryable = true;
+            setRecord(agent, record, "pending");
+            emit({ type: "delivery", agentId: agent.config.agentId, deliveryId: record.deliveryId, messageId: record.messageId, status: "deferred", reason });
+            return { status: "deferred", deliveryId: record.deliveryId, reason };
+        }
+        finally {
+            agent.submitting = false;
+            if (agent.retryAfterSubmit && !agent.stopped) {
+                agent.retryAfterSubmit = false;
+                queueMicrotask(() => { void retryPending(agent); });
+            }
+        }
+    };
+    const retryPending = async (agent) => {
+        reconcileExternalConsumption(agent);
+        if (agent.submitting) {
+            agent.retryAfterSubmit = true;
+            return;
+        }
+        if (agent.busy || agent.turnInProgress || !agent.session)
+            return;
+        const record = [...agent.records.values()].find((candidate) => candidate.status === "pending" || candidate.status === "submitting");
+        if (record)
+            await submit(agent, record, false);
+    };
+    const scheduleRecreate = (agent, reason) => {
+        if (agent.stopped || agent.retryTimer || agent.starting || agent.session)
+            return;
+        if (agent.recreateAttempts >= retryPolicy.maxAttempts) {
+            emit({ type: "agent-status", agentId: agent.config.agentId, status: "error",
+                error: `runtime recreation exhausted after ${agent.recreateAttempts} attempts: ${reason}` });
+            return;
+        }
+        const attempt = ++agent.recreateAttempts;
+        const delay = Math.min(retryPolicy.maxDelayMs, retryPolicy.baseDelayMs * 2 ** (attempt - 1));
+        emit({ type: "agent-status", agentId: agent.config.agentId, status: "error",
+            error: `runtime recreate attempt ${attempt}/${retryPolicy.maxAttempts} in ${delay}ms: ${reason}` });
+        agent.retryTimer = setTimeout(() => {
+            agent.retryTimer = null;
+            if (agent.stopped)
+                return;
+            void ensureSession(agent).then(() => {
+                return retryPending(agent);
+            }).catch((error) => {
+                const readiness = error instanceof runtime_readiness_js_1.RuntimePrerequisiteError ? error.readiness
+                    : (0, runtime_readiness_js_1.classifyRuntimePrerequisite)(agent.adapter.id, error);
+                agent.readiness = readiness;
+                const nextReason = error instanceof Error ? error.message : String(error);
+                if (readiness.state === "unavailable")
+                    scheduleRecreate(agent, nextReason);
+                else {
+                    agent.disabledReason = nextReason;
+                    emit({ type: "agent-status", agentId: agent.config.agentId, status: "error", error: nextReason, readiness });
+                }
+            });
+        }, delay);
+        agent.retryTimer.unref?.();
+    };
+    const replaceSession = (agent, session, reason) => {
+        if (agent.session !== session || agent.stopped)
+            return;
+        agent.session = null;
+        agent.busy = false;
+        agent.submitting = false;
+        agent.generation += 1;
+        agent.recreateReason = reason;
+        if (agent.stabilityTimer)
+            clearTimeout(agent.stabilityTimer);
+        agent.stabilityTimer = null;
+        void session.close(`replace after ${reason}`).catch((error) => log("runtime close after replacement failed", String(error)));
+        for (const record of agent.records.values())
+            if (isActiveDelivery(record.status))
+                record.status = "pending";
+        emitConsumed(agent, persist(agent));
+        emit({ type: "agent-status", agentId: agent.config.agentId, status: "error", error: reason });
+        scheduleRecreate(agent, reason);
+    };
+    const recoverConfiguration = (agent, session, message) => {
+        if (agent.session !== session || agent.stopped)
+            return;
+        agent.disabledReason = `runtime configuration recovery in progress: ${message}`;
+        agent.session = null;
+        agent.busy = false;
+        agent.submitting = false;
+        agent.generation += 1;
+        if (agent.stabilityTimer)
+            clearTimeout(agent.stabilityTimer);
+        agent.stabilityTimer = null;
+        for (const record of agent.records.values()) {
+            if (!isActiveDelivery(record.status))
+                continue;
+            setRecord(agent, record, "pending");
+            emit({ type: "delivery", agentId: agent.config.agentId, deliveryId: record.deliveryId,
+                messageId: record.messageId, status: "deferred", reason: message });
+        }
+        emit({ type: "agent-status", agentId: agent.config.agentId, status: "error", error: message });
+        const recovery = (async () => {
+            try {
+                await session.close("runtime configuration error");
+                const result = agent.adapter.recoverConfigurationError
+                    ? await agent.adapter.recoverConfigurationError(message)
+                    : { recovered: false, reason: "runtime adapter does not support automatic configuration recovery" };
+                if (agent.stopped)
+                    return;
+                if (!result.recovered) {
+                    agent.disabledReason = `${message}\n${result.reason}`;
+                    emit({ type: "agent-status", agentId: agent.config.agentId, status: "error", error: agent.disabledReason });
+                    return;
+                }
+                agent.disabledReason = null;
+                agent.recreateAttempts = 0;
+                agent.recreateReason = result.reason;
+                scheduleRecreate(agent, result.reason);
+            }
+            catch (error) {
+                if (agent.stopped)
+                    return;
+                const reason = error instanceof Error ? error.message : String(error);
+                agent.disabledReason = `${message}\nCodex update failed: ${reason}`;
+                emit({ type: "agent-status", agentId: agent.config.agentId, status: "error", error: agent.disabledReason });
+            }
+            finally {
+                agent.configurationRecovery = null;
+            }
+        })();
+        agent.configurationRecovery = recovery;
+    };
+    const observe = (agent, session, event) => {
+        if (agent.session !== session)
+            return; // Ignore late output from a replaced child.
+        // Keep the trace parent published until authoritative Inbox reconciliation
+        // has observed any direct CLI poll completed by this turn.
+        if (event.type !== "turn-end")
+            telemetry?.runtimeEvent(agent.config.agentId, event);
+        emit({ type: "runtime", agentId: agent.config.agentId, event });
+        if (event.type === "session-init") {
+            agent.config.sessionId = event.sessionId;
+            emit({ type: "session", agentId: agent.config.agentId, runtime: agent.adapter.id, sessionId: event.sessionId, launchId: agent.launchId,
+                ...(event.model ? { model: event.model } : {}), ...(event.reasoningEffort ? { reasoningEffort: event.reasoningEffort } : {}) });
+            void retryPending(agent);
+        }
+        else if (event.type === "turn-start") {
+            agent.busy = true;
+            agent.turnInProgress = true;
+            agent.turnHadFailure = false;
+            agent.turnHadAuthenticatedOutput = false;
+            markSessionStable(agent, session);
+            emit({ type: "activity", agentId: agent.config.agentId, activity: "working", activityKind: "working", detailKind: "turn_started" });
+        }
+        else if (event.type === "turn-end") {
+            const recoveredAuthentication = agent.authFailureActive && agent.turnInProgress
+                && agent.turnHadAuthenticatedOutput && !agent.turnHadFailure;
+            agent.turnInProgress = false;
+            agent.busy = false;
+            emit({ type: "activity", agentId: agent.config.agentId, activity: "idle", activityKind: "idle", detailKind: "turn_ended" });
+            reconcileAcceptedAtTurnEnd(agent);
+            telemetry?.runtimeEvent(agent.config.agentId, event);
+            if (recoveredAuthentication) {
+                agent.authFailureActive = false;
+                const prior = agent.readiness;
+                agent.readiness = {
+                    runtime: agent.adapter.id,
+                    state: "ready",
+                    ...(prior?.executable ? { executable: prior.executable } : {}),
+                    ...(prior?.version ? { version: prior.version } : {}),
+                };
+                emit({ type: "agent-status", agentId: agent.config.agentId, status: "active", readiness: agent.readiness });
+            }
+            void retryPending(agent);
+        }
+        else if (event.type === "activity") {
+            if (agent.turnInProgress && event.activity !== "internal")
+                agent.turnHadAuthenticatedOutput = true;
+            emit({ type: "activity", agentId: agent.config.agentId, activity: event.activity, activityKind: event.activity });
+        }
+        else if (event.type === "input-error") {
+            const record = event.inputId
+                ? agent.records.get(event.inputId) ?? [...agent.records.values()].find((candidate) => candidate.input.inputId === event.inputId)
+                : undefined;
+            if (!record || record.status === "consumed" || record.status === "error")
+                return;
+            agent.turnHadFailure = true;
+            if (event.willRetry) {
+                emit({ type: "delivery", agentId: agent.config.agentId, deliveryId: record.deliveryId,
+                    messageId: record.messageId, status: "deferred", reason: event.message });
+                return;
+            }
+            const submittedWhileBusy = record.input.kind === "inbox_update" || record.input.kind === "inbox-update";
+            if (!submittedWhileBusy)
+                agent.busy = false;
+            record.reason = event.message;
+            record.retryable = event.retryable;
+            const finalRecord = setRecord(agent, record, event.retryable ? "pending" : "error");
+            if (finalRecord.status !== "consumed")
+                emit({ type: "delivery", agentId: agent.config.agentId,
+                    deliveryId: record.deliveryId, messageId: record.messageId,
+                    status: event.retryable ? "deferred" : "error", reason: event.message });
+            if (event.errorCategory === "auth" && !event.retryable) {
+                const readiness = (0, runtime_readiness_js_1.providerAuthenticationFailureReadiness)(agent.adapter.id, event.upstream?.provider);
+                agent.authFailureActive = true;
+                agent.readiness = {
+                    ...readiness,
+                    ...(agent.readiness?.executable ? { executable: agent.readiness.executable } : {}),
+                    ...(agent.readiness?.version ? { version: agent.readiness.version } : {}),
+                };
+                emit({ type: "agent-status", agentId: agent.config.agentId, status: "error",
+                    error: `${agent.readiness.reason} ${agent.readiness.nextAction}`, readiness: agent.readiness });
+            }
+            if (event.retryable && !agent.busy && !agent.turnInProgress)
+                void retryPending(agent);
+        }
+        else if (event.type === "configuration-error") {
+            recoverConfiguration(agent, session, event.message);
+        }
+        else if (event.type === "error" || event.type === "closed") {
+            replaceSession(agent, session, event.type === "error" ? event.message : `runtime closed (${event.code ?? event.signal ?? "unknown"})`);
+        }
+    };
+    const ensureSession = async (agent) => {
+        if (agent.disabledReason)
+            throw new Error(agent.disabledReason);
+        if (agent.session)
+            return agent.session;
+        if (agent.starting)
+            return agent.starting;
+        const probeEnv = runtimeEnv(agent.config);
+        await assertOfficialCliReady(agent.config, probeEnv);
+        const readiness = agent.adapter.probe ? await agent.adapter.probe({ agentId: agent.config.agentId,
+            workspaceDir: agent.config.workspaceDir, stateDir: agent.config.stateDir,
+            env: { LARKIN_PI_COMMAND: process.env.LARKIN_PI_COMMAND, LARKIN_CODEX_COMMAND: process.env.LARKIN_CODEX_COMMAND,
+                LARKIN_CLAUDE_COMMAND: process.env.LARKIN_CLAUDE_COMMAND, ...probeEnv } })
+            : { runtime: agent.adapter.id, state: "ready" };
+        if (!agent.authFailureActive)
+            agent.readiness = readiness;
+        if (readiness.state !== "ready")
+            throw new runtime_readiness_js_1.RuntimePrerequisiteError(readiness);
+        const standingPrompt = options.promptBuilder.build({
+            agentId: agent.config.agentId, name: agent.config.displayName || agent.config.name,
+            description: agent.config.description || "", runtime: agent.adapter.id,
+            cli: (0, agent_cli_capabilities_js_1.agentCliPromptCapabilities)("larkin"),
+        });
+        const generation = ++agent.generation;
+        let completedSession = null;
+        agent.starting = agent.adapter.createSession({
+            agentId: agent.config.agentId, model: agent.config.model, reasoningEffort: agent.config.effort || null,
+            workspaceDir: agent.config.workspaceDir, stateDir: agent.config.stateDir,
+            resumeSessionId: agent.config.sessionId || null, standingPrompt,
+            env: runtimeEnv(agent.config, `${agent.launchId}:${generation}`),
+        }).then((session) => {
+            completedSession = session;
+            if (agent.stopped || generation !== agent.generation) {
+                void session.close("stale creation");
+                throw new Error("stale runtime session creation");
+            }
+            agent.session = session;
+            session.subscribe((event) => observe(agent, session, event));
+            if (agent.session !== session)
+                return session;
+            if (session.sessionId) {
+                agent.config.sessionId = session.sessionId;
+                emit({ type: "session", agentId: agent.config.agentId, runtime: agent.adapter.id, sessionId: session.sessionId, launchId: agent.launchId,
+                    ...(session.effectiveModel ? { model: session.effectiveModel } : {}),
+                    ...(session.effectiveReasoningEffort ? { reasoningEffort: session.effectiveReasoningEffort } : {}) });
+            }
+            emit({ type: "agent-status", agentId: agent.config.agentId, status: agent.authFailureActive ? "error" : "active",
+                ...(agent.authFailureActive ? { error: `${agent.readiness?.reason} ${agent.readiness?.nextAction}` } : {}),
+                readiness: agent.readiness ?? readiness });
+            agent.stabilityTimer = setTimeout(() => markSessionStable(agent, session), retryPolicy.stableWindowMs);
+            agent.stabilityTimer.unref?.();
+            return session;
+        }).finally(() => {
+            agent.starting = null;
+            if (completedSession && !agent.session && !agent.stopped) {
+                scheduleRecreate(agent, agent.recreateReason || "runtime closed during session initialization");
+            }
+        });
+        return agent.starting;
+    };
+    return {
+        async probe(config) {
+            const adapter = options.adapterFor(config.runtime);
+            const env = runtimeEnv(config);
+            await assertOfficialCliReady(config, env);
+            return adapter.probe ? adapter.probe({ agentId: config.agentId, workspaceDir: config.workspaceDir, stateDir: config.stateDir,
+                env: { LARKIN_PI_COMMAND: process.env.LARKIN_PI_COMMAND, LARKIN_CODEX_COMMAND: process.env.LARKIN_CODEX_COMMAND,
+                    LARKIN_CLAUDE_COMMAND: process.env.LARKIN_CLAUDE_COMMAND, ...env } })
+                : { runtime: adapter.id, state: "ready" };
+        },
+        async stage(config) {
+            const previous = managed.get(config.agentId);
+            if (!previous)
+                throw new Error(`cannot stage unknown runtime Agent: ${config.agentId}`);
+            if (previous.busy || previous.submitting || previous.starting) {
+                throw new Error(`Agent ${config.agentId} is not idle for runtime staging`);
+            }
+            const adapter = options.adapterFor(config.runtime);
+            const stageEnv = runtimeEnv(config, `${node_crypto_1.default.randomUUID()}:staged`);
+            await assertOfficialCliReady(config, stageEnv);
+            const readiness = adapter.probe ? await adapter.probe({ agentId: config.agentId, workspaceDir: config.workspaceDir, stateDir: config.stateDir,
+                env: { LARKIN_PI_COMMAND: process.env.LARKIN_PI_COMMAND, LARKIN_CODEX_COMMAND: process.env.LARKIN_CODEX_COMMAND,
+                    LARKIN_CLAUDE_COMMAND: process.env.LARKIN_CLAUDE_COMMAND, ...stageEnv } })
+                : { runtime: adapter.id, state: "ready" };
+            if (readiness.state !== "ready")
+                throw new runtime_readiness_js_1.RuntimePrerequisiteError(readiness);
+            const standingPrompt = options.promptBuilder.build({
+                agentId: config.agentId, name: config.displayName || config.name,
+                description: config.description || "", runtime: adapter.id,
+                cli: (0, agent_cli_capabilities_js_1.agentCliPromptCapabilities)("larkin"),
+            });
+            const session = await adapter.createSession({
+                agentId: config.agentId, model: config.model, reasoningEffort: config.effort || null,
+                workspaceDir: config.workspaceDir, stateDir: config.stateDir,
+                resumeSessionId: config.sessionId || null, standingPrompt,
+                env: stageEnv,
+            });
+            let state = "staged";
+            const rollback = async (reason) => {
+                if (state !== "staged")
+                    return;
+                state = "rolled_back";
+                await session.close(reason);
+            };
+            return {
+                readiness,
+                async commit() {
+                    if (state !== "staged")
+                        throw new Error(`runtime candidate is ${state}`);
+                    const current = managed.get(config.agentId);
+                    if (current !== previous || previous.busy || previous.submitting || previous.starting) {
+                        await rollback("runtime candidate commit precondition changed");
+                        throw new Error(`Agent ${config.agentId} changed or became busy during runtime staging`);
+                    }
+                    state = "committed";
+                    previous.stopped = true;
+                    previous.generation += 1;
+                    if (previous.poller)
+                        clearInterval(previous.poller);
+                    if (previous.retryTimer)
+                        clearTimeout(previous.retryTimer);
+                    if (previous.stabilityTimer)
+                        clearTimeout(previous.stabilityTimer);
+                    const candidate = {
+                        ...previous, config, adapter, session, launchId: node_crypto_1.default.randomUUID(), busy: false, submitting: false,
+                        starting: null, retryAfterSubmit: false, generation: 0, poller: null, retryTimer: null,
+                        recreateAttempts: 0, stabilityTimer: null, recreateReason: null, stopped: false,
+                        disabledReason: null, configurationRecovery: null,
+                        readiness: previous.authFailureActive ? previous.readiness : readiness,
+                    };
+                    managed.set(config.agentId, candidate);
+                    session.subscribe((event) => observe(candidate, session, event));
+                    if (session.sessionId) {
+                        candidate.config.sessionId = session.sessionId;
+                        emit({ type: "session", agentId: config.agentId, runtime: adapter.id, sessionId: session.sessionId,
+                            launchId: candidate.launchId, ...(session.effectiveModel ? { model: session.effectiveModel } : {}),
+                            ...(session.effectiveReasoningEffort ? { reasoningEffort: session.effectiveReasoningEffort } : {}) });
+                    }
+                    candidate.poller = setInterval(() => reconcileExternalConsumption(candidate), 250);
+                    candidate.poller.unref?.();
+                    if (!candidate.authFailureActive) {
+                        emit({ type: "agent-status", agentId: config.agentId, status: "active", readiness: candidate.readiness ?? readiness });
+                    }
+                    await previous.session?.close("runtime candidate committed")
+                        .catch((error) => log("previous runtime close after candidate commit failed", String(error)));
+                },
+                rollback,
+            };
+        },
+        isBusy(agentId) { const agent = managed.get(agentId); return Boolean(agent?.busy || agent?.submitting || agent?.starting); },
+        async resetSession(agentId) {
+            const agent = managed.get(agentId);
+            if (!agent || agent.stopped)
+                throw new RuntimeSessionResetError("unknown_agent", `unknown runtime Agent: ${agentId}`);
+            if (agent.busy || agent.turnInProgress || agent.submitting || agent.starting) {
+                throw new RuntimeSessionResetError("agent_busy", `Agent ${agentId} is not idle`);
+            }
+            const countPending = () => agent.stateStore
+                ? agent.stateStore.withInboxTransaction(() => agent.stateStore.readNdjson?.("inbox").length ?? 0)
+                : [...agent.records.values()].filter((record) => isActiveDelivery(record.status)).length;
+            const pendingCount = countPending();
+            if (pendingCount > 0)
+                throw new RuntimeSessionResetError("inbox_backlog", `Agent ${agentId} has unconsumed Inbox backlog`, pendingCount);
+            const oldSession = agent.session;
+            if (!oldSession)
+                throw new RuntimeSessionResetError("agent_busy", `Agent ${agentId} Runtime session is unavailable`);
+            const oldSessionId = oldSession.sessionId;
+            const probeEnv = runtimeEnv(agent.config, `${agent.launchId}:reset`);
+            await assertOfficialCliReady(agent.config, probeEnv);
+            const readiness = agent.adapter.probe ? await agent.adapter.probe({ agentId: agent.config.agentId,
+                workspaceDir: agent.config.workspaceDir, stateDir: agent.config.stateDir,
+                env: { LARKIN_PI_COMMAND: process.env.LARKIN_PI_COMMAND, LARKIN_CODEX_COMMAND: process.env.LARKIN_CODEX_COMMAND,
+                    LARKIN_CLAUDE_COMMAND: process.env.LARKIN_CLAUDE_COMMAND, ...probeEnv } })
+                : { runtime: agent.adapter.id, state: "ready" };
+            if (readiness.state !== "ready")
+                throw new runtime_readiness_js_1.RuntimePrerequisiteError(readiness);
+            const standingPrompt = options.promptBuilder.build({
+                agentId: agent.config.agentId, name: agent.config.displayName || agent.config.name,
+                description: agent.config.description || "", runtime: agent.adapter.id,
+                cli: (0, agent_cli_capabilities_js_1.agentCliPromptCapabilities)("larkin"),
+            });
+            const create = agent.adapter.createSession({
+                agentId: agent.config.agentId, model: agent.config.model, reasoningEffort: agent.config.effort || null,
+                workspaceDir: agent.config.workspaceDir, stateDir: agent.config.stateDir,
+                resumeSessionId: null, standingPrompt, env: probeEnv,
+            });
+            agent.starting = create;
+            let fresh;
+            try {
+                fresh = await create;
+            }
+            finally {
+                if (agent.starting === create)
+                    agent.starting = null;
+            }
+            const commit = () => {
+                if (agent.session !== oldSession || agent.busy || agent.turnInProgress || agent.submitting || agent.stopped) {
+                    throw new RuntimeSessionResetError("agent_busy", `Agent ${agentId} changed during reset`);
+                }
+                const pendingAfterCreate = agent.stateStore?.readNdjson?.("inbox").length
+                    ?? [...agent.records.values()].filter((record) => isActiveDelivery(record.status)).length;
+                if (pendingAfterCreate > 0) {
+                    throw new RuntimeSessionResetError("inbox_backlog", `Agent ${agentId} received Inbox backlog during reset`, pendingAfterCreate);
+                }
+                agent.generation += 1;
+                agent.launchId = node_crypto_1.default.randomUUID();
+                agent.config.sessionId = null;
+                agent.session = fresh;
+                agent.readiness = readiness;
+                agent.disabledReason = null;
+            };
+            try {
+                if (agent.stateStore)
+                    agent.stateStore.withInboxTransaction(commit);
+                else
+                    commit();
+            }
+            catch (error) {
+                await fresh.close("fresh session reset precondition changed");
+                throw error;
+            }
+            fresh.subscribe((event) => observe(agent, fresh, event));
+            if (fresh.sessionId) {
+                agent.config.sessionId = fresh.sessionId;
+                emit({ type: "session", agentId, runtime: agent.adapter.id, sessionId: fresh.sessionId, launchId: agent.launchId,
+                    ...(fresh.effectiveModel ? { model: fresh.effectiveModel } : {}),
+                    ...(fresh.effectiveReasoningEffort ? { reasoningEffort: fresh.effectiveReasoningEffort } : {}) });
+            }
+            emit({ type: "agent-status", agentId, status: "active", readiness });
+            await oldSession.close("fresh session reset committed")
+                .catch((error) => log("previous runtime close after fresh reset failed", String(error)));
+            return { generationChanged: true, sessionChanged: oldSessionId !== fresh.sessionId, turns: 0,
+                runtimeReady: true, pendingCount: 0, sessionId: fresh.sessionId };
+        },
+        async start(configs) {
+            let activeCount = 0;
+            let recoveringCount = 0;
+            const startupFailures = [];
+            for (const config of configs) {
+                if (managed.has(config.agentId)) {
+                    activeCount += 1;
+                    continue;
+                }
+                const stateStore = options.stateStoreFor?.(config.agentId);
+                const persisted = stateStore
+                    ? stateStore.withInboxTransaction(() => {
+                        const deliveryFile = stateStore.readJson("runtimeDeliveries", { version: 1, records: [] });
+                        if (!stateStore.readNdjson)
+                            return deliveryFile;
+                        const inboxIds = new Set(stateStore.readNdjson("inbox").flatMap((row) => typeof row?.message_id === "string" ? [row.message_id] : []));
+                        let changed = false;
+                        const records = deliveryFile.records.map((record) => {
+                            const synthetic = /^(?:redeliver_|rem_|interaction_)/.test(record.messageId);
+                            if (!synthetic || !isActiveDelivery(record.status) || inboxIds.has(record.messageId))
+                                return record;
+                            changed = true;
+                            return { ...record, status: "consumed", updatedAt: now() };
+                        });
+                        const migrated = changed ? { ...deliveryFile, records } : deliveryFile;
+                        if (changed)
+                            stateStore.writeJson("runtimeDeliveries", migrated);
+                        return migrated;
+                    })
+                    : readDeliveryFile(config.stateDir ? node_path_1.default.join(config.stateDir, "runtime-deliveries.json") : null);
+                const agent = { config, adapter: options.adapterFor(config.runtime), session: null,
+                    launchId: node_crypto_1.default.randomUUID(), busy: false, submitting: false, starting: null, retryAfterSubmit: false,
+                    records: new Map(persisted.records.map((record) => [record.deliveryId, record])),
+                    byMessage: new Map(persisted.records.map((record) => [record.messageId, record.deliveryId])),
+                    generation: 0, poller: null, retryTimer: null, recreateAttempts: 0,
+                    stabilityTimer: null, recreateReason: null, stopped: false, disabledReason: null,
+                    configurationRecovery: null, stateStore, readiness: null,
+                    turnInProgress: false, turnHadFailure: false, turnHadAuthenticatedOutput: false, authFailureActive: false };
+                for (const record of agent.records.values())
+                    if (isActiveDelivery(record.status))
+                        record.status = "pending";
+                emitConsumed(agent, persist(agent));
+                managed.set(config.agentId, agent);
+                try {
+                    await ensureSession(agent);
+                    activeCount += 1;
+                    await retryPending(agent);
+                }
+                catch (error) {
+                    const reason = error instanceof Error ? error.message : String(error);
+                    const transient = error instanceof runtime_readiness_js_1.RuntimePrerequisiteError && error.readiness.state === "unavailable";
+                    agent.disabledReason = transient ? null : reason;
+                    if (transient) {
+                        recoveringCount += 1;
+                        scheduleRecreate(agent, reason);
+                    }
+                    startupFailures.push(`${config.agentId}: ${reason}`);
+                    emit({ type: "agent-status", agentId: config.agentId, status: "error", error: reason,
+                        ...(error instanceof runtime_readiness_js_1.RuntimePrerequisiteError ? { readiness: error.readiness } : {}) });
+                }
+                agent.poller = setInterval(() => reconcileExternalConsumption(agent), 250);
+                agent.poller.unref?.();
+            }
+            if (configs.length > 0 && activeCount === 0 && recoveringCount === 0) {
+                throw new Error(`No runtime Agent started: ${startupFailures.join("; ")}`);
+            }
+        },
+        async deliver(agentId, envelope) {
+            const messageId = String(envelope.message_id || envelope.seq || node_crypto_1.default.randomUUID());
+            const agent = managed.get(agentId);
+            if (!agent) {
+                telemetry?.delivery(agentId, messageId, "error");
+                throw new Error(`unknown runtime Agent: ${agentId}`);
+            }
+            reconcileExternalConsumption(agent);
+            const existingId = agent.byMessage.get(messageId);
+            if (existingId) {
+                const existing = agent.records.get(existingId);
+                if (existing?.status === "error") {
+                    existing.input.attempt += 1;
+                    delete existing.reason;
+                    delete existing.retryable;
+                    setRecord(agent, existing, "pending");
+                    const receipt = await (telemetry?.phase(messageId, "runtime.deliver", api_1.SpanKind.PRODUCER, () => submit(agent, existing, agent.busy || agent.submitting)) ?? submit(agent, existing, agent.busy || agent.submitting));
+                    telemetry?.delivery(agentId, messageId, receipt.status);
+                    reconcileAbsentCanonical(agent, agent.records.get(existingId) ?? existing);
+                    return receipt;
+                }
+                if (existing)
+                    reconcileAbsentCanonical(agent, existing);
+                telemetry?.delivery(agentId, messageId, "duplicate");
+                return { status: "duplicate", deliveryId: existingId };
+            }
+            if ([...agent.records.values()].filter((record) => isActiveDelivery(record.status)).length >= MAX_DELIVERIES) {
+                const deliveryId = `overflow-${node_crypto_1.default.createHash("sha256").update(messageId).digest("hex").slice(0, 24)}`;
+                telemetry?.delivery(agentId, messageId, "deferred");
+                return { status: "deferred", deliveryId, reason: `runtime delivery backlog limit ${MAX_DELIVERIES} reached` };
+            }
+            const deliveryId = node_crypto_1.default.randomUUID();
+            const busy = agent.busy || agent.submitting;
+            const input = { inputId: deliveryId, deliveryId, kind: busy ? "inbox_update" : "wake",
+                text: options.promptBuilder.buildInboxNotice({ busy, count: 1, deliveryId,
+                    ...(typeof envelope.target === "string" ? { target: envelope.target } : {}),
+                    ...(typeof envelope.wake_reason === "string" ? { wakeReason: envelope.wake_reason } : {}) }), attempt: 0 };
+            const record = { deliveryId, messageId, status: "pending", input, updatedAt: now() };
+            agent.records.set(deliveryId, record);
+            agent.byMessage.set(messageId, deliveryId);
+            persist(agent);
+            if (agent.disabledReason) {
+                reconcileAbsentCanonical(agent, record);
+                telemetry?.delivery(agentId, messageId, "deferred");
+                return { status: "deferred", deliveryId, reason: agent.disabledReason };
+            }
+            const receipt = await (telemetry?.phase(messageId, "runtime.deliver", api_1.SpanKind.PRODUCER, () => submit(agent, record, busy)) ?? submit(agent, record, busy));
+            telemetry?.delivery(agentId, messageId, receipt.status);
+            reconcileAbsentCanonical(agent, agent.records.get(deliveryId) ?? record);
+            return receipt;
+        },
+        async stop(agentId, reason) {
+            const agent = managed.get(agentId);
+            if (!agent)
+                return;
+            agent.stopped = true;
+            if (agent.poller)
+                clearInterval(agent.poller);
+            if (agent.retryTimer)
+                clearTimeout(agent.retryTimer);
+            if (agent.stabilityTimer)
+                clearTimeout(agent.stabilityTimer);
+            if (agent.busy)
+                await agent.session?.cancel(reason);
+            await agent.session?.close(reason);
+            managed.delete(agentId);
+            emit({ type: "agent-status", agentId, status: "inactive" });
+        },
+        async shutdown(reason) { await Promise.allSettled([...managed.keys()].map((id) => this.stop(id, reason))); },
+        subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
+    };
+}