@tea-agent/loop-agent 0.15.0 → 0.16.1-beta.0

package/dist/worker/task-spec/workflow-routing.js

@@ -0,0 +1,149 @@
+import { z } from "zod";
+/**
+ * Explicit runtime workflow that routes a TaskSpec to a controller DAG.
+ *
+ * The workflow is orthogonal to the business {@link TaskSpec.type} and the
+ * governance `loop_agent` profile. It is the only field the materializer uses
+ * to derive {@link TaskKind} (written to `task.json.taskKind`) which the
+ * published controller turns into a concrete DAG.
+ */
+export const workflowSchema = z.enum([
+    "agent-dag",
+    "frontend-implementation",
+    "backend-test",
+    "frontend-test",
+]);
+/**
+ * Deterministic workflow → taskKind mapping.
+ *
+ * - `agent-dag` → `standard` (the default agent DAG).
+ * - The three remaining workflows map 1:1 to their same-named taskKind.
+ */
+export const WORKFLOW_TASK_KIND = {
+    "agent-dag": "standard",
+    "frontend-implementation": "frontend-implementation",
+    "backend-test": "backend-test",
+    "frontend-test": "frontend-test",
+};
+/**
+ * Legacy QA business types that have no deterministic backend/frontend split.
+ * Without an explicit {@link Workflow} they MUST surface migration guidance
+ * rather than silently guessing `backend-test` or `frontend-test`.
+ */
+export const LEGACY_QA_TYPES = new Set([
+    "qa-casegen",
+    "qa-testcode",
+    "qa-execute",
+]);
+/**
+ * Legacy business types that deterministically route to `frontend-implementation`.
+ */
+const FRONTEND_FEATURE_TYPES = new Set(["frontend-feature"]);
+/**
+ * Legacy business types that deterministically route to the `agent-dag`/`standard`
+ * DAG. Anything that is not a QA type and not a frontend-feature lands here.
+ */
+export function legacyDefaultWorkflow(type) {
+    return FRONTEND_FEATURE_TYPES.has(type) ? "frontend-implementation" : "agent-dag";
+}
+/** Migration guidance surfaced whenever a legacy QA type lacks an explicit workflow. */
+export const LEGACY_QA_MIGRATION_GUIDANCE = "Legacy qa-casegen/qa-testcode/qa-execute tasks no longer auto-select a backend or frontend workflow. " +
+    "Add `execution.workflow` with one of: agent-dag, frontend-implementation, backend-test, frontend-test. " +
+    "Use backend-test for backend-only test generation/execution, frontend-test for browser/UI tests, " +
+    "or agent-dag when the QA task is a generic agent study.";
+export class WorkflowRoutingError extends Error {
+    code;
+    migrationGuidance;
+    constructor(code, message, migrationGuidance) {
+        super(message);
+        this.name = "WorkflowRoutingError";
+        this.code = code;
+        this.migrationGuidance = migrationGuidance;
+    }
+}
+/**
+ * Resolve the runtime {@link Workflow} and {@link TaskKind} for a TaskSpec.
+ *
+ * Resolution order:
+ * 1. Explicit `taskSpec.execution?.workflow` (source: `explicit`).
+ * 2. Legacy `frontend-feature` → `frontend-implementation`.
+ * 3. Legacy `backend-feature` (and any non-QA legacy type) → `agent-dag`.
+ * 4. Legacy QA types ({@link LEGACY_QA_TYPES}) without an explicit workflow →
+ *    preserve their historic default `standard` execution as `agent-dag` and
+ *    emit migration guidance during validation. We never guess backend vs frontend.
+ *
+ * Compatibility between an explicit workflow and the business `type` must be
+ * validated first via {@link validateWorkflowCompatibility}; this function
+ * assumes the combination is already known-valid.
+ */
+export function resolveWorkflow(taskSpec) {
+    const explicit = taskSpec.execution?.workflow;
+    if (explicit) {
+        return {
+            workflow: explicit,
+            taskKind: WORKFLOW_TASK_KIND[explicit],
+            source: "explicit",
+        };
+    }
+    if (LEGACY_QA_TYPES.has(taskSpec.type)) {
+        return {
+            workflow: "agent-dag",
+            taskKind: WORKFLOW_TASK_KIND["agent-dag"],
+            source: "legacy-warning",
+        };
+    }
+    const workflow = legacyDefaultWorkflow(taskSpec.type);
+    return {
+        workflow,
+        taskKind: WORKFLOW_TASK_KIND[workflow],
+        source: "legacy-deterministic",
+    };
+}
+/**
+ * Deterministic compatibility validation between an explicit workflow and the
+ * business {@link TaskSpec.type}. Legacy QA types without an explicit workflow
+ * surface a single migration-guidance issue instead of a routing decision.
+ *
+ * Incompatible combinations (e.g. `frontend-feature` + `backend-test`,
+ * `backend-feature` + `frontend-implementation`, or a `qa-*` type paired with
+ * an implementation/test workflow from the wrong surface) are reported so the
+ * validator can fail fast rather than silently materializing a wrong DAG.
+ */
+export function validateWorkflowCompatibility(taskSpec) {
+    const explicit = taskSpec.execution?.workflow;
+    if (!explicit) {
+        if (LEGACY_QA_TYPES.has(taskSpec.type)) {
+            return { issues: [], migrationGuidance: LEGACY_QA_MIGRATION_GUIDANCE };
+        }
+        // Legacy backend/frontend feature and other non-QA types route deterministically.
+        return { issues: [] };
+    }
+    const issues = [];
+    const type = taskSpec.type;
+    if (type === "backend-feature" && explicit !== "agent-dag" && explicit !== "backend-test") {
+        issues.push({
+            code: "workflow-type-incompatible",
+            message: `backend-feature is incompatible with workflow "${explicit}" (expected agent-dag or backend-test)`,
+            path: "execution.workflow",
+        });
+    }
+    if (type === "frontend-feature" && explicit !== "frontend-implementation" && explicit !== "frontend-test") {
+        issues.push({
+            code: "workflow-type-incompatible",
+            message: `frontend-feature is incompatible with workflow "${explicit}" (expected frontend-implementation or frontend-test)`,
+            path: "execution.workflow",
+        });
+    }
+    if (LEGACY_QA_TYPES.has(type)) {
+        // qa-* types are allowed to opt into a concrete test/implementation workflow
+        // but never into a feature implementation surface that does not match QA intent.
+        if (explicit === "frontend-implementation") {
+            issues.push({
+                code: "workflow-type-incompatible",
+                message: `${type} is a QA type and cannot route to frontend-implementation; use frontend-test, backend-test, or agent-dag`,
+                path: "execution.workflow",
+            });
+        }
+    }
+    return { issues };
+}

package/dist/workflows/dag/init-hybrid.js

@@ -1338,10 +1338,11 @@ function buildFrontendMockAssessNode(sources, sourceContext, mockContextBlock, f
         allowedPaths: readOnlyPaths,
         forbiddenPaths,
         skills: FRONTEND_IMPLEMENTATION_SKILLS,
-        outputContract: "Plain Markdown whose first non-empty line is MOCK_STRATEGY: native|browser-intercept|request-adapter|not-needed|blocked, followed by Mock Decision, API Contract Evidence, Specification Evidence, Service Evidence, Backend Readiness, Selection Evidence, Endpoint / Fixture Matrix, Activation, Target Files, Production Safety, Verification Plan, Real Integration Gap, and Blocking Issues. No file writes.",
+        firstProtocolLine: "MOCK_STRATEGY:",
+        outputContract: "Plain Markdown whose first line is MOCK_STRATEGY: native|browser-intercept|request-adapter|not-needed|blocked, followed by Mock Decision, API Contract Evidence, Specification Evidence, Service Evidence, Backend Readiness, Selection Evidence, Endpoint / Fixture Matrix, Activation, Target Files, Production Safety, Verification Plan, Real Integration Gap, and Blocking Issues. No file writes.",
         subtask_prompt: [
             "Perform read-only Mock assessment and select one safe frontend data strategy.",
-            "The first non-empty line must be exactly one of: MOCK_STRATEGY: native, MOCK_STRATEGY: browser-intercept, MOCK_STRATEGY: request-adapter, MOCK_STRATEGY: not-needed, or MOCK_STRATEGY: blocked.",
+            "The first line must be exactly one of: MOCK_STRATEGY: native, MOCK_STRATEGY: browser-intercept, MOCK_STRATEGY: request-adapter, MOCK_STRATEGY: not-needed, or MOCK_STRATEGY: blocked. Do not emit blank lines, headings, or explanatory preamble before it.",
             "Prefer an existing native Mock facility. Use browser-intercept only with an existing browser/e2e harness. When no Mock exists but the API layer is writable, use request-adapter by adding a minimal reversible adapter/DI seam within the approved writeSet; the real adapter must remain the production default.",
             autoMaySkipMissingMock
                 ? "Auto mode may skip Mock when no project Mock capability is confirmed. Select not-needed with positive evidence from contract/scout that no project Mock capability is confirmed, continue without adding Mock files or dependencies, run the fixed verification entrypoints, and record any unproved real API behavior in Real Integration Gap. Do not block solely because no project Mock capability, browser interception harness, or request adapter exists."

package/dist/workflows/dag/types.js

@@ -267,6 +267,7 @@ export const dagTaskSchema = z.object({
     shell: dagShellConfigSchema.optional(),
     static: dagStaticConfigSchema.optional(),
     outputContract: z.string().optional(),
+    firstProtocolLine: z.string().min(1).optional(),
     allowedPaths: z.array(z.string()).optional().default([]),
     forbiddenPaths: z.array(z.string()).optional().default([]),
     decisionGate: dagDecisionGateSchema.optional(),

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

@@ -366,6 +366,11 @@
           "type": "string",
           "minLength": 1
         },
+        "firstProtocolLine": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Optional protocol prefix whose first matching Pi assistant-output line is promoted to the canonical first line. Missing matches are not synthesized."
+        },
         "allowedPaths": {
           "type": "array",
           "items": { "type": "string", "minLength": 1 },

package/harness.json

@@ -59,7 +59,7 @@
     "pi": {
       "description": "Pi planning, review, diagnosis, and bounded writing when DAG toolProfile=write",
       "LOW": "gpt-5.3-codex-spark",
-      "MED": "glm-5.2",
+      "MED": "grok-4.5",
       "HIGH": "gpt-5.6-sol"
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.15.0",
+  "version": "0.16.1-beta.0",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",

package/skills/frontend-implementation/references/node-contracts.md

@@ -6,9 +6,9 @@ Pre-write nodes are read-only. Preserve IDs, labels, commands, language, require
 
 - **`frontend-contract-pi`**: `Scope`, `Non-goals`, `Acceptance Criteria`, `UI States`, `Target Runtime Environment`, `Risks`, `Verification Expectations`. No guessed requirements.
 - **`frontend-scout-pi`**: routes, components, tokens, data/API/Mock, scripts, tests, assets. Fact vs inference vs gap. Knowledge base first; else search+read `<repoRoot>/openSpec/**` before repo fallback. Output stack, routes, components, styling, conventions, state/data, test entry points, reuse, risks.
-- **`frontend-mock-assess-pi` + gate**: first non-empty line
+- **`frontend-mock-assess-pi` + gate**: declares `firstProtocolLine: "MOCK_STRATEGY:"`; canonical output first line
   `MOCK_STRATEGY: native|browser-intercept|request-adapter|not-needed|blocked`
-  Prefer native Mock; browser intercept only with existing e2e; request-adapter only for reversible local preview. Default `auto` may select `not-needed` when contract/scout evidence confirms no project Mock capability, without adding Mock files/deps, while keeping real requests default and recording the Real Integration Gap. Other `not-needed` cases need positive no-remote/stable-backend evidence; invalid when `frontendMock.policy=required`. `blocked` for missing/conflicting contracts, unsafe paths/deps, unread specs, production-default-on, unverifiable entrypoints. Output Mock Decision, API/spec/service evidence, backend readiness, selection evidence, endpoint/fixture matrix, activation, targets, production safety, verification plan, real-integration gap, blocking issues. Never invent fields, store secrets, comment real requests, import test mocks into production, or treat Mock as real integration. Gate uses `first-non-empty` only; never authorizes writes. Unsafe required contracts → no writer.
+  Pi output mapping promotes the first matching protocol line ahead of any preamble without inventing or replacing its value; missing, malformed, or blocked strategies still fail closed. Prefer native Mock; browser intercept only with existing e2e; request-adapter only for reversible local preview. Default `auto` may select `not-needed` when contract/scout evidence confirms no project Mock capability, without adding Mock files/deps, while keeping real requests default and recording the Real Integration Gap. Other `not-needed` cases need positive no-remote/stable-backend evidence; invalid when `frontendMock.policy=required`. `blocked` for missing/conflicting contracts, unsafe paths/deps, unread specs, production-default-on, unverifiable entrypoints. Output Mock Decision, API/spec/service evidence, backend readiness, selection evidence, endpoint/fixture matrix, activation, targets, production safety, verification plan, real-integration gap, blocking issues. Never invent fields, store secrets, comment real requests, import test mocks into production, or treat Mock as real integration. Gate uses `first-non-empty` only; never authorizes writes. Unsafe required contracts → no writer.
 - **`frontend-plan-pi` + design loop**: AC → steps, in-bound files, UI states, reuse, deps, activation/rollback, frozen verify entrypoints, real-integration gap. First gate: `VERDICT: pass|request-revision`. Pass may emit `PASS_NO_REVISION_NEEDED`; else full corrected plan without invented evidence. Final review rechecks plan/findings/revision/assessment/Mock safety. Only final `VERDICT: pass` authorizes writes; failure → replan/rerun (not dev-fix).
 - **`frontend-implement-pi`**: sole exclusive writer. Stay in `writeSet`; real requests default-on; Mock reversible, dev/test-only, production-off. Atomic handler/intercept/adapter with consumer+tests. Stop on forbidden paths or guesses. Output changed files, behavior, UI states, styling notes, verification attempted, residual risks. Optional mock-verify when frozen; static+behavior always; behavior must prove page consumption. Skipped-Mock `not-needed` keeps real integration pending unless the real backend path has fresh evidence.
 

package/skills/loop-agent/references/hybrid-dag.md

@@ -117,7 +117,7 @@ contract-pi → scout-src ∥ scout-tests → plan-pi → write-set-audit-pi
 | `authority-surface-audit-pi` + `authority-surface-gate-shell` | 可选 permission/state/tool-exposure audit；仅 authority signal 或显式 `authority-surface-audit` marker 时插入；gate 仅接受 `VERDICT: pass` |
 | `review-pi` + `review-gate-shell` | Critical/Important → `request-revision`；node JSON 上 `shell.verdictGate` block，除非 extracted verdict 行为 `VERDICT: pass` |
 
-**Verdict gate contract（`shell.verdictGate`）**：声明 `fromNodeId`、`accept[]`、可选 `label`、可选 `lineMode`。runner 展开为一条 shell command，从 injected current run directory 读 `$HARNESS_DAG_RUN_DIR/<fromNodeId>.json`，对 extracted `assistantText ?? stdout` verdict line 与 `accept[]` exact-match。默认 `lineMode` 为 `first-non-empty` 以兼容；supervised gate 用 `first-verdict-line` 选 Pi 在 preamble 或常见整行 Markdown emphasis（如 `**VERDICT: pass**`）后第一条 normalized `VERDICT:` line。勿用 `result.summary.md`、grep VERDICT、latest-active-run discovery 或 multi-command stateful gate。`--strict-governance` 对 anti-pattern fail。supervisor 仍为 `executor: pi` 上的 `role: supervisor`。
+**Verdict gate contract（`shell.verdictGate`）**：声明 `fromNodeId`、`accept[]`、可选 `label`、可选 `lineMode`。runner 展开为一条 shell command，从 injected current run directory 读 `$HARNESS_DAG_RUN_DIR/<fromNodeId>.json`，对 extracted `assistantText ?? stdout` verdict line 与 `accept[]` exact-match。默认 `lineMode` 为 `first-non-empty` 以兼容；需要固定非 `VERDICT:` 协议首行的 Pi 节点可显式声明 `firstProtocolLine`，executor 会把第一条匹配前缀的行提升为 canonical 首行，不匹配时不伪造。`frontend-mock-assess-pi` 用它固定 `MOCK_STRATEGY:`，gate 仍保持 `first-non-empty` exact-match。supervised gate 用 `first-verdict-line` 选 Pi 在 preamble 或常见整行 Markdown emphasis（如 `**VERDICT: pass**`）后第一条 normalized `VERDICT:` line。勿用 `result.summary.md`、grep VERDICT、latest-active-run discovery 或 multi-command stateful gate。`--strict-governance` 对 anti-pattern fail。supervisor 仍为 `executor: pi` 上的 `role: supervisor`。
 
 **Repair artifact gate contract（`shell.repairArtifactGate`）**：声明 `fromNodeId`（supervisor artifact 节点）与 `repairNodeId`（承接修订的 Pi 修复节点）。runner **不再**按节点名（历史 `repair-cursor` / `repair-pi`）猜测 repair 节点：显式 `repairNodeId` 必须存在、直接 `depends_on` gate、且是受治理 Pi writer（`executor: pi`、`toolProfile: write`、`writePolicy: exclusive`、`allowedPaths`+`writeSet` 非空且 `writeSet` 不与 `forbiddenPaths` 冲突）。新生成的 supervised DAG 总是写入 `repairNodeId`；旧 DAG 缺失时只在能唯一、安全地推导出下游 Pi writer 时兼容，零个或多个候选、或候选不满足契约都在执行前 fail closed。validation 覆盖存在性、直接下游、writer 属性与路径边界。