@oh-my-pi/pi-agent-core 18.3.0 → 18.3.1

package/src/live-steering.ts

@@ -0,0 +1,89 @@
+/**
+ * Agent side of provider live steering ({@link LiveSteering}).
+ *
+ * A provider that can put user input into the response it is streaming (OpenAI
+ * Responses `response.steer`) pulls queued steering through a
+ * {@link LiveSteeringChannel}. The loop records what the provider accepted right
+ * after that response, so the transcript matches what the model saw; anything
+ * it declined is injected at the next boundary like ordinary steering.
+ */
+import type { LiveSteerClaim, LiveSteering, UserMessage } from "@oh-my-pi/pi-ai";
+import { logger } from "@oh-my-pi/pi-utils";
+import type { AgentMessage } from "./types";
+
+/** Steering-queue access for one provider call, supplied by the agent loop. */
+export interface LiveSteeringQueue {
+	/** Resolves once steering is queued or `signal` aborts; never consumes. */
+	wait(signal: AbortSignal): Promise<void>;
+	/** Dequeues the next steering batch. */
+	take(signal: AbortSignal): Promise<AgentMessage[]>;
+	/**
+	 * Provider view of `messages` appended to the in-flight call's context, or
+	 * `undefined` when that view is not purely user messages.
+	 */
+	toProvider(messages: AgentMessage[], signal: AbortSignal): Promise<UserMessage[] | undefined>;
+}
+
+/** One provider call's {@link LiveSteering} source. */
+export class LiveSteeringChannel implements LiveSteering {
+	/** Steering the provider delivered into the in-flight response, in queue order. */
+	readonly accepted: AgentMessage[] = [];
+	/** Steering taken from the queue but not delivered; always queued after {@link accepted}. */
+	readonly deferred: AgentMessage[] = [];
+	readonly #queue: LiveSteeringQueue;
+
+	constructor(queue: LiveSteeringQueue) {
+		this.#queue = queue;
+	}
+
+	wait(signal: AbortSignal): Promise<void> {
+		// Once input is deferred, later input must follow it at the boundary;
+		// delivering it live would reorder the user's messages.
+		if (this.deferred.length === 0) return this.#queue.wait(signal);
+		if (signal.aborted) return Promise.resolve();
+		const { promise, resolve } = Promise.withResolvers<void>();
+		signal.addEventListener("abort", () => resolve(), { once: true });
+		return promise;
+	}
+
+	async claim(signal: AbortSignal): Promise<LiveSteerClaim | undefined> {
+		if (this.deferred.length > 0 || signal.aborted) return undefined;
+		let messages: AgentMessage[];
+		try {
+			messages = await this.#queue.take(signal);
+		} catch (error) {
+			// The queue restores what it could not hand over.
+			logger.debug("Live steering dequeue failed", {
+				error: error instanceof Error ? error.message : String(error),
+			});
+			return undefined;
+		}
+		if (messages.length === 0) return undefined;
+		let providerMessages: UserMessage[] | undefined;
+		try {
+			providerMessages = await this.#queue.toProvider(messages, signal);
+		} catch (error) {
+			logger.debug("Live steering conversion failed", {
+				error: error instanceof Error ? error.message : String(error),
+			});
+		}
+		if (!providerMessages) {
+			this.deferred.push(...messages);
+			return undefined;
+		}
+		let settled = false;
+		return {
+			messages: providerMessages,
+			accept: () => {
+				if (settled) return;
+				settled = true;
+				this.accepted.push(...messages);
+			},
+			reject: () => {
+				if (settled) return;
+				settled = true;
+				this.deferred.push(...messages);
+			},
+		};
+	}
+}

package/src/output-budget.ts

@@ -0,0 +1,130 @@
+import type { Context, Model, Tool } from "@oh-my-pi/pi-ai";
+import { stopsOutputAtContextWindow } from "@oh-my-pi/pi-catalog/compat/output-limits";
+import { stringifyJson } from "@oh-my-pi/pi-utils";
+import { findRequestUsageAnchor } from "./compaction/transcript-tokens";
+import type { Tokenizer } from "./tokenizer";
+
+/** Smallest output cap {@link fitOutputTokensToContextWindow} will request. */
+export const MIN_FITTED_OUTPUT_TOKENS = 1024;
+
+/**
+ * Local counts are padded by 1/this before sizing the output cap: the
+ * provider's tokenizer can disagree with ours by a few percent, and
+ * undercounting reproduces the overflow this guards against. This is a
+ * tokenizer-error margin on locally counted text only (provider-reported
+ * usage is exact), not a context reserve; compaction's own reserve
+ * (`resolveBudgetReserveTokens`) still decides when to compact.
+ */
+const PROMPT_ESTIMATE_MARGIN_DIVISOR = 10;
+
+/**
+ * Output cap for a request, so prompt plus output stays inside the model's
+ * context window.
+ *
+ * Chat Completions-style providers (DeepSeek, OpenAI, vLLM, ...) reject a
+ * request whose prompt tokens plus `max_tokens` exceed the window. Every
+ * request asks for `model.maxTokens` of output by default, so without this a
+ * large model output cap (DeepSeek V4: ~384k of a ~1M window) makes every
+ * request fail once the prompt passes window minus output cap, long before
+ * compaction triggers, and side turns (`/btw`, recaps) have no overflow
+ * recovery at all.
+ *
+ * The prompt size is the provider's own report from the newest trustworthy
+ * assistant turn (see {@link findRequestUsageAnchor}) plus a local count of
+ * only the messages appended after it; the whole context is counted locally
+ * only when no turn can anchor (fresh or freshly rewritten context).
+ *
+ * Returns `maxTokens` unchanged when the requested cap already fits, the
+ * model declares no window, the host ends generation at the window itself
+ * instead of rejecting the request (`stops-output-at-context-window`, e.g.
+ * Claude 4.5+ on the Claude API), or nothing would be requested (including an
+ * OpenRouter-hosted model with no caller cap: the transport omits the catalog
+ * default there so each upstream self-caps, and a fitted value would turn into
+ * an explicit cap that filters upstreams). Otherwise returns
+ * the remaining room (never below {@link MIN_FITTED_OUTPUT_TOKENS}); a
+ * prompt that fills the whole window still overflows and is left to the
+ * caller's compaction. Near a full window the floor means a turn can stop on
+ * `length` instead of failing with a 400.
+ *
+ * Lives here, not next to the default in pi-ai's `mapOptionsForApi`, because
+ * pi-ai has no tokenizer; callers apply it in their `streamFn` (coding-agent
+ * does so in its shared settings-aware wrapper).
+ *
+ * Not fixed: Anthropic budget-thinking transports raise `max_tokens` back to
+ * at least the thinking budget plus a fallback buffer downstream
+ * (`ensureMaxTokensForThinking`), so a fitted cap below that is overridden
+ * and the request can still exceed the window as before.
+ */
+export function fitOutputTokensToContextWindow(
+	model: Model,
+	context: Context,
+	maxTokens: number | undefined,
+	tokenizer: Tokenizer,
+): number | undefined {
+	if (maxTokens === undefined && omitsDefaultOutputCap(model.compat)) return undefined;
+	const requested = maxTokens ?? model.maxTokens;
+	const contextWindow = model.contextWindow;
+	if (!requested || !contextWindow || contextWindow <= 0) return maxTokens;
+	if (stopsOutputAtContextWindow(model)) return maxTokens;
+
+	const room = contextWindow - countPromptTokens(context, tokenizer);
+	if (room >= requested) return maxTokens;
+	return Math.max(MIN_FITTED_OUTPUT_TOKENS, room);
+}
+
+/** OpenRouter hosts drop the catalog default cap unless the endpoint always needs one. */
+function omitsDefaultOutputCap(compat: Model["compat"] | undefined): boolean {
+	return (
+		compat !== undefined && "isOpenRouterHost" in compat && compat.isOpenRouterHost && !compat.alwaysSendMaxTokens
+	);
+}
+
+/**
+ * Framing tokens (system prompt, tool definitions) memoized per array: these
+ * are stable identities for the life of a turn, so side turns and repeat
+ * requests do not re-stringify and re-tokenize them. Length is part of the key
+ * to catch in-place growth.
+ */
+const framingCounts = new WeakMap<readonly unknown[], { tokenizer: Tokenizer; length: number; tokens: number }>();
+
+function countFraming(items: readonly unknown[] | undefined, tokenizer: Tokenizer, fragments: () => string[]): number {
+	if (!items || items.length === 0) return 0;
+	const cached = framingCounts.get(items);
+	if (cached && cached.tokenizer === tokenizer && cached.length === items.length) return cached.tokens;
+	const tokens = tokenizer.countTokens(fragments());
+	framingCounts.set(items, { tokenizer, length: items.length, tokens });
+	return tokens;
+}
+
+function toolFragments(tools: readonly Tool[]): string[] {
+	const fragments: string[] = [];
+	for (const tool of tools) fragments.push(tool.name, tool.description, stringifyJson(tool.parameters) ?? "");
+	return fragments;
+}
+
+function withMargin(localTokens: number): number {
+	return localTokens + Math.ceil(localTokens / PROMPT_ESTIMATE_MARGIN_DIVISOR);
+}
+
+/** Provider-anchored prompt size; falls back to a full local count when nothing anchors. */
+function countPromptTokens(context: Context, tokenizer: Tokenizer): number {
+	const { messages } = context;
+	const anchor = findRequestUsageAnchor(messages);
+	if (!anchor) return withMargin(countContextTokens(context, tokenizer));
+	let tail = 0;
+	for (let index = anchor.index + 1; index < messages.length; index++) {
+		tail += tokenizer.countMessage(messages[index]);
+	}
+	return anchor.tokens + withMargin(tail);
+}
+
+function countContextTokens(context: Context, tokenizer: Tokenizer): number {
+	const { systemPrompt, tools, inactiveTools } = context;
+	return (
+		countFraming(systemPrompt, tokenizer, () => [...(systemPrompt ?? [])]) +
+		countFraming(tools, tokenizer, () => toolFragments(tools ?? [])) +
+		// Anthropic replays retired tool definitions, so they are prompt too.
+		countFraming(inactiveTools, tokenizer, () => toolFragments(inactiveTools ?? [])) +
+		tokenizer.countMessages(context.messages)
+	);
+}

package/src/tool-context.ts

@@ -0,0 +1,49 @@
+import type { ToolResultMessage } from "@oh-my-pi/pi-ai";
+import type { AgentMessage } from "./types";
+
+/**
+ * Symbol-keyed carrier for passive context reported by a tool executed outside
+ * the agent loop (Cursor exec-channel dispatch). The executor attaches the
+ * joined context to the {@link ToolResultMessage} it returns; `Agent` reads it
+ * when the provider hands the result back and injects it after the buffered
+ * results. Symbol keys never serialize, so the context cannot leak into the
+ * persisted tool result.
+ */
+export const TOOL_RESULT_ADDITIONAL_CONTEXT = Symbol("tool-result-additional-context");
+
+/** A tool result optionally carrying {@link TOOL_RESULT_ADDITIONAL_CONTEXT}. */
+export type ToolResultWithAdditionalContext = ToolResultMessage & { [TOOL_RESULT_ADDITIONAL_CONTEXT]?: string };
+
+/**
+ * True for a passive-context value worth delivering: a string with at least
+ * one non-whitespace character. Shared by every producer and aggregation site
+ * so blank values never produce a developer message.
+ */
+export function isNonBlankContext(value: unknown): value is string {
+	return typeof value === "string" && value.trim().length > 0;
+}
+
+/**
+ * Join passive context values in order, dropping blanks. Returns undefined
+ * when nothing remains.
+ */
+export function joinAdditionalContext(values: Iterable<string | undefined>): string | undefined {
+	const kept: string[] = [];
+	for (const value of values) {
+		if (isNonBlankContext(value)) kept.push(value);
+	}
+	return kept.length > 0 ? kept.join("\n\n") : undefined;
+}
+
+/**
+ * Build the developer message that carries passive tool context to the next
+ * provider request. Emitted after the tool results it belongs to.
+ */
+export function createAdditionalContextMessage(text: string): AgentMessage {
+	return {
+		role: "developer",
+		content: [{ type: "text", text }],
+		attribution: "agent",
+		timestamp: Date.now(),
+	};
+}

package/src/types.ts

@@ -69,6 +69,12 @@ export interface AgentTurnEndContext {
 	message: AgentMessage;
 	/** Tool results produced by this turn, already paired with `message` in the live context. */
 	toolResults: ToolResultMessage[];
+	/**
+	 * Passive model-visible messages appended after the tool results at this
+	 * boundary. The agent loop always sends an array (possibly empty);
+	 * absent is equivalent to empty for hosts that construct the context.
+	 */
+	additionalMessages?: AgentMessage[];
 	/** True when the current tool-loop batch is continuing without yielding to post-turn steering. */
 	willContinue: boolean;
 }
@@ -344,7 +350,11 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 
 	/**
 	 * Provides tool execution context, resolved per tool call.
-	 * Use for late-bound UI or session state access.
+	 * Use for late-bound UI or session state access. The loop passes the tool
+	 * call's {@link ToolCallContext}; hosts that support passive tool context
+	 * surface its `addAdditionalContext` sink as
+	 * {@link AgentToolContext.addAdditionalContext}. The returned object is
+	 * handed to the tool as-is.
 	 */
 	getToolContext?: (toolCall?: ToolCallContext) => AgentToolContext | undefined;
 
@@ -422,6 +432,12 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 * model's text output back into canonical `toolCall` blocks.
 	 */
 	dialect?: Dialect;
+	/**
+	 * Per-call owned-dialect resolver, read once per LLM call with the model
+	 * being requested. Authoritative when set: its return value (including
+	 * `undefined` = native tool calling) replaces the static {@link dialect}.
+	 */
+	getDialect?: (model: Model) => Dialect | undefined;
 	/**
 	 * When owned (in-band) tool calling is active and the model starts
 	 * fabricating a tool result inside its own turn, control how the loop reacts:
@@ -615,6 +631,13 @@ export interface ToolCallContext {
 	 * always safe (the message injects at the next batch boundary).
 	 */
 	steeringSignal?: AbortSignal;
+	/**
+	 * Loop-owned sink for passive context reported while this call executes.
+	 * Values join the call's context at the batch boundary and are injected
+	 * after the batch's tool results, in assistant tool-call order, before the
+	 * next provider request. Blank values are ignored.
+	 */
+	addAdditionalContext?: (context: string) => void;
 }
 
 /** A single tool-call content block emitted by an assistant message. */
@@ -817,11 +840,19 @@ export interface SpeculativeToolExecutionConfig {
  * written back to the tool-call block on the assistant message, and seen by
  * history, scheduling, execution events, and `tool.execute` alike. It is
  * ignored when `block` is true.
+ *
+ * Set `additionalContext` to attach passive model-visible context to this call.
+ * Non-empty values from a tool batch are injected in assistant tool-call order
+ * after every result settles and before the next provider request. It is
+ * dropped when the call is blocked or skipped, or when its final result is an
+ * error (including an approval denial raised by the tool's own gate). Within a
+ * call it follows any context the tool reported during execution.
  */
 export interface BeforeToolCallResult {
 	block?: boolean;
 	reason?: string;
 	args?: Record<string, unknown>;
+	additionalContext?: string;
 }
 
 /**
@@ -989,6 +1020,16 @@ export type ToolApproval = ToolApprovalDecision | ((args: unknown) => ToolApprov
  * Apps can extend via declaration merging.
  */
 export interface AgentToolContext {
+	/**
+	 * Attach trusted, agent-authored instructions to the next provider request.
+	 * The host emits them after tool results with developer/system priority where
+	 * the selected transport supports it. Do not use this channel for raw tool
+	 * output, retrieved documents, web content, or other untrusted data; return
+	 * those through the ordinary tool result instead. Hosts populate it from
+	 * {@link ToolCallContext.addAdditionalContext} (or their own collector for
+	 * calls dispatched outside the loop); absent when the host has no sink.
+	 */
+	addAdditionalContext?(context: string): void;
 	/** Present only while the matching outer tool owns its finalized stream session. */
 	[SPECULATIVE_STREAM_SESSION]?: ToolSpeculationStreamSession;
 }