@synapsor/runner 0.1.0-alpha.10 → 0.1.0-alpha.11

package/README.md

@@ -20,6 +20,10 @@ These are current alpha requirements, not hidden behavior:
 - `synapsor-runner mcp serve-streamable-http` is standard MCP Streamable HTTP
   with `initialize` and in-memory session behavior for SDK/client HTTP MCP
   integrations.
+- OpenAI Agents SDK rejects dotted function/tool names. Use
+  `--alias-mode openai` or `--openai-tool-aliases` for OpenAI-facing MCP
+  transports. Runner exposes aliases such as `billing__inspect_invoice` and
+  keeps the canonical Synapsor capability name in tool metadata.
 - `synapsor-runner mcp serve-http` is a small authenticated JSON-RPC bridge for
   `tools/list`, `tools/call`, and `resources/read`. Use it only when you want a
   simple app/server wrapper instead of full HTTP MCP.
@@ -199,6 +203,15 @@ synapsor-runner mcp serve \
   --store ./.synapsor/local.db
 ```
 
+For OpenAI Agents SDK over stdio, add OpenAI-safe aliases:
+
+```bash
+synapsor-runner mcp serve \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --alias-mode openai
+```
+
 App/server deployments:
 
 ```bash
@@ -207,12 +220,29 @@ export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
 synapsor-runner mcp serve-streamable-http \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db \
-  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN \
+  --alias-mode openai
+```
+
+Equivalent unified command:
+
+```bash
+synapsor-runner mcp serve \
+  --transport streamable-http \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN \
+  --alias-mode openai
 ```
 
 Streamable HTTP defaults to `127.0.0.1:8766`, requires bearer auth by default,
 and should use private networking, TLS, and rate limits before being exposed
-beyond a local machine.
+beyond a local machine. With `--alias-mode openai`, tools are exposed to
+the model as OpenAI-safe aliases such as `billing__inspect_invoice`; `_meta`
+still includes `synapsor.canonical_tool_name = billing.inspect_invoice`, and
+Runner routes calls back to the canonical Synapsor capability. Use
+`--alias-mode both` during migrations if one client still expects canonical
+dotted names while another needs OpenAI-safe aliases.
 
 Bridge mode:
 
@@ -245,6 +275,15 @@ Before asking an agent to solve a real task, confirm it can call a Runner tool:
 synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
 ```
 
+For OpenAI-facing clients:
+
+```bash
+synapsor-runner tools preview \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --alias-mode openai
+```
+
 Then ask the agent:
 
 ```text

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAYA,OAAO,EAAkF,KAAK,WAAW,EAAoD,MAAM,6BAA6B,CAAC;AAkBjM,OAAO,EAA6G,KAAK,YAAY,EAAwB,MAAM,2BAA2B,CAAC;AAC/L,OAAO,EAOL,KAAK,gBAAgB,EAEtB,MAAM,mCAAmC,CAAC;AAkS3C,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAiD1D;AA0DD,KAAK,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9E,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;CACvC,GACL,OAAO,CAAC,MAAM,CAAC,CA2OjB;AAo9CD,wBAAsB,0BAA0B,CAAC,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAM/H"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAYA,OAAO,EAAqG,KAAK,WAAW,EAAwE,MAAM,6BAA6B,CAAC;AAkBxO,OAAO,EAA6G,KAAK,YAAY,EAAwB,MAAM,2BAA2B,CAAC;AAC/L,OAAO,EAOL,KAAK,gBAAgB,EAEtB,MAAM,mCAAmC,CAAC;AAkS3C,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAiD1D;AA0DD,KAAK,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9E,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;CACvC,GACL,OAAO,CAAC,MAAM,CAAC,CA2OjB;AAo9CD,wBAAsB,0BAA0B,CAAC,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAM/H"}

package/dist/runner.mjs

@@ -2685,59 +2685,74 @@ function createMcpRuntime(config, options = {}) {
     }
   };
 }
-function createSynapsorMcpServer(runtime) {
+function createSynapsorMcpServer(runtime, options = {}) {
   const server = new McpServer(
-    { name: "synapsor-runner", version: "0.1.0-alpha.10" },
+    { name: "synapsor-runner", version: "0.1.0-alpha.11" },
     { capabilities: { tools: {}, resources: {} } }
   );
+  const toolNameStyle = options.toolNameStyle ?? "canonical";
   if (runtime.config.mode === "cloud") {
-    for (const tool of runtime.listTools()) {
-      server.registerTool(
-        tool.name,
-        {
-          title: tool.title,
-          description: tool.description,
-          inputSchema: zodInputShapeFromJsonSchema(tool.input_schema),
-          annotations: {
-            readOnlyHint: Boolean(tool.annotations.readOnlyHint),
-            destructiveHint: false,
-            idempotentHint: Boolean(tool.annotations.idempotentHint),
-            openWorldHint: false
+    const tools2 = runtime.listTools();
+    const exposedNames = toolNameExposureMap(tools2.map((tool) => tool.name), toolNameStyle);
+    for (const tool of tools2) {
+      for (const exposedName of exposedNames.get(tool.name) ?? [tool.name]) {
+        server.registerTool(
+          exposedName,
+          {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: zodInputShapeFromJsonSchema(tool.input_schema),
+            annotations: {
+              readOnlyHint: Boolean(tool.annotations.readOnlyHint),
+              destructiveHint: false,
+              idempotentHint: Boolean(tool.annotations.idempotentHint),
+              openWorldHint: false
+            },
+            _meta: {
+              ...tool.annotations,
+              "synapsor.cloud_delegated": true,
+              "synapsor.canonical_tool_name": tool.name,
+              "synapsor.exposed_tool_name": exposedName,
+              "synapsor.tool_name_style": toolNameStyle,
+              "synapsor.raw_sql_exposed": false,
+              "synapsor.approval_tool": false
+            }
           },
-          _meta: {
-            ...tool.annotations,
-            "synapsor.cloud_delegated": true,
-            "synapsor.raw_sql_exposed": false,
-            "synapsor.approval_tool": false
-          }
-        },
-        async (args) => toolCallResult(runtime, tool.name, args)
-      );
+          async (args) => toolCallResult(runtime, tool.name, args)
+        );
+      }
     }
   } else {
-    for (const capability of listedLocalCapabilities(runtime.config)) {
-      server.registerTool(
-        capability.name,
-        {
-          title: capability.name,
-          description: capabilityDescription(capability),
-          inputSchema: zodInputShape(capability),
-          annotations: {
-            readOnlyHint: capability.kind === "read",
-            destructiveHint: false,
-            idempotentHint: capability.kind === "read",
-            openWorldHint: false
+    const capabilities = listedLocalCapabilities(runtime.config);
+    const exposedNames = toolNameExposureMap(capabilities.map((capability) => capability.name), toolNameStyle);
+    for (const capability of capabilities) {
+      for (const exposedName of exposedNames.get(capability.name) ?? [capability.name]) {
+        server.registerTool(
+          exposedName,
+          {
+            title: capability.name,
+            description: capabilityDescription(capability),
+            inputSchema: zodInputShape(capability),
+            annotations: {
+              readOnlyHint: capability.kind === "read",
+              destructiveHint: false,
+              idempotentHint: capability.kind === "read",
+              openWorldHint: false
+            },
+            _meta: {
+              "synapsor.kind": capability.kind,
+              "synapsor.source": capability.source,
+              "synapsor.target": `${capability.target.schema}.${capability.target.table}`,
+              "synapsor.canonical_tool_name": capability.name,
+              "synapsor.exposed_tool_name": exposedName,
+              "synapsor.tool_name_style": toolNameStyle,
+              "synapsor.raw_sql_exposed": false,
+              "synapsor.approval_tool": false
+            }
           },
-          _meta: {
-            "synapsor.kind": capability.kind,
-            "synapsor.source": capability.source,
-            "synapsor.target": `${capability.target.schema}.${capability.target.table}`,
-            "synapsor.raw_sql_exposed": false,
-            "synapsor.approval_tool": false
-          }
-        },
-        async (args) => toolCallResult(runtime, capability.name, args)
-      );
+          async (args) => toolCallResult(runtime, capability.name, args)
+        );
+      }
     }
   }
   server.registerResource(
@@ -2764,7 +2779,7 @@ async function serveStdio(options = {}) {
   const config = options.config ?? loadRuntimeConfigFromFile(options.configPath);
   const cloudTools = config.mode === "cloud" ? await fetchCloudToolMetadata(config, process.env) : void 0;
   const runtime = createMcpRuntime(config, { storePath: options.storePath, cloudTools });
-  const server = createSynapsorMcpServer(runtime);
+  const server = createSynapsorMcpServer(runtime, { toolNameStyle: options.toolNameStyle });
   const transport = new StdioServerTransport();
   await server.connect(transport);
   await new Promise((resolve) => {
@@ -2872,6 +2887,7 @@ async function startStreamableHttpMcpServer(options = {}) {
       readRow: options.readRow,
       cloudTools,
       env,
+      toolNameStyle: options.toolNameStyle,
       authToken,
       devNoAuth,
       corsOrigin: options.corsOrigin,
@@ -2914,7 +2930,7 @@ async function startStreamableHttpMcpServer(options = {}) {
   };
 }
 async function handleStreamableHttpMcpRequest(input) {
-  const { request, response, config, storePath, readRow, cloudTools, env, authToken, devNoAuth, corsOrigin, sessions, openSessions } = input;
+  const { request, response, config, storePath, readRow, cloudTools, env, toolNameStyle, authToken, devNoAuth, corsOrigin, sessions, openSessions } = input;
   try {
     setCorsHeaders(response, corsOrigin);
     if (request.method === "OPTIONS" && corsOrigin) {
@@ -2982,7 +2998,7 @@ async function handleStreamableHttpMcpRequest(input) {
     transport.onclose = () => {
       if (session) disposeStreamableSession(session, sessions, openSessions);
     };
-    await createSynapsorMcpServer(runtime).connect(transport);
+    await createSynapsorMcpServer(runtime, { toolNameStyle }).connect(transport);
     await transport.handleRequest(request, response, parsedBody);
   } catch (error) {
     const message = sanitizeHttpError(error, authToken);
@@ -3103,6 +3119,50 @@ function requestIdFromPayload(payload) {
   }
   return isRecord3(payload) ? payload.id ?? null : null;
 }
+function openaiToolNameAlias(canonicalName) {
+  const sanitized = canonicalName.replace(/[^A-Za-z0-9_-]+/g, "__").replace(/_{3,}/g, "__").replace(/^_+|_+$/g, "");
+  const base = sanitized.length > 0 ? sanitized : `tool_${shortToolHash(canonicalName)}`;
+  if (base.length <= 64) return base;
+  const suffix = shortToolHash(canonicalName);
+  return `${base.slice(0, Math.max(1, 63 - suffix.length)).replace(/_+$/g, "")}_${suffix}`;
+}
+function toolNameExposures(canonicalNames, style) {
+  const exposedNames = toolNameExposureMap(canonicalNames, style);
+  return canonicalNames.flatMap((canonicalName) => {
+    return (exposedNames.get(canonicalName) ?? [canonicalName]).map((exposedName) => ({
+      canonicalName,
+      exposedName,
+      isAlias: exposedName !== canonicalName,
+      style
+    }));
+  });
+}
+function toolNameExposureMap(canonicalNames, style) {
+  const exposedByCanonical = /* @__PURE__ */ new Map();
+  const canonicalByExposed = /* @__PURE__ */ new Map();
+  if (style === "both") {
+    for (const canonical of canonicalNames) canonicalByExposed.set(canonical, canonical);
+  }
+  for (const canonical of canonicalNames) {
+    const names = /* @__PURE__ */ new Set();
+    if (style === "canonical" || style === "both") names.add(canonical);
+    if (style === "openai" || style === "both") {
+      let alias = openaiToolNameAlias(canonical);
+      const existing = canonicalByExposed.get(alias);
+      if (existing && existing !== canonical) {
+        const suffix = shortToolHash(canonical);
+        alias = `${alias.slice(0, Math.max(1, 63 - suffix.length)).replace(/_+$/g, "")}_${suffix}`;
+      }
+      canonicalByExposed.set(alias, canonical);
+      names.add(alias);
+    }
+    exposedByCanonical.set(canonical, [...names]);
+  }
+  return exposedByCanonical;
+}
+function shortToolHash(value) {
+  return crypto.createHash("sha256").update(value).digest("hex").slice(0, 8);
+}
 function setCorsHeaders(response, corsOrigin) {
   if (corsOrigin) {
     response.setHeader("access-control-allow-origin", corsOrigin);
@@ -8633,7 +8693,7 @@ async function cloudConnect(args) {
     return 1;
   }
   const runnerId = String(parsed.cloud.runner_id || process2.env.SYNAPSOR_RUNNER_ID || "synapsor_runner_local").trim();
-  const runnerVersion = String(parsed.cloud.runner_version || process2.env.npm_package_version || "0.1.0-alpha.10").trim();
+  const runnerVersion = String(parsed.cloud.runner_version || process2.env.npm_package_version || "0.1.0-alpha.11").trim();
   const engines = normalizeEngines(parsed.cloud.engines);
   const capabilities = normalizeCapabilities(parsed.cloud.capabilities);
   const client = new ControlPlaneClient({
@@ -8687,6 +8747,7 @@ async function mcp(args) {
   if (subcommand === "serve-streamable-http") return mcpServeStreamableHttp(rest);
   if (subcommand === "audit") return mcpAudit(rest);
   if (subcommand === "config") return mcpConfig(rest);
+  if (subcommand === "client-config") return mcpConfigure(rest);
   if (subcommand === "configure") return mcpConfigure(rest);
   if (subcommand === "smoke") return mcpSmoke(rest);
   usage(["mcp"]);
@@ -9345,13 +9406,19 @@ function quickDemoChangeSet() {
   };
 }
 async function mcpServe(args) {
+  const transport = optionalArg(args, "--transport") ?? "stdio";
+  if (transport === "streamable-http") return mcpServeStreamableHttp(args);
+  if (transport === "http" || transport === "json-rpc-http" || transport === "jsonrpc-http") return mcpServeHttp(args);
+  if (transport !== "stdio") throw new Error("--transport must be stdio, streamable-http, or http");
   const configPath = optionalArg(args, "--config") ?? process2.env.SYNAPSOR_MCP_CONFIG;
   const readOnly = args.includes("--read-only");
   const config = readOnly ? { ...await readRuntimeConfig(configPath ?? defaultConfigPath), mode: "read_only" } : void 0;
+  const toolNameStyle = toolNameStyleOption(args);
   await serveStdio({
     configPath,
     storePath: optionalArg(args, "--store") ?? process2.env.SYNAPSOR_LOCAL_STORE,
-    config
+    config,
+    toolNameStyle
   });
   return 0;
 }
@@ -9394,6 +9461,7 @@ async function mcpServeStreamableHttp(args) {
   const configPath = optionalArg(args, "--config") ?? process2.env.SYNAPSOR_MCP_CONFIG;
   const readOnly = args.includes("--read-only");
   const config = readOnly ? { ...await readRuntimeConfig(configPath ?? defaultConfigPath), mode: "read_only" } : void 0;
+  const toolNameStyle = toolNameStyleOption(args);
   const host = optionalArg(args, "--host") ?? "127.0.0.1";
   const port = Number(optionalArg(args, "--port") ?? "8766");
   if (!Number.isInteger(port) || port <= 0 || port > 65535) {
@@ -9408,6 +9476,7 @@ async function mcpServeStreamableHttp(args) {
     storePath: optionalArg(args, "--store") ?? process2.env.SYNAPSOR_LOCAL_STORE,
     host,
     port,
+    toolNameStyle,
     authTokenEnv: optionalArg(args, "--auth-token-env") ?? "SYNAPSOR_RUNNER_HTTP_TOKEN",
     devNoAuth: args.includes("--dev-no-auth"),
     corsOrigin: optionalArg(args, "--cors-origin")
@@ -9425,6 +9494,21 @@ async function mcpServeStreamableHttp(args) {
   });
   return 0;
 }
+function toolNameStyleOption(args) {
+  const requestedStyle = optionalArg(args, "--tool-name-style");
+  const requestedAliasMode = optionalArg(args, "--alias-mode");
+  if (requestedStyle && requestedAliasMode && requestedStyle !== requestedAliasMode) {
+    throw new Error("--tool-name-style and --alias-mode must match when both are provided");
+  }
+  const requested = requestedAliasMode ?? requestedStyle;
+  if (args.includes("--openai-tool-aliases")) {
+    if (requested && requested !== "openai") throw new Error("--openai-tool-aliases cannot be combined with a non-openai alias mode");
+    return "openai";
+  }
+  if (!requested) return "canonical";
+  if (requested === "canonical" || requested === "openai" || requested === "both") return requested;
+  throw new Error("--alias-mode must be canonical, openai, or both");
+}
 async function mcpAudit(args) {
   const format = optionalArg(args, "--format") ?? (args.includes("--json") ? "json" : "text");
   if (!["text", "json", "markdown"].includes(format)) {
@@ -9567,21 +9651,29 @@ function formatProposeResult(capabilityName, result, storePath) {
 `;
 }
 async function mcpConfigure(args) {
-  const client = optionalArg(args, "--client");
-  if (!client) throw new Error("mcp configure requires --client generic-stdio|claude-desktop|cursor|vscode");
+  const client = normalizeMcpClientName(optionalArg(args, "--client"));
+  if (!client) throw new Error("mcp configure requires --client generic-stdio|claude|claude-desktop|cursor|vscode|openai-agents");
   const useAbsolutePaths = args.includes("--absolute-paths");
   const rawConfigPath = optionalArg(args, "--config") ?? "./synapsor.runner.json";
   const rawStorePath = optionalArg(args, "--store") ?? "./.synapsor/local.db";
   const configPath = useAbsolutePaths ? path3.resolve(rawConfigPath) : rawConfigPath;
   const storePath = useAbsolutePaths ? path3.resolve(rawStorePath) : rawStorePath;
+  const transport = mcpClientConfigTransport(args, client);
+  const aliasMode = mcpClientConfigAliasMode(args, client);
+  const host = optionalArg(args, "--host") ?? "127.0.0.1";
+  const port = Number(optionalArg(args, "--port") ?? "8766");
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    throw new Error("--port must be an integer from 1 to 65535");
+  }
+  const authTokenEnv = optionalArg(args, "--auth-token-env") ?? "SYNAPSOR_RUNNER_HTTP_TOKEN";
   if (!await fileExists(rawConfigPath)) {
     process2.stderr.write(`Warning: config path does not exist yet: ${rawConfigPath}
 `);
   }
-  if (!path3.isAbsolute(configPath) || !path3.isAbsolute(storePath)) {
+  if (transport === "stdio" && (!path3.isAbsolute(configPath) || !path3.isAbsolute(storePath))) {
     process2.stderr.write("Warning: relative paths are resolved by the MCP client working directory. Use --absolute-paths if the client runs from another directory.\n");
   }
-  const snippet = mcpClientSnippet(client, configPath, storePath);
+  const snippet = mcpClientSnippet(client, configPath, storePath, { transport, aliasMode, host, port, authTokenEnv });
   if (args.includes("--write")) {
     const destination = optionalArg(args, "--destination");
     if (!destination) throw new Error("mcp configure --write requires --destination <path>");
@@ -9599,18 +9691,99 @@ async function mcpConfigure(args) {
 async function mcpConfig(args) {
   const [client, ...rest] = args;
   if (!client || client.startsWith("--")) return mcpConfigure(["--client", "claude-desktop", ...args]);
-  return mcpConfigure(["--client", client, ...rest]);
+  return mcpConfigure(["--client", normalizeMcpClientName(client) ?? client, ...rest]);
+}
+function normalizeMcpClientName(client) {
+  if (client === "claude") return "claude-desktop";
+  return client;
+}
+function mcpClientConfigTransport(args, client) {
+  const requested = optionalArg(args, "--transport") ?? (client === "openai-agents" ? "streamable-http" : "stdio");
+  if (requested === "stdio" || requested === "streamable-http") return requested;
+  if (requested === "http" || requested === "json-rpc-http" || requested === "jsonrpc-http") {
+    throw new Error("mcp config uses stdio or streamable-http. The lightweight JSON-RPC HTTP bridge is not a standard MCP client transport.");
+  }
+  throw new Error("--transport must be stdio or streamable-http");
+}
+function mcpClientConfigAliasMode(args, client) {
+  const requested = optionalArg(args, "--alias-mode");
+  const aliasMode = requested ?? (args.includes("--openai-tool-aliases") ? "openai" : client === "openai-agents" ? "openai" : "canonical");
+  if (aliasMode === "canonical" || aliasMode === "openai" || aliasMode === "both") return aliasMode;
+  throw new Error("--alias-mode must be canonical, openai, or both");
 }
-function mcpClientSnippet(client, configPath, storePath) {
+function serveArgsForClient(configPath, storePath, options) {
+  const args = options.transport === "streamable-http" ? [
+    "mcp",
+    "serve-streamable-http",
+    "--config",
+    configPath,
+    "--store",
+    storePath,
+    "--host",
+    options.host,
+    "--port",
+    String(options.port),
+    "--auth-token-env",
+    options.authTokenEnv
+  ] : ["mcp", "serve", "--config", configPath, "--store", storePath];
+  if (options.aliasMode !== "canonical") args.push("--alias-mode", options.aliasMode);
+  return args;
+}
+function mcpClientSnippet(client, configPath, storePath, options) {
   const command = cliCommandName();
-  const args = ["mcp", "serve", "--config", configPath, "--store", storePath];
+  const args = serveArgsForClient(configPath, storePath, options);
   if (client === "generic" || client === "generic-stdio") return { command, args };
   if (client === "claude-desktop" || client === "cursor") {
+    if (options.transport !== "stdio") throw new Error(`${client} config output currently supports stdio. Use --transport stdio.`);
     return { mcpServers: { synapsor: { command, args } } };
   }
   if (client === "vscode") {
+    if (options.transport !== "stdio") throw new Error("vscode config output currently supports stdio. Use --transport stdio.");
     return { servers: { synapsor: { type: "stdio", command, args } } };
   }
+  if (client === "openai-agents") {
+    if (options.transport !== "streamable-http") throw new Error("openai-agents config output uses Streamable HTTP. Use --transport streamable-http.");
+    const url = `http://${options.host}:${options.port}/mcp`;
+    return {
+      transport: "streamable-http",
+      start_server: {
+        command,
+        args,
+        env: {
+          [options.authTokenEnv]: "<set-a-random-local-token>"
+        }
+      },
+      openai_agents_sdk: {
+        package: "openai-agents",
+        url,
+        headers_from_env: {
+          Authorization: `Bearer $${options.authTokenEnv}`
+        },
+        python: [
+          "import os",
+          "from agents.mcp import MCPServerStreamableHttp",
+          "",
+          "synapsor_mcp = MCPServerStreamableHttp(",
+          `    params={`,
+          `        "url": "${url}",`,
+          `        "headers": {"Authorization": f"Bearer {os.environ['${options.authTokenEnv}']}"},`,
+          "    }",
+          ")"
+        ].join("\n")
+      },
+      tool_names: {
+        canonical: "billing.inspect_invoice",
+        model_visible_with_alias_mode_openai: "billing__inspect_invoice",
+        alias_mode: options.aliasMode
+      },
+      notes: [
+        "Start the local Streamable HTTP MCP server before creating the OpenAI Agents SDK server.",
+        "OpenAI-facing configs should use --alias-mode openai because OpenAI function names cannot contain dots.",
+        "Runner maps aliases back to canonical Synapsor capability names and includes the canonical name in MCP tool metadata.",
+        "This config contains no database URLs, write credentials, API keys, or bearer token values."
+      ]
+    };
+  }
   throw new Error(`unsupported MCP client: ${client}`);
 }
 async function mcpSmoke(args) {
@@ -9659,7 +9832,9 @@ async function toolsPreview(args) {
       ok: boundary.ok,
       config_path: boundary.configPath,
       store_path: boundary.storePath,
+      alias_mode: boundary.aliasMode,
       exposed_to_mcp: boundary.names,
+      alias_mappings: boundary.exposures,
       not_exposed_to_mcp: defaultBlockedToolSurface(),
       checks: boundary.checks
     }, null, 2)}
@@ -9672,6 +9847,7 @@ async function toolsPreview(args) {
 async function inspectMcpToolBoundary(args) {
   const configPath = optionalArg(args, "--config") ?? "./synapsor.runner.json";
   const storePath = optionalArg(args, "--store") ?? "./.synapsor/local.db";
+  const aliasMode = args.includes("--aliases") && !optionalArg(args, "--alias-mode") && !optionalArg(args, "--tool-name-style") ? "both" : toolNameStyleOption(args);
   if (!await fileExists(configPath)) {
     throw new Error(`MCP tool preview could not find ${configPath}.
 
@@ -9685,7 +9861,8 @@ Run ${cliCommandName()} onboard db --from-env DATABASE_URL, or pass --config <pa
   const runtime = createMcpRuntime(parsed, { storePath });
   try {
     const tools2 = runtime.listTools();
-    const names = tools2.map((tool) => tool.name);
+    const exposures = toolNameExposures(tools2.map((tool) => tool.name), aliasMode);
+    const names = exposures.map((item) => item.exposedName);
     const serialized = JSON.stringify(tools2);
     const checks = [
       { name: "semantic tools present", ok: names.length > 0, detail: names.join(", ") || "none" },
@@ -9696,7 +9873,7 @@ Run ${cliCommandName()} onboard db --from-env DATABASE_URL, or pass --config <pa
       { name: "write credentials absent", ok: !/(password|secret|bearer|private[_-]?key|token)/i.test(serialized), detail: "MCP tools do not include write credentials" }
     ];
     const ok = checks.every((check) => check.ok);
-    return { ok, configPath, storePath, names, checks };
+    return { ok, configPath, storePath, aliasMode, names, exposures, checks };
   } finally {
     runtime.close();
   }
@@ -9713,13 +9890,15 @@ function defaultBlockedToolSurface() {
   ];
 }
 function formatToolsPreview(input) {
+  const exposedLines = input.exposures.length > 0 ? input.exposures.map((item) => item.isAlias ? `  - ${item.exposedName} -> ${item.canonicalName}` : `  - ${item.exposedName}`) : ["  - (none)"];
   const lines = [
     `Synapsor tools preview: ${input.ok ? "ok" : "failed"}`,
     `Config: ${input.configPath}`,
     `Store: ${input.storePath}`,
+    `Alias mode: ${input.aliasMode}`,
     "",
     "Exposed to MCP:",
-    ...input.names.length > 0 ? input.names.map((name) => `  - ${name}`) : ["  - (none)"],
+    ...exposedLines,
     "",
     "Not exposed to MCP:",
     ...defaultBlockedToolSurface().map((name) => `  - ${name}`),
@@ -11397,7 +11576,7 @@ function databaseInputFromArgs(args) {
   if (inlineUrl && !isDatabaseUrl(inlineUrl)) {
     throw new Error("--from must be a postgres://, postgresql://, or mysql:// URL.");
   }
-  const fromEnv = optionalArg(args, "--from-env") ?? optionalArg(args, "--database-url-env");
+  const fromEnv = optionalArg(args, "--from-env") ?? optionalArg(args, "--url-env") ?? optionalArg(args, "--database-url-env");
   const configDatabaseUrlEnv = fromEnv ?? "SYNAPSOR_DATABASE_READ_URL";
   if (inlineUrl) {
     return {
@@ -11443,6 +11622,7 @@ function firstPositional(args) {
     "--format",
     "--from",
     "--from-env",
+    "--url-env",
     "--host",
     "--idempotency-key",
     "--input",
@@ -12371,7 +12551,7 @@ function starterCloudConfig() {
       base_url_env: "SYNAPSOR_CLOUD_BASE_URL",
       runner_token_env: "SYNAPSOR_RUNNER_TOKEN",
       runner_id: "synapsor_runner_local",
-      runner_version: "0.1.0-alpha.10",
+      runner_version: "0.1.0-alpha.11",
       project_id: "token_scope",
       adapter_id: "mcp.your_adapter",
       source_id: "src_replace_me",
@@ -12492,12 +12672,14 @@ so it is not confused with first-run onboarding.
 `,
     inspect: `Usage:
   ${cmd} inspect --from-env DATABASE_URL [--engine auto|postgres|mysql] [--schema public] [--json]
+  ${cmd} inspect --engine postgres --url-env DATABASE_URL
   ${cmd} inspect "<postgres-or-mysql-url>" [--engine auto|postgres|mysql] [--schema public] [--json]
 
 Inspect schema metadata without mutating the database or printing credentials.
 `,
     init: `Usage:
   ${cmd} init --wizard --from-env DATABASE_URL [--mode read_only|review|shadow] [--out synapsor.runner.json]
+  ${cmd} init --engine postgres --url-env DATABASE_URL --mode review --table public.invoices
   ${cmd} init --inspection-json schema.json --table invoices --mode review --patch-from-arg waiver_reason=reason
   ${cmd} init --inspection-json schema.json --table invoices --mode review --writeback http_handler --handler-url-env APP_WRITEBACK_URL
 
@@ -12506,9 +12688,11 @@ Review mode writeback choices: sql_update, http_handler, command_handler.
 `,
     mcp: `Usage:
   ${cmd} mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
+  ${cmd} mcp serve --transport streamable-http --config ./synapsor.runner.json --store ./.synapsor/local.db --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
   ${cmd} mcp serve-streamable-http --config ./synapsor.runner.json --store ./.synapsor/local.db --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
   ${cmd} mcp serve-http --config ./synapsor.runner.json --store ./.synapsor/local.db --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
   ${cmd} mcp config --absolute-paths --config ./synapsor.runner.json --store ./.synapsor/local.db
+  ${cmd} mcp client-config --client openai-agents --config ./synapsor.runner.json --store ./.synapsor/local.db
   ${cmd} mcp audit --example dangerous-db-mcp
   ${cmd} mcp audit ./tools-list.json
 
@@ -12516,19 +12700,24 @@ Use stdio for local MCP clients that launch the runner. Use Streamable HTTP for
 MCP clients see semantic tools. They do not receive raw SQL, write credentials, approval tools, or commit tools.
 `,
     "mcp serve": `Usage:
-  ${cmd} mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db [--read-only] [--local]
+  ${cmd} mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db [--transport stdio] [--read-only] [--local] [--alias-mode canonical|openai|both]
+  ${cmd} mcp serve --transport streamable-http --config ./synapsor.runner.json --store ./.synapsor/local.db --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
 
 Start the stdio MCP server for local MCP clients such as Claude Desktop, Cursor, or local agent tools. Startup logs stay off stdout so the MCP protocol remains clean.
+Use --alias-mode openai, or --openai-tool-aliases, for clients that reject dotted tool names. Use --alias-mode both to expose canonical and alias names.
 `,
     "mcp serve-streamable-http": `Usage:
   export SYNAPSOR_RUNNER_HTTP_TOKEN=...
-  ${cmd} mcp serve-streamable-http --config ./synapsor.runner.json --store ./.synapsor/local.db [--host 127.0.0.1] [--port 8766] [--auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN]
+  ${cmd} mcp serve-streamable-http --config ./synapsor.runner.json --store ./.synapsor/local.db [--host 127.0.0.1] [--port 8766] [--auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN] [--alias-mode canonical|openai|both]
 
 Start the spec-compatible MCP Streamable HTTP endpoint for clients and SDKs that support HTTP MCP.
 Bearer auth is required by default.
 
 Alpha scope:
   - Supports MCP initialize/session behavior through the official MCP Streamable HTTP transport.
+  - Use --alias-mode openai, or --openai-tool-aliases, for clients that reject dotted tool names.
+  - Use --alias-mode both to expose canonical names and aliases.
+  - OpenAI aliases expose names such as billing__inspect_invoice while preserving the canonical Synapsor name in _meta.
   - Use /mcp for the MCP endpoint and /healthz for service health.
   - Sessions are in-memory. Restarting the runner clears active HTTP MCP sessions.
 
@@ -12557,9 +12746,19 @@ Security:
   - Optional CORS: --cors-origin http://localhost:3000
 `,
     "mcp config": `Usage:
-  ${cmd} mcp config [claude-desktop|cursor|generic|vscode] [--absolute-paths] [--config ./synapsor.runner.json] [--store ./.synapsor/local.db]
+  ${cmd} mcp config [claude-desktop|cursor|generic|vscode|openai-agents] [--absolute-paths] [--config ./synapsor.runner.json] [--store ./.synapsor/local.db]
+  ${cmd} mcp client-config --client openai-agents [--transport streamable-http] [--port 8766] [--alias-mode openai] [--config ./synapsor.runner.json] [--store ./.synapsor/local.db]
 
 Print MCP client configuration that references the local runner command, not database URLs. Defaults to claude-desktop.
+OpenAI Agents SDK output uses Streamable HTTP and OpenAI-safe aliases by default.
+`,
+    "mcp client-config": `Usage:
+  ${cmd} mcp client-config --client claude-desktop [--absolute-paths] [--config ./synapsor.runner.json] [--store ./.synapsor/local.db]
+  ${cmd} mcp client-config --client cursor [--absolute-paths] [--config ./synapsor.runner.json] [--store ./.synapsor/local.db]
+  ${cmd} mcp client-config --client openai-agents [--transport streamable-http] [--port 8766] [--alias-mode openai] [--config ./synapsor.runner.json] [--store ./.synapsor/local.db]
+
+Print MCP client configuration that references the local runner command, not database URLs.
+OpenAI Agents SDK output uses Streamable HTTP and OpenAI-safe aliases by default.
 `,
     smoke: `Usage:
   ${cmd} smoke call [capability-name] [--sample] [--config ./synapsor.runner.json] [--store ./.synapsor/local.db]