@molecule/api-ai-agents-llm 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,18 @@
+/**
+ * Browser guard — `@molecule/api-ai-agents-llm` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-ai-agents-llm is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};

package/dist/errors.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Typed error for a failed agent run.
+ *
+ * @module
+ */
+import type { TokenUsage } from '@molecule/api-ai';
+import type { AgentStep } from '@molecule/api-ai-agents';
+/**
+ * Thrown by `run()` when the agentic loop fails partway through — a provider
+ * API error (rate limit, auth, overload, network), an abort, or any other
+ * exception raised while draining a model turn or executing a tool.
+ *
+ * @remarks
+ * A plain rejected `run()` promise has no channel to deliver partial
+ * metering: the `Promise<AgentRunResult>` contract only carries `usage` on
+ * the RESOLVED path, so a long run that dies on step 8 used to silently
+ * under-meter the 7 turns of real, already-billed spend that came before it.
+ * `AgentRunError` carries the `usage` totaled across every turn that
+ * completed before the failure, plus the `steps` recorded so far, so a
+ * caller that meters spend can book the partial usage instead of losing it.
+ *
+ * `error.message` is unchanged from the plain `Error` this replaces —
+ * existing `catch (error) { … error.message … }` call sites keep working
+ * without any change. Only callers that want the partial usage/steps need to
+ * check `error instanceof AgentRunError`.
+ *
+ * @example
+ * ```ts
+ * import { AgentRunError } from '@molecule/api-ai-agents-llm'
+ *
+ * try {
+ *   const result = await requireProvider().run({ task, tools })
+ *   meterUsage(result.usage)
+ * } catch (error) {
+ *   if (error instanceof AgentRunError) {
+ *     meterUsage(error.usage) // book whatever was billed before the failure
+ *   }
+ *   throw error
+ * }
+ * ```
+ */
+export declare class AgentRunError extends Error {
+    /** Token usage summed across every turn that completed before the failure. */
+    readonly usage: TokenUsage;
+    /** Every intermediate step (with its tool calls) recorded before the failure. */
+    readonly steps: AgentStep[];
+    /**
+     * Builds the error, carrying the partial run alongside the failure so a
+     * caller can report what the agent had already spent and done.
+     *
+     * @param message - The error message (same text a plain `Error` would carry).
+     * @param usage - Token usage accumulated across turns completed before the failure.
+     * @param steps - Steps recorded before the failure.
+     * @param options - Standard `Error` options — `cause` preserves the original thrown value.
+     */
+    constructor(message: string, usage: TokenUsage, steps: AgentStep[], options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,CAAA;IAE3B;;;;;;;;OAQG;gBAED,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,SAAS,EAAE,EAClB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAOhC"}

package/dist/errors.js

@@ -0,0 +1,60 @@
+/**
+ * Typed error for a failed agent run.
+ *
+ * @module
+ */
+/**
+ * Thrown by `run()` when the agentic loop fails partway through — a provider
+ * API error (rate limit, auth, overload, network), an abort, or any other
+ * exception raised while draining a model turn or executing a tool.
+ *
+ * @remarks
+ * A plain rejected `run()` promise has no channel to deliver partial
+ * metering: the `Promise<AgentRunResult>` contract only carries `usage` on
+ * the RESOLVED path, so a long run that dies on step 8 used to silently
+ * under-meter the 7 turns of real, already-billed spend that came before it.
+ * `AgentRunError` carries the `usage` totaled across every turn that
+ * completed before the failure, plus the `steps` recorded so far, so a
+ * caller that meters spend can book the partial usage instead of losing it.
+ *
+ * `error.message` is unchanged from the plain `Error` this replaces —
+ * existing `catch (error) { … error.message … }` call sites keep working
+ * without any change. Only callers that want the partial usage/steps need to
+ * check `error instanceof AgentRunError`.
+ *
+ * @example
+ * ```ts
+ * import { AgentRunError } from '@molecule/api-ai-agents-llm'
+ *
+ * try {
+ *   const result = await requireProvider().run({ task, tools })
+ *   meterUsage(result.usage)
+ * } catch (error) {
+ *   if (error instanceof AgentRunError) {
+ *     meterUsage(error.usage) // book whatever was billed before the failure
+ *   }
+ *   throw error
+ * }
+ * ```
+ */
+export class AgentRunError extends Error {
+    /** Token usage summed across every turn that completed before the failure. */
+    usage;
+    /** Every intermediate step (with its tool calls) recorded before the failure. */
+    steps;
+    /**
+     * Builds the error, carrying the partial run alongside the failure so a
+     * caller can report what the agent had already spent and done.
+     *
+     * @param message - The error message (same text a plain `Error` would carry).
+     * @param usage - Token usage accumulated across turns completed before the failure.
+     * @param steps - Steps recorded before the failure.
+     * @param options - Standard `Error` options — `cause` preserves the original thrown value.
+     */
+    constructor(message, usage, steps, options) {
+        super(message, options);
+        this.name = 'AgentRunError';
+        this.usage = usage;
+        this.steps = steps;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+/**
+ * LLM-backed AI agents provider for molecule.dev — the batteries-included
+ * tool-calling loop that implements the `@molecule/api-ai-agents` core contract.
+ *
+ * Ships a default `provider` (`name: 'llm'`) that drives a model↔tool loop over
+ * the swappable `ai` chat bond (`@molecule/api-ai`): it calls the model,
+ * executes any tools the model requests via each `AITool.execute()`, feeds the
+ * results back, and repeats until the model stops calling tools (or the
+ * `maxSteps` budget is exhausted). Bond it once at startup, then drive it from
+ * anywhere via the `@molecule/api-ai-agents` accessor.
+ *
+ * @example
+ * ```typescript
+ * import { bond } from '@molecule/api-bond'
+ * import { requireProvider } from '@molecule/api-ai-agents'
+ * import { provider as agents } from '@molecule/api-ai-agents-llm'
+ * import type { AITool } from '@molecule/api-ai'
+ *
+ * // Wire at startup (an `ai` provider must already be bonded).
+ * bond('ai-agents', agents)
+ *
+ * const myTool: AITool = {
+ *   name: 'add',
+ *   description: 'Add two numbers',
+ *   parameters: {
+ *     type: 'object',
+ *     properties: { a: { type: 'number' }, b: { type: 'number' } },
+ *     required: ['a', 'b'],
+ *   },
+ *   execute: async (input) => {
+ *     const { a, b } = input as { a: number; b: number }
+ *     return a + b
+ *   },
+ * }
+ *
+ * const result = await requireProvider().run({
+ *   task: 'What is 1 + 2? Use the add tool.',
+ *   tools: [myTool],
+ * })
+ * console.log(result.output) // final assistant answer
+ * console.log(result.steps)  // intermediate tool calls + results
+ * console.log(result.usage)  // token usage summed across all model calls
+ * ```
+ *
+ * @remarks
+ * **Requires a bonded `ai` provider** (`bond('ai', provider)` or a named
+ * provider selected via `run({ provider: 'anthropic' })`) whose model supports
+ * tool use — this agent has no model of its own; it orchestrates the `ai` bond.
+ *
+ * The loop executes your tools: each model `tool_use` runs the matching
+ * `AITool.execute(input)` and the return value is fed back as a `tool_result`.
+ * A thrown tool error or an unknown tool name becomes an error `tool_result`
+ * (recorded with `isError: true`) instead of aborting the run, so the model can
+ * recover. `run()` requires exactly one of `task` (a single user turn) or
+ * `messages` (a full history); it throws if neither — or both — is supplied.
+ *
+ * Every model turn streams by default (`input.stream` — set `false` to force
+ * non-streaming) and, when `input.cacheControl` is set, is passed through to
+ * `ai.chat()` on every turn so a provider that supports prompt caching (e.g.
+ * `@molecule/api-ai-anthropic`) doesn't re-bill the identical `system` + `tools`
+ * prefix on each of up to `maxSteps` turns. Note `onEvent` is only an
+ * INCREMENTAL live hook while streaming — with `stream: false` it fires once
+ * per turn with the whole response.
+ *
+ * Failure semantics (how to tell failure modes apart):
+ * - **Tool failure** (throwing `execute()`, unknown tool name) — NON-fatal:
+ *   recorded on the step with `isError: true` and fed back to the model.
+ * - **AI provider API failure** (rate limit, bad key, overload, network — the
+ *   `ai` bond emits an in-band `error` ChatEvent), **an abort, or any other
+ *   mid-run exception** — FATAL: `run()` rejects with an `AgentRunError`
+ *   (message text unchanged from a plain `Error`) carrying the `usage` and
+ *   `steps` accumulated across every turn that completed before the failure —
+ *   a caller that meters spend can book that partial usage instead of losing
+ *   it. `run()` never resolves with a silently empty `output`, so an empty
+ *   `result.output` means the model genuinely produced no text, not that the
+ *   API failed.
+ * - **Step budget exhausted** — resolves normally; `output` is the last
+ *   assistant text or an explicit "step budget exhausted" note.
+ *
+ * Swappable like any bond: replace this LLM agent with your own
+ * `AIAgentsProvider` via `bond('ai-agents', myProvider)` — nothing else changes.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './errors.js';
+export * from './provider.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,88 @@
+/**
+ * LLM-backed AI agents provider for molecule.dev — the batteries-included
+ * tool-calling loop that implements the `@molecule/api-ai-agents` core contract.
+ *
+ * Ships a default `provider` (`name: 'llm'`) that drives a model↔tool loop over
+ * the swappable `ai` chat bond (`@molecule/api-ai`): it calls the model,
+ * executes any tools the model requests via each `AITool.execute()`, feeds the
+ * results back, and repeats until the model stops calling tools (or the
+ * `maxSteps` budget is exhausted). Bond it once at startup, then drive it from
+ * anywhere via the `@molecule/api-ai-agents` accessor.
+ *
+ * @example
+ * ```typescript
+ * import { bond } from '@molecule/api-bond'
+ * import { requireProvider } from '@molecule/api-ai-agents'
+ * import { provider as agents } from '@molecule/api-ai-agents-llm'
+ * import type { AITool } from '@molecule/api-ai'
+ *
+ * // Wire at startup (an `ai` provider must already be bonded).
+ * bond('ai-agents', agents)
+ *
+ * const myTool: AITool = {
+ *   name: 'add',
+ *   description: 'Add two numbers',
+ *   parameters: {
+ *     type: 'object',
+ *     properties: { a: { type: 'number' }, b: { type: 'number' } },
+ *     required: ['a', 'b'],
+ *   },
+ *   execute: async (input) => {
+ *     const { a, b } = input as { a: number; b: number }
+ *     return a + b
+ *   },
+ * }
+ *
+ * const result = await requireProvider().run({
+ *   task: 'What is 1 + 2? Use the add tool.',
+ *   tools: [myTool],
+ * })
+ * console.log(result.output) // final assistant answer
+ * console.log(result.steps)  // intermediate tool calls + results
+ * console.log(result.usage)  // token usage summed across all model calls
+ * ```
+ *
+ * @remarks
+ * **Requires a bonded `ai` provider** (`bond('ai', provider)` or a named
+ * provider selected via `run({ provider: 'anthropic' })`) whose model supports
+ * tool use — this agent has no model of its own; it orchestrates the `ai` bond.
+ *
+ * The loop executes your tools: each model `tool_use` runs the matching
+ * `AITool.execute(input)` and the return value is fed back as a `tool_result`.
+ * A thrown tool error or an unknown tool name becomes an error `tool_result`
+ * (recorded with `isError: true`) instead of aborting the run, so the model can
+ * recover. `run()` requires exactly one of `task` (a single user turn) or
+ * `messages` (a full history); it throws if neither — or both — is supplied.
+ *
+ * Every model turn streams by default (`input.stream` — set `false` to force
+ * non-streaming) and, when `input.cacheControl` is set, is passed through to
+ * `ai.chat()` on every turn so a provider that supports prompt caching (e.g.
+ * `@molecule/api-ai-anthropic`) doesn't re-bill the identical `system` + `tools`
+ * prefix on each of up to `maxSteps` turns. Note `onEvent` is only an
+ * INCREMENTAL live hook while streaming — with `stream: false` it fires once
+ * per turn with the whole response.
+ *
+ * Failure semantics (how to tell failure modes apart):
+ * - **Tool failure** (throwing `execute()`, unknown tool name) — NON-fatal:
+ *   recorded on the step with `isError: true` and fed back to the model.
+ * - **AI provider API failure** (rate limit, bad key, overload, network — the
+ *   `ai` bond emits an in-band `error` ChatEvent), **an abort, or any other
+ *   mid-run exception** — FATAL: `run()` rejects with an `AgentRunError`
+ *   (message text unchanged from a plain `Error`) carrying the `usage` and
+ *   `steps` accumulated across every turn that completed before the failure —
+ *   a caller that meters spend can book that partial usage instead of losing
+ *   it. `run()` never resolves with a silently empty `output`, so an empty
+ *   `result.output` means the model genuinely produced no text, not that the
+ *   API failed.
+ * - **Step budget exhausted** — resolves normally; `output` is the last
+ *   assistant text or an explicit "step budget exhausted" note.
+ *
+ * Swappable like any bond: replace this LLM agent with your own
+ * `AIAgentsProvider` via `bond('ai-agents', myProvider)` — nothing else changes.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './errors.js';
+export * from './provider.js';
+export * from './types.js';

package/dist/provider.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The default LLM-backed AI agents provider: a tool-calling loop over the
+ * bonded `ai` chat provider.
+ *
+ * This provider owns the agentic loop that used to live in the
+ * `@molecule/api-ai-agents` core. It composes the swappable `ai` chat bond
+ * (`@molecule/api-ai`): it calls the model, executes any tools the model
+ * requests, feeds the results back, and repeats until the model stops calling
+ * tools (or the `maxSteps` budget is exhausted). Living in a bond package (not
+ * the core) keeps the core interface-only.
+ *
+ * @module
+ */
+import './types.js';
+import type { AIAgentsProvider } from '@molecule/api-ai-agents';
+/**
+ * The LLM-backed AI agents provider: a tool-calling loop over the bonded `ai`
+ * chat provider.
+ *
+ * Bond it with `bond('ai-agents', provider)` and drive it with
+ * `requireProvider().run({ task, tools })`. Requires a bonded `ai` provider
+ * whose model supports tool use.
+ */
+export declare const provider: AIAgentsProvider;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,YAAY,CAAA;AAOnB,OAAO,KAAK,EAKV,gBAAgB,EACjB,MAAM,yBAAyB,CAAA;AAkHhC;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,EAAE,gBA2KtB,CAAA"}

package/dist/provider.js

@@ -0,0 +1,250 @@
+/**
+ * The default LLM-backed AI agents provider: a tool-calling loop over the
+ * bonded `ai` chat provider.
+ *
+ * This provider owns the agentic loop that used to live in the
+ * `@molecule/api-ai-agents` core. It composes the swappable `ai` chat bond
+ * (`@molecule/api-ai`): it calls the model, executes any tools the model
+ * requests, feeds the results back, and repeats until the model stops calling
+ * tools (or the `maxSteps` budget is exhausted). Living in a bond package (not
+ * the core) keeps the core interface-only.
+ *
+ * @module
+ */
+// Side-effect import: registers the `stream`/`cacheControl` module
+// augmentation on `AgentRunInput` (see types.ts) so `input.stream` and
+// `input.cacheControl` below are typed, not `any`.
+import './types.js';
+import { getProviderByName as getAiProviderByName, requireProvider as requireAiProvider, } from '@molecule/api-ai';
+import { t } from '@molecule/api-i18n';
+import { AgentRunError } from './errors.js';
+/**
+ * Adds one usage delta into a running total (input/output summed, cache fields
+ * carried when present).
+ *
+ * @param total - The running total, mutated in place.
+ * @param delta - The usage to add.
+ */
+function addUsage(total, delta) {
+    total.inputTokens += delta.inputTokens ?? 0;
+    total.outputTokens += delta.outputTokens ?? 0;
+    if (delta.cacheCreationInputTokens != null) {
+        total.cacheCreationInputTokens =
+            (total.cacheCreationInputTokens ?? 0) + delta.cacheCreationInputTokens;
+    }
+    if (delta.cacheReadInputTokens != null) {
+        total.cacheReadInputTokens = (total.cacheReadInputTokens ?? 0) + delta.cacheReadInputTokens;
+    }
+}
+/**
+ * Stringifies a tool result for a `tool_result` content block.
+ *
+ * @param result - The value returned by a tool's `execute()`.
+ * @returns A string representation suitable for the model.
+ */
+function stringifyResult(result) {
+    if (typeof result === 'string')
+        return result;
+    try {
+        // JSON.stringify returns `undefined` for `undefined`/functions/symbols —
+        // fall back to String() so the block content is always a string.
+        return JSON.stringify(result) ?? String(result);
+    }
+    catch (_error) {
+        // Circular structures throw; a plain String() is the best available
+        // representation for the model. Intentionally not fatal to the run.
+        return String(result);
+    }
+}
+/**
+ * Drains a single chat stream, accumulating text and tool calls, forwarding
+ * every event to `onEvent`, and summing `done.usage`.
+ *
+ * @param stream - The async iterable of chat events from `ai.chat()`.
+ * @param onEvent - Optional hook invoked for every event.
+ * @returns The accumulated text, tool calls, and usage for this turn.
+ */
+async function drainStream(stream, onEvent) {
+    let text = '';
+    const toolUses = [];
+    const usage = { inputTokens: 0, outputTokens: 0 };
+    let errorMessage;
+    let sawDone = false;
+    let lastSnapshot;
+    for await (const event of stream) {
+        onEvent?.(event);
+        switch (event.type) {
+            case 'text':
+                text += event.content;
+                break;
+            case 'tool_use':
+                toolUses.push({ id: event.id, name: event.name, input: event.input });
+                break;
+            case 'usage':
+                // Incremental snapshot (latest wins) — booked below if the stream ends
+                // without a `done` (metering contract in @molecule/api-ai ChatEvent).
+                lastSnapshot = event.usage;
+                break;
+            case 'error':
+                // Keep the FIRST error; providers emit one sanitized error then return.
+                errorMessage ??= event.message;
+                break;
+            case 'done':
+                sawDone = true;
+                addUsage(usage, event.usage);
+                break;
+            default:
+                break;
+        }
+    }
+    // METERING CONTRACT: a stream cut without a `done` (provider error event,
+    // upstream disconnect) still billed the tokens reported so far — book the
+    // latest snapshot instead of silently dropping the turn's spend.
+    if (!sawDone && lastSnapshot) {
+        addUsage(usage, lastSnapshot);
+    }
+    return { text, toolUses, usage, errorMessage };
+}
+/**
+ * The LLM-backed AI agents provider: a tool-calling loop over the bonded `ai`
+ * chat provider.
+ *
+ * Bond it with `bond('ai-agents', provider)` and drive it with
+ * `requireProvider().run({ task, tools })`. Requires a bonded `ai` provider
+ * whose model supports tool use.
+ */
+export const provider = {
+    name: 'llm',
+    async run(input) {
+        if (!input.task && !(input.messages && input.messages.length > 0)) {
+            throw new Error(t('ai-agents.error.noTaskOrMessages', undefined, {
+                defaultValue: 'AgentRunInput requires a `task` string or a non-empty `messages` array.',
+            }));
+        }
+        // The contract is EXACTLY one of task/messages (see AgentRunInput). The old
+        // behavior silently discarded `task` when both were passed — an executor's
+        // task vanished with no signal. Fail loudly instead.
+        if (input.task && input.messages && input.messages.length > 0) {
+            throw new Error(t('ai-agents.error.bothTaskAndMessages', undefined, {
+                defaultValue: 'AgentRunInput accepts either `task` or `messages`, not both. Put the task in the `messages` history (as the last user message) or drop one of the two.',
+            }));
+        }
+        const ai = input.provider ? getAiProviderByName(input.provider) : requireAiProvider();
+        if (!ai) {
+            throw new Error(t('ai-agents.error.aiProviderNotFound', { name: input.provider ?? '' }, { defaultValue: `AI provider "${input.provider}" is not bonded.` }));
+        }
+        const messages = input.messages
+            ? [...input.messages]
+            : [{ role: 'user', content: input.task }];
+        const maxSteps = input.maxSteps ?? 10;
+        const steps = [];
+        const usage = { inputTokens: 0, outputTokens: 0 };
+        let lastText = '';
+        // Everything below can fail partway through a multi-turn run (a provider
+        // API error, an abort, or an unexpected throw from ai.chat() itself —
+        // e.g. a signal-aborted fetch). A plain rejection would silently drop
+        // every prior turn's `usage`/`steps`: a run that dies on step 8 would
+        // under-meter 7 turns of real billed spend. Wrap the whole loop so ANY
+        // failure re-throws as an AgentRunError carrying what was accumulated so
+        // far — `error.message` is unchanged, so existing catch sites keep
+        // working; only callers that want the partial usage/steps need to check
+        // `instanceof AgentRunError`.
+        try {
+            for (let step = 0; step < maxSteps; step++) {
+                const turn = await drainStream(ai.chat({
+                    messages,
+                    system: input.system,
+                    tools: input.tools,
+                    model: input.model,
+                    maxTokens: input.maxTokens,
+                    temperature: input.temperature,
+                    // Defaults to streaming (see the `stream` augmentation in
+                    // types.ts): onEvent is a LIVE hook, and non-streaming requests
+                    // with large outputs (a big tool input at a raised maxTokens) are
+                    // exactly what provider docs warn will time out over HTTP.
+                    // drainStream already folds streamed events correctly, so there
+                    // is no extra cost to defaulting streaming on. Set
+                    // `input.stream: false` to force non-streaming.
+                    stream: input.stream !== false,
+                    // Prompt-cache breakpoint hint: the system+tools prefix is
+                    // identical across turns, so passing this through avoids
+                    // re-billing the full (growing) prompt on every one of up to
+                    // maxSteps turns. Providers without cache support ignore it.
+                    cacheControl: input.cacheControl,
+                    signal: input.signal,
+                }), input.onEvent);
+                addUsage(usage, turn.usage);
+                // A provider API failure (rate limit, auth, overload, network) arrives
+                // as an in-band `error` ChatEvent — the stream ends without text or
+                // tools. Rejecting here disambiguates "the AI provider failed" from
+                // "the model legitimately answered nothing": the old fall-through
+                // returned { output: '', steps, usage } as if the run succeeded, and
+                // callers debugging the empty output had no signal that the API ever
+                // errored.
+                if (turn.errorMessage !== undefined) {
+                    throw new Error(t('ai-agents.error.providerError', { message: turn.errorMessage }, { defaultValue: `AI provider error during agent run: ${turn.errorMessage}` }));
+                }
+                if (turn.text)
+                    lastText = turn.text;
+                // Append the assistant turn: a text block (if any) + one tool_use block
+                // per requested tool call.
+                const assistantContent = [];
+                if (turn.text)
+                    assistantContent.push({ type: 'text', text: turn.text });
+                for (const tu of turn.toolUses) {
+                    assistantContent.push({ type: 'tool_use', id: tu.id, name: tu.name, input: tu.input });
+                }
+                messages.push({ role: 'assistant', content: assistantContent });
+                if (turn.toolUses.length === 0) {
+                    // No tools requested — the model is done.
+                    return { output: turn.text, steps, usage };
+                }
+                // Execute each requested tool and build the tool_result turn.
+                const resultBlocks = [];
+                const toolCalls = [];
+                for (const tu of turn.toolUses) {
+                    if (input.signal?.aborted) {
+                        throw new Error(t('ai-agents.error.aborted', undefined, {
+                            defaultValue: 'Agent run aborted before tool execution completed.',
+                        }));
+                    }
+                    const tool = input.tools?.find((candidate) => candidate.name === tu.name);
+                    let result;
+                    let isError = false;
+                    if (!tool) {
+                        result = `Error: unknown tool "${tu.name}".`;
+                        isError = true;
+                    }
+                    else {
+                        try {
+                            result = await tool.execute(tu.input);
+                        }
+                        catch (error) {
+                            // The model can recover from a failed tool call; surface the error
+                            // back to it as a tool_result rather than aborting the whole run.
+                            result = `Error: ${error instanceof Error ? error.message : String(error)}`;
+                            isError = true;
+                        }
+                    }
+                    toolCalls.push({ id: tu.id, name: tu.name, input: tu.input, result, isError });
+                    resultBlocks.push({
+                        type: 'tool_result',
+                        tool_use_id: tu.id,
+                        content: stringifyResult(result),
+                    });
+                }
+                messages.push({ role: 'user', content: resultBlocks });
+                steps.push({ text: turn.text || undefined, toolCalls });
+            }
+            // Step budget exhausted while the model was still calling tools.
+            const output = lastText ||
+                t('ai-agents.stepBudgetExhausted', undefined, {
+                    defaultValue: 'Agent stopped: step budget exhausted before a final answer.',
+                });
+            return { output, steps, usage };
+        }
+        catch (error) {
+            throw new AgentRunError(error instanceof Error ? error.message : String(error), usage, steps, { cause: error });
+        }
+    },
+};

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Module augmentation: extends the core `@molecule/api-ai-agents` contract's
+ * `AgentRunInput` with two options this bond's `run()` honors.
+ *
+ * @remarks
+ * Both fields are ADDITIVE ONLY — they never widen or erase an existing
+ * `AgentRunInput` field — and are consumed exclusively by this bond's `run()`
+ * implementation; a different `AIAgentsProvider` bond is free to ignore them.
+ * Any file that imports `@molecule/api-ai-agents-llm` (directly, or
+ * transitively by bonding its `provider`) sees the merged `AgentRunInput`
+ * type, matching the shape `@molecule/api-ai`'s `ChatParams` already accepts
+ * for `stream` and `cacheControl`.
+ *
+ * @module
+ */
+import '@molecule/api-ai-agents';
+declare module '@molecule/api-ai-agents' {
+    interface AgentRunInput {
+        /**
+         * Whether each model turn streams its response (default `true`).
+         *
+         * The loop previously hardcoded `stream: false` on every turn even
+         * though `onEvent` exists specifically as a live hook — with streaming
+         * off, every provider bond parses the FULL response in one shot, so
+         * `onEvent` only ever fires once per turn instead of incrementally.
+         * That also risks HTTP timeouts on a large non-streamed turn (e.g. a
+         * big tool input at a raised `maxTokens`) — exactly the case provider
+         * docs recommend streaming to avoid. `drainStream` already handles
+         * streamed events correctly (text accumulation, `tool_use`, `done` all
+         * fold the same way), so there is no extra work to opt in. Set `false`
+         * to force non-streaming (e.g. a provider/proxy that cannot forward
+         * SSE) — `onEvent` then only fires once per turn.
+         */
+        stream?: boolean;
+        /**
+         * Prompt-cache breakpoint hint passed through to `ai.chat()` on every
+         * turn. The loop's `system` + `tools` prefix is identical across turns,
+         * so caching it avoids re-billing the full (growing) prompt on each of
+         * up to `maxSteps` turns. Only providers that support prompt caching
+         * (e.g. `@molecule/api-ai-anthropic`) act on it; others ignore it.
+         */
+        cacheControl?: {
+            type: 'ephemeral';
+        };
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,yBAAyB,CAAA;AAEhC,OAAO,QAAQ,yBAAyB,CAAC;IACvC,UAAU,aAAa;QACrB;;;;;;;;;;;;;;WAcG;QACH,MAAM,CAAC,EAAE,OAAO,CAAA;QAChB;;;;;;WAMG;QACH,YAAY,CAAC,EAAE;YAAE,IAAI,EAAE,WAAW,CAAA;SAAE,CAAA;KACrC;CACF"}

package/dist/types.js

@@ -0,0 +1,18 @@
+/**
+ * Module augmentation: extends the core `@molecule/api-ai-agents` contract's
+ * `AgentRunInput` with two options this bond's `run()` honors.
+ *
+ * @remarks
+ * Both fields are ADDITIVE ONLY — they never widen or erase an existing
+ * `AgentRunInput` field — and are consumed exclusively by this bond's `run()`
+ * implementation; a different `AIAgentsProvider` bond is free to ignore them.
+ * Any file that imports `@molecule/api-ai-agents-llm` (directly, or
+ * transitively by bonding its `provider`) sees the merged `AgentRunInput`
+ * type, matching the shape `@molecule/api-ai`'s `ChatParams` already accepts
+ * for `stream` and `cacheControl`.
+ *
+ * @module
+ */
+// Side-effect import: makes this file a module augmenting
+// `@molecule/api-ai-agents` rather than a standalone global script.
+import '@molecule/api-ai-agents';

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@molecule/api-ai-agents-llm",
+  "version": "1.0.0",
+  "description": "LLM-backed AI agents provider for molecule.dev — a tool-calling loop over the swappable @molecule/api-ai chat bond",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "molecule",
+    "ai",
+    "agents",
+    "tools",
+    "agentic",
+    "llm"
+  ],
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@molecule/api-ai": "^1.0.0",
+    "@molecule/api-ai-agents": "^1.0.0",
+    "@molecule/api-i18n": "^1.0.0"
+  },
+  "devDependencies": {
+    "@molecule/api-ai": "1.0.0",
+    "@molecule/api-ai-agents": "1.0.0",
+    "@molecule/api-bond": "1.0.0",
+    "@molecule/api-i18n": "1.0.0",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  }
+}