@owlmeans/llm-common 0.1.14

package/README.md

@@ -0,0 +1,106 @@
+# @owlmeans/llm-common
+
+Serializable contracts for LLM inference and execution. Runtime-free — it holds the enums,
+policy shapes and record formats that both an inference runtime (`@owlmeans/llm`) and a
+persistence/queue consumer need to name the same things.
+
+## Overview
+
+- Provider identifiers, effort tiers, execution levels and structured-output modes
+- The inheritable `ModelPolicy` and its JSON-safe `ModelConfigPatch` / `ModelConfigOverride`
+- `ExecutionState` / `TaskExecutionState` — what an execution looks like once its
+  collaborators (models, file access, live handles) are stripped off
+- Spectator record contracts and the `NullCapture` diagnostic
+- No `@langchain/*` runtime dependency: safe to import from a browser bundle, a queue
+  worker, or a package that must not pull an inference SDK
+
+Split rationale: the dependency direction is one-way. A consumer's own contracts package
+extends these; `@owlmeans/llm` implements against them.
+
+## Installation
+
+```bash
+bun add @owlmeans/llm-common
+```
+
+## Usage
+
+Naming a role and a policy without depending on any inference runtime:
+
+```typescript
+import { ExecutionEffort, ModelProvider } from '@owlmeans/llm-common'
+import type { ModelPolicy } from '@owlmeans/llm-common'
+
+export enum MyRole {
+  Analyst = 'analyst',
+  Coder = 'coder',
+}
+
+export const DEFAULT_POLICY: ModelPolicy = {
+  effort: ExecutionEffort.Standard,
+  modelOverrides: { [MyRole.Coder]: { maxTokens: 16000 } },
+}
+```
+
+Extending the serializable state with domain context:
+
+```typescript
+import type { ExecutionState, LlmPurpose } from '@owlmeans/llm-common'
+
+export interface MyPurpose extends LlmPurpose {
+  agent?: string
+}
+
+export interface MyExecutionState extends ExecutionState {
+  purpose: MyPurpose
+  projectId?: string
+}
+```
+
+## API
+
+### Constants
+
+| Export | Description |
+|--------|-------------|
+| `ModelProvider` | `OpenAI` · `Anthropic` · `Compatible` — each maps to an `LlmPlugin` type in `@owlmeans/llm`. |
+| `ExecutionLevel` | `Project` → `Task` → `Helper`; an execution is refined downward only. |
+| `ExecutionEffort` | `Economy` · `Standard` · `High` · `Max` — the one "how hard should this run" axis. |
+| `StructuredMode` | `Native` (provider JSON-schema mode) vs `Tool` (forced tool call). |
+| `SpectatorContentType` | `Text` · `Json` · `ToolCall`. |
+| `SPECTATOR_GENERAL` | Default entry kind for consumers that do not classify calls. |
+
+### Types
+
+| Export | Description |
+|--------|-------------|
+| `ModelRole` | Open `string`. Declare your own enum; its values stay assignable. |
+| `ModelConfigPatch` | JSON-safe subset of a runtime model config — never credentials. |
+| `ModelConfigOverride` | `string` (a config alias) or a `ModelConfigPatch`. |
+| `ModelPolicy` | `{ effort, roleOverrides?, modelOverrides? }` — inherited by every refinement. |
+| `ExecutionState` | `{ level, purpose, policy }` — the persistable core. |
+| `TaskExecutionState` | Adds `phase` / `completed` / `cursor` / `data` for checkpoint & resume. |
+| `LlmPurpose` | `{ type?, dedication? }` — observability metadata carried on every call. |
+| `NullCapture`, `NullKind` | Full diagnostics of a call that returned nothing usable. |
+| `SpectatorArgument`, `SpectatorEntry`, `SpectatorEntryLogged`, `SpectatorEntryMessage` | The record format an observability sink stores. |
+
+## Related
+
+- `@owlmeans/llm` — the runtime: model, provider plugins, model factory, execution service
+
+<!-- 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-common.instructions.md

@@ -0,0 +1,53 @@
+---
+description: "How to use @owlmeans/llm-common — runtime-free serializable contracts for LLM inference and execution, and how to extend them for a domain."
+applyTo: "**/*.ts, **/*.tsx"
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/llm-common
+
+**Layer:** Core
+**Install:** `"@owlmeans/llm-common": "^0.1.14"` in `dependencies`
+
+The contracts half of the LLM stack. **No `@langchain/*` runtime dependency** — importable
+from a browser bundle or a queue worker. Dependency direction is one-way: a domain contracts
+package extends these; `@owlmeans/llm` implements against them.
+
+## Key Exports
+
+| Export | Description |
+|--------|-------------|
+| `ModelProvider` | `OpenAI` · `Anthropic` · `Compatible` — each is an `LlmPlugin.type`. |
+| `ExecutionLevel` / `ExecutionEffort` | `Project`→`Task`→`Helper`; `Economy`/`Standard`/`High`/`Max`. |
+| `StructuredMode` | `Native` vs `Tool` structured output. |
+| `ModelRole` | Open `string` — declare your own enum. |
+| `ModelConfigPatch` / `ModelConfigOverride` / `ModelPolicy` | JSON-safe model selection. |
+| `ExecutionState` / `TaskExecutionState` | The persistable execution core + resumable fields. |
+| `LlmPurpose` | `{ type?, dedication? }` observability metadata. |
+| `NullCapture`, `NullKind` | Diagnostics of a call that returned nothing usable. |
+| `SpectatorArgument` / `SpectatorEntry` / `SpectatorEntryLogged` / `SpectatorEntryMessage`, `SpectatorContentType` | Observability records. |
+
+## Rules
+
+- Extend, never fork: `interface MyPurpose extends LlmPurpose`,
+  `interface MyExecutionState extends ExecutionState`.
+- For a domain task state, take the base fields from your own `ExecutionState` and mix in
+  only the resumable half: `Omit<TaskExecutionState, keyof ExecutionState>`.
+- `ModelRole` and `SpectatorEntry.kind` are open strings so a consumer's enum stays
+  assignable — narrow them on your own interfaces.
+- Nothing that fails `JSON.stringify` belongs here: no model instances, credentials, file
+  handles or callbacks. `ModelConfig` (with `secret`/`headers`/`fallback`) lives in
+  `@owlmeans/llm`.
+
+## Usage
+
+```typescript
+import { ExecutionEffort } from '@owlmeans/llm-common'
+import type { ModelPolicy } from '@owlmeans/llm-common'
+
+export const DEFAULT_POLICY: ModelPolicy = { effort: ExecutionEffort.Standard }
+```
+
+## Depends On
+
+Nothing at runtime (`@langchain/core` is a dev dependency, for one type).

package/agent-meta/manifest.json

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

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

@@ -0,0 +1,74 @@
+---
+name: llm-common
+description: How to use @owlmeans/llm-common — runtime-free serializable contracts for LLM inference and execution (ModelProvider, ExecutionEffort/Level, ModelPolicy, ExecutionState, spectator records, NullCapture). Auto-invoked when importing those contracts or extending them for a domain.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/llm-common
+
+**Layer:** Core
+**Install:** `"@owlmeans/llm-common": "^0.1.14"` 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.
+The dependency direction is one-way: a domain contracts package extends these;
+`@owlmeans/llm` implements against them.
+
+## Key Exports
+
+| Export | Description |
+|--------|-------------|
+| `ModelProvider` | `OpenAI` · `Anthropic` · `Compatible`. Each value is an `LlmPlugin.type` in `@owlmeans/llm`. |
+| `ExecutionLevel` | `Project` → `Task` → `Helper`. Refinement is downward only. |
+| `ExecutionEffort` | `Economy` · `Standard` · `High` · `Max` — the single "how hard should this run" axis. |
+| `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. |
+| `ExecutionState` / `TaskExecutionState` | The persistable core (`level`/`purpose`/`policy`, plus `phase`/`completed`/`cursor`/`data`). |
+| `LlmPurpose` | `{ type?, dedication? }` — metadata carried on every model call. |
+| `NullCapture`, `NullKind` | Full diagnostics of a call that returned nothing usable. |
+| `SpectatorArgument`, `SpectatorEntry`, `SpectatorEntryLogged`, `SpectatorEntryMessage` | What an observability sink stores. |
+
+## Extension rules
+
+Open types are open **on purpose** — extend, do not fork:
+
+```typescript
+// 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.
+export interface MyPurpose extends LlmPurpose { agent?: string }
+export interface MyExecutionState extends ExecutionState {
+  purpose: MyPurpose
+  projectId?: string
+}
+
+// A task state adds domain fields to the RESUMABLE half only — the base fields
+// come from your own ExecutionState, so omit them from the llm task state.
+export interface MyTaskState
+  extends MyExecutionState, Omit<LlmTaskExecutionState, keyof LlmExecutionState> {
+  story?: Story
+}
+```
+
+`SpectatorEntry.kind` is an open `string` for the same reason: declare your own kind enum
+and narrow it on your own entry interface.
+
+## What must NOT go here
+
+Anything that cannot survive `JSON.stringify` or that needs an inference SDK: model
+instances, credentials, file handles, callbacks, `ModelConfig` (it carries `secret` /
+`headers` / `fallback` — that lives in `@owlmeans/llm`).
+
+## Depends On
+
+Nothing at runtime. `@langchain/core` is a **dev** dependency, for the `UsageMetadata` type
+on a spectator message only.
+
+## Related
+
+- [[llm]] — the runtime that implements these contracts

package/build/consts.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Inference provider family a {@link ModelConfigPatch}/config targets. Each value is
+ * the `type` of an `LlmPlugin` registered in `@owlmeans/llm`; a downstream package
+ * can register additional plugins under its own type string.
+ */
+export declare enum ModelProvider {
+    /** Proprietary OpenAI endpoint (Responses API for the `gpt-5*` / `codex-*` families). */
+    OpenAI = "openai",
+    /** Anthropic messages API. */
+    Anthropic = "anthropic",
+    /** Any OpenAI-compatible endpoint — OpenRouter, HuggingFace router, Together, vLLM, … */
+    Compatible = "compatible"
+}
+/**
+ * Refinement level of an execution. An execution is refined downward only:
+ * root → task → helper, each step producing a new frozen object.
+ */
+export declare enum ExecutionLevel {
+    Project = "project",
+    Task = "task",
+    Helper = "helper"
+}
+/**
+ * Orthogonal capability tier carried by a {@link ModelPolicy} — the single,
+ * inheritable "how hard should this run" axis. Maps to a JSON-safe model config
+ * patch through the effort table in `@owlmeans/llm`.
+ */
+export declare enum ExecutionEffort {
+    Economy = "economy",
+    Standard = "standard",
+    High = "high",
+    Max = "max"
+}
+/**
+ * How a model is asked to produce a schema-conforming object.
+ *
+ * - `Native` — the provider's own JSON-schema mode
+ *   (`response_format: { type: 'json_schema' }`).
+ * - `Tool` — the forced-`tool_choice` tool-calling hack: a synthetic function whose
+ *   parameters ARE the schema, with the tool choice pinned to it.
+ *
+ * The decision is per provider plugin, overridable per model config.
+ */
+export declare enum StructuredMode {
+    Native = "native",
+    Tool = "tool"
+}
+/** Content shape of a single logged spectator message. */
+export declare enum SpectatorContentType {
+    Text = "text",
+    Json = "json",
+    ToolCall = "tool_call"
+}
+/** Default spectator entry kind for consumers that do not classify their calls. */
+export declare const SPECTATOR_GENERAL = "general";
+//# 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":"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"}

package/build/consts.js

@@ -0,0 +1,61 @@
+/**
+ * Inference provider family a {@link ModelConfigPatch}/config targets. Each value is
+ * the `type` of an `LlmPlugin` registered in `@owlmeans/llm`; a downstream package
+ * can register additional plugins under its own type string.
+ */
+export var ModelProvider;
+(function (ModelProvider) {
+    /** Proprietary OpenAI endpoint (Responses API for the `gpt-5*` / `codex-*` families). */
+    ModelProvider["OpenAI"] = "openai";
+    /** Anthropic messages API. */
+    ModelProvider["Anthropic"] = "anthropic";
+    /** Any OpenAI-compatible endpoint — OpenRouter, HuggingFace router, Together, vLLM, … */
+    ModelProvider["Compatible"] = "compatible";
+})(ModelProvider || (ModelProvider = {}));
+/**
+ * Refinement level of an execution. An execution is refined downward only:
+ * root → task → helper, each step producing a new frozen object.
+ */
+export var ExecutionLevel;
+(function (ExecutionLevel) {
+    ExecutionLevel["Project"] = "project";
+    ExecutionLevel["Task"] = "task";
+    ExecutionLevel["Helper"] = "helper";
+})(ExecutionLevel || (ExecutionLevel = {}));
+/**
+ * Orthogonal capability tier carried by a {@link ModelPolicy} — the single,
+ * inheritable "how hard should this run" axis. Maps to a JSON-safe model config
+ * patch through the effort table in `@owlmeans/llm`.
+ */
+export var ExecutionEffort;
+(function (ExecutionEffort) {
+    ExecutionEffort["Economy"] = "economy";
+    ExecutionEffort["Standard"] = "standard";
+    ExecutionEffort["High"] = "high";
+    ExecutionEffort["Max"] = "max";
+})(ExecutionEffort || (ExecutionEffort = {}));
+/**
+ * How a model is asked to produce a schema-conforming object.
+ *
+ * - `Native` — the provider's own JSON-schema mode
+ *   (`response_format: { type: 'json_schema' }`).
+ * - `Tool` — the forced-`tool_choice` tool-calling hack: a synthetic function whose
+ *   parameters ARE the schema, with the tool choice pinned to it.
+ *
+ * The decision is per provider plugin, overridable per model config.
+ */
+export var StructuredMode;
+(function (StructuredMode) {
+    StructuredMode["Native"] = "native";
+    StructuredMode["Tool"] = "tool";
+})(StructuredMode || (StructuredMode = {}));
+/** Content shape of a single logged spectator message. */
+export var SpectatorContentType;
+(function (SpectatorContentType) {
+    SpectatorContentType["Text"] = "text";
+    SpectatorContentType["Json"] = "json";
+    SpectatorContentType["ToolCall"] = "tool_call";
+})(SpectatorContentType || (SpectatorContentType = {}));
+/** Default spectator entry kind for consumers that do not classify their calls. */
+export const SPECTATOR_GENERAL = 'general';
+//# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -0,0 +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"}

package/build/index.d.ts

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

package/build/index.d.ts.map

@@ -0,0 +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"}

package/build/index.js

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

package/build/index.js.map

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

package/build/spectator/types.d.ts

@@ -0,0 +1,37 @@
+import type { UsageMetadata } from '@langchain/core/messages';
+import type { SpectatorContentType } from '../consts.js';
+import type { LlmPurpose } from '../types.js';
+/** What a caller hands to the spectator sink for a single completed model call. */
+export interface SpectatorArgument {
+    action: string;
+    retries: number;
+    tries?: number;
+    messages: SpectatorEntryMessage[];
+    startedAt?: number;
+}
+/** A stored spectator record — the argument plus the resolved call context. */
+export interface SpectatorEntry extends SpectatorArgument {
+    /**
+     * Consumer-defined classification of the call. Open `string` so a consumer can
+     * declare its own enum (e.g. `coder` / `fixer` / `general`) and stay assignable.
+     */
+    kind: string;
+    model: string;
+    purpose: LlmPurpose;
+    timestamp: number;
+}
+/** A spectator record that has been persisted and has an identity. */
+export interface SpectatorEntryLogged extends SpectatorEntry {
+    id: string;
+}
+/** One message (prompt or completion) inside a spectator entry. */
+export interface SpectatorEntryMessage {
+    type: string;
+    callType: string;
+    content: string;
+    name?: string;
+    contentType: SpectatorContentType;
+    usage?: UsageMetadata;
+    raw?: string;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/spectator/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C,mFAAmF;AACnF,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,qBAAqB,EAAE,CAAA;IACjC,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,+EAA+E;AAC/E,MAAM,WAAW,cAAe,SAAQ,iBAAiB;IACvD;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,UAAU,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,sEAAsE;AACtE,MAAM,WAAW,oBAAqB,SAAQ,cAAc;IAC1D,EAAE,EAAE,MAAM,CAAA;CACX;AAED,mEAAmE;AACnE,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,oBAAoB,CAAA;IACjC,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,GAAG,CAAC,EAAE,MAAM,CAAA;CACb"}

package/build/spectator/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/spectator/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/spectator/types.ts"],"names":[],"mappings":""}

package/build/types.d.ts

@@ -0,0 +1,118 @@
+import type { ExecutionEffort, ExecutionLevel } from './consts.js';
+/**
+ * Free-form observability metadata attached to every model call — forwarded to the
+ * inference provider as run metadata and recorded on every spectator entry. Kept
+ * intentionally small; a consumer extends it with its own domain fields.
+ */
+export interface LlmPurpose {
+    /** Coarse classification of the caller (e.g. `'coder'`, `'analyst'`). */
+    type?: string;
+    /** Narrow, per-call refinement — set by `ExecutionService.forHelper`. */
+    dedication?: string;
+}
+/**
+ * Serializable role name used to select a model. Deliberately an open `string`:
+ * a consumer declares its own role enum (whose values are strings) and it stays
+ * assignable here.
+ */
+export type ModelRole = string;
+/**
+ * JSON-safe subset of the runtime `ModelConfig` (`@owlmeans/llm`). Mirrors only the
+ * serializable, tier-relevant fields — never `provider` / `secret` / `headers` /
+ * `fallback`. Lives here so an execution state can be persisted and replayed.
+ */
+export interface ModelConfigPatch {
+    preset?: string;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    maxTokensCap?: number;
+    topP?: number;
+    disableThinking?: boolean;
+}
+/** A JSON-safe model override: a config alias, or a partial config patch. */
+export type ModelConfigOverride = string | ModelConfigPatch;
+/**
+ * A single, inheritable model-selection policy carried by every execution.
+ * Resolution precedence (see `ExecutionService.model`):
+ * roleOverride → modelOverride → effort tier → `LlmService.getModel`.
+ */
+export interface ModelPolicy {
+    /** Orthogonal capability tier. */
+    effort: ExecutionEffort;
+    /** "Use role X wherever role Y is requested" — remap an entire sub-flow's roles. */
+    roleOverrides?: Partial<Record<ModelRole, ModelRole>>;
+    /** "Pin a role to a specific model/config" — alias or partial config override. */
+    modelOverrides?: Partial<Record<ModelRole, ModelConfigOverride>>;
+}
+/**
+ * Serializable execution state — no functions, no file access, no model instances.
+ * The runtime `Execution` (`@owlmeans/llm`) = this state + attached collaborators.
+ * A consumer extends this interface with its own domain fields; everything declared
+ * on the extension is carried into the snapshot automatically.
+ */
+export interface ExecutionState {
+    level: ExecutionLevel;
+    purpose: LlmPurpose;
+    policy: ModelPolicy;
+}
+/** Resumable state of a task-level execution. */
+export interface TaskExecutionState extends ExecutionState {
+    /** Abstract workflow position for checkpoint/resume. */
+    phase?: string;
+    completed?: string[];
+    cursor?: string;
+    data?: Record<string, unknown>;
+}
+/** Which model call produced a null/unusable result — carried by {@link NullCapture}. */
+export type NullKind = 'ask' | 'talk' | 'invoke' | 'request';
+/**
+ * Full diagnostic capture of a model call that returned nothing usable. Emitted by the
+ * model to the spectator's `captureNull` sink so a stalled/empty provider response can
+ * be replayed and diagnosed after the fact (finish reason, token accounting, whether a
+ * tool call was attempted, the exact request that produced it).
+ */
+export interface NullCapture {
+    meta: {
+        kind: NullKind;
+        action: string;
+        purpose?: LlmPurpose;
+        attempt: number;
+        id: string;
+        timestamp: number;
+        elapsedMs: number;
+    };
+    model: {
+        id?: string;
+        provider?: string;
+        baseUrl?: string;
+        maxTokens?: number;
+        reasoning?: unknown;
+        temperature?: number;
+        topP?: number;
+    };
+    request: {
+        messages: unknown[];
+        schema?: {
+            toolName: string;
+            innerSchema: unknown;
+        };
+        useCache: boolean;
+    };
+    response: {
+        content: unknown;
+        additional_kwargs?: unknown;
+        response_metadata?: unknown;
+        usage_metadata?: unknown;
+        tool_calls?: unknown;
+    } | null;
+    diagnostics: {
+        finishReason?: string;
+        inputTokens?: number;
+        outputTokens?: number;
+        reasoningTokens?: number;
+        contentEmpty: boolean;
+        hadToolCall: boolean;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

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

package/build/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@owlmeans/llm-common",
+  "version": "0.1.14",
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "sleep 171 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
+    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+  },
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "require": "./build/index.js",
+      "default": "./build/index.js",
+      "module": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "devDependencies": {
+    "@langchain/core": "^1.1.39",
+    "@owlmeans/dep-config": "workspace:*",
+    "nodemon": "^3.1.14",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/consts.ts

@@ -0,0 +1,61 @@
+
+/**
+ * Inference provider family a {@link ModelConfigPatch}/config targets. Each value is
+ * the `type` of an `LlmPlugin` registered in `@owlmeans/llm`; a downstream package
+ * can register additional plugins under its own type string.
+ */
+export enum ModelProvider {
+  /** Proprietary OpenAI endpoint (Responses API for the `gpt-5*` / `codex-*` families). */
+  OpenAI = 'openai',
+  /** Anthropic messages API. */
+  Anthropic = 'anthropic',
+  /** Any OpenAI-compatible endpoint — OpenRouter, HuggingFace router, Together, vLLM, … */
+  Compatible = 'compatible',
+}
+
+/**
+ * Refinement level of an execution. An execution is refined downward only:
+ * root → task → helper, each step producing a new frozen object.
+ */
+export enum ExecutionLevel {
+  Project = 'project',
+  Task = 'task',
+  Helper = 'helper',
+}
+
+/**
+ * Orthogonal capability tier carried by a {@link ModelPolicy} — the single,
+ * inheritable "how hard should this run" axis. Maps to a JSON-safe model config
+ * patch through the effort table in `@owlmeans/llm`.
+ */
+export enum ExecutionEffort {
+  Economy = 'economy',
+  Standard = 'standard',
+  High = 'high',
+  Max = 'max',
+}
+
+/**
+ * How a model is asked to produce a schema-conforming object.
+ *
+ * - `Native` — the provider's own JSON-schema mode
+ *   (`response_format: { type: 'json_schema' }`).
+ * - `Tool` — the forced-`tool_choice` tool-calling hack: a synthetic function whose
+ *   parameters ARE the schema, with the tool choice pinned to it.
+ *
+ * The decision is per provider plugin, overridable per model config.
+ */
+export enum StructuredMode {
+  Native = 'native',
+  Tool = 'tool',
+}
+
+/** Content shape of a single logged spectator message. */
+export enum SpectatorContentType {
+  Text = 'text',
+  Json = 'json',
+  ToolCall = 'tool_call',
+}
+
+/** Default spectator entry kind for consumers that do not classify their calls. */
+export const SPECTATOR_GENERAL = 'general'

package/src/index.ts

@@ -0,0 +1,4 @@
+
+export * from './consts.js'
+export type * from './types.js'
+export type * from './spectator/types.js'

package/src/spectator/types.ts

@@ -0,0 +1,40 @@
+import type { UsageMetadata } from '@langchain/core/messages'
+import type { SpectatorContentType } from '../consts.js'
+import type { LlmPurpose } from '../types.js'
+
+/** What a caller hands to the spectator sink for a single completed model call. */
+export interface SpectatorArgument {
+  action: string
+  retries: number
+  tries?: number
+  messages: SpectatorEntryMessage[]
+  startedAt?: number
+}
+
+/** A stored spectator record — the argument plus the resolved call context. */
+export interface SpectatorEntry extends SpectatorArgument {
+  /**
+   * Consumer-defined classification of the call. Open `string` so a consumer can
+   * declare its own enum (e.g. `coder` / `fixer` / `general`) and stay assignable.
+   */
+  kind: string
+  model: string
+  purpose: LlmPurpose
+  timestamp: number
+}
+
+/** A spectator record that has been persisted and has an identity. */
+export interface SpectatorEntryLogged extends SpectatorEntry {
+  id: string
+}
+
+/** One message (prompt or completion) inside a spectator entry. */
+export interface SpectatorEntryMessage {
+  type: string
+  callType: string
+  content: string
+  name?: string
+  contentType: SpectatorContentType
+  usage?: UsageMetadata
+  raw?: string
+}

package/src/types.ts

@@ -0,0 +1,123 @@
+import type { ExecutionEffort, ExecutionLevel } from './consts.js'
+
+/**
+ * Free-form observability metadata attached to every model call — forwarded to the
+ * inference provider as run metadata and recorded on every spectator entry. Kept
+ * intentionally small; a consumer extends it with its own domain fields.
+ */
+export interface LlmPurpose {
+  /** Coarse classification of the caller (e.g. `'coder'`, `'analyst'`). */
+  type?: string
+  /** Narrow, per-call refinement — set by `ExecutionService.forHelper`. */
+  dedication?: string
+}
+
+/**
+ * Serializable role name used to select a model. Deliberately an open `string`:
+ * a consumer declares its own role enum (whose values are strings) and it stays
+ * assignable here.
+ */
+export type ModelRole = string
+
+/**
+ * JSON-safe subset of the runtime `ModelConfig` (`@owlmeans/llm`). Mirrors only the
+ * serializable, tier-relevant fields — never `provider` / `secret` / `headers` /
+ * `fallback`. Lives here so an execution state can be persisted and replayed.
+ */
+export interface ModelConfigPatch {
+  preset?: string
+  model?: string
+  temperature?: number
+  maxTokens?: number
+  maxTokensCap?: number
+  topP?: number
+  disableThinking?: boolean
+}
+
+/** A JSON-safe model override: a config alias, or a partial config patch. */
+export type ModelConfigOverride = string | ModelConfigPatch
+
+/**
+ * A single, inheritable model-selection policy carried by every execution.
+ * Resolution precedence (see `ExecutionService.model`):
+ * roleOverride → modelOverride → effort tier → `LlmService.getModel`.
+ */
+export interface ModelPolicy {
+  /** Orthogonal capability tier. */
+  effort: ExecutionEffort
+  /** "Use role X wherever role Y is requested" — remap an entire sub-flow's roles. */
+  roleOverrides?: Partial<Record<ModelRole, ModelRole>>
+  /** "Pin a role to a specific model/config" — alias or partial config override. */
+  modelOverrides?: Partial<Record<ModelRole, ModelConfigOverride>>
+}
+
+/**
+ * Serializable execution state — no functions, no file access, no model instances.
+ * The runtime `Execution` (`@owlmeans/llm`) = this state + attached collaborators.
+ * A consumer extends this interface with its own domain fields; everything declared
+ * on the extension is carried into the snapshot automatically.
+ */
+export interface ExecutionState {
+  level: ExecutionLevel
+  purpose: LlmPurpose
+  policy: ModelPolicy
+}
+
+/** Resumable state of a task-level execution. */
+export interface TaskExecutionState extends ExecutionState {
+  /** Abstract workflow position for checkpoint/resume. */
+  phase?: string
+  completed?: string[]
+  cursor?: string
+  data?: Record<string, unknown>
+}
+
+/** Which model call produced a null/unusable result — carried by {@link NullCapture}. */
+export type NullKind = 'ask' | 'talk' | 'invoke' | 'request'
+
+/**
+ * Full diagnostic capture of a model call that returned nothing usable. Emitted by the
+ * model to the spectator's `captureNull` sink so a stalled/empty provider response can
+ * be replayed and diagnosed after the fact (finish reason, token accounting, whether a
+ * tool call was attempted, the exact request that produced it).
+ */
+export interface NullCapture {
+  meta: {
+    kind: NullKind
+    action: string
+    purpose?: LlmPurpose
+    attempt: number
+    id: string
+    timestamp: number
+    elapsedMs: number
+  }
+  model: {
+    id?: string
+    provider?: string
+    baseUrl?: string
+    maxTokens?: number
+    reasoning?: unknown
+    temperature?: number
+    topP?: number
+  }
+  request: {
+    messages: unknown[]
+    schema?: { toolName: string; innerSchema: unknown }
+    useCache: boolean
+  }
+  response: {
+    content: unknown
+    additional_kwargs?: unknown
+    response_metadata?: unknown
+    usage_metadata?: unknown
+    tool_calls?: unknown
+  } | null
+  diagnostics: {
+    finishReason?: string
+    inputTokens?: number
+    outputTokens?: number
+    reasoningTokens?: number
+    contentEmpty: boolean
+    hadToolCall: boolean
+  }
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": ["@owlmeans/dep-config/tsconfig.base.json"],
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./build/",
+    "moduleResolution": "Bundler"
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "./dist/**/*",
+    "./build/**/*"
+  ]
+}