@tea-agent/loop-agent 0.39.3 → 0.40.0-beta.2

package/dist/workflows/dag/types.js

@@ -80,7 +80,10 @@ export const dagShellVerifyEvidenceSchema = z.object({
     selectionReasons: z.array(z.string()).default([]),
     /** Non-executing generation-time cwd/local-script validation evidence. */
     preflight: z
-        .array(z.object({ label: z.string(), status: z.enum(["ok", "future-delivery-script"]) }))
+        .array(z.object({
+        label: z.string(),
+        status: z.enum(["ok", "future-delivery-script"]),
+    }))
         .default([]),
     /** Effective timeout applied independently to each shell command. */
     commandTimeoutMs: z.number().int().positive().optional(),
@@ -382,7 +385,7 @@ export const dagWritePolicySchema = z.enum([
     "none",
 ]);
 /** Git/post-diff write guard intensity for exclusive Pi writers. */
-export const dagWriteGuardPolicySchema = z.enum(["full", "tools-only"]);
+export const dagWriteGuardPolicySchema = z.enum(["full", "tools-only", "filesystem-only"]);
 /**
  * Fail-closed outcome/diff consistency contract for bounded Pi writers.
  * The writer must begin with IMPLEMENTATION_OUTCOME: changed,
@@ -589,6 +592,8 @@ export const dagDynamicExpansionChildTaskSchema = z.object({
     allowedPaths: z.array(z.string()).optional().default([]),
     forbiddenPaths: z.array(z.string()).optional().default([]),
     writeSet: z.array(z.string()).optional(),
+    /** Template-rendered strict repository-relative read allowlist. */
+    readSet: z.array(z.string()).optional(),
     /**
      * Materialized-child pass-through fields for bounded Pi writer children
      * (backend-test md/pytest case sharding). All optional so legacy
@@ -732,7 +737,58 @@ export const structuredContractOutputSchemaIds = [
     "frontend-implementation-contract-plan-patch-v1",
     "frontend-implementation-contract-revision-patch-v1",
 ];
-export const dagTaskSchema = z.object({ id: z.string().regex(/^[a-z][a-z0-9-]*$/, "task id must be kebab-case"),
+export const dagArtifactIdentitySchema = z
+    .string()
+    .regex(/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/, "artifact id must be stable lower-case dot/kebab syntax");
+const dagArtifactRelativePathSchema = z
+    .string()
+    .min(1)
+    .refine((value) => !value.includes("\0"), "artifact path must not contain NUL")
+    .refine((value) => !value.includes("\\"), "artifact path must use POSIX separators")
+    .refine((value) => !value.startsWith("/") && !/^[A-Za-z]:/.test(value), "artifact path must be run-relative")
+    .refine((value) => value.split("/").every((segment) => segment !== "" && segment !== ".."), "artifact path must not escape the run");
+export const dagProducedArtifactSchema = z
+    .object({
+    artifactId: dagArtifactIdentitySchema,
+    kind: z.enum(["structured", "assistant", "stdout"]),
+    path: dagArtifactRelativePathSchema,
+    mediaType: z.string().min(1),
+    schemaId: z.string().min(1).optional(),
+    revisionPolicy: z.enum(["immutable", "replace-file"]),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    if (value.kind === "structured" && !value.schemaId) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["schemaId"],
+            message: "structured artifact requires schemaId",
+        });
+    }
+    if (value.kind !== "structured" && value.schemaId) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["schemaId"],
+            message: "only structured artifacts may declare schemaId",
+        });
+    }
+    if (value.revisionPolicy === "replace-file" &&
+        value.kind !== "structured") {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["revisionPolicy"],
+            message: "MVP revisions are limited to structured artifacts",
+        });
+    }
+});
+export const dagConsumedArtifactSchema = z
+    .object({
+    artifactId: dagArtifactIdentitySchema,
+    required: z.boolean().default(true),
+})
+    .strict();
+export const dagTaskSchema = z.object({
+    id: z.string().regex(/^[a-z][a-z0-9-]*$/, "task id must be kebab-case"),
     depends_on: z.array(z.string()).default([]),
     /**
      * How SKIPPED upstreams affect readiness.
@@ -776,10 +832,34 @@ export const dagTaskSchema = z.object({ id: z.string().regex(/^[a-z][a-z0-9-]*$/
     commandPolicy: dagCommandPolicySchema.optional(),
     writePolicy: dagWritePolicySchema.optional(),
     writeSet: z.array(z.string()).optional(),
+    /** Strict repository-relative read allowlist for bounded Pi nodes. */
+    readSet: z.array(z.string()).optional(),
+    /**
+     * Online per-attempt Pi context guard. Unlike run/map cost budgets, this
+     * aborts the active SDK session before an oversized conversation reaches
+     * the provider's context rejection boundary.
+     */
+    contextBudget: z
+        .object({
+        maxTurns: z.number().int().positive().optional(),
+        maxTokens: z.number().int().positive().optional(),
+    })
+        .strict()
+        .refine((value) => value.maxTurns !== undefined || value.maxTokens !== undefined, "contextBudget requires maxTurns or maxTokens")
+        .optional(),
     piStep: z.string().optional(),
     shell: dagShellConfigSchema.optional(),
     static: dagStaticConfigSchema.optional(),
     outputContract: z.string().optional(),
+    /**
+     * Frozen producer declarations for run-owned artifacts. These declarations,
+     * together with consumesArtifacts, are the only authority for artifact
+     * lineage and impact analysis. Prompt/outputContract/path heuristics are
+     * intentionally forbidden.
+     */
+    producesArtifacts: z.array(dagProducedArtifactSchema).optional(),
+    /** Frozen logical artifact inputs consumed by this node. */
+    consumesArtifacts: z.array(dagConsumedArtifactSchema).optional(),
     outputMode: dagOutputModeSchema.optional(),
     firstProtocolLine: z.string().min(1).optional(),
     /**
@@ -808,8 +888,7 @@ export const dagTaskSchema = z.object({ id: z.string().regex(/^[a-z][a-z0-9-]*$/
     })
         .strict()
         .superRefine((value, ctx) => {
-        if (value.schemaId ===
-            "frontend-implementation-contract-plan-patch-v1" &&
+        if (value.schemaId === "frontend-implementation-contract-plan-patch-v1" &&
             !value.skeleton) {
             ctx.addIssue({
                 code: "custom",
@@ -864,6 +943,121 @@ export const dagTaskSchema = z.object({ id: z.string().regex(/^[a-z][a-z0-9-]*$/
     dynamicCondition: dagDynamicConditionSchema.optional(),
     dynamicLoopUntil: dagDynamicLoopUntilSchema.optional(),
 });
+function hasTransitiveDependency(tasksById, consumerNodeId, producerNodeId) {
+    const queue = [...(tasksById.get(consumerNodeId)?.depends_on ?? [])];
+    const seen = new Set();
+    while (queue.length > 0) {
+        const nodeId = queue.shift();
+        if (nodeId === producerNodeId)
+            return true;
+        if (seen.has(nodeId))
+            continue;
+        seen.add(nodeId);
+        queue.push(...(tasksById.get(nodeId)?.depends_on ?? []));
+    }
+    return false;
+}
+function validateFrozenArtifactBindings(tasks, ctx) {
+    const tasksById = new Map(tasks.map((task) => [task.id, task]));
+    const producers = new Map();
+    const paths = new Map();
+    for (const [taskIndex, task] of tasks.entries()) {
+        const localIds = new Set();
+        for (const [artifactIndex, artifact] of (task.producesArtifacts ?? []).entries()) {
+            if (localIds.has(artifact.artifactId) ||
+                producers.has(artifact.artifactId)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: [
+                        "tasks",
+                        taskIndex,
+                        "producesArtifacts",
+                        artifactIndex,
+                        "artifactId",
+                    ],
+                    message: `artifact ${artifact.artifactId} must have exactly one producer`,
+                });
+            }
+            else {
+                producers.set(artifact.artifactId, {
+                    nodeId: task.id,
+                    taskIndex,
+                    artifactIndex,
+                    path: artifact.path,
+                });
+            }
+            localIds.add(artifact.artifactId);
+            const foldedPath = artifact.path
+                .normalize("NFC")
+                .toLocaleLowerCase("en-US");
+            const existingArtifactId = paths.get(foldedPath);
+            if (existingArtifactId && existingArtifactId !== artifact.artifactId) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: [
+                        "tasks",
+                        taskIndex,
+                        "producesArtifacts",
+                        artifactIndex,
+                        "path",
+                    ],
+                    message: `artifact path collides with ${existingArtifactId} under case folding`,
+                });
+            }
+            else {
+                paths.set(foldedPath, artifact.artifactId);
+            }
+        }
+    }
+    for (const [taskIndex, task] of tasks.entries()) {
+        const consumed = new Set();
+        for (const [artifactIndex, binding] of (task.consumesArtifacts ?? []).entries()) {
+            if (consumed.has(binding.artifactId)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: [
+                        "tasks",
+                        taskIndex,
+                        "consumesArtifacts",
+                        artifactIndex,
+                        "artifactId",
+                    ],
+                    message: `artifact ${binding.artifactId} is consumed more than once by ${task.id}`,
+                });
+            }
+            consumed.add(binding.artifactId);
+            const producer = producers.get(binding.artifactId);
+            if (!producer) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: [
+                        "tasks",
+                        taskIndex,
+                        "consumesArtifacts",
+                        artifactIndex,
+                        "artifactId",
+                    ],
+                    message: `artifact ${binding.artifactId} has no declared producer`,
+                });
+                continue;
+            }
+            if (producer.nodeId === task.id ||
+                !hasTransitiveDependency(tasksById, task.id, producer.nodeId)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: [
+                        "tasks",
+                        taskIndex,
+                        "consumesArtifacts",
+                        artifactIndex,
+                        "artifactId",
+                    ],
+                    message: `consumer ${task.id} must be downstream of producer ${producer.nodeId}`,
+                });
+            }
+        }
+    }
+}
 export const dagModelsSchema = z
     .object({
     HIGH: z.string().optional(),
@@ -893,9 +1087,7 @@ export const dagBudgetSchema = campaignBudgetSchema;
 export const dagSourceBindingSourceSchema = z.object({
     kind: z.enum(["requirement", "constraint", "reference"]),
     path: z.string().min(1),
-    sha256: z
-        .string()
-        .regex(/^[a-f0-9]{64}$/, "sha256 must be lowercase hex"),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/, "sha256 must be lowercase hex"),
 });
 /**
  * DagSourceBinding v1：无 ledger 字段（schemaVersion=1，.strict() 拒绝 ledger
@@ -997,6 +1189,8 @@ export const dagSpecSchema = z
     taskContractBinding: dagTaskContractBindingSchema.optional(),
     /** Optional unresolved parent-run feedback for a full task rerun. */
     rerunFeedback: dagRerunFeedbackSchema.optional(),
+    /** Backend-test-only workspace mutation control; absent means Git. */
+    backendTestWorkspaceControl: z.enum(["git", "filesystem-only"]).optional(),
     /** Frozen backend-test artifact layout (plan A); absent = historical default testcase/ layout. */
     backendTestLayout: z
         .object({
@@ -1044,6 +1238,7 @@ export const dagSpecSchema = z
 })
     .superRefine((spec, ctx) => {
     const supportsV3Fields = spec.version === 3 || spec.version === 4;
+    validateFrozenArtifactBindings(spec.tasks, ctx);
     if (spec.evaluation && !supportsV3Fields) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,

package/docs/README.md

@@ -73,6 +73,7 @@
 | `design/active/` | 仍会影响后续决策的设计输入、路线与契约 |
 | `design/visual-references/` | 长期视觉参考，不表达实现状态 |
 | `design/archive/` | 历史设计和已被实现/替代的阶段性设计 |
+| `superpowers/specs/` | Superpowers 工作流产出的阶段性实现设计输入 |
 | `exec-plans/active/` | 仍需推进或明确保持 open 的任务合同 |
 | `exec-plans/completed/` | 已完成任务合同归档 |
 | `progress/` | 仍需下一次会话接手的当前 handoff 入口 |

package/docs/architecture/runtime-boundaries.md

@@ -160,18 +160,18 @@ Runner / Loop         ──(迁移中)──>  逐步改为仅经 Store / Appli
 
 | From | May import | Must not import |
 | ------ | ------------ | ----------------- |
-| `src/commands/**` | application, workflows, infrastructure, task, records, executors, shared | — |
-| `src/workflows/**` | executors, task, records, shared, application（目标） | `src/commands/**` |
+| `src/commands/**` | application, workflows, infrastructure, task, records, executors, shared | `src/worker/**` |
+| `src/workflows/**` | executors, task, records, shared, infrastructure, application（目标） | `src/commands/**` |
 | `src/executors/**` | shared, 外部 SDK | `src/commands/**`, `src/cli/**` |
-| `src/worker/**` | worker-local modules, task contracts, shared, Node APIs | `src/commands/**`, `src/cli/**`, `src/application/**` |
-| `src/cli/**` | commands, adapters, shared, application（目标） | — |
+| `src/worker/**` | worker-local modules, task contracts, shared, infrastructure, Node APIs | `src/commands/**`, `src/cli/**`, `src/application/**` |
+| `src/cli/**` | commands, adapters, shared, infrastructure, application（目标） | — |
 | `.agents/skills/**` | （Markdown 引用，非 TS import） | 运行时 TS 模块 |
 
 ## 已知过渡耦合
 
-当前没有允许的 `src/workflows/**` / `src/executors/**` forbidden import，也没有允许的 `src/worker/**` → `src/{cli,commands,application}/**` TypeScript import。
+当前没有允许的 `src/workflows/**` / `src/executors/**` forbidden import，也没有允许的 `src/worker/**` → `src/{cli,commands,application}/**` 或 `src/commands/**` → `src/worker/**` TypeScript import。Console app-data 存储（operations、context exports、artifact revisions、app-data path helpers）位于 `src/infrastructure/console/**`，由 Console（worker 层）与 CLI 命令共同向下依赖；Console 专属的 route/action 编排仍留在 `src/worker/console/**`。
 
-`scripts/check-architecture-boundaries.sh` 的 transitional allowlist 保持为空。任何新增的 `workflows/executors/worker` forbidden import 必须导致检查 **exit 1**；如果未来确有临时例外，必须先写入 active exec plan，说明移除时间和验证门禁。
+`scripts/check-architecture-boundaries.sh` 的 transitional allowlist 保持为空。任何新增的 `workflows/executors/worker/commands` forbidden import 必须导致检查 **exit 1**；如果未来确有临时例外，必须先写入 active exec plan，说明移除时间和验证门禁。
 
 ## Governance 钩子
 

package/docs/architecture/worker-and-feature.md

@@ -61,7 +61,7 @@ controller identity 与 DAG skill snapshot 是两个不同冻结层（前者跨
 
 - schema/validate：`src/worker/task-spec/{schema,validate}.ts`。
 - 校验验收条件、依赖、验证命令；`agent-worker task validate-feature` 等用之。
-- **0.16.0+**：可选 `execution.workflow` 映射到 loop-agent `taskKind`（如 agent-dag / frontend-implementation / backend-test / frontend-test）；typed Task Outcome 与 artifact-aware Ready 门禁见 completed `2026-07-19-taskspec-workflow-routing.md`。
+- **0.16.0+**：可选 `execution.workflow` 映射到 loop-agent `taskKind`（agent-dag / frontend-implementation / backend-test-analysis / backend-test / frontend-test）；`backend-test-analysis` 只读生成严格 analysis artifact，不执行测试；typed Task Outcome 与 artifact-aware Ready 门禁见 completed `2026-07-19-taskspec-workflow-routing.md`。
 - 文档映射镜像：`docs/architecture/taskspec-to-loop-agent-mapping.md`（runtime 真源仍在 `src/worker/` 与 materialize 路径）。
 
 ### Task Pool

package/docs/operations/local-development-environment.md

@@ -2,6 +2,27 @@
 
 本文记录仅与特定开发环境有关、但可能反复影响验证结果的问题。它不是通用工程规则；标准验证命令仍以 [`verification-matrix.md`](../governance/verification-matrix.md) 为准。
 
+## Operator Console 前端快速迭代
+
+对 `src/worker/console/static-src/` 内的对话样式和前端交互做高频调整时，使用固定 8790 的开发入口：
+
+```bash
+npm run console:dev
+```
+
+它从当前源码启动真实 Console 后端，并在内部 `8791` 常驻 Vite dev server。浏览器始终访问 `http://127.0.0.1:8790/`：API、HttpOnly Cookie、确认令牌和 Origin 校验仍由真实 Console 处理，前端 HTML/模块请求才由 8790 转发给 Vite。CSS 保存后原地热替换，TSX 保存后自动整页刷新；不生成 `static-dev` bundle，也不重复运行生产 build。
+
+常用参数：
+
+```bash
+npm run console:dev -- --no-open
+npm run console:dev -- --port 8792 --reload-port 8793 --no-open
+```
+
+默认端口是 Console `8790`、内部 Vite/HMR `8791`；两者都只允许 loopback。端口已占用时命令会失败并报告端口，不会停止或接管已有进程。前端类型检查在后台持续输出诊断，但不阻塞 HMR；后端源码变化时只重启 Console 子进程，Vite 保持常驻。
+
+该命令只优化编辑反馈，不构成验收。独立交互修复完成后仍需运行定向 Vitest；交付前按验证矩阵运行 typecheck、正式 `npm run console:build` / `npm run build`。正式构建继续写入 `dist/worker/console/static/`，不会包含 `/@vite/client`、8791 或开发代理代码。
+
 ## Git hooks（本仓库）
 
 每个 clone 安装一次：

package/docs/templates/agent-dag.schema.json

@@ -483,6 +483,28 @@
         "sha256": { "type": "string", "minLength": 1 }
       }
     },
+    "producedArtifact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["artifactId", "kind", "path", "mediaType", "revisionPolicy"],
+      "properties": {
+        "artifactId": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" },
+        "kind": { "enum": ["structured", "assistant", "stdout"] },
+        "path": { "type": "string", "pattern": "^(?!/)(?![A-Za-z]:)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\).+$" },
+        "mediaType": { "type": "string", "minLength": 1 },
+        "schemaId": { "type": "string", "minLength": 1 },
+        "revisionPolicy": { "enum": ["immutable", "replace-file"] }
+      }
+    },
+    "consumedArtifact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["artifactId"],
+      "properties": {
+        "artifactId": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" },
+        "required": { "type": "boolean", "default": true }
+      }
+    },
     "task": {
       "type": "object",
       "additionalProperties": false,
@@ -538,6 +560,24 @@
           "type": "array",
           "items": { "type": "string", "minLength": 1 }
         },
+        "readSet": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "description": "Strict repository-relative read allowlist for bounded Pi nodes."
+        },
+        "contextBudget": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Online per-attempt Pi SDK conversation guard. At least one threshold is required; exhaustion aborts the active session with context-budget-exhausted partial evidence.",
+          "properties": {
+            "maxTurns": { "type": "integer", "minimum": 1 },
+            "maxTokens": { "type": "integer", "minimum": 1 }
+          },
+          "anyOf": [
+            { "required": ["maxTurns"] },
+            { "required": ["maxTokens"] }
+          ]
+        },
         "piStep": {
           "type": "string",
           "minLength": 1
@@ -552,6 +592,16 @@
           "type": "string",
           "minLength": 1
         },
+        "producesArtifacts": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/producedArtifact" },
+          "description": "Frozen producer declarations. Artifact lineage and impact analysis must use these declarations, never prompt/outputContract/path heuristics."
+        },
+        "consumesArtifacts": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/consumedArtifact" },
+          "description": "Frozen logical artifact inputs consumed by this node."
+        },
         "outputMode": {
           "enum": ["default", "structured-required"],
           "description": "Optional output semantics for Pi nodes. structured-required means oversized assistant output must not be accepted as a truncated success; eligible read-only nodes may compact-retry and downstream gates should rely on canonical structured artifacts."