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

package/build/inquiry/utils.d.ts

@@ -0,0 +1,45 @@
+import type { Inquiry, InquiryAnswer } from './types.js';
+/**
+ * Pure helpers over an inquiry and its answer — no IO, no state, no clock.
+ *
+ * They are here rather than in the runtime because every layer needs the same reading of an
+ * answer: the execution service, the pipeline runner, the `ask_user` tool, the connector and the
+ * screen that finally shows it. A second reading of "was this answered" is a second contract.
+ */
+/**
+ * What to assume when nobody answers: the question's own default, or a decline.
+ *
+ * A decline is an ANSWER — the run carries on and records what it assumed — which is why this
+ * never throws and never returns null.
+ */
+export declare const defaultAnswerFor: (inquiry: Inquiry) => InquiryAnswer;
+/**
+ * The one thing an answer says, as a string — the first chosen value, else the free text, else
+ * `null` when it says nothing at all (a decline, or an empty answer).
+ */
+export declare const answeredWith: (answer: InquiryAnswer) => string | null;
+/** Nobody could decide. Distinct from an empty answer — see {@link answeredWith}. */
+export declare const isDeclined: (answer: InquiryAnswer) => boolean;
+/**
+ * Cut an answer's free TEXT to the ceiling and SAY SO.
+ *
+ * Only the prose is cut. A `value` IS the decision — for a choice it has to equal one of the
+ * question's own option values — so slicing one does not degrade an answer, it silently replaces
+ * it with an identifier nobody offered and nothing matches, which `answeredWith` then hands on as
+ * what the person chose. An over-long value is a defect upstream rather than a long answer (the
+ * connector's schema refuses one outright instead of shortening it), so it travels on whole and is
+ * REPORTED through `truncated` — the flag every consumer already reads as "this is not exactly
+ * what the person gave".
+ */
+export declare const capAnswer: (answer: InquiryAnswer, max?: number) => InquiryAnswer;
+/**
+ * The copy of an answer a resumable pipeline STATE keeps: the decision whole, the prose cut to
+ * {@link INQUIRY_STATE_TEXT_CHARS}.
+ *
+ * The full answer goes back to whoever asked; only this reduced one is persisted, so a run that
+ * asks several questions still holds a state made of keys rather than of paragraphs.
+ */
+export declare const stateAnswerOf: (answer: InquiryAnswer) => InquiryAnswer;
+/** One-line label of a question — for a note, a trace line or a run row. */
+export declare const renderInquiry: (inquiry: Inquiry) => string;
+//# sourceMappingURL=utils.d.ts.map

package/build/inquiry/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/inquiry/utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAExD;;;;;;GAMG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,YAAa,OAAO,KAAG,aAGL,CAAA;AAE/C;;;GAGG;AACH,eAAO,MAAM,YAAY,WAAY,aAAa,KAAG,MAAM,GAAG,IAM7D,CAAA;AAED,qFAAqF;AACrF,eAAO,MAAM,UAAU,WAAY,aAAa,KAAG,OAAmC,CAAA;AAEtF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,WACZ,aAAa,QAAO,MAAM,KACjC,aAYF,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,WAAY,aAAa,KAAG,aAG1C,CAAA;AAEZ,4EAA4E;AAC5E,eAAO,MAAM,aAAa,YAAa,OAAO,KAAG,MAMhD,CAAA"}

package/build/inquiry/utils.js

@@ -0,0 +1,72 @@
+import { DEFAULT_INQUIRY_ANSWER_CHARS, INQUIRY_STATE_TEXT_CHARS } from './consts.js';
+/**
+ * Pure helpers over an inquiry and its answer — no IO, no state, no clock.
+ *
+ * They are here rather than in the runtime because every layer needs the same reading of an
+ * answer: the execution service, the pipeline runner, the `ask_user` tool, the connector and the
+ * screen that finally shows it. A second reading of "was this answered" is a second contract.
+ */
+/**
+ * What to assume when nobody answers: the question's own default, or a decline.
+ *
+ * A decline is an ANSWER — the run carries on and records what it assumed — which is why this
+ * never throws and never returns null.
+ */
+export const defaultAnswerFor = (inquiry) => inquiry.default != null
+    ? { inquiryId: inquiry.id, value: inquiry.default }
+    : { inquiryId: inquiry.id, declined: true };
+/**
+ * The one thing an answer says, as a string — the first chosen value, else the free text, else
+ * `null` when it says nothing at all (a decline, or an empty answer).
+ */
+export const answeredWith = (answer) => {
+    const value = Array.isArray(answer.value) ? answer.value[0] : answer.value;
+    if (value != null && value !== '')
+        return value;
+    if (answer.text != null && answer.text !== '')
+        return answer.text;
+    return null;
+};
+/** Nobody could decide. Distinct from an empty answer — see {@link answeredWith}. */
+export const isDeclined = (answer) => answer.declined === true;
+/**
+ * Cut an answer's free TEXT to the ceiling and SAY SO.
+ *
+ * Only the prose is cut. A `value` IS the decision — for a choice it has to equal one of the
+ * question's own option values — so slicing one does not degrade an answer, it silently replaces
+ * it with an identifier nobody offered and nothing matches, which `answeredWith` then hands on as
+ * what the person chose. An over-long value is a defect upstream rather than a long answer (the
+ * connector's schema refuses one outright instead of shortening it), so it travels on whole and is
+ * REPORTED through `truncated` — the flag every consumer already reads as "this is not exactly
+ * what the person gave".
+ */
+export const capAnswer = (answer, max = DEFAULT_INQUIRY_ANSWER_CHARS) => {
+    const text = answer.text != null && answer.text.length > max
+        ? answer.text.slice(0, max)
+        : undefined;
+    const values = Array.isArray(answer.value)
+        ? answer.value
+        : answer.value != null ? [answer.value] : [];
+    const oversized = values.some(value => value.length > max);
+    if (text == null && !oversized)
+        return answer;
+    return { ...answer, ...(text != null ? { text } : {}), truncated: true };
+};
+/**
+ * The copy of an answer a resumable pipeline STATE keeps: the decision whole, the prose cut to
+ * {@link INQUIRY_STATE_TEXT_CHARS}.
+ *
+ * The full answer goes back to whoever asked; only this reduced one is persisted, so a run that
+ * asks several questions still holds a state made of keys rather than of paragraphs.
+ */
+export const stateAnswerOf = (answer) => answer.text != null && answer.text.length > INQUIRY_STATE_TEXT_CHARS
+    ? { ...answer, text: answer.text.slice(0, INQUIRY_STATE_TEXT_CHARS), truncated: true }
+    : answer;
+/** One-line label of a question — for a note, a trace line or a run row. */
+export const renderInquiry = (inquiry) => {
+    const options = inquiry.options != null && inquiry.options.length > 0
+        ? ` (${inquiry.options.map(option => option.value).join(' | ')})`
+        : '';
+    return `[${inquiry.kind}] ${inquiry.question}${options}`.replace(/\s+/g, ' ').trim();
+};
+//# sourceMappingURL=utils.js.map

package/build/inquiry/utils.js.map

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

package/build/types.d.ts

@@ -1,4 +1,5 @@
 import type { ExecutionEffort, ExecutionLevel, PromptBlock } from './consts.js';
+import type { InquiryConfig } from './inquiry/types.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
@@ -29,6 +30,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 +51,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
@@ -119,10 +132,23 @@ export interface ExecutionState {
     policy: ModelPolicy;
     /** Role + skills for this level; merged downward by `ExecutionService`. */
     prompt?: PromptPolicy;
+    /**
+     * How this run may put a question to a person. Serializable, and deliberately NOT a
+     * collaborator: a run that is resumed days later must ask through the same channel, under the
+     * same policy, as the one that parked it.
+     */
+    inquiry?: InquiryConfig;
 }
-/** 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 +197,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.21",
   "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,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'
+export * from './inquiry/index.js'

package/src/inquiry/consts.ts

@@ -0,0 +1,52 @@
+/**
+ * What shape of answer a question expects. Deliberately three, because a question a person is
+ * asked mid-run is answered in seconds or not at all: pick one of these, say it in your own
+ * words, or say yes/no. Anything richer is a form, and a form belongs to an application screen.
+ */
+export enum InquiryKind {
+  Choice = 'choice',
+  Text = 'text',
+  Confirm = 'confirm',
+}
+
+/**
+ * What a run is allowed to do when it needs a decision that is not its own.
+ *
+ * - `Ask` — put it to a person through the seated transport and wait.
+ * - `Default` — assume the question's own default (or record a decline) and carry on. The caller
+ *   is expected to RECORD the assumption; a run nobody is watching must never block.
+ * - `Refuse` — nobody may be asked at all; the attempt is an error.
+ */
+export enum InquiryPolicy {
+  Ask = 'ask',
+  Default = 'default',
+  Refuse = 'refuse',
+}
+
+/**
+ * The ONE ceiling on a stored answer, in characters. An answer is a decision, not a document.
+ *
+ * Every layer that carries an answer references this constant rather than choosing its own:
+ * `viable-common`'s `CONNECT_INQUIRY_MAX_TEXT` (the wire copy) equals it, `capAnswer` enforces it,
+ * and the connector's answer schema caps `text` at it. Three ceilings for one value is how a
+ * user's answer gets accepted on the wire and silently halved further in.
+ */
+export const DEFAULT_INQUIRY_ANSWER_CHARS = 2_000
+
+/** How many options one question may offer. Beyond this it is not a question. */
+export const DEFAULT_INQUIRY_OPTIONS = 12
+
+/**
+ * How much of an answer's free text a resumable pipeline STATE may hold.
+ *
+ * A pipeline state is keys, markers and paths — a couple of full-size answers would make it prose,
+ * which is the invariant the whole pipeline design rests on. The decision (`value`/`declined`)
+ * stays whole; the prose is cut here and belongs in whatever document the application keeps for
+ * it (`stateAnswerOf`).
+ */
+export const INQUIRY_STATE_TEXT_CHARS = 200
+
+/** The answer value of a confirmed {@link InquiryKind.Confirm}. */
+export const CONFIRM_YES = 'yes'
+/** The answer value of a refused {@link InquiryKind.Confirm}. */
+export const CONFIRM_NO = 'no'

package/src/inquiry/index.ts

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

package/src/inquiry/types.ts

@@ -0,0 +1,77 @@
+import type { InquiryKind, InquiryPolicy } from './consts.js'
+
+/**
+ * One question put to a person while a run is in flight, and the answer that comes back.
+ *
+ * Everything here is serializable for the same reason a delegated task is: whoever answers is
+ * outside this process — a browser dialog, a coding agent driving the application through a
+ * connector, a test double — and the question may outlive the process that asked it, parked on a
+ * pipeline run row until somebody comes back to it.
+ */
+
+export interface InquiryOption {
+  value: string
+  label: string
+  description?: string
+}
+
+export interface Inquiry {
+  /** Stable id, chosen by whoever asks. The ONLY thing that routes an answer back. */
+  id: string
+  kind: InquiryKind
+  /** One question, in plain words. */
+  question: string
+  /** One or two sentences of background. Never the whole task. */
+  context?: string
+  /** Required for {@link InquiryKind.Choice}; ignored otherwise. */
+  options?: InquiryOption[]
+  multiple?: boolean
+  /** A `Choice` the answerer may answer in their own words instead. */
+  allowText?: boolean
+  /** What to assume when nobody answers. {@link InquiryPolicy.Default} returns exactly this. */
+  default?: string | string[]
+  expiresAt?: string
+}
+
+export interface InquiryAnswer {
+  inquiryId: string
+  value?: string | string[]
+  text?: string
+  /** Nobody could decide. A legitimate ANSWER, never a failure. */
+  declined?: boolean
+  /**
+   * This answer is not exactly the one that was given. Never an answerer's own flag.
+   *
+   * Two writers, two ceilings: `capAnswer` cuts the text to `DEFAULT_INQUIRY_ANSWER_CHARS` (and
+   * raises this WITHOUT cutting when a `value` arrived over that ceiling, since a shortened
+   * identifier matches no option), while `stateAnswerOf` cuts the text again to the much smaller
+   * `INQUIRY_STATE_TEXT_CHARS` a pipeline state may hold. So a flag read back off a resumed run
+   * says the state's copy is short — not that the person hit the answer ceiling.
+   *
+   * It exists so no cut is silent: whoever records the answer can say that the rest of it was
+   * dropped, instead of the answerer discovering it in the work that followed.
+   */
+  truncated?: boolean
+}
+
+/**
+ * How a question reaches a person.
+ *
+ * One method, like `DelegateTransport` beside it, and for the same reason: routing, waiting,
+ * redelivery and giving up all belong to whoever implements it. A transport that cannot serve the
+ * question must THROW rather than answer — a declined answer is a decision, while a channel that
+ * is not there is terminal, and the two must never look alike.
+ */
+export interface InquiryTransport {
+  ask: (inquiry: Inquiry, signal?: AbortSignal) => Promise<InquiryAnswer>
+}
+
+/**
+ * How one run may put a question to a person. Carried on an execution's serializable state, so a
+ * resumed run keeps the channel and the policy it was started with.
+ */
+export interface InquiryConfig {
+  /** The key the application seated an {@link InquiryTransport} under. */
+  transport?: string
+  policy: InquiryPolicy
+}

package/src/inquiry/utils.ts

@@ -0,0 +1,84 @@
+import { DEFAULT_INQUIRY_ANSWER_CHARS, INQUIRY_STATE_TEXT_CHARS } from './consts.js'
+import type { Inquiry, InquiryAnswer } from './types.js'
+
+/**
+ * Pure helpers over an inquiry and its answer — no IO, no state, no clock.
+ *
+ * They are here rather than in the runtime because every layer needs the same reading of an
+ * answer: the execution service, the pipeline runner, the `ask_user` tool, the connector and the
+ * screen that finally shows it. A second reading of "was this answered" is a second contract.
+ */
+
+/**
+ * What to assume when nobody answers: the question's own default, or a decline.
+ *
+ * A decline is an ANSWER — the run carries on and records what it assumed — which is why this
+ * never throws and never returns null.
+ */
+export const defaultAnswerFor = (inquiry: Inquiry): InquiryAnswer =>
+  inquiry.default != null
+    ? { inquiryId: inquiry.id, value: inquiry.default }
+    : { inquiryId: inquiry.id, declined: true }
+
+/**
+ * The one thing an answer says, as a string — the first chosen value, else the free text, else
+ * `null` when it says nothing at all (a decline, or an empty answer).
+ */
+export const answeredWith = (answer: InquiryAnswer): string | null => {
+  const value = Array.isArray(answer.value) ? answer.value[0] : answer.value
+  if (value != null && value !== '') return value
+  if (answer.text != null && answer.text !== '') return answer.text
+
+  return null
+}
+
+/** Nobody could decide. Distinct from an empty answer — see {@link answeredWith}. */
+export const isDeclined = (answer: InquiryAnswer): boolean => answer.declined === true
+
+/**
+ * Cut an answer's free TEXT to the ceiling and SAY SO.
+ *
+ * Only the prose is cut. A `value` IS the decision — for a choice it has to equal one of the
+ * question's own option values — so slicing one does not degrade an answer, it silently replaces
+ * it with an identifier nobody offered and nothing matches, which `answeredWith` then hands on as
+ * what the person chose. An over-long value is a defect upstream rather than a long answer (the
+ * connector's schema refuses one outright instead of shortening it), so it travels on whole and is
+ * REPORTED through `truncated` — the flag every consumer already reads as "this is not exactly
+ * what the person gave".
+ */
+export const capAnswer = (
+  answer: InquiryAnswer, max: number = DEFAULT_INQUIRY_ANSWER_CHARS
+): InquiryAnswer => {
+  const text = answer.text != null && answer.text.length > max
+    ? answer.text.slice(0, max)
+    : undefined
+  const values = Array.isArray(answer.value)
+    ? answer.value
+    : answer.value != null ? [answer.value] : []
+  const oversized = values.some(value => value.length > max)
+
+  if (text == null && !oversized) return answer
+
+  return { ...answer, ...(text != null ? { text } : {}), truncated: true }
+}
+
+/**
+ * The copy of an answer a resumable pipeline STATE keeps: the decision whole, the prose cut to
+ * {@link INQUIRY_STATE_TEXT_CHARS}.
+ *
+ * The full answer goes back to whoever asked; only this reduced one is persisted, so a run that
+ * asks several questions still holds a state made of keys rather than of paragraphs.
+ */
+export const stateAnswerOf = (answer: InquiryAnswer): InquiryAnswer =>
+  answer.text != null && answer.text.length > INQUIRY_STATE_TEXT_CHARS
+    ? { ...answer, text: answer.text.slice(0, INQUIRY_STATE_TEXT_CHARS), truncated: true }
+    : answer
+
+/** One-line label of a question — for a note, a trace line or a run row. */
+export const renderInquiry = (inquiry: Inquiry): string => {
+  const options = inquiry.options != null && inquiry.options.length > 0
+    ? ` (${inquiry.options.map(option => option.value).join(' | ')})`
+    : ''
+
+  return `[${inquiry.kind}] ${inquiry.question}${options}`.replace(/\s+/g, ' ').trim()
+}