@linxiraos/pi-agent-core 1.1.14 → 1.1.16

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

@@ -14,19 +14,19 @@
  *   summarization endpoints that accept `{ systemPrompt, prompt }` and reply
  *   with `{ summary, shortSummary? }`.
  */
-import type { CodexCompactionContext, FetchImpl, Message, Model, ProviderSessionState } from "@linxiraos/pi-ai/types";
+import type { Api, CodexCompactionContext, FetchImpl, Message, Model, ProviderSessionState } from "@linxiraos/pi-ai/types";
 import { Tokenizer } from "../tokenizer.js";
 export * from "./compaction-v2-streaming.js";
 export declare const OPENAI_REMOTE_COMPACTION_PRESERVE_KEY = "openaiRemoteCompaction";
 /**
- * Hard ceiling on remote compaction HTTP requests. Unlike every provider
- * stream (guarded by first-event/idle watchdogs in pi-ai), these are raw
- * fetches awaiting one non-streamed JSON body — a connection silently dropped
- * by a middlebox would otherwise hang the whole compaction pipeline forever
- * (frozen "Auto context-full maintenance…" spinner, manual /compact queueing
- * behind it). On timeout the caller falls back to local summarization.
+ * Hard ceiling on remote compaction HTTP requests (5 minutes). Unlike every
+ * provider stream (guarded by first-event/idle watchdogs in pi-ai), these are
+ * raw fetches awaiting one non-streamed JSON body — a connection silently
+ * dropped by a middlebox would otherwise hang the whole compaction pipeline
+ * forever (frozen "Auto context-full maintenance…" spinner, manual /compact
+ * queueing behind it). On timeout the caller falls back to local summarization.
  */
-export declare const REMOTE_COMPACTION_TIMEOUT_MS = 180000;
+export declare const REMOTE_COMPACTION_TIMEOUT_MS = 300000;
 export declare const CONTEXT_WINDOW_TRUNCATED_OUTPUT_MESSAGE: string;
 export interface TrimRemoteCompactionInputResult {
     input: Array<Record<string, unknown>>;
@@ -72,6 +72,7 @@ export interface RemoteCompactionResponse {
     summary: string;
     shortSummary?: string;
 }
+export declare function isOpenAiRemoteCompactionApi(api: Api | undefined): boolean;
 export declare function shouldUseOpenAiRemoteCompaction(model: Model): boolean;
 export declare function getPreservedOpenAiRemoteCompactionData(preserveData: Record<string, unknown> | undefined): OpenAiRemoteCompactionPreserveData | undefined;
 export declare function withOpenAiRemoteCompactionPreserveData(preserveData: Record<string, unknown> | undefined, remoteCompaction: OpenAiRemoteCompactionPreserveData | undefined): Record<string, unknown> | undefined;

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 "@linxiraos/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/thinking.d.ts

@@ -1,4 +1,4 @@
-import { Effort } from "@linxiraos/pi-ai";
+import { Effort } from "@linxiraos/pi-catalog/effort";
 /**
  * Agent-local thinking selector.
  *

package/dist/types/types.d.ts

@@ -6,8 +6,17 @@ import type { AgentRunCoverage, AgentRunSummary } from "./run-collector.js";
 import type { AgentTelemetryConfig } from "./telemetry.js";
 /** Stream function - can return sync or Promise for async config lookup */
 export type StreamFn = (...args: Parameters<typeof streamSimple>) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>;
+/** Staged queue preparation; commit synchronously only while the batch is still owned. */
+export interface QueuedMessagePreparation {
+    /** Append context after the originals; undefined stops this attempt, retaining originals unless explicitly removed. */
+    commit(): readonly AgentMessage[] | undefined;
+}
+/** Prepare an exclusively claimed batch. Undefined delivers unchanged; the signal also aborts when the claim is cancelled. */
+export type PrepareQueuedMessages = (messages: readonly AgentMessage[], signal: AbortSignal) => QueuedMessagePreparation | undefined | Promise<QueuedMessagePreparation | undefined>;
 /** 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 +290,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 +520,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 +734,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 +854,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). */
@@ -678,8 +881,9 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any
      * Called at `toolcall_start`, before any argument delta. Return `undefined` to opt out.
      */
     openArgStream?: (init: AgentToolArgStreamInit) => AgentToolArgStream | undefined;
-    /** If true, tool is excluded unless explicitly listed in --tools or agent's tools field */
     hidden?: boolean;
+    /** If true, the tool can read `skill://<name>` instruction content; prompt builders gate skill guidance on it. */
+    readsSkillUris?: boolean;
     /** If true, tool can stage a pending action that requires explicit resolution via the resolve tool. */
     deferrable?: boolean;
     /** How an enabled tool is presented. See {@link ToolLoadMode}. Omitted is treated as `"essential"` for built-ins; custom-tool adapters normalize omission to `"discoverable"`. */
@@ -693,6 +897,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": "@linxiraos/pi-agent-core",
-	"version": "1.1.14",
+	"version": "1.1.16",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://linxira-os.github.io/zeta/",
 	"author": "Can Boluk",
@@ -35,19 +35,19 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@linxiraos/pi-ai": "1.1.14",
-		"@linxiraos/pi-catalog": "1.1.14",
-		"@linxiraos/pi-natives": "1.1.14",
-		"@linxiraos/pi-utils": "1.1.14",
-		"@linxiraos/pi-wire": "1.1.14",
-		"@linxiraos/pi-snapcompact": "1.1.14",
-		"@opentelemetry/api": "^1.9.1"
+		"@opentelemetry/api": "^1.9.1",
+		"@linxiraos/pi-ai": "1.1.16",
+		"@linxiraos/pi-catalog": "1.1.16",
+		"@linxiraos/pi-natives": "1.1.16",
+		"@linxiraos/pi-utils": "1.1.16",
+		"@linxiraos/pi-wire": "1.1.16",
+		"@linxiraos/pi-snapcompact": "1.1.16"
 	},
 	"devDependencies": {
-		"@linxiraos/pi-omptype": "1.1.14",
 		"@opentelemetry/context-async-hooks": "^2.9.0",
 		"@opentelemetry/sdk-trace-base": "^2.9.0",
-		"@types/bun": "^1.3.14"
+		"@types/bun": "^1.3.14",
+		"@linxiraos/pi-omptype": "1.1.16"
 	},
 	"engines": {
 		"bun": ">=1.3.14"