@oh-my-pi/pi-agent-core 18.1.17 → 18.1.19

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## [Unreleased]
 
+## [18.1.19] - 2026-09-12
+
+### Added
+
+- Added `Agent.getPendingToolResults()` for reconstructing live displays before buffered tool results are persisted ([#11868](https://github.com/can1357/oh-my-pi/pull/11868) by [@serverinspector](https://github.com/serverinspector)).
+- Added opt-in host authorization and exact-once streamed child execution for discard-safe local reads.
+
+### Changed
+
+- `Tool <name> not found` now also suggests mounted `xd://` devices, not just the advertised tool set, via the new `suggestFallbackToolNames` option ([#11516](https://github.com/can1357/oh-my-pi/issues/11516), [#10109](https://github.com/can1357/oh-my-pi/issues/10109) by [@oldschoola](https://github.com/oldschoola)).
+
+### Fixed
+
+- Speculative stream sessions are now discarded when a hook or argument transform replaces a call's arguments while keeping its ID, instead of releasing deferred work planned from the original code ([#11889](https://github.com/can1357/oh-my-pi/pull/11889) by [@h4vc](https://github.com/h4vc)).
+
+## [18.1.18] - 2026-09-11
+
+### Added
+
+- Anthropic server-side compaction as a `remote` compaction backend: model lines the beta supports (`compat.supportsServerCompaction`, rule-owned in the catalog: Opus 4.6+, Sonnet 4.6+, Fable/Mythos 5) on the official endpoint, resolved the way the provider routes requests, plus Anthropic-compatible routes with `remoteCompaction.enabled`, compact by re-issuing the live turn's own request — same system prompt, tools, and history, so it reads the prompt cache the last turn wrote — with the `compact_20260112` edit paused after the summary and the harness summary prompt as `instructions`. The instructions name where the retained tail begins so the summary covers only the history the rebuilt context drops. The API's summary is stored as the entry text and as `preserveData.anthropicCompaction`, replayed natively on later Anthropic requests and read as plain text by every other provider; the retained tail comes from session entries as with a local summary. Contexts below 55k tokens (the API trigger floor plus margin) keep summarizing locally, and a response without a summary is a native failure, like the OpenAI lanes. An aborted compaction response is the abort (a cancellation, never a native failure) and an error response keeps its HTTP status, so auth and timeout classification match the OpenAI lanes; the block's opaque `encrypted_content` is persisted as `preserveData.anthropicCompaction.encryptedContent` and replayed verbatim.
+
+### Fixed
+
+- `compact()` now forwards the caller's `oneshotRetry` opt-out to every summarization oneshot; auto-compaction's outer retry loop no longer multiplies with the inner transient-failure retries.
+
 ## [18.1.17] - 2026-09-10
 
 ### Changed

package/dist/types/agent.d.ts

@@ -1,9 +1,9 @@
-import { type ApiKey, type AssistantMessage, type AssistantMessageEvent, type Context, type CursorExecHandlers, type CursorToolResultHandler, type Effort, type ImageContent, type Message, type Model, type ProviderSessionState, type ServiceTier, type SimpleStreamOptions, type ThinkingBudgets, type ToolChoice } from "@oh-my-pi/pi-ai";
+import { type ApiKey, type AssistantMessage, type AssistantMessageEvent, type Context, type CursorExecHandlers, type CursorToolResultHandler, type Effort, type ImageContent, type Message, type Model, type ProviderSessionState, type ServiceTier, type SimpleStreamOptions, type ThinkingBudgets, type ToolChoice, type ToolResultMessage } from "@oh-my-pi/pi-ai";
 import type { Dialect } from "@oh-my-pi/pi-ai/dialect";
 import type { HarmonyAuditEvent } from "@oh-my-pi/pi-ai/utils/harmony-leak";
 import type { AppendOnlyContextManager } from "./append-only-context.js";
 import { Tokenizer } from "./tokenizer.js";
-import type { AgentBeforeModelCall, AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, AgentToolContext, AgentTurnEndContext, AsideMessage, StreamFn, ToolCallContext, ToolChoiceDirective } from "./types.js";
+import type { AgentBeforeModelCall, AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, AgentToolContext, AgentTurnEndContext, AsideMessage, SpeculativeToolExecutionConfig, StreamFn, ToolCallContext, ToolChoiceDirective } from "./types.js";
 export declare class AgentBusyError extends Error {
     constructor(message?: string);
 }
@@ -135,12 +135,20 @@ export interface AgentOptions {
      * Use for deobfuscating secrets or rewriting arguments.
      */
     transformToolCallArguments?: (args: Record<string, unknown>, toolName: string) => Record<string, unknown>;
+    /** Host authorization and telemetry for opt-in speculative tool execution. */
+    speculativeToolExecution?: SpeculativeToolExecutionConfig;
     /**
      * Resolve a tool call whose name matched no advertised tool. Lets hosts
      * route calls to tools exposed through side transports (e.g. `xd://`
      * device mounts) instead of failing with "Tool not found".
      */
-    resolveFallbackTool?: (name: string) => AgentTool<any> | undefined;
+    resolveFallbackTool?: (name: string, advertised: readonly AgentTool<any>[]) => AgentTool<any> | undefined;
+    /**
+     * Names routable by {@link resolveFallbackTool} that the advertised set
+     * omits (e.g. `xd://` device mounts), used only to suggest a target when a
+     * call misses.
+     */
+    suggestFallbackToolNames?: () => Iterable<string>;
     /** Enable intent tracing schema injection/stripping in the harness. */
     intentTracing?: boolean;
     /**
@@ -449,6 +457,8 @@ export declare class Agent {
     /** Non-consuming view of the pending follow-up queue. See
      *  {@link peekSteeringQueue}. */
     peekFollowUpQueue(): readonly AgentMessage[];
+    /** Nonblocking snapshot of the latest results, including provisional payloads while transforms are pending. */
+    getPendingToolResults(): readonly ToolResultMessage[];
     get isAborting(): boolean;
     /**
      * Remove and return the last steering message from the queue (LIFO).

package/dist/types/compaction/anthropic.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Anthropic server-side compaction (`compact-2026-01-12` beta).
+ *
+ * The compaction request is the live turn's own request shape — same system
+ * prompt, tools, and message history — plus the `compact_20260112` edit with
+ * `pause_after_compaction`. The API summarizes the prompt from the already
+ * cached prefix and stops; the summary arrives as a `compaction` block that
+ * the provider surfaces as an `anthropicCompaction` payload. The summary is
+ * plain text, so it doubles as the compaction entry's readable summary for
+ * every other provider, while the Anthropic provider replays it as a native
+ * block (the API drops everything that precedes it). The retained tail after
+ * the cut point is replayed from session entries exactly like a local summary.
+ */
+import type { AnthropicCompactionPayload, ApiKey, Effort, Message, Model, SimpleStreamOptions, Tool, Usage } from "@oh-my-pi/pi-ai";
+import { type InstrumentedChatSpanOptions } from "../telemetry.js";
+export declare const ANTHROPIC_COMPACTION_PRESERVE_KEY = "anthropicCompaction";
+/** The API rejects a `compact_20260112` trigger below this many input tokens. */
+export declare const ANTHROPIC_COMPACTION_MIN_TRIGGER_TOKENS = 50000;
+/**
+ * Smallest context the native lane accepts. The trigger sits at the API
+ * floor, so a prompt that lands below it is answered instead of compacted;
+ * the margin over the floor absorbs the difference between the last reported
+ * context size and the compaction request's own input.
+ */
+export declare const ANTHROPIC_COMPACTION_MIN_CONTEXT_TOKENS = 55000;
+/** Summary persisted under {@link ANTHROPIC_COMPACTION_PRESERVE_KEY}. */
+export interface AnthropicCompactionPreserveData {
+    provider: string;
+    content: string;
+    /** Opaque provider state the API attached to the block; replayed verbatim. */
+    encryptedContent?: string;
+    /** Harness file metadata (`<files>` section) replayed after the native block. */
+    filesText?: string;
+    /** Model that wrote the summary. */
+    model?: string;
+    /** Prompt tokens the compaction request processed, for display. */
+    usedTokens?: number;
+}
+/**
+ * Whether a model compacts through the Anthropic compaction beta. Model
+ * eligibility is catalog policy (`compat.supportsServerCompaction`, the
+ * lineage the beta documents); endpoint eligibility is resolved the way the
+ * provider routes requests, so a Foundry or `ANTHROPIC_BASE_URL` reroute of a
+ * first-party model is excluded unless the route opted in with
+ * `remoteCompaction.enabled`.
+ */
+export declare function shouldUseAnthropicNativeCompaction(model: Model): model is Model<"anthropic-messages">;
+export declare function getPreservedAnthropicCompactionData(preserveData: Record<string, unknown> | undefined): AnthropicCompactionPreserveData | undefined;
+/** Set or strip the Anthropic compaction slot; a new compaction never inherits a stale summary. */
+export declare function withAnthropicCompactionPreserveData(preserveData: Record<string, unknown> | undefined, compaction: AnthropicCompactionPreserveData | undefined): Record<string, unknown> | undefined;
+/** Replay payload for a compaction summary the active model produced natively. */
+export declare function getAnthropicCompactionPayload(preserveData: Record<string, unknown> | undefined): AnthropicCompactionPayload | undefined;
+/**
+ * The retained tail as the model will see it, for the summarization
+ * instructions: how many of the conversation's final wire messages stay in
+ * context verbatim, and the role of the first. The compaction request carries
+ * the whole conversation so the prompt cache the live turn wrote is read, but
+ * the summary must cover only the history before that tail — the local
+ * summarizer never sees the tail, and the rebuilt context replays it after the
+ * summary. Counting mirrors the provider's message conversion (consecutive
+ * tool results collapse into one user message; developer messages are user
+ * messages). Structured for the prompt template, which renders the
+ * singular/plural wording; the description quotes no content: quoting the
+ * tail would hand the summarizer the very facts it must leave to the tail.
+ */
+export interface RetainedTailScope {
+    count: number;
+    role: "assistant" | "user";
+}
+export declare function describeRetainedTail(messages: readonly Message[]): RetainedTailScope | undefined;
+/**
+ * Summarization prompt sent as the edit's `instructions`, which replace the
+ * API default entirely. The template lays out the retained-tail boundary
+ * first, so the summary covers only the history the rebuilt context drops,
+ * then the caller's extra context, the same structure prompt as the local
+ * summarizer, the caller's focus, and the tool-abstention clause the API
+ * recommends when tools are defined (a summarization pass that calls a tool
+ * yields no summary).
+ */
+export declare function buildAnthropicCompactionInstructions(basePrompt: string, customInstructions: string | undefined, extraContext: string | undefined, retainedTail: RetainedTailScope | undefined): string;
+export interface AnthropicNativeCompactionRequest {
+    systemPrompt: string[];
+    messages: Message[];
+    tools?: Tool[];
+    instructions: string;
+    maxTokens: number;
+    reasoning?: Effort;
+}
+export interface AnthropicNativeCompactionResponse {
+    content: string;
+    encryptedContent?: string;
+    usage: Usage;
+    model: string;
+}
+export interface AnthropicNativeCompactionOptions extends Pick<SimpleStreamOptions, "initiatorOverride" | "metadata" | "fetch" | "sessionId" | "promptCacheKey" | "providerSessionState" | "maxInFlightRequests">, Pick<InstrumentedChatSpanOptions, "completeImpl" | "telemetry" | "retry"> {
+}
+/**
+ * Run one compaction request and return the summary the API wrote, with the
+ * opaque `encrypted_content` the API attached for the replay. `completeSimple`
+ * resolves terminal failures as messages, so their classification is restored
+ * here: an aborted response is an `AbortError` (a cancellation, never a native
+ * failure) and an error response keeps its HTTP status, so auth and timeout
+ * handling downstream classify it the same way as the OpenAI lanes. A response
+ * without a summary is a native failure — the API answers the prompt instead
+ * when its input never reached the trigger, and returns an empty block when
+ * the model called a tool during summarization.
+ */
+export declare function requestAnthropicNativeCompaction(model: Model<"anthropic-messages">, apiKey: ApiKey, request: AnthropicNativeCompactionRequest, signal: AbortSignal | undefined, options: AnthropicNativeCompactionOptions): Promise<AnthropicNativeCompactionResponse>;

package/dist/types/compaction/compaction.d.ts

@@ -65,7 +65,11 @@ export declare const DEFAULT_RESERVE_TOKENS = 16384;
  */
 export declare const MAX_SUMMARY_TOKENS = 16384;
 export declare const DEFAULT_COMPACTION_SETTINGS: CompactionSettings;
-/** Whether a compaction candidate preserves provider-native transport under the effective settings. */
+/**
+ * Whether a compaction candidate preserves provider-native transport under the
+ * effective settings: an OpenAI Responses compact route (V1 or streamed V2) or
+ * the Anthropic compaction beta.
+ */
 export declare function shouldUseProviderNativeCompaction(model: Model, settings: Pick<CompactionSettings, "remoteEnabled" | "remoteStreamingV2Enabled">): boolean;
 /**
  * Calculate total context tokens from usage.
@@ -290,6 +294,8 @@ export interface CompactionPreparation {
     tokensBefore: number;
     /** Summary from previous compaction, for iterative update */
     previousSummary?: string;
+    /** ISO timestamp of the previous compaction entry, for iterative update */
+    previousSummaryTimestamp?: string;
     /** Preserved opaque compaction payload from the previous compaction, if any. */
     previousPreserveData?: Record<string, unknown>;
     /** File operations extracted from messagesToSummarize */

package/dist/types/compaction/index.d.ts

@@ -1,6 +1,7 @@
 /**
  * Compaction and summarization utilities.
  */
+export * from "./anthropic.js";
 export * from "./branch-summarization.js";
 export * from "./compaction.js";
 export * from "./entries.js";

package/dist/types/index.d.ts

@@ -6,6 +6,7 @@ export * from "./pause.js";
 export * from "./proxy.js";
 export * from "./replay-policy.js";
 export * from "./run-collector.js";
+export * from "./speculative-execution.js";
 export * from "./telemetry.js";
 export * from "./thinking.js";
 export * from "./tokenizer.js";

package/dist/types/speculative-execution.d.ts

@@ -0,0 +1,63 @@
+import { type AssistantMessage } from "@oh-my-pi/pi-ai";
+import type { AgentContext, AgentLoopConfig, AgentTool, AgentToolCall, AgentToolResult, SpeculativeChildDefinition, SpeculativeChildHandle, SpeculativeToolExecutionConfig, ToolSpeculationEffect, ToolSpeculationStreamSession } from "./types.js";
+export type SpeculativeRawOutcome = {
+    result: AgentToolResult<unknown>;
+    isError: boolean;
+};
+export type CoerceToolResult = (raw: unknown) => {
+    result: AgentToolResult<unknown>;
+    malformed: boolean;
+};
+type CoordinatorEnvironment = {
+    context: AgentContext;
+    loopConfig: AgentLoopConfig;
+    signal?: AbortSignal;
+};
+/** JSON canonicalization shared by assessment and final reconciliation. */
+export declare function canonicalJson(value: unknown, ancestors?: Set<object>): string;
+export declare function createExecutionFingerprint(toolCall: AgentToolCall, executionArgs: Readonly<Record<string, unknown>>, effect: ToolSpeculationEffect): string;
+/** Rejects malformed or ambiguous effects and returns a frozen logical identity. */
+export declare function normalizeSpeculationEffect(effect: unknown): ToolSpeculationEffect | undefined;
+/** One streamed assistant response's invisible speculative-operation lifecycle. */
+export declare class SpeculativeOperationCoordinator {
+    #private;
+    readonly config: SpeculativeToolExecutionConfig;
+    readonly environment?: CoordinatorEnvironment | undefined;
+    constructor(config: SpeculativeToolExecutionConfig, environment?: CoordinatorEnvironment | undefined);
+    get maxInFlight(): number;
+    get size(): number;
+    register(_contentIndex: number): void;
+    registerStreamSession(toolCallId: string, session: ToolSpeculationStreamSession): boolean;
+    streamSession(toolCallId: string): ToolSpeculationStreamSession | undefined;
+    takeStreamSession(toolCallId: string): ToolSpeculationStreamSession | undefined;
+    discardStreamSession(toolCallId: string, reason: string): Promise<void>;
+    finalizeAdmissions(): Promise<void>;
+    attach(message: AssistantMessage): void;
+    static take(message: AssistantMessage): SpeculativeOperationCoordinator | undefined;
+    static discardForMessage(message: AssistantMessage, reason: string, outcome?: "discarded" | "aborted"): void;
+    ineligible(toolCall: AgentToolCall, reason: string, source?: "direct" | "eval_shadow", parentToolCallId?: string): false;
+    close(reason: string, outcome?: "discarded" | "aborted"): Promise<void>;
+    discardAll(reason: string, outcome?: "discarded" | "aborted"): Promise<void>;
+    /**
+     * Settles queued admissions without releasing host-deferred work. Lets
+     * final reconciliation reuse an admission-time transform result instead of
+     * running the (possibly stateful) transform a second time. Unlike
+     * `finalizeAdmissions` this never starts deferred candidates, so the
+     * `beforeToolCall` gate keeps its release semantics.
+     */
+    settleAdmissions(): Promise<void>;
+    /**
+     * Admission-time transformed args for a direct candidate whose raw call is
+     * unchanged. Returns undefined when there is no usable candidate, in which
+     * case the caller recomputes at most once via the transform. Gating on the
+     * raw call keeps `beforeToolCall` policy intact: any hook revision changes
+     * the raw args and forces a fresh transform plus re-reconciliation.
+     */
+    directExecutionArgsFor(toolCallId: string, rawArgs: Readonly<Record<string, unknown>>): Record<string, unknown> | undefined;
+    reconcileFinalCalls(calls: ReadonlyMap<string, AgentToolCall>): Promise<void>;
+    discardChildren(parentToolCallId: string, reason: string): Promise<void>;
+    claim(tool: AgentTool | undefined, toolCall: AgentToolCall, args: Record<string, unknown>): Promise<SpeculativeRawOutcome | undefined>;
+    admitFinalized(context: AgentContext, toolCall: AgentToolCall, loopConfig: AgentLoopConfig, signal: AbortSignal | undefined): void;
+    admit(definition: SpeculativeChildDefinition): Promise<SpeculativeChildHandle | undefined>;
+}
+export {};

package/dist/types/types.d.ts

@@ -8,6 +8,8 @@ import type { AgentTelemetryConfig } from "./telemetry.js";
 export type StreamFn = (...args: Parameters<typeof streamSimple>) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>;
 /** Called once an aside has been inserted into the agent's live context. */
 export declare const ASIDE_MESSAGE_COMMIT: unique symbol;
+/** Symbol-keyed handoff for one finalized, tool-owned stream speculation session. */
+export declare const SPECULATIVE_STREAM_SESSION: unique symbol;
 /** Called when an aside was drained but the agent loop ended before inserting it. */
 export declare const ASIDE_MESSAGE_DISCARD: unique symbol;
 export type CommittableAsideMessage = AgentMessage & {
@@ -281,13 +283,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, 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.
      */
-    resolveFallbackTool?: (name: string) => AgentTool<any> | undefined;
+    suggestFallbackToolNames?: () => Iterable<string>;
     /**
      * Enable intent tracing for tool calls.
      * When enabled, the harness injects a `string` field into tool schemas sent to the model,
@@ -491,6 +513,178 @@ export interface ToolCallContext {
 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`.
  *
@@ -533,7 +727,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;
@@ -653,6 +847,8 @@ export type ToolApproval = ToolApprovalDecision | ((args: unknown) => ToolApprov
  * Apps can extend via declaration merging.
  */
 export interface AgentToolContext {
+    /** 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> = (this: AgentTool<TParameters, TDetails, TTheme>, toolCallId: string, params: Static<TParameters>, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<TDetails, TParameters>, context?: AgentToolContext) => Promise<AgentToolResult<TDetails, TParameters>>;
 /** Live receiver for a tool call's streamed arguments (see AgentTool.openArgStream). */
@@ -693,6 +889,11 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any
      * - 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;
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "18.1.17",
+	"version": "18.1.19",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://omp.sh",
 	"author": "Stencil Labs, Inc.",
@@ -35,16 +35,16 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "18.1.17",
-		"@oh-my-pi/pi-catalog": "18.1.17",
-		"@oh-my-pi/pi-natives": "18.1.17",
-		"@oh-my-pi/pi-utils": "18.1.17",
-		"@oh-my-pi/pi-wire": "18.1.17",
-		"@oh-my-pi/snapcompact": "18.1.17",
+		"@oh-my-pi/pi-ai": "18.1.19",
+		"@oh-my-pi/pi-catalog": "18.1.19",
+		"@oh-my-pi/pi-natives": "18.1.19",
+		"@oh-my-pi/pi-utils": "18.1.19",
+		"@oh-my-pi/pi-wire": "18.1.19",
+		"@oh-my-pi/snapcompact": "18.1.19",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {
-		"@oh-my-pi/omptype": "18.1.17",
+		"@oh-my-pi/omptype": "18.1.19",
 		"@opentelemetry/context-async-hooks": "^2.9.0",
 		"@opentelemetry/sdk-trace-base": "^2.9.0",
 		"@types/bun": "^1.3.14"