@tea-agent/loop-agent 0.4.0 → 0.6.0

package/dist/executors/config-core.js

@@ -1,5 +1,5 @@
 import { DEFAULT_CURSOR_MODEL } from './cursor-executor.js';
-import { DEFAULT_DAG_MODELS } from './model-routing.js';
+import { resolveExecutorModelMatrix } from './model-routing.js';
 export const TASK_COMPLEXITY_TO_DAG = {
     small: 'LOW',
     medium: 'MED',
@@ -13,7 +13,8 @@ export function resolveCursorModelForTaskConfig(taskConfig, cursorConfig) {
         return taskConfig.cursorModel.trim();
     }
     const dagLevel = TASK_COMPLEXITY_TO_DAG[taskConfig.complexity ?? 'medium'];
-    return DEFAULT_DAG_MODELS[dagLevel] ?? resolveCursorModel({}, cursorConfig);
+    const matrix = resolveExecutorModelMatrix('cursor', cursorConfig);
+    return matrix[dagLevel] ?? resolveCursorModel({}, cursorConfig);
 }
 export function resolveTaskExecutor(taskConfig, override) {
     if (override)

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/model-routing.js

@@ -1,9 +1,52 @@
+import { DEFAULT_DAG_EXECUTOR_MODELS, } from '../workflows/dag/types.js';
 export const DEFAULT_DAG_CURSOR_MODEL = "composer-2.5";
 export const DEFAULT_DAG_MODELS = {
     HIGH: "gpt-5.5",
     MED: "composer-2.5",
     LOW: "composer-2.5",
 };
+/**
+ * DAG executor model tier keys that may carry a per-complexity override.
+ */
+const EXECUTOR_MODEL_TIERS = ["LOW", "MED", "HIGH"];
+/**
+ * Resolve the DAG executor model matrix for a single executor from its harness
+ * `executors.<name>` config.
+ *
+ * Priority per tier (LOW/MED/HIGH):
+ *   1. execConfig[tier]  (truthy and !== "default" sentinel)
+ *   2. execConfig.defaultModel (truthy and !== "default" sentinel)
+ *   3. DEFAULT_DAG_EXECUTOR_MODELS[executor][tier]
+ *
+ * The "default" literal (injected by the schema `.default("default")`) and
+ * absent/undefined both mean "no override, fall through".
+ */
+export function resolveExecutorModelMatrix(executor, execConfig) {
+    const tierValue = (tier) => {
+        const tierOverride = execConfig?.[tier];
+        if (tierOverride && tierOverride !== "default")
+            return tierOverride;
+        const defaultModel = execConfig?.defaultModel;
+        if (defaultModel && defaultModel !== "default")
+            return defaultModel;
+        return DEFAULT_DAG_EXECUTOR_MODELS[executor][tier];
+    };
+    return {
+        LOW: tierValue("LOW"),
+        MED: tierValue("MED"),
+        HIGH: tierValue("HIGH"),
+    };
+}
+/**
+ * Resolve both pi and cursor DAG executor model matrices from a harness manifest.
+ * Single entry point for DAG generation and --strict-models baseline resolution.
+ */
+export function resolveExecutorModelMatrices(manifest) {
+    return {
+        pi: resolveExecutorModelMatrix("pi", manifest.executors?.pi),
+        cursor: resolveExecutorModelMatrix("cursor", manifest.executors?.cursor),
+    };
+}
 export function resolveModelSelection(manifest, taskConfig, step, options) {
     const retryAttempt = options?.retryAttempt ?? 0;
     if (Object.keys(manifest.modelProfiles ?? {}).length === 0) {

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/governance/manifest-types.js

@@ -21,7 +21,15 @@ export const executorManifestSchema = z.object({
     description: z.string().optional(),
     enabled: z.boolean().optional(),
     defaultModel: z.string().optional().default("default"),
-    requiresApiKey: z.string().optional().default("CURSOR_API_KEY"),
+    /**
+     * Per-complexity DAG model overrides. When set (and not the "default" sentinel),
+     * these take priority over defaultModel for the matching DAG executor tier.
+     * "default" literal and absent/undefined both mean "no override, fall through".
+     */
+    LOW: z.string().optional(),
+    MED: z.string().optional(),
+    HIGH: z.string().optional(),
+    requiresApiKey: z.string().optional(),
 });
 export const workflowPolicyProfileNameSchema = z.enum([
     "minimal",

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/source-references.js

@@ -0,0 +1,221 @@
+/**
+ * Deterministic source reference materialization for task harnesses.
+ *
+ * Keeps user-authored PRD / reference docs as immutable copies under
+ * source/references/, separate from the derived source/需求.md contract.
+ */
+import { createHash } from "node:crypto";
+import { access, copyFile, mkdir, readdir, readFile, writeFile, } from "node:fs/promises";
+import path from "node:path";
+import { getTaskPaths, loadTaskConfig } from "./runtime.js";
+import { writeTaskConfig } from "../infrastructure/harness/task-store.js";
+export const SOURCE_REFERENCE_DIRECTORY = "references";
+export const SOURCE_MANIFEST_FILE = "source-manifest.json";
+function toPosixRelative(from, to) {
+    return path.relative(from, to).split(path.sep).join("/");
+}
+function slugifyName(value) {
+    const trimmed = value.trim().toLowerCase();
+    const slug = trimmed
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .replace(/-{2,}/g, "-");
+    return slug || "requirement";
+}
+function ensureUniqueReferenceName(existing, baseName, extension) {
+    const used = new Set(existing);
+    const candidate = `${baseName}${extension}`;
+    if (!used.has(candidate))
+        return candidate;
+    let index = 2;
+    while (used.has(`${baseName}-${index}${extension}`)) {
+        index += 1;
+    }
+    return `${baseName}-${index}${extension}`;
+}
+export function getSourceManifestPath(sourceDir) {
+    return path.join(sourceDir, SOURCE_MANIFEST_FILE);
+}
+export async function readSourceManifest(sourceDir) {
+    try {
+        const raw = await readFile(getSourceManifestPath(sourceDir), "utf-8");
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+async function writeSourceManifest(sourceDir, manifest) {
+    await writeFile(getSourceManifestPath(sourceDir), `${JSON.stringify(manifest, null, 2)}\n`, "utf-8");
+}
+export async function hashFile(filePath) {
+    const content = await readFile(filePath);
+    return {
+        sha256: createHash("sha256").update(content).digest("hex"),
+        bytes: content.byteLength,
+        content,
+    };
+}
+/**
+ * Copy task.json.referenceDocs into source/references/ without rewriting content.
+ * Existing same-basename files are left untouched (immutable once present).
+ */
+export async function materializeTaskReferenceDocs(input) {
+    const paths = getTaskPaths(input.repoRoot, input.taskId);
+    const taskConfig = input.taskConfig ?? (await loadTaskConfig(input.repoRoot, input.taskId));
+    const docs = taskConfig.referenceDocs ?? [];
+    if (docs.length === 0)
+        return [];
+    const referenceDir = path.join(paths.sourceDir, SOURCE_REFERENCE_DIRECTORY);
+    await mkdir(referenceDir, { recursive: true });
+    const materialized = [];
+    for (const doc of docs) {
+        const absoluteSource = path.isAbsolute(doc.path)
+            ? doc.path
+            : path.resolve(input.repoRoot, doc.path);
+        await assertReadableFile(absoluteSource, `referenceDocs entry "${doc.name ?? doc.path}"`);
+        const extension = path.extname(absoluteSource) || ".md";
+        const baseName = slugifyName(doc.name ?? path.basename(absoluteSource, extension));
+        const targetName = `${baseName}${extension}`;
+        const targetPath = path.join(referenceDir, targetName);
+        try {
+            await access(targetPath);
+            // Keep existing materialized copy immutable.
+        }
+        catch {
+            await copyFile(absoluteSource, targetPath);
+        }
+        materialized.push(targetPath);
+    }
+    return materialized;
+}
+export async function importPrdDocument(input) {
+    const now = input.now ?? new Date();
+    const paths = getTaskPaths(input.repoRoot, input.taskId);
+    await assertTaskExists(paths.taskConfigPath, input.taskId);
+    const absoluteSource = path.isAbsolute(input.filePath)
+        ? input.filePath
+        : path.resolve(input.repoRoot, input.filePath);
+    await assertReadableFile(absoluteSource, "PRD file");
+    const hash = await hashFile(absoluteSource);
+    const extension = path.extname(absoluteSource) || ".md";
+    const requestedName = slugifyName(input.name ?? "requirement");
+    const role = input.role ?? "requirement";
+    const referenceDir = path.join(paths.sourceDir, SOURCE_REFERENCE_DIRECTORY);
+    await mkdir(referenceDir, { recursive: true });
+    const existingManifest = await readSourceManifest(paths.sourceDir);
+    const existingNames = new Set((existingManifest?.documents ?? []).map((doc) => path.basename(doc.materializedPath)));
+    // Also avoid clobbering non-manifest files in references/.
+    try {
+        for (const entry of await readdir(referenceDir)) {
+            existingNames.add(entry);
+        }
+    }
+    catch {
+        // directory may be empty / just created
+    }
+    // Prefer stable name "requirement.md" when free; otherwise suffix.
+    const preferredName = `${requestedName}${extension}`;
+    const targetFileName = existingNames.has(preferredName)
+        ? // If the same content is already there, reuse; else unique name.
+            (await sameHashIfExists(path.join(referenceDir, preferredName), hash.sha256))
+                ? preferredName
+                : ensureUniqueReferenceName(existingNames, requestedName, extension)
+        : preferredName;
+    const targetPath = path.join(referenceDir, targetFileName);
+    if (!(await fileExists(targetPath))) {
+        await writeFile(targetPath, hash.content);
+    }
+    const importedAt = now.toISOString();
+    const sourcePathForRecord = path.isAbsolute(input.filePath)
+        ? toPosixRelative(input.repoRoot, absoluteSource)
+        : input.filePath.split(path.sep).join("/");
+    const materializedRelativePath = `${SOURCE_REFERENCE_DIRECTORY}/${targetFileName}`;
+    const document = {
+        role,
+        name: requestedName,
+        sourcePath: sourcePathForRecord,
+        materializedPath: materializedRelativePath,
+        sha256: hash.sha256,
+        bytes: hash.bytes,
+        importedAt,
+    };
+    const documents = [...(existingManifest?.documents ?? [])].filter((entry) => entry.materializedPath !== materializedRelativePath);
+    documents.push(document);
+    documents.sort((left, right) => left.materializedPath.localeCompare(right.materializedPath));
+    const manifest = {
+        schemaVersion: 1,
+        taskId: input.taskId,
+        updatedAt: importedAt,
+        documents,
+    };
+    await writeSourceManifest(paths.sourceDir, manifest);
+    const taskConfig = await loadTaskConfig(input.repoRoot, input.taskId);
+    const referenceDocs = [...(taskConfig.referenceDocs ?? [])];
+    const alreadyListed = referenceDocs.some((doc) => {
+        const absolute = path.isAbsolute(doc.path)
+            ? doc.path
+            : path.resolve(input.repoRoot, doc.path);
+        return absolute === absoluteSource;
+    });
+    if (!alreadyListed) {
+        referenceDocs.push({
+            name: requestedName,
+            path: sourcePathForRecord,
+        });
+        await writeTaskConfig(input.repoRoot, input.taskId, {
+            ...taskConfig,
+            referenceDocs,
+        });
+    }
+    return {
+        taskId: input.taskId,
+        sourcePath: sourcePathForRecord,
+        materializedAbsolutePath: targetPath,
+        materializedRelativePath,
+        sha256: hash.sha256,
+        bytes: hash.bytes,
+        manifestPath: getSourceManifestPath(paths.sourceDir),
+        referenceDocs: alreadyListed ? referenceDocs : [...referenceDocs],
+    };
+}
+async function sameHashIfExists(filePath, sha256) {
+    try {
+        const existing = await hashFile(filePath);
+        return existing.sha256 === sha256;
+    }
+    catch {
+        return false;
+    }
+}
+async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function assertTaskExists(taskConfigPath, taskId) {
+    try {
+        await access(taskConfigPath);
+    }
+    catch {
+        throw new Error(`task not found: ${taskId} (expected ${taskConfigPath}). Run new-task first.`);
+    }
+}
+async function assertReadableFile(filePath, label) {
+    try {
+        await access(filePath);
+    }
+    catch {
+        throw new Error(`${label} is not readable: ${filePath}`);
+    }
+}

package/dist/worker/cli.js

@@ -9,6 +9,11 @@ import { resolveLoopAgentProfile } from "./profile-mapping.js";
 import { writeMorningReport } from "./report/morning-report.js";
 import { buildBatchRunId, runReadyTasks } from "./runner/run-ready.js";
 import { createProgressReporter } from "./progress-reporter.js";
+import { createCompositeProgressReporter } from "./observability/progress-composite.js";
+import { createRoutedWorkerEventStore } from "./observability/event-store.js";
+import { buildGlobalSnapshot } from "./observability/read-model.js";
+import { createObserveServer } from "./observe/server.js";
+import { prepareTaskPoolRetry } from "./pool/run-store.js";
 import { taskSpecSchema } from "./task-spec/schema.js";
 import { validateTaskSpec } from "./task-spec/validate.js";
 export function buildAgentWorkerProgram() {
@@ -21,6 +26,7 @@ export function buildAgentWorkerProgram() {
     const task = program.command("task").description("TaskSpec utilities");
     const batch = program.command("batch").description("Task Pool batch utilities");
     const report = program.command("report").description("Task Pool reporting utilities");
+    const observe = program.command("observe").description("Observe UI server and snapshot utilities");
     task
         .command("validate")
         .argument("<task-yaml>", "TaskSpec YAML file")
@@ -43,6 +49,20 @@ export function buildAgentWorkerProgram() {
         const result = resolveLoopAgentProfile(parsed);
         process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
     });
+    task
+        .command("retry")
+        .argument("<task-id>", "Failed Task Pool task to requeue")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--reason <reason>", "Why the failure is safe to retry")
+        .description("Explicitly requeue a failed task; the next run-ready uses a new workerRunId")
+        .action(async (taskId, options) => {
+        const result = await prepareTaskPoolRetry({
+            repoRoot: path.resolve(options.repo),
+            taskId,
+            ...(options.reason ? { reason: options.reason } : {}),
+        });
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    });
     batch
         .command("run-ready")
         .requiredOption("--feature-dir <dir>", "Feature directory containing tasks/task-graph.yaml")
@@ -62,7 +82,18 @@ export function buildAgentWorkerProgram() {
             loopAgentBin: options.loopAgentBin,
             artifactRoot: path.join(repoRoot, ".task-pool", "artifacts", batchRunId),
         });
-        const progress = createProgressReporter({ quiet: options.quiet ?? false });
+        let progress;
+        try {
+            const eventStore = createRoutedWorkerEventStore(repoRoot);
+            progress = createCompositeProgressReporter({
+                quiet: options.quiet ?? false,
+                eventStore,
+                context: { batchRunId },
+            });
+        }
+        catch {
+            progress = createProgressReporter({ quiet: options.quiet ?? false });
+        }
         const result = await runReadyTasks({
             repoRoot,
             featureDir: path.resolve(options.featureDir),
@@ -80,6 +111,36 @@ export function buildAgentWorkerProgram() {
         if (result.status !== "completed")
             process.exitCode = 1;
     });
+    observe
+        .command("serve")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--port <port>", "HTTP port", "8787")
+        .option("--host <host>", "Bind host", "127.0.0.1")
+        .description("Start read-only observe HTTP server")
+        .action(async (options) => {
+        const repoRoot = path.resolve(options.repo);
+        const server = await createObserveServer({
+            repoRoot,
+            host: options.host,
+            port: Number.parseInt(options.port, 10),
+        });
+        process.stdout.write(`${server.url}\n`);
+        await new Promise((resolve) => {
+            const shutdown = () => resolve();
+            process.once("SIGINT", shutdown);
+            process.once("SIGTERM", shutdown);
+        });
+        await server.close();
+    });
+    observe
+        .command("snapshot")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--json", "Emit JSON (default)")
+        .description("Print GlobalSnapshot JSON to stdout")
+        .action(async (options) => {
+        const snapshot = await buildGlobalSnapshot({ repoRoot: path.resolve(options.repo) });
+        process.stdout.write(`${JSON.stringify(snapshot)}\n`);
+    });
     report
         .command("morning")
         .requiredOption("--repo <repo-root>", "Target repo root")