@oh-my-pi/pi-coding-agent 17.1.6 → 17.1.7

package/dist/types/config/settings-schema.d.ts

@@ -3941,11 +3941,26 @@ export declare const SETTINGS_SCHEMA: {
     readonly "inspect_image.enabled": {
         readonly type: "boolean";
         readonly default: false;
+    };
+    readonly "inspect_image.mode": {
+        readonly type: "enum";
+        readonly values: readonly ["auto", "on", "off"];
+        readonly default: "auto";
         readonly ui: {
             readonly tab: "tools";
             readonly group: "Available Tools";
             readonly label: "Inspect Image";
-            readonly description: "Enable the inspect_image tool, delegating image understanding to a vision-capable model";
+            readonly description: "Controls the inspect_image tool, which delegates image understanding to a vision-capable model. 'auto' exposes it only when the active model lacks native image input; 'on' always exposes it; 'off' never does.";
+            readonly options: readonly [{
+                readonly value: "auto";
+                readonly label: "Auto (only for models without vision)";
+            }, {
+                readonly value: "on";
+                readonly label: "On";
+            }, {
+                readonly value: "off";
+                readonly label: "Off";
+            }];
         };
     };
     readonly "computer.enabled": {

package/dist/types/cursor.d.ts

@@ -5,7 +5,8 @@ interface CursorExecBridgeOptions {
     cwd: string;
     getCwd?: () => string;
     tools: Map<string, AgentTool>;
-    getTool?: (name: string) => AgentTool | undefined;
+    /** Resolves execution overrides (mounted-device permission wrappers) before the canonical map. */
+    getExecutableTool?: (name: string) => AgentTool | undefined;
     getToolContext?: () => AgentToolContext | undefined;
     emitEvent?: (event: AgentEvent) => void;
     /**

package/dist/types/extensibility/extensions/runner.d.ts

@@ -69,6 +69,10 @@ export declare class ExtensionRunner {
     private readonly modelRegistry;
     private readonly settings?;
     private readonly localProtocolOptions?;
+    /** Records that the loop already emitted `tool_call` for this dispatch. */
+    markToolCallEmitted(toolCallId: string, toolName: string): void;
+    /** Consumes a {@link markToolCallEmitted} marker; true when the loop already emitted. */
+    consumeToolCallEmitted(toolCallId: string, toolName: string): boolean;
     constructor(extensions: Extension[], runtime: ExtensionRuntime, cwd: string, sessionManager: SessionManager, modelRegistry: ModelRegistry, getMemory?: () => MemoryRuntimeContext | undefined, settings?: Settings | undefined, localProtocolOptions?: LocalProtocolOptions | undefined);
     initialize(actions: ExtensionActions, contextActions: ExtensionContextActions, commandContextActions?: ExtensionCommandContextActions, uiContext?: ExtensionUIContext): void;
     /**

package/dist/types/extensibility/shared-events.d.ts

@@ -228,13 +228,30 @@ export interface TodoReminderEvent {
 }
 /**
  * Return type for `tool_call` handlers.
- * Allows handlers to block tool execution.
+ * Allows handlers to block tool execution or revise the input the tool runs with.
  */
 export interface ToolCallEventResult {
     /** If true, block the tool from executing */
     block?: boolean;
     /** Reason for blocking (returned to LLM as error) */
     reason?: string;
+    /**
+     * Replacement input the tool executes with, instead of the original arguments. Ignored when
+     * `block` is true. This is the raw execution input passed to the tool's `execute` (the handler
+     * owns its correctness) — not the normalized `event.input` view, which may carry derived
+     * gate-only fields (e.g. hashline `edit` `path`/`paths`) that are not real parameters. When
+     * multiple handlers set `input`, the last one wins; handlers do not observe each other's
+     * revisions (each sees the original `event.input`). Not applied to `computer` tool calls.
+     *
+     * For model-issued tool calls the event fires at arg-prep time in the agent loop, before
+     * concurrency scheduling, `tool_execution_start`, and the approval gate: the revision is
+     * revalidated against the tool schema and becomes what the loop schedules, displays, persists,
+     * and executes — the user always approves what actually runs. For dispatches the loop never
+     * sees (nested `write xd://` device calls, Cursor direct execution) the tool wrapper applies
+     * the revision before its own approval gate; a revised nested xd:// input forfeits the outer
+     * write gate's approval and faces the full prompt again.
+     */
+    input?: Record<string, unknown>;
 }
 /**
  * Return type for `tool_result` handlers.

package/dist/types/modes/components/custom-editor.d.ts

@@ -103,6 +103,11 @@ export declare class CustomEditor extends Editor {
      *  reset the editor text and all pending draft-image state. The shared tail of
      *  every "message submitted" path; pass no argument for a plain discard. */
     clearDraft(historyText?: string): void;
+    /** Replace the composer draft with a restored historical prompt: sets the text and
+     *  re-attaches the message's images so positional `[Image #N]` markers resolve on
+     *  resubmit instead of degrading to literal text (esc-esc branch, `/tree`). Source
+     *  links are unknown for restored drafts, so every link slot is `undefined`. */
+    setDraft(text: string, images?: readonly ImageContent[]): void;
     /** Treat image/paste markers as indivisible: a stray backspace deletes the whole token
      *  instead of corrupting `[Paste #1, +30 lines]` into plain text. */
     atomicTokenPattern: RegExp;

package/dist/types/session/agent-session-types.d.ts

@@ -15,7 +15,7 @@ import type { Skill, SkillWarning } from "../extensibility/skills.js";
 import type { FileSlashCommand } from "../extensibility/slash-commands.js";
 import type { SecretObfuscator } from "../secrets/obfuscator.js";
 import type { ConfiguredThinkingLevel } from "../thinking.js";
-import type { XdevRegistry } from "../tools/xdev.js";
+import type { XdevState } from "../tools/xdev.js";
 import type { SessionManager } from "./session-manager.js";
 /** Maximum time the interactive shutdown path waits for Mnemopi consolidation. */
 export declare const SHUTDOWN_CONSOLIDATE_BUDGET_MS = 1500;
@@ -121,6 +121,8 @@ export interface AgentSessionConfig {
     createMemoryTools?: () => Promise<AgentTool[]>;
     /** Creates the built-in `computer` tool for session-scoped runtime enablement (see {@link AgentSession.setComputerToolEnabled}). */
     createComputerTool?: () => Promise<AgentTool | null>;
+    /** Creates the built-in `inspect_image` tool for session-scoped runtime enablement (see {@link AgentSession.setInspectImageMode}). */
+    createInspectImageTool?: () => Promise<AgentTool | null>;
     /** Model registry for API key resolution and model discovery. */
     modelRegistry: ModelRegistry;
     /** Tool registry for LSP and settings. */
@@ -164,10 +166,8 @@ export interface AgentSessionConfig {
         name: string;
         summary: string;
     }>;
-    /** Session-owned `xd://` registry. */
-    xdevRegistry?: XdevRegistry;
-    /** Discoverable tools mounted under `xd://` in the initial enabled set. */
-    initialMountedXdevToolNames?: string[];
+    /** `xd://` presentation state backed by the canonical tool map. */
+    xdev?: XdevState;
     /** Names pinned top-level during runtime repartitioning. */
     presentationPinnedToolNames?: ReadonlySet<string>;
     /** Accessor for live MCP server instructions. */

package/dist/types/session/agent-session.d.ts

@@ -46,6 +46,7 @@ import { type AskToolDetails, type AskToolInput } from "../tools/ask.js";
 import type { CheckpointState, CompletedRewindState } from "../tools/checkpoint.js";
 import { type PlanProposalHandler } from "../tools/resolve.js";
 import type { TodoPhase } from "../tools/todo.js";
+import type { InspectImageMode } from "../utils/inspect-image-mode.js";
 import type { VibeModeState } from "../vibe/state.js";
 import type { AgentSessionEventListener } from "./agent-session-events.js";
 import type { AgentSessionConfig, AgentSessionDisposeOptions, AsyncJobSnapshot, CommandMetadataChangedListener, ContextUsageBreakdown, FollowUpOptions, FreshSessionResult, HandoffResult, ModelCycleResult, Prewalk, PromptOptions, ResolvedRoleModel, RestoredQueuedMessage, RoleModelCycle, RoleModelCycleResult, SessionHandoffOptions, SessionOAuthAccountList, SessionStats, UsageFallbackConfirmation } from "./agent-session-types.js";
@@ -283,6 +284,26 @@ export declare class AgentSession {
      * tool (e.g. restricted child sessions have no factory).
      */
     setComputerToolEnabled(enabled: boolean): Promise<boolean>;
+    /**
+     * Session-scoped inspect_image mode (`/vision`). `auto` clears the override
+     * and returns to the persisted `inspect_image.mode` setting; `on`/`off`
+     * force the tool for this session only. See {@link SessionTools.setInspectImageMode}.
+     */
+    setInspectImageMode(mode: InspectImageMode): Promise<boolean>;
+    /** Effective inspect_image state for `/vision status`. */
+    inspectImageState(): {
+        mode: InspectImageMode;
+        active: boolean;
+        model: string | undefined;
+    };
+    /** Session-scoped `/vision` override; undefined means "follow the persisted setting". */
+    getInspectImageModeOverride(): InspectImageMode | undefined;
+    /**
+     * Reconciles the inspect_image tool set after the persisted
+     * `inspect_image.mode` setting changed (e.g. via the settings selector), so
+     * the new value takes effect immediately instead of on the next model switch.
+     */
+    applyInspectImageModeChange(): Promise<boolean>;
     /** Cancels the local rollout-memory startup owned by this session. */
     cancelLocalMemoryStartup(): void;
     /** Starts a new local rollout-memory generation and cancels its predecessor. */
@@ -766,10 +787,12 @@ export declare class AgentSession {
      * @param entryId ID of the entry to branch from
      * @returns Object with:
      *   - selectedText: The text of the selected user message (for editor pre-fill)
+     *   - selectedImages: Image attachments of the selected user message (for editor draft restore)
      *   - cancelled: True if a hook cancelled the branch
      */
     branch(entryId: string): Promise<{
         selectedText: string;
+        selectedImages: ImageContent[];
         cancelled: boolean;
     }>;
     branchFromBtw(question: string, assistantMessage: AssistantMessage): Promise<{
@@ -783,7 +806,7 @@ export declare class AgentSession {
      * @param targetId The entry ID to navigate to
      * @param options.summarize Whether user wants to summarize abandoned branch
      * @param options.customInstructions Custom instructions for summarizer
-     * @returns Result with editorText (if user message) and cancelled status
+     * @returns Result with editorText/editorImages (if user message) and cancelled status
      */
     navigateTree(targetId: string, options?: {
         summarize?: boolean;
@@ -810,6 +833,8 @@ export declare class AgentSession {
         reanswerAskResult?: AgentToolResult<AskToolDetails>;
     }): Promise<{
         editorText?: string;
+        /** Image attachments of the target user message, parallel to the positional `[Image #N]` markers in {@link editorText}. */
+        editorImages?: ImageContent[];
         cancelled: boolean;
         aborted?: boolean;
         summaryEntry?: BranchSummaryEntry;

package/dist/types/session/model-controls.d.ts

@@ -21,7 +21,7 @@ export interface ModelControlsHost {
     promptGeneration(): number;
     resolveActiveEditMode(): EditMode;
     syncAfterModelChange(previousEditMode: EditMode): Promise<void>;
-    setModelWithProviderSessionReset(model: Model): void;
+    setModelWithProviderSessionReset(model: Model): Promise<void>;
     clearActiveRetryFallback(): void;
     clearInheritedProviderPromptCacheKey(): void;
     magicKeywordEnabled(keyword: "orchestrate" | "ultrathink" | "workflow"): boolean;

package/dist/types/session/session-tools.d.ts

@@ -7,8 +7,9 @@ import type { ExtensionRunner } from "../extensibility/extensions/index.js";
 import { type Skill, type SkillWarning } from "../extensibility/skills.js";
 import { type LocalProtocolOptions } from "../internal-urls/index.js";
 import type { MemoryBackendStartOptions } from "../memory-backend/types.js";
-import { type XdevRegistry } from "../tools/xdev.js";
+import { type XdevState } from "../tools/xdev.js";
 import { type EditMode } from "../utils/edit-mode.js";
+import { type InspectImageMode } from "../utils/inspect-image-mode.js";
 import type { ClientBridge } from "./client-bridge.js";
 import type { CustomMessage } from "./messages.js";
 import type { SessionManager } from "./session-manager.js";
@@ -33,12 +34,17 @@ export interface SessionToolsHost {
     emitNotice(level: "info" | "warning" | "error", message: string, source?: string): void;
     notifyCommandMetadataChanged(): void;
     localProtocolOptions(): LocalProtocolOptions;
+    /** Session-scoped `/vision` override; undefined means "follow the persisted setting". */
+    getInspectImageModeOverride(): InspectImageMode | undefined;
+    setInspectImageModeOverride(mode: InspectImageMode | undefined): void;
 }
 interface SessionToolsOptions {
     autoApprove?: boolean;
     toolRegistry?: Map<string, AgentTool>;
     createVibeTools?: () => AgentTool[];
     createComputerTool?: () => Promise<AgentTool | null>;
+    /** Creates the built-in `inspect_image` tool for session-scoped runtime enablement (see {@link SessionTools.setInspectImageMode}). */
+    createInspectImageTool?: () => Promise<AgentTool | null>;
     builtInToolNames?: Iterable<string>;
     presentationPinnedToolNames?: ReadonlySet<string>;
     ensureWriteRegistered?: () => Promise<boolean>;
@@ -47,8 +53,7 @@ interface SessionToolsOptions {
     }>;
     getLocalCalendarDate?: () => string;
     getMcpServerInstructions?: () => Map<string, string> | undefined;
-    xdevRegistry?: XdevRegistry;
-    initialMountedXdevToolNames?: string[];
+    xdev?: XdevState;
     setActiveToolNames?: (names: Iterable<string>) => void;
     baseSystemPrompt: string[];
     skills?: Skill[];
@@ -99,13 +104,13 @@ export declare class SessionTools {
     get skillsSettings(): SkillsSettings | undefined;
     /** Drops cached per-session ACP `allow_always`/`reject_always` decisions. */
     clearAcpPermissionDecisions(): void;
-    /** Re-wraps active and mounted tools after the ACP client changes. */
+    /** Drops cached ACP decisions and re-wraps active tools after the client changes. */
     refreshAcpPermissionGates(): void;
     /** Names of tools currently exposed at the top level. */
     getActiveToolNames(): string[];
     /** Enabled top-level and discoverable tool names. */
     getEnabledToolNames(): string[];
-    /** Names of dynamic tools mounted under `xd://`. */
+    /** Names currently presented as `xd://` devices. */
     getMountedXdevToolNames(): string[];
     /** Whether the edit tool is registered. */
     get hasEditTool(): boolean;
@@ -139,7 +144,7 @@ export declare class SessionTools {
      * Restore an enabled tool set with its exact top-level versus `xd://` partition.
      *
      * Both inputs are required because {@link setActiveToolsByName} only receives the
-     * enabled name list and classifies mounts from the current `#mountedXdevToolNames`.
+     * enabled name list and classifies mounts from the current presentation set.
      * Rollback/restore callers must pass the snapshotted mounted subset so names that
      * were top-level stay pinned (`#runtimeSelectedToolNames`) and names that were under
      * `xd://` remain mount-eligible, even when the live mount set has drifted.
@@ -166,6 +171,39 @@ export declare class SessionTools {
      * tool (e.g. restricted child sessions have no factory).
      */
     setComputerToolEnabled(enabled: boolean): Promise<boolean>;
+    /** Current effective inspect_image state for `/vision status`. */
+    inspectImageState(): {
+        mode: InspectImageMode;
+        active: boolean;
+        model: string | undefined;
+    };
+    /**
+     * Brings the active tool set in line with the effective inspect_image state
+     * (mode setting, `/vision` override, active-model image capability).
+     * Mirrors {@link setComputerToolEnabled}: enabling builds the tool through
+     * the config factory on first use and reuses the registry entry afterwards.
+     * Idempotent — safe to call from every model/settings change path.
+     *
+     * @returns false when the tool should be active but this session cannot
+     *   build it (e.g. restricted child sessions have no factory).
+     */
+    reconcileInspectImageTool(): Promise<boolean>;
+    /**
+     * Reconciles inspect_image after a model change and surfaces a notice when
+     * the visible tool set actually flipped. Called from every model-change
+     * path — including retry-fallback switches that bypass
+     * {@link syncAfterModelChange}.
+     */
+    reconcileInspectImageAfterModelChange(): Promise<void>;
+    /**
+     * Session-scoped `/vision` override. `auto` clears the override so the
+     * persisted `inspect_image.mode` setting (itself possibly `auto`) decides;
+     * `on`/`off` force the tool for this session only. Takes effect before the
+     * next model call.
+     *
+     * @returns false when `on` was requested but the tool cannot be built here.
+     */
+    setInspectImageMode(mode: InspectImageMode): Promise<boolean>;
     /** Rebuilds the stable base prompt for the current tools and model. */
     refreshBaseSystemPrompt(): Promise<void>;
     /** Applies one-turn memory prompt injection before an agent run. */

package/dist/types/session/streaming-output.d.ts

@@ -34,12 +34,17 @@ export interface OutputSummary {
 export interface OutputSinkOptions {
     artifactPath?: string;
     artifactId?: string;
-    /** Tail buffer budget (bytes). Default DEFAULT_MAX_BYTES. */
+    /**
+     * Total inline body budget (bytes). Default DEFAULT_MAX_BYTES. The head
+     * window and rolling tail window share this budget, so a composed
+     * `dump()` body never exceeds it (plus the elision marker).
+     */
     spillThreshold?: number;
     /**
      * When > 0, the sink keeps the first `headBytes` of output in addition to
      * the rolling tail window. Output between the two windows is elided
-     * (middle elision). Default 0 = tail-only behavior.
+     * (middle elision). Clamped to `spillThreshold / 2` so the tail keeps at
+     * least half the inline budget. Default 0 = tail-only behavior.
      */
     headBytes?: number;
     /**

package/dist/types/session/turn-recovery.d.ts

@@ -43,7 +43,7 @@ export interface TurnRecoveryHost {
     waitForSessionMessagePersistence(message: AssistantMessage): Promise<void>;
     appendSessionMessage(message: AssistantMessage): void;
     sessionMessageAlreadyPersisted(message: AssistantMessage): boolean;
-    setModelWithProviderSessionReset(model: Model): void;
+    setModelWithProviderSessionReset(model: Model): Promise<void>;
     resetCurrentResponsesProviderSession(reason: string): void;
     maybeAutoRedeemCodexReset(): Promise<boolean>;
     runAutoCompaction(reason: "overflow" | "threshold" | "idle" | "incomplete", willRetry: boolean, deferred?: boolean, allowDefer?: boolean, options?: {

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

@@ -24,12 +24,13 @@ import type { ToolChoiceQueue } from "../session/tool-choice-queue.js";
 import type { AgentOutputManager } from "../task/output-manager.js";
 import { type StructuredSubagentSchemaMode } from "../task/types.js";
 import type { EventBus } from "../utils/event-bus.js";
+import { type InspectImageMode } from "../utils/inspect-image-mode.js";
 import type { WorkspaceTree } from "../workspace-tree.js";
 import { type BuiltinToolName, type HiddenToolName } from "./builtin-names.js";
 import { type CheckpointState, type CompletedRewindState } from "./checkpoint.js";
 import type { PlanProposalHandler } from "./resolve.js";
 import { type TodoPhase } from "./todo.js";
-import { XdevRegistry } from "./xdev.js";
+import { type XdevState } from "./xdev.js";
 export * from "../edit/index.js";
 export * from "../goals/index.js";
 export * from "../lsp/index.js";
@@ -204,8 +205,10 @@ export interface ToolSession {
     isToolActive?: (name: string) => boolean;
     /** Update the active built-in tool predicate when a session changes tools mid-run. */
     setActiveToolNames?: (names: Iterable<string>) => void;
-    /** Tools mounted under `xd://` (set by createTools when `tools.xdev` is active); read/write consult it at execute time. */
-    xdevRegistry?: XdevRegistry;
+    /** Canonical map containing every registered tool exactly once. */
+    toolRegistry?: Map<string, Tool>;
+    /** `xd://` presentation state backed by {@link toolRegistry}. */
+    xdev?: XdevState;
     /** Agent registry for IRC routing across live sessions. */
     agentRegistry?: AgentRegistry;
     /** Idle→parked→revive lifecycle owner; lets the hub kill a non-job-backed agent registration. Default: AgentLifecycleManager.global(). */
@@ -227,6 +230,8 @@ export interface ToolSession {
     getActiveModelString?: () => string | undefined;
     /** Get the current session model object (provider/api capabilities), regardless of how it was chosen. */
     getActiveModel?: () => Model | undefined;
+    /** Session-scoped inspect_image mode override set by `/vision`; wins over the persisted setting. */
+    getInspectImageModeOverride?: () => InspectImageMode | undefined;
     /** Get the session's live per-family service tiers (undefined = none). Source of truth for subagent `tier.subagent: inherit`. */
     getServiceTierByFamily?: () => ServiceTierByFamily | undefined;
     /** Auth storage for passing to subagents (avoids re-discovery) */

package/dist/types/tools/output-meta.d.ts

@@ -197,6 +197,11 @@ export declare function stripOutputNotice(text: string, meta: OutputMeta | undef
  * middle elision with the same per-user configuration.
  */
 export declare function resolveOutputSinkHeadBytes(s: Settings | undefined): number;
+/**
+ * Resolve the `enforceInlineByteCap` budget for streaming tools (bash/ssh)
+ * from session settings: the user's spill threshold plus notice slack.
+ */
+export declare function resolveInlineByteCapBudget(s: Settings | undefined): number;
 /**
  * Resolve the per-line column cap from session settings. Shared by streaming
  * executors (bash/python/ssh/eval via OutputSink) and the `read` tool's

package/dist/types/tools/read.d.ts

@@ -56,12 +56,20 @@ export declare class ReadTool implements AgentTool<typeof readSchema, ReadToolDe
     readonly approval: (args: unknown) => ToolTier;
     readonly label = "Read";
     readonly loadMode = "essential";
-    readonly description: string;
+    description: string;
     readonly parameters: import("arktype/internal/variants/object.ts").ObjectType<{
         path: string;
     }, {}>;
     readonly strict = true;
     constructor(session: ToolSession);
+    /**
+     * Re-evaluate the effective inspect_image state; it can flip when the model
+     * or the `/vision` override changes after this tool was constructed. Keeps
+     * the behavior branch and the advertised description in lockstep. Called
+     * per image read and by tool reconciliation before prompt rebuilds (which
+     * passes the post-change availability as `availableOverride`).
+     */
+    syncInspectImageState(availableOverride?: boolean): boolean;
     execute(_toolCallId: string, params: ReadParams, signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<ReadToolDetails>, _toolContext?: AgentToolContext): Promise<AgentToolResult<ReadToolDetails>>;
 }
 interface ReadRenderArgs {

package/dist/types/tools/xdev.d.ts

@@ -9,15 +9,20 @@
  *   read  xd://<tool>    → tool docs + JSON parameter schema
  *   write xd://<tool>    → execute: `content` is the JSON args object
  *
+ * Direct and device dispatch share one canonical tool map. The mounted-name
+ * set controls presentation only; dispatch accepts the enabled union of
+ * top-level active and mounted names. Listing and prompt docs stay
+ * mounted-only because top-level tools already ship their schemas.
+ *
  * Args go through the same machinery as native tool calls: validated with
  * pi-ai's `validateToolArguments` (the schema is returned on mismatch, so a
  * malformed call self-corrects without a round trip) and streamed through
  * the write tool's existing incremental `content` decoding for live render
  * previews. Compared to a dispatcher def this still costs zero *schema
  * duplication* — one wire schema per tool instead of one per dispatcher
- * branch — but full docs + schema for every mounted device are inlined into
- * the system prompt (`XdevRegistry.docsAll()`) so no discovery `read` is
- * needed before first use; `read xd://<tool>` remains for on-demand re-fetch.
+ * branch — but full docs + schema for every mounted device can be inlined
+ * into the system prompt, so no discovery read is needed before first use;
+ * `read xd://<tool>` remains for on-demand re-fetch.
  *
  * Rendering: the write renderer draws NOTHING until the streamed `path` is
  * known and provably does not target `xd://`; device writes then delegate to
@@ -54,8 +59,7 @@ export type XdevDocsMode = "inline" | "builtins" | "catalog";
  * while the `xd://` transport is active. Discoverable tools mount unless they
  * are pinned top-level by {@link XDEV_KEEP_TOP_LEVEL} or carry the transport
  * itself ({@link XDEV_TRANSPORT_TOOLS}); essential tools never do. The caller
- * gates this on the transport being active (a session-owned
- * {@link XdevRegistry} existing).
+ * gates this on the transport being active.
  */
 export declare function isMountableUnderXdev(tool: {
     name: string;
@@ -72,69 +76,51 @@ export interface XdevDispatch {
 }
 /** Wire the wrapped-renderer lookup. Called once by `renderers.ts`. */
 export declare function setXdevRendererLookup(lookup: (name: string) => ToolRenderer | undefined): void;
-/**
- * Registry of tools mounted under `xd://` for one session. `createTools`
- * mounts discoverable built-ins first; SDK assembly adds custom tools that do
- * not opt out. `read`/`write` consult it at execute time.
- */
-export declare class XdevRegistry {
-    #private;
-    constructor(builtins: Iterable<Tool>);
-    /**
-     * Replace the dynamic mount set while preserving the built-in devices. Order
-     * follows `tools`; names absent from it are dropped. A built-in device is
-     * never shadowed by a same-named dynamic entry.
-     */
-    reconcile(tools: Iterable<Tool>): void;
-    get size(): number;
-    /** Mounted tools in catalog order: built-ins first, then dynamic mounts. */
-    list(): readonly Tool[];
-    get(name: string): Tool | undefined;
-    /** `{name, summary}` pairs for prompt templates and /tools display. */
-    entries(): Array<{
-        name: string;
-        summary: string;
-    }>;
-    /** `read xd://` listing with one device per line. */
-    listing(): string;
-    /** Docs + schema for one device; throws with the listing when unknown. */
-    docs(name: string): string;
-    /**
-     * Char budget for the full docs inlined into the system prompt. Large MCP
-     * catalogs previously shipped every schema top-level; without a cap they
-     * would bloat every request. Devices past the budget fall back to a
-     * one-line summary — their docs stay one `read xd://<tool>` away.
-     */
-    static readonly DOCS_TOTAL_BUDGET = 48000;
-    /** A single device's docs above this size never inline: one pathological
-     *  MCP description must not starve every later device. */
-    static readonly DOCS_PER_DEVICE_CAP = 10000;
-    /** Description cap for EXTERNAL devices (dynamic mounts: MCP, custom,
-     *  extension, …) in the system-prompt embedding. Built-in devices inline
-     *  their full curated docs; external descriptions are server-controlled
-     *  prose the model can re-fetch, so only the lede earns prompt space. */
-    static readonly EXTERNAL_DESCRIPTION_CAP = 200;
-    /**
-     * Docs + schema for mounted devices, nested under `##` headings for
-     * system-prompt embedding. Inlines full docs in catalog order (built-ins
-     * first) until {@link DOCS_TOTAL_BUDGET} is spent; the rest are listed by
-     * name + summary with a pointer to on-demand `read xd://<tool>` docs.
-     * Dynamic mounts embed at most {@link EXTERNAL_DESCRIPTION_CAP} description
-     * chars (schema always intact); `read xd://<tool>` returns the full text.
-     */
-    docsAll(mode?: XdevDocsMode, inlinePatterns?: readonly string[]): string;
-    /** Docs for selected mounted devices under the configured prompt-doc policy. */
-    docsFor(names: Iterable<string>, mode: XdevDocsMode, inlinePatterns?: readonly string[]): string;
-    /**
-     * Execute a device write: `content` is the JSON args object (empty, `?`, or
-     * `help` returns docs). Args validate against the wrapped tool's schema —
-     * the schema comes back in the error on mismatch.
-     */
-    dispatch(name: string, content: string, toolCallId: string, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback, context?: AgentToolContext): Promise<{
-        result: AgentToolResult<unknown>;
-        xdev: XdevDispatch;
-    }>;
+/** Shared tool state consumed by the `xd://` presentation layer. */
+export interface XdevState {
+    /** Canonical session tool map; direct and device dispatch read the same instances. */
+    readonly tools: Map<string, Tool>;
+    /** Ordered names currently presented as mounted devices. */
+    readonly mountedNames: Set<string>;
+    /** Names originating from built-in factories, used only for prompt presentation. */
+    readonly builtInNames: Set<string>;
+    /** Whether a name is active at the top level. */
+    readonly isActive: (name: string) => boolean;
+    /** Optional execution-only decorator, such as the ACP permission gate. */
+    decorateExecution?(tool: Tool): Tool;
 }
+/** Full-doc character budget for system-prompt mounted-device sections. */
+export declare const XDEV_DOCS_TOTAL_BUDGET = 48000;
+/** Per-device cap preventing one pathological description from starving later devices. */
+export declare const XDEV_DOCS_PER_DEVICE_CAP = 10000;
+/** Description cap for external mounted tools; their full docs remain readable on demand. */
+export declare const XDEV_EXTERNAL_DESCRIPTION_CAP = 200;
+/** Resolve any enabled tool through the canonical session map. */
+export declare function resolveXdevTool(state: XdevState, name: string): Tool | undefined;
+/** Resolve a mounted tool for top-level fallback execution. */
+export declare function resolveMountedXdevTool(state: XdevState, name: string): Tool | undefined;
+/** Resolve a mounted tool with its execution-only permission decorator. */
+export declare function resolveMountedXdevExecutable(state: XdevState, name: string): Tool | undefined;
+/** Mounted tools in presentation order, resolved from the canonical map. */
+export declare function listXdevTools(state: XdevState): Tool[];
+/** `{name, summary}` pairs for prompt templates and `/tools` display. */
+export declare function xdevEntries(state: XdevState): Array<{
+    name: string;
+    summary: string;
+}>;
+/** `read xd://` listing with one device per line. */
+export declare function xdevListing(state: XdevState): string;
+/** Docs + schema for any enabled tool. */
+export declare function xdevDocs(state: XdevState, name: string): string;
+/** Docs + schema for mounted devices under the configured prompt-doc policy. */
+export declare function xdevDocsAll(state: XdevState, mode?: XdevDocsMode, inlinePatterns?: readonly string[]): string;
+/** Docs for selected mounted devices under the configured prompt-doc policy. */
+export declare function xdevDocsFor(state: XdevState, names: Iterable<string>, mode: XdevDocsMode, inlinePatterns?: readonly string[]): string;
+/** Execute an enabled canonical tool through `write xd://<tool>`. */
+export declare function dispatchXdevTool(state: XdevState, name: string, content: string, toolCallId: string, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback, context?: AgentToolContext): Promise<{
+    result: AgentToolResult<unknown>;
+    xdev: XdevDispatch;
+}>;
 /**
  * Streaming-safe call preview for an `xd://` write: forwards the decoded inner
  * args to the mounted tool's renderer (session instance first, then the static

package/dist/types/utils/cpuprofile.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Parser and renderer for V8 `.cpuprofile` files (emitted by `node --cpu-prof`,
+ * `bun --cpu-prof`, Chrome DevTools, and the CDP `Profiler` domain).
+ *
+ * The raw file is a JSON blob with a flat node table and up to millions of
+ * sample/timestamp entries — useless to read directly. `renderCpuProfile`
+ * converts it into a compact bottleneck summary:
+ *
+ * - the hot-path call tree, pruned to frames with meaningful self time,
+ *   with pass-through chains collapsed and direct recursion flattened
+ * - `(idle)` time excluded from on-CPU totals
+ * - a profile-wide "top functions by self time" table
+ *
+ * Consumed by the read tool: `*.cpuprofile` reads show the summary, `:raw`
+ * returns the original JSON.
+ */
+/** Matches paths the read tool should treat as V8 CPU profiles. */
+export declare function isCpuProfilePath(filePath: string): boolean;
+/** Call-site metadata of one profile node. `lineNumber` is 0-based. */
+export interface CpuProfileCallFrame {
+    functionName: string;
+    url?: string;
+    lineNumber?: number;
+}
+/** One node in the flat profile tree; `children` are node ids. */
+export interface CpuProfileNode {
+    id: number;
+    callFrame: CpuProfileCallFrame;
+    hitCount?: number;
+    children?: number[];
+}
+/** Parsed V8 CPU profile. `startTime`/`endTime`/`timeDeltas` are microseconds. */
+export interface CpuProfile {
+    nodes: CpuProfileNode[];
+    startTime: number;
+    endTime: number;
+    samples?: number[];
+    timeDeltas?: number[];
+}
+/**
+ * Parse a `.cpuprofile` JSON blob. Accepts both the bare profile and the CDP
+ * `Profiler.stop` result shape (`{ profile: {...} }`). Returns null when the
+ * text is not a structurally valid V8 CPU profile.
+ */
+export declare function parseCpuProfile(text: string): CpuProfile | null;
+/**
+ * Render a V8 CPU profile as an agent-friendly bottleneck summary.
+ * Returns null when `text` is not a CPU profile (caller falls back to the
+ * plain-text path).
+ */
+export declare function renderCpuProfile(text: string): string | null;