@tea-agent/loop-agent 0.44.0-next.1 → 0.44.0-next.11

package/dist/executors/dag-pi/plan/schema.js

@@ -0,0 +1,129 @@
+/**
+ * 前端 plan ledger 的 13 个 typebox schema。
+ *
+ * `Type` 由调用方注入，而不是模块级 `import { Type } from "typebox"`：executor 工厂内以
+ * `await import("typebox")` 延迟加载 typebox，改成静态导入会改变模块加载时机。
+ */
+export function buildPlanSchemas(Type) {
+    const stringArray = Type.Array(Type.String({}));
+    const optionalString = Type.Optional(Type.String({}));
+    const optionalStringArray = Type.Optional(stringArray);
+    const requirementSchema = Type.Object({
+        id: Type.String({}),
+        expectedOutcome: Type.Optional(Type.String({
+            description: "Optional. When omitted, the runtime derives it from the contract requirement. Prefer omitting it to keep this tool call small.",
+        })),
+        implementationTargets: stringArray,
+        verificationTargetIds: Type.Optional(stringArray),
+        evidenceGap: Type.Optional(Type.Object({
+            requirementId: optionalString,
+            description: Type.String({}),
+            blocking: Type.Boolean(),
+        }, { additionalProperties: false })),
+    }, { additionalProperties: false });
+    const uiStateSchema = Type.Object({
+        name: Type.String({}),
+        applicable: Type.Boolean(),
+        expectedBehavior: optionalString,
+        implementationTargets: optionalStringArray,
+        verificationTargetIds: optionalStringArray,
+        notApplicableReason: optionalString,
+        reason: Type.Optional(Type.String({})),
+    }, { additionalProperties: false });
+    const interactionSchema = Type.Object({
+        name: optionalString,
+        id: Type.Optional(Type.String({})),
+        trigger: Type.String({}),
+        expectedBehavior: Type.String({}),
+        implementationTargets: stringArray,
+        verificationTargetIds: stringArray,
+    }, { additionalProperties: false });
+    const mockEndpointSchema = Type.Object({
+        method: Type.Enum({ GET: "GET", POST: "POST", PUT: "PUT", PATCH: "PATCH", DELETE: "DELETE", HEAD: "HEAD", OPTIONS: "OPTIONS" }),
+        path: Type.String({}),
+        fixture: optionalString,
+        consumer: optionalString,
+    }, { additionalProperties: false });
+    const mockApiSchema = Type.Object({
+        strategy: Type.Union([
+            Type.Literal("native"),
+            Type.Literal("browser-intercept"),
+            Type.Literal("request-adapter"),
+            Type.Literal("not-needed"),
+        ], {
+            description: "native | browser-intercept | request-adapter | not-needed",
+        }),
+        activation: Type.String({}),
+        endpoints: Type.Array(mockEndpointSchema),
+    }, { additionalProperties: false });
+    const designEvidenceSchema = Type.Object({
+        source: Type.String({}),
+        paths: stringArray,
+        conflicts: stringArray,
+    }, { additionalProperties: false });
+    // Verification mode is runtime-owned (contract v2): the plan submits a
+    // commandId referencing the frozen command directory, never a type. A
+    // soft Type.String would let the model commit values that only fail at
+    // compile time — keep the reference a required string and validate it
+    // against the directory at the tool boundary below.
+    const verificationTargetScopeSchema = Type.Union([
+        Type.Literal("unit"),
+        Type.Literal("component"),
+        Type.Literal("integration"),
+    ]);
+    const verificationTargetSchema = Type.Object({
+        id: Type.String({}),
+        commandId: Type.String({
+            description: "Frozen command directory key (e.g. verify-npm-run-build); the runtime resolves mode and label from it.",
+        }),
+        file: Type.String({}),
+        requirementIds: stringArray,
+        scope: Type.Optional(verificationTargetScopeSchema),
+        uiStates: Type.Optional(Type.Array(Type.String({}), {
+            description: "Optional only at this tool boundary. An omitted value is deterministically recorded as []. Pass an explicit array for new calls.",
+        })),
+    }, { additionalProperties: false });
+    const evidenceGapSchema = Type.Object({
+        requirementId: optionalString,
+        description: Type.String({}),
+        blocking: Type.Boolean(),
+    }, { additionalProperties: false });
+    const uiComponentChoiceSchema = Type.Object({
+        purpose: Type.String({}),
+        component: Type.String({}),
+        decision: Type.Union([
+            Type.Literal("specified"),
+            Type.Literal("reuse-existing"),
+            Type.Literal("new"),
+        ], {
+            description: "specified | reuse-existing | new",
+        }),
+        specReference: Type.Optional(Type.Object({
+            path: Type.String({}),
+            section: Type.String({}),
+            line: Type.Optional(Type.Integer({ minimum: 1 })),
+        }, { additionalProperties: false })),
+        rationale: Type.Optional(Type.String({ minLength: 1 })),
+        covers: Type.Optional(Type.Array(Type.String({}), {
+            description: "UI state and/or interaction names this single component choice covers (one choice may cover many ids).",
+        })),
+        evidencePath: Type.Optional(Type.String({
+            description: "REQUIRED for decision=reuse-existing: repo-relative path whose existing file is the reuse evidence. Greenfield paths must use decision=new.",
+        })),
+    }, { additionalProperties: false });
+    return {
+        stringArray,
+        optionalString,
+        optionalStringArray,
+        requirementSchema,
+        uiStateSchema,
+        interactionSchema,
+        mockEndpointSchema,
+        mockApiSchema,
+        designEvidenceSchema,
+        verificationTargetScopeSchema,
+        verificationTargetSchema,
+        evidenceGapSchema,
+        uiComponentChoiceSchema,
+    };
+}

package/dist/executors/dag-pi/plan/session.js

@@ -0,0 +1 @@
+export {};

package/dist/executors/dag-pi/plan/tool-helpers.js

@@ -0,0 +1,16 @@
+/** plan ledger 工具共用的纯 helper：零状态、零 I/O。 */
+export const stringList = (value) => Array.isArray(value)
+    ? value.filter((item) => typeof item === "string")
+    : [];
+export const nonEmptyString = (value) => typeof value === "string" && value.trim().length > 0
+    ? value.trim()
+    : undefined;
+export const planToolReceipt = (details) => ({
+    content: [
+        {
+            type: "text",
+            text: JSON.stringify(details),
+        },
+    ],
+    details,
+});

package/dist/executors/dag-pi/sessions/index.js

@@ -0,0 +1,6 @@
+/** DAG Pi 会话族兼容转发：既有测试从 entry 导入的符号统一经此转发，逐步迁移后移除。 */
+export { estimateFrontendPlanRequirementRecordCalls, batchFrontendPlanRequirements, FRONTEND_PLAN_COVERAGE_MAX_CONCURRENCY, FRONTEND_PLAN_BATCH_MAX_SESSIONS, mapWithConcurrency, buildFrontendPlanWorkload, collectFrontendPlanRequirementIds, loadOrCreateFrontendPlanCoverageLayout, collectFrontendVerificationCommandFiles } from "./plan-batches.js";
+export { compactFrontendPlanLedgerContext, compactFrontendPlanPromptForRequirementSlice } from "./plan-prompts.js";
+export { isPlannerThinkingExhausted, isWriterThinkingExhausted, readWriterThinkingExhaustionEvidence, WRITER_BUDGET_EXHAUSTED_CATEGORY, WRITER_TOKEN_BUDGET, WRITER_THINKING_EXHAUSTED_CATEGORY, PLANNER_THINKING_EXHAUSTED_CATEGORY } from "./writer-evidence.js";
+export { aggregateParallelPiResults, combineSequentialPiResults, runFrontendScoutParallelSessions } from "./scout-parallel.js";
+export { runFrontendContractSegmentedSessions, runFrontendPlanSegmentedSessions, runFrontendReviewSegmentedSessions, runFrontendScoutSegmentedSessions } from "./segmented-plan.js";

package/dist/executors/dag-pi/sessions/plan-batches.js

@@ -0,0 +1,280 @@
+/** DAG Pi 分段会话的批次规划：work 装配、批次上限、覆盖布局与并发映射。覆盖布局会读写 coverage-layout.json；禁止反向依赖执行器入口。 */
+import path from "node:path";
+import { readFile, stat } from "node:fs/promises";
+import { z } from "zod";
+import { FRONTEND_SCOPE_TARGET_BYTES, packFrontendInputUnits, parseFrontendInputBlock } from "../../../workflows/dag/frontend-input-projection.js";
+import { sha256OfCanonicalJson } from "../../../task/contract/hash.js";
+import { writeDagNodeJsonArtifact } from "../../../infrastructure/harness/artifact-store.js";
+import { isRecordObject } from "../guards.js";
+export const FRONTEND_PLAN_SEGMENTS = [
+    {
+        id: "coverage",
+        toolNames: new Set([
+            "record_plan_requirement",
+            "record_plan_group_coverage",
+            "record_plan_verification_target",
+            "record_plan_evidence_gap",
+            "adopt_staged_fact",
+        ]),
+        instruction: [
+            "PLAN PHASE — requirement coverage only.",
+            "Your ONLY job: for every frozen requirement, emit record_plan_requirement (requirement → implementation files) and record_plan_verification_target facts (verification target bound to requirement ids and files). Group related requirements under one non-static behavior target when one observable test behavior proves them together; do not mechanically create one target per requirement. Target ids identify contract entries, not test-title markers. Reuse affected existing test files and their names; do not add tests or rename titles just to carry generated ids. Never submit prose as a symbol. Do NOT record components, UI states, mock, dependency, or routes — a follow-up session owns those.",
+            "A coverage session is complete only when EVERY requirement assigned to this session (the full inventory, or the exact COVERAGE BATCH / shard list when present) has committed coverage facts: a record_plan_requirement entry plus verification targets, or a committed evidence gap. Keep committing in batches of up to 4 record_* calls per assistant message until then; do not write a concluding summary while any assigned requirement is still uncommitted — an early stop strands the remainder into a MISSING-FACT repair session and doubles the sessions needed.",
+            "If a requirement genuinely cannot have a verification target, record a non-empty record_plan_evidence_gap. Do not call finalize_plan; it is not available in this phase.",
+        ].join(" "),
+    },
+    {
+        id: "ux-registry",
+        toolNames: new Set(["record_state_registry", "adopt_staged_fact"]),
+        instruction: [
+            "PLAN PHASE — global UX vocabulary.",
+            "Bootstrap the global UX vocabulary from the execution-group index and authoritative declared states. This is navigation, not permission to decide unseen behavior. Detailed complete scopes may extend the registry with replace:true while preserving live names. UI states use declaredUiStates ids when present. Interaction names are stable kebab-case behavior domains; merge requirements that describe the same behavior instead of renaming it per AC slice. Empty arrays explicitly declare that no UX vocabulary applies. Do not record component choices or state-flow details in this phase.",
+            "Do not call finalize_plan; it is not available in this phase.",
+        ].join(" "),
+    },
+    {
+        id: "ux-local",
+        toolNames: new Set([
+            "record_state_registry",
+            "record_component_choice",
+            "record_state_flow",
+            "record_plan_verification_target",
+            "adopt_staged_fact",
+        ]),
+        instruction: [
+            "PLAN PHASE — global UX decisions.",
+            "Requirements and verification targets are already committed in the ledger; do not re-record unchanged facts. Review the current complete execution-group scope and the committed global UX registry together, then record each component choice, UI state and interaction exactly once. Bind each applicable state to its verificationTargetIds; the runtime derives the reverse VT.uiStates relation. If a VT requires correction, record_plan_verification_target with replace:true is available after declaring its states; preserve its requirement coverage. Multiple requirements describing one behavior share one registry name and state-flow entry; never repeat or rename it per AC. Cross-cutting data flow belongs to the global Mock/data phase. Do not record routes, Mock/API policy, dependencies, or design deviations here.",
+            "Do not call finalize_plan; it is not available in this phase.",
+        ].join(" "),
+    },
+    {
+        id: "global-route",
+        toolNames: new Set(["record_route_selection", "adopt_staged_fact"]),
+        instruction: [
+            "PLAN PHASE — global route decision.",
+            "Use the Scout target surface and record only the selected route(s). Do not record requirement-local UX, Mock/data, dependency, or deviation facts. Do not call finalize_plan.",
+        ].join(" "),
+    },
+    {
+        id: "global-mock-data",
+        toolNames: new Set(["record_data_flow", "record_mock_api", "record_mock_endpoint", "adopt_staged_fact"]),
+        instruction: [
+            "PLAN PHASE — global Mock/API and data policy.",
+            "Record the cross-cutting interaction-to-endpoint data flow and Mock/API strategy only. Keep this decision set separate from route, component, state, dependency, and deviation facts. Do not call finalize_plan.",
+        ].join(" "),
+    },
+    {
+        id: "global-dependency-deviation",
+        toolNames: new Set(["record_dependency", "record_design_deviation", "adopt_staged_fact"]),
+        instruction: [
+            "PLAN PHASE — global dependency and design-deviation policy.",
+            "Record only dependency policy and design-evidence conflicts. Do not record route, Mock/data, or requirement-local UX facts. Do not call finalize_plan.",
+        ].join(" "),
+    },
+];
+export function estimateFrontendPlanRequirementRecordCalls(fact) {
+    const record = fact && typeof fact === "object" && !Array.isArray(fact)
+        ? fact
+        : {};
+    const declaredTargetCount = Array.isArray(record.verificationTargetIds)
+        ? record.verificationTargetIds.filter((value) => typeof value === "string" && value.trim()).length
+        : Array.isArray(record.verificationTargets)
+            ? record.verificationTargets.length
+            : 0;
+    const evidence = record.evidence && typeof record.evidence === "object"
+        ? record.evidence
+        : undefined;
+    const targetCount = Math.max(declaredTargetCount, evidence?.behavior === "required" ? 2 : 1);
+    return 1 + targetCount;
+}
+export function batchFrontendPlanRequirements(input) {
+    const batches = [];
+    let current = [];
+    let currentCost = 0;
+    for (const id of input.requirementIds) {
+        const cost = Math.max(1, input.requirementCosts?.get(id) ?? 2);
+        if (current.length > 0 &&
+            (currentCost + cost > input.maxEstimatedRecordCalls ||
+                (input.maxRequirements !== undefined &&
+                    current.length >= input.maxRequirements))) {
+            batches.push(current);
+            current = [];
+            currentCost = 0;
+        }
+        current.push(id);
+        currentCost += cost;
+    }
+    if (current.length > 0)
+        batches.push(current);
+    return batches;
+}
+export const FRONTEND_PLAN_COVERAGE_MAX_RECORD_CALLS = 10;
+export const FRONTEND_PLAN_COVERAGE_MAX_CONCURRENCY = 4;
+export const FRONTEND_PLAN_BATCH_MAX_SESSIONS = 128;
+export const FRONTEND_PLAN_SMALL_MAX_REQUIREMENTS = 8;
+export const FRONTEND_PLAN_SMALL_MAX_ESTIMATED_CALLS = 24;
+export async function mapWithConcurrency(items, limit, worker, shouldReduceConcurrency) {
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    let concurrency = Math.max(1, limit);
+    const running = new Map();
+    try {
+        while (nextIndex < items.length || running.size > 0) {
+            while (nextIndex < items.length && running.size < concurrency) {
+                const index = nextIndex++;
+                running.set(index, worker(items[index], index).then(result => ({ index, result })));
+            }
+            const { index, result } = await Promise.race(running.values());
+            running.delete(index);
+            results[index] = result;
+            // Drain existing work; only pending shards use the reduced cap.
+            // Failed shards remain failed and receive no extra retry allowance.
+            if (shouldReduceConcurrency(result))
+                concurrency = Math.max(1, Math.floor(concurrency / 2));
+        }
+    }
+    catch (error) {
+        await Promise.allSettled(running.values());
+        throw error;
+    }
+    return results;
+}
+export function collectFrontendVerificationCommandFiles(basePrompt) {
+    const files = new Set();
+    const configRe = /--config\s+([\w@./-]+\.(?:js|mjs|cjs|ts|json))/g;
+    const checkRe = /node\s+--check\s+([\w@./-]+\.(?:js|mjs|cjs))/g;
+    for (const re of [configRe, checkRe]) {
+        for (const match of basePrompt.matchAll(re)) {
+            const file = match[1];
+            if (file && file.includes("/"))
+                files.add(file);
+        }
+    }
+    return [...files].sort();
+}
+export function countFrontendPlanTargetSurfaces(basePrompt) {
+    const match = /<frontend_plan_input>[\s\S]*?<\/frontend_plan_input>/.exec(basePrompt);
+    if (!match)
+        return undefined;
+    for (const line of match[0].split(/\r?\n/)) {
+        try {
+            const payload = JSON.parse(line);
+            if (Array.isArray(payload.targetSurface))
+                return payload.targetSurface.length;
+        }
+        catch {
+            // surrounding lines are prose
+        }
+    }
+    return undefined;
+}
+export function buildFrontendPlanWorkload(input) {
+    const allRequirementIds = input.requirementIds;
+    const compiledInput = parseFrontendInputBlock(input.basePrompt, "plan")?.payload;
+    const fullUnits = new Map(compiledInput?.requirements.map(r => [r.id, r]) ?? []);
+    const declaredGroups = Array.isArray(compiledInput?.executionGroups)
+        ? compiledInput.executionGroups.filter(isRecordObject) : [];
+    const workGroups = declaredGroups.map(g => ({
+        id: String(g.id), kind: String(g.kind),
+        requirementIds: Array.isArray(g.requirementIds)
+            ? g.requirementIds.filter((id) => typeof id === "string" && allRequirementIds.includes(id)) : [],
+    })).filter(g => g.requirementIds.length);
+    const groupedIds = new Set(workGroups.flatMap(g => g.requirementIds));
+    for (const id of allRequirementIds) {
+        if (!groupedIds.has(id))
+            workGroups.push({ id, kind: "unclassified", requirementIds: [id] });
+    }
+    const workCost = (ids) => 1 + ids.reduce((total, id) => total + Math.max(1, (input.requirementCosts?.get(id) ?? 2) - 1), 0);
+    const policy = input.sessionOptions.frontendExecutionPolicy;
+    const targetBytes = policy?.scopeTargetBytes ?? FRONTEND_SCOPE_TARGET_BYTES;
+    const buildWorkBatches = (ids) => {
+        const work = workGroups.flatMap((g, index) => {
+            const members = g.requirementIds.filter(id => ids.includes(id));
+            return members.length ? [{ id: `${index}:${g.id}`, requirementIds: members,
+                    requirements: members.map(id => fullUnits.get(id) ?? { id }), estimatedCalls: workCost(members) }] : [];
+        });
+        // Pack complete work units, not the repeated request scaffold. Deducting
+        // fixed context/tools can leave a one-byte budget and force one AC per
+        // session without reducing that overhead. The SDK checks the actual
+        // request against model capacity; capacity recovery splits unfinished work.
+        return packFrontendInputUnits(work, {
+            targetBytes,
+            maxUnits: policy?.maxScopeUnits ?? 4,
+            maxCost: FRONTEND_PLAN_COVERAGE_MAX_RECORD_CALLS, cost: g => g.estimatedCalls,
+        }).map(batch => batch.flatMap(g => g.requirementIds));
+    };
+    // This renderer also carries the Plan's evolving UX checkpoint on resume.
+    // Only the Contract/Scout-derived input participates in ownership binding.
+    const { committedUx: _committedUx, ...frozenInput } = compiledInput ?? {};
+    return {
+        frozenInput, workGroups, buildWorkBatches,
+        compactEligible: input.requirementCosts !== undefined &&
+            workGroups.length <= FRONTEND_PLAN_SMALL_MAX_REQUIREMENTS &&
+            workGroups.reduce((total, group) => total + workCost(group.requirementIds), 0) <= FRONTEND_PLAN_SMALL_MAX_ESTIMATED_CALLS &&
+            countFrontendPlanTargetSurfaces(input.basePrompt) === 1,
+    };
+}
+export function collectFrontendPlanRequirementIds(contractFacts) {
+    return [
+        ...new Set(contractFacts
+            .filter((record) => record.fact?.kind ===
+            "requirement")
+            .map((record) => record.fact?.id)
+            .filter((id) => typeof id === "string")),
+    ];
+}
+export const frontendPlanCoverageLayoutSchema = z.object({
+    schemaVersion: z.literal(1),
+    bindingSha256: z.string(),
+    coverageBatches: z.array(z.array(z.string().min(1)).min(1)).min(1),
+    layoutSha256: z.string(),
+}).strict();
+export async function loadOrCreateFrontendPlanCoverageLayout(input) {
+    const fileName = "coverage-layout.json";
+    const file = path.join(input.runDir, input.nodeId, fileName);
+    const bindingSha256 = sha256OfCanonicalJson(input.binding);
+    let raw;
+    try {
+        raw = await readFile(file, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    let layout;
+    if (raw !== undefined) {
+        layout = frontendPlanCoverageLayoutSchema.parse(JSON.parse(raw));
+    }
+    else {
+        // Losing the ownership receipt must never repartition acknowledged facts.
+        for (const relative of ["plan-typed-facts.jsonl", "parallel"]) {
+            const existing = await stat(path.join(input.runDir, input.nodeId, relative)).catch(error => {
+                if (error.code !== "ENOENT")
+                    throw error;
+                return undefined;
+            });
+            if (existing && (existing.isDirectory() || existing.size > 0)) {
+                throw Error("FRONTEND_PLAN_LAYOUT_MISSING: preserve the existing ledger and restart its owning phase");
+            }
+        }
+        const descriptor = {
+            schemaVersion: 1, bindingSha256,
+            coverageBatches: input.workload.compactEligible ? [input.requirementIds] : input.workload.buildWorkBatches(input.requirementIds),
+        };
+        layout = { ...descriptor, layoutSha256: sha256OfCanonicalJson(descriptor) };
+    }
+    const { layoutSha256, ...descriptor } = layout;
+    if (layout.bindingSha256 !== bindingSha256 || layoutSha256 !== sha256OfCanonicalJson(descriptor)) {
+        throw Error("FRONTEND_PLAN_LAYOUT_MISMATCH: frozen coverage ownership or input binding changed");
+    }
+    const members = layout.coverageBatches.flat();
+    const owners = new Map(layout.coverageBatches.flatMap((batch, index) => batch.map(id => [id, index])));
+    if (members.length !== owners.size || members.length !== input.requirementIds.length ||
+        input.requirementIds.some(id => !owners.has(id)) ||
+        input.workload.workGroups.some(group => new Set(group.requirementIds.map(id => owners.get(id))).size !== 1)) {
+        throw Error("FRONTEND_PLAN_LAYOUT_INVALID: coverage must partition complete execution groups exactly once");
+    }
+    if (raw === undefined)
+        await writeDagNodeJsonArtifact(input.runDir, input.nodeId, fileName, layout);
+    return layout.coverageBatches;
+}