@owlmeans/llm 0.1.14

package/README.md

@@ -0,0 +1,193 @@
+# @owlmeans/llm
+
+LLM inference runtime for OwlMeans applications: a resilient four-method model over any
+LangChain chat model, a provider-plugin layer, a model factory service, and an execution
+abstraction that resolves models from an inheritable policy.
+
+## Overview
+
+- **Model** — `ask` / `talk` / `invoke` / `request` with streaming under an idle deadline,
+  retry with an escalating output budget, schema validation and coercion, observability
+  and full diagnostics when a call returns nothing usable
+- **Plugins** — everything provider-specific (client construction, retry refinement,
+  structured-output mode, `tool_choice` spelling, prompt caching, fatal-error rules) lives
+  in a replaceable `LlmPlugin`; Anthropic, OpenAI and OpenAI-compatible ship built in
+- **Service** — `LlmService` builds and memoizes models from a config list, with preset
+  inheritance and a stronger `fallback` model attached for retry escalation
+- **Execution** — frozen, three-level (`Project` → `Task` → `Helper`) execution objects
+  carrying a `ModelPolicy`, plus snapshot / restore / checkpoint for resumable workflows
+
+## Installation
+
+```bash
+bun add @owlmeans/llm @owlmeans/llm-common
+bun add @langchain/core @langchain/openai @langchain/anthropic   # peer dependencies
+```
+
+The `@langchain/*` packages are **peer dependencies** on purpose: model instances cross the
+package boundary, and two copies of a class with protected members are nominally distinct
+types. Your app must provide exactly one copy.
+
+## Usage
+
+### Resolve a model and talk to it
+
+```typescript
+import { makeLlmService, makeLlmModel } from '@owlmeans/llm'
+import { ModelProvider } from '@owlmeans/llm-common'
+
+const llm = makeLlmService({
+  models: () => [{
+    alias: 'analyst',
+    provider: ModelProvider.Compatible,
+    model: 'z-ai/glm-5.1',
+    secret: process.env.OPENROUTER_SECRET!,
+    baseUrl: 'https://openrouter.ai/api/v1',
+    maxTokens: 8192,
+    maxTokensCap: 32000,
+    reasoning: { max_tokens: 1024 },
+  }],
+})
+
+const model = makeLlmModel(
+  { model: llm.getModel('analyst'), purpose: { type: 'analysis' } },
+  spectator,          // any { log, captureNull? } sink
+)
+
+const text = await model.ask('Summarise this changelog', { action: 'summarise' })
+const spec = await model.invoke('Describe the app', SpecSchema, { action: 'spec' })
+```
+
+### Drive it through an execution
+
+An execution carries the policy, so a caller never picks a model by name:
+
+```typescript
+import { appendExecutionService, appendLlmService, DEFAULT_EFFORT } from '@owlmeans/llm'
+import { ExecutionEffort } from '@owlmeans/llm-common'
+
+appendLlmService(context, { models: () => configs })
+appendExecutionService(context)
+
+const root = context.executions().root({
+  models: () => context.llm(),
+  policy: { effort: DEFAULT_EFFORT },
+  purpose: { type: 'ingest' },
+})
+
+// Refine downward — each step returns a NEW frozen object.
+const task = context.executions().forTask(root, { phase: 'draft' })
+const helper = context.executions().forHelper(task, { role: 'analyst', dedication: 'summary' })
+// A hard sub-step runs on a stronger tier without touching the branch it came from:
+const harder = context.executions().escalate(task, { effort: ExecutionEffort.High })
+```
+
+Resolution precedence in `executions().model(exec, role, override)`:
+**roleOverride → modelOverride → effort tier → `LlmService.getModel`**.
+
+### Persist and resume
+
+```typescript
+context.executions().use({
+  onCheckpoint: async (state, _exec, key) => queue.put(key!, JSON.stringify(state)),
+  onRestore: async key => JSON.parse(await queue.get(key)),
+})
+
+await context.executions().checkpoint(task, jobId)                 // JSON-safe, no collaborators
+const resumed = context.executions().restore(state, { models: () => context.llm() })
+```
+
+### Add a provider
+
+```typescript
+import { openAiFamily, registerLlmPlugin } from '@owlmeans/llm'
+import { StructuredMode } from '@owlmeans/llm-common'
+
+registerLlmPlugin({
+  ...openAiFamily,                       // shares owns/refine/toolChoice/responseFormat
+  type: 'my-gateway',
+  structuredMode: config => config.structuredOutput === true ? StructuredMode.Native : StructuredMode.Tool,
+  build: ({ config, secret, callbacks }) => new ChatOpenAI({ /* … */ }),
+})
+```
+
+Registration order matters for instance-based lookup (a refined model that lost its config
+metadata): the first plugin whose `owns` matches wins, so the conservative member of a
+client family must be registered first.
+
+## API
+
+### Model
+
+| Method | Returns | Use for |
+|--------|---------|---------|
+| `ask(input, options)` | `string` | Plain text. |
+| `talk(input, options)` | `AIMessage` | The raw message (tool calls, metadata). |
+| `invoke(input, schema, options)` | `T` | A schema-validated object. |
+| `request(input, schema, options)` | `AIMessage` | A message whose `content` is the validated JSON. |
+
+Shared options: `action` (run name + spectator label), `ref` (out-of-band result +
+spectator entry), `filter` (reject a result and force a retry), `useCache` / `cacheMax`
+(prompt caching where the provider supports it), `temperature` (`invoke` only).
+
+### Resilience built into every call
+
+| Problem | What the package does |
+|---------|-----------------------|
+| Provider accepts the request and never streams | Idle (per-token) deadline aborts and retries — `ModelConfig.streamTimeout` |
+| Duplicate final SSE chunk corrupts tool-call arguments | Stream breaks at the first non-empty `finish_reason` |
+| Reasoning eats the whole output budget | Retry doubles `maxTokens` toward `maxTokensCap` **and** shrinks an absolute reasoning cap |
+| A weak cheap model keeps failing | Escalates to `ModelConfig.fallback` after `FALLBACK_AFTER_ATTEMPTS`, within one plugin family |
+| Model stringifies arrays / over-wraps scalars | `coerceToSchema` reconciles the answer with the schema before validation |
+| Model ignores the tool and answers in prose | `parseJsonContent` salvages JSON from fences and surrounding text |
+| Nothing usable came back | `NullCapture` — request, response, token accounting and finish reason, to the spectator |
+| An error no retry can fix | `registerFatalError` / `LlmPlugin.isFatal` abort the loop immediately |
+
+### Helpers (usable alongside a model)
+
+`withRetry` · `registerFatalError` · `spectate` · `normalizeInput` · `parseJsonContent` ·
+`coerceToSchema`. Also exported from `@owlmeans/llm/helpers`.
+
+Everything under `src/utils/` is library-private and deliberately not exported.
+
+### Plugins
+
+Exported from `@owlmeans/llm/plugins` as well as the root: `plugins` (the registry),
+`registerLlmPlugin`, `resolvePlugin`, `pluginOf`, `pluginFor`, `anthropicPlugin`,
+`openAiPlugin`, `compatiblePlugin`, `openAiFamily`.
+
+## Tests
+
+```bash
+bun test ./tests
+```
+
+Offline specs always run. The live specs in `tests/model.spec.ts` are gated: set
+`OPENROUTER_SECRET` (and optionally `OPENROUTER_URL`) and/or `ANTHROPIC_SECRET` in the repo
+root `.env`. With none set they self-skip with a printed reason — never a failure.
+
+## Depends On
+
+- `@owlmeans/llm-common` — serializable contracts
+- `@owlmeans/context` — service registration
+- `@owlmeans/error` — `ResilientError` family
+- `@owlmeans/basic-ids` — diagnostic ids
+- `ajv` — schema validation
+- peer `@langchain/core`, `@langchain/openai`, `@langchain/anthropic`
+
+<!-- owlmeans:agent-guidance:start -->
+## Agent guidance
+
+This package ships embedded Claude Code skills and GitHub Copilot instructions under
+`agent-meta/`. After installing your `@owlmeans/*` packages, run the OwlMeans
+agent-skills installer to place them into your project's native locations
+(`.claude/skills/` and `.github/instructions/`):
+
+```sh
+npx @owlmeans/agent-skills
+```
+
+The embedded files are version-matched to this package release. Do not edit them
+directly — they are regenerated on each publish. To contribute guidance edits,
+open a PR against the source monorepo.
+<!-- owlmeans:agent-guidance:end -->

package/agent-meta/instructions/llm.instructions.md

@@ -0,0 +1,66 @@
+---
+description: "How to use @owlmeans/llm — the LLM inference runtime: four-method model, provider plugins, model factory service, and the policy-driven execution abstraction."
+applyTo: "**/*.ts, **/*.tsx"
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/llm
+
+**Layer:** Core
+**Install:** `"@owlmeans/llm": "^0.1.14"` in `dependencies` (plus the `@langchain/*` peers)
+
+The inference runtime. Everything provider-specific is a **plugin**; the model owns only the
+provider-independent parts. Serializable contracts live in `@owlmeans/llm-common`.
+
+## Key Exports
+
+| Export | Description |
+|--------|-------------|
+| `makeLlmModel(options, spectator)` | `ask` / `talk` / `invoke` / `request`. |
+| `makeLlmService` · `appendLlmService` · `llmServiceApi` | Model factory/registry; `llmServiceApi` composes into your own service. |
+| `makeExecutionService` · `appendExecutionService` · `executionServiceApi` | Frozen 3-level executions, policy resolution, snapshot/restore/checkpoint. |
+| `plugins`, `registerLlmPlugin`, `resolvePlugin`, `pluginOf`, `pluginFor` | Provider-plugin registry (`@owlmeans/llm/plugins`). |
+| `anthropicPlugin`, `openAiPlugin`, `compatiblePlugin`, `openAiFamily` | Built-ins; spread `openAiFamily` into a new OpenAI-compatible plugin. |
+| `withRetry`, `registerFatalError`, `spectate`, `normalizeInput`, `parseJsonContent`, `coerceToSchema` | Helpers (`@owlmeans/llm/helpers`). |
+| `LlmModelError` (retryable), `LlmMissconfiguredError`, `LlmPluginError`, `LlmRetryExceededError` | `ResilientError` family. |
+
+## Rules
+
+- `src/helpers/` is what consumers may use; `src/utils/` is library-private and never
+  exported. Place a new function on the right side rather than exporting a util for a test.
+- Never branch on the provider (`instanceof ChatAnthropic`, `provider === …`) in the model or
+  the service — put it on the `LlmPlugin` (`build` / `owns` / `family` / `refine` /
+  `structuredMode` / `toolChoice` / `responseFormat` / `patchCache` / `isFatal`).
+- Plugin registration order is load-bearing: `pluginFor` returns the first `owns` match, and
+  `compatible` precedes `openai` so an unlabelled `ChatOpenAI` gets the conservative
+  tool-calling behaviour.
+- `@langchain/*` are **peer** dependencies — model instances cross the package boundary and
+  two installed copies are nominally distinct types. Pin one copy in the consumer.
+- Extend the execution generically: your own `ExecutionShape`, your collaborator fields in
+  `collaboratorKeys`. Do not narrow inherited method signatures (contravariance error).
+
+## Usage
+
+```typescript
+import { makeLlmModel, makeLlmService } from '@owlmeans/llm'
+
+const llm = makeLlmService({ models: () => configs })
+const model = makeLlmModel(
+  { model: llm.getModel('analyst'), purpose: { type: 'analysis' } }, spectator
+)
+const spec = await model.invoke('Describe the app', SpecSchema, { action: 'spec' })
+```
+
+Execution resolution precedence: **roleOverride → modelOverride → effort tier →
+`LlmService.getModel`**.
+
+## Already handled — do not reimplement
+
+Idle stream deadline · duplicate-final-chunk dedup · output-budget escalation ·
+reasoning-cap shrink · same-family fallback model · schema coercion · JSON salvage from
+prose · `NullCapture` diagnostics · fatal-error short-circuit.
+
+## Depends On
+
+- `@owlmeans/llm-common`, `@owlmeans/context`, `@owlmeans/error`, `@owlmeans/basic-ids`, `ajv`
+- peer `@langchain/core`, `@langchain/openai`, `@langchain/anthropic`

package/agent-meta/manifest.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "package": "@owlmeans/llm",
+  "version": "0.1.14",
+  "generatedAt": "2026-08-05T16:56:53.378Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "skill",
+      "name": "llm",
+      "category": "package-specific",
+      "file": "skills/llm/SKILL.md",
+      "canonicalPath": ".claude/skills/llm/SKILL.md"
+    },
+    {
+      "kind": "instruction",
+      "name": "llm",
+      "category": "package-specific",
+      "file": "instructions/llm.instructions.md",
+      "canonicalPath": ".github/instructions/llm.instructions.md"
+    }
+  ]
+}

package/agent-meta/skills/llm/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: llm
+description: How to use @owlmeans/llm — the LLM inference runtime (four-method model, provider plugins, model factory service, policy-driven execution abstraction). Auto-invoked when importing the model, an LlmPlugin, the LlmService, or the execution service.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/llm
+
+**Layer:** Core
+**Install:** `"@owlmeans/llm": "^0.1.14"` in `dependencies` (plus the `@langchain/*` peers)
+
+The inference runtime. Everything provider-specific is a **plugin**; the model itself only
+owns the provider-independent parts (streaming discipline, retries, validation,
+observability). Serializable contracts live in `@owlmeans/llm-common`.
+
+## Key Exports
+
+| Export | Description |
+|--------|-------------|
+| `makeLlmModel(options, spectator)` | The four-method model: `ask` / `talk` / `invoke` / `request`. |
+| `makeLlmService(options, alias?)` · `appendLlmService(ctx, options, alias?)` | Model factory/registry — resolves a `ModelConfig` by alias, memoized per alias+override. |
+| `llmServiceApi(options, self)` | The factory half WITHOUT `createService`, to compose into your own service (role accessors, domain helpers). |
+| `makeExecutionService(alias?, options?)` · `appendExecutionService(ctx, alias?, options?)` | Frozen 3-level executions + policy resolution + snapshot/restore/checkpoint. |
+| `executionServiceApi(options, self)` | The execution half without `createService`, for the same composition pattern. |
+| `plugins`, `registerLlmPlugin`, `resolvePlugin`, `pluginOf`, `pluginFor` | The provider-plugin registry. Also at `@owlmeans/llm/plugins`. |
+| `anthropicPlugin`, `openAiPlugin`, `compatiblePlugin`, `openAiFamily` | Built-in providers; `openAiFamily` is the shared OpenAI-client behaviour to spread into a new plugin. |
+| `withRetry`, `registerFatalError`, `spectate`, `normalizeInput`, `parseJsonContent`, `coerceToSchema` | Helpers usable alongside a model. Also at `@owlmeans/llm/helpers`. |
+| `LlmError`, `LlmModelError`, `LlmMissconfiguredError`, `LlmPluginError`, `LlmRetryExceededError` | `ResilientError` family. `LlmModelError` is the RETRYABLE one. |
+| `DEFAULT_MODEL_RETRIES`, `MODEL_STREAM_TIMEOUT_MS`, `FALLBACK_AFTER_ATTEMPTS`, `DEFAULT_EFFORT`, `EFFORT_TABLE`, `LLM_SERVICE`, `EXECUTION_SERVICE` | Tuning + aliases. |
+
+## helpers/ vs utils/ — the rule this package follows
+
+- `src/helpers/` — functions a **consumer** may use alongside a model. Exported.
+- `src/utils/` — used only inside the library. **Never exported**; a spec that needs one
+  imports it from `../src/utils/…`.
+
+Adding a function? Decide which side it belongs to first, then place it. Do not export a
+`utils/` symbol "because a test needs it".
+
+## Provider differences are plugins, never `if`s
+
+`LlmPlugin` is the single seam. If you find yourself writing `instanceof ChatAnthropic` or
+`config.provider === …` in `model.ts` or `service.ts`, it belongs on the plugin instead:
+
+| Plugin member | Replaces |
+|---|---|
+| `build` | the provider switch in the model factory |
+| `owns` / `family` | `instanceof` checks; `family` gates cross-provider fallback |
+| `refine` | the per-provider retry rebuild (budget doubling, reasoning shrink) |
+| `structuredMode` | native `response_format` vs the forced-tool-call hack |
+| `toolChoice` / `responseFormat` | the provider-specific call shapes |
+| `patchCache` | prompt-cache markers |
+| `isFatal` | "this error can never be retried" |
+
+**Registration order is load-bearing.** Instance-based lookup (`pluginFor`) returns the
+FIRST plugin whose `owns` matches. `compatible` is registered before `openai` because both
+build a `ChatOpenAI`, and assuming the tool-calling hack for an unlabelled model is safe
+everywhere while assuming native JSON-schema support is not.
+
+## Execution: policy in, model out
+
+```
+ProjectExecution   ← root: policy + purpose + models resolver
+  └─ TaskExecution    ← + resumable state (phase/cursor/completed/data)
+       └─ HelperExecution ← + a RESOLVED model + temperatureFactory, bound to a role
+```
+
+Every method returns a NEW `Object.freeze`d object. Resolution precedence in
+`model(exec, role, override)`: **roleOverride → modelOverride → effort tier →
+`LlmService.getModel`**. `escalate(exec, { effort })` raises the tier once and cascades to
+everything derived from it.
+
+Extending it for a domain: declare your own `Execution`/input types, list your collaborator
+fields in `ExecutionServiceOptions.collaboratorKeys` so they stay out of snapshots, and
+instantiate the service generic with your own `ExecutionShape` — **do not narrow the
+inherited method signatures**, which would be a contravariance error.
+
+`snapshot` excludes `state` itself; without that, every `derive`/`escalate`/`withPurpose`
+on a task would nest another copy of the previous state.
+
+## Peer-dependency rule (langchain identity)
+
+`@langchain/core`, `@langchain/openai` and `@langchain/anthropic` are **peer** dependencies:
+model instances cross the package boundary, and two installed copies of a class with
+protected members are nominally distinct types. In a linked-workspace checkout the consumer
+must pin them to a single copy — see the `bun-linked-workspaces` skill.
+
+## Usage
+
+```typescript
+import { makeLlmModel, makeLlmService } from '@owlmeans/llm'
+import { ModelProvider } from '@owlmeans/llm-common'
+
+const llm = makeLlmService({ models: () => configs })
+const model = makeLlmModel(
+  { model: llm.getModel('analyst'), purpose: { type: 'analysis' } }, spectator
+)
+const spec = await model.invoke('Describe the app', SpecSchema, { action: 'spec' })
+```
+
+## Resilience already handled — do not reimplement
+
+Idle stream deadline · duplicate-final-chunk dedup · output-budget escalation · reasoning-cap
+shrink · same-family fallback model · schema coercion · JSON salvage from prose · `NullCapture`
+diagnostics · fatal-error short-circuit. Details: package `README.md`.
+
+## Tests
+
+`bun test ./tests` in the package. Offline specs always run; `tests/model.spec.ts` is gated
+on `OPENROUTER_SECRET` / `ANTHROPIC_SECRET` in the repo-root `.env` and self-skips otherwise.
+
+## Depends On
+
+- `@owlmeans/llm-common` · `@owlmeans/context` · `@owlmeans/error` · `@owlmeans/basic-ids` · `ajv`
+- peer `@langchain/core`, `@langchain/openai`, `@langchain/anthropic`
+
+## Related
+
+- [[llm-common]] — the serializable contracts
+- [[context]] — service registration · [[error]] — the `ResilientError` family

package/build/consts.d.ts

@@ -0,0 +1,67 @@
+import { ExecutionEffort } from '@owlmeans/llm-common';
+import type { ModelConfigPatch } from '@owlmeans/llm-common';
+/** Context-service alias for the {@link LlmService} (model factory / registry). */
+export declare const LLM_SERVICE = "owlmeans-llm-service";
+/** Context-service alias for the {@link ExecutionService}. */
+export declare const EXECUTION_SERVICE = "owlmeans-llm-execution-service";
+/** Default number of attempts a single model call makes before giving up. */
+export declare const DEFAULT_MODEL_RETRIES = 8;
+/**
+ * Idle (inactivity) deadline in ms for a streamed response: abort the stream when no
+ * new token has arrived within this window. NOT a total cap — the timer is re-armed on
+ * every chunk, so long but actively-streaming generations are never aborted. Guards
+ * against a provider that accepts the request and then never streams anything (observed
+ * with throughput-sorted OpenRouter routing), which would otherwise block forever —
+ * `maxRetries` never helps there because the request never errors, it just hangs.
+ * Overridable per model via `ModelConfig.streamTimeout`.
+ */
+export declare const MODEL_STREAM_TIMEOUT_MS: number;
+/**
+ * Number of failed attempts after which the retry escalator switches from a role's
+ * cheap primary model to its configured `fallback` (stronger) model. With
+ * {@link DEFAULT_MODEL_RETRIES} = 8 the primary runs attempts 0..2 and the fallback
+ * runs attempts 3..7.
+ */
+export declare const FALLBACK_AFTER_ATTEMPTS = 3;
+/**
+ * Output-token ceiling used by the retry escalator when a model config declares no
+ * `maxTokensCap`. Deliberately high (192K) — it exceeds many real per-request output
+ * limits, which is why a precise cap belongs in the preset: without it a retry can
+ * issue a 400 "max_tokens exceeds the model's per-request limit".
+ */
+export declare const DEFAULT_MAX_OUTPUT_CAP: number;
+/** Provider hard limit on prompt-cache breakpoints (Anthropic). */
+export declare const MAX_CACHE_BREAKPOINTS = 4;
+/**
+ * Appended to the prompt of `invoke`/`request` when no message already mentions JSON.
+ * Some providers refuse or ignore JSON modes unless the word appears in the prompt;
+ * the length guidance keeps a verbose model from padding the object past the output
+ * limit and truncating it.
+ */
+export declare const JSON_INSTRUCTION: string;
+/**
+ * Qwen3-family soft switch that suppresses hidden reasoning. Injected when
+ * `ModelConfig.disableThinking` is set; without it those models routinely spend the
+ * whole output budget on thinking and return empty content with `finish_reason="length"`.
+ */
+export declare const NO_THINK_DIRECTIVE = "/no_think";
+/** Tool name used for structured output when a schema carries no usable title/name. */
+export declare const DEFAULT_TOOL_NAME = "extract";
+/** Default effort tier when a policy does not specify one. */
+export declare const DEFAULT_EFFORT = ExecutionEffort.Standard;
+/**
+ * Effort tier → JSON-safe model config bump merged into `LlmService.getModel` overrides.
+ * Pure data: an explicit `modelOverride` always wins over this table, and a `roleOverride`
+ * is applied before it.
+ */
+export declare const EFFORT_TABLE: Record<ExecutionEffort, ModelConfigPatch>;
+/**
+ * Execution fields that are collaborators, not state: never copied into a snapshot.
+ * A consumer adds its own (e.g. a file-access helper) through
+ * `ExecutionServiceOptions.collaboratorKeys`.
+ *
+ * `state` is in the list because a `TaskExecution` carries its own composed state —
+ * without excluding it every `derive`/`escalate`/`withPurpose` would nest another copy.
+ */
+export declare const COLLABORATOR_KEYS: string[];
+//# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAE5D,mFAAmF;AACnF,eAAO,MAAM,WAAW,yBAAyB,CAAA;AAEjD,8DAA8D;AAC9D,eAAO,MAAM,iBAAiB,mCAAmC,CAAA;AAEjE,6EAA6E;AAC7E,eAAO,MAAM,qBAAqB,IAAI,CAAA;AAEtC;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,QAAgB,CAAA;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,IAAI,CAAA;AAExC;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,QAAY,CAAA;AAE/C,mEAAmE;AACnE,eAAO,MAAM,qBAAqB,IAAI,CAAA;AAEtC;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,QAGkD,CAAA;AAE/E;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,cAAc,CAAA;AAE7C,uFAAuF;AACvF,eAAO,MAAM,iBAAiB,YAAY,CAAA;AAE1C,8DAA8D;AAC9D,eAAO,MAAM,cAAc,2BAA2B,CAAA;AAEtD;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,eAAe,EAAE,gBAAgB,CAKlE,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,EAErC,CAAA"}

package/build/consts.js

@@ -0,0 +1,76 @@
+import { ExecutionEffort } from '@owlmeans/llm-common';
+/** Context-service alias for the {@link LlmService} (model factory / registry). */
+export const LLM_SERVICE = 'owlmeans-llm-service';
+/** Context-service alias for the {@link ExecutionService}. */
+export const EXECUTION_SERVICE = 'owlmeans-llm-execution-service';
+/** Default number of attempts a single model call makes before giving up. */
+export const DEFAULT_MODEL_RETRIES = 8;
+/**
+ * Idle (inactivity) deadline in ms for a streamed response: abort the stream when no
+ * new token has arrived within this window. NOT a total cap — the timer is re-armed on
+ * every chunk, so long but actively-streaming generations are never aborted. Guards
+ * against a provider that accepts the request and then never streams anything (observed
+ * with throughput-sorted OpenRouter routing), which would otherwise block forever —
+ * `maxRetries` never helps there because the request never errors, it just hangs.
+ * Overridable per model via `ModelConfig.streamTimeout`.
+ */
+export const MODEL_STREAM_TIMEOUT_MS = 5 * 60 * 1000;
+/**
+ * Number of failed attempts after which the retry escalator switches from a role's
+ * cheap primary model to its configured `fallback` (stronger) model. With
+ * {@link DEFAULT_MODEL_RETRIES} = 8 the primary runs attempts 0..2 and the fallback
+ * runs attempts 3..7.
+ */
+export const FALLBACK_AFTER_ATTEMPTS = 3;
+/**
+ * Output-token ceiling used by the retry escalator when a model config declares no
+ * `maxTokensCap`. Deliberately high (192K) — it exceeds many real per-request output
+ * limits, which is why a precise cap belongs in the preset: without it a retry can
+ * issue a 400 "max_tokens exceeds the model's per-request limit".
+ */
+export const DEFAULT_MAX_OUTPUT_CAP = 3 * 64000;
+/** Provider hard limit on prompt-cache breakpoints (Anthropic). */
+export const MAX_CACHE_BREAKPOINTS = 4;
+/**
+ * Appended to the prompt of `invoke`/`request` when no message already mentions JSON.
+ * Some providers refuse or ignore JSON modes unless the word appears in the prompt;
+ * the length guidance keeps a verbose model from padding the object past the output
+ * limit and truncating it.
+ */
+export const JSON_INSTRUCTION = 'Respond with a single complete and valid JSON object only. '
+    + 'Do not wrap it in markdown fences, and do not add any commentary, reasoning, or explanation outside the JSON. '
+    + 'Keep string values focused — do not pad them with restated requirements or numbered summaries, '
+    + 'so the whole object stays within the output limit and is never truncated.';
+/**
+ * Qwen3-family soft switch that suppresses hidden reasoning. Injected when
+ * `ModelConfig.disableThinking` is set; without it those models routinely spend the
+ * whole output budget on thinking and return empty content with `finish_reason="length"`.
+ */
+export const NO_THINK_DIRECTIVE = '/no_think';
+/** Tool name used for structured output when a schema carries no usable title/name. */
+export const DEFAULT_TOOL_NAME = 'extract';
+/** Default effort tier when a policy does not specify one. */
+export const DEFAULT_EFFORT = ExecutionEffort.Standard;
+/**
+ * Effort tier → JSON-safe model config bump merged into `LlmService.getModel` overrides.
+ * Pure data: an explicit `modelOverride` always wins over this table, and a `roleOverride`
+ * is applied before it.
+ */
+export const EFFORT_TABLE = {
+    [ExecutionEffort.Economy]: { maxTokensCap: 16000 },
+    [ExecutionEffort.Standard]: {},
+    [ExecutionEffort.High]: { maxTokens: 16000, maxTokensCap: 32000 },
+    [ExecutionEffort.Max]: { maxTokens: 32000, maxTokensCap: 64000 },
+};
+/**
+ * Execution fields that are collaborators, not state: never copied into a snapshot.
+ * A consumer adds its own (e.g. a file-access helper) through
+ * `ExecutionServiceOptions.collaboratorKeys`.
+ *
+ * `state` is in the list because a `TaskExecution` carries its own composed state —
+ * without excluding it every `derive`/`escalate`/`withPurpose` would nest another copy.
+ */
+export const COLLABORATOR_KEYS = [
+    'state', 'models', 'model', 'temperatureFactory', 'outputErrors',
+];
+//# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAGtD,mFAAmF;AACnF,MAAM,CAAC,MAAM,WAAW,GAAG,sBAAsB,CAAA;AAEjD,8DAA8D;AAC9D,MAAM,CAAC,MAAM,iBAAiB,GAAG,gCAAgC,CAAA;AAEjE,6EAA6E;AAC7E,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAA;AAEtC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAA;AAEpD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAA;AAExC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,GAAG,KAAK,CAAA;AAE/C,mEAAmE;AACnE,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAA;AAEtC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,6DAA6D;MACzF,gHAAgH;MAChH,iGAAiG;MACjG,2EAA2E,CAAA;AAE/E;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,WAAW,CAAA;AAE7C,uFAAuF;AACvF,MAAM,CAAC,MAAM,iBAAiB,GAAG,SAAS,CAAA;AAE1C,8DAA8D;AAC9D,MAAM,CAAC,MAAM,cAAc,GAAG,eAAe,CAAC,QAAQ,CAAA;AAEtD;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAA8C;IACrE,CAAC,eAAe,CAAC,OAAO,CAAC,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE;IAClD,CAAC,eAAe,CAAC,QAAQ,CAAC,EAAE,EAAE;IAC9B,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE;IACjE,CAAC,eAAe,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE;CACjE,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAa;IACzC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,oBAAoB,EAAE,cAAc;CACjE,CAAA"}

package/build/errors.d.ts

@@ -0,0 +1,33 @@
+import { ResilientError } from '@owlmeans/error';
+export declare class LlmError extends ResilientError {
+    static typeName: string;
+    constructor(message?: string);
+}
+/**
+ * A model call produced something unusable (null/empty content, failed validation,
+ * a rejected filter, a stalled stream). **Retryable** — `withRetry` swallows it and
+ * escalates to the next attempt.
+ */
+export declare class LlmModelError extends LlmError {
+    static typeName: string;
+    retry: number;
+    constructor(message?: string);
+}
+/** A model alias has no config, or its config names no provider/secret/plugin. */
+export declare class LlmMissconfiguredError extends LlmError {
+    static typeName: string;
+    constructor(message?: string);
+}
+/** No provider plugin is registered for the requested type / model instance. */
+export declare class LlmPluginError extends LlmError {
+    static readonly NO_PLUGIN = "no-plugin";
+    static typeName: string;
+    constructor(message?: string);
+}
+/** Every attempt failed. `cause` carries the last error, `attempt` the last index. */
+export declare class LlmRetryExceededError extends LlmError {
+    static typeName: string;
+    attempt: number;
+    constructor(message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/build/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,qBAAa,QAAS,SAAQ,cAAc;IAC1C,OAAuB,QAAQ,SAAkC;gBAErD,OAAO,GAAE,MAAgB;CAGtC;AAED;;;;GAIG;AACH,qBAAa,aAAc,SAAQ,QAAQ;IACzC,OAAuB,QAAQ,SAA8B;IAEtD,KAAK,EAAE,MAAM,CAAI;gBAEZ,OAAO,GAAE,MAAgB;CAItC;AAED,kFAAkF;AAClF,qBAAa,sBAAuB,SAAQ,QAAQ;IAClD,OAAuB,QAAQ,SAAuC;gBAE1D,OAAO,GAAE,MAAgB;CAItC;AAED,gFAAgF;AAChF,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,gBAAuB,SAAS,eAAc;IAE9C,OAAuB,QAAQ,SAA+B;gBAElD,OAAO,GAAE,MAAgB;CAItC;AAED,sFAAsF;AACtF,qBAAa,qBAAsB,SAAQ,QAAQ;IACjD,OAAuB,QAAQ,SAAsC;IAE9D,OAAO,EAAE,MAAM,CAAI;gBAEd,OAAO,GAAE,MAAgB;CAItC"}

package/build/errors.js

@@ -0,0 +1,52 @@
+import { ResilientError } from '@owlmeans/error';
+export class LlmError extends ResilientError {
+    static typeName = `Llm${ResilientError.typeName}`;
+    constructor(message = 'error') {
+        super(LlmError.typeName, `llm:${message}`);
+    }
+}
+/**
+ * A model call produced something unusable (null/empty content, failed validation,
+ * a rejected filter, a stalled stream). **Retryable** — `withRetry` swallows it and
+ * escalates to the next attempt.
+ */
+export class LlmModelError extends LlmError {
+    static typeName = `Model${LlmError.typeName}`;
+    retry = 0;
+    constructor(message = 'error') {
+        super(`model:${message}`);
+        this.type = LlmModelError.typeName;
+    }
+}
+/** A model alias has no config, or its config names no provider/secret/plugin. */
+export class LlmMissconfiguredError extends LlmError {
+    static typeName = `Missconfigured${LlmError.typeName}`;
+    constructor(message = 'error') {
+        super(`missconfigured:${message}`);
+        this.type = LlmMissconfiguredError.typeName;
+    }
+}
+/** No provider plugin is registered for the requested type / model instance. */
+export class LlmPluginError extends LlmError {
+    static NO_PLUGIN = 'no-plugin';
+    static typeName = `Plugin${LlmError.typeName}`;
+    constructor(message = 'error') {
+        super(`plugin:${message}`);
+        this.type = LlmPluginError.typeName;
+    }
+}
+/** Every attempt failed. `cause` carries the last error, `attempt` the last index. */
+export class LlmRetryExceededError extends LlmError {
+    static typeName = `RetryExceeded${LlmError.typeName}`;
+    attempt = 0;
+    constructor(message = 'error') {
+        super(`retry-exceeded:${message}`);
+        this.type = LlmRetryExceededError.typeName;
+    }
+}
+ResilientError.registerErrorClass(LlmError);
+ResilientError.registerErrorClass(LlmModelError);
+ResilientError.registerErrorClass(LlmMissconfiguredError);
+ResilientError.registerErrorClass(LlmPluginError);
+ResilientError.registerErrorClass(LlmRetryExceededError);
+//# sourceMappingURL=errors.js.map

package/build/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,MAAM,OAAO,QAAS,SAAQ,cAAc;IACnC,MAAM,CAAU,QAAQ,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEjE,YAAY,UAAkB,OAAO;QACnC,KAAK,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,OAAO,EAAE,CAAC,CAAA;IAC5C,CAAC;;AAGH;;;;GAIG;AACH,MAAM,OAAO,aAAc,SAAQ,QAAQ;IAClC,MAAM,CAAU,QAAQ,GAAG,QAAQ,QAAQ,CAAC,QAAQ,EAAE,CAAA;IAEtD,KAAK,GAAW,CAAC,CAAA;IAExB,YAAY,UAAkB,OAAO;QACnC,KAAK,CAAC,SAAS,OAAO,EAAE,CAAC,CAAA;QACzB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC,QAAQ,CAAA;IACpC,CAAC;;AAGH,kFAAkF;AAClF,MAAM,OAAO,sBAAuB,SAAQ,QAAQ;IAC3C,MAAM,CAAU,QAAQ,GAAG,iBAAiB,QAAQ,CAAC,QAAQ,EAAE,CAAA;IAEtE,YAAY,UAAkB,OAAO;QACnC,KAAK,CAAC,kBAAkB,OAAO,EAAE,CAAC,CAAA;QAClC,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC,QAAQ,CAAA;IAC7C,CAAC;;AAGH,gFAAgF;AAChF,MAAM,OAAO,cAAe,SAAQ,QAAQ;IACnC,MAAM,CAAU,SAAS,GAAG,WAAW,CAAA;IAEvC,MAAM,CAAU,QAAQ,GAAG,SAAS,QAAQ,CAAC,QAAQ,EAAE,CAAA;IAE9D,YAAY,UAAkB,OAAO;QACnC,KAAK,CAAC,UAAU,OAAO,EAAE,CAAC,CAAA;QAC1B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAA;IACrC,CAAC;;AAGH,sFAAsF;AACtF,MAAM,OAAO,qBAAsB,SAAQ,QAAQ;IAC1C,MAAM,CAAU,QAAQ,GAAG,gBAAgB,QAAQ,CAAC,QAAQ,EAAE,CAAA;IAE9D,OAAO,GAAW,CAAC,CAAA;IAE1B,YAAY,UAAkB,OAAO;QACnC,KAAK,CAAC,kBAAkB,OAAO,EAAE,CAAC,CAAA;QAClC,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC,QAAQ,CAAA;IAC5C,CAAC;;AAGH,cAAc,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAA;AAC3C,cAAc,CAAC,kBAAkB,CAAC,aAAa,CAAC,CAAA;AAChD,cAAc,CAAC,kBAAkB,CAAC,sBAAsB,CAAC,CAAA;AACzD,cAAc,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAA;AACjD,cAAc,CAAC,kBAAkB,CAAC,qBAAqB,CAAC,CAAA"}

package/build/execution/index.d.ts

@@ -0,0 +1,4 @@
+export type * from './types.js';
+export * from './utils.js';
+export * from './service.js';
+//# sourceMappingURL=index.d.ts.map