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

package/dist/tasks/schedule.js

@@ -0,0 +1,36 @@
+export function hasUncertainOutcome(run) {
+    return run.nodes.some(node => node.status === "interrupted");
+}
+export function initialTime(schedule, now) {
+    return schedule.type === "now" ? now : Date.parse(schedule.type === "once" ? schedule.at : schedule.startAt);
+}
+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");
+    next.status = "active";
+    if (next.nextAt < now) {
+        if (next.input.schedule.type === "interval")
+            next.nextAt += (Math.floor((now - next.nextAt) / (next.input.schedule.seconds * 1000)) + 1) * next.input.schedule.seconds * 1000;
+        else {
+            next.nextAt = null;
+            next.status = "completed";
+        }
+    }
+    return next;
+}
+/** Calendar only. Node dispatch remains the coordinator's decision. */
+export function dueTrigger(task, overlaps, now) {
+    if (task.status !== "active" || task.nextAt === null)
+        return { kind: "none" };
+    if (task.input.expiresAt && now >= Date.parse(task.input.expiresAt))
+        return { kind: "expired" };
+    if (task.nextAt > now)
+        return { kind: "none" };
+    const schedule = task.input.schedule;
+    const count = schedule.type === "interval" ? Math.floor((now - task.nextAt) / (schedule.seconds * 1000)) + 1 : 1;
+    const at = task.nextAt + (schedule.type === "interval" ? (count - 1) * schedule.seconds * 1000 : 0);
+    return { kind: "due", at, count, nextAt: schedule.type === "interval" ? at + schedule.seconds * 1000 : null,
+        reason: overlaps ? "Previous round still active; slot skipped" : now - at > 30_000 ? "Late slot skipped" : null };
+}
+//# sourceMappingURL=schedule.js.map

package/dist/tasks/sessions.js

@@ -0,0 +1,62 @@
+/** Owns every opened handle and its lifetime timer, including sessions retained while waiting for facts. */
+export class NodeSessions {
+    openExecution;
+    fatal;
+    sessions = new Map();
+    closing;
+    constructor(openExecution, fatal) {
+        this.openExecution = openExecution;
+        this.fatal = fatal;
+    }
+    get size() { return this.sessions.size; }
+    has(id) { return !this.closing && this.sessions.get(id)?.state === "open"; }
+    runIds() { return [...new Set([...this.sessions.values()].map(value => value.runId))]; }
+    nodeIds() { return [...this.sessions.keys()]; }
+    get(id) {
+        const active = this.sessions.get(id);
+        if (this.closing || active?.state !== "open")
+            throw new Error("ACP session unavailable or closing");
+        return active.handle;
+    }
+    open(id, runId, input, seconds, event, beforeStart, expired, disconnected) {
+        if (this.closing)
+            throw new Error("Node sessions closed");
+        if (this.sessions.has(id))
+            throw new Error("Node session already exists");
+        const handle = this.openExecution(input, event, beforeStart);
+        const timer = setTimeout(expired, seconds * 1000);
+        this.sessions.set(id, { runId, handle, state: "open", timer });
+        void handle.closed.then(() => {
+            if (this.sessions.get(id)?.state === "open" && !this.closing)
+                disconnected();
+        }).catch(this.fatal);
+        return handle;
+    }
+    closeSession(id) {
+        const owned = this.sessions.get(id);
+        if (!owned)
+            return Promise.resolve();
+        if (owned.state === "closing")
+            return owned.completion;
+        clearTimeout(owned.timer);
+        // Mark closing before the handle can report a disconnect; concurrent close calls share completion.
+        const completion = Promise.resolve().then(() => owned.handle.close()).then(() => { this.sessions.delete(id); });
+        this.sessions.set(id, { runId: owned.runId, handle: owned.handle, state: "closing", completion });
+        return completion;
+    }
+    async closeRun(id) {
+        const results = await Promise.allSettled([...this.sessions].filter(([, value]) => value.runId === id).map(([key]) => this.closeSession(key)));
+        const failure = results.find(result => result.status === "rejected");
+        if (failure?.status === "rejected")
+            throw failure.reason;
+    }
+    close() {
+        return this.closing ??= (async () => {
+            const results = await Promise.allSettled([...this.sessions.keys()].map(id => this.closeSession(id)));
+            const failure = results.find(result => result.status === "rejected");
+            if (failure?.status === "rejected")
+                throw failure.reason;
+        })();
+    }
+}
+//# sourceMappingURL=sessions.js.map

package/dist/tasks/storage/records.js

@@ -0,0 +1,45 @@
+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";
+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"]),
+    nextAt: z.number().finite().nullable(), createdAt: timestamp,
+}).strict();
+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"]),
+    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(),
+    questions: z.array(questionData.extend({
+        id: z.string().uuid(), createdAt: timestamp, expiresAt: timestamp, sessionExpiresAt: timestamp.nullable(),
+        reply: z.object({ requestKey: identifier, answer: text(16000), receivedAt: timestamp }).strict().nullable(),
+    })).max(20),
+    nodes: z.array(z.object({
+        id: z.string().uuid(), definition: nodeData,
+        status: z.enum(["pending", "running", "awaiting_review", "succeeded", "failed", "blocked", "interrupted"]),
+        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(),
+    }).strict().superRefine((node, context) => {
+        if (["running", "awaiting_review", "succeeded"].includes(node.status) && (!node.startedAt || !node.turns.length)) {
+            context.addIssue({ code: "custom", message: "Started nodes require a start time and turn" });
+        }
+        if (node.status === "succeeded" && (!node.resultFile || !node.result?.trim() || !node.acceptance?.trim() || node.turns.at(-1)?.stopReason !== "end_turn")) {
+            context.addIssue({ code: "custom", message: "Accepted node requires a completed turn and delivery" });
+        }
+    })).min(1).max(20),
+}).strict().superRefine((run, context) => {
+    const live = ["running", "waiting_input"].includes(run.status);
+    if (live !== (run.finishedAt === null))
+        context.addIssue({ code: "custom", message: "Run completion time does not match status" });
+    if (run.status === "waiting_input" && (!run.questions.length || run.questions.at(-1).reply !== null)) {
+        context.addIssue({ code: "custom", message: "Waiting run requires an unanswered question" });
+    }
+    if (run.status === "succeeded" && (!run.summary?.trim() || run.nodes.some(node => node.status !== "succeeded"))) {
+        context.addIssue({ code: "custom", message: "Successful run requires accepted nodes and summary" });
+    }
+});
+//# sourceMappingURL=records.js.map

package/dist/{task-storage.js → tasks/storage/store.js}

@@ -1,34 +1,8 @@
-import { DatabaseSync } from "node:sqlite";
+import { DatabaseSync } from "../../infrastructure/sqlite.js";
 import { mkdirSync } from "node:fs";
 import { join } from "node:path";
-import { z } from "zod";
-import { executorSchema, identifier, timestamp } from "./model.js";
-import { nodeSchema, questionSchema, taskSchema } from "./task-contract.js";
-const definitionSchema = z.object({
-    id: z.string().uuid(), input: taskSchema, workspace: z.string().nullable(), executors: z.record(identifier, executorSchema),
-    status: z.enum(["active", "paused", "cancelled", "completed", "expired"]),
-    nextAt: z.number().finite().nullable(), createdAt: timestamp,
-}).strict();
-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"]),
-    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(),
-    questions: z.array(questionSchema.extend({
-        id: z.string().uuid(), createdAt: timestamp, expiresAt: timestamp, sessionExpiresAt: timestamp.nullable(),
-        reply: z.object({ requestKey: identifier, answer: z.string().min(1).max(16000), receivedAt: timestamp }).strict().nullable(),
-    })).max(20),
-    nodes: z.array(z.object({
-        id: z.string().uuid(), definition: nodeSchema,
-        status: z.enum(["pending", "running", "awaiting_review", "succeeded", "failed", "blocked", "interrupted"]),
-        workspace: z.string().nullable(), inputFiles: z.array(z.string()), resultFile: z.string().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(),
-    }).strict()).min(1).max(20),
-}).strict();
-export class StorageError extends Error {
-}
+import { StorageError } from "../../shared/errors.js";
+import { definitionSchema, roundSchema } from "./records.js";
 /** Task definitions and rounds share one transactional store. */
 export class TaskStore {
     db;
@@ -42,6 +16,8 @@ export class TaskStore {
             if (tables.length) {
                 this.db.prepare("SELECT seq,id,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();
             }
             this.db.exec("PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL; PRAGMA foreign_keys=ON");
             if (!tables.length)
@@ -52,44 +28,55 @@ export class TaskStore {
         COMMIT;`);
         }
         catch (error) {
-            this.db.close();
+            this.close();
             throw error;
         }
     }
     check() { if (this.closed)
         throw new StorageError("Task storage closed"); }
+    decode(schema, data) {
+        try {
+            return schema.parse(JSON.parse(String(data)));
+        }
+        catch (error) {
+            this.close();
+            throw new StorageError("Invalid stored task data; no conversion or repair performed", { cause: error });
+        }
+    }
     definitions() {
         this.check();
-        return this.db.prepare("SELECT data FROM definitions ORDER BY seq").all().map(row => definitionSchema.parse(JSON.parse(String(row["data"]))));
+        return this.db.prepare("SELECT data FROM definitions ORDER BY seq").all().map(row => this.decode(definitionSchema, row["data"]));
     }
     rounds(taskId) {
         this.check();
         const rows = taskId ? this.db.prepare("SELECT data FROM rounds WHERE task_id=? ORDER BY seq").all(taskId)
             : this.db.prepare("SELECT data FROM rounds ORDER BY seq").all();
-        return rows.map(row => roundSchema.parse(JSON.parse(String(row["data"]))));
+        return rows.map(row => this.decode(roundSchema, row["data"]));
     }
     activeRounds(taskId) {
         this.check();
         const rows = taskId
             ? this.db.prepare("SELECT data FROM rounds WHERE task_id=? AND json_extract(data,'$.status') IN ('running','waiting_input')").all(taskId)
             : this.db.prepare("SELECT data FROM rounds WHERE json_extract(data,'$.status') IN ('running','waiting_input')").all();
-        return rows.map(row => roundSchema.parse(JSON.parse(String(row["data"]))));
+        return rows.map(row => this.decode(roundSchema, row["data"]));
     }
     get(id) {
         this.check();
         const row = this.db.prepare("SELECT data FROM definitions WHERE id=?").get(id);
         if (!row)
             throw new Error("Task not found");
-        return definitionSchema.parse(JSON.parse(String(row["data"])));
+        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");
-        return roundSchema.parse(JSON.parse(String(row["data"])));
+        return this.decode(roundSchema, row["data"]);
     }
     /** The service supplies all policy; the store commits a cursor and round atomically. */
+    saveDefinition(task) { this.commit(task); }
+    commitRun(run, task) { this.commit(task, run); }
     commit(definition, round) {
         this.check();
         if (definition)
@@ -120,4 +107,4 @@ export class TaskStore {
         this.db.close();
     } }
 }
-//# sourceMappingURL=task-storage.js.map
+//# sourceMappingURL=store.js.map

package/dist/tasks/supervisor.js

@@ -0,0 +1,227 @@
+import { errorText, StorageError } from "../shared/errors.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. */
+export class RunSupervisor {
+    runs;
+    coordinate;
+    fatal;
+    closed = false;
+    closing;
+    timer;
+    active = new Map();
+    turns = new Set();
+    sessions;
+    constructor(runs, openExecution, coordinate, fatal) {
+        this.runs = runs;
+        this.coordinate = coordinate;
+        this.fatal = fatal;
+        this.sessions = new NodeSessions(openExecution, fatal);
+    }
+    check() { if (this.closed)
+        throw new Error("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 };
+    }
+    actions(id, requestId = coordinatorInput(this.runs.get(id)).requestId) {
+        this.check();
+        const current = () => { this.check(); return this.runs.current(id, requestId); };
+        return {
+            inspect: () => { current(); return this.runs.inspect(id, requestId); },
+            step: () => { current(); try {
+                this.runs.step(id);
+            }
+            finally {
+                this.reconcile(id);
+            } },
+            converse: (node, message) => { current(); return this.converse(id, node, message); },
+            accept: (node, turn, result, reason) => { current(); return this.accept(id, node, turn, result, reason); },
+            ask: request => {
+                current();
+                const question = this.runs.ask(id, request);
+                clearTimeout(this.active.get(id)?.timer);
+                return question;
+            },
+            finish: summary => { current(); this.runs.finish(id, summary); },
+            stop: (status, reason) => { current(); this.stopActive(id, status, reason); },
+        };
+    }
+    converse(id, nodeId, message) {
+        const pending = this.performTurn(id, nodeId, message);
+        this.turns.add(pending);
+        void pending.finally(() => this.turns.delete(pending)).catch(() => { });
+        return pending;
+    }
+    async performTurn(id, nodeId, message) {
+        this.check();
+        let dispatched = false;
+        try {
+            const dispatch = this.runs.prepareTurn(id, nodeId, message, this.sessions);
+            dispatched = true;
+            const handle = dispatch.kind === "continue" ? this.sessions.get(dispatch.nodeRunId)
+                : this.sessions.open(dispatch.nodeRunId, id, dispatch.input, dispatch.seconds, (kind, data, text) => this.runs.record(id, nodeId, kind, data, text), () => { this.check(); this.runs.beforeStart(id, nodeId); }, () => {
+                    const waiting = this.runs.get(id).status === "waiting_input";
+                    this.stopActive(id, waiting ? "interrupted" : "timed_out", waiting
+                        ? "ACP session lifetime expired while waiting; no replay" : "ACP node session timed out");
+                }, () => { if (!this.closed && this.runs.healthy)
+                    this.stopActive(id, "interrupted", "ACP session disconnected; external effects unknown"); });
+            const result = await handle.prompt(dispatch.text);
+            return this.runs.completeTurn(id, nodeId, result.stopReason);
+        }
+        catch (error) {
+            if (error instanceof StorageError)
+                this.fatal(error);
+            else if (dispatched && !this.closed && this.runs.healthy)
+                this.stopActive(id, "interrupted", errorText(error));
+            throw error;
+        }
+        finally {
+            if (!this.closed)
+                this.reconcile(id);
+        }
+    }
+    async accept(id, nodeId, turn, result, reason) {
+        this.check();
+        const owned = this.runs.accept(id, nodeId, turn, result, reason);
+        await this.sessions.closeSession(owned);
+    }
+    reconcile(id) {
+        if (!this.runs.healthy)
+            return;
+        if (["running", "waiting_input"].includes(this.runs.get(id).status))
+            return;
+        this.active.get(id)?.controller.abort(new Error("Run stopped"));
+        void this.sessions.closeRun(id).catch(this.fatal);
+    }
+    stopActive(id, status, reason) {
+        try {
+            this.runs.end(id, status, reason);
+        }
+        catch (error) {
+            this.fatal(error);
+        }
+        finally {
+            this.active.get(id)?.controller.abort(new Error(reason));
+            void this.sessions.closeRun(id).catch(this.fatal);
+        }
+    }
+    reply(input, now = Date.now()) {
+        this.check();
+        try {
+            return this.runs.reply(input, id => this.sessions.has(id), now);
+        }
+        finally {
+            this.reconcile(input.runId);
+        }
+    }
+    cancel(id) {
+        this.check();
+        this.runs.get(id);
+        this.stopActive(id, "cancelled", "Run cancelled; external effects are not rolled back");
+        return this.runs.get(id);
+    }
+    recover() {
+        this.check();
+        if (this.active.size || this.sessions.size)
+            throw new Error("Recovery requires no active resources");
+        this.runs.recover();
+    }
+    start() {
+        this.check();
+        if (this.timer)
+            throw new Error("Run supervisor already started");
+        this.recover();
+        this.timer = setInterval(() => this.tick(), 500);
+        this.tick();
+    }
+    tick() {
+        this.check();
+        try {
+            this.runs.trigger();
+            for (const run of this.runs.active()) {
+                if (run.status === "waiting_input") {
+                    this.runs.expireWaiting(run.id);
+                    this.reconcile(run.id);
+                    continue;
+                }
+                if (this.active.has(run.id) || this.active.size >= 4)
+                    continue;
+                this.launch(run.id);
+            }
+        }
+        catch (error) {
+            if (this.timer)
+                clearInterval(this.timer);
+            this.fatal(error);
+        }
+    }
+    launch(id) {
+        const coordinate = this.coordinate;
+        if (!coordinate) {
+            this.runs.end(id, "failed", "Coordinator not configured");
+            return;
+        }
+        const admission = this.runs.admitCoordinator(id);
+        if (!admission)
+            return;
+        const { input, remaining } = admission;
+        const stillCurrent = () => {
+            const current = this.runs.get(id);
+            return current.status === "running" && coordinatorInput(current).requestId === input.requestId;
+        };
+        const controller = new AbortController();
+        const timer = setTimeout(() => this.stopActive(id, "timed_out", "Task run timed out"), remaining);
+        // Register the controller before the deferred external entry. Recheck generation and cancellation there.
+        const completion = Promise.resolve().then(() => {
+            this.check();
+            controller.signal.throwIfAborted();
+            this.runs.current(id, input.requestId);
+            return coordinate(id, input, this.actions(id, input.requestId), controller.signal);
+        }).then(() => {
+            if (!this.closed && stillCurrent())
+                this.runs.end(id, "failed", "Coordinator ended without an explicit completion or blocking decision");
+        }, error => {
+            if (error instanceof StorageError)
+                throw error;
+            if (!this.closed && this.runs.healthy && stillCurrent())
+                this.runs.end(id, "failed", errorText(error));
+        }).catch(this.fatal).finally(async () => {
+            clearTimeout(timer);
+            try {
+                if (!this.runs.healthy || !["running", "waiting_input"].includes(this.runs.get(id).status))
+                    await this.sessions.closeRun(id);
+            }
+            finally {
+                this.active.delete(id);
+            }
+        }).catch(this.fatal);
+        this.active.set(id, { controller, completion, timer });
+    }
+    close() { return this.closing ??= this.stop(); }
+    async stop() {
+        this.closed = true;
+        if (this.timer)
+            clearInterval(this.timer);
+        const errors = [];
+        for (const id of this.sessions.runIds()) {
+            try {
+                this.runs.end(id, "interrupted", "Service stopped with an open ACP session");
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        for (const active of this.active.values()) {
+            clearTimeout(active.timer);
+            active.controller.abort(new Error("Service stopping"));
+        }
+        const stopped = await Promise.allSettled([this.sessions.close(), ...[...this.active.values()].map(active => active.completion), ...this.turns]);
+        // Rejected prompts are expected during cancellation; resource-close failures remain fatal.
+        if (stopped[0]?.status === "rejected")
+            errors.push(stopped[0].reason);
+        if (errors.length)
+            throw new AggregateError(errors, "Run supervision could not close cleanly");
+    }
+}
+//# sourceMappingURL=supervisor.js.map

package/dist/tasks/validation.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { absolutePath, identifier, text, timestamp } from "../shared/validation.js";
+export const scheduleData = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("now") }).strict(),
+    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 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),
+}).strict();
+export const questionData = z.object({ nodeId: identifier.optional(), question: text(4000), completedWork: text(4000) }).strict();
+export const replyData = z.object({
+    runId: z.string().uuid(), questionId: z.string().uuid(), requestKey: identifier, answer: text(16000),
+}).strict();
+/** Valid internal data. No request defaults, coercion or normalization at this boundary. */
+export const taskData = z.object({
+    requestKey: identifier, name: text(200), prompt: text(64_000), nodes: z.array(nodeData).min(1).max(20),
+    workspace: absolutePath.optional(), schedule: scheduleData, expiresAt: timestamp.optional(),
+    maxRunSeconds: z.number().int().min(1).max(86_400), maxSteps: z.number().int().min(1).max(200),
+    maxNodeTurns: z.number().int().min(1).max(10), inputWaitSeconds: z.number().int().min(1).max(604800),
+}).strict();
+export const taskUpdateData = z.object({ id: z.string().uuid(), action: z.enum(["pause", "resume", "cancel"]) }).strict();
+//# sourceMappingURL=validation.js.map

package/dist/web/settings-view.js

@@ -14,14 +14,18 @@ function executorEditor(host, executor) {
     const item = field(label, value, kind); fields[key] = item.input; card.append(item.row);
   }
   const approved = field("已由管理员审核原生授权，允许无人值守执行", executor.unattendedApproved, "checkbox");
-  for (const [key, input] of Object.entries(fields)) if (key !== "note") input.addEventListener("input", () => { approved.input.checked = false; });
+  let explicitlyApproved = false;
+  approved.input.addEventListener("change", () => { explicitlyApproved = approved.input.checked; });
+  for (const [key, input] of Object.entries(fields)) if (key !== "note") input.addEventListener("input", () => {
+    approved.input.checked = false; explicitlyApproved = false;
+  });
   card.append(approved.row, element("p", "按类型从用户原生 PATH 查找 ACP 适配器。继承用户原生环境，但过滤服务私密变量；额外 ACP 审批一律拒绝。结果固定保存在 dataDir/results，只向节点提供指定上游文件，不提供整个数据目录读取。"),
     button("从待保存配置中移除", () => { card.remove(); host.dispatchEvent(new Event("input", { bubbles: true })); }));
   host.append(card);
-  return () => card.parentNode === host ? [{
+  return () => card.parentNode === host ? [{ explicitlyApproved, executor: {
     id: fields.id.value, type: fields.type.value, note: fields.note.value,
     cwd: fields.cwd.value, unattendedApproved: approved.input.checked,
-  }] : [];
+  } }] : [];
 }
 function coordinatorEditor(host, config) {
   const provider = select("协调模型提供方", [["", "未配置"], ["openai", "OpenAI"], ["anthropic", "Anthropic"],
@@ -73,10 +77,13 @@ export async function renderSettings(root, navigate) {
   }, state.writeBlocked));
   const preview = element("div");
   const save = submit(form, "校验并预览配置变更", async () => {
-    const input = { editToken: state.editToken, config: { dataDir: startup.dataDir.input.value, port: startup.port.input.valueAsNumber, tokenEnv: startup.tokenEnv.input.value,
-      coordinator: readModel(), executors: readers.flatMap(read => read()) } };
+    const entries = readers.flatMap(read => read());
+    const input = { editToken: state.editToken, approveExecutors: entries.filter(item => item.explicitlyApproved).map(item => item.executor.id),
+      config: { dataDir: startup.dataDir.input.value, port: startup.port.input.valueAsNumber, tokenEnv: startup.tokenEnv.input.value,
+      coordinator: readModel(), executors: entries.map(item => item.executor) } };
     const checked = await request("/settings/validate", input);
     preview.replaceChildren(block("校验后的待保存配置", checked.config),
+      block("配置变更", checked.changes),
       block("重启后受执行端变更影响的任务", checked.affectedTasks));
     const affected = checked.affectedTasks.map(task => task.name + " (" + task.id + ")").join("\n") || "无";
     if (!confirm("本地校验通过，不代表模型认证或 ACP 执行已验证。\n受影响任务：\n" + affected +
@@ -121,6 +128,6 @@ export async function renderSettings(root, navigate) {
       const ready = await request("/restart", {});
       document.dispatchEvent(new CustomEvent("service-restarted", { detail: ready }));
     }, state.writeBlocked),
-    block("前台或 systemd / launchd 托管实例", "agent-task restart [--home /absolute/installation]"),
+    block("重启命令", "agent-task restart [--home /absolute/installation]"),
     element("p", "只有新实例通过认证健康检查才显示成功。若请求结果不确定，请先运行 agent-task status；启动失败时检查当前 dataDir/service.log，不删除历史或重放任务来修复。"));
 }

package/docs/architecture-guidelines.md

@@ -1,6 +1,6 @@
 # 架构原则
 
-目标是让维护者可以局部理解并安全修改系统，不为目录对称或未来假设增加机制。产品边界见[总体方案](design-proposal.md)，当前差距见[代码导航](technical-design.md)。
+目标是让维护者可以局部理解并安全修改系统，不为目录对称或未来假设增加机制。产品边界见[总体方案](design-proposal.md)，职责与资源所有权见[代码导航](technical-design.md)。
 
 ## 职责与依赖
 
@@ -12,11 +12,13 @@
 | MCP/ACP、进程及操作系统协议 | 接入 |
 | 依赖装配、运行实例及生命周期 | 应用入口 |
 | 普通领域数据，不含业务行为或 SDK 对象 | 模型 |
-| 展示与收集操作，通过服务执行 | Web 控制台 |
+| 展示与收集操作，通过服务执行 | Web 控制台、CLI |
 
 服务只接收普通数据和窄能力，不依赖 SDK 上下文、HTTP 对象、UI 或完整进程对象。接入实现服务所需能力，由入口装配；存储不反向依赖服务或协议。禁止循环依赖、隐藏的全局可变状态和服务定位器。
 
-当前仍是扁平 MVP，不要求立即按层建目录。修改受影响职责时连同边界收敛，并保持行为测试；不做纯目录搬迁，不加空目录、无人使用的接口、转发层或动态插件平台。依赖边界检查应在分层落实后引入，不能提前声称已有。
+CLI 覆盖 Web 的全部配置和管理操作，两端必须复用同一套底层服务，不维护各自的业务规则。
+
+按业务能力聚合模型、规则和服务，存储实现与协议接入保留明确边界。新增职责必须指定状态修改入口和资源所有者；保持关键行为测试，不加空目录、无人使用的接口、转发层或动态插件平台。实际分层和随 `npm run check` 执行的依赖检查见[代码导航](technical-design.md#依赖与一致性边界)。
 
 ## 执行与持久性
 
@@ -27,7 +29,7 @@
 - 未收到结果不等于没有执行。中断或结果不明时阻止新派发，包括模型新发起的调用；不自动重试、切换 Agent 或创建新身份重放。
 - 截止时间限制新执行开始，执行超时是另一规则。客户端断开不取消任务；取消不回滚外部操作。
 - 资源有明确所有者，关闭幂等，关闭后拒绝操作。先停止新派发，再处理活动执行、网络与存储，最后释放所有权。
-- 目录锁、事务、worker 监督和服务管理器解决不同问题，不等于跨机一致性、无孤儿进程或工具沙箱。
+- 目录锁、事务和 worker 监督解决不同问题，不等于跨机一致性、无孤儿进程或工具沙箱。
 
 ## 权限与敏感数据
 

package/docs/cli.md

@@ -0,0 +1,49 @@
+# 本机管理 CLI
+
+CLI 覆盖 Web 的配置、凭据、任务查询、未来触发控制及重启操作。两端通过同一管理 API 使用配置和任务服务；重启由同一启动器处理。命令入口见 [命令实现](../src/protocol/cli/commands.ts)，管理传输见 [admin-client.ts](../src/protocol/cli/admin-client.ts)。
+
+## 连接与命令
+
+先按[部署说明](deployment.md)安装并启动服务。CLI 通过安装目录定位当前实例，从私有环境文件读取管理员令牌，不需要复制令牌或登录命令。使用自定义安装目录时，每条命令都传入 `--home /absolute/installation`。
+
+```bash
+agent-task --help
+agent-task config --help
+agent-task executor --help
+agent-task coordinator --help
+agent-task credential --help
+agent-task task --help
+agent-task run --help
+```
+
+逐级帮助是命令与参数的完整入口。管理命令支持 `--json`，结果写入 stdout，预览和诊断写入 stderr；失败退出码非零。非交互保存与任务变更须使用 `--yes`，它只确认本次操作，不替代校验或执行端授权。
+
+服务不可用时，管理命令失败，不自动离线写文件。首次安装仍使用 `setup`；启动故障按[部署说明](deployment.md#前台重启与健康检查)停服核查。CLI 不迁移数据或修复历史。
+
+## 配置流程
+
+交互编辑可用 `agent-task config edit`。编辑器由 `--editor`、`VISUAL` 或 `EDITOR` 指定，值须是可执行文件名或路径，不包含 shell 参数。退出编辑器后先校验并显示影响，再确认保存。
+
+批量编辑使用配置草稿：
+
+```bash
+agent-task config export --output /absolute/private/draft.json
+# 编辑草稿中的配置，保留编辑令牌。
+agent-task config validate --file /absolute/private/draft.json
+agent-task config apply --file /absolute/private/draft.json --yes
+agent-task config diff
+agent-task restart
+agent-task config show --running
+```
+
+导出文件不包含密钥值，以私有权限创建，拒绝覆盖已有文件。编辑令牌过期、服务重启或任一客户端保存配置/凭据后，旧草稿不能提交；重新读取并人工核对，不自动合并。草稿契约见 [settings-contract.ts](../src/protocol/settings-contract.ts)。
+
+`executor` 和 `coordinator` 提供便捷操作，配置服务负责生成候选配置，再走同一预览、校验和保存流程。新执行端默认未批准；修改 ID、类型或工作空间后清除批准。原生授权审核完成后，显式运行 `executor approve ID`。完整草稿新增或变更已批准的执行端时，也须明确声明对候选配置的授权。
+
+配置与凭据均在下次启动生效。影响预览不修改旧任务快照，也不证明模型认证或 ACP 执行成功。保存顺序、端点与凭据隔离、重启影响见[控制台说明](web-console.md#保存与重启)。
+
+## 凭据与任务
+
+`credential set NAME` 使用隐藏终端输入；自动化通过 `--stdin --yes` 从可信凭据工具或受保护文件传值，不把值写进命令参数。`credential list` 只显示设置状态。执行端原生登录和权限继续由其官方工具管理。
+
+`task show ID` 查看固定 DAG，`run show ID` 查看节点、原始回合、已接受交付及问题回复。`task pause/resume/cancel` 仅控制未来触发，不停止当前运行；恢复不补跑，取消后不可恢复未来触发；有不确定外部结果时也拒绝恢复。操作边界与 Web 一致，见[控制台说明](web-console.md#操作范围)。