@tea-agent/loop-agent 0.1.0

package/dist/task/source-state.js

@@ -0,0 +1 @@
+export { assertPlanFreshForImplement, markSpecCompleted, refreshSourceState, } from "./runtime.js";

package/dist/task/state.js

@@ -0,0 +1,55 @@
+import { copyFile, readFile, rename, unlink, writeFile, } from 'node:fs/promises';
+import { workflowStateSchema } from '../shared/types.js';
+function parseWorkflowState(raw) {
+    try {
+        return workflowStateSchema.parse(JSON.parse(raw));
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist backup atomically (tmp → rename), tolerant of Windows rename semantics. */
+async function writeBackupCopy(bakPath, json) {
+    const bakTmp = `${bakPath}.${process.pid}.tmp`;
+    await writeFile(bakTmp, json, 'utf-8');
+    try {
+        await rename(bakTmp, bakPath);
+    }
+    catch {
+        await copyFile(bakTmp, bakPath);
+        await unlink(bakTmp).catch(() => { });
+    }
+}
+export async function loadWorkflowState(statePath) {
+    const bakPath = `${statePath}.bak`;
+    let raw = '';
+    try {
+        raw = await readFile(statePath, 'utf-8');
+    }
+    catch {
+        raw = '';
+    }
+    const primary = raw.trim() ? parseWorkflowState(raw) : null;
+    if (primary)
+        return primary;
+    try {
+        raw = await readFile(bakPath, 'utf-8');
+    }
+    catch {
+        raw = '';
+    }
+    const fromBak = raw.trim() ? parseWorkflowState(raw) : null;
+    if (fromBak) {
+        const json = `${JSON.stringify(fromBak, null, 2)}\n`;
+        await writeFile(statePath, json, 'utf-8');
+        await writeBackupCopy(bakPath, json);
+        return fromBak;
+    }
+    throw new Error(`workflow state unreadable or missing: ${statePath} (no valid ${bakPath})`);
+}
+export async function saveWorkflowState(statePath, state) {
+    const json = `${JSON.stringify(state, null, 2)}\n`;
+    const bakPath = `${statePath}.bak`;
+    await writeFile(statePath, json, 'utf-8');
+    await writeBackupCopy(bakPath, json);
+}

package/dist/task/subagent-guidance.js

@@ -0,0 +1 @@
+export { resolvePiSubagentTools, resolveSubagentGuidance, shouldInjectSubagentGuidance, SUBAGENT_GUIDANCE, SUBAGENT_GUIDANCE_STANDARD, SUBAGENT_GUIDANCE_STRONG, } from "./runtime.js";

package/dist/task/workflow-state-types.js

@@ -0,0 +1,92 @@
+import { z } from "zod";
+import { taskExecutorSchema } from "../governance/manifest-types.js";
+export const stepNameSchema = z.enum([
+    "analyze",
+    "plan",
+    "spec",
+    "implement",
+    "verify",
+    "retrospective",
+]);
+export const workflowTaskStatusSchema = z.enum([
+    "draft",
+    "active",
+    "completed",
+    "failed",
+]);
+export const taskGoalStatusSchema = z.enum([
+    "active",
+    "paused",
+    "budget_limited",
+    "complete",
+]);
+export const taskGoalStateSchema = z.object({
+    objective: z.string().default(""),
+    status: taskGoalStatusSchema.default("paused"),
+    tokenBudget: z.number().int().positive().nullable().default(null),
+    tokensUsed: z.number().int().nonnegative().default(0),
+    timeUsedSeconds: z.number().int().nonnegative().default(0),
+    pendingObjectiveUpdatedNotice: z.boolean().default(false),
+    pendingBudgetLimitNotice: z.boolean().default(false),
+    /** Number of legacy goal continuation attempts in the current goal lifecycle */
+    continuationRuns: z.number().int().nonnegative().default(0),
+    createdAt: z.string().default(""),
+    updatedAt: z.string().default(""),
+});
+export const workflowDecisionSchema = z.object({
+    time: z.string(),
+    step: stepNameSchema,
+    fromStatus: workflowTaskStatusSchema,
+    toStatus: workflowTaskStatusSchema,
+    reason: z.string(),
+    evidence: z.string().optional().default(""),
+});
+export const sourceStateSchema = z.object({
+    currentHash: z.string().default(""),
+    plannedHash: z.string().default(""),
+    trackedFiles: z.array(z.string()).default([]),
+    lastCheckedAt: z.string().default(""),
+    lastPlannedAt: z.string().default(""),
+    lastPlannedStep: z.enum(["plan", "spec"]).nullable().default(null),
+    stalePlan: z.boolean().default(false),
+});
+export const workflowStateSchema = z.object({
+    taskId: z.string(),
+    status: workflowTaskStatusSchema,
+    currentStep: stepNameSchema,
+    completedSteps: z.array(stepNameSchema),
+    lastUpdated: z.string(),
+    executor: z.object({
+        name: taskExecutorSchema.default("pi"),
+        mode: z.enum(["json", "sdk"]).optional().default("json"),
+    }),
+    artifacts: z.object({
+        analysis: z.boolean(),
+        plan: z.boolean(),
+        modifyLog: z.boolean(),
+        verifyResult: z.boolean(),
+        retrospective: z.boolean(),
+    }),
+    sourceState: sourceStateSchema.default({
+        currentHash: "",
+        plannedHash: "",
+        trackedFiles: [],
+        lastCheckedAt: "",
+        lastPlannedAt: "",
+        lastPlannedStep: null,
+        stalePlan: false,
+    }),
+    goal: taskGoalStateSchema.default({
+        objective: "",
+        status: "paused",
+        tokenBudget: null,
+        tokensUsed: 0,
+        timeUsedSeconds: 0,
+        pendingObjectiveUpdatedNotice: false,
+        pendingBudgetLimitNotice: false,
+        continuationRuns: 0,
+        createdAt: "",
+        updatedAt: "",
+    }),
+    decisionLog: z.array(workflowDecisionSchema).default([]),
+});

package/dist/task/worktree-cleanup.js

@@ -0,0 +1,140 @@
+import { copyFile, mkdir, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { loadHarnessManifest } from '../governance/harness.js';
+import { appendWorkflowLog } from '../shared/logger.js';
+import { getTaskDir, getTaskPaths } from './runtime.js';
+import { copyDir } from '../shared/copy-dir.js';
+import { removeWorktree, resolveWorktreePath } from './worktree.js';
+/**
+ * If cwd is `.worktrees/<taskId>`, return the main repo root; otherwise treat cwd as main repo.
+ */
+export function inferMainRepoRoot(cwd, taskId) {
+    if (process.platform === 'win32' && cwd.startsWith('/') && !cwd.startsWith('//')) {
+        const resolved = path.posix.normalize(cwd);
+        if (path.posix.basename(resolved) === taskId && path.posix.basename(path.posix.dirname(resolved)) === '.worktrees') {
+            return {
+                mainRepoRoot: path.posix.dirname(path.posix.dirname(resolved)),
+                worktreePath: resolved,
+            };
+        }
+        return { mainRepoRoot: resolved, worktreePath: null };
+    }
+    const resolved = path.resolve(cwd);
+    if (path.basename(resolved) === taskId && path.basename(path.dirname(resolved)) === '.worktrees') {
+        return {
+            mainRepoRoot: path.dirname(path.dirname(resolved)),
+            worktreePath: resolved,
+        };
+    }
+    return { mainRepoRoot: resolved, worktreePath: null };
+}
+async function pathExists(p) {
+    try {
+        await stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Copy artifacts/logs/state from worktree task dir into main repo task dir. */
+export async function archiveTaskDirFromWorktree(mainRepoRoot, worktreePath, taskId) {
+    const srcTaskDir = getTaskPaths(worktreePath, taskId).taskDir;
+    const destTaskDir = getTaskPaths(mainRepoRoot, taskId).taskDir;
+    for (const sub of ['artifacts', 'logs']) {
+        const srcSub = path.join(srcTaskDir, sub);
+        const destSub = path.join(destTaskDir, sub);
+        if (await pathExists(srcSub)) {
+            await mkdir(destSub, { recursive: true });
+            await copyDir(srcSub, destSub);
+        }
+    }
+    const srcStateFile = path.join(srcTaskDir, '.workflow_state.json');
+    const destStateFile = path.join(destTaskDir, '.workflow_state.json');
+    if (await pathExists(srcStateFile)) {
+        await mkdir(path.dirname(destStateFile), { recursive: true });
+        await copyFile(srcStateFile, destStateFile);
+    }
+}
+/**
+ * After a task reaches `completed`, archive worktree task data to the main repo and
+ * remove the git worktree directory. The task branch is kept for `harvest` merge.
+ */
+export async function cleanupWorktreeAfterTaskCompleted(repoRoot, taskId, opts = {}) {
+    const { mainRepoRoot, worktreePath: inferredPath } = inferMainRepoRoot(repoRoot, taskId);
+    let manifest;
+    try {
+        manifest = await loadHarnessManifest(mainRepoRoot);
+    }
+    catch {
+        manifest = undefined;
+    }
+    const worktreePath = inferredPath ?? resolveWorktreePath(mainRepoRoot, manifest, taskId);
+    if (!(await pathExists(worktreePath))) {
+        return {
+            attempted: false,
+            archived: false,
+            worktreeRemoved: false,
+            mainRepoRoot,
+            message: 'no worktree directory',
+        };
+    }
+    const mainTaskDir = getTaskDir(mainRepoRoot, taskId);
+    let archived = false;
+    let worktreeRemoved = false;
+    try {
+        await archiveTaskDirFromWorktree(mainRepoRoot, worktreePath, taskId);
+        archived = true;
+        await appendWorkflowLog(mainTaskDir, `archived task artifacts/logs from worktree before cleanup (${worktreePath})`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        await appendWorkflowLog(mainTaskDir, `worktree archive before cleanup failed: ${message}`);
+        return {
+            attempted: true,
+            archived: false,
+            worktreeRemoved: false,
+            mainRepoRoot,
+            worktreePath,
+            message,
+        };
+    }
+    try {
+        await removeWorktree(mainRepoRoot, manifest, {
+            taskId,
+            path: worktreePath,
+            // Task dir is archived; remaining .harness (often gitignored) must not block removal.
+            force: true,
+            deleteBranch: opts.deleteBranch === true,
+        });
+        worktreeRemoved = true;
+        await appendWorkflowLog(mainTaskDir, `worktree removed after task completed (${worktreePath})`);
+        try {
+            if (await pathExists(worktreePath)) {
+                await rm(worktreePath, { recursive: true, force: true });
+            }
+        }
+        catch {
+            /* orphan .harness dir after git worktree remove */
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        await appendWorkflowLog(mainTaskDir, `worktree remove after completed failed: ${message}`);
+        return {
+            attempted: true,
+            archived,
+            worktreeRemoved: false,
+            mainRepoRoot,
+            worktreePath,
+            message,
+        };
+    }
+    return {
+        attempted: true,
+        archived,
+        worktreeRemoved,
+        mainRepoRoot,
+        worktreePath,
+    };
+}

package/dist/task/worktree.js

@@ -0,0 +1,171 @@
+import { access, mkdir, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+/**
+ * Resolve the worktree root directory from a harness manifest.
+ * Falls back to `<repoRoot>/.worktrees` when not configured.
+ */
+export function resolveWorktreeRoot(repoRoot, manifest) {
+    const relativePath = manifest?.worktree?.rootRelativePath ?? '.worktrees';
+    return path.resolve(repoRoot, relativePath);
+}
+/**
+ * Resolve the worktree directory path for a given taskId.
+ */
+export function resolveWorktreePath(repoRoot, manifest, taskId) {
+    const root = resolveWorktreeRoot(repoRoot, manifest);
+    return path.join(root, taskId);
+}
+/**
+ * Resolve repoRoot to its real path (resolving symlinks) so that paths match
+ * what `git worktree list --porcelain` returns (e.g. /tmp → /private/tmp on macOS).
+ */
+async function resolveRepoRoot(repoRoot) {
+    try {
+        return await realpath(repoRoot);
+    }
+    catch {
+        return repoRoot;
+    }
+}
+/**
+ * Create a new git worktree for a task.
+ *
+ * @returns The created worktree path, branch name, and base ref.
+ */
+export async function createWorktree(repoRoot, manifest, opts) {
+    const resolvedRoot = await resolveRepoRoot(repoRoot);
+    const worktreePath = resolveWorktreePath(resolvedRoot, manifest, opts.taskId);
+    const branch = opts.branch ?? `task/${opts.taskId}`;
+    const base = opts.base ?? 'HEAD';
+    // Check if worktree path already exists
+    try {
+        await access(worktreePath);
+        throw new Error(`worktree path already exists: ${worktreePath}`);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    // Ensure parent directory exists
+    await mkdir(path.dirname(worktreePath), { recursive: true });
+    // Build git worktree add arguments
+    const addArgs = ['worktree', 'add', worktreePath];
+    // Check if branch already exists; if so, don't pass -b
+    const branchExists = await gitBranchExists(resolvedRoot, branch);
+    if (!branchExists) {
+        addArgs.push('-b', branch);
+    }
+    addArgs.push(base);
+    await runGit(resolvedRoot, addArgs);
+    return { path: worktreePath, branch, base };
+}
+/**
+ * List git worktrees by parsing `git worktree list --porcelain`.
+ */
+export async function listWorktrees(repoRoot) {
+    const resolvedRoot = await resolveRepoRoot(repoRoot);
+    const stdout = await runGit(resolvedRoot, ['worktree', 'list', '--porcelain']);
+    const entries = [];
+    const blocks = stdout.split('\n\n').filter((b) => b.trim().length > 0);
+    for (const block of blocks) {
+        const lines = block.trim().split('\n');
+        let entryPath = '';
+        let branch;
+        let head = '';
+        let bare = false;
+        let locked = false;
+        for (const line of lines) {
+            if (line.startsWith('worktree ')) {
+                entryPath = line.slice('worktree '.length);
+            }
+            else if (line.startsWith('branch ')) {
+                const ref = line.slice('branch '.length);
+                // Convert refs/heads/<name> to <name>
+                branch = ref.replace(/^refs\/heads\//, '');
+            }
+            else if (line.startsWith('HEAD ')) {
+                head = line.slice('HEAD '.length);
+            }
+            else if (line === 'bare') {
+                bare = true;
+            }
+            else if (line === 'locked') {
+                locked = true;
+            }
+        }
+        if (entryPath) {
+            entries.push({ path: path.normalize(entryPath), branch, head, bare, locked });
+        }
+    }
+    return entries.sort((a, b) => a.path.localeCompare(b.path));
+}
+/**
+ * Remove a git worktree.
+ * Either `taskId` or `path` must be provided.
+ */
+export async function removeWorktree(repoRoot, manifest, opts) {
+    const resolvedRoot = await resolveRepoRoot(repoRoot);
+    const worktreePath = opts.path ?? (opts.taskId ? resolveWorktreePath(resolvedRoot, manifest, opts.taskId) : undefined);
+    if (!worktreePath) {
+        throw new Error('removeWorktree requires either taskId or path');
+    }
+    const removeArgs = ['worktree', 'remove'];
+    if (opts.force) {
+        removeArgs.push('--force');
+    }
+    removeArgs.push(worktreePath);
+    await runGit(resolvedRoot, removeArgs);
+    // Optionally delete the branch
+    if (opts.deleteBranch && opts.taskId) {
+        const branch = `task/${opts.taskId}`;
+        try {
+            await runGit(resolvedRoot, ['branch', '-d', branch]);
+        }
+        catch {
+            // Branch may already be deleted or not exist; ignore
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Run a git command and return stdout. Throws on non-zero exit.
+ */
+async function runGit(cwd, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('git', ['-C', cwd, ...args], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        child.stdout?.on('data', (chunk) => stdoutChunks.push(chunk));
+        child.stderr?.on('data', (chunk) => stderrChunks.push(chunk));
+        child.on('error', (err) => {
+            reject(new Error(`git ${args.join(' ')} spawn error: ${err.message}`));
+        });
+        child.on('close', (code) => {
+            const stdout = Buffer.concat(stdoutChunks).toString('utf-8');
+            const stderr = Buffer.concat(stderrChunks).toString('utf-8');
+            if (code !== 0) {
+                reject(new Error(`git ${args.join(' ')} failed (exit ${code}): ${stderr.trim()}`));
+                return;
+            }
+            resolve(stdout);
+        });
+    });
+}
+/**
+ * Check if a branch exists in the local git repository.
+ */
+async function gitBranchExists(cwd, branchName) {
+    try {
+        const stdout = await runGit(cwd, ['branch', '--list', branchName]);
+        return stdout.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/workflows/dag/authoring.js

@@ -0,0 +1,8 @@
+export * from "./authority-surface.js";
+export * from "./init-hybrid.js";
+export * from "./prompt-source.js";
+export * from "./prompt.js";
+export * from "../../executors/shell-presets.js";
+export * from "./skill-instructions.js";
+export * from "./skills.js";
+export * from "./final-verification.js";

package/dist/workflows/dag/authority-surface.js

@@ -0,0 +1,138 @@
+export const AUTHORITY_SURFACE_AUDIT_PROMPT_PATH = "docs/templates/agent-dag-authority-surface-audit.prompt.md";
+export const AUTHORITY_SURFACE_EXPLICIT_MARKERS = [
+    /authority-surface-audit/i,
+    /<!--\s*authority-surface-audit\s*-->/i,
+];
+export const AUTHORITY_SIGNAL_RULES = [
+    {
+        id: "permission-authority",
+        pattern: /权限|permission|authority|完成权|ownership\s+gate/i,
+        message: "task/source mentions permission, authority, or completion ownership",
+    },
+    {
+        id: "state-machine",
+        pattern: /状态机|state\s*machine|workflow\s*state|task\.json\.status|\.workflow_state/i,
+        message: "task/source mentions workflow/task state machines",
+    },
+    {
+        id: "tool-exposure",
+        pattern: /tool\s*exposure|model-facing|工具暴露|工具表|api\s*surface|普通工具表/i,
+        message: "task/source mentions model-facing tools or API surface",
+    },
+    {
+        id: "completion-authority",
+        pattern: /update_goal|complete\s*gate|completion\s*authority|orchestrator.*complete|完成.*gate/i,
+        message: "task/source mentions goal completion authority or orchestrator gates",
+    },
+    {
+        id: "bypass-path",
+        pattern: /bypass\s*path|绕过.*gate|绕过.*verifier|fail\s*closed/i,
+        message: "task/source mentions bypass paths or fail-closed gates",
+    },
+    {
+        id: "orchestrator-internal",
+        pattern: /orchestrator-only|orchestrator\s*owned|internal\s*path|orchestrator\s*only/i,
+        message: "task/source mentions orchestrator-only or internal ownership paths",
+    },
+];
+function collectAuthoritySourceText(sources) {
+    return [
+        sources.taskConfig.title,
+        sources.taskConfig.taskId,
+        ...sources.taskConfig.hardConstraints,
+        sources.requirementMarkdown,
+        sources.constraintMarkdown ?? "",
+    ].join("\n");
+}
+export function hasExplicitAuthoritySurfaceAudit(text, taskConfig) {
+    const corpus = [
+        text,
+        ...(taskConfig?.hardConstraints ?? []),
+    ].join("\n");
+    return AUTHORITY_SURFACE_EXPLICIT_MARKERS.some((pattern) => pattern.test(corpus));
+}
+export function detectAuthoritySurfaceSignals(text) {
+    const signals = [];
+    for (const rule of AUTHORITY_SIGNAL_RULES) {
+        if (rule.pattern.test(text)) {
+            signals.push({ id: rule.id, message: rule.message });
+        }
+    }
+    return signals;
+}
+export function resolveAuthoritySurfaceAudit(sources) {
+    const corpus = collectAuthoritySourceText(sources);
+    const explicit = hasExplicitAuthoritySurfaceAudit(corpus, sources.taskConfig);
+    const signals = detectAuthoritySurfaceSignals(corpus);
+    const reasons = [];
+    if (explicit) {
+        reasons.push("authority-surface-audit explicitly enabled via task source marker or hardConstraint");
+    }
+    for (const signal of signals) {
+        reasons.push(`authority signal: ${signal.id} (${signal.message})`);
+    }
+    const enabled = explicit || signals.length > 0;
+    if (!enabled) {
+        reasons.push("no authority signals or explicit enablement; authority surface audit omitted");
+    }
+    return { enabled, explicit, signals, reasons };
+}
+export function buildAuthoritySurfaceAuditNode(sources) {
+    return {
+        id: "authority-surface-audit-pi",
+        depends_on: ["hard-verify-shell"],
+        role: "verifier",
+        executor: "pi",
+        complexity: "HIGH",
+        writePolicy: "read-only",
+        allowedPaths: sources.taskConfig.allowedPaths.length > 0
+            ? sources.taskConfig.allowedPaths
+            : ["**"],
+        forbiddenPaths: [
+            ".harness/**",
+            ".harness/dag-runs/**",
+            "artifacts/**",
+            ...sources.taskConfig.forbiddenPaths,
+        ],
+        outputContract: "Plain Markdown whose first non-empty line is VERDICT: pass or VERDICT: request-revision; cites code/test/tool-table/API surface evidence for authority questions. No file writes.",
+        subtask_prompt: [
+            "Audit authority surface for state-write ownership, model-facing tools/APIs, orchestrator-only paths, and completion-authority bypass paths.",
+            "First non-empty line must be exactly VERDICT: pass or VERDICT: request-revision.",
+            "Answer who can write state, what is model-facing, whether orchestrator-only paths stay internal, and whether any bypass path exists.",
+            "Cite concrete evidence from code, tests, tool tables, CLI/registry surfaces, or API schemas. Read-only: do not modify files.",
+            `Follow invariants in ${AUTHORITY_SURFACE_AUDIT_PROMPT_PATH}.`,
+        ].join("\n\n"),
+    };
+}
+export function buildAuthoritySurfaceGateNode(sources) {
+    return {
+        id: "authority-surface-gate-shell",
+        depends_on: ["authority-surface-audit-pi"],
+        role: "verifier",
+        executor: "shell",
+        complexity: "LOW",
+        writePolicy: "read-only",
+        allowedPaths: sources.taskConfig.allowedPaths.length > 0
+            ? sources.taskConfig.allowedPaths
+            : ["**"],
+        forbiddenPaths: [
+            ".harness/**",
+            ".harness/dag-runs/**",
+            "artifacts/**",
+            ...sources.taskConfig.forbiddenPaths,
+        ],
+        outputContract: "Deterministic authority surface audit verdict gate: exit 0 only when authority-surface-audit-pi first extracted VERDICT line is pass.",
+        subtask_prompt: "Deterministic gate: block review/closeout unless authority-surface-audit-pi emitted VERDICT: pass.",
+        shell: {
+            commands: [],
+            verdictGate: {
+                fromNodeId: "authority-surface-audit-pi",
+                accept: ["VERDICT: pass"],
+                label: "authority surface audit",
+                lineMode: "first-verdict-line",
+            },
+            cwd: ".",
+            timeoutMs: 60000,
+        },
+    };
+}