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

package/README.md

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

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/llm-common",
-  "version": "0.1.18-rc.20",
-  "generatedAt": "2026-09-12T14:21:25.466Z",
+  "version": "0.1.18-rc.22",
+  "generatedAt": "2026-09-15T12:38:52.491Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/llm-common
 
 **Layer:** Core
-**Install:** `"@owlmeans/llm-common": "^0.1.18-rc.20"` in `dependencies`
+**Install:** `"@owlmeans/llm-common": "^0.1.18-rc.22"` 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.

package/build/index.d.ts

@@ -4,4 +4,5 @@ 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';
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

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

package/build/index.js

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

package/build/index.js.map

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

package/build/inquiry/consts.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 declare 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 declare 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 declare const DEFAULT_INQUIRY_ANSWER_CHARS = 2000;
+/** How many options one question may offer. Beyond this it is not a question. */
+export declare 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 declare const INQUIRY_STATE_TEXT_CHARS = 200;
+/** The answer value of a confirmed {@link InquiryKind.Confirm}. */
+export declare const CONFIRM_YES = "yes";
+/** The answer value of a refused {@link InquiryKind.Confirm}. */
+export declare const CONFIRM_NO = "no";
+//# sourceMappingURL=consts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../../src/inquiry/consts.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,oBAAY,WAAW;IACrB,MAAM,WAAW;IACjB,IAAI,SAAS;IACb,OAAO,YAAY;CACpB;AAED;;;;;;;GAOG;AACH,oBAAY,aAAa;IACvB,GAAG,QAAQ;IACX,OAAO,YAAY;IACnB,MAAM,WAAW;CAClB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,OAAQ,CAAA;AAEjD,iFAAiF;AACjF,eAAO,MAAM,uBAAuB,KAAK,CAAA;AAEzC;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,MAAM,CAAA;AAE3C,mEAAmE;AACnE,eAAO,MAAM,WAAW,QAAQ,CAAA;AAChC,iEAAiE;AACjE,eAAO,MAAM,UAAU,OAAO,CAAA"}

package/build/inquiry/consts.js

@@ -0,0 +1,50 @@
+/**
+ * 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 var InquiryKind;
+(function (InquiryKind) {
+    InquiryKind["Choice"] = "choice";
+    InquiryKind["Text"] = "text";
+    InquiryKind["Confirm"] = "confirm";
+})(InquiryKind || (InquiryKind = {}));
+/**
+ * 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 var InquiryPolicy;
+(function (InquiryPolicy) {
+    InquiryPolicy["Ask"] = "ask";
+    InquiryPolicy["Default"] = "default";
+    InquiryPolicy["Refuse"] = "refuse";
+})(InquiryPolicy || (InquiryPolicy = {}));
+/**
+ * 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';
+//# sourceMappingURL=consts.js.map

package/build/inquiry/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../../src/inquiry/consts.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAN,IAAY,WAIX;AAJD,WAAY,WAAW;IACrB,gCAAiB,CAAA;IACjB,4BAAa,CAAA;IACb,kCAAmB,CAAA;AACrB,CAAC,EAJW,WAAW,KAAX,WAAW,QAItB;AAED;;;;;;;GAOG;AACH,MAAM,CAAN,IAAY,aAIX;AAJD,WAAY,aAAa;IACvB,4BAAW,CAAA;IACX,oCAAmB,CAAA;IACnB,kCAAiB,CAAA;AACnB,CAAC,EAJW,aAAa,KAAb,aAAa,QAIxB;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,KAAK,CAAA;AAEjD,iFAAiF;AACjF,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAA;AAEzC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAG,CAAA;AAE3C,mEAAmE;AACnE,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,CAAA;AAChC,iEAAiE;AACjE,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,CAAA"}

package/build/inquiry/index.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/inquiry/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,mBAAmB,YAAY,CAAA;AAC/B,cAAc,YAAY,CAAA"}

package/build/inquiry/index.js

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

package/build/inquiry/index.js.map

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

package/build/inquiry/types.d.ts

@@ -0,0 +1,72 @@
+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;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/inquiry/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAE7D;;;;;;;GAOG;AAEH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,OAAO;IACtB,oFAAoF;IACpF,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,WAAW,CAAA;IACjB,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAA;IAChB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,kEAAkE;IAClE,OAAO,CAAC,EAAE,aAAa,EAAE,CAAA;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,qEAAqE;IACrE,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACzB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,iEAAiE;IACjE,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,aAAa,CAAC,CAAA;CACxE;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,aAAa,CAAA;CACtB"}

package/build/inquiry/types.js

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

package/build/inquiry/types.js.map

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

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
@@ -131,6 +132,12 @@ 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;
 }
 /**
  * The task level's own fields.

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.20",
+  "version": "0.1.18-rc.22",
   "license": "MIT",
   "type": "module",
   "scripts": {

package/src/index.ts

@@ -5,3 +5,4 @@ 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()
+}

package/src/types.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
@@ -141,6 +142,12 @@ 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
 }
 
 /**

package/tests/inquiry.spec.ts

@@ -0,0 +1,112 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  answeredWith, capAnswer, CONFIRM_NO, CONFIRM_YES, defaultAnswerFor, DEFAULT_INQUIRY_ANSWER_CHARS,
+  INQUIRY_STATE_TEXT_CHARS, InquiryKind, isDeclined, renderInquiry, stateAnswerOf,
+} from '../src/index.js'
+import type { Inquiry, InquiryAnswer } from '../src/index.js'
+
+/**
+ * The pure half of the inquiry primitive. Every layer that carries an answer — the execution
+ * service, the pipeline runner, the `ask_user` tool, the connector — reads it through exactly
+ * these functions, so a second reading of "was this answered" is what these specs exist to stop.
+ */
+
+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,
+})
+
+describe('@owlmeans/llm-common — what an unanswered question assumes', () => {
+  test('a question with a default answers itself with it', () => {
+    expect(defaultAnswerFor(inquiry({ default: 'postgres' })))
+      .toEqual({ inquiryId: 'q1', value: 'postgres' })
+  })
+
+  test('a question without one declines — a decision, never a failure', () => {
+    const answer = defaultAnswerFor(inquiry())
+    expect(isDeclined(answer)).toBe(true)
+    expect(answeredWith(answer)).toBeNull()
+  })
+
+  test('a multiple-choice default travels whole', () => {
+    expect(defaultAnswerFor(inquiry({ multiple: true, default: ['postgres', 'mongo'] })).value)
+      .toEqual(['postgres', 'mongo'])
+  })
+})
+
+describe('@owlmeans/llm-common — reading one answer', () => {
+  test('the chosen value wins over free text, and the first of a list is the answer', () => {
+    expect(answeredWith({ inquiryId: 'q1', value: 'mongo', text: 'or postgres' })).toBe('mongo')
+    expect(answeredWith({ inquiryId: 'q1', value: ['mongo', 'redis'] })).toBe('mongo')
+  })
+
+  test('free text answers a question that offered no options', () => {
+    expect(answeredWith({ inquiryId: 'q1', text: 'the vendor one' })).toBe('the vendor one')
+  })
+
+  test('an answer that says nothing reads as nothing, declined or not', () => {
+    expect(answeredWith({ inquiryId: 'q1' })).toBeNull()
+    expect(answeredWith({ inquiryId: 'q1', value: '', text: '' })).toBeNull()
+    expect(isDeclined({ inquiryId: 'q1' })).toBe(false)
+    expect(isDeclined({ inquiryId: 'q1', declined: true })).toBe(true)
+  })
+
+  test('a confirmation is just its two values', () => {
+    expect(answeredWith({ inquiryId: 'q1', value: CONFIRM_YES })).toBe(CONFIRM_YES)
+    expect(answeredWith({ inquiryId: 'q1', value: CONFIRM_NO })).toBe(CONFIRM_NO)
+  })
+})
+
+describe('@owlmeans/llm-common — the one ceiling', () => {
+  test('an answer inside the ceiling is left exactly as it came', () => {
+    const answer: InquiryAnswer = { inquiryId: 'q1', value: 'mongo', text: 'because of the driver' }
+    expect(capAnswer(answer)).toEqual(answer)
+    expect(capAnswer(answer).truncated).toBeUndefined()
+  })
+
+  test('a cut is never silent', () => {
+    const capped = capAnswer({ inquiryId: 'q1', text: 'x'.repeat(DEFAULT_INQUIRY_ANSWER_CHARS + 5) })
+    expect(capped.text).toHaveLength(DEFAULT_INQUIRY_ANSWER_CHARS)
+    expect(capped.truncated).toBe(true)
+  })
+
+  test('an over-long value is reported, never shortened into an option nobody offered', () => {
+    const value = ['ok', 'y'.repeat(40)]
+    const capped = capAnswer({ inquiryId: 'q1', value }, 10)
+    // Cutting prose degrades an answer; cutting an identifier CHANGES it — `answeredWith` would
+    // then hand the caller a choice the question never carried.
+    expect(capped.value).toEqual(value)
+    expect(capped.truncated).toBe(true)
+  })
+
+  test('the state copy keeps the decision whole and cuts only the prose', () => {
+    const answer: InquiryAnswer = {
+      inquiryId: 'q1', value: 'postgres', text: 'z'.repeat(INQUIRY_STATE_TEXT_CHARS + 100),
+    }
+    const stored = stateAnswerOf(answer)
+    expect(stored.value).toBe('postgres')
+    expect(stored.text).toHaveLength(INQUIRY_STATE_TEXT_CHARS)
+    expect(stored.truncated).toBe(true)
+    // The answer handed back to whoever asked is untouched — only the persisted copy is reduced.
+    expect(answer.text).toHaveLength(INQUIRY_STATE_TEXT_CHARS + 100)
+    expect(stateAnswerOf({ inquiryId: 'q1', value: 'postgres' }).truncated).toBeUndefined()
+  })
+})
+
+describe('@owlmeans/llm-common — one line for a trace', () => {
+  test('the label names the kind, the question and the choices, on one line', () => {
+    expect(renderInquiry(inquiry({ question: 'Which\n  database?' })))
+      .toBe('[choice] Which database? (postgres | mongo)')
+  })
+
+  test('a question with no options renders without an empty bracket', () => {
+    expect(renderInquiry({ id: 'q2', kind: InquiryKind.Confirm, question: 'Relocate the origin?' }))
+      .toBe('[confirm] Relocate the origin?')
+  })
+})

package/tsconfig.json

@@ -10,6 +10,8 @@
   ],
   "exclude": [
     "./dist/**/*",
-    "./build/**/*"
+    "./build/**/*",
+    "./tests/**/*",
+    "./*.ts"
   ]
 }