@owlmeans/llm-common 0.1.18-rc.2 → 0.1.18-rc.20

package/README.md

@@ -20,7 +20,7 @@ extends these; `@owlmeans/llm` implements against them.
 ## Installation
 
 ```bash
-bun add @owlmeans/llm-common
+bun add @owlmeans/llm-common@^0.1.18-rc.11
 ```
 
 ## Usage
@@ -96,7 +96,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18-rc.20
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/llm-common",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.510Z",
+  "version": "0.1.18-rc.20",
+  "generatedAt": "2026-09-12T14:21:25.466Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/llm-common
 
 **Layer:** Core
-**Install:** `"@owlmeans/llm-common": "^0.1.18-rc.0"` in `dependencies`
+**Install:** `"@owlmeans/llm-common": "^0.1.18-rc.20"` in `dependencies`
 
 The contracts half of the LLM stack. **No `@langchain/*` runtime dependency** — importable
 from a browser bundle, a queue worker, or any package that must not pull an inference SDK.
@@ -25,29 +25,52 @@ The dependency direction is one-way: a domain contracts package extends these;
 | `StructuredMode` | `Native` (provider JSON-schema mode) vs `Tool` (forced tool call). |
 | `SpectatorContentType`, `SPECTATOR_GENERAL` | Observability record enums/defaults. |
 | `ModelRole` | Open `string` — declare your own enum, its values stay assignable. |
-| `ModelConfigPatch` / `ModelConfigOverride` | The JSON-safe config subset; never credentials. |
-| `ModelPolicy` | `{ effort, roleOverrides?, modelOverrides? }` — inherited by every refinement. |
+| `ModelConfigPatch` / `ModelConfigOverride` | The JSON-safe config subset; never credentials. Carries the model-capability fields (`contextWindow`, `maxOutput`, `combinedWindow`) alongside the budget ones — see the `llm` skill for what each means. |
+| `ModelPolicy` | `{ effort, roleOverrides?, modelOverrides?, utilityRole? }` — inherited by every refinement. |
+| `UTILITY_ROLE` | `'utility'` — the conventional cheap tier for side calls (a relevance pick, a classification). `ModelPolicy.utilityRole` points it at another alias; `ExecutionService.utility` resolves it. |
 | `ExecutionState` / `TaskExecutionState` | The persistable core (`level`/`purpose`/`policy`, plus `phase`/`completed`/`cursor`/`data`). |
 | `LlmPurpose` | `{ type?, dedication? }` — metadata carried on every model call. |
 | `PromptBlock`, `PROMPT_BLOCK_ORDER`, `DEFAULT_SKILL_ORDER` | The ordered sections of a composed system prompt — the order IS the cache key. |
 | `SkillDefinition` | One named block of reusable prompt knowledge. `body` must be a pure constant. |
 | `PromptPolicy` | `{ role?, skills?, cacheSystem?, cacheTtl? }` — carried on `ExecutionState`, merged downward. |
 | `CacheTtl`, `CacheUsage` | `'5m' \| '1h'`; normalized prompt-cache accounting. |
-| `LlmFileProvider`, `FileProviderRef`, `resolveFileProvider` | The minimal read/write file contract prompt plugins work against. |
+| `LlmFileProvider`, `FileProviderRef`, `resolveFileProvider` | The file contract prompt plugins work against — four members, every path relative to the host's project root. `FileProviderRef` accepts the provider or a thunk returning one; `resolveFileProvider` unwraps whichever form arrived, or `undefined`. |
 | `NullCapture`, `NullKind` | Full diagnostics of a call that returned nothing usable. |
 | `SpectatorArgument`, `SpectatorEntry`, `SpectatorEntryLogged`, `SpectatorEntryMessage` | What an observability sink stores. |
 
+## `LlmFileProvider` — what a host must supply
+
+A consumer's own file helper satisfies it structurally (`interface FileHelper extends
+LlmFileProvider`); implementing it from scratch means all four:
+
+| Member | Contract |
+|---|---|
+| `readFile(path, noThrow?)` | Read a file relative to the root. With `noThrow`, a missing file yields `''`. |
+| `getSourceList(pattern?)` | Glob for files relative to the root. Project-skill discovery in `@owlmeans/agent-skills` is built on it, so a provider that stubs it indexes nothing. |
+| `writeFile(path, content)` | Write relative to the root, creating parent directories. |
+| `deleteFile(path, noThrow?)` | Delete relative to the root. With `noThrow`, a missing file is a no-op. |
+| `key?` | Optional. The provider's stable identity (project root, sandbox id) — the only thing a plugin caching per-project reads can key on, since providers are rebuilt per request. A provider without one is treated as uncacheable. |
+
+Resolving the project root is deliberately NOT part of the contract, and an implementation must not
+narrow an inherited signature — that is what stops a rich helper from satisfying this one.
+
 ## Extension rules
 
 Open types are open **on purpose** — extend, do not fork:
 
 ```typescript
+import type {
+  ExecutionState as LlmExecutionState, LlmPurpose,
+  TaskExecutionState as LlmTaskExecutionState,
+} from '@owlmeans/llm-common'
+
 // Your roles: an enum whose values satisfy the open `ModelRole` string.
 export enum MyRole { Analyst = 'analyst', Coder = 'coder' }
 
-// Your purpose and state: extend, never redeclare.
+// Your purpose and state: extend, never redeclare. Aliasing the imports keeps your own
+// `ExecutionState` the name the rest of your domain uses.
 export interface MyPurpose extends LlmPurpose { agent?: string }
-export interface MyExecutionState extends ExecutionState {
+export interface MyExecutionState extends LlmExecutionState {
   purpose: MyPurpose
   projectId?: string
 }

package/build/consts.d.ts

@@ -9,7 +9,21 @@ export declare enum ModelProvider {
     /** Anthropic messages API. */
     Anthropic = "anthropic",
     /** Any OpenAI-compatible endpoint — OpenRouter, HuggingFace router, Together, vLLM, … */
-    Compatible = "compatible"
+    Compatible = "compatible",
+    /**
+     * No endpoint at all: the call is handed to whoever holds the execution.
+     *
+     * A delegated model does not talk to a provider. It packages the call — the system prompt, the
+     * conversation, the tools or the schema — and hands it to a transport the application seated,
+     * which carries it to something outside this process entirely: a coding agent driving the
+     * application through a connector, a human, a test. The answer comes back the same way and is
+     * turned into a completion the rest of the stack cannot tell apart from a provider's.
+     *
+     * It exists so that "who performs this call" can be a property of the SESSION rather than of the
+     * code: the same pipeline, the same prompts and the same retry rules, billed to somebody else's
+     * model.
+     */
+    Delegated = "delegated"
 }
 /**
  * Refinement level of an execution. An execution is refined downward only:
@@ -82,4 +96,11 @@ export declare enum PromptBlock {
 export declare const PROMPT_BLOCK_ORDER: readonly PromptBlock[];
 /** Sort weight of a skill that declares none — see `SkillDefinition.order`. */
 export declare const DEFAULT_SKILL_ORDER = 100;
+/**
+ * Conventional {@link ModelRole} for the cheap side calls the layer makes on its own
+ * behalf — a relevance pick, a classification, a one-line judgement — rather than for the
+ * work a caller asked for. A deployment that names its cheap tier differently points
+ * `ModelPolicy.utilityRole` at its own alias; nothing else has to change.
+ */
+export declare const UTILITY_ROLE = "utility";
 //# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA;;;;GAIG;AACH,oBAAY,aAAa;IACvB,yFAAyF;IACzF,MAAM,WAAW;IACjB,8BAA8B;IAC9B,SAAS,cAAc;IACvB,yFAAyF;IACzF,UAAU,eAAe;CAC1B;AAED;;;GAGG;AACH,oBAAY,cAAc;IACxB,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,MAAM,WAAW;CAClB;AAED;;;;GAIG;AACH,oBAAY,eAAe;IACzB,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,IAAI,SAAS;IACb,GAAG,QAAQ;CACZ;AAED;;;;;;;;;GASG;AACH,oBAAY,cAAc;IACxB,MAAM,WAAW;IACjB,IAAI,SAAS;CACd;AAED,0DAA0D;AAC1D,oBAAY,oBAAoB;IAC9B,IAAI,SAAS;IACb,IAAI,SAAS;IACb,QAAQ,cAAc;CACvB;AAED,mFAAmF;AACnF,eAAO,MAAM,iBAAiB,YAAY,CAAA;AAE1C;;;;;;;;;;;;;;GAcG;AACH,oBAAY,WAAW;IACrB,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,OAAO,YAAY;CACpB;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,WAAW,EAK3C,CAAA;AAEV,+EAA+E;AAC/E,eAAO,MAAM,mBAAmB,MAAM,CAAA"}
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA;;;;GAIG;AACH,oBAAY,aAAa;IACvB,yFAAyF;IACzF,MAAM,WAAW;IACjB,8BAA8B;IAC9B,SAAS,cAAc;IACvB,yFAAyF;IACzF,UAAU,eAAe;IACzB;;;;;;;;;;;;OAYG;IACH,SAAS,cAAc;CACxB;AAED;;;GAGG;AACH,oBAAY,cAAc;IACxB,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,MAAM,WAAW;CAClB;AAED;;;;GAIG;AACH,oBAAY,eAAe;IACzB,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,IAAI,SAAS;IACb,GAAG,QAAQ;CACZ;AAED;;;;;;;;;GASG;AACH,oBAAY,cAAc;IACxB,MAAM,WAAW;IACjB,IAAI,SAAS;CACd;AAED,0DAA0D;AAC1D,oBAAY,oBAAoB;IAC9B,IAAI,SAAS;IACb,IAAI,SAAS;IACb,QAAQ,cAAc;CACvB;AAED,mFAAmF;AACnF,eAAO,MAAM,iBAAiB,YAAY,CAAA;AAE1C;;;;;;;;;;;;;;GAcG;AACH,oBAAY,WAAW;IACrB,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,OAAO,YAAY;CACpB;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,WAAW,EAK3C,CAAA;AAEV,+EAA+E;AAC/E,eAAO,MAAM,mBAAmB,MAAM,CAAA;AAEtC;;;;;GAKG;AACH,eAAO,MAAM,YAAY,YAAY,CAAA"}

package/build/consts.js

@@ -11,6 +11,20 @@ export var ModelProvider;
     ModelProvider["Anthropic"] = "anthropic";
     /** Any OpenAI-compatible endpoint — OpenRouter, HuggingFace router, Together, vLLM, … */
     ModelProvider["Compatible"] = "compatible";
+    /**
+     * No endpoint at all: the call is handed to whoever holds the execution.
+     *
+     * A delegated model does not talk to a provider. It packages the call — the system prompt, the
+     * conversation, the tools or the schema — and hands it to a transport the application seated,
+     * which carries it to something outside this process entirely: a coding agent driving the
+     * application through a connector, a human, a test. The answer comes back the same way and is
+     * turned into a completion the rest of the stack cannot tell apart from a provider's.
+     *
+     * It exists so that "who performs this call" can be a property of the SESSION rather than of the
+     * code: the same pipeline, the same prompts and the same retry rules, billed to somebody else's
+     * model.
+     */
+    ModelProvider["Delegated"] = "delegated";
 })(ModelProvider || (ModelProvider = {}));
 /**
  * Refinement level of an execution. An execution is refined downward only:
@@ -93,4 +107,11 @@ export const PROMPT_BLOCK_ORDER = [
 ];
 /** Sort weight of a skill that declares none — see `SkillDefinition.order`. */
 export const DEFAULT_SKILL_ORDER = 100;
+/**
+ * Conventional {@link ModelRole} for the cheap side calls the layer makes on its own
+ * behalf — a relevance pick, a classification, a one-line judgement — rather than for the
+ * work a caller asked for. A deployment that names its cheap tier differently points
+ * `ModelPolicy.utilityRole` at its own alias; nothing else has to change.
+ */
+export const UTILITY_ROLE = 'utility';
 //# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -1 +1 @@
-{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA;;;;GAIG;AACH,MAAM,CAAN,IAAY,aAOX;AAPD,WAAY,aAAa;IACvB,yFAAyF;IACzF,kCAAiB,CAAA;IACjB,8BAA8B;IAC9B,wCAAuB,CAAA;IACvB,yFAAyF;IACzF,0CAAyB,CAAA;AAC3B,CAAC,EAPW,aAAa,KAAb,aAAa,QAOxB;AAED;;;GAGG;AACH,MAAM,CAAN,IAAY,cAIX;AAJD,WAAY,cAAc;IACxB,qCAAmB,CAAA;IACnB,+BAAa,CAAA;IACb,mCAAiB,CAAA;AACnB,CAAC,EAJW,cAAc,KAAd,cAAc,QAIzB;AAED;;;;GAIG;AACH,MAAM,CAAN,IAAY,eAKX;AALD,WAAY,eAAe;IACzB,sCAAmB,CAAA;IACnB,wCAAqB,CAAA;IACrB,gCAAa,CAAA;IACb,8BAAW,CAAA;AACb,CAAC,EALW,eAAe,KAAf,eAAe,QAK1B;AAED;;;;;;;;;GASG;AACH,MAAM,CAAN,IAAY,cAGX;AAHD,WAAY,cAAc;IACxB,mCAAiB,CAAA;IACjB,+BAAa,CAAA;AACf,CAAC,EAHW,cAAc,KAAd,cAAc,QAGzB;AAED,0DAA0D;AAC1D,MAAM,CAAN,IAAY,oBAIX;AAJD,WAAY,oBAAoB;IAC9B,qCAAa,CAAA;IACb,qCAAa,CAAA;IACb,8CAAsB,CAAA;AACxB,CAAC,EAJW,oBAAoB,KAApB,oBAAoB,QAI/B;AAED,mFAAmF;AACnF,MAAM,CAAC,MAAM,iBAAiB,GAAG,SAAS,CAAA;AAE1C;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAN,IAAY,WAKX;AALD,WAAY,WAAW;IACrB,4BAAa,CAAA;IACb,gCAAiB,CAAA;IACjB,oCAAqB,CAAA;IACrB,kCAAmB,CAAA;AACrB,CAAC,EALW,WAAW,KAAX,WAAW,QAKtB;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAA2B;IACxD,WAAW,CAAC,IAAI;IAChB,WAAW,CAAC,MAAM;IAClB,WAAW,CAAC,QAAQ;IACpB,WAAW,CAAC,OAAO;CACX,CAAA;AAEV,+EAA+E;AAC/E,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAA"}
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA;;;;GAIG;AACH,MAAM,CAAN,IAAY,aAqBX;AArBD,WAAY,aAAa;IACvB,yFAAyF;IACzF,kCAAiB,CAAA;IACjB,8BAA8B;IAC9B,wCAAuB,CAAA;IACvB,yFAAyF;IACzF,0CAAyB,CAAA;IACzB;;;;;;;;;;;;OAYG;IACH,wCAAuB,CAAA;AACzB,CAAC,EArBW,aAAa,KAAb,aAAa,QAqBxB;AAED;;;GAGG;AACH,MAAM,CAAN,IAAY,cAIX;AAJD,WAAY,cAAc;IACxB,qCAAmB,CAAA;IACnB,+BAAa,CAAA;IACb,mCAAiB,CAAA;AACnB,CAAC,EAJW,cAAc,KAAd,cAAc,QAIzB;AAED;;;;GAIG;AACH,MAAM,CAAN,IAAY,eAKX;AALD,WAAY,eAAe;IACzB,sCAAmB,CAAA;IACnB,wCAAqB,CAAA;IACrB,gCAAa,CAAA;IACb,8BAAW,CAAA;AACb,CAAC,EALW,eAAe,KAAf,eAAe,QAK1B;AAED;;;;;;;;;GASG;AACH,MAAM,CAAN,IAAY,cAGX;AAHD,WAAY,cAAc;IACxB,mCAAiB,CAAA;IACjB,+BAAa,CAAA;AACf,CAAC,EAHW,cAAc,KAAd,cAAc,QAGzB;AAED,0DAA0D;AAC1D,MAAM,CAAN,IAAY,oBAIX;AAJD,WAAY,oBAAoB;IAC9B,qCAAa,CAAA;IACb,qCAAa,CAAA;IACb,8CAAsB,CAAA;AACxB,CAAC,EAJW,oBAAoB,KAApB,oBAAoB,QAI/B;AAED,mFAAmF;AACnF,MAAM,CAAC,MAAM,iBAAiB,GAAG,SAAS,CAAA;AAE1C;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAN,IAAY,WAKX;AALD,WAAY,WAAW;IACrB,4BAAa,CAAA;IACb,gCAAiB,CAAA;IACjB,oCAAqB,CAAA;IACrB,kCAAmB,CAAA;AACrB,CAAC,EALW,WAAW,KAAX,WAAW,QAKtB;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAA2B;IACxD,WAAW,CAAC,IAAI;IAChB,WAAW,CAAC,MAAM;IAClB,WAAW,CAAC,QAAQ;IACpB,WAAW,CAAC,OAAO;CACX,CAAA;AAEV,+EAA+E;AAC/E,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAA;AAEtC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,SAAS,CAAA"}

package/build/delegate/index.d.ts

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

package/build/delegate/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/delegate/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA"}

package/build/delegate/index.js

@@ -0,0 +1,2 @@
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/build/delegate/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/delegate/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA"}

package/build/delegate/types.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The serializable form of one model call, for a performer outside this process.
+ *
+ * A delegated call cannot pass a `BaseChatModel` or a langchain message anywhere: the thing that
+ * answers it is a coding agent on somebody's laptop, a test double, or a person. So the call is
+ * reduced to what any of them can act on — a persona, a conversation, and the shape the answer
+ * must take — and everything provider-specific is left behind.
+ *
+ * There is no vocabulary here from whatever pipeline asked. A `role` and a `tier` travel because
+ * the performer has to choose a model; nothing else about the caller does.
+ */
+/** What the answer must be. */
+export declare enum DelegatedMode {
+    /** Prose or code. */
+    Text = "text",
+    /** Exactly one JSON object satisfying `outputSchema`. */
+    Json = "json",
+    /** A list of calls chosen from `tools`. */
+    Tools = "tools"
+}
+/** Who a message came from. Deliberately the four roles every chat API agrees on. */
+export declare enum DelegatedRole {
+    System = "system",
+    User = "user",
+    Assistant = "assistant",
+    Tool = "tool"
+}
+/** What shape an answer came back in. */
+export declare enum DelegatedResultKind {
+    Text = "text",
+    Json = "json",
+    ToolCalls = "tool-calls",
+    /** The performer could not answer. Treated as a malformed answer: asked again, with the reason. */
+    Error = "error"
+}
+export interface DelegatedToolCall {
+    id?: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+export interface DelegatedMessage {
+    role: DelegatedRole;
+    content: string;
+    /** Assistant turns that called tools. */
+    toolCalls?: DelegatedToolCall[];
+    /** Tool turns answer one call, and name the tool they answer. */
+    toolCallId?: string;
+    name?: string;
+}
+export interface DelegatedTool {
+    name: string;
+    description?: string;
+    /** JSON Schema of the arguments. */
+    parameters: Record<string, unknown>;
+}
+export type DelegatedToolChoice = 'auto' | 'none' | {
+    name: string;
+};
+export interface DelegatedTask {
+    id: string;
+    /** Which transport is expected to answer it — the key the application seated it under. */
+    delegate: string;
+    /** The performer's role name, for its own logging. Never load-bearing. */
+    role?: string;
+    /** Which power class the performer should run this on. */
+    tier?: string;
+    /** 0-based. Above zero means a previous answer was refused; `feedback` says why. */
+    attempt: number;
+    mode: DelegatedMode;
+    system?: string;
+    messages: DelegatedMessage[];
+    tools?: DelegatedTool[];
+    toolChoice?: DelegatedToolChoice;
+    outputSchema?: Record<string, unknown>;
+    /** A soft cap, stated so a performer can size its own call. */
+    maxOutputChars?: number;
+    feedback?: string;
+    /** ISO. A performer past this may say so rather than answer. */
+    expiresAt?: string;
+}
+export interface DelegatedUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+}
+export interface DelegatedResult {
+    taskId: string;
+    kind: DelegatedResultKind;
+    text?: string;
+    json?: unknown;
+    toolCalls?: DelegatedToolCall[];
+    error?: string;
+    /** What the performer spent. Recorded; it costs this deployment nothing. */
+    usage?: DelegatedUsage;
+    /** What the performer actually ran. Display only. */
+    model?: string;
+}
+/**
+ * How a delegated call reaches its performer.
+ *
+ * One method, because that is the whole seam: everything about routing, waiting, redelivery and
+ * giving up belongs to whoever implements it. A transport that cannot serve the call must THROW
+ * rather than answer with an error result — an error result is a bad answer, which is retried,
+ * while a transport that is gone is terminal.
+ */
+export interface DelegateTransport {
+    dispatch: (task: DelegatedTask, signal?: AbortSignal) => Promise<DelegatedResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/delegate/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/delegate/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,+BAA+B;AAC/B,oBAAY,aAAa;IACvB,qBAAqB;IACrB,IAAI,SAAS;IACb,yDAAyD;IACzD,IAAI,SAAS;IACb,2CAA2C;IAC3C,KAAK,UAAU;CAChB;AAED,qFAAqF;AACrF,oBAAY,aAAa;IACvB,MAAM,WAAW;IACjB,IAAI,SAAS;IACb,SAAS,cAAc;IACvB,IAAI,SAAS;CACd;AAED,yCAAyC;AACzC,oBAAY,mBAAmB;IAC7B,IAAI,SAAS;IACb,IAAI,SAAS;IACb,SAAS,eAAe;IACxB,mGAAmG;IACnG,KAAK,UAAU;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,aAAa,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,yCAAyC;IACzC,SAAS,CAAC,EAAE,iBAAiB,EAAE,CAAA;IAC/B,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACpC;AAED,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAEpE,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,0FAA0F;IAC1F,QAAQ,EAAE,MAAM,CAAA;IAChB,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,oFAAoF;IACpF,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,aAAa,CAAA;IACnB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,gBAAgB,EAAE,CAAA;IAC5B,KAAK,CAAC,EAAE,aAAa,EAAE,CAAA;IACvB,UAAU,CAAC,EAAE,mBAAmB,CAAA;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACtC,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,mBAAmB,CAAA;IACzB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,SAAS,CAAC,EAAE,iBAAiB,EAAE,CAAA;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4EAA4E;IAC5E,KAAK,CAAC,EAAE,cAAc,CAAA;IACtB,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,eAAe,CAAC,CAAA;CAClF"}

package/build/delegate/types.js

@@ -0,0 +1,39 @@
+/**
+ * The serializable form of one model call, for a performer outside this process.
+ *
+ * A delegated call cannot pass a `BaseChatModel` or a langchain message anywhere: the thing that
+ * answers it is a coding agent on somebody's laptop, a test double, or a person. So the call is
+ * reduced to what any of them can act on — a persona, a conversation, and the shape the answer
+ * must take — and everything provider-specific is left behind.
+ *
+ * There is no vocabulary here from whatever pipeline asked. A `role` and a `tier` travel because
+ * the performer has to choose a model; nothing else about the caller does.
+ */
+/** What the answer must be. */
+export var DelegatedMode;
+(function (DelegatedMode) {
+    /** Prose or code. */
+    DelegatedMode["Text"] = "text";
+    /** Exactly one JSON object satisfying `outputSchema`. */
+    DelegatedMode["Json"] = "json";
+    /** A list of calls chosen from `tools`. */
+    DelegatedMode["Tools"] = "tools";
+})(DelegatedMode || (DelegatedMode = {}));
+/** Who a message came from. Deliberately the four roles every chat API agrees on. */
+export var DelegatedRole;
+(function (DelegatedRole) {
+    DelegatedRole["System"] = "system";
+    DelegatedRole["User"] = "user";
+    DelegatedRole["Assistant"] = "assistant";
+    DelegatedRole["Tool"] = "tool";
+})(DelegatedRole || (DelegatedRole = {}));
+/** What shape an answer came back in. */
+export var DelegatedResultKind;
+(function (DelegatedResultKind) {
+    DelegatedResultKind["Text"] = "text";
+    DelegatedResultKind["Json"] = "json";
+    DelegatedResultKind["ToolCalls"] = "tool-calls";
+    /** The performer could not answer. Treated as a malformed answer: asked again, with the reason. */
+    DelegatedResultKind["Error"] = "error";
+})(DelegatedResultKind || (DelegatedResultKind = {}));
+//# sourceMappingURL=types.js.map

package/build/delegate/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/delegate/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,+BAA+B;AAC/B,MAAM,CAAN,IAAY,aAOX;AAPD,WAAY,aAAa;IACvB,qBAAqB;IACrB,8BAAa,CAAA;IACb,yDAAyD;IACzD,8BAAa,CAAA;IACb,2CAA2C;IAC3C,gCAAe,CAAA;AACjB,CAAC,EAPW,aAAa,KAAb,aAAa,QAOxB;AAED,qFAAqF;AACrF,MAAM,CAAN,IAAY,aAKX;AALD,WAAY,aAAa;IACvB,kCAAiB,CAAA;IACjB,8BAAa,CAAA;IACb,wCAAuB,CAAA;IACvB,8BAAa,CAAA;AACf,CAAC,EALW,aAAa,KAAb,aAAa,QAKxB;AAED,yCAAyC;AACzC,MAAM,CAAN,IAAY,mBAMX;AAND,WAAY,mBAAmB;IAC7B,oCAAa,CAAA;IACb,oCAAa,CAAA;IACb,+CAAwB,CAAA;IACxB,mGAAmG;IACnG,sCAAe,CAAA;AACjB,CAAC,EANW,mBAAmB,KAAnB,mBAAmB,QAM9B"}

package/build/files/types.d.ts

@@ -17,6 +17,16 @@
  * that stops a rich helper from satisfying this one.
  */
 export interface LlmFileProvider {
+    /**
+     * Stable identity of WHAT this provider reads — a project root, a sandbox id.
+     *
+     * A prompt plugin that caches resolved reads across calls has nothing else to key on:
+     * providers are late-bound and often rebuilt per request, so object identity says
+     * nothing, and a cache shared between two projects serves the first one's files to the
+     * second. A provider that supplies no key is treated as uncacheable rather than as one
+     * more anonymous member of a shared bucket.
+     */
+    key?: string;
     /** Read a file relative to the root. With `noThrow`, a missing file yields `''`. */
     readFile: (filePath: string, noThrow?: boolean) => Promise<string>;
     /** Glob for files relative to the root. */

package/build/files/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/files/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,eAAe;IAC9B,oFAAoF;IACpF,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAElE,2CAA2C;IAC3C,aAAa,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IAEtD,gFAAgF;IAChF,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAE/D,qFAAqF;IACrF,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACnE;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,eAAe,GAAG,CAAC,MAAM,eAAe,CAAC,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/files/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;OAQG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IAEZ,oFAAoF;IACpF,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAElE,2CAA2C;IAC3C,aAAa,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IAEtD,gFAAgF;IAChF,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAE/D,qFAAqF;IACrF,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACnE;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,eAAe,GAAG,CAAC,MAAM,eAAe,CAAC,CAAA"}

package/build/index.d.ts

@@ -3,4 +3,5 @@ export type * from './types.js';
 export type * from './spectator/types.js';
 export type * from './files/types.js';
 export * from './files/utils.js';
+export * from './delegate/index.js';
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,mBAAmB,YAAY,CAAA;AAC/B,mBAAmB,sBAAsB,CAAA;AACzC,mBAAmB,kBAAkB,CAAA;AACrC,cAAc,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,mBAAmB,YAAY,CAAA;AAC/B,mBAAmB,sBAAsB,CAAA;AACzC,mBAAmB,kBAAkB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,qBAAqB,CAAA"}

package/build/index.js

@@ -1,3 +1,4 @@
 export * from './consts.js';
 export * from './files/utils.js';
+export * from './delegate/index.js';
 //# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAI3B,cAAc,kBAAkB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAI3B,cAAc,kBAAkB,CAAA;AAChC,cAAc,qBAAqB,CAAA"}

package/build/types.d.ts

@@ -29,6 +29,12 @@ export interface ModelConfigPatch {
     maxTokensCap?: number;
     topP?: number;
     disableThinking?: boolean;
+    /** Total window the model accepts (input + output). Informational / validation only. */
+    contextWindow?: number;
+    /** What the PROVIDER can emit in one request. Hard ceiling for `maxTokens`/`maxTokensCap`. */
+    maxOutput?: number;
+    /** The window is shared between input and output rather than input-only. */
+    combinedWindow?: boolean;
 }
 /** A JSON-safe model override: a config alias, or a partial config patch. */
 export type ModelConfigOverride = string | ModelConfigPatch;
@@ -44,6 +50,12 @@ export interface ModelPolicy {
     roleOverrides?: Partial<Record<ModelRole, ModelRole>>;
     /** "Pin a role to a specific model/config" — alias or partial config override. */
     modelOverrides?: Partial<Record<ModelRole, ModelConfigOverride>>;
+    /**
+     * Role resolved by `ExecutionService.utility` for cheap side calls. Defaults to
+     * `UTILITY_ROLE`; name another alias when the deployment calls its cheap tier
+     * something else. `roleOverrides` still applies on top of whichever one is used.
+     */
+    utilityRole?: ModelRole;
 }
 /**
  * Lifetime of a provider-side prompt cache entry. `'1h'` costs roughly twice as much to
@@ -120,9 +132,16 @@ export interface ExecutionState {
     /** Role + skills for this level; merged downward by `ExecutionService`. */
     prompt?: PromptPolicy;
 }
-/** Resumable state of a task-level execution. */
+/**
+ * The task level's own fields.
+ *
+ * `phase`, `completed` and `cursor` are LABELS — for a trace line, a prompt, a log — and never a
+ * workflow position. Recoverable position lives on a pipeline run row (`@owlmeans/agent`), which is
+ * a single authority; an execution that also claimed to know where a run stood would be a second
+ * one, and the two would disagree the first time a step wrote only one of them.
+ */
 export interface TaskExecutionState extends ExecutionState {
-    /** Abstract workflow position for checkpoint/resume. */
+    /** A label for the stage a task considers itself in. Never read back to decide anything. */
     phase?: string;
     completed?: string[];
     cursor?: string;
@@ -171,11 +190,18 @@ export interface NullCapture {
         tool_calls?: unknown;
     } | null;
     diagnostics: {
+        /** Whatever the provider called it — OpenAI's `finish_reason` or Anthropic's `stop_reason`. */
         finishReason?: string;
         inputTokens?: number;
         outputTokens?: number;
         reasoningTokens?: number;
         contentEmpty: boolean;
+        /**
+         * Content arrived, but none of it was text — the shape of an answer that was all reasoning.
+         * Distinguishes "spent the budget thinking" from "returned nothing at all", which
+         * `contentEmpty` alone cannot.
+         */
+        thinkingOnly?: boolean;
         hadToolCall: boolean;
     };
 }

package/build/types.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/llm-common",
-  "version": "0.1.18-rc.2",
+  "version": "0.1.18-rc.20",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -21,7 +21,7 @@
     }
   },
   "devDependencies": {
-    "@langchain/core": "^1.1.39",
+    "@langchain/core": "^1.2.9",
     "@owlmeans/dep-config": "workspace:*",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"

package/src/consts.ts

@@ -11,6 +11,20 @@ export enum ModelProvider {
   Anthropic = 'anthropic',
   /** Any OpenAI-compatible endpoint — OpenRouter, HuggingFace router, Together, vLLM, … */
   Compatible = 'compatible',
+  /**
+   * No endpoint at all: the call is handed to whoever holds the execution.
+   *
+   * A delegated model does not talk to a provider. It packages the call — the system prompt, the
+   * conversation, the tools or the schema — and hands it to a transport the application seated,
+   * which carries it to something outside this process entirely: a coding agent driving the
+   * application through a connector, a human, a test. The answer comes back the same way and is
+   * turned into a completion the rest of the stack cannot tell apart from a provider's.
+   *
+   * It exists so that "who performs this call" can be a property of the SESSION rather than of the
+   * code: the same pipeline, the same prompts and the same retry rules, billed to somebody else's
+   * model.
+   */
+  Delegated = 'delegated',
 }
 
 /**
@@ -96,3 +110,11 @@ export const PROMPT_BLOCK_ORDER: readonly PromptBlock[] = [
 
 /** Sort weight of a skill that declares none — see `SkillDefinition.order`. */
 export const DEFAULT_SKILL_ORDER = 100
+
+/**
+ * Conventional {@link ModelRole} for the cheap side calls the layer makes on its own
+ * behalf — a relevance pick, a classification, a one-line judgement — rather than for the
+ * work a caller asked for. A deployment that names its cheap tier differently points
+ * `ModelPolicy.utilityRole` at its own alias; nothing else has to change.
+ */
+export const UTILITY_ROLE = 'utility'

package/src/delegate/index.ts

@@ -0,0 +1 @@
+export * from './types.js'

package/src/delegate/types.ts

@@ -0,0 +1,116 @@
+/**
+ * The serializable form of one model call, for a performer outside this process.
+ *
+ * A delegated call cannot pass a `BaseChatModel` or a langchain message anywhere: the thing that
+ * answers it is a coding agent on somebody's laptop, a test double, or a person. So the call is
+ * reduced to what any of them can act on — a persona, a conversation, and the shape the answer
+ * must take — and everything provider-specific is left behind.
+ *
+ * There is no vocabulary here from whatever pipeline asked. A `role` and a `tier` travel because
+ * the performer has to choose a model; nothing else about the caller does.
+ */
+
+/** What the answer must be. */
+export enum DelegatedMode {
+  /** Prose or code. */
+  Text = 'text',
+  /** Exactly one JSON object satisfying `outputSchema`. */
+  Json = 'json',
+  /** A list of calls chosen from `tools`. */
+  Tools = 'tools',
+}
+
+/** Who a message came from. Deliberately the four roles every chat API agrees on. */
+export enum DelegatedRole {
+  System = 'system',
+  User = 'user',
+  Assistant = 'assistant',
+  Tool = 'tool',
+}
+
+/** What shape an answer came back in. */
+export enum DelegatedResultKind {
+  Text = 'text',
+  Json = 'json',
+  ToolCalls = 'tool-calls',
+  /** The performer could not answer. Treated as a malformed answer: asked again, with the reason. */
+  Error = 'error',
+}
+
+export interface DelegatedToolCall {
+  id?: string
+  name: string
+  args: Record<string, unknown>
+}
+
+export interface DelegatedMessage {
+  role: DelegatedRole
+  content: string
+  /** Assistant turns that called tools. */
+  toolCalls?: DelegatedToolCall[]
+  /** Tool turns answer one call, and name the tool they answer. */
+  toolCallId?: string
+  name?: string
+}
+
+export interface DelegatedTool {
+  name: string
+  description?: string
+  /** JSON Schema of the arguments. */
+  parameters: Record<string, unknown>
+}
+
+export type DelegatedToolChoice = 'auto' | 'none' | { name: string }
+
+export interface DelegatedTask {
+  id: string
+  /** Which transport is expected to answer it — the key the application seated it under. */
+  delegate: string
+  /** The performer's role name, for its own logging. Never load-bearing. */
+  role?: string
+  /** Which power class the performer should run this on. */
+  tier?: string
+  /** 0-based. Above zero means a previous answer was refused; `feedback` says why. */
+  attempt: number
+  mode: DelegatedMode
+  system?: string
+  messages: DelegatedMessage[]
+  tools?: DelegatedTool[]
+  toolChoice?: DelegatedToolChoice
+  outputSchema?: Record<string, unknown>
+  /** A soft cap, stated so a performer can size its own call. */
+  maxOutputChars?: number
+  feedback?: string
+  /** ISO. A performer past this may say so rather than answer. */
+  expiresAt?: string
+}
+
+export interface DelegatedUsage {
+  inputTokens?: number
+  outputTokens?: number
+}
+
+export interface DelegatedResult {
+  taskId: string
+  kind: DelegatedResultKind
+  text?: string
+  json?: unknown
+  toolCalls?: DelegatedToolCall[]
+  error?: string
+  /** What the performer spent. Recorded; it costs this deployment nothing. */
+  usage?: DelegatedUsage
+  /** What the performer actually ran. Display only. */
+  model?: string
+}
+
+/**
+ * How a delegated call reaches its performer.
+ *
+ * One method, because that is the whole seam: everything about routing, waiting, redelivery and
+ * giving up belongs to whoever implements it. A transport that cannot serve the call must THROW
+ * rather than answer with an error result — an error result is a bad answer, which is retried,
+ * while a transport that is gone is terminal.
+ */
+export interface DelegateTransport {
+  dispatch: (task: DelegatedTask, signal?: AbortSignal) => Promise<DelegatedResult>
+}

package/src/files/types.ts

@@ -17,6 +17,17 @@
  * that stops a rich helper from satisfying this one.
  */
 export interface LlmFileProvider {
+  /**
+   * Stable identity of WHAT this provider reads — a project root, a sandbox id.
+   *
+   * A prompt plugin that caches resolved reads across calls has nothing else to key on:
+   * providers are late-bound and often rebuilt per request, so object identity says
+   * nothing, and a cache shared between two projects serves the first one's files to the
+   * second. A provider that supplies no key is treated as uncacheable rather than as one
+   * more anonymous member of a shared bucket.
+   */
+  key?: string
+
   /** Read a file relative to the root. With `noThrow`, a missing file yields `''`. */
   readFile: (filePath: string, noThrow?: boolean) => Promise<string>
 

package/src/index.ts

@@ -4,3 +4,4 @@ export type * from './types.js'
 export type * from './spectator/types.js'
 export type * from './files/types.js'
 export * from './files/utils.js'
+export * from './delegate/index.js'

package/src/types.ts

@@ -32,6 +32,12 @@ export interface ModelConfigPatch {
   maxTokensCap?: number
   topP?: number
   disableThinking?: boolean
+  /** Total window the model accepts (input + output). Informational / validation only. */
+  contextWindow?: number
+  /** What the PROVIDER can emit in one request. Hard ceiling for `maxTokens`/`maxTokensCap`. */
+  maxOutput?: number
+  /** The window is shared between input and output rather than input-only. */
+  combinedWindow?: boolean
 }
 
 /** A JSON-safe model override: a config alias, or a partial config patch. */
@@ -49,6 +55,12 @@ export interface ModelPolicy {
   roleOverrides?: Partial<Record<ModelRole, ModelRole>>
   /** "Pin a role to a specific model/config" — alias or partial config override. */
   modelOverrides?: Partial<Record<ModelRole, ModelConfigOverride>>
+  /**
+   * Role resolved by `ExecutionService.utility` for cheap side calls. Defaults to
+   * `UTILITY_ROLE`; name another alias when the deployment calls its cheap tier
+   * something else. `roleOverrides` still applies on top of whichever one is used.
+   */
+  utilityRole?: ModelRole
 }
 
 /**
@@ -131,9 +143,16 @@ export interface ExecutionState {
   prompt?: PromptPolicy
 }
 
-/** Resumable state of a task-level execution. */
+/**
+ * The task level's own fields.
+ *
+ * `phase`, `completed` and `cursor` are LABELS — for a trace line, a prompt, a log — and never a
+ * workflow position. Recoverable position lives on a pipeline run row (`@owlmeans/agent`), which is
+ * a single authority; an execution that also claimed to know where a run stood would be a second
+ * one, and the two would disagree the first time a step wrote only one of them.
+ */
 export interface TaskExecutionState extends ExecutionState {
-  /** Abstract workflow position for checkpoint/resume. */
+  /** A label for the stage a task considers itself in. Never read back to decide anything. */
   phase?: string
   completed?: string[]
   cursor?: string
@@ -181,11 +200,18 @@ export interface NullCapture {
     tool_calls?: unknown
   } | null
   diagnostics: {
+    /** Whatever the provider called it — OpenAI's `finish_reason` or Anthropic's `stop_reason`. */
     finishReason?: string
     inputTokens?: number
     outputTokens?: number
     reasoningTokens?: number
     contentEmpty: boolean
+    /**
+     * Content arrived, but none of it was text — the shape of an answer that was all reasoning.
+     * Distinguishes "spent the budget thinking" from "returned nothing at all", which
+     * `contentEmpty` alone cannot.
+     */
+    thinkingOnly?: boolean
     hadToolCall: boolean
   }
 }