@glbgpt/cli 0.1.3 → 0.2.0

package/dist/src/core/structuredOutput.d.ts

@@ -0,0 +1,63 @@
+export type StructuredOutputMode = 'json_schema' | 'json_object';
+export interface OutputSchemaSpec {
+    /** Schema name sent to json_schema-capable providers (default "output"). */
+    name?: string;
+    schema: Record<string, unknown>;
+}
+export interface StructuredOutputPlan {
+    mode: StructuredOutputMode;
+    /** OpenAI `response_format` value to send. */
+    responseFormat: Record<string, unknown>;
+    /** Appended to the system prompt when the provider cannot enforce the schema itself. */
+    systemAddendum?: string;
+}
+/**
+ * Which structured-output mechanism a model supports. The server catalog may say so explicitly
+ * (`structured_output`); otherwise fall back to the known-family list, defaulting to json_schema.
+ */
+export declare function structuredOutputMode(model: string): StructuredOutputMode;
+/**
+ * True when `schema` already satisfies OpenAI strict-mode rules, so `strict:true` cannot be
+ * rejected: every object node has `additionalProperties:false` and a `required` array covering
+ * all of its `properties`; the check recurses through properties, array items, $defs/definitions
+ * and anyOf/oneOf/allOf. Anything unusual (non-object schema, boolean subschemas, `$ref` to
+ * elsewhere) is treated conservatively as non-compliant.
+ */
+export declare function isStrictCompliant(schema: unknown): boolean;
+/**
+ * Rewrite `schema` into an OpenAI strict-mode-compliant equivalent, or null when it uses a
+ * construct strict mode cannot express (allOf, patternProperties, an `additionalProperties`
+ * schema, tuple items, if/then/not, boolean subschemas).
+ *
+ * Rules applied recursively: every object gets `additionalProperties:false` and `required` listing
+ * ALL of its properties; properties that were optional become nullable (`type: [T, "null"]`, or an
+ * `anyOf` with `{type:"null"}`); `oneOf` becomes `anyOf`. Because optional properties are only
+ * *representable* as required-nullable in strict mode, {@link stripSyntheticNulls} removes the
+ * nulls the model emits for them so the caller sees its own schema's semantics again.
+ *
+ * Why not just send `strict:false`? Some upstream channels validate strictly regardless of the
+ * flag (observed 2026-08-18: gpt-5.6-luna channel rejected a loose schema with strict:false).
+ */
+export declare function strictify(schema: unknown): Record<string, unknown> | null;
+/**
+ * Undo the nullability {@link strictify} introduced: walk `value` alongside the CALLER's original
+ * schema and drop object properties that are null when the original schema neither required them
+ * nor allowed null. Everything else is left untouched (in place; returns `value` for chaining).
+ */
+export declare function stripSyntheticNulls(value: unknown, originalSchema: unknown): unknown;
+/** Build the request-side plan for `schema` on `model` (see module doc). */
+export declare function planStructuredOutput(model: string, spec: OutputSchemaSpec): StructuredOutputPlan;
+/** Same as {@link planStructuredOutput} but for an explicit mode (used for the json_object fallback). */
+export declare function planForMode(mode: StructuredOutputMode, spec: OutputSchemaSpec): StructuredOutputPlan;
+/**
+ * Whether a turn error is the provider rejecting our structured-output request itself (schema
+ * validation / unsupported response_format) — the case where retrying once in json_object mode
+ * is worth it. Never matches generic network/auth/billing errors.
+ */
+export declare function isResponseFormatRejection(message: string): boolean;
+/**
+ * Parse a model's structured reply. Accepts clean JSON, JSON inside ``` fences, and JSON with a
+ * short preamble/trailer (some models add "Here is the JSON:" despite instructions). Throws when
+ * no JSON value can be recovered.
+ */
+export declare function parseStructuredJson(text: string): unknown;

package/dist/src/core/structuredOutput.js

@@ -0,0 +1,328 @@
+/**
+ * Structured output (JSON schema) planning per chat model.
+ *
+ * Why this exists (prod cli_chat_turn audit, 2026-08-18): the MCP `glbgpt_chat` tool and exec
+ * `--output-schema` used to send `response_format: {type:'json_schema', strict:true, schema}`
+ * with the caller's schema untouched. Two failure classes accounted for ~70% of the anywhere-side
+ * chat errors of the last 10 days:
+ *  - OpenAI strict mode rejects any schema that is not fully "strict" (every object needs
+ *    `additionalProperties:false` and `required` listing every property key). Agents pass ordinary
+ *    JSON Schemas → 400 "Invalid schema for response_format 'output'".
+ *  - DeepSeek does not support `json_schema` at all (400 "This response_format type is unavailable
+ *    now"); it only offers `json_object`.
+ * Both surfaced to the user as a misleading "Network error" after 3 pointless retries.
+ *
+ * Plan: strict only when the schema already qualifies (keeps the guarantee for callers who did the
+ * work), non-strict otherwise; models without json_schema support get `json_object` plus the schema
+ * spelled out in the system prompt. Parsing tolerates code fences / surrounding prose either way.
+ */
+import { getChatModels } from '../tui/models.js';
+/** Model families known to reject `response_format.type = json_schema` (only json_object). */
+const JSON_OBJECT_ONLY_PREFIXES = ['deepseek'];
+/**
+ * Which structured-output mechanism a model supports. The server catalog may say so explicitly
+ * (`structured_output`); otherwise fall back to the known-family list, defaulting to json_schema.
+ */
+export function structuredOutputMode(model) {
+    const fromCatalog = getChatModels().find((m) => m.id === model)?.structuredOutput;
+    if (fromCatalog)
+        return fromCatalog;
+    const id = model.toLowerCase();
+    return JSON_OBJECT_ONLY_PREFIXES.some((p) => id.startsWith(p)) ? 'json_object' : 'json_schema';
+}
+/**
+ * True when `schema` already satisfies OpenAI strict-mode rules, so `strict:true` cannot be
+ * rejected: every object node has `additionalProperties:false` and a `required` array covering
+ * all of its `properties`; the check recurses through properties, array items, $defs/definitions
+ * and anyOf/oneOf/allOf. Anything unusual (non-object schema, boolean subschemas, `$ref` to
+ * elsewhere) is treated conservatively as non-compliant.
+ */
+export function isStrictCompliant(schema) {
+    return checkStrict(schema, 0);
+}
+function checkStrict(node, depth) {
+    if (depth > 32)
+        return false;
+    if (typeof node !== 'object' || node === null || Array.isArray(node))
+        return false;
+    const s = node;
+    const type = s.type;
+    const isObject = type === 'object' || (Array.isArray(type) && type.includes('object')) || s.properties !== undefined;
+    if (isObject) {
+        if (s.additionalProperties !== false)
+            return false;
+        const props = s.properties;
+        const keys = typeof props === 'object' && props !== null ? Object.keys(props) : [];
+        const required = Array.isArray(s.required) ? s.required : [];
+        for (const k of keys)
+            if (!required.includes(k))
+                return false;
+        for (const k of keys)
+            if (!checkStrict(props[k], depth + 1))
+                return false;
+    }
+    if (s.items !== undefined) {
+        if (Array.isArray(s.items)) {
+            for (const it of s.items)
+                if (!checkStrict(it, depth + 1))
+                    return false;
+        }
+        else if (!checkStrict(s.items, depth + 1))
+            return false;
+    }
+    for (const key of ['anyOf', 'oneOf', 'allOf']) {
+        const branches = s[key];
+        if (branches !== undefined) {
+            if (!Array.isArray(branches))
+                return false;
+            for (const b of branches)
+                if (!checkStrict(b, depth + 1))
+                    return false;
+        }
+    }
+    for (const key of ['$defs', 'definitions']) {
+        const defs = s[key];
+        if (defs !== undefined) {
+            if (typeof defs !== 'object' || defs === null)
+                return false;
+            for (const d of Object.values(defs))
+                if (!checkStrict(d, depth + 1))
+                    return false;
+        }
+    }
+    return true;
+}
+/**
+ * Rewrite `schema` into an OpenAI strict-mode-compliant equivalent, or null when it uses a
+ * construct strict mode cannot express (allOf, patternProperties, an `additionalProperties`
+ * schema, tuple items, if/then/not, boolean subschemas).
+ *
+ * Rules applied recursively: every object gets `additionalProperties:false` and `required` listing
+ * ALL of its properties; properties that were optional become nullable (`type: [T, "null"]`, or an
+ * `anyOf` with `{type:"null"}`); `oneOf` becomes `anyOf`. Because optional properties are only
+ * *representable* as required-nullable in strict mode, {@link stripSyntheticNulls} removes the
+ * nulls the model emits for them so the caller sees its own schema's semantics again.
+ *
+ * Why not just send `strict:false`? Some upstream channels validate strictly regardless of the
+ * flag (observed 2026-08-18: gpt-5.6-luna channel rejected a loose schema with strict:false).
+ */
+export function strictify(schema) {
+    const out = strictifyNode(schema, 0);
+    return out;
+}
+const UNSUPPORTED_KEYS = ['allOf', 'patternProperties', 'prefixItems', 'if', 'then', 'else', 'not', 'dependentSchemas', 'unevaluatedProperties'];
+function strictifyNode(node, depth) {
+    if (depth > 32)
+        return null;
+    if (typeof node !== 'object' || node === null || Array.isArray(node))
+        return null;
+    const s = node;
+    for (const k of UNSUPPORTED_KEYS)
+        if (s[k] !== undefined)
+            return null;
+    const out = { ...s };
+    const type = s.type;
+    const isObject = type === 'object' || (Array.isArray(type) && type.includes('object')) || s.properties !== undefined;
+    if (isObject) {
+        if (s.additionalProperties !== undefined && s.additionalProperties !== false && s.additionalProperties !== true)
+            return null;
+        const props = (typeof s.properties === 'object' && s.properties !== null ? s.properties : {});
+        const required = new Set(Array.isArray(s.required) ? s.required.filter((r) => typeof r === 'string') : []);
+        const newProps = {};
+        for (const [k, v] of Object.entries(props)) {
+            const child = strictifyNode(v, depth + 1);
+            if (!child)
+                return null;
+            newProps[k] = required.has(k) ? child : makeNullable(child);
+        }
+        out.properties = newProps;
+        out.required = Object.keys(props);
+        out.additionalProperties = false;
+    }
+    if (s.items !== undefined) {
+        if (Array.isArray(s.items))
+            return null;
+        const items = strictifyNode(s.items, depth + 1);
+        if (!items)
+            return null;
+        out.items = items;
+    }
+    const branches = s.anyOf ?? s.oneOf;
+    if (branches !== undefined) {
+        if (!Array.isArray(branches) || (s.anyOf !== undefined && s.oneOf !== undefined))
+            return null;
+        const conv = [];
+        for (const b of branches) {
+            const c = strictifyNode(b, depth + 1);
+            if (!c)
+                return null;
+            conv.push(c);
+        }
+        delete out.oneOf;
+        out.anyOf = conv;
+    }
+    for (const key of ['$defs', 'definitions']) {
+        const defs = s[key];
+        if (defs !== undefined) {
+            if (typeof defs !== 'object' || defs === null || Array.isArray(defs))
+                return null;
+            const conv = {};
+            for (const [k, v] of Object.entries(defs)) {
+                const c = strictifyNode(v, depth + 1);
+                if (!c)
+                    return null;
+                conv[k] = c;
+            }
+            out[key] = conv;
+        }
+    }
+    return out;
+}
+/** Make a (strictified) subschema accept null in the way strict mode understands. */
+function makeNullable(node) {
+    if (allowsNull(node))
+        return node;
+    if (typeof node.type === 'string')
+        return { ...node, type: [node.type, 'null'] };
+    if (Array.isArray(node.type))
+        return { ...node, type: [...node.type, 'null'] };
+    if (Array.isArray(node.anyOf))
+        return { ...node, anyOf: [...node.anyOf, { type: 'null' }] };
+    if (Array.isArray(node.enum))
+        return { ...node, enum: [...node.enum, null] };
+    // $ref / const / bare descriptions: wrap.
+    return { anyOf: [node, { type: 'null' }] };
+}
+/** Whether a schema node already admits null (by type, anyOf/oneOf branch, enum member or const). */
+function allowsNull(node) {
+    if (typeof node !== 'object' || node === null)
+        return false;
+    const s = node;
+    if (s.type === 'null' || (Array.isArray(s.type) && s.type.includes('null')))
+        return true;
+    if (Array.isArray(s.enum) && s.enum.includes(null))
+        return true;
+    if (s.const === null)
+        return true;
+    for (const key of ['anyOf', 'oneOf']) {
+        if (Array.isArray(s[key]) && s[key].some(allowsNull))
+            return true;
+    }
+    return false;
+}
+/**
+ * Undo the nullability {@link strictify} introduced: walk `value` alongside the CALLER's original
+ * schema and drop object properties that are null when the original schema neither required them
+ * nor allowed null. Everything else is left untouched (in place; returns `value` for chaining).
+ */
+export function stripSyntheticNulls(value, originalSchema) {
+    walkStrip(value, originalSchema, 0);
+    return value;
+}
+function walkStrip(value, schema, depth) {
+    if (depth > 32 || typeof schema !== 'object' || schema === null || typeof value !== 'object' || value === null)
+        return;
+    const s = schema;
+    if (Array.isArray(value)) {
+        if (s.items !== undefined && !Array.isArray(s.items))
+            for (const item of value)
+                walkStrip(item, s.items, depth + 1);
+        return;
+    }
+    const branches = (Array.isArray(s.anyOf) ? s.anyOf : Array.isArray(s.oneOf) ? s.oneOf : null);
+    if (branches && s.properties === undefined) {
+        // Cannot know which branch produced the value; only descend when exactly one branch is an object schema.
+        const objectBranches = branches.filter((b) => typeof b === 'object' && b !== null && b.properties !== undefined);
+        if (objectBranches.length === 1)
+            walkStrip(value, objectBranches[0], depth + 1);
+        return;
+    }
+    const props = (typeof s.properties === 'object' && s.properties !== null ? s.properties : null);
+    if (!props)
+        return;
+    const required = new Set(Array.isArray(s.required) ? s.required : []);
+    const obj = value;
+    for (const [k, sub] of Object.entries(props)) {
+        if (!(k in obj))
+            continue;
+        if (obj[k] === null && !required.has(k) && !allowsNull(sub)) {
+            delete obj[k];
+            continue;
+        }
+        walkStrip(obj[k], sub, depth + 1);
+    }
+}
+/** Build the request-side plan for `schema` on `model` (see module doc). */
+export function planStructuredOutput(model, spec) {
+    return planForMode(structuredOutputMode(model), spec);
+}
+/** Same as {@link planStructuredOutput} but for an explicit mode (used for the json_object fallback). */
+export function planForMode(mode, spec) {
+    const name = spec.name?.trim() || 'output';
+    if (mode === 'json_object') {
+        return {
+            mode,
+            responseFormat: { type: 'json_object' },
+            // The word "JSON" must appear in the prompt for json_object mode (DeepSeek/OpenAI requirement).
+            systemAddendum: 'Respond ONLY with a single JSON object that conforms to the following JSON Schema. ' +
+                'No prose, no markdown code fences, nothing before or after the JSON.\n' +
+                JSON.stringify(spec.schema),
+        };
+    }
+    if (isStrictCompliant(spec.schema)) {
+        return { mode, responseFormat: { type: 'json_schema', json_schema: { name, strict: true, schema: spec.schema } } };
+    }
+    const strict = strictify(spec.schema);
+    if (strict) {
+        return { mode, responseFormat: { type: 'json_schema', json_schema: { name, strict: true, schema: strict } } };
+    }
+    // Constructs strict mode cannot express: best effort, non-strict.
+    return { mode, responseFormat: { type: 'json_schema', json_schema: { name, strict: false, schema: spec.schema } } };
+}
+/**
+ * Whether a turn error is the provider rejecting our structured-output request itself (schema
+ * validation / unsupported response_format) — the case where retrying once in json_object mode
+ * is worth it. Never matches generic network/auth/billing errors.
+ */
+export function isResponseFormatRejection(message) {
+    return /response_format|json_schema|schema for response|structured output/i.test(message);
+}
+/**
+ * Parse a model's structured reply. Accepts clean JSON, JSON inside ``` fences, and JSON with a
+ * short preamble/trailer (some models add "Here is the JSON:" despite instructions). Throws when
+ * no JSON value can be recovered.
+ */
+export function parseStructuredJson(text) {
+    const trimmed = text.trim();
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        /* fall through */
+    }
+    const fence = /```(?:json)?\s*([\s\S]*?)```/i.exec(trimmed);
+    if (fence) {
+        try {
+            return JSON.parse(fence[1].trim());
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    const starts = [trimmed.indexOf('{'), trimmed.indexOf('[')].filter((i) => i >= 0);
+    if (starts.length > 0) {
+        const start = Math.min(...starts);
+        const closer = trimmed[start] === '{' ? '}' : ']';
+        const end = trimmed.lastIndexOf(closer);
+        if (end > start) {
+            try {
+                return JSON.parse(trimmed.slice(start, end + 1));
+            }
+            catch {
+                /* fall through */
+            }
+        }
+    }
+    throw new Error('Model output did not parse as JSON despite the requested schema.');
+}
+//# sourceMappingURL=structuredOutput.js.map

package/dist/src/core/structuredOutput.js.map

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

package/dist/src/core/turnLoop.d.ts

@@ -1,7 +1,12 @@
 import type { ChatBackend, EngineEvent } from './types.js';
 import type { Session } from './session.js';
 import type { ToolRegistry } from './toolRegistry.js';
-export type Emit = (event: EngineEvent) => void;
+/**
+ * Event sink. A returned promise applies BACKPRESSURE on the streaming pump (pi A3):
+ * consumeStream awaits it before pulling the next chunk, so a slow consumer (exec piping
+ * into a slow reader) bounds memory instead of buffering the whole model stream.
+ */
+export type Emit = (event: EngineEvent) => void | Promise<void>;
 /** Per-turn options. `exec --output-schema` passes a `response_format` value here. */
 export interface TurnOptions {
     responseFormat?: unknown;
@@ -11,6 +16,14 @@ export interface TurnOptions {
     includeGatedTools?: boolean;
     /** Hard cap on tool calls dispatched in this turn. Default MAX_TOOL_CALLS_PER_TURN. */
     maxToolCalls?: number;
+    /**
+     * Steering (pi B2): called at each round boundary AFTER tool results are appended and
+     * BEFORE the next model call. Returned items are appended as user messages, so text the
+     * user typed mid-turn reaches the model without waiting for the whole turn to finish.
+     * Only multi-round (tool-using) turns have injection points; anything not injected by
+     * turn end stays queued for the caller's normal follow-up flush.
+     */
+    takeSteering?: () => Array<string | import('./types.js').ContentPart[]>;
 }
 /**
  * Drives one user turn to completion, following the OpenAI tool-calling protocol:
@@ -32,6 +45,9 @@ export declare class TurnLoop {
     runTurn(session: Session, userContent: string | import('./types.js').ContentPart[], emit: Emit, opts?: TurnOptions): Promise<void>;
     /** Stream a single model call, emitting text deltas and accumulating tool_calls. */
     private streamOneCall;
-    /** Iterate the backend stream, forwarding deltas/usage and accumulating tool-call pieces. */
+    /**
+     * Iterate the backend stream, forwarding deltas/usage and accumulating tool-call pieces.
+     * Returns the last non-null finish_reason seen (providers send it on the closing chunk).
+     */
     private consumeStream;
 }

package/dist/src/core/turnLoop.js

@@ -1,7 +1,16 @@
 import { BUDGET_EXHAUSTED_MESSAGE, MAX_TOOL_CALLS_PER_TURN } from '../fs/limits.js';
 import { track } from '../telemetry/telemetry.js';
 /** Pathological backstop only — the tool budget below governs normal turns. */
-const MAX_ROUNDS = 24;
+const MAX_ROUNDS = 32;
+/**
+ * Fed back for every tool call on a message the provider cut off with finish_reason=length:
+ * streamed tool-call arguments are accumulated incrementally, so a length-truncated message
+ * can yield arguments that parse as valid JSON yet are semantically incomplete. With tools
+ * that mutate files or spend credits, executing them would corrupt state — discard them all
+ * and let the model re-issue (pi agent-loop behavior, 2026-08-08 调研 A1).
+ */
+const LENGTH_TRUNCATED_TOOLS_MESSAGE = 'Response was truncated by the output limit; this tool call was discarded because its ' +
+    'arguments may be incomplete. Re-issue the call (smaller, if possible).';
 /**
  * Drives one user turn to completion, following the OpenAI tool-calling protocol:
  *
@@ -39,8 +48,9 @@ export class TurnLoop {
         for (let round = 0; round < MAX_ROUNDS; round++) {
             let content;
             let toolCalls;
+            let finishReason;
             try {
-                ({ content, toolCalls } = await this.streamOneCall(session, emit, opts, toolCallsUsed >= budget));
+                ({ content, toolCalls, finishReason } = await this.streamOneCall(session, emit, opts, toolCallsUsed >= budget));
             }
             catch (err) {
                 // User interruption (Esc): keep whatever partial text already streamed so the
@@ -61,7 +71,10 @@ export class TurnLoop {
             if (content.length === 0 && toolCalls.length === 0) {
                 // The request itself succeeded (no throw) — the model just returned nothing. Keep the
                 // user message (not a poison payload) so a retry has context; only add nothing more.
-                emit({ type: 'error', message: 'The model returned no output. Please try again.' });
+                emit({
+                    type: 'error',
+                    message: 'The model returned no output. Please try again.',
+                });
                 return;
             }
             session.addAssistantMessage(content.length > 0 ? content : null, toolCalls);
@@ -74,6 +87,28 @@ export class TurnLoop {
                 emit({ type: 'turn_complete' });
                 return;
             }
+            // Length-truncated message with tool calls: never execute them (arguments may be
+            // silently incomplete). Answer every call with an error result and loop so the
+            // model re-issues. Consumes no budget — nothing ran.
+            if (finishReason === 'length') {
+                for (const call of toolCalls) {
+                    const result = { error: LENGTH_TRUNCATED_TOOLS_MESSAGE };
+                    emit({
+                        type: 'tool_call_begin',
+                        id: call.id,
+                        name: call.function.name,
+                        args: safeParseArgs(call.function.arguments),
+                    });
+                    emit({
+                        type: 'tool_call_end',
+                        id: call.id,
+                        name: call.function.name,
+                        result,
+                    });
+                    session.addToolMessage(call.id, call.function.name, result);
+                }
+                continue;
+            }
             // Execute the requested tools and feed results back into the conversation.
             // Tool execution itself is never aborted mid-flight (a paid submit must not be torn),
             // but an interrupt takes effect before the next model call.
@@ -116,7 +151,12 @@ export class TurnLoop {
                         ? { error: denied }
                         : await this.registry.dispatch(call.function.name, call.function.arguments);
                     // Ends may arrive out of completion order; the TUI matches rows by call id.
-                    emit({ type: 'tool_call_end', id: call.id, name: call.function.name, result });
+                    emit({
+                        type: 'tool_call_end',
+                        id: call.id,
+                        name: call.function.name,
+                        result,
+                    });
                     return result;
                 }));
                 // Tool messages must follow the tool_calls order the model emitted.
@@ -126,14 +166,24 @@ export class TurnLoop {
                 for (let i = 0; i < toolCalls.length; i++) {
                     const call = toolCalls[i];
                     const args = safeParseArgs(call.function.arguments);
-                    emit({ type: 'tool_call_begin', id: call.id, name: call.function.name, args });
+                    emit({
+                        type: 'tool_call_begin',
+                        id: call.id,
+                        name: call.function.name,
+                        args,
+                    });
                     // Past a budget/cap, don't dispatch: feed the model an error instead, so it
                     // wraps up with what it has (a normal answer, not a hard stop).
                     const denied = denial[i];
                     const result = denied
                         ? { error: denied }
                         : await this.registry.dispatch(call.function.name, call.function.arguments);
-                    emit({ type: 'tool_call_end', id: call.id, name: call.function.name, result });
+                    emit({
+                        type: 'tool_call_end',
+                        id: call.id,
+                        name: call.function.name,
+                        result,
+                    });
                     session.addToolMessage(call.id, call.function.name, result);
                 }
             }
@@ -141,10 +191,17 @@ export class TurnLoop {
                 emit({ type: 'turn_interrupted' });
                 return;
             }
-            // Loop: stream again now that tool results are in the messages.
+            // Steering: text typed mid-turn joins the conversation before the next model call.
+            for (const content of opts.takeSteering?.() ?? []) {
+                session.addUserMessage(content);
+            }
+            // Loop: stream again now that tool results (and any steering) are in the messages.
         }
         session.rollbackTo(checkpoint);
-        emit({ type: 'error', message: `Turn exceeded ${MAX_ROUNDS} tool-calling rounds` });
+        emit({
+            type: 'error',
+            message: `Turn exceeded ${MAX_ROUNDS} tool-calling rounds`,
+        });
     }
     /** Stream a single model call, emitting text deltas and accumulating tool_calls. */
     async streamOneCall(session, emit, opts, forceNoTools) {
@@ -159,8 +216,9 @@ export class TurnLoop {
         };
         let content = '';
         const toolAcc = new Map();
+        let finishReason = null;
         try {
-            await this.consumeStream(req, opts, emit, (text) => (content += text), toolAcc);
+            finishReason = await this.consumeStream(req, opts, emit, (text) => (content += text), toolAcc);
         }
         catch (err) {
             // Attach the partial text so an interrupt can preserve what already streamed.
@@ -178,10 +236,14 @@ export class TurnLoop {
             ...(e.extraContent !== undefined ? { extra_content: e.extraContent } : {}),
         }))
             .filter((c) => c.function.name.length > 0);
-        return { content, toolCalls };
+        return { content, toolCalls, finishReason };
     }
-    /** Iterate the backend stream, forwarding deltas/usage and accumulating tool-call pieces. */
+    /**
+     * Iterate the backend stream, forwarding deltas/usage and accumulating tool-call pieces.
+     * Returns the last non-null finish_reason seen (providers send it on the closing chunk).
+     */
     async consumeStream(req, opts, emit, onText, toolAcc) {
+        let finishReason = null;
         for await (const chunk of this.backend.stream(req, opts.signal)) {
             // The final chunk (include_usage) carries token counts with empty/no choices; surface
             // them before the delta guard below skips it.
@@ -193,12 +255,16 @@ export class TurnLoop {
                 });
             }
             const choice = chunk.choices?.[0];
+            if (typeof choice?.finish_reason === 'string')
+                finishReason = choice.finish_reason;
             const delta = choice?.delta;
             if (!delta)
                 continue;
             if (typeof delta.content === 'string' && delta.content.length > 0) {
                 onText(delta.content);
-                emit({ type: 'assistant_delta', text: delta.content });
+                const r = emit({ type: 'assistant_delta', text: delta.content });
+                if (r)
+                    await r; // backpressure: wait for the consumer to drain
             }
             if (delta.tool_calls) {
                 for (const tc of delta.tool_calls) {
@@ -215,6 +281,7 @@ export class TurnLoop {
                 }
             }
         }
+        return finishReason;
     }
 }
 /** Thrown when the user aborts mid-stream; carries the text streamed so far. */