@oh-my-pi/pi-agent-core 18.1.18 → 18.1.20

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [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

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/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.18",
+	"version": "18.1.20",
 	"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.18",
-		"@oh-my-pi/pi-catalog": "18.1.18",
-		"@oh-my-pi/pi-natives": "18.1.18",
-		"@oh-my-pi/pi-utils": "18.1.18",
-		"@oh-my-pi/pi-wire": "18.1.18",
-		"@oh-my-pi/snapcompact": "18.1.18",
+		"@oh-my-pi/pi-ai": "18.1.20",
+		"@oh-my-pi/pi-catalog": "18.1.20",
+		"@oh-my-pi/pi-natives": "18.1.20",
+		"@oh-my-pi/pi-utils": "18.1.20",
+		"@oh-my-pi/pi-wire": "18.1.20",
+		"@oh-my-pi/snapcompact": "18.1.20",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {
-		"@oh-my-pi/omptype": "18.1.18",
+		"@oh-my-pi/omptype": "18.1.20",
 		"@opentelemetry/context-async-hooks": "^2.9.0",
 		"@opentelemetry/sdk-trace-base": "^2.9.0",
 		"@types/bun": "^1.3.14"