torus-ai 0.2.1 → 0.4.0

package/src/mcp-client.ts

@@ -0,0 +1,114 @@
+import { createSdkMcpServer, tool } from "./tools.ts";
+import type { SdkMcpServer, ToolDefinition } from "./types.ts";
+
+// MCP client: connect to EXTERNAL Model Context Protocol servers (local stdio
+// subprocesses or remote HTTP) and expose their tools to the agent. Each remote
+// tool is wrapped as a normal SdkMcpServer tool, so it flows through the same
+// registry, namespacing (mcp__<server>__<tool>), loop, and permission allowlist
+// as in-process tools. Requires the optional `@modelcontextprotocol/sdk` package.
+
+export type McpServerConfig =
+  | {
+      type?: "stdio";
+      command: string;
+      args?: string[];
+      env?: Record<string, string>;
+    }
+  | {
+      type: "http";
+      url: string;
+      headers?: Record<string, string>;
+    };
+
+export interface McpConnection {
+  /** Namespaced server — its tools become mcp__<name>__<tool>. */
+  server: SdkMcpServer;
+  /** Tear down the MCP client + transport. */
+  close(): Promise<void>;
+}
+
+async function connect(config: McpServerConfig): Promise<any> {
+  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 as any).Client;
+
+  let transport: any;
+  if (config.type === "http") {
+    const mod = await import("@modelcontextprotocol/sdk/client/streamableHttp.js");
+    transport = new (mod as any).StreamableHTTPClientTransport(
+      new URL(config.url),
+      config.headers ? { requestInit: { headers: config.headers } } : undefined,
+    );
+  } else {
+    const mod = await import("@modelcontextprotocol/sdk/client/stdio.js");
+    transport = new (mod as any).StdioClientTransport({
+      command: config.command,
+      args: config.args ?? [],
+      env: { ...process.env, ...(config.env ?? {}) } as Record<string, string>,
+    });
+  }
+
+  const client = new Client({ name: "torus", version: "0.4.0" }, { capabilities: {} });
+  await client.connect(transport);
+  return client;
+}
+
+/** Connect to one external MCP server and expose its tools as an SdkMcpServer. */
+export async function connectMcpServer(name: string, config: McpServerConfig): Promise<McpConnection> {
+  const client = await connect(config);
+  const listed = await client.listTools();
+
+  const tools: ToolDefinition[] = (listed.tools ?? []).map((t: any) =>
+    tool(
+      t.name,
+      t.description ?? "",
+      (t.inputSchema as Record<string, unknown>) ?? { type: "object", properties: {} },
+      async (input: Record<string, unknown>) => {
+        const res: any = await client.callTool({ name: t.name, arguments: input ?? {} });
+        const text =
+          (res.content ?? [])
+            .filter((c: any) => c?.type === "text")
+            .map((c: any) => 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 {
+        // best-effort teardown
+      }
+    },
+  };
+}
+
+/**
+ * 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();
+ */
+export async function connectMcpServers(
+  configs: Record<string, McpServerConfig>,
+): Promise<{ servers: SdkMcpServer[]; close(): Promise<void> }> {
+  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()));
+    },
+  };
+}

package/src/pack.ts

@@ -0,0 +1,155 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { builtinTools } from "./builtins.ts";
+import { runLoop } from "./loop.ts";
+import { matchesAllow, PermissionEngine } from "./permissions.ts";
+import { createCatalogServer, type CatalogItem } from "./packkit.ts";
+import { createDefaultProvider } from "./providers/cascade.ts";
+import { ToolRegistry } from "./tools.ts";
+import type {
+  AgentEvent,
+  CanUseTool,
+  ContentBlock,
+  Message,
+  ModelProvider,
+  SdkMcpServer,
+} from "./types.ts";
+
+// Specialize the generic engine to a product by loading a *pack* (an adapter):
+// persona + sales playbook + policy + domain tools + catalog grounding + guardrails.
+// One engine, many packs — don't fork the SDK per vertical.
+
+export 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;
+}
+
+export 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;
+}
+
+export interface AgentPack {
+  name: string;
+  persona: string; // who it is + voice (system prompt core)
+  playbook?: string; // sales stages + goal
+  tools?: SdkMcpServer[]; // domain actions (quote, reserve, invoice, handoff, ...)
+  knowledge?: PackKnowledge;
+  guardrails?: PackGuardrails;
+  model?: ModelProvider; // defaults to the free-first cascade
+}
+
+export 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;
+}
+
+export 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. */
+export function createSpecializedAgent(pack: AgentPack, opts: SpecializeOptions = {}): SpecializedAgent {
+  // Assemble the system prompt from persona + playbook + policy + grounding + faqs.
+  const servers: SdkMcpServer[] = [...(pack.tools ?? [])];
+  if (pack.knowledge?.catalog?.length) servers.unshift(createCatalogServer(pack.knowledge.catalog));
+
+  const parts = [pack.persona.trim()];
+  if (pack.playbook) parts.push(`## Playbook\n${pack.playbook.trim()}`);
+  if (pack.guardrails?.policy) parts.push(`## Policy\n${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\n${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: 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: ContentBlock[] =
+        typeof prompt === "string" ? [{ type: "text", text: prompt }] : prompt;
+      const messages: Message[] = [{ 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 };
+    },
+  };
+}
+
+/**
+ * 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`.
+ */
+export async function loadPack(
+  dir: string,
+  opts: { tools?: SdkMcpServer[] } = {},
+): Promise<AgentPack> {
+  const read = async (f: string): Promise<string | undefined> => {
+    const p = join(dir, f);
+    return existsSync(p) ? await readFile(p, "utf8") : undefined;
+  };
+  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) as CatalogItem[]) : undefined,
+      faqs: await read("faqs.md"),
+    },
+    guardrails: policy ? { policy } : undefined,
+    tools: opts.tools,
+  };
+}

package/src/packkit.ts

@@ -0,0 +1,147 @@
+import { createSdkMcpServer, tool } from "./tools.ts";
+import type { SdkMcpServer } from "./types.ts";
+
+// Reusable tool patterns for specializing an agent to a vertical (a "pack").
+// Compose these into a pack's `tools`. They are deliberately backend-agnostic —
+// swap the in-memory stubs for real catalog/CRM/payment integrations later.
+
+export 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). */
+export function createCatalogServer(
+  items: CatalogItem[],
+  opts: { serverName?: string } = {},
+): SdkMcpServer {
+  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 — never guess.",
+    {
+      type: "object",
+      properties: {
+        query: { type: "string" },
+        maxPrice: { type: "number" },
+        tags: { type: "array", items: { type: "string" } },
+        limit: { type: "number" },
+      },
+    },
+    (input: { query?: string; maxPrice?: number; tags?: string[]; limit?: number }) => {
+      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] });
+}
+
+/** `get_lead` / `update_lead` over an in-memory customer profile (the funnel state). */
+export function createLeadMemoryServer(
+  initial: Record<string, unknown> = {},
+): SdkMcpServer & { lead: Record<string, unknown> } {
+  const lead: Record<string, unknown> = { ...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: { fields: Record<string, unknown> }) => {
+      Object.assign(lead, input.fields ?? {});
+      return { content: `updated: ${Object.keys(input.fields ?? {}).join(", ") || "(none)"}` };
+    },
+  );
+  return Object.assign(createSdkMcpServer({ name: "lead", tools: [get, update] }), { lead });
+}
+
+export 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).
+ */
+export function createInvoiceServer(
+  opts: { onCreate?: (inv: Invoice) => void } = {},
+): SdkMcpServer & { invoices: Invoice[] } {
+  const invoices: Invoice[] = [];
+  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: { amount: number; currency?: string; items?: unknown; customer?: unknown }) => {
+      const inv: Invoice = {
+        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 });
+}
+
+/** A `handoff_human` escalation tool. Wire `onHandoff` to notify a real agent. */
+export function createHandoffServer(
+  opts: { onHandoff?: (info: { reason: string; summary: string }) => void } = {},
+): SdkMcpServer {
+  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: { reason: string; summary?: string }) => {
+      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] });
+}