@realqiyan/agent-task 0.0.1-rc.3 → 0.1.0-rc.2

package/dist/protocol/task-contract.js

@@ -1,28 +1,55 @@
 import { z } from "zod";
 import { requestTimestamp } from "../shared/validation.js";
-import { nodeData, replyData, taskData, taskUpdateData } from "../tasks/validation.js";
+import { nodeData, replyData, runStatusSchema, taskData, taskUpdateData } from "../tasks/validation.js";
 export const nodeSchema = nodeData.extend({
-    prompt: z.string().trim().min(1).max(64_000),
-    dependsOn: nodeData.shape.dependsOn.default([]), maxRunSeconds: nodeData.shape.maxRunSeconds.default(600),
+    id: nodeData.shape.id.describe("Unique caller-defined ID in this DAG, referenced by dependsOn; not a run UUID."),
+    prompt: z.string().trim().min(1).max(64_000).describe("Self-contained work and acceptance criteria for this executor. The task-level prompt is not copied here. Plain text/Markdown delivery is valid unless a format is required."),
+    executorId: nodeData.shape.executorId.describe("ID from executor_list with state=ready; fixed at creation, with no automatic fallback."),
+    dependsOn: nodeData.shape.dependsOn.default([]).describe("Direct upstream node IDs; omit for none. Must exist, with no duplicates, self-references or cycles. Only their accepted deliveries unlock this node and are supplied as file paths, not full transcripts."),
+    maxRunSeconds: nodeData.shape.maxRunSeconds.default(600).describe("Total ACP session lifetime in seconds from opening, including execution, review, clarification and human-input waits; does not reset each turn."),
 });
-export const replySchema = replyData.extend({ answer: z.string().trim().min(1).max(16000) });
-export const taskIdSchema = z.object({ id: z.string().uuid() }).strict();
+export const replySchema = replyData.extend({
+    runId: replyData.shape.runId.describe("UUID of the run that owns the question; not a task or node ID."),
+    questionId: replyData.shape.questionId.describe("Latest unanswered questions[].id from task_run_list/get. Reply before expiresAt and any non-null sessionExpiresAt."),
+    requestKey: replyData.shape.requestKey.describe("Caller-chosen reply key, scoped to this run. Use a new key per answer; retry with the same key, questionId and trimmed answer to return the current run without resuming twice, even after completion. Conflicting reuse fails."),
+    answer: z.string().trim().min(1).max(16000).describe("User-provided facts answering this question, not invented assumptions or permission grants. Trimmed before storage and duplicate comparison."),
+});
+export const taskIdSchema = z.object({ id: z.string().uuid().describe("Persisted task UUID returned by task_create or task_list; not a run ID.") }).strict();
+export const runIdSchema = z.object({ id: z.string().uuid().describe("Persisted task-run UUID returned by task_run_list or task_run_get; not a task or DAG node ID.") }).strict();
 export const taskListSchema = z.object({
-    after: z.number().int().nonnegative().default(0), limit: z.number().int().min(1).max(100).default(20),
+    after: z.number().int().nonnegative().default(0).describe("Zero-based offset in the matching records, oldest first; not an ID or timestamp. Use next with unchanged filters to continue a scan. Restart at 0 to refresh, especially with status filters; pages are not a snapshot."),
+    limit: z.number().int().min(1).max(100).default(20).describe("Maximum records per page."),
 }).strict();
-export const taskRunListSchema = taskListSchema.extend({ taskId: z.string().uuid().optional() });
-export const taskUpdateSchema = taskUpdateData;
+export const taskRunListSchema = taskListSchema.extend({
+    taskId: z.string().uuid().optional().describe("Filter runs by task UUID. Omit to list runs across all tasks; unknown task IDs yield an empty page."),
+    status: runStatusSchema.optional().describe("Filter by run state; omit for all outcomes. waiting_input finds questions; running also includes queued runs, not just active ACP work."),
+});
+export const taskUpdateSchema = taskUpdateData.extend({
+    id: taskIdSchema.shape.id,
+    action: taskUpdateData.shape.action.describe("pause keeps the next trigger but suspends it; resume re-enables it without catch-up (past interval slots advance; past now/once slots become completed); cancel permanently removes future triggers. pause/resume require a remaining trigger. resume fails if any run has an interrupted node."),
+});
 export const taskSchema = taskData.extend({
-    name: z.string().trim().min(1).max(200),
-    prompt: z.string().trim().min(1).max(64_000).describe("Overall goal; the caller supplies the fixed DAG."),
-    nodes: z.array(nodeSchema).min(1).max(20).describe("Fixed DAG with an administrator-registered ACP executorId on every node."),
+    requestKey: taskData.shape.requestKey.describe("Caller-chosen creation key, scoped to the canonical workspace. Keep it stable for retries: identical normalized parameters return the existing task, including cancelled/completed tasks; changes conflict. A new key creates separate work, not a retry."),
+    name: z.string().trim().min(1).max(200).describe("Short display name; not an identifier or deduplication key."),
+    prompt: z.string().trim().min(1).max(64_000).describe("Overall goal and final delivery criteria for the coordinator. Put each executor's instructions in its node prompt; this does not replace the DAG."),
+    nodes: z.array(nodeSchema).min(1).max(20).describe("Complete fixed DAG; use one node for a single-step task. Only dependsOn imposes order, not array position; independent nodes may run concurrently."),
+    workspace: taskData.shape.workspace.describe("Existing absolute directory on the service machine, canonicalized and fixed for every run. Omit only via local stdio, which uses its launch directory, not necessarily the host's current project. Required over direct HTTP; not a sandbox or permission grant."),
     schedule: z.discriminatedUnion("type", [
-        z.object({ type: z.literal("now") }).strict(),
-        z.object({ type: z.literal("once"), at: requestTimestamp }).strict(),
-        z.object({ type: z.literal("interval"), startAt: requestTimestamp, seconds: z.number().int().min(60).max(31_536_000) }).strict(),
-    ]),
-    expiresAt: requestTimestamp.optional(),
-    maxRunSeconds: taskData.shape.maxRunSeconds.default(1800), maxSteps: taskData.shape.maxSteps.default(40),
-    maxNodeTurns: taskData.shape.maxNodeTurns.default(3), inputWaitSeconds: taskData.shape.inputWaitSeconds.default(86400),
+        z.object({ type: z.literal("now").describe("One slot eligible immediately; the scheduler creates and starts the run asynchronously.") }).strict(),
+        z.object({
+            type: z.literal("once").describe("One slot at the specified future time."),
+            at: requestTimestamp.describe("Future ISO 8601 trigger time with UTC Z or numeric offset; normalized to UTC."),
+        }).strict(),
+        z.object({
+            type: z.literal("interval").describe("Repeating slots anchored to startAt, not to completion of the previous run."),
+            startAt: requestTimestamp.describe("First trigger, in the future, as ISO 8601 with UTC Z or numeric offset."),
+            seconds: z.number().int().min(60).max(31_536_000).describe("Fixed elapsed seconds between slots; not a calendar/timezone schedule."),
+        }).strict(),
+    ]).describe("When runs become eligible, not guaranteed start times. Slots over 30 seconds late or overlapping a running/waiting run of this task are skipped, not queued for catch-up."),
+    expiresAt: requestTimestamp.optional().describe("Cutoff for new runs and previously unstarted nodes, not a completion timeout. Must follow the first trigger. Existing ACP sessions may continue. ISO 8601 with timezone; omit for no cutoff."),
+    maxRunSeconds: taskData.shape.maxRunSeconds.default(1800).describe("Run execution budget in seconds from coordinator start, excluding human-input waits; includes ACP execution. Separate from expiresAt and each node's session lifetime."),
+    maxSteps: taskData.shape.maxSteps.default(40).describe("Maximum coordinator tool calls per run, including inspection, delivery acceptance and finalization; not executor-internal tool calls."),
+    maxNodeTurns: taskData.shape.maxNodeTurns.default(3).describe("Maximum ACP turns per node per run: initial work plus clarifications in the same session, not automatic retries."),
+    inputWaitSeconds: taskData.shape.inputWaitSeconds.default(86400).describe("Seconds allowed for each user answer. With retained ACP sessions, waiting is also capped at 300 seconds and their remaining lifetime. Follow the earlier of the question's expiresAt and non-null sessionExpiresAt."),
 });
 //# sourceMappingURL=task-contract.js.map

package/dist/shared/errors.js

@@ -3,6 +3,21 @@ export function errorText(error) {
 }
 export class StorageError extends Error {
 }
+/** A business failure with a stable class; the message stays the operator-facing explanation. */
+export class TaskError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export function errorCode(error) {
+    if (error instanceof TaskError)
+        return error.code;
+    if (error instanceof StorageError)
+        return "unavailable";
+    return "internal";
+}
 export class FileCommitError extends Error {
     uncertain;
     constructor(uncertain) {

package/dist/shared/limits.js

@@ -1,3 +1,6 @@
 export const OUTPUT_LIMIT = 262_144;
 export const EVENT_LIMIT = 2000;
+export const MAX_ACTIVE_RUNS = 4;
+export const MAX_TASKS = 1000;
+export const MAX_NODE_SESSIONS = 8;
 //# sourceMappingURL=limits.js.map

package/dist/tasks/definitions.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
-import { authorizedProfile } from "../executors/registry.js";
+import { TaskError } from "../shared/errors.js";
+import { MAX_TASKS } from "../shared/limits.js";
 import { iso } from "../shared/time.js";
 import { validateGraph } from "./graph.js";
 import { hasUncertainOutcome, initialTime, resumeSchedule } from "./schedule.js";
@@ -18,28 +19,32 @@ export class TaskDefinitions {
         this.coordinatorConfigured = coordinatorConfigured;
     }
     check() { if (this.closed)
-        throw new Error("Task definition service closed"); }
+        throw new TaskError("unavailable", "Task definition service closed"); }
     create(value, now = Date.now()) {
         this.check();
         if (!this.coordinatorConfigured)
-            throw new Error("Coordinator is not configured");
+            throw new TaskError("precondition", "Coordinator is not configured");
         const input = taskData.parse(value), all = this.store.definitions();
-        const existing = all.find(item => item.input.requestKey === input.requestKey);
+        if (input.workspace === undefined)
+            throw new TaskError("validation", "workspace is required without a local MCP launch directory");
+        const workspace = this.workspaces.resolve(input.workspace);
+        input.workspace = workspace;
+        const existing = all.find(item => item.workspace === workspace && item.input.requestKey === input.requestKey);
         if (existing) {
             if (JSON.stringify(existing.input) !== JSON.stringify(input))
-                throw new Error("requestKey already used with different parameters");
+                throw new TaskError("conflict", "requestKey already used with different parameters");
             return existing;
         }
-        if (all.length >= 1000)
-            throw new Error("Task definition limit reached");
+        if (all.length >= MAX_TASKS)
+            throw new TaskError("precondition", "Task definition limit reached");
         validateGraph(input.nodes);
         const executors = this.executors.snapshot(input.nodes.map(node => node.executorId));
         const nextAt = initialTime(input.schedule, now);
         if (input.schedule.type !== "now" && nextAt < now)
-            throw new Error("Schedule must start in the future");
+            throw new TaskError("validation", "Schedule must start in the future");
         if (input.expiresAt && Date.parse(input.expiresAt) <= Math.max(now, nextAt))
-            throw new Error("Deadline must follow first trigger");
-        const task = { id: randomUUID(), input, workspace: input.workspace === undefined ? null : this.workspaces.resolve(input.workspace),
+            throw new TaskError("validation", "Deadline must follow first trigger");
+        const task = { id: randomUUID(), input, workspace,
             executors, nextAt, status: "active", createdAt: iso(now) };
         this.store.saveDefinition(task);
         return task;
@@ -60,22 +65,22 @@ export class TaskDefinitions {
         }
         else {
             if (task.nextAt === null || ["cancelled", "expired"].includes(task.status))
-                throw new Error("Task has no future schedule");
+                throw new TaskError("precondition", "Task has no future schedule");
             if (action === "pause")
                 task.status = "paused";
             else {
                 if (this.store.rounds(id).some(hasUncertainOutcome))
-                    throw new Error("Task has uncertain external outcomes; future triggers require reconciliation");
+                    throw new TaskError("precondition", "Task has uncertain external outcomes; future triggers require reconciliation");
                 task = resumeSchedule(task, now);
             }
         }
         this.store.saveDefinition(task);
         return task;
     }
-    executorImpact(profiles) {
+    executorImpact(disabled) {
         this.check();
         return this.store.definitions().filter(task => ((task.nextAt !== null && ["active", "paused"].includes(task.status)) || this.store.activeRounds(task.id).length > 0) &&
-            Object.entries(task.executors).some(([id, snapshot]) => !authorizedProfile(snapshot, profiles.find(profile => profile.id === id))))
+            Object.values(task.executors).some(snapshot => disabled.includes(snapshot.type)))
             .map(task => ({ id: task.id, name: task.input.name }));
     }
     close() { this.closed = true; }

package/dist/tasks/graph.js

@@ -1,18 +1,19 @@
+import { TaskError } from "../shared/errors.js";
 export function validateGraph(nodes) {
     const graph = new Map(nodes.map(node => [node.id, node]));
     if (!nodes.length || nodes.length > 20 || graph.size !== nodes.length)
-        throw new Error("Invalid or duplicate plan nodes");
+        throw new TaskError("validation", "Invalid or duplicate plan nodes");
     const visited = new Set(), visiting = new Set();
     const visit = (id) => {
         if (visiting.has(id))
-            throw new Error("Cyclic dependency: " + id);
+            throw new TaskError("validation", "Cyclic dependency: " + id);
         if (visited.has(id))
             return;
         const node = graph.get(id);
         if (!node)
-            throw new Error("Unknown dependency: " + id);
+            throw new TaskError("validation", "Unknown dependency: " + id);
         if (new Set(node.dependsOn).size !== node.dependsOn.length)
-            throw new Error("Duplicate dependency");
+            throw new TaskError("validation", "Duplicate dependency");
         visiting.add(id);
         node.dependsOn.forEach(visit);
         visiting.delete(id);

package/dist/tasks/human-input.js

@@ -1,14 +1,15 @@
+import { TaskError } from "../shared/errors.js";
 import { iso } from "../shared/time.js";
 /** Human facts are persisted business state, not executor permission or retry authorization. */
 export function askInput(run, request, seconds, now, questionId) {
     if (run.status !== "running")
-        throw new Error("Task run is not running");
+        throw new TaskError("precondition", "Task run is not running");
     if (run.nodes.some(node => node.status === "running"))
-        throw new Error("Wait for all ACP turns before asking for input");
+        throw new TaskError("precondition", "Wait for all ACP turns before asking for input");
     if (request.nodeId && !run.nodes.some(node => node.definition.id === request.nodeId))
-        throw new Error("Unknown question node");
+        throw new TaskError("not_found", "Unknown question node");
     if (run.questions.length >= 20)
-        throw new Error("Question limit reached");
+        throw new TaskError("precondition", "Question limit reached");
     run = structuredClone(run);
     const sessions = run.nodes.filter(node => node.status === "awaiting_review");
     const question = { ...request, id: questionId, createdAt: iso(now), expiresAt: iso(now + seconds * 1000),
@@ -32,20 +33,20 @@ export function applyReply(run, input, now) {
     run = structuredClone(run);
     const question = run.questions.find(value => value.id === input.questionId);
     if (!question)
-        throw new Error("Unknown question");
+        throw new TaskError("not_found", "Unknown question");
     const used = run.questions.find(value => value.reply?.requestKey === input.requestKey);
     if (used) {
         if (used.id !== question.id || used.reply.answer !== input.answer)
-            throw new Error("Reply requestKey already used with different parameters");
+            throw new TaskError("conflict", "Reply requestKey already used with different parameters");
         return undefined;
     }
     if (question.reply || run.questions.at(-1)?.id !== question.id)
-        throw new Error("Question already answered or stale");
+        throw new TaskError("conflict", "Question already answered or stale");
     if (run.status !== "waiting_input")
-        throw new Error("Task run is not waiting for input: " + run.status);
+        throw new TaskError("precondition", "Task run is not waiting for input: " + run.status);
     const failure = waitingFailure(run, now);
     if (failure)
-        throw new Error(failure.reason);
+        throw new TaskError("precondition", failure.reason);
     question.reply = { requestKey: input.requestKey, answer: input.answer, receivedAt: iso(now) };
     run.waitedMs += Math.max(0, now - Date.parse(question.createdAt));
     run.status = "running";

package/dist/tasks/runs.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
-import { EVENT_LIMIT, OUTPUT_LIMIT } from "../shared/limits.js";
+import { TaskError } from "../shared/errors.js";
+import { EVENT_LIMIT, MAX_NODE_SESSIONS, OUTPUT_LIMIT } from "../shared/limits.js";
 import { iso } from "../shared/time.js";
 import { applyReply, askInput, coordinatorInput, waitingFailure } from "./human-input.js";
 import { dueTrigger, hasUncertainOutcome } from "./schedule.js";
@@ -19,26 +20,26 @@ export class TaskRuns {
     }
     get healthy() { return !this.closed && this.store.healthy; }
     check() { if (this.closed)
-        throw new Error("Task run service closed"); }
+        throw new TaskError("unavailable", "Task run service closed"); }
     get(id) { this.check(); return this.store.run(id); }
-    list(taskId, after = 0, limit = 20) {
+    list(taskId, after = 0, limit = 20, status) {
         this.check();
-        const all = this.store.rounds(taskId);
+        const all = this.store.rounds(taskId).filter(run => status === undefined || run.status === status);
         return { items: all.slice(after, after + limit), next: all.length > after + limit ? after + limit : null };
     }
     active() { this.check(); return this.store.activeRounds(); }
     current(id, requestId) {
         const run = this.get(id);
         if (run.status !== "running")
-            throw new Error("Task run is not running: " + run.status);
+            throw new TaskError("precondition", "Task run is not running: " + run.status);
         if (requestId !== undefined && coordinatorInput(run).requestId !== requestId)
-            throw new Error("Stale coordinator input");
+            throw new TaskError("conflict", "Stale coordinator input");
         return run;
     }
     node(run, id) {
         const node = run.nodes.find(node => node.definition.id === id);
         if (!node)
-            throw new Error("Unknown plan node");
+            throw new TaskError("not_found", "Unknown plan node");
         return node;
     }
     inspect(id, requestId) {
@@ -79,7 +80,7 @@ export class TaskRuns {
         const run = this.current(id), task = this.store.get(run.taskId);
         if (run.steps >= task.input.maxSteps) {
             this.end(id, "failed", "Coordinator step budget exhausted");
-            throw new Error("Step budget exhausted");
+            throw new TaskError("precondition", "Step budget exhausted");
         }
         run.steps++;
         this.store.commitRun(run);
@@ -93,9 +94,9 @@ export class TaskRuns {
     finish(id, summary) {
         const run = this.current(id);
         if (!run.nodes.length || run.nodes.some(node => node.status !== "succeeded"))
-            throw new Error("Every planned node must have an accepted deliverable");
+            throw new TaskError("precondition", "Every planned node must have an accepted deliverable");
         if (!summary.trim() || summary.length > 16000)
-            throw new Error("Invalid final summary");
+            throw new TaskError("validation", "Invalid final summary");
         run.summary = summary;
         run.status = "succeeded";
         run.finishedAt = iso();
@@ -105,31 +106,31 @@ export class TaskRuns {
         const run = this.current(id), task = this.store.get(run.taskId), node = this.node(run, nodeId);
         const executor = this.executors.authorize(task.executors[node.definition.executorId]);
         if (!["pending", "awaiting_review"].includes(node.status))
-            throw new Error("Node cannot start or continue: " + node.status);
+            throw new TaskError("precondition", "Node cannot start or continue: " + node.status);
         if (node.turns.length >= task.input.maxNodeTurns)
-            throw new Error("Node turn budget exhausted");
+            throw new TaskError("precondition", "Node turn budget exhausted");
         if (message !== undefined && (!message.trim() || message.length > 64000))
-            throw new Error("Invalid follow-up");
+            throw new TaskError("validation", "Invalid follow-up");
         if (node.status === "pending" && message !== undefined)
-            throw new Error("First turn uses the committed plan prompt");
+            throw new TaskError("validation", "First turn uses the committed plan prompt");
         if (node.status === "awaiting_review" && !message)
-            throw new Error("Follow-up requires a message");
+            throw new TaskError("validation", "Follow-up requires a message");
         const parents = node.definition.dependsOn.map(parent => this.node(run, parent));
         if (parents.some(parent => parent.status !== "succeeded" || !parent.resultFile))
-            throw new Error("Dependencies have no accepted deliverable");
+            throw new TaskError("precondition", "Dependencies have no accepted deliverable");
         const opening = node.status === "pending";
         if (opening) {
             if (task.input.expiresAt && Date.now() >= Date.parse(task.input.expiresAt))
-                throw new Error("Deadline reached before node start");
-            if (sessions.size >= 8)
-                throw new Error("ACP session capacity reached; accept existing results first");
-            node.workspace = task.workspace ?? executor.cwd;
+                throw new TaskError("precondition", "Deadline reached before node start");
+            if (sessions.size >= MAX_NODE_SESSIONS)
+                throw new TaskError("precondition", "ACP session capacity reached; accept existing results first");
+            node.workspace = task.workspace;
             this.workspaces.check(node.workspace);
             node.inputFiles = parents.map(parent => parent.resultFile);
         }
         else if (!sessions.has(node.id)) {
             this.end(id, "interrupted", "ACP session unavailable; no replay");
-            throw new Error("ACP session unavailable");
+            throw new TaskError("precondition", "ACP session unavailable");
         }
         for (const path of node.inputFiles)
             this.results.readable(path);
@@ -141,24 +142,24 @@ export class TaskRuns {
         // The no-replay barrier precedes worker creation, not just the ACP prompt.
         this.store.commitRun(run);
         return opening ? { kind: "open", nodeRunId: node.id, text, seconds: node.definition.maxRunSeconds,
-            input: { executor: { ...executor, cwd: node.workspace }, inputFiles: node.inputFiles, resultsRoot: this.results.root } }
+            input: { executor, workspace: node.workspace, inputFiles: node.inputFiles, resultsRoot: this.results.root } }
             : { kind: "continue", nodeRunId: node.id, text };
     }
     beforeStart(id, nodeId) {
         const run = this.current(id), task = this.store.get(run.taskId), node = this.node(run, nodeId);
         if (node.status !== "running")
-            throw new Error("Dispatch is no longer active");
+            throw new TaskError("conflict", "Dispatch is no longer active");
         this.executors.authorize(task.executors[node.definition.executorId]);
         this.workspaces.check(node.workspace);
         if (task.input.expiresAt && Date.now() >= Date.parse(task.input.expiresAt))
-            throw new Error("Deadline reached before ACP start");
+            throw new TaskError("precondition", "Deadline reached before ACP start");
     }
     record(id, nodeId, kind, data, text) {
         const run = this.current(id), node = this.node(run, nodeId);
         if (node.status !== "running")
-            throw new Error("Unexpected ACP output outside a turn");
+            throw new TaskError("precondition", "Unexpected ACP output outside a turn");
         if (++node.eventCount > EVENT_LIMIT || Buffer.byteLength(node.turns.map(turn => turn.output).join("") + text) > OUTPUT_LIMIT)
-            throw new Error("Node output/event limit exceeded");
+            throw new TaskError("precondition", "Node output/event limit exceeded");
         node.turns.at(-1).output += text;
         if (kind === "session" && typeof data === "string")
             node.sessionId = data;
@@ -168,7 +169,7 @@ export class TaskRuns {
         // Re-read after await: cancellation, deadlines and other node events may have committed meanwhile.
         const run = this.current(id), node = this.node(run, nodeId);
         if (node.status !== "running")
-            throw new Error("Turn is no longer active");
+            throw new TaskError("precondition", "Turn is no longer active");
         node.turns.at(-1).stopReason = stopReason;
         node.status = "awaiting_review";
         this.store.commitRun(run);
@@ -179,9 +180,9 @@ export class TaskRuns {
     accept(id, nodeId, turn, result, reason) {
         const run = this.current(id), node = this.node(run, nodeId);
         if (node.status !== "awaiting_review" || turn !== node.turns.length || node.turns.at(-1)?.stopReason !== "end_turn")
-            throw new Error("Only the latest completed turn can be accepted");
+            throw new TaskError("conflict", "Only the latest completed turn can be accepted");
         if (!result.trim() || !node.turns.at(-1).output.includes(result) || !reason.trim() || reason.length > 4000)
-            throw new Error("Deliverable must be a nonempty exact excerpt of the executor output, with an acceptance reason");
+            throw new TaskError("validation", "Deliverable must be a nonempty exact excerpt of the executor output, with an acceptance reason");
         node.resultFile = this.results.save(run.id, node.definition.id, node.id, result);
         node.result = result;
         node.acceptance = reason;
@@ -224,7 +225,7 @@ export class TaskRuns {
                 this.executors.authorize(task.executors[node.definition.executorId]);
             if (node.status === "awaiting_review" && !hasSession(node.id)) {
                 this.end(run.id, "interrupted", "ACP session unavailable at human reply; no replay");
-                throw new Error("ACP session unavailable; reconcile external effects first");
+                throw new TaskError("precondition", "ACP session unavailable; reconcile external effects first");
             }
         }
         this.store.commitRun(run);

package/dist/tasks/schedule.js

@@ -1,3 +1,4 @@
+import { TaskError } from "../shared/errors.js";
 export function hasUncertainOutcome(run) {
     return run.nodes.some(node => node.status === "interrupted");
 }
@@ -7,7 +8,7 @@ export function initialTime(schedule, now) {
 export function resumeSchedule(task, now) {
     const next = structuredClone(task);
     if (next.nextAt === null || ["cancelled", "expired"].includes(next.status))
-        throw new Error("Task has no future schedule");
+        throw new TaskError("precondition", "Task has no future schedule");
     next.status = "active";
     if (next.nextAt < now) {
         if (next.input.schedule.type === "interval")

package/dist/tasks/storage/records.js

@@ -1,15 +1,15 @@
 import { z } from "zod";
 import { executorRecord } from "../../executors/validation.js";
 import { absolutePath, identifier, text, timestamp } from "../../shared/validation.js";
-import { nodeData, questionData, taskData } from "../validation.js";
+import { nodeData, nodeStatusSchema, questionData, runStatusSchema, taskData, taskStatusSchema } from "../validation.js";
 export const definitionSchema = z.object({
-    id: z.string().uuid(), input: taskData, workspace: absolutePath.nullable(), executors: z.record(identifier, executorRecord),
-    status: z.enum(["active", "paused", "cancelled", "completed", "expired"]),
+    id: z.string().uuid(), input: taskData, workspace: absolutePath, executors: z.record(identifier, executorRecord),
+    status: taskStatusSchema,
     nextAt: z.number().finite().nullable(), createdAt: timestamp,
-}).strict();
+}).strict().refine(task => task.input.workspace === task.workspace, "Task workspace must match the canonical request");
 export const roundSchema = z.object({
     id: z.string().uuid(), taskId: z.string().uuid(), scheduledAt: z.number().finite(),
-    status: z.enum(["running", "succeeded", "failed", "interrupted", "skipped", "cancelled", "timed_out", "waiting_input"]),
+    status: runStatusSchema,
     createdAt: timestamp, finishedAt: timestamp.nullable(), error: z.string().nullable(), skippedCount: z.number().int().nonnegative(),
     steps: z.number().int().nonnegative(), coordinatorStartedAt: timestamp.nullable(), summary: z.string().nullable(),
     waitedMs: z.number().finite().nonnegative(),
@@ -19,7 +19,7 @@ export const roundSchema = z.object({
     })).max(20),
     nodes: z.array(z.object({
         id: z.string().uuid(), definition: nodeData,
-        status: z.enum(["pending", "running", "awaiting_review", "succeeded", "failed", "blocked", "interrupted"]),
+        status: nodeStatusSchema,
         workspace: absolutePath.nullable(), inputFiles: z.array(absolutePath), resultFile: absolutePath.nullable(), result: z.string().nullable(), acceptance: z.string().nullable(),
         turns: z.array(z.object({ prompt: z.string(), output: z.string(), stopReason: z.string().nullable() }).strict()),
         error: z.string().nullable(), sessionId: z.string().nullable(), startedAt: timestamp.nullable(), eventCount: z.number().int().nonnegative(),

package/dist/tasks/storage/store.js

@@ -1,7 +1,7 @@
 import { DatabaseSync } from "../../infrastructure/sqlite.js";
 import { mkdirSync } from "node:fs";
 import { join } from "node:path";
-import { StorageError } from "../../shared/errors.js";
+import { StorageError, TaskError } from "../../shared/errors.js";
 import { definitionSchema, roundSchema } from "./records.js";
 /** Task definitions and rounds share one transactional store. */
 export class TaskStore {
@@ -14,7 +14,7 @@ export class TaskStore {
         try {
             const tables = this.db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all();
             if (tables.length) {
-                this.db.prepare("SELECT seq,id,request_key,data FROM definitions LIMIT 0").all();
+                this.db.prepare("SELECT seq,id,workspace,request_key,data FROM definitions LIMIT 0").all();
                 this.db.prepare("SELECT seq,id,task_id,scheduled_at,data FROM rounds LIMIT 0").all();
                 this.definitions();
                 this.rounds();
@@ -22,7 +22,8 @@ export class TaskStore {
             this.db.exec("PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL; PRAGMA foreign_keys=ON");
             if (!tables.length)
                 this.db.exec(`BEGIN IMMEDIATE;
-        CREATE TABLE definitions(seq INTEGER PRIMARY KEY, id TEXT UNIQUE NOT NULL, request_key TEXT UNIQUE NOT NULL, data TEXT NOT NULL);
+        CREATE TABLE definitions(seq INTEGER PRIMARY KEY, id TEXT UNIQUE NOT NULL, workspace TEXT NOT NULL,
+          request_key TEXT NOT NULL, data TEXT NOT NULL, UNIQUE(workspace,request_key));
         CREATE TABLE rounds(seq INTEGER PRIMARY KEY, id TEXT UNIQUE NOT NULL, task_id TEXT NOT NULL REFERENCES definitions(id),
           scheduled_at REAL NOT NULL, data TEXT NOT NULL, UNIQUE(task_id,scheduled_at));
         COMMIT;`);
@@ -64,14 +65,14 @@ export class TaskStore {
         this.check();
         const row = this.db.prepare("SELECT data FROM definitions WHERE id=?").get(id);
         if (!row)
-            throw new Error("Task not found");
+            throw new TaskError("not_found", "Task not found");
         return this.decode(definitionSchema, row["data"]);
     }
     run(id) {
         this.check();
         const row = this.db.prepare("SELECT data FROM rounds WHERE id=?").get(id);
         if (!row)
-            throw new Error("Task run not found");
+            throw new TaskError("not_found", "Task run not found");
         return this.decode(roundSchema, row["data"]);
     }
     /** The service supplies all policy; the store commits a cursor and round atomically. */
@@ -86,8 +87,8 @@ export class TaskStore {
         try {
             this.db.exec("BEGIN IMMEDIATE");
             if (definition)
-                this.db.prepare(`INSERT INTO definitions(id,request_key,data) VALUES(?,?,?)
-        ON CONFLICT(id) DO UPDATE SET data=excluded.data`).run(definition.id, definition.input.requestKey, JSON.stringify(definition));
+                this.db.prepare(`INSERT INTO definitions(id,workspace,request_key,data) VALUES(?,?,?,?)
+        ON CONFLICT(id) DO UPDATE SET data=excluded.data`).run(definition.id, definition.workspace, definition.input.requestKey, JSON.stringify(definition));
             if (round)
                 this.db.prepare(`INSERT INTO rounds(id,task_id,scheduled_at,data) VALUES(?,?,?,?)
         ON CONFLICT(id) DO UPDATE SET data=excluded.data`).run(round.id, round.taskId, round.scheduledAt, JSON.stringify(round));

package/dist/tasks/supervisor.js

@@ -1,4 +1,5 @@
-import { errorText, StorageError } from "../shared/errors.js";
+import { errorText, StorageError, TaskError } from "../shared/errors.js";
+import { MAX_ACTIVE_RUNS, MAX_NODE_SESSIONS, MAX_TASKS } from "../shared/limits.js";
 import { coordinatorInput } from "./human-input.js";
 import { NodeSessions } from "./sessions.js";
 /** Owns coordinator generations, the calendar clock and NodeSessions. All persisted decisions go through TaskRuns. */
@@ -19,10 +20,12 @@ export class RunSupervisor {
         this.sessions = new NodeSessions(openExecution, fatal);
     }
     check() { if (this.closed)
-        throw new Error("Run supervisor closed"); }
+        throw new TaskError("unavailable", "Run supervisor closed"); }
     status() {
         return { running: !this.closed && this.timer !== undefined && this.runs.healthy,
-            activeTaskRunIds: [...this.active.keys()], activeNodeRunIds: this.sessions.nodeIds(), storageHealthy: this.runs.healthy };
+            activeTaskRunIds: [...this.active.keys()], activeNodeRunIds: this.sessions.nodeIds(),
+            storageHealthy: this.runs.healthy, coordinatorConfigured: this.coordinate !== undefined,
+            limits: { maxActiveRuns: MAX_ACTIVE_RUNS, maxTasks: MAX_TASKS, maxNodeSessions: MAX_NODE_SESSIONS } };
     }
     actions(id, requestId = coordinatorInput(this.runs.get(id)).requestId) {
         this.check();
@@ -124,15 +127,15 @@ export class RunSupervisor {
     recover() {
         this.check();
         if (this.active.size || this.sessions.size)
-            throw new Error("Recovery requires no active resources");
+            throw new TaskError("conflict", "Recovery requires no active resources");
         this.runs.recover();
     }
     start() {
         this.check();
         if (this.timer)
-            throw new Error("Run supervisor already started");
+            throw new TaskError("conflict", "Run supervisor already started");
         this.recover();
-        this.timer = setInterval(() => this.tick(), 500);
+        this.timer = setInterval(() => this.tick(), 10_000);
         this.tick();
     }
     tick() {
@@ -145,7 +148,7 @@ export class RunSupervisor {
                     this.reconcile(run.id);
                     continue;
                 }
-                if (this.active.has(run.id) || this.active.size >= 4)
+                if (this.active.has(run.id) || this.active.size >= MAX_ACTIVE_RUNS)
                     continue;
                 this.launch(run.id);
             }

package/dist/tasks/validation.js

@@ -5,6 +5,9 @@ export const scheduleData = z.discriminatedUnion("type", [
     z.object({ type: z.literal("once"), at: timestamp }).strict(),
     z.object({ type: z.literal("interval"), startAt: timestamp, seconds: z.number().int().min(60).max(31_536_000) }).strict(),
 ]);
+export const taskStatusSchema = z.enum(["active", "paused", "cancelled", "completed", "expired"]);
+export const runStatusSchema = z.enum(["running", "succeeded", "failed", "interrupted", "skipped", "cancelled", "timed_out", "waiting_input"]);
+export const nodeStatusSchema = z.enum(["pending", "running", "awaiting_review", "succeeded", "blocked", "interrupted"]);
 export const nodeData = z.object({
     id: identifier, prompt: text(64_000), executorId: identifier,
     dependsOn: z.array(identifier).max(20), maxRunSeconds: z.number().int().min(1).max(3600),