@linxiraos/pi-agent-core 1.1.13 → 1.1.15

package/src/tokenizer.ts

@@ -219,14 +219,22 @@ export class Tokenizer {
 		}
 
 		switch (message.role) {
-			case "user": {
-				const content: string | Array<{ type: string; text?: string }> = message.content;
+			case "user":
+			case "developer": {
+				// Both roles carry `string | (TextContent | ImageContent)[]` and both are
+				// sent to the provider -- convertMessageToLlm handles developer alongside
+				// user -- so they are counted alike. Without the developer case the switch
+				// fell through to `default: return 0`, and the old annotation narrowed the
+				// blocks to text-only, hiding the image charge the toolResult arm applies.
+				const content = message.content;
 				if (typeof content === "string") {
 					fragments.push(content);
 				} else if (Array.isArray(content)) {
 					for (const block of content) {
 						if (block.type === "text" && block.text) {
 							fragments.push(block.text);
+						} else if (block.type === "image") {
+							extra += IMAGE_TOKEN_ESTIMATE;
 						}
 					}
 				}

package/src/types.ts

@@ -33,6 +33,8 @@ export type StreamFn = (
 
 /** Called once an aside has been inserted into the agent's live context. */
 export const ASIDE_MESSAGE_COMMIT = Symbol("aside-message-commit");
+/** Symbol-keyed handoff for one finalized, tool-owned stream speculation session. */
+export const SPECULATIVE_STREAM_SESSION = Symbol("speculative-stream-session");
 /** Called when an aside was drained but the agent loop ended before inserting it. */
 export const ASIDE_MESSAGE_DISCARD = Symbol("aside-message-discard");
 
@@ -338,13 +340,33 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 * Use for deobfuscating secrets or rewriting arguments.
 	 */
 	transformToolCallArguments?: (args: Record<string, unknown>, toolName: string) => Record<string, unknown>;
+	/**
+	 * Opt-in speculative execution for finalized, discard-safe tool calls.
+	 *
+	 * Candidates remain invisible until ordinary dispatch commits their result.
+	 */
+	speculativeToolExecution?: SpeculativeToolExecutionConfig;
 	/**
 	 * Resolve a tool call whose name matched no advertised tool (including
 	 * `customWireName` aliases). Lets hosts route calls to tools they expose
 	 * through side transports (e.g. `xd://` device mounts) instead of failing
 	 * with "Tool not found". Returning `undefined` keeps the failure.
+	 *
+	 * `advertised` is the very snapshot exact-name dispatch just searched — the
+	 * set offered to THIS request. A host must resolve against it rather than
+	 * its own live tool state: an MCP `tools/list_changed` mid-stream reassigns
+	 * the agent's tools, so live state can hold a roster the model never saw,
+	 * and a name-recovering host would dispatch a tool this request never
+	 * advertised while exact dispatch still answered from the snapshot.
 	 */
-	resolveFallbackTool?: (name: string) => AgentTool<any> | undefined;
+	resolveFallbackTool?: (name: string, advertised: readonly AgentTool<any>[]) => AgentTool<any> | undefined;
+	/**
+	 * Names reachable through {@link resolveFallbackTool} but absent from the
+	 * advertised set (e.g. `xd://` device mounts). Consulted only to name a
+	 * plausible target when a call misses, so a mis-transcribed device call is
+	 * recoverable; never a dispatch source.
+	 */
+	suggestFallbackToolNames?: () => Iterable<string>;
 
 	/**
 	 * Enable intent tracing for tool calls.
@@ -565,6 +587,192 @@ export interface ToolCallContext {
 /** A single tool-call content block emitted by an assistant message. */
 export type AgentToolCall = Extract<AssistantMessage["content"][number], { type: "toolCall" }>;
 
+export interface SpeculativeResourceAccess {
+	scheme: "file";
+	path: string;
+	access: "read";
+}
+
+/** Declares an operation whose early execution can be discarded without rollback. */
+export type ToolSpeculationEffect =
+	| { kind: "pure" }
+	| { kind: "local_read"; resources: readonly SpeculativeResourceAccess[] };
+
+export type ToolSpeculationAssessment =
+	| { eligible: false; reason: string }
+	| { eligible: true; effect: ToolSpeculationEffect };
+
+/** Immutable finalized call data provided to a tool-owned policy. */
+export interface ToolSpeculationAssessmentContext {
+	toolCall: AgentToolCall;
+	args: Readonly<Record<string, unknown>>;
+}
+
+export interface ToolSpeculationExecutionContext extends ToolSpeculationAssessmentContext {
+	effect: ToolSpeculationEffect;
+}
+
+export interface ToolSpeculationCommitContext extends ToolSpeculationExecutionContext {
+	physicalOutcome: SpeculativePhysicalOutcome;
+}
+
+export interface ToolSpeculationDiscardContext extends ToolSpeculationExecutionContext {
+	reason: string;
+}
+
+export interface SpeculativePhysicalOutcome {
+	kind: "result";
+	result: AgentToolResult<unknown>;
+	isError: boolean;
+	/** Opaque evidence binding the result to the local bytes actually consumed. */
+	evidence?: unknown;
+}
+
+export interface SpeculativeToolReference {
+	name: string;
+	approval?: ToolApproval;
+	formatApprovalDetails?: (args: unknown) => string | string[] | undefined;
+}
+
+export interface SpeculativeOperationContext extends ToolSpeculationExecutionContext {
+	tool: SpeculativeToolReference;
+	candidateId: string;
+	source: "direct" | "eval_shadow";
+	dependencies: readonly string[];
+}
+
+export interface SpeculativeCommitContext extends SpeculativeOperationContext {
+	physicalOutcome: SpeculativePhysicalOutcome;
+}
+
+export interface SpeculativeDiscardContext extends SpeculativeOperationContext {
+	reason: string;
+}
+
+export type SpeculativeAuthorization =
+	| { allowed: false; reason: string }
+	| { allowed: true; deferBeforeToolCall?: boolean };
+
+export type SpeculativeCommitDecision =
+	| { kind: "committed"; result: AgentToolResult<unknown> }
+	| { kind: "fallback"; reason: string }
+	| { kind: "failed"; error: unknown };
+
+export interface SpeculativeExecutionHost {
+	authorize(context: SpeculativeOperationContext): SpeculativeAuthorization | Promise<SpeculativeAuthorization>;
+	/**
+	 * Capture content evidence after admission gates pass but before the
+	 * candidate executes. The coordinator invokes this immediately before
+	 * starting speculative execution — which for hook-deferred candidates is
+	 * after `beforeToolCall` runs — so content inspection never precedes a
+	 * hook that may block the call. Return false (or throw) to veto the
+	 * candidate without executing it. Hosts without this hook keep the legacy
+	 * behavior of capturing during `authorize`.
+	 */
+	captureEvidence?(context: SpeculativeOperationContext): boolean | Promise<boolean>;
+	validate?(context: SpeculativeCommitContext): boolean | Promise<boolean>;
+	commit?(
+		context: SpeculativeCommitContext,
+		commitDefault: () => Promise<AgentToolResult<unknown>>,
+	): Promise<SpeculativeCommitDecision>;
+	discard?(context: SpeculativeDiscardContext): void | Promise<void>;
+	close?(reason: string): void | Promise<void>;
+}
+
+export interface ToolSpeculationStreamContext {
+	readonly coordinator: SpeculativeOperationSink;
+	readonly parentToolCallId: string;
+}
+
+/** One dependency-aware child operation projected by a streamed outer tool. */
+export interface SpeculativeChildDefinition {
+	candidateId: string;
+	parentToolCallId: string;
+	dependencies: readonly string[];
+	toolCall: AgentToolCall;
+	tool: AgentTool;
+	source: "eval_shadow";
+	virtualDurationMs?: number;
+}
+
+/** Opaque ownership handle returned after agent-core validates and authorizes a child. */
+export interface SpeculativeChildHandle {
+	readonly candidateId: string;
+	readonly fingerprint: string;
+	readonly effect: ToolSpeculationEffect;
+	readonly outcome: Promise<SpeculativePhysicalOutcome>;
+	commit(actualArgs: Readonly<Record<string, unknown>>): Promise<AgentToolResult<unknown> | undefined>;
+	discard(reason: string): Promise<void>;
+}
+
+export interface ToolSpeculationStreamSession {
+	/** True when the tool owns claim routing and does not need an AgentToolContext attachment. */
+	readonly contextIndependent?: boolean;
+	update(toolCall: AgentToolCall, partialJson?: string): void | Promise<void>;
+	finalize(context: ToolSpeculationAssessmentContext): void | Promise<void>;
+	commit(): void | Promise<void>;
+	discard(reason: string): void | Promise<void>;
+	/**
+	 * Whether the session's streamed plan still authorizes these final
+	 * arguments. The coordinator discards the session when the finalized call
+	 * kept its ID but a hook or argument transform replaced its arguments:
+	 * deferred work planned from the original code must never release.
+	 * Sessions without this predicate are always retained.
+	 */
+	matchesFinalArgs?(args: Readonly<Record<string, unknown>>): boolean;
+}
+
+export interface SpeculativeOperationSink {
+	readonly maxInFlight: number;
+	admit(definition: SpeculativeChildDefinition): Promise<SpeculativeChildHandle | undefined>;
+	discardChildren?(parentToolCallId: string, reason: string): void | Promise<void>;
+	close(reason: string): void | Promise<void>;
+}
+
+export interface ToolSpeculationPolicy {
+	finalized?: {
+		assess(context: ToolSpeculationAssessmentContext): ToolSpeculationAssessment | Promise<ToolSpeculationAssessment>;
+		execute(context: ToolSpeculationExecutionContext, signal: AbortSignal): Promise<SpeculativePhysicalOutcome>;
+		commit?(
+			context: ToolSpeculationCommitContext,
+			outcome: SpeculativePhysicalOutcome,
+		): Promise<AgentToolResult<unknown>>;
+		discard?(context: ToolSpeculationDiscardContext): void | Promise<void>;
+	};
+	stream?: {
+		open(
+			context: ToolSpeculationStreamContext,
+		): ToolSpeculationStreamSession | Promise<ToolSpeculationStreamSession | undefined>;
+	};
+}
+
+/** Diagnostic information for one speculative operation. */
+export interface SpeculativeToolTelemetry {
+	source: "direct" | "eval_shadow";
+	candidateId: string;
+	parentToolCallId?: string;
+	toolName: string;
+	effectKind?: ToolSpeculationEffect["kind"];
+	candidateStartedAt?: number;
+	candidateFinishedAt?: number;
+	dispatchReachedAt?: number;
+	dependencyCount: number;
+	queueMs?: number;
+	executionDurationMs?: number;
+	overlapMs?: number;
+	outcome: "committed" | "discarded" | "ineligible" | "fingerprint_mismatch" | "aborted" | "commit_conflict";
+	reason?: string;
+	resourceCount: number;
+}
+
+/** Opt-in configuration for discard-safe speculative tool execution. */
+export interface SpeculativeToolExecutionConfig {
+	enabled: boolean;
+	maxInFlight?: number;
+	host?: SpeculativeExecutionHost;
+	onTelemetry?: (event: SpeculativeToolTelemetry) => void;
+}
+
 /**
  * Result returned from `beforeToolCall`.
  *
@@ -609,7 +817,7 @@ export interface BeforeToolCallContext {
 	/** The raw tool call block from `assistantMessage.content`. */
 	toolCall: AgentToolCall;
 	/** The resolved tool the call dispatches to. */
-	tool: AgentTool<any>;
+	tool: AgentTool;
 	/**
 	 * Validated tool arguments. The same reference is forwarded to `tool.execute`
 	 * (after any `transformToolCallArguments` pass), so in-place mutations stick;
@@ -748,7 +956,8 @@ export type ToolApproval = ToolApprovalDecision | ((args: unknown) => ToolApprov
  * Apps can extend via declaration merging.
  */
 export interface AgentToolContext {
-	// Empty by default - apps extend via declaration merging
+	/** Present only while the matching outer tool owns its finalized stream session. */
+	[SPECULATIVE_STREAM_SESSION]?: ToolSpeculationStreamSession;
 }
 
 export type AgentToolExecFn<TParameters extends TSchema = TSchema, TDetails = any, TTheme = unknown> = (
@@ -806,6 +1015,12 @@ export interface AgentTool<
 	 * - function: resolved per call from the (raw, pre-validation) arguments
 	 */
 	concurrency?: "shared" | "exclusive" | ((args: Partial<Static<TParameters>>) => "shared" | "exclusive");
+
+	/**
+	 * Declares the bounded, validated effect of a finalized call that may execute
+	 * before ordinary dispatch commits its result.
+	 */
+	speculation?: ToolSpeculationPolicy;
 	/** If true, argument validation errors are non-fatal: raw args are passed to execute() instead of returning an error to the LLM. */
 	lenientArgValidation?: boolean;
 	/**