@linxiraos/pi-agent-core 1.1.20 → 1.1.22

package/src/tokenizer.ts

@@ -1,8 +1,9 @@
 import type { Model } from "@linxiraos/pi-ai";
 import type { ModelTokenizer } from "@linxiraos/pi-catalog/types";
 import * as natives from "@linxiraos/pi-natives";
+import { materializeString, stringifyJson } from "@linxiraos/pi-utils";
+import { LRUCache } from "@linxiraos/pi-utils/lru";
 import * as snapcompact from "@linxiraos/pi-snapcompact";
-import { stringifyJson } from "@linxiraos/pi-utils";
 import { isEstimateCacheable, messageEstimateVersion } from "./compaction/message-cache";
 import type { AgentMessage } from "./types";
 
@@ -67,13 +68,43 @@ interface NativeTokenCount {
 	exact: boolean;
 }
 
+// Growing streamed text and large tool results must not evict the reusable
+// short fragments. Account for UTF-16 key storage plus a per-entry allowance.
+const NATIVE_CACHE_MAX_LENGTH = 16 * 1024;
+
+function countNativeFragment(
+	text: string,
+	encoding: natives.Encoding | null | undefined,
+	counts: LRUCache<string, number>,
+): number {
+	if (text.length > NATIVE_CACHE_MAX_LENGTH) return natives.countTokens(text, encoding);
+	const cached = counts.get(text);
+	if (cached !== undefined) return cached;
+	const tokens = natives.countTokens(text, encoding);
+	// Detach sliced strings so a small key cannot retain a much larger source.
+	counts.set(materializeString(text), tokens);
+	return tokens;
+}
+
 function countTokensNat(
 	text: string | string[],
 	encoding: natives.Encoding | null | undefined,
 	mode: TokenCountMode,
+	counts: LRUCache<string, number>,
 ): NativeTokenCount {
 	try {
-		return { tokens: natives.countTokens(text, encoding), exact: true };
+		let tokens: number;
+		if (typeof text === "string") {
+			tokens = countNativeFragment(text, encoding, counts);
+		} else if (text.length > 0 && text.length < 16) {
+			// The native API sums independent fragments, not their concatenation.
+			// Keep its parallel batch path for arrays of 16 or more fragments.
+			tokens = 0;
+			for (const fragment of text) tokens += countNativeFragment(fragment, encoding, counts);
+		} else {
+			tokens = natives.countTokens(text, encoding);
+		}
+		return { tokens, exact: true };
 	} catch (error) {
 		if (
 			!(error instanceof Error) ||
@@ -131,6 +162,13 @@ interface MessageEstimate {
 export class Tokenizer {
 	readonly #encoding: natives.Encoding | null;
 
+	/** Exact counts only; byte fallbacks remain mode-dependent and uncached. */
+	readonly #nativeCounts = new LRUCache<string, number>({
+		max: 256,
+		maxSize: 512 * 1024,
+		sizeCalculation: (_tokens, text) => text.length * 2 + 64,
+	});
+
 	/**
 	 * Per-message estimate memo. Keyed by message identity, deliberately not a
 	 * symbol-tagged property: callers spread messages to derive throwaway
@@ -150,9 +188,10 @@ export class Tokenizer {
 	}
 
 	countTokens(text: string | string[], mode: TokenCountMode = "approximate"): number {
-		if (mode === "strict") return countTokensNat(text, this.#encoding, mode).tokens;
-		if (!testEnv && this.#encoding !== null) return countTokensNat(text, this.#encoding, mode).tokens;
-		if (accurate) return countTokensNat(text, undefined, mode).tokens;
+		if (mode === "strict") return countTokensNat(text, this.#encoding, mode, this.#nativeCounts).tokens;
+		if (!testEnv && this.#encoding !== null)
+			return countTokensNat(text, this.#encoding, mode, this.#nativeCounts).tokens;
+		if (accurate) return countTokensNat(text, undefined, mode, this.#nativeCounts).tokens;
 		return sumFragments(text, mode === "upperbound" ? byteLength : byteEstimate);
 	}
 
@@ -170,7 +209,7 @@ export class Tokenizer {
 	checkTokenBudget(text: string | string[], budget: number): TokenBudgetCheck {
 		const bound = sumFragments(text, byteLength);
 		if (bound <= budget) return { fits: true, tokens: bound, exact: false };
-		const result = countTokensNat(text, this.#encoding, "strict");
+		const result = countTokensNat(text, this.#encoding, "strict", this.#nativeCounts);
 		return { fits: result.tokens <= budget, tokens: result.tokens, exact: result.exact };
 	}
 

package/src/tool-context.ts

@@ -0,0 +1,55 @@
+import type { ToolResultMessage } from "@linxiraos/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 and repeats of an
+ * earlier value (compared without surrounding whitespace; the first original
+ * is kept). Returns undefined when nothing remains.
+ */
+export function joinAdditionalContext(values: Iterable<string | undefined>): string | undefined {
+	const seen = new Set<string>();
+	const kept: string[] = [];
+	for (const value of values) {
+		if (!isNonBlankContext(value)) continue;
+		const key = value.trim();
+		if (seen.has(key)) continue;
+		seen.add(key);
+		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

@@ -24,6 +24,7 @@ import type { Dialect } from "@linxiraos/pi-ai/dialect";
 import type { HarmonyAuditEvent } from "@linxiraos/pi-ai/utils/harmony-leak";
 import type { AppendOnlyContextManager } from "./append-only-context";
 import type { AgentRunCoverage, AgentRunSummary } from "./run-collector";
+import type { SentToolDefinitions } from "./sent-tool-definitions";
 import type { AgentTelemetryConfig } from "./telemetry";
 
 /** Stream function - can return sync or Promise for async config lookup */
@@ -68,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;
 }
@@ -163,8 +170,10 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 
 	/**
 	 * When to interrupt tool execution for steering messages.
-	 * - "immediate" = check after each tool call (default)
-	 * - "wait" = defer steering until the current turn completes
+	 * - "immediate" = cut interruptible waits short and raise the cooperative
+	 *   `steeringSignal` for other running tools (default)
+	 * - "wait" = let non-interruptible tools finish undisturbed; interruptible
+	 *   waits are still cut short, since they have no work to complete
 	 */
 	interruptMode?: "immediate" | "wait";
 
@@ -238,6 +247,9 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 */
 	transformProviderContext?: (context: Context, model: Model) => Context | Promise<Context>;
 
+	/** Remembers sent tool definitions to fill {@link Context.inactiveTools}. */
+	sentToolDefinitions?: SentToolDefinitions;
+
 	/**
 	 * Resolves the API key or resolver for the current model before each LLM call.
 	 *
@@ -259,8 +271,9 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	/**
 	 * Peeks whether steering messages are queued, without consuming them.
 	 *
-	 * Polled while a tool batch runs (unless interruptMode is "wait") to decide
-	 * whether to abort in-flight and skip not-yet-started *interruptible* waits;
+	 * Polled while a tool batch runs (in "wait" mode, only when the batch holds an
+	 * interruptible tool) to decide whether to abort in-flight and skip
+	 * not-yet-started *interruptible* waits;
 	 * every other already-emitted call still executes and the message injects
 	 * at the batch boundary. The queue keeps
 	 * owning its messages until the loop reaches the next injection boundary and
@@ -285,14 +298,36 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 */
 	waitForSteeringMessages?: (signal?: AbortSignal) => Promise<void>;
 
+	/**
+	 * Called when live steering dequeues messages via {@link getSteeringMessages}
+	 * for the response being streamed. The loop records them in the transcript
+	 * after that response (or its tool batch); an abort before then leaves them
+	 * unrecorded for the host to requeue.
+	 */
+	onLiveSteeringTaken?: (messages: AgentMessage[]) => void;
+
 	/**
 	 * Peeks whether IRC messages should interrupt an interruptible waiting tool.
 	 *
 	 * Uses the same delivery rules as steering: the poll is non-consuming, only
-	 * runs for interruptible tools, and is ignored when interruptMode is "wait".
+	 * runs for interruptible tools, and cuts them short even when interruptMode
+	 * is "wait".
 	 * The host owns message injection at the next boundary.
 	 */
 	hasIrcInterrupts?: () => boolean | Promise<boolean>;
+	/**
+	 * Peeks whether a background completion (finished job, exited supervised
+	 * process) is queued for aside injection at the next boundary.
+	 *
+	 * Same rules as {@link hasIrcInterrupts}: non-consuming, only cuts
+	 * *interruptible* waits short, in either interruptMode. Without
+	 * it a completion notice sits behind an hour-long `wait` that the agent
+	 * would have abandoned had it seen the notice. Unlike a peer IRC it never
+	 * raises {@link ToolCallContext.steeringSignal}: a queued completion must
+	 * not push ordinary foreground work (auto-background bash/eval) into the
+	 * background.
+	 */
+	hasBackgroundCompletions?: () => boolean | Promise<boolean>;
 
 	/**
 	 * Returns follow-up messages to process after the agent would otherwise stop.
@@ -323,7 +358,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;
 
@@ -401,6 +440,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:
@@ -550,6 +595,14 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 */
 	transformAssistantMessage?: (message: AssistantMessage, signal?: AbortSignal) => Promise<void> | void;
 
+	/**
+	 * Declares that {@link transformAssistantMessage} never rewrites or removes a
+	 * tool call the model streamed (it may edit text or append new calls). Stream
+	 * speculation sessions and direct speculative candidates plan from streamed
+	 * calls, so they stay disabled under a transform unless this is set.
+	 */
+	transformAssistantMessagePreservesToolCalls?: boolean;
+
 	/**
 	 * Called after a tool finishes executing, before `tool_execution_end` and the
 	 * tool-result message are emitted.
@@ -594,6 +647,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. */
@@ -688,9 +748,24 @@ export interface SpeculativeExecutionHost {
 		commitDefault: () => Promise<AgentToolResult<unknown>>,
 	): Promise<SpeculativeCommitDecision>;
 	discard?(context: SpeculativeDiscardContext): void | Promise<void>;
+	/**
+	 * Authorize a stream session to start effectful work (e.g. subagents) from
+	 * partially streamed arguments. The session owns that work and must abort it
+	 * when the finalized call is invalid, blocked, or changed. Hosts without this
+	 * hook deny every launch.
+	 */
+	authorizeLaunch?(context: SpeculativeLaunchContext): SpeculativeAuthorization | Promise<SpeculativeAuthorization>;
 	close?(reason: string): void | Promise<void>;
 }
 
+/** Effectful work a tool-owned stream session asks to start before its outer call dispatches. */
+export interface SpeculativeLaunchContext {
+	tool: SpeculativeToolReference;
+	toolCall: AgentToolCall;
+	/** Arguments the launch was planned from: the streamed prefix of the outer call. */
+	args: Readonly<Record<string, unknown>>;
+}
+
 export interface ToolSpeculationStreamContext {
 	readonly coordinator: SpeculativeOperationSink;
 	readonly parentToolCallId: string;
@@ -737,6 +812,8 @@ export interface ToolSpeculationStreamSession {
 export interface SpeculativeOperationSink {
 	readonly maxInFlight: number;
 	admit(definition: SpeculativeChildDefinition): Promise<SpeculativeChildHandle | undefined>;
+	/** Host-gated permission for effectful stream work; see {@link SpeculativeExecutionHost.authorizeLaunch}. */
+	authorizeLaunch?(context: SpeculativeLaunchContext): Promise<SpeculativeAuthorization>;
 	discardChildren?(parentToolCallId: string, reason: string): void | Promise<void>;
 	close(reason: string): void | Promise<void>;
 }
@@ -796,11 +873,20 @@ 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,
+ * a value identical to an earlier one in the batch only once,
+ * 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;
 }
 
 /**
@@ -968,6 +1054,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;
 }
@@ -1021,6 +1117,12 @@ export interface AgentTool<
 	loadMode?: ToolLoadMode;
 	/** Short one-line summary used for tool discovery indexes. */
 	summary?: string;
+	/**
+	 * On-demand documentation topics (`topic → markdown`), readable as
+	 * `xd://<tool>/<topic>`. Lets a tool keep large sub-surfaces out of its
+	 * description and advertise only a one-line pointer per topic.
+	 */
+	docTopics?(): Readonly<Record<string, string>>;
 	/**
 	 * Concurrency mode for tool scheduling when multiple calls are in one turn.
 	 * - "shared": can run alongside other shared tools (default)
@@ -1045,7 +1147,7 @@ export interface AgentTool<
 	 * cleanly (e.g. `job` poll), so the abort surfaces the tool's current
 	 * snapshot rather than corrupting a side effect. Every other call runs to
 	 * completion even when steering is queued; the message lands at the next
-	 * batch boundary. Honored only when `interruptMode` is "immediate".
+	 * batch boundary. Honored in both `interruptMode`s.
 	 */
 	interruptible?: boolean | ((args: Partial<Static<TParameters>>) => boolean);
 	/**