vigiles 5.2.0 → 6.0.0

package/dist/cli.js

@@ -14,12 +14,14 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const glob_1 = require("glob");
 const generate_types_js_1 = require("./core/generate-types.js");
+const generate_harness_js_1 = require("./core/generate-harness.js");
 const validate_js_1 = require("./core/validate.js");
 const cli_flags_js_1 = require("./cli-flags.js");
 const setup_plan_js_1 = require("./setup-plan.js");
 const types_js_1 = require("./core/types.js");
 const test_coverage_js_1 = require("./test-coverage.js");
 const scaffold_test_js_1 = require("./scaffold-test.js");
+const effects_js_1 = require("./core/effects.js");
 const scan_js_1 = require("./scan.js");
 const score_explainer_js_1 = require("./score-explainer.js");
 const scan_behavioral_js_1 = require("./scan-behavioral.js");
@@ -2573,6 +2575,78 @@ function handleGenerateSchema(args, restArgs) {
     console.log("  Add to your markdown frontmatter:\n" +
         `    # yaml-language-server: $schema=./${outPath}`);
 }
+/**
+ * `vigiles generate-harness [dir] [out]` — emit one typed registry over every
+ * `*.spec.ts` under `dir`, so a single `tsc --noEmit` cross-checks the whole
+ * harness (dangling delegates → a tsc error; duplicate names → this command
+ * exits non-zero; the capability lattice → a computed export). The third
+ * generated artifact beside `generate-types` / `generate-schema`. See
+ * docs/cli.md and research/whole-harness-codegen.md.
+ */
+async function handleGenerateHarness(args, restArgs) {
+    const checkOnly = args.includes("--check");
+    const dir = (0, node_path_1.resolve)(restArgs[0] ?? ".");
+    const outPath = restArgs[1] ?? (0, node_path_1.resolve)(dir, generate_harness_js_1.HARNESS_GEN_FILENAME);
+    const fullOut = (0, node_path_1.resolve)(process.cwd(), outPath);
+    const specImport = args
+        .filter((a) => a.startsWith("--spec-import="))
+        .map((a) => a.split("=")[1])
+        .filter(Boolean)[0] ?? undefined;
+    // Resolve the harness ONCE (honour --harness / config / auto-detect) so the
+    // capability lattice is computed against the right dialect — never defaulting
+    // to Claude Code in core. The dialect is INJECTED into the generator.
+    const harnessFlag = harnessFlagFrom(args);
+    const adapter = harnessFlag
+        ? (0, adapter_registry_js_1.resolveAdapter)(dir, harnessFlag)
+        : (0, adapter_registry_js_1.detectAdapterResult)(dir).adapter;
+    console.log(`Scanning ${(0, generate_harness_js_1.labelFor)(process.cwd(), dir)} for *.spec.ts...\n`);
+    const model = await (0, generate_harness_js_1.loadHarnessModel)(dir, (abs) => loadSpec(abs));
+    const result = (0, generate_harness_js_1.generateHarness)(model, {
+        dialect: adapter.dialect,
+        outDir: (0, node_path_1.dirname)(fullOut),
+        specImport,
+    });
+    console.log(`  ${String(result.agentCount)} agent(s), ${String(result.edgeCount)} delegate edge(s)` +
+        (result.handoffCount > 0
+            ? `, ${String(result.handoffCount)} handoff check(s)`
+            : ""));
+    console.log(`  capabilities: ${result.capabilities.purity} (` +
+        `${String(result.capabilities.sideEffecting.length)} side-effecting, ` +
+        `${String(result.capabilities.unknown.length)} unknown)`);
+    // DUPLICATE NAME — the O(N) JS check (never a type). Exit non-zero, no write.
+    if (result.duplicate) {
+        console.log(`\n✗ ${result.duplicate.message}`);
+        console.log(`::error::${result.duplicate.message}`);
+        process.exit(2);
+    }
+    if (checkOnly) {
+        if (!(0, node_fs_1.existsSync)(fullOut)) {
+            console.log(`\n✗ ${outPath} does not exist. Run \`vigiles generate-harness\` to create it.`);
+            process.exit(1);
+        }
+        const existing = (0, node_fs_1.readFileSync)(fullOut, "utf-8");
+        const normalize = (s) => s
+            .split("\n")
+            .map((l) => l.trimEnd())
+            .join("\n")
+            .replace(/\n{3,}/g, "\n\n")
+            .trim();
+        if (normalize(existing) === normalize(result.gen)) {
+            console.log(`\n✓ ${outPath} is up to date`);
+        }
+        else {
+            console.log(`\n✗ ${outPath} is stale. Run \`vigiles generate-harness\` to update.`);
+            process.exit(1);
+        }
+        return;
+    }
+    const outDir = (0, node_path_1.dirname)(fullOut);
+    if (!(0, node_fs_1.existsSync)(outDir))
+        (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
+    (0, node_fs_1.writeFileSync)(fullOut, result.gen);
+    console.log(`\n✓ Generated ${(0, generate_harness_js_1.labelFor)(process.cwd(), fullOut)}`);
+    console.log("  `tsc --noEmit` over this file now checks every delegate target resolves.");
+}
 /**
  * `vigiles test` / `vigiles eval` — discover and run the two-tier harness
  * scripts (deterministic `*.harness.mjs` / real-model `*.eval.mjs`) as child
@@ -2681,7 +2755,34 @@ function pluginNameFor(dir, manifestPath) {
     return (0, node_path_1.basename)(dir);
 }
 /** Enrich an untested Surface with the metadata the right template needs. */
-function scaffoldInputFor(s, report, pluginName) {
+/** Extract `"name": type` fields from one rendered `vigiles:ok`/`err` shape block. */
+function parseContractFields(block) {
+    const fields = [];
+    const re = /"([^"]+)"\s*:\s*(string\[\]|string|number|boolean)/g;
+    let m;
+    while ((m = re.exec(block)) !== null) {
+        fields.push({ name: m[1], type: m[2] });
+    }
+    return fields;
+}
+/**
+ * Parse a subagent's compiled `## Output contract` (the `vigiles:ok` / `vigiles:err`
+ * blocks the compiler emits) back into a typed `ResultContract`, so the generator
+ * can write an `assertAgentOk` test against the real fields. Returns null when the
+ * agent has no result() contract.
+ */
+function parseResultContract(md) {
+    const ok = /```vigiles:ok\n([\s\S]*?)```/.exec(md);
+    const err = /```vigiles:err\n([\s\S]*?)```/.exec(md);
+    if (!ok && !err)
+        return null;
+    const okFields = ok ? parseContractFields(ok[1]) : [];
+    const errFields = err ? parseContractFields(err[1]) : [];
+    if (okFields.length === 0 && errFields.length === 0)
+        return null;
+    return { ok: okFields, err: errFields };
+}
+function scaffoldInputFor(s, report, pluginName, dir, dialect) {
     const base = { kind: s.kind, name: s.name, path: s.path };
     switch (s.kind) {
         case "skill": {
@@ -2690,7 +2791,18 @@ function scaffoldInputFor(s, report, pluginName) {
         }
         case "agent": {
             const ag = report.agents.find((x) => x.name === s.name);
-            return { ...base, tools: ag?.tools ?? null };
+            const tools = ag?.tools ?? null;
+            const sideEffectingTools = tools
+                ? (0, effects_js_1.effectSurface)(tools, dialect).sideEffecting
+                : undefined;
+            let resultContract = null;
+            try {
+                resultContract = parseResultContract((0, node_fs_1.readFileSync)((0, node_path_1.resolve)(dir, s.path), "utf-8"));
+            }
+            catch {
+                // agent .md unreadable → no contract to generate against
+            }
+            return { ...base, tools, sideEffectingTools, resultContract };
         }
         case "hook":
             return { ...base, hookCommand: `bash ${s.path}` };
@@ -2719,7 +2831,7 @@ function handleScaffoldTest(restArgs, args) {
     });
     const report = (0, scan_js_1.scanPlugin)(dir, adapter.layout, adapter.dialect);
     const pluginName = pluginNameFor(dir, adapter.layout.manifestPath);
-    const scaffolds = untested.map((s) => (0, scaffold_test_js_1.scaffoldTest)(scaffoldInputFor(s, report, pluginName)));
+    const scaffolds = untested.map((s) => (0, scaffold_test_js_1.scaffoldTest)(scaffoldInputFor(s, report, pluginName, dir, adapter.dialect)));
     if (json) {
         console.log(JSON.stringify(scaffolds, null, 2));
         return;
@@ -2777,6 +2889,8 @@ function printUsage(command) {
     console.log("  vigiles generate-types --check  Verify .d.ts is up to date");
     console.log("  vigiles generate-schema [out] Emit JSON Schema for vigiles: frontmatter");
     console.log("  vigiles generate-schema --check Verify schema.json is up to date");
+    console.log("  vigiles generate-harness [dir] Emit harness.gen.ts — one typed registry");
+    console.log("  vigiles generate-harness --check Verify harness.gen.ts is up to date");
     console.log("  vigiles --version             Print the version number");
     if (command && command !== "--help") {
         console.log(`\nUnknown command: "${command}"`);
@@ -2927,9 +3041,13 @@ function agentHookCommand() {
     }
     let tool = "";
     let command;
+    let event = "";
+    let toolInput;
     try {
         const parsed = JSON.parse(raw);
+        event = parsed.hook_event_name ?? "";
         tool = parsed.tool_name ?? "";
+        toolInput = parsed.tool_input;
         if (typeof parsed.tool_input?.command === "string") {
             command = parsed.tool_input.command;
         }
@@ -2937,9 +3055,34 @@ function agentHookCommand() {
     catch {
         /* malformed input → no tool, allow */
     }
+    const cwd = process.cwd();
+    // EXPERIMENTAL (parked P3, flat-only — do NOT auto-wire): the Task/SubagentStop
+    // bracketing below assumes one active subagent at a time and is NOT nesting-safe
+    // (CC v2.1.172 depth-5 nesting needs a stack + spawn-tool-name check). See
+    // research/effect-boundary-design.md.
+    // SubagentStop → CLOSE the window deterministically (no model `agent-done`):
+    // the subagent returned, so its contract/purity no longer apply.
+    if (event === "SubagentStop") {
+        (0, agent_runtime_js_1.clearActiveAgent)(cwd);
+        (0, effect_region_js_1.clearEffectActive)(cwd);
+        return;
+    }
+    // PreToolUse(Task) → OPEN the window deterministically (no model `agent-start`
+    // / `effect-enter`): the parent is dispatching a subagent, so activate that
+    // subagent's compiled contract for the tool calls it is about to make. The
+    // Task dispatch itself is the PARENT's action — don't gate it against the
+    // subagent's contract; just open the window and allow.
+    if (tool === "Task") {
+        const agentPath = (0, agent_runtime_js_1.decideTaskDispatch)(toolInput, cwd, process.env.CLAUDE_PLUGIN_ROOT);
+        if (agentPath) {
+            (0, agent_runtime_js_1.setActiveAgent)(cwd, agentPath);
+            (0, effect_region_js_1.setEffectActive)(cwd);
+        }
+        return;
+    }
     if (!tool)
         return;
-    const decision = (0, agent_runtime_js_1.evaluatePreToolUse)(process.cwd(), tool, command);
+    const decision = (0, agent_runtime_js_1.evaluatePreToolUse)(cwd, tool, command);
     if (!decision.allow) {
         console.error(decision.message);
         process.exit(2);
@@ -3298,6 +3441,9 @@ async function main() {
         case "generate-schema":
             handleGenerateSchema(args, restArgs);
             break;
+        case "generate-harness":
+            await handleGenerateHarness(args, restArgs);
+            break;
         default:
             if (!handleSkillCommand(command, restArgs))
                 printUsage(command);

package/dist/core/compile.d.ts

@@ -25,7 +25,7 @@ export declare function verifyHash(content: string): {
  */
 /** @internal */ export declare function estimateTokens(text: string): number;
 export interface CompileError {
-    type: "stale-file" | "stale-command" | "stale-ref" | "invalid-rule" | "budget-exceeded" | "section-too-long" | "section-has-header" | "reserved-section-key" | "spec-name-mismatch" | "unknown-tool" | "invalid-railway" | "purity-violation" | "output-without-fork";
+    type: "stale-file" | "stale-command" | "stale-ref" | "invalid-rule" | "budget-exceeded" | "section-too-long" | "section-has-header" | "reserved-section-key" | "spec-name-mismatch" | "unknown-tool" | "invalid-railway" | "purity-violation" | "output-without-fork" | "effect-in-skill";
     message: string;
     path?: string;
 }

package/dist/core/compile.js

@@ -730,6 +730,20 @@ function compileSkill(spec, options = {}) {
                 "as a subagent, or drop `output`.",
         });
     }
+    // effect() is a SUBAGENT primitive. A deterministic effect REGION needs a
+    // structural call→return bracket to scope it; a default skill is spliced into
+    // the main conversation and has none (the dogfood that proved the model-emitted
+    // boundary is fragile — research/effect-boundary-design.md). A skill bounds its
+    // effects with a `purity` floor and promotes to `context:'fork'` (a subagent)
+    // when it must mutate.
+    if (collectSkillRefs(spec).some((f) => typeof f !== "string" && f._ref === "effect")) {
+        errors.push({
+            type: "effect-in-skill",
+            message: "effect() is a subagent primitive — a skill has no call→return boundary to " +
+                "scope an effect region. Declare a `purity` floor on the skill and use " +
+                "context:'fork' to run it as a subagent when it must mutate.",
+        });
+    }
     // purity floor check — the dialect is optional (callers that don't pass one
     // skip the check rather than crash; the CLI always passes it). An absent
     // tools list inherits ALL tools, so it's checked as the "*" wildcard (a

package/dist/core/generate-harness.d.ts

@@ -0,0 +1,187 @@
+/**
+ * vigiles generate-harness — emit ONE typed registry over the whole harness.
+ *
+ * The third generated artifact beside `generate-types` (`.d.ts`) and
+ * `generate-schema` (JSON Schema): a `harness.gen.ts` that imports every
+ * `*.spec.ts` in a directory, folds the agents into a `registry`, and asserts
+ * the cross-spec invariants at the TYPE level — so a single `tsc --noEmit`
+ * checks the WHOLE harness as one program (think TanStack's `routeTree.gen.ts`).
+ * See research/whole-harness-codegen.md for the design + the measured perf.
+ *
+ * The shipped scope (the first increment):
+ *  1. DANGLING `delegate` → a `tsc` error. Each `railway()` delegate target is a
+ *     name the generator reads at codegen time; the gen file emits one shallow
+ *     per-edge assertion (`KnownAgentName<"target", AgentName>` — O(N), no
+ *     recursion) that the target resolves to a real agent, else a `tsc` error
+ *     naming the dangling target + its railway.
+ *  2. DUPLICATE agent/skill NAMES → a generator error (this module returns a
+ *     `duplicate` diagnostic; the CLI exits non-zero). This is the O(N) JS check
+ *     the encoding rule mandates — a set-uniqueness MAPPED TYPE is the TS2589
+ *     wall (measured ≈ N=1000), so duplicates are NEVER a type.
+ *  3. The whole-harness CAPABILITY LATTICE: the UNION of every agent's
+ *     `effectSurface(tools, dialect)` — a generator-computed value + type, the
+ *     substrate the future repo-scale capability-diff reads.
+ *  4. CROSS-FILE TYPED COMPOSITION: when a `railway()` success-track step declares
+ *     what it `needs()`, the gen file emits one shallow per-pair assertion
+ *     (`Handoff<OkOf<typeof registry[producer]>, needs>` — O(N), no recursion)
+ *     that the PRIOR step's `result().ok` SUPPLIES it, so a cross-file handoff
+ *     mismatch (a missing field / wrong type) is a `tsc` error naming the field.
+ *     The repo-scale generalization of the per-file `pipe`/`Supplies` composition.
+ *     Scoped to the linear success track; recover/onError (which consume an `err`,
+ *     not the prior `ok`) are a noted follow-up.
+ *
+ * Harness-agnostic: the `dialect` (for the capability lattice) is INJECTED by
+ * the composition root (the CLI), never hard-coded — mirroring `compileAgent` /
+ * `scanPlugin`. The core stays free of any Claude-Code literal.
+ */
+import type { HarnessDialect } from "./dialect.js";
+import { type PurityLevel } from "./effects.js";
+/** One agent the harness defines (its registry-relevant facts). */
+export interface HarnessAgentEntry {
+    /** The agent's dispatch name — also a registry key + the dangling-check union. */
+    readonly name: string;
+    /** The agent's declared tool contract (used to compute its effect surface). */
+    readonly tools?: readonly string[];
+    /** The spec file this agent came from (for import + duplicate diagnostics). */
+    readonly file: string;
+}
+/** One delegate edge: a railway dispatches `target` (resolved against agents). */
+export interface HarnessDelegateEdge {
+    /** The railway / orchestrator the edge originates from (for the diagnostic). */
+    readonly from: string;
+    /** The delegate target name — must resolve to a known agent, else dangling. */
+    readonly target: string;
+}
+/**
+ * One CROSS-FILE handoff edge: a consecutive success-track pair where the
+ * CONSUMER (`to`) declares the input it `needs`, asserted against the PRODUCER
+ * (`from`, the prior step's agent) `result().ok` at the type level. The
+ * registry already imports each agent's `TypedAgentSpec`, so the generator reads
+ * the producer's `ok` shape off the registry (`OkOf<typeof registry[from]>`) and
+ * emits one shallow `Handoff<>` assertion per such pair (O(N), no recursion).
+ */
+export interface HarnessHandoffEdge {
+    /** The railway the edge originates from (for the diagnostic). */
+    readonly railway: string;
+    /** The PRODUCER agent name (the prior success-track step) — registry key. */
+    readonly from: string;
+    /** The CONSUMER agent name (this step) — names the failing edge. */
+    readonly to: string;
+    /** The consumer's declared input shape (`needs(...)`) — the literal emitted. */
+    readonly needs: Readonly<Record<string, string>>;
+}
+/** Everything the generator needs, already loaded (the pure-core input). */
+export interface HarnessModel {
+    readonly agents: readonly HarnessAgentEntry[];
+    readonly edges: readonly HarnessDelegateEdge[];
+    /**
+     * Cross-file handoff edges (consecutive success-track step pairs whose
+     * consumer declares `needs`). Optional + defaults to none, so an existing
+     * model with no handoffs generates exactly as before — backwards-compatible.
+     */
+    readonly handoffs?: readonly HarnessHandoffEdge[];
+}
+export interface GenerateHarnessOptions {
+    /** The dialect the capability lattice is computed against (injected). */
+    readonly dialect: HarnessDialect;
+    /**
+     * The module specifier the generated file imports `KnownAgentName` from.
+     * Defaults to the public package (`"vigiles/spec"`); the in-repo dogfood
+     * passes a relative path so the generated file resolves without the package.
+     */
+    readonly specImport?: string;
+    /** The directory the gen file will be written to (to relativize spec imports). */
+    readonly outDir: string;
+}
+/** A duplicate-name collision found at codegen time (the O(N) JS check). */
+export interface DuplicateNameDiagnostic {
+    readonly name: string;
+    readonly first: string;
+    readonly second: string;
+    /** A ready-to-print message. */
+    readonly message: string;
+}
+/** The whole-harness capability lattice — the union of every agent's surface. */
+export interface HarnessCapabilities {
+    /** Every read-only tool reachable anywhere in the harness (de-duped, sorted). */
+    readonly readOnly: readonly string[];
+    /** Every side-effecting tool reachable anywhere (de-duped, sorted). */
+    readonly sideEffecting: readonly string[];
+    /** Every unknown-effect tool (MCP / unrecognized) reachable anywhere. */
+    readonly unknown: readonly string[];
+    /** The harness-wide purity: the LOOSEST purity of any single agent. */
+    readonly purity: PurityLevel;
+}
+export interface GenerateHarnessResult {
+    /** The generated `harness.gen.ts` source (always produced — even on a dup, so
+     *  the caller can decide; the CLI gates the WRITE on `duplicate` being absent). */
+    readonly gen: string;
+    /** The computed capability lattice (also embedded in `gen`). */
+    readonly capabilities: HarnessCapabilities;
+    /** Set iff two agents declare the same name — the caller exits non-zero. */
+    readonly duplicate?: DuplicateNameDiagnostic;
+    /** The number of agents + edges folded in (for the CLI summary). */
+    readonly agentCount: number;
+    readonly edgeCount: number;
+    /** The number of cross-file handoff assertions emitted (for the CLI summary). */
+    readonly handoffCount: number;
+}
+/**
+ * Fold every agent's `effectSurface` into one harness-wide lattice: the union of
+ * each bucket and the loosest purity. An agent with no `tools` inherits all (a
+ * wildcard), so its surface is `unrestricted` — handled by `effectSurface` when
+ * we pass `["*"]`. O(N) over the agents; the per-agent legs are fixed-arity.
+ */
+export declare function computeHarnessCapabilities(agents: readonly HarnessAgentEntry[], dialect: HarnessDialect): HarnessCapabilities;
+/**
+ * Find the FIRST pair of agents that declare the same `name`. O(N) over the
+ * agents — the set-cardinality check the encoding rule says must live in the JS
+ * generator, never as an N×N mapped type (the measured TS2589 wall). Returns
+ * `undefined` when names are unique.
+ */
+export declare function findDuplicateName(agents: readonly HarnessAgentEntry[]): DuplicateNameDiagnostic | undefined;
+/**
+ * Generate the `harness.gen.ts` source over an already-loaded `HarnessModel`.
+ *
+ * Pure: no filesystem read, no spec loading — just string emission + the two
+ * O(N) computations (capability lattice + duplicate check). The fs/scan wrapper
+ * (`loadHarnessModel`) feeds this.
+ */
+export declare function generateHarness(model: HarnessModel, options: GenerateHarnessOptions): GenerateHarnessResult;
+/** A minimal shape of a loaded spec value (the fields the model reads). */
+interface LoadedSpecLike {
+    readonly _specType?: string;
+    readonly name?: string;
+    readonly tools?: readonly string[];
+    readonly steps?: readonly {
+        readonly agent?: string;
+        readonly needs?: Readonly<Record<string, string>>;
+    }[];
+    readonly onError?: {
+        readonly agent?: string;
+    };
+    readonly recover?: {
+        readonly step?: {
+            readonly agent?: string;
+        };
+    };
+}
+/** Discover every `*.spec.ts` directly under `dir` (non-recursive, sorted). */
+export declare function findHarnessSpecFiles(dir: string): string[];
+/**
+ * Build a `HarnessModel` from `dir`'s spec files using a caller-supplied
+ * `load(file) → value` (the CLI injects its `loadSpec`, so this stays
+ * fs/runtime-agnostic and unit-testable with fakes). Agents become registry
+ * entries; railways contribute delegate edges (steps + recover + onError).
+ */
+export declare function loadHarnessModel(dir: string, load: (absFile: string) => Promise<LoadedSpecLike | null>): Promise<HarnessModel>;
+/** Convenience: the gen file's basename, used by the CLI default out path. */
+export declare const HARNESS_GEN_FILENAME = "harness.gen.ts";
+/** Relative label for a path under cwd (CLI-only nicety; pure). */
+export declare function labelFor(cwd: string, abs: string): string;
+/** Read a spec file's raw text (helper exposed for callers that need the source). */
+export declare function readSpecSource(absFile: string): string;
+/** The directory a gen file at `outFile` lives in (helper for the CLI). */
+export declare function genOutDir(outFile: string): string;
+export {};
+//# sourceMappingURL=generate-harness.d.ts.map