@tea-agent/loop-agent 0.21.0 → 0.23.1

package/dist/application/context-usage/skill-resolution-stats.js

@@ -0,0 +1,263 @@
+/**
+ * Read-only skill-resolution / context-usage aggregation over recent DAG runs.
+ *
+ * Terminology: this reports resolution / truncation / unresolved-reference
+ * distribution and correlated node outcomes. It does NOT claim skill "execution"
+ * or model compliance rates — snapshots prove parse+inject only.
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { isDagSkillSnapshotIntegrityError, readSkillSnapshot, } from "../../workflows/dag/skill-snapshot.js";
+const LIFECYCLES = ["active", "paused", "completed"];
+function emptySkillCounts() {
+    return {
+        declared: 0,
+        resolved: 0,
+        missing: 0,
+        error: 0,
+        entryTruncated: 0,
+        referenceTruncated: 0,
+        unresolvedByReason: {},
+    };
+}
+function emptyNodeOutcomes() {
+    return {
+        FINISHED: 0,
+        ERROR: 0,
+        SKIPPED: 0,
+        PENDING: 0,
+        RUNNING: 0,
+        other: 0,
+        failureCategories: {},
+    };
+}
+function bumpReason(map, reason) {
+    map[reason] = (map[reason] ?? 0) + 1;
+}
+function ensureSkill(skills, name) {
+    if (!skills[name])
+        skills[name] = emptySkillCounts();
+    return skills[name];
+}
+export function parseStatsContextArgs(args) {
+    let last = 50;
+    let json = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const token = args[i];
+        if (token === "--json" || token === "--json=true") {
+            json = true;
+            continue;
+        }
+        if (token.startsWith("--json=")) {
+            json = token.slice("--json=".length) === "true";
+            continue;
+        }
+        if (token === "--last") {
+            const raw = args[i + 1];
+            if (!raw || raw.startsWith("-")) {
+                throw new Error("usage: stats context [--last <n>] [--json]");
+            }
+            const parsed = Number.parseInt(raw, 10);
+            if (!Number.isFinite(parsed) || parsed < 1) {
+                throw new Error(`--last must be a positive integer, got: ${raw}`);
+            }
+            last = parsed;
+            i += 1;
+            continue;
+        }
+        if (token.startsWith("--last=")) {
+            const raw = token.slice("--last=".length);
+            const parsed = Number.parseInt(raw, 10);
+            if (!Number.isFinite(parsed) || parsed < 1) {
+                throw new Error(`--last must be a positive integer, got: ${raw}`);
+            }
+            last = parsed;
+            continue;
+        }
+        throw new Error(`unknown argument: ${token}\nusage: stats context [--last <n>] [--json]`);
+    }
+    return { last, json };
+}
+async function listRecentDagRuns(repoRoot, last) {
+    const matches = [];
+    for (const lifecycle of LIFECYCLES) {
+        const lifecycleDir = path.join(repoRoot, ".harness", "dag-runs", lifecycle);
+        let entries = [];
+        try {
+            entries = await readdir(lifecycleDir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            if (!name || name === ".gitkeep")
+                continue;
+            const runDir = path.join(lifecycleDir, name);
+            let st;
+            try {
+                st = await stat(runDir);
+            }
+            catch {
+                continue;
+            }
+            if (!st.isDirectory())
+                continue;
+            matches.push({
+                runId: name,
+                lifecycle,
+                runDir,
+                mtimeMs: st.mtimeMs,
+            });
+        }
+    }
+    matches.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return matches.slice(0, last);
+}
+async function readOptionalJson(filePath) {
+    try {
+        return JSON.parse(await readFile(filePath, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function ingestSnapshot(skills, snapshot) {
+    for (const profile of snapshot.profiles) {
+        for (const skillName of profile.skills) {
+            ensureSkill(skills, skillName).declared += 1;
+        }
+        for (const instruction of profile.resolvedInstructions) {
+            const row = ensureSkill(skills, instruction.name);
+            if (instruction.resolution === "resolved")
+                row.resolved += 1;
+            else if (instruction.resolution === "missing")
+                row.missing += 1;
+            else if (instruction.resolution === "error")
+                row.error += 1;
+            if (instruction.truncated)
+                row.entryTruncated += 1;
+            for (const ref of instruction.references ?? []) {
+                if (ref.truncated)
+                    row.referenceTruncated += 1;
+            }
+            for (const unresolved of instruction.unresolvedReferences ?? []) {
+                bumpReason(row.unresolvedByReason, unresolved.reason);
+            }
+        }
+    }
+}
+function ingestNodeOutcomes(outcomes, state) {
+    for (const node of Object.values(state.nodes ?? {})) {
+        const status = node.status;
+        if (status === "FINISHED")
+            outcomes.FINISHED += 1;
+        else if (status === "ERROR")
+            outcomes.ERROR += 1;
+        else if (status === "SKIPPED")
+            outcomes.SKIPPED += 1;
+        else if (status === "PENDING")
+            outcomes.PENDING += 1;
+        else if (status === "RUNNING")
+            outcomes.RUNNING += 1;
+        else
+            outcomes.other += 1;
+        if (node.failureCategory) {
+            bumpReason(outcomes.failureCategories, node.failureCategory);
+        }
+    }
+}
+/**
+ * Pure-ish builder: filesystem reads only; never writes `.harness/**`.
+ */
+export async function buildContextUsageReport(repoRoot, options = {}) {
+    const last = options.last ?? 50;
+    const candidates = await listRecentDagRuns(repoRoot, last);
+    const skills = {};
+    const nodeOutcomes = emptyNodeOutcomes();
+    const byLifecycle = {
+        active: 0,
+        paused: 0,
+        completed: 0,
+    };
+    const findings = [];
+    const notes = [
+        "skill-resolution telemetry only; does not claim model compliance or skill execution rates",
+        "corrupted snapshots are reported as findings and are not silently skipped",
+    ];
+    for (const candidate of candidates) {
+        byLifecycle[candidate.lifecycle] += 1;
+        const state = await readOptionalJson(path.join(candidate.runDir, "state.json"));
+        const runJson = await readOptionalJson(path.join(candidate.runDir, "run.json"));
+        const finding = {
+            runId: candidate.runId,
+            lifecycle: candidate.lifecycle,
+            mtimeMs: candidate.mtimeMs,
+            runStatus: state?.status,
+            contextPolicyId: runJson?.defaults?.contextPolicyId,
+            snapshot: "missing",
+        };
+        if (state)
+            ingestNodeOutcomes(nodeOutcomes, state);
+        const ref = state?.skillSnapshotRef;
+        if (!ref) {
+            findings.push(finding);
+            continue;
+        }
+        try {
+            const snapshot = await readSkillSnapshot(candidate.runDir, ref);
+            finding.snapshot = "ok";
+            ingestSnapshot(skills, snapshot);
+        }
+        catch (error) {
+            finding.snapshot = "corrupted";
+            finding.snapshotError = isDagSkillSnapshotIntegrityError(error)
+                ? error.message
+                : error instanceof Error
+                    ? error.message
+                    : String(error);
+        }
+        findings.push(finding);
+    }
+    const corrupted = findings.filter((f) => f.snapshot === "corrupted").length;
+    return {
+        schemaVersion: 1,
+        command: "stats.context",
+        ok: corrupted === 0,
+        scannedRuns: candidates.length,
+        requestedLast: last,
+        byLifecycle,
+        skills,
+        nodeOutcomes,
+        findings,
+        notes,
+    };
+}
+export function formatContextUsageReportHuman(report) {
+    const lines = [];
+    lines.push(`stats context (last ${report.requestedLast}, scanned ${report.scannedRuns})`);
+    lines.push(`lifecycle: active=${report.byLifecycle.active} paused=${report.byLifecycle.paused} completed=${report.byLifecycle.completed}`);
+    lines.push(`nodes: FINISHED=${report.nodeOutcomes.FINISHED} ERROR=${report.nodeOutcomes.ERROR} SKIPPED=${report.nodeOutcomes.SKIPPED} PENDING=${report.nodeOutcomes.PENDING} RUNNING=${report.nodeOutcomes.RUNNING}`);
+    const skillNames = Object.keys(report.skills).sort();
+    if (skillNames.length === 0) {
+        lines.push("skills: (none resolved in scanned snapshots)");
+    }
+    else {
+        lines.push("skills:");
+        for (const name of skillNames) {
+            const s = report.skills[name];
+            const budget = s.unresolvedByReason.budget ?? 0;
+            lines.push(`  ${name}: declared=${s.declared} resolved=${s.resolved} missing=${s.missing} error=${s.error} entryTrunc=${s.entryTruncated} refTrunc=${s.referenceTruncated} budgetSkip=${budget}`);
+        }
+    }
+    const corrupted = report.findings.filter((f) => f.snapshot === "corrupted");
+    if (corrupted.length > 0) {
+        lines.push(`corrupted snapshots: ${corrupted.length}`);
+        for (const finding of corrupted.slice(0, 5)) {
+            lines.push(`  ${finding.lifecycle}/${finding.runId}: ${finding.snapshotError ?? "unknown"}`);
+        }
+    }
+    for (const note of report.notes) {
+        lines.push(`note: ${note}`);
+    }
+    return lines.join("\n");
+}

package/dist/application/dag/generate-task-dag.js

@@ -68,6 +68,15 @@ function buildNextSteps(taskId, outputPath, cwd) {
         `loop-agent dag run-task ${taskId} --execute --cwd ${cwd}`,
     ];
 }
+function buildBasicValidationLevel(outputPath) {
+    return {
+        level: "basic",
+        strictGovernance: false,
+        strictGovernanceValidationRequiredSeparately: true,
+        standaloneStrictGovernanceCommand: `loop-agent dag validate --dag ${outputPath} --strict-models --strict-governance`,
+        note: "Internal generation validation is basic only; standalone strict governance validation must be confirmed separately.",
+    };
+}
 function isBroadWriteSetEntryForPacket(entry) {
     const normalized = entry.trim().replace(/\\/g, "/").replace(/^\.\//, "");
     if (!normalized || normalized === "." || normalized === "./")
@@ -168,6 +177,7 @@ async function buildReviewPacket(input) {
                 ? (task.decisionGate.mode ?? "record-only")
                 : "disabled",
         })),
+        validation: buildBasicValidationLevel(input.dagPath),
         expectedVerification: shellVerification.flatMap((entry) => entry.commands),
     };
 }
@@ -281,10 +291,12 @@ export async function generateTaskDagUseCase(input) {
         profileRouting,
         governanceProfile,
     });
+    const validation = buildBasicValidationLevel(outputPath);
+    const message = "DAG draft created with basic validation; standalone strict governance validation still requires separate confirmation.";
     if (!shouldRunExecution(parsed)) {
         return {
-            mode: "generate+validate",
-            message: "DAG draft created",
+            mode: "generate+basic-validate",
+            message,
             ok: true,
             taskId: initResult.taskId,
             outputPath,
@@ -296,6 +308,7 @@ export async function generateTaskDagUseCase(input) {
             governanceProfile,
             profileRouting,
             reviewPacket,
+            validation,
             warnings: validateSummary.warnings,
             next: buildNextSteps(parsed.taskId, outputPath, parsed.cwd),
         };
@@ -327,7 +340,7 @@ export async function generateTaskDagUseCase(input) {
     });
     return {
         mode: resolveExecutionMode(parsed),
-        message: "DAG draft created",
+        message,
         ok: true,
         taskId: initResult.taskId,
         outputPath,
@@ -338,6 +351,7 @@ export async function generateTaskDagUseCase(input) {
         governanceProfile,
         profileRouting,
         reviewPacket,
+        validation,
         warnings: validateSummary.warnings,
         run: runSummary,
     };

package/dist/cli/command-definitions.js

@@ -184,9 +184,9 @@ export const COMMAND_DEFINITIONS = [
         adapter: "required",
         tier: "operator",
         intent: "Check local loop-agent runtime health.",
-        usage: "doctor",
-        handler: async ({ adapter, repoRoot }) => {
-            await runDoctor(adapter, repoRoot);
+        usage: "doctor [--json] [--context]",
+        handler: async ({ adapter, repoRoot, rest }) => {
+            await runDoctor(adapter, repoRoot, rest.filter((arg) => Boolean(arg)));
         },
     },
     {
@@ -345,10 +345,11 @@ export const COMMAND_DEFINITIONS = [
         name: "stats",
         adapter: "required",
         tier: "operator",
-        intent: "Inspect historical step duration statistics.",
-        usage: "stats",
-        handler: async ({ repoRoot }) => {
-            await runStats(repoRoot);
+        intent: "Inspect historical step duration statistics, or skill-resolution context usage.",
+        usage: "stats | stats context [--last <n>] [--json]",
+        subcommands: ["context"],
+        handler: async ({ repoRoot, subcommand, rest }) => {
+            await runStats(repoRoot, [subcommand, ...rest].filter((arg) => Boolean(arg)));
         },
     },
     {

package/dist/cli/program.js

@@ -92,25 +92,27 @@ function commandChain(command) {
     }
     return names;
 }
-async function resolveDispatchContext(command, defaultRepoRoot) {
-    const options = collectGlobalOptions(command);
-    const repoRoot = path.resolve(options.repoRoot ?? defaultRepoRoot);
+async function dispatchRegisteredCommand(commandObject, defaultRepoRoot, rawArgs) {
+    const chain = commandChain(commandObject);
+    const command = chain[0] ?? "";
+    const [subcommand, ...rest] = chain.length <= 1 ? rawArgs : [chain[1], ...chain.slice(2), ...rawArgs];
+    const options = collectGlobalOptions(commandObject);
+    const quiet = (command === "doctor" &&
+        [...rest, ...rawArgs].some((token) => token === "--json")) ||
+        (command === "stats" &&
+            subcommand === "context" &&
+            [...rest, ...rawArgs].some((token) => token === "--json"));
+    const repoRoot = resolveRepoRootOnly(commandObject, defaultRepoRoot, {
+        quiet,
+    });
     const adapter = await resolveAdapter(repoRoot, options.adapter);
-    if (options.adapter)
+    if (options.adapter && !quiet)
         console.log(`[loop-agent] adapter: ${adapter.name}`);
-    if (options.repoRoot)
-        console.log(`[loop-agent] repo root: ${repoRoot}`);
-    return {
+    const ctx = {
         adapter,
         repoRoot,
         explicitWorktree: options.worktree,
     };
-}
-async function dispatchRegisteredCommand(commandObject, defaultRepoRoot, rawArgs) {
-    const chain = commandChain(commandObject);
-    const command = chain[0] ?? "";
-    const [subcommand, ...rest] = chain.length <= 1 ? rawArgs : [chain[1], ...chain.slice(2), ...rawArgs];
-    const ctx = await resolveDispatchContext(commandObject, defaultRepoRoot);
     await runCommanderAction(ctx, command, subcommand, rest);
 }
 async function runCommanderAction(ctx, command, subcommand, rest) {
@@ -119,7 +121,7 @@ async function runCommanderAction(ctx, command, subcommand, rest) {
             await runInspect(ctx.adapter, ctx.repoRoot);
             return;
         case "doctor":
-            await runDoctor(ctx.adapter, ctx.repoRoot);
+            await runDoctor(ctx.adapter, ctx.repoRoot, compactArgs([subcommand, ...rest]));
             return;
         case "docs":
             if (subcommand === "audit") {
@@ -184,7 +186,7 @@ async function runCommanderAction(ctx, command, subcommand, rest) {
             await runCloseout(ctx.repoRoot, compactArgs([subcommand, ...rest]));
             return;
         case "stats":
-            await runStats(ctx.repoRoot);
+            await runStats(ctx.repoRoot, compactArgs([subcommand, ...rest]));
             return;
         case "plan":
             if (subcommand === "list" || subcommand === undefined) {