@caupulican/pi-adaptative 0.81.41 → 0.81.43

package/dist/core/delegation/worker-agent-control-coordinator.js

@@ -0,0 +1,216 @@
+import { WorkerAgentMailbox } from "./worker-agent-control.js";
+/**
+ * Sole owner of model-facing logical-agent controls and their durable inboxes.
+ *
+ * It deliberately owns no worker execution policy, provider loop, or terminal persistence. Those
+ * controller-owned callbacks keep this narrow port from becoming a second lifecycle authority.
+ */
+export class WorkerAgentControlCoordinator {
+    constructor(options) {
+        this.mailboxes = new Map();
+        this.stateListeners = new Set();
+        this.options = options;
+    }
+    getProcessOwnerId() {
+        return this.options.processOwnerId;
+    }
+    sendWorkerAgentMessage(agentId, message) {
+        this.requireControl();
+        const agent = this.requireKnownAgent(agentId);
+        const queued = this.getMailbox(agent.agentId).enqueue({ kind: "follow_up", content: message });
+        this.signalStateChanged();
+        return { messageId: queued.messageId, queued: true };
+    }
+    followUpWorkerAgent(agentId, message) {
+        this.requireControl();
+        const agent = this.requireKnownAgent(agentId);
+        const canonicalAgentId = agent.agentId;
+        const active = agent.activeAttemptId
+            ? this.options.getLifecycle().getTaskRuntimeSnapshot().attempts[agent.activeAttemptId]
+            : undefined;
+        if (active?.status === "running" || active?.status === "leased") {
+            const queued = this.getMailbox(canonicalAgentId).enqueue({ kind: "steer", content: message });
+            this.signalStateChanged();
+            return { started: false, steering: true, messageId: queued.messageId };
+        }
+        if (agent.status !== "registered") {
+            return { started: false, steering: false, messageId: "", skipReason: `agent_${agent.status}` };
+        }
+        const queued = this.getMailbox(canonicalAgentId).enqueue({ kind: "follow_up", content: message });
+        try {
+            const prepared = this.options
+                .getLifecycle()
+                .prepareAgentTurn({ agentId: canonicalAgentId, instructions: message });
+            this.options.scheduler.enqueue(prepared.record, this.options.recoveredRequest(prepared.attempt));
+            this.options.statusChanged();
+            this.options.scheduler.drain();
+            this.signalStateChanged();
+            return { started: true, steering: false, messageId: queued.messageId, record: prepared.record };
+        }
+        catch (error) {
+            return {
+                started: false,
+                steering: false,
+                messageId: queued.messageId,
+                skipReason: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    interruptWorkerAgent(agentId) {
+        const { agent, attempt } = this.controlledAgentAttempt(agentId);
+        if (!attempt || (attempt.status !== "running" && attempt.status !== "leased")) {
+            return { interrupted: false, reason: "agent_not_running" };
+        }
+        try {
+            this.options.getLifecycle().suspendAgent(attempt.taskId, agent.agentId, this.options.processOwnerId);
+            this.options.abortLane(attempt.taskId, "agent_interrupted");
+            this.signalStateChanged();
+            return { interrupted: true };
+        }
+        catch (error) {
+            return { interrupted: false, reason: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    resumeWorkerAgent(agentId) {
+        const { attempt } = this.controlledAgentAttempt(agentId);
+        if (!attempt || attempt.status !== "suspended")
+            return { started: false, skipReason: "agent_not_suspended" };
+        const record = this.options.getLifecycle().getRecord(attempt.taskId);
+        if (!record)
+            return { started: false, skipReason: "orchestration_projection_missing" };
+        const promise = this.options.run(this.options.recoveredRequest(attempt), record);
+        this.options.scheduler.track(record.laneId, promise);
+        this.signalStateChanged();
+        return { started: true, record };
+    }
+    cancelWorkerAgent(agentId, reasonCode = "agent_cancelled") {
+        const { attempt } = this.controlledAgentAttempt(agentId);
+        if (!attempt)
+            return undefined;
+        this.options.abortLane(attempt.taskId, reasonCode);
+        const record = this.options.cancelLane(attempt.taskId, reasonCode);
+        this.signalStateChanged();
+        return record;
+    }
+    /** Event-driven wait: durable projection plus state/mailbox notifications, never output polling. */
+    waitForWorkerAgent(agentId, timeoutMs = 30_000) {
+        this.requireControl();
+        const canonicalAgentId = agentId.trim();
+        const boundedTimeoutMs = Number.isFinite(timeoutMs)
+            ? Math.max(1, Math.min(Math.floor(timeoutMs), 300_000))
+            : 30_000;
+        const currentStatus = () => {
+            const agent = this.options.getLifecycle().getAgent(canonicalAgentId);
+            if (!agent)
+                return "unknown";
+            if (agent.status === "active" || agent.status === "resuming")
+                return "active";
+            if (agent.status === "suspended")
+                return "suspended";
+            return "idle";
+        };
+        const immediate = currentStatus();
+        if (immediate !== "active")
+            return Promise.resolve({ status: immediate });
+        return new Promise((resolve) => {
+            let settled = false;
+            const settle = () => {
+                if (settled)
+                    return;
+                const next = currentStatus();
+                if (next === "active")
+                    return;
+                settled = true;
+                unsubscribeMailbox();
+                unsubscribeState();
+                clearTimeout(timeout);
+                resolve({ status: next });
+            };
+            const unsubscribeMailbox = this.getMailbox(canonicalAgentId).subscribe(settle);
+            const unsubscribeState = this.subscribeStateChanges(settle);
+            const timeout = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                unsubscribeMailbox();
+                unsubscribeState();
+                resolve({ status: currentStatus() });
+            }, boundedTimeoutMs);
+            if (typeof timeout === "object" && "unref" in timeout)
+                timeout.unref();
+        });
+    }
+    /** Read mailbox items at a safe boundary and reconcile the narrow append-before-ack crash window. */
+    mailboxMessagesForConversation(agentId, conversation, includeFollowUp) {
+        const mailbox = this.getMailbox(agentId);
+        const pending = mailbox.pending();
+        if (pending.length === 0)
+            return [];
+        const delivered = conversation.findDeliveredWorkerControlMessageIds(pending.map((message) => message.messageId));
+        for (const messageId of delivered)
+            mailbox.acknowledgeDelivered(messageId);
+        return mailbox
+            .pending()
+            .filter((message) => message.kind === "steer" || includeFollowUp)
+            .map((message) => this.mailboxMessage(message));
+    }
+    /** Acknowledge only after the exact child transcript message has been durably appended. */
+    acknowledgeMailboxMessage(agentId, message) {
+        if (message.role !== "user" || typeof message.content !== "string")
+            return;
+        const messageId = /^\[Worker control (worker-message-[^\]]+)\]\n/.exec(message.content)?.[1];
+        if (messageId)
+            this.getMailbox(agentId).acknowledgeDelivered(messageId);
+    }
+    /** Called by controller-owned execution transitions after lifecycle state changed. */
+    signalStateChanged() {
+        for (const listener of this.stateListeners)
+            listener();
+    }
+    requireControl() {
+        if (!this.options.isControlAvailable()) {
+            throw new Error("Worker delegation control is unavailable in this UAC surface.");
+        }
+    }
+    requireKnownAgent(agentId) {
+        const normalized = agentId.trim();
+        if (!normalized)
+            throw new Error("Logical worker agent id is required.");
+        const agent = this.options.getLifecycle().getAgent(normalized);
+        if (!agent)
+            throw new Error(`Unknown logical worker agent '${normalized}'.`);
+        return agent;
+    }
+    controlledAgentAttempt(agentId) {
+        this.requireControl();
+        const agent = this.requireKnownAgent(agentId);
+        const attempt = agent.activeAttemptId
+            ? this.options.getLifecycle().getTaskRuntimeSnapshot().attempts[agent.activeAttemptId]
+            : undefined;
+        return { agent, attempt };
+    }
+    getMailbox(agentId) {
+        let mailbox = this.mailboxes.get(agentId);
+        if (!mailbox) {
+            mailbox = new WorkerAgentMailbox({
+                agentDir: this.options.agentDir,
+                parentSessionId: this.options.parentSessionId,
+                agentId,
+            });
+            this.mailboxes.set(agentId, mailbox);
+        }
+        return mailbox;
+    }
+    subscribeStateChanges(listener) {
+        this.stateListeners.add(listener);
+        return () => this.stateListeners.delete(listener);
+    }
+    mailboxMessage(message) {
+        return {
+            role: "user",
+            content: `[Worker control ${message.messageId}]\n${message.content}`,
+            timestamp: Date.now(),
+        };
+    }
+}
+//# sourceMappingURL=worker-agent-control-coordinator.js.map

package/dist/core/delegation/worker-agent-control-coordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-agent-control-coordinator.js","sourceRoot":"","sources":["../../../src/core/delegation/worker-agent-control-coordinator.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AgentMessage } from \"@caupulican/pi-agent-core\";\nimport type { WorkerDelegationRunOutcome } from \"../agent-session-contracts.ts\";\nimport type { LaneRecord } from \"../autonomy/lane-tracker.ts\";\nimport type { AgentBindingContract } from \"../orchestration/contracts.ts\";\nimport type { AttemptRuntimeState } from \"../orchestration/task-runtime.ts\";\nimport { type WorkerAgentControlPort, WorkerAgentMailbox, type WorkerAgentMessage } from \"./worker-agent-control.ts\";\nimport type { WorkerConversation } from \"./worker-conversation-store.ts\";\nimport type { WorkerDelegationRequest } from \"./worker-delegation-request.ts\";\nimport type { WorkerDispatchScheduler } from \"./worker-dispatch-scheduler.ts\";\nimport type { WorkerLifecycle } from \"./worker-lifecycle.ts\";\n\nexport interface WorkerAgentControlCoordinatorOptions {\n\tagentDir: string;\n\tparentSessionId: string;\n\tprocessOwnerId: string;\n\tisControlAvailable(): boolean;\n\tgetLifecycle(): WorkerLifecycle;\n\trecoveredRequest(attempt: AttemptRuntimeState): WorkerDelegationRequest;\n\trun(request: WorkerDelegationRequest, record: LaneRecord): Promise<WorkerDelegationRunOutcome>;\n\tscheduler: Pick<WorkerDispatchScheduler, \"enqueue\" | \"track\" | \"drain\">;\n\tstatusChanged(): void;\n\tabortLane(laneId: string, reasonCode: string): void;\n\tcancelLane(laneId: string, reasonCode: string): LaneRecord | undefined;\n}\n\n/**\n * Sole owner of model-facing logical-agent controls and their durable inboxes.\n *\n * It deliberately owns no worker execution policy, provider loop, or terminal persistence. Those\n * controller-owned callbacks keep this narrow port from becoming a second lifecycle authority.\n */\nexport class WorkerAgentControlCoordinator implements WorkerAgentControlPort {\n\tprivate readonly options: WorkerAgentControlCoordinatorOptions;\n\tprivate readonly mailboxes = new Map<string, WorkerAgentMailbox>();\n\tprivate readonly stateListeners = new Set<() => void>();\n\n\tconstructor(options: WorkerAgentControlCoordinatorOptions) {\n\t\tthis.options = options;\n\t}\n\n\tgetProcessOwnerId(): string {\n\t\treturn this.options.processOwnerId;\n\t}\n\n\tsendWorkerAgentMessage(agentId: string, message: string): { messageId: string; queued: true } {\n\t\tthis.requireControl();\n\t\tconst agent = this.requireKnownAgent(agentId);\n\t\tconst queued = this.getMailbox(agent.agentId).enqueue({ kind: \"follow_up\", content: message });\n\t\tthis.signalStateChanged();\n\t\treturn { messageId: queued.messageId, queued: true };\n\t}\n\n\tfollowUpWorkerAgent(\n\t\tagentId: string,\n\t\tmessage: string,\n\t): { started: boolean; steering: boolean; messageId: string; record?: LaneRecord; skipReason?: string } {\n\t\tthis.requireControl();\n\t\tconst agent = this.requireKnownAgent(agentId);\n\t\tconst canonicalAgentId = agent.agentId;\n\t\tconst active = agent.activeAttemptId\n\t\t\t? this.options.getLifecycle().getTaskRuntimeSnapshot().attempts[agent.activeAttemptId]\n\t\t\t: undefined;\n\t\tif (active?.status === \"running\" || active?.status === \"leased\") {\n\t\t\tconst queued = this.getMailbox(canonicalAgentId).enqueue({ kind: \"steer\", content: message });\n\t\t\tthis.signalStateChanged();\n\t\t\treturn { started: false, steering: true, messageId: queued.messageId };\n\t\t}\n\t\tif (agent.status !== \"registered\") {\n\t\t\treturn { started: false, steering: false, messageId: \"\", skipReason: `agent_${agent.status}` };\n\t\t}\n\t\tconst queued = this.getMailbox(canonicalAgentId).enqueue({ kind: \"follow_up\", content: message });\n\t\ttry {\n\t\t\tconst prepared = this.options\n\t\t\t\t.getLifecycle()\n\t\t\t\t.prepareAgentTurn({ agentId: canonicalAgentId, instructions: message });\n\t\t\tthis.options.scheduler.enqueue(prepared.record, this.options.recoveredRequest(prepared.attempt));\n\t\t\tthis.options.statusChanged();\n\t\t\tthis.options.scheduler.drain();\n\t\t\tthis.signalStateChanged();\n\t\t\treturn { started: true, steering: false, messageId: queued.messageId, record: prepared.record };\n\t\t} catch (error) {\n\t\t\treturn {\n\t\t\t\tstarted: false,\n\t\t\t\tsteering: false,\n\t\t\t\tmessageId: queued.messageId,\n\t\t\t\tskipReason: error instanceof Error ? error.message : String(error),\n\t\t\t};\n\t\t}\n\t}\n\n\tinterruptWorkerAgent(agentId: string): { interrupted: boolean; reason?: string } {\n\t\tconst { agent, attempt } = this.controlledAgentAttempt(agentId);\n\t\tif (!attempt || (attempt.status !== \"running\" && attempt.status !== \"leased\")) {\n\t\t\treturn { interrupted: false, reason: \"agent_not_running\" };\n\t\t}\n\t\ttry {\n\t\t\tthis.options.getLifecycle().suspendAgent(attempt.taskId, agent.agentId, this.options.processOwnerId);\n\t\t\tthis.options.abortLane(attempt.taskId, \"agent_interrupted\");\n\t\t\tthis.signalStateChanged();\n\t\t\treturn { interrupted: true };\n\t\t} catch (error) {\n\t\t\treturn { interrupted: false, reason: error instanceof Error ? error.message : String(error) };\n\t\t}\n\t}\n\n\tresumeWorkerAgent(agentId: string): { started: boolean; record?: LaneRecord; skipReason?: string } {\n\t\tconst { attempt } = this.controlledAgentAttempt(agentId);\n\t\tif (!attempt || attempt.status !== \"suspended\") return { started: false, skipReason: \"agent_not_suspended\" };\n\t\tconst record = this.options.getLifecycle().getRecord(attempt.taskId);\n\t\tif (!record) return { started: false, skipReason: \"orchestration_projection_missing\" };\n\t\tconst promise = this.options.run(this.options.recoveredRequest(attempt), record);\n\t\tthis.options.scheduler.track(record.laneId, promise);\n\t\tthis.signalStateChanged();\n\t\treturn { started: true, record };\n\t}\n\n\tcancelWorkerAgent(agentId: string, reasonCode = \"agent_cancelled\"): LaneRecord | undefined {\n\t\tconst { attempt } = this.controlledAgentAttempt(agentId);\n\t\tif (!attempt) return undefined;\n\t\tthis.options.abortLane(attempt.taskId, reasonCode);\n\t\tconst record = this.options.cancelLane(attempt.taskId, reasonCode);\n\t\tthis.signalStateChanged();\n\t\treturn record;\n\t}\n\n\t/** Event-driven wait: durable projection plus state/mailbox notifications, never output polling. */\n\twaitForWorkerAgent(\n\t\tagentId: string,\n\t\ttimeoutMs = 30_000,\n\t): Promise<{ status: \"active\" | \"suspended\" | \"idle\" | \"unknown\" }> {\n\t\tthis.requireControl();\n\t\tconst canonicalAgentId = agentId.trim();\n\t\tconst boundedTimeoutMs = Number.isFinite(timeoutMs)\n\t\t\t? Math.max(1, Math.min(Math.floor(timeoutMs), 300_000))\n\t\t\t: 30_000;\n\t\tconst currentStatus = (): \"active\" | \"suspended\" | \"idle\" | \"unknown\" => {\n\t\t\tconst agent = this.options.getLifecycle().getAgent(canonicalAgentId);\n\t\t\tif (!agent) return \"unknown\";\n\t\t\tif (agent.status === \"active\" || agent.status === \"resuming\") return \"active\";\n\t\t\tif (agent.status === \"suspended\") return \"suspended\";\n\t\t\treturn \"idle\";\n\t\t};\n\t\tconst immediate = currentStatus();\n\t\tif (immediate !== \"active\") return Promise.resolve({ status: immediate });\n\t\treturn new Promise((resolve) => {\n\t\t\tlet settled = false;\n\t\t\tconst settle = () => {\n\t\t\t\tif (settled) return;\n\t\t\t\tconst next = currentStatus();\n\t\t\t\tif (next === \"active\") return;\n\t\t\t\tsettled = true;\n\t\t\t\tunsubscribeMailbox();\n\t\t\t\tunsubscribeState();\n\t\t\t\tclearTimeout(timeout);\n\t\t\t\tresolve({ status: next });\n\t\t\t};\n\t\t\tconst unsubscribeMailbox = this.getMailbox(canonicalAgentId).subscribe(settle);\n\t\t\tconst unsubscribeState = this.subscribeStateChanges(settle);\n\t\t\tconst timeout = setTimeout(() => {\n\t\t\t\tif (settled) return;\n\t\t\t\tsettled = true;\n\t\t\t\tunsubscribeMailbox();\n\t\t\t\tunsubscribeState();\n\t\t\t\tresolve({ status: currentStatus() });\n\t\t\t}, boundedTimeoutMs);\n\t\t\tif (typeof timeout === \"object\" && \"unref\" in timeout) timeout.unref();\n\t\t});\n\t}\n\n\t/** Read mailbox items at a safe boundary and reconcile the narrow append-before-ack crash window. */\n\tmailboxMessagesForConversation(\n\t\tagentId: string,\n\t\tconversation: WorkerConversation,\n\t\tincludeFollowUp: boolean,\n\t): AgentMessage[] {\n\t\tconst mailbox = this.getMailbox(agentId);\n\t\tconst pending = mailbox.pending();\n\t\tif (pending.length === 0) return [];\n\t\tconst delivered = conversation.findDeliveredWorkerControlMessageIds(pending.map((message) => message.messageId));\n\t\tfor (const messageId of delivered) mailbox.acknowledgeDelivered(messageId);\n\t\treturn mailbox\n\t\t\t.pending()\n\t\t\t.filter((message) => message.kind === \"steer\" || includeFollowUp)\n\t\t\t.map((message) => this.mailboxMessage(message));\n\t}\n\n\t/** Acknowledge only after the exact child transcript message has been durably appended. */\n\tacknowledgeMailboxMessage(agentId: string, message: { role: string; content: unknown }): void {\n\t\tif (message.role !== \"user\" || typeof message.content !== \"string\") return;\n\t\tconst messageId = /^\\[Worker control (worker-message-[^\\]]+)\\]\\n/.exec(message.content)?.[1];\n\t\tif (messageId) this.getMailbox(agentId).acknowledgeDelivered(messageId);\n\t}\n\n\t/** Called by controller-owned execution transitions after lifecycle state changed. */\n\tsignalStateChanged(): void {\n\t\tfor (const listener of this.stateListeners) listener();\n\t}\n\n\tprivate requireControl(): void {\n\t\tif (!this.options.isControlAvailable()) {\n\t\t\tthrow new Error(\"Worker delegation control is unavailable in this UAC surface.\");\n\t\t}\n\t}\n\n\tprivate requireKnownAgent(agentId: string): AgentBindingContract {\n\t\tconst normalized = agentId.trim();\n\t\tif (!normalized) throw new Error(\"Logical worker agent id is required.\");\n\t\tconst agent = this.options.getLifecycle().getAgent(normalized);\n\t\tif (!agent) throw new Error(`Unknown logical worker agent '${normalized}'.`);\n\t\treturn agent;\n\t}\n\n\tprivate controlledAgentAttempt(agentId: string): {\n\t\tagent: AgentBindingContract;\n\t\tattempt: AttemptRuntimeState | undefined;\n\t} {\n\t\tthis.requireControl();\n\t\tconst agent = this.requireKnownAgent(agentId);\n\t\tconst attempt = agent.activeAttemptId\n\t\t\t? this.options.getLifecycle().getTaskRuntimeSnapshot().attempts[agent.activeAttemptId]\n\t\t\t: undefined;\n\t\treturn { agent, attempt };\n\t}\n\n\tprivate getMailbox(agentId: string): WorkerAgentMailbox {\n\t\tlet mailbox = this.mailboxes.get(agentId);\n\t\tif (!mailbox) {\n\t\t\tmailbox = new WorkerAgentMailbox({\n\t\t\t\tagentDir: this.options.agentDir,\n\t\t\t\tparentSessionId: this.options.parentSessionId,\n\t\t\t\tagentId,\n\t\t\t});\n\t\t\tthis.mailboxes.set(agentId, mailbox);\n\t\t}\n\t\treturn mailbox;\n\t}\n\n\tprivate subscribeStateChanges(listener: () => void): () => void {\n\t\tthis.stateListeners.add(listener);\n\t\treturn () => this.stateListeners.delete(listener);\n\t}\n\n\tprivate mailboxMessage(message: WorkerAgentMessage): AgentMessage {\n\t\treturn {\n\t\t\trole: \"user\",\n\t\t\tcontent: `[Worker control ${message.messageId}]\\n${message.content}`,\n\t\t\ttimestamp: Date.now(),\n\t\t};\n\t}\n}\n"]}

package/dist/core/delegation/worker-agent-control.d.ts

@@ -0,0 +1,66 @@
+import type { LaneRecord } from "../autonomy/lane-tracker.ts";
+export type WorkerAgentMessageKind = "steer" | "follow_up";
+export interface WorkerAgentMessage {
+    messageId: string;
+    kind: WorkerAgentMessageKind;
+    content: string;
+    createdAt: string;
+    deliveredAt?: string;
+}
+export interface WorkerAgentMailboxOptions {
+    agentDir: string;
+    parentSessionId: string;
+    agentId: string;
+}
+/** One canonical host port for model-facing logical-agent controls. */
+export interface WorkerAgentControlPort {
+    sendWorkerAgentMessage(agentId: string, message: string): {
+        messageId: string;
+        queued: true;
+    };
+    followUpWorkerAgent(agentId: string, message: string): {
+        started: boolean;
+        steering: boolean;
+        messageId: string;
+        record?: LaneRecord;
+        skipReason?: string;
+    };
+    interruptWorkerAgent(agentId: string): {
+        interrupted: boolean;
+        reason?: string;
+    };
+    resumeWorkerAgent(agentId: string): {
+        started: boolean;
+        record?: LaneRecord;
+        skipReason?: string;
+    };
+    cancelWorkerAgent(agentId: string, reasonCode?: string): LaneRecord | undefined;
+    waitForWorkerAgent(agentId: string, timeoutMs?: number): Promise<{
+        status: "active" | "suspended" | "idle" | "unknown";
+    }>;
+}
+/**
+ * Bounded durable inbox for a single logical worker agent.
+ *
+ * A message is never considered delivered merely because a controller read it. Its caller must
+ * acknowledge it only after the exact corresponding user message has been appended to the child
+ * WorkerConversation. The in-process subscription is a notification edge, not a polling loop.
+ */
+export declare class WorkerAgentMailbox {
+    private readonly parentSessionId;
+    private readonly agentId;
+    private readonly file;
+    private readonly listeners;
+    constructor(options: WorkerAgentMailboxOptions);
+    enqueue(input: {
+        kind: WorkerAgentMessageKind;
+        content: string;
+    }): WorkerAgentMessage;
+    pending(kind?: WorkerAgentMessageKind): WorkerAgentMessage[];
+    acknowledgeDelivered(messageId: string): void;
+    subscribe(listener: () => void): () => void;
+    private notify;
+    private read;
+    private update;
+}
+//# sourceMappingURL=worker-agent-control.d.ts.map

package/dist/core/delegation/worker-agent-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-agent-control.d.ts","sourceRoot":"","sources":["../../../src/core/delegation/worker-agent-control.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAU9D,MAAM,MAAM,sBAAsB,GAAG,OAAO,GAAG,WAAW,CAAC;AAE3D,MAAM,WAAW,kBAAkB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,sBAAsB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AASD,MAAM,WAAW,yBAAyB;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,uEAAuE;AACvE,MAAM,WAAW,sBAAsB;IACtC,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,IAAI,CAAA;KAAE,CAAC;IAC9F,mBAAmB,CAClB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACb;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,UAAU,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxG,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG;QAAE,WAAW,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjF,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,UAAU,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnG,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAChF,kBAAkB,CACjB,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC;QAAE,MAAM,EAAE,QAAQ,GAAG,WAAW,GAAG,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC,CAAC;CACpE;AAwED;;;;;;GAMG;AACH,qBAAa,kBAAkB;IAC9B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IAEnD,YAAY,OAAO,EAAE,yBAAyB,EAQ7C;IAED,OAAO,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,sBAAsB,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,kBAAkB,CAsBpF;IAED,OAAO,CAAC,IAAI,CAAC,EAAE,sBAAsB,GAAG,kBAAkB,EAAE,CAM3D;IAED,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAa5C;IAED,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAG1C;IAED,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,IAAI;IAWZ,OAAO,CAAC,MAAM;CAWd"}

package/dist/core/delegation/worker-agent-control.js

@@ -0,0 +1,160 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { workerAgentMailboxFile } from "../agent-paths.js";
+import { withFileLockSync, writeFileAtomicSync } from "../util/atomic-file.js";
+import { readBoundedTextFileSync } from "../util/bounded-file.js";
+const MAX_MAILBOX_MESSAGES = 64;
+const MAX_MAILBOX_MESSAGE_CHARS = 4_096;
+const MAX_MAILBOX_BYTES = 128 * 1024;
+const MAX_MAILBOX_MESSAGE_ID_CHARS = 512;
+const MAX_MAILBOX_TIMESTAMP_CHARS = 128;
+function mailboxDigest(parentSessionId, agentId) {
+    return createHash("sha256")
+        .update("pi-worker-agent-mailbox-v1")
+        .update("\0")
+        .update(parentSessionId)
+        .update("\0")
+        .update(agentId)
+        .digest("hex");
+}
+function assertIdentity(value, label) {
+    const normalized = value.trim();
+    if (!normalized)
+        throw new TypeError(`A worker ${label} is required.`);
+    if (normalized.length > 512)
+        throw new TypeError(`Worker ${label} exceeds 512 characters.`);
+    return normalized;
+}
+function parseState(raw, parentSessionId, agentId) {
+    let candidate;
+    try {
+        candidate = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("Worker agent mailbox is invalid JSON.");
+    }
+    if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+        throw new Error("Worker agent mailbox is invalid.");
+    }
+    const state = candidate;
+    if (state.version !== 1 ||
+        state.parentSessionId !== parentSessionId ||
+        state.agentId !== agentId ||
+        !Array.isArray(state.messages)) {
+        throw new Error("Worker agent mailbox identity conflicts with the requested logical worker.");
+    }
+    const messages = state.messages.map((message) => {
+        if (!message ||
+            typeof message !== "object" ||
+            Array.isArray(message) ||
+            typeof message.messageId !== "string" ||
+            message.messageId.length === 0 ||
+            message.messageId.length > MAX_MAILBOX_MESSAGE_ID_CHARS ||
+            (message.kind !== "steer" && message.kind !== "follow_up") ||
+            typeof message.content !== "string" ||
+            message.content.length === 0 ||
+            message.content.length > MAX_MAILBOX_MESSAGE_CHARS ||
+            typeof message.createdAt !== "string" ||
+            message.createdAt.length === 0 ||
+            message.createdAt.length > MAX_MAILBOX_TIMESTAMP_CHARS ||
+            (message.deliveredAt !== undefined &&
+                (typeof message.deliveredAt !== "string" ||
+                    message.deliveredAt.length === 0 ||
+                    message.deliveredAt.length > MAX_MAILBOX_TIMESTAMP_CHARS))) {
+            throw new Error("Worker agent mailbox contains an invalid message.");
+        }
+        return { ...message };
+    });
+    const pendingMessages = messages.filter((message) => message.deliveredAt === undefined);
+    if (pendingMessages.length > MAX_MAILBOX_MESSAGES)
+        throw new Error("Worker agent mailbox exceeds its pending-message bound.");
+    return { version: 1, parentSessionId, agentId, messages: pendingMessages };
+}
+function encodedStateBytes(state) {
+    return Buffer.byteLength(JSON.stringify(state), "utf-8");
+}
+/**
+ * Bounded durable inbox for a single logical worker agent.
+ *
+ * A message is never considered delivered merely because a controller read it. Its caller must
+ * acknowledge it only after the exact corresponding user message has been appended to the child
+ * WorkerConversation. The in-process subscription is a notification edge, not a polling loop.
+ */
+export class WorkerAgentMailbox {
+    constructor(options) {
+        this.listeners = new Set();
+        this.parentSessionId = assertIdentity(options.parentSessionId, "parent session id");
+        this.agentId = assertIdentity(options.agentId, "agent id");
+        this.file = workerAgentMailboxFile(options.agentDir, this.parentSessionId, mailboxDigest(this.parentSessionId, this.agentId));
+    }
+    enqueue(input) {
+        const content = input.content.trim();
+        if (!content)
+            throw new TypeError("A worker control message is required.");
+        if (content.length > MAX_MAILBOX_MESSAGE_CHARS) {
+            throw new TypeError(`Worker control messages may not exceed ${MAX_MAILBOX_MESSAGE_CHARS.toLocaleString("en-US")} characters.`);
+        }
+        const message = {
+            messageId: `worker-message-${randomUUID()}`,
+            kind: input.kind,
+            content,
+            createdAt: new Date().toISOString(),
+        };
+        this.update((state) => {
+            if (state.messages.length >= MAX_MAILBOX_MESSAGES) {
+                throw new Error(`Worker agent mailbox reached its ${MAX_MAILBOX_MESSAGES} message limit.`);
+            }
+            return { ...state, messages: [...state.messages, message] };
+        });
+        this.notify();
+        return structuredClone(message);
+    }
+    pending(kind) {
+        return this.read()
+            .messages.filter((message) => message.deliveredAt === undefined && (kind === undefined || message.kind === kind))
+            .map((message) => structuredClone(message));
+    }
+    acknowledgeDelivered(messageId) {
+        const normalized = messageId.trim();
+        if (!normalized)
+            throw new TypeError("A worker control message id is required.");
+        let changed = false;
+        this.update((state) => {
+            const messages = state.messages.filter((message) => {
+                if (message.messageId !== normalized)
+                    return true;
+                changed = true;
+                return false;
+            });
+            return changed ? { ...state, messages } : state;
+        });
+        if (changed)
+            this.notify();
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    notify() {
+        for (const listener of this.listeners)
+            listener();
+    }
+    read() {
+        if (!existsSync(this.file)) {
+            return { version: 1, parentSessionId: this.parentSessionId, agentId: this.agentId, messages: [] };
+        }
+        return parseState(readBoundedTextFileSync(this.file, MAX_MAILBOX_BYTES, "Worker agent mailbox durable size bound"), this.parentSessionId, this.agentId);
+    }
+    update(mutator) {
+        withFileLockSync(this.file, () => {
+            const state = this.read();
+            const next = mutator(state);
+            if (next.messages.length > MAX_MAILBOX_MESSAGES || encodedStateBytes(next) > MAX_MAILBOX_BYTES) {
+                throw new Error("Worker agent mailbox exceeds its durable size bound.");
+            }
+            if (JSON.stringify(next) !== JSON.stringify(state))
+                writeFileAtomicSync(this.file, `${JSON.stringify(next)}\n`, { mode: 0o600 });
+        });
+    }
+}
+//# sourceMappingURL=worker-agent-control.js.map

package/dist/core/delegation/worker-agent-control.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-agent-control.js","sourceRoot":"","sources":["../../../src/core/delegation/worker-agent-control.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash, randomUUID } from \"node:crypto\";\nimport { existsSync } from \"node:fs\";\nimport { workerAgentMailboxFile } from \"../agent-paths.ts\";\nimport type { LaneRecord } from \"../autonomy/lane-tracker.ts\";\nimport { withFileLockSync, writeFileAtomicSync } from \"../util/atomic-file.ts\";\nimport { readBoundedTextFileSync } from \"../util/bounded-file.ts\";\n\nconst MAX_MAILBOX_MESSAGES = 64;\nconst MAX_MAILBOX_MESSAGE_CHARS = 4_096;\nconst MAX_MAILBOX_BYTES = 128 * 1024;\nconst MAX_MAILBOX_MESSAGE_ID_CHARS = 512;\nconst MAX_MAILBOX_TIMESTAMP_CHARS = 128;\n\nexport type WorkerAgentMessageKind = \"steer\" | \"follow_up\";\n\nexport interface WorkerAgentMessage {\n\tmessageId: string;\n\tkind: WorkerAgentMessageKind;\n\tcontent: string;\n\tcreatedAt: string;\n\tdeliveredAt?: string;\n}\n\ninterface WorkerAgentMailboxState {\n\tversion: 1;\n\tparentSessionId: string;\n\tagentId: string;\n\tmessages: WorkerAgentMessage[];\n}\n\nexport interface WorkerAgentMailboxOptions {\n\tagentDir: string;\n\tparentSessionId: string;\n\tagentId: string;\n}\n\n/** One canonical host port for model-facing logical-agent controls. */\nexport interface WorkerAgentControlPort {\n\tsendWorkerAgentMessage(agentId: string, message: string): { messageId: string; queued: true };\n\tfollowUpWorkerAgent(\n\t\tagentId: string,\n\t\tmessage: string,\n\t): { started: boolean; steering: boolean; messageId: string; record?: LaneRecord; skipReason?: string };\n\tinterruptWorkerAgent(agentId: string): { interrupted: boolean; reason?: string };\n\tresumeWorkerAgent(agentId: string): { started: boolean; record?: LaneRecord; skipReason?: string };\n\tcancelWorkerAgent(agentId: string, reasonCode?: string): LaneRecord | undefined;\n\twaitForWorkerAgent(\n\t\tagentId: string,\n\t\ttimeoutMs?: number,\n\t): Promise<{ status: \"active\" | \"suspended\" | \"idle\" | \"unknown\" }>;\n}\n\nfunction mailboxDigest(parentSessionId: string, agentId: string): string {\n\treturn createHash(\"sha256\")\n\t\t.update(\"pi-worker-agent-mailbox-v1\")\n\t\t.update(\"\\0\")\n\t\t.update(parentSessionId)\n\t\t.update(\"\\0\")\n\t\t.update(agentId)\n\t\t.digest(\"hex\");\n}\n\nfunction assertIdentity(value: string, label: string): string {\n\tconst normalized = value.trim();\n\tif (!normalized) throw new TypeError(`A worker ${label} is required.`);\n\tif (normalized.length > 512) throw new TypeError(`Worker ${label} exceeds 512 characters.`);\n\treturn normalized;\n}\n\nfunction parseState(raw: string, parentSessionId: string, agentId: string): WorkerAgentMailboxState {\n\tlet candidate: unknown;\n\ttry {\n\t\tcandidate = JSON.parse(raw);\n\t} catch {\n\t\tthrow new Error(\"Worker agent mailbox is invalid JSON.\");\n\t}\n\tif (!candidate || typeof candidate !== \"object\" || Array.isArray(candidate)) {\n\t\tthrow new Error(\"Worker agent mailbox is invalid.\");\n\t}\n\tconst state = candidate as Partial<WorkerAgentMailboxState>;\n\tif (\n\t\tstate.version !== 1 ||\n\t\tstate.parentSessionId !== parentSessionId ||\n\t\tstate.agentId !== agentId ||\n\t\t!Array.isArray(state.messages)\n\t) {\n\t\tthrow new Error(\"Worker agent mailbox identity conflicts with the requested logical worker.\");\n\t}\n\tconst messages = state.messages.map((message): WorkerAgentMessage => {\n\t\tif (\n\t\t\t!message ||\n\t\t\ttypeof message !== \"object\" ||\n\t\t\tArray.isArray(message) ||\n\t\t\ttypeof message.messageId !== \"string\" ||\n\t\t\tmessage.messageId.length === 0 ||\n\t\t\tmessage.messageId.length > MAX_MAILBOX_MESSAGE_ID_CHARS ||\n\t\t\t(message.kind !== \"steer\" && message.kind !== \"follow_up\") ||\n\t\t\ttypeof message.content !== \"string\" ||\n\t\t\tmessage.content.length === 0 ||\n\t\t\tmessage.content.length > MAX_MAILBOX_MESSAGE_CHARS ||\n\t\t\ttypeof message.createdAt !== \"string\" ||\n\t\t\tmessage.createdAt.length === 0 ||\n\t\t\tmessage.createdAt.length > MAX_MAILBOX_TIMESTAMP_CHARS ||\n\t\t\t(message.deliveredAt !== undefined &&\n\t\t\t\t(typeof message.deliveredAt !== \"string\" ||\n\t\t\t\t\tmessage.deliveredAt.length === 0 ||\n\t\t\t\t\tmessage.deliveredAt.length > MAX_MAILBOX_TIMESTAMP_CHARS))\n\t\t) {\n\t\t\tthrow new Error(\"Worker agent mailbox contains an invalid message.\");\n\t\t}\n\t\treturn { ...message };\n\t});\n\tconst pendingMessages = messages.filter((message) => message.deliveredAt === undefined);\n\tif (pendingMessages.length > MAX_MAILBOX_MESSAGES)\n\t\tthrow new Error(\"Worker agent mailbox exceeds its pending-message bound.\");\n\treturn { version: 1, parentSessionId, agentId, messages: pendingMessages };\n}\n\nfunction encodedStateBytes(state: WorkerAgentMailboxState): number {\n\treturn Buffer.byteLength(JSON.stringify(state), \"utf-8\");\n}\n\n/**\n * Bounded durable inbox for a single logical worker agent.\n *\n * A message is never considered delivered merely because a controller read it. Its caller must\n * acknowledge it only after the exact corresponding user message has been appended to the child\n * WorkerConversation. The in-process subscription is a notification edge, not a polling loop.\n */\nexport class WorkerAgentMailbox {\n\tprivate readonly parentSessionId: string;\n\tprivate readonly agentId: string;\n\tprivate readonly file: string;\n\tprivate readonly listeners = new Set<() => void>();\n\n\tconstructor(options: WorkerAgentMailboxOptions) {\n\t\tthis.parentSessionId = assertIdentity(options.parentSessionId, \"parent session id\");\n\t\tthis.agentId = assertIdentity(options.agentId, \"agent id\");\n\t\tthis.file = workerAgentMailboxFile(\n\t\t\toptions.agentDir,\n\t\t\tthis.parentSessionId,\n\t\t\tmailboxDigest(this.parentSessionId, this.agentId),\n\t\t);\n\t}\n\n\tenqueue(input: { kind: WorkerAgentMessageKind; content: string }): WorkerAgentMessage {\n\t\tconst content = input.content.trim();\n\t\tif (!content) throw new TypeError(\"A worker control message is required.\");\n\t\tif (content.length > MAX_MAILBOX_MESSAGE_CHARS) {\n\t\t\tthrow new TypeError(\n\t\t\t\t`Worker control messages may not exceed ${MAX_MAILBOX_MESSAGE_CHARS.toLocaleString(\"en-US\")} characters.`,\n\t\t\t);\n\t\t}\n\t\tconst message: WorkerAgentMessage = {\n\t\t\tmessageId: `worker-message-${randomUUID()}`,\n\t\t\tkind: input.kind,\n\t\t\tcontent,\n\t\t\tcreatedAt: new Date().toISOString(),\n\t\t};\n\t\tthis.update((state) => {\n\t\t\tif (state.messages.length >= MAX_MAILBOX_MESSAGES) {\n\t\t\t\tthrow new Error(`Worker agent mailbox reached its ${MAX_MAILBOX_MESSAGES} message limit.`);\n\t\t\t}\n\t\t\treturn { ...state, messages: [...state.messages, message] };\n\t\t});\n\t\tthis.notify();\n\t\treturn structuredClone(message);\n\t}\n\n\tpending(kind?: WorkerAgentMessageKind): WorkerAgentMessage[] {\n\t\treturn this.read()\n\t\t\t.messages.filter(\n\t\t\t\t(message) => message.deliveredAt === undefined && (kind === undefined || message.kind === kind),\n\t\t\t)\n\t\t\t.map((message) => structuredClone(message));\n\t}\n\n\tacknowledgeDelivered(messageId: string): void {\n\t\tconst normalized = messageId.trim();\n\t\tif (!normalized) throw new TypeError(\"A worker control message id is required.\");\n\t\tlet changed = false;\n\t\tthis.update((state) => {\n\t\t\tconst messages = state.messages.filter((message) => {\n\t\t\t\tif (message.messageId !== normalized) return true;\n\t\t\t\tchanged = true;\n\t\t\t\treturn false;\n\t\t\t});\n\t\t\treturn changed ? { ...state, messages } : state;\n\t\t});\n\t\tif (changed) this.notify();\n\t}\n\n\tsubscribe(listener: () => void): () => void {\n\t\tthis.listeners.add(listener);\n\t\treturn () => this.listeners.delete(listener);\n\t}\n\n\tprivate notify(): void {\n\t\tfor (const listener of this.listeners) listener();\n\t}\n\n\tprivate read(): WorkerAgentMailboxState {\n\t\tif (!existsSync(this.file)) {\n\t\t\treturn { version: 1, parentSessionId: this.parentSessionId, agentId: this.agentId, messages: [] };\n\t\t}\n\t\treturn parseState(\n\t\t\treadBoundedTextFileSync(this.file, MAX_MAILBOX_BYTES, \"Worker agent mailbox durable size bound\"),\n\t\t\tthis.parentSessionId,\n\t\t\tthis.agentId,\n\t\t);\n\t}\n\n\tprivate update(mutator: (state: WorkerAgentMailboxState) => WorkerAgentMailboxState): void {\n\t\twithFileLockSync(this.file, () => {\n\t\t\tconst state = this.read();\n\t\t\tconst next = mutator(state);\n\t\t\tif (next.messages.length > MAX_MAILBOX_MESSAGES || encodedStateBytes(next) > MAX_MAILBOX_BYTES) {\n\t\t\t\tthrow new Error(\"Worker agent mailbox exceeds its durable size bound.\");\n\t\t\t}\n\t\t\tif (JSON.stringify(next) !== JSON.stringify(state))\n\t\t\t\twriteFileAtomicSync(this.file, `${JSON.stringify(next)}\\n`, { mode: 0o600 });\n\t\t});\n\t}\n}\n"]}

package/dist/core/delegation/worker-attempt-executor.d.ts

@@ -0,0 +1,80 @@
+import type { ThinkingLevel } from "@caupulican/pi-agent-core";
+import type { Api, Model, Usage } from "@caupulican/pi-ai";
+import type { IsolatedCompletionOptions, IsolatedCompletionResult } from "../agent-session-contracts.ts";
+import type { WorkerRequest } from "../autonomy/contracts.ts";
+import type { LaneToolSurface } from "../autonomy/lane-tool-surface.ts";
+import type { ModelCapabilityProfile } from "../model-capability.ts";
+import type { AttemptUsageSnapshot, ExecutionGrant } from "../orchestration/contracts.ts";
+import type { StartedDelegationAttempt } from "../orchestration/delegation-ledger.ts";
+import { WorkerActionJournal } from "./worker-action-journal.ts";
+import type { AppliedActionsReport, WorkerAction } from "./worker-actions.ts";
+import type { WorkerAgentControlCoordinator } from "./worker-agent-control-coordinator.ts";
+import type { WorkerConversation, WorkerConversationRetentionPolicy } from "./worker-conversation-store.ts";
+import type { WorkerExecutionPlan } from "./worker-execution-policy.ts";
+import type { WorkerLifecycle } from "./worker-lifecycle.ts";
+import { type WorkerRunOutcome } from "./worker-runner.ts";
+export interface RecoveredWorkerTerminalCompletion {
+    text: string;
+    usage: Usage;
+    stopReason: string;
+}
+/** The live mutable state that must be visible to session disposal before provider work yields. */
+export interface WorkerAttemptExecutionLedger {
+    changedFiles: Set<string>;
+    getUsage(): AttemptUsageSnapshot;
+}
+export interface WorkerAttemptExecutionResult {
+    rawOutcome: WorkerRunOutcome;
+    usage: AttemptUsageSnapshot;
+    changedFiles: readonly string[];
+}
+/**
+ * The provider/tool-loop portion of a prepared worker attempt.
+ *
+ * Admission, durable leasing, grant compilation, terminalization, notification, verification, and
+ * scheduling remain outside this boundary. This unit owns only the ordered child conversation:
+ * persist assistant tool requests before execution, append messages before mailbox acknowledgements,
+ * checkpoint cumulative usage before later boundaries, and compact only the provider projection.
+ */
+export interface WorkerAttemptExecutorOptions {
+    request: WorkerRequest;
+    grant: ExecutionGrant;
+    executionPlan: WorkerExecutionPlan;
+    toolSurface: LaneToolSurface;
+    conversation: WorkerConversation;
+    lifecycle: Pick<WorkerLifecycle, "checkpoint">;
+    laneId: string;
+    agentId: string;
+    durableHandle: StartedDelegationAttempt;
+    parentSessionId: string;
+    agentDir: string;
+    cwd: string;
+    model: Model<Api>;
+    thinkingLevel?: ThinkingLevel;
+    laneCapability: Pick<ModelCapabilityProfile, "laneMaxOutputTokens">;
+    soul?: string;
+    workerResourceSystemPrompt: string;
+    initialUsage: AttemptUsageSnapshot;
+    hasPersistedUsageCheckpoint: boolean;
+    usageReportId: string;
+    processCapable: boolean;
+    verificationSubjectTaskId?: string;
+    recoveredTerminal?: RecoveredWorkerTerminalCompletion;
+    retentionPolicy?: WorkerConversationRetentionPolicy;
+    signal?: AbortSignal;
+    runIsolatedCompletion(options: IsolatedCompletionOptions): Promise<IsolatedCompletionResult>;
+    agentControl: Pick<WorkerAgentControlCoordinator, "acknowledgeMailboxMessage" | "mailboxMessagesForConversation">;
+    applyActions?(actions: readonly WorkerAction[], actionJournal?: WorkerActionJournal): AppliedActionsReport;
+    warn(message: string): void;
+}
+/**
+ * Constructs one execution exactly once. The caller registers {@link ledger} before calling
+ * {@link run}, allowing synchronous disposal to observe mutations and cumulative usage while the
+ * provider/tool loop is suspended.
+ */
+export declare function createWorkerAttemptExecutor(options: WorkerAttemptExecutorOptions): {
+    ledger: WorkerAttemptExecutionLedger;
+    checkpointUsage(summary: string): AttemptUsageSnapshot;
+    run(): Promise<WorkerAttemptExecutionResult>;
+};
+//# sourceMappingURL=worker-attempt-executor.d.ts.map

package/dist/core/delegation/worker-attempt-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-attempt-executor.d.ts","sourceRoot":"","sources":["../../../src/core/delegation/worker-attempt-executor.ts"],"names":[],"mappings":"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"}