@winspan/claude-forge 9.2.0 → 9.12.0

package/dist/cli/commands/agent.d.ts

@@ -0,0 +1,169 @@
+/**
+ * `cf agent` — analysis / retro commands for agent templates (decision 234f1ad4).
+ *
+ * Distinct from the plural `cf agents` family (sync/list = template deployment):
+ * `cf agent retro` is a READ-ONLY analysis report ("Agent 体检 / 模板改进建议").
+ *
+ *   cf agent retro [--agent <name>] [--days N] [--json] [--mint]
+ *
+ * 不变量 (cross-Phase, decision 234f1ad4): READ-ONLY. The report NEVER writes
+ * agent templates — it only reads health/drift signals and prints suggestions.
+ * `--mint` (default OFF) is reserved for routing high-confidence suggestions into
+ * the existing nudge/decisions register chain; this first version is text-only.
+ */
+import type { Command } from 'commander';
+import { SQLiteStorage } from '../../core/storage/sqlite.js';
+import { type AgentHealth } from '../../core/insights/agent-health.js';
+import { type DriftNudge } from '../../core/insights/agent-drift.js';
+import { buildDistillContext, type FailureSample } from '../../core/insights/agent-distill-context.js';
+interface RetroOptions {
+    agent?: string;
+    days?: string;
+    json?: boolean;
+    mint?: boolean;
+}
+interface RetroDeps {
+    storage?: SQLiteStorage;
+    io?: {
+        log: (m: string) => void;
+        error: (m: string) => void;
+    };
+}
+export declare function register(program: Command): void;
+interface SuggestOptions {
+    module?: string;
+    days?: string;
+    top?: string;
+    json?: boolean;
+}
+interface SuggestDeps {
+    storage?: SQLiteStorage;
+    registry?: {
+        getAll(): Array<{
+            id: string;
+            name: string;
+            description?: string;
+            keywords: string[];
+        }>;
+    };
+    io?: {
+        log: (m: string) => void;
+        error: (m: string) => void;
+    };
+}
+/**
+ * Exported for tests. Returns exit code instead of calling process.exit.
+ * Wires the read-only storage signals into the pure `suggestAgents` ranker.
+ */
+export declare function runSuggest(taskDesc: string, opts: SuggestOptions, deps?: SuggestDeps): number;
+/**
+ * Exported for tests. Returns exit code instead of calling process.exit.
+ */
+export declare function runRetro(opts: RetroOptions, deps?: RetroDeps): number;
+interface DistillOptions {
+    days?: string;
+    dryRun?: boolean;
+    maxFailures?: string;
+    out?: string;
+    json?: boolean;
+}
+interface DistillDeps {
+    storage?: SQLiteStorage;
+    io?: {
+        log: (m: string) => void;
+        error: (m: string) => void;
+    };
+    /** Injected spawn (tests pass a fake; real path uses the headless claude CLI). */
+    spawn?: (prompt: string) => Promise<string>;
+    /** Override the templates dir (tests). */
+    templatesDir?: string;
+    /** Override the draft output base dir (tests). */
+    outBaseDir?: string;
+}
+/** Parse a `version: N` line from a template's frontmatter (default 1). */
+export declare function readTemplateVersion(templateText: string): number;
+/** Dry-run preview payload (the JSON the CLI `--dry-run --json` prints). */
+export interface AgentDistillPreview {
+    agent: string;
+    current_version: number;
+    maturity: string;
+    enough_signal: boolean;
+    insufficient_reason: string | null;
+    proposed_change_types: string[];
+    drift: DriftNudge[];
+    recommended_skills: AgentHealth['recommended_skills'];
+    failure_samples: FailureSample[];
+    /** The dry-run human-readable summary (ctx.summary). */
+    summary: string;
+}
+/** Result of assembling the full distill run context (gate + prompt). */
+export interface AgentDistillRunContext {
+    agent: string;
+    currentVersion: number;
+    enoughSignal: boolean;
+    insufficientReason: string | null;
+    maturity: string;
+    /** Structured prompt fed to the distiller (only used on a real spawn). */
+    prompt: string;
+}
+interface BuildAgentDistillDeps {
+    storage: SQLiteStorage;
+    templatesDir?: string;
+    days?: number;
+    maxFailures?: number;
+}
+/**
+ * Assemble the read-only signal context shared by --dry-run preview and the
+ * real spawn path. Pure aside from the injected storage reads + template read.
+ * Throws on a missing template (caller maps to 404). Exported for web reuse.
+ */
+export declare function buildAgentDistillContextFor(agent: string, deps: BuildAgentDistillDeps): {
+    ctx: ReturnType<typeof buildDistillContext>;
+    currentVersion: number;
+    drift: DriftNudge[];
+    health: AgentHealth | null;
+    failureSamples: FailureSample[];
+};
+/**
+ * Web-callable: the --dry-run preview payload. FREE — never spawns the LLM.
+ * Throws on a missing template (route maps to 404).
+ */
+export declare function buildAgentDistillPreview(agent: string, deps: BuildAgentDistillDeps): AgentDistillPreview;
+/**
+ * Exported for tests. Returns a Promise<exit code>. Human-triggered
+ * retro-distill:
+ *   - assemble read-only signals → buildDistillContext
+ *   - --dry-run: print the summary + proposed changes; NO spawn, NO file writes
+ *   - else: gate check → spawn distiller → parse envelope → anchor-guard → draft
+ * NEVER writes src/daemon/templates/agents/.
+ */
+export declare function runDistill(agent: string, opts: DistillOptions, deps?: DistillDeps): Promise<number>;
+/**
+ * Render the human-reviewed draft markdown (decision 234f1ad4). Exported so the
+ * web AgentDistillManager writes byte-identical drafts (decision 568a8c53).
+ */
+export declare function renderDraft(agent: string, currentVersion: number, targetVersion: number, maturity: string, rationale: string, patch: string): string;
+interface RollbackOptions {
+    to: string;
+    write?: boolean;
+}
+interface RollbackDeps {
+    io?: {
+        log: (m: string) => void;
+        error: (m: string) => void;
+    };
+    templatesDir?: string;
+    installedDir?: string;
+    /** Injected git blob reader (tests). Returns the historical template text. */
+    readGitBlob?: (ref: string, path: string) => string;
+}
+/**
+ * Exported for tests. Human-assisted rollback (decision 234f1ad4 Q4):
+ *   - default: print the vN draft path + suggested git ops (read-only).
+ *   - --write: write the historical git blob back to the src template, then
+ *     self-check the project-level copy is byte-identical (invariant 75344363).
+ *     Divergent copies → non-zero exit warning.
+ */
+export declare function runRollback(agent: string, opts: RollbackOptions, deps?: RollbackDeps): number;
+export {};
+//# sourceMappingURL=agent.d.ts.map

package/dist/cli/commands/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/agent.ts"],"names":[],"mappings":"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"}