@realqiyan/agent-task 0.1.0-rc.1 → 0.1.0-rc.3

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 a ready local 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,4 +1,6 @@
 import { randomUUID } from "node:crypto";
+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";
@@ -17,31 +19,31 @@ 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();
         if (input.workspace === undefined)
-            throw new Error("workspace is required without a local MCP launch directory");
+            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");
+            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);
@@ -63,12 +65,12 @@ 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);
             }
         }

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");
+                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);
@@ -147,18 +148,18 @@ export class TaskRuns {
     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, executors: z.record(identifier, executorRecord),
-    status: z.enum(["active", "paused", "cancelled", "completed", "expired"]),
+    status: taskStatusSchema,
     nextAt: z.number().finite().nullable(), createdAt: timestamp,
 }).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 {
@@ -65,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. */

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,13 +127,13 @@ 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(), 10_000);
         this.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),

package/docs/cli.md

@@ -44,11 +44,16 @@ agent-task config show --running
 
 ## 执行端发现与更新
 
-`agent-task executor list` 查看当前发现和准备结果；`executor show codex` 查看单个执行端。安装新的原生 CLI 后，运行 `executor refresh` 重新检测并在后台准备缺少的 ACP 适配器。该操作无需重启。准备失败时先检查报告的原因，修正后显式刷新或升级。
-
-已准备的适配器不会随普通启动或刷新自动升级。需要更新时运行 `agent-task executor upgrade codex --yes`，再用 `executor list` 检查结果。升级期间暂停向该执行端派发新工作；它不修改已有任务指派。OpenCode 使用原生 ACP 命令，通过原生 CLI 的安装渠道更新。
+```bash
+agent-task executor list
+agent-task executor show codex
+agent-task executor refresh
+# 仅在需要升级适配器时执行：
+agent-task executor upgrade codex --yes
+agent-task executor list
+```
 
-就绪状态只表示启动依赖已准备。原生登录和权限仍由执行端管理；首次准备、版本来源及运行边界见[部署说明](deployment.md)。
+发现、安装复用、升级影响和原生认证统一见[部署说明](deployment.md#执行端发现与准备)。就绪不证明工具授权或任务成功；PATH 变化也不能仅靠刷新生效。
 
 ## 凭据与任务
 

package/docs/deployment.md

@@ -54,7 +54,7 @@ agent-task setup --home /absolute/private/agent-task \
 
 发现原生 CLI 后，后台为缺少 ACP 适配器的执行端安装当时最新版，已有安装直接复用；OpenCode 使用原生 ACP 命令。安装在后台进行，可用 MCP `executor_list`、`agent-task executor list` 或 Web 查看准备结果。任务只能选择就绪执行端。适配器安装失败时保留管理入口和其他就绪执行端，修正原因后显式刷新或升级。包映射和安装实现见 [discovery.ts](../src/integrations/acp/discovery.ts)。
 
-适配器保存在安装目录的私有 `adapters/` 中，不修改全局 npm 包或执行 CLI 的原生配置。普通重连不访问 registry 升级已有适配器。显式更新使用 `agent-task executor upgrade codex --yes`，再查询状态；新版本发布成功前保留原安装，活动 ACP 进程不因升级被重启。高级启停设置及 Web/CLI 操作见 [CLI 说明](cli.md#执行端发现与更新)。
+适配器保存在安装目录的私有 `adapters/` 中，不修改全局 npm 包或执行 CLI 的原生配置。普通重连不访问 registry 升级已有适配器。显式更新使用 `agent-task executor upgrade codex --yes`，再查询状态；升级期间暂停向该执行端派发新工作，新版本发布成功前保留原安装，活动 ACP 进程不因升级被重启。重新检测和升级直接作用于当前执行端目录，无需重启，也不保存启动配置。OpenCode 通过原生 CLI 的安装渠道更新。命令入口见 [CLI 说明](cli.md#执行端发现与更新)。
 
 后台的原生环境来自启动它的进程，不随不同 MCP 客户端切换。新 CLI 位于已有 PATH 时可用 `executor refresh` 重新检测；PATH 本身变化时先停止后台，再从正确环境连接或启动。原生登录须与后台使用同一 OS 用户及 HOME/配置目录。
 
@@ -82,7 +82,7 @@ MCP 接入不会自动重启一个已存在但不可用的后台。故障时查
 
 运行配置、私有环境文件、任务和协调会话记录、结果及服务日志位于当前 `dataDir`。安装目录保留 `launch.json` 定位文件、初始化清单、适配器及启动器控制资源。npm 包、项目工作空间和执行端原生配置与数据目录分开。路径实现见 [startup.ts](../src/application/startup.ts)。
 
-打开 `status` 返回地址同源的 `/admin/`，用本地编辑器读取当前 `dataDir/environment.json` 中的 `AGENT_TASK_ADMIN_TOKEN`，在连接表单输入。不要把 token 放入 URL、命令参数、Git 或截图。CLI 从私有文件读取管理员令牌。两端使用同一管理服务，见[控制台说明](web-console.md)和 [CLI 说明](cli.md)。
+Web 访问 `status` 返回地址同源的 `/admin/`，连接与令牌保护见[控制台说明](web-console.md#启用与连接)；命令行管理见 [CLI 说明](cli.md)。两端使用同一管理服务。
 
 修改数据目录后，下次启动只准备目标配置和私有环境，并切换定位文件；不复制任务、会话、结果或日志，不删除旧目录。目标已有不同启动文件时拒绝覆盖，须停服核对并显式准备目标。新目录没有旧任务，目录切换不是恢复或重放许可。