visionclaw 0.1.219-beta.0 → 0.1.219-dev.codex-issue-2805-worker-runtime.1

package/dist/threads/foreman-host.js

@@ -0,0 +1,891 @@
+import { createHash, randomUUID } from "node:crypto";
+import { DEFAULT_THREAD_ID } from "../channels/interface.js";
+import { isDeliveryTarget } from "../channels/delivery-target.js";
+import { taskContinuationRouting } from "../agent/reply-target.js";
+import { resolveWorkspaceCwd } from "../agent/workspace-cwd.js";
+import { t } from "../i18n/index.js";
+import { logger } from "../logger.js";
+import { ExecutionCommandConflictError, isTerminalExecutionState, } from "./execution-store.js";
+import { DEFAULT_LAB_RUN_BUDGET } from "./execution-snapshot.js";
+import { prepareTaskWorkspace } from "./task-workspace.js";
+import { publicTaskText, taskDeliveryMode } from "./foreman-delivery.js";
+import { CancelArgsSchema, DelegateArgsSchema, DelegateBatchArgsSchema, FOREMAN_EVENT_META_KEY, FOREMAN_SCOPE, InputArgsSchema, StatusArgsSchema, } from "./foreman-protocol.js";
+/**
+ * The Foreman host (#2805 stage 3), in the main process.
+ *
+ * General's background-task tools reach it directly (default thread) or over
+ * IPC (other conversational threads; the supervisor fills in the thread id
+ * from the worker it talks to). It turns their commands into execution
+ * protocol commands with caller `{ kind: "general", ref: threadId }`, so a
+ * thread can only see and steer the tasks it delegated itself.
+ *
+ * It is also the `general` caller's delivery handler: a worker's question or
+ * result becomes a durable system message in the delegating thread's queue,
+ * and opens the owner delivery obligation that the fallback sweep enforces.
+ */
+const SWEEP_INTERVAL_MS = 30_000;
+/** About 4k tokens, the issue's initial budget for General's active-task summary. */
+const SUMMARY_CHAR_BUDGET = 12_000;
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function fail(text) {
+    return { ok: false, text: `Error: ${text}` };
+}
+function invalid(error) {
+    return fail(`invalid arguments: ${error.issues.map((issue) => `${issue.path.map(String).join(".") || "args"}: ${issue.message}`).join("; ")}`);
+}
+/** Event payload fields are untyped JSON; only a string is shown as text. */
+function textOf(value, fallback = "") {
+    return typeof value === "string" ? value : fallback;
+}
+function clip(text, max) {
+    return text.length <= max ? text : `${text.slice(0, max)}…`;
+}
+function identity(...parts) {
+    return createHash("sha256").update(parts.join("\0")).digest("hex").slice(0, 32);
+}
+function taskIdFor(conversation, dispatch, key) {
+    return `task-${identity(conversation, dispatch, key)}`;
+}
+function remainingBudget(limits, attempts) {
+    const used = (field) => attempts.reduce((sum, attempt) => {
+        const value = (attempt.usage ?? attempt.result?.usage)?.[field];
+        return sum + (typeof value === "number" && Number.isFinite(value) ? Math.max(0, value) : 0);
+    }, 0);
+    return {
+        maxModelAttempts: limits.maxModelAttempts - used("modelAttempts"),
+        maxToolCalls: limits.maxToolCalls - used("toolCalls"),
+        maxDurationMs: limits.maxDurationMs - used("elapsedMs"),
+    };
+}
+function describeState(record) {
+    switch (record.state) {
+        case "queued": return "queued, waiting for a worker slot";
+        case "running": return "running";
+        case "waiting_input": return "waiting for an answer";
+        case "cancel_requested": return "stopping: cancel requested, the worker has not confirmed it stopped yet";
+        case "succeeded": return "succeeded";
+        case "failed": return "failed";
+        case "cancelled": return "cancelled";
+    }
+}
+function fallbackKey(obligation) {
+    if (obligation.kind === "question")
+        return "foreman.fallback.question";
+    if (obligation.status === "succeeded")
+        return "foreman.fallback.succeeded";
+    if (obligation.status === "cancelled")
+        return "foreman.fallback.cancelled";
+    if (obligation.status === "partial")
+        return "foreman.fallback.partial";
+    return "foreman.fallback.failed";
+}
+export class ForemanHost {
+    deps;
+    pendingBatches = new Map();
+    timer = null;
+    sweeping = false;
+    now;
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? (() => new Date());
+    }
+    /** Start the fallback sweep. The first pass finds obligations a restart left overdue. */
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => { void this.sweep(); }, SWEEP_INTERVAL_MS);
+        this.timer.unref();
+        void this.sweep();
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+    }
+    /** The supervisor supplies executor identity; model arguments never select an account. */
+    async readBusiness(executionId, tool, args, workspace) {
+        const record = this.deps.executions.get(executionId);
+        const dispatch = record ? this.ownedDispatch(record.caller.ref, record.taskId) : null;
+        if (record?.caller.kind !== "general" || record.state !== "running" || !record.payload.businessRead || !dispatch?.metadata.businessRead
+            || !this.deps.canReadBusiness?.(dispatch.threadId, dispatch.replyTarget) || !this.deps.readBusiness) {
+            return fail("This execution is not authorized to read the owner's workspace");
+        }
+        if (record.payload.workspaceMode === "read_only" && tool === "manage_drive"
+            && typeof args === "object" && args !== null && "action" in args && args.action === "download_file") {
+            return fail("A read-only Task cannot download files into its workspace");
+        }
+        const stillAuthorized = () => {
+            const current = this.deps.executions.get(executionId);
+            return current?.state === "running" && current.workerInstanceId === record.workerInstanceId
+                && this.deps.canReadBusiness?.(dispatch.threadId, dispatch.replyTarget) === true;
+        };
+        const result = await this.deps.readBusiness(tool, args, workspace, stillAuthorized);
+        return stillAuthorized() ? result : fail("The execution stopped or its business-read permission was revoked");
+    }
+    async handle(threadId, command) {
+        try {
+            return await this.run(threadId, command);
+        }
+        catch (error) {
+            logger.warn(`[foreman] ${command.type} from thread=${threadId} failed: ${errorMessage(error)}`);
+            return fail(errorMessage(error));
+        }
+    }
+    // ----------------------------------------------------------- delivery
+    /**
+     * The execution outbox delivers a `general` caller's event. Only a question
+     * or a result asks something of General; acceptance and progress are read
+     * on demand through background_task_status. Resolves true once the event is
+     * in the thread's durable queue; a throw makes the outbox retry it.
+     */
+    deliverEvent(event, caller) {
+        if (caller.kind !== "general")
+            return Promise.resolve(false);
+        if (event.type !== "question" && event.type !== "result")
+            return Promise.resolve(true);
+        const threadId = caller.ref;
+        const dispatch = this.ownedDispatch(threadId, event.taskId);
+        if (dispatch?.metadata.parentTaskId && event.type === "result") {
+            return this.deliverParentResult(threadId, dispatch.metadata.parentTaskId);
+        }
+        // A retried Task may still have an older result/question in the outbox.
+        // A transport replay must not revive that superseded attempt's delivery.
+        const latest = dispatch && !dispatch.metadata.children?.length ? this.latest(dispatch.taskId) : null;
+        if (latest && latest.executionId !== event.executionId)
+            return Promise.resolve(true);
+        if (event.type === "result" && this.deps.store.isUserCancelled(event.taskId))
+            return Promise.resolve(true);
+        const userCancelled = event.type === "result" && event.payload.status === "cancelled"
+            && (event.payload.userInitiated === true || this.deps.store.isUserCancelled(event.taskId));
+        const publicText = publicTaskText(event);
+        const direct = Boolean(dispatch?.replyTarget && !userCancelled && publicText !== null && taskDeliveryMode(event) === "direct"
+            && !dispatch.metadata.children?.length);
+        // Queue first, then open the obligation: both are idempotent per event, so
+        // a crash in between is repaired by the outbox's redelivery.
+        if (!direct)
+            this.deps.enqueueToGeneral(threadId, this.eventMessage(event, threadId, dispatch, dispatch !== null && !userCancelled));
+        if (dispatch) {
+            this.deps.store.open({
+                taskId: event.taskId,
+                eventId: event.eventId,
+                executionId: event.executionId,
+                kind: event.type,
+                status: event.type === "question" ? "question" : String(event.payload.status),
+                userInitiated: userCancelled,
+                publicText,
+                deliveryMode: direct ? "direct" : "review",
+            });
+        }
+        return direct ? this.sweep().then(() => true) : Promise.resolve(true);
+    }
+    /** Deliver the public event content for every obligation that is due. */
+    async sweep() {
+        if (this.sweeping)
+            return;
+        this.sweeping = true;
+        try {
+            for (const cancel of this.deps.store.groupCancels()) {
+                const parent = this.deps.store.dispatch(cancel.taskId);
+                if (parent)
+                    this.cancelChildren(parent, cancel.reason, cancel.byUser);
+            }
+            for (const obligation of this.deps.store.due()) {
+                const dispatch = this.deps.store.dispatch(obligation.taskId);
+                if (!dispatch?.replyTarget) {
+                    this.deps.store.fallbackFailed(obligation.taskId, obligation.eventId, "No reply target was recorded for this task");
+                    continue;
+                }
+                const legacyEvent = obligation.publicText === null
+                    ? this.allEvents(obligation.executionId).find((event) => event.eventId === obligation.eventId) : undefined;
+                const publicText = obligation.publicText ?? (legacyEvent ? publicTaskText(legacyEvent) : null);
+                const text = obligation.deliveryMode === "direct" && publicText ? `${dispatch.title}\n\n${publicText}`
+                    : obligation.deliveryMode === "review" && obligation.kind === "result"
+                        ? t("foreman.fallback.review", this.deps.locale(), dispatch.title)
+                        : [t(fallbackKey(obligation), this.deps.locale(), dispatch.title), publicText].filter(Boolean).join("\n\n");
+                let result;
+                try {
+                    result = await this.deps.deliver(dispatch.replyTarget, text, dispatch.threadId);
+                }
+                catch (error) {
+                    result = { ok: false, errorMessage: errorMessage(error) };
+                }
+                if (result.ok) {
+                    if (obligation.deliveryMode === "direct")
+                        this.deps.store.markDelivered(obligation.taskId, obligation.kind === "result" ? "completion" : undefined, obligation.eventId);
+                    else
+                        this.deps.store.fallbackSent(obligation.taskId, obligation.eventId);
+                    logger.system(`[foreman] Sent ${obligation.deliveryMode === "direct" ? "direct delivery" : "fallback notice"} for task=${obligation.taskId} event=${obligation.eventId} (${obligation.kind})`);
+                    continue;
+                }
+                const after = this.deps.store.fallbackFailed(obligation.taskId, obligation.eventId, result.errorMessage);
+                const message = `[foreman] Delivery fallback for task=${obligation.taskId} failed: ${result.errorMessage}`;
+                if (after?.state === "delivery_failed")
+                    logger.err(`${message}; giving up (delivery_failed)`);
+                else
+                    logger.warn(message);
+            }
+        }
+        catch (error) {
+            logger.err(`[foreman] Delivery fallback sweep failed: ${errorMessage(error)}`);
+        }
+        finally {
+            this.sweeping = false;
+        }
+    }
+    // ----------------------------------------------------------- commands
+    run(threadId, command) {
+        switch (command.type) {
+            case "business_read": return fail("Business reads require an admitted execution connection");
+            case "delegate": return this.deps.allowDelegation?.() === false ? fail("New Task delegation is disabled") : this.delegate(threadId, command);
+            case "delegate_batch": return this.deps.allowDelegation?.() === false ? fail("New Task delegation is disabled") : this.delegateBatch(threadId, command);
+            case "status": return this.status(threadId, command.args);
+            case "input": return this.input(threadId, command.args);
+            case "cancel": return this.cancel(threadId, command.args);
+            case "cancel_all": {
+                const roots = this.deps.store.allForThread(threadId).filter((task) => !task.metadata.parentTaskId && this.isOpen(task));
+                const results = roots.map((task) => this.cancel(threadId, { task_id: task.taskId, requested_by_user: true, reason: "User stopped this conversation's tasks" }));
+                return {
+                    ok: results.every((result) => result.ok),
+                    text: roots.length > 0 ? [
+                        t("foreman.cancel_all", this.deps.locale(), String(roots.length)),
+                        ...roots.slice(0, 10).map((task) => `- ${task.title}`),
+                        ...results.filter((result) => !result.ok).map((result) => result.text),
+                    ].join("\n") : "",
+                };
+            }
+            case "delivered": return this.delivered(threadId, command.taskId, command.purpose, command.eventId);
+            case "turn_ended": return this.turnEnded(threadId, command.events);
+            case "summary": return { ok: true, text: this.summary(threadId) };
+        }
+    }
+    envelope(threadId, commandId) {
+        return { commandId, caller: { kind: "general", ref: threadId }, scope: FOREMAN_SCOPE };
+    }
+    /** A task dispatched by this thread; any other thread's task is not visible. */
+    ownedDispatch(threadId, taskId) {
+        const dispatch = this.deps.store.dispatch(taskId);
+        return dispatch?.threadId === threadId ? dispatch : null;
+    }
+    latest(taskId) {
+        return this.deps.executions.latestForTask(taskId, FOREMAN_SCOPE);
+    }
+    childRecords(parent) {
+        return (parent.metadata.children ?? []).map((taskId) => ({ taskId, record: this.latest(taskId) }));
+    }
+    parentState(parent) {
+        const children = this.childRecords(parent);
+        if (children.every((child) => child.record === null))
+            return "not_started";
+        if (children.some((child) => child.record === null || !isTerminalExecutionState(child.record.state))) {
+            if (children.some((child) => child.record?.state === "running"))
+                return "running";
+            if (children.some((child) => child.record?.state === "cancel_requested"))
+                return "cancel_requested";
+            if (children.some((child) => child.record?.state === "waiting_input"))
+                return "waiting_input";
+            return "queued";
+        }
+        if (children.every((child) => child.record?.state === "succeeded"))
+            return "succeeded";
+        if (children.every((child) => child.record?.state === "cancelled") || this.deps.store.groupCancels().some((item) => item.taskId === parent.taskId))
+            return "cancelled";
+        if (children.some((child) => child.record?.state === "succeeded"))
+            return "partial";
+        return "failed";
+    }
+    deliverParentResult(threadId, taskId) {
+        const parent = this.ownedDispatch(threadId, taskId);
+        if (!parent?.metadata.children?.length)
+            return Promise.resolve(false);
+        const children = this.childRecords(parent);
+        if (children.some((child) => !child.record || !isTerminalExecutionState(child.record.state)))
+            return Promise.resolve(true);
+        const records = children.map((child) => child.record).filter((record) => record !== null);
+        // The set of attempts is the result version. A late event from an old
+        // attempt cannot create a second delivery for the current result version.
+        const eventId = `evt-task-${identity(taskId, ...records.map((record) => record.executionId))}`;
+        const status = this.parentState(parent);
+        const summary = records.map((record) => {
+            const childId = record.taskId;
+            const title = this.deps.store.dispatch(childId)?.title ?? childId;
+            return `${childId} "${title}": ${record.state}. ${clip(record.result?.summary ?? record.result?.error?.message ?? "", 400)}`;
+        }).join("\n");
+        const event = {
+            protocolVersion: 1, eventId, seq: 0, taskId, executionId: taskId, type: "result",
+            createdAt: records.map((record) => record.updatedAt).sort().at(-1) ?? this.now().toISOString(),
+            payload: {
+                status, summary,
+                data: { userMessage: children.map(({ taskId: childId, record }) => {
+                        const message = publicTaskText({ type: "result", payload: { data: record?.result?.data } });
+                        const title = this.deps.store.dispatch(childId)?.title ?? childId;
+                        return message ? `${title}\n${message}` : null;
+                    }).filter(Boolean).join("\n\n") },
+                artifactRefs: records.flatMap((record) => record.result?.artifactRefs ?? []).slice(0, 30),
+                userInitiated: status === "cancelled" && this.deps.store.isUserCancelled(taskId),
+            },
+        };
+        return this.deliverEvent(event, { kind: "general", ref: threadId });
+    }
+    cancelChildren(parent, reason, byUser) {
+        for (const { taskId, record } of this.childRecords(parent)) {
+            if (!record || isTerminalExecutionState(record.state))
+                continue;
+            if (byUser)
+                this.deps.store.markUserCancelled(taskId);
+            this.deps.store.withdraw(taskId);
+            this.deps.executions.cancel(this.envelope(parent.threadId, `cancel-${identity(parent.taskId, record.executionId, reason, String(byUser))}`), {
+                executionId: record.executionId, reason, userInitiated: byUser,
+            });
+        }
+    }
+    delegateBatch(threadId, command) {
+        const parsed = DelegateBatchArgsSchema.safeParse(command.args);
+        if (!parsed.success)
+            return Promise.resolve(invalid(parsed.error));
+        const key = identity(threadId, command.dispatchKey, parsed.data.title);
+        const specification = JSON.stringify(parsed.data);
+        const pending = this.pendingBatches.get(key);
+        if (pending)
+            return pending.specification === specification ? pending.result : Promise.resolve(fail("Batch identity is already being prepared with different content"));
+        const result = this.prepareBatch(threadId, command);
+        this.pendingBatches.set(key, { specification, result });
+        void result.finally(() => { this.pendingBatches.delete(key); }).catch(() => { });
+        return result;
+    }
+    async prepareBatch(threadId, command) {
+        const parsed = DelegateBatchArgsSchema.safeParse(command.args);
+        if (!parsed.success)
+            return invalid(parsed.error);
+        const args = parsed.data;
+        if (new Set(args.tasks.map((task) => task.key)).size !== args.tasks.length)
+            return fail("Task keys must be unique within a batch");
+        const atomic = this.deps.executions.atomic;
+        if (!atomic)
+            return fail("This execution host does not support atomic task batches");
+        const rootId = taskIdFor(threadId, command.dispatchKey, `batch:${args.title}`);
+        const specification = identity(JSON.stringify(args));
+        const previous = this.ownedDispatch(threadId, rootId);
+        if (previous && previous.metadata.specification !== specification)
+            return fail("This batch key was already used with different tasks; use a distinct title for new work");
+        const ids = args.tasks.map((task) => taskIdFor(threadId, command.dispatchKey, `${rootId}:${task.key}`));
+        const commits = new Map();
+        // Filesystem preparation happens before the synchronous acceptance transaction.
+        // No worker starts until every Task and command has been committed.
+        const workspaces = [];
+        const contexts = [];
+        for (const [index, task] of args.tasks.entries()) {
+            const existing = this.ownedDispatch(threadId, ids[index]);
+            if (existing?.metadata.specification && existing.metadata.specification !== identity(specification, task.key))
+                throw new Error(`Task key ${task.key} was already used with different content`);
+            const source = task.context_task_id ? this.ownedDispatch(threadId, task.context_task_id) : null;
+            const sourceRecord = source ? (existing?.metadata.contextExecutionId
+                ? this.deps.executions.get(existing.metadata.contextExecutionId) : this.latest(source.taskId)) : null;
+            if (task.context_task_id && (!sourceRecord || sourceRecord.taskId !== source?.taskId || !isTerminalExecutionState(sourceRecord.state))) {
+                return fail("context_task_id must name a completed execution Task from this conversation");
+            }
+            contexts.push(sourceRecord?.executionId);
+            const directory = task.project_dir ?? sourceRecord?.payload.workspaceRef ?? source?.workspace;
+            workspaces.push(existing?.workspace ?? (directory
+                ? await prepareTaskWorkspace(directory, ids[index], task.workspace_mode, commits)
+                : undefined));
+        }
+        const parent = args.result_mode === "combined" && args.tasks.length > 1;
+        const foreground = this.ownedDispatch(threadId, ids[0])?.metadata.foregroundCalls
+            ?? Math.max(0, Math.trunc(command.foreground.toolCallsUsed));
+        const budget = DEFAULT_LAB_RUN_BUDGET;
+        return atomic(() => this.deps.store.atomic(() => {
+            if (parent)
+                this.deps.store.recordDispatch({
+                    taskId: rootId, threadId, title: args.title, replyTarget: isDeliveryTarget(command.replyTarget)
+                        ? command.replyTarget : threadId === DEFAULT_THREAD_ID ? this.deps.ownerTarget() : null,
+                    sender: command.sender ?? "", metadata: { children: ids, specification, sourceKey: command.dispatchKey },
+                });
+            for (const [index, task] of args.tasks.entries()) {
+                const result = this.delegate(threadId, {
+                    type: "delegate", args: { ...task, project_dir: workspaces[index], workspace_mode: task.workspace_mode === "isolated" ? "shared" : task.workspace_mode },
+                    foreground: { taskId: ids[index], toolCallsUsed: index === 0 ? foreground : 0 },
+                    ...(parent ? { parentTaskId: rootId } : {}),
+                    preparedWorkspace: Boolean(workspaces[index] && task.workspace_mode === "isolated"),
+                    contextExecutionId: contexts[index],
+                    specification: identity(specification, task.key),
+                    sourceKey: command.dispatchKey,
+                    budget, replyTarget: command.replyTarget, sender: command.sender,
+                });
+                if (!result.ok)
+                    throw new Error(result.text);
+            }
+            return {
+                ok: true, acceptedTaskId: parent ? rootId : ids[0], acceptedTaskIds: ids,
+                text: `Accepted ${ids.length} Task(s)${parent ? ` under parent ${rootId} for one combined delivery` : " with independent delivery"}: ${args.tasks.map((task, i) => `${task.key}=${ids[i]}`).join(", ")}. Each Task has its own budget and runs when slots are available. You may delegate more independent work, coordinate existing Tasks, or reply. Do not repeat work assigned to these Tasks.`,
+            };
+        }));
+    }
+    delegate(threadId, command) {
+        if (command.args && typeof command.args === "object" && "worker" in command.args && command.args.worker !== null && command.args.worker !== undefined) {
+            return fail("Worker aliases are no longer used. Select a completed context_task_id, or send input to the existing Task.");
+        }
+        const parsed = DelegateArgsSchema.safeParse(command.args);
+        if (!parsed.success)
+            return invalid(parsed.error);
+        const args = parsed.data;
+        let retryOf = null;
+        const retryDispatchId = args.retry_task_id && command.dispatchKey ? identity(threadId, command.dispatchKey) : undefined;
+        const retrySpecification = retryDispatchId ? identity(JSON.stringify(args)) : undefined;
+        if (args.retry_task_id) {
+            if (!this.ownedDispatch(threadId, args.retry_task_id))
+                return fail(`task ${args.retry_task_id} was not delegated from this conversation`);
+            const replay = retryDispatchId ? this.deps.executions.attemptsForTask?.(args.retry_task_id, FOREMAN_SCOPE)
+                .find((attempt) => attempt.payload.retryDispatchId === retryDispatchId) : undefined;
+            if (replay)
+                return replay.payload.retrySpecification === retrySpecification
+                    ? { ok: true, acceptedTaskId: replay.taskId, text: `Retry already accepted for task ${replay.taskId}, execution ${replay.executionId}: ${describeState(replay)}.` }
+                    : fail("This retry was already accepted with different content; use background_task_input or a new user instruction");
+            retryOf = this.latest(args.retry_task_id);
+            if (!retryOf)
+                return fail(`task ${args.retry_task_id} has no earlier run to retry`);
+            if (!isTerminalExecutionState(retryOf.state)) {
+                return fail(`task ${args.retry_task_id} is still ${describeState(retryOf)}; send changes with background_task_input instead`);
+            }
+        }
+        const taskId = args.retry_task_id ?? (command.dispatchKey
+            ? taskIdFor(threadId, command.dispatchKey, args.key ?? identity(JSON.stringify(args)))
+            : command.foreground.taskId);
+        const oldDispatch = this.ownedDispatch(threadId, taskId);
+        if (command.parentTaskId && !this.ownedDispatch(threadId, command.parentTaskId)?.metadata.children?.includes(taskId)) {
+            return fail("The parent Task did not admit this child");
+        }
+        const previous = args.context_task_id ? this.ownedDispatch(threadId, args.context_task_id) : null;
+        const contextExecutionId = command.contextExecutionId ?? oldDispatch?.metadata.contextExecutionId;
+        const previousRecord = previous ? (contextExecutionId
+            ? this.deps.executions.get(contextExecutionId) : this.latest(previous.taskId)) : null;
+        if (args.context_task_id) {
+            if (args.retry_task_id)
+                return fail("Use either context_task_id for new work or retry_task_id for another attempt, not both");
+            if (!previousRecord || previousRecord.taskId !== previous?.taskId)
+                return fail("context_task_id must name an execution Task from this conversation");
+            if (!isTerminalExecutionState(previousRecord.state))
+                return fail("That Task is unfinished; use background_task_input to continue it");
+        }
+        let workspace;
+        if (retryOf && args.workspace_mode && (retryOf.payload.workspaceMode === "read_only") !== (args.workspace_mode === "read_only")) {
+            return fail("A retry keeps its workspace access. Delegate a new Task to change read-only versus writable access");
+        }
+        const workspaceMode = retryOf?.payload.workspaceMode ?? (command.preparedWorkspace ? "isolated" : args.workspace_mode ?? "shared");
+        const requestedDir = args.project_dir ?? retryOf?.payload.workspaceRef ?? oldDispatch?.workspace ?? previousRecord?.payload.workspaceRef ?? previous?.workspace ?? undefined;
+        if (requestedDir) {
+            try {
+                workspace = resolveWorkspaceCwd(requestedDir, { writable: workspaceMode !== "read_only" });
+            }
+            catch (error) {
+                return fail(`project_dir: ${errorMessage(error)}. Nothing was delegated.`);
+            }
+        }
+        // The reply target comes from the authenticated inbound message, never
+        // from the model. A replayed or retried dispatch keeps the first one.
+        const replyTarget = isDeliveryTarget(command.replyTarget)
+            ? command.replyTarget
+            : threadId === DEFAULT_THREAD_ID ? this.deps.ownerTarget() : null;
+        const dispatch = this.deps.store.recordDispatch({
+            taskId,
+            threadId,
+            title: args.title,
+            replyTarget,
+            sender: typeof command.sender === "string" ? command.sender : "",
+            workspace: workspace ?? null,
+            metadata: {
+                sourceKey: command.sourceKey ?? command.dispatchKey ?? (command.parentTaskId ? this.deps.store.dispatch(command.parentTaskId)?.metadata.sourceKey : undefined),
+                contextTaskId: previous?.taskId,
+                contextExecutionId: previousRecord?.executionId,
+                businessRead: this.deps.canReadBusiness?.(threadId, replyTarget) ?? false,
+                ...(command.parentTaskId ? { parentTaskId: command.parentTaskId } : {}),
+                budget: command.budget ?? DEFAULT_LAB_RUN_BUDGET,
+                foregroundCalls: command.foreground.toolCallsUsed,
+                preparedWorkspace: command.preparedWorkspace,
+                specification: command.specification,
+            },
+        });
+        const context = [
+            args.context,
+            retryOf?.result?.summary ? `Previous attempt result: ${clip(retryOf.result.summary, 4_000)}` : undefined,
+            retryOf?.payload.contextSummary,
+            dispatch.sender ? `Requested by: ${dispatch.sender}` : undefined,
+            previous && previous.taskId !== taskId ? this.previousWork(previous, previousRecord) : undefined,
+        ].filter((part) => typeof part === "string" && part.length > 0);
+        const toolCallsUsed = retryOf ? command.foreground.toolCallsUsed : dispatch.metadata.foregroundCalls ?? command.foreground.toolCallsUsed;
+        const payload = {
+            goal: args.goal,
+            requirements: [...new Set([...(retryOf?.payload.requirements ?? []), ...args.requirements])],
+            ...((args.expected_output ?? retryOf?.payload.expectedOutput) ? { expectedOutput: args.expected_output ?? retryOf?.payload.expectedOutput } : {}),
+            ...(context.length > 0 ? { contextSummary: clip(context.join("\n\n"), 20_000) } : {}),
+            checkpoint: {
+                done: args.done,
+                remaining: args.remaining,
+                decisions: [],
+                blockers: [],
+                artifactRefs: [...new Set([...(previousRecord?.result?.artifactRefs ?? []), ...args.artifacts])],
+                uncertainOperations: args.uncertain_operations,
+            },
+            title: dispatch.title,
+            businessRead: dispatch.metadata.businessRead === true,
+            foregroundToolCallsUsed: Number.isInteger(toolCallsUsed) && toolCallsUsed >= 0 ? toolCallsUsed : 0,
+            ...(workspace ? { workspaceRef: workspace } : {}),
+            workspaceMode,
+            ...(dispatch.metadata.parentTaskId ? { parentTaskId: dispatch.metadata.parentTaskId } : {}),
+            ...((command.preparedWorkspace || (dispatch.metadata.preparedWorkspace && workspace === dispatch.workspace)
+                || (previousRecord?.payload.preparedWorkspace && workspace === previousRecord.payload.workspaceRef)
+                || (retryOf?.payload.preparedWorkspace && workspace === retryOf.payload.workspaceRef)) ? { preparedWorkspace: true } : {}),
+            ...(retryOf ? { priorExecutionId: retryOf.executionId } : {}),
+            ...(retryDispatchId ? { retryDispatchId, retrySpecification } : {}),
+        };
+        // One command per handoff (or per retry of one run): a repeated call
+        // returns the original acceptance instead of starting a second worker.
+        const commandId = retryOf ? `retry-${taskId}-${retryOf.executionId}` : `delegate-${taskId}`;
+        const budget = remainingBudget(dispatch.metadata.budget ?? DEFAULT_LAB_RUN_BUDGET, retryOf ? this.deps.executions.attemptsForTask?.(taskId, FOREMAN_SCOPE) ?? [retryOf] : []);
+        if (budget.maxModelAttempts < 1 || budget.maxToolCalls <= toolCallsUsed || budget.maxDurationMs < 1)
+            return fail(`Task ${taskId} has exhausted its cumulative budget`);
+        let outcome;
+        try {
+            outcome = this.deps.executions.submit(this.envelope(threadId, commandId), {
+                taskId,
+                ...(retryOf ? { retryOf: retryOf.executionId } : {}),
+                payload,
+                budget,
+            });
+        }
+        catch (error) {
+            if (error instanceof ExecutionCommandConflictError) {
+                return fail(`task ${taskId} was already delegated with different content. Send changes with background_task_input, or check it with background_task_status`);
+            }
+            throw error;
+        }
+        if (outcome.kind === "stale") {
+            return outcome.reason === "task_has_live_execution" && outcome.record
+                ? fail(`task ${taskId} is already ${describeState(outcome.record)} in the background; send further requirements with background_task_input`)
+                : fail(`nothing was delegated (${outcome.reason})`);
+        }
+        if (retryOf) {
+            // The previous result is superseded: whatever it still owed the user moves to the new run.
+            this.deps.store.withdraw(taskId);
+            this.deps.store.clearUserCancelled(taskId);
+            if (dispatch.metadata.parentTaskId) {
+                this.deps.store.withdraw(dispatch.metadata.parentTaskId);
+                this.deps.store.clearUserCancelled(dispatch.metadata.parentTaskId);
+                this.deps.store.clearGroupCancel(dispatch.metadata.parentTaskId);
+            }
+        }
+        logger.system(`[foreman] Delegated task=${taskId} execution=${outcome.value.executionId} from thread=${threadId}${retryOf ? ` (retry of ${retryOf.executionId})` : ""}`);
+        return {
+            ok: true,
+            acceptedTaskId: taskId,
+            text: [
+                `Delegated as background task ${taskId} ("${dispatch.title}"), execution ${outcome.value.executionId}, ${outcome.value.state === "queued" ? "queued: it starts when a worker slot is free" : outcome.value.state}.`,
+                "Do not repeat this Task's work here. You may delegate more independent Tasks, coordinate existing work, or reply to the user.",
+                "Its question or result arrives later as a [Background task update] message.",
+            ].join(" "),
+        };
+    }
+    /** Explicit Task context survives process replacement without a worker identity. */
+    previousWork(previous, record) {
+        const lines = [`Referenced Task: ${previous.taskId} "${previous.title}" (${record ? describeState(record) : "not started"})`];
+        if (record?.result?.summary)
+            lines.push(`Its result: ${clip(record.result.summary, 4_000)}`);
+        if (record?.result?.artifactRefs?.length)
+            lines.push(`Its artifacts: ${record.result.artifactRefs.slice(0, 20).join(", ")}`);
+        return lines.join("\n");
+    }
+    status(threadId, args) {
+        const parsed = StatusArgsSchema.safeParse(args ?? {});
+        if (!parsed.success)
+            return invalid(parsed.error);
+        if (parsed.data.task_id) {
+            const dispatch = this.ownedDispatch(threadId, parsed.data.task_id);
+            return dispatch
+                ? { ok: true, text: this.describeTask(dispatch, true) }
+                : fail(`no background task ${parsed.data.task_id} in this conversation`);
+        }
+        const roots = this.deps.store.allForThread(threadId).filter((dispatch) => !dispatch.metadata.parentTaskId);
+        const active = roots.filter((dispatch) => this.isOpen(dispatch));
+        const dispatches = [...active, ...roots.filter((dispatch) => !this.isOpen(dispatch)).slice(0, Math.max(0, 20 - active.length))];
+        if (dispatches.length === 0)
+            return { ok: true, text: "No background tasks in this conversation." };
+        return { ok: true, text: dispatches.map((dispatch) => this.describeTask(dispatch, false)).join("\n") };
+    }
+    input(threadId, args) {
+        const parsed = InputArgsSchema.safeParse(args);
+        if (!parsed.success)
+            return invalid(parsed.error);
+        const { task_id: taskId, text } = parsed.data;
+        const dispatch = this.ownedDispatch(threadId, taskId);
+        if (!dispatch)
+            return fail(`no background task ${taskId} in this conversation`);
+        if (dispatch.metadata.children?.length)
+            return fail(`Send the answer or requirement to a child Task: ${dispatch.metadata.children.join(", ")}. Each child owns its input cursor.`);
+        const record = this.latest(taskId);
+        if (!record)
+            return fail(`task ${taskId} has not started`);
+        if (isTerminalExecutionState(record.state)) {
+            return fail(`task ${taskId} already ${record.state}. To change its result, run it again with delegate_task(retry_task_id="${taskId}") and put the change in requirements`);
+        }
+        if (record.state === "cancel_requested")
+            return fail(`task ${taskId} is stopping and takes no more input`);
+        const questionId = parsed.data.question_id
+            ?? (record.state === "waiting_input" ? record.openQuestionId ?? undefined : undefined);
+        const outcome = this.deps.executions.sendInput(this.envelope(threadId, `input-${randomUUID()}`), {
+            executionId: record.executionId,
+            text,
+            ...(questionId ? { questionId } : {}),
+        });
+        if (outcome.kind === "stale") {
+            return fail(outcome.reason === "question_not_open"
+                ? `question ${questionId ?? ""} of task ${taskId} is no longer open`
+                : `the input was not accepted (${outcome.reason})`);
+        }
+        // General handled what the task asked; the next result carries the obligation.
+        this.deps.store.withdraw(taskId);
+        return {
+            ok: true,
+            text: questionId
+                ? `Answer stored for task ${taskId} (input ${outcome.value.inputSeq}); the task resumes with it.`
+                : `Input stored for task ${taskId} (input ${outcome.value.inputSeq}); the worker reads it at its next step. It is not applied yet.`,
+        };
+    }
+    cancel(threadId, args) {
+        const parsed = CancelArgsSchema.safeParse(args);
+        if (!parsed.success)
+            return invalid(parsed.error);
+        const { task_id: taskId, requested_by_user: byUser, reason } = parsed.data;
+        const dispatch = this.ownedDispatch(threadId, taskId);
+        if (!dispatch)
+            return fail(`no background task ${taskId} in this conversation`);
+        if (dispatch.metadata.children?.length) {
+            if (!this.isOpen(dispatch))
+                return { ok: true, text: `Task ${taskId} has already finished (${this.parentState(dispatch)}).` };
+            if (byUser)
+                this.deps.store.markUserCancelled(taskId);
+            this.deps.store.withdraw(taskId);
+            this.deps.store.requestGroupCancel(taskId, reason ?? "Parent task cancelled", byUser);
+            this.cancelChildren(dispatch, reason ?? "Parent task cancelled", byUser);
+            return { ok: true, text: `Cancel requested for all unfinished children of ${taskId}. Running children must confirm their stop before the parent is cancelled.` };
+        }
+        const record = this.latest(taskId);
+        if (!record || isTerminalExecutionState(record.state)) {
+            if (byUser) {
+                this.deps.store.markUserCancelled(taskId);
+                this.deps.store.withdraw(taskId);
+            }
+            return { ok: true, text: `Task ${taskId} is not running (${record ? record.state : "never started"}); nothing to cancel.` };
+        }
+        // Recorded first: the cancelled result that follows owes the user nothing.
+        if (byUser)
+            this.deps.store.markUserCancelled(taskId);
+        this.deps.store.withdraw(taskId);
+        const outcome = this.deps.executions.cancel(this.envelope(threadId, `cancel-${randomUUID()}`), {
+            executionId: record.executionId,
+            ...(reason ? { reason } : {}),
+            userInitiated: byUser,
+        });
+        if (outcome.kind === "stale")
+            return fail(`the cancel was not accepted (${outcome.reason})`);
+        return {
+            ok: true,
+            text: outcome.value.state === "cancelled"
+                ? `Task ${taskId} was cancelled before a worker started it.`
+                : `Cancel requested for task ${taskId}. The worker has not confirmed it stopped yet; do not tell the user it has stopped. The task is reported cancelled only after it does.`,
+        };
+    }
+    delivered(threadId, taskId, purpose, eventId) {
+        const dispatch = this.ownedDispatch(threadId, taskId);
+        if (!dispatch)
+            return { ok: false, text: `no background task ${taskId} in this conversation` };
+        if (dispatch.metadata.children?.length && !eventId)
+            return fail("A parent Task delivery must identify its result event/version");
+        const satisfied = this.deps.store.markDelivered(taskId, purpose === "completion" ? "completion" : undefined, eventId);
+        return { ok: true, text: String(satisfied) };
+    }
+    /** General's turn that handled these events ended: whatever it did not deliver is due now. */
+    turnEnded(threadId, events) {
+        let due = 0;
+        for (const event of events) {
+            if (typeof event.taskId !== "string" || typeof event.eventId !== "string")
+                continue;
+            if (!this.ownedDispatch(threadId, event.taskId))
+                continue;
+            this.deps.store.makeDueNow(event.taskId, [event.eventId]);
+            due += 1;
+        }
+        if (due > 0)
+            void this.sweep();
+        return { ok: true, text: "" };
+    }
+    /** Open tasks of this conversation, for General's wake context. Empty when none. */
+    summary(threadId) {
+        const roots = this.deps.store.allForThread(threadId).filter((dispatch) => !dispatch.metadata.parentTaskId);
+        const open = roots.filter((dispatch) => this.isOpen(dispatch));
+        const recent = roots.filter((dispatch) => {
+            const delivery = this.deps.store.latest(dispatch.taskId);
+            return !this.isOpen(dispatch) && delivery?.deliveryMode === "direct" && delivery.state === "delivered";
+        }).slice(0, 5);
+        if (open.length === 0 && recent.length === 0)
+            return "";
+        let text = [
+            "## Background Tasks",
+            "Tasks this conversation delegated that are still open. Answer status questions from this list or background_task_status; do not guess. Send new requirements for a listed task with background_task_input instead of working on it here.",
+        ].join("\n");
+        for (const dispatch of open) {
+            const entry = this.describeTask(dispatch, false);
+            if (text.length + entry.length + 1 > SUMMARY_CHAR_BUDGET) {
+                text += "\n- More tasks: see background_task_status.";
+                break;
+            }
+            text += `\n${entry}`;
+        }
+        for (const dispatch of recent) {
+            const entry = `\n- Already delivered directly: ${dispatch.taskId} "${dispatch.title}": ${clip(this.deps.store.latest(dispatch.taskId)?.publicText ?? "", 1_000)}. Do not send it again.`;
+            if (text.length + entry.length <= SUMMARY_CHAR_BUDGET)
+                text += entry;
+        }
+        return text;
+    }
+    describeTask(dispatch, detail) {
+        if (dispatch.metadata.children?.length) {
+            const children = dispatch.metadata.children.map((id) => this.deps.store.dispatch(id))
+                .filter((item) => item !== null);
+            const delivery = this.deps.store.latest(dispatch.taskId);
+            return [
+                `- ${dispatch.taskId} "${dispatch.title}": ${this.parentState(dispatch)} (${children.length} child Tasks)`,
+                ...children.map((child) => `  ${this.describeTask(child, detail)}`),
+                ...(delivery ? [`  parent delivery: ${delivery.state} (event ${delivery.eventId})`] : []),
+            ].join("\n");
+        }
+        const record = this.latest(dispatch.taskId);
+        const lines = [`- ${dispatch.taskId} "${dispatch.title}": ${record ? describeState(record) : "not started"}`];
+        if (dispatch.metadata.contextTaskId)
+            lines.push(`  context from Task: ${dispatch.metadata.contextTaskId}`);
+        if (record) {
+            const events = detail || record.state === "waiting_input" ? this.allEvents(record.executionId) : [];
+            const newestFirst = [...events].reverse();
+            if (record.state === "waiting_input" && record.openQuestionId) {
+                const question = newestFirst.find((event) => event.type === "question" && event.payload.questionId === record.openQuestionId);
+                lines.push(`  open question ${record.openQuestionId}: ${clip(textOf(question?.payload.text, "(text unavailable)"), 1_000)}`);
+            }
+            if (detail) {
+                lines.push(`  execution ${record.executionId}: queued ${record.queuedAt}`
+                    + (record.startedAt ? `, started ${record.startedAt}` : "")
+                    + (record.stoppedAt ? `, stopped ${record.stoppedAt}` : "")
+                    + (record.autoResumeCount > 0 ? `, resumed ${record.autoResumeCount} time(s) after interruptions` : ""));
+                const progress = newestFirst.find((event) => event.type === "progress" && typeof event.payload.summary === "string");
+                if (progress)
+                    lines.push(`  latest progress (${progress.createdAt}): ${clip(String(progress.payload.summary), 1_000)}`);
+                else if (!record.result)
+                    lines.push("  no progress reported yet");
+            }
+            const result = record.result;
+            if (result?.summary)
+                lines.push(`  result: ${clip(result.summary, detail ? 4_000 : 400)}`);
+            const prepared = detail ? publicTaskText({ type: "result", payload: { data: result?.data } }) : null;
+            if (prepared)
+                lines.push(`  prepared answer: ${prepared}`);
+            if (result?.error)
+                lines.push(`  error: ${result.error.code}: ${clip(result.error.message, 1_000)}`);
+            if (result?.artifactRefs?.length)
+                lines.push(`  artifacts: ${result.artifactRefs.slice(0, 20).join(", ")}`);
+        }
+        const delivery = this.deps.store.latest(dispatch.taskId);
+        if (delivery && delivery.state !== "delivered" && delivery.state !== "withdrawn") {
+            lines.push(`  delivery to the user: ${delivery.state}${delivery.lastError ? ` (${delivery.lastError})` : ""} (event ${delivery.eventId})`);
+            if (delivery.deliveryMode === "review" && delivery.state === "fallback_sent")
+                lines.push("  Only a status notice was sent; the result still requires General to review and deliver it.");
+        }
+        return lines.join("\n");
+    }
+    isOpen(dispatch) {
+        const record = this.latest(dispatch.taskId);
+        const workOpen = dispatch.metadata.children?.length
+            ? this.childRecords(dispatch).some((child) => child.record !== null && !isTerminalExecutionState(child.record.state))
+            : record !== null && !isTerminalExecutionState(record.state);
+        const delivery = this.deps.store.latest(dispatch.taskId);
+        return workOpen || delivery?.state === "pending" || delivery?.state === "delivery_failed"
+            || (delivery?.state === "fallback_sent" && delivery.deliveryMode === "review" && delivery.kind === "result");
+    }
+    allEvents(executionId) {
+        const events = [];
+        let after = 0;
+        for (;;) {
+            const page = this.deps.executions.eventsAfter(executionId, after);
+            const last = page.at(-1)?.seq ?? after;
+            if (last <= after)
+                break;
+            events.push(...page);
+            after = last;
+            if (page.length < 500)
+                break;
+        }
+        return events;
+    }
+    /** The system message that brings a question or result to the delegating thread. */
+    eventMessage(event, threadId, dispatch, obligationOpens) {
+        const payload = event.payload;
+        const title = dispatch?.title ?? event.taskId;
+        const taskQuote = `task_id="${event.taskId}"`;
+        const quote = `${taskQuote}, event_id="${event.eventId}"`;
+        const lines = [`[Background task update] ${event.type === "question" ? "Question from" : "Result of"} background task ${event.taskId} "${title}"`];
+        if (dispatch?.sender)
+            lines.push(`Requested by: ${dispatch.sender}`);
+        if (event.type === "question") {
+            lines.push(`Question ${textOf(payload.questionId)}: ${clip(textOf(payload.text), 4_000)}`);
+            if (Array.isArray(payload.choices) && payload.choices.length > 0) {
+                lines.push(`Choices: ${payload.choices.map(String).join(" / ")}`);
+            }
+            lines.push(`If you can answer from what you know, answer with background_task_input(${taskQuote}, question_id="${textOf(payload.questionId)}"). Otherwise ask the requester with notify_user(${quote}) and pass their answer on. Do not do the task's work here.`);
+        }
+        else {
+            const status = String(payload.status);
+            lines.push(`Status: ${status}`);
+            if (typeof payload.summary === "string")
+                lines.push(`Summary: ${clip(payload.summary, 8_000)}`);
+            const preparedReply = publicTaskText(event);
+            if (preparedReply)
+                lines.push(`Prepared reply for the requester (review before sending): ${preparedReply}`);
+            const error = payload.error;
+            if (error && typeof error === "object") {
+                const { code, message } = error;
+                lines.push(`Error: ${String(code)}: ${clip(String(message), 2_000)}`);
+            }
+            if (Array.isArray(payload.artifactRefs) && payload.artifactRefs.length > 0) {
+                lines.push(`Artifacts: ${payload.artifactRefs.slice(0, 30).map(String).join(", ")}`);
+            }
+            if (status === "cancelled" && !obligationOpens) {
+                lines.push("The requester asked to stop this task; nothing more is needed unless they asked to hear back.");
+            }
+            else if (dispatch?.metadata.children?.length) {
+                lines.push(`Review the child results together. Deliver the overall result with notify_user(${quote}, purpose="completion"). Retry only children that need further work using their child task_id; do not repeat successful children. The parent does not occupy a worker.`);
+            }
+            else if (status === "succeeded") {
+                lines.push(`Check the result against the request before you deliver it. If it holds up, tell the requester with notify_user(${quote}, purpose="completion") in your own words, and send any drafts it contains with the right tool. If it falls short, run it again with delegate_task(retry_task_id="${event.taskId}") and say what must change.`);
+            }
+            else {
+                lines.push(`Tell the requester what happened with notify_user(${quote}, purpose="completion"), or run it again with delegate_task(retry_task_id="${event.taskId}") if a retry can succeed.`);
+            }
+        }
+        if (obligationOpens)
+            lines.push("If this turn ends without that notify_user, the requester gets a short automatic notice instead.");
+        const routing = taskContinuationRouting(dispatch?.replyTarget
+            ? { sender: dispatch.sender, delivery: dispatch.replyTarget }
+            : undefined);
+        return {
+            id: `foreman-${event.eventId}`,
+            channel: "system",
+            // An empty recorded sender (no inbound message) also falls back.
+            sender: dispatch && dispatch.sender.length > 0 ? dispatch.sender : "background-task",
+            text: lines.join("\n"),
+            attachments: [],
+            timestamp: event.createdAt,
+            ...routing,
+            meta: { ...routing.meta, [FOREMAN_EVENT_META_KEY]: { taskId: event.taskId, eventId: event.eventId } },
+            ...(threadId !== DEFAULT_THREAD_ID ? { threadId } : {}),
+        };
+    }
+}
+//# sourceMappingURL=foreman-host.js.map