@owlmeans/llm 0.1.18-rc.21 → 0.1.18-rc.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/llm",
-  "version": "0.1.18-rc.21",
+  "version": "0.1.18-rc.22",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -47,7 +47,7 @@
     "@langchain/core": "^1.2.9",
     "@langchain/openai": "^1.5.10",
     "@owlmeans/dep-config": "workspace:*",
-    "@owlmeans/test": "^0.1.18-rc.16",
+    "@owlmeans/test": "^0.1.18-rc.17",
     "@types/bun": "^1.4.0",
     "@types/node": "^26.1.0",
     "nodemon": "^3.1.14",
@@ -55,10 +55,10 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.78.0",
-    "@owlmeans/basic-ids": "^0.1.18-rc.17",
-    "@owlmeans/context": "^0.1.18-rc.16",
-    "@owlmeans/error": "^0.1.18-rc.16",
-    "@owlmeans/llm-common": "^0.1.18-rc.20",
+    "@owlmeans/basic-ids": "^0.1.18-rc.18",
+    "@owlmeans/context": "^0.1.18-rc.17",
+    "@owlmeans/error": "^0.1.18-rc.17",
+    "@owlmeans/llm-common": "^0.1.18-rc.21",
     "ajv": "^8.17.1"
   },
   "publishConfig": {

package/src/consts.ts

@@ -129,6 +129,10 @@ export const EFFORT_TABLE: Record<ExecutionEffort, ModelConfigPatch> = {
  *
  * `state` is in the list because a `TaskExecution` carries its own composed state —
  * without excluding it every `derive`/`escalate`/`withPurpose` would nest another copy.
+ *
+ * `inquiry` is deliberately ABSENT: how a run may put a question to a person is state, and a run
+ * resumed from a snapshot must ask through the same channel under the same policy. Listing it
+ * here would leave a resumed run silently unable to ask anything.
  */
 export const COLLABORATOR_KEYS: string[] = [
   'state', 'models', 'model', 'temperatureFactory', 'outputErrors', 'files', 'prompts',

package/src/execution/service.ts

@@ -1,8 +1,12 @@
 import { createService } from '@owlmeans/context'
 import type { BasicConfig, BasicContext } from '@owlmeans/context'
-import { ExecutionEffort, ExecutionLevel, UTILITY_ROLE } from '@owlmeans/llm-common'
+import {
+  capAnswer, defaultAnswerFor, ExecutionEffort, ExecutionLevel, InquiryPolicy, UTILITY_ROLE,
+} from '@owlmeans/llm-common'
 import type { ExecutionState, ModelPolicy, TaskExecutionState } from '@owlmeans/llm-common'
 import { COLLABORATOR_KEYS, EXECUTION_SERVICE } from '../consts.js'
+import { InquiryDeclined } from '../inquiry/errors.js'
+import { inquiryTransportFor } from '../inquiry/transport.js'
 import type { TemperatureFactory } from '../types.js'
 import type {
   Execution, ExecutionPlugin, ExecutionService, ExecutionServiceOptions, ExecutionShape,
@@ -52,6 +56,9 @@ export const executionServiceApi = <S extends ExecutionShape = ExecutionShape>(
       purpose: { ...input.purpose },
       policy: { ...input.policy },
       ...(input.prompt != null ? { prompt: { ...input.prompt } } : {}),
+      // Copied like every other piece of state, and NOT listed in `COLLABORATOR_KEYS`: a resumed
+      // run has to ask through the channel and policy it was started with.
+      ...(input.inquiry != null ? { inquiry: { ...input.inquiry } } : {}),
     }) as S['project'],
 
     forTask: (parent, input) => {
@@ -180,6 +187,15 @@ export const executionServiceApi = <S extends ExecutionShape = ExecutionShape>(
       return null
     },
 
+    ask: async (exec, inquiry, signal) => {
+      const policy = exec.inquiry?.policy ?? InquiryPolicy.Default
+      // No channel was ever configured, so there is nobody to wait for: assume and carry on.
+      if (policy === InquiryPolicy.Default) return defaultAnswerFor(inquiry)
+      if (policy === InquiryPolicy.Refuse) throw new InquiryDeclined(inquiry.id)
+
+      return capAnswer(await inquiryTransportFor(exec.inquiry?.transport).ask(inquiry, signal))
+    },
+
     snapshot: exec => {
       if (exec.level === ExecutionLevel.Task) {
         return freeze({ ...(exec as unknown as TaskExecution).state })

package/src/execution/types.ts

@@ -1,8 +1,9 @@
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models'
 import type { InitializedService } from '@owlmeans/context'
 import type {
-  ExecutionEffort, ExecutionLevel, ExecutionState, FileProviderRef, LlmPurpose,
-  ModelConfigOverride, ModelPolicy, ModelRole, PromptPolicy, TaskExecutionState,
+  ExecutionEffort, ExecutionLevel, ExecutionState, FileProviderRef, Inquiry, InquiryAnswer,
+  InquiryConfig, LlmPurpose, ModelConfigOverride, ModelPolicy, ModelRole, PromptPolicy,
+  TaskExecutionState,
 } from '@owlmeans/llm-common'
 import type { LlmService, TemperatureFactory } from '../types.js'
 import type { PromptService } from '../prompt/types.js'
@@ -53,6 +54,11 @@ export interface ProjectExecutionInput {
   purpose: LlmPurpose
   /** Baseline role and skills for the whole run. */
   prompt?: PromptPolicy
+  /**
+   * How this run may put a question to a person (see {@link ExecutionService.ask}). State, not a
+   * collaborator — it travels into every snapshot, so a resumed run asks the same way.
+   */
+  inquiry?: InquiryConfig
   outputErrors?: boolean
   captureNull?: boolean
 }
@@ -200,6 +206,20 @@ export interface ExecutionService<S extends ExecutionShape = ExecutionShape> ext
   snapshot: (exec: S['exec']) => ExecutionState
   restore: (state: ExecutionState, collaborators?: S['collaborators']) => S['exec']
 
+  /**
+   * Put a question to whoever is behind this execution, under its own policy.
+   *
+   * `ask` → the seated transport (and the answer comes back capped to
+   * `DEFAULT_INQUIRY_ANSWER_CHARS`); `default` → the question's own default, or a decline, which
+   * the caller is expected to RECORD as an assumption; `refuse` → `InquiryDeclined`. No config at
+   * all means `default`: a run that was never given a channel must never block on one.
+   *
+   * Throws `InquiryUnavailable` when the policy is `ask` and nothing is seated under the
+   * execution's transport key. Wire it through `executionInquiry` to read that as "nobody is
+   * there" instead.
+   */
+  ask: (exec: S['exec'], inquiry: Inquiry, signal?: AbortSignal) => Promise<InquiryAnswer>
+
   /**
    * Ask the registered plugins about the project this execution runs in. Plugins are
    * consulted in registration order and the FIRST usable answer wins, so one advisor owns

package/src/index.ts

@@ -6,6 +6,7 @@ export * from './model.js'
 export * from './service.js'
 export * from './helpers/index.js'
 export * from './execution/index.js'
+export * from './inquiry/index.js'
 export * from './prompt/index.js'
 export type * from './plugins/types.js'
 export { plugins, registerLlmPlugin, pluginOf, pluginFor, resolvePlugin } from './plugins/index.js'

package/src/inquiry/bridge.ts

@@ -0,0 +1,33 @@
+import type { Inquiry, InquiryAnswer } from '@owlmeans/llm-common'
+import { InquiryUnavailable } from './errors.js'
+
+/**
+ * The ONE adapter between an execution and whatever asks questions through it — a pipeline
+ * runner's `inquiry.ask`, an agent plugin's channel.
+ *
+ * It exists so "nobody is there" is decided in a single place: {@link InquiryUnavailable} becomes
+ * `null`, which every consumer reads as "carry on without an answer", and everything else — a
+ * decline included — escapes untouched. A consumer that mapped the two together would turn a
+ * person saying "I will not decide" into a run that parks forever, or the reverse.
+ *
+ * It asks for the one METHOD it calls rather than for an `ExecutionService<S>`, and infers the
+ * execution type from the execution it is handed. A shape generic would be unusable here: every
+ * member of `ExecutionService<S>` mentions `S` only through an indexed access (`S['exec']`,
+ * `S['projectInput']`, …), which is not an inference site, so `S` fell back to the bare
+ * `ExecutionShape` and then refused every real service contravariantly on `root`. The narrow
+ * parameter also lets anything that can answer a question stand in — a service, a facade, a
+ * test double — which is the whole point of an adapter.
+ */
+export const executionInquiry = <E>(
+  service: { ask: (exec: E, inquiry: Inquiry, signal?: AbortSignal) => Promise<InquiryAnswer> },
+  exec: E
+): ((inquiry: Inquiry, signal?: AbortSignal) => Promise<InquiryAnswer | null>) =>
+  async (inquiry, signal) => {
+    try {
+      return await service.ask(exec, inquiry, signal)
+    } catch (e) {
+      if (e instanceof InquiryUnavailable) return null
+
+      throw e
+    }
+  }

package/src/inquiry/errors.ts

@@ -0,0 +1,46 @@
+import { ResilientError } from '@owlmeans/error'
+
+export class InquiryError extends ResilientError {
+  public static override typeName = `Inquiry${ResilientError.typeName}`
+
+  constructor(message: string = 'error') {
+    super(InquiryError.typeName, `inquiry:${message}`)
+  }
+}
+
+/**
+ * No transport is seated under this key, or the one that was has gone.
+ *
+ * FATAL, and registered as such beside the throw. Nothing above it can improve by trying again:
+ * every retry ladder in the stack exists for a performer that answered badly, and there is nobody
+ * to ask. Left unrecognised, an absent channel costs an agent its whole turn budget on a tool it
+ * will never get an answer from.
+ */
+export class InquiryUnavailable extends InquiryError {
+  public static override typeName = `Unavailable${InquiryError.typeName}`
+
+  constructor(message: string = 'error') {
+    super(`unavailable:${message}`)
+    this.type = InquiryUnavailable.typeName
+  }
+}
+
+/**
+ * Nobody may be asked (policy `refuse`), or the answerer refused to decide.
+ *
+ * NOT retryable either, and deliberately a different class from {@link InquiryUnavailable}: a
+ * channel that answered "I will not decide this" is working. Whoever asked must decide itself and
+ * record the assumption, rather than treat the run as broken.
+ */
+export class InquiryDeclined extends InquiryError {
+  public static override typeName = `Declined${InquiryError.typeName}`
+
+  constructor(message: string = 'error') {
+    super(`declined:${message}`)
+    this.type = InquiryDeclined.typeName
+  }
+}
+
+ResilientError.registerErrorClass(InquiryError)
+ResilientError.registerErrorClass(InquiryUnavailable)
+ResilientError.registerErrorClass(InquiryDeclined)

package/src/inquiry/index.ts

@@ -0,0 +1,3 @@
+export * from './errors.js'
+export * from './transport.js'
+export * from './bridge.js'

package/src/inquiry/transport.ts

@@ -0,0 +1,42 @@
+import type { InquiryTransport } from '@owlmeans/llm-common'
+import { registerFatalError } from '../helpers/retry.js'
+import { InquiryUnavailable } from './errors.js'
+
+/**
+ * Which channel reaches which person.
+ *
+ * Module-level and keyed by string, exactly like the delegate-transport registry beside it: a
+ * process holds many at once — one per connected agent, one per open browser session — and an
+ * execution names the one its run belongs to. Seating is what an application does when a channel
+ * attaches; releasing is what it does when one goes away, and a question that arrives afterwards
+ * fails immediately rather than hanging on nobody.
+ */
+const transports: Record<string, InquiryTransport> = {}
+
+export const registerInquiryTransport = (key: string, transport: InquiryTransport): void => {
+  transports[key] = transport
+}
+
+export const releaseInquiryTransport = (key: string): void => {
+  delete transports[key]
+}
+
+export const hasInquiryTransport = (key: string): boolean => transports[key] != null
+
+/**
+ * The transport for a key, or a fatal refusal — never a wait.
+ *
+ * Named `inquiryTransportFor` rather than `transportFor`: `@owlmeans/llm` and
+ * `@owlmeans/llm-delegate` are re-exported into one namespace by `@owlmeans/viable`.
+ */
+export const inquiryTransportFor = (key: string | undefined): InquiryTransport => {
+  if (key == null || transports[key] == null) {
+    throw new InquiryUnavailable(key ?? 'unkeyed')
+  }
+
+  return transports[key]
+}
+
+// Beside the throw, so no caller has to remember: an absent channel aborts every retry loop at
+// once instead of being spent through as if the answer might come next time.
+registerFatalError(e => e instanceof InquiryUnavailable ? e : null)

package/src/model.ts

@@ -184,6 +184,24 @@ export const makeLlmModel = ({
     }
   }
 
+  /**
+   * Give a spectator one best-effort terminal-error observation without allowing that
+   * observation to replace the work's real failure. Keeping this outside `withRetry` means
+   * transient attempts stay private to the retry ladder.
+   */
+  const observeFailure = async <T>(action: string, work: () => Promise<T>): Promise<T> => {
+    try {
+      return await work()
+    } catch (error) {
+      try {
+        await spectator.error?.({ action, error })
+      } catch (observerError) {
+        console.warn('[MODEL-ERROR] spectator observation failed', observerError)
+      }
+      throw error
+    }
+  }
+
   /**
    * Record the diagnostics of a call that produced nothing usable and build the
    * retryable error describing it. The caller throws it, so control flow stays visible.
@@ -316,9 +334,10 @@ export const makeLlmModel = ({
         escalation, fatal,
       }: LlmAskOptions
     ) => {
-      const msgs = await prepare(input, action, useCache, cacheMax, false, skills)
-      const seed = ladderSeed(escalation)
-      return withRetry({ retries, outputErrors, fatal }, async i => {
+      return await observeFailure(action, async () => {
+        const msgs = await prepare(input, action, useCache, cacheMax, false, skills)
+        const seed = ladderSeed(escalation)
+        return await withRetry({ retries, outputErrors, fatal }, async i => {
         const refined = refineModel(seed + i)
         console.log('Use model to ask: ', refined.getName(), refined.lc_kwargs.model)
         const startedAt = Date.now()
@@ -378,6 +397,7 @@ export const makeLlmModel = ({
 
         notifyRef(ref, message)
         return output
+        })
       })
     },
 
@@ -388,9 +408,10 @@ export const makeLlmModel = ({
         escalation, fatal,
       }: LlmTalkOptions
     ) => {
-      const msgs = await prepare(input, action, useCache, cacheMax, false, skills)
-      const seed = ladderSeed(escalation)
-      return withRetry({ retries, outputErrors, fatal }, async i => {
+      return await observeFailure(action, async () => {
+        const msgs = await prepare(input, action, useCache, cacheMax, false, skills)
+        const seed = ladderSeed(escalation)
+        return await withRetry({ retries, outputErrors, fatal }, async i => {
         const refined = refineModel(seed + i)
         console.log('Use model to talk: ', refined.getName(), refined.lc_kwargs.model)
         const startedAt = Date.now()
@@ -417,6 +438,7 @@ export const makeLlmModel = ({
 
         notifyRef(ref, message)
         return message
+        })
       })
     },
 
@@ -428,12 +450,13 @@ export const makeLlmModel = ({
         skills, escalation, fatal,
       }: LlmInvokeOptions<T>
     ) => {
-      const msgs = await prepare(input, action, useCache, cacheMax, true, skills)
-      const { name, innerSchema, validate } = resolveSchemaValidator<T>(ajv, schema)
-      const toolName = toToolName((innerSchema as { title?: string }).title ?? name)
+      return await observeFailure(action, async () => {
+        const msgs = await prepare(input, action, useCache, cacheMax, true, skills)
+        const { name, innerSchema, validate } = resolveSchemaValidator<T>(ajv, schema)
+        const toolName = toToolName((innerSchema as { title?: string }).title ?? name)
 
-      const seed = ladderSeed(escalation)
-      return withRetry({ retries, outputErrors, fatal }, async i => {
+        const seed = ladderSeed(escalation)
+        return await withRetry({ retries, outputErrors, fatal }, async i => {
         const refined = refineModel(seed + i, temperature)
         console.log('Use model invoke: ', refined.getName(), refined.lc_kwargs.model)
         const startedAt = Date.now()
@@ -469,6 +492,7 @@ export const makeLlmModel = ({
 
         notifyRef(ref, message)
         return result as T
+        })
       })
     },
 
@@ -480,12 +504,13 @@ export const makeLlmModel = ({
         escalation, fatal,
       }: LlmRequestOptions
     ) => {
-      const msgs = await prepare(input, action, useCache, cacheMax, true, skills)
-      const { name, innerSchema, validate } = resolveSchemaValidator<T>(ajv, schema)
-      const toolName = toToolName((innerSchema as { title?: string }).title ?? name)
+      return await observeFailure(action, async () => {
+        const msgs = await prepare(input, action, useCache, cacheMax, true, skills)
+        const { name, innerSchema, validate } = resolveSchemaValidator<T>(ajv, schema)
+        const toolName = toToolName((innerSchema as { title?: string }).title ?? name)
 
-      const seed = ladderSeed(escalation)
-      return withRetry({ retries, outputErrors, fatal }, async i => {
+        const seed = ladderSeed(escalation)
+        return await withRetry({ retries, outputErrors, fatal }, async i => {
         const refined = refineModel(seed + i)
         console.log('Use model request: ', refined.getName(), refined.lc_kwargs.model)
         const startedAt = Date.now()
@@ -525,6 +550,7 @@ export const makeLlmModel = ({
 
         notifyRef(ref, message)
         return message
+        })
       })
     },
   }

package/src/types.ts

@@ -163,6 +163,19 @@ export interface LlmSpectator {
   log: (arg: SpectatorArgument) => Promise<SpectatorEntryLogged>
   /** Optional sink for full diagnostics of a call that returned nothing usable. */
   captureNull?: (capture: NullCapture) => Promise<void>
+  /**
+   * Optional observer for a call that failed permanently after its retry policy finished.
+   *
+   * Observers are diagnostics only: the model preserves the original failure even when one
+   * cannot receive it. This is deliberately terminal rather than per-attempt so consumers do
+   * not turn one exhausted budget into a notification storm.
+   */
+  error?: (event: LlmSpectatorError) => Promise<void>
+}
+
+export interface LlmSpectatorError {
+  action: string
+  error: unknown
 }
 
 /** Resolves a model of the same role at a different temperature. */

package/tests/inquiry.spec.ts

@@ -0,0 +1,200 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { DEFAULT_INQUIRY_ANSWER_CHARS, InquiryKind, InquiryPolicy } from '@owlmeans/llm-common'
+import type { Inquiry, InquiryAnswer } from '@owlmeans/llm-common'
+import {
+  DEFAULT_EFFORT, executionInquiry, hasInquiryTransport, inquiryTransportFor, InquiryDeclined,
+  InquiryUnavailable, isFatalError, makeExecutionService, makeLlmService,
+  registerInquiryTransport, releaseInquiryTransport,
+} from '@owlmeans/llm'
+import type {
+  Execution, ExecutionService, ExecutionShape, ProjectExecution, ProjectExecutionInput,
+} from '@owlmeans/llm'
+import { offlineConfigs } from './context.js'
+
+/**
+ * The runtime half of the inquiry primitive: who answers, under which policy, and what a caller
+ * above it is allowed to conclude from a failure. The distinction the specs are here to hold is
+ * that "nobody is there" and "the person declined" are different outcomes — one is a channel
+ * fault no retry can fix, the other is a decision the run carries on from.
+ */
+
+const KEY = 'spec-inquiry'
+
+/**
+ * A consumer's OWN shape, every member narrowed — the way `@owlmeans/viable` declares
+ * `ViableExecutionShape` and instantiates the service with it.
+ *
+ * The bridge must take a service built from one without a type argument. Being generic over the
+ * SHAPE cannot do that: `S` appears in `ExecutionService<S>` only through indexed accesses
+ * (`S['exec']`, `S['projectInput']`, …), which is not an inference site, so it fell back to the
+ * bare `ExecutionShape` and then refused every real service contravariantly on `root`. Nothing
+ * written against the DEFAULT shape can see that, which is why this spec declares its own.
+ */
+interface SpecExecution extends Execution {
+  origin: string
+}
+
+interface SpecProjectExecution extends ProjectExecution {
+  origin: string
+}
+
+interface SpecProjectInput extends ProjectExecutionInput {
+  origin: string
+}
+
+interface SpecShape extends ExecutionShape {
+  exec: SpecExecution
+  project: SpecProjectExecution
+  projectInput: SpecProjectInput
+}
+
+const inquiry = (patch: Partial<Inquiry> = {}): Inquiry => ({
+  id: 'q1',
+  kind: InquiryKind.Choice,
+  question: 'Which database does the origin use?',
+  options: [
+    { value: 'postgres', label: 'PostgreSQL' },
+    { value: 'mongo', label: 'MongoDB' },
+  ],
+  ...patch,
+})
+
+let service: ExecutionService
+let asked: Inquiry[]
+
+/** A channel that records what it was asked and answers what the spec told it to. */
+const seat = (answer: (asked: Inquiry) => InquiryAnswer | Promise<InquiryAnswer>): void => {
+  registerInquiryTransport(KEY, {
+    ask: async question => {
+      asked.push(question)
+
+      return await answer(question)
+    },
+  })
+}
+
+const root = (transport?: string, policy?: InquiryPolicy): ProjectExecution => service.root({
+  models: () => makeLlmService({ models: offlineConfigs }, `spec-inquiry-llm-${asked.length}`),
+  policy: { effort: DEFAULT_EFFORT },
+  purpose: { type: 'spec' },
+  ...(policy != null ? { inquiry: { transport, policy } } : {}),
+})
+
+beforeEach(() => {
+  asked = []
+  service = makeExecutionService(`spec-inquiry-${Math.trunc(performance.now() * 1000)}`)
+})
+
+afterEach(() => releaseInquiryTransport(KEY))
+
+describe('@owlmeans/llm — the inquiry transport registry', () => {
+  test('a channel is seated under a key and released again', () => {
+    expect(hasInquiryTransport(KEY)).toBe(false)
+    seat(() => ({ inquiryId: 'q1', value: 'mongo' }))
+    expect(hasInquiryTransport(KEY)).toBe(true)
+    expect(inquiryTransportFor(KEY)).toBeDefined()
+    releaseInquiryTransport(KEY)
+    expect(hasInquiryTransport(KEY)).toBe(false)
+  })
+
+  test('an unseated key refuses at once rather than waiting for one to arrive', () => {
+    expect(() => inquiryTransportFor(KEY)).toThrow(InquiryUnavailable)
+    expect(() => inquiryTransportFor(undefined)).toThrow(InquiryUnavailable)
+  })
+
+  test('an absent channel is fatal, so no retry ladder spends itself on it', () => {
+    expect(isFatalError(new InquiryUnavailable('x'))).not.toBeNull()
+    // A decline is an answer, not a fault: nothing above may abort a run over one.
+    expect(isFatalError(new InquiryDeclined('q1'))).toBeNull()
+  })
+})
+
+describe('@owlmeans/llm — ExecutionService.ask policy matrix', () => {
+  test('`ask` reaches the seated channel and caps what comes back', async () => {
+    seat(() => ({ inquiryId: 'q1', value: 'mongo', text: 'x'.repeat(10) }))
+    const answer = await service.ask(root(KEY, InquiryPolicy.Ask), inquiry())
+    expect(answer.value).toBe('mongo')
+    expect(answer.truncated).toBeUndefined()
+    expect(asked).toHaveLength(1)
+  })
+
+  test('an answer over the ceiling is cut here, and the cut is reported', async () => {
+    // The cap belongs to the service, not to the channel: nothing seated by an application is
+    // obliged to know the ceiling, and an answer that reached a pipeline state uncut is prose in
+    // a state made of keys.
+    seat(() => ({ inquiryId: 'q1', text: 'x'.repeat(DEFAULT_INQUIRY_ANSWER_CHARS + 5) }))
+    const answer = await service.ask(root(KEY, InquiryPolicy.Ask), inquiry({ kind: InquiryKind.Text }))
+    expect(answer.text).toHaveLength(DEFAULT_INQUIRY_ANSWER_CHARS)
+    expect(answer.truncated).toBe(true)
+  })
+
+  test('`ask` with nothing seated is an unavailable channel, never a decline', async () => {
+    await expect(service.ask(root(KEY, InquiryPolicy.Ask), inquiry()))
+      .rejects.toThrow(InquiryUnavailable)
+  })
+
+  test('`default` assumes the default the question carries, or declines — and asks nobody', async () => {
+    const exec = root(KEY, InquiryPolicy.Default)
+    seat(() => ({ inquiryId: 'q1', value: 'mongo' }))
+    expect(await service.ask(exec, inquiry({ default: 'postgres' })))
+      .toEqual({ inquiryId: 'q1', value: 'postgres' })
+    expect(await service.ask(exec, inquiry())).toEqual({ inquiryId: 'q1', declined: true })
+    expect(asked).toHaveLength(0)
+  })
+
+  test('`refuse` declines every question outright', async () => {
+    seat(() => ({ inquiryId: 'q1', value: 'mongo' }))
+    await expect(service.ask(root(KEY, InquiryPolicy.Refuse), inquiry({ default: 'postgres' })))
+      .rejects.toThrow(InquiryDeclined)
+    expect(asked).toHaveLength(0)
+  })
+
+  test('no configuration at all behaves as `default` — a run given no channel never blocks', async () => {
+    seat(() => ({ inquiryId: 'q1', value: 'mongo' }))
+    expect(await service.ask(root(), inquiry({ default: 'postgres' })))
+      .toEqual({ inquiryId: 'q1', value: 'postgres' })
+    expect(asked).toHaveLength(0)
+  })
+})
+
+describe('@owlmeans/llm — the executionInquiry bridge', () => {
+  test('an unavailable channel reads as "nobody is there"', async () => {
+    const ask = executionInquiry(service, root(KEY, InquiryPolicy.Ask))
+    expect(await ask(inquiry())).toBeNull()
+  })
+
+  test('a decline escapes — a person who would not decide is not an absent person', async () => {
+    const ask = executionInquiry(service, root(KEY, InquiryPolicy.Refuse))
+    await expect(ask(inquiry())).rejects.toThrow(InquiryDeclined)
+  })
+
+  test('an answered question comes back whole', async () => {
+    seat(() => ({ inquiryId: 'q1', value: 'postgres' }))
+    const ask = executionInquiry(service, root(KEY, InquiryPolicy.Ask))
+    expect(await ask(inquiry())).toEqual({ inquiryId: 'q1', value: 'postgres' })
+  })
+
+  test('a consumer\'s own execution shape wires through unannotated', async () => {
+    seat(() => ({ inquiryId: 'q1', value: 'postgres' }))
+    const scoped = makeExecutionService<SpecShape>(`spec-inquiry-shape-${asked.length}`)
+    const exec = scoped.root({
+      models: () => makeLlmService({ models: offlineConfigs }, 'spec-inquiry-shape-llm'),
+      policy: { effort: DEFAULT_EFFORT },
+      purpose: { type: 'spec' },
+      origin: 'legacy-app',
+      inquiry: { transport: KEY, policy: InquiryPolicy.Ask },
+    })
+
+    expect(exec.origin).toBe('legacy-app')
+    expect(await executionInquiry(scoped, exec)(inquiry()))
+      .toEqual({ inquiryId: 'q1', value: 'postgres' })
+  })
+})
+
+describe('@owlmeans/llm — the channel survives a snapshot', () => {
+  test('a resumed execution asks through the same channel under the same policy', () => {
+    const state = service.snapshot(root(KEY, InquiryPolicy.Ask))
+    expect(state.inquiry).toEqual({ transport: KEY, policy: InquiryPolicy.Ask })
+    expect(service.restore(state).inquiry).toEqual({ transport: KEY, policy: InquiryPolicy.Ask })
+  })
+})