@tea-agent/loop-agent 0.38.0 → 0.38.2

package/dist/shared/operator/capabilities.js

@@ -13,13 +13,45 @@ const CONTROLLER_PROTOCOL_CAPABILITIES = [
     "worker-attempt-revision-v1",
     "recovery-decision-v2",
 ];
-function officialModelCallable(coverage, kind) {
+function officialModelCallable(coverage, _kind) {
     if (coverage === "human-gated-required")
         return "prepare-only";
-    if (coverage === "advanced" && kind !== "read")
+    // 2026-08-18: advanced actions (read or mutation) stay OUT of the model
+    // tool surface — low-frequency/forensic commands with generic args[] params
+    // diluted model attention. They remain dispatchable via UI capabilities.
+    if (coverage === "advanced")
         return "never";
     return "always";
 }
+const OFFICIAL_ACTION_DESCRIPTIONS = {
+    dagDecisionInspect: "Inspect a pending DAG decision envelope (inputs, options, chosen branch). Use before advising the operator on approve/reject; read-only.",
+    dagDecisionValidate: "Validate a DAG decision envelope against its schema. Use when a decision payload looks malformed or a writer emitted a suspect envelope; read-only.",
+    dagCloseoutDraft: "Draft the closeout handoff document for a finished DAG run. Use when the run is FINISHED and you need the handoff text; read-only.",
+    planList: "List execution plans in the repository. Use to discover plan ids before plan create/complete/check.",
+    planCreate: "Create an execution plan from a summary. Use to record the next work block before starting it.",
+    planComplete: "Mark an execution plan complete with a summary of what was delivered. Use after a work block is done and verified.",
+    planCheck: "Check execution-plan health and drift. Use to audit plan state without mutating anything.",
+    docsAudit: "Audit docs freshness and links (document catalog policy). Use when asked whether docs are stale or need review.",
+    handoffCheck: "Check handoff document completeness against the verification matrix. Use before claiming a task is fully handed off.",
+    handoffCoverage: "Show verification coverage across tests/docs/links for the repo. Use when asked what is verified and what is not.",
+    coverageReport: "Produce the verification coverage report. Use for a structured view of tests vs requirements.",
+    stats: "Repository workflow statistics (tasks, runs, durations). Use for quantitative status questions.",
+    promoteRun: "Task advance alias; passes a task id and flags through to task advance to promote a run. Does not pre-verify run state here — confirm with dagReport that the run is FINISHED before calling.",
+    closeoutTask: "Task advance alias; passes a task id and flags through to task advance to close out a task. Confirm the task's work is delivered and verified before calling.",
+    knowledgeCurate: "Generate knowledge-base curation proposals (may write a proposal file when --output is passed). Write-capable; use via the operator CLI, not as a model tool.",
+    knowledgeQuery: "Query the repository knowledge base. Use instead of re-reading files when a curated answer may exist.",
+    workerFeatureReview: "Review worker feature status and checkpoints (agent-worker). Use to see where a feature line stands.",
+    workerFeatureDoctor: "Diagnose worker feature health (agent-worker). Use when a feature line looks stuck or inconsistent.",
+    workerTaskValidate: "Validate a worker task spec (agent-worker). Use before queuing or when a task looks malformed.",
+    workerBatchPlanReady: "Show which batch tasks are ready to run (agent-worker). Use for queue triage before workerBatchRunReady.",
+    workerReportMorning: "Morning report for overnight worker activity (agent-worker). Use at the start of a session to catch overnight failures.",
+    workerReportMetrics: "Worker throughput and failure metrics (agent-worker). Use for quantitative worker questions.",
+    workerAdmissionShow: "Show night admission queue state (agent-worker). Use before night-scheduler mutations.",
+    workerSchedulerList: "List night-scheduler schedules (agent-worker). Use to discover schedule ids.",
+    workerSchedulerStatus: "Night-scheduler status overview (agent-worker). Use to check whether overnight jobs are healthy.",
+    workerSchedulerLedger: "Night-scheduler harvest ledger (agent-worker). Use to audit what overnight runs produced.",
+    workerSchedulerDoctor: "Diagnose night-scheduler health (agent-worker). Use when overnight jobs fail to fire or harvest.",
+};
 const officialAction = (action, cli, kind, coverage) => ({
     action,
     cli,
@@ -38,7 +70,8 @@ const officialAction = (action, cli, kind, coverage) => ({
             "TRANSACTION_INCOMPLETE",
             "NOT_FOUND",
         ],
-    description: `Official CLI action coverage for ${cli}.`,
+    description: OFFICIAL_ACTION_DESCRIPTIONS[action] ??
+        `Official CLI action coverage for ${cli}.`,
     inputParams: [
         {
             name: "args",
@@ -63,8 +96,6 @@ const officialAction = (action, cli, kind, coverage) => ({
 });
 const OFFICIAL_ACTIONS = [
     ...[
-        ["dagDoctor", "loop-agent dag doctor", "read", "model-callable"],
-        ["dagStatus", "loop-agent dag status", "read", "model-callable"],
         [
             "dagDecisionInspect",
             "loop-agent dag decision inspect",
@@ -160,8 +191,8 @@ const OFFICIAL_ACTIONS = [
         [
             "knowledgeCurate",
             "loop-agent knowledge curate",
-            "read",
-            "model-callable",
+            "mutation",
+            "advanced",
         ],
         ["knowledgeQuery", "loop-agent knowledge query", "read", "model-callable"],
         [
@@ -284,7 +315,6 @@ const OFFICIAL_ACTIONS = [
             "long-running",
             "advanced",
         ],
-        ["workerPoolDoctor", "agent-worker pool doctor", "read", "model-callable"],
         [
             "workerPoolMarkFailed",
             "agent-worker pool mark-failed",
@@ -337,6 +367,12 @@ const OFFICIAL_ACTIONS = [
         ],
     ],
 ].map(([action, cli, kind, coverage]) => officialAction(action, cli, kind, coverage));
+/**
+ * Action ids produced by the officialAction() factory (the generic CLI
+ * coverage tail). Derived from the same tuple table so dispatcher / gate
+ * checks do not string-match descriptions.
+ */
+export const OFFICIAL_TAIL_ACTION_IDS = new Set(OFFICIAL_ACTIONS.map((entry) => entry.action));
 /** Shared constants so dag + dagSpecVersions cannot diverge. */
 const DAG_SPEC_SUPPORTED_PARSE = [1, 2, 3, 4];
 const DAG_SPEC_NEW_WRITER_DEFAULT = 4;
@@ -612,7 +648,7 @@ export function buildOperatorCapabilitiesDocument() {
             resultSchemaVersion: 1,
             envelopeSchemaVersion: 1,
             requiredErrorCodes: [...COMMON_MUTATION_ERRORS],
-            description: "Create or advance a task via the single lifecycle mutation entry.",
+            description: "Create a new task (lifecycle entry). Prefer taskAdvance for the standard flow (PRD import, taskKind, boundaries, DAG generation); newTask only bootstraps a task id + title.",
             inputParams: [
                 {
                     name: "taskId",
@@ -688,7 +724,7 @@ export function buildOperatorCapabilitiesDocument() {
             resultSchemaVersion: 1,
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["NOT_FOUND", "INVALID_INPUT"],
-            description: "Read source instruction contract for a task.",
+            description: "Read the task's source instruction contract (需求.md/执行约束.md projection: requirements, constraints, allowed/forbidden paths). Use before drafting or revising a contract to stay aligned with the source.",
             inputParams: [
                 {
                     name: "taskId",
@@ -838,8 +874,33 @@ export function buildOperatorCapabilitiesDocument() {
             resultSchemaVersion: 1,
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["INVALID_INPUT"],
-            description: "Build Observe deep link from stable object identity.",
-            inputParams: [],
+            description: "Build Observe deep link from stable object identity. Pass exactly one of dagRunId (preferred), taskId (resolves to latest run), featureId, or workerRunId; omit all for the Console home link.",
+            inputParams: [
+                {
+                    name: "dagRunId",
+                    type: "string",
+                    required: false,
+                    description: "dag run id; deep-links to #/dag/<runId> (preferred when known)",
+                },
+                {
+                    name: "taskId",
+                    type: "string",
+                    required: false,
+                    description: "task id; resolves to the latest dag run when one exists, else #/task/<taskId>",
+                },
+                {
+                    name: "featureId",
+                    type: "string",
+                    required: false,
+                    description: "feature line id; deep-links to the feature view",
+                },
+                {
+                    name: "workerRunId",
+                    type: "string",
+                    required: false,
+                    description: "worker run id; deep-links to the worker run view",
+                },
+            ],
             modelCallable: "always",
             humanConfirmation: "none",
         },
@@ -851,7 +912,7 @@ export function buildOperatorCapabilitiesDocument() {
             resultSchemaVersion: 1,
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["INVALID_INPUT"],
-            description: "Repo preflight (registry entry; envelope migration follow-up).",
+            description: "Preflight a repository for loop-agent: checks harness presence, task-pool layout, and reports what the Console can operate on. Use at session start on an unfamiliar repo, before init/upgrade decisions.",
             inputParams: [],
             modelCallable: "always",
             humanConfirmation: "none",
@@ -910,7 +971,7 @@ export function buildOperatorCapabilitiesDocument() {
             resultSchemaVersion: 1,
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["NOT_FOUND", "INVALID_INPUT"],
-            description: "Task lifecycle status (read-only).",
+            description: "Read one task's lifecycle status: state, blockers, gates, contract revision, run associations. Use for task-level questions; use dagStatus for a specific DAG run's live node/liveness.",
             inputParams: [
                 {
                     name: "taskId",
@@ -930,7 +991,7 @@ export function buildOperatorCapabilitiesDocument() {
             resultSchemaVersion: 1,
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["NOT_FOUND", "INVALID_INPUT"],
-            description: "Spine audit (registry entry).",
+            description: "Audit a task's minimal spec spine: source docs, path ownership, requirement ids, final verification coverage. Use before closing out a task to confirm every AC is verified.",
             inputParams: [
                 {
                     name: "taskId",
@@ -1023,7 +1084,7 @@ export function buildOperatorCapabilitiesDocument() {
                 "EXTERNALLY_MODIFIED",
                 "INVALID_INPUT",
             ],
-            description: "Generate + strict-validate DAG via task advance (stops at writeSet gate).",
+            description: "Generate + strict-validate a task's DAG (via task advance, stops at the writeSet gate). Legacy entry; the standard flow is taskAdvance then prepareDagExecution + runDag.",
             inputParams: [
                 {
                     name: "taskId",
@@ -1079,7 +1140,7 @@ export function buildOperatorCapabilitiesDocument() {
                 "CONTROLLER_MISMATCH",
                 "INVALID_INPUT",
             ],
-            description: "Consume a single-use execution receipt and execute the reviewed DAG (prefer task advance --approve-gate when gate token present). accepted/queued/running/operationId are NOT completion — supervise via operationGet/status/dagReport/dagDoctor/operationWait.",
+            description: "Consume a single-use executionId from prepareDagExecution and execute the reviewed DAG. Do not pass a DAG path and do not bash `task advance --approve-gate`. accepted/queued/running/operationId are NOT completion — supervise via operationGet/status/dagReport/dagDoctor/operationWait.",
             inputParams: [
                 {
                     name: "executionId",
@@ -1102,7 +1163,7 @@ export function buildOperatorCapabilitiesDocument() {
             resultSchemaVersion: 1,
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["INVALID_INPUT", "NOT_FOUND"],
-            description: "Read-only R1 subgraph plan (no mutation). Call before dagRerun. Prefer primaryFailure.nodeId from dagReport. If eligible=false (writer/decision/fingerprint, unsafe shell, worker-managed, workspace/controller drift), do not force execute — Worker-owned runs use workerTaskRetry; standalone runs use standaloneTaskRerun or same-task advance after fixing the root cause (contract changes must be adopted first). Returns planHash required by execute.",
+            description: "Read-only check for failed-node recovery; it does not execute. Call after dagReport with primaryFailure.nodeId. eligible=true returns the exact planHash required by dagRerun. eligible=false covers writer/decision/fingerprint, unsafe shell, Worker ownership, or workspace/controller drift: use workerTaskRetry for Worker/Task Pool failures, or standaloneTaskRerun after any required contract adopt for standalone runs. Do not force dagRerun or invent a new task.",
             inputParams: [
                 {
                     name: "runId",
@@ -1132,7 +1193,7 @@ export function buildOperatorCapabilitiesDocument() {
                 "BINDING_DRIFT",
                 "INVALID_INPUT",
             ],
-            description: "Execute R1 continuation from effective node. Requires planHash from a fresh dagRerunPlan (eligible=true). Prefer this over new task / standaloneTaskRerun for provider flake and safe downstream failures. Server enforces planHash/binding/fingerprint freshness.",
+            description: "Continue the same DAG from the effective failed node by creating a continuation run. Requires a fresh eligible dagRerunPlan and its exact planHash. Prefer this for provider, network, rate-limit, timeout, and other safe downstream failures. Not a full task regenerate: use standaloneTaskRerun for that. Server rejects stale planHash, binding, or fingerprint drift.",
             inputParams: [
                 {
                     name: "runId",
@@ -1498,7 +1559,7 @@ export function buildOperatorCapabilitiesDocument() {
                 "INVALID_INPUT",
                 "HUMAN_CONFIRMATION_REQUIRED",
             ],
-            description: "Full standalone task regenerate → validate → execute with parent lineage. Only when node rerun plan is ineligible or primaryRecovery recommends rerun-task; the server checks read-only run facts before accepting. Regeneration reuses the CURRENT contract snapshot: if the failure requires contract changes (e.g. allowing a catalog index path), first update the contract (re-import PRD, or adopt externally-edited sources via `task contract adopt`) BEFORE calling this action, otherwise the regenerated DAG repeats the same failure.",
+            description: "Regenerate the whole standalone DAG from the CURRENT contract, then validate and execute a new run with parent lineage and the latest unresolved verify/review feedback when available. This is NOT continue-from-failed-node (use dagRerun for that). Server rejects the call when dagRerunPlan is eligible, primaryRecovery.humanRequired=true, or run facts do not recommend rerun-task. Feedback is recovery context, not a contract rewrite; adopt required contract changes before calling or the new DAG repeats the same failure.",
             inputParams: [
                 {
                     name: "runId",
@@ -1542,7 +1603,7 @@ export function buildOperatorCapabilitiesDocument() {
                 "INVALID_INPUT",
                 "HUMAN_CONFIRMATION_REQUIRED",
             ],
-            description: "Requeue failed Task Pool task (Failed → Ready) via in-package pool store. Only when read-only validation confirms the task exists in Failed state; the server checks this before accepting.",
+            description: "Requeue a Worker Task Pool task Failed → Ready. Not a DAG node rerun (use dagRerun) and not a standalone DAG regenerate (use standaloneTaskRerun). Confirm with workerPoolDoctor first; server accepts only Failed pool tasks. Pass featureId when known — it must match the pool record.",
             inputParams: [
                 {
                     name: "taskId",
@@ -1568,6 +1629,66 @@ export function buildOperatorCapabilitiesDocument() {
             modelCallable: "always",
             humanConfirmation: "none",
         },
+        {
+            action: "dagDoctor",
+            cli: "loop-agent dag doctor [--run-id <id>] --json",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["NOT_FOUND", "INVALID_INPUT"],
+            description: "Diagnose DAG run health. Omit runId for a repo-wide inventory (active/paused/completed + health issues). Pass runId for one run's liveness, heartbeat, failure node, and recovery hints. Use this to supervise stalls; it does not mutate the run.",
+            inputParams: [
+                {
+                    name: "runId",
+                    type: "string",
+                    required: false,
+                    description: "optional dag run id; omit to inventory all runs, pass to diagnose one run",
+                },
+            ],
+            modelCallable: "always",
+            humanConfirmation: "none",
+        },
+        {
+            action: "dagStatus",
+            cli: "loop-agent dag status --run-id <id>",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["NOT_FOUND", "INVALID_INPUT"],
+            description: "Read one DAG run's live status, current node, and liveness. Requires runId. Complements dagReport (terminal handoff) and dagDoctor (health diagnosis). Does not mutate the run.",
+            inputParams: [
+                {
+                    name: "runId",
+                    type: "string",
+                    required: true,
+                    description: "dag run id",
+                },
+            ],
+            modelCallable: "always",
+            humanConfirmation: "none",
+        },
+        {
+            action: "workerPoolDoctor",
+            cli: "agent-worker pool doctor --repo . --json",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["INVALID_INPUT", "NOT_FOUND"],
+            description: "Read-only Task Pool inventory (legacy + v2). Use before workerTaskRetry to confirm the task exists and status is Failed. Optional taskId filters the returned inventory to that task.",
+            inputParams: [
+                {
+                    name: "taskId",
+                    type: "string",
+                    required: false,
+                    description: "optional task id to focus the inventory",
+                },
+            ],
+            modelCallable: "always",
+            humanConfirmation: "none",
+        },
         ...OFFICIAL_ACTIONS,
     ];
     return {
@@ -1947,12 +2068,12 @@ export const OPERATOR_COMMAND_COVERAGE = Object.freeze([
     },
     {
         command: "loop-agent knowledge curate",
-        coverage: "model-callable",
+        coverage: "advanced",
         action: "knowledgeCurate",
         source: "loop-agent",
+        note: "Writes knowledge proposals (conditional on --output); not model-callable.",
     },
-    {
-        command: "loop-agent knowledge query",
+    { command: "loop-agent knowledge query",
         coverage: "model-callable",
         action: "knowledgeQuery",
         source: "loop-agent",
@@ -2527,9 +2648,10 @@ export function assertCoverageManifestConsistent() {
                 capability.humanConfirmation !== "required"))
             throw new Error(`invalid required gate classification: ${entry.action}`);
         if (entry.coverage === "advanced") {
-            const expected = capability.kind === "read" ? "always" : "never";
-            if (capability.modelCallable !== expected) {
-                throw new Error(`invalid advanced classification: ${entry.action} (expected modelCallable=${expected} for kind=${capability.kind})`);
+            // 2026-08-18: advanced actions are never model-callable (read or
+            // mutation) — see officialModelCallable. UI dispatch stays available.
+            if (capability.modelCallable !== "never") {
+                throw new Error(`invalid advanced classification: ${entry.action} (expected modelCallable=never)`);
             }
         }
     }

package/dist/task/config-types.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { isOpenspecSpecFilePath } from "../shared/openspec-spec.js";
 export const taskFlowSchema = z.enum([
     "auto",
     "micro",
@@ -65,6 +66,24 @@ export const frontendMockConfigSchema = z.object({
     serviceRoot: z.string().min(1).optional(),
     verifyCommands: z.array(frontendMockVerifyCommandSchema).optional().default([]),
 });
+/** OpenSpec gate policy for frontend prewrite: cited (default) vs scan-strict. */
+export const frontendOpenspecPolicySchema = z.enum(["cited", "scan-strict"]);
+/**
+ * Frontend OpenSpec gate configuration. `cited` (the task-config default) makes
+ * the prewrite gate verify contract-declared requiredReadPaths plus task-source
+ * citations instead of the full generation-time directory snapshot; `scan-strict`
+ * keeps the auto-discovered full-read semantics.
+ */
+export const frontendOpenspecConfigSchema = z.object({
+    policy: frontendOpenspecPolicySchema.optional().default("cited"),
+    requiredReadPaths: z
+        .array(z
+        .string()
+        .refine((candidate) => !candidate.includes("\\") &&
+        isOpenspecSpecFilePath(candidate), "frontendOpenspec.requiredReadPaths entries must be repo-relative supported files under openspec/schemas/, openspec/project-specs/, or ai_workspace/"))
+        .optional()
+        .default([]),
+});
 /** Batch limits and gate profile for the browser-driven frontend test DAG.
  * Token fields are post-case stop thresholds, not model-provider hard caps. */
 export const frontendTestConfigSchema = z.object({
@@ -105,6 +124,26 @@ export const frontendTestConfigSchema = z.object({
         .strict()
         .optional(),
 });
+/** Backend-test artifact layout and pipeline mode configuration (plan A/B/D). */
+export const backendTestConfigSchema = z
+    .object({
+    /** Repository-relative test root. Default "testcase". */
+    testRoot: z.string().min(1).optional(),
+    /** Markdown subdirectory relative to testRoot. Default "md". */
+    markdownRel: z.string().min(1).optional(),
+    /** Pytest script subdirectory relative to testRoot. Default "." (testRoot itself). */
+    scriptRel: z.string().min(1).optional(),
+    /** User-provided shared setup document (plan B). Read-only bound source. */
+    sharedSetupDoc: z.string().min(1).optional(),
+    /** Pipeline mode: full 16-node chain (default) or gap-fill incremental DAG (plan D). */
+    mode: z.enum(["full", "gap-fill"]).optional(),
+    /** Required for mode=gap-fill: user missing-scenario document path. */
+    gapDoc: z.string().min(1).optional(),
+    /** gap-fill pytest execution scope: only affected items (default) or all eligible. */
+    executeScope: z.enum(["affected", "all"]).optional(),
+})
+    .strict()
+    .optional();
 export const convergenceConfigSchema = z.object({
     enabled: z.boolean().optional().default(false),
     maxPasses: z.number().int().positive().optional().default(3),
@@ -175,6 +214,10 @@ const taskConfigObjectSchema = z.object({
     frontendMock: frontendMockConfigSchema.optional(),
     /** Frontend browser-test batch and post-case token-stop configuration. */
     frontendTest: frontendTestConfigSchema.optional(),
+    /** Frontend OpenSpec gate policy and contract-declared required read paths. */
+    frontendOpenspec: frontendOpenspecConfigSchema.optional(),
+    /** Backend-test layout / shared-setup / gap-fill configuration. */
+    backendTest: backendTestConfigSchema,
     notes: z.string().optional().default(""),
 });
 export const taskConfigSchema = z.preprocess((raw) => {