toolfactory 0.1.1

package/dist/surfaces/openclaw-native.js

@@ -0,0 +1,956 @@
+/**
+ * OpenClaw native plugin — the §4.4 escape hatch. The package under `hosts/openclaw/` is the
+ * scaffold `openclaw plugins init <id> --type tool` writes, with the tool list projected from
+ * the operations OpenClaw can actually run.
+ *
+ * A plugin that contributes something other than tools (a realtime-voice provider, a speech
+ * provider) is the same package: `defineToolPlugin` keeps the upstream build/validate gates,
+ * and the host registrations it declares in `tool.json` (`openclaw.registers`) drive the
+ * manifest contracts, the plugin inspector's expectations and the generated test. The one
+ * thing toolfactory cannot write is the registration body, so `src/index.ts` is a region file:
+ * toolfactory owns the entry, the author owns the tail that wires the registrations.
+ *
+ * §8 C2 ("mirror scaffolds by execution, not transcription"): `plan()` is pure and therefore
+ * has to carry the scaffold's constants, so `validate()` runs the real generator and fails when
+ * any of them drifted. Every pinned value lives in OPENCLAW_SCAFFOLD below and nowhere else.
+ */
+import { execArgv } from "node:process";
+import { KERNEL_DIR } from "../bindings/typescript.js";
+import { DRIFT_ENTRY } from "../hosts/openclaw.js";
+import { projectName } from "../identity/name.js";
+import { isPortable } from "../model.js";
+import { includedOperations } from "../report/coverage.js";
+import { compact, configProperties, dataDirEnvName, envName, has, isSensitive, json, npmName, rootEnvName, } from "./shared.js";
+/** Transcribed from `openclaw plugins init --type tool`; `validate()` proves them still current. */
+export const OPENCLAW_SCAFFOLD = {
+    /** The OpenClaw release the scaffold was taken from (`package.json openclaw.build`). */
+    openclawVersion: "2026.9.2",
+    /** `peerDependencies.openclaw` and `openclaw.compat.pluginApi`. */
+    pluginApi: ">=2026.5.17",
+    private: true,
+    scripts: {
+        build: "tsc -p tsconfig.json",
+        "plugin:build": "npm run build && openclaw plugins build --entry ./dist/index.js",
+        "plugin:validate": "npm run build && openclaw plugins validate --entry ./dist/index.js",
+        test: "vitest run --config ./vitest.config.ts",
+    },
+    files: ["dist", "openclaw.plugin.json", "README.md"],
+    dependencies: { typebox: "^1.1.38" },
+    devDependencies: { openclaw: "latest", typescript: "^5.9.0", vitest: "^3.2.0" },
+    tsconfig: {
+        compilerOptions: {
+            target: "ES2022",
+            module: "NodeNext",
+            moduleResolution: "NodeNext",
+            strict: true,
+            declaration: true,
+            outDir: "dist",
+            skipLibCheck: true,
+        },
+        include: ["src/**/*.ts"],
+    },
+    vitestConfig: `import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["src/**/*.test.ts"],
+  },
+});
+`,
+    /** Entry module, relative to the plugin root, as `openclaw.extensions` records it. */
+    entry: "./dist/index.js",
+    sdkModule: "openclaw/plugin-sdk/tool-plugin",
+    /** `resolveStateDir()`: the directory OpenClaw keeps its own state in. */
+    statePathsModule: "openclaw/plugin-sdk/state-paths",
+    /** Where `OpenClawPluginApi` and every registrar's parameter type come from. */
+    entryModule: "openclaw/plugin-sdk/plugin-entry",
+    /** `pluginInspector` in package.json, as `--type provider` writes it. */
+    inspector: { version: 1, priority: "high", seams: ["plugin-runtime"], sourceRoot: "." },
+};
+/**
+ * toolfactory's additions over the upstream scaffold. Each is a key `openclaw plugins init` does
+ * not write, which is why the drift check (`src/hosts/openclaw.ts`) requires every scaffold key to
+ * survive into the projection but allows extra ones: upstream stays the source of truth for
+ * everything it does write.
+ */
+export const OPENCLAW_ADDITIONS = {
+    /** Without it `tsc` emits a `dist/` from source that failed type-checking. */
+    compilerOptions: { noEmitOnError: true },
+    /** The scripted-model end-to-end lane; OpenClaw's own QA lane drives OpenClaw through aimock. */
+    aimock: "^1.39.0",
+    e2eScript: "npm run build && vitest run --config ./vitest.e2e.config.ts",
+    /**
+     * OpenClaw's install-time safety scan rejects a `node_modules` symlink whose target is outside
+     * the install root (`src/plugins/install-security-scan.runtime.ts`), which is exactly what npm
+     * makes of the `file:../..` core dependency. `install-links` materialises it as a real directory.
+     */
+    npmrc: `# OpenClaw's install-time safety scan refuses a node_modules symlink pointing outside the
+# install root, which is what npm makes of a file: dependency. Materialise it instead.
+install-links=true
+`,
+    /** The scripted model the e2e fixtures answer as; any id works, nothing resolves it upstream. */
+    model: "openai/gpt-5.6-luna",
+};
+export const HOST_DIR = "hosts/openclaw";
+const HEADER = "// Generated by toolfactory. Do not edit; run `toolfactory build` to regenerate.\n";
+/** The region of `src/index.ts` toolfactory owns; the tail below the end marker is the author's. */
+export const ENTRY_BEGIN = "// tf:entry";
+export const ENTRY_END = "// /tf:entry";
+/** `titleFromId` from OpenClaw's scaffold generator. */
+export function displayName(id) {
+    return projectName.display(id);
+}
+/** Host registrations the plugin declares beyond tools. */
+export function registrations(project) {
+    return project.tool.openclaw?.registers ?? [];
+}
+/**
+ * The gateway route and the Control UI tab the plugin adds when the tool also has a `web`
+ * surface. Only for the in-process binding: the route hands requests to the core package's own
+ * exported handler, so `<prefix>/mcp` is answered by the same operations without a second
+ * listener, and `<prefix>/` is the built page. A Python tool's plugin is an out-of-process
+ * shim with no such handler to mount, so it gets the README's `mcp --http --open` line instead.
+ */
+function servesWeb(project, operations) {
+    return has(project, "web") && project.tool.binding === "typescript" && operations.length > 0;
+}
+/** The prefix the route claims and the tab points at; one constant, three uses. */
+function webPath(project) {
+    return `/plugins/${project.identity.name}/web`;
+}
+/** `activation` for both the entry and the manifest; OpenClaw's own default is startup. */
+export function activation(project) {
+    return project.tool.openclaw?.activation ?? { onStartup: true };
+}
+/**
+ * OpenClaw stores `normalizeJsonSchema(schema)` in the plugin manifest, so emit schemas that are
+ * already in that shape and `openclaw plugins build --check` stays a byte-for-byte agreement.
+ */
+export function normalizeSchema(value) {
+    if (Array.isArray(value))
+        return value.map(normalizeSchema);
+    if (!value || typeof value !== "object")
+        return value;
+    const record = { ...value };
+    delete record.$schema;
+    for (const [key, nested] of Object.entries(record))
+        record[key] = normalizeSchema(nested);
+    const propertyNames = record.propertyNames;
+    if (propertyNames && typeof propertyNames === "object" && propertyNames.type === "string") {
+        delete record.propertyNames;
+    }
+    if (Array.isArray(record.required) && record.required.length === 0)
+        delete record.required;
+    return record;
+}
+/** A JSON value as a TypeScript literal, re-indented to sit at `indent` columns. */
+function literal(value, indent) {
+    return JSON.stringify(value, null, 2).replaceAll("\n", `\n${" ".repeat(indent)}`);
+}
+/** `EMPTY_TOOL_PLUGIN_CONFIG_SCHEMA` from the SDK: what a plugin with no config schema reports. */
+const EMPTY_CONFIG_SCHEMA = { type: "object", properties: {}, additionalProperties: false };
+function hasConfig(project) {
+    return Boolean(project.tool.config) && Object.keys(configProperties(project)).length > 0;
+}
+/** The plugin's `configSchema`: the tool's own config schema, or OpenClaw's empty default. */
+export function configSchema(project) {
+    return hasConfig(project)
+        ? normalizeSchema(project.tool.config)
+        : EMPTY_CONFIG_SCHEMA;
+}
+function pluginDescription(project) {
+    return (project.identity.description ?? `Add ${displayName(project.identity.name)} tools to OpenClaw.`);
+}
+function verdict(operation, project) {
+    if (!isPortable(operation))
+        return { kind: "excluded", reason: "excluded:implement-in-hosts" };
+    return project.tool.binding === "typescript"
+        ? { kind: "native" }
+        : { kind: "degraded", reason: "degraded:out-of-process" };
+}
+/** The API range the plugin declares; the author's `pluginApi` wins over the scaffold's. */
+function pluginApi(project) {
+    return project.tool.openclaw?.pluginApi ?? OPENCLAW_SCAFFOLD.pluginApi;
+}
+/** The manifest contract keys the plugin fills: `tools` when it has any, plus every declared one. */
+function contractKeys(project, operations) {
+    const declared = registrations(project).map((registration) => registration.contract);
+    return [...new Set([...(operations.length ? ["tools"] : []), ...declared])];
+}
+/**
+ * The inspector fixture, in the shape `--type provider` writes: it re-derives the registrations
+ * from the source and the contracts from the manifest, so a declaration nobody wired fails
+ * `plugin-inspector inspect --check` by name.
+ */
+/**
+ * Every registrar the entry calls: the ones `tool.json` declares, plus — generated, not
+ * declared — the web tab's route and descriptor. Neither of those is a manifest contract key,
+ * so `contracts` is unchanged; the inspector's static scan is what has to agree.
+ */
+function expectedRegistrations(project, operations) {
+    return [
+        ...registrations(project).map((registration) => registration.api),
+        ...(servesWeb(project, operations) ? ["registerHttpRoute", "registerControlUiDescriptor"] : []),
+    ];
+}
+function pluginInspector(project, operations) {
+    return {
+        version: OPENCLAW_SCAFFOLD.inspector.version,
+        plugin: {
+            id: project.identity.name,
+            priority: OPENCLAW_SCAFFOLD.inspector.priority,
+            seams: OPENCLAW_SCAFFOLD.inspector.seams,
+            sourceRoot: OPENCLAW_SCAFFOLD.inspector.sourceRoot,
+            expect: {
+                registrations: expectedRegistrations(project, operations),
+                manifestContracts: contractKeys(project, operations),
+            },
+        },
+    };
+}
+function packageJson(project, operations, kase) {
+    // The core is imported in-process only when an operation reaches this surface.
+    const core = project.tool.binding === "typescript" && operations.length
+        ? { [npmName(project)]: "file:../.." }
+        : undefined;
+    const extra = project.tool.openclaw;
+    const e2e = kase ? { "test:e2e": OPENCLAW_ADDITIONS.e2eScript } : undefined;
+    return json(compact({
+        name: projectName.openclawPackage(project.identity.name),
+        version: project.identity.version ?? "0.0.0",
+        description: pluginDescription(project),
+        type: "module",
+        private: OPENCLAW_SCAFFOLD.private,
+        scripts: { ...OPENCLAW_SCAFFOLD.scripts, ...e2e },
+        files: OPENCLAW_SCAFFOLD.files,
+        peerDependencies: { openclaw: pluginApi(project), ...extra?.peerDependencies },
+        dependencies: { ...OPENCLAW_SCAFFOLD.dependencies, ...core, ...extra?.dependencies },
+        devDependencies: {
+            ...OPENCLAW_SCAFFOLD.devDependencies,
+            ...(kase ? { "@copilotkit/aimock": OPENCLAW_ADDITIONS.aimock } : {}),
+            ...extra?.devDependencies,
+        },
+        openclaw: {
+            extensions: [OPENCLAW_SCAFFOLD.entry],
+            compat: { pluginApi: pluginApi(project) },
+            build: { openclawVersion: OPENCLAW_SCAFFOLD.openclawVersion },
+        },
+        pluginInspector: expectedRegistrations(project, operations).length
+            ? pluginInspector(project, operations)
+            : undefined,
+    }));
+}
+/**
+ * `openclaw plugins build` regenerates this file; emitting it keeps `--check` green from a clean
+ * tree. The builder owns `contracts.tools` and preserves every other contract key, so a declared
+ * registration's ids survive a rebuild. `uiHints` is manifest-owned too: it is how OpenClaw's
+ * config UI learns which keys to mask, from the same `x-toolfactory.sensitive` declaration every
+ * other surface reads.
+ */
+function pluginManifest(project, operations) {
+    const sensitive = Object.entries(configProperties(project))
+        .filter(([, property]) => isSensitive(property))
+        .map(([key]) => [key, { sensitive: true }]);
+    const declared = registrations(project).map((registration) => [
+        registration.contract,
+        registration.ids,
+    ]);
+    return json(compact({
+        id: project.identity.name,
+        name: displayName(project.identity.name),
+        description: pluginDescription(project),
+        version: project.identity.version ?? "0.0.0",
+        configSchema: configSchema(project),
+        uiHints: sensitive.length ? Object.fromEntries(sensitive) : undefined,
+        activation: activation(project),
+        contracts: {
+            tools: operations.map((operation) => operation.name),
+            ...Object.fromEntries(declared),
+        },
+    }));
+}
+function executeBody(project, operation) {
+    if (project.tool.binding === "typescript") {
+        return `execute: async (params, config) =>
+        operation(${JSON.stringify(operation.name)}).handler(params as never, {
+          config: config as Record<string, string | undefined>,
+          dataDir: dataDir(),
+        }),`;
+    }
+    return `execute: async (params, config) => kernel(${JSON.stringify(operation.name)}, params, config),`;
+}
+function pythonKernel(project) {
+    const module = `${projectName.pythonPackage(project.identity.name)}.toolfactory.cli`;
+    return `const repoRoot =
+  process.env[${JSON.stringify(rootEnvName(project))}] ?? fileURLToPath(new URL("../../../", import.meta.url));
+
+/**
+ * Shim variant: the core is Python, so every call crosses a process boundary and config
+ * travels as environment, exactly as it does for the CLI and the MCP server.
+ */
+async function kernel(name: string, params: unknown, config: unknown): Promise<unknown> {
+  const env: Record<string, string> = { ...(process.env as Record<string, string>) };
+  for (const [key, value] of Object.entries((config ?? {}) as Record<string, unknown>)) {
+    if (value !== undefined && value !== null) env[key.toUpperCase().replace(/[^A-Z0-9]/g, "_")] = String(value);
+  }
+  env[${JSON.stringify(dataDirEnvName(project))}] = dataDir();
+  const { stdout } = await execFileAsync(
+    "uv",
+    ["run", "python", "-m", ${JSON.stringify(module)}, name, "--json", JSON.stringify(params)],
+    { cwd: repoRoot, env },
+  );
+  return JSON.parse(stdout) as unknown;
+}
+`;
+}
+/** `Parameters<OpenClawPluginApi["<api>"]>[0]`: the typed route to a registrar's argument. */
+function registrarType(api) {
+    return `Parameters<OpenClawPluginApi[${JSON.stringify(api)}]>[0]`;
+}
+/** The generated region of `src/index.ts`: imports, the entry, and how to reach it from the tail. */
+function indexRegion(project, operations) {
+    const typescript = project.tool.binding === "typescript";
+    const shim = !typescript && operations.length > 0;
+    const imports = [
+        ...(shim
+            ? [
+                `import { execFile } from "node:child_process";`,
+                `import { fileURLToPath } from "node:url";`,
+                `import { promisify } from "node:util";`,
+            ]
+            : []),
+        ...(operations.length ? [`import { join } from "node:path";`] : []),
+        `import { defineToolPlugin } from ${JSON.stringify(OPENCLAW_SCAFFOLD.sdkModule)};`,
+        ...(operations.length
+            ? [`import { resolveStateDir } from ${JSON.stringify(OPENCLAW_SCAFFOLD.statePathsModule)};`]
+            : []),
+        ...(operations.length || hasConfig(project) ? [`import { Type } from "typebox";`] : []),
+        ...(typescript && operations.length
+            ? [`import { operations } from ${JSON.stringify(`${npmName(project)}/dist/ops.js`)};`]
+            : []),
+        ...(servesWeb(project, operations)
+            ? [
+                `import { handler } from ${JSON.stringify(`${npmName(project)}/dist/${KERNEL_DIR.replace(/^src\//, "")}/mcp.js`)};`,
+                `import type { OpenClawPluginApi } from ${JSON.stringify(OPENCLAW_SCAFFOLD.entryModule)};`,
+            ]
+            : []),
+    ];
+    // The host's own state directory is what the tool keeps its data under; the kernel's
+    // `<N>_DATA_DIR` fallback only has to answer when no host supplies one.
+    const dataDir = !operations.length
+        ? ""
+        : `
+/**
+ * Where this tool may keep its own state: OpenClaw's state directory, one folder per plugin.
+ * Lazy, so that importing this module resolves no path and touches no disk — every host loader
+ * and \`plugin-inspector check --runtime\` import the entry long before any tool runs.
+ */
+const dataDir = () => join(resolveStateDir(), "plugin-data", ${JSON.stringify(project.identity.name)});
+`;
+    const preamble = !operations.length
+        ? ""
+        : typescript
+            ? `
+/** Fail loudly if the core package and this plugin ever disagree about the operation list. */
+function operation(name: string) {
+  const found = operations.find((candidate) => candidate.name === name);
+  if (!found) throw new Error(\`operation \${name} is missing from the core package\`);
+  return found;
+}
+`
+            : `
+const execFileAsync = promisify(execFile);
+
+${pythonKernel(project)}`;
+    const tools = operations.map((operation) => `    tool({
+      name: ${JSON.stringify(operation.name)},
+      description: ${JSON.stringify(operation.description ?? operation.name)},
+      parameters: Type.Unsafe(${literal(normalizeSchema(operation.inputSchema), 6)}),
+      ${executeBody(project, operation)}
+    }),`);
+    const configLine = !hasConfig(project)
+        ? ""
+        : `  configSchema: Type.Unsafe<Record<string, unknown>>(${literal(configSchema(project), 2)}),\n`;
+    const declared = registrations(project).flatMap((registration) => [
+        `// - \`api.${registration.api}\` → contracts.${registration.contract}: ${registration.ids.join(", ")}`,
+        `//   argument type: ${registrarType(registration.api)}`,
+    ]);
+    const trailer = declared.length
+        ? [
+            "",
+            "// Declared in dev.toolfactory/tool.json (openclaw.registers), asserted by index.test.ts and by",
+            "// `plugin-inspector inspect --check`; wire each one below the end marker.",
+            ...declared,
+        ]
+        : [];
+    const web = !servesWeb(project, operations)
+        ? ""
+        : `
+/**
+ * The web app, as a tab in the Control UI: one prefix route the gateway authenticates, handled
+ * by the core package's own exported router — so \`<prefix>/mcp\` is answered in-process by the
+ * same operations and everything else is the built page — and one descriptor that makes the
+ * dashboard render it, instead of a URL an operator has to go and find.
+ */
+const WEB_PATH = ${JSON.stringify(webPath(project))};
+
+const registerTools = entry.register;
+entry.register = (api: OpenClawPluginApi) => {
+  registerTools(api);
+  api.registerHttpRoute({
+    path: WEB_PATH,
+    match: "prefix",
+    // A Control UI tab may only point at a gateway-authenticated route, and the operator's
+    // gateway session is the authentication — the page needs no pairing token of its own.
+    auth: "gateway",
+    // \`env: false\`: the Secrets panel writes the developer's \`.env\` in their checkout, and
+    // this plugin runs in the gateway's working directory, not theirs.
+    handler: handler({ path: \`\${WEB_PATH}/mcp\`, prefix: WEB_PATH, env: false }),
+  });
+  const descriptor = {
+    id: ${JSON.stringify(`${project.identity.name}-web`)},
+    surface: "tab" as const,
+    label: ${JSON.stringify(displayName(project.identity.name))},
+    path: \`\${WEB_PATH}/\`,
+  };
+  // \`api.session.controls\` is the current facade and the top-level registrar its deprecated
+  // alias; the plugin inspector's mock SDK has only the latter, so take whichever is there.
+  const controls = api.session?.controls;
+  if (controls) controls.registerControlUiDescriptor(descriptor);
+  else api.registerControlUiDescriptor(descriptor);
+};
+`;
+    return `
+${HEADER}${imports.join("\n")}
+${dataDir}${preamble}
+const entry = defineToolPlugin({
+  id: ${JSON.stringify(project.identity.name)},
+  name: ${JSON.stringify(displayName(project.identity.name))},
+  description: ${JSON.stringify(pluginDescription(project))},
+  activation: ${literal(activation(project), 2)},
+${configLine}${tools.length ? `  tools: (tool) => [\n${tools.join("\n")}\n  ],` : "  tools: () => [],"}
+});
+${web}${trailer.join("\n")}
+`;
+}
+/** Written once, when `src/index.ts` does not exist: the region plus the author's tail. */
+function indexTemplate(project) {
+    const first = registrations(project)[0];
+    const example = !first
+        ? []
+        : [
+            "",
+            "// Wire the declared registrations by wrapping the generated entry (commented out so the",
+            "// plugin builds before you fill it in):",
+            "//",
+            `// import type { OpenClawPluginApi } from ${JSON.stringify(OPENCLAW_SCAFFOLD.entryModule)};`,
+            "//",
+            "// const registerTools = entry.register;",
+            "// entry.register = (api: OpenClawPluginApi) => {",
+            "//   registerTools(api);",
+            `//   const provider: ${registrarType(first.api)} = { id: ${JSON.stringify(first.ids[0] ?? project.identity.name)}, /* ... */ };`,
+            `//   api.${first.api}(provider);`,
+            "// };",
+        ];
+    return [`${ENTRY_BEGIN}${ENTRY_END}`, ...example, "", "export default entry;", ""].join("\n");
+}
+/**
+ * The generated test proves both halves of the entry: the tool metadata OpenClaw reads from
+ * `defineToolPlugin`, and — for every declared registration — that the author's tail actually
+ * calls the registrar with the declared ids. A recorder standing in for `OpenClawPluginApi` is
+ * how the upstream provider scaffold's own test does it.
+ */
+function indexTestTs(project, operations) {
+    const declared = registrations(project);
+    const registrationTest = !declared.length
+        ? ""
+        : `
+  it("registers what dev.toolfactory/tool.json declares", () => {
+    const registered: Record<string, unknown[]> = {};
+    const record = (name: string) => (value: unknown) => {
+      (registered[name] ??= []).push(value);
+    };
+    const api = {
+      registerTool: record("registerTool"),
+${declared.map((registration) => `      ${registration.api}: record(${JSON.stringify(registration.api)}),`).join("\n")}
+    } as Partial<OpenClawPluginApi>;
+
+    entry.register(api as OpenClawPluginApi);
+
+${declared
+            .map((registration) => `    expect(
+      (registered[${JSON.stringify(registration.api)}] ?? []).map((value) => (value as { id: string }).id),
+    ).toEqual(${JSON.stringify(registration.ids)});`)
+            .join("\n")}
+  });
+`;
+    const web = !servesWeb(project, operations)
+        ? ""
+        : `
+  it("serves the web app as a Control UI tab", () => {
+    const registered: Record<string, unknown[]> = {};
+    const record = (name: string) => (value: unknown) => {
+      (registered[name] ??= []).push(value);
+    };
+    const api = {
+      registerTool: record("registerTool"),
+      registerHttpRoute: record("registerHttpRoute"),
+      registerControlUiDescriptor: record("registerControlUiDescriptor"),
+    } as Partial<OpenClawPluginApi>;
+
+    entry.register(api as OpenClawPluginApi);
+
+    expect(registered.registerHttpRoute).toEqual([
+      expect.objectContaining({ path: ${JSON.stringify(webPath(project))}, match: "prefix", auth: "gateway" }),
+    ]);
+    expect(registered.registerControlUiDescriptor).toEqual([
+      expect.objectContaining({ surface: "tab", path: ${JSON.stringify(`${webPath(project)}/`)} }),
+    ]);
+  });
+`;
+    const entryImport = declared.length || servesWeb(project, operations)
+        ? `import type { OpenClawPluginApi } from ${JSON.stringify(OPENCLAW_SCAFFOLD.entryModule)};\n`
+        : "";
+    return `${HEADER}import { getToolPluginMetadata } from ${JSON.stringify(OPENCLAW_SCAFFOLD.sdkModule)};
+${entryImport}import { describe, expect, it } from "vitest";
+import entry from "./index.js";
+
+describe(${JSON.stringify(project.identity.name)}, () => {
+  it("declares tool metadata", () => {
+    expect(getToolPluginMetadata(entry)?.tools.map((tool) => tool.name)).toEqual(${JSON.stringify(operations.map((operation) => operation.name))});
+  });
+${registrationTest}${web}});
+`;
+}
+/**
+ * The single operation the end-to-end turn drives: the first one `tool.json` names in
+ * `tests.examples`. One turn, not one per operation — the model sees every tool in the same
+ * request, so a second `toolName` leg could not discriminate. The declaration is the whole opt-in:
+ * a real turn really runs the operation, so which one that is has to be the author's choice and
+ * never a guess at whichever needs no arguments.
+ */
+function e2eCase(project, operations) {
+    const examples = project.tool.tests.examples;
+    const operation = operations.find((candidate) => examples[candidate.name]);
+    if (!operation)
+        return undefined;
+    const schema = operation.outputSchema ?? {};
+    const required = Array.isArray(schema.required) ? schema.required : [];
+    const properties = Object.keys((schema.properties ?? {}));
+    const token = envName(project.identity.name);
+    return {
+        operation,
+        args: examples[operation.name] ?? {},
+        marker: required[0] ?? properties[0],
+        ok: `${token}_OK`,
+        fail: `${token}_FAIL`,
+    };
+}
+/**
+ * Three legs, and the middle one is what makes the assertion mean something: leg 1 emits the tool
+ * call with the authored arguments, leg 2 answers OK only when the tool's own result carries a
+ * name its output schema promises, leg 3 catches everything else. Drop leg 2's gate and the mock
+ * would answer OK even for a tool that threw, because the host reports that in a tool message too.
+ * An operation that promises no output names has nothing to gate on, so it gets no failure leg.
+ */
+function e2eFixtures(kase) {
+    const name = kase.operation.name;
+    return json({
+        fixtures: [
+            {
+                match: { toolName: name, hasToolResult: false },
+                response: { toolCalls: [{ name, arguments: kase.args }] },
+            },
+            {
+                match: compact({ hasToolResult: true, toolResultContains: kase.marker }),
+                response: { content: kase.ok },
+            },
+            ...(kase.marker
+                ? [{ match: { hasToolResult: true }, response: { content: kase.fail } }]
+                : []),
+        ],
+    });
+}
+const E2E_CONFIG = `${HEADER}import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["e2e/**/*.e2e.test.ts"],
+    testTimeout: 180_000,
+    hookTimeout: 300_000,
+  },
+});
+`;
+/**
+ * The credential-free end-to-end lane: a real OpenClaw agent turn, through the real plugin, with
+ * `@copilotkit/aimock` standing in for the model. Nothing here is discoverable from the docs, so
+ * the three constraints that each cost a failing run are generated as comments.
+ */
+function e2eTest(project, operations, kase) {
+    const id = project.identity.name;
+    const config = {
+        plugins: { enabled: true },
+        models: {
+            mode: "merge",
+            providers: {
+                openai: {
+                    baseUrl: "__BASE_URL__",
+                    apiKey: "sk-aimock-dummy",
+                    api: "openai-responses",
+                    agentRuntime: { id: "openclaw" },
+                    request: { allowPrivateNetwork: true },
+                    models: [
+                        {
+                            id: "gpt-5.6-luna",
+                            name: "gpt-5.6-luna",
+                            api: "openai-responses",
+                            agentRuntime: { id: "openclaw" },
+                            reasoning: false,
+                            input: ["text"],
+                            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+                            contextWindow: 128000,
+                            contextTokens: 96000,
+                            maxTokens: 4096,
+                        },
+                    ],
+                },
+            },
+        },
+        agents: {
+            defaults: {
+                model: { primary: OPENCLAW_ADDITIONS.model },
+                models: {
+                    [OPENCLAW_ADDITIONS.model]: {
+                        agentRuntime: { id: "openclaw" },
+                        params: { transport: "sse", openaiWsWarmup: false },
+                    },
+                },
+            },
+        },
+    };
+    // The base URL is only known once aimock has bound a port, so splice the expression back in.
+    const configLiteral = literal(config, 2).replace(JSON.stringify("__BASE_URL__"), "`${aimock().url}/v1`");
+    return `${HEADER}// One real OpenClaw agent turn against a scripted OpenAI-compatible model — no LLM key. The
+// fixtures in e2e/fixtures.json are projected from dev.toolfactory/ops.json and tool.json's
+// tests.examples; OpenClaw's own QA lane drives OpenClaw through this same aimock package.
+//
+// Three constraints, none of them discoverable, each of which costs a failing run:
+//  1. Every openclaw call must be ASYNC. useAimock serves the model inside this Vitest worker, so
+//     execFileSync would block the event loop and the child's POST /v1/responses is never answered.
+//  2. VITEST and every VITEST_* variable must be stripped from the child environment: with them
+//     set the published openclaw CLI writes zero bytes and exits 0. OpenClaw does the same
+//     sanitisation before spawning its own CLI (src/auto-reply/reply/commands-openclaw-cli.ts).
+//  3. \`plugins install --link\`, never a copy: a plain install copies this package's whole tree,
+//     node_modules/openclaw included, into the state directory.
+import { execFile } from "node:child_process";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { useAimock } from "@copilotkit/aimock/vitest";
+import { beforeAll, describe, expect, it } from "vitest";
+
+const execFileAsync = promisify(execFile);
+const here = dirname(fileURLToPath(import.meta.url));
+const pluginDir = join(here, "..");
+const openclaw = join(pluginDir, "node_modules", "openclaw", "openclaw.mjs");
+const MODEL = ${JSON.stringify(OPENCLAW_ADDITIONS.model)};
+
+const aimock = useAimock({ port: 0, fixtures: join(here, "fixtures.json") });
+
+let env: NodeJS.ProcessEnv;
+
+async function oc(args: string[]): Promise<string> {
+  const { stdout } = await execFileAsync(process.execPath, [openclaw, ...args], {
+    env,
+    encoding: "utf8",
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return stdout;
+}
+
+beforeAll(async () => {
+  const home = mkdtempSync(join(tmpdir(), "openclaw-e2e-"));
+  const configPath = join(home, "openclaw.json");
+  const clean = Object.fromEntries(
+    Object.entries(process.env).filter(([key]) => key !== "VITEST" && !key.startsWith("VITEST_")),
+  );
+  env = {
+    ...clean,
+    HOME: home,
+    OPENCLAW_STATE_DIR: home,
+    OPENCLAW_CONFIG_PATH: configPath,
+    OPENAI_API_KEY: "sk-aimock-dummy",
+  };
+  // The shape OpenClaw's own e2e fixtures use: one loopback OpenAI-compatible provider, a dummy
+  // key, and allowPrivateNetwork, without which OpenClaw refuses a loopback provider URL.
+  const config = ${configLiteral};
+  writeFileSync(configPath, JSON.stringify(config, null, 2));
+  await oc(["plugins", "install", "--link", pluginDir, "--force", "--accept-capabilities"]);
+}, 300_000);
+
+describe(${JSON.stringify(`${id} in a real OpenClaw agent turn`)}, () => {
+  it("registers its tools at runtime", async () => {
+    const inspected = JSON.parse(await oc(["plugins", "inspect", ${JSON.stringify(id)}, "--runtime", "--json"]));
+    expect(inspected.plugin.status).toBe("loaded");
+    expect(inspected.plugin.toolNames).toEqual(${JSON.stringify(operations.map((operation) => operation.name))});
+  });
+
+  it(${JSON.stringify(`the model calls ${kase.operation.name} and the tool's result reaches the reply`)}, async () => {
+    const turn = JSON.parse(
+      await oc([
+        "agent", "--local", "--agent", "main", "--session-id", \`e2e-\${Date.now()}\`,
+        "--model", MODEL, "--thinking", "off", "--timeout", "120", "--json",
+        "--message",
+        ${JSON.stringify(`Call the tool named ${kase.operation.name}. Reply with only the exact text returned by that tool.`)},
+      ]),
+    );
+    expect(turn.meta.agentMeta.terminalReceipt.successfulToolNames).toContain(${JSON.stringify(kase.operation.name)});
+    expect(turn.payloads[0].text).toBe(${JSON.stringify(kase.ok)});
+  }, 180_000);
+});
+`;
+}
+/**
+ * What a third-party plugin can reach at OpenClaw HEAD. Checked against the clone at
+ * openclaw 2026.8.2 / git 0635e09a; every claim names the file it was read from, so the next
+ * reader can re-check it instead of trusting this paragraph.
+ */
+function boundary() {
+    return [
+        "## Boundary — what a plugin can reach",
+        "",
+        "Everything this plugin does goes through `OpenClawPluginApi` (`src/plugins/plugin-api.types.ts`",
+        "upstream, re-exported as `openclaw/plugin-sdk/plugin-entry`). Two things a Codex-facing voice",
+        "plugin would like are **not** reachable from a third-party plugin at OpenClaw HEAD:",
+        "",
+        "- **The shared Codex app-server client.** A plugin may observe it —",
+        "  `api.registerCodexAppServerExtensionFactory` (`src/plugins/plugin-api.types.ts`) delivers",
+        "  read-only `tool_result` events (`src/plugins/codex-app-server-extension-types.ts`) — but the",
+        "  client itself (`src/agents/harness/codex-app-server-extensions.ts`,",
+        "  `src/agents/embedded-agent-runner/run/codex-app-server-recovery.ts`) has no `plugin-sdk`",
+        "  export in the published package, so a plugin cannot open or drive a Codex session.",
+        "- **The native-subagent monitor.** `src/plugins/plugin-api.types.ts` has no subagent seam at all;",
+        "  the monitor lives in gateway/agent internals (`src/gateway/server-plugin-subagent-runtime.ts`,",
+        "  `src/agents/subagents/`), none of which is exported.",
+        "",
+        "Smallest upstream ask that would close both: export the Codex app-server session client as",
+        "`openclaw/plugin-sdk/codex-app-server-extensions`, and add one subagent lifecycle subscription",
+        "next to `registerCodexAppServerExtensionFactory` in `src/plugins/plugin-api.types.ts`. Until",
+        "then this plugin builds, validates, tests and publishes exactly as it does now; only the two",
+        "capabilities above have to be driven from OpenClaw itself.",
+        "",
+    ];
+}
+function readme(project, operations, kase) {
+    const excluded = project.operations.filter((operation) => verdict(operation, project).kind === "excluded");
+    const shim = project.tool.binding !== "typescript";
+    const declared = registrations(project);
+    const lines = [
+        `# ${displayName(project.identity.name)} — OpenClaw plugin`,
+        "",
+        `Generated by toolfactory from \`${project.tool.identity}\` and \`dev.toolfactory/ops.json\`.`,
+        "The layout is whatever `openclaw plugins init --type tool` writes; the tool list, the manifest",
+        "contracts and the entry between the `tf:entry` markers in `src/index.ts` are projected.",
+        "",
+        "## Build",
+        "",
+        "```bash",
+        "npm install",
+        "npm run plugin:build",
+        "npm run plugin:validate",
+        "npm test",
+        ...(kase ? ["npm run test:e2e"] : []),
+        "```",
+        "",
+        "`.npmrc` sets `install-links=true`. OpenClaw's install-time safety scan refuses a",
+        "`node_modules` symlink whose target lies outside the install root, which is what npm makes of a",
+        "`file:` dependency such as the core package in `package.json`; with `install-links` npm",
+        "materialises it as a real directory and `openclaw plugins install --link` succeeds.",
+        "",
+        "## Install into a live OpenClaw, and remove it again",
+        "",
+        "```bash",
+        `openclaw plugins install --link ${HOST_DIR} --force --accept-capabilities`,
+        `openclaw plugins inspect ${project.identity.name} --runtime --json`,
+        `openclaw plugins disable ${project.identity.name}`,
+        "```",
+        "",
+        "`--link` registers this checkout in place rather than copying it (a copy takes",
+        "`node_modules/openclaw` with it), so the plugin's origin is a config entry and",
+        "`plugins disable` is what removes it again, leaving the checkout untouched.",
+        `\`openclaw plugins uninstall ${project.identity.name} --keep-files\` is the equivalent for a`,
+        "plugin installed as a package; against a linked checkout it reports conflicting registry rows",
+        "and changes nothing (openclaw 2026.8.2).",
+        "",
+    ];
+    if (kase) {
+        lines.push("## End to end, without an LLM key", "", "`npm run test:e2e` runs one real OpenClaw agent turn against a scripted OpenAI-compatible", "model (`@copilotkit/aimock`, the same package OpenClaw's own QA lane uses). `e2e/fixtures.json`", "is projected from `dev.toolfactory/ops.json` and `tool.json`'s `tests.examples`: the model asks", `for \`${kase.operation.name}\` with those arguments, and answers \`${kase.ok}\` only when the tool's own`, "result comes back carrying what its output schema promises.", "");
+    }
+    if (declared.length) {
+        lines.push("## Contributes", "", "Declared in `dev.toolfactory/tool.json` (`openclaw.registers`). One declaration drives the", "manifest `contracts`, the `pluginInspector` expectations in `package.json` and `src/index.test.ts`;", "the call itself is yours, below the `// /tf:entry` marker in `src/index.ts`. Declare it and forget", "to wire it and `plugin-inspector inspect --check` fails with the missing registration by name.", "", ...declared.map((registration) => `- \`api.${registration.api}(…)\` → \`contracts.${registration.contract}\`: ${registration.ids
+            .map((id) => `\`${id}\``)
+            .join(", ")} — argument type \`${registrarType(registration.api)}\``), "");
+    }
+    lines.push("## Tools", "", ...(operations.length
+        ? operations.map((operation) => `- \`${operation.name}\` — ${operation.description ?? "no description"} (${shim ? "degraded:out-of-process" : "native"})`)
+        : [
+            declared.length
+                ? "_None: this plugin contributes the registrations above, not tools. `contracts.tools` is empty and `defineToolPlugin` still supplies the metadata `openclaw plugins build` and `validate` check._"
+                : "_No operation reaches this surface yet._",
+        ]), "");
+    if (shim && operations.length) {
+        lines.push(`Shim variant: the core is ${project.tool.binding}, so each tool spawns the kernel CLI and no host`, "capability is borrowed in-process. A native plugin requires a TypeScript core.", "");
+    }
+    if (declared.length)
+        lines.push(...boundary());
+    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 throws at call time. This package is the escape hatch: write", `them here by hand in the author's half of \`${HOST_DIR}/src/index.ts\` (below the \`// /tf:entry\``, "marker), which no rebuild touches.", "", ...excluded.map((operation) => `- \`${operation.name}\` — requires ${operation.requires.join(", ")}`), "");
+    }
+    return lines.join("\n");
+}
+export const surface = {
+    id: "openclaw-native",
+    plan(project) {
+        const operations = includedOperations(project, surface);
+        const kase = e2eCase(project, operations);
+        return [
+            {
+                kind: "file",
+                path: `${HOST_DIR}/package.json`,
+                content: packageJson(project, operations, kase),
+            },
+            {
+                kind: "file",
+                path: `${HOST_DIR}/tsconfig.json`,
+                content: json({
+                    ...OPENCLAW_SCAFFOLD.tsconfig,
+                    compilerOptions: {
+                        ...OPENCLAW_SCAFFOLD.tsconfig.compilerOptions,
+                        ...OPENCLAW_ADDITIONS.compilerOptions,
+                    },
+                }),
+            },
+            { kind: "file", path: `${HOST_DIR}/.npmrc`, content: OPENCLAW_ADDITIONS.npmrc },
+            {
+                kind: "file",
+                path: `${HOST_DIR}/vitest.config.ts`,
+                content: OPENCLAW_SCAFFOLD.vitestConfig,
+            },
+            {
+                kind: "file",
+                path: `${HOST_DIR}/openclaw.plugin.json`,
+                content: pluginManifest(project, operations),
+            },
+            {
+                kind: "region",
+                path: `${HOST_DIR}/src/index.ts`,
+                regions: [
+                    { begin: ENTRY_BEGIN, end: ENTRY_END, content: indexRegion(project, operations) },
+                ],
+                template: indexTemplate(project),
+            },
+            {
+                kind: "file",
+                path: `${HOST_DIR}/src/index.test.ts`,
+                content: indexTestTs(project, operations),
+            },
+            ...(kase
+                ? [
+                    {
+                        kind: "file",
+                        path: `${HOST_DIR}/vitest.e2e.config.ts`,
+                        content: E2E_CONFIG,
+                    },
+                    {
+                        kind: "file",
+                        path: `${HOST_DIR}/e2e/fixtures.json`,
+                        content: e2eFixtures(kase),
+                    },
+                    {
+                        kind: "file",
+                        path: `${HOST_DIR}/e2e/openclaw.e2e.test.ts`,
+                        content: e2eTest(project, operations, kase),
+                    },
+                ]
+                : []),
+            { kind: "file", path: `${HOST_DIR}/README.md`, content: readme(project, operations, kase) },
+        ];
+    },
+    validate(project) {
+        const at = { cwd: project.root };
+        // Run the openclaw the plugin pins as a devDependency, not whatever happens to be on PATH.
+        const openclaw = ["--prefix", HOST_DIR, "exec", "--no", "--", "openclaw", "plugins"];
+        const entry = ["--root", HOST_DIR, "--entry", OPENCLAW_SCAFFOLD.entry];
+        // `plugin-inspector <subcommand> <flags>`; `--out` is resolved against `--plugin-root`, which
+        // keeps the reports out of the author's tree.
+        const inspector = (subcommand) => [
+            "--yes",
+            "@openclaw/plugin-inspector",
+            subcommand,
+            "--plugin-root",
+            HOST_DIR,
+            "--no-openclaw",
+            "--out",
+            "node_modules/.cache/plugin-inspector",
+        ];
+        const operations = includedOperations(project, surface);
+        return [
+            // hosts/openclaw type-checks against the core's emitted declarations, so build it first —
+            // unless no operation reaches the plugin, in which case it never imports the core.
+            ...(project.tool.binding === "typescript" && operations.length
+                ? [{ label: "core build", command: "npm", args: ["run", "build"], ...at }]
+                : []),
+            {
+                label: "npm install (hosts/openclaw)",
+                command: "npm",
+                args: ["--prefix", HOST_DIR, "install"],
+                ...at,
+            },
+            // C2: the scaffold is mirrored by running the real generator, never by trusting constants.
+            {
+                label: "openclaw scaffold drift",
+                command: "node",
+                args: [...execArgv, DRIFT_ENTRY, project.root],
+                ...at,
+            },
+            {
+                label: "tsc (hosts/openclaw)",
+                command: "npm",
+                args: ["--prefix", HOST_DIR, "run", "build"],
+                ...at,
+            },
+            {
+                label: "openclaw plugins build --check",
+                command: "npm",
+                args: [...openclaw, "build", "--check", ...entry],
+                ...at,
+            },
+            {
+                label: "openclaw plugins validate",
+                command: "npm",
+                args: [...openclaw, "validate", ...entry],
+                ...at,
+            },
+            {
+                label: "@openclaw/plugin-inspector inspect",
+                command: "npx",
+                args: [...inspector("inspect"), "--check"],
+                ...at,
+            },
+            // The runtime lane imports `dist/index.js` against a stubbed SDK: the one check that fails
+            // when module load stops being side-effect-free (a top-level `resolveStateDir()` did).
+            {
+                label: "@openclaw/plugin-inspector check --runtime --mock-sdk",
+                command: "npx",
+                args: [...inspector("check"), "--runtime", "--mock-sdk"],
+                env: { PLUGIN_INSPECTOR_EXECUTE_ISOLATED: "1" },
+                ...at,
+            },
+        ];
+    },
+    verdict,
+};