toolfactory 0.1.1

package/dist/surfaces/hermes-native.js

@@ -0,0 +1,507 @@
+/**
+ * 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 } 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() {
+    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) {
+    return `${projectName.pythonPackage(project.identity.name)}_hermes`;
+}
+/** The directory Hermes discovers: it carries both the manifest and the module. */
+export function pluginDir(project) {
+    return `${HOST_DIR}/${pluginPackage(project)}`;
+}
+/** A plugin may invent its own toolset name; it is enabled by default (brief §9). */
+export function toolset(project) {
+    return project.tool.hermes?.toolset ?? projectName.hermesToolset(project.identity.name);
+}
+function verdict(operation, project) {
+    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" };
+}
+/**
+ * `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) {
+    const required = new Set(requiredConfig(project));
+    const entries = Object.entries(configProperties(project)).map(([key, property]) => {
+        const meta = (property["x-toolfactory"] ?? {});
+        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,
+            }),
+        };
+    });
+    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) {
+    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) {
+    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, operations) {
+    const examples = project.tool.tests.examples;
+    const callable = (candidate) => {
+        const args = examples[candidate.name] ?? {};
+        const required = candidate.inputSchema.required;
+        return (Array.isArray(required) ? required : []).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 : [];
+    const properties = Object.keys((schema.properties ?? {}));
+    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) {
+    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, operations) {
+    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, operations) {
+    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) {
+    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) {
+    const rank = (line) => (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) {
+    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");
+}
+/** Python core: the handler calls the author's own operation in-process. */
+function pythonCore(project) {
+    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) {
+    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, operations) {
+    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, operations) {
+    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 = {
+    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/dist/surfaces/hermes-native.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/surfaces/hermes-native.test.js

@@ -0,0 +1,156 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { parse as parseToml } from "smol-toml";
+import { describe, expect, it } from "vitest";
+import { parse as parseYaml } from "yaml";
+import { HOST_DIR, pluginDir, surface } from "./hermes-native.js";
+const echo = {
+    name: "echo",
+    description: "Return the text you pass in.",
+    inputSchema: {
+        $schema: "https://json-schema.org/draft/2020-12/schema",
+        type: "object",
+        properties: { text: { type: "string" } },
+        required: ["text"],
+    },
+    outputSchema: { type: "object", properties: { text: { type: "string" } }, required: ["text"] },
+    requires: [],
+};
+const shoot = { name: "shoot", inputSchema: { type: "object" }, requires: ["browser"] };
+function project(overrides = {}) {
+    return {
+        root: "/repo",
+        tool: {
+            schemaVersion: 1,
+            identity: "package.json",
+            binding: "typescript",
+            surfaces: ["hermes-native", "cli"],
+            bundle: { runtime: "package" },
+            tests: { examples: { echo: { text: "hi" } } },
+            config: {
+                type: "object",
+                properties: {
+                    apiKey: {
+                        description: "Acme key",
+                        "x-toolfactory": { sensitive: true, url: "https://a" },
+                    },
+                    region: { description: "Acme region" },
+                },
+                required: ["apiKey"],
+            },
+            ...overrides.tool,
+        },
+        identity: { name: "hello", version: "1.2.0", description: "Say hello" },
+        identityExtra: {},
+        operations: [echo, shoot],
+        toolfactoryVersion: "0.1.0",
+        ...overrides,
+    };
+}
+function emitted(target) {
+    return Object.fromEntries(surface.plan(target).map((file) => [file.path, file.kind === "file" ? file.content : ""]));
+}
+const python = project({ tool: { ...project().tool, binding: "python" } });
+describe("hermes-native", () => {
+    it("projects the manifest Hermes parses and the credentials it prompts for", () => {
+        const files = emitted(project());
+        const manifest = parseYaml(files[`${pluginDir(project())}/plugin.yaml`] ?? "");
+        // 1, not the loader's newer-supported 2: `hermes plugins install`'s own cap is still stuck
+        // at 1 and rejects a v2 manifest outright, even though the loader and `doctor` accept it.
+        expect(manifest.manifest_version).toBe(1);
+        expect(manifest.name).toBe("hello");
+        // Only what the surface can actually run: `shoot` is excluded, so it is never advertised.
+        expect(manifest.provides_tools).toEqual(["echo"]);
+        expect(surface.verdict?.(shoot, project())).toEqual({
+            kind: "excluded",
+            reason: "excluded:implement-in-hosts",
+        });
+        // One credential declaration becomes the rich env form Hermes' config UI prompts from.
+        expect(manifest.requires_env).toEqual([
+            {
+                name: "APIKEY",
+                description: "Acme key",
+                secret: true,
+                url: "https://a",
+            },
+        ]);
+        expect(manifest.optional_env.map((entry) => entry.name)).toEqual([
+            "REGION",
+            "HELLO_ROOT",
+        ]);
+        const pyproject = parseToml(files[`${HOST_DIR}/pyproject.toml`] ?? "");
+        expect(pyproject.project["entry-points"]["hermes_agent.plugins"]).toEqual({
+            hello: "hello_hermes:register",
+        });
+    });
+    it("shims a TypeScript core out of process and calls a Python core in it", () => {
+        const shim = emitted(project())[`${pluginDir(project())}/__init__.py`] ?? "";
+        expect(surface.verdict?.(echo, project())).toEqual({
+            kind: "degraded",
+            reason: "degraded:out-of-process",
+        });
+        expect(shim).toContain('KERNEL = ["node", "--import", "tsx", "src/toolfactory/cli.ts"]');
+        expect(shim).toContain('_ROOT = os.environ.get("HELLO_ROOT")');
+        // Hermes' own per-plugin data directory reaches the kernel through the shared variable.
+        expect(shim).toContain('os.environ.setdefault("HELLO_DATA_DIR", str(ctx.state.data_dir))');
+        const native = emitted(python)[`${pluginDir(python)}/__init__.py`] ?? "";
+        expect(surface.verdict?.(echo, python)).toEqual({ kind: "native" });
+        expect(native).toContain("from hello.ops import OPERATIONS");
+        expect(native).not.toContain("subprocess");
+        // The published wheel resolves the pin; the checkout resolves the uv path source.
+        const pyproject = parseToml(emitted(python)[`${HOST_DIR}/pyproject.toml`] ?? "");
+        expect(pyproject.project.dependencies).toEqual(["hello>=1.2.0,<2"]);
+        expect(pyproject.tool.uv.sources.hello).toEqual({ path: "../..", editable: true });
+    });
+    it("emits a fake-ctx test that registers and calls a real handler, no Hermes import", () => {
+        const shim = emitted(project())[`${HOST_DIR}/tests/test_plugin.py`] ?? "";
+        expect(shim).not.toMatch(/^\s*(import|from) hermes/m);
+        expect(shim).toContain("from hello_hermes import register");
+        expect(shim).toContain("def register_tool(self, **kwargs: Any) -> None:");
+        expect(shim).toContain("self.state = _State(data_dir)");
+        // `shoot` is excluded (browser), so only `echo` is registered and only `echo` is callable.
+        expect(shim).toContain('assert [r["name"] for r in ctx.registrations] == ["echo"]');
+        expect(shim).toContain('r["name"] == "echo"');
+        expect(shim).toContain('handler({"text":"hi"})');
+        // The marker comes from `echo`'s own output schema, not a hardcoded assumption.
+        expect(shim).toContain('assert "text" in result');
+        expect(shim).toContain("checkout and Node, which the shim handler spawns");
+        const native = emitted(python)[`${HOST_DIR}/tests/test_plugin.py`] ?? "";
+        expect(native).toContain("from hello_hermes import register");
+        expect(native).not.toContain("and Node");
+    });
+});
+function hasHermes() {
+    try {
+        execFileSync("hermes", ["--version"], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The only claim that matters: Hermes' own runtime discovers, imports and registers this. */
+describe.skipIf(!hasHermes())("hermes plugins doctor", () => {
+    it("loads and registers the generated plugin", () => {
+        const root = mkdtempSync(join(tmpdir(), "toolfactory-hermes-"));
+        try {
+            for (const file of surface.plan(project())) {
+                if (file.kind !== "file")
+                    continue;
+                mkdirSync(dirname(join(root, file.path)), { recursive: true });
+                writeFileSync(join(root, file.path), file.content);
+            }
+            const commands = surface.validate?.({ ...project(), root }) ?? [];
+            const command = commands.find((c) => c.label === "hermes plugins doctor");
+            if (!command)
+                throw new Error("the hermes surface no longer declares a doctor validator");
+            const output = execFileSync(command.command, command.args, { cwd: root, encoding: "utf8" });
+            expect(output).toContain("registrations: 1 tool(s)");
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    });
+});

package/dist/surfaces/kernel.d.ts

@@ -0,0 +1,5 @@
+import type { Surface } from "../model.js";
+/** MCP Inspector session config pointing at the dev kernel (no build step). */
+export declare const INSPECTOR_CONFIG_PATH = "dev.toolfactory/inspector.json";
+export declare const mcp: Surface;
+export declare const cli: Surface;