@interf/compiler 0.13.0 → 0.18.0

package/builtin-methods/interf-default/method.schema.json

@@ -3,71 +3,73 @@
   "version": 1,
   "target_type": "compiled",
   "label": "Interf built-in Method schema",
-  "zones": [
+  "artifacts": [
+    {
+      "id": "atlas",
+      "description": "Primary entrypoint note that agents read first. Routes to summaries, knowledge entities, claims, and indexes.",
+      "shape": { "kind": "path", "path": "home.md", "artifact_kind": "file" },
+      "checks": [
+        { "id": "exists", "kind": "file_exists", "required": true },
+        {
+          "id": "no-placeholder",
+          "kind": "must_not_contain",
+          "required": true,
+          "params": { "phrases": ["Not yet compiled."] }
+        },
+        { "id": "wikilinks", "kind": "wikilinks_valid", "required": true }
+      ],
+      "built_by_stages": ["shape"]
+    },
     {
       "id": "summaries",
-      "role": "working",
-      "path": "summaries",
-      "kind": "directory",
-      "required": true,
-      "owned_by": [
-        "summarize"
+      "description": "Per-file evidence notes that preserve the source-grounded synthesis agents quote against.",
+      "shape": { "kind": "path", "path": "summaries", "artifact_kind": "directory" },
+      "checks": [
+        {
+          "id": "all-files-summarized",
+          "kind": "min_file_count_matches_source",
+          "required": true,
+          "params": { "match": "source_total" }
+        },
+        { "id": "frontmatter-valid", "kind": "frontmatter_valid", "required": true },
+        {
+          "id": "evidence-keys",
+          "kind": "frontmatter_required_keys",
+          "required": true,
+          "params": { "keys": ["source", "source_kind", "evidence_tier", "truth_mode", "state"] }
+        }
       ],
-      "description": "Per-file evidence notes produced by file-evidence stages."
+      "built_by_stages": ["summarize"]
     },
     {
       "id": "knowledge-entities",
-      "role": "output",
-      "path": "knowledge/entities",
-      "kind": "directory",
-      "required": true,
-      "owned_by": [
-        "structure"
+      "description": "Canonical entity notes that anchor the cross-file knowledge structure.",
+      "shape": { "kind": "path", "path": "knowledge/entities", "artifact_kind": "directory" },
+      "checks": [
+        { "id": "exists", "kind": "min_file_count", "required": true, "params": { "min": 1 } },
+        { "id": "wikilinks", "kind": "wikilinks_valid", "required": true }
       ],
-      "description": "Canonical entity notes produced by knowledge-structure stages."
+      "built_by_stages": ["structure"]
     },
     {
       "id": "knowledge-claims",
-      "role": "output",
-      "path": "knowledge/claims",
-      "kind": "directory",
-      "required": true,
-      "owned_by": [
-        "structure"
+      "description": "Claim notes extracted from summaries with evidence references.",
+      "shape": { "kind": "path", "path": "knowledge/claims", "artifact_kind": "directory" },
+      "checks": [
+        { "id": "exists", "kind": "min_file_count", "required": true, "params": { "min": 1 } },
+        { "id": "wikilinks", "kind": "wikilinks_valid", "required": true }
       ],
-      "description": "Claim notes produced by knowledge-structure stages."
+      "built_by_stages": ["structure"]
     },
     {
       "id": "knowledge-indexes",
-      "role": "output",
-      "path": "knowledge/indexes",
-      "kind": "directory",
-      "required": true,
-      "owned_by": [
-        "structure",
-        "shape"
-      ],
-      "description": "Retrieval indexes and navigation notes produced by structure and shape stages."
-    },
-    {
-      "id": "home",
-      "role": "output",
-      "path": "home.md",
-      "kind": "file",
-      "required": true,
-      "owned_by": [
-        "shape"
+      "description": "Retrieval indexes and navigation notes for the knowledge structure.",
+      "shape": { "kind": "path", "path": "knowledge/indexes", "artifact_kind": "directory" },
+      "checks": [
+        { "id": "exists", "kind": "min_file_count", "required": true, "params": { "min": 1 } },
+        { "id": "wikilinks", "kind": "wikilinks_valid", "required": true }
       ],
-      "description": "Primary entrypoint note for agents using the portable context."
-    },
-    {
-      "id": "runtime",
-      "role": "runtime",
-      "path": ".interf/runtime",
-      "kind": "runtime",
-      "required": true,
-      "owned_by": [],
-      "description": "CLI-owned runtime state, health, stage contracts, and proof artifacts."
+      "built_by_stages": ["structure", "shape"]
     }
   ]
 }

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

@@ -0,0 +1,2 @@
+import type { CommandModule } from "yargs";
+export declare const agentsCommand: CommandModule;

package/dist/cli/commands/agents.js

@@ -0,0 +1,213 @@
+/**
+ * `interf agents` — manage connected agents + role mapping.
+ *
+ *   interf agents ls                                # list registered + detected
+ *   interf agents use <name>                        # set active agent
+ *   interf agents register <name> --command <cmd> [--display-name <s>]
+ *   interf agents unregister <name>                 # custom CLIs only
+ *   interf agents map <role> <agent>                # pin a role to an agent
+ *   interf agents unmap <role>                      # clear a role
+ *
+ * All subcommands hit the connected local service. They never touch
+ * `~/.interf/agents.json` directly — the service is the source of truth.
+ */
+import chalk from "chalk";
+import { CONNECT_OR_ERROR_HINT, readActiveConnection, } from "../../packages/engine/connection-config.js";
+function resolveConnection(args) {
+    const conn = readActiveConnection({
+        urlOverride: args.url,
+        authTokenOverride: args.token,
+    });
+    if (!conn) {
+        console.error(CONNECT_OR_ERROR_HINT);
+        process.exit(1);
+    }
+    return { url: conn.url.replace(/\/+$/, ""), token: conn.auth_token };
+}
+async function callJson(url, token, init = {}) {
+    const headers = new Headers(init.headers ?? {});
+    if (token)
+        headers.set("authorization", `Bearer ${token}`);
+    if (init.body && !headers.has("content-type")) {
+        headers.set("content-type", "application/json");
+    }
+    const response = await fetch(url, { ...init, headers });
+    const raw = await response.text();
+    let body = null;
+    if (raw.length > 0) {
+        try {
+            body = JSON.parse(raw);
+        }
+        catch {
+            body = null;
+        }
+    }
+    return { status: response.status, body, raw };
+}
+function formatAgentLine(agent, registry) {
+    const isActive = agent.name === registry.active_agent?.name;
+    const sourceLabel = agent.source === "builtin" ? "builtin" : "user";
+    const activeMarker = isActive ? chalk.green(" (active)") : "";
+    const availabilityMarker = agent.available === false ? chalk.yellow(" (not installed)") : "";
+    return `  ${chalk.bold(agent.name)} ${chalk.dim(`[${sourceLabel}]`)} ${chalk.dim(agent.display_name)} — ${chalk.dim(agent.command)}${activeMarker}${availabilityMarker}`;
+}
+function printRegistry(registry) {
+    if (registry.agents.length === 0) {
+        console.log();
+        console.log(chalk.yellow("  No agents available."));
+        console.log();
+        console.log("  Install Claude Code, Codex, Gemini, or another agent CLI,");
+        console.log("  or register a custom CLI: `interf agents register <name> --command <cmd>`.");
+        console.log();
+        return;
+    }
+    console.log();
+    console.log(chalk.bold("  Connected agents"));
+    for (const agent of registry.agents) {
+        console.log(formatAgentLine(agent, registry));
+    }
+    if (Object.keys(registry.role_map).length > 0) {
+        console.log();
+        console.log(chalk.bold("  Role mapping"));
+        for (const [role, agentName] of Object.entries(registry.role_map)) {
+            console.log(`  ${chalk.bold(role.padEnd(11))} → ${agentName}`);
+        }
+    }
+    console.log();
+}
+export const agentsCommand = {
+    command: "agents <subcommand>",
+    describe: "Manage connected agents and role mapping",
+    builder: (yargs) => yargs
+        .option("url", { type: "string", describe: "Override the active connection URL" })
+        .option("token", { type: "string", describe: "Override the active bearer token" })
+        .command("ls", "List registered + detected agents", (y) => y, async (args) => {
+        const { url, token } = resolveConnection(args);
+        const { status, body, raw } = await callJson(`${url}/v1/agents`, token);
+        if (status !== 200 || !body) {
+            console.error(chalk.red(`Failed to list agents (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        printRegistry(body);
+    })
+        .command("use <name>", "Set the active agent (mirrors to role_map.general + sweeps roles still on the prior active)", (y) => y.positional("name", {
+        type: "string",
+        demandOption: true,
+        describe: "Agent name (e.g. claude-code, codex, opencode)",
+    }), async (args) => {
+        const { url, token } = resolveConnection(args);
+        const { status, body, raw } = await callJson(`${url}/v1/executor`, token, {
+            method: "POST",
+            body: JSON.stringify({ agent: args.name }),
+        });
+        if (status !== 200 && status !== 202) {
+            console.error(chalk.red(`Failed to set active agent (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        const display = body?.executor?.display_name ?? args.name;
+        console.log(chalk.green(`  Active agent: ${chalk.bold(display)}.`));
+    })
+        .command("register <name>", "Register a custom agent CLI", (y) => y
+        .positional("name", {
+        type: "string",
+        demandOption: true,
+        describe: "Agent name (lowercase identifier, e.g. opencode)",
+    })
+        .option("command", {
+        type: "string",
+        demandOption: true,
+        describe: "Command to invoke (e.g. \"opencode --prompt\")",
+    })
+        .option("display-name", {
+        type: "string",
+        describe: "Human-readable name (defaults to the agent name)",
+    }), async (args) => {
+        const { url, token } = resolveConnection(args);
+        const displayName = args.displayName ?? args.name;
+        const { status, body, raw } = await callJson(`${url}/v1/agents`, token, {
+            method: "POST",
+            body: JSON.stringify({
+                name: args.name,
+                display_name: displayName,
+                command: args.command,
+            }),
+        });
+        if (status !== 201 || !body) {
+            console.error(chalk.red(`Failed to register agent (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        console.log(chalk.green(`  Registered ${chalk.bold(args.name)} → ${args.command}.`));
+        printRegistry(body);
+    })
+        .command("unregister <name>", "Unregister a custom agent (built-ins cannot be unregistered)", (y) => y.positional("name", {
+        type: "string",
+        demandOption: true,
+        describe: "Agent name to remove",
+    }), async (args) => {
+        const { url, token } = resolveConnection(args);
+        const { status, body, raw } = await callJson(`${url}/v1/agents/${encodeURIComponent(args.name)}`, token, { method: "DELETE" });
+        if (status !== 200 || !body) {
+            console.error(chalk.red(`Failed to unregister agent (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        console.log(chalk.green(`  Unregistered ${chalk.bold(args.name)}.`));
+        printRegistry(body);
+    })
+        .command("map <role> <agent>", "Map a role to an agent", (y) => y
+        .positional("role", {
+        type: "string",
+        demandOption: true,
+        describe: "Role name (e.g. extractor, summarizer, verifier, general)",
+    })
+        .positional("agent", {
+        type: "string",
+        demandOption: true,
+        describe: "Agent name to bind to the role",
+    }), async (args) => {
+        const { url, token } = resolveConnection(args);
+        const patch = { [args.role]: args.agent };
+        const { status, body, raw } = await callJson(`${url}/v1/agents/role-map`, token, {
+            method: "PATCH",
+            body: JSON.stringify(patch),
+        });
+        if (status !== 200 || !body) {
+            console.error(chalk.red(`Failed to update role map (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        console.log(chalk.green(`  Mapped ${chalk.bold(args.role)} → ${args.agent}.`));
+    })
+        .command("unmap <role>", "Clear a role mapping (falls back to active agent)", (y) => y.positional("role", {
+        type: "string",
+        demandOption: true,
+        describe: "Role name to clear",
+    }), async (args) => {
+        const { url, token } = resolveConnection(args);
+        const patch = { [args.role]: "" };
+        const { status, raw } = await callJson(`${url}/v1/agents/role-map`, token, {
+            method: "PATCH",
+            body: JSON.stringify(patch),
+        });
+        if (status !== 200) {
+            console.error(chalk.red(`Failed to clear role mapping (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        console.log(chalk.green(`  Cleared role ${chalk.bold(args.role)}.`));
+    })
+        .demandCommand(1)
+        .strict(),
+    handler: () => {
+        /* yargs subcommand handlers do the work */
+    },
+};

package/dist/cli/commands/compile.js

@@ -8,7 +8,7 @@
  * Requires an active connection. Hits POST /v1/preparations/<id>/compile-runs.
  */
 import chalk from "chalk";
-import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/local-service/connection-config.js";
+import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/engine/connection-config.js";
 function resolveConnection(args) {
     const conn = readActiveConnection({
         urlOverride: args.url,
@@ -51,6 +51,15 @@ export const compileCommand = {
         .option("token", { type: "string", describe: "Override the active bearer token" }),
     handler: async (args) => {
         const { url, token } = resolveConnection(args);
+        // 0.15 hard-error: refuse to start a compile if the engine has zero
+        // connected agents — the compile pipeline can't run without one.
+        const instance = await callJson(`${url}/v1/instance`, token);
+        if (instance.body && instance.body.agent_count === 0) {
+            console.error(chalk.red("  Cannot compile — no agents available."));
+            console.error("  Install Claude Code, Codex, Gemini, or another agent CLI, or");
+            console.error("  register a custom CLI: `interf agents register <name> --command <cmd>`.");
+            process.exit(1);
+        }
         const headers = {};
         if (args.idempotencyKey)
             headers["x-interf-idempotency-key"] = args.idempotencyKey;

package/dist/cli/commands/doctor.js

@@ -1,5 +1,5 @@
 import chalk from "chalk";
-import { agents, userConfig } from "../../packages/agents/index.js";
+import { agents, userConfig } from "../../packages/engine/agents/index.js";
 function iconFor(status) {
     if (status === "pass")
         return chalk.green("✓");

package/dist/cli/commands/login.js

@@ -10,7 +10,7 @@
  * startup).
  */
 import chalk from "chalk";
-import { ConnectionRecordSchema, writeConnection, } from "../../packages/local-service/connection-config.js";
+import { ConnectionRecordSchema, writeConnection, } from "../../packages/engine/connection-config.js";
 export const loginCommand = {
     command: "login",
     describe: "Set the active Interf instance connection (URL + optional bearer token)",

package/dist/cli/commands/logout.js

@@ -5,7 +5,7 @@
  * non-zero with the connect-or-error hint until a new connection is set.
  */
 import chalk from "chalk";
-import { clearConnection } from "../../packages/local-service/connection-config.js";
+import { clearConnection } from "../../packages/engine/connection-config.js";
 export const logoutCommand = {
     command: "logout",
     describe: "Clear the active Interf instance connection",

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

@@ -0,0 +1,42 @@
+/**
+ * `interf mcp` — Model Context Protocol server.
+ *
+ * Wraps the local-service HTTP API as a typed agent surface so coding
+ * agents can interact with Interf the same way they call other MCP tools
+ * (instead of shelling out to the CLI).
+ *
+ *   interf mcp                              # stdio transport (default)
+ *   interf mcp --transport=http --port=4889 # advanced: HTTP transport
+ *
+ * The server reads `~/.interf/connection.json` (the same file every other
+ * client uses) and exits non-zero with the connect-or-error hint if no
+ * instance is reachable. Tools call straight through to the API; the
+ * server itself holds no state. The transport options are intentionally
+ * minimal — agents speaking MCP today are stdio-first.
+ *
+ * Tool list mirrors the API verbatim:
+ *   prep_list           GET /v1/preparations
+ *   prep_create         POST /v1/preparations
+ *   prep_show           GET /v1/preparations/{id}
+ *   prep_set_method     PATCH /v1/preparations/{id}
+ *   prep_remove         DELETE /v1/preparations/{id}
+ *   prep_compile        POST /v1/preparations/{id}/compile-runs
+ *   prep_verify         POST /v1/preparations/{id}/verify-runs
+ *   method_list         GET /v1/methods
+ *   method_install      POST /v1/methods (preparation-scoped via `prep_id`)
+ *   method_draft        POST /v1/preparations/{id}/method-authoring-runs
+ *   method_improve      POST /v1/preparations/{id}/method-improvement-runs
+ *   runs_status         GET /v1/runs/{run-id}
+ *   runs_watch          GET /v1/runs/{run-id}/events  (snapshot, not SSE)
+ *   runs_cancel         POST /v1/runs/{run-id}/cancel
+ *   runs_fetch          GET /v1/runs/{run-id}/artifacts
+ *   instance_status     GET /v1/instance
+ */
+import type { CommandModule } from "yargs";
+interface McpArgs {
+    transport?: "stdio" | "http";
+    url?: string;
+    token?: string;
+}
+export declare const mcpCommand: CommandModule<unknown, McpArgs>;
+export {};