@pome-sh/cli 0.19.0 → 0.21.0

package/dist/chunk-LZIPGCQJ.js

@@ -0,0 +1,1512 @@
+import { redactSecrets, redactEvent } from './chunk-SG6ZTIMT.js';
+import { Hono } from 'hono';
+import { z } from 'zod';
+import { mkdirSync, openSync, createWriteStream, closeSync, writeFileSync, rmSync, readFileSync, fsync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { timingSafeEqual, createHmac, randomBytes, randomUUID } from 'node:crypto';
+import { verify } from 'hono/jwt';
+
+var NodeSqliteTwinDatabase = class {
+  #db;
+  #savepointId = 0;
+  constructor(path) {
+    this.#db = new DatabaseSync(path);
+  }
+  prepare(sql) {
+    const statement = this.#db.prepare(sql);
+    return {
+      run: (...params) => {
+        const result = statement.run(...params);
+        return { changes: Number(result.changes), lastInsertRowid: result.lastInsertRowid };
+      },
+      get: (...params) => statement.get(...params),
+      all: (...params) => statement.all(...params)
+    };
+  }
+  exec(sql) {
+    this.#db.exec(sql);
+  }
+  pragma(statement, options = {}) {
+    const rows = this.#db.prepare(`PRAGMA ${statement}`).all();
+    if (!options.simple)
+      return rows;
+    const row = rows[0];
+    if (row === void 0)
+      return void 0;
+    return row[Object.keys(row)[0]];
+  }
+  transaction(fn) {
+    const wrap = (begin) => ((...args) => {
+      if (this.#db.isTransaction)
+        return this.#nested(fn, args);
+      this.#db.exec(begin);
+      try {
+        const out = fn(...args);
+        this.#db.exec("COMMIT");
+        return out;
+      } catch (error) {
+        if (this.#db.isTransaction)
+          this.#db.exec("ROLLBACK");
+        throw error;
+      }
+    });
+    const tx = wrap("BEGIN");
+    tx.immediate = wrap("BEGIN IMMEDIATE");
+    return tx;
+  }
+  /**
+   * A transaction function called inside an open transaction joins it under a
+   * SAVEPOINT (better-sqlite3's semantics): success releases the savepoint,
+   * failure rolls back only the inner work. The BEGIN variant is irrelevant
+   * here — the outermost transaction already holds the lock mode.
+   */
+  #nested(fn, args) {
+    const name = `_pome_tx_${this.#savepointId++}`;
+    this.#db.exec(`SAVEPOINT ${name}`);
+    try {
+      const out = fn(...args);
+      this.#db.exec(`RELEASE ${name}`);
+      return out;
+    } catch (error) {
+      if (this.#db.isTransaction) {
+        this.#db.exec(`ROLLBACK TO ${name}`);
+        this.#db.exec(`RELEASE ${name}`);
+      }
+      throw error;
+    }
+  }
+  close() {
+    if (this.#db.isOpen)
+      this.#db.close();
+  }
+};
+function openTwinDatabase(path = ":memory:", options = {}) {
+  if (path !== ":memory:") {
+    mkdirSync(dirname(path), { recursive: true });
+  }
+  const db = new NodeSqliteTwinDatabase(path);
+  db.exec("PRAGMA busy_timeout = 5000");
+  db.exec("PRAGMA journal_mode = WAL");
+  db.exec("PRAGMA foreign_keys = ON");
+  options.migrate?.(db);
+  return db;
+}
+
+// ../packages/sdk/dist/index.js
+var fidelityTierSchema = z.enum(["semantic", "shape", "unsupported"]);
+function toolInputSchema(tool) {
+  return tool.inputSchema ?? z.toJSONSchema(tool.schema);
+}
+function toolListExtras(tool) {
+  return {
+    ...tool.title !== void 0 ? { title: tool.title } : {},
+    ...tool.outputSchema !== void 0 ? { outputSchema: tool.outputSchema } : {},
+    ...tool.annotations ? { annotations: tool.annotations } : {}
+  };
+}
+var TwinManifestError = class extends Error {
+  issues;
+  constructor(message, issues = []) {
+    super(message);
+    this.issues = issues;
+    this.name = "TwinManifestError";
+  }
+};
+var isZodType = (value) => value instanceof z.ZodType || typeof value === "object" && value !== null && typeof value.parse === "function" && typeof value.safeParse === "function";
+var isFunction = (value) => typeof value === "function";
+var slugLike = /^[a-z][a-z0-9_-]*$/;
+var toolFidelityMeta = z.object({
+  tier: fidelityTierSchema.optional(),
+  backingSurface: z.string().optional(),
+  tests: z.array(z.string()).optional(),
+  deviations: z.string().optional()
+});
+var toolMeta = z.object({
+  name: z.string().min(1).regex(slugLike, "tool name must be a lowercase slug"),
+  description: z.string().min(1),
+  schema: z.custom(isZodType, "tool.schema must be a Zod schema"),
+  handler: z.custom(isFunction, "tool.handler must be a function"),
+  mutation: z.boolean(),
+  fidelity: toolFidelityMeta.optional(),
+  title: z.string().min(1).optional(),
+  annotations: z.record(z.string(), z.unknown()).optional(),
+  inputSchema: z.record(z.string(), z.unknown()).optional(),
+  outputSchema: z.record(z.string(), z.unknown()).optional()
+});
+var adminMeta = z.object({
+  reset: z.custom(isFunction).optional(),
+  seed: z.custom(isFunction).optional(),
+  recorded: z.boolean().optional(),
+  errorEnvelope: z.custom(isFunction).optional(),
+  forbidden: z.custom(isFunction).optional()
+});
+var twinMeta = z.object({
+  id: z.string().min(1).regex(slugLike, "twin id must be a lowercase slug"),
+  version: z.string().min(1),
+  fidelity: z.object({ default: fidelityTierSchema }),
+  seed: z.custom(isZodType, "seed must be a Zod schema").optional(),
+  domain: z.custom(isFunction, "domain must be a function"),
+  routes: z.custom(isFunction, "routes must be a function").optional(),
+  tools: z.array(toolMeta),
+  state: z.custom(isFunction).optional(),
+  admin: adminMeta.optional(),
+  errorEnvelope: z.custom(isFunction).optional(),
+  implementation: z.string().min(1).optional(),
+  packageName: z.string().min(1).optional(),
+  healthz: z.custom(isFunction).optional(),
+  bodyReader: z.custom(isFunction).optional(),
+  middleware: z.custom(isFunction).optional(),
+  legacyMcp: z.object({
+    aliases: z.boolean().optional(),
+    missingTool: z.custom(isFunction).optional()
+  }).optional(),
+  pomeHealth: z.custom(isFunction).optional(),
+  unsupported: z.custom(isFunction).optional(),
+  pomeRoutes: z.record(z.string(), z.custom(isFunction)).optional(),
+  stampToolCallId: z.boolean().optional(),
+  mcpUnknownTool: z.custom(isFunction).optional(),
+  sessionHealthz: z.boolean().optional(),
+  mountSessionAtRoot: z.boolean().optional(),
+  auth: z.custom((value) => typeof value === "object" && value !== null, "auth must be an options object").optional(),
+  recordingProjection: z.custom(isFunction).optional()
+});
+function defineTwin(spec) {
+  const parsed = twinMeta.safeParse(spec);
+  if (!parsed.success) {
+    const detail = parsed.error.issues.map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`).join("; ");
+    throw new TwinManifestError(`Invalid twin manifest: ${detail}`, parsed.error.issues);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const tool of spec.tools) {
+    if (seen.has(tool.name)) {
+      throw new TwinManifestError(`Duplicate tool name: ${tool.name}`);
+    }
+    seen.add(tool.name);
+  }
+  return spec;
+}
+var RESERVED_SESSION_PREFIXES = ["/_pome", "/mcp"];
+var CLIENT_IP_VAR = "pomeClientIp";
+var nodeGetConnInfo;
+function loadNodeGetConnInfo() {
+  nodeGetConnInfo ??= import('@hono/node-server/conninfo').then((mod) => mod.getConnInfo, () => void 0);
+  return nodeGetConnInfo;
+}
+function setClientIp(c, ip) {
+  c.set(CLIENT_IP_VAR, ip);
+}
+async function getClientIp(c) {
+  const override = c.get(CLIENT_IP_VAR);
+  if (typeof override === "string" && override.length > 0)
+    return override;
+  const getConnInfo = await loadNodeGetConnInfo();
+  if (!getConnInfo)
+    return void 0;
+  try {
+    const address = getConnInfo(c).remote?.address;
+    return typeof address === "string" && address.length > 0 ? address : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function isLoopbackAddress(remote) {
+  return remote === "127.0.0.1" || remote === "::1" || remote === "::ffff:127.0.0.1" || remote === "localhost";
+}
+function defaultForbidden() {
+  return Response.json({ message: "Forbidden", documentation_url: "" }, { status: 403 });
+}
+function createAdminGate(options = {}) {
+  const forbidden = options.forbidden ?? defaultForbidden;
+  return async (c, next) => {
+    const adminToken = process.env.TWIN_ADMIN_TOKEN;
+    if (adminToken && adminToken.length > 0) {
+      const provided = c.req.header("X-Admin-Token");
+      if (!provided)
+        return forbidden();
+      const a = Buffer.from(provided);
+      const b = Buffer.from(adminToken);
+      if (a.length !== b.length || !timingSafeEqual(a, b))
+        return forbidden();
+      await next();
+      return;
+    }
+    const remote = await getClientIp(c);
+    if (!remote) {
+      if (process.env.NODE_ENV === "production")
+        return forbidden();
+      await next();
+      return;
+    }
+    if (!isLoopbackAddress(remote))
+      return forbidden();
+    await next();
+  };
+}
+
+// ../packages/sdk/dist/auth.js
+var PROVIDER_SHAPED_TEAM_ID = "provider-shaped";
+function resolveAuthSecret() {
+  const secret = process.env.TWIN_AUTH_SECRET;
+  if (!secret && process.env.NODE_ENV === "production") {
+    throw new Error("TWIN_AUTH_SECRET required in production");
+  }
+  return secret ?? "dev-only-insecure-secret";
+}
+var SIG_LENGTH = 22;
+function mintProviderToken(spec, options) {
+  const prefix = options.prefix ?? spec.prefixes[0];
+  if (!prefix || !spec.prefixes.includes(prefix)) {
+    throw new Error(`mintProviderToken: prefix "${options.prefix ?? "<none>"}" is not declared by provider "${spec.provider}"`);
+  }
+  const secret = options.secret ?? resolveAuthSecret();
+  const encoded = Buffer.from(options.sid, "utf8").toString("base64url");
+  if (options.exp !== void 0) {
+    if (!Number.isSafeInteger(options.exp) || options.exp <= 0) {
+      throw new Error(`mintProviderToken: exp must be a positive integer unix timestamp in seconds (got ${String(options.exp)})`);
+    }
+    if (options.exp >= 1e12) {
+      throw new Error(`mintProviderToken: exp ${options.exp} looks like milliseconds \u2014 pass a unix timestamp in SECONDS`);
+    }
+    return `${prefix}${encoded}_${options.exp}_${signProviderExp(spec.provider, options.sid, options.exp, secret)}`;
+  }
+  return `${prefix}${encoded}_${signProvider(spec.provider, options.sid, secret)}`;
+}
+function verifyProviderToken(spec, token, secret = resolveAuthSecret()) {
+  const prefix = spec.prefixes.find((p) => token.startsWith(p));
+  if (!prefix)
+    return void 0;
+  const rest = token.slice(prefix.length);
+  if (rest.length < SIG_LENGTH + 2)
+    return void 0;
+  if (rest[rest.length - SIG_LENGTH - 1] !== "_")
+    return void 0;
+  const sig = rest.slice(-SIG_LENGTH);
+  const head = rest.slice(0, -23);
+  const expMatch = head.match(/^(.+)_(\d{1,12})$/);
+  if (expMatch) {
+    const sid2 = decodeBase64Url(expMatch[1]);
+    const exp = Number(expMatch[2]);
+    if (sid2 !== void 0 && Number.isSafeInteger(exp)) {
+      if (safeEqual(sig, signProviderExp(spec.provider, sid2, exp, secret))) {
+        return exp >= Math.floor(Date.now() / 1e3) ? sid2 : void 0;
+      }
+    }
+  }
+  const sid = decodeBase64Url(head);
+  if (sid === void 0)
+    return void 0;
+  if (safeEqual(sig, signProvider(spec.provider, sid, secret)))
+    return sid;
+  return void 0;
+}
+function signProvider(provider, sid, secret) {
+  return createHmac("sha256", secret).update(`${provider}:${sid}`).digest("base64url").slice(0, SIG_LENGTH);
+}
+function signProviderExp(provider, sid, exp, secret) {
+  return createHmac("sha256", secret).update(`${provider}:${sid}:${exp}`).digest("base64url").slice(0, SIG_LENGTH);
+}
+function decodeBase64Url(value) {
+  try {
+    return Buffer.from(value, "base64url").toString("utf8");
+  } catch {
+    return void 0;
+  }
+}
+function safeEqual(a, b) {
+  const ab = Buffer.from(a);
+  const bb = Buffer.from(b);
+  return ab.length === bb.length && timingSafeEqual(ab, bb);
+}
+function queryTokenResolver(param = "token") {
+  return (c) => {
+    const token = c.req.query(param);
+    return token && token.length > 0 ? token : void 0;
+  };
+}
+function formTokenResolver(param = "token") {
+  return async (c) => {
+    if (c.req.method !== "POST")
+      return void 0;
+    const contentType = (c.req.header("content-type") ?? "").toLowerCase();
+    if (!contentType.includes("application/x-www-form-urlencoded") && !contentType.includes("multipart/form-data")) {
+      return void 0;
+    }
+    try {
+      const body = await c.req.parseBody();
+      const token = body[param];
+      return typeof token === "string" && token.length > 0 ? token : void 0;
+    } catch {
+      return void 0;
+    }
+  };
+}
+var defaultUnauthorized = () => ({
+  status: 401,
+  body: { message: "Bad credentials", documentation_url: "" }
+});
+var defaultSidMismatch = () => ({
+  status: 401,
+  body: { message: "Forbidden", documentation_url: "" }
+});
+function respond(envelope) {
+  return Response.json(envelope.body, { status: envelope.status });
+}
+function extractSidFromUrl(rawUrl) {
+  try {
+    const path = new URL(rawUrl).pathname;
+    const match = path.match(/^\/s\/([^/]+)/);
+    return match?.[1] ? decodeURIComponent(match[1]) : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function bearerHeaderToken(c, allowRaw) {
+  const header = c.req.header("Authorization") ?? c.req.header("authorization");
+  if (!header)
+    return void 0;
+  const trimmed = header.trim();
+  if (allowRaw) {
+    if (trimmed.toLowerCase().startsWith("bearer ")) {
+      const token2 = trimmed.slice("bearer ".length).trim();
+      return token2.length > 0 ? token2 : void 0;
+    }
+    return trimmed.length > 0 ? trimmed : void 0;
+  }
+  if (!trimmed.startsWith("Bearer "))
+    return void 0;
+  const token = trimmed.slice("Bearer ".length).trim();
+  return token.length > 0 ? token : void 0;
+}
+function classifyJwtError(err) {
+  const name = err.name ?? "";
+  const message = err instanceof Error ? err.message : "";
+  return name === "JwtTokenExpired" || /expired/i.test(message) ? "expired" : "invalid";
+}
+function bearerAuth(options = {}) {
+  const unauthorized = options.unauthorized ?? defaultUnauthorized;
+  const sidMismatch = options.sidMismatch ?? defaultSidMismatch;
+  const requirePathSid = options.requirePathSid ?? true;
+  const allowRawBearer = options.allowRawBearer === true;
+  return async (c, next) => {
+    let token = bearerHeaderToken(c, allowRawBearer);
+    if (!token && options.tokenResolvers) {
+      for (const resolveToken of options.tokenResolvers) {
+        token = await resolveToken(c) || void 0;
+        if (token)
+          break;
+      }
+    }
+    if (!token)
+      return respond(unauthorized("no_token"));
+    const pathSid = c.req.param("sid") ?? extractSidFromUrl(c.req.url);
+    const checkSid = (sid) => {
+      if (pathSid)
+        return sid === pathSid ? void 0 : respond(sidMismatch());
+      return requirePathSid ? respond(sidMismatch()) : void 0;
+    };
+    if (options.resolveCredential) {
+      const resolved = await options.resolveCredential(token, c);
+      if (resolved) {
+        const mismatch2 = checkSid(resolved.sid);
+        if (mismatch2)
+          return mismatch2;
+        c.set("session", resolved);
+        await next();
+        return;
+      }
+    }
+    if (options.providerToken) {
+      const providerSid = verifyProviderToken(options.providerToken, token);
+      if (providerSid) {
+        const mismatch2 = checkSid(providerSid);
+        if (mismatch2)
+          return mismatch2;
+        c.set("session", {
+          sid: providerSid,
+          team_id: PROVIDER_SHAPED_TEAM_ID,
+          ...options.providerSession?.(providerSid) ?? {}
+        });
+        await next();
+        return;
+      }
+    }
+    let claims;
+    try {
+      claims = await verify(token, resolveAuthSecret(), "HS256");
+    } catch (err) {
+      return respond(unauthorized(classifyJwtError(err), { token }));
+    }
+    if (typeof claims.exp === "number" && claims.exp < Math.floor(Date.now() / 1e3)) {
+      return respond(unauthorized("expired", { token }));
+    }
+    if (!claims.sid)
+      return respond(unauthorized("invalid", { token }));
+    const mismatch = checkSid(claims.sid);
+    if (mismatch)
+      return mismatch;
+    c.set("session", {
+      sid: claims.sid,
+      team_id: claims.team_id,
+      ...options.sessionExtras?.(claims) ?? {}
+    });
+    await next();
+  };
+}
+function requireAdminAuth() {
+  return createAdminGate();
+}
+
+// ../packages/sdk/dist/tool-context.js
+function makeToolCallContext(c) {
+  let reported = null;
+  let didReport = false;
+  return {
+    ctx: {
+      session: c.get("session"),
+      reportDelta: (delta) => {
+        reported = delta;
+        didReport = true;
+      }
+    },
+    delta: () => reported,
+    reportedDelta: () => didReport
+  };
+}
+
+// ../packages/sdk/dist/build-info.js
+function twinBuildInfo(packageName) {
+  return {
+    package: packageName,
+    version: process.env.POME_TWIN_VERSION ?? "0.1.0",
+    git_sha: process.env.POME_TWIN_GIT_SHA ?? process.env.VERCEL_GIT_COMMIT_SHA ?? "dev",
+    build_time: process.env.POME_TWIN_BUILD_TIME ?? "dev"
+  };
+}
+var TwinError = class extends Error {
+  status;
+  errors;
+  constructor(message, status, errors) {
+    super(message);
+    this.status = status;
+    this.errors = errors;
+    this.name = "TwinError";
+  }
+};
+var UnknownToolError = class extends TwinError {
+  tool;
+  constructor(tool, status = 404) {
+    super(`Unknown tool: ${tool}`, status);
+    this.tool = tool;
+    this.name = "UnknownToolError";
+  }
+};
+function envelopeFor(error) {
+  if (error instanceof TwinError) {
+    return {
+      status: error.status,
+      body: { message: error.message, ...error.errors ? { errors: error.errors } : {} }
+    };
+  }
+  if (error instanceof z.ZodError) {
+    return {
+      status: 422,
+      body: {
+        message: "Validation Failed",
+        errors: error.issues.map((issue) => ({
+          field: issue.path.join("."),
+          code: issue.code,
+          message: issue.message
+        }))
+      }
+    };
+  }
+  if (error instanceof SyntaxError) {
+    return { status: 400, body: { message: "Problems parsing JSON" } };
+  }
+  return {
+    status: 500,
+    body: { message: error instanceof Error ? error.message : "Internal Server Error" }
+  };
+}
+
+// ../packages/sdk/dist/request-capture.js
+function recordedRequestHeaders(c) {
+  return c.req.header();
+}
+var RECORDED_TOOL_KEY = "pomeRecordedTool";
+function setRecordedTool(c, tool) {
+  c.set(RECORDED_TOOL_KEY, tool);
+}
+function resolveRecordedTool(c, declared) {
+  const stashed = c.get(RECORDED_TOOL_KEY);
+  if (typeof stashed === "string" && stashed.length > 0)
+    return stashed;
+  return declared && declared.length > 0 ? declared : null;
+}
+
+// ../packages/sdk/dist/mcp-jsonrpc.js
+var PARSE_ERROR = -32700;
+var INVALID_REQUEST = -32600;
+var METHOD_NOT_FOUND = -32601;
+var INVALID_PARAMS = -32602;
+var INTERNAL_ERROR = -32603;
+var DEFAULT_PROTOCOL_VERSION = "2025-06-18";
+var SUPPORTED_PROTOCOL_VERSIONS = /* @__PURE__ */ new Set(["2024-11-05", "2025-03-26", "2025-06-18"]);
+function mcpMethodNotAllowed(c) {
+  return c.json({ jsonrpc: "2.0", id: null, error: { code: METHOD_NOT_FOUND, message: "Method not allowed in stateless mode" } }, 405, { Allow: "POST" });
+}
+async function handleMcpJsonRpc(c, deps) {
+  let body;
+  try {
+    body = await c.req.json();
+  } catch {
+    return jsonRpcErrorResponse(null, PARSE_ERROR, "Problems parsing JSON");
+  }
+  if (Array.isArray(body)) {
+    if (body.length === 0) {
+      return jsonRpcErrorResponse(null, INVALID_REQUEST, "Invalid Request");
+    }
+    const out = [];
+    for (const message of body) {
+      const response2 = await dispatch(message, deps, c);
+      if (response2)
+        out.push(response2);
+    }
+    if (out.length === 0)
+      return new Response(null, { status: 202 });
+    return Response.json(out, { status: 200, headers: { "content-type": "application/json" } });
+  }
+  const response = await dispatch(body, deps, c);
+  if (!response)
+    return new Response(null, { status: 202 });
+  return Response.json(response, { status: 200, headers: { "content-type": "application/json" } });
+}
+async function dispatch(message, deps, c) {
+  if (!isObject(message))
+    return errorEnvelope(null, INVALID_REQUEST, "Invalid Request");
+  if (message.jsonrpc !== "2.0" || typeof message.method !== "string") {
+    return errorEnvelope(idOf(message), INVALID_REQUEST, "Invalid Request");
+  }
+  const method = message.method;
+  const params = isObject(message.params) ? message.params : {};
+  const rawId = message.id;
+  if (rawId === void 0 || rawId === null)
+    return null;
+  if (typeof rawId !== "string" && typeof rawId !== "number") {
+    return errorEnvelope(null, INVALID_REQUEST, "Invalid Request: id must be string or number");
+  }
+  const id = rawId;
+  try {
+    switch (method) {
+      case "initialize":
+        return { jsonrpc: "2.0", id, result: buildInitializeResult(params, deps.definition) };
+      case "ping":
+        return { jsonrpc: "2.0", id, result: {} };
+      case "tools/list":
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            tools: deps.definition.tools.map((tool) => ({
+              name: tool.name,
+              description: tool.description,
+              inputSchema: toolInputSchema(tool),
+              ...toolListExtras(tool)
+            }))
+          }
+        };
+      case "tools/call":
+        return await handleToolsCall(id, params, deps, c);
+      default:
+        return errorEnvelope(id, METHOD_NOT_FOUND, `Method not found: ${method}`);
+    }
+  } catch (err) {
+    return errorEnvelope(id, INTERNAL_ERROR, err instanceof Error ? err.message : "Internal error");
+  }
+}
+function buildInitializeResult(params, definition) {
+  const requested = typeof params.protocolVersion === "string" ? params.protocolVersion : void 0;
+  const protocolVersion = requested && SUPPORTED_PROTOCOL_VERSIONS.has(requested) ? requested : DEFAULT_PROTOCOL_VERSION;
+  return {
+    protocolVersion,
+    capabilities: { tools: { listChanged: false } },
+    serverInfo: { name: `twin-${definition.id}`, version: definition.version }
+  };
+}
+async function handleToolsCall(id, params, deps, c) {
+  const name = params.name;
+  const args = params.arguments === void 0 || params.arguments === null ? {} : isObject(params.arguments) ? params.arguments : void 0;
+  if (typeof name !== "string" || name.length === 0 || args === void 0) {
+    return errorEnvelope(id, INVALID_PARAMS, "Invalid params: expected { name: string, arguments?: object }");
+  }
+  const projectError = deps.definition.errorEnvelope ?? envelopeFor;
+  const tool = deps.definition.tools.find((t) => t.name === name);
+  const started = Date.now();
+  const call = makeToolCallContext(c);
+  let status;
+  let responseBody;
+  let toolError = null;
+  let mutation = false;
+  let mcpResult;
+  if (!tool) {
+    const envelope = projectError(new UnknownToolError(name));
+    const body = deps.definition.mcpUnknownTool ? deps.definition.mcpUnknownTool(name) : envelope.body;
+    status = envelope.status;
+    responseBody = body;
+    toolError = `Unknown tool: ${name}`;
+    mcpResult = { content: [{ type: "text", text: JSON.stringify(body) }], isError: true };
+  } else {
+    try {
+      const parsed = tool.schema.parse(args);
+      const value = await tool.handler(deps.domain, parsed, call.ctx);
+      status = 200;
+      responseBody = value;
+      mutation = tool.mutation;
+      mcpResult = {
+        content: [
+          {
+            type: "text",
+            text: tool.contentText ? tool.contentText(value) : JSON.stringify(value)
+          }
+        ],
+        ...tool.outputSchema !== void 0 ? { structuredContent: value } : {},
+        ...tool.includeIsError ? { isError: false } : {}
+      };
+    } catch (err) {
+      const envelope = projectError(err);
+      status = envelope.status;
+      responseBody = envelope.body;
+      toolError = err instanceof Error ? err.message : "tool call failed";
+      mcpResult = { content: [{ type: "text", text: JSON.stringify(envelope.body) }], isError: true };
+    }
+  }
+  const delta = status < 400 ? call.delta() : null;
+  const effectiveMutation = status < 400 && mutation && (!call.reportedDelta() || delta !== null);
+  deps.recorder.record(buildEventCore(c, deps, {
+    started,
+    status,
+    requestBody: { tool: name, arguments: args },
+    responseBody,
+    mutation: effectiveMutation,
+    delta,
+    error: toolError,
+    // The name the CALLER used, stamped even when `tool` above is undefined
+    // (unknown tool) or the handler threw. See `RecorderEvent.tool`.
+    tool: name
+  }));
+  return { jsonrpc: "2.0", id, result: mcpResult };
+}
+function buildEventCore(c, deps, fields) {
+  const requestId = `req_${randomUUID()}`;
+  const stepId = c.req.header("x-pome-scenario-step-id") ?? null;
+  const correlationHeader = c.req.header("x-pome-correlation-id") ?? null;
+  return {
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    run_id: deps.runId,
+    twin: deps.definition.id,
+    request_id: requestId,
+    correlation_id: correlationHeader ?? requestId,
+    task_step_id: stepId,
+    scenario_step_id: stepId,
+    step_id: null,
+    // FDRS-402 adapter-rich path — per-twin pin, see recorder.ts (F-682).
+    tool_call_id: deps.definition.stampToolCallId ? correlationHeader : null,
+    method: c.req.method,
+    path: new URL(c.req.url).pathname,
+    request_body: fields.requestBody,
+    request_headers: recordedRequestHeaders(c),
+    // F-1125 — the whole reason the field exists. This surface is where the
+    // tool name used to be reachable only by digging it out of `request_body`
+    // on a `/mcp` path; a check that had to do that was reverse-engineering
+    // transport, and getting it wrong false-passes a negative criterion.
+    tool: fields.tool,
+    status: fields.status,
+    response_body: fields.responseBody,
+    latency_ms: Date.now() - fields.started,
+    fidelity: "semantic",
+    state_mutation: fields.mutation,
+    state_delta: fields.delta,
+    error: fields.error
+  };
+}
+function errorEnvelope(id, code, message) {
+  return { jsonrpc: "2.0", id, error: { code, message } };
+}
+function jsonRpcErrorResponse(id, code, message) {
+  return Response.json(errorEnvelope(id, code, message), {
+    status: 200,
+    headers: { "content-type": "application/json" }
+  });
+}
+function idOf(message) {
+  const id = message.id;
+  if (typeof id === "string" || typeof id === "number")
+    return id;
+  return null;
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function createRecorderStore(options = {}) {
+  const items = [];
+  const cap = options.maxEvents !== void 0 ? Math.max(1, options.maxEvents) : void 0;
+  let droppedCount = 0;
+  return {
+    record(event) {
+      items.push(event);
+      if (cap !== void 0) {
+        while (items.length > cap) {
+          items.shift();
+          droppedCount += 1;
+        }
+      }
+    },
+    events() {
+      return [...items];
+    },
+    count() {
+      return items.length;
+    },
+    dropped() {
+      return droppedCount;
+    },
+    async flush() {
+    },
+    async close() {
+    }
+  };
+}
+var POME_RECORDER_EVENTS_PATH = "POME_RECORDER_EVENTS_PATH";
+function toTwinHttpEventRow(event) {
+  const maybeKind = event.kind;
+  if (maybeKind === "TwinHttpEvent") {
+    const existing = event;
+    return {
+      ...existing,
+      event_id: typeof existing.event_id === "string" ? existing.event_id : event.request_id,
+      parent_event_id: null
+    };
+  }
+  return {
+    ...event,
+    kind: "TwinHttpEvent",
+    event_id: event.request_id,
+    parent_event_id: null
+  };
+}
+function createFileBackedRecorderStore(options) {
+  const items = [];
+  const cap = options.maxEvents !== void 0 ? Math.max(1, options.maxEvents) : void 0;
+  let droppedCount = 0;
+  let closed = false;
+  const doFsync = options.fsync !== false;
+  mkdirSync(dirname(options.path), { recursive: true });
+  const fd = openSync(options.path, "a");
+  const writer = createWriteStream(options.path, { fd, autoClose: false });
+  const pending = /* @__PURE__ */ new Set();
+  let writeFailure = null;
+  function enqueueWrite(line) {
+    const write = new Promise((resolve, reject) => {
+      writer.write(line, (err) => {
+        if (err) {
+          reject(err);
+          return;
+        }
+        if (!doFsync) {
+          resolve();
+          return;
+        }
+        fsync(fd, (fsyncErr) => fsyncErr ? reject(fsyncErr) : resolve());
+      });
+    });
+    pending.add(write);
+    void write.then(() => {
+      pending.delete(write);
+    }, (err) => {
+      pending.delete(write);
+      if (!writeFailure) {
+        writeFailure = err instanceof Error ? err : new Error(String(err));
+      }
+    });
+  }
+  async function flush() {
+    while (pending.size > 0) {
+      await Promise.allSettled([...pending]);
+    }
+    if (writeFailure) {
+      const err = writeFailure;
+      writeFailure = null;
+      throw err;
+    }
+  }
+  return {
+    record(event) {
+      if (closed) {
+        throw new Error("RecorderStore.record() after close()");
+      }
+      items.push(event);
+      if (cap !== void 0) {
+        while (items.length > cap) {
+          items.shift();
+          droppedCount += 1;
+        }
+      }
+      enqueueWrite(`${JSON.stringify(toTwinHttpEventRow(event))}
+`);
+    },
+    events() {
+      return [...items];
+    },
+    count() {
+      return items.length;
+    },
+    dropped() {
+      return droppedCount;
+    },
+    flush,
+    async close() {
+      if (closed) {
+        await flush();
+        return;
+      }
+      closed = true;
+      await flush();
+      await new Promise((resolve, reject) => {
+        writer.end((err) => {
+          try {
+            closeSync(fd);
+          } catch (closeErr) {
+            reject(err ?? closeErr);
+            return;
+          }
+          if (err)
+            reject(err);
+          else
+            resolve();
+        });
+      });
+    }
+  };
+}
+function resolveRecorderStore(options = {}) {
+  const path = process.env[POME_RECORDER_EVENTS_PATH]?.trim();
+  if (path) {
+    return createFileBackedRecorderStore({ ...options, path });
+  }
+  return createRecorderStore(options);
+}
+function createRecorderHandle(options) {
+  const store = options.store ?? createRecorderStore();
+  const errorEnvelope2 = options.errorEnvelope ?? envelopeFor;
+  const project = options.recordingProjection;
+  function accept(event) {
+    store.record(redactEvent(project ? project(event) : event));
+  }
+  function emit(c, started, requestBody, result, mutation, fidelity, error, declaredTool) {
+    const requestId = `req_${randomUUID()}`;
+    const stepId = c.req.header("x-pome-scenario-step-id") ?? null;
+    const correlationHeader = c.req.header("x-pome-correlation-id") ?? null;
+    accept({
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      run_id: options.runId,
+      twin: options.twin,
+      request_id: requestId,
+      correlation_id: correlationHeader ?? requestId,
+      task_step_id: stepId,
+      scenario_step_id: stepId,
+      step_id: null,
+      // FDRS-402 adapter-rich path: only twins that pin `stampToolCallId`
+      // persist the header here (github); the default tape stamps null.
+      tool_call_id: options.stampToolCallId ? correlationHeader : null,
+      method: c.req.method,
+      path: new URL(c.req.url).pathname,
+      request_body: requestBody,
+      request_headers: recordedRequestHeaders(c),
+      tool: resolveRecordedTool(c, declaredTool),
+      status: result.status,
+      response_body: result.body,
+      latency_ms: Date.now() - started,
+      fidelity,
+      state_mutation: mutation,
+      state_delta: result.delta ?? null,
+      error
+    });
+  }
+  return {
+    record(event) {
+      accept(event);
+    },
+    events() {
+      return store.events();
+    },
+    count() {
+      return store.count?.() ?? store.events().length;
+    },
+    dropped() {
+      return store.dropped?.() ?? 0;
+    },
+    async flush() {
+      await store.flush?.();
+    },
+    async close() {
+      await store.close?.();
+    },
+    handle({ mutation, fidelity = "semantic", errorEnvelope: perCallEnvelope, tool }, fn) {
+      const projectError = perCallEnvelope ?? errorEnvelope2;
+      return async (c) => {
+        const started = Date.now();
+        let requestBody = null;
+        try {
+          requestBody = c.req.method === "GET" || c.req.method === "HEAD" ? null : await readRequestJson(c);
+          const result = await fn(c);
+          const effectiveMutation = result.mutation ?? mutation;
+          const errorMsg = result.status >= 400 ? extractMessage(result.body) ?? "request failed" : null;
+          emit(c, started, requestBody, result, effectiveMutation, fidelity, errorMsg, tool);
+          return respondWith(c, result.status, result.body);
+        } catch (caught) {
+          const envelope = projectError(caught);
+          const errMsg = extractMessage(envelope.body) ?? (caught instanceof Error ? caught.message : "request failed");
+          emit(c, started, requestBody, { status: envelope.status, body: envelope.body }, false, fidelity, errMsg, tool);
+          return respondWith(c, envelope.status, envelope.body);
+        }
+      };
+    }
+  };
+}
+function respondWith(c, status, body) {
+  if (status === 204 || status === 205 || status === 304) {
+    return c.body(null, status);
+  }
+  return c.json(body, status);
+}
+async function readRequestJson(c) {
+  try {
+    return await c.req.raw.clone().json();
+  } catch {
+    return null;
+  }
+}
+function extractMessage(body) {
+  if (!body || typeof body !== "object")
+    return void 0;
+  const record = body;
+  if (typeof record.message === "string")
+    return record.message;
+  if (record.error && typeof record.error === "object") {
+    const nested = record.error.message;
+    if (typeof nested === "string")
+      return nested;
+  }
+  return void 0;
+}
+var TwinBootError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TwinBootError";
+  }
+};
+var POME_CORE_ROUTE_NAMES = /* @__PURE__ */ new Set(["health", "state", "events"]);
+function makeDeltaSink() {
+  let delta = null;
+  return {
+    report(d) {
+      delta = d;
+    },
+    value() {
+      return delta;
+    }
+  };
+}
+function isLoopbackHost(value) {
+  return value === "127.0.0.1" || value === "::1" || value === "localhost";
+}
+function ensureTwinAuthSecret(twin, host) {
+  if (process.env.TWIN_AUTH_SECRET)
+    return;
+  if (isLoopbackHost(host))
+    return;
+  const dataDir = process.env.POME_TWIN_DATA_DIR || join(".pome-data", twin);
+  const secretPath = join(dataDir, "secret");
+  try {
+    const persisted = readSecretFile(secretPath);
+    if (persisted) {
+      process.env.TWIN_AUTH_SECRET = persisted;
+      console.log(`[twin-${twin}] TWIN_AUTH_SECRET not set \u2014 using the persisted secret from ${secretPath}`);
+      return;
+    }
+    const secret = randomBytes(32).toString("hex");
+    mkdirSync(dataDir, { recursive: true });
+    try {
+      writeFileSync(secretPath, `${secret}
+`, { mode: 384, flag: "wx" });
+    } catch (err) {
+      if (err.code !== "EEXIST")
+        throw err;
+      const winner = readSecretFile(secretPath);
+      if (winner) {
+        process.env.TWIN_AUTH_SECRET = winner;
+        console.log(`[twin-${twin}] TWIN_AUTH_SECRET not set \u2014 using the persisted secret from ${secretPath}`);
+        return;
+      }
+      rmSync(secretPath, { force: true });
+      try {
+        writeFileSync(secretPath, `${secret}
+`, { mode: 384, flag: "wx" });
+      } catch (err2) {
+        if (err2.code !== "EEXIST")
+          throw err2;
+        const late = readSecretFile(secretPath);
+        if (!late)
+          throw err2;
+        process.env.TWIN_AUTH_SECRET = late;
+        console.log(`[twin-${twin}] TWIN_AUTH_SECRET not set \u2014 using the persisted secret from ${secretPath}`);
+        return;
+      }
+    }
+    process.env.TWIN_AUTH_SECRET = secret;
+    console.log(`[twin-${twin}] TWIN_AUTH_SECRET not set \u2014 generated ${secret} (persisted to ${secretPath}; subsequent boots reuse it, an env-injected TWIN_AUTH_SECRET overrides it)`);
+  } catch (err) {
+    if (err instanceof TwinBootError)
+      throw err;
+    throw new TwinBootError(`TWIN_AUTH_SECRET is not set and self-generating one at ${secretPath} failed: ${err.message}`);
+  }
+}
+function readSecretFile(secretPath) {
+  let raw;
+  try {
+    raw = readFileSync(secretPath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT")
+      return void 0;
+    throw err;
+  }
+  const trimmed = raw.trim();
+  if (trimmed.length === 0)
+    return void 0;
+  if (trimmed.length < 32) {
+    throw new TwinBootError(`TWIN_AUTH_SECRET is not set and the persisted secret at ${secretPath} is shorter than 32 chars \u2014 fix or delete the file, or inject TWIN_AUTH_SECRET.`);
+  }
+  return trimmed;
+}
+function shadowedPrefix(routePath) {
+  for (const prefix of RESERVED_SESSION_PREFIXES) {
+    if (routePath === prefix || routePath.startsWith(`${prefix}/`))
+      return prefix;
+  }
+  return null;
+}
+function assertUniqueToolNames(tools, twinId) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const tool of tools) {
+    if (seen.has(tool.name)) {
+      throw new TwinBootError(`Twin "${twinId}" has duplicate tool name: ${tool.name}`);
+    }
+    seen.add(tool.name);
+  }
+}
+function findTool(definition, name) {
+  const tool = definition.tools.find((t) => t.name === name);
+  if (!tool) {
+    throw new UnknownToolError(name);
+  }
+  return tool;
+}
+async function readJson(req) {
+  try {
+    const cloned = req.clone();
+    const text = await cloned.text();
+    if (!text)
+      return null;
+    return JSON.parse(text);
+  } catch (err) {
+    if (err instanceof SyntaxError)
+      throw err;
+    return null;
+  }
+}
+function ok(body, mutation = false) {
+  return { status: 200, body, mutation };
+}
+function created(body) {
+  return { status: 201, body, mutation: true };
+}
+var FAILURE_INJECTION_OVERRIDE_KEY = "failureInjectionOverride";
+var failureInjectionRuleSchema = z.object({
+  method: z.string().min(1).transform((s) => s.toUpperCase()),
+  path: z.string().min(1),
+  attempt: z.number().int().positive(),
+  mode: z.enum(["before_handler", "after_handler"]).default("after_handler"),
+  status: z.number().int().min(100).max(599),
+  body: z.unknown()
+});
+function createFailureInjectionStore() {
+  let rules = [];
+  const counters = /* @__PURE__ */ new Map();
+  const tuplesWithRules = /* @__PURE__ */ new Set();
+  function tupleKey(method, path) {
+    return `${method.toUpperCase()}\0${path}`;
+  }
+  function counterKey(accountId, method, path) {
+    return `${accountId}\0${method.toUpperCase()}\0${path}`;
+  }
+  function rebuildIndex() {
+    tuplesWithRules.clear();
+    for (const r of rules)
+      tuplesWithRules.add(tupleKey(r.method, r.path));
+  }
+  return {
+    setRules(next) {
+      rules = next.slice();
+      counters.clear();
+      rebuildIndex();
+    },
+    clear() {
+      rules = [];
+      counters.clear();
+      tuplesWithRules.clear();
+    },
+    matchAndConsume(accountId, method, path) {
+      const tk = tupleKey(method, path);
+      if (!tuplesWithRules.has(tk))
+        return null;
+      const ck = counterKey(accountId, method, path);
+      const count = (counters.get(ck) ?? 0) + 1;
+      counters.set(ck, count);
+      return rules.find((r) => r.method.toUpperCase() === method.toUpperCase() && r.path === path && r.attempt === count) ?? null;
+    }
+  };
+}
+function failureInjectionMiddleware(store, options) {
+  return async (c, next) => {
+    const session = c.get("session");
+    if (!session) {
+      await next();
+      return;
+    }
+    const accountId = typeof session.account_id === "string" ? session.account_id : String(session.sid ?? "_anon");
+    const method = c.req.method.toUpperCase();
+    const rawPath = new URL(c.req.url).pathname;
+    const path = stripSessionPrefix(rawPath);
+    const rule = store.matchAndConsume(accountId, method, path);
+    if (!rule) {
+      await next();
+      return;
+    }
+    if (rule.mode === "before_handler") {
+      const started = Date.now();
+      let requestBody = null;
+      try {
+        requestBody = await c.req.raw.clone().text();
+      } catch {
+        requestBody = null;
+      }
+      const requestId = `req_${randomUUID()}`;
+      const stepId = c.req.header("x-pome-scenario-step-id") ?? null;
+      options.recorder?.record({
+        ts: (/* @__PURE__ */ new Date()).toISOString(),
+        run_id: options.runId,
+        twin: options.twin,
+        request_id: requestId,
+        correlation_id: c.req.header("x-pome-correlation-id") ?? requestId,
+        task_step_id: stepId,
+        scenario_step_id: stepId,
+        step_id: null,
+        tool_call_id: null,
+        method,
+        path: rawPath,
+        request_body: requestBody,
+        // F-1125 — same capture policy as the engine's emit(); an injected
+        // fault must not be the one row a header-reading check cannot see.
+        request_headers: recordedRequestHeaders(c),
+        // Injection is transport-level: it intercepts a (method, path) tuple,
+        // never a declared twin action.
+        tool: null,
+        status: rule.status,
+        response_body: rule.body,
+        latency_ms: Date.now() - started,
+        fidelity: "semantic",
+        state_mutation: false,
+        state_delta: null,
+        error: rule.status >= 400 ? errorMessage(rule.body) : null
+      });
+      return c.json(rule.body, rule.status);
+    }
+    const override = { status: rule.status, body: rule.body };
+    c.set(FAILURE_INJECTION_OVERRIDE_KEY, override);
+    await next();
+  };
+}
+function stripSessionPrefix(path) {
+  const match = path.match(/^\/s\/[^/]+(\/.*)$/);
+  return match?.[1] ?? path;
+}
+function errorMessage(body) {
+  if (body && typeof body === "object" && "error" in body) {
+    const err = body.error;
+    if (err && typeof err.message === "string")
+      return err.message;
+  }
+  return "request failed";
+}
+
+// ../packages/sdk/dist/server.js
+var jsonRecord = z.record(z.string(), z.unknown());
+function createApp(definition, options = {}) {
+  let seed;
+  if (options.seed !== void 0) {
+    if (definition.seed) {
+      seed = definition.seed.parse(options.seed);
+    } else {
+      seed = options.seed;
+    }
+  }
+  const domain = definition.domain({ db: options.db, seed });
+  const runId = options.runId ?? "local";
+  const recorder = createRecorderHandle({
+    runId,
+    twin: definition.id,
+    store: options.recorder ?? resolveRecorderStore(),
+    errorEnvelope: definition.errorEnvelope,
+    stampToolCallId: definition.stampToolCallId,
+    recordingProjection: definition.recordingProjection
+  });
+  const userApp = new Hono();
+  if (definition.routes) {
+    definition.routes(userApp, { domain, recorder, runId, twin: definition.id });
+    for (const route of userApp.routes) {
+      const shadowed = shadowedPrefix(route.path);
+      if (shadowed) {
+        throw new TwinBootError(`Twin "${definition.id}" route ${route.method} ${route.path} shadows reserved SDK prefix ${shadowed}/*`);
+      }
+    }
+  }
+  assertUniqueToolNames(definition.tools, definition.id);
+  const root = new Hono();
+  const healthzExtras = definition.healthz ?? (() => ({ version: definition.version, fidelity: definition.fidelity.default }));
+  root.get("/healthz", (c) => c.json({
+    ok: true,
+    twin: definition.id,
+    implementation: definition.implementation ?? `${definition.id}_clone`,
+    tools: definition.tools.length,
+    runtime: twinBuildInfo(definition.packageName ?? `@pome-sh/twin-${definition.id}`),
+    ...healthzExtras()
+  }));
+  const readBody = definition.bodyReader ?? ((c) => readJson(c.req.raw));
+  const adminForbidden = definition.admin?.forbidden;
+  const adminApp = new Hono();
+  adminApp.use("*", adminForbidden ? createAdminGate({
+    forbidden: () => {
+      const envelope = adminForbidden();
+      return Response.json(envelope.body, { status: envelope.status });
+    }
+  }) : requireAdminAuth());
+  const adminEnvelope = definition.admin?.errorEnvelope;
+  const wrapAdmin = definition.admin?.recorded !== false ? (fn) => recorder.handle({ mutation: true, errorEnvelope: adminEnvelope }, fn) : (fn) => async (c) => {
+    try {
+      const result = await fn(c);
+      return c.json(result.body, result.status);
+    } catch (err) {
+      const envelope = (adminEnvelope ?? definition.errorEnvelope ?? envelopeFor)(err);
+      return c.json(envelope.body, envelope.status);
+    }
+  };
+  adminApp.post("/reset", wrapAdmin(async () => {
+    if (!definition.admin?.reset) {
+      throw new TwinError("admin.reset is not configured for this twin", 501);
+    }
+    const delta = makeDeltaSink();
+    const body = await definition.admin.reset({ domain, reportDelta: delta.report }) ?? { ok: true };
+    return { status: 200, body, delta: delta.value() };
+  }));
+  adminApp.post("/seed", wrapAdmin(async (c) => {
+    if (!definition.admin?.seed) {
+      throw new TwinError("admin.seed is not configured for this twin", 501);
+    }
+    if (!definition.seed) {
+      throw new TwinError("Twin manifest has no `seed` schema; cannot accept POST /admin/seed", 501);
+    }
+    const raw = await readBody(c);
+    const parsed = definition.seed.parse(raw);
+    const delta = makeDeltaSink();
+    const body = await definition.admin.seed({ domain, seed: parsed, reportDelta: delta.report }) ?? { ok: true };
+    return { status: 200, body, delta: delta.value() };
+  }));
+  root.route("/admin", adminApp);
+  const session = new Hono();
+  session.use("*", bearerAuth(definition.auth));
+  if (definition.middleware) {
+    definition.middleware(session, { domain, recorder, runId, twin: definition.id });
+  }
+  if (definition.sessionHealthz !== false) {
+    session.get("/healthz", (c) => c.json({ ok: true, sid: c.req.param("sid") }));
+  }
+  const pomeHealthExtras = definition.pomeHealth ?? (() => ({ version: definition.version, fidelity: definition.fidelity.default }));
+  session.get("/_pome/health", (c) => c.json({
+    ok: true,
+    twin: definition.id,
+    ...pomeHealthExtras({ recorder })
+  }));
+  session.get("/_pome/state", async (c) => {
+    try {
+      if (!definition.state) {
+        throw new TwinError("state introspection is not configured for this twin", 501);
+      }
+      const session2 = c.get("session");
+      const state = await definition.state({ domain, session: session2 });
+      return c.json(redactSecrets(state));
+    } catch (err) {
+      const envelope = (definition.errorEnvelope ?? envelopeFor)(err);
+      return c.json(envelope.body, envelope.status);
+    }
+  });
+  session.get("/_pome/events", (c) => c.json(recorder.events()));
+  if (definition.pomeRoutes) {
+    for (const [name, handler] of Object.entries(definition.pomeRoutes)) {
+      if (POME_CORE_ROUTE_NAMES.has(name)) {
+        throw new TwinBootError(`Twin "${definition.id}" pome route "/_pome/${name}" shadows a reserved engine route`);
+      }
+      session.get(`/_pome/${name}`, async (c) => c.json(await handler({ domain })));
+    }
+  }
+  session.post("/mcp", (c) => handleMcpJsonRpc(c, { definition, domain, recorder, runId }));
+  session.get("/mcp", (c) => mcpMethodNotAllowed(c));
+  session.delete("/mcp", (c) => mcpMethodNotAllowed(c));
+  session.get("/mcp/tools", (c) => c.json({
+    tools: definition.tools.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      input_schema: toolInputSchema(tool),
+      ...toolListExtras(tool)
+    }))
+  }));
+  session.post("/mcp/tools/:name", recorder.handle({ mutation: false }, async (c) => {
+    const name = c.req.param("name") ?? "";
+    if (name)
+      setRecordedTool(c, name);
+    const tool = findTool(definition, name);
+    const args = await readBody(c);
+    const parsed = tool.schema.parse(args ?? {});
+    const call = makeToolCallContext(c);
+    const result = await tool.handler(domain, parsed, call.ctx);
+    const delta = call.delta();
+    const mutation = tool.mutation && (!call.reportedDelta() || delta !== null);
+    return { status: 200, body: result, mutation, delta };
+  }));
+  session.post("/mcp/call", recorder.handle({ mutation: false }, async (c) => {
+    const raw = await readBody(c);
+    let call;
+    if (definition.legacyMcp?.aliases) {
+      const rec = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+      const name = rec.tool ?? rec.name;
+      if (typeof name !== "string" || name.length === 0) {
+        const missing = definition.legacyMcp.missingTool;
+        if (missing) {
+          const envelope = missing();
+          return { status: envelope.status, body: envelope.body };
+        }
+        z.object({ tool: z.string().min(1) }).parse(rec);
+      }
+      call = {
+        tool: name,
+        arguments: rec.arguments ?? rec.params ?? {}
+      };
+    } else {
+      call = z.object({ tool: z.string().min(1), arguments: jsonRecord.default({}) }).parse(raw);
+    }
+    setRecordedTool(c, call.tool);
+    const tool = findTool(definition, call.tool);
+    const parsed = tool.schema.parse(call.arguments);
+    const toolCall = makeToolCallContext(c);
+    const result = await tool.handler(domain, parsed, toolCall.ctx);
+    const delta = toolCall.delta();
+    const mutation = tool.mutation && (!toolCall.reportedDelta() || delta !== null);
+    return { status: 200, body: result, mutation, delta };
+  }));
+  if (definition.routes) {
+    session.route("/", userApp);
+  }
+  session.all("*", recorder.handle({ mutation: false, fidelity: "unsupported" }, async (c) => {
+    const ctx = { method: c.req.method, path: new URL(c.req.url).pathname };
+    if (definition.unsupported)
+      return definition.unsupported(ctx);
+    return {
+      status: 501,
+      body: {
+        message: `Endpoint not modeled by twin "${definition.id}".`,
+        fidelity: "unsupported",
+        method: ctx.method,
+        path: ctx.path
+      }
+    };
+  }));
+  root.route("/s/:sid", session);
+  if (definition.mountSessionAtRoot) {
+    root.route("/", session);
+  }
+  if (!definition.admin?.reset) {
+    console.warn(`[@pome-sh/sdk] twin "${definition.id}" has no admin.reset configured \u2014 POST /admin/reset returns 501. Most CI workflows rely on this for clean-state-per-test.`);
+  }
+  return root;
+}
+async function serve(definition, options = {}) {
+  const hostname = options.hostname ?? "127.0.0.1";
+  if (options.port !== void 0 && !isLoopbackHost(hostname)) {
+    ensureTwinAuthSecret(definition.id, hostname);
+  }
+  const store = options.recorder ?? resolveRecorderStore();
+  const app = createApp(definition, { ...options, recorder: store });
+  const closeRecorder = async () => {
+    await store.flush?.();
+    await store.close?.();
+  };
+  if (options.port === void 0) {
+    return { app, close: closeRecorder };
+  }
+  const { serve: nodeServe } = await import('@hono/node-server');
+  const server = await new Promise((resolve) => {
+    const bound = nodeServe({
+      fetch: app.fetch,
+      port: options.port,
+      hostname
+    }, () => resolve(bound));
+  });
+  let closed = false;
+  const close = async () => {
+    if (closed) {
+      await closeRecorder();
+      return;
+    }
+    closed = true;
+    unregisterServeShutdown(close);
+    await new Promise((resolve, reject) => {
+      server.close((err) => err ? reject(err) : resolve());
+    });
+    await closeRecorder();
+  };
+  registerServeShutdown(close);
+  return { app, close };
+}
+var serveShutdownHooks = /* @__PURE__ */ new Set();
+var serveSignalHandlersInstalled = false;
+function registerServeShutdown(close) {
+  serveShutdownHooks.add(close);
+  if (serveSignalHandlersInstalled)
+    return;
+  serveSignalHandlersInstalled = true;
+  const onSignal = () => {
+    void (async () => {
+      const hooks = [...serveShutdownHooks];
+      serveShutdownHooks.clear();
+      await Promise.allSettled(hooks.map((hook) => hook()));
+      process.exit(0);
+    })();
+  };
+  process.once("SIGINT", onSignal);
+  process.once("SIGTERM", onSignal);
+}
+function unregisterServeShutdown(close) {
+  serveShutdownHooks.delete(close);
+}
+
+export { FAILURE_INJECTION_OVERRIDE_KEY, POME_RECORDER_EVENTS_PATH, PROVIDER_SHAPED_TEAM_ID, TwinBootError, TwinError, UnknownToolError, bearerAuth, createAdminGate, createApp, createFailureInjectionStore, createFileBackedRecorderStore, createRecorderHandle, createRecorderStore, created, defineTwin, ensureTwinAuthSecret, failureInjectionMiddleware, failureInjectionRuleSchema, formTokenResolver, isLoopbackHost, mintProviderToken, ok, openTwinDatabase, queryTokenResolver, recordedRequestHeaders, requireAdminAuth, resolveAuthSecret, resolveRecorderStore, serve, setClientIp, setRecordedTool, toTwinHttpEventRow, twinBuildInfo, verifyProviderToken };