@sidecar-ai/cli 0.1.0-alpha.1 → 0.1.0-alpha.4

package/dist/index.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 
 // packages/cli/src/index.ts
-import { existsSync as existsSync5, realpathSync } from "fs";
-import { mkdir as mkdir9, readFile as readFile8, writeFile as writeFile9 } from "fs/promises";
+import { existsSync as existsSync6, realpathSync } from "fs";
+import { mkdir as mkdir10, readFile as readFile8, writeFile as writeFile10 } from "fs/promises";
 import { createServer as createServer2 } from "http";
-import path18 from "path";
+import path19 from "path";
 import { createInterface as createInterface2 } from "readline/promises";
 import { fileURLToPath, pathToFileURL } from "url";
 import { cwd, exit, stdin as stdin2, stdout as stdout2 } from "process";
@@ -14,7 +14,7 @@ import { tsImport } from "tsx/esm/api";
 var authBrand = /* @__PURE__ */ Symbol.for("sidecar.auth");
 function isSidecarAuth(value) {
   return Boolean(
-    value && typeof value === "object" && value[authBrand]
+    value && typeof value === "object" && (value[authBrand] || value.kind === "sidecar.auth")
   );
 }
 
@@ -26,13 +26,19 @@ var resourceBrand = /* @__PURE__ */ Symbol.for("sidecar.resource");
 var resourceResultBrand = /* @__PURE__ */ Symbol.for("sidecar.resourceResult");
 var promptBrand = /* @__PURE__ */ Symbol.for("sidecar.prompt");
 function isSidecarTool(value) {
-  return Boolean(value && typeof value === "object" && value[toolBrand]);
+  return Boolean(
+    value && typeof value === "object" && (value[toolBrand] || value.kind === "sidecar.tool")
+  );
 }
 function isSidecarResource(value) {
-  return Boolean(value && typeof value === "object" && value[resourceBrand]);
+  return Boolean(
+    value && typeof value === "object" && (value[resourceBrand] || value.kind === "sidecar.resource")
+  );
 }
 function isSidecarPrompt(value) {
-  return Boolean(value && typeof value === "object" && value[promptBrand]);
+  return Boolean(
+    value && typeof value === "object" && (value[promptBrand] || value.kind === "sidecar.prompt")
+  );
 }
 var toolResult = Object.assign(
   createToolResult,
@@ -755,12 +761,19 @@ function typeToJsonSchemaInner(type) {
     return { anyOf: parts.map((part) => typeToJsonSchema(part)) };
   }
   const properties = type.getProperties();
+  const indexType = type.getStringIndexType() ?? type.getNumberIndexType();
   if (properties.length > 0) {
-    return objectTypeToSchema(properties);
+    return objectTypeToSchema(properties, indexType);
+  }
+  if (indexType) {
+    return {
+      type: "object",
+      additionalProperties: indexTypeToAdditionalProperties(indexType)
+    };
   }
   return {};
 }
-function objectTypeToSchema(properties) {
+function objectTypeToSchema(properties, indexType) {
   const schemaProperties = {};
   const required = [];
   for (const property of properties) {
@@ -784,9 +797,16 @@ function objectTypeToSchema(properties) {
     type: "object",
     properties: schemaProperties,
     required,
-    additionalProperties: false
+    additionalProperties: indexType ? indexTypeToAdditionalProperties(indexType) : false
   };
 }
+function indexTypeToAdditionalProperties(type) {
+  if (type.isAny() || type.isUnknown()) {
+    return true;
+  }
+  const schema = typeToJsonSchema(type);
+  return Object.keys(schema).length ? schema : true;
+}
 function literalOrPrimitive(type, primitive) {
   if (isLiteralType(type)) {
     return { const: literalValue(type) };
@@ -855,6 +875,7 @@ import {
   Node as Node3,
   SyntaxKind
 } from "ts-morph";
+var CLAUDE_FONT_RESOURCE_DOMAIN = "https://assets.claude.ai";
 async function buildWidgets(rootDir, outDir, tools) {
   const widgets = tools.filter(
     (entry) => Boolean(entry.widget)
@@ -1038,7 +1059,7 @@ function widgetMeta(resourceUri, options = {}, target = "mcp") {
 function widgetResourceMeta(options = {}, target = "mcp") {
   const csp = stripUndefined3({
     connectDomains: options.csp?.connectDomains ? [...options.csp.connectDomains] : [],
-    resourceDomains: options.csp?.resourceDomains ? [...options.csp.resourceDomains] : [],
+    resourceDomains: widgetResourceDomains(options, target),
     frameDomains: options.csp?.frameDomains ? [...options.csp.frameDomains] : void 0,
     baseUriDomains: options.csp?.baseUriDomains ? [...options.csp.baseUriDomains] : void 0
   });
@@ -1051,6 +1072,13 @@ function widgetResourceMeta(options = {}, target = "mcp") {
   });
   return Object.keys(ui).length ? { ui } : void 0;
 }
+function widgetResourceDomains(options, target) {
+  const domains = [...options.csp?.resourceDomains ?? []];
+  if (target === "claude" && !domains.includes(CLAUDE_FONT_RESOURCE_DOMAIN)) {
+    domains.push(CLAUDE_FONT_RESOURCE_DOMAIN);
+  }
+  return domains;
+}
 function findWidgetDefinition(sourceFile) {
   const call = resolveDefaultExportCall(sourceFile, "widget");
   if (!call) {
@@ -1636,8 +1664,8 @@ function readStringArrayProperty2(definition, propertyName) {
 }
 
 // packages/compiler/src/build.ts
-import { mkdir as mkdir8, writeFile as writeFile8 } from "fs/promises";
-import path17 from "path";
+import { mkdir as mkdir9, writeFile as writeFile9 } from "fs/promises";
+import path18 from "path";
 
 // packages/compiler/src/config.ts
 import path5 from "path";
@@ -2054,10 +2082,6 @@ function uniqueMethodNames(names) {
   });
 }
 
-// packages/compiler/src/plugins.ts
-import { mkdir as mkdir7, writeFile as writeFile7 } from "fs/promises";
-import path14 from "path";
-
 // packages/compiler/src/identity.ts
 import { readFile as readFile3 } from "fs/promises";
 import path8 from "path";
@@ -2098,6 +2122,10 @@ function readConfigString(configText, key) {
   return match?.[1];
 }
 
+// packages/compiler/src/plugins.ts
+import { mkdir as mkdir7, writeFile as writeFile7 } from "fs/promises";
+import path14 from "path";
+
 // packages/compiler/src/plugin-components/agents.ts
 import { mkdir as mkdir3, readdir as readdir2, readFile as readFile4, writeFile as writeFile3 } from "fs/promises";
 import path9 from "path";
@@ -2542,7 +2570,7 @@ This package was generated by Sidecar.
 
 Set \`SIDECAR_MCP_URL\` to the hosted MCP endpoint for this app.
 
-For local testing, run \`sidecar dev --tunnel\` and use the printed HTTPS MCP URL.
+For local testing, run \`sidecar dev --tunnel\` and use the validated HTTPS MCP URL it prints. Temporary quick tunnels are public and best-effort; use a configured tunnel/domain or deployed preview for repeatable testing.
 
 Claude/Cowork plugin-specific components such as skills, slash commands, agents, hooks, output styles, themes, monitors, assets, and bin scripts will be emitted here when the source project defines them.
 `
@@ -2953,15 +2981,319 @@ function readStringArrayProperty4(definition, propertyName) {
   return initializer.getElements().filter(Node8.isStringLiteral).map((element) => element.getLiteralText());
 }
 
+// packages/compiler/src/server-output.ts
+import { existsSync as existsSync5 } from "fs";
+import { mkdir as mkdir8, rm, writeFile as writeFile8 } from "fs/promises";
+import path17 from "path";
+import { build as esbuild2 } from "esbuild";
+var SERVER_ENTRYPOINT = "server/index.js";
+var VERCEL_ENTRYPOINT = "api/sidecar.js";
+async function buildServerOutput(rootDir, outDir, manifest, identity, host = "node") {
+  const cacheDir = path17.join(rootDir, ".sidecar", "cache", "server");
+  await mkdir8(cacheDir, { recursive: true });
+  const entryFile = path17.join(cacheDir, "index.ts");
+  await writeFile8(entryFile, renderServerEntry(rootDir, entryFile, manifest, identity));
+  const serverFile = path17.join(outDir, SERVER_ENTRYPOINT);
+  await mkdir8(path17.dirname(serverFile), { recursive: true });
+  await esbuild2({
+    absWorkingDir: rootDir,
+    alias: sidecarBundleAliases(rootDir),
+    banner: {
+      js: `import { createRequire as __sidecarCreateRequire } from "node:module";
+const require = __sidecarCreateRequire(import.meta.url);`
+    },
+    bundle: true,
+    entryPoints: [entryFile],
+    format: "esm",
+    legalComments: "none",
+    minify: false,
+    nodePaths: [
+      path17.join(rootDir, "node_modules"),
+      path17.join(process.cwd(), "node_modules")
+    ],
+    outfile: serverFile,
+    platform: "node",
+    sourcemap: false,
+    target: "node20"
+  });
+  await writeFile8(path17.join(outDir, "package.json"), renderServerPackage(identity));
+  if (host === "vercel") {
+    await mkdir8(path17.join(outDir, "api"), { recursive: true });
+    await writeFile8(path17.join(outDir, VERCEL_ENTRYPOINT), renderVercelEntrypoint());
+    await writeFile8(path17.join(outDir, "vercel.json"), renderVercelConfig());
+  } else {
+    await rm(path17.join(outDir, "api"), { recursive: true, force: true });
+    await rm(path17.join(outDir, "vercel.json"), { force: true });
+  }
+}
+function renderServerEntry(rootDir, entryFile, manifest, identity) {
+  const entryDir = path17.dirname(entryFile);
+  const tools = manifest.tools;
+  const resources = manifest.resources;
+  const prompts = manifest.prompts;
+  const imports = [
+    `import { readFileSync, realpathSync } from "node:fs";`,
+    `import { createServer } from "node:http";`,
+    `import { pathToFileURL } from "node:url";`,
+    `import { createSidecarHttpHandler } from "@sidecar-ai/server";`,
+    `import { isSidecarAuth } from "@sidecar-ai/auth";`,
+    `import { isSidecarPrompt, isSidecarResource, isSidecarTool } from "@sidecar-ai/core";`,
+    `import { isSidecarProxy } from "@sidecar-ai/server/proxy";`,
+    ...tools.map(
+      (entry, index) => `import tool${index} from ${JSON.stringify(toImportSpecifier(entryDir, path17.join(rootDir, entry.sourceFile)))};`
+    ),
+    ...resources.map(
+      (entry, index) => `import resource${index} from ${JSON.stringify(toImportSpecifier(entryDir, path17.join(rootDir, entry.sourceFile)))};`
+    ),
+    ...prompts.map(
+      (entry, index) => `import prompt${index} from ${JSON.stringify(toImportSpecifier(entryDir, path17.join(rootDir, entry.sourceFile)))};`
+    ),
+    existsSync5(path17.join(rootDir, "auth.ts")) ? `import authExport from ${JSON.stringify(toImportSpecifier(entryDir, path17.join(rootDir, "auth.ts")))};` : `const authExport = undefined;`,
+    existsSync5(path17.join(rootDir, "proxy.ts")) ? `import proxyExport from ${JSON.stringify(toImportSpecifier(entryDir, path17.join(rootDir, "proxy.ts")))};` : `const proxyExport = undefined;`,
+    existsSync5(path17.join(rootDir, "sidecar.config.ts")) ? `import configExport from ${JSON.stringify(toImportSpecifier(entryDir, path17.join(rootDir, "sidecar.config.ts")))};` : `const configExport = undefined;`
+  ].join("\n");
+  return `${imports}
+
+const manifest = ${JSON.stringify(manifest, null, 2)};
+const identity = ${JSON.stringify(identity, null, 2)};
+
+const loadedAuth = authExport === undefined ? undefined : assertAuth(authExport);
+const auth = loadedAuth && process.env.SIDECAR_MCP_URL
+  ? loadedAuth.withResource(process.env.SIDECAR_MCP_URL)
+  : loadedAuth;
+const proxy = proxyExport === undefined ? undefined : assertProxy(proxyExport);
+const runtimeConfig = configExport && typeof configExport === "object" ? configExport : undefined;
+
+if (auth && !process.env.SIDECAR_MCP_URL) {
+  console.warn("Sidecar auth is enabled. Set SIDECAR_MCP_URL to the public https://.../mcp URL before hosting.");
+}
+
+export const handler = createSidecarHttpHandler({
+  name: identity.name,
+  version: identity.version,
+  path: process.env.SIDECAR_MCP_PATH ?? "/mcp",
+  publicUrl: process.env.SIDECAR_PUBLIC_URL ?? process.env.SIDECAR_MCP_URL,
+  auth,
+  proxy,
+  tools: [
+${tools.map((entry, index) => `    loadTool(${JSON.stringify(entry.sourceFile)}, tool${index}, manifest.tools[${index}].descriptor),`).join("\n")}
+  ],
+  resources: [
+${renderWidgetResources(manifest)}
+${resources.map((entry, index) => `    loadResource(${JSON.stringify(entry.sourceFile)}, resource${index}, manifest.resources[${index}]),`).join("\n")}
+  ],
+  resourceTemplates: manifest.resourceTemplates.map((entry) => ({ descriptor: entry.descriptor })),
+  prompts: [
+${prompts.map((entry, index) => `    loadPrompt(${JSON.stringify(entry.sourceFile)}, prompt${index}, manifest.prompts[${index}].descriptor),`).join("\n")}
+  ],
+  capabilities: {
+    tools: runtimeConfig?.tools ?? manifest.config.tools,
+    resources: runtimeConfig?.resources ?? manifest.config.resources,
+    prompts: runtimeConfig?.prompts ?? manifest.config.prompts,
+  },
+  pagination: runtimeConfig?.pagination ?? {
+    pageSize: manifest.config.pagination.pageSize,
+  },
+});
+
+export default handler;
+
+export const server = createServer(handler);
+
+if (isDirectRun()) {
+  const port = readPort();
+  const host = process.env.SIDECAR_HOST ?? process.env.HOST ?? "0.0.0.0";
+  server.listen(port, host, () => {
+    const localHost = host === "0.0.0.0" ? "127.0.0.1" : host;
+    console.log(\`MCP running on Streamable HTTP at http://\${localHost}:\${port}\${process.env.SIDECAR_MCP_PATH ?? "/mcp"}\`);
+  });
+
+  process.on("SIGTERM", () => shutdown());
+  process.on("SIGINT", () => shutdown());
+}
+
+function loadTool(sourceFile, value, descriptor) {
+  const tool = unwrapRuntimeDefault(value);
+  if (!isSidecarTool(tool)) {
+    throw new Error(\`\${sourceFile} did not default-export a Sidecar tool.\`);
+  }
+  return { tool, descriptor };
+}
+
+function loadResource(sourceFile, value, entry) {
+  const resource = unwrapRuntimeDefault(value);
+  if (!isSidecarResource(resource)) {
+    throw new Error(\`\${sourceFile} did not default-export a Sidecar resource.\`);
+  }
+  return {
+    uri: entry.uri,
+    descriptor: entry.descriptor,
+    resource,
+  };
+}
+
+function loadPrompt(sourceFile, value, descriptor) {
+  const prompt = unwrapRuntimeDefault(value);
+  if (!isSidecarPrompt(prompt)) {
+    throw new Error(\`\${sourceFile} did not default-export a Sidecar prompt.\`);
+  }
+  return { prompt, descriptor };
+}
+
+function assertAuth(value) {
+  const authValue = unwrapRuntimeDefault(value);
+  if (!isSidecarAuth(authValue)) {
+    throw new Error("auth.ts must default-export auth({ ... }) from sidecar-ai.");
+  }
+  return authValue;
+}
+
+function assertProxy(value) {
+  const proxyValue = unwrapRuntimeDefault(value);
+  if (!isSidecarProxy(proxyValue)) {
+    throw new Error("proxy.ts must default-export proxy({ ... }) from @sidecar-ai/server/proxy.");
+  }
+  return proxyValue;
+}
+
+function unwrapRuntimeDefault(value) {
+  if (
+    value &&
+    typeof value === "object" &&
+    "default" in value &&
+    Object.keys(value).length === 1
+  ) {
+    return unwrapRuntimeDefault(value.default);
+  }
+  return value;
+}
+
+function readWidget(outputFile) {
+  return readFileSync(new URL(\`../\${outputFile}\`, import.meta.url), "utf8");
+}
+
+function readPort() {
+  const raw = process.env.PORT ?? process.env.SIDECAR_PORT ?? "3001";
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new Error(\`Invalid PORT/SIDECAR_PORT value: \${raw}\`);
+  }
+  return port;
+}
+
+function isDirectRun() {
+  const entry = process.argv[1];
+  if (!entry) {
+    return false;
+  }
+
+  return import.meta.url === pathToFileURL(realpathSync(entry)).href;
+}
+
+function shutdown() {
+  server.close(() => process.exit(0));
+}
+`;
+}
+function renderWidgetResources(manifest) {
+  return manifest.tools.filter((entry) => entry.widget?.outputFile).map((entry) => `    {
+      uri: ${JSON.stringify(entry.widget?.resourceUri)},
+      name: ${JSON.stringify(entry.name)},
+      description: ${JSON.stringify(entry.widget?.options?.description)},
+      mimeType: "text/html;profile=mcp-app",
+      text: readWidget(${JSON.stringify(entry.widget?.outputFile)}),
+      _meta: ${JSON.stringify(entry.widget?.resourceMeta ?? void 0)},
+    },`).join("\n");
+}
+function renderServerPackage(identity) {
+  return `${JSON.stringify({
+    name: `${identity.slug}-sidecar-server`,
+    version: identity.version,
+    private: true,
+    type: "module",
+    scripts: {
+      start: "node server/index.js"
+    },
+    engines: {
+      node: ">=20"
+    }
+  }, null, 2)}
+`;
+}
+function renderVercelEntrypoint() {
+  return `export { default } from "../server/index.js";
+`;
+}
+function renderVercelConfig() {
+  return `${JSON.stringify({
+    rewrites: [
+      {
+        source: "/(.*)",
+        destination: "/api/sidecar"
+      }
+    ],
+    functions: {
+      "api/sidecar.js": {
+        includeFiles: "public/**",
+        maxDuration: 300
+      }
+    }
+  }, null, 2)}
+`;
+}
+function sidecarBundleAliases(rootDir) {
+  const repoRoot = findSidecarRepoRoot2(rootDir) ?? findSidecarRepoRoot2(process.cwd());
+  if (!repoRoot) {
+    return void 0;
+  }
+  return {
+    "sidecar-ai": path17.join(repoRoot, "packages", "sidecar-ai", "src", "index.ts"),
+    "@sidecar-ai/auth": path17.join(repoRoot, "packages", "auth", "src", "index.ts"),
+    "@sidecar-ai/core": path17.join(repoRoot, "packages", "core", "src", "index.ts"),
+    "@sidecar-ai/server": path17.join(repoRoot, "packages", "server", "src", "index.ts"),
+    "@sidecar-ai/server/proxy": path17.join(repoRoot, "packages", "server", "src", "proxy.ts"),
+    "@sidecar-ai/client": path17.join(repoRoot, "packages", "client", "src", "index.ts"),
+    "@sidecar-ai/react": path17.join(repoRoot, "packages", "react", "src", "index.ts"),
+    "@sidecar-ai/native": path17.join(repoRoot, "packages", "native", "src", "index.ts"),
+    "@sidecar-ai/native/components": path17.join(repoRoot, "packages", "native", "src", "components", "index.tsx"),
+    "@sidecar-ai/openai": path17.join(repoRoot, "packages", "openai", "src", "index.ts"),
+    "@sidecar-ai/openai/components": path17.join(repoRoot, "packages", "openai", "src", "components.tsx"),
+    "@sidecar-ai/openai/official": path17.join(repoRoot, "packages", "openai", "src", "official.ts"),
+    "@sidecar-ai/anthropic": path17.join(repoRoot, "packages", "anthropic", "src", "index.ts"),
+    "@sidecar-ai/anthropic/agent": path17.join(repoRoot, "packages", "anthropic", "src", "agent.ts"),
+    "@sidecar-ai/anthropic/command": path17.join(repoRoot, "packages", "anthropic", "src", "command.ts"),
+    "@sidecar-ai/anthropic/components": path17.join(repoRoot, "packages", "anthropic", "src", "components.tsx"),
+    "@sidecar-ai/anthropic/hooks": path17.join(repoRoot, "packages", "anthropic", "src", "hooks.ts"),
+    "@sidecar-ai/anthropic/mcp": path17.join(repoRoot, "packages", "anthropic", "src", "mcp.ts"),
+    "@sidecar-ai/anthropic/plugin": path17.join(repoRoot, "packages", "anthropic", "src", "plugin.ts"),
+    "@sidecar-ai/anthropic/skill": path17.join(repoRoot, "packages", "anthropic", "src", "skill.ts")
+  };
+}
+function findSidecarRepoRoot2(startDir) {
+  let current = path17.resolve(startDir);
+  while (true) {
+    if (existsSync5(path17.join(current, "packages", "core", "src", "index.ts"))) {
+      return current;
+    }
+    const parent = path17.dirname(current);
+    if (parent === current) {
+      return void 0;
+    }
+    current = parent;
+  }
+}
+
 // packages/compiler/src/build.ts
 async function buildProject(options) {
-  const rootDir = path17.resolve(options.rootDir);
+  const rootDir = path18.resolve(options.rootDir);
   const target = options.target ?? "mcp";
+  const host = options.host ?? "node";
   const config = analyzeProjectConfig(rootDir);
   const tools = await analyzeProjectTools(rootDir, { target });
   const resources = await analyzeProjectResources(rootDir);
   const resourceTemplates = [];
   const prompts = await analyzeProjectPrompts(rootDir);
+  const identity = await loadProjectIdentity(rootDir);
   const diagnostics = await collectProjectDiagnostics(rootDir, {
     tools,
     resources,
@@ -2977,6 +3309,7 @@ async function buildProject(options) {
   const manifest = {
     version: 1,
     target,
+    host,
     rootDir: ".",
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     config,
@@ -2986,23 +3319,24 @@ async function buildProject(options) {
     prompts,
     diagnostics
   };
-  await mkdir8(outDir, { recursive: true });
-  await writeFile8(
-    path17.join(outDir, "manifest.sidecar.json"),
+  await mkdir9(outDir, { recursive: true });
+  await writeFile9(
+    path18.join(outDir, "manifest.sidecar.json"),
     `${JSON.stringify(manifest, null, 2)}
 `
   );
-  await writeFile8(path17.join(outDir, "README.md"), renderMcpReadme(manifest));
+  await writeFile9(path18.join(outDir, "README.md"), renderMcpReadme(manifest));
   await writeGeneratedTypes(rootDir, tools);
+  await buildServerOutput(rootDir, outDir, manifest, identity, host);
   if (options.plugins) {
-    await buildPluginPackages(rootDir, path17.dirname(outDir), manifest);
+    await buildPluginPackages(rootDir, path18.dirname(outDir), manifest);
   }
   return manifest;
 }
 function resolveInsideRoot(rootDir, output) {
-  const resolved = path17.resolve(rootDir, output);
-  const relative = path17.relative(rootDir, resolved);
-  if (relative.startsWith("..") || path17.isAbsolute(relative)) {
+  const resolved = path18.resolve(rootDir, output);
+  const relative = path18.relative(rootDir, resolved);
+  if (relative.startsWith("..") || path18.isAbsolute(relative)) {
     throw new Error(`Build output must stay inside the project root: ${output}`);
   }
   return resolved;
@@ -3027,9 +3361,35 @@ ${resources || "No resources detected."}
 
 ${prompts || "No prompts detected."}
 
+${manifest.host === "vercel" ? renderVercelReadmeSection() : renderNodeReadmeSection()}
+
 ## Local HTTPS Testing
 
-Run \`sidecar dev --tunnel\` from the project root to start the local MCP server on Streamable HTTP and print an HTTPS MCP URL that can be added to ChatGPT, Claude, or a Claude plugin install.
+Run \`sidecar dev --tunnel\` from the project root to start the local MCP server on Streamable HTTP and print a validated HTTPS MCP URL that can be added to ChatGPT, Claude, or a Claude plugin install. Temporary quick tunnels are public and best-effort; use a configured tunnel/domain or deployed preview for repeatable testing.
+`;
+}
+function renderNodeReadmeSection() {
+  return `## Run The Server
+
+This output includes a standalone Node MCP server. Start it with:
+
+\`\`\`sh
+npm start
+\`\`\`
+
+or:
+
+\`\`\`sh
+node server/index.js
+\`\`\`
+
+Set \`PORT\` or \`SIDECAR_PORT\` to choose the listen port. Hosted/authenticated MCPs should set \`SIDECAR_MCP_URL\` to the public \`https://.../mcp\` URL before starting.
+`;
+}
+function renderVercelReadmeSection() {
+  return `## Deploy To Vercel
+
+This output includes a Vercel Function shim at \`api/sidecar.js\` and a \`vercel.json\` rewrite that sends Streamable HTTP traffic to \`/mcp\`. Deploy this output directory with Vercel and set \`SIDECAR_MCP_URL\` to the public \`https://.../mcp\` URL.
 `;
 }
 
@@ -3042,7 +3402,7 @@ import { randomUUID } from "crypto";
 var proxyBrand = /* @__PURE__ */ Symbol.for("sidecar.proxy");
 function isSidecarProxy(value) {
   return Boolean(
-    value && typeof value === "object" && value[proxyBrand] === true
+    value && typeof value === "object" && (value[proxyBrand] === true || value.kind === "sidecar.proxy")
   );
 }
 async function runProxy(proxyConfig, request) {
@@ -3055,8 +3415,90 @@ async function runProxy(proxyConfig, request) {
   return void 0;
 }
 
-// packages/server/src/index.ts
+// packages/server/src/sse.ts
 import { JSONRPC_VERSION } from "@modelcontextprotocol/sdk/types.js";
+var sseEventCounter = 0;
+function createSseHub() {
+  const streams = /* @__PURE__ */ new Set();
+  return {
+    open(response) {
+      const stream = createSseStream(response);
+      streams.add(stream);
+      response.on("close", () => {
+        streams.delete(stream);
+      });
+      return stream;
+    },
+    send(method, params) {
+      const stream = streams.values().next().value;
+      stream?.send(method, params);
+    }
+  };
+}
+function createSseStream(response, options = {}) {
+  let closed = false;
+  response.writeHead(200, {
+    "content-type": "text/event-stream",
+    "cache-control": "no-cache, no-transform",
+    "connection": "keep-alive",
+    "x-accel-buffering": "no"
+  });
+  response.flushHeaders?.();
+  const keepAlive = setInterval(() => {
+    writeRaw(": keepalive\n\n");
+  }, 3e4);
+  keepAlive.unref?.();
+  response.on("close", () => {
+    closed = true;
+    clearInterval(keepAlive);
+  });
+  writeRaw(`id: ${nextSseEventId()}
+data:
+
+`);
+  function writeRaw(frame) {
+    if (!closed && !response.destroyed) {
+      response.write(frame);
+    }
+  }
+  function sendJson(value) {
+    writeRaw([
+      `id: ${nextSseEventId()}`,
+      "event: message",
+      `data: ${JSON.stringify(value)}`,
+      "",
+      ""
+    ].join("\n"));
+  }
+  return {
+    supportsRequestProgress: options.supportsRequestProgress,
+    send(method, params) {
+      sendJson(omitUndefined({
+        jsonrpc: JSONRPC_VERSION,
+        method,
+        params
+      }));
+    },
+    sendJson,
+    end() {
+      closed = true;
+      clearInterval(keepAlive);
+      response.end();
+    }
+  };
+}
+function nextSseEventId() {
+  sseEventCounter += 1;
+  return `sidecar-${Date.now()}-${sseEventCounter}`;
+}
+function omitUndefined(value) {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, entry]) => entry !== void 0)
+  );
+}
+
+// packages/server/src/index.ts
+import { JSONRPC_VERSION as JSONRPC_VERSION2 } from "@modelcontextprotocol/sdk/types.js";
 var SIDECAR_MCP_PROTOCOL_VERSION = "2025-11-25";
 var SidecarMcpServer = class {
   constructor(options) {
@@ -3100,6 +3542,8 @@ var SidecarMcpServer = class {
   resources = /* @__PURE__ */ new Map();
   prompts = /* @__PURE__ */ new Map();
   resourceTemplates;
+  activeRequests = /* @__PURE__ */ new Map();
+  subscribedResourceUris = /* @__PURE__ */ new Set();
   /** Returns all tool descriptors exposed through `tools/list`. */
   descriptors() {
     return [...this.tools.values()].map((loaded) => loaded.descriptor);
@@ -3124,13 +3568,16 @@ var SidecarMcpServer = class {
       const authorizedContext = { ...context, authSession };
       const result = await this.dispatch(request, authorizedContext);
       return {
-        jsonrpc: JSONRPC_VERSION,
+        jsonrpc: JSONRPC_VERSION2,
         id: request.id,
         result
       };
     } catch (error) {
+      if (error instanceof RequestCancelledError) {
+        return void 0;
+      }
       return {
-        jsonrpc: JSONRPC_VERSION,
+        jsonrpc: JSONRPC_VERSION2,
         id: request.id,
         error: normalizeError(error)
       };
@@ -3148,6 +3595,8 @@ var SidecarMcpServer = class {
             version: this.options.version ?? "0.0.0-dev"
           }
         };
+      case "ping":
+        return {};
       case "tools/list":
         return this.listTools(request, context);
       case "tools/call":
@@ -3260,29 +3709,39 @@ var SidecarMcpServer = class {
     if (authSession !== void 0) {
       ctx.auth = authSession;
     }
+    ctx.notify = this.createNotifications(context, request);
     const controller = new AbortController();
+    if (request.id !== null && request.id !== void 0) {
+      this.activeRequests.set(request.id, controller);
+    }
     ctx.request = {
       ...ctx.request,
       signal: controller.signal
     };
-    const args = loaded.descriptorProvided ? validateAgainstSchema(
-      loaded.descriptor.inputSchema,
-      params?.arguments ?? {},
-      `Invalid parameters for tool "${name}".`
-    ) : params?.arguments ?? {};
-    const result = await withTimeout(
-      executeTool(loaded.tool, args, ctx),
-      this.options.toolTimeoutMs,
-      controller
-    );
-    if (loaded.descriptorProvided) {
-      validateAgainstSchema(
-        loaded.descriptor.outputSchema,
-        result.structuredContent,
-        `Invalid structuredContent returned by tool "${name}".`
+    try {
+      const args = loaded.descriptorProvided ? validateAgainstSchema(
+        loaded.descriptor.inputSchema,
+        params?.arguments ?? {},
+        `Invalid parameters for tool "${name}".`
+      ) : params?.arguments ?? {};
+      const result = await withTimeout(
+        executeTool(loaded.tool, args, ctx),
+        this.options.toolTimeoutMs,
+        controller
       );
+      if (loaded.descriptorProvided) {
+        validateAgainstSchema(
+          loaded.descriptor.outputSchema,
+          result.structuredContent,
+          `Invalid structuredContent returned by tool "${name}".`
+        );
+      }
+      return result;
+    } finally {
+      if (request.id !== null && request.id !== void 0) {
+        this.activeRequests.delete(request.id);
+      }
     }
-    return result;
   }
   /** Authenticates the whole HTTP MCP request when auth.ts is configured. */
   async authorizeEndpoint(context) {
@@ -3334,6 +3793,7 @@ var SidecarMcpServer = class {
       if (context.authSession !== void 0) {
         toolContext.auth = context.authSession;
       }
+      toolContext.notify = this.createNotifications(context, request);
       return executeResource(resource.resource, toResourceContext(toolContext), {
         uri,
         mimeType: resource.descriptor.mimeType
@@ -3359,6 +3819,7 @@ var SidecarMcpServer = class {
     if (!this.resources.has(uri)) {
       throw new JsonRpcError(-32002, `Resource not found: "${uri}".`, { uri });
     }
+    this.subscribedResourceUris.add(uri);
     return {};
   }
   /** Accepts a resource unsubscription when server-level support is enabled. */
@@ -3370,6 +3831,7 @@ var SidecarMcpServer = class {
     if (!this.resources.has(uri)) {
       throw new JsonRpcError(-32002, `Resource not found: "${uri}".`, { uri });
     }
+    this.subscribedResourceUris.delete(uri);
     return {};
   }
   /** Renders one named prompt with validated arguments. */
@@ -3387,20 +3849,56 @@ var SidecarMcpServer = class {
     if (context.authSession !== void 0) {
       toolContext.auth = context.authSession;
     }
+    toolContext.notify = this.createNotifications(context, request);
     return executePrompt(loaded.prompt, params?.arguments ?? {}, toPromptContext(toolContext));
   }
+  /** Creates notification helpers scoped by advertised server capabilities. */
+  createNotifications(context, request) {
+    const configured = this.options.capabilities ?? {};
+    return createRuntimeNotifications(
+      context.notifications,
+      readProgressToken(request),
+      {
+        toolsListChanged: Boolean(configured.tools?.listChanged),
+        resourcesListChanged: Boolean(configured.resources?.listChanged),
+        promptsListChanged: Boolean(configured.prompts?.listChanged),
+        isResourceSubscribed: (uri) => this.subscribedResourceUris.has(uri)
+      }
+    );
+  }
   /** Accepts notifications without side effects for client compatibility. */
-  async handleNotification(_request) {
+  async handleNotification(request) {
+    if (request.method === "notifications/cancelled") {
+      this.cancelRequest(request);
+    }
+  }
+  /** Applies a client cancellation notification to an active request. */
+  cancelRequest(request) {
+    const params = request.params;
+    const requestId = params?.requestId;
+    if (typeof requestId !== "string" && typeof requestId !== "number") {
+      return;
+    }
+    const controller = this.activeRequests.get(requestId);
+    if (!controller || controller.signal.aborted) {
+      return;
+    }
+    const reason = typeof params?.reason === "string" ? params.reason : "Request cancelled.";
+    controller.abort(new RequestCancelledError(reason));
   }
 };
 function createSidecarMcpServer(options) {
   return new SidecarMcpServer(options);
 }
 function createSidecarHttpServer(options) {
-  const mcp = createSidecarMcpServer(options);
+  return createServer(createSidecarHttpHandler(options));
+}
+function createSidecarHttpHandler(options) {
   const endpoint = options.path ?? "/mcp";
   const maxBodyBytes = options.maxBodyBytes ?? 1e6;
-  return createServer(async (request, response) => {
+  const streamHub = createSseHub();
+  const mcp = createSidecarMcpServer(options);
+  return async (request, response) => {
     if (isRejectedOrigin(request, options.allowedOrigins)) {
       response.writeHead(403, { "content-type": "application/json" });
       response.end(JSON.stringify({ error: "forbidden_origin" }));
@@ -3419,11 +3917,39 @@ function createSidecarHttpServer(options) {
       return;
     }
     if (request.method === "GET" && pathname === endpoint) {
-      response.writeHead(405, { "content-type": "application/json" });
-      response.end(JSON.stringify({ error: "sse_not_supported" }));
+      try {
+        validateProtocolVersion(request);
+        validateGetHeaders(request);
+        const fetchRequest = toFetchRequest(request, options.publicUrl ?? options.auth?.resource);
+        if (options.auth) {
+          const authSession = await authorizeHttpRequest(options.auth, fetchRequest, response);
+          if (authSession === AUTH_RESPONSE_SENT) {
+            return;
+          }
+        }
+        streamHub.open(response);
+      } catch (error) {
+        const status = error instanceof JsonRpcHttpError ? error.status : 400;
+        response.writeHead(status, { "content-type": "application/json" });
+        response.end(
+          JSON.stringify({
+            jsonrpc: JSONRPC_VERSION2,
+            id: null,
+            error: normalizeHttpError(error)
+          })
+        );
+      }
       return;
     }
-    if (request.method !== "POST" || pathname !== endpoint) {
+    if (pathname === endpoint && request.method !== "POST") {
+      response.writeHead(405, {
+        "allow": "GET, POST",
+        "content-type": "application/json"
+      });
+      response.end(JSON.stringify({ error: "method_not_allowed" }));
+      return;
+    }
+    if (pathname !== endpoint) {
       response.writeHead(404, { "content-type": "application/json" });
       response.end(JSON.stringify({ error: "not_found" }));
       return;
@@ -3446,9 +3972,23 @@ function createSidecarHttpServer(options) {
       if (options.auth && authSession === AUTH_RESPONSE_SENT) {
         return;
       }
+      if (rpcRequest.id !== void 0 && hasProgressToken(rpcRequest)) {
+        const stream = createSseStream(response, { supportsRequestProgress: true });
+        const payload2 = await mcp.handle(rpcRequest, {
+          request: fetchRequest,
+          authSession,
+          notifications: stream
+        });
+        if (payload2) {
+          stream.sendJson(payload2);
+        }
+        stream.end();
+        return;
+      }
       const payload = await mcp.handle(rpcRequest, {
         request: fetchRequest,
-        authSession
+        authSession,
+        notifications: streamHub
       }) ?? null;
       const responses = payload === null ? [] : [payload];
       if (!responses.length) {
@@ -3467,13 +4007,13 @@ function createSidecarHttpServer(options) {
       response.writeHead(status, { "content-type": "application/json" });
       response.end(
         JSON.stringify({
-          jsonrpc: JSONRPC_VERSION,
+          jsonrpc: JSONRPC_VERSION2,
           id: null,
           error: normalizeHttpError(error)
         })
       );
     }
-  });
+  };
 }
 var DEFAULT_ALLOWED_ORIGINS = [
   "https://chatgpt.com",
@@ -3541,6 +4081,12 @@ var JsonRpcHttpError = class extends JsonRpcError {
   }
   status;
 };
+var RequestCancelledError = class extends Error {
+  constructor(message = "Request cancelled.") {
+    super(message);
+    this.name = "RequestCancelledError";
+  }
+};
 var AUTH_RESPONSE_SENT = /* @__PURE__ */ Symbol("sidecar.auth.response-sent");
 async function authorizeHttpRequest(auth, request, response) {
   const result = await auth.authorizeRequest(request);
@@ -3553,7 +4099,7 @@ async function authorizeHttpRequest(auth, request, response) {
   });
   response.end(
     JSON.stringify({
-      jsonrpc: JSONRPC_VERSION,
+      jsonrpc: JSONRPC_VERSION2,
       id: null,
       error: {
         code: result.status === 401 ? -32001 : -32003,
@@ -3596,9 +4142,57 @@ function createDefaultContext(request) {
         memory.delete(key);
       }
     },
+    notify: noopNotifications,
     env: process.env
   };
 }
+var noopNotifications = {
+  async progress() {
+  },
+  async toolsChanged() {
+  },
+  async resourcesChanged() {
+  },
+  async promptsChanged() {
+  },
+  async resourceUpdated() {
+  }
+};
+function createRuntimeNotifications(sink, progressToken, options) {
+  return {
+    async progress(update) {
+      if (!sink?.supportsRequestProgress || progressToken === void 0) {
+        return;
+      }
+      sink.send("notifications/progress", stripUndefined4({
+        progressToken,
+        progress: update.progress,
+        total: update.total,
+        message: update.message
+      }));
+    },
+    async toolsChanged() {
+      if (options.toolsListChanged) {
+        sink?.send("notifications/tools/list_changed");
+      }
+    },
+    async resourcesChanged() {
+      if (options.resourcesListChanged) {
+        sink?.send("notifications/resources/list_changed");
+      }
+    },
+    async promptsChanged() {
+      if (options.promptsListChanged) {
+        sink?.send("notifications/prompts/list_changed");
+      }
+    },
+    async resourceUpdated(uri) {
+      if (options.isResourceSubscribed(uri)) {
+        sink?.send("notifications/resources/updated", { uri });
+      }
+    }
+  };
+}
 function toResourceContext(ctx) {
   return {
     auth: ctx.auth,
@@ -3606,6 +4200,7 @@ function toResourceContext(ctx) {
     services: ctx.services,
     log: ctx.log,
     storage: ctx.storage,
+    notify: ctx.notify,
     env: ctx.env
   };
 }
@@ -3616,6 +4211,7 @@ function toPromptContext(ctx) {
     services: ctx.services,
     log: ctx.log,
     storage: ctx.storage,
+    notify: ctx.notify,
     env: ctx.env
   };
 }
@@ -3637,6 +4233,27 @@ function readUriParam(request, method) {
   }
   return uri;
 }
+function readProgressToken(request) {
+  const params = request.params;
+  if (!params || typeof params !== "object") {
+    return void 0;
+  }
+  const meta = params._meta;
+  if (!meta || typeof meta !== "object") {
+    return void 0;
+  }
+  const progressToken = meta.progressToken;
+  if (typeof progressToken === "string") {
+    return progressToken;
+  }
+  if (typeof progressToken === "number" && Number.isInteger(progressToken)) {
+    return progressToken;
+  }
+  return void 0;
+}
+function hasProgressToken(request) {
+  return readProgressToken(request) !== void 0;
+}
 function selectPaginationOverride(override, operation) {
   if (!override) {
     return void 0;
@@ -3725,18 +4342,48 @@ function validatePostHeaders(request) {
     );
   }
 }
+function validateGetHeaders(request) {
+  const accept = request.headers.accept;
+  const acceptValue = Array.isArray(accept) ? accept.join(",") : accept;
+  if (!acceptValue || !acceptValue.toLowerCase().includes("text/event-stream")) {
+    throw new JsonRpcHttpError(
+      406,
+      -32600,
+      "GET Accept must include text/event-stream."
+    );
+  }
+}
 async function withTimeout(promise, timeoutMs, controller) {
+  let abortListener;
+  const abortPromise = new Promise((_resolve, reject) => {
+    abortListener = () => {
+      reject(abortReason(controller.signal.reason));
+    };
+    if (controller.signal.aborted) {
+      abortListener();
+      return;
+    }
+    controller.signal.addEventListener("abort", abortListener, { once: true });
+  });
   if (!timeoutMs || timeoutMs <= 0) {
-    return promise;
+    try {
+      return await Promise.race([promise, abortPromise]);
+    } finally {
+      if (abortListener) {
+        controller.signal.removeEventListener("abort", abortListener);
+      }
+    }
   }
   let timeout;
   try {
     return await Promise.race([
       promise,
+      abortPromise,
       new Promise((_resolve, reject) => {
         timeout = setTimeout(() => {
-          controller.abort();
-          reject(new JsonRpcError(-32e3, "Tool execution timed out."));
+          const error = new JsonRpcError(-32e3, "Tool execution timed out.");
+          controller.abort(error);
+          reject(error);
         }, timeoutMs);
       })
     ]);
@@ -3744,7 +4391,16 @@ async function withTimeout(promise, timeoutMs, controller) {
     if (timeout) {
       clearTimeout(timeout);
     }
+    if (abortListener) {
+      controller.signal.removeEventListener("abort", abortListener);
+    }
+  }
+}
+function abortReason(reason) {
+  if (reason instanceof Error) {
+    return reason;
   }
+  return new RequestCancelledError();
 }
 function validateAgainstSchema(schema, value, message, options = {}) {
   if (!schema || value === void 0 && options.optional) {
@@ -3756,80 +4412,87 @@ function validateAgainstSchema(schema, value, message, options = {}) {
   }
   return value;
 }
-function schemaFailure(schema, value, path19) {
-  if (schema.anyOf?.length && !schema.anyOf.some((entry) => !schemaFailure(entry, value, path19))) {
-    return `${path19} must match one anyOf schema.`;
+function schemaFailure(schema, value, path20) {
+  if (schema.anyOf?.length && !schema.anyOf.some((entry) => !schemaFailure(entry, value, path20))) {
+    return `${path20} must match one anyOf schema.`;
   }
-  if (schema.oneOf?.length && schema.oneOf.filter((entry) => !schemaFailure(entry, value, path19)).length !== 1) {
-    return `${path19} must match exactly one oneOf schema.`;
+  if (schema.oneOf?.length && schema.oneOf.filter((entry) => !schemaFailure(entry, value, path20)).length !== 1) {
+    return `${path20} must match exactly one oneOf schema.`;
   }
   if (schema.allOf?.length) {
     for (const entry of schema.allOf) {
-      const failure = schemaFailure(entry, value, path19);
+      const failure = schemaFailure(entry, value, path20);
       if (failure) return failure;
     }
   }
   if (schema.const !== void 0 && value !== schema.const) {
-    return `${path19} must equal ${JSON.stringify(schema.const)}.`;
+    return `${path20} must equal ${JSON.stringify(schema.const)}.`;
   }
   if (schema.enum && !schema.enum.some((entry) => JSON.stringify(entry) === JSON.stringify(value))) {
-    return `${path19} must be one of the declared enum values.`;
+    return `${path20} must be one of the declared enum values.`;
   }
   if (schema.type) {
     const types = Array.isArray(schema.type) ? schema.type : [schema.type];
     if (!types.some((type) => matchesJsonSchemaType(type, value))) {
-      return `${path19} must be ${types.join(" or ")}.`;
+      return `${path20} must be ${types.join(" or ")}.`;
     }
   }
   if (schema.type === "object" || schema.properties || schema.required) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
-      return `${path19} must be an object.`;
+      return `${path20} must be an object.`;
     }
     const record = value;
     for (const required of schema.required ?? []) {
       if (!(required in record)) {
-        return `${path19}.${required} is required.`;
+        return `${path20}.${required} is required.`;
       }
     }
     for (const [key, propertySchema] of Object.entries(schema.properties ?? {})) {
       if (key in record) {
-        const failure = schemaFailure(propertySchema, record[key], `${path19}.${key}`);
+        const failure = schemaFailure(propertySchema, record[key], `${path20}.${key}`);
         if (failure) return failure;
       }
     }
+    const allowed = new Set(Object.keys(schema.properties ?? {}));
     if (schema.additionalProperties === false) {
-      const allowed = new Set(Object.keys(schema.properties ?? {}));
       const extra = Object.keys(record).find((key) => !allowed.has(key));
       if (extra) {
-        return `${path19}.${extra} is not allowed.`;
+        return `${path20}.${extra} is not allowed.`;
+      }
+    } else if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
+      for (const [key, entry] of Object.entries(record)) {
+        if (!allowed.has(key)) {
+          const failure = schemaFailure(schema.additionalProperties, entry, `${path20}.${key}`);
+          if (failure) return failure;
+        }
       }
     }
   }
   if (schema.type === "array" || schema.items) {
     if (!Array.isArray(value)) {
-      return `${path19} must be an array.`;
+      return `${path20} must be an array.`;
     }
     if (schema.items) {
       for (const [index, entry] of value.entries()) {
-        const failure = schemaFailure(schema.items, entry, `${path19}[${index}]`);
+        const failure = schemaFailure(schema.items, entry, `${path20}[${index}]`);
         if (failure) return failure;
       }
     }
   }
   if (typeof value === "string") {
     if (schema.minLength !== void 0 && value.length < schema.minLength) {
-      return `${path19} is shorter than ${schema.minLength}.`;
+      return `${path20} is shorter than ${schema.minLength}.`;
     }
     if (schema.maxLength !== void 0 && value.length > schema.maxLength) {
-      return `${path19} is longer than ${schema.maxLength}.`;
+      return `${path20} is longer than ${schema.maxLength}.`;
     }
   }
   if (typeof value === "number") {
     if (schema.minimum !== void 0 && value < schema.minimum) {
-      return `${path19} is less than ${schema.minimum}.`;
+      return `${path20} is less than ${schema.minimum}.`;
     }
     if (schema.maximum !== void 0 && value > schema.maximum) {
-      return `${path19} is greater than ${schema.maximum}.`;
+      return `${path20} is greater than ${schema.maximum}.`;
     }
   }
   return void 0;
@@ -3937,14 +4600,14 @@ function assertJsonRpcRequest(value) {
     throw new JsonRpcError(-32600, "Request must be a JSON object.");
   }
   const record = value;
-  if (record.jsonrpc !== JSONRPC_VERSION || typeof record.method !== "string") {
+  if (record.jsonrpc !== JSONRPC_VERSION2 || typeof record.method !== "string") {
     throw new JsonRpcError(-32600, "Invalid JSON-RPC request.");
   }
   if ("id" in record && record.id !== void 0 && record.id !== null && typeof record.id !== "string" && typeof record.id !== "number") {
     throw new JsonRpcError(-32600, "JSON-RPC id must be a string, number, or null.");
   }
   return {
-    jsonrpc: JSONRPC_VERSION,
+    jsonrpc: JSONRPC_VERSION2,
     id: typeof record.id === "string" || typeof record.id === "number" || record.id === null ? record.id : void 0,
     method: record.method,
     params: record.params
@@ -3955,7 +4618,7 @@ function isJsonRpcResponseMessage(value) {
     return false;
   }
   const record = value;
-  if (record.jsonrpc !== JSONRPC_VERSION || !("id" in record) || !("result" in record || "error" in record)) {
+  if (record.jsonrpc !== JSONRPC_VERSION2 || !("id" in record) || !("result" in record || "error" in record)) {
     return false;
   }
   return record.id === null || typeof record.id === "string" || typeof record.id === "number";
@@ -4007,11 +4670,31 @@ import { stdin, stdout } from "process";
 async function startTunnel(options) {
   const provider = await resolveProvider(options.provider);
   const localUrl = `http://127.0.0.1:${options.port}`;
-  const path19 = options.path ?? "/mcp";
+  const path20 = options.path ?? "/mcp";
   if (provider === "cloudflared") {
-    return startCloudflared(localUrl, path19, options.timeoutMs);
-  }
-  return startWrangler(localUrl, path19, options.timeoutMs);
+    return startCloudflared(localUrl, path20, options.timeoutMs);
+  }
+  return startWrangler(localUrl, path20, options.timeoutMs);
+}
+async function validateTunnelEndpoint(options) {
+  const timeoutMs = options.timeoutMs ?? 1e4;
+  const mcpUrl = new URL(options.mcpUrl);
+  if ((options.requireHttps ?? true) && mcpUrl.protocol !== "https:") {
+    throw new Error(`Tunnel URL must use https://, received ${options.mcpUrl}.`);
+  }
+  await retryTunnelValidation(async () => {
+    if (options.auth) {
+      await validateProtectedResourceMetadata({
+        mcpUrl,
+        expectedResource: options.expectedResource ?? options.mcpUrl,
+        timeoutMs
+      });
+      await validateAuthChallenge({ mcpUrl, timeoutMs });
+      return;
+    }
+    await validateInitialize({ mcpUrl, timeoutMs });
+    await validateToolsList({ mcpUrl, timeoutMs });
+  }, timeoutMs);
 }
 function tunnelInstallMessage(provider = "auto") {
   if (provider === "wrangler") {
@@ -4115,7 +4798,7 @@ function assertNpxAvailable() {
     throw new Error(tunnelInstallMessage("wrangler"));
   }
 }
-async function startCloudflared(localUrl, path19, timeoutMs = 2e4) {
+async function startCloudflared(localUrl, path20, timeoutMs = 2e4) {
   const child = spawn("cloudflared", ["tunnel", "--url", localUrl, "--no-autoupdate"], {
     stdio: ["ignore", "pipe", "pipe"]
   });
@@ -4123,13 +4806,13 @@ async function startCloudflared(localUrl, path19, timeoutMs = 2e4) {
   return {
     provider: "cloudflared",
     publicUrl,
-    mcpUrl: appendPath(publicUrl, path19),
+    mcpUrl: appendPath(publicUrl, path20),
     close() {
       child.kill("SIGTERM");
     }
   };
 }
-async function startWrangler(localUrl, path19, timeoutMs = 2e4) {
+async function startWrangler(localUrl, path20, timeoutMs = 2e4) {
   const child = spawn("npx", ["--yes", "wrangler", "tunnel", "quick-start", localUrl], {
     stdio: ["ignore", "pipe", "pipe"]
   });
@@ -4137,7 +4820,7 @@ async function startWrangler(localUrl, path19, timeoutMs = 2e4) {
   return {
     provider: "wrangler",
     publicUrl,
-    mcpUrl: appendPath(publicUrl, path19),
+    mcpUrl: appendPath(publicUrl, path20),
     close() {
       child.kill("SIGTERM");
     }
@@ -4146,15 +4829,20 @@ async function startWrangler(localUrl, path19, timeoutMs = 2e4) {
 function waitForTunnelUrl(child, pattern, timeoutMs) {
   return new Promise((resolve, reject) => {
     let settled = false;
+    let output = "";
     const timeout = setTimeout(() => {
       if (!settled) {
         settled = true;
         child.kill("SIGTERM");
-        reject(new Error("Timed out waiting for HTTPS tunnel URL."));
+        reject(new Error([
+          "Timed out waiting for HTTPS tunnel URL.",
+          tunnelOutputHint(output)
+        ].filter(Boolean).join("\n")));
       }
     }, timeoutMs);
     const inspect = (chunk) => {
-      const match = chunk.toString("utf8").match(pattern);
+      output = tail(`${output}${chunk.toString("utf8")}`, 4e3);
+      const match = output.match(pattern);
       if (match?.[0] && !settled) {
         settled = true;
         clearTimeout(timeout);
@@ -4174,11 +4862,209 @@ function waitForTunnelUrl(child, pattern, timeoutMs) {
       if (!settled) {
         settled = true;
         clearTimeout(timeout);
-        reject(new Error(`Tunnel process exited before producing a URL${code === null ? "" : ` with code ${code}`}.`));
+        reject(new Error([
+          `Tunnel process exited before producing a URL${code === null ? "" : ` with code ${code}`}.`,
+          tunnelOutputHint(output)
+        ].filter(Boolean).join("\n")));
       }
     });
   });
 }
+async function validateProtectedResourceMetadata(options) {
+  const metadataUrl = protectedResourceMetadataUrl(options.mcpUrl);
+  const response = await fetchWithTimeout(metadataUrl, {
+    headers: { accept: "application/json" },
+    timeoutMs: options.timeoutMs
+  });
+  const body = await readValidationBody(response);
+  assertNotHtml(response, body, metadataUrl);
+  if (response.status !== 200) {
+    if (isTransientHttpStatus(response.status)) {
+      throw new TransientTunnelValidationError(`Tunnel validation failed: ${metadataUrl} returned HTTP ${response.status}.`);
+    }
+    throw new Error(`Tunnel validation failed: ${metadataUrl} returned HTTP ${response.status}.`);
+  }
+  const metadata = parseJsonObject(body, metadataUrl);
+  if (metadata.resource !== options.expectedResource) {
+    throw new Error([
+      "Tunnel validation failed: OAuth protected-resource metadata does not match the public MCP URL.",
+      `  expected resource: ${options.expectedResource}`,
+      `  actual resource: ${String(metadata.resource)}`
+    ].join("\n"));
+  }
+}
+async function validateAuthChallenge(options) {
+  const response = await postJsonRpc(options.mcpUrl, {
+    jsonrpc: "2.0",
+    id: 1,
+    method: "initialize",
+    params: {
+      protocolVersion: "2025-11-25",
+      capabilities: {},
+      clientInfo: { name: "sidecar-tunnel-check", version: "0.0.0" }
+    }
+  }, options.timeoutMs);
+  const body = await readValidationBody(response);
+  assertNotHtml(response, body, options.mcpUrl.toString());
+  if (response.status !== 401) {
+    if (isTransientHttpStatus(response.status)) {
+      throw new TransientTunnelValidationError(`Tunnel validation failed: authenticated MCP endpoint returned HTTP ${response.status}.`);
+    }
+    throw new Error(`Tunnel validation failed: authenticated MCP endpoint should return HTTP 401 without a bearer token, received HTTP ${response.status}.`);
+  }
+  if (!response.headers.get("www-authenticate")?.toLowerCase().includes("bearer")) {
+    throw new Error("Tunnel validation failed: authenticated MCP endpoint did not include a Bearer WWW-Authenticate challenge.");
+  }
+  parseJsonObject(body, options.mcpUrl.toString());
+}
+async function validateInitialize(options) {
+  const response = await postJsonRpc(options.mcpUrl, {
+    jsonrpc: "2.0",
+    id: 1,
+    method: "initialize",
+    params: {
+      protocolVersion: "2025-11-25",
+      capabilities: {},
+      clientInfo: { name: "sidecar-tunnel-check", version: "0.0.0" }
+    }
+  }, options.timeoutMs);
+  const body = await readValidationBody(response);
+  assertNotHtml(response, body, options.mcpUrl.toString());
+  if (response.status !== 200) {
+    if (isTransientHttpStatus(response.status)) {
+      throw new TransientTunnelValidationError(`Tunnel validation failed: initialize returned HTTP ${response.status}.`);
+    }
+    throw new Error(`Tunnel validation failed: initialize returned HTTP ${response.status}.`);
+  }
+  const payload = parseJsonObject(body, options.mcpUrl.toString());
+  if (!isRecord3(payload.result) || typeof payload.result.protocolVersion !== "string") {
+    throw new Error("Tunnel validation failed: initialize did not return an MCP server result.");
+  }
+}
+async function validateToolsList(options) {
+  const response = await postJsonRpc(options.mcpUrl, {
+    jsonrpc: "2.0",
+    id: 2,
+    method: "tools/list"
+  }, options.timeoutMs);
+  const body = await readValidationBody(response);
+  assertNotHtml(response, body, options.mcpUrl.toString());
+  if (response.status !== 200) {
+    if (isTransientHttpStatus(response.status)) {
+      throw new TransientTunnelValidationError(`Tunnel validation failed: tools/list returned HTTP ${response.status}.`);
+    }
+    throw new Error(`Tunnel validation failed: tools/list returned HTTP ${response.status}.`);
+  }
+  const payload = parseJsonObject(body, options.mcpUrl.toString());
+  if (!isRecord3(payload.result) || !Array.isArray(payload.result.tools)) {
+    throw new Error("Tunnel validation failed: tools/list did not return a tools array.");
+  }
+}
+function postJsonRpc(url, payload, timeoutMs) {
+  return fetchWithTimeout(url.toString(), {
+    method: "POST",
+    headers: {
+      accept: "application/json, text/event-stream",
+      "content-type": "application/json"
+    },
+    body: JSON.stringify(payload),
+    timeoutMs
+  });
+}
+async function fetchWithTimeout(url, options) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
+  try {
+    return await fetch(url, {
+      ...options,
+      signal: controller.signal
+    });
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new TransientTunnelValidationError(`Tunnel validation failed: timed out fetching ${url}.`);
+    }
+    throw new TransientTunnelValidationError(
+      `Tunnel validation failed: could not fetch ${url}: ${errorMessage(error)}.`
+    );
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+async function retryTunnelValidation(validate, timeoutMs) {
+  const startedAt = Date.now();
+  let lastError;
+  while (Date.now() - startedAt <= timeoutMs) {
+    try {
+      await validate();
+      return;
+    } catch (error) {
+      lastError = error;
+      if (!(error instanceof TransientTunnelValidationError)) {
+        throw error;
+      }
+      await delay(500);
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error("Tunnel validation failed before the public endpoint became reachable.");
+}
+var TransientTunnelValidationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TransientTunnelValidationError";
+  }
+};
+function isTransientHttpStatus(status) {
+  return status === 408 || status === 425 || status === 429 || status >= 500;
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function readValidationBody(response) {
+  const text = await response.text();
+  return text.slice(0, 2e4);
+}
+function assertNotHtml(response, body, url) {
+  const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
+  const trimmed = body.trimStart().toLowerCase();
+  if (contentType.includes("text/html") || trimmed.startsWith("<!doctype html") || trimmed.startsWith("<html")) {
+    throw new Error([
+      `Tunnel validation failed: ${url} returned HTML instead of MCP JSON.`,
+      "This usually means the tunnel provider returned an interstitial, warning page, or bad route."
+    ].join("\n"));
+  }
+}
+function parseJsonObject(body, url) {
+  try {
+    const parsed = JSON.parse(body);
+    if (isRecord3(parsed)) {
+      return parsed;
+    }
+  } catch {
+  }
+  throw new Error(`Tunnel validation failed: ${url} did not return a JSON object.`);
+}
+function protectedResourceMetadataUrl(mcpUrl) {
+  const url = new URL(mcpUrl.origin);
+  const pathname = mcpUrl.pathname.replace(/\/+$/, "") || "/";
+  url.pathname = pathname === "/" ? "/.well-known/oauth-protected-resource" : `/.well-known/oauth-protected-resource${pathname}`;
+  return url.toString();
+}
+function tunnelOutputHint(output) {
+  const trimmed = output.trim();
+  return trimmed ? `Tunnel output:
+${trimmed}` : "";
+}
+function tail(value, maxLength) {
+  return value.length > maxLength ? value.slice(value.length - maxLength) : value;
+}
+function errorMessage(error) {
+  if (error instanceof Error) {
+    const cause = error.cause;
+    const causeMessage = cause instanceof Error ? ` (${cause.message})` : "";
+    return `${error.message}${causeMessage}`;
+  }
+  return String(error);
+}
 function hasCommand(command) {
   return spawnSync("which", [command], { stdio: "ignore" }).status === 0;
 }
@@ -4195,8 +5081,11 @@ function runInherited(command, args) {
     });
   });
 }
-function appendPath(origin, path19) {
-  return `${origin.replace(/\/+$/, "")}/${path19.replace(/^\/+/, "")}`;
+function appendPath(origin, path20) {
+  return `${origin.replace(/\/+$/, "")}/${path20.replace(/^\/+/, "")}`;
+}
+function isRecord3(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 
 // packages/cli/src/index.ts
@@ -4206,10 +5095,11 @@ async function main(argv) {
   switch (command) {
     case "build": {
       const target = readTarget(argv);
+      const host = readHost(argv);
       const outDir = readOption(argv, "--out") ?? `out/${target}`;
       const plugins = argv.includes("--plugins");
       const strict = argv.includes("--strict");
-      const manifest = await buildProject({ rootDir, outDir, plugins, strict, target });
+      const manifest = await buildProject({ rootDir, host, outDir, plugins, strict, target });
       printDiagnostics(manifest.diagnostics ?? []);
       if (strict && manifest.diagnostics?.length) {
         exit(1);
@@ -4217,6 +5107,12 @@ async function main(argv) {
       console.log(
         `Built ${manifest.tools.length} ${target} tool${manifest.tools.length === 1 ? "" : "s"}, ${manifest.resources.length} resource${manifest.resources.length === 1 ? "" : "s"}, and ${manifest.prompts.length} prompt${manifest.prompts.length === 1 ? "" : "s"} to ${outDir}.`
       );
+      console.log(`Host runtime: ${host}`);
+      if (host === "vercel") {
+        console.log(`Vercel MCP function: ${path19.join(outDir, VERCEL_ENTRYPOINT)}`);
+      } else {
+        console.log(`Hostable MCP server: ${path19.join(outDir, SERVER_ENTRYPOINT)}`);
+      }
       if (plugins) {
         console.log("Built claude-plugin package.");
       }
@@ -4248,18 +5144,20 @@ async function main(argv) {
       const target = readTarget(argv);
       const tunnelProvider = readTunnelProvider(argv);
       const outDir = `.sidecar/dev/${target}`;
+      const loadedAuth = await loadRuntimeAuth(rootDir);
+      const runtimeConfig = await loadRuntimeConfig(rootDir);
+      const proxy = await loadRuntimeProxy(rootDir);
+      const runtimeToolEntries = await analyzeProjectTools(rootDir, { target });
+      const runtimeTools = await loadRuntimeTools(rootDir, runtimeToolEntries);
       const manifest = await buildProject({ rootDir, outDir, target });
       printDiagnostics(manifest.diagnostics ?? []);
-      const tools = await loadRuntimeTools(rootDir, manifest);
+      const tools = attachBuiltToolDescriptors(runtimeTools, manifest);
       let tunnel;
       if (tunnelProvider) {
         tunnel = await startTunnel({ provider: tunnelProvider, port, path: "/mcp" });
         process.env.SIDECAR_MCP_URL = tunnel.mcpUrl;
       }
-      const loadedAuth = await loadRuntimeAuth(rootDir);
-      const runtimeConfig = await loadRuntimeConfig(rootDir);
       const auth = loadedAuth && tunnel ? loadedAuth.withResource(tunnel.mcpUrl) : loadedAuth;
-      const proxy = await loadRuntimeProxy(rootDir);
       const resources = await loadResources(rootDir, outDir, manifest);
       const prompts = await loadRuntimePrompts(rootDir, manifest);
       const server = createSidecarHttpServer({
@@ -4280,14 +5178,29 @@ async function main(argv) {
           pageSize: manifest.config.pagination.pageSize
         }
       });
-      server.listen(port, "127.0.0.1", () => {
+      let listening = false;
+      try {
+        await listenOnLocalhost(server, port);
+        listening = true;
+        if (tunnel) {
+          await validateTunnelEndpoint({
+            mcpUrl: tunnel.mcpUrl,
+            auth: Boolean(auth)
+          });
+        }
         console.log(`MCP running on Streamable HTTP (${target}) at http://127.0.0.1:${port}/mcp`);
         console.log(`Loaded ${tools.length} tool${tools.length === 1 ? "" : "s"}, ${resources.length} resource${resources.length === 1 ? "" : "s"}, and ${prompts.length} prompt${prompts.length === 1 ? "" : "s"}.`);
         if (tunnel) {
-          console.log(`HTTPS tunnel (${tunnel.provider}) ready: ${tunnel.mcpUrl}`);
+          console.log(`HTTPS tunnel (${tunnel.provider}) validated: ${tunnel.mcpUrl}`);
           console.log("Use this HTTPS MCP URL in ChatGPT, Claude, or a Claude plugin install.");
         }
-      });
+      } catch (error) {
+        tunnel?.close();
+        if (listening) {
+          await closeServer(server);
+        }
+        throw error;
+      }
       const shutdown = () => {
         tunnel?.close();
         server.close(() => exit(0));
@@ -4330,7 +5243,7 @@ async function main(argv) {
       console.log(`Sidecar
 
 Usage:
-  sidecar build [--cwd <dir>] [--target mcp|chatgpt|claude] [--out <dir>] [--plugins] [--strict]
+  sidecar build [--cwd <dir>] [--target mcp|chatgpt|claude] [--host node|vercel] [--out <dir>] [--plugins] [--strict]
   sidecar check [--cwd <dir>] [--target mcp|chatgpt|claude] [--strict]
   sidecar dev [--cwd <dir>] [--target mcp|chatgpt|claude] [--port <port>] [--tunnel [cloudflared|wrangler]]
   sidecar inspect [--cwd <dir>] [--target mcp|chatgpt|claude]
@@ -4345,9 +5258,16 @@ function readTarget(argv) {
   }
   throw new Error(`Unsupported Sidecar target "${target}". Expected mcp, chatgpt, or claude.`);
 }
+function readHost(argv) {
+  const host = readOption(argv, "--host") ?? "node";
+  if (host === "node" || host === "vercel") {
+    return host;
+  }
+  throw new Error(`Unsupported Sidecar host "${host}". Expected node or vercel.`);
+}
 async function previewComponents(options) {
-  const cliDir = path18.dirname(fileURLToPath(import.meta.url));
-  const css = await readFile8(path18.join(cliDir, "../../native/src/styles.css"), "utf8").catch(() => readFile8(path18.join(process.cwd(), "packages/native/src/styles.css"), "utf8")).catch(() => "");
+  const cliDir = path19.dirname(fileURLToPath(import.meta.url));
+  const css = await readFile8(path19.join(cliDir, "../../native/src/styles.css"), "utf8").catch(() => readFile8(path19.join(process.cwd(), "packages/native/src/styles.css"), "utf8")).catch(() => "");
   const html = renderComponentPreviewHtml(
     options.host,
     options.compare,
@@ -4387,10 +5307,10 @@ async function previewComponents(options) {
   server.close();
 }
 async function writeComponentApproval(rootDir, approval) {
-  const dir = path18.join(rootDir, ".sidecar", "approvals");
-  await mkdir9(dir, { recursive: true });
-  await writeFile9(
-    path18.join(dir, `components.${approval.host}.json`),
+  const dir = path19.join(rootDir, ".sidecar", "approvals");
+  await mkdir10(dir, { recursive: true });
+  await writeFile10(
+    path19.join(dir, `components.${approval.host}.json`),
     `${JSON.stringify(approval, null, 2)}
 `
   );
@@ -4742,84 +5662,98 @@ function printDiagnostics(diagnostics) {
   }
 }
 async function loadRuntimeAuth(rootDir) {
-  const authPath = path18.join(rootDir, "auth.ts");
-  if (!existsSync5(authPath)) {
+  const authPath = path19.join(rootDir, "auth.ts");
+  if (!existsSync6(authPath)) {
     return void 0;
   }
-  const parentURL = pathToFileURL(path18.join(rootDir, "sidecar.config.ts")).href;
-  const tsconfigPath = path18.join(rootDir, "tsconfig.json");
-  const tsconfig = existsSync5(tsconfigPath) ? tsconfigPath : false;
+  const parentURL = pathToFileURL(path19.join(rootDir, "sidecar.config.ts")).href;
+  const tsconfigPath = path19.join(rootDir, "tsconfig.json");
+  const tsconfig = existsSync6(tsconfigPath) ? tsconfigPath : false;
   const module = await tsImport(pathToFileURL(authPath).href, {
     parentURL,
     tsconfig
   });
-  if (!isSidecarAuth(module.default)) {
+  const defaultExport = unwrapRuntimeDefault(module.default);
+  if (!isSidecarAuth(defaultExport)) {
     throw new Error("auth.ts must default-export auth({ ... }) from sidecar-ai.");
   }
-  return module.default;
+  return defaultExport;
 }
 async function loadRuntimeProxy(rootDir) {
-  const proxyPath = path18.join(rootDir, "proxy.ts");
-  if (!existsSync5(proxyPath)) {
+  const proxyPath = path19.join(rootDir, "proxy.ts");
+  if (!existsSync6(proxyPath)) {
     return void 0;
   }
-  const parentURL = pathToFileURL(path18.join(rootDir, "sidecar.config.ts")).href;
-  const tsconfigPath = path18.join(rootDir, "tsconfig.json");
-  const tsconfig = existsSync5(tsconfigPath) ? tsconfigPath : false;
+  const parentURL = pathToFileURL(path19.join(rootDir, "sidecar.config.ts")).href;
+  const tsconfigPath = path19.join(rootDir, "tsconfig.json");
+  const tsconfig = existsSync6(tsconfigPath) ? tsconfigPath : false;
   const module = await tsImport(pathToFileURL(proxyPath).href, {
     parentURL,
     tsconfig
   });
-  if (!isSidecarProxy(module.default)) {
+  const defaultExport = unwrapRuntimeDefault(module.default);
+  if (!isSidecarProxy(defaultExport)) {
     throw new Error("proxy.ts must default-export proxy({ ... }) from @sidecar-ai/server/proxy.");
   }
-  return module.default;
+  return defaultExport;
 }
 async function loadRuntimeConfig(rootDir) {
-  const configPath = path18.join(rootDir, "sidecar.config.ts");
-  if (!existsSync5(configPath)) {
+  const configPath = path19.join(rootDir, "sidecar.config.ts");
+  if (!existsSync6(configPath)) {
     return void 0;
   }
   const parentURL = pathToFileURL(configPath).href;
-  const tsconfigPath = path18.join(rootDir, "tsconfig.json");
-  const tsconfig = existsSync5(tsconfigPath) ? tsconfigPath : false;
+  const tsconfigPath = path19.join(rootDir, "tsconfig.json");
+  const tsconfig = existsSync6(tsconfigPath) ? tsconfigPath : false;
   const module = await tsImport(pathToFileURL(configPath).href, {
     parentURL,
     tsconfig
   });
-  if (!module.default || typeof module.default !== "object") {
+  const defaultExport = unwrapRuntimeDefault(module.default);
+  if (!defaultExport || typeof defaultExport !== "object") {
     throw new Error("sidecar.config.ts must default-export defineConfig({ ... }) from sidecar-ai.");
   }
-  return module.default;
+  return defaultExport;
 }
-async function loadRuntimeTools(rootDir, manifest) {
-  const parentURL = pathToFileURL(path18.join(rootDir, "sidecar.config.ts")).href;
-  const tsconfigPath = path18.join(rootDir, "tsconfig.json");
-  const tsconfig = existsSync5(tsconfigPath) ? tsconfigPath : false;
+async function loadRuntimeTools(rootDir, entries) {
+  const parentURL = pathToFileURL(path19.join(rootDir, "sidecar.config.ts")).href;
+  const tsconfigPath = path19.join(rootDir, "tsconfig.json");
+  const tsconfig = existsSync6(tsconfigPath) ? tsconfigPath : false;
   const loaded = [];
-  for (const entry of manifest.tools) {
-    const sourcePath = path18.join(rootDir, entry.sourceFile);
+  for (const entry of entries) {
+    const sourcePath = path19.join(rootDir, entry.sourceFile);
     const module = await tsImport(pathToFileURL(sourcePath).href, {
       parentURL,
       tsconfig
     });
-    if (!isSidecarTool(module.default)) {
+    const defaultExport = unwrapRuntimeDefault(module.default);
+    if (!isSidecarTool(defaultExport)) {
       throw new Error(`${entry.sourceFile} did not default-export a Sidecar tool.`);
     }
     loaded.push({
-      tool: module.default,
+      sourceFile: entry.sourceFile,
+      tool: defaultExport,
       descriptor: entry.descriptor
     });
   }
   return loaded;
 }
+function attachBuiltToolDescriptors(loadedTools, manifest) {
+  const descriptorsBySource = new Map(
+    manifest.tools.map((entry) => [entry.sourceFile, entry.descriptor])
+  );
+  return loadedTools.map(({ sourceFile, tool, descriptor }) => ({
+    tool,
+    descriptor: descriptorsBySource.get(sourceFile) ?? descriptor
+  }));
+}
 async function loadResources(rootDir, outDir, manifest) {
   const resources = [];
   for (const entry of manifest.tools) {
     if (!entry.widget?.outputFile) {
       continue;
     }
-    const text = await readFile8(path18.join(rootDir, outDir, entry.widget.outputFile), "utf8");
+    const text = await readFile8(path19.join(rootDir, outDir, entry.widget.outputFile), "utf8");
     resources.push({
       uri: entry.widget.resourceUri,
       name: entry.name,
@@ -4829,47 +5763,72 @@ async function loadResources(rootDir, outDir, manifest) {
       _meta: entry.widget.resourceMeta
     });
   }
-  const parentURL = pathToFileURL(path18.join(rootDir, "sidecar.config.ts")).href;
-  const tsconfigPath = path18.join(rootDir, "tsconfig.json");
-  const tsconfig = existsSync5(tsconfigPath) ? tsconfigPath : false;
+  const parentURL = pathToFileURL(path19.join(rootDir, "sidecar.config.ts")).href;
+  const tsconfigPath = path19.join(rootDir, "tsconfig.json");
+  const tsconfig = existsSync6(tsconfigPath) ? tsconfigPath : false;
   for (const entry of manifest.resources) {
-    const sourcePath = path18.join(rootDir, entry.sourceFile);
+    const sourcePath = path19.join(rootDir, entry.sourceFile);
     const module = await tsImport(pathToFileURL(sourcePath).href, {
       parentURL,
       tsconfig
     });
-    if (!isSidecarResource(module.default)) {
+    const defaultExport = unwrapRuntimeDefault(module.default);
+    if (!isSidecarResource(defaultExport)) {
       throw new Error(`${entry.sourceFile} did not default-export a Sidecar resource.`);
     }
     resources.push({
       uri: entry.uri,
       descriptor: entry.descriptor,
-      resource: module.default
+      resource: defaultExport
     });
   }
   return resources;
 }
 async function loadRuntimePrompts(rootDir, manifest) {
-  const parentURL = pathToFileURL(path18.join(rootDir, "sidecar.config.ts")).href;
-  const tsconfigPath = path18.join(rootDir, "tsconfig.json");
-  const tsconfig = existsSync5(tsconfigPath) ? tsconfigPath : false;
+  const parentURL = pathToFileURL(path19.join(rootDir, "sidecar.config.ts")).href;
+  const tsconfigPath = path19.join(rootDir, "tsconfig.json");
+  const tsconfig = existsSync6(tsconfigPath) ? tsconfigPath : false;
   const loaded = [];
   for (const entry of manifest.prompts) {
-    const sourcePath = path18.join(rootDir, entry.sourceFile);
+    const sourcePath = path19.join(rootDir, entry.sourceFile);
     const module = await tsImport(pathToFileURL(sourcePath).href, {
       parentURL,
       tsconfig
     });
-    if (!isSidecarPrompt(module.default)) {
+    const defaultExport = unwrapRuntimeDefault(module.default);
+    if (!isSidecarPrompt(defaultExport)) {
       throw new Error(`${entry.sourceFile} did not default-export a Sidecar prompt.`);
     }
     loaded.push({
-      prompt: module.default,
+      prompt: defaultExport,
       descriptor: entry.descriptor
     });
   }
   return loaded;
 }
+function unwrapRuntimeDefault(value) {
+  if (value && typeof value === "object" && "default" in value && Object.keys(value).length === 1) {
+    return unwrapRuntimeDefault(value.default);
+  }
+  return value;
+}
+function listenOnLocalhost(server, port) {
+  return new Promise((resolve, reject) => {
+    const onError = (error) => {
+      reject(error);
+    };
+    server.once("error", onError);
+    server.listen(port, "127.0.0.1", () => {
+      server.off("error", onError);
+      resolve();
+    });
+  });
+}
+function closeServer(server) {
+  return new Promise((resolve) => {
+    server.close(() => resolve());
+  });
+}
 function readOption(argv, name) {
   const index = argv.indexOf(name);
   if (index === -1) {