@~lyre/ai-agents 0.5.0 → 0.5.4

package/dist/index.d.ts

@@ -51,6 +51,33 @@ type Message = {
 type ClientDefaults = {
     apiKey?: string;
     model?: ModelLike;
+    /**
+     * Remote agent source (e.g. Axis Intelligence). When set, a run for an agent NOT registered locally
+     * fetches its definition from `${remoteBaseUrl}/agents/{slug}/definition`, runs it locally against the
+     * provider, and reports the result to `${remoteBaseUrl}/runs`. Tools the definition names that aren't
+     * registered locally become proxy tools that POST to `${remoteBaseUrl}/tools/{slug}/call`.
+     */
+    remoteBaseUrl?: string;
+    /** Bearer token (service key) sent to the remote source for fetch/proxy/report calls. */
+    remoteToken?: string;
+};
+/** A tool spec carried by a remote agent definition (name-only for built-ins; schema for apiTools). */
+type RemoteToolSpec = {
+    name: string;
+    description?: string | null;
+    inputSchema?: any;
+    /** The slug the consumer POSTs to `${remoteBaseUrl}/tools/{proxySlug}/call`. Null for built-ins. */
+    proxySlug?: string | null;
+};
+/** A registered remote proxy tool — materialized (with the run's context) into an AI-SDK tool at run time
+ *  in buildTools, so the tool call sent to the source carries the run's scope (appId/tenantId/etc.). */
+type ProxyToolSpec = {
+    name: string;
+    description: string;
+    inputSchema: any;
+    proxySlug: string;
+    base: string;
+    headers: Record<string, string>;
 };
 type AgentDefinition = {
     /** Stable identifier; used as the lookup key. Defaults to `name`. */
@@ -91,6 +118,31 @@ type RunParams = {
     temperature?: number;
     /** Max number of tool-call iterations before bailing. Default 8. */
     maxSteps?: number;
+    /**
+     * Optional schema-constrained final output. When set, the run uses tools AND forces the model's
+     * FINAL answer to be a JSON object matching this schema (AI SDK `Output.object`) — i.e. call tools,
+     * read their results, then produce a validated object. The validated object is surfaced on the
+     * `finish` stream event as `object` (and on `RunResult.object`). Generating the object counts as a
+     * step, so keep `maxSteps` high enough for tool calls + the object step. Omit for free-text runs.
+     */
+    output?: {
+        schema: z.ZodSchema<any>;
+        name?: string;
+        description?: string;
+    };
+    /**
+     * Tool-selection policy for the FIRST step (AI SDK / OpenAI `tool_choice`):
+     * - `'auto'` (default): the model decides whether to call a tool.
+     * - `'required'`: the model MUST call a tool before it can answer — use this to force a data
+     *   round-trip so the model can't fabricate an answer (e.g. a canvas with placeholder values).
+     * - `'none'`: the model must not call tools.
+     * - `{ toolName }`: force a specific tool.
+     * Only the first step is constrained; later steps fall back to `auto` so the model can stop calling
+     * tools and produce its final (optionally schema-constrained) answer.
+     */
+    toolChoice?: 'auto' | 'required' | 'none' | {
+        toolName: string;
+    };
     /** Forwarded to tool `execute(input, context)`. */
     context?: Record<string, any>;
 };
@@ -112,6 +164,8 @@ type RunResult = {
         toolName: string;
         output: unknown;
     }[];
+    /** The schema-validated final object, present only when the run was given `output`. */
+    object?: unknown;
     raw: any;
 };
 type StreamEvent = {
@@ -140,6 +194,8 @@ type StreamEvent = {
         outputTokens: number;
         totalTokens: number;
     };
+    /** The schema-validated final object, present only when the run was given `output`. */
+    object?: unknown;
 } | {
     type: 'error';
     error: unknown;
@@ -183,8 +239,15 @@ type RunObjectResult<T = unknown> = {
  */
 declare class Registry {
     readonly tools: Map<string, ToolDefinition>;
+    readonly proxyTools: Map<string, ProxyToolSpec>;
     readonly agents: Map<string, Agent>;
     registerTool<I, O>(tool: ToolDefinition<I, O>): ToolDefinition<I, O>;
+    /** Register a remote proxy tool spec by name (materialized with run context in buildTools). */
+    registerProxyTool(spec: ProxyToolSpec): void;
+    /** True if a tool with this name is registered (either shape). */
+    hasTool(name: string): boolean;
+    /** True if an agent with this id/name is registered. */
+    hasAgent(idOrName: string): boolean;
     createAgent(definition: AgentDefinition): Agent;
     resolveAgent(input: string | AgentDefinition): Agent;
     resolveTools(agent: Agent): ToolDefinition[];
@@ -240,4 +303,4 @@ declare const SUPPORTED_PROVIDERS: string[];
  */
 declare function resolveModelString(model: string, apiKey?: string): LanguageModel | string;
 
-export { type Agent, type AgentDefinition, AiAgentsClient, type ClientDefaults, type Message, type ModelId, type ModelLike, Registry, type RunObjectParams, type RunObjectResult, type RunParams, type RunResult, SUPPORTED_PROVIDERS, type StreamEvent, type ToolContext, type ToolDefinition, createClient, resolveModelString, run, runObject, runStream };
+export { type Agent, type AgentDefinition, AiAgentsClient, type ClientDefaults, type Message, type ModelId, type ModelLike, type ProxyToolSpec, Registry, type RemoteToolSpec, type RunObjectParams, type RunObjectResult, type RunParams, type RunResult, SUPPORTED_PROVIDERS, type StreamEvent, type ToolContext, type ToolDefinition, createClient, resolveModelString, run, runObject, runStream };

package/dist/index.js

@@ -5,11 +5,26 @@ import {
 // src/agents.ts
 var Registry = class {
   tools = /* @__PURE__ */ new Map();
+  // Remote proxy tool specs — materialized into AI-SDK tools at run time in buildTools, so each call can
+  // fold the run's CONTEXT (scope: appId/tenantId/targetApps/…) into the request sent to the source.
+  proxyTools = /* @__PURE__ */ new Map();
   agents = /* @__PURE__ */ new Map();
   registerTool(tool2) {
     this.tools.set(tool2.name, tool2);
     return tool2;
   }
+  /** Register a remote proxy tool spec by name (materialized with run context in buildTools). */
+  registerProxyTool(spec) {
+    this.proxyTools.set(spec.name, spec);
+  }
+  /** True if a tool with this name is registered (either shape). */
+  hasTool(name) {
+    return this.tools.has(name) || this.proxyTools.has(name);
+  }
+  /** True if an agent with this id/name is registered. */
+  hasAgent(idOrName) {
+    return this.agents.has(idOrName);
+  }
   createAgent(definition) {
     const agent = {
       id: definition.id ?? definition.name,
@@ -80,7 +95,103 @@ function resolveModelString(model, apiKey) {
   return model;
 }
 
+// src/remote.ts
+import { tool as aiTool, jsonSchema } from "ai";
+function authHeaders(defaults) {
+  const h = { "Content-Type": "application/json" };
+  if (defaults.remoteToken) h.Authorization = `Bearer ${defaults.remoteToken}`;
+  return h;
+}
+async function ensureRemoteAgent(registry, agentSlug, defaults) {
+  if (!defaults.remoteBaseUrl) return null;
+  if (registry.hasAgent(agentSlug)) return agentSlug;
+  const base = defaults.remoteBaseUrl.replace(/\/+$/, "");
+  let def;
+  try {
+    const res = await fetch(`${base}/agents/${encodeURIComponent(agentSlug)}/definition`, {
+      method: "GET",
+      headers: authHeaders(defaults)
+    });
+    if (!res.ok) return null;
+    def = await res.json();
+  } catch {
+    return null;
+  }
+  for (const spec of def.tools ?? []) {
+    if (!spec?.name || registry.hasTool(spec.name)) continue;
+    if (!spec.proxySlug) continue;
+    registry.registerProxyTool({
+      name: spec.name,
+      description: spec.description ?? `Proxied tool "${spec.proxySlug}".`,
+      inputSchema: spec.inputSchema ?? { type: "object", properties: {} },
+      proxySlug: spec.proxySlug,
+      base,
+      headers: authHeaders(defaults)
+    });
+  }
+  registry.createAgent({
+    id: def.slug,
+    name: def.slug,
+    model: def.model,
+    instructions: def.instructions ?? "",
+    temperature: def.temperature,
+    maxOutputTokens: def.maxOutputTokens,
+    tools: (def.tools ?? []).map((t) => t.name)
+  });
+  return def.slug;
+}
+function buildProxyTool(spec, context) {
+  const schema = spec.inputSchema ?? { type: "object", properties: {} };
+  const scope = pickScope(context);
+  return aiTool({
+    description: spec.description,
+    inputSchema: jsonSchema(schema),
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    execute: async (input) => {
+      const res = await fetch(`${spec.base}/tools/${encodeURIComponent(spec.proxySlug)}/call`, {
+        method: "POST",
+        headers: spec.headers,
+        body: JSON.stringify({ input, ...scope })
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        return { error: `Proxied tool "${spec.proxySlug}" failed: HTTP ${res.status} ${text}`.trim() };
+      }
+      const body = await res.json().catch(() => ({}));
+      return body.output ?? body;
+    }
+  });
+}
+function pickScope(context) {
+  const out = {};
+  for (const key of ["appId", "tenantId", "scopeMode", "targetApps", "collectionIds", "range"]) {
+    if (context[key] !== void 0 && context[key] !== null) out[key] = context[key];
+  }
+  if (context.toolContext && typeof context.toolContext === "object") {
+    out.toolContext = context.toolContext;
+  }
+  return out;
+}
+async function reportRun(defaults, report) {
+  if (!defaults.remoteBaseUrl) return;
+  const base = defaults.remoteBaseUrl.replace(/\/+$/, "");
+  try {
+    await fetch(`${base}/runs`, {
+      method: "POST",
+      headers: authHeaders(defaults),
+      body: JSON.stringify(report)
+    });
+  } catch {
+  }
+}
+
 // src/run.ts
+async function resolveAgentMaybeRemote(registry, agentInput, defaults) {
+  if (typeof agentInput === "string" && defaults?.remoteBaseUrl && !registry.hasAgent(agentInput)) {
+    await ensureRemoteAgent(registry, agentInput, defaults);
+  }
+  return registry.resolveAgent(agentInput);
+}
 function resolveModel(agent, defaults) {
   const model = agent.model ?? defaults?.model;
   if (typeof model === "string") return resolveModelString(model, defaults?.apiKey);
@@ -109,22 +220,44 @@ function buildTools(registry, agent, context) {
       execute: async (input, opts) => def.execute(input, { toolCallId: opts.toolCallId, app: context })
     });
   }
+  const allowed = agent.tools && agent.tools.length > 0 ? new Set(agent.tools) : null;
+  for (const [name, spec] of registry.proxyTools) {
+    if (allowed && !allowed.has(name)) continue;
+    if (!out[name]) out[name] = buildProxyTool(spec, context);
+  }
   return out;
 }
+function buildRunOptions(params) {
+  const opts = {};
+  if (params.output) {
+    opts.output = Output.object({
+      schema: params.output.schema,
+      name: params.output.name,
+      description: params.output.description
+    });
+  }
+  if (params.toolChoice && params.toolChoice !== "auto") {
+    opts.toolChoice = params.toolChoice;
+    opts.prepareStep = ({ stepNumber }) => stepNumber === 0 ? { toolChoice: params.toolChoice } : { toolChoice: "auto" };
+  }
+  return opts;
+}
 async function run(registry, params, defaults) {
-  const agent = registry.resolveAgent(params.agent);
+  const startedAt = Date.now();
+  const agent = await resolveAgentMaybeRemote(registry, params.agent, defaults);
   const messages = buildMessages(agent, params);
   const tools = buildTools(registry, agent, params.context ?? {});
   const result = await generateText({
     model: resolveModel(agent, defaults),
     messages,
     tools,
+    ...buildRunOptions(params),
     temperature: params.temperature ?? agent.temperature,
     maxOutputTokens: params.maxOutputTokens ?? agent.maxOutputTokens,
     stopWhen: ({ steps }) => steps.length >= (params.maxSteps ?? 8),
     providerOptions: agent.providerOptions
   });
-  return {
+  const runResult = {
     text: result.text,
     finishReason: result.finishReason,
     usage: {
@@ -142,17 +275,44 @@ async function run(registry, params, defaults) {
       toolName: r.toolName,
       output: r.output
     })),
+    ...params.output ? { object: result.experimental_output } : {},
     raw: result
   };
+  void reportRun(defaults ?? {}, buildRunReport(agent, params, runResult, true, null, startedAt));
+  return runResult;
+}
+function buildRunReport(agent, params, result, ok, error, startedAt) {
+  return {
+    operation: "agent_ask",
+    agentSlug: agent.name,
+    model: typeof agent.model === "string" ? agent.model : null,
+    question: params.message ?? null,
+    requestPayload: { message: params.message ?? null, context: params.context ?? null },
+    responsePayload: { text: result.text, object: result.object ?? null, finishReason: result.finishReason ?? null },
+    toolCalls: result.toolCalls,
+    toolResults: result.toolResults,
+    inputTokens: result.usage.inputTokens,
+    outputTokens: result.usage.outputTokens,
+    totalTokens: result.usage.totalTokens,
+    latencyMs: Date.now() - startedAt,
+    ok,
+    error
+  };
 }
 async function* runStream(registry, params, defaults) {
-  const agent = registry.resolveAgent(params.agent);
+  const startedAt = Date.now();
+  const agent = await resolveAgentMaybeRemote(registry, params.agent, defaults);
   const messages = buildMessages(agent, params);
   const tools = buildTools(registry, agent, params.context ?? {});
+  let reportText = "";
+  let reportObject;
+  const reportToolCalls = [];
+  const reportToolResults = [];
   const result = streamText({
     model: resolveModel(agent, defaults),
     messages,
     tools,
+    ...buildRunOptions(params),
     temperature: params.temperature ?? agent.temperature,
     maxOutputTokens: params.maxOutputTokens ?? agent.maxOutputTokens,
     stopWhen: ({ steps }) => steps.length >= (params.maxSteps ?? 8),
@@ -167,13 +327,17 @@ async function* runStream(registry, params, defaults) {
   };
   for await (const part of result.fullStream) {
     switch (part.type) {
-      case "text-delta":
-        yield { type: "text-delta", text: part.text ?? part.delta ?? "" };
+      case "text-delta": {
+        const t = part.text ?? part.delta ?? "";
+        reportText += t;
+        yield { type: "text-delta", text: t };
         break;
+      }
       case "finish-step":
         addUsage(part.usage);
         break;
       case "tool-call":
+        reportToolCalls.push({ toolCallId: part.toolCallId, toolName: part.toolName, input: part.input ?? part.args });
         yield {
           type: "tool-call",
           toolCallId: part.toolCallId,
@@ -182,6 +346,7 @@ async function* runStream(registry, params, defaults) {
         };
         break;
       case "tool-result":
+        reportToolResults.push({ toolCallId: part.toolCallId, toolName: part.toolName, output: part.output ?? part.result });
         yield {
           type: "tool-result",
           toolCallId: part.toolCallId,
@@ -199,18 +364,47 @@ async function* runStream(registry, params, defaults) {
         break;
       case "finish": {
         const finalUsage = part.totalUsage ?? part.usage;
+        let object;
+        if (params.output) {
+          object = await result.experimental_output;
+        }
+        reportObject = object;
+        const usage = {
+          inputTokens: finalUsage?.inputTokens ?? accumulatedUsage.inputTokens,
+          outputTokens: finalUsage?.outputTokens ?? accumulatedUsage.outputTokens,
+          totalTokens: finalUsage?.totalTokens ?? accumulatedUsage.totalTokens
+        };
+        void reportRun(
+          defaults ?? {},
+          buildRunReport(
+            agent,
+            params,
+            { text: reportText, usage, toolCalls: reportToolCalls, toolResults: reportToolResults, object: reportObject, finishReason: part.finishReason },
+            true,
+            null,
+            startedAt
+          )
+        );
         yield {
           type: "finish",
           finishReason: part.finishReason,
-          usage: {
-            inputTokens: finalUsage?.inputTokens ?? accumulatedUsage.inputTokens,
-            outputTokens: finalUsage?.outputTokens ?? accumulatedUsage.outputTokens,
-            totalTokens: finalUsage?.totalTokens ?? accumulatedUsage.totalTokens
-          }
+          usage,
+          ...params.output ? { object } : {}
         };
         break;
       }
       case "error":
+        void reportRun(
+          defaults ?? {},
+          buildRunReport(
+            agent,
+            params,
+            { text: reportText, usage: accumulatedUsage, toolCalls: reportToolCalls, toolResults: reportToolResults, object: reportObject },
+            false,
+            part.error instanceof Error ? part.error.message : String(part.error),
+            startedAt
+          )
+        );
         yield { type: "error", error: part.error };
         break;
     }
@@ -249,7 +443,12 @@ var AiAgentsClient = class {
   defaults;
   constructor(config) {
     this.registry = new Registry();
-    this.defaults = { apiKey: config?.apiKey, model: config?.model };
+    this.defaults = {
+      apiKey: config?.apiKey,
+      model: config?.model,
+      remoteBaseUrl: config?.remoteBaseUrl,
+      remoteToken: config?.remoteToken
+    };
   }
   registerTool(tool2) {
     return this.registry.registerTool(tool2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@~lyre/ai-agents",
-  "version": "0.5.0",
+  "version": "0.5.4",
   "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,