torus-ai 0.2.0 → 0.3.0

package/README.md

@@ -92,9 +92,10 @@ into `query()`, `runPipeline()`, or `runLoop()` interchangeably:
 **The default is a free-first cascade.** If you don't pass a provider, `query()`
 uses `createDefaultProvider()` — it tries each step and falls through on failure:
 
-1. **NVIDIA Kimi K2.6** — main; agentic + multimodal (image/video), free NIM endpoint
-2. **NVIDIA DeepSeek V4 Pro** — 1M-context text model, free; *skipped for image/video*
-3. **Gemini 2.5 Flash** — final fallback, different provider for resilience
+1. **NVIDIA Kimi K2.6** — main; agentic + tools (text), free NIM endpoint
+2. **NVIDIA DeepSeek V4 Pro** — 1M-context text model, free; *skipped for media*
+3. **NVIDIA Llama-3.2-90B-Vision** — image requests, free
+4. **Gemini 2.5 Flash** — final fallback (image + video), different provider for resilience
 
 ```ts
 import { query } from "torus-ai";          // NVIDIA_API_KEY in env → cascade default
@@ -104,20 +105,25 @@ import { createDefaultProvider } from "torus-ai";
 const provider = createDefaultProvider({ mainModel: "moonshotai/kimi-k2.6" });
 ```
 
-It's **capability-aware**: image/video requests automatically skip text-only steps.
+It's **capability-aware**: image requests skip text-only steps and route to a
+vision model; video requests route only to a video-capable step.
 
-### Multimodal (image now, video experimental)
+### Multimodal (image verified, video experimental)
 
-Pass content blocks instead of a string. Images route to a vision-capable step
-(Kimi / Gemini / Claude); video is best-effort to Kimi.
+Pass content blocks instead of a string. Images route to a vision step
+(NVIDIA Llama-Vision → Gemini); video routes to Gemini.
 
 ```ts
 await query([
-  { type: "text", text: "What's in this image?" },
-  { type: "image", url: "https://example.com/cat.png" },         // or { data, mimeType }
+  { type: "text", text: "What animal is this?" },
+  { type: "image", url: "https://example.com/cat.jpg" },   // or { data: base64, mimeType }
 ]);
 ```
 
+> Note: Kimi K2.6's docs claim vision, but its NIM endpoint is **text-only in
+> practice** (verified) — so the cascade sends images to a real vision model
+> instead. Video is experimental and currently served only by Gemini.
+
 ### Cost routing (per provider)
 
 Each model provider also supports `route: true` — fast heuristics, then a
@@ -138,6 +144,52 @@ 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`.
 
+## 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

@@ -329,6 +329,7 @@ declare const NVIDIA_BASE_URL = "https://integrate.api.nvidia.com/v1";
 declare const KIMI_K2_6 = "moonshotai/kimi-k2.6";
 declare const DEEPSEEK_V4_PRO = "deepseek-ai/deepseek-v4-pro";
 declare const DEEPSEEK_V4_FLASH = "deepseek-ai/deepseek-v4-flash";
+declare const LLAMA_VISION = "meta/llama-3.2-90b-vision-instruct";
 interface NvidiaOptions {
     model?: string;
     apiKey?: string;
@@ -351,6 +352,7 @@ interface CascadeStep {
     provider: ModelProvider;
     label: string;
     vision: boolean;
+    video?: boolean;
 }
 interface CascadeOptions {
     steps: CascadeStep[];
@@ -375,20 +377,117 @@ interface DefaultProviderOptions {
     mainModel?: string;
     /** Override the secondary NVIDIA model (default DeepSeek V4 Pro). */
     secondaryModel?: string;
+    /** NVIDIA vision model for image requests (default llama-3.2-90b-vision). */
+    visionModel?: string;
     /** Gemini model used as the final fallback option (default gemini-2.5-flash). */
     geminiModel?: string;
     onFallback?: CascadeOptions["onFallback"];
 }
 /**
  * The SDK's recommended default: free NVIDIA endpoints first, Google as one
- * fallback option.
+ * fallback option. Capability-aware — image/video requests skip the text-only
+ * steps automatically.
  *
- *   1. NVIDIA Kimi K2.6        — main; agentic + multimodal (image/video)
- *   2. NVIDIA DeepSeek V4 Pro  — text-only; skipped for image/video requests
- *   3. Gemini 2.5 Flash        — final fallback; multimodal
+ *   1. NVIDIA Kimi K2.6                  — main; agentic + tools (text)
+ *   2. NVIDIA DeepSeek V4 Pro            — 1M-ctx text; skipped for media
+ *   3. NVIDIA Llama-3.2-90B-Vision       — image requests
+ *   4. Gemini 2.5 Flash                  — final fallback; image + video
  */
 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>;
+
 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";
@@ -451,4 +550,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, 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 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, 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

@@ -705,6 +705,7 @@ var NVIDIA_BASE_URL = "https://integrate.api.nvidia.com/v1";
 var KIMI_K2_6 = "moonshotai/kimi-k2.6";
 var DEEPSEEK_V4_PRO = "deepseek-ai/deepseek-v4-pro";
 var DEEPSEEK_V4_FLASH = "deepseek-ai/deepseek-v4-flash";
+var LLAMA_VISION = "meta/llama-3.2-90b-vision-instruct";
 var NvidiaProvider = class {
   name = "nvidia";
   model;
@@ -717,7 +718,7 @@ var NvidiaProvider = class {
     this.apiKey = opts.apiKey ?? process.env.NVIDIA_API_KEY;
     this.baseURL = opts.baseURL ?? NVIDIA_BASE_URL;
     this.maxTokens = opts.maxTokens ?? 2048;
-    this.temperature = opts.temperature ?? 0.6;
+    this.temperature = opts.temperature ?? 0.2;
   }
   async generate(req) {
     if (!this.apiKey) throw new Error("NvidiaProvider needs NVIDIA_API_KEY (nvapi-...).");
@@ -830,10 +831,15 @@ var CascadeProvider = class {
     this.onFallback = opts.onFallback;
   }
   async generate(req) {
-    const needsVision = hasMedia(req.messages);
-    const eligible = this.steps.filter((s) => !needsVision || s.vision);
+    const has = (t) => req.messages.some((m) => m.content.some((b) => b.type === t));
+    const needsVideo = has("video");
+    const needsImage = has("image");
+    const needsVision = needsImage || needsVideo;
+    const eligible = needsVideo ? this.steps.filter((s) => s.video) : needsImage ? this.steps.filter((s) => s.vision) : this.steps;
     if (!eligible.length) {
-      throw new Error("Cascade: request needs vision but no step supports image/video input.");
+      throw new Error(
+        `Cascade: request needs ${needsVideo ? "video" : "image"} input but no step supports it.`
+      );
     }
     let lastErr;
     for (const step of eligible) {
@@ -854,31 +860,210 @@ var CascadeProvider = class {
 function createDefaultProvider(opts = {}) {
   const main = opts.mainModel ?? KIMI_K2_6;
   const secondary = opts.secondaryModel ?? DEEPSEEK_V4_PRO;
+  const vision = opts.visionModel ?? LLAMA_VISION;
   const gemini = opts.geminiModel ?? "gemini-2.5-flash";
+  const nv = (model) => new NvidiaProvider({ model, apiKey: opts.nvidiaApiKey });
   return new CascadeProvider({
     onFallback: opts.onFallback ?? ((info) => console.warn(`[cascade] ${info.from} failed (${info.reason}); trying next`)),
     steps: [
-      {
-        provider: new NvidiaProvider({ model: main, apiKey: opts.nvidiaApiKey }),
-        label: `nvidia:${main}`,
-        vision: true
-        // Kimi K2.6 accepts image + video
-      },
-      {
-        provider: new NvidiaProvider({ model: secondary, apiKey: opts.nvidiaApiKey }),
-        label: `nvidia:${secondary}`,
-        vision: false
-        // DeepSeek V4 is text-only
-      },
+      { provider: nv(main), label: `nvidia:${main}`, vision: false, video: false },
+      { provider: nv(secondary), label: `nvidia:${secondary}`, vision: false, video: false },
+      { provider: nv(vision), label: `nvidia:${vision}`, vision: true, video: false },
       {
         provider: new GeminiProvider({ model: gemini, apiKey: opts.googleApiKey }),
         label: `gemini:${gemini}`,
-        vision: true
+        vision: true,
+        video: true
       }
     ]
   });
 }
 
+// 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/index.ts
 async function* query(prompt, options = {}) {
   const registry = new ToolRegistry();
@@ -908,6 +1093,7 @@ export {
   GEMINI_EXPENSIVE_MODEL,
   GeminiProvider,
   KIMI_K2_6,
+  LLAMA_VISION,
   MockProvider,
   NVIDIA_BASE_URL,
   NvidiaProvider,
@@ -916,8 +1102,13 @@ export {
   builtinTools,
   classifyComplexity,
   classifyComplexityGemini,
+  createCatalogServer,
   createDefaultProvider,
+  createHandoffServer,
+  createInvoiceServer,
+  createLeadMemoryServer,
   createSdkMcpServer,
+  createSpecializedAgent,
   fastHeuristic,
   getRoutingStats,
   hasMedia,
@@ -925,6 +1116,7 @@ export {
   judgeComplexityGemini,
   latestUserText,
   listDirTool,
+  loadPack,
   loadStageContext,
   loadStages,
   matchesAllow,