@~lyre/ai-agents 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,31 @@
-# @lyre/ai-agents
+# @~lyre/ai-agents
+
+Multi-provider AI agents SDK for SvelteKit and Node. Thin agent/tool/run/runStream/runObject API on top of the [Vercel AI SDK](https://ai-sdk.dev/) — supports OpenAI, Anthropic, Google Gemini, Mistral, Cohere, and any other provider the AI SDK targets.
+
+## Structured output (`runObject`) — added in 0.2.0
+
+`run`/`runStream` return free text. For analysis/extraction where you want a validated,
+typed object, use `runObject` — single-shot, schema-constrained generation over the AI
+SDK's `generateObject`. Purely additive; existing `run`/`runStream` are unchanged.
+
+```ts
+import { createClient } from '@~lyre/ai-agents';
+import { z } from 'zod';
+
+const ai = createClient();
+ai.createAgent({ name: 'extractor', model: anthropic('claude-sonnet-4-5'), instructions: '...' });
+
+const { object } = await ai.runObject({
+  agent: 'extractor',
+  message: 'Summarize these conversations …',
+  inputSchema: z.object({
+    topics: z.array(z.string()),
+    sentiment: z.enum(['positive', 'neutral', 'negative', 'mixed'])
+  })
+});
+// object is typed + validated; no manual JSON parsing.
+```
 
-Multi-provider AI agents SDK for SvelteKit and Node. Thin agent/tool/run/runStream API on top of the [Vercel AI SDK](https://ai-sdk.dev/) — supports OpenAI, Anthropic, Google Gemini, Mistral, Cohere, and any other provider the AI SDK targets.
 
 ## Why
 
@@ -9,12 +34,12 @@ The original `@kigathi/ai-agents` v1.1.0 (in `belva/axis/packages/lyre-ai-agents
 ## Quick start
 
 ```bash
-pnpm add @lyre/ai-agents ai zod
+pnpm add @~lyre/ai-agents ai zod
 pnpm add @ai-sdk/anthropic   # or @ai-sdk/openai, @ai-sdk/google, etc.
 ```
 
 ```ts
-import { createClient } from '@lyre/ai-agents';
+import { createClient } from '@~lyre/ai-agents';
 import { z } from 'zod';
 
 const ai = createClient();

package/dist/chunk-7CW6W47V.js

@@ -0,0 +1,64 @@
+// src/sanitize.ts
+var ALLOWED_TAGS = /* @__PURE__ */ new Set([
+  "a",
+  "b",
+  "blockquote",
+  "br",
+  "code",
+  "div",
+  "em",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "hr",
+  "i",
+  "li",
+  "ol",
+  "p",
+  "pre",
+  "span",
+  "strong",
+  "table",
+  "tbody",
+  "td",
+  "th",
+  "thead",
+  "tr",
+  "u",
+  "ul"
+]);
+var ALLOWED_ATTRS = {
+  a: /* @__PURE__ */ new Set(["href", "title", "target", "rel"]),
+  "*": /* @__PURE__ */ new Set(["class"])
+};
+var UNSAFE_PROTOCOLS = /^\s*(javascript|data|vbscript):/i;
+function sanitizeRichHtml(input) {
+  if (!input) return "";
+  let html = String(input);
+  html = html.replace(/<\s*(script|style|iframe|object|embed|link|meta)[^>]*>[\s\S]*?<\s*\/\s*\1\s*>/gi, "");
+  html = html.replace(/<\s*(script|style|iframe|object|embed|link|meta)[^>]*\/?\s*>/gi, "");
+  html = html.replace(/\s+on[a-z]+\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi, "");
+  html = html.replace(
+    /\s+(href|src)\s*=\s*("(?:[^"]*?)"|'(?:[^']*?)'|[^\s>]+)/gi,
+    (match, attr, value) => {
+      const v = value.replace(/^['"]|['"]$/g, "");
+      if (UNSAFE_PROTOCOLS.test(v)) return "";
+      return ` ${attr}="${v.replace(/"/g, "&quot;")}"`;
+    }
+  );
+  html = html.replace(/<\s*\/?\s*([a-zA-Z][a-zA-Z0-9]*)\b[^>]*>/g, (match, tagName) => {
+    const lower = tagName.toLowerCase();
+    if (ALLOWED_TAGS.has(lower)) return match;
+    return "";
+  });
+  return html;
+}
+
+export {
+  ALLOWED_TAGS,
+  ALLOWED_ATTRS,
+  sanitizeRichHtml
+};

package/dist/index.d.ts

@@ -0,0 +1,214 @@
+import { z } from 'zod';
+export { sanitizeRichHtml } from './sanitize.js';
+
+/**
+ * A model identifier. Vercel AI SDK v6 accepts strings like `'openai/gpt-4o'`,
+ * `'anthropic/claude-sonnet-4.5'`, `'google/gemini-2.5-flash'`. Provider auth comes
+ * from environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`,
+ * `GOOGLE_GENERATIVE_AI_API_KEY`) unless you wire an explicit provider object.
+ */
+type ModelId = string;
+/**
+ * Anything `streamText` / `generateText` accepts as `model`. Use a string for
+ * registry-resolved providers; pass a `LanguageModel` instance for custom wiring.
+ */
+type ModelLike = ModelId | {
+    specificationVersion: string;
+    [k: string]: any;
+};
+type ToolDefinition<Input = unknown, Output = unknown> = {
+    name: string;
+    description: string;
+    /**
+     * Zod schema for the tool's input arguments. The AI SDK uses this to constrain
+     * the model's function-call output and to type the `execute` callback.
+     */
+    inputSchema: z.ZodSchema<Input>;
+    execute: (input: Input, context: ToolContext) => Promise<Output> | Output;
+};
+type ToolContext = {
+    /** Unique tool call id from the model, useful for correlating tool-call → tool-result. */
+    toolCallId: string;
+    /** Forwarded from RunParams.context — apps thread per-request state (user id, locale, etc.). */
+    app: Record<string, any>;
+};
+type Message = {
+    role: 'system';
+    content: string;
+} | {
+    role: 'user';
+    content: string;
+} | {
+    role: 'assistant';
+    content: string;
+};
+type AgentDefinition = {
+    /** Stable identifier; used as the lookup key. Defaults to `name`. */
+    id?: string;
+    name: string;
+    model: ModelLike;
+    /** System prompt. Inserted as a `system` message when no system message is in the history. */
+    instructions?: string;
+    temperature?: number;
+    maxOutputTokens?: number;
+    /**
+     * Tool names this agent may call. If omitted, all globally-registered tools are available.
+     */
+    tools?: readonly string[];
+    /**
+     * Provider-specific options. Forwarded to Vercel AI SDK's `providerOptions`.
+     * Example: `{ anthropic: { cacheControl: { type: 'ephemeral' } } }`.
+     */
+    providerOptions?: Record<string, Record<string, any>>;
+    metadata?: Record<string, any>;
+};
+type Agent = Required<Pick<AgentDefinition, 'id' | 'name' | 'model' | 'instructions'>> & Omit<AgentDefinition, 'id' | 'name' | 'model' | 'instructions'>;
+type RunParams = {
+    /** Agent id, name, or definition object. */
+    agent: string | AgentDefinition;
+    /** The new user message. Combined with `history` to form the full conversation. */
+    message?: string;
+    /** Prior conversation. The agent's `instructions` is prepended as a system message. */
+    history?: readonly Message[];
+    /** Override `maxOutputTokens` per call. */
+    maxOutputTokens?: number;
+    /** Override `temperature` per call. */
+    temperature?: number;
+    /** Max number of tool-call iterations before bailing. Default 8. */
+    maxSteps?: number;
+    /** Forwarded to tool `execute(input, context)`. */
+    context?: Record<string, any>;
+};
+type RunResult = {
+    text: string;
+    finishReason: string;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+    toolCalls: {
+        toolCallId: string;
+        toolName: string;
+        input: unknown;
+    }[];
+    toolResults: {
+        toolCallId: string;
+        toolName: string;
+        output: unknown;
+    }[];
+    raw: any;
+};
+type StreamEvent = {
+    type: 'text-delta';
+    text: string;
+} | {
+    type: 'tool-call';
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+} | {
+    type: 'tool-result';
+    toolCallId: string;
+    toolName: string;
+    output: unknown;
+} | {
+    type: 'tool-error';
+    toolCallId: string;
+    toolName: string;
+    error: unknown;
+} | {
+    type: 'finish';
+    finishReason: string;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+} | {
+    type: 'error';
+    error: unknown;
+};
+/**
+ * Parameters for `runObject` — schema-constrained structured generation. Mirrors
+ * `RunParams` minus tools/maxSteps (structured generation is single-shot), plus a Zod
+ * `schema` the model output is validated against. Added in 0.2.0; non-breaking.
+ */
+type RunObjectParams<T = unknown> = {
+    /** Agent id, name, or definition object. */
+    agent: string | AgentDefinition;
+    /** The new user message. Combined with `history` to form the full conversation. */
+    message?: string;
+    /** Prior conversation. The agent's `instructions` is prepended as a system message. */
+    history?: readonly Message[];
+    /** Zod schema the model's JSON output must satisfy. The SDK constrains + validates. */
+    inputSchema: z.ZodSchema<T>;
+    /** Optional schema name/description forwarded to the provider for better grounding. */
+    schemaName?: string;
+    schemaDescription?: string;
+    maxOutputTokens?: number;
+    temperature?: number;
+    /** Forwarded to the model call (not to tools — structured generation has no tools). */
+    context?: Record<string, any>;
+};
+type RunObjectResult<T = unknown> = {
+    /** The validated, typed object. */
+    object: T;
+    finishReason: string;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+    raw: any;
+};
+
+/**
+ * In-memory registry of agents and tools. One per `Client`.
+ */
+declare class Registry {
+    readonly tools: Map<string, ToolDefinition>;
+    readonly agents: Map<string, Agent>;
+    registerTool<I, O>(tool: ToolDefinition<I, O>): ToolDefinition<I, O>;
+    createAgent(definition: AgentDefinition): Agent;
+    resolveAgent(input: string | AgentDefinition): Agent;
+    resolveTools(agent: Agent): ToolDefinition[];
+}
+
+/**
+ * AI agents client. Stateless besides the agent/tool registry; create one per app
+ * (or per request — they're cheap).
+ */
+declare class AiAgentsClient {
+    private readonly registry;
+    constructor();
+    registerTool<I, O>(tool: ToolDefinition<I, O>): ToolDefinition<I, O>;
+    createAgent(definition: AgentDefinition): Agent;
+    run(params: RunParams): Promise<RunResult>;
+    runStream(params: RunParams): AsyncGenerator<StreamEvent, void, unknown>;
+    /**
+     * Schema-constrained structured generation. Returns a validated, typed object
+     * instead of free text. Single-shot (no tools). Added in 0.2.0.
+     */
+    runObject<T>(params: RunObjectParams<T>): Promise<RunObjectResult<T>>;
+    /** Direct access to the underlying registry for advanced introspection. */
+    get raw(): Registry;
+}
+/**
+ * Factory. Provider auth comes from environment variables. To explicitly configure
+ * provider clients (e.g., for testing), pass `LanguageModel` instances to
+ * `createAgent({ model })` instead of string identifiers.
+ */
+declare function createClient(): AiAgentsClient;
+
+declare function run(registry: Registry, params: RunParams): Promise<RunResult>;
+declare function runStream(registry: Registry, params: RunParams): AsyncGenerator<StreamEvent, void, unknown>;
+/**
+ * Schema-constrained structured generation. Single-shot (no tools): the model is
+ * forced to return JSON matching `params.inputSchema`, validated by the AI SDK before
+ * it resolves. Use this for analysis/extraction where you want a typed object instead
+ * of free text. Additive — does not touch `run`/`runStream`.
+ */
+declare function runObject<T>(registry: Registry, params: RunObjectParams<T>): Promise<RunObjectResult<T>>;
+
+export { type Agent, type AgentDefinition, AiAgentsClient, type Message, type ModelId, type ModelLike, Registry, type RunObjectParams, type RunObjectResult, type RunParams, type RunResult, type StreamEvent, type ToolContext, type ToolDefinition, createClient, run, runObject, runStream };

package/dist/index.js

@@ -0,0 +1,237 @@
+import {
+  sanitizeRichHtml
+} from "./chunk-7CW6W47V.js";
+
+// src/agents.ts
+var Registry = class {
+  tools = /* @__PURE__ */ new Map();
+  agents = /* @__PURE__ */ new Map();
+  registerTool(tool2) {
+    this.tools.set(tool2.name, tool2);
+    return tool2;
+  }
+  createAgent(definition) {
+    const agent = {
+      id: definition.id ?? definition.name,
+      name: definition.name,
+      model: definition.model,
+      instructions: definition.instructions ?? "",
+      temperature: definition.temperature,
+      maxOutputTokens: definition.maxOutputTokens,
+      tools: definition.tools,
+      providerOptions: definition.providerOptions,
+      metadata: definition.metadata
+    };
+    this.agents.set(agent.id, agent);
+    if (agent.name !== agent.id) this.agents.set(agent.name, agent);
+    return agent;
+  }
+  resolveAgent(input) {
+    if (typeof input !== "string") {
+      return this.createAgent(input);
+    }
+    const found = this.agents.get(input);
+    if (!found) throw new Error(`Unknown agent: ${input}`);
+    return found;
+  }
+  resolveTools(agent) {
+    const names = agent.tools && agent.tools.length > 0 ? agent.tools : [...this.tools.keys()];
+    const out = [];
+    for (const name of names) {
+      const tool2 = this.tools.get(name);
+      if (tool2) out.push(tool2);
+    }
+    return out;
+  }
+};
+
+// src/run.ts
+import { generateObject, generateText, streamText, tool } from "ai";
+function resolveModel(agent) {
+  return agent.model;
+}
+function buildMessages(agent, params) {
+  const messages = [];
+  const history = params.history ?? [];
+  const hasSystem = history.some((m) => m.role === "system");
+  if (!hasSystem && agent.instructions) {
+    messages.push({ role: "system", content: agent.instructions });
+  }
+  for (const m of history) messages.push(m);
+  if (params.message) {
+    messages.push({ role: "user", content: params.message });
+  }
+  return messages;
+}
+function buildTools(registry, agent, context) {
+  const defs = registry.resolveTools(agent);
+  const out = {};
+  for (const def of defs) {
+    out[def.name] = tool({
+      description: def.description,
+      inputSchema: def.inputSchema,
+      execute: async (input, opts) => def.execute(input, { toolCallId: opts.toolCallId, app: context })
+    });
+  }
+  return out;
+}
+async function run(registry, params) {
+  const agent = registry.resolveAgent(params.agent);
+  const messages = buildMessages(agent, params);
+  const tools = buildTools(registry, agent, params.context ?? {});
+  const result = await generateText({
+    model: resolveModel(agent),
+    messages,
+    tools,
+    temperature: params.temperature ?? agent.temperature,
+    maxOutputTokens: params.maxOutputTokens ?? agent.maxOutputTokens,
+    stopWhen: ({ steps }) => steps.length >= (params.maxSteps ?? 8),
+    providerOptions: agent.providerOptions
+  });
+  return {
+    text: result.text,
+    finishReason: result.finishReason,
+    usage: {
+      inputTokens: result.usage?.inputTokens ?? 0,
+      outputTokens: result.usage?.outputTokens ?? 0,
+      totalTokens: result.usage?.totalTokens ?? 0
+    },
+    toolCalls: (result.toolCalls ?? []).map((c) => ({
+      toolCallId: c.toolCallId,
+      toolName: c.toolName,
+      input: c.input
+    })),
+    toolResults: (result.toolResults ?? []).map((r) => ({
+      toolCallId: r.toolCallId,
+      toolName: r.toolName,
+      output: r.output
+    })),
+    raw: result
+  };
+}
+async function* runStream(registry, params) {
+  const agent = registry.resolveAgent(params.agent);
+  const messages = buildMessages(agent, params);
+  const tools = buildTools(registry, agent, params.context ?? {});
+  const result = streamText({
+    model: resolveModel(agent),
+    messages,
+    tools,
+    temperature: params.temperature ?? agent.temperature,
+    maxOutputTokens: params.maxOutputTokens ?? agent.maxOutputTokens,
+    stopWhen: ({ steps }) => steps.length >= (params.maxSteps ?? 8),
+    providerOptions: agent.providerOptions
+  });
+  for await (const part of result.fullStream) {
+    switch (part.type) {
+      case "text-delta":
+        yield { type: "text-delta", text: part.text ?? part.delta ?? "" };
+        break;
+      case "tool-call":
+        yield {
+          type: "tool-call",
+          toolCallId: part.toolCallId,
+          toolName: part.toolName,
+          input: part.input ?? part.args
+        };
+        break;
+      case "tool-result":
+        yield {
+          type: "tool-result",
+          toolCallId: part.toolCallId,
+          toolName: part.toolName,
+          output: part.output ?? part.result
+        };
+        break;
+      case "tool-error":
+        yield {
+          type: "tool-error",
+          toolCallId: part.toolCallId,
+          toolName: part.toolName,
+          error: part.error
+        };
+        break;
+      case "finish":
+        yield {
+          type: "finish",
+          finishReason: part.finishReason,
+          usage: {
+            inputTokens: part.usage?.inputTokens ?? 0,
+            outputTokens: part.usage?.outputTokens ?? 0,
+            totalTokens: part.usage?.totalTokens ?? 0
+          }
+        };
+        break;
+      case "error":
+        yield { type: "error", error: part.error };
+        break;
+    }
+  }
+}
+async function runObject(registry, params) {
+  const agent = registry.resolveAgent(params.agent);
+  const messages = buildMessages(agent, params);
+  const result = await generateObject({
+    model: resolveModel(agent),
+    messages,
+    schema: params.inputSchema,
+    schemaName: params.schemaName,
+    schemaDescription: params.schemaDescription,
+    temperature: params.temperature ?? agent.temperature,
+    maxOutputTokens: params.maxOutputTokens ?? agent.maxOutputTokens,
+    providerOptions: agent.providerOptions
+  });
+  return {
+    object: result.object,
+    finishReason: result.finishReason ?? "stop",
+    usage: {
+      inputTokens: result.usage?.inputTokens ?? 0,
+      outputTokens: result.usage?.outputTokens ?? 0,
+      totalTokens: result.usage?.totalTokens ?? 0
+    },
+    raw: result
+  };
+}
+
+// src/client.ts
+var AiAgentsClient = class {
+  registry;
+  constructor() {
+    this.registry = new Registry();
+  }
+  registerTool(tool2) {
+    return this.registry.registerTool(tool2);
+  }
+  createAgent(definition) {
+    return this.registry.createAgent(definition);
+  }
+  async run(params) {
+    return run(this.registry, params);
+  }
+  runStream(params) {
+    return runStream(this.registry, params);
+  }
+  /**
+   * Schema-constrained structured generation. Returns a validated, typed object
+   * instead of free text. Single-shot (no tools). Added in 0.2.0.
+   */
+  async runObject(params) {
+    return runObject(this.registry, params);
+  }
+  /** Direct access to the underlying registry for advanced introspection. */
+  get raw() {
+    return this.registry;
+  }
+};
+function createClient() {
+  return new AiAgentsClient();
+}
+export {
+  AiAgentsClient,
+  Registry,
+  createClient,
+  run,
+  runObject,
+  runStream,
+  sanitizeRichHtml
+};

package/dist/sanitize.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Minimal HTML sanitizer for AI-generated rich text. Strips script/style/iframe and
+ * inline event handlers; keeps a small allowlist of tags and attributes suitable for
+ * advisor output.
+ *
+ * Ported from @kigathi/ai-agents v1.1.0 with minor TS typing tweaks.
+ */
+declare const ALLOWED_TAGS: Set<string>;
+declare const ALLOWED_ATTRS: Record<string, Set<string>>;
+declare function sanitizeRichHtml(input: string | null | undefined): string;
+
+export { ALLOWED_ATTRS, ALLOWED_TAGS, sanitizeRichHtml };

package/dist/sanitize.js

@@ -0,0 +1,10 @@
+import {
+  ALLOWED_ATTRS,
+  ALLOWED_TAGS,
+  sanitizeRichHtml
+} from "./chunk-7CW6W47V.js";
+export {
+  ALLOWED_ATTRS,
+  ALLOWED_TAGS,
+  sanitizeRichHtml
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@~lyre/ai-agents",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Multi-provider AI agents SDK for SvelteKit + Node. Thin agent/tool/run/runStream surface over the Vercel AI SDK — OpenAI, Anthropic, Google Gemini, Mistral, Cohere. Zod-typed tools, full streaming event surface, optional HTML sanitizer.",
   "type": "module",
   "sideEffects": false,
@@ -8,12 +8,11 @@
   "author": "Britam Trust Services / Lyre",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/REPLACE_ME/britam-legacy.git",
-    "directory": "packages/ai-agents"
+    "url": "git+https://github.com/kigathi-chege/lyre-ai-agents.git"
   },
-  "homepage": "https://github.com/REPLACE_ME/britam-legacy/tree/main/packages/ai-agents#readme",
+  "homepage": "https://github.com/kigathi-chege/lyre-ai-agents#readme",
   "bugs": {
-    "url": "https://github.com/REPLACE_ME/britam-legacy/issues"
+    "url": "https://github.com/kigathi-chege/lyre-ai-agents/issues"
   },
   "keywords": [
     "ai",
@@ -28,24 +27,25 @@
     "sveltekit",
     "lyre"
   ],
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./src/index.ts",
-      "import": "./src/index.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     },
     "./sanitize": {
-      "types": "./src/sanitize.ts",
-      "import": "./src/sanitize.ts"
+      "types": "./dist/sanitize.d.ts",
+      "import": "./dist/sanitize.js"
     }
   },
   "files": [
-    "src",
+    "dist",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
+    "build": "tsup src/index.ts src/sanitize.ts --format esm --dts --clean",
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
@@ -55,6 +55,7 @@
   "devDependencies": {
     "@types/node": "^22",
     "ai": "^6.0.0",
+    "tsup": "^8.3.5",
     "typescript": "^6.0.2",
     "zod": "^4.0.0"
   },

package/src/agents.ts

@@ -1,53 +0,0 @@
-import type { Agent, AgentDefinition, ToolDefinition } from './types';
-
-/**
- * In-memory registry of agents and tools. One per `Client`.
- */
-export class Registry {
-	readonly tools = new Map<string, ToolDefinition>();
-	readonly agents = new Map<string, Agent>();
-
-	registerTool<I, O>(tool: ToolDefinition<I, O>): ToolDefinition<I, O> {
-		this.tools.set(tool.name, tool as unknown as ToolDefinition);
-		return tool;
-	}
-
-	createAgent(definition: AgentDefinition): Agent {
-		const agent: Agent = {
-			id: definition.id ?? definition.name,
-			name: definition.name,
-			model: definition.model,
-			instructions: definition.instructions ?? '',
-			temperature: definition.temperature,
-			maxOutputTokens: definition.maxOutputTokens,
-			tools: definition.tools,
-			providerOptions: definition.providerOptions,
-			metadata: definition.metadata
-		};
-
-		this.agents.set(agent.id, agent);
-		// Also key by name when distinct from id, so consumers can look up by either.
-		if (agent.name !== agent.id) this.agents.set(agent.name, agent);
-		return agent;
-	}
-
-	resolveAgent(input: string | AgentDefinition): Agent {
-		if (typeof input !== 'string') {
-			// Allow callers to pass a fully-formed definition for one-off calls.
-			return this.createAgent(input);
-		}
-		const found = this.agents.get(input);
-		if (!found) throw new Error(`Unknown agent: ${input}`);
-		return found;
-	}
-
-	resolveTools(agent: Agent): ToolDefinition[] {
-		const names = agent.tools && agent.tools.length > 0 ? agent.tools : [...this.tools.keys()];
-		const out: ToolDefinition[] = [];
-		for (const name of names) {
-			const tool = this.tools.get(name);
-			if (tool) out.push(tool);
-		}
-		return out;
-	}
-}

package/src/client.ts

@@ -1,52 +0,0 @@
-import { Registry } from './agents';
-import { run, runStream } from './run';
-import type {
-	Agent,
-	AgentDefinition,
-	RunParams,
-	RunResult,
-	StreamEvent,
-	ToolDefinition
-} from './types';
-
-/**
- * AI agents client. Stateless besides the agent/tool registry; create one per app
- * (or per request — they're cheap).
- */
-export class AiAgentsClient {
-	private readonly registry: Registry;
-
-	constructor() {
-		this.registry = new Registry();
-	}
-
-	registerTool<I, O>(tool: ToolDefinition<I, O>): ToolDefinition<I, O> {
-		return this.registry.registerTool(tool);
-	}
-
-	createAgent(definition: AgentDefinition): Agent {
-		return this.registry.createAgent(definition);
-	}
-
-	async run(params: RunParams): Promise<RunResult> {
-		return run(this.registry, params);
-	}
-
-	runStream(params: RunParams): AsyncGenerator<StreamEvent, void, unknown> {
-		return runStream(this.registry, params);
-	}
-
-	/** Direct access to the underlying registry for advanced introspection. */
-	get raw(): Registry {
-		return this.registry;
-	}
-}
-
-/**
- * Factory. Provider auth comes from environment variables. To explicitly configure
- * provider clients (e.g., for testing), pass `LanguageModel` instances to
- * `createAgent({ model })` instead of string identifiers.
- */
-export function createClient(): AiAgentsClient {
-	return new AiAgentsClient();
-}

package/src/index.ts

@@ -1,19 +0,0 @@
-// Public API
-export { createClient, AiAgentsClient } from './client';
-export { Registry } from './agents';
-export { run, runStream } from './run';
-export { sanitizeRichHtml } from './sanitize';
-
-// Types
-export type {
-	ModelId,
-	ModelLike,
-	Message,
-	ToolDefinition,
-	ToolContext,
-	AgentDefinition,
-	Agent,
-	RunParams,
-	RunResult,
-	StreamEvent
-} from './types';

package/src/run.ts

@@ -1,153 +0,0 @@
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-import { generateText, streamText, tool, type ModelMessage, type Tool } from 'ai';
-import type { Registry } from './agents';
-import type {
-	Message,
-	RunParams,
-	RunResult,
-	StreamEvent,
-	Agent,
-	ToolDefinition
-} from './types';
-
-function buildMessages(agent: Agent, params: RunParams): ModelMessage[] {
-	const messages: ModelMessage[] = [];
-
-	const history = params.history ?? [];
-	const hasSystem = history.some((m) => m.role === 'system');
-	if (!hasSystem && agent.instructions) {
-		messages.push({ role: 'system', content: agent.instructions });
-	}
-
-	for (const m of history) messages.push(m as unknown as ModelMessage);
-
-	if (params.message) {
-		messages.push({ role: 'user', content: params.message });
-	}
-
-	return messages;
-}
-
-function buildTools(
-	registry: Registry,
-	agent: Agent,
-	context: Record<string, unknown>
-): Record<string, Tool> {
-	const defs = registry.resolveTools(agent);
-	const out: Record<string, Tool> = {};
-	for (const def of defs as ToolDefinition[]) {
-		out[def.name] = tool({
-			description: def.description,
-			inputSchema: def.inputSchema,
-			execute: async (input, opts: { toolCallId: string }) =>
-				def.execute(input, { toolCallId: opts.toolCallId, app: context })
-		});
-	}
-	return out;
-}
-
-export async function run(registry: Registry, params: RunParams): Promise<RunResult> {
-	const agent = registry.resolveAgent(params.agent);
-	const messages = buildMessages(agent, params);
-	const tools = buildTools(registry, agent, params.context ?? {});
-
-	const result = await generateText({
-		model: agent.model,
-		messages,
-		tools,
-		temperature: params.temperature ?? agent.temperature,
-		maxOutputTokens: params.maxOutputTokens ?? agent.maxOutputTokens,
-		stopWhen: ({ steps }) => steps.length >= (params.maxSteps ?? 8),
-		providerOptions: agent.providerOptions
-	});
-
-	return {
-		text: result.text,
-		finishReason: result.finishReason as string,
-		usage: {
-			inputTokens: result.usage?.inputTokens ?? 0,
-			outputTokens: result.usage?.outputTokens ?? 0,
-			totalTokens: result.usage?.totalTokens ?? 0
-		},
-		toolCalls: (result.toolCalls ?? []).map((c) => ({
-			toolCallId: c.toolCallId,
-			toolName: c.toolName,
-			input: c.input
-		})),
-		toolResults: (result.toolResults ?? []).map((r) => ({
-			toolCallId: r.toolCallId,
-			toolName: r.toolName,
-			output: (r as { output: unknown }).output
-		})),
-		raw: result
-	};
-}
-
-export async function* runStream(
-	registry: Registry,
-	params: RunParams
-): AsyncGenerator<StreamEvent, void, unknown> {
-	const agent = registry.resolveAgent(params.agent);
-	const messages = buildMessages(agent, params);
-	const tools = buildTools(registry, agent, params.context ?? {});
-
-	const result = streamText({
-		model: agent.model,
-		messages,
-		tools,
-		temperature: params.temperature ?? agent.temperature,
-		maxOutputTokens: params.maxOutputTokens ?? agent.maxOutputTokens,
-		stopWhen: ({ steps }) => steps.length >= (params.maxSteps ?? 8),
-		providerOptions: agent.providerOptions
-	});
-
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	for await (const part of result.fullStream as AsyncIterable<any>) {
-		switch (part.type) {
-			case 'text-delta':
-				yield { type: 'text-delta', text: part.text ?? part.delta ?? '' };
-				break;
-			case 'tool-call':
-				yield {
-					type: 'tool-call',
-					toolCallId: part.toolCallId,
-					toolName: part.toolName,
-					input: part.input ?? part.args
-				};
-				break;
-			case 'tool-result':
-				yield {
-					type: 'tool-result',
-					toolCallId: part.toolCallId,
-					toolName: part.toolName,
-					output: part.output ?? part.result
-				};
-				break;
-			case 'tool-error':
-				yield {
-					type: 'tool-error',
-					toolCallId: part.toolCallId,
-					toolName: part.toolName,
-					error: part.error
-				};
-				break;
-			case 'finish':
-				yield {
-					type: 'finish',
-					finishReason: part.finishReason,
-					usage: {
-						inputTokens: part.usage?.inputTokens ?? 0,
-						outputTokens: part.usage?.outputTokens ?? 0,
-						totalTokens: part.usage?.totalTokens ?? 0
-					}
-				};
-				break;
-			case 'error':
-				yield { type: 'error', error: part.error };
-				break;
-			// Silently drop other chunk types (start/step boundaries, raw text accumulators, etc.).
-		}
-	}
-}
-
-export type { Message };

package/src/sanitize.ts

@@ -1,80 +0,0 @@
-/**
- * Minimal HTML sanitizer for AI-generated rich text. Strips script/style/iframe and
- * inline event handlers; keeps a small allowlist of tags and attributes suitable for
- * advisor output.
- *
- * Ported from @kigathi/ai-agents v1.1.0 with minor TS typing tweaks.
- */
-
-const ALLOWED_TAGS = new Set([
-	'a',
-	'b',
-	'blockquote',
-	'br',
-	'code',
-	'div',
-	'em',
-	'h1',
-	'h2',
-	'h3',
-	'h4',
-	'h5',
-	'h6',
-	'hr',
-	'i',
-	'li',
-	'ol',
-	'p',
-	'pre',
-	'span',
-	'strong',
-	'table',
-	'tbody',
-	'td',
-	'th',
-	'thead',
-	'tr',
-	'u',
-	'ul'
-]);
-
-const ALLOWED_ATTRS: Record<string, Set<string>> = {
-	a: new Set(['href', 'title', 'target', 'rel']),
-	'*': new Set(['class'])
-};
-
-const UNSAFE_PROTOCOLS = /^\s*(javascript|data|vbscript):/i;
-
-export function sanitizeRichHtml(input: string | null | undefined): string {
-	if (!input) return '';
-	let html = String(input);
-
-	// Strip dangerous tags wholesale.
-	html = html.replace(/<\s*(script|style|iframe|object|embed|link|meta)[^>]*>[\s\S]*?<\s*\/\s*\1\s*>/gi, '');
-	html = html.replace(/<\s*(script|style|iframe|object|embed|link|meta)[^>]*\/?\s*>/gi, '');
-
-	// Strip on* attributes.
-	html = html.replace(/\s+on[a-z]+\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi, '');
-
-	// Strip unsafe href/src values.
-	html = html.replace(
-		/\s+(href|src)\s*=\s*("(?:[^"]*?)"|'(?:[^']*?)'|[^\s>]+)/gi,
-		(match, attr: string, value: string) => {
-			const v = value.replace(/^['"]|['"]$/g, '');
-			if (UNSAFE_PROTOCOLS.test(v)) return '';
-			return ` ${attr}="${v.replace(/"/g, '&quot;')}"`;
-		}
-	);
-
-	// Optional: drop tags not in allowlist. We do this last so attribute stripping above
-	// applies to the broader HTML stream first.
-	html = html.replace(/<\s*\/?\s*([a-zA-Z][a-zA-Z0-9]*)\b[^>]*>/g, (match, tagName: string) => {
-		const lower = tagName.toLowerCase();
-		if (ALLOWED_TAGS.has(lower)) return match;
-		return '';
-	});
-
-	return html;
-}
-
-export { ALLOWED_TAGS, ALLOWED_ATTRS };

package/src/types.ts

@@ -1,110 +0,0 @@
-import type { z } from 'zod';
-
-/**
- * A model identifier. Vercel AI SDK v6 accepts strings like `'openai/gpt-4o'`,
- * `'anthropic/claude-sonnet-4.5'`, `'google/gemini-2.5-flash'`. Provider auth comes
- * from environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`,
- * `GOOGLE_GENERATIVE_AI_API_KEY`) unless you wire an explicit provider object.
- */
-export type ModelId = string;
-
-/**
- * Anything `streamText` / `generateText` accepts as `model`. Use a string for
- * registry-resolved providers; pass a `LanguageModel` instance for custom wiring.
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type ModelLike = ModelId | { specificationVersion: string; [k: string]: any };
-
-export type ToolDefinition<Input = unknown, Output = unknown> = {
-	name: string;
-	description: string;
-	/**
-	 * Zod schema for the tool's input arguments. The AI SDK uses this to constrain
-	 * the model's function-call output and to type the `execute` callback.
-	 */
-	inputSchema: z.ZodSchema<Input>;
-	execute: (input: Input, context: ToolContext) => Promise<Output> | Output;
-};
-
-export type ToolContext = {
-	/** Unique tool call id from the model, useful for correlating tool-call → tool-result. */
-	toolCallId: string;
-	/** Forwarded from RunParams.context — apps thread per-request state (user id, locale, etc.). */
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	app: Record<string, any>;
-};
-
-export type Message =
-	| { role: 'system'; content: string }
-	| { role: 'user'; content: string }
-	| { role: 'assistant'; content: string };
-
-export type AgentDefinition = {
-	/** Stable identifier; used as the lookup key. Defaults to `name`. */
-	id?: string;
-	name: string;
-	model: ModelLike;
-	/** System prompt. Inserted as a `system` message when no system message is in the history. */
-	instructions?: string;
-	temperature?: number;
-	maxOutputTokens?: number;
-	/**
-	 * Tool names this agent may call. If omitted, all globally-registered tools are available.
-	 */
-	tools?: readonly string[];
-	/**
-	 * Provider-specific options. Forwarded to Vercel AI SDK's `providerOptions`.
-	 * Example: `{ anthropic: { cacheControl: { type: 'ephemeral' } } }`.
-	 */
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	providerOptions?: Record<string, Record<string, any>>;
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	metadata?: Record<string, any>;
-};
-
-export type Agent = Required<Pick<AgentDefinition, 'id' | 'name' | 'model' | 'instructions'>> &
-	Omit<AgentDefinition, 'id' | 'name' | 'model' | 'instructions'>;
-
-export type RunParams = {
-	/** Agent id, name, or definition object. */
-	agent: string | AgentDefinition;
-	/** The new user message. Combined with `history` to form the full conversation. */
-	message?: string;
-	/** Prior conversation. The agent's `instructions` is prepended as a system message. */
-	history?: readonly Message[];
-	/** Override `maxOutputTokens` per call. */
-	maxOutputTokens?: number;
-	/** Override `temperature` per call. */
-	temperature?: number;
-	/** Max number of tool-call iterations before bailing. Default 8. */
-	maxSteps?: number;
-	/** Forwarded to tool `execute(input, context)`. */
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	context?: Record<string, any>;
-};
-
-export type RunResult = {
-	text: string;
-	finishReason: string;
-	usage: {
-		inputTokens: number;
-		outputTokens: number;
-		totalTokens: number;
-	};
-	toolCalls: { toolCallId: string; toolName: string; input: unknown }[];
-	toolResults: { toolCallId: string; toolName: string; output: unknown }[];
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	raw: any;
-};
-
-export type StreamEvent =
-	| { type: 'text-delta'; text: string }
-	| { type: 'tool-call'; toolCallId: string; toolName: string; input: unknown }
-	| { type: 'tool-result'; toolCallId: string; toolName: string; output: unknown }
-	| { type: 'tool-error'; toolCallId: string; toolName: string; error: unknown }
-	| {
-			type: 'finish';
-			finishReason: string;
-			usage: { inputTokens: number; outputTokens: number; totalTokens: number };
-	  }
-	| { type: 'error'; error: unknown };