toolfactory 0.1.1

package/src/bindings/python.ts

@@ -0,0 +1,862 @@
+/**
+ * Python binding: the six language-specific things, as templates against upstream
+ * packages only (`mcp` 2.x + pydantic 2, and the standard library for the CLI). The
+ * kernel files under `src/<pkg>/toolfactory/` are regenerated on every build; the
+ * author's `src/<pkg>/ops.py` is scaffolded once and then owned.
+ */
+import { stringify as toml } from "smol-toml";
+import { projectName } from "../identity/name.js";
+import type { PlannedFile, Project } from "../model.js";
+import { secretsOf } from "../project/gate.js";
+import {
+  compact,
+  configProperties,
+  dataDirEnvName,
+  envName,
+  has,
+  liveCredentials,
+  liveExample,
+  pypiName,
+} from "../surfaces/shared.js";
+import { WEB_DIR } from "../surfaces/web.js";
+
+/** Import package: the canonical name with `.` and `-` folded to `_` (PEP 8 / PEP 503). */
+export function pythonPackage(project: Project): string {
+  return projectName.pythonPackage(project.identity.name);
+}
+
+export function kernelDir(project: Project): string {
+  return `src/${pythonPackage(project)}/toolfactory`;
+}
+
+export function opsPath(project: Project): string {
+  return `src/${pythonPackage(project)}/ops.py`;
+}
+
+export const LIVE_TEST_PATH = "tests/test_live.py";
+/** What the `live` CI job runs; the author adds `--env-file .env` locally (documented in the file header). */
+export const LIVE_TEST_COMMAND = `uv run --with pytest pytest -q ${LIVE_TEST_PATH}`;
+
+const LIVE_GUARD_BEGIN = "# tf:live-guard";
+const LIVE_GUARD_END = "# /tf:live-guard";
+
+export function cliEntryPoint(project: Project): string {
+  return `${pythonPackage(project)}.toolfactory.cli:main`;
+}
+
+/** `uv run` syncs the project into `.venv` on first use, so no build step is needed. */
+export function kernelCommand(project: Project): { command: string; args: string[] } {
+  return {
+    command: "uv",
+    args: ["run", "--quiet", "python", "-m", `${pythonPackage(project)}.toolfactory.mcp`],
+  };
+}
+
+/** The CLI counterpart of `kernelCommand`: same module path, `cli` instead of `mcp`. */
+export function cliCommand(project: Project): { command: string; args: string[] } {
+  return {
+    command: "uv",
+    args: ["run", "--quiet", "python", "-m", `${pythonPackage(project)}.toolfactory.cli`],
+  };
+}
+
+const HEADER = "# Generated by toolfactory. Do not edit; run `toolfactory build` to regenerate.\n";
+
+function typesTemplate(): string {
+  return `${HEADER}"""The operation contract: what an entry in \`OPERATIONS\` looks like."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel
+
+#: Host capabilities an operation may declare. Portable: net, fs, shell, secret.
+Capability = Literal["net", "fs", "shell", "secret", "browser", "model", "user-input", "channel"]
+
+
+@dataclass(frozen=True)
+class Context:
+    """Configuration read from the environment, keyed as declared in dev.toolfactory/tool.json."""
+
+    config: dict[str, str | None]
+    #: Directory this tool may keep its own state in. Created by the tool, not by the kernel.
+    data_dir: Path
+
+
+@dataclass(frozen=True)
+class Operation:
+    """One operation: a pure function of (arguments, context.config, filesystem)."""
+
+    name: str
+    description: str
+    input: type[BaseModel]
+    handler: Callable[[Any, Context], Any]
+    output: type[BaseModel] | None = None
+    requires: tuple[Capability, ...] = ()
+    annotations: dict[str, bool] = field(default_factory=dict)
+
+#: Capabilities every surface can satisfy on its own.
+PORTABLE: frozenset[str] = frozenset({"net", "fs", "shell", "secret"})
+
+
+def serves(operation: "Operation", surface: Literal["mcp", "cli"]) -> bool:
+    """Whether a surface can run an operation: MCP needs a portable one; a CLI also has a human for user-input."""
+    return all(c in PORTABLE or (surface == "cli" and c == "user-input") for c in operation.requires)
+`;
+}
+
+function initTemplate(): string {
+  return `${HEADER}"""Generated kernel: the MCP server, the CLI, and the operation contract."""
+
+from .types import Capability, Context, Operation
+
+__all__ = ["Capability", "Context", "Operation"]
+`;
+}
+
+function configTemplate(project: Project): string {
+  const entries = Object.keys(configProperties(project)).map(
+    (key) =>
+      `            ${JSON.stringify(key)}: os.environ.get(${JSON.stringify(envName(key))}),\n`,
+  );
+  const body = entries.length ? `{\n${entries.join("")}        }` : "{}";
+  const name = project.identity.name;
+  const dataDirEnv = dataDirEnvName(project);
+  return `${HEADER}"""Configuration is read from the environment; hosts inject it from their own settings UI."""
+
+import os
+from pathlib import Path
+
+from .types import Context
+
+
+def data_dir() -> Path:
+    """Where this tool may keep its own state: ${dataDirEnv} when a host sets it, else the
+    platform's own data location (XDG on POSIX, %LOCALAPPDATA% on Windows)."""
+    # Hosts that launch the kernel export their own name for it: Agent Plugins clients and
+    # OpenClaw set PLUGIN_DATA, Claude Code sets CLAUDE_PLUGIN_DATA.
+    configured = (
+        os.environ.get(${JSON.stringify(dataDirEnv)})
+        or os.environ.get("PLUGIN_DATA")
+        or os.environ.get("CLAUDE_PLUGIN_DATA")
+    )
+    if configured:
+        return Path(configured)
+    if os.name == "nt":
+        base = Path(os.environ.get("LOCALAPPDATA") or Path.home() / "AppData" / "Local")
+    else:
+        base = Path(os.environ.get("XDG_DATA_HOME") or Path.home() / ".local" / "share")
+    return base / ${JSON.stringify(name)}
+
+
+def context() -> Context:
+    return Context(config=${body}, data_dir=data_dir())
+`;
+}
+
+/**
+ * What the kernel adds when the `web` surface is selected: the Starlette routes for the built
+ * page and — only when the project declares a secret — `/env`, which the page's Secrets panel
+ * reads and writes. `.env` is the developer's own file, resolved from the working directory:
+ * names out, one name in, never a value in a log or a response.
+ */
+function webRoutes(secrets: string[]): string {
+  const env = !secrets.length
+    ? ""
+    : `
+
+
+#: The names this project declares; \`/env\` writes no other.
+SECRETS = ${JSON.stringify(secrets)}
+
+
+def env_path() -> Path:
+    return Path.cwd() / ".env"
+
+
+def env_lines() -> "list[str]":
+    try:
+        return env_path().read_text().rstrip("\\n").split("\\n")
+    except OSError:
+        return []
+
+
+def env_present() -> "list[str]":
+    """Which declared names \`.env\` already carries a value for. Names only — never a value."""
+    found = {}
+    for line in env_lines():
+        name, _, value = line.lstrip().removeprefix("export ").partition("=")
+        if value.strip():
+            found[name.strip()] = True
+    return [name for name in SECRETS if name in found]
+
+
+def env_write(name: str, value: str) -> None:
+    """Rewrite one line of \`.env\`, keeping every other line, and keep the file private."""
+    lines = env_lines()
+    for index, line in enumerate(lines):
+        if line.lstrip().removeprefix("export ").partition("=")[0].strip() == name:
+            lines[index] = f"{name}={value}"
+            break
+    else:
+        lines.append(f"{name}={value}")
+    env_path().write_text("\\n".join(lines) + "\\n")
+    env_path().chmod(0o600)
+    # The name, never the value: this log is the one place a secret could leak by accident.
+    print(f".env: set {name}", file=sys.stderr, flush=True)
+
+
+def env_route(token: "str | None") -> Route:
+    """\`GET\` the names present, \`POST {name, value}\` one of them. Writing needs the bearer token."""
+
+    async def endpoint(request: Any) -> JSONResponse:
+        # Names, never values: what this project declares and which \`.env\` already carries.
+        if request.method == "GET":
+            return JSONResponse({"declared": SECRETS, "present": env_present()})
+        # Even on loopback: without a token in force there is no client to trust with a write.
+        if token is None:
+            return JSONResponse({"error": "unpaired: restart with \`mcp --http --open\`"}, status_code=403)
+        try:
+            payload = await request.json()
+            name, value = payload["name"], payload["value"]
+        except Exception:
+            return JSONResponse({"error": "expected {name, value}"}, status_code=400)
+        if name not in SECRETS:
+            return JSONResponse({"error": "not a declared secret"}, status_code=400)
+        if not isinstance(value, str) or not value:
+            return JSONResponse({"error": "empty value"}, status_code=400)
+        env_write(name, value)
+        return JSONResponse({"declared": SECRETS, "present": env_present()})
+
+    return Route("/env", endpoint, methods=["GET", "POST"])`;
+  return `
+
+def web_dist() -> "Path | None":
+    """The built page: the wheel force-includes \`${WEB_DIR}/dist\` here, a checkout has it in place."""
+    package = Path(__file__).resolve().parent.parent
+    for candidate in (package / "${WEB_DIR}", package.parent.parent / "${WEB_DIR}" / "dist"):
+        if candidate.is_dir():
+            return candidate
+    return None
+
+
+def web_route() -> "Mount | Route":
+    """Everything that is not an API route is the page, or the hint that it was never built."""
+    directory = web_dist()
+    if directory is not None:
+        return Mount("/", app=StaticFiles(directory=directory, html=True))
+
+    async def missing(request: Any) -> PlainTextResponse:
+        return PlainTextResponse("no ${WEB_DIR}/dist; run \`npm -C ${WEB_DIR} run build\`\\n", status_code=404)
+
+    return Route("/{path:path}", missing)${env}
+`;
+}
+
+/**
+ * The `web` operation, generated with the `web` surface: it reaches every surface at once
+ * (MCP `tools/call`, the skill, the CLI, the page itself) without a socket inside the stdio
+ * server — the kernel's own HTTP listener runs in a detached child, which is also what opens
+ * the browser, so the page appears on the machine running the tool and no host has to open a
+ * URL a tool returns.
+ */
+function webTemplate(): string {
+  return `${HEADER}"""The \`web\` operation: start the kernel's HTTP listener and hand back its URL."""
+
+import re
+import subprocess
+import sys
+from typing import Any
+from urllib.parse import urlsplit
+
+from pydantic import BaseModel
+
+from .types import Context, Operation
+
+SERVING = re.compile(r"Serving MCP streamable HTTP on (\\S+)")
+
+
+class WebInput(BaseModel):
+    pass
+
+
+class WebOutput(BaseModel):
+    url: str
+
+
+def web(arguments: WebInput, context: Context) -> WebOutput:
+    child: Any = subprocess.Popen(
+        [sys.executable, "-m", f"{__package__}.mcp", "--http", "0", "--open"],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.PIPE,
+        text=True,
+        # The listener outlives this call, and this process: an operation may not hold a socket.
+        start_new_session=True,
+    )
+    for line in child.stderr:
+        found = SERVING.search(line)
+        if found:
+            served = urlsplit(found.group(1))
+            # The page, not the endpoint, and without the token the child already handed the
+            # browser: an operation's result travels through an agent, and a token is a credential.
+            return WebOutput(url=f"{served.scheme}://{served.netloc}/")
+    raise RuntimeError("the kernel exited before it started serving")
+
+
+OPERATION = Operation(
+    name="web",
+    description=(
+        "Open this tool's web app: serves the operations page and the MCP endpoint on a free "
+        "local port, opens a browser there, and returns the URL."
+    ),
+    input=WebInput,
+    output=WebOutput,
+    requires=("shell", "net"),
+    annotations={"openWorldHint": False},
+    handler=web,
+)
+`;
+}
+
+function mcpTemplate(project: Project): string {
+  const tokenEnv = `${envName(project.identity.name)}_MCP_TOKEN`;
+  const web = has(project, "web");
+  const declared = web ? secretsOf(project) : [];
+  return `${HEADER}"""The kernel MCP server: every operation registered from its pydantic input model.
+
+Serves over stdio by default; \`serve_http()\` (or the CLI's \`mcp --http [port]\`) serves the
+same server over MCP streamable HTTP instead: one Starlette app — the SDK's own streamable-HTTP
+route${web ? ", the built web app" : ""}${declared.length ? " and `/env`" : ""} — under uvicorn.${
+    web
+      ? `
+The page is served beside the endpoint so it POSTs same-origin, and \`--open\` is the whole launch.`
+      : ""
+  }
+"""
+
+import argparse
+import hashlib
+import hmac
+import inspect
+import os
+import secrets
+import sys${
+    web
+      ? `
+import webbrowser`
+      : ""
+  }
+from pathlib import Path
+from typing import Annotated, Any
+
+from mcp.server.mcpserver import MCPServer${
+    web
+      ? `
+from starlette.responses import JSONResponse, PlainTextResponse
+from starlette.routing import Mount, Route
+from starlette.staticfiles import StaticFiles`
+      : ""
+  }
+
+from ..ops import OPERATIONS${web ? " as AUTHORED_OPERATIONS" : ""}
+from .config import context, data_dir
+from .types import Operation, serves${
+    web
+      ? `
+from .web import OPERATION as WEB_OPERATION
+
+#: The authored operations plus the generated \`web\` one; \`introspect\` snapshots this list.
+OPERATIONS = [*AUTHORED_OPERATIONS, WEB_OPERATION]`
+      : ""
+  }
+
+server = MCPServer(
+    name=${JSON.stringify(project.identity.name)},
+    version=${JSON.stringify(project.identity.version ?? "0.0.0")},
+    description=${JSON.stringify(project.identity.description ?? project.identity.name)},
+)
+
+
+def bind(operation: Operation) -> Any:
+    """Give the handler the signature of its input model, so the SDK publishes that schema."""
+    parameters = [
+        inspect.Parameter(
+            name,
+            inspect.Parameter.KEYWORD_ONLY,
+            annotation=Annotated[spec.annotation, spec],
+            default=inspect.Parameter.empty if spec.is_required() else spec.default,
+        )
+        for name, spec in operation.input.model_fields.items()
+    ]
+
+    async def call(**arguments: Any) -> Any:
+        result = operation.handler(operation.input(**arguments), context())
+        return await result if inspect.isawaitable(result) else result
+
+    call.__name__ = operation.name
+    call.__signature__ = inspect.Signature(
+        parameters,
+        return_annotation=operation.output if operation.output else inspect.Signature.empty,
+    )
+    return call
+
+
+#: toolfactory introspects with every operation visible; a served instance lists only what MCP can run.
+INTROSPECTING = bool(os.environ.get("TOOLFACTORY_INTROSPECT"))
+
+for operation in OPERATIONS:
+    if not INTROSPECTING and not serves(operation, "mcp"):
+        continue
+    server.add_tool(
+        bind(operation),
+        name=operation.name,
+        description=operation.description,
+        annotations=operation.annotations or None,
+        meta={"dev.toolfactory": {"requires": list(operation.requires)}},
+    )
+
+
+def serve() -> None:
+    server.run("stdio")
+
+
+#: The pairing token, so a browser extension (or anything else on loopback) can prove it is the
+#: client the user paired: the endpoint requires \`Authorization: Bearer <token>\` when
+#: ${tokenEnv} is set or \`mcp --http --pair\` has written one under the data directory. With
+#: neither, nothing changes and the endpoint stays open on loopback.
+TOKEN_FILE = "relay-token"
+
+
+def token_path() -> Path:
+    return data_dir() / TOKEN_FILE
+
+
+def paired_token() -> str | None:
+    configured = os.environ.get(${JSON.stringify(tokenEnv)})
+    if configured:
+        return configured
+    try:
+        return token_path().read_text().strip() or None
+    except OSError:
+        return None
+
+
+def mint_token() -> str:
+    """Mint a token and keep it 0600 under the data directory. Never rotates an existing one."""
+    token = secrets.token_urlsafe(32)
+    path = token_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(f"{token}\\n")
+    path.chmod(0o600)
+    return token
+
+
+def guard(app: Any, token: str, paths: "set[str]") -> Any:
+    """Wrap the ASGI app: no \`Authorization: Bearer <token>\`, no request — on the API paths only.
+    The page itself is never guarded: a browser cannot put a header on its own document request."""
+    expected = hashlib.sha256(token.encode()).digest()
+
+    async def guarded(scope: Any, receive: Any, send: Any) -> None:
+        if scope["type"] == "http" and scope["path"] in paths:
+            presented = dict(scope["headers"]).get(b"authorization", b"").removeprefix(b"Bearer ")
+            if not hmac.compare_digest(hashlib.sha256(presented).digest(), expected):
+                await send(
+                    {
+                        "type": "http.response.start",
+                        "status": 401,
+                        "headers": [(b"www-authenticate", b"Bearer")],
+                    }
+                )
+                await send({"type": "http.response.body", "body": b""})
+                return
+        await app(scope, receive, send)
+
+    return guarded
+${web ? webRoutes(declared) : ""}
+
+def serve_http(
+    host: str = "127.0.0.1",
+    port: int = 3000,
+    path: str = "/mcp",
+    pair: bool = False,${
+      web
+        ? `
+    open_browser: bool = False,`
+        : ""
+    }
+) -> None:
+    """Serve over MCP streamable HTTP instead of stdio. Opt-in; stdio stays the default transport."""
+    import uvicorn
+${
+  web
+    ? `
+    # \`--open\` needs a token for the page to call back with; an existing one is never rotated,
+    # because the browser extension holds it.
+    token = mint_token() if pair else (paired_token() or (mint_token() if open_browser else None))`
+    : `
+    token = mint_token() if pair else paired_token()`
+}
+    # One ASGI app: the SDK's own streamable-HTTP route (its session-manager lifespan with it),
+    # plus ours. Appending to its router is what keeps that lifespan the app's own.
+    app = server.streamable_http_app(streamable_http_path=path, stateless_http=True, host=host)${
+      web
+        ? `${declared.length ? "\n    app.router.routes.append(env_route(token))" : ""}
+    app.router.routes.append(web_route())`
+        : ""
+    }
+    if token is not None:
+        app = guard(app, token, {path${web && declared.length ? ', "/env"' : ""}})
+    config = uvicorn.Config(app, host=host, port=port, log_level="warning")
+    # Bind before serving: \`--http 0\` asks the OS for a free port and the URL is only known then.
+    sock = config.bind_socket()
+    base = f"http://{host}:{sock.getsockname()[1]}"
+    if pair:
+        print(f"{base}{path}#{token}", flush=True)
+    suffix = " (bearer token required)" if token else ""
+    print(f"Serving MCP streamable HTTP on {base}{path}{suffix}", file=sys.stderr, flush=True)${
+      web
+        ? `
+    if open_browser:
+        webbrowser.open(f"{base}/#{token}")`
+        : ""
+    }
+    uvicorn.Server(config).run(sockets=[sock])
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--http",
+        nargs="?",
+        const=3000,
+        type=int,
+        default=None,
+        metavar="PORT",
+        help="serve over MCP streamable HTTP instead of stdio (default port 3000, host 127.0.0.1, path /mcp)",
+    )
+    parser.add_argument(
+        "--pair",
+        action="store_true",
+        help="serve over HTTP with a fresh pairing token: prints <url>#<token> and requires it as a bearer token",
+    )${
+      web
+        ? `
+    parser.add_argument(
+        "--open",
+        action="store_true",
+        help="serve over HTTP and open the web app in this machine's browser",
+    )`
+        : ""
+    }
+    args = parser.parse_args()
+    if args.http is None and not args.pair${web ? " and not args.open" : ""}:
+        serve()
+    else:
+        # \`--http 0\` is a port, not a missing one: only \`None\` means "use the default".
+        serve_http(port=3000 if args.http is None else args.http, pair=args.pair${web ? ", open_browser=args.open" : ""})
+
+
+if __name__ == "__main__":
+    main()
+`;
+}
+
+function cliTemplate(project: Project): string {
+  const web = has(project, "web");
+  const mcpCommand = has(project, "mcp")
+    ? `
+    mcp = subcommands.add_parser(
+        "mcp", help="Serve the operations as an MCP server over stdio, or over streamable HTTP with --http"
+    )
+    mcp.add_argument(
+        "--http",
+        nargs="?",
+        const=3000,
+        type=int,
+        default=None,
+        metavar="PORT",
+        help="serve over MCP streamable HTTP instead of stdio (default port 3000, host 127.0.0.1, path /mcp)",
+    )
+    mcp.add_argument(
+        "--pair",
+        action="store_true",
+        help="serve over HTTP with a fresh pairing token: prints <url>#<token> and requires it as a bearer token",
+    )${
+      web
+        ? `
+    mcp.add_argument(
+        "--open",
+        action="store_true",
+        help="serve over HTTP and open the web app in this machine's browser",
+    )`
+        : ""
+    }
+    mcp.set_defaults(tf_operation=None, tf_schema={})
+`
+    : "";
+  const mcpDispatch = has(project, "mcp")
+    ? `    if options.tf_operation is None:
+        if options.http is not None or options.pair${web ? " or options.open" : ""}:
+            from .mcp import serve_http
+
+            serve_http(port=3000 if options.http is None else options.http, pair=options.pair${web ? ", open_browser=options.open" : ""})
+        else:
+            from .mcp import serve
+
+            serve()
+        return
+`
+    : "";
+  return `${HEADER}"""The kernel CLI: one subcommand per operation, built from its input model's schema."""
+
+import argparse
+import asyncio
+import inspect
+import json
+from typing import Any
+
+from pydantic import BaseModel
+
+from ..ops import OPERATIONS${web ? " as AUTHORED_OPERATIONS" : ""}
+from .types import serves
+from .config import context${
+    web
+      ? `
+from .web import OPERATION as WEB_OPERATION
+
+#: The authored operations plus the generated \`web\` one, exactly as the MCP kernel lists them.
+OPERATIONS = [*AUTHORED_OPERATIONS, WEB_OPERATION]`
+      : ""
+  }
+
+
+def kind(schema: dict[str, Any]) -> str:
+    """The JSON Schema type of a property, looking through the optional/nullable union."""
+    if "type" in schema:
+        return str(schema["type"])
+    for variant in schema.get("anyOf", []):
+        if variant.get("type") not in (None, "null"):
+            return str(variant["type"])
+    return "string"
+
+
+def coerce(value: str, of: str) -> Any:
+    if of in ("integer", "number"):
+        return int(value) if of == "integer" else float(value)
+    if of == "array":
+        return [item.strip() for item in value.split(",") if item.strip()]
+    if of == "object":
+        return json.loads(value)
+    return value
+
+
+def parser() -> argparse.ArgumentParser:
+    root = argparse.ArgumentParser(
+        prog=${JSON.stringify(project.identity.name)},
+        description=${JSON.stringify(project.identity.description ?? project.identity.name)},
+    )
+    subcommands = root.add_subparsers(dest="tf_command", required=True)
+    for operation in OPERATIONS:
+        if not serves(operation, "cli"):
+            continue
+        schema = operation.input.model_json_schema()
+        command = subcommands.add_parser(operation.name, help=operation.description)
+        command.add_argument(
+            "--json", dest="tf_json", metavar="JSON", help="all arguments as one JSON object"
+        )
+        for name, property in (schema.get("properties") or {}).items():
+            of = kind(property)
+            hint = {"array": " (comma-separated)", "object": " (JSON)"}.get(of, "")
+            help_text = f"{property.get('description', name)}{hint}"
+            if of == "boolean":
+                command.add_argument(f"--{name}", action="store_true", default=None, help=help_text)
+            else:
+                command.add_argument(f"--{name}", metavar="VALUE", help=help_text)
+        command.set_defaults(tf_operation=operation, tf_schema=schema)
+${mcpCommand}    return root
+
+
+def main(argv: list[str] | None = None) -> None:
+    options = parser().parse_args(argv)
+${mcpDispatch}    operation = options.tf_operation
+    properties: dict[str, Any] = options.tf_schema.get("properties") or {}
+    values: dict[str, Any] = json.loads(options.tf_json) if options.tf_json else {}
+    for name, property in properties.items():
+        given = getattr(options, name, None)
+        if given is not None:
+            values[name] = given if isinstance(given, bool) else coerce(given, kind(property))
+    result = operation.handler(operation.input(**values), context())
+    if inspect.isawaitable(result):
+        result = asyncio.run(result)
+    payload = result.model_dump(mode="json") if isinstance(result, BaseModel) else result
+    print(json.dumps(payload, indent=2, default=str))
+
+
+if __name__ == "__main__":
+    main()
+`;
+}
+
+function opsScaffold(): string {
+  return `"""Your tool's operations: pure functions of (arguments, context.config, filesystem).
+
+Declare \`requires\` for anything a host must provide; toolfactory decides per surface
+whether that operation is native, bridged, degraded, or excluded.
+"""
+
+from pydantic import BaseModel, Field
+
+from .toolfactory import Context, Operation
+
+
+class EchoInput(BaseModel):
+    text: str = Field(description="Text to echo back")
+
+
+class EchoOutput(BaseModel):
+    text: str
+
+
+def echo(arguments: EchoInput, context: Context) -> EchoOutput:
+    return EchoOutput(text=arguments.text)
+
+
+OPERATIONS = [
+    Operation(
+        name="echo",
+        description="Return the text you pass in.",
+        input=EchoInput,
+        output=EchoOutput,
+        annotations={"readOnlyHint": True},
+        handler=echo,
+    ),
+]
+`;
+}
+
+/**
+ * The T4 live tier: real calls against the real service, kept out of the default `pytest` run
+ * by a generated guard over the credentials `tool.json` declares as required and sensitive.
+ * The markers hold only the guard; the example test around them is the author's.
+ */
+export function liveTest(project: Project): PlannedFile[] {
+  const credentials = liveCredentials(project).map(envName);
+  const example = liveExample(project);
+  if (credentials.length === 0 || !example) return [];
+  const tuple = `(${credentials.map((name) => JSON.stringify(name)).join(", ")}${credentials.length === 1 ? "," : ""})`;
+  const guard = `
+CREDENTIALS = ${tuple}
+LIVE = all(os.environ.get(name) for name in CREDENTIALS)
+`;
+  const pkg = pythonPackage(project);
+  const template = `"""Live tests: real calls against the real service, so they run only when the credentials
+(${credentials.join(", ")}) are in the environment — a plain \`pytest\` run skips them.
+
+Locally: copy .env.example to .env, fill it in, then
+    ${LIVE_TEST_COMMAND.replace("uv run ", "uv run --env-file .env ")}
+In CI:   the \`live\` job of .github/workflows/ci.yml, from the \`live-tests\` environment.
+"""
+
+import asyncio
+import inspect
+import os
+
+import pytest
+
+from ${pkg}.ops import OPERATIONS
+from ${pkg}.toolfactory.config import context
+
+${LIVE_GUARD_BEGIN}${LIVE_GUARD_END}
+
+
+@pytest.mark.skipif(not LIVE, reason=f"live credentials are not set: {', '.join(CREDENTIALS)}")
+def test_${example.name.replace(/[^A-Za-z0-9_]/g, "_")}() -> None:
+    operation = next(op for op in OPERATIONS if op.name == ${JSON.stringify(example.name)})
+    result = operation.handler(
+        operation.input.model_validate_json(${JSON.stringify(JSON.stringify(example.args))}), context()
+    )
+    if inspect.isawaitable(result):
+        result = asyncio.run(result)
+    # Replace this with the assertion that proves the real service answered correctly.
+    assert result is not None
+`;
+  return [
+    {
+      kind: "region",
+      path: LIVE_TEST_PATH,
+      regions: [{ begin: LIVE_GUARD_BEGIN, end: LIVE_GUARD_END, content: guard }],
+      template,
+    },
+  ];
+}
+
+/** Generated on every build. */
+export function kernel(project: Project): PlannedFile[] {
+  const dir = kernelDir(project);
+  const files: PlannedFile[] = [
+    { kind: "file", path: `${dir}/__init__.py`, content: initTemplate() },
+    { kind: "file", path: `${dir}/types.py`, content: typesTemplate() },
+    { kind: "file", path: `${dir}/config.py`, content: configTemplate(project) },
+  ];
+  files.push({ kind: "file", path: `${dir}/mcp.py`, content: mcpTemplate(project) });
+  // The `web` surface's own operation: generated here because it is the kernel's listener it
+  // starts, and appended to `OPERATIONS` by the two templates above, so `introspect` sees it.
+  if (has(project, "web")) {
+    files.push({ kind: "file", path: `${dir}/web.py`, content: webTemplate() });
+  }
+  return files;
+}
+
+/** The CLI surface's file. */
+export function cli(project: Project): PlannedFile[] {
+  return [{ kind: "file", path: `${kernelDir(project)}/cli.py`, content: cliTemplate(project) }];
+}
+
+/** The `[project]` table the scaffold and the pypi surface agree on. */
+export function projectTable(project: Project): Record<string, unknown> {
+  const { identity } = project;
+  return compact({
+    name: pypiName(project),
+    version: identity.version,
+    description: identity.description,
+    license: identity.license,
+    keywords: identity.keywords,
+    authors: identity.author?.name
+      ? [compact({ name: identity.author.name, email: identity.author.email })]
+      : undefined,
+    urls:
+      identity.homepage || identity.repository
+        ? compact({ Homepage: identity.homepage, Repository: identity.repository })
+        : undefined,
+  });
+}
+
+/** Written by `init` only when absent; owned by the author afterwards. */
+export function scaffold(project: Project): PlannedFile[] {
+  const pkg = pythonPackage(project);
+  const pyproject = {
+    project: {
+      ...projectTable(project),
+      "requires-python": ">=3.11",
+      dependencies: ["mcp>=2,<3", "pydantic>=2"],
+      ...(has(project, "cli")
+        ? { scripts: { [project.identity.name]: cliEntryPoint(project) } }
+        : {}),
+    },
+    "build-system": { requires: ["hatchling"], "build-backend": "hatchling.build" },
+    tool: { hatch: { build: { targets: { wheel: { packages: [`src/${pkg}`] } } } } },
+  };
+  return [
+    {
+      kind: "file",
+      path: `src/${pkg}/__init__.py`,
+      content: `"""${project.identity.description ?? project.identity.name}"""\n`,
+    },
+    { kind: "file", path: opsPath(project), content: opsScaffold() },
+    { kind: "file", path: "pyproject.toml", content: `${toml(pyproject)}\n` },
+  ];
+}