@enderfga/claw-orchestrator 7.12.1 → 7.14.0

package/dist/src/kernel/nodes/autoloop.d.ts

@@ -15,6 +15,9 @@
 import type { NodeContext, NodeResult } from '../engine.js';
 import type { NodeSpec, RunRecord } from '../types.js';
 import type { AutoloopState } from '../../autoloop/types.js';
+import { type AutoloopInputSnapshot, type InFlightChat, type PendingChatEntry } from '../../autoloop/runner.js';
+export declare const AUTOLOOP_RESTORE_MALFORMED = "Autoloop resume refused: stored chat checkpoint is malformed";
+export declare const AUTOLOOP_RESTORE_UNPERSISTED = "Autoloop resume refused: pending chat could not be checkpointed";
 /** Whatever SessionManager hands back from booting the loop. */
 export interface AutoloopHandle {
     runner: {
@@ -22,6 +25,12 @@ export interface AutoloopHandle {
         stop(): void;
         on(event: 'state', listener: () => void): unknown;
         off(event: 'state', listener: () => void): unknown;
+        /** The accepted-chat snapshot the next checkpoint should carry. */
+        checkpointInput?(): AutoloopInputSnapshot;
+        /** Before ready: record a restored in-flight marker as a notice. */
+        reconcileRestoredInput?(): void;
+        /** After ready: queue or park restored pending chat. */
+        releaseRestoredInput?(): void;
     };
     dispatcher: {
         sessionNames: {
@@ -32,11 +41,21 @@ export interface AutoloopHandle {
         }): Promise<void>;
     };
     ledgerDir: string;
+    /** Called synchronously by `RunKernel.cancel`. */
+    abort?(): void;
+    /**
+     * After the initial publish and notice reconciliation, before `ready`.
+     * SessionManager uses this for committed-iteration recovery so it cannot
+     * send before the publisher gate. Failure rejects the start the same way
+     * a refused initial publish does.
+     */
+    afterPublishReconcile?(): Promise<void>;
 }
 export interface AutoloopNodeDeps {
     /** `secrets` carries what the spec deliberately does not — custom-engine configs. */
     boot(config: Record<string, unknown>, secrets: Record<string, unknown>, opts: {
         freshStart: boolean;
+        restoredInput?: AutoloopInputSnapshot;
     }): Promise<AutoloopHandle>;
     /**
      * Resolve/reject the deferred the caller is waiting on.
@@ -56,9 +75,10 @@ export interface AutoloopNodeDeps {
     /**
      * Hand back a way to refresh the checkpoint mid-run. The loop's role
      * selection changes when `spawn_subagents` picks engines, and that has to
-     * reach the record — it used to be written to the registry file.
+     * reach the record — it used to be written to the registry file. Returns
+     * true only when the refreshed payload was committed.
      */
-    registerPublisher(runId: string, publish: () => void): void;
+    registerPublisher(runId: string, publish: () => boolean): void;
     unregisterPublisher(runId: string): void;
     /** Extra payload to publish alongside the state (currently the role selection). */
     extra(runId: string): Record<string, unknown>;
@@ -69,7 +89,17 @@ export interface AutoloopNodeData {
     plannerSession: string;
     /** Engines/models actually in use, as chosen by `spawn_subagents`. */
     roleSelection?: Record<string, unknown>;
+    /** Accepted chat not yet handed to the dispatcher, in order. */
+    pendingChat?: ReadonlyArray<PendingChatEntry>;
+    /** The accepted chat whose physical send may have started. */
+    inFlightChat?: InFlightChat | null;
 }
+/**
+ * Validate the accepted-chat fields of a stored node payload. Absent fields
+ * restore as empty; anything malformed or over the acceptance bounds is
+ * refused with one fixed error.
+ */
+export declare function validateStoredInput(data: unknown): AutoloopInputSnapshot;
 export declare function makeAutoloopExecutor(deps: AutoloopNodeDeps): (node: NodeSpec, ctx: NodeContext) => Promise<NodeResult>;
 /**
  * Rebuild an `AutoloopState` for a run that is not live in this process.

package/dist/src/kernel/nodes/autoloop.js

@@ -12,35 +12,137 @@
  * closed over itself. The node spec carries only JSON, because it is
  * checkpointed with the run.
  */
+import { MAX_PENDING_CHAT, MAX_PENDING_CHAT_BYTES, pendingChatBytes, } from '../../autoloop/runner.js';
+export const AUTOLOOP_RESTORE_MALFORMED = 'Autoloop resume refused: stored chat checkpoint is malformed';
+export const AUTOLOOP_RESTORE_UNPERSISTED = 'Autoloop resume refused: pending chat could not be checkpointed';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isIsoTimestamp = (value) => {
+    if (typeof value !== 'string')
+        return false;
+    const ms = Date.parse(value);
+    return Number.isFinite(ms) && new Date(ms).toISOString() === value;
+};
+const isCount = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+/**
+ * Validate the accepted-chat fields of a stored node payload. Absent fields
+ * restore as empty; anything malformed or over the acceptance bounds is
+ * refused with one fixed error.
+ */
+export function validateStoredInput(data) {
+    const refuse = () => {
+        throw new Error(AUTOLOOP_RESTORE_MALFORMED);
+    };
+    if (data === undefined || data === null)
+        return { pendingChat: [], inFlightChat: null };
+    if (!isRecord(data))
+        return refuse();
+    const pendingChat = [];
+    if (data.pendingChat !== undefined) {
+        if (!Array.isArray(data.pendingChat) || data.pendingChat.length > MAX_PENDING_CHAT)
+            return refuse();
+        const ids = new Set();
+        for (const raw of data.pendingChat) {
+            if (!isRecord(raw))
+                return refuse();
+            const { msg_id, iter, ts, text } = raw;
+            if (typeof msg_id !== 'string' || msg_id.length === 0 || ids.has(msg_id))
+                return refuse();
+            if (!isCount(iter) || !isIsoTimestamp(ts) || typeof text !== 'string')
+                return refuse();
+            ids.add(msg_id);
+            pendingChat.push({ msg_id, iter, ts, text });
+        }
+        if (pendingChatBytes(pendingChat) > MAX_PENDING_CHAT_BYTES)
+            return refuse();
+    }
+    let inFlightChat = null;
+    if (data.inFlightChat !== undefined && data.inFlightChat !== null) {
+        const raw = data.inFlightChat;
+        if (!isRecord(raw) || typeof raw.msg_id !== 'string' || raw.msg_id.length === 0)
+            return refuse();
+        if (!isIsoTimestamp(raw.handed_at))
+            return refuse();
+        inFlightChat = { msg_id: raw.msg_id, handed_at: raw.handed_at };
+    }
+    let unconfirmed;
+    const state = data.state;
+    if (isRecord(state) && state.unconfirmed_chat !== undefined) {
+        const raw = state.unconfirmed_chat;
+        if (!isRecord(raw) || !isCount(raw.count) || !isIsoTimestamp(raw.last_at))
+            return refuse();
+        if (typeof raw.history_pending !== 'boolean')
+            return refuse();
+        unconfirmed = { count: raw.count, last_at: raw.last_at, history_pending: raw.history_pending };
+    }
+    return { pendingChat, inFlightChat, ...(unconfirmed ? { unconfirmed } : {}) };
+}
+function hasObligations(input) {
+    return Boolean(input && (input.pendingChat.length > 0 || input.inFlightChat || input.unconfirmed?.history_pending));
+}
+function nodePayload(handle, extra) {
+    const input = handle.runner.checkpointInput?.();
+    const state = { ...handle.runner.state };
+    if (input?.unconfirmed)
+        state.unconfirmed_chat = input.unconfirmed;
+    else
+        delete state.unconfirmed_chat;
+    return {
+        state,
+        plannerSession: handle.dispatcher.sessionNames.planner,
+        ...extra,
+        ...(input && input.pendingChat.length > 0 ? { pendingChat: input.pendingChat } : {}),
+        ...(input?.inFlightChat ? { inFlightChat: input.inFlightChat } : {}),
+    };
+}
 export function makeAutoloopExecutor(deps) {
     return async function executeAutoloopNode(node, ctx) {
         const spec = node;
+        const readyKey = ctx.tag ?? ctx.runId;
         let handle;
+        let restoredInput;
         try {
             // Kernel commits visits += 1 before execute; first visit in the run is fresh.
             const freshStart = ctx.record.nodes[node.id]?.visits === 1;
-            handle = await deps.boot(spec.config, ctx.secrets, { freshStart });
+            if (!freshStart)
+                restoredInput = validateStoredInput(ctx.record.nodes[node.id]?.data);
+            handle = await deps.boot(spec.config, ctx.secrets, { freshStart, restoredInput });
         }
         catch (err) {
-            deps.ready(ctx.tag ?? ctx.runId, err);
+            deps.ready(readyKey, err);
             return { ok: false, error: err.message };
         }
         ctx.setHandle(handle);
-        const publish = () => ctx.publish({
-            state: handle.runner.state,
-            plannerSession: handle.dispatcher.sessionNames.planner,
-            ...deps.extra(ctx.runId),
-        });
+        const publish = () => ctx.publish(nodePayload(handle, deps.extra(ctx.runId)));
         deps.registerPublisher(ctx.runId, publish);
-        publish();
+        if (!publish() && hasObligations(restoredInput)) {
+            // Restored chat that cannot be checkpointed must not be delivered.
+            deps.unregisterPublisher(ctx.runId);
+            handle.runner.stop();
+            await handle.dispatcher.shutdown('start-failed').catch(() => undefined);
+            deps.ready(readyKey, new Error(AUTOLOOP_RESTORE_UNPERSISTED));
+            return { ok: false, error: AUTOLOOP_RESTORE_UNPERSISTED };
+        }
         // The runner emits state after it writes pause fields (send timeout and
         // operator pause). Re-publish that snapshot so a non-owning autoloop_status
         // can read it while this process still owns the live handle.
         handle.runner.on('state', publish);
-        deps.ready(ctx.tag ?? ctx.runId, {
+        handle.runner.reconcileRestoredInput?.();
+        try {
+            await handle.afterPublishReconcile?.();
+        }
+        catch (err) {
+            handle.runner.off('state', publish);
+            deps.unregisterPublisher(ctx.runId);
+            handle.runner.stop();
+            await handle.dispatcher.shutdown('start-failed').catch(() => undefined);
+            deps.ready(readyKey, err);
+            return { ok: false, error: err.message };
+        }
+        deps.ready(readyKey, {
             plannerSession: handle.dispatcher.sessionNames.planner,
             state: handle.runner.state,
         });
+        handle.runner.releaseRestoredInput?.();
         try {
             await deps.waitForExit(handle, ctx.signal);
         }
@@ -54,11 +156,7 @@ export function makeAutoloopExecutor(deps) {
             ok: status !== 'crashed',
             output: `autoloop ${status} at iter ${handle.runner.state.iter}`,
             error: status === 'crashed' ? (handle.runner.state.status_reason ?? 'autoloop crashed') : undefined,
-            data: {
-                state: handle.runner.state,
-                plannerSession: handle.dispatcher.sessionNames.planner,
-                ...deps.extra(ctx.runId),
-            },
+            data: nodePayload(handle, deps.extra(ctx.runId)),
         };
     };
 }
@@ -75,8 +173,17 @@ export function autoloopStateFromRecord(record) {
     if (!data?.state)
         return undefined;
     const terminal = record.state === 'completed' || record.state === 'failed' || record.state === 'cancelled';
-    return terminal && data.state.status !== 'terminated' && data.state.status !== 'crashed'
+    const state = terminal && data.state.status !== 'terminated' && data.state.status !== 'crashed'
         ? { ...data.state, status: 'terminated', status_reason: data.state.status_reason ?? `run ${record.state}` }
         : data.state;
+    const inFlight = data.inFlightChat;
+    if (!isRecord(inFlight) || typeof inFlight.handed_at !== 'string')
+        return state;
+    // A stored marker is a delivery nobody has confirmed yet.
+    const prev = state.unconfirmed_chat;
+    return {
+        ...state,
+        unconfirmed_chat: { count: prev?.count ?? 0, last_at: prev?.last_at ?? inFlight.handed_at, history_pending: true },
+    };
 }
 //# sourceMappingURL=autoloop.js.map

package/dist/src/kernel/nodes/autoloop.js.map

@@ -1 +1 @@
-{"version":3,"file":"autoloop.js","sourceRoot":"","sources":["../../../../src/kernel/nodes/autoloop.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"autoloop.js","sourceRoot":"","sources":["../../../../src/kernel/nodes/autoloop.ts"],"names":[],"mappings":"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"}

package/dist/src/kernel/nodes/goal.d.ts

@@ -0,0 +1,94 @@
+/**
+ * `goal` node — a Codex `/goal` run on one `codex-app` thread.
+ *
+ * Codex's app-server runs a goal itself: `thread/goal/set` starts its turn loop,
+ * which keeps going until the goal is `complete`, out of budget, blocked, or
+ * stopped by a usage limit. What the kernel adds is what a long unattended run
+ * needs around that loop:
+ *
+ *  - **Reattach, never restart.** The thread id is checkpointed as soon as the
+ *    session opens. A resumed run hands it to `thread/resume`, and a resume
+ *    that comes back on a different thread fails the attempt instead of quietly
+ *    starting the objective over.
+ *  - **Resume what stalls, within a bound.** A usage-limited goal, a paused
+ *    one, or an active goal with no turn and no news for `stallMs` is set back
+ *    to `active` after a backoff. Every attempt counts before it is made, and
+ *    past `capacityRetry.max` the node fails for good.
+ *  - **Repair on the same thread.** Revisited after a red verifier, the node
+ *    sets a new objective on the thread it already has — the failing checks
+ *    first, then the original objective — so the agent keeps its context.
+ *  - **Steer live.** Text from `workflow_steer` goes into the running turn via
+ *    `turn/steer`; with no turn running it waits for the next one.
+ */
+import type { NodeContext, NodeResult } from '../engine.js';
+import type { NodeSpec } from '../types.js';
+export type GoalStatus = 'active' | 'paused' | 'blocked' | 'usageLimited' | 'budgetLimited' | 'complete';
+export interface GoalSnapshot {
+    objective: string;
+    status: GoalStatus;
+    tokenBudget: number | null;
+    tokensUsed: number;
+    timeUsedSeconds: number;
+}
+/** The `codex-app` surface this node drives. `PersistentCodexAppServerSession` implements it. */
+export interface GoalSession {
+    readonly codexThreadId: string | undefined;
+    readonly goal: GoalSnapshot | null;
+    readonly lastError: {
+        message: string;
+        code: string | null;
+        willRetry: boolean;
+        at: string;
+    } | null;
+    readonly turnActive: boolean;
+    setGoal(p: {
+        objective?: string;
+        status?: 'active' | 'paused';
+        tokenBudget?: number | null;
+    }): Promise<GoalSnapshot>;
+    getGoal(): Promise<GoalSnapshot | null>;
+    clearGoal(): Promise<void>;
+    steer(text: string): Promise<{
+        steered: boolean;
+    }>;
+    interrupt(): Promise<{
+        interrupted: boolean;
+    }>;
+    on(event: string, listener: (...args: unknown[]) => void): unknown;
+    off(event: string, listener: (...args: unknown[]) => void): unknown;
+}
+/** What the node checkpoints. Readable by `workflow_status` while the goal runs. */
+export interface GoalNodeData {
+    threadId: string;
+    objective: string;
+    status: GoalStatus | 'unset';
+    tokensUsed: number;
+    timeUsedSeconds: number;
+    /** Resume attempts made after a usage limit, a pause or a stall. */
+    resumes: number;
+    /** The agent's last reply, at most 4,000 characters from its end. */
+    lastMessage?: string;
+    /** The thread's spend so far, priced from codex's cumulative token totals. */
+    costUsd?: number;
+    /**
+     * How much of `costUsd` has been reported to the run. A result reports the
+     * difference, so spend from an attempt that never returned — the process was
+     * killed — is counted by the attempt that finally does.
+     */
+    reportedCostUsd?: number;
+    lastError?: {
+        message: string;
+        code: string | null;
+        at: string;
+    };
+}
+/** Codex refuses a goal objective longer than this many characters. */
+export declare const GOAL_OBJECTIVE_MAX_CHARS = 4000;
+/**
+ * The objective a revisit sets: what the agent must hear first (steers, the
+ * failing checks), then the original objective. The original always survives
+ * whole; when the two do not fit in Codex's limit the preface is cut, and the
+ * full check output stays in the run's evidence.
+ */
+export declare function composeObjective(preface: string[], objective: string): string;
+export declare function executeGoalNode(node: NodeSpec, ctx: NodeContext): Promise<NodeResult>;