@caupulican/pi-adaptative 0.81.41 → 0.81.42

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

@@ -0,0 +1,75 @@
+import type { AgentMessage } from "@caupulican/pi-agent-core";
+import type { WorkerDelegationRunOutcome } from "../agent-session-contracts.ts";
+import type { LaneRecord } from "../autonomy/lane-tracker.ts";
+import type { AttemptRuntimeState } from "../orchestration/task-runtime.ts";
+import { type WorkerAgentControlPort } from "./worker-agent-control.ts";
+import type { WorkerConversation } from "./worker-conversation-store.ts";
+import type { WorkerDelegationRequest } from "./worker-delegation-request.ts";
+import type { WorkerDispatchScheduler } from "./worker-dispatch-scheduler.ts";
+import type { WorkerLifecycle } from "./worker-lifecycle.ts";
+export interface WorkerAgentControlCoordinatorOptions {
+    agentDir: string;
+    parentSessionId: string;
+    processOwnerId: string;
+    isControlAvailable(): boolean;
+    getLifecycle(): WorkerLifecycle;
+    recoveredRequest(attempt: AttemptRuntimeState): WorkerDelegationRequest;
+    run(request: WorkerDelegationRequest, record: LaneRecord): Promise<WorkerDelegationRunOutcome>;
+    scheduler: Pick<WorkerDispatchScheduler, "enqueue" | "track" | "drain">;
+    statusChanged(): void;
+    abortLane(laneId: string, reasonCode: string): void;
+    cancelLane(laneId: string, reasonCode: string): LaneRecord | undefined;
+}
+/**
+ * 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 declare class WorkerAgentControlCoordinator implements WorkerAgentControlPort {
+    private readonly options;
+    private readonly mailboxes;
+    private readonly stateListeners;
+    constructor(options: WorkerAgentControlCoordinatorOptions);
+    getProcessOwnerId(): string;
+    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;
+    /** Event-driven wait: durable projection plus state/mailbox notifications, never output polling. */
+    waitForWorkerAgent(agentId: string, timeoutMs?: number): Promise<{
+        status: "active" | "suspended" | "idle" | "unknown";
+    }>;
+    /** Read mailbox items at a safe boundary and reconcile the narrow append-before-ack crash window. */
+    mailboxMessagesForConversation(agentId: string, conversation: WorkerConversation, includeFollowUp: boolean): AgentMessage[];
+    /** Acknowledge only after the exact child transcript message has been durably appended. */
+    acknowledgeMailboxMessage(agentId: string, message: {
+        role: string;
+        content: unknown;
+    }): void;
+    /** Called by controller-owned execution transitions after lifecycle state changed. */
+    signalStateChanged(): void;
+    private requireControl;
+    private requireKnownAgent;
+    private getMailbox;
+    private subscribeStateChanges;
+    private mailboxMessage;
+}
+//# sourceMappingURL=worker-agent-control-coordinator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"worker-agent-control-coordinator.d.ts","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\tthis.requireControl();\n\t\tconst agent = this.requireKnownAgent(agentId);\n\t\tconst attemptId = agent.activeAttemptId;\n\t\tconst attempt = attemptId ? this.options.getLifecycle().getTaskRuntimeSnapshot().attempts[attemptId] : undefined;\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\tthis.requireControl();\n\t\tconst agent = this.requireKnownAgent(agentId);\n\t\tconst attemptId = agent.activeAttemptId;\n\t\tconst attempt = attemptId ? this.options.getLifecycle().getTaskRuntimeSnapshot().attempts[attemptId] : undefined;\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\tthis.requireControl();\n\t\tconst agent = this.requireKnownAgent(agentId);\n\t\tconst attemptId = agent.activeAttemptId;\n\t\tconst attempt = attemptId ? this.options.getLifecycle().getTaskRuntimeSnapshot().attempts[attemptId] : undefined;\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 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-coordinator.js

@@ -0,0 +1,218 @@
+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 {
+    options;
+    mailboxes = new Map();
+    stateListeners = new Set();
+    constructor(options) {
+        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) {
+        this.requireControl();
+        const agent = this.requireKnownAgent(agentId);
+        const attemptId = agent.activeAttemptId;
+        const attempt = attemptId ? this.options.getLifecycle().getTaskRuntimeSnapshot().attempts[attemptId] : undefined;
+        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) {
+        this.requireControl();
+        const agent = this.requireKnownAgent(agentId);
+        const attemptId = agent.activeAttemptId;
+        const attempt = attemptId ? this.options.getLifecycle().getTaskRuntimeSnapshot().attempts[attemptId] : undefined;
+        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") {
+        this.requireControl();
+        const agent = this.requireKnownAgent(agentId);
+        const attemptId = agent.activeAttemptId;
+        const attempt = attemptId ? this.options.getLifecycle().getTaskRuntimeSnapshot().attempts[attemptId] : undefined;
+        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;
+    }
+    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\tthis.requireControl();\n\t\tconst agent = this.requireKnownAgent(agentId);\n\t\tconst attemptId = agent.activeAttemptId;\n\t\tconst attempt = attemptId ? this.options.getLifecycle().getTaskRuntimeSnapshot().attempts[attemptId] : undefined;\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\tthis.requireControl();\n\t\tconst agent = this.requireKnownAgent(agentId);\n\t\tconst attemptId = agent.activeAttemptId;\n\t\tconst attempt = attemptId ? this.options.getLifecycle().getTaskRuntimeSnapshot().attempts[attemptId] : undefined;\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\tthis.requireControl();\n\t\tconst agent = this.requireKnownAgent(agentId);\n\t\tconst attemptId = agent.activeAttemptId;\n\t\tconst attempt = attemptId ? this.options.getLifecycle().getTaskRuntimeSnapshot().attempts[attemptId] : undefined;\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 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","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-agent-control.js

@@ -0,0 +1,163 @@
+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 {
+    parentSessionId;
+    agentId;
+    file;
+    listeners = new Set();
+    constructor(options) {
+        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