@tea-agent/loop-agent 0.35.2 → 0.35.4-beta.0

package/dist/workflows/dag/types.js

@@ -654,8 +654,15 @@ export const dagConvergenceSpecSchema = z
     chainNodeIds: z.array(z.string()).optional(),
 })
     .optional();
-export const dagTaskSchema = z.object({
-    id: z.string().regex(/^[a-z][a-z0-9-]*$/, "task id must be kebab-case"),
+/**
+ * Schema ids that may opt a node into producing-node structured contract
+ * self-validation. Validators are registered in the contract output registry
+ * (src/workflows/dag/contract-output-registry.ts).
+ */
+export const structuredContractOutputSchemaIds = [
+    "frontend-implementation-contract-v1",
+];
+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.
@@ -704,6 +711,20 @@ export const dagTaskSchema = z.object({
      * on safe read-only Pi nodes before the node becomes ERROR.
      */
     outputProtocol: dagOutputProtocolSchema.optional(),
+    /**
+     * Node-level structured contract self-check: after the Pi output is
+     * produced, validate it against the named contract schema at the node so
+     * schema/typo/null violations become invalid-output (retryable on the node)
+     * instead of failing later at a downstream deterministic gate. Validators
+     * are resolved via the contract output registry keyed by schemaId.
+     */
+    structuredContractOutput: z
+        .object({
+        schemaId: z.enum(structuredContractOutputSchemaIds),
+        retryOnInvalid: z.boolean().default(true),
+    })
+        .strict()
+        .optional(),
     /**
      * Fail-closed outcome/diff consistency contract for bounded Pi writers.
      * The writer must begin with IMPLEMENTATION_OUTCOME: changed,
@@ -874,6 +895,113 @@ export const dagSpecSchema = z
         });
     }
 });
+export const FRONTEND_RECOVERY_STATE_SCHEMA_VERSION = 1;
+export const FRONTEND_RECOVERY_RESULT_SCHEMA_VERSION = 1;
+/**
+ * Frontend candidate-continuation recovery phase (decision B, phase-3 subset).
+ * Phase 3a parents converge first, so `rollback-pending` is not produced and
+ * was removed by AC-1; the phase starts at `child-staging` and ends at
+ * `settled`.
+ */
+export const frontendRecoveryPhaseSchema = z.enum([
+    "child-staging",
+    "child-activating",
+    "child-running",
+    "settled",
+]);
+/**
+ * Single-writer recovery intent/lineage stored on `DagRunState`. The parent run
+ * owns the authoritative copy and advances it via revision-guarded CAS writes;
+ * the child carries a frozen lineage snapshot so the activation gate can prove
+ * it is the reserved child of a child-running parent.
+ *
+ * Invariants: `attemptIndex ∈ {0,1}`; `continuationCount ∈ {0,1}`; a child's
+ * `recoveryRootRunId` always equals the root runId; `revision` is the CAS
+ * pre-comparison counter. `revision` monotonicity is enforced at runtime by the
+ * runner's `(existing?.revision ?? 0) + 1` CAS write (the schema only bounds it
+ * non-negative). `childRunId` may be absent through `child-activating` and must
+ * be non-empty from `child-running` onward.
+ */
+export const frontendRecoveryStateSchema = z
+    .object({
+    schemaVersion: z.literal(FRONTEND_RECOVERY_STATE_SCHEMA_VERSION),
+    phase: frontendRecoveryPhaseSchema,
+    requestId: z.string().min(1),
+    recoveryRootRunId: z.string().min(1),
+    parentRunId: z.string().min(1),
+    childRunId: z.string().min(1).optional(),
+    attemptId: z.string().min(1),
+    attemptIndex: z.number().int().min(0).max(1),
+    continuationCount: z.number().int().min(0).max(1),
+    /** Node id of the reset-closure root: frontend-plan-pi /
+     *  frontend-plan-revision-pi / frontend-prewrite-gate-shell /
+     *  frontend-implement-pi (writer partial write). */
+    failureSource: z.string().min(1).optional(),
+    revision: z.number().int().nonnegative(),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    const requiresChild = value.phase === "child-running" || value.phase === "settled";
+    if (requiresChild && !value.childRunId) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `phase ${value.phase} requires a non-empty childRunId`,
+            path: ["childRunId"],
+        });
+    }
+});
+export const frontendRecoveryOutcomeSchema = z.enum([
+    "none",
+    "recovered",
+    "candidate-contract-invalid",
+    "prewrite-blocked",
+    "repair-exhausted",
+    "auto-recovery-blocked",
+]);
+export const frontendRecoveryOriginSchema = z
+    .object({
+    kind: z.enum(["frontend-prewrite-gate", "frontend-writer"]),
+    parentRunId: z.string().min(1),
+    childRunId: z.string().min(1).optional(),
+    requestId: z.string().min(1),
+    failedNodeId: z.string(),
+})
+    .strict();
+export const frontendRecoveryFailureClassSchema = z
+    .object({
+    code: z.enum([
+        "candidate-contract-invalid",
+        "prewrite-blocked",
+        "staging-failed",
+        "writer-transient-partial-write",
+    ]),
+    classification: z.string(),
+    reason: z.string(),
+})
+    .strict();
+export const frontendRecoveryEvidenceRefSchema = z
+    .object({
+    runId: z.string().min(1),
+    relativePath: z.string().min(1),
+    sha256: z.string().min(1),
+})
+    .strict();
+/**
+ * Terminal frontend recovery result. `failureClass` is absent for `none`,
+ * `recovered` and `auto-recovery-blocked` outcomes. The schema intentionally
+ * stays permissive (failureClass optional, evidenceRefs may be empty) so it
+ * accepts the runner's actual phase-3a products, which do not always carry a
+ * failure class or evidence reference.
+ */
+export const frontendRecoveryResultSchema = z
+    .object({
+    schemaVersion: z.literal(FRONTEND_RECOVERY_RESULT_SCHEMA_VERSION),
+    outcome: frontendRecoveryOutcomeSchema,
+    origin: frontendRecoveryOriginSchema,
+    failureClass: frontendRecoveryFailureClassSchema.optional(),
+    evidenceRefs: z.array(frontendRecoveryEvidenceRefSchema),
+})
+    .strict();
 export const DEFAULT_DAG_EXECUTOR_MODELS = {
     pi: {
         LOW: "gpt-5.3-codex-spark",

package/docs/templates/frontend-task-constraints.md

@@ -18,13 +18,19 @@ TODO
 
 ## Mock 约束（数据型任务）
 
-- Mock/API/schema 规范路径：TODO
-- 既有 Mock service root、handler/fixture/bootstrap：TODO
-- 既有 browser/e2e interception 或 request adapter/DI seam：TODO
-- 启动、健康检查和专项验证命令：TODO
-- production 禁用边界：TODO
-- 真实请求默认路径与 Mock 显式启用方式：TODO
-- `task.json.frontendMock.policy`：`auto | required | disabled`
+本段决定生成期 `allowedMockStrategies` 与冻结的 Mock 验证命令。只有当生成期**能证明任务确实包含 Mock 且有确定性验证命令**时，DAG 才会放行 `native` / `browser-intercept` / `request-adapter`；否则自动收敛为 `not-needed`，design review 若按项目规范改选 `native`，会在 prewrite 被 `mock-strategy-outside-allowed` 拦截、`implement` 被跳过。
+
+- **何时必须填**：项目规范（`openspec/project-specs/**`、`ai_workspace/**`、mock 规则或类似 DEC-* 决策）要求/建议 Mock；或需求涉及远端接口且后端未就绪。规范要求 Mock 时，优先 `task.json.frontendMock.policy: "required"`。
+- **命令要探索、不要硬编码**：到项目 `package.json` scripts 里找实际存在的 Mock 相关脚本（如 `mock`、`mock:*`、`dev:mock`，或名字含 mock 的脚本），结合既有 service root 的 handler/fixture/bootstrap 启动方式，确定一条**真实存在、确定、可自终止**（启动→断言→退出 0）的验证命令。常驻 dev server 必须包装成自终止脚本（start→assert→stop），否则 verify shell 会超时 fail-closed。
+- **写入 task.json**：把探索到的命令原样写进 `frontendMock.verifyCommands`（`label` 唯一、`command` 与项目脚本一致）。`label` 会进入冻结命令集，implementation contract 的 `verificationTarget.commandLabel` 必须逐字引用它。
+- **命令来源白名单**：只允许项目 `package.json` 已有脚本、Mock capability seed、或本段声明的 `verifyCommands`；plan/design 阶段不能发明 shell 命令。
+- **Mock/API/schema 规范路径**：TODO
+- **既有 Mock service root、handler/fixture/bootstrap**：TODO
+- **既有 browser/e2e interception 或 request adapter/DI seam**：TODO
+- **production 禁用边界**：TODO
+- **真实请求默认路径与 Mock 显式启用方式**：TODO
+- **`task.json.frontendMock.policy`**：`auto | required | disabled`（规范强制 Mock 用 `required`）
+- **被拦截时怎么修**：`mock-strategy-outside-allowed` / `no authorized Mock verification commands` 是**生成期契约问题，不是 plan 问题**——补 `frontendMock.verifyCommands`（或 `policy: "required"` + 命令）后**重新生成 DAG** 再跑，plan-revision 无法修复它。
 
 ## allowedPaths
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.35.2",
+  "version": "0.35.4-beta.0",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",
@@ -45,7 +45,7 @@
     "pi-prompt": "node --import tsx/esm src/cli.ts pi-prompt",
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "brand:sync": "node scripts/sync-brand-assets.mjs",
-    "build": "npm run brand:sync && npm run clean && tsc -p tsconfig.build.json && node -e \"const fs=require('node:fs');const p='dist/worker/observe/static';fs.mkdirSync(p,{recursive:true});fs.cpSync('src/worker/observe/static',p,{recursive:true});\" && npm run console:build",
+    "build": "npm run brand:sync && npm run clean && tsc -p tsconfig.build.json && node -e \"const fs=require('node:fs');const p='dist/worker/observe/static';fs.mkdirSync(p,{recursive:true});fs.cpSync('src/worker/observe/static',p,{recursive:true});\" && npm run console:build && node scripts/write-build-stamp.mjs",
     "console:typecheck": "tsc -p src/worker/console/tsconfig.json",
     "console:build": "npm run console:typecheck && vite build --config src/worker/console/vite.config.ts",
     "prepack": "npm run build",
@@ -88,5 +88,6 @@
     "typescript": "^5.9.3",
     "vite": "^7.0.0",
     "vitest": "^3.2.4"
-  }
+  },
+  "packageManager": "pnpm@10.33.0+sha512.10568bb4a6afb58c9eb3630da90cc9516417abebd3fabbe6739f0ae795728da1491e9db5a544c76ad8eb7570f5c4bb3d6c637b2cb41bfdcdb47fa823c8649319"
 }