torus-ai 0.2.1 → 0.4.0

package/README.md

@@ -144,6 +144,82 @@ A weekly GitHub Action ([model-watch.yml](./.github/workflows/model-watch.yml))
 pulls NVIDIA's live `/v1/models`, flags new free endpoints as candidates, and opens
 a PR for human review against the policy. Run it locally with `npm run model-watch`.
 
+## Connecting to MCP servers (Torus is an MCP host)
+
+Torus speaks two flavors of [MCP](https://modelcontextprotocol.io):
+
+- **In-process** — `tool()` + `createSdkMcpServer()` define tools that run in your
+  process (the toolkit, the catalog/billing servers).
+- **External** — connect to the wider MCP ecosystem (GitHub, Postgres, Slack, …)
+  over **stdio** (a local subprocess) or **HTTP**. Their tools are discovered and
+  registered under the same `mcp__<server>__<tool>` namespace, so they work in the
+  loop, the cascade, and packs, gated by the same permission allowlist.
+
+```ts
+import { query, connectMcpServers } from "torus-ai";
+
+const { servers, close } = await connectMcpServers({
+  github: { command: "npx", args: ["-y", "@modelcontextprotocol/server-github"],
+            env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN! } }, // stdio
+  docs:   { type: "http", url: "https://example.com/mcp" },     // remote
+});
+
+for await (const ev of query("List my 3 newest GitHub issues", {
+  mcpServers: servers,
+  permissions: { allowedTools: ["mcp__github__*"] }, // allowlist the external tools
+})) { /* ... */ }
+
+await close(); // tear down the subprocess / connection
+```
+
+Needs the optional `@modelcontextprotocol/sdk` package (`npm i @modelcontextprotocol/sdk`).
+
+## Specializing for a product (packs)
+
+Don't fork the SDK per product — load a **pack**. A pack is an adapter that turns
+the generic engine into a vertical specialist (a bridal consultant, a mortgage
+advisor, a support agent): persona + sales playbook + policy + domain tools +
+catalog grounding + guardrails.
+
+```ts
+import { createSpecializedAgent, createCatalogServer, createInvoiceServer,
+         createHandoffServer } from "torus-ai";
+
+const agent = createSpecializedAgent({
+  name: "bridal",
+  persona: "You are a warm bridal consultant for Aurora Bridal.",
+  playbook: "discover needs → recommend → handle objections → close → settle → confirm",
+  knowledge: { catalog: dresses, faqs: "Alterations take 3 weeks. ..." }, // → search_catalog
+  tools: [createInvoiceServer(), createHandoffServer()],
+  guardrails: {
+    policy: "Never invent a price or availability. Max 10% discount. Escalate over $5,000.",
+    confirm: ["mcp__billing__create_invoice"], // money step needs a yes
+  },
+}, {
+  onConfirm: async (tool, input) => askHuman(tool, input), // your confirmation UI
+});
+
+for await (const ev of agent.query("Anything under $2k for an August wedding?")) { /* ... */ }
+```
+
+What the pack gives you, mapped to the engine:
+
+| Pack part | Effect |
+|---|---|
+| `persona` + `playbook` + `policy` | assembled into the system prompt |
+| `knowledge.catalog` | auto-wired `search_catalog` tool + a "never guess prices" instruction |
+| `tools` | your domain actions (compose the [toolkit](./src/packkit.ts): catalog, lead memory, invoice, handoff) |
+| `guardrails.allowedTools` / `confirm` / `canUseTool` | the safety gate — irreversible steps (billing) pause for confirmation |
+| `model` | defaults to the free-first cascade |
+
+Edit content as files (`persona.md`, `playbook.md`, `policy.md`, `catalog.json`,
+`faqs.md`) and `loadPack("packs/bridal", { tools })` assembles the pack — so a shop
+owner edits the catalog and tone while devs write the few action tools.
+
+The reusable toolkit ([`src/packkit.ts`](./src/packkit.ts)): `createCatalogServer`,
+`createLeadMemoryServer`, `createInvoiceServer` (generic settle stub),
+`createHandoffServer`.
+
 ## The stage contract (Layer 2)
 
 Each `stages/NN_verb/CONTEXT.md` is both the agent's instructions and human docs:

package/dist/index.d.ts

@@ -395,6 +395,133 @@ interface DefaultProviderOptions {
  */
 declare function createDefaultProvider(opts?: DefaultProviderOptions): CascadeProvider;
 
+type CatalogItem = Record<string, unknown> & {
+    id?: string;
+    name?: string;
+    price?: number;
+    tags?: string[];
+    available?: boolean;
+};
+/** A `search_catalog` tool over an in-memory product list (text + price + tags). */
+declare function createCatalogServer(items: CatalogItem[], opts?: {
+    serverName?: string;
+}): SdkMcpServer;
+/** `get_lead` / `update_lead` over an in-memory customer profile (the funnel state). */
+declare function createLeadMemoryServer(initial?: Record<string, unknown>): SdkMcpServer & {
+    lead: Record<string, unknown>;
+};
+interface Invoice {
+    id: string;
+    amount: number;
+    currency: string;
+    items?: unknown;
+    customer?: unknown;
+    status: "pending";
+}
+/**
+ * A generic `create_invoice` settle tool: records an order + amount as pending
+ * and returns an invoice id. Provider-agnostic — wire your processor via
+ * `onCreate` (e.g. create a real payment link, then confirm via webhook).
+ */
+declare function createInvoiceServer(opts?: {
+    onCreate?: (inv: Invoice) => void;
+}): SdkMcpServer & {
+    invoices: Invoice[];
+};
+/** A `handoff_human` escalation tool. Wire `onHandoff` to notify a real agent. */
+declare function createHandoffServer(opts?: {
+    onHandoff?: (info: {
+        reason: string;
+        summary: string;
+    }) => void;
+}): SdkMcpServer;
+
+interface PackKnowledge {
+    /** Product catalog — auto-wired into a `search_catalog` tool for grounding. */
+    catalog?: CatalogItem[];
+    /** Short reference text (policies, FAQs) appended to the system prompt. */
+    faqs?: string;
+}
+interface PackGuardrails {
+    /** Allowlist of tool names the agent may call (namespaced, wildcards ok). */
+    allowedTools?: string[];
+    /** Tools that require explicit confirmation before running (namespaced names). */
+    confirm?: string[];
+    /** Extra custom gate, evaluated after allow/confirm. */
+    canUseTool?: CanUseTool;
+    /** Rules text (discount authority, no-overpromise, escalation) added to the prompt. */
+    policy?: string;
+}
+interface AgentPack {
+    name: string;
+    persona: string;
+    playbook?: string;
+    tools?: SdkMcpServer[];
+    knowledge?: PackKnowledge;
+    guardrails?: PackGuardrails;
+    model?: ModelProvider;
+}
+interface SpecializeOptions {
+    provider?: ModelProvider;
+    /** Called when a `confirm` tool wants to run; return true to allow. */
+    onConfirm?: (toolName: string, input: Record<string, unknown>) => boolean | Promise<boolean>;
+    /** Allow built-in file tools (read/write/list). Off by default for packs. */
+    includeBuiltins?: boolean;
+    maxTurns?: number;
+}
+interface SpecializedAgent {
+    pack: AgentPack;
+    system: string;
+    servers: SdkMcpServer[];
+    query(prompt: string | ContentBlock[], extra?: {
+        maxTurns?: number;
+    }): AsyncGenerator<AgentEvent>;
+}
+/** Build a ready-to-run specialized agent from a pack. */
+declare function createSpecializedAgent(pack: AgentPack, opts?: SpecializeOptions): SpecializedAgent;
+/**
+ * Load a pack's content from a folder (so non-devs can edit it):
+ *   persona.md · playbook.md · policy.md · catalog.json · faqs.md
+ * Code tools (quote/reserve/invoice/...) are passed via `opts.tools`.
+ */
+declare function loadPack(dir: string, opts?: {
+    tools?: SdkMcpServer[];
+}): Promise<AgentPack>;
+
+type McpServerConfig = {
+    type?: "stdio";
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+} | {
+    type: "http";
+    url: string;
+    headers?: Record<string, string>;
+};
+interface McpConnection {
+    /** Namespaced server — its tools become mcp__<name>__<tool>. */
+    server: SdkMcpServer;
+    /** Tear down the MCP client + transport. */
+    close(): Promise<void>;
+}
+/** Connect to one external MCP server and expose its tools as an SdkMcpServer. */
+declare function connectMcpServer(name: string, config: McpServerConfig): Promise<McpConnection>;
+/**
+ * Connect to several external MCP servers at once.
+ *
+ *   const { servers, close } = await connectMcpServers({
+ *     github: { command: "npx", args: ["-y", "@modelcontextprotocol/server-github"], env: { GITHUB_TOKEN } },
+ *     docs:   { type: "http", url: "https://example.com/mcp" },
+ *   });
+ *   for await (const ev of query("...", { mcpServers: servers,
+ *                                          permissions: { allowedTools: ["mcp__github__*"] } })) { ... }
+ *   await close();
+ */
+declare function connectMcpServers(configs: Record<string, McpServerConfig>): Promise<{
+    servers: SdkMcpServer[];
+    close(): Promise<void>;
+}>;
+
 declare const CHEAP_MODEL = "claude-haiku-4-5";
 declare const EXPENSIVE_MODEL = "claude-sonnet-4-6";
 declare const GEMINI_CHEAP_MODEL = "gemini-2.5-flash-lite";
@@ -457,4 +584,4 @@ interface QueryOptions {
  */
 declare function query(prompt: string | ContentBlock[], options?: QueryOptions): AsyncGenerator<AgentEvent>;
 
-export { type AgentEvent, type AnthropicOptions, AnthropicProvider, CHEAP_MODEL, type CanUseTool, type CascadeOptions, CascadeProvider, type CascadeStep, type Complexity, type ContentBlock, DEEPSEEK_V4_FLASH, DEEPSEEK_V4_PRO, type DefaultProviderOptions, EXPENSIVE_MODEL, GEMINI_CHEAP_MODEL, GEMINI_EXPENSIVE_MODEL, type GeminiOptions, GeminiProvider, type JSONSchema, KIMI_K2_6, LLAMA_VISION, type LoadedContext, type LoopOptions, type LoopResult, type MediaBlock, type Message, type MockOptions, MockProvider, type ModelProvider, type ModelRequest, type ModelResponse, NVIDIA_BASE_URL, type NvidiaOptions, NvidiaProvider, type PermissionConfig, type PermissionDecision, PermissionEngine, type PipelineOptions, type QueryOptions, type RegisteredTool, type Role, type RouterOptions, type RoutingStats, type SdkMcpServer, type StageContract, type StageInput, type StopReason, type TextBlock, type ToolContext, type ToolDefinition, ToolRegistry, type ToolResultBlock, type ToolResultPayload, type ToolSchema, type ToolUseBlock, builtinTools, classifyComplexity, classifyComplexityGemini, createDefaultProvider, createSdkMcpServer, fastHeuristic, getRoutingStats, hasMedia, judgeComplexity, judgeComplexityGemini, latestUserText, listDirTool, loadStageContext, loadStages, matchesAllow, parseContract, query, readFileTool, runLoop, runPipeline, selectGeminiModel, selectModel, tool, writeFileTool };
+export { type AgentEvent, type AgentPack, type AnthropicOptions, AnthropicProvider, CHEAP_MODEL, type CanUseTool, type CascadeOptions, CascadeProvider, type CascadeStep, type CatalogItem, type Complexity, type ContentBlock, DEEPSEEK_V4_FLASH, DEEPSEEK_V4_PRO, type DefaultProviderOptions, EXPENSIVE_MODEL, GEMINI_CHEAP_MODEL, GEMINI_EXPENSIVE_MODEL, type GeminiOptions, GeminiProvider, type Invoice, type JSONSchema, KIMI_K2_6, LLAMA_VISION, type LoadedContext, type LoopOptions, type LoopResult, type McpConnection, type McpServerConfig, type MediaBlock, type Message, type MockOptions, MockProvider, type ModelProvider, type ModelRequest, type ModelResponse, NVIDIA_BASE_URL, type NvidiaOptions, NvidiaProvider, type PackGuardrails, type PackKnowledge, type PermissionConfig, type PermissionDecision, PermissionEngine, type PipelineOptions, type QueryOptions, type RegisteredTool, type Role, type RouterOptions, type RoutingStats, type SdkMcpServer, type SpecializeOptions, type SpecializedAgent, type StageContract, type StageInput, type StopReason, type TextBlock, type ToolContext, type ToolDefinition, ToolRegistry, type ToolResultBlock, type ToolResultPayload, type ToolSchema, type ToolUseBlock, builtinTools, classifyComplexity, classifyComplexityGemini, connectMcpServer, connectMcpServers, createCatalogServer, createDefaultProvider, createHandoffServer, createInvoiceServer, createLeadMemoryServer, createSdkMcpServer, createSpecializedAgent, fastHeuristic, getRoutingStats, hasMedia, judgeComplexity, judgeComplexityGemini, latestUserText, listDirTool, loadPack, loadStageContext, loadStages, matchesAllow, parseContract, query, readFileTool, runLoop, runPipeline, selectGeminiModel, selectModel, tool, writeFileTool };

package/dist/index.js

@@ -879,6 +879,253 @@ function createDefaultProvider(opts = {}) {
   });
 }
 
+// src/pack.ts
+import { existsSync as existsSync2 } from "fs";
+import { readFile as readFile4 } from "fs/promises";
+import { join as join4 } from "path";
+
+// src/packkit.ts
+function createCatalogServer(items, opts = {}) {
+  const search = tool(
+    "search_catalog",
+    "Search the product catalog by text, max price, and tags. Returns matching items with prices and availability. Use this for every product/price/availability question \u2014 never guess.",
+    {
+      type: "object",
+      properties: {
+        query: { type: "string" },
+        maxPrice: { type: "number" },
+        tags: { type: "array", items: { type: "string" } },
+        limit: { type: "number" }
+      }
+    },
+    (input) => {
+      let res = items.filter((it) => it.available !== false);
+      if (input.query) {
+        const words = input.query.toLowerCase().split(/\s+/).filter(Boolean);
+        res = res.filter((it) => {
+          const hay = JSON.stringify(it).toLowerCase();
+          return words.every((w) => hay.includes(w));
+        });
+      }
+      if (typeof input.maxPrice === "number") {
+        res = res.filter((it) => typeof it.price !== "number" || it.price <= input.maxPrice);
+      }
+      if (Array.isArray(input.tags) && input.tags.length) {
+        res = res.filter((it) => Array.isArray(it.tags) && input.tags.some((t) => it.tags.includes(t)));
+      }
+      const out = res.slice(0, input.limit ?? 5);
+      return { content: out.length ? JSON.stringify(out, null, 2) : "No matching items." };
+    }
+  );
+  return createSdkMcpServer({ name: opts.serverName ?? "catalog", tools: [search] });
+}
+function createLeadMemoryServer(initial = {}) {
+  const lead = { ...initial };
+  const get = tool(
+    "get_lead",
+    "Get what we know about the current customer (name, date, budget, stage, items seen).",
+    { type: "object", properties: {} },
+    () => ({ content: JSON.stringify(lead, null, 2) })
+  );
+  const update = tool(
+    "update_lead",
+    "Merge fields into the customer profile, e.g. { budget: 2000, stage: 'recommend' }.",
+    { type: "object", properties: { fields: { type: "object" } }, required: ["fields"] },
+    (input) => {
+      Object.assign(lead, input.fields ?? {});
+      return { content: `updated: ${Object.keys(input.fields ?? {}).join(", ") || "(none)"}` };
+    }
+  );
+  return Object.assign(createSdkMcpServer({ name: "lead", tools: [get, update] }), { lead });
+}
+function createInvoiceServer(opts = {}) {
+  const invoices = [];
+  let n = 0;
+  const create = tool(
+    "create_invoice",
+    "Record an order and amount as a pending invoice to settle, returning an invoice id. Call this only after the customer has agreed to buy.",
+    {
+      type: "object",
+      properties: {
+        amount: { type: "number" },
+        currency: { type: "string" },
+        items: {},
+        customer: {}
+      },
+      required: ["amount"]
+    },
+    (input) => {
+      const inv = {
+        id: `inv_${++n}`,
+        amount: input.amount,
+        currency: input.currency ?? "USD",
+        items: input.items,
+        customer: input.customer,
+        status: "pending"
+      };
+      invoices.push(inv);
+      opts.onCreate?.(inv);
+      return {
+        content: JSON.stringify({ invoiceId: inv.id, status: inv.status, amount: inv.amount, currency: inv.currency })
+      };
+    }
+  );
+  return Object.assign(createSdkMcpServer({ name: "billing", tools: [create] }), { invoices });
+}
+function createHandoffServer(opts = {}) {
+  const handoff = tool(
+    "handoff_human",
+    "Escalate to a human agent with a reason and a short summary of the conversation so far. Use when you're stuck, the request is high-value, or the customer asks for a person.",
+    {
+      type: "object",
+      properties: { reason: { type: "string" }, summary: { type: "string" } },
+      required: ["reason"]
+    },
+    (input) => {
+      opts.onHandoff?.({ reason: input.reason, summary: input.summary ?? "" });
+      return { content: "Escalated to a human; they will take over shortly." };
+    }
+  );
+  return createSdkMcpServer({ name: "support", tools: [handoff] });
+}
+
+// src/pack.ts
+function createSpecializedAgent(pack, opts = {}) {
+  const servers = [...pack.tools ?? []];
+  if (pack.knowledge?.catalog?.length) servers.unshift(createCatalogServer(pack.knowledge.catalog));
+  const parts = [pack.persona.trim()];
+  if (pack.playbook) parts.push(`## Playbook
+${pack.playbook.trim()}`);
+  if (pack.guardrails?.policy) parts.push(`## Policy
+${pack.guardrails.policy.trim()}`);
+  if (servers.some((s) => s.tools.some((t) => t.name === "search_catalog"))) {
+    parts.push(
+      "Use the `search_catalog` tool for every product, price, or availability question. Never invent a price or claim availability you did not look up."
+    );
+  }
+  if (pack.knowledge?.faqs) parts.push(`## Reference
+${pack.knowledge.faqs.trim()}`);
+  const system = parts.join("\n\n");
+  const confirmTools = pack.guardrails?.confirm ?? [];
+  const allow = pack.guardrails?.allowedTools;
+  const base = pack.guardrails?.canUseTool;
+  const canUseTool = async (name, input) => {
+    if (confirmTools.includes(name)) {
+      const ok = opts.onConfirm ? await opts.onConfirm(name, input) : false;
+      if (!ok) return { behavior: "deny", message: `${name} requires confirmation and it was not granted.` };
+    }
+    if (allow && !matchesAllow(name, allow)) {
+      return { behavior: "deny", message: `${name} is not allowed by this pack's guardrails.` };
+    }
+    return base ? base(name, input) : { behavior: "allow" };
+  };
+  const provider = opts.provider ?? pack.model ?? createDefaultProvider();
+  const includeBuiltins = opts.includeBuiltins ?? false;
+  return {
+    pack,
+    system,
+    servers,
+    async *query(prompt, extra) {
+      const registry = new ToolRegistry();
+      if (includeBuiltins) registry.addBuiltins(builtinTools);
+      for (const s of servers) registry.addServer(s);
+      const content = typeof prompt === "string" ? [{ type: "text", text: prompt }] : prompt;
+      const messages = [{ role: "user", content }];
+      const result = yield* runLoop({
+        provider,
+        registry,
+        permissions: new PermissionEngine({ canUseTool }),
+        system,
+        messages,
+        toolContext: { workspaceDir: process.cwd() },
+        maxTurns: extra?.maxTurns ?? opts.maxTurns
+      });
+      yield { type: "result", finalText: result.finalText, turns: result.turns };
+    }
+  };
+}
+async function loadPack(dir, opts = {}) {
+  const read = async (f) => {
+    const p = join4(dir, f);
+    return existsSync2(p) ? await readFile4(p, "utf8") : void 0;
+  };
+  const catalogRaw = await read("catalog.json");
+  const policy = await read("policy.md");
+  return {
+    name: dir.split(/[\\/]/).filter(Boolean).pop() ?? "pack",
+    persona: await read("persona.md") ?? "",
+    playbook: await read("playbook.md"),
+    knowledge: {
+      catalog: catalogRaw ? JSON.parse(catalogRaw) : void 0,
+      faqs: await read("faqs.md")
+    },
+    guardrails: policy ? { policy } : void 0,
+    tools: opts.tools
+  };
+}
+
+// src/mcp-client.ts
+async function connect(config) {
+  const clientMod = await import("@modelcontextprotocol/sdk/client/index.js").catch(() => {
+    throw new Error("MCP client needs @modelcontextprotocol/sdk: run `npm i @modelcontextprotocol/sdk`.");
+  });
+  const Client = clientMod.Client;
+  let transport;
+  if (config.type === "http") {
+    const mod = await import("@modelcontextprotocol/sdk/client/streamableHttp.js");
+    transport = new mod.StreamableHTTPClientTransport(
+      new URL(config.url),
+      config.headers ? { requestInit: { headers: config.headers } } : void 0
+    );
+  } else {
+    const mod = await import("@modelcontextprotocol/sdk/client/stdio.js");
+    transport = new mod.StdioClientTransport({
+      command: config.command,
+      args: config.args ?? [],
+      env: { ...process.env, ...config.env ?? {} }
+    });
+  }
+  const client = new Client({ name: "torus", version: "0.4.0" }, { capabilities: {} });
+  await client.connect(transport);
+  return client;
+}
+async function connectMcpServer(name, config) {
+  const client = await connect(config);
+  const listed = await client.listTools();
+  const tools = (listed.tools ?? []).map(
+    (t) => tool(
+      t.name,
+      t.description ?? "",
+      t.inputSchema ?? { type: "object", properties: {} },
+      async (input) => {
+        const res = await client.callTool({ name: t.name, arguments: input ?? {} });
+        const text = (res.content ?? []).filter((c) => c?.type === "text").map((c) => c.text).join("\n") || JSON.stringify(res.content ?? res);
+        return { content: text, isError: !!res.isError };
+      }
+    )
+  );
+  return {
+    server: createSdkMcpServer({ name, version: "1.0.0", tools }),
+    close: async () => {
+      try {
+        await client.close();
+      } catch {
+      }
+    }
+  };
+}
+async function connectMcpServers(configs) {
+  const conns = await Promise.all(
+    Object.entries(configs).map(([name, cfg]) => connectMcpServer(name, cfg))
+  );
+  return {
+    servers: conns.map((c) => c.server),
+    close: async () => {
+      await Promise.all(conns.map((c) => c.close()));
+    }
+  };
+}
+
 // src/index.ts
 async function* query(prompt, options = {}) {
   const registry = new ToolRegistry();
@@ -917,8 +1164,15 @@ export {
   builtinTools,
   classifyComplexity,
   classifyComplexityGemini,
+  connectMcpServer,
+  connectMcpServers,
+  createCatalogServer,
   createDefaultProvider,
+  createHandoffServer,
+  createInvoiceServer,
+  createLeadMemoryServer,
   createSdkMcpServer,
+  createSpecializedAgent,
   fastHeuristic,
   getRoutingStats,
   hasMedia,
@@ -926,6 +1180,7 @@ export {
   judgeComplexityGemini,
   latestUserText,
   listDirTool,
+  loadPack,
   loadStageContext,
   loadStages,
   matchesAllow,