@linxiraos/pi-agent-core 1.1.20 → 1.1.23

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 "@linxiraos/pi-ai";
+import { logger } from "@linxiraos/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,142 @@
+import type { Context, Model, Tool } from "@linxiraos/pi-ai";
+import { stopsOutputAtContextWindow } from "@linxiraos/pi-catalog/compat/output-limits";
+import { stringifyJson } from "@linxiraos/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;
+
+/**
+ * Absolute headway subtracted from the remaining room (unconditionally, on anchored and
+ * fully-local counts alike). Proportional padding covers
+ * tokenizer drift that scales with the prompt, but a host can still count a few tokens more
+ * than any local estimate can see (chat-template framing, reasoning wrappers). Measured
+ * against a 262,144-token host: fitted caps landed +11 to +42 tokens over and were rejected
+ * with 400s. 64 tokens covers the observed drift with margin to spare; the
+ * {@link MIN_FITTED_OUTPUT_TOKENS} floor still applies.
+ */
+export const OUTPUT_FIT_HEADWAY_TOKENS = 64;
+
+/**
+ * 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 minus {@link OUTPUT_FIT_HEADWAY_TOKENS} (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) - OUTPUT_FIT_HEADWAY_TOKENS;
+	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/sent-tool-definitions.ts

@@ -0,0 +1,40 @@
+import type { Message, Tool } from "@linxiraos/pi-ai";
+
+/**
+ * Last wire definition this Agent sent for each tool name, so a provider that keeps
+ * withdrawn tools declared (Anthropic `tool_removal`) can re-declare them byte-identically.
+ * Used by prepareProviderCall and Agent.buildSideRequestContext.
+ */
+export class SentToolDefinitions {
+	#byName = new Map<string, Tool>();
+
+	/** Remember the definitions a request is about to send. */
+	record(tools: readonly Tool[]): void {
+		for (const tool of tools) this.#byName.set(tool.name, tool);
+	}
+
+	/**
+	 * Definitions for names the latest `requestControls.tools.declared` in `messages` holds
+	 * that are not in `active`; undefined when none. Names never sent by this Agent are
+	 * skipped: the provider drops them from the declaration.
+	 */
+	inactiveFor(messages: readonly Message[], active: readonly Tool[]): Tool[] | undefined {
+		let declared: readonly string[] | undefined;
+		for (let index = messages.length - 1; index >= 0; index--) {
+			const message = messages[index];
+			if (message?.role === "assistant" && message.requestControls?.tools) {
+				declared = message.requestControls.tools.declared;
+				break;
+			}
+		}
+		if (!declared) return undefined;
+		const activeNames = new Set(active.map(tool => tool.name));
+		const inactive: Tool[] = [];
+		for (const name of declared) {
+			if (activeNames.has(name)) continue;
+			const tool = this.#byName.get(name);
+			if (tool) inactive.push(tool);
+		}
+		return inactive.length > 0 ? inactive : undefined;
+	}
+}

package/src/speculative-execution.ts

@@ -10,6 +10,7 @@ import type {
 	SpeculativeChildDefinition,
 	SpeculativeChildHandle,
 	SpeculativeCommitContext,
+	SpeculativeLaunchContext,
 	SpeculativeOperationContext,
 	SpeculativePhysicalOutcome,
 	SpeculativeResourceAccess,
@@ -520,6 +521,17 @@ export class SpeculativeOperationCoordinator {
 		}
 	}
 
+	async authorizeLaunch(context: SpeculativeLaunchContext): Promise<SpeculativeAuthorization> {
+		if (this.#closed) return { allowed: false, reason: "speculation coordinator is closed" };
+		const authorize = this.config.host?.authorizeLaunch;
+		if (!authorize) return { allowed: false, reason: "host does not authorize speculative launches" };
+		try {
+			return await authorize.call(this.config.host, context);
+		} catch {
+			return { allowed: false, reason: "host launch authorization failed" };
+		}
+	}
+
 	async discardChildren(parentToolCallId: string, reason: string): Promise<void> {
 		await this.#admission;
 		await Promise.all(