@smithers-orchestrator/agents 0.21.0 → 0.23.0

package/src/index.js

@@ -13,22 +13,39 @@
  * @template [TOOLS=import("ai").ToolSet]
  * @typedef {import("./OpenAIAgentOptions.ts").OpenAIAgentOptions<CALL_OPTIONS, TOOLS>} OpenAIAgentOptions
  */
+/**
+ * @template [CALL_OPTIONS=never]
+ * @template [TOOLS=import("ai").ToolSet]
+ * @typedef {import("./HermesAgentOptions.ts").HermesAgentOptions<CALL_OPTIONS, TOOLS>} HermesAgentOptions
+ */
 /** @typedef {import("./PiAgentOptions.ts").PiAgentOptions} PiAgentOptions */
 /** @typedef {import("./BaseCliAgent/PiExtensionUiRequest.ts").PiExtensionUiRequest} PiExtensionUiRequest */
 /** @typedef {import("./BaseCliAgent/PiExtensionUiResponse.ts").PiExtensionUiResponse} PiExtensionUiResponse */
 /** @typedef {import("./OpenCodeAgent.ts").OpenCodeAgentOptions} OpenCodeAgentOptions */
+/** @typedef {import("./VibeAgentOptions.ts").VibeAgentOptions} VibeAgentOptions */
 /** @typedef {import("./agent-contract/SmithersAgentContract.ts").SmithersAgentContract} SmithersAgentContract */
 /** @typedef {import("./agent-contract/SmithersAgentContractTool.ts").SmithersAgentContractTool} SmithersAgentContractTool */
 /** @typedef {import("./agent-contract/SmithersAgentToolCategory.ts").SmithersAgentToolCategory} SmithersAgentToolCategory */
 /** @typedef {import("./agent-contract/SmithersListedTool.ts").SmithersListedTool} SmithersListedTool */
 /** @typedef {import("./agent-contract/SmithersToolSurface.ts").SmithersToolSurface} SmithersToolSurface */
+/** @typedef {import("./cli-capabilities/CliAgentCapabilityAdapterId.ts").CliAgentCapabilityAdapterId} CliAgentCapabilityAdapterId */
+/** @typedef {import("./cli-capabilities/CliAgentCapabilityDoctorReport.ts").CliAgentCapabilityDoctorEntry} CliAgentCapabilityDoctorEntry */
+/** @typedef {import("./cli-capabilities/CliAgentCapabilityDoctorReport.ts").CliAgentCapabilityDoctorReport} CliAgentCapabilityDoctorReport */
+/** @typedef {import("./cli-capabilities/CliAgentCapabilityDoctorReport.ts").CliAgentCapabilityIssue} CliAgentCapabilityIssue */
+/** @typedef {import("./cli-capabilities/CliAgentCapabilityReportEntry.ts").CliAgentCapabilityReportEntry} CliAgentCapabilityReportEntry */
+/** @typedef {import("./cli-surface/CliAgentSurfaceTypes.ts").CliAgentSurfaceManifestEntry} CliAgentSurfaceManifestEntry */
+/** @typedef {import("./cli-surface/CliAgentSurfaceTypes.ts").CliAgentSurfaceOptionMapping} CliAgentSurfaceOptionMapping */
+/** @typedef {import("./cli-surface/CliAgentSurfaceTypes.ts").CliAgentSurfaceResumeContract} CliAgentSurfaceResumeContract */
+/** @typedef {import("./cli-surface/CliAgentSurfaceTypes.ts").CliAgentUnsupportedFlag} CliAgentUnsupportedFlag */
 // @smithers-type-exports-end
 
 export { BaseCliAgent } from "./BaseCliAgent/index.js";
 export { hashCapabilityRegistry } from "./capability-registry/index.js";
 export { AnthropicAgent } from "./AnthropicAgent.js";
 export { OpenAIAgent } from "./OpenAIAgent.js";
+export { HermesAgent } from "./HermesAgent.js";
 export { AmpAgent } from "./AmpAgent.js";
+export { createAmpCapabilityRegistry } from "./AmpAgent.js";
 export { AntigravityAgent, createAntigravityCapabilityRegistry } from "./AntigravityAgent.js";
 export { ClaudeCodeAgent } from "./ClaudeCodeAgent.js";
 export { CodexAgent } from "./CodexAgent.js";
@@ -36,7 +53,17 @@ export { GeminiAgent } from "./GeminiAgent.js";
 export { PiAgent } from "./PiAgent.js";
 export { KimiAgent } from "./KimiAgent.js";
 export { ForgeAgent } from "./ForgeAgent.js";
+export { createForgeCapabilityRegistry } from "./ForgeAgent.js";
 export { OpenCodeAgent } from "./OpenCodeAgent.js";
+export { VibeAgent, createVibeCapabilityRegistry } from "./VibeAgent.js";
+export {
+  getCliAgentCapabilityReport,
+  getCliAgentCapabilityDoctorReport,
+  formatCliAgentCapabilityDoctorReport,
+  CLI_AGENT_SURFACE_MANIFEST,
+  getCliAgentSurfaceManifestEntry,
+  listCliAgentSurfaceManifests,
+} from "./cli-capabilities/index.js";
 export { createSmithersAgentContract } from "./agent-contract/createSmithersAgentContract.js";
 export { renderSmithersAgentPromptGuidance } from "./agent-contract/renderSmithersAgentPromptGuidance.js";
 export { zodToOpenAISchema } from "./zodToOpenAISchema.js";

package/src/mcp/McpServerConfig.ts

@@ -0,0 +1,19 @@
+/**
+ * How to launch an MCP server over stdio. Swap `command`/`args` to point at any
+ * MCP server (the demo fixture, GitHub's `@modelcontextprotocol/server-github`,
+ * Linear's MCP server, etc.) and its tools become agent-callable.
+ */
+export type McpServerConfig = {
+  /** Executable to spawn, e.g. `"bun"`, `"npx"`, `"node"`. */
+  command: string;
+  /** Arguments passed to the executable. */
+  args?: string[];
+  /**
+   * Environment for the spawned process. When omitted, the MCP SDK passes a
+   * minimal safe environment. Include any secrets the server needs here
+   * (e.g. `GITHUB_PERSONAL_ACCESS_TOKEN`).
+   */
+  env?: Record<string, string>;
+  /** Working directory for the spawned process. */
+  cwd?: string;
+};

package/src/mcp/McpToolset.ts

@@ -0,0 +1,17 @@
+import type { Tool } from "ai";
+
+/**
+ * A live connection to an MCP server, with its tools projected as AI SDK tools.
+ *
+ * `tools` is shaped exactly like the record returned by `createOpenApiTools`, so it
+ * drops straight into an SDK agent's `tools`. The connection (and the spawned server
+ * process) stays open until `close()` is called.
+ */
+export type McpToolset = {
+  /** AI SDK tools keyed by (prefixed) MCP tool name. */
+  tools: Record<string, Tool>;
+  /** Names present in `tools`, after include/exclude/prefix are applied. */
+  toolNames: string[];
+  /** Disconnect the client and terminate the spawned server process. */
+  close: () => Promise<void>;
+};

package/src/mcp/createMcpToolset.js

@@ -0,0 +1,94 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { dynamicTool, jsonSchema } from "ai";
+
+/** @typedef {import("./McpServerConfig.ts").McpServerConfig} McpServerConfig */
+/** @typedef {import("./McpToolset.ts").McpToolset} McpToolset */
+
+/**
+ * Options for shaping the generated toolset. Mirrors the curation knobs on
+ * `createOpenApiTools` so MCP and OpenAPI integrations feel the same.
+ *
+ * @typedef {object} McpToolsetOptions
+ * @property {string[]} [include] Only expose these MCP tool names.
+ * @property {string[]} [exclude] Drop these MCP tool names.
+ * @property {string} [namePrefix] Prefix applied to every tool name (e.g. `"github_"`).
+ * @property {string} [clientName] Identifies this client to the server.
+ * @property {string} [clientVersion] Client version reported to the server.
+ */
+
+/**
+ * Connect to an MCP server and expose its tools as AI SDK tools an agent can call.
+ *
+ * This is the inbound half of MCP-as-integration: declare a server, get back a
+ * `Record<string, Tool>` to hand to an SDK agent's `tools`. Each generated tool
+ * proxies to the server via `tools/call` on demand, so the agent discovers and
+ * invokes them mid reasoning loop. The returned `close()` MUST be called to
+ * disconnect and terminate the spawned server process.
+ *
+ * @param {McpServerConfig} config
+ * @param {McpToolsetOptions} [options]
+ * @returns {Promise<McpToolset>}
+ */
+export async function createMcpToolset(config, options = {}) {
+  const transport = new StdioClientTransport({
+    command: config.command,
+    args: config.args ?? [],
+    ...(config.env ? { env: config.env } : {}),
+    ...(config.cwd ? { cwd: config.cwd } : {}),
+    stderr: "pipe",
+  });
+  const client = new Client({
+    name: options.clientName ?? "smithers-mcp-toolset",
+    version: options.clientVersion ?? "0.0.0",
+  });
+  await client.connect(transport);
+
+  const prefix = options.namePrefix ?? "";
+  const listed = await client.listTools();
+  /** @type {Record<string, import("ai").Tool>} */
+  const tools = {};
+  for (const mcpTool of listed.tools) {
+    if (options.include && !options.include.includes(mcpTool.name)) continue;
+    if (options.exclude && options.exclude.includes(mcpTool.name)) continue;
+    tools[`${prefix}${mcpTool.name}`] = dynamicTool({
+      description: mcpTool.description ?? mcpTool.name,
+      inputSchema: jsonSchema(/** @type {any} */ (mcpTool.inputSchema ?? { type: "object", properties: {} })),
+      execute: async (input) => callMcpTool(client, mcpTool.name, input),
+    });
+  }
+
+  return {
+    tools,
+    toolNames: Object.keys(tools),
+    close: () => client.close(),
+  };
+}
+
+/**
+ * Invoke one MCP tool and reduce its result to a value the model can read:
+ * structured content when the server returns it, otherwise the joined text.
+ *
+ * @param {Client} client
+ * @param {string} name
+ * @param {unknown} input
+ * @returns {Promise<unknown>}
+ */
+async function callMcpTool(client, name, input) {
+  const result = await client.callTool({
+    name,
+    arguments: /** @type {Record<string, unknown>} */ (input ?? {}),
+  });
+  const parts = Array.isArray(result.content) ? result.content : [];
+  let text = "";
+  for (const part of parts) {
+    const item = /** @type {{ type?: string; text?: string }} */ (part);
+    if (item.type === "text" && typeof item.text === "string") {
+      text += text ? `\n${item.text}` : item.text;
+    }
+  }
+  if (result.isError) {
+    return { error: true, message: text || `MCP tool "${name}" failed`, status: "failed" };
+  }
+  return result.structuredContent ?? text;
+}

package/src/sanitizeForOpenAI.js

@@ -4,13 +4,13 @@
  * OpenAI's `response_format` imposes constraints beyond standard JSON Schema:
  *
  * 1. Every object node **must** include `"type": "object"`.
- * 2. `additionalProperties` must be a boolean or a valid sub-schema with a
- *    `type` key -- bare `{}` is rejected.
- * 3. `additionalProperties: true` is accepted but tells the model it can
- *    return extra keys -- set to `false` if you want strict conformance.
+ * 2. Structured output object nodes must set `additionalProperties: false`.
+ * 3. When `additionalProperties: false`, every key in `properties` must also
+ *    appear in `required` (strict mode treats all listed properties as
+ *    required; truly-optional fields should be modeled as nullable).
  *
- * Zod v4's `toJSONSchema()` can violate (1) when `z.looseObject()` is used:
- * it emits `{ additionalProperties: true }` without `"type": "object"`.
+ * Zod v4's `toJSONSchema()` can violate these rules when loose/passthrough
+ * objects are used. Codex rejects those schemas unless they are strict.
  *
  * This function fixes these issues in-place so any agent (Codex, future
  * OpenAI-backed agents, etc.) can safely use a JSON Schema for OpenAI.
@@ -19,20 +19,23 @@ export function sanitizeForOpenAI(node) {
     if (node == null || typeof node !== "object")
         return;
     const obj = node;
-    // Rule 1 & 2: If a node has `additionalProperties`, it must also
-    // have `"type": "object"`.  Zod's toJSONSchema omits `type` on
-    // passthrough objects, which OpenAI rejects.
+    // Rule 1: If a node has `additionalProperties`, it must also have
+    // `"type": "object"`. Zod can omit `type` on passthrough objects.
     if ("additionalProperties" in obj && !("type" in obj)) {
         obj.type = "object";
     }
-    // Rule 2b: If `additionalProperties` is an empty object `{}`,
-    // OpenAI rejects it because it lacks a `type` key.  Coerce to `true`
-    // which is semantically equivalent and accepted by OpenAI.
-    if (typeof obj.additionalProperties === "object" &&
-        obj.additionalProperties !== null &&
-        !Array.isArray(obj.additionalProperties) &&
-        Object.keys(obj.additionalProperties).length === 0) {
-        obj.additionalProperties = true;
+    // Rule 2: Codex/OpenAI structured outputs require strict object schemas.
+    if (obj.type === "object" && obj.additionalProperties !== false) {
+        obj.additionalProperties = false;
+    }
+    // Rule 3: With `additionalProperties: false`, OpenAI strict mode requires
+    // every key in `properties` to also appear in `required`. Zod omits
+    // optional fields from `required`, which strict mode rejects. List all
+    // property keys (truly-optional fields should be modeled as nullable).
+    if (obj.additionalProperties === false &&
+        obj.properties != null &&
+        typeof obj.properties === "object") {
+        obj.required = Object.keys(obj.properties);
     }
     // Recurse into all sub-schemas
     for (const value of Object.values(obj)) {