toolfactory 0.1.1

package/src/surfaces/hermes-native.ts

@@ -0,0 +1,584 @@
+/**
+ * Hermes native plugin — the §4.4 escape hatch on the Python side. Hermes ships no plugin
+ * scaffolder, so the package under `hosts/hermes/` is written to the shape Hermes' own loader
+ * reads: a directory holding `plugin.yaml` + `__init__.py` (`hermes_cli/plugins.py`
+ * `_load_directory_module`), packaged for pip through the `hermes_agent.plugins` entry point
+ * so the same code installs either way.
+ *
+ * Two contracts from `hermes_cli/plugins.py` are hard and are the only reason this file writes
+ * Python at all:
+ *   - `PluginContext.register_tool(name, toolset, schema, handler, check_fn, requires_env, ...)`
+ *     takes an OpenAI-style `schema` of `{name, description, parameters}` (line ~1778);
+ *   - a tool handler takes `(args: dict, **kwargs)` and returns a **JSON string**; raising
+ *     propagates into dispatch, so every generated handler returns `{"error": ...}` instead.
+ *
+ * `validate()` runs `hermes plugins doctor --ci`, which loads the plugin through the real
+ * runtime under a temp `HERMES_HOME` with network denied, so none of the above is assumed —
+ * `doctor` proves registration only, never a handler call (`hermes_cli/plugin_dev.py`'s
+ * `doctor_plugin()` tears the registration down without dispatching). `hosts/hermes/tests/
+ * test_plugin.py` proves the rest: a fake `PluginContext` collects `register_tool(...)` calls
+ * and drives one real handler, entirely without importing Hermes. It is deliberately not built
+ * on `hermes_cli.plugin_dev`'s `_doctor_runtime` / `tools.registry.registry.dispatch` — that
+ * machinery works, but its own module docstring calls it "deliberately private Doctor
+ * machinery, not a standalone plugin test framework", and shipping it into every generated repo
+ * would pin thousands of projects to an underscore-prefixed API upstream has declined to
+ * support. The fake-ctx test gets the same behavioural coverage with no Hermes import at all.
+ */
+import { join } from "node:path";
+import { stringify as toml } from "smol-toml";
+import { stringify as yaml } from "yaml";
+import { KERNEL_DIR } from "../bindings/typescript.js";
+import { projectName } from "../identity/name.js";
+import { isPortable, type Operation, type Project, type Surface, type Verdict } from "../model.js";
+import { includedOperations } from "../report/coverage.js";
+import {
+  compact,
+  configProperties,
+  dataDirEnvName,
+  envName,
+  isSensitive,
+  pypiName,
+  requiredConfig,
+  rootEnvName,
+} from "./shared.js";
+
+export const HOST_DIR = "hosts/hermes";
+
+/**
+ * `hermes_cli/plugins.py` `SUPPORTED_MANIFEST_VERSION` is 2 and the loader parses every field
+ * toolfactory emits (`python_dependencies`, `license`, `homepage`, …) regardless of the declared
+ * version — but `hermes plugins install`'s own cap, `hermes_cli/plugins_cmd.py`
+ * `_SUPPORTED_MANIFEST_VERSION`, is still 1 and rejects a v2 manifest outright before ever
+ * loading it (verified against the pinned commit: `Plugin '<name>' requires manifest_version 2,
+ * but this installer only supports up to 1`). Declaring 1 costs nothing — v1 is "supported
+ * forever" — and is what makes `hermes plugins install file://…` actually install.
+ */
+export const MANIFEST_VERSION = 1;
+
+/**
+ * The Hermes this generator was proven against (C5). Hermes ships through its own installer
+ * (it refuses wheel builds from git, and the PyPI release predates `plugins doctor`), so CI and
+ * the container harness run that installer pinned to this commit.
+ */
+export const HERMES_PIN = {
+  commit: "180291162ff4df0d42b5dc4fecd08005cf7cebf9",
+  installer: "https://hermes-agent.nousresearch.com/install.sh",
+};
+
+/** The one-line install CI and compose share: headless, pinned, no browser or bundled skills. */
+export function hermesInstall(): string {
+  return `curl -fsSL ${HERMES_PIN.installer} | bash -s -- --commit ${HERMES_PIN.commit} --skip-setup --skip-browser --skip-computer-use --non-interactive --no-skills`;
+}
+
+const HEADER = "# Generated by toolfactory. Do not edit; run `toolfactory build` to regenerate.\n";
+
+/**
+ * The plugin package. It is a sibling of the author's own package rather than part of it: a
+ * Hermes directory plugin *is* a Python package, and the two must be importable side by side.
+ */
+export function pluginPackage(project: Project): string {
+  return `${projectName.pythonPackage(project.identity.name)}_hermes`;
+}
+
+/** The directory Hermes discovers: it carries both the manifest and the module. */
+export function pluginDir(project: Project): string {
+  return `${HOST_DIR}/${pluginPackage(project)}`;
+}
+
+/** A plugin may invent its own toolset name; it is enabled by default (brief §9). */
+export function toolset(project: Project): string {
+  return project.tool.hermes?.toolset ?? projectName.hermesToolset(project.identity.name);
+}
+
+function verdict(operation: Operation, project: Project): Verdict {
+  if (!isPortable(operation)) return { kind: "excluded", reason: "excluded:implement-in-hosts" };
+  return project.tool.binding === "python"
+    ? { kind: "native" }
+    : { kind: "degraded", reason: "degraded:out-of-process" };
+}
+
+/** Config keys reach the core as environment variables, upper-cased, as both bindings read them. */
+
+interface EnvEntry {
+  name: string;
+  description: string;
+  secret?: boolean;
+  url?: string;
+}
+
+/**
+ * `requires_env` / `optional_env`, from the one credential declaration in `tool.json`
+ * (§6). Hermes accepts a bare name or the rich `{name, description, secret, url}` form its
+ * config UI prompts from (`hermes_cli/config.py`, labelled by the variable name); the rich
+ * form is what carries the `x-toolfactory` metadata across.
+ */
+export function envDeclarations(project: Project): { required: EnvEntry[]; optional: EnvEntry[] } {
+  const required = new Set(requiredConfig(project));
+  const entries = Object.entries(configProperties(project)).map(([key, property]) => {
+    const meta = (property["x-toolfactory"] ?? {}) as { url?: string };
+    const description = typeof property.description === "string" ? property.description : key;
+    return {
+      // Only schema-required keys are required by Hermes; an optional secret stays optional.
+      needed: required.has(key),
+      entry: compact({
+        name: envName(key),
+        description,
+        // `hermes plugins install` masks the prompt on `secret`; config.py accepts either key.
+        secret: isSensitive(property) || undefined,
+        url: meta.url,
+      }) as EnvEntry,
+    };
+  });
+  return {
+    required: entries.filter((e) => e.needed).map((e) => e.entry),
+    optional: entries.filter((e) => !e.needed).map((e) => e.entry),
+  };
+}
+
+/** `<name>>=<version>,<<next major>` — the upper bound Plugin Doctor asks every pin to carry. */
+function pinnedCore(project: Project): string | undefined {
+  const version = project.identity.version;
+  if (!version) return undefined;
+  const major = Number(version.split(".")[0]);
+  const upper = Number.isFinite(major) ? `,<${major + 1}` : "";
+  return `${pypiName(project)}>=${version}${upper}`;
+}
+
+/** The tool table Hermes registers: `{name, description, parameters}` per `register_tool`. */
+export function toolSchemas(operations: Operation[]): Record<string, unknown>[] {
+  return operations.map((operation) => {
+    // `parameters` is handed straight to the model provider; `$schema` is not a function-call key.
+    const { $schema, ...parameters } = operation.inputSchema;
+    return {
+      name: operation.name,
+      description: operation.description ?? operation.name,
+      parameters,
+    };
+  });
+}
+
+/**
+ * The one operation `hosts/hermes/tests/test_plugin.py` calls for real: the first callable one
+ * `tool.json` `tests.examples` supplies complete arguments for — the same predicate
+ * `openclaw-native.ts`'s `e2eCase` uses, so one declaration drives both credential-free suites —
+ * else the first that needs none. An operation whose required input nobody supplied gets no
+ * lane rather than a call guaranteed to fail. `marker` mirrors the OpenClaw e2e gate: a name the
+ * operation's own output schema promises, so the assertion means the handler actually ran rather
+ * than merely not throwing.
+ */
+function testCase(
+  project: Project,
+  operations: Operation[],
+): { operation: Operation; args: Record<string, unknown>; marker: string | undefined } | undefined {
+  const examples = project.tool.tests.examples;
+  const callable = (candidate: Operation) => {
+    const args = examples[candidate.name] ?? {};
+    const required = candidate.inputSchema.required;
+    return (Array.isArray(required) ? (required as string[]) : []).every((key) => key in args);
+  };
+  const candidates = operations.filter(callable);
+  const operation = candidates.find((candidate) => examples[candidate.name]) ?? candidates[0];
+  if (!operation) return undefined;
+  const schema = operation.outputSchema ?? {};
+  const required = Array.isArray(schema.required) ? (schema.required as string[]) : [];
+  const properties = Object.keys((schema.properties ?? {}) as Record<string, unknown>);
+  return { operation, args: examples[operation.name] ?? {}, marker: required[0] ?? properties[0] };
+}
+
+/** A Python identifier from an operation name, for the generated test function's suffix. */
+function pySafeName(name: string): string {
+  return name.replace(/[^A-Za-z0-9_]/g, "_");
+}
+
+/**
+ * `hosts/hermes/tests/test_plugin.py`. See the module doc comment for why this exists instead of
+ * `hermes_cli.plugin_dev`.
+ */
+function testPluginPy(project: Project, operations: Operation[]): string {
+  const pkg = pluginPackage(project);
+  const names = operations.map((operation) => operation.name);
+  const kase = testCase(project, operations);
+  const handlerTest = kase
+    ? `
+
+
+def test_${pySafeName(kase.operation.name)}_handler_returns_the_real_result() -> None:
+    with tempfile.TemporaryDirectory() as tmp:
+        ctx = FakeCtx(Path(tmp))
+        register(ctx)
+        handler = next(r["handler"] for r in ctx.registrations if r["name"] == ${JSON.stringify(kase.operation.name)})
+        result = json.loads(handler(${JSON.stringify(kase.args)}))
+        assert "error" not in result${kase.marker ? `\n        assert ${JSON.stringify(kase.marker)} in result` : ""}`
+    : "";
+  return `${HEADER}"""Registers the generated plugin through a fake \`PluginContext\` and, when \`tool.json\`
+\`tests.examples\` supplies one, calls a real handler — everything \`hermes plugins doctor --ci\`
+proves for registration, plus the one call doctor never makes. No Hermes import: needs only this
+checkout${project.tool.binding === "python" ? "" : " and Node, which the shim handler spawns"}.
+"""
+
+from __future__ import annotations
+
+import json
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from ${pkg} import register
+
+
+class _State:
+    def __init__(self, data_dir: Path) -> None:
+        self.data_dir = data_dir
+
+
+class FakeCtx:
+    """The slice of \`hermes_cli.plugins.PluginContext\` that \`register(ctx)\` touches."""
+
+    def __init__(self, data_dir: Path) -> None:
+        self.state = _State(data_dir)
+        self.registrations: list[dict[str, Any]] = []
+
+    def register_tool(self, **kwargs: Any) -> None:
+        self.registrations.append(kwargs)
+
+
+def test_register_adds_every_declared_tool() -> None:
+    with tempfile.TemporaryDirectory() as tmp:
+        ctx = FakeCtx(Path(tmp))
+        register(ctx)
+        assert [r["name"] for r in ctx.registrations] == ${JSON.stringify(names)}${handlerTest}
+`;
+}
+
+function manifest(project: Project, operations: Operation[]): string {
+  const { identity } = project;
+  const { required, optional } = envDeclarations(project);
+  const shim = project.tool.binding !== "python";
+  if (shim) {
+    optional.push({
+      name: rootEnvName(project),
+      description: `Path to the ${identity.name} checkout the kernel CLI runs from (default: the plugin's own repository).`,
+    });
+  }
+  const core = project.tool.binding === "python" ? pinnedCore(project) : undefined;
+  const author = identity.author?.name
+    ? [identity.author.name, identity.author.email].filter(Boolean).join(", ")
+    : undefined;
+  const document = compact({
+    manifest_version: MANIFEST_VERSION,
+    name: identity.name,
+    version: identity.version,
+    description: identity.description,
+    author,
+    license: identity.license,
+    homepage: identity.homepage,
+    provides_tools: operations.map((operation) => operation.name),
+    requires_env: required.length ? required : undefined,
+    optional_env: optional.length ? optional : undefined,
+    python_dependencies: core ? [core] : undefined,
+  });
+  return `${HEADER}${yaml(document)}`;
+}
+
+function pyproject(project: Project): string {
+  const core = pinnedCore(project) ?? pypiName(project);
+  const python = project.tool.binding === "python";
+  const document = compact({
+    project: compact({
+      name: `${pypiName(project)}-hermes-plugin`,
+      version: project.identity.version,
+      description: `${project.identity.description ?? project.identity.name} — Hermes plugin.`,
+      license: project.identity.license,
+      "requires-python": ">=3.11",
+      // The shim variant spawns the kernel CLI, so it depends on nothing importable.
+      dependencies: python ? [core] : [],
+      "entry-points": {
+        "hermes_agent.plugins": { [project.identity.name]: `${pluginPackage(project)}:register` },
+      },
+    }),
+    "build-system": { requires: ["hatchling"], "build-backend": "hatchling.build" },
+    tool: compact({
+      hatch: { build: { targets: { wheel: { packages: [pluginPackage(project)] } } } },
+      // Develop against the checkout; the pin above is what the published wheel resolves.
+      uv: python
+        ? { sources: { [pypiName(project)]: { path: "../..", editable: true } } }
+        : undefined,
+    }),
+  });
+  return `${toml(document)}\n`;
+}
+
+/** isort order: plain `import` before `from`, alphabetical within each. */
+function sortImports(lines: string[]): string {
+  const rank = (line: string) => (line.startsWith("import ") ? 0 : 1);
+  return [...lines].sort((a, b) => rank(a) - rank(b) || a.localeCompare(b)).join("\n");
+}
+
+/** The module's import block: the standard library, then everything the core variant needs. */
+function importBlock(core: PluginCore): string {
+  const stdlib = ["import json", "import os", "from typing import Any, Callable", ...core.stdlib];
+  return [sortImports(stdlib), core.external.length ? sortImports(core.external) : ""]
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+interface PluginCore {
+  /** Standard-library statements, merged into the module's stdlib group. */
+  stdlib: string[];
+  /** Everything outside the standard library, merged into the group after it. */
+  external: string[];
+  body: string;
+}
+
+/** Python core: the handler calls the author's own operation in-process. */
+function pythonCore(project: Project): PluginCore {
+  const pkg = projectName.pythonPackage(project.identity.name);
+  return {
+    stdlib: ["import asyncio", "import inspect"],
+    external: [
+      "from pydantic import BaseModel",
+      `from ${pkg}.ops import OPERATIONS`,
+      `from ${pkg}.toolfactory.config import context`,
+    ],
+    body: `def _operation(name: str) -> Any:
+    """Fail loudly if the core package and this plugin disagree on the operations."""
+    for operation in OPERATIONS:
+        if operation.name == name:
+            return operation
+    raise LookupError(f"operation {name} is missing from the core package")
+
+
+def _handler(name: str) -> Callable[..., str]:
+    operation = _operation(name)
+
+    def call(args: dict, **_kwargs: Any) -> str:
+        try:
+            result = operation.handler(operation.input(**args), context())
+            if inspect.isawaitable(result):
+                result = asyncio.run(result)
+            if isinstance(result, BaseModel):
+                result = result.model_dump(mode="json")
+            return json.dumps(result, default=str)
+        except Exception as exc:
+            return json.dumps({"error": str(exc)})
+
+    call.__name__ = f"{name}_handler"
+    return call`,
+  };
+}
+
+/** TypeScript core: the handler shells out to the kernel CLI — `degraded:out-of-process`. */
+function typescriptCore(project: Project): PluginCore {
+  return {
+    stdlib: ["import subprocess", "from pathlib import Path"],
+    external: [],
+    body: `#: The plugin sits at <repo>/${HOST_DIR}/<package>, so in a checkout the root is
+#: three levels up; once Hermes has copied the plugin into $HERMES_HOME/plugins,
+#: ${rootEnvName(project)} is how the operator says where it went.
+_ROOT = os.environ.get(${JSON.stringify(rootEnvName(project))})
+REPO_ROOT = Path(_ROOT) if _ROOT else Path(__file__).resolve().parents[3]
+KERNEL = ["node", "--import", "tsx", "${KERNEL_DIR}/cli.ts"]
+
+
+
+def _handler(name: str) -> Callable[..., str]:
+    def call(args: dict, **_kwargs: Any) -> str:
+        try:
+            done = subprocess.run(
+                [*KERNEL, name, "--json", json.dumps(args)],
+                cwd=REPO_ROOT,
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            return done.stdout.strip()
+        except subprocess.CalledProcessError as exc:
+            detail = (exc.stderr or exc.stdout or "").strip()
+            return json.dumps({"error": detail or f"{name} exited {exc.returncode}"})
+        except Exception as exc:
+            return json.dumps({"error": str(exc)})
+
+    call.__name__ = f"{name}_handler"
+    return call`,
+  };
+}
+
+function initPy(project: Project, operations: Operation[]): string {
+  const core = project.tool.binding === "python" ? pythonCore(project) : typescriptCore(project);
+  const names = envDeclarations(project).required.map((entry) => entry.name);
+  return `${HEADER}"""Hermes plugin for ${project.identity.name}, registered through PluginContext.
+
+Every handler returns a JSON string and never raises: Hermes dispatches tool
+calls without a guard of its own, so an exception here escapes into the turn.
+"""
+
+from __future__ import annotations
+
+${importBlock(core)}
+
+TOOLSET = ${JSON.stringify(toolset(project))}
+REQUIRES_ENV = ${JSON.stringify(names)}
+TOOLS = json.loads(
+    r"""${JSON.stringify(toolSchemas(operations), null, 2)}"""
+)
+
+
+def _ready() -> bool:
+    """Hermes gates dispatch on this: every declared credential has to be present."""
+    return all(os.environ.get(name) for name in REQUIRES_ENV)
+
+
+${core.body}
+
+
+def register(ctx: Any) -> None:
+    # Hermes' own per-plugin data directory, through the variable every host uses.
+    os.environ.setdefault(${JSON.stringify(dataDirEnvName(project))}, str(ctx.state.data_dir))
+    for schema in TOOLS:
+        ctx.register_tool(
+            name=schema["name"],
+            toolset=TOOLSET,
+            schema=schema,
+            handler=_handler(schema["name"]),
+            check_fn=_ready,
+            requires_env=list(REQUIRES_ENV),
+            description=schema["description"],
+        )
+`;
+}
+
+function readme(project: Project, operations: Operation[]): string {
+  const shim = project.tool.binding !== "python";
+  const excluded = project.operations.filter(
+    (operation) => verdict(operation, project).kind === "excluded",
+  );
+  const pkg = pluginPackage(project);
+  const lines = [
+    `# ${project.identity.name} — Hermes plugin`,
+    "",
+    `Generated by toolfactory from \`${project.tool.identity}\` and \`dev.toolfactory/ops.json\`.`,
+    `\`${pkg}/\` is a Hermes directory plugin (\`plugin.yaml\` + \`__init__.py\`) and a Python`,
+    "package at the same time, so the same code loads from a checkout and from PyPI.",
+    "",
+    "## Validate",
+    "",
+    "```bash",
+    `hermes plugins doctor ${pluginDir(project)} --ci`,
+    "```",
+    "",
+    "## Install",
+    "",
+    "```bash",
+    `pip install .            # registers the hermes_agent.plugins entry point`,
+    `hermes plugins enable ${project.identity.name}`,
+    "```",
+    "",
+    "Developing against this checkout, without publishing a package first:",
+    "",
+    "```bash",
+    `hermes plugins install file://<repo>#${pluginDir(project)} --force`,
+    "```",
+    "",
+    "Hermes copies from that URL rather than linking it — there is no dev-link mode — so re-run",
+    "the command above after every change. `file://` sources (like `http://`) trigger a security",
+    "warning at install time; that is expected for a local checkout, not a sign anything is",
+    "wrong. Each `hermes` invocation is a fresh process that already re-reads the plugin, so",
+    "nothing needs restarting; `hermes gateway restart` only matters if the long-running",
+    "messaging gateway (Telegram, Discord, WhatsApp, …), not the CLI itself, is what needs the",
+    "new registration.",
+    "",
+    `Remove it cleanly with \`hermes plugins remove ${project.identity.name}\` (aliases \`rm\`,`,
+    "`uninstall`) — it deletes Hermes' own copy and never touches this checkout.",
+    "",
+    "## Validate without Hermes",
+    "",
+    "```bash",
+    "cd hosts/hermes && uv run --with pytest pytest -q",
+    "```",
+    "",
+    "Registers the generated plugin through a fake `PluginContext` and calls one handler for",
+    "real — the same behaviour `hermes plugins doctor --ci` proves for registration, plus the",
+    "call doctor never makes, with no Hermes install required.",
+    "",
+    "## Tools",
+    "",
+    ...(operations.length
+      ? operations.map(
+          (operation) =>
+            `- \`${operation.name}\` — ${operation.description ?? "no description"} (${
+              shim ? "degraded:out-of-process" : "native"
+            })`,
+        )
+      : ["_No operation reaches this surface yet._"]),
+    "",
+    `All of them register into the \`${toolset(project)}\` toolset.`,
+    "",
+  ];
+  if (shim) {
+    lines.push(
+      `Shim variant: the core is ${project.tool.binding}, so each handler spawns the kernel CLI`,
+      "from the repository root. Registration and configuration are native; nothing is borrowed",
+      "in-process. A native plugin requires a Python core.",
+      "",
+      `Installed outside the checkout, set \`${rootEnvName(project)}\` to the repository path — the`,
+      "default is resolved relative to this directory, which only holds inside the repository.",
+      "",
+    );
+  }
+  if (excluded.length) {
+    lines.push(
+      "## Not generated — `excluded:implement-in-hosts`",
+      "",
+      "These operations declare a capability no portable core can satisfy, so toolfactory omits",
+      "them rather than shipping a tool that fails at call time. This package is the escape",
+      "hatch: write them here by hand against the full PluginContext, then run `toolfactory",
+      `adopt ${pluginDir(project)}/__init__.py\` so your edits are never regenerated away.`,
+      "",
+      ...excluded.map(
+        (operation) => `- \`${operation.name}\` — requires ${operation.requires.join(", ")}`,
+      ),
+      "",
+    );
+  }
+  return lines.join("\n");
+}
+
+export const surface: Surface = {
+  id: "hermes-native",
+  plan(project) {
+    const operations = includedOperations(project, surface);
+    const dir = pluginDir(project);
+    return [
+      { kind: "file", path: `${dir}/plugin.yaml`, content: manifest(project, operations) },
+      { kind: "file", path: `${dir}/__init__.py`, content: initPy(project, operations) },
+      { kind: "file", path: `${HOST_DIR}/pyproject.toml`, content: pyproject(project) },
+      { kind: "file", path: `${HOST_DIR}/README.md`, content: readme(project, operations) },
+      {
+        kind: "file",
+        path: `${HOST_DIR}/tests/test_plugin.py`,
+        content: testPluginPy(project, operations),
+      },
+    ];
+  },
+  validate(project) {
+    return [
+      {
+        // Registration and one real handler call, with no Hermes import and therefore no
+        // Hermes install — safe to run everywhere `uv` already runs.
+        label: "hermes plugin behaviour",
+        command: "uv",
+        args: ["run", "--with", "pytest", "pytest", "-q"],
+        cwd: join(project.root, HOST_DIR),
+      },
+      {
+        // Loads the plugin through Hermes' real discovery, import and registration path,
+        // under a temporary HERMES_HOME with outbound sockets denied.
+        label: "hermes plugins doctor",
+        command: "hermes",
+        args: ["plugins", "doctor", pluginDir(project), "--ci"],
+        cwd: project.root,
+      },
+    ];
+  },
+  verdict,
+};

package/src/surfaces/kernel.ts

@@ -0,0 +1,68 @@
+/**
+ * The kernel surfaces: `mcp` (the MCP server over stdio) and `cli` (one subcommand per
+ * operation plus `mcp`). Both are the binding's generated files; the binding owns the
+ * templates, these surfaces own the verdicts and the smoke commands.
+ */
+import { getBinding } from "../bindings/index.js";
+import type { Project, Surface } from "../model.js";
+import { TOOLFACTORY_DIR } from "../project/lock.js";
+import { cliVerdict, json, mcpVerdict } from "./shared.js";
+
+/** MCP Inspector session config pointing at the dev kernel (no build step). */
+export const INSPECTOR_CONFIG_PATH = `${TOOLFACTORY_DIR}/inspector.json`;
+
+function inspectorConfig(project: Project): string {
+  const launch = getBinding(project.tool.binding).kernelCommand(project);
+  return json({ mcpServers: { [project.identity.name]: launch } });
+}
+
+export const mcp: Surface = {
+  id: "mcp",
+  // The kernel itself is generated for every tool (plan.ts); this surface ships it.
+  plan(project) {
+    // A build output: it points at absolute-free launch args, is gitignored, and is rebuilt.
+    return [
+      {
+        kind: "file",
+        path: INSPECTOR_CONFIG_PATH,
+        content: inspectorConfig(project),
+        output: true,
+      },
+    ];
+  },
+  validate(project) {
+    return [
+      {
+        label: "mcp-inspector tools/list",
+        command: "npx",
+        args: [
+          "--yes",
+          "@modelcontextprotocol/inspector",
+          "--cli",
+          "--config",
+          INSPECTOR_CONFIG_PATH,
+          "--server",
+          project.identity.name,
+          "--method",
+          "tools/list",
+        ],
+        cwd: project.root,
+      },
+    ];
+  },
+  verdict: mcpVerdict,
+};
+
+export const cli: Surface = {
+  id: "cli",
+  plan(project) {
+    return getBinding(project.tool.binding).cli(project);
+  },
+  validate(project) {
+    const launch = getBinding(project.tool.binding).cliCommand(project);
+    return [
+      { label: "cli --help", ...launch, args: [...launch.args, "--help"], cwd: project.root },
+    ];
+  },
+  verdict: cliVerdict,
+};