@tea-agent/loop-agent 0.5.0 → 0.7.0

package/dist/commands/instructions.js

@@ -1,42 +1,42 @@
-import { access, readdir } from 'node:fs/promises';
-import path from 'node:path';
-import { getArtifactPath, getArtifactRelativePath, } from '../shared/artifacts-core.js';
-import { defaultHybridDagOutputPath } from '../workflows/dag/init-hybrid.js';
-import { getTaskDir, getTaskPaths, loadTaskConfig } from '../task/runtime.js';
+import { access, readdir } from "node:fs/promises";
+import path from "node:path";
+import { getArtifactPath, getArtifactRelativePath, } from "../shared/artifacts-core.js";
+import { defaultHybridDagOutputPath } from "../workflows/dag/init-hybrid.js";
+import { getTaskDir, getTaskPaths, loadTaskConfig } from "../task/runtime.js";
 const STAGES = new Set([
-    'source',
-    'dag-draft',
-    'task-artifacts',
-    'promotion',
-    'closeout',
+    "source",
+    "dag-draft",
+    "task-artifacts",
+    "promotion",
+    "closeout",
 ]);
 export function parseInstructionsArgs(args) {
     const [stageRaw, ...rest] = args;
     if (!stageRaw || !STAGES.has(stageRaw)) {
-        throw new Error('usage: instructions <source|dag-draft|task-artifacts|promotion|closeout> --task <task-id> [--json]');
+        throw new Error("usage: instructions <source|dag-draft|task-artifacts|promotion|closeout> --task <task-id> [--json]");
     }
     let taskId;
     let json = false;
     for (let i = 0; i < rest.length; i += 1) {
         const arg = rest[i];
-        if (arg === '--task') {
+        if (arg === "--task") {
             taskId = rest[++i];
             if (!taskId)
-                throw new Error('instructions --task requires a task id');
+                throw new Error("instructions --task requires a task id");
             continue;
         }
-        if (arg.startsWith('--task=')) {
-            taskId = arg.slice('--task='.length);
+        if (arg.startsWith("--task=")) {
+            taskId = arg.slice("--task=".length);
             continue;
         }
-        if (arg === '--json') {
+        if (arg === "--json") {
             json = true;
             continue;
         }
         throw new Error(`unknown instructions flag: ${arg}`);
     }
     if (!taskId)
-        throw new Error('instructions requires --task <task-id>');
+        throw new Error("instructions requires --task <task-id>");
     return { stage: stageRaw, taskId, json };
 }
 export async function runInstructions(repoRoot, args) {
@@ -54,13 +54,13 @@ export async function buildInstructions(repoRoot, stage, taskId) {
     const taskConfig = await loadTaskConfig(repoRoot, taskId);
     const allowedEditRoots = taskConfig.allowedPaths.length > 0
         ? taskConfig.allowedPaths
-        : [path.relative(repoRoot, taskDir).replace(/\\/g, '/')];
+        : [path.relative(repoRoot, taskDir).replace(/\\/g, "/")];
     const writePolicy = {
-        mode: stage === 'promotion'
-            ? 'run-evidence-read-only'
-            : stage === 'closeout'
-                ? 'docs-progress'
-                : 'task-owned',
+        mode: stage === "promotion"
+            ? "run-evidence-read-only"
+            : stage === "closeout"
+                ? "docs-progress"
+                : "task-owned",
         allowedEditRoots,
         forbiddenPaths: taskConfig.forbiddenPaths,
     };
@@ -70,74 +70,106 @@ export async function buildInstructions(repoRoot, stage, taskId) {
         existingFiles: await listExistingFiles(taskDir),
         writePolicy,
     };
-    if (stage === 'source') {
+    if (stage === "source") {
         return refreshInstructionBlockers(withMissingDependencies({
             ...base,
             outputPath: paths.sourceDir,
             dependencies: [paths.taskConfigPath],
-            template: { requiredHeadings: ['# 需求', '# 执行约束'] },
+            template: {
+                requiredHeadings: [
+                    "# 需求",
+                    "# 执行约束",
+                    "## 目标",
+                    "## 验收标准",
+                    "## 非目标",
+                ],
+            },
             completionCriteria: [
-                'source/需求.md exists with concrete requirements',
-                'source/执行约束.md exists when path or behavioral constraints matter',
+                "source/references/ holds the immutable original PRD (via import-prd or materialize); do not let AI rewrite it",
+                "source/需求.md is a derived execution contract with objective, scope, non-goals, and acceptance criteria mapped back to the original PRD",
+                "source/需求.md uses stable REQ/AC ids or explicit source anchors when the original PRD is long",
+                "source/执行约束.md exists when path or behavioral constraints matter",
+                "AI assumptions that are not in the original PRD stay under open questions, never as fake requirements",
             ],
         }));
     }
-    if (stage === 'dag-draft') {
+    if (stage === "dag-draft") {
         return refreshInstructionBlockers(withMissingDependencies({
             ...base,
             outputPath: defaultHybridDagOutputPath(taskId),
             dependencies: [
                 paths.taskConfigPath,
-                path.join(paths.sourceDir, '需求.md'),
+                path.join(paths.sourceDir, "需求.md"),
             ],
-            template: { requiredHeadings: ['version', 'title', 'objective', 'tasks', 'executorModels'] },
+            template: {
+                requiredHeadings: [
+                    "version",
+                    "title",
+                    "objective",
+                    "tasks",
+                    "executorModels",
+                ],
+            },
             completionCriteria: [
-                'dag draft validates with dag validate --strict-models --strict-governance',
-                'writeSet is narrow and matches task constraints',
+                "dag draft validates with dag validate --strict-models --strict-governance",
+                "writeSet is narrow and matches task constraints",
             ],
         }));
     }
-    if (stage === 'promotion') {
+    if (stage === "promotion") {
         return refreshInstructionBlockers(withMissingDependencies({
             ...base,
-            outputPath: path.join(taskDir, 'artifacts'),
+            outputPath: path.join(taskDir, "artifacts"),
             dependencies: [
-                path.join(repoRoot, '.harness', 'dag-runs', 'completed'),
-                path.join(repoRoot, '.harness', 'runs', 'completed'),
+                path.join(repoRoot, ".harness", "dag-runs", "completed"),
+                path.join(repoRoot, ".harness", "runs", "completed"),
             ],
-            template: { requiredHeadings: ['# 修改记录', '# 验证结果'] },
+            template: { requiredHeadings: ["# 修改记录", "# 验证结果"] },
             completionCriteria: [
-                'completed run facts remain read-only',
-                'task artifacts summarize real run evidence without inventing verification',
+                "completed run facts remain read-only",
+                "task artifacts summarize real run evidence without inventing verification",
             ],
         }));
     }
-    if (stage === 'closeout') {
+    if (stage === "closeout") {
         return refreshInstructionBlockers(withMissingDependencies({
             ...base,
-            outputPath: path.join(repoRoot, 'docs', 'progress', `${taskId}.md`),
+            outputPath: path.join(repoRoot, "docs", "progress", `${taskId}.md`),
             dependencies: [
-                getArtifactPath(taskDir, 'implement'),
-                getArtifactPath(taskDir, 'verify'),
+                getArtifactPath(taskDir, "implement"),
+                getArtifactPath(taskDir, "verify"),
             ],
-            template: { requiredHeadings: ['# Progress', '## Summary', '## Verification', '## Remaining Risk'] },
+            template: {
+                requiredHeadings: [
+                    "# Progress",
+                    "## Summary",
+                    "## Verification",
+                    "## Remaining Risk",
+                ],
+            },
             completionCriteria: [
-                'records commands actually run and their outcome',
-                'links remaining risks or follow-up tasks',
+                "records commands actually run and their outcome",
+                "links remaining risks or follow-up tasks",
             ],
         }));
     }
-    const artifactSteps = ['analyze', 'plan', 'implement', 'verify', 'retrospective'];
+    const artifactSteps = [
+        "analyze",
+        "plan",
+        "implement",
+        "verify",
+        "retrospective",
+    ];
     return refreshInstructionBlockers(withMissingDependencies({
         ...base,
-        outputPath: path.join(taskDir, 'artifacts'),
+        outputPath: path.join(taskDir, "artifacts"),
         dependencies: [paths.taskConfigPath, paths.statePath],
         template: {
             requiredHeadings: artifactSteps.map((step) => getArtifactRelativePath(step)),
         },
         completionCriteria: [
-            'artifact content is substantive and not the new-task template',
-            'verification artifact names exact commands and pass/fail results',
+            "artifact content is substantive and not the new-task template",
+            "verification artifact names exact commands and pass/fail results",
         ],
     }));
 }
@@ -153,7 +185,7 @@ async function listExistingFiles(root) {
         const names = await readdir(root, { recursive: true });
         return names
             .map((name) => String(name))
-            .filter((name) => !name.includes('/logs/'))
+            .filter((name) => !name.includes("/logs/"))
             .sort();
     }
     catch {
@@ -179,17 +211,17 @@ export async function refreshInstructionBlockers(doc) {
 function formatInstructionsMarkdown(doc) {
     const lines = [
         `# Instructions: ${doc.artifactId}`,
-        '',
+        "",
         `- task: \`${doc.taskId}\``,
         `- output: \`${doc.outputPath}\``,
         `- write policy: \`${doc.writePolicy.mode}\``,
-        `- blocked: ${doc.blocked ? 'yes' : 'no'}`,
-        '',
-        '## Dependencies',
+        `- blocked: ${doc.blocked ? "yes" : "no"}`,
+        "",
+        "## Dependencies",
         ...doc.dependencies.map((dep) => `- \`${dep}\``),
-        '',
-        '## Completion Criteria',
+        "",
+        "## Completion Criteria",
         ...doc.completionCriteria.map((criterion) => `- ${criterion}`),
     ];
-    return `${lines.join('\n')}\n`;
+    return `${lines.join("\n")}\n`;
 }

package/dist/commands/loop-benchmark.js

@@ -37,17 +37,17 @@ export function parseLoopBenchmarkArgs(args) {
     return { json, markdown, outputPath };
 }
 export function printLoopBenchmarkUsage() {
-    console.log(`usage: loop-benchmark [options]
-
-Deterministic loop-agent loop benchmark baseline (no live Pi/Cursor calls).
-
-Options:
-  --json              Emit JSON (default when no format flag is set)
-  --markdown          Emit Markdown report
-  --output <path>     Write Markdown report to a repo-relative or absolute path
-  -h, --help          Show this help
-
-Control groups: single-repair, 3-pass-convergence, 3-pass-convergence+quota.
+    console.log(`usage: loop-benchmark [options]
+
+Deterministic loop-agent loop benchmark baseline (no live Pi/Cursor calls).
+
+Options:
+  --json              Emit JSON (default when no format flag is set)
+  --markdown          Emit Markdown report
+  --output <path>     Write Markdown report to a repo-relative or absolute path
+  -h, --help          Show this help
+
+Control groups: single-repair, 3-pass-convergence, 3-pass-convergence+quota.
 Recommendation never changes convergence.enabled default.`);
 }
 export async function runLoopBenchmark(repoRoot, rawArgs) {

package/dist/commands/pi-reuse-benchmark.js

@@ -106,22 +106,22 @@ export function parsePiReuseBenchmarkArgs(args) {
     };
 }
 export function printPiReuseBenchmarkUsage() {
-    console.log(`usage: pi-reuse-benchmark [options]
-
-Deterministic Pi runtime reuse benchmark/decision summary (no live Pi calls).
-
-Options:
-  --report <path>         Benchmark report markdown (approval status)
-  --approval <path>       Explicit approval JSON artifact
-  --off-executor <path>   Baseline executor.jsonl (reuse off)
-  --on-executor <path>    Treatment executor.jsonl (reuse on)
-  --off-task <task-id>    Resolve baseline from .harness/tasks/<id>/logs/executor.jsonl
-  --on-task <task-id>     Resolve treatment from .harness/tasks/<id>/logs/executor.jsonl
-  --json                  Emit JSON (default when no format flag is set)
-  --markdown              Emit Markdown summary
-  -h, --help              Show this help
-
-Recommendations: defer | maintain-opt-in | eligible-for-human-review
+    console.log(`usage: pi-reuse-benchmark [options]
+
+Deterministic Pi runtime reuse benchmark/decision summary (no live Pi calls).
+
+Options:
+  --report <path>         Benchmark report markdown (approval status)
+  --approval <path>       Explicit approval JSON artifact
+  --off-executor <path>   Baseline executor.jsonl (reuse off)
+  --on-executor <path>    Treatment executor.jsonl (reuse on)
+  --off-task <task-id>    Resolve baseline from .harness/tasks/<id>/logs/executor.jsonl
+  --on-task <task-id>     Resolve treatment from .harness/tasks/<id>/logs/executor.jsonl
+  --json                  Emit JSON (default when no format flag is set)
+  --markdown              Emit Markdown summary
+  -h, --help              Show this help
+
+Recommendations: defer | maintain-opt-in | eligible-for-human-review
 Never changes CODE_AGENT_PI_REUSE_RUNTIME default (off).`);
 }
 function resolveRepoRelative(repoRoot, filePath) {

package/dist/executors/cursor-executor.js

@@ -29,7 +29,7 @@ export function resolveArtifactWriteDir(options) {
 }
 export function buildArtifactPathPrompt(writeDir) {
     if (!writeDir)
-        return `After changes, write artifacts/修改记录.md and artifacts/验证结果.md with verification evidence.
+        return `After changes, write artifacts/修改记录.md and artifacts/验证结果.md with verification evidence.
 ${ARTIFACT_INSTRUCTIONS}`;
     return [
         `After changes, write the following files:`,

package/dist/executors/dag-pi-executor.js

@@ -256,6 +256,7 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep) {
         step,
         toolNames: resolveDagPiToolNames(input.task),
         userMessage: buildDagPiUserMessage(input.task, persona, step),
+        sessionEventsPath: path.join(meta.runDir, input.task.id, "session-events.jsonl"),
     });
     const context = {
         channel: "dag",

package/dist/executors/pi-sdk-executor.js

@@ -1,3 +1,5 @@
+import { appendFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
 import { classifyPiFailure, DEFAULT_TIMEOUT_MS, extractAssistantTextFromPiJson, extractTokenUsageFromPiJson, } from './pi-executor.js';
 import { serializeSessionEvent } from './pi-event-serializer.js';
 let sdkSessionFactoryOverride;
@@ -132,6 +134,51 @@ async function createSdkSession(sdk, input, shared) {
     });
     return created.session;
 }
+/**
+ * Throttle high-noise Pi SDK events from session-events.jsonl.
+ * Always keeps tool lifecycle, turn/agent end, assistant messages, and errors.
+ * Skips thinking_delta and message_update token floods.
+ */
+export function shouldPersistSessionEvent(event) {
+    const type = typeof event.type === 'string' ? event.type : '';
+    if (type === 'tool_start' || type === 'tool_end'
+        || type === 'tool_execution_start' || type === 'tool_execution_end'
+        || type === 'turn_end' || type === 'agent_end'
+        || type === 'assistant_message' || type === 'message_end') {
+        return true;
+    }
+    if (type === 'thinking_delta' || type === 'message_update') {
+        return false;
+    }
+    if (type.includes('error') || event.isError === true) {
+        return true;
+    }
+    return true;
+}
+function createSessionEventAppender(filePath, onSessionEvent) {
+    let chain = Promise.resolve();
+    let dirEnsured = false;
+    return {
+        append(line, event) {
+            chain = chain.then(async () => {
+                try {
+                    if (!dirEnsured) {
+                        await mkdir(path.dirname(filePath), { recursive: true });
+                        dirEnsured = true;
+                    }
+                    await appendFile(filePath, `${line}\n`, 'utf-8');
+                    onSessionEvent?.(line, event);
+                }
+                catch {
+                    // best-effort: never fail the pi step
+                }
+            });
+        },
+        drain() {
+            return chain;
+        },
+    };
+}
 async function resolveSdkSessionFactory(reuseScope) {
     if (sdkSessionFactoryOverride)
         return sdkSessionFactoryOverride;
@@ -168,6 +215,9 @@ export async function executeSingleSdkAttempt(options) {
     const stdoutLines = [];
     let session;
     let timeoutHandle;
+    const sessionEventAppender = options.sessionEventsPath
+        ? createSessionEventAppender(options.sessionEventsPath, options.onSessionEvent)
+        : undefined;
     try {
         const createSession = await resolveSdkSessionFactory(options.reuseScope);
         session = await createSession({
@@ -179,7 +229,11 @@ export async function executeSingleSdkAttempt(options) {
             thinking: modelConfig.thinking,
         });
         const unsubscribe = session.subscribe((event) => {
-            stdoutLines.push(serializeSessionEvent(event));
+            const line = serializeSessionEvent(event);
+            stdoutLines.push(line);
+            if (sessionEventAppender && shouldPersistSessionEvent(event)) {
+                sessionEventAppender.append(line, event);
+            }
         });
         const filePrefix = options.attachedFiles.map((file) => `@${file}`).join(' ');
         const promptMessage = filePrefix
@@ -225,6 +279,14 @@ export async function executeSingleSdkAttempt(options) {
                 stderr = stderr ? `${stderr}\n${message}` : message;
             }
         }
+        if (sessionEventAppender) {
+            try {
+                await sessionEventAppender.drain();
+            }
+            catch {
+                // best-effort: never fail the pi step
+            }
+        }
     }
     const stdout = stdoutLines.join('\n');
     const durationMs = Date.now() - startedAt;

package/dist/shared/preview.js

@@ -0,0 +1,39 @@
+const ENCODER = new TextEncoder();
+const DECODER = new TextDecoder();
+export function redactSecrets(text) {
+    return text
+        .replace(/\bBearer\s+[^\s"']+/gi, "Bearer ***")
+        .replace(/(\b[A-Z][A-Z0-9_]*=)[^\s]+/g, "$1***")
+        .replace(/(["']?(?:api[_-]?key|token|password|secret|authorization)["']?\s*[:=]\s*["']?)([^"'\s,}]+)/gi, "$1***");
+}
+export function truncateUtf8Preview(text, maxBytes = 4096) {
+    if (maxBytes <= 0)
+        return "";
+    const bytes = ENCODER.encode(text);
+    if (bytes.length <= maxBytes)
+        return text;
+    let prefixEnd = safeUtf8End(bytes, Math.max(0, maxBytes - 32));
+    for (let attempt = 0; attempt < 8; attempt += 1) {
+        const omittedBytes = bytes.length - prefixEnd;
+        const suffix = `…<truncated ${omittedBytes} bytes>`;
+        const suffixBytes = ENCODER.encode(suffix);
+        if (suffixBytes.length >= maxBytes) {
+            const suffixEnd = safeUtf8End(suffixBytes, maxBytes);
+            return DECODER.decode(suffixBytes.subarray(0, suffixEnd));
+        }
+        const nextPrefixEnd = safeUtf8End(bytes, maxBytes - suffixBytes.length);
+        if (nextPrefixEnd === prefixEnd) {
+            return DECODER.decode(bytes.subarray(0, prefixEnd)) + suffix;
+        }
+        prefixEnd = nextPrefixEnd;
+    }
+    const omittedBytes = bytes.length - prefixEnd;
+    return `${DECODER.decode(bytes.subarray(0, prefixEnd))}…<truncated ${omittedBytes} bytes>`;
+}
+function safeUtf8End(bytes, budget) {
+    let end = Math.min(bytes.length, Math.max(0, budget));
+    while (end > 0 && end < bytes.length && (bytes[end] & 0xc0) === 0x80) {
+        end -= 1;
+    }
+    return end;
+}

package/dist/task/config-types.js

@@ -19,6 +19,7 @@ export const referenceDocConfigSchema = z.object({
     path: z.string().min(1),
 });
 export const taskComplexitySchema = z.enum(["small", "medium", "large"]);
+export const taskCapabilitySchema = z.enum(["interactive-ui"]);
 export const contextProfileSchema = z.enum(["full", "slim"]);
 export const piSubagentModeSchema = z.enum(["off", "analyze-plan", "full"]);
 export const verifyModeSchema = z.enum(["parallel", "serial"]);
@@ -68,6 +69,8 @@ export const taskConfigSchema = z.object({
     timeoutMs: z.number().int().positive().optional(),
     flow: taskFlowSchema.optional().default("auto"),
     complexity: taskComplexitySchema.optional().default("medium"),
+    /** Explicit delivery capabilities that affect writer contracts/model tier without changing risk. */
+    capabilities: z.array(taskCapabilitySchema).optional(),
     verifyMode: verifyModeSchema.optional().default("parallel"),
     verifyPreset: verifyPresetSchema.optional().default("auto"),
     /** Verification selection policy. Intermediate loops may use quota; final gates still run full required verification. */

package/dist/task/runtime.js

@@ -236,35 +236,35 @@ export function shouldInjectSubagentGuidance(step, mode) {
     return false;
 }
 /** Advisory guidance for `analyze-plan` mode. */
-export const SUBAGENT_GUIDANCE_STANDARD = `<subagent_guidance>
-You have access to the \`subagent\` tool for lightweight delegation within this step.
-Use it only for read-only tasks:
-- Parallel scout: dispatch multiple subagents to search/read different areas simultaneously
-- Chain: scout -> planner (one subagent scouts, another plans based on findings)
-- Reviewer: have a subagent review your analysis/plan before finalizing
-Do NOT use subagent for writing, editing, or executing commands.
-Subagent output is advisory only; always verify and incorporate findings into your own output.
-Do NOT treat subagent results as authoritative state or artifact sources.
+export const SUBAGENT_GUIDANCE_STANDARD = `<subagent_guidance>
+You have access to the \`subagent\` tool for lightweight delegation within this step.
+Use it only for read-only tasks:
+- Parallel scout: dispatch multiple subagents to search/read different areas simultaneously
+- Chain: scout -> planner (one subagent scouts, another plans based on findings)
+- Reviewer: have a subagent review your analysis/plan before finalizing
+Do NOT use subagent for writing, editing, or executing commands.
+Subagent output is advisory only; always verify and incorporate findings into your own output.
+Do NOT treat subagent results as authoritative state or artifact sources.
 </subagent_guidance>`;
 /** Strong guidance for `full` mode — prescriptive when to delegate. */
-export const SUBAGENT_GUIDANCE_STRONG = `<subagent_guidance>
-You have access to the \`subagent\` tool for lightweight delegation within this step.
-
-You SHOULD delegate to subagent scouts when:
-- The task requires scanning 3+ directories or comparing implementations across modules
-- You would otherwise need 5+ sequential read/grep calls to gather context
-- A reviewer subagent can independently catch scope drift before you finalize your output
-
-Delegation saves context tokens and produces better results.
-
-Allowed patterns:
-- Parallel scout: dispatch 2-3 subagents simultaneously to cover different file trees
-- Chain: scout -> planner (one subagent scouts, another plans based on findings)
-- Reviewer: have a subagent review your analysis/plan before finalizing
-
-Do NOT use subagent for writing, editing, or executing commands.
-Subagent output is advisory only; always verify and incorporate findings into your own output.
-Do NOT treat subagent results as authoritative state or artifact sources.
+export const SUBAGENT_GUIDANCE_STRONG = `<subagent_guidance>
+You have access to the \`subagent\` tool for lightweight delegation within this step.
+
+You SHOULD delegate to subagent scouts when:
+- The task requires scanning 3+ directories or comparing implementations across modules
+- You would otherwise need 5+ sequential read/grep calls to gather context
+- A reviewer subagent can independently catch scope drift before you finalize your output
+
+Delegation saves context tokens and produces better results.
+
+Allowed patterns:
+- Parallel scout: dispatch 2-3 subagents simultaneously to cover different file trees
+- Chain: scout -> planner (one subagent scouts, another plans based on findings)
+- Reviewer: have a subagent review your analysis/plan before finalizing
+
+Do NOT use subagent for writing, editing, or executing commands.
+Subagent output is advisory only; always verify and incorporate findings into your own output.
+Do NOT treat subagent results as authoritative state or artifact sources.
 </subagent_guidance>`;
 /** Preserved for backward compatibility (alias of STANDARD). */
 export const SUBAGENT_GUIDANCE = SUBAGENT_GUIDANCE_STANDARD;