From 7d9487e48e1144f7b2251c0c3d76d3edc3d12791 Mon Sep 17 00:00:00 2001 From: ework-agent Date: Wed, 23 Sep 2026 01:25:53 +0800 Subject: [PATCH] =?UTF-8?q?feat(output-steering):=20kernel-side=20output?= =?UTF-8?q?=20steering=20decisions=20=E2=80=94=20turn=20classification,=20?= =?UTF-8?q?verbosity=20L0-L4,=20clamp-only=20effort=20routing=20(#355)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- DESIGN.md | 2 + README.md | 1 + src/index.ts | 26 +++ src/output-steering.ts | 320 +++++++++++++++++++++++++ tests/output-steering.test.ts | 429 ++++++++++++++++++++++++++++++++++ 5 files changed, 778 insertions(+) create mode 100644 src/output-steering.ts create mode 100644 tests/output-steering.test.ts diff --git a/DESIGN.md b/DESIGN.md index ea4d187..1a84e47 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -211,6 +211,8 @@ A default `countTokens` ships with the core (word-level + unicode CJK tokenizer, | compress/decompress/search/status **tool registration** | **adapter** (calls core pure fns) | | `/acp` commands | **adapter** | | opencode hooks | **OpenCode adapter** | +| output-steering **decisions** (turn classification / verbosity level / effort clamp, #355) | **core** `decideOutputSteering` (pure; operates on a structural summary — role + block kinds, no content) | +| output-steering **landing** (wire field write-back, system-prompt carrier selection, numeric budget floors) | **adapter** | | config three-layer merge | **adapter** (core only consumes its own `Config`) | | logger / auth / persistence / update | **adapter** (core does zero I/O) | diff --git a/README.md b/README.md index a0cc423..ab5aa52 100644 --- a/README.md +++ b/README.md @@ -104,6 +104,7 @@ live-recomputed tags, use `renderVisibleRefs` directly. | `rebuildCompressionState` | Fork-recovery: replay historical compress calls | | `applyMessageFilters` | Pluggable message-filter framework | | `resolveTransformChannel` | Channel-selection policy: an explicit preference wins; the default is the wire channel only when the caller reports it viable | +| `decideOutputSteering` / `classifyTurn` / `clampEffortToFloor` / `applySteeringToPrompt` | Output-side steering *decisions* (#355): structural turn classification (`new_user_ask` / `mechanical_continuation` / `error_continuation` / `unknown`), byte-stable verbosity directives L0–L4 (default L2), and clamp-only effort routing. The kernel decides; adapters land decisions onto wire fields. Default OFF | | `applySectionOverrides` / `cloneWithDescriptions` / `applyAcpToolOverrides` | Prompt/tool *surface* customization (see below) | | `sanitizePackSurface` / `createPackResolver` / `defaultPackSources` | Prompt packs: named, swappable surface presets resolved over pluggable sources (see below) | diff --git a/src/index.ts b/src/index.ts index 6af20e0..7fcc251 100644 --- a/src/index.ts +++ b/src/index.ts @@ -249,3 +249,29 @@ export { export * from "./filter/index.js"; export { VIABLE_RANGE_MIN_TOKENS, viableRanges } from "./viable.js"; +export { + classifyTurn, + verbosityDirective, + renderSteeringBlock, + applySteeringToPrompt, + clampEffortToFloor, + resolveVerbosityLevel, + resolveOutputSteeringConfig, + decideOutputSteering, + VERBOSITY_LEVELS, + EFFORT_LADDER, + DEFAULT_OUTPUT_STEERING_CONFIG, + DEFAULT_STEERING_SENTINEL, + DEFAULT_VERBOSITY_LEVEL, + MIN_VERBOSITY_LEVEL, + MAX_VERBOSITY_LEVEL, +} from "./output-steering.js"; +export type { + TurnKind, + StructuralMessage, + StructuralBlock, + OutputSteeringConfig, + OutputSteeringDecision, + SteeringPlacement, + EffortValue, +} from "./output-steering.js"; diff --git a/src/output-steering.ts b/src/output-steering.ts new file mode 100644 index 0000000..6dd95ef --- /dev/null +++ b/src/output-steering.ts @@ -0,0 +1,320 @@ +/** + * Output-side steering decisions (#355): turn-structure classification, + * verbosity levels (L0–L4), clamp-only effort routing. + * + * This module is the protocol-agnostic half of output-side compression. It + * DECIDES; adapters LAND. Adapters (e.g. billion-context) own: + * - mapping their wire body onto `StructuralMessage[]` (contract below), + * - writing the decision onto wire-specific fields (effort field names, + * system-prompt carriers, numeric budget floors), + * - config persistence and logging of returned warnings. + * + * Hard boundaries: + * 1. CLAMP-ONLY — `lowerEffort` never means "raise". Adapters lower only + * effort fields the client ALREADY sent; absent fields are never + * injected (models without effort support 400 on them), and values + * at/below the floor are left alone (`clampEffortToFloor`). + * 2. TAIL-ONLY injection — the verbosity directive goes at the TAIL of the + * system prompt (prefix cache requires stable head bytes; never prepend). + * `applySteeringToPrompt` replaces an existing sentinel block in place, + * so re-applying the same level is a byte-stable no-op (compress retries + * re-send through this path). + * 3. BYTE-STABLE directives — the L1–L4 texts below are frozen across + * releases. Editing one character busts the prefix cache of every + * session pinned at that level. Change only with a deliberate, + * announced cache bust. + * + * Origin: decision logic adapted from billion-context PR#1096 + * (`2026-09-21_output-side-compression`, `src/output-steering.ts`; design per + * headroomlabs-ai/headroom's output-token-reduction proposal). Per-wire rules + * are preserved here as the normalization contract; wire-side landing stays + * in adapters. + */ + +export type TurnKind = + "new_user_ask" | "mechanical_continuation" | "error_continuation" | "unknown"; + +export interface StructuralBlock { + /** + * `text` / `image` / `document` — user signal ⇒ new_user_ask. + * `tool_result` — machine-produced result; accumulates toward a + * continuation verdict. + */ + kind: "text" | "image" | "document" | "tool_result"; + /** `tool_result` only: the wire's error flag (Anthropic `is_error`). Absent = clean. */ + isError?: boolean; +} + +export interface StructuralMessage { + role: string; + /** Plain-string content (Anthropic/OpenAI allow string content). Mutually exclusive with `blocks` in practice; `text` wins when both present. */ + text?: string; + blocks?: StructuralBlock[]; +} + +/** + * Classify the FINAL turn purely structurally — block composition only, no + * content pattern-matching. Only the last message matters. Conservative by + * design: anything unrecognized yields `unknown` (never a guess), because an + * unrecognized composition may carry user intent we cannot see. + */ +export function classifyTurn(messages: readonly StructuralMessage[]): TurnKind { + if (messages.length === 0) return "unknown"; + const last = messages[messages.length - 1]!; + if (!last || last.role !== "user") return "unknown"; + if (typeof last.text === "string") + return last.text.trim() ? "new_user_ask" : "unknown"; + const blocks = last.blocks; + if (!Array.isArray(blocks) || blocks.length === 0) return "unknown"; + let sawToolResult = false; + let sawError = false; + for (const b of blocks) { + if (!b) return "unknown"; + switch (b.kind) { + case "tool_result": + sawToolResult = true; + if (b.isError === true) sawError = true; + break; + case "text": + case "image": + case "document": + return "new_user_ask"; + default: + return "unknown"; + } + } + if (sawError) return "error_continuation"; + if (sawToolResult) return "mechanical_continuation"; + return "unknown"; +} + +/** + * Normalization contract (adapter responsibility — documented here because + * classification correctness depends on it): + * + * - Anthropic: pass through. String content → `text`; content blocks map by + * `type`: text/image/document → same kind; tool_result → tool_result with + * `isError = block.is_error === true`. + * - OpenAI chat: fold trailing consecutive `role:"tool"` messages into ONE + * synthetic final user message carrying tool_result blocks (no error flag + * exists on this wire → `isError` stays absent). A trailing user message + * passes through (string content → `text`; array content: non-empty text + * part → text block, otherwise unknown). + * - Responses: walk `input` BACKWARD from the end (clients re-send full + * history every request — scanning forward would hit the original ask on + * every turn). Items after the last user signal: `*_call_output` + * (function/custom_tool/local_shell/apply_patch) → tool_result blocks; + * assistant-side items (message/function_call/custom_tool_call/ + * local_shell_call/apply_patch_call/reasoning) form the preceding + * assistant message(s). User signal = `input_text` (non-empty), + * `input_image`, `input_file`, or a role:"user" message with non-empty + * text. Trailing outputs ⇒ final user(tool_results); none ⇒ final + * user(text); pending call with no output yet ⇒ unknown. + * - Google: the last `contents` entry must be role:"user"; parts map: + * functionResponse → tool_result; non-empty text → text; empty text → + * dropped (neutral); inlineData/fileData/videoMetadata → image/document. + * + * Anything unrecognized maps to nothing (→ `unknown`), never to a guess. + */ + +export const MIN_VERBOSITY_LEVEL = 0; +export const MAX_VERBOSITY_LEVEL = 4; +export const DEFAULT_VERBOSITY_LEVEL = 2; + +/** Conciseness directives L1–L4. L0 = no directive. FROZEN across releases. */ +export const VERBOSITY_LEVELS: Readonly> = { + 1: "Skip preamble and postamble. Do not announce what you are about to do or recap what you just did; start with the substance.", + 2: "Skip preamble and postamble; start with the substance. Never restate code, file contents, diffs, or tool output that already appear in this conversation — reference them by path and line instead. After a tool call succeeds, continue without narrating the result.", + 3: "Skip preamble and postamble. Never restate code, file contents, diffs, or tool output already in this conversation — cite the exact file path and line or symbol instead, always; a reference that omits the location is not a reference. Give conclusions only; omit rationale unless the user asks why. Prefer the smallest edit over rewriting whole files. Keep prose to the minimum needed to be unambiguous. Never drop anything the turn or task needs to be correct, including negations (not, never, no, only, except) — shorten how you say it, not what you say. Use full prose for destructive or irreversible actions, security warnings, and any multi-step sequence where brevity would create ambiguity.", + 4: "Minimum tokens. Fragments fine. No preamble, no postamble, no restating context, no rationale. Answer, smallest-possible edits, nothing else. Never drop anything the turn or task needs to be correct, including negations (not, never, no, only, except). Use full prose for destructive or irreversible actions, security warnings, and any multi-step sequence where brevity would create ambiguity.", +}; + +export function verbosityDirective(level: number): string | null { + if (!Number.isInteger(level)) return null; + return VERBOSITY_LEVELS[level] ?? null; +} + +/** + * Default sentinel wrapping the steering directive. Each host SHOULD pass its + * own sentinel so a body that passes through several proxies never collides + * (billion-context uses ``). Must be a full opening + * XML-style tag ``; the closing tag is derived as ``. + */ +export const DEFAULT_STEERING_SENTINEL = ""; + +export function renderSteeringBlock( + level: number, + sentinel: string = DEFAULT_STEERING_SENTINEL, +): string | null { + const text = verbosityDirective(level); + if (text === null) return null; + return `${sentinel}\n${text}\n= 0) { + const found = existing.indexOf(suffix, start); + const end = found < 0 ? existing.length : found + suffix.length; + const prefix = existing.slice(0, start).replace(/\s+$/, ""); + const tail = existing.slice(end).replace(/^\n+/, ""); + const parts = [prefix, block, tail].filter((p) => p.length > 0); + const updated = parts.join("\n\n"); + return { updated, changed: updated !== existing }; + } + const trimmed = existing.trim(); + const updated = + trimmed.length > 0 ? `${existing.replace(/\s+$/, "")}\n\n${block}` : block; + return { updated, changed: updated !== existing }; +} + +/** + * Ascending shared effort ladder (OpenAI chat / Responses / Anthropic + * output_config.effort use these values). Wire-specific NUMERIC budget floors + * (e.g. Anthropic thinking.budget_tokens ≥ 1024, Google thinkingBudget ≥ 128, + * dynamic `-1` untouched) live adapter-side — they are properties of wire + * fields, not of the decision. + */ +export const EFFORT_LADDER = [ + "minimal", + "low", + "medium", + "high", + "xhigh", +] as const; +export type EffortValue = (typeof EFFORT_LADDER)[number]; + +/** + * Clamp-only floor computation. Returns the value to write, or null when the + * field is absent/unrecognized or already at/below `floor`. Never raises: a + * client that explicitly asked for `minimal` keeps it. Unrecognized values + * are left untouched rather than coerced — coercing an unknown value that + * happens to sit below the floor would be a raise. + */ +export function clampEffortToFloor( + current: unknown, + floor: EffortValue = "low", +): EffortValue | null { + if (typeof current !== "string") return null; + const ci = (EFFORT_LADDER as readonly string[]).indexOf(current); + if (ci === -1) return null; + const fi = EFFORT_LADDER.indexOf(floor); + return ci > fi ? floor : null; +} + +export interface OutputSteeringConfig { + /** Master switch. Default OFF — both levers inert until explicitly on. */ + enabled: boolean; + /** Verbosity level 0–4 (0 = no directive). Default 2. */ + verbosityLevel: number; + /** Effort-routing sub-switch. Default on whenever `enabled` is. */ + effortRouting: boolean; +} + +export const DEFAULT_OUTPUT_STEERING_CONFIG: OutputSteeringConfig = { + enabled: false, + verbosityLevel: DEFAULT_VERBOSITY_LEVEL, + effortRouting: true, +}; + +/** + * Resolve a raw verbosity level. An OMITTED field silently takes the default; + * a PRESENT but out-of-range value falls back WITH a warning (honest output — + * a valid partial config must not be accused of being malformed). + */ +export function resolveVerbosityLevel(v: unknown): { + level: number; + warning?: string; +} { + if ( + typeof v === "number" && + Number.isInteger(v) && + v >= MIN_VERBOSITY_LEVEL && + v <= MAX_VERBOSITY_LEVEL + ) { + return { level: v }; + } + const level = DEFAULT_OUTPUT_STEERING_CONFIG.verbosityLevel; + if (v === undefined) return { level }; + return { + level, + warning: `[config] outputSteering.verbosityLevel must be an integer ${MIN_VERBOSITY_LEVEL}-${MAX_VERBOSITY_LEVEL}; got ${JSON.stringify(v)} — falling back to ${level}`, + }; +} + +/** + * Validate a raw `outputSteering` config value (e.g. parsed JSON). Malformed + * fields fall back to defaults rather than throwing; warnings are returned + * as data for the host to log. Non-object input yields pure defaults. + */ +export function resolveOutputSteeringConfig(v: unknown): { + config: OutputSteeringConfig; + warnings: string[]; +} { + if (!v || typeof v !== "object" || Array.isArray(v)) { + return { config: DEFAULT_OUTPUT_STEERING_CONFIG, warnings: [] }; + } + const obj = v as Record; + const lvl = resolveVerbosityLevel(obj.verbosityLevel); + return { + config: { + enabled: obj.enabled === true, + verbosityLevel: lvl.level, + effortRouting: obj.effortRouting !== false, + }, + warnings: lvl.warning ? [lvl.warning] : [], + }; +} + +export interface OutputSteeringDecision { + /** Structural classification of the final turn (echoed for observability/logging). */ + turnKind: TurnKind; + /** Level to inject; 0 = inject nothing. Always 0 while disabled. */ + verbosityLevel: number; + /** + * Clamp-only routing: true ⇔ enabled && effortRouting && mechanical + * continuation. The adapter lowers each effort field the client already + * sent toward its wire floor; it never injects absent fields and never + * raises any value. + */ + lowerEffort: boolean; +} + +/** + * Single decision entry point: structural summary of the FINAL message list + * (+ resolved config) → steering decision. Pure, synchronous, side-effect + * free. Landing — which field gets written, which carrier holds the system + * prompt — is the adapter's job. + */ +export function decideOutputSteering( + messages: readonly StructuralMessage[], + config: OutputSteeringConfig = DEFAULT_OUTPUT_STEERING_CONFIG, +): OutputSteeringDecision { + const turnKind = classifyTurn(messages); + return { + turnKind, + verbosityLevel: config.enabled ? config.verbosityLevel : 0, + lowerEffort: + config.enabled && + config.effortRouting && + turnKind === "mechanical_continuation", + }; +} diff --git a/tests/output-steering.test.ts b/tests/output-steering.test.ts new file mode 100644 index 0000000..aa19a26 --- /dev/null +++ b/tests/output-steering.test.ts @@ -0,0 +1,429 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { + applySteeringToPrompt, + clampEffortToFloor, + classifyTurn, + decideOutputSteering, + DEFAULT_OUTPUT_STEERING_CONFIG, + DEFAULT_STEERING_SENTINEL, + EFFORT_LADDER, + renderSteeringBlock, + resolveOutputSteeringConfig, + resolveVerbosityLevel, + VERBOSITY_LEVELS, + verbosityDirective, +} from "../src/output-steering.js"; +import type { + OutputSteeringConfig, + StructuralBlock, + StructuralMessage, +} from "../src/output-steering.js"; + +const ON: OutputSteeringConfig = { + enabled: true, + verbosityLevel: 2, + effortRouting: true, +}; + +const userText = (text: string): StructuralMessage => ({ role: "user", text }); +const userBlocks = (blocks: StructuralBlock[]): StructuralMessage => ({ + role: "user", + blocks, +}); +const assistant = (): StructuralMessage => ({ role: "assistant" }); +const toolResult = (isError = false): StructuralBlock => ({ + kind: "tool_result", + ...(isError ? { isError: true } : {}), +}); +const textBlock = (): StructuralBlock => ({ kind: "text" }); + +// ---- classifyTurn ---- + +test("classifyTurn: empty list and non-user last message are unknown", () => { + assert.equal(classifyTurn([]), "unknown"); + assert.equal(classifyTurn([assistant()]), "unknown"); + assert.equal(classifyTurn([userText("hi"), assistant()]), "unknown"); +}); + +test("classifyTurn: string content — non-empty asks, empty/whitespace unknown", () => { + assert.equal(classifyTurn([userText("hi")]), "new_user_ask"); + assert.equal(classifyTurn([userText("")]), "unknown"); + assert.equal(classifyTurn([userText(" \n\t")]), "unknown"); +}); + +test("classifyTurn: tool_result composition", () => { + assert.equal( + classifyTurn([userBlocks([toolResult()])]), + "mechanical_continuation", + ); + assert.equal( + classifyTurn([userBlocks([toolResult(), toolResult()])]), + "mechanical_continuation", + ); + assert.equal( + classifyTurn([userBlocks([toolResult(true)])]), + "error_continuation", + ); + assert.equal( + classifyTurn([userBlocks([toolResult(), toolResult(true)])]), + "error_continuation", + ); +}); + +test("classifyTurn: any user-signal block short-circuits to new_user_ask", () => { + assert.equal( + classifyTurn([userBlocks([toolResult(), textBlock()])]), + "new_user_ask", + ); + assert.equal(classifyTurn([userBlocks([{ kind: "image" }])]), "new_user_ask"); + assert.equal( + classifyTurn([userBlocks([{ kind: "document" }])]), + "new_user_ask", + ); +}); + +test("classifyTurn: unrecognized composition is unknown, never a guess", () => { + assert.equal(classifyTurn([userBlocks([])]), "unknown"); + assert.equal(classifyTurn([{ role: "user" }]), "unknown"); + const mystery: StructuralBlock = JSON.parse('{"kind":"mystery_block"}'); + assert.equal(classifyTurn([userBlocks([toolResult(), mystery])]), "unknown"); + const nullBlock: StructuralBlock = JSON.parse("null"); + assert.equal( + classifyTurn([userBlocks([toolResult(), nullBlock])]), + "unknown", + ); +}); + +test("normalize contract: openai trailing-tool fold ⇒ mechanical", () => { + // Adapter folds trailing role:"tool" messages into one synthetic user message. + const folded: StructuralMessage[] = [ + userText("hi"), + assistant(), + userBlocks([toolResult()]), + ]; + assert.equal(classifyTurn(folded), "mechanical_continuation"); +}); + +test("normalize contract: responses full-history re-send ⇒ mechanical", () => { + // Original ask + call + trailing output; backward walk lands on the output. + const resent: StructuralMessage[] = [ + userText("fix the bug"), + assistant(), + userBlocks([toolResult()]), + ]; + assert.equal(classifyTurn(resent), "mechanical_continuation"); +}); + +test("normalize contract: responses pending call with no output ⇒ unknown", () => { + const pending: StructuralMessage[] = [userText("do X"), assistant()]; + assert.equal(classifyTurn(pending), "unknown"); +}); + +test("normalize contract: fresh user signal at the tail blocks lowering", () => { + const fresh: StructuralMessage[] = [ + userText("do X"), + assistant(), + userBlocks([toolResult()]), + userText("now do Y"), + ]; + assert.equal(classifyTurn(fresh), "new_user_ask"); +}); + +test("normalize contract: google functionResponse-only turn ⇒ mechanical", () => { + assert.equal( + classifyTurn([userBlocks([toolResult()])]), + "mechanical_continuation", + ); +}); + +// ---- Verbosity levels (byte-stable) ---- + +test("VERBOSITY_LEVELS are byte-stable across versions (frozen baseline)", () => { + assert.equal( + VERBOSITY_LEVELS[1], + "Skip preamble and postamble. Do not announce what you are about to do or recap what you just did; start with the substance.", + ); + assert.equal( + VERBOSITY_LEVELS[2], + "Skip preamble and postamble; start with the substance. Never restate code, file contents, diffs, or tool output that already appear in this conversation — reference them by path and line instead. After a tool call succeeds, continue without narrating the result.", + ); + assert.equal( + VERBOSITY_LEVELS[3], + "Skip preamble and postamble. Never restate code, file contents, diffs, or tool output already in this conversation — cite the exact file path and line or symbol instead, always; a reference that omits the location is not a reference. Give conclusions only; omit rationale unless the user asks why. Prefer the smallest edit over rewriting whole files. Keep prose to the minimum needed to be unambiguous. Never drop anything the turn or task needs to be correct, including negations (not, never, no, only, except) — shorten how you say it, not what you say. Use full prose for destructive or irreversible actions, security warnings, and any multi-step sequence where brevity would create ambiguity.", + ); + assert.equal( + VERBOSITY_LEVELS[4], + "Minimum tokens. Fragments fine. No preamble, no postamble, no restating context, no rationale. Answer, smallest-possible edits, nothing else. Never drop anything the turn or task needs to be correct, including negations (not, never, no, only, except). Use full prose for destructive or irreversible actions, security warnings, and any multi-step sequence where brevity would create ambiguity.", + ); + assert.equal(VERBOSITY_LEVELS[0], undefined, "L0 has no directive"); + assert.equal(VERBOSITY_LEVELS[5], undefined); +}); + +test("verbosityDirective: L0 and out-of-range yield null", () => { + assert.equal(verbosityDirective(0), null); + assert.equal(verbosityDirective(5), null); + assert.equal(verbosityDirective(-1), null); + assert.equal(verbosityDirective(2.5), null); + for (const lvl of [1, 2, 3, 4]) + assert.equal(verbosityDirective(lvl), VERBOSITY_LEVELS[lvl]); +}); + +test("renderSteeringBlock: sentinel-wrapped, distinct per level, custom sentinel supported", () => { + const l2 = renderSteeringBlock(2)!; + assert.ok(l2.startsWith(`${DEFAULT_STEERING_SENTINEL}\n`)); + assert.ok(l2.endsWith(`")!; + assert.ok(bili.startsWith("\n")); + assert.ok(bili.endsWith("")); + assert.equal(renderSteeringBlock(0), null); +}); + +// ---- applySteeringToPrompt (tail-only, idempotent) ---- + +test("applySteeringToPrompt: appends at the tail, never prepends", () => { + const block = renderSteeringBlock(2)!; + const empty = applySteeringToPrompt("", block); + assert.deepEqual(empty, { updated: block, changed: true }); + const filled = applySteeringToPrompt("You are terse.", block); + assert.equal(filled.changed, true); + assert.equal(filled.updated, `You are terse.\n\n${block}`); + assert.ok( + !filled.updated.startsWith(DEFAULT_STEERING_SENTINEL), + "never prepends", + ); +}); + +test("applySteeringToPrompt: same-level re-apply is a byte-stable no-op (retry safety)", () => { + const block = renderSteeringBlock(2)!; + const first = applySteeringToPrompt("You are terse.", block); + const second = applySteeringToPrompt(first.updated, block); + assert.equal(second.changed, false); + assert.equal(second.updated, first.updated); +}); + +test("applySteeringToPrompt: a level change REPLACES the block in place (no duplication)", () => { + const first = applySteeringToPrompt( + "You are terse.", + renderSteeringBlock(2)!, + ); + const third = applySteeringToPrompt(first.updated, renderSteeringBlock(3)!); + assert.equal(third.changed, true); + assert.equal( + third.updated.split(DEFAULT_STEERING_SENTINEL).length - 1, + 1, + "exactly one steering block after a level change", + ); + assert.ok(third.updated.includes(VERBOSITY_LEVELS[3]!)); + assert.ok( + !third.updated.includes(VERBOSITY_LEVELS[2]!), + "old directive removed", + ); +}); + +test("applySteeringToPrompt: surrounding text after the block is preserved", () => { + const sent = DEFAULT_STEERING_SENTINEL; + const close = ` { + const sent = DEFAULT_STEERING_SENTINEL; + const block = renderSteeringBlock(2)!; + const first = applySteeringToPrompt(`x ${sent}\npartial`, block); + assert.equal(first.changed, true); + assert.equal(first.updated.split(sent).length - 1, 1); + const second = applySteeringToPrompt(first.updated, block); + assert.equal(second.changed, false); +}); + +// ---- clampEffortToFloor (clamp-only) ---- + +test("clampEffortToFloor: known ladder values clamp down to low", () => { + assert.equal(clampEffortToFloor("medium"), "low"); + assert.equal(clampEffortToFloor("high"), "low"); + assert.equal(clampEffortToFloor("xhigh"), "low"); +}); + +test("clampEffortToFloor: never raises — at/below floor stays untouched", () => { + assert.equal( + clampEffortToFloor("minimal"), + null, + "minimal sits below low — client intent wins", + ); + assert.equal(clampEffortToFloor("low"), null); +}); + +test("clampEffortToFloor: absent/unrecognized values are left alone (never injected, never coerced)", () => { + assert.equal(clampEffortToFloor(undefined), null); + assert.equal(clampEffortToFloor(null), null); + assert.equal(clampEffortToFloor(42), null); + assert.equal(clampEffortToFloor(""), null); + assert.equal(clampEffortToFloor("off"), null); + assert.equal(clampEffortToFloor("LOW"), null); +}); + +test("clampEffortToFloor: custom floor clamps toward it, still never raises", () => { + assert.equal(clampEffortToFloor("high", "medium"), "medium"); + assert.equal(clampEffortToFloor("xhigh", "medium"), "medium"); + assert.equal(clampEffortToFloor("medium", "medium"), null); + assert.equal(clampEffortToFloor("low", "medium"), null); +}); + +test("EFFORT_LADDER is ascending minimal < low < medium < high < xhigh", () => { + const order = ["minimal", "low", "medium", "high", "xhigh"]; + assert.deepEqual([...EFFORT_LADDER], order); +}); + +// ---- Config resolution ---- + +test("DEFAULT_OUTPUT_STEERING_CONFIG is off by default (hard requirement)", () => { + assert.equal(DEFAULT_OUTPUT_STEERING_CONFIG.enabled, false); + assert.equal(DEFAULT_OUTPUT_STEERING_CONFIG.verbosityLevel, 2); + assert.equal(DEFAULT_OUTPUT_STEERING_CONFIG.effortRouting, true); +}); + +test("resolveVerbosityLevel: omitted takes default WITHOUT warning", () => { + assert.deepEqual(resolveVerbosityLevel(undefined), { level: 2 }); +}); + +test("resolveVerbosityLevel: valid levels 0-4 pass through untouched", () => { + for (const n of [0, 1, 2, 3, 4]) + assert.deepEqual(resolveVerbosityLevel(n), { level: n }); +}); + +test("resolveVerbosityLevel: present-but-invalid values warn and fall back", () => { + for (const bad of [9, -1, 2.5, "high", null]) { + const r = resolveVerbosityLevel(bad); + assert.equal(r.level, 2); + assert.ok( + r.warning?.includes("must be an integer 0-4"), + `expected warning for ${JSON.stringify(bad)}, got ${r.warning}`, + ); + } +}); + +test("resolveOutputSteeringConfig: non-object falls back to pure defaults", () => { + for (const v of [undefined, null, "on", [], 42]) { + const r = resolveOutputSteeringConfig(v); + assert.deepEqual( + r.config, + DEFAULT_OUTPUT_STEERING_CONFIG, + `${JSON.stringify(v)} → defaults`, + ); + assert.deepEqual(r.warnings, []); + } +}); + +test("resolveOutputSteeringConfig: partial configs fill defaults, malformed fields fall back", () => { + assert.deepEqual( + resolveOutputSteeringConfig({}).config, + DEFAULT_OUTPUT_STEERING_CONFIG, + ); + assert.deepEqual(resolveOutputSteeringConfig({ enabled: true }).config, { + enabled: true, + verbosityLevel: 2, + effortRouting: true, + }); + assert.equal( + resolveOutputSteeringConfig({ enabled: "yes" }).config.enabled, + false, + "strict === true", + ); + assert.equal( + resolveOutputSteeringConfig({ verbosityLevel: 0 }).config.verbosityLevel, + 0, + ); + assert.equal( + resolveOutputSteeringConfig({ verbosityLevel: 4 }).config.verbosityLevel, + 4, + ); + const bad = resolveOutputSteeringConfig({ verbosityLevel: 9 }); + assert.equal(bad.config.verbosityLevel, 2); + assert.equal(bad.warnings.length, 1); + assert.deepEqual( + resolveOutputSteeringConfig({ effortRouting: false }).config, + { enabled: false, verbosityLevel: 2, effortRouting: false }, + ); +}); + +// ---- decideOutputSteering ---- + +const MECH: StructuralMessage[] = [assistant(), userBlocks([toolResult()])]; +const ASK: StructuralMessage[] = [assistant(), userText("next question")]; +const ERR: StructuralMessage[] = [assistant(), userBlocks([toolResult(true)])]; + +test("decideOutputSteering: disabled (default) is fully inert even on mechanical turns", () => { + assert.deepEqual(decideOutputSteering(MECH), { + turnKind: "mechanical_continuation", + verbosityLevel: 0, + lowerEffort: false, + }); +}); + +test("decideOutputSteering: enabled fires both levers on mechanical continuations", () => { + assert.deepEqual(decideOutputSteering(MECH, ON), { + turnKind: "mechanical_continuation", + verbosityLevel: 2, + lowerEffort: true, + }); +}); + +test("decideOutputSteering: effort routing never fires off mechanical turns", () => { + assert.equal(decideOutputSteering(ASK, ON).lowerEffort, false); + assert.equal(decideOutputSteering(ERR, ON).lowerEffort, false); + assert.equal(decideOutputSteering([assistant()], ON).lowerEffort, false); + assert.equal(decideOutputSteering(ERR, ON).turnKind, "error_continuation"); + assert.equal(decideOutputSteering(ASK, ON).turnKind, "new_user_ask"); +}); + +test("decideOutputSteering: effortRouting sub-switch gates lowering only", () => { + const cfg: OutputSteeringConfig = { + enabled: true, + verbosityLevel: 2, + effortRouting: false, + }; + const d = decideOutputSteering(MECH, cfg); + assert.equal(d.lowerEffort, false); + assert.equal(d.verbosityLevel, 2, "verbosity unaffected by the sub-switch"); +}); + +test("decideOutputSteering: verbosityLevel 0 disables injection but keeps routing", () => { + const d = decideOutputSteering(MECH, { + enabled: true, + verbosityLevel: 0, + effortRouting: true, + }); + assert.deepEqual(d, { + turnKind: "mechanical_continuation", + verbosityLevel: 0, + lowerEffort: true, + }); +}); + +// ---- End-to-end retry path (idempotency requirement) ---- + +test("retry path: decide → inject → re-inject is byte-stable; level change replaces in place", () => { + const d1 = decideOutputSteering(MECH, ON); + const block = renderSteeringBlock(d1.verbosityLevel)!; + let prompt = "You are terse."; + const p1 = applySteeringToPrompt(prompt, block); + assert.equal(p1.changed, true); + const p2 = applySteeringToPrompt(p1.updated, block); + assert.equal(p2.changed, false, "re-applying the same level must not mutate"); + assert.equal(p2.updated, p1.updated, "...and must be byte-identical"); + const p3 = applySteeringToPrompt(p1.updated, renderSteeringBlock(3)!); + assert.equal( + p3.updated.split(DEFAULT_STEERING_SENTINEL).length - 1, + 1, + "no duplicated steering blocks", + ); +});