@owlmeans/llm 0.1.14

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@owlmeans/llm",
+  "version": "0.1.14",
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "sleep 174 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
+  },
+  "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"
+    },
+    "./plugins": {
+      "import": "./build/plugins/export.js",
+      "require": "./build/plugins/export.js",
+      "default": "./build/plugins/export.js",
+      "module": "./build/plugins/export.js",
+      "types": "./build/plugins/export.d.ts"
+    },
+    "./helpers": {
+      "import": "./build/helpers/index.js",
+      "require": "./build/helpers/index.js",
+      "default": "./build/helpers/index.js",
+      "module": "./build/helpers/index.js",
+      "types": "./build/helpers/index.d.ts"
+    }
+  },
+  "devDependencies": {
+    "@langchain/anthropic": "^1.3.26",
+    "@langchain/core": "^1.1.39",
+    "@langchain/openai": "^1.4.4",
+    "@owlmeans/dep-config": "workspace:*",
+    "@owlmeans/test": "^0.1.14",
+    "@types/bun": "^1.3.14",
+    "@types/node": "^26.1.0",
+    "nodemon": "^3.1.14",
+    "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.78.0",
+    "@owlmeans/basic-ids": "^0.1.14",
+    "@owlmeans/context": "^0.1.14",
+    "@owlmeans/error": "^0.1.14",
+    "@owlmeans/llm-common": "^0.1.14",
+    "ajv": "^8.17.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@langchain/anthropic": "^1.3.26",
+    "@langchain/core": "^1.1.39",
+    "@langchain/openai": "^1.4.4"
+  }
+}

package/src/consts.ts

@@ -0,0 +1,89 @@
+import { ExecutionEffort } from '@owlmeans/llm-common'
+import type { ModelConfigPatch } 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: Record<ExecutionEffort, ModelConfigPatch> = {
+  [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: string[] = [
+  'state', 'models', 'model', 'temperatureFactory', 'outputErrors',
+]

package/src/errors.ts

@@ -0,0 +1,65 @@
+import { ResilientError } from '@owlmeans/error'
+
+export class LlmError extends ResilientError {
+  public static override typeName = `Llm${ResilientError.typeName}`
+
+  constructor(message: string = '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 {
+  public static override typeName = `Model${LlmError.typeName}`
+
+  public retry: number = 0
+
+  constructor(message: string = '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 {
+  public static override typeName = `Missconfigured${LlmError.typeName}`
+
+  constructor(message: string = 'error') {
+    super(`missconfigured:${message}`)
+    this.type = LlmMissconfiguredError.typeName
+  }
+}
+
+/** No provider plugin is registered for the requested type / model instance. */
+export class LlmPluginError extends LlmError {
+  public static readonly NO_PLUGIN = 'no-plugin'
+
+  public static override typeName = `Plugin${LlmError.typeName}`
+
+  constructor(message: string = '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 {
+  public static override typeName = `RetryExceeded${LlmError.typeName}`
+
+  public attempt: number = 0
+
+  constructor(message: string = 'error') {
+    super(`retry-exceeded:${message}`)
+    this.type = LlmRetryExceededError.typeName
+  }
+}
+
+ResilientError.registerErrorClass(LlmError)
+ResilientError.registerErrorClass(LlmModelError)
+ResilientError.registerErrorClass(LlmMissconfiguredError)
+ResilientError.registerErrorClass(LlmPluginError)
+ResilientError.registerErrorClass(LlmRetryExceededError)

package/src/execution/index.ts

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

package/src/execution/service.ts

@@ -0,0 +1,185 @@
+import { createService } from '@owlmeans/context'
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import { ExecutionLevel } from '@owlmeans/llm-common'
+import type { ExecutionState, ModelPolicy, TaskExecutionState } from '@owlmeans/llm-common'
+import { COLLABORATOR_KEYS, EXECUTION_SERVICE } from '../consts.js'
+import type { TemperatureFactory } from '../types.js'
+import type {
+  Execution, ExecutionPlugin, ExecutionService, ExecutionServiceOptions, ExecutionShape,
+  HelperExecution, TaskExecution, WithExecutionService,
+} from './types.js'
+import {
+  composeExecState, composeTaskState, effortPatch, freeze, mergeOverride, mergePolicy, resolveRole,
+} from './utils.js'
+
+/**
+ * Build the execution service implementation WITHOUT registering it as a context
+ * service, so a consumer can publish extra methods alongside it (observability
+ * factories, domain-specific refinement). Spread it into your own `createService`:
+ *
+ * ```ts
+ * const api = executionServiceApi<MyShape>({ collaboratorKeys: ['files'] }, () => service)
+ * const service = createService<MyExecutionService>(alias, {
+ *   ...api,
+ *   // delegate to `api`, never to `service`, or you recurse
+ *   forTask: (parent, input) => api.forTask(parent, { ...input, effort: effortOf(input.mode) }),
+ *   spectator: (exec, kind) => makeSpectator(exec, kind),
+ * } as MyExecutionService)
+ * ```
+ */
+export const executionServiceApi = <S extends ExecutionShape = ExecutionShape>(
+  options: ExecutionServiceOptions,
+  self: () => ExecutionService<S>,
+): ExecutionService<S> => {
+  const plugins: ExecutionPlugin[] = []
+  const collaboratorKeys = [...COLLABORATOR_KEYS, ...(options.collaboratorKeys ?? [])]
+
+  /** Recompose the JSON-safe state of a task execution after any refinement. */
+  const recompose = <E extends Execution>(exec: E): E => {
+    if (exec.level === ExecutionLevel.Task) {
+      const task = exec as unknown as TaskExecution
+      ;(task as { state: TaskExecutionState }).state = composeTaskState(task, collaboratorKeys)
+    }
+    return exec
+  }
+
+  const api: ExecutionService<S> = {
+
+    root: input => freeze({
+      ...input,
+      level: ExecutionLevel.Project,
+      purpose: { ...input.purpose },
+      policy: { ...input.policy },
+    }) as S['project'],
+
+    forTask: (parent, input) => {
+      const { effort, phase, data, ...extras } = input
+      const policy = effort != null
+        ? mergePolicy(parent.policy, { effort })
+        : { ...parent.policy }
+
+      // Spreading the parent carries every collaborator and domain field forward; the
+      // task's own state is composed afterwards, from the seeded resumable fields.
+      const taskExec = {
+        ...parent, ...extras, level: ExecutionLevel.Task, purpose: { ...parent.purpose }, policy,
+      } as unknown as TaskExecution
+      ;(taskExec as { state: TaskExecutionState }).state = composeTaskState({
+        ...taskExec,
+        state: {
+          level: ExecutionLevel.Task,
+          purpose: taskExec.purpose,
+          policy: taskExec.policy,
+          phase,
+          data,
+        } as TaskExecutionState,
+      }, collaboratorKeys)
+
+      return freeze(taskExec) as S['task']
+    },
+
+    forHelper: (parent, input) => {
+      const { role, effort, dedication, ...extras } = input
+      const localPolicy = effort != null ? mergePolicy(parent.policy, { effort }) : parent.policy
+      const scoped = { ...parent, policy: localPolicy } as S['exec']
+
+      const helperExec = {
+        ...parent,
+        ...extras,
+        level: ExecutionLevel.Helper,
+        purpose: dedication != null
+          ? { ...parent.purpose, dedication }
+          : { ...parent.purpose },
+        policy: localPolicy,
+        role: resolveRole(localPolicy, role),
+        model: self().model(scoped, role),
+        temperatureFactory: self().temperatureFactory(scoped, role),
+      } as unknown as HelperExecution
+      // A helper is not resumable — drop a parent task's composed state.
+      delete (helperExec as { state?: unknown }).state
+
+      return freeze(helperExec) as S['helper']
+    },
+
+    derive: (exec, patch) => freeze(recompose({ ...exec, ...patch })),
+
+    withPurpose: (exec, patch) =>
+      freeze(recompose({ ...exec, purpose: { ...exec.purpose, ...patch } })),
+
+    escalate: (exec, patch: Partial<ModelPolicy>) =>
+      freeze(recompose({ ...exec, policy: mergePolicy(exec.policy, patch) })),
+
+    model: (exec, role, override) => {
+      const effectiveRole = resolveRole(exec.policy, role ?? (exec as HelperExecution).role)
+      const policyOverride = exec.policy.modelOverrides?.[effectiveRole]
+      const merged = mergeOverride(effortPatch(exec.policy.effort), policyOverride, override)
+      // Strip undefined values so the factory does not see spurious keys.
+      const clean = Object.fromEntries(
+        Object.entries(merged).filter(([, value]) => value !== undefined)
+      ) as typeof merged
+
+      return exec.models().getModel(effectiveRole, clean)
+    },
+
+    temperatureFactory: (exec, role): TemperatureFactory =>
+      temperature =>
+        self().model(exec, role, {
+          ...(temperature != null ? { temperature } : {}),
+          ...(temperature != null && temperature > 0.2 ? { topP: 0.8 } : {}),
+        }),
+
+    use: plugin => {
+      plugins.push(plugin)
+    },
+
+    checkpoint: async (exec, key) => {
+      if (plugins.length === 0) {
+        return
+      }
+      const state = self().snapshot(exec)
+      await Promise.all(plugins.map(plugin => plugin.onCheckpoint?.(state, exec, key)))
+    },
+
+    snapshot: exec => {
+      if (exec.level === ExecutionLevel.Task) {
+        return freeze({ ...(exec as unknown as TaskExecution).state })
+      }
+      return freeze(composeExecState(exec, collaboratorKeys))
+    },
+
+    restore: (state: ExecutionState, collaborators = {} as S['collaborators']) => freeze({
+      ...state,
+      ...collaborators,
+      ...(state.level === ExecutionLevel.Task ? { state } : {}),
+    }) as S['exec'],
+
+  } as ExecutionService<S>
+
+  return api
+}
+
+export const makeExecutionService = <S extends ExecutionShape = ExecutionShape>(
+  alias: string = EXECUTION_SERVICE,
+  options: ExecutionServiceOptions = {},
+): ExecutionService<S> => {
+  const service: ExecutionService<S> = createService<ExecutionService<S>>(
+    alias, executionServiceApi<S>(options, () => service) as ExecutionService<S>
+  )
+
+  return service
+}
+
+export const appendExecutionService = <
+  C extends BasicConfig, T extends BasicContext<C>, S extends ExecutionShape = ExecutionShape
+>(
+  ctx: T,
+  alias: string = EXECUTION_SERVICE,
+  options: ExecutionServiceOptions = {},
+): T & WithExecutionService<S> => {
+  const context = ctx as T & WithExecutionService<S>
+
+  context.registerService(makeExecutionService<S>(alias, options))
+
+  context.executions = () => context.service<ExecutionService<S>>(alias)
+
+  return context
+}

package/src/execution/types.ts

@@ -0,0 +1,139 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models'
+import type { InitializedService } from '@owlmeans/context'
+import type {
+  ExecutionEffort, ExecutionLevel, ExecutionState, LlmPurpose, ModelConfigOverride,
+  ModelPolicy, ModelRole, TaskExecutionState,
+} from '@owlmeans/llm-common'
+import type { LlmService, TemperatureFactory } from '../types.js'
+
+/**
+ * Runtime execution = serializable {@link ExecutionState} + attached collaborators.
+ * A frozen data object with NO behavior of its own — all logic (construct, refine,
+ * resolve a model, snapshot, restore) lives on {@link ExecutionService}. Passing it to
+ * the next performer creates a NEW object; an execution is immutable between layers.
+ *
+ * Extend this interface (and {@link ExecutionState}) to carry domain context; every
+ * field that is not declared a collaborator travels into the snapshot automatically.
+ */
+export interface Execution extends ExecutionState {
+  /** Resolver for the model factory — a function so the service can be swapped/cloned. */
+  models: () => LlmService
+  outputErrors?: boolean
+  captureNull?: boolean
+}
+
+export interface ProjectExecution extends Execution {
+  level: ExecutionLevel.Project
+}
+
+export interface TaskExecution extends Execution {
+  level: ExecutionLevel.Task
+  /** The composed, JSON-safe state — recomposed on every refinement. */
+  state: TaskExecutionState
+}
+
+export interface HelperExecution extends Execution {
+  level: ExecutionLevel.Helper
+  role: ModelRole
+  /** A model already resolved against the policy (effort + overrides). */
+  model: BaseChatModel
+  temperatureFactory: TemperatureFactory
+}
+
+export interface ProjectExecutionInput {
+  models: () => LlmService
+  policy: ModelPolicy
+  purpose: LlmPurpose
+  outputErrors?: boolean
+  captureNull?: boolean
+}
+
+export interface TaskExecutionInput {
+  /** Raise (or lower) the effort tier for this task and everything derived from it. */
+  effort?: ExecutionEffort
+  /** Optional seeds for the resumable task state. */
+  phase?: string
+  data?: Record<string, unknown>
+}
+
+export interface HelperExecutionInput {
+  role: ModelRole
+  /** Local effort bump without escalating the whole branch. */
+  effort?: ExecutionEffort
+  /** Refines `purpose.dedication`. */
+  dedication?: string
+}
+
+/** Collaborators re-attached to a state that was restored from storage. */
+export interface RestoreCollaborators {
+  models?: () => LlmService
+}
+
+/**
+ * Resilience extension seam. A plugin observes flow boundaries (via
+ * {@link ExecutionService.checkpoint}) and can persist/enqueue the JSON-safe
+ * {@link ExecutionState}, or supply one back on resume. This package ships NO concrete
+ * implementation — with no plugin registered, `checkpoint` is a no-op.
+ */
+export interface ExecutionPlugin {
+  /** Fired at a flow boundary with a JSON-safe snapshot; persist/enqueue as desired. */
+  onCheckpoint?: (state: ExecutionState, exec: Execution, key?: string) => Promise<void>
+  /** Resume hook: return a previously persisted state for `key`, or `null`. */
+  onRestore?: (key: string) => Promise<ExecutionState | null>
+}
+
+/**
+ * The set of domain types an {@link ExecutionService} works with. A consumer declares
+ * its own shape (extending each member) and instantiates the service generic with it,
+ * which keeps the method signatures precise without redeclaring — and therefore without
+ * the contravariance problem that narrowing an inherited method signature would cause.
+ */
+export interface ExecutionShape {
+  exec: Execution
+  project: ProjectExecution
+  task: TaskExecution
+  helper: HelperExecution
+  projectInput: ProjectExecutionInput
+  taskInput: TaskExecutionInput
+  helperInput: HelperExecutionInput
+  purpose: LlmPurpose
+  collaborators: RestoreCollaborators
+}
+
+/**
+ * Standard OwlMeans context service. Every construction/refinement method returns a new,
+ * `Object.freeze`d object — executions are immutable between performers.
+ */
+export interface ExecutionService<S extends ExecutionShape = ExecutionShape> extends InitializedService {
+  // Construction / refinement (immutable; each returns a frozen object)
+  root: (input: S['projectInput']) => S['project']
+  forTask: (parent: S['project'], input: S['taskInput']) => S['task']
+  forHelper: (parent: S['exec'], input: S['helperInput']) => S['helper']
+  derive: <E extends S['exec']>(exec: E, patch: Partial<E>) => E
+  withPurpose: <E extends S['exec']>(exec: E, patch: Partial<S['purpose']>) => E
+  escalate: <E extends S['exec']>(exec: E, patch: Partial<ModelPolicy>) => E
+
+  // Model resolution (policy-aware)
+  model: (exec: S['exec'], role?: ModelRole, override?: ModelConfigOverride) => BaseChatModel
+  temperatureFactory: (exec: S['exec'], role?: ModelRole) => TemperatureFactory
+
+  // Resilience
+  /** Register a resilience plugin (checkpoint/resume). No-op seam until one is provided. */
+  use: (plugin: ExecutionPlugin) => void
+  /** Snapshot `exec` and dispatch it to every registered plugin. No-op if none. */
+  checkpoint: (exec: S['exec'], key?: string) => Promise<void>
+  snapshot: (exec: S['exec']) => ExecutionState
+  restore: (state: ExecutionState, collaborators?: S['collaborators']) => S['exec']
+}
+
+export interface ExecutionServiceOptions {
+  /**
+   * Execution fields that are collaborators, not state — excluded from every snapshot.
+   * Merged with the package's own {@link COLLABORATOR_KEYS}.
+   */
+  collaboratorKeys?: string[]
+}
+
+export interface WithExecutionService<S extends ExecutionShape = ExecutionShape> {
+  executions: () => ExecutionService<S>
+}

package/src/execution/utils.ts

@@ -0,0 +1,79 @@
+import { ExecutionLevel } from '@owlmeans/llm-common'
+import type {
+  ExecutionEffort, ExecutionState, ModelConfigOverride, ModelConfigPatch,
+  ModelPolicy, ModelRole, TaskExecutionState,
+} from '@owlmeans/llm-common'
+import { EFFORT_TABLE } from '../consts.js'
+import type { Execution, TaskExecution } from './types.js'
+
+export const freeze = <T extends object>(o: T): Readonly<T> => Object.freeze(o)
+
+/** Overlay a partial policy onto a base one. Override maps are merged, not replaced. */
+export const mergePolicy = (base: ModelPolicy, patch: Partial<ModelPolicy>): ModelPolicy => ({
+  effort: patch.effort ?? base.effort,
+  roleOverrides: patch.roleOverrides != null || base.roleOverrides != null
+    ? { ...base.roleOverrides, ...patch.roleOverrides }
+    : undefined,
+  modelOverrides: patch.modelOverrides != null || base.modelOverrides != null
+    ? { ...base.modelOverrides, ...patch.modelOverrides }
+    : undefined,
+})
+
+/** Apply the policy's role→role remap. */
+export const resolveRole = (policy: ModelPolicy, role: ModelRole): ModelRole =>
+  (policy.roleOverrides?.[role] as ModelRole | undefined) ?? role
+
+export const effortPatch = (effort: ExecutionEffort): ModelConfigPatch => EFFORT_TABLE[effort]
+
+/** Normalize a {@link ModelConfigOverride} (alias or patch) to a patch. */
+export const resolveModelConfig = (override: ModelConfigOverride): ModelConfigPatch =>
+  typeof override === 'string' ? { preset: override } : override
+
+/**
+ * Merge effort < policy.modelOverride < call-site override into a single patch.
+ * Any field present in a higher-precedence source wins.
+ */
+export const mergeOverride = (
+  effortBase: ModelConfigPatch,
+  policyOverride: ModelConfigOverride | undefined,
+  callOverride: ModelConfigOverride | undefined,
+): ModelConfigPatch => {
+  const policy = policyOverride != null ? resolveModelConfig(policyOverride) : {}
+  const call = callOverride != null ? resolveModelConfig(callOverride) : {}
+  return { ...effortBase, ...policy, ...call }
+}
+
+// --- Serialization ---
+
+/**
+ * Project an execution down to its JSON-safe state: every own field except the declared
+ * collaborators. Domain fields added by a consumer are carried through automatically,
+ * which is what lets an extended execution be persisted without extra wiring.
+ */
+export const composeExecState = (exec: Execution, collaboratorKeys: string[]): ExecutionState => {
+  const state: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(exec)) {
+    if (!collaboratorKeys.includes(key)) {
+      state[key] = value
+    }
+  }
+  return state as unknown as ExecutionState
+}
+
+/**
+ * Same as {@link composeExecState}, plus the resumable task fields carried over from the
+ * execution's PRIOR state (they live only there — `phase`/`cursor`/`completed`/`data` are
+ * advanced by the workflow, not by refinement).
+ */
+export const composeTaskState = (exec: TaskExecution, collaboratorKeys: string[]): TaskExecutionState => {
+  const base = composeExecState(exec, collaboratorKeys) as TaskExecutionState
+  const prior = exec.state ?? ({} as TaskExecutionState)
+  return {
+    ...base,
+    level: ExecutionLevel.Task,
+    phase: prior.phase,
+    completed: prior.completed,
+    cursor: prior.cursor,
+    data: prior.data,
+  }
+}

package/src/helpers/index.ts

@@ -0,0 +1,5 @@
+
+export * from './retry.js'
+export * from './json.js'
+export * from './messages.js'
+export * from './spectate.js'