@tea-agent/loop-agent 0.22.0 → 0.24.0

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) {

package/dist/commands/doctor.js

@@ -1,32 +1,283 @@
-import { access } from 'node:fs/promises';
-import path from 'node:path';
-import { checkPiAvailability, resolvePiBackend } from '../executors/pi-executor.js';
-import { checkPiSdkAvailability } from '../executors/pi-sdk-executor.js';
-export async function runDoctor(adapter, repoRoot) {
+import os from "node:os";
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { checkPiAvailability, resolvePiBackend } from "../executors/pi-executor.js";
+import { checkPiSdkAvailability } from "../executors/pi-sdk-executor.js";
+import { getContextPolicy, } from "../workflows/dag/context-policy.js";
+import { DEFAULT_SKILLS_BY_ROLE, } from "../workflows/dag/skills.js";
+import { resolveDagSkillInstructions, } from "../workflows/dag/skill-instructions.js";
+const ENTRYPOINT_KEYS = [
+    "readme",
+    "agents",
+    "governanceIndex",
+    "principles",
+    "workflow",
+    "verificationMatrix",
+];
+const CONTEXT_AUDIT_ROLES = ["planner", "supervisor", "closeout"];
+/** Parse `--flag` / `--flag=value` boolean flags from a raw argv token list. */
+export function parseDoctorArgs(args) {
+    let json = false;
+    let context = false;
+    for (const token of args) {
+        if (token === "--json" || token === "--json=true")
+            json = true;
+        else if (token === "--context" || token === "--context=true")
+            context = true;
+        else if (token.startsWith("--context="))
+            context = token.slice("--context=".length) === "true";
+        else if (token.startsWith("--json="))
+            json = token.slice("--json=".length) === "true";
+    }
+    return { json, context };
+}
+function summarize(checks) {
+    let errors = 0;
+    let warnings = 0;
+    let infos = 0;
+    for (const check of checks) {
+        if (check.status === "error")
+            errors += 1;
+        else if (check.status === "warning")
+            warnings += 1;
+        else
+            infos += 1;
+    }
+    return { errors, warnings, infos };
+}
+async function collectManifestChecks(adapter, repoRoot) {
+    const checks = [];
     const manifest = await adapter.loadHarnessManifest(repoRoot);
     const requiredPaths = [];
-    for (const key of ['readme', 'agents', 'governanceIndex', 'principles', 'workflow', 'verificationMatrix']) {
+    const entrypointLabels = [];
+    for (const key of ENTRYPOINT_KEYS) {
         const value = manifest.entrypoints[key];
-        if (value)
+        if (value) {
             requiredPaths.push(value);
+            entrypointLabels.push(`${key}=${value}`);
+        }
     }
     const checkRepoScript = manifest.scripts?.checkRepo;
-    if (checkRepoScript)
+    if (checkRepoScript) {
         requiredPaths.push(checkRepoScript);
-    requiredPaths.push('.harness/prompts/analyze.md');
-    requiredPaths.push('.harness/prompts/plan.md');
+    }
+    requiredPaths.push(".harness/prompts/analyze.md");
+    requiredPaths.push(".harness/prompts/plan.md");
     for (const rel of requiredPaths) {
-        await access(path.join(repoRoot, rel));
+        try {
+            await access(path.join(repoRoot, rel));
+        }
+        catch {
+            checks.push({
+                id: `manifest-path:${rel}`,
+                status: "error",
+                message: `required harness path missing: ${rel}`,
+            });
+        }
     }
-    const pi = checkPiAvailability();
-    if (!pi.ok) {
-        throw new Error(`pi unavailable: ${pi.detail}`);
+    checks.push({
+        id: "manifest-entrypoints",
+        status: "info",
+        message: `harness manifest entrypoints resolved`,
+        detail: { entrypoints: entrypointLabels },
+    });
+    return checks;
+}
+function collectExecutorChecks(piOk, piDetail, backendMode, sdkOk, sdkDetail) {
+    const checks = [];
+    if (!piOk) {
+        checks.push({
+            id: "executor:pi-cli",
+            status: "error",
+            message: `pi unavailable: ${piDetail}`,
+        });
+        return checks;
+    }
+    checks.push({
+        id: "executor:pi-cli",
+        status: "info",
+        message: `pi backend=${backendMode} cli=ok sdk=${sdkOk ? "ok" : "unavailable"}`,
+    });
+    if (backendMode === "sdk-first" && !sdkOk) {
+        checks.push({
+            id: "executor:pi-sdk",
+            status: "warning",
+            message: `CODE_AGENT_PI_BACKEND=sdk-first but pi SDK unavailable (${sdkDetail}); steps will fall back to CLI`,
+        });
     }
+    return checks;
+}
+async function collectContextAudit(repoRoot) {
+    const policyId = "baseline-v1";
+    const policy = getContextPolicy(policyId);
+    const manifest = policy.toManifest();
+    const roles = [];
+    for (const role of CONTEXT_AUDIT_ROLES) {
+        const skillNames = DEFAULT_SKILLS_BY_ROLE[role];
+        const budget = policy.resolveSkillInstructionBudget({
+            role,
+            executor: "pi",
+        });
+        const resolved = await resolveDagSkillInstructions([...skillNames], {
+            cwd: repoRoot,
+            env: {},
+            homeDir: os.homedir(),
+            perSkillMaxChars: budget.perSkillMaxChars,
+            totalMaxChars: budget.totalMaxChars,
+            includeLearnedPatterns: budget.includeLearnedPatterns,
+        });
+        const skills = resolved.map((entry) => toContextAuditSkill(entry));
+        roles.push({ role, skills });
+    }
+    return { policy: manifest, roles };
+}
+function toContextAuditSkill(entry) {
+    return {
+        name: entry.name,
+        resolution: entry.resolution,
+        entryTruncated: Boolean(entry.truncated),
+        ...(entry.references
+            ? {
+                references: entry.references.map((ref) => ({
+                    name: ref.name,
+                    sha256: ref.sha256,
+                    bytes: ref.bytes,
+                    truncated: Boolean(ref.truncated),
+                })),
+            }
+            : {}),
+        ...(entry.unresolvedReferences
+            ? { unresolvedReferences: entry.unresolvedReferences }
+            : {}),
+    };
+}
+function contextAuditToChecks(audit) {
+    const checks = [];
+    for (const roleEntry of audit.roles) {
+        for (const skill of roleEntry.skills) {
+            if (skill.resolution === "missing" || skill.resolution === "error") {
+                checks.push({
+                    id: `context:${roleEntry.role}:${skill.name}:resolution`,
+                    status: "error",
+                    message: `role ${roleEntry.role} skill ${skill.name} did not resolve (${skill.resolution})`,
+                });
+            }
+            if (skill.entryTruncated) {
+                checks.push({
+                    id: `context:${roleEntry.role}:${skill.name}:entry-truncated`,
+                    status: "warning",
+                    message: `role ${roleEntry.role} skill ${skill.name} entry truncated under default budget`,
+                });
+            }
+            for (const ref of skill.references ?? []) {
+                if (ref.truncated) {
+                    checks.push({
+                        id: `context:${roleEntry.role}:${skill.name}:ref:${ref.name}:truncated`,
+                        status: "warning",
+                        message: `role ${roleEntry.role} skill ${skill.name} reference ${ref.name} excerpt truncated under default budget`,
+                    });
+                }
+            }
+            for (const unresolved of skill.unresolvedReferences ?? []) {
+                if (unresolved.reason === "budget") {
+                    checks.push({
+                        id: `context:${roleEntry.role}:${skill.name}:ref:${unresolved.name ?? unresolved.path}:budget`,
+                        status: "error",
+                        message: `role ${roleEntry.role} skill ${skill.name} reference ${unresolved.name ?? unresolved.path} skipped: reason=budget`,
+                    });
+                }
+                else if (unresolved.reason === "missing" ||
+                    unresolved.reason === "read-error" ||
+                    unresolved.reason === "cycle") {
+                    checks.push({
+                        id: `context:${roleEntry.role}:${skill.name}:ref:${unresolved.name ?? unresolved.path}:${unresolved.reason}`,
+                        status: "error",
+                        message: `role ${roleEntry.role} skill ${skill.name} reference ${unresolved.name ?? unresolved.path} unresolved: reason=${unresolved.reason}`,
+                    });
+                }
+            }
+        }
+    }
+    return checks;
+}
+/**
+ * Build the typed DoctorReport without side effects. This is the single fact
+ * source shared by both the human-readable and JSON renderers in runDoctor.
+ */
+export async function buildDoctorReport(adapter, repoRoot, options = {}) {
+    const checks = [];
+    checks.push(...(await collectManifestChecks(adapter, repoRoot)));
+    const pi = checkPiAvailability();
     const backendMode = resolvePiBackend();
     const sdk = await checkPiSdkAvailability(repoRoot);
-    console.log(`doctor: pi backend=${backendMode} cli=${pi.ok ? 'ok' : 'fail'} sdk=${sdk.ok ? 'ok' : 'unavailable'}`);
-    if (backendMode === 'sdk-first' && !sdk.ok) {
-        console.error(`doctor warning: CODE_AGENT_PI_BACKEND=sdk-first but pi SDK unavailable (${sdk.detail}); steps will fall back to CLI`);
+    checks.push(...collectExecutorChecks(pi.ok, pi.detail, backendMode, sdk.ok, sdk.detail));
+    if (options.context) {
+        const audit = await collectContextAudit(repoRoot);
+        checks.push(...contextAuditToChecks(audit));
+        return {
+            schemaVersion: 1,
+            ok: !checks.some((check) => check.status === "error"),
+            command: "doctor",
+            checks,
+            summary: summarize(checks),
+            contextAudit: audit,
+        };
+    }
+    return {
+        schemaVersion: 1,
+        ok: !checks.some((check) => check.status === "error"),
+        command: "doctor",
+        checks,
+        summary: summarize(checks),
+    };
+}
+function renderHumanReport(report) {
+    for (const check of report.checks) {
+        const tag = check.status === "error"
+            ? "ERROR"
+            : check.status === "warning"
+                ? "warn"
+                : "info";
+        const line = check.detail !== undefined
+            ? `doctor [${tag}] ${check.id}: ${check.message}`
+            : `doctor [${tag}] ${check.id}: ${check.message}`;
+        if (check.status === "error") {
+            console.error(line);
+        }
+        else {
+            console.log(line);
+        }
+    }
+    if (report.contextAudit) {
+        console.log(`doctor context: policy=${report.contextAudit.policy.policyId} roles=${report.contextAudit.roles.map((role) => role.role).join(",")}`);
+        for (const role of report.contextAudit.roles) {
+            for (const skill of role.skills) {
+                const refs = (skill.references ?? [])
+                    .map((ref) => `${ref.name}${ref.truncated ? "*" : ""}`)
+                    .join(",");
+                console.log(`  ${role.role}/${skill.name}: resolution=${skill.resolution} entryTruncated=${skill.entryTruncated}${refs ? ` refs=${refs}` : ""}`);
+            }
+        }
+    }
+    console.log(`doctor: ${report.ok ? "ok" : "errors"} (errors=${report.summary.errors} warnings=${report.summary.warnings} infos=${report.summary.infos})`);
+}
+/**
+ * Run the doctor command. Renders a human-readable summary by default, or a
+ * single JSON document when `--json` is present. Both renderers consume the
+ * same typed DoctorReport. Returns the process exit code (1 on any error
+ * finding, 0 otherwise) and sets process.exitCode accordingly.
+ */
+export async function runDoctor(adapter, repoRoot, args = []) {
+    const { json, context } = parseDoctorArgs(args);
+    const report = await buildDoctorReport(adapter, repoRoot, { context });
+    const exitCode = report.ok ? 0 : 1;
+    process.exitCode = exitCode;
+    if (json) {
+        // Machine envelope: stdout must contain only a single JSON document.
+        process.stdout.write(`${JSON.stringify(report)}\n`);
+    }
+    else {
+        renderHumanReport(report);
     }
-    console.log('doctor ok');
+    return exitCode;
 }