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

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
@@ -32,6 +33,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. */
@@ -49,6 +56,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
 }
 
 /**
@@ -129,11 +142,24 @@ 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
@@ -181,11 +207,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/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"
   ]
 }