akm-cli 0.7.5 → 0.8.0-rc.3

package/dist/output/shapes.js

@@ -6,6 +6,70 @@
  * `Record<string, unknown>` shapes, which makes them trivial to unit test.
  */
 const NORMAL_DESCRIPTION_LIMIT = 250;
+const PASSTHROUGH_COMMANDS = new Set([
+    "add",
+    "agent-result",
+    "clone",
+    "config",
+    "consolidate",
+    "curate",
+    "disable",
+    "enable",
+    "feedback",
+    "graph-entities",
+    "graph-export",
+    "graph-related",
+    "graph-relations",
+    "graph-summary",
+    "health",
+    "import",
+    "improve",
+    "index",
+    "info",
+    "init",
+    "lint",
+    "list",
+    "registry-add",
+    "registry-build-index",
+    "registry-list",
+    "registry-remove",
+    "remember",
+    "remove",
+    "save",
+    "setup",
+    "tasks-add",
+    "tasks-disable",
+    "tasks-doctor",
+    "tasks-enable",
+    "tasks-history",
+    "tasks-list",
+    "tasks-remove",
+    "tasks-run",
+    "tasks-show",
+    "tasks-sync",
+    "update",
+    "upgrade",
+    "vault-create",
+    "vault-set",
+    "vault-unset",
+    "wiki-create",
+    "wiki-ingest",
+    "wiki-lint",
+    "wiki-list",
+    "wiki-pages",
+    "wiki-register",
+    "wiki-remove",
+    "wiki-show",
+    "wiki-stash",
+    "workflow-complete",
+    "workflow-create",
+    "workflow-list",
+    "workflow-next",
+    "workflow-resume",
+    "workflow-start",
+    "workflow-status",
+    "workflow-validate",
+]);
 export function shapeForCommand(command, result, detail, forAgent = false) {
     switch (command) {
         case "search":
@@ -45,66 +109,31 @@ export function shapeForCommand(command, result, detail, forAgent = false) {
         case "reflect":
         case "propose":
             return shapeProposalProducerOutput(result, detail);
-        // Output shape registration for `akm distill <ref>` (#228). The shape is
-        // simple — outcome + ids + optional payload — so `brief` strips the full
-        // proposal blob, `normal` keeps the headline fields, and `full` projects
-        // everything for downstream automation.
         case "distill":
             return shapeDistillOutput(result, detail);
-        // Identity-passthrough commands — registered here so the registry stays
-        // exhaustive (v1 spec §9). Each result object is already shaped at the
-        // command boundary; the registry just confirms there's no surprise
-        // command name slipping through.
-        case "add":
-        case "clone":
-        case "config":
-        case "curate":
-        case "disable":
-        case "enable":
-        case "feedback":
-        case "import":
-        case "index":
-        case "info":
-        case "init":
-        case "list":
-        case "registry-add":
-        case "registry-build-index":
-        case "registry-list":
-        case "registry-remove":
-        case "remember":
-        case "remove":
-        case "save":
-        case "update":
-        case "upgrade":
-        case "vault-create":
-        case "vault-list":
-        case "vault-set":
-        case "vault-unset":
-        case "wiki-create":
-        case "wiki-ingest":
-        case "wiki-lint":
-        case "wiki-list":
-        case "wiki-pages":
-        case "wiki-register":
-        case "wiki-remove":
-        case "wiki-show":
-        case "wiki-stash":
-        case "workflow-complete":
-        case "workflow-create":
-        case "workflow-list":
-        case "workflow-next":
-        case "workflow-resume":
-        case "workflow-start":
-        case "workflow-status":
-        case "workflow-validate":
-            return result;
+        case "vault-list": {
+            const r = result;
+            const vaults = Array.isArray(r.vaults) ? r.vaults : [];
+            return {
+                ...r,
+                vaults: vaults.map((v) => {
+                    const { path: _path, ...rest } = v;
+                    return rest;
+                }),
+            };
+        }
         default:
-            // v1 spec §9 (output-shape registry exhaustive): no silent JSON.stringify
-            // fallback. A missing case here is a registration bug — fail loudly so
-            // the caller (or its tests) sees the missing command name.
+            // v1 spec §9 (output-shape registry exhaustive): identity-passthrough
+            // commands are listed in PASSTHROUGH_COMMANDS; anything not in that set
+            // is a registration bug — fail loudly.
+            if (PASSTHROUGH_COMMANDS.has(command))
+                return result;
             throw new Error(`output shape not registered for command: ${command}`);
     }
 }
+function maybeAddSchema(base, detail, version) {
+    return detail === "full" ? { schemaVersion: version ?? 1, ...base } : base;
+}
 /**
  * Shape the result of `akm reflect` / `akm propose`. On success we surface
  * the queued proposal entry (using the standard proposal-entry shaper so
@@ -141,10 +170,7 @@ export function shapeProposalProducerOutput(result, detail) {
         ...(typeof result.durationMs === "number" ? { durationMs: result.durationMs } : {}),
         proposal: shapeProposalEntry(proposal, detail === "brief" ? "normal" : detail),
     };
-    if (detail === "full") {
-        return { schemaVersion: result.schemaVersion ?? 1, ...base };
-    }
-    return base;
+    return maybeAddSchema(base, detail, result.schemaVersion);
 }
 export function shapeProposalEntry(entry, detail) {
     if (detail === "brief") {
@@ -173,10 +199,7 @@ export function shapeProposalListOutput(result, detail) {
         totalCount: result.totalCount ?? shaped.length,
         proposals: shaped,
     };
-    if (detail === "full") {
-        return { schemaVersion: result.schemaVersion ?? 1, ...base };
-    }
-    return base;
+    return maybeAddSchema(base, detail, result.schemaVersion);
 }
 export function shapeProposalShowOutput(result, detail) {
     const proposal = result.proposal ?? {};
@@ -185,10 +208,7 @@ export function shapeProposalShowOutput(result, detail) {
         proposal: shapeProposalEntry(proposal, detail === "brief" ? "normal" : detail),
         ...(validation ? { validation } : {}),
     };
-    if (detail === "full") {
-        return { schemaVersion: result.schemaVersion ?? 1, ...base };
-    }
-    return base;
+    return maybeAddSchema(base, detail, result.schemaVersion);
 }
 export function shapeProposalAcceptOutput(result, detail) {
     const proposal = result.proposal ?? {};
@@ -199,10 +219,7 @@ export function shapeProposalAcceptOutput(result, detail) {
         assetPath: result.assetPath,
         proposal: shapeProposalEntry(proposal, detail === "brief" ? "normal" : detail),
     };
-    if (detail === "full") {
-        return { schemaVersion: result.schemaVersion ?? 1, ...base };
-    }
-    return base;
+    return maybeAddSchema(base, detail, result.schemaVersion);
 }
 export function shapeProposalRejectOutput(result, detail) {
     const proposal = result.proposal ?? {};
@@ -213,10 +230,7 @@ export function shapeProposalRejectOutput(result, detail) {
         ...(result.reason !== undefined ? { reason: result.reason } : {}),
         proposal: shapeProposalEntry(proposal, detail === "brief" ? "normal" : detail),
     };
-    if (detail === "full") {
-        return { schemaVersion: result.schemaVersion ?? 1, ...base };
-    }
-    return base;
+    return maybeAddSchema(base, detail, result.schemaVersion);
 }
 export function shapeDistillOutput(result, detail) {
     const proposal = result.proposal;
@@ -233,10 +247,7 @@ export function shapeDistillOutput(result, detail) {
         ...(Array.isArray(result.findings) && result.findings.length > 0 ? { findings: result.findings } : {}),
         ...(proposal ? { proposal: shapeProposalEntry(proposal, detail === "summary" ? "normal" : detail) } : {}),
     };
-    if (detail === "full") {
-        return { schemaVersion: result.schemaVersion ?? 1, ...base };
-    }
-    return base;
+    return maybeAddSchema(base, detail, result.schemaVersion);
 }
 export function shapeProposalDiffOutput(result, detail) {
     const base = {
@@ -246,10 +257,7 @@ export function shapeProposalDiffOutput(result, detail) {
         unified: result.unified,
         ...(result.targetPath !== undefined ? { targetPath: result.targetPath } : {}),
     };
-    if (detail === "full") {
-        return { schemaVersion: result.schemaVersion ?? 1, ...base };
-    }
-    return base;
+    return maybeAddSchema(base, detail, result.schemaVersion);
 }
 export function shapeEventsOutput(result, detail) {
     const events = Array.isArray(result.events) ? result.events : [];
@@ -268,16 +276,10 @@ export function shapeEventsOutput(result, detail) {
     if (typeof result.reason === "string") {
         base.reason = result.reason;
     }
-    if (detail === "full") {
-        return { schemaVersion: result.schemaVersion ?? 1, ...base };
-    }
-    return base;
+    return maybeAddSchema(base, detail, result.schemaVersion);
 }
 export function shapeEventEntry(entry, detail) {
-    if (detail === "brief") {
-        return pickFields(entry, ["eventType", "ref", "ts"]);
-    }
-    if (detail === "normal" || detail === "summary") {
+    if (detail === "brief" || detail === "normal" || detail === "summary") {
         return pickFields(entry, ["eventType", "ref", "ts"]);
     }
     // full / agent: project everything the reader emits.
@@ -462,6 +464,7 @@ export function shapeShowOutput(result, detail, forAgent = false) {
             "steps",
             "keys",
             "comments",
+            "related",
         ]);
     }
     if (detail === "summary") {
@@ -477,9 +480,10 @@ export function shapeShowOutput(result, detail, forAgent = false) {
             "origin",
             "keys",
             "comments",
+            "related",
         ]);
     }
-    const base = pickFields(result, [
+    const baseFields = [
         "type",
         "name",
         "origin",
@@ -502,11 +506,15 @@ export function shapeShowOutput(result, detail, forAgent = false) {
         "activeRun",
         "keys",
         "comments",
+        "related",
         // path and editable are always projected so JSON consumers can locate and
         // edit the asset without needing --detail full (QA #7).
-        "path",
+        // Exception: vault assets omit path to avoid leaking absolute disk paths
+        // into structured JSON output (security fix M3).
+        ...(result.type === "vault" ? [] : ["path"]),
         "editable",
-    ]);
+    ];
+    const base = pickFields(result, baseFields);
     if (detail !== "full") {
         return base;
     }

package/dist/output/text.js

@@ -38,6 +38,13 @@ export function formatPlain(command, result, detail) {
         case "index": {
             const indexResult = result;
             let out = `Indexed ${indexResult.totalEntries ?? 0} entries from ${indexResult.directoriesScanned ?? 0} directories (mode: ${indexResult.mode ?? "unknown"})`;
+            const graphQuality = indexResult.graphQuality;
+            if (graphQuality) {
+                const coverage = typeof graphQuality.extractionCoverage === "number"
+                    ? `${Math.round(graphQuality.extractionCoverage * 100)}%`
+                    : "n/a";
+                out += `\nGraph quality: entities ${graphQuality.entityCount ?? 0}, relations ${graphQuality.relationCount ?? 0}, coverage ${coverage}, density ${graphQuality.density ?? 0}`;
+            }
             const warnings = indexResult.warnings;
             if (Array.isArray(warnings) && warnings.length > 0) {
                 out += `\nWarnings (${warnings.length}):`;
@@ -221,6 +228,31 @@ export function formatPlain(command, result, detail) {
         case "distill": {
             return formatDistillPlain(r);
         }
+        case "graph-summary":
+            return formatGraphSummaryPlain(r);
+        case "graph-entities":
+            return formatGraphEntitiesPlain(r);
+        case "graph-relations":
+            return formatGraphRelationsPlain(r);
+        case "graph-related":
+            return formatGraphRelatedPlain(r);
+        case "graph-export":
+            return formatGraphExportPlain(r);
+        case "improve": {
+            return formatImprovePlain(r);
+        }
+        case "consolidate": {
+            return formatConsolidatePlain(r);
+        }
+        // Output shape registration for `akm agent <profile>` (#agent-dispatch).
+        // In interactive mode stdout/stderr are empty (they went to the TTY), so
+        // we print only the profile name and exit status. In captured mode we
+        // emit stdout first, then stderr, then the exit code summary.
+        case "agent-result": {
+            return formatAgentResultPlain(r);
+        }
+        case "health":
+            return formatHealthPlain(r);
         case "info":
             return formatInfoPlain(r);
         case "config":
@@ -249,7 +281,7 @@ export function formatPlain(command, result, detail) {
         case "vault-list":
             return formatVaultListPlain(r);
         case "vault-create":
-            return `Created vault ${String(r.ref ?? "?")} at ${String(r.path ?? "?")}`;
+            return `Created vault ${String(r.ref ?? "?")}`;
         case "vault-set":
             return `Set ${String(r.key ?? "?")} in ${String(r.ref ?? "?")} (value not displayed)`;
         case "vault-unset": {
@@ -299,6 +331,50 @@ export function formatInfoPlain(r) {
         return JSON.stringify(r, null, 2);
     return lines.join("\n");
 }
+export function formatHealthPlain(r) {
+    const lines = [];
+    lines.push(`health: ${String(r.status ?? "unknown")}`);
+    if (typeof r.since === "string")
+        lines.push(`since: ${r.since}`);
+    const metrics = typeof r.metrics === "object" && r.metrics !== null ? r.metrics : undefined;
+    if (metrics) {
+        lines.push("metrics:");
+        lines.push(`  taskFailRate: ${String(metrics.taskFailRate ?? 0)}`);
+        lines.push(`  agentFailureRate: ${String(metrics.agentFailureRate ?? 0)}`);
+        lines.push(`  stuckActiveRuns: ${String(metrics.stuckActiveRuns ?? 0)}`);
+        lines.push(`  logBackingRate: ${String(metrics.logBackingRate ?? 0)}`);
+        lines.push(`  probeRoundTripMs: ${String(metrics.probeRoundTripMs ?? "null")}`);
+    }
+    const improve = typeof r.improve === "object" && r.improve !== null ? r.improve : undefined;
+    if (improve) {
+        const actions = typeof improve.actions === "object" && improve.actions !== null
+            ? improve.actions
+            : {};
+        lines.push("improve:");
+        lines.push(`  invoked: ${String(improve.invoked ?? 0)}`);
+        lines.push(`  completed: ${String(improve.completed ?? 0)}`);
+        lines.push(`  skipped: ${String(improve.skipped ?? 0)}`);
+        lines.push(`  plannedRefs: ${String(improve.plannedRefs ?? 0)}`);
+        lines.push(`  actions: reflect=${String(actions.reflect ?? 0)} distill=${String(actions.distill ?? 0)} distillSkipped=${String(actions.distillSkipped ?? 0)} memoryPrune=${String(actions.memoryPrune ?? 0)} memoryInference=${String(actions.memoryInference ?? 0)} graphExtraction=${String(actions.graphExtraction ?? 0)} error=${String(actions.error ?? 0)}`);
+        lines.push(`  coverageGapCount: ${String(improve.coverageGapCount ?? 0)}`);
+        lines.push(`  executionLogCandidateCount: ${String(improve.executionLogCandidateCount ?? 0)}`);
+        lines.push(`  deadUrlCount: ${String(improve.deadUrlCount ?? 0)}`);
+    }
+    const sections = [
+        ["hardChecks", r.hardChecks],
+        ["advisories", r.advisories],
+    ];
+    for (const [label, value] of sections) {
+        const checks = Array.isArray(value) ? value : [];
+        if (checks.length === 0)
+            continue;
+        lines.push(`${label}:`);
+        for (const check of checks) {
+            lines.push(`  - [${String(check.status ?? "unknown")}] ${String(check.name ?? "check")}: ${String(check.message ?? "")}`);
+        }
+    }
+    return lines.join("\n");
+}
 export function formatConfigPlain(r) {
     // Recursive flattener: prints `key=value` lines, and nested objects as
     // `parent.child=value`. Arrays render as JSON for compactness.
@@ -440,6 +516,57 @@ export function formatWorkflowValidatePlain(r) {
     const stepCount = typeof r.stepCount === "number" ? r.stepCount : 0;
     return `workflow validate: ok — ${title || pathValue} (${stepCount} step(s))`;
 }
+export function formatGraphSummaryPlain(r) {
+    const lines = [
+        `Graph: ${String(r.graphPath ?? "?")}`,
+        `Generated: ${String(r.generatedAt ?? "?")}`,
+        `Files: ${String(r.fileCount ?? 0)}  Entities: ${String(r.entityCount ?? 0)}  Relations: ${String(r.relationCount ?? 0)}`,
+    ];
+    const quality = r.quality;
+    if (quality) {
+        const coverage = typeof quality.extractionCoverage === "number" ? `${Math.round(quality.extractionCoverage * 100)}%` : "n/a";
+        lines.push(`Coverage: ${coverage}  Density: ${String(quality.density ?? 0)}`);
+    }
+    return lines.join("\n");
+}
+export function formatGraphEntitiesPlain(r) {
+    const entities = Array.isArray(r.entities) ? r.entities : [];
+    if (entities.length === 0)
+        return "No entities found in graph.";
+    const lines = [`Entities (${String(r.total ?? entities.length)} total):`];
+    for (const entity of entities) {
+        lines.push(`- ${String(entity.name ?? "?")} (${String(entity.fileCount ?? 0)} files)`);
+    }
+    return lines.join("\n");
+}
+export function formatGraphRelationsPlain(r) {
+    const relations = Array.isArray(r.relations) ? r.relations : [];
+    if (relations.length === 0)
+        return "No relations found in graph.";
+    const lines = [`Relations (${String(r.total ?? relations.length)} total):`];
+    for (const relation of relations) {
+        const type = relation.type ? ` [${String(relation.type)}]` : "";
+        lines.push(`- ${String(relation.from ?? "?")} -> ${String(relation.to ?? "?")}${type} x${String(relation.count ?? 0)}`);
+    }
+    return lines.join("\n");
+}
+export function formatGraphRelatedPlain(r) {
+    const related = Array.isArray(r.related) ? r.related : [];
+    if (related.length === 0)
+        return String(r.tip ?? "No related graph neighbors were found.");
+    const lines = [`Related (${String(r.total ?? related.length)} total) for ${String(r.ref ?? "?")}:`];
+    for (const hit of related) {
+        const shared = Array.isArray(hit.sharedEntities) ? hit.sharedEntities.map(String).join(", ") : "";
+        lines.push(`- ${String(hit.type ?? "?")}: ${formatRelatedLabel(hit)}`);
+        if (shared)
+            lines.push(`  shared: ${shared}`);
+        lines.push(`  relationCount: ${String(hit.relationCount ?? 0)}`);
+    }
+    return lines.join("\n");
+}
+export function formatGraphExportPlain(r) {
+    return `Exported graph (${String(r.format ?? "json")}, ${String(r.bytes ?? 0)} bytes) to ${String(r.outPath ?? "?")}`;
+}
 export function formatProposalProducerPlain(command, r) {
     if (r.ok === false) {
         const reason = String(r.reason ?? "unknown");
@@ -464,7 +591,7 @@ export function formatProposalListPlain(r) {
     const proposals = Array.isArray(r.proposals) ? r.proposals : [];
     const total = typeof r.totalCount === "number" ? r.totalCount : proposals.length;
     if (proposals.length === 0) {
-        return `${total} proposal(s).\nNo proposals.\nGenerate one with \`akm reflect <ref>\`, \`akm propose <type> <name> --task ...\`, or \`akm distill <ref>\`.`;
+        return `${total} proposal(s).\nNo proposals.\nGenerate one with \`akm improve\`, \`akm propose <type> <name> --task ...\`, or \`akm improve <ref>\`.`;
     }
     const lines = [`${total} proposal(s)`, ""];
     for (const p of proposals) {
@@ -529,7 +656,7 @@ export function formatDistillPlain(r) {
     const lessonRef = String(r.lessonRef ?? "?");
     if (outcome === "queued") {
         const id = String(r.proposalId ?? "?");
-        return `Distilled ${inputRef} → proposal ${id} (${lessonRef}). Run \`akm proposal show ${id}\` to review.`;
+        return `Distilled ${inputRef} → proposal ${id} (${lessonRef}). Run \`akm show proposal ${id}\` to review.`;
     }
     if (outcome === "validation_failed") {
         const findings = Array.isArray(r.findings) ? r.findings : [];
@@ -543,6 +670,50 @@ export function formatDistillPlain(r) {
     const message = typeof r.message === "string" ? r.message : "feature disabled or LLM unavailable";
     return `Distill skipped for ${inputRef}: ${message}`;
 }
+export function formatConsolidatePlain(r) {
+    const processed = typeof r.processed === "number" ? r.processed : 0;
+    const merged = typeof r.merged === "number" ? r.merged : 0;
+    const deleted = typeof r.deleted === "number" ? r.deleted : 0;
+    const promoted = Array.isArray(r.promoted) ? r.promoted.length : 0;
+    const warnings = Array.isArray(r.warnings) ? r.warnings : [];
+    const lines = [];
+    if (r.dryRun === true) {
+        lines.push(`[consolidate] dry-run: ${processed} memories found, no AI call`);
+    }
+    else if (r.previewOnly === true) {
+        lines.push(`[consolidate] preview: processed=${processed}`);
+        const planned = Array.isArray(r.planned) ? r.planned : [];
+        for (const op of planned) {
+            if (op.op === "merge") {
+                lines.push(`  merge: ${String(op.primary)} ← ${String(Array.isArray(op.secondaries) ? op.secondaries.join(", ") : "")}`);
+            }
+            else if (op.op === "delete") {
+                lines.push(`  delete: ${String(op.ref)} (${String(op.reason ?? "")})`);
+            }
+            else if (op.op === "promote") {
+                lines.push(`  promote: ${String(op.ref)} → ${String(op.knowledgeRef)}`);
+            }
+        }
+    }
+    else {
+        lines.push(`[consolidate] processed=${processed} merged=${merged} deleted=${deleted} promoted=${promoted}`);
+    }
+    for (const w of warnings) {
+        lines.push(`  warning: ${w}`);
+    }
+    return lines.join("\n");
+}
+export function formatImprovePlain(r) {
+    const scope = r.scope ?? {};
+    const mode = String(scope.mode ?? "all");
+    const value = typeof scope.value === "string" ? ` ${scope.value}` : "";
+    const plannedRefs = Array.isArray(r.plannedRefs) ? r.plannedRefs.length : 0;
+    if (r.dryRun === true) {
+        return `Improve dry-run:${mode === "all" ? " all assets" : value} (${plannedRefs} planned ref(s))`;
+    }
+    const actions = Array.isArray(r.actions) ? r.actions.length : 0;
+    return `Improve:${mode === "all" ? " all assets" : value} queued ${actions} action(s) across ${plannedRefs} ref(s)`;
+}
 export function formatProposalDiffPlain(r) {
     const header = r.isNew
         ? `# proposal ${String(r.id ?? "?")} (new asset: ${String(r.ref ?? "?")})`
@@ -552,18 +723,25 @@ export function formatProposalDiffPlain(r) {
         return `${header}\n(no changes)`;
     return `${header}\n${unified}`;
 }
-export function formatEventsPlain(r) {
-    const events = Array.isArray(r.events) ? r.events : [];
-    const headerParts = [];
+/**
+ * Build the summary header line shared by formatEventsPlain and formatHistoryPlain.
+ * Accumulates ref/type/since label parts then appends the count label.
+ */
+function buildEventHeader(r, countLabel, totalCount) {
+    const parts = [];
     if (typeof r.ref === "string" && r.ref)
-        headerParts.push(`ref: ${r.ref}`);
+        parts.push(`ref: ${r.ref}`);
     if (typeof r.type === "string" && r.type)
-        headerParts.push(`type: ${r.type}`);
+        parts.push(`type: ${r.type}`);
     if (typeof r.since === "string" && r.since)
-        headerParts.push(`since: ${r.since}`);
+        parts.push(`since: ${r.since}`);
+    parts.push(`${totalCount} ${countLabel}`);
+    return parts.join("  ");
+}
+export function formatEventsPlain(r) {
+    const events = Array.isArray(r.events) ? r.events : [];
     const totalCount = typeof r.totalCount === "number" ? r.totalCount : events.length;
-    headerParts.push(`${totalCount} event(s)`);
-    const header = headerParts.join("  ");
+    const header = buildEventHeader(r, "event(s)", totalCount);
     if (events.length === 0) {
         return `${header}\nNo events.`;
     }
@@ -586,13 +764,8 @@ export function formatEventLine(event) {
 }
 export function formatHistoryPlain(r) {
     const entries = Array.isArray(r.entries) ? r.entries : [];
-    const headerParts = [];
-    if (typeof r.ref === "string" && r.ref)
-        headerParts.push(`ref: ${r.ref}`);
-    if (typeof r.since === "string" && r.since)
-        headerParts.push(`since: ${r.since}`);
     const totalCount = typeof r.totalCount === "number" ? r.totalCount : entries.length;
-    headerParts.push(`${totalCount} event(s)`);
+    const headerParts = [buildEventHeader(r, "event(s)", totalCount)];
     // Show active event sources so operators know which streams were consulted.
     if (Array.isArray(r.sources) && r.sources.length > 0) {
         headerParts.push(`sources: ${r.sources.join(", ")}`);
@@ -670,6 +843,19 @@ function formatShowPlain(r, detail) {
         if (r.schemaVersion !== undefined)
             lines.push(`schemaVersion: ${String(r.schemaVersion)}`);
     }
+    const related = typeof r.related === "object" && r.related !== null ? r.related : undefined;
+    const relatedHits = related && Array.isArray(related.hits) ? related.hits : [];
+    if (related) {
+        lines.push("");
+        lines.push(`related: ${String(related.total ?? relatedHits.length)}`);
+        for (const hit of relatedHits) {
+            lines.push(`  - ${String(hit.type ?? "?")}: ${formatRelatedLabel(hit)}`);
+            const shared = Array.isArray(hit.sharedEntities) ? hit.sharedEntities.map(String) : [];
+            if (shared.length > 0)
+                lines.push(`    shared: ${shared.join(", ")}`);
+            lines.push(`    relationCount: ${String(hit.relationCount ?? 0)}`);
+        }
+    }
     const payloads = [r.content, r.template, r.prompt].filter((value) => value != null).map(String);
     if (Array.isArray(r.steps) && r.steps.length > 0) {
         if (lines.length > 0)
@@ -786,6 +972,13 @@ function isCommandOutputSkill(lines) {
     const yamlCount = codeLines.filter((l) => yamlPattern.test(l)).length;
     return cliCount > yamlCount && cliCount > 0;
 }
+function formatRelatedLabel(hit) {
+    const ref = typeof hit.ref === "string" ? hit.ref : undefined;
+    if (ref)
+        return ref;
+    const pathValue = typeof hit.path === "string" ? hit.path : "?";
+    return pathValue.split("/").pop() ?? pathValue;
+}
 export function formatWorkflowListPlain(result) {
     const runs = Array.isArray(result.runs) ? result.runs : [];
     if (runs.length === 0) {
@@ -918,6 +1111,24 @@ export function formatSearchPlain(r, detail) {
         if (Array.isArray(hit.warnings) && hit.warnings.length > 0) {
             lines.push(`  warnings: ${hit.warnings.join("; ")}`);
         }
+        const graph = typeof hit.graph === "object" && hit.graph !== null ? hit.graph : undefined;
+        if (graph) {
+            const entities = Array.isArray(graph.entities) ? graph.entities : [];
+            if (entities.length > 0) {
+                const matched = entities
+                    .filter((entity) => String(entity.kind ?? "") === "matched")
+                    .map((entity) => String(entity.name ?? "?"));
+                const neighbors = entities
+                    .filter((entity) => String(entity.kind ?? "") !== "matched")
+                    .map((entity) => String(entity.name ?? "?"));
+                lines.push(`  graph: ${[
+                    matched.length > 0 ? `query match=${matched.join(", ")}` : undefined,
+                    neighbors.length > 0 ? `neighbors=${neighbors.join(", ")}` : undefined,
+                ]
+                    .filter(Boolean)
+                    .join("; ")}`);
+            }
+        }
         if (detail === "full") {
             if (hit.path)
                 lines.push(`  path: ${String(hit.path)}`);
@@ -1113,3 +1324,31 @@ export function formatCuratePlain(r, detail) {
     lines.push("To search further: akm search '<query>'");
     return lines.join("\n");
 }
+/**
+ * Render the result of `akm agent <profile>`.
+ *
+ * Interactive mode: stdout and stderr are empty (output went to the TTY).
+ * Print only the profile name and exit code so the caller knows the agent
+ * finished.
+ *
+ * Captured mode: emit stdout (if non-empty), then stderr (if non-empty),
+ * then the profile/exit-code summary line.
+ */
+export function formatAgentResultPlain(r) {
+    const profile = String(r.profileName ?? "agent");
+    const exitCode = r.exitCode !== undefined && r.exitCode !== null ? Number(r.exitCode) : 0;
+    const stdout = typeof r.stdout === "string" ? r.stdout : "";
+    const stderr = typeof r.stderr === "string" ? r.stderr : "";
+    // Interactive mode: both streams are empty.
+    if (!stdout && !stderr) {
+        return `[${profile}] agent exited with code ${exitCode}`;
+    }
+    // Captured mode: stream content + summary.
+    const parts = [];
+    if (stdout)
+        parts.push(stdout.trimEnd());
+    if (stderr)
+        parts.push(stderr.trimEnd());
+    parts.push(`[${profile}] agent exited with code ${exitCode}`);
+    return parts.join("\n");
+}