@loomwork/llm 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,202 @@
+                                 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
+      (an example is provided in the Appendix below).
+
+      "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. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to 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. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by 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
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   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, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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/NOTICE

@@ -0,0 +1,8 @@
+Loom
+Copyright 2026 Sushil Chhetri
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this project except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# @loomwork/llm
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A provider-agnostic model interface (`LlmProvider`), three HTTP providers (Anthropic, OpenAI, Gemini),
+and `createLlmEffect`, which wraps a provider as a journaled effect. Use it when a flow needs a model
+call that is recorded in the log, replayed instead of re-called, and checked before it leaves the
+process. The providers use `fetch` directly and add no vendor SDK. For tool-using loops see
+`@loomwork/agent`; for routing across several models see `@loomwork/reasoning`.
+
+```ts
+import { tainted } from "@loomwork/classify";
+import { AnthropicProvider, UNTRUSTED_CONTENT_SYSTEM_NOTE, createLlmEffect } from "@loomwork/llm";
+
+const provider = new AnthropicProvider({ model: "claude-opus-4-8" }); // key from ANTHROPIC_API_KEY
+
+export const summarize = createLlmEffect<{ ticket: string }, string>({
+  provider,
+  buildRequest: ({ ticket }) => ({
+    system: `You summarize support tickets.\n${UNTRUSTED_CONTENT_SYSTEM_NOTE}`,
+    maxTokens: 300,
+    // Tainted text is fenced as data before it reaches the model.
+    messages: [{ role: "user", content: tainted(ticket, "customer-email") }],
+  }),
+  parseResponse: (response) => response.content, // the default
+  stream: true,
+});
+```
+
+## Surface
+
+- **Providers.** `AnthropicProvider`, `OpenAiProvider`, `GeminiProvider`, each taking
+  `{ apiKey?, model?, baseUrl?, capabilities?, headers? }`. Anything with `complete(request)` (and
+  optionally `stream`) is an `LlmProvider`, so a test double or another vendor needs no adapter.
+- **The effect.** `createLlmEffect({ provider, buildRequest, parseResponse?, stream?, resolveContent?,
+  reasoning?, onDelta?, guard? })`.
+- **Messages.** `content` is a string, a tainted string, or an array of parts: text, image, audio,
+  file (by `ref` address or inline base64), `tool_use`, `tool_result`. `textOf`, `toParts` and
+  `assistantMessageOf` read and build them.
+- **Capabilities.** A provider declares which media types it takes; a request outside that throws
+  `UnsupportedModalityError` before any network call.
+- **Reasoning capture.** `reasoning: { store }` keeps model reasoning text in a sidecar store, off the
+  step value; `readReasoning` reads it back (ADR 0133).
+- **Streaming.** `collectStream`, `assembleStream`, `LLM_INTERRUPTED` (a cut-off generation keeps its
+  partial text as a typed failure).
+- **Errors.** `LlmHttpError` (`status`, `kind: "auth"`), `LlmResponseLimitError`, `LlmStreamError`,
+  `InvalidLlmRequestError`, `OversizedInlinePartError`, `UntrustedContentError`.
+
+## Behaviour that surprises people
+
+- **Streaming is opt-in.** `stream` defaults to off; with it on, a provider that has no `stream`
+  falls back to `complete`. Deltas passed to `onDelta` are not journaled and are not replayed.
+- **Tainted content may appear only in a `user` message.** Anywhere else `guardRequest` throws
+  `UntrustedContentError`. In a `user` message it is wrapped in an `<untrusted-input>` fence. The fence
+  is a label the model can still be talked across, and it only helps if your system prompt says what it
+  means: add `UNTRUSTED_CONTENT_SYSTEM_NOTE` yourself, the library does not write your prompt.
+- **Media is claim-checked.** The journaled request holds a ref's address, not bytes. A `ref` needs a
+  `resolveContent` that authorizes the caller, or the call throws `UnresolvedContentError` before
+  any network call. Inline data is capped (64 KiB per part, 256 KiB per request by default).
+- **Media capability is an allowlist by model id.** The shipped providers declare image/file support
+  only for model ids they recognise, and none when `baseUrl` is not the vendor default.
+  Pass `capabilities` to override.
+- **Constructors do not check the key.** The Anthropic provider reads `ANTHROPIC_API_KEY` when no
+  `apiKey` is given and falls back to an empty string; the failure arrives as an `LlmHttpError` on
+  the first call.
+- **Redirects are never followed**, since that would re-send the body and credentials. The response
+  body of a failed call is not put on the error, because it can echo the prompt. Response, stream and
+  line sizes are bounded (defaults 8 MiB, 128 MiB, 1 MiB, adjustable per provider).
+- **`headers` cannot override** the headers a provider sets itself (`x-api-key`, `authorization`, and
+  similar); doing so throws at construction.
+
+## See also
+
+- API reference: section "`@loomwork/llm` — provider-agnostic models" in
+  [docs/api-reference.org](../../docs/api-reference.org).
+- Guide: [isolation and untrusted content](../../docs/user-guide/isolation-and-untrusted-content.md).
+- ADRs: [0085 untrusted content](../../docs/adr/0085-untrusted-content-integrity-axis.md),
+  [0120 content parts](../../docs/adr/0120-llm-content-parts-and-tool-threading.md),
+  [0060 typed failures](../../docs/adr/0060-typed-failure-channels.md).
+
+## Install
+
+Unpublished for now: inside this repo use `workspace:*`; from a sibling checkout use a `link:` override (see [AGENTS.md](../../AGENTS.md)).

package/dist/assembleStream.d.ts

@@ -0,0 +1,95 @@
+import type { LlmResponse, LlmStreamChunk } from "./types";
+/** Thrown when a stream violates its shape contract (no terminal chunk, or more than one). */
+export declare class MalformedStreamError extends Error {
+    constructor(message: string);
+}
+/**
+ * Fold a completed stream into the `LlmResponse` it represents.
+ *
+ * `stopReason` defaults to `"end_turn"` when the provider does not report one —
+ * the same value `complete` yields for an unrecognised stop reason, so a
+ * text-only streaming provider assembles to the same shape it always would.
+ * `toolCalls` and `usage` stay ABSENT rather than becoming empty: `undefined`
+ * means "not reported", `[]` would mean "reported none", and metering must be
+ * able to tell a provider that omits usage from one that charged nothing.
+ */
+export declare function assembleStream(chunks: readonly LlmStreamChunk[]): LlmResponse;
+/**
+ * The channel an interrupted generation fails on (ADR 0060). Its payload is
+ * {@link InterruptedGeneration} — the text produced before the abort, which is
+ * usually the most expensive artifact the turn made and was previously discarded:
+ * `complete` + abort throws with the response body unread, so there is nothing to
+ * keep. Only a call that has been accumulating deltas has a partial to hand back.
+ *
+ * Declare it in the owning contract's `errors:` map to get the ADR 0060 treatment
+ * (recorded as `STEP_FAILED { channel, payload }`, substituted on replay);
+ * undeclared, it degrades to an ordinary failure exactly as before.
+ */
+export declare const LLM_INTERRUPTED = "llmInterrupted";
+export interface InterruptedGeneration {
+    /** Deltas received before the abort, concatenated. May be empty. */
+    content: string;
+    /** Usage, if the provider reported any before the interruption. */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+/** What a stream has produced so far, offered to {@link CollectStreamOptions.guard}. */
+export interface StreamProgress {
+    /** Everything received so far, concatenated. */
+    text: string;
+    /** Number of deltas received. */
+    deltas: number;
+    /** Usage, if the provider has reported any yet. Most report only at the end. */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+export interface CollectStreamOptions {
+    /** When this is aborted, the partial is captured instead of being thrown away. */
+    signal?: AbortSignal;
+    /** Transient sink for deltas as they arrive. Never journaled by this function. */
+    onDelta?: (delta: string) => void;
+    /**
+     * ADR 0133 D6 - transient sink for readable reasoning increments, a channel SEPARATE from
+     * `onDelta` (and never part of `guard`'s `text`, nor of the interrupted partial). Never journaled.
+     */
+    onReasoningDelta?: (delta: string) => void;
+    /** R5 — transient sink for tool-call input fragments. Never journaled. */
+    onToolDelta?: (delta: {
+        id: string;
+        name?: string;
+        inputDelta: string;
+    }) => void;
+    /**
+     * Called after every delta. THROW to sever the generation mid-flight — the
+     * throw propagates, the `for await` exits, and the underlying HTTP call is
+     * released.
+     *
+     * This is the seam K8.4 needs and the only one a stream can offer: providers
+     * report usage once at the end, so the sole thing observable *while* a
+     * generation runs is its own output. A guard that throws here is the
+     * difference between paying for a runaway generation and stopping it.
+     *
+     * Deliberately generic — no budget vocabulary lives in this package.
+     * `@loomwork/middleware`'s `streamTokenBudget` builds the budget-shaped one.
+     */
+    guard?: (progress: StreamProgress) => void;
+}
+/**
+ * `assembleStream` over a live stream — drains it, feeds deltas out as they
+ * arrive, and folds what arrived.
+ *
+ * With a `signal`, an abort mid-generation is NOT a lost generation: what was
+ * produced is captured as an {@link LLM_INTERRUPTED} typed failure. Anything else
+ * propagates untyped, so a transport failure stays one — K9 retries the turn
+ * whole, and a network blip never reads as a user stop.
+ *
+ * Shared by `createLlmEffect` and `AgentRunner` deliberately: two copies of an
+ * accumulate-and-capture loop is two chances to differ about what "interrupted"
+ * means, and the whole point is that the partial survives identically either way.
+ */
+export declare function collectStream(stream: AsyncIterable<LlmStreamChunk>, options?: CollectStreamOptions): Promise<LlmResponse>;
+//# sourceMappingURL=assembleStream.d.ts.map

package/dist/assembleStream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assembleStream.d.ts","sourceRoot":"","sources":["../src/assembleStream.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAc3D,8FAA8F;AAC9F,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,GAAG,WAAW,CAsB7E;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,mBAAmB,CAAC;AAEhD,MAAM,WAAW,qBAAqB;IACpC,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,KAAK,CAAC,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;CACvD;AAED,wFAAwF;AACxF,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,KAAK,CAAC,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;CACvD;AAED,MAAM,WAAW,oBAAoB;IACnC,kFAAkF;IAClF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,kFAAkF;IAClF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,0EAA0E;IAC1E,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACjF;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,CAAC;CAC5C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,EACrC,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,WAAW,CAAC,CAuFtB"}

package/dist/assembleStream.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLM_INTERRUPTED = exports.MalformedStreamError = void 0;
+exports.assembleStream = assembleStream;
+exports.collectStream = collectStream;
+const core_1 = require("@loomwork/core");
+// ── The streamed-≡-completed contract ─────────────────────────────────────────
+//
+// Two paths to one outcome need a rule saying they agree, or they drift and the
+// drift shows up as an agent that behaves differently once streaming is switched
+// on. ADR 0059 D1 set the precedent for content: a streamed address MUST equal
+// the whole-buffer address. This is the same discipline for the model call —
+// assembling a stream MUST produce what `complete` would have returned.
+//
+// Assembly is deliberately dumb: concatenate the deltas, take the outcome fields
+// from the terminal chunk. Anything cleverer would be a place for the two paths
+// to disagree.
+/** Thrown when a stream violates its shape contract (no terminal chunk, or more than one). */
+class MalformedStreamError extends Error {
+    constructor(message) {
+        super(`Malformed LLM stream: ${message}`);
+        this.name = "MalformedStreamError";
+    }
+}
+exports.MalformedStreamError = MalformedStreamError;
+/**
+ * Fold a completed stream into the `LlmResponse` it represents.
+ *
+ * `stopReason` defaults to `"end_turn"` when the provider does not report one —
+ * the same value `complete` yields for an unrecognised stop reason, so a
+ * text-only streaming provider assembles to the same shape it always would.
+ * `toolCalls` and `usage` stay ABSENT rather than becoming empty: `undefined`
+ * means "not reported", `[]` would mean "reported none", and metering must be
+ * able to tell a provider that omits usage from one that charged nothing.
+ */
+function assembleStream(chunks) {
+    const terminals = chunks.filter((c) => c.done);
+    if (terminals.length === 0) {
+        throw new MalformedStreamError("no terminal chunk (none had done: true)");
+    }
+    if (terminals.length > 1) {
+        throw new MalformedStreamError(`${terminals.length} terminal chunks (exactly one is allowed)`);
+    }
+    const last = chunks[chunks.length - 1];
+    if (last?.done !== true) {
+        throw new MalformedStreamError("the terminal chunk is not last");
+    }
+    const content = chunks.map((c) => c.delta).join("");
+    return {
+        content,
+        ...(last.toolCalls !== undefined && { toolCalls: last.toolCalls }),
+        stopReason: last.stopReason ?? "end_turn",
+        ...(last.usage !== undefined && { usage: last.usage }),
+        ...(last.reasoning !== undefined && { reasoning: last.reasoning }),
+        ...(last.layout !== undefined && { layout: last.layout }),
+    };
+}
+/**
+ * The channel an interrupted generation fails on (ADR 0060). Its payload is
+ * {@link InterruptedGeneration} — the text produced before the abort, which is
+ * usually the most expensive artifact the turn made and was previously discarded:
+ * `complete` + abort throws with the response body unread, so there is nothing to
+ * keep. Only a call that has been accumulating deltas has a partial to hand back.
+ *
+ * Declare it in the owning contract's `errors:` map to get the ADR 0060 treatment
+ * (recorded as `STEP_FAILED { channel, payload }`, substituted on replay);
+ * undeclared, it degrades to an ordinary failure exactly as before.
+ */
+exports.LLM_INTERRUPTED = "llmInterrupted";
+/**
+ * `assembleStream` over a live stream — drains it, feeds deltas out as they
+ * arrive, and folds what arrived.
+ *
+ * With a `signal`, an abort mid-generation is NOT a lost generation: what was
+ * produced is captured as an {@link LLM_INTERRUPTED} typed failure. Anything else
+ * propagates untyped, so a transport failure stays one — K9 retries the turn
+ * whole, and a network blip never reads as a user stop.
+ *
+ * Shared by `createLlmEffect` and `AgentRunner` deliberately: two copies of an
+ * accumulate-and-capture loop is two chances to differ about what "interrupted"
+ * means, and the whole point is that the partial survives identically either way.
+ */
+async function collectStream(stream, options = {}) {
+    // Only three facts about the stream survive the fold — the text, the terminal
+    // chunk's outcome, and the shape checks — so nothing retains the chunks
+    // themselves. A long generation would otherwise hold one small object per
+    // delta for its whole duration, times every concurrent stream.
+    let count = 0;
+    let terminals = 0;
+    let last;
+    // Running state, maintained per chunk rather than recomputed per chunk. The
+    // first cut rebuilt the text with `chunks.map(...).join("")` and rescanned for
+    // usage on EVERY delta, which is O(n²) over a generation: 4,000 deltas cost
+    // ~90ms of pure copying, and `streamTokenBudget`'s `checkEvery` could not help
+    // because the expensive part ran before the guard was ever consulted.
+    // Appending to a string is amortized O(1); tracking the last reported usage is
+    // O(1). The guard is now the only cost per delta.
+    let text = "";
+    let usage;
+    // A guard breach is NOT an interruption, and the two are easy to confuse: a
+    // guard that severs typically aborts the execution too, so by the time the
+    // catch below runs, `signal.aborted` is true and the budget error would be
+    // rewritten into "interrupted" — losing the reason the generation stopped.
+    // The caller has to be able to tell "a human stopped this" from "this cost too
+    // much", so the guard's own error is remembered and rethrown untouched.
+    let guardError;
+    try {
+        for await (const chunk of stream) {
+            count += 1;
+            last = chunk;
+            if (chunk.done)
+                terminals += 1;
+            text += chunk.delta;
+            // Providers report usage late; keep the most recent one seen.
+            if (chunk.usage !== undefined)
+                usage = chunk.usage;
+            // The guard runs BEFORE delivery: a delta that breaches it severs the stream
+            // and is never handed to a sink (ADR 0119 — a live tail must not see what the
+            // guard exists to stop).
+            if (options.guard !== undefined) {
+                try {
+                    options.guard({
+                        text,
+                        deltas: count,
+                        ...(usage !== undefined && { usage }),
+                    });
+                }
+                catch (err) {
+                    guardError = err;
+                    throw err;
+                }
+            }
+            // A provider that ignores the signal keeps yielding after an abort; checking
+            // here severs it at the next chunk instead of delivering text to a caller who
+            // has gone (the catch below turns it into the LLM_INTERRUPTED partial).
+            if (options.signal?.aborted === true) {
+                throw options.signal.reason instanceof Error
+                    ? options.signal.reason
+                    : new Error("generation aborted");
+            }
+            if (chunk.delta !== "")
+                options.onDelta?.(chunk.delta);
+            if (chunk.toolDelta !== undefined)
+                options.onToolDelta?.(chunk.toolDelta);
+            if (chunk.reasoningDelta !== undefined && chunk.reasoningDelta !== "") {
+                options.onReasoningDelta?.(chunk.reasoningDelta);
+            }
+        }
+    }
+    catch (err) {
+        if (guardError !== undefined)
+            throw guardError;
+        if (options.signal?.aborted === true) {
+            const partial = {
+                content: text,
+                ...(usage !== undefined && { usage }),
+            };
+            (0, core_1.fail)(exports.LLM_INTERRUPTED, partial, "generation interrupted");
+        }
+        throw err;
+    }
+    // Same contract as `assembleStream`, checked against the counters rather than
+    // a retained array.
+    if (terminals === 0)
+        throw new MalformedStreamError("no terminal chunk (none had done: true)");
+    if (terminals > 1) {
+        throw new MalformedStreamError(`${terminals} terminal chunks (exactly one is allowed)`);
+    }
+    if (last?.done !== true)
+        throw new MalformedStreamError("the terminal chunk is not last");
+    return {
+        content: text,
+        ...(last.toolCalls !== undefined && { toolCalls: last.toolCalls }),
+        stopReason: last.stopReason ?? "end_turn",
+        ...(last.usage !== undefined && { usage: last.usage }),
+        ...(last.reasoning !== undefined && { reasoning: last.reasoning }),
+        ...(last.layout !== undefined && { layout: last.layout }),
+    };
+}
+//# sourceMappingURL=assembleStream.js.map

package/dist/assembleStream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assembleStream.js","sourceRoot":"","sources":["../src/assembleStream.ts"],"names":[],"mappings":"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"}

package/dist/capabilities.d.ts

@@ -0,0 +1,43 @@
+import type { LlmMediaPart, LlmModality } from "./parts";
+import type { LlmRequest } from "./types";
+/**
+ * The media types a provider accepts for one modality: a list of exact types
+ * (`image/png`), type wildcards (`image/*`), or `"*"` for any.
+ */
+export type MediaTypeSet = readonly string[];
+/** Text and tool calls are always supported; media is opt-in per modality. */
+export interface LlmCapabilities {
+    image?: MediaTypeSet;
+    audio?: MediaTypeSet;
+    file?: MediaTypeSet;
+    /** ADR 0133 - the provider can return model reasoning. Drives the boot warning when no reasoning store is configured. */
+    reasoning?: boolean;
+}
+/** Thrown, before any network call, when a request carries a modality the provider did not declare. */
+export declare class UnsupportedModalityError extends Error {
+    readonly modality: LlmModality;
+    readonly mediaType: string;
+    readonly provider: string | undefined;
+    constructor(modality: LlmModality, mediaType: string, provider?: string);
+}
+export declare function mediaTypeAccepted(set: MediaTypeSet | undefined, mediaType: string): boolean;
+/** Every media part in a request, in order (including those inside `tool_result`s). */
+export declare function requestMediaParts(request: Pick<LlmRequest, "messages">): Generator<LlmMediaPart>;
+/**
+ * Refuse a request that uses a modality / media type the provider has not declared.
+ * Pure and cheap (one walk); providers call it at the top of `complete` / `stream` and
+ * `createLlmEffect` calls it before resolving any content, so the refusal precedes
+ * every byte of I/O.
+ */
+export declare function assertRequestSupported(request: Pick<LlmRequest, "messages">, capabilities: LlmCapabilities | undefined, provider?: string): void;
+/**
+ * The modalities a shipped provider declares for `model`: an ALLOWLIST. `base` only when the id
+ * matches a family known to take media (`allow`); every other id — unknown, older, a local alias —
+ * declares nothing, so a model that cannot take an image is refused locally instead of 400'd by the
+ * API, and a new family needs one line here before it is trusted with media. `config.capabilities`
+ * always wins (`capabilities: {}` = text-only). A provider on a non-default `baseUrl` (an
+ * OpenAI-compatible server) declares nothing either, since the model id says nothing about what is
+ * behind it; pass `capabilities` to turn media on.
+ */
+export declare function capabilitiesForModel(model: string, base: LlmCapabilities, allow: readonly RegExp[]): LlmCapabilities;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACzE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAI1C;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,MAAM,EAAE,CAAC;AAE7C,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,yHAAyH;IACzH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,uGAAuG;AACvG,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;gBAC1B,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM;CASxE;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAQ3F;AAWD,uFAAuF;AACvF,wBAAiB,iBAAiB,CAAC,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,GAAG,SAAS,CAAC,YAAY,CAAC,CAIjG;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,EACrC,YAAY,EAAE,eAAe,GAAG,SAAS,EACzC,QAAQ,CAAC,EAAE,MAAM,GAChB,IAAI,CAMN;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,eAAe,CAEjB"}