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

package/dist/types/cursor.d.ts

@@ -1,23 +1,69 @@
 import type { AgentEvent, AgentTool, AgentToolContext } from "@oh-my-pi/pi-agent-core";
-import type { CursorMcpCall, CursorShellStreamCallbacks, CursorTodoSnapshot, CursorExecHandlers as ICursorExecHandlers, ToolResultMessage } from "@oh-my-pi/pi-ai";
+import type { CursorMcpCall, CursorMcpResource, CursorMcpResourceContent, CursorShellStreamCallbacks, CursorTodoSnapshot, CursorExecHandlers as ICursorExecHandlers, ToolResultMessage } from "@oh-my-pi/pi-ai";
+import type { MCPResourceReadResult } from "./mcp/types.js";
 import type { TodoPhase } from "./tools/todo.js";
+/**
+ * A tool instance the bridge can run, matching the erased shape the session's
+ * tool registry stores. The concrete tools have narrower `execute` parameter
+ * types than the default `AgentTool`, which only unify through this alias.
+ */
+type CursorBridgeTool = AgentTool<any, any, any>;
+/**
+ * The live MCP connections Cursor's resource frames are answered from.
+ *
+ * Named so every construction site can hand over the same adapter; a session
+ * and its advisors share one set of connections.
+ */
+export interface CursorMcpResourceAdapter {
+    serverNames(): string[];
+    getServerResources(name: string): Promise<{
+        resources: {
+            uri: string;
+            name?: string;
+            description?: string;
+            mimeType?: string;
+        }[];
+    } | undefined>;
+    readServerResource(name: string, uri: string): Promise<MCPResourceReadResult | undefined>;
+}
 interface CursorExecBridgeOptions {
     cwd: string;
     getCwd?: () => string;
     tools: Map<string, AgentTool>;
     /** Resolves execution overrides (mounted-device permission wrappers) before the canonical map. */
     getExecutableTool?: (name: string) => AgentTool | undefined;
+    /**
+     * The `replace`-mode `edit` instance `pi_edit` must run, when the session
+     * granted `edit` at all.
+     *
+     * `PiEditExecArgs` is that mode's schema verbatim, and the session's own
+     * `edit` may be in any mode — `hashline` by default — whose schema rejects
+     * `old_text`/`new_text` outright. {@link tools} therefore cannot be trusted
+     * for this one frame: a session that starts on another provider keeps its
+     * configured instance in the map (only Cursor sessions move `edit` out), and
+     * switching to Cursor later does not rebuild the roster.
+     */
+    getEditReplaceTool?: () => CursorBridgeTool | undefined;
     getToolContext?: () => AgentToolContext | undefined;
     emitEvent?: (event: AgentEvent) => void;
     /**
-     * Whether the Cursor native `delete` frame may remove files. Unlike every
-     * other exec handler, `executeDelete` mutates the filesystem directly instead
-     * of consulting {@link tools}, so a background read-only advisor could delete
-     * workspace files it was never granted a mutating tool for (issue #5680
-     * review). Defaults to allowed to preserve the primary agent's behavior;
-     * callers with a restricted tool set (advisors) opt out.
+     * Whether frames that mutate the filesystem WITHOUT running a registry tool
+     * may do so: the native `delete` frame, and a `read_mcp_resource` carrying
+     * `download_path`. Both write or remove workspace files directly instead of
+     * consulting {@link tools}, so a background read-only advisor could touch
+     * files it was never granted a mutating tool for (issue #5680 review).
+     *
+     * This is a grant, not a policy: it answers "did the session hand this
+     * channel a file-writing tool", which callers derive from their own roster
+     * before any bridge-specific rewriting. The primary Cursor session moves
+     * `edit` out of {@link tools} and serves it through
+     * {@link getEditReplaceTool}, so reading the map here would deny an
+     * edit-only session. Defaults to allowed
+     * to preserve the primary agent's behavior; callers with a restricted tool
+     * set (advisors) opt out. The user's approval policy is resolved separately,
+     * per call.
      */
-    allowNativeDelete?: boolean;
+    allowDirectFileMutation?: boolean;
     /**
      * Mirror Cursor's server-owned todo list into local session state. Cursor
      * resolves `update_todos` / `read_todos` remotely, so without this bridge
@@ -30,18 +76,148 @@ interface CursorExecBridgeOptions {
      * Cursor emits no local `todo` toolResult, so nothing else records it.
      */
     persistTodoPhases?: (phases: TodoPhase[]) => void;
+    /**
+     * Build a `grep` tool honoring a frame's own context width and match cap.
+     *
+     * The modern `pi_grep` frame carries both, and the shared `grep` instance
+     * is fixed to the session settings at construction — so without this the
+     * two fields are silently dropped. Callers that cannot supply it keep the
+     * shared instance and the session's defaults.
+     *
+     * The returned tool is executed as-is. Callers whose registry tools carry an
+     * approval wrapper MUST apply the same wrapper here, or a frame supplying
+     * either field silently escapes the approval gate that every other call
+     * goes through.
+     */
+    createGrepTool?(options: {
+        context?: number;
+        totalMatchLimit?: number;
+    }): CursorBridgeTool | undefined;
+    /**
+     * The session's live MCP connections, for Cursor's resource frames.
+     *
+     * `list_mcp_resources` / `read_mcp_resource` ask what this client's servers
+     * advertise. Without this the bridge answers an empty catalog and
+     * `not_found`, hiding resources the session is in fact connected to.
+     *
+     * `getServerResources` is async because a server's catalog loads in the
+     * background after its tools register: a frame arriving in that window would
+     * otherwise read the not-yet-populated cache and report an empty catalog,
+     * which is indistinguishable from a server that advertises nothing.
+     */
+    mcpResources?: CursorMcpResourceAdapter;
 }
 export declare class CursorExecHandlers implements ICursorExecHandlers {
     private options;
     constructor(options: CursorExecBridgeOptions);
+    /**
+     * Modern Cursor builds paginate the legacy `read` frame with
+     * `offset`/`limit`, exactly as `pi_read` does. Dropping them returns the
+     * whole file (or its own truncation) for every page, so a model walking a
+     * large file never advances. Composed with the same helper, so both frames
+     * translate a range identically.
+     */
     read(args: Parameters<NonNullable<ICursorExecHandlers["read"]>>[0]): Promise<ToolResultMessage<unknown>>;
     ls(args: Parameters<NonNullable<ICursorExecHandlers["ls"]>>[0]): Promise<ToolResultMessage<unknown>>;
+    /**
+     * Modern Cursor builds paginate this frame with `offset`. The local `grep`
+     * paginates by file through `skip`, which is the same unit its own
+     * "use skip=N for the next page" advice counts in — so an unforwarded
+     * offset re-runs the identical search and returns page one forever.
+     */
     grep(args: Parameters<NonNullable<ICursorExecHandlers["grep"]>>[0]): Promise<ToolResultMessage<unknown>>;
     write(args: Parameters<NonNullable<ICursorExecHandlers["write"]>>[0]): Promise<ToolResultMessage<unknown>>;
     delete(args: Parameters<NonNullable<ICursorExecHandlers["delete"]>>[0]): Promise<ToolResultMessage<unknown>>;
     shell(args: Parameters<NonNullable<ICursorExecHandlers["shell"]>>[0]): Promise<ToolResultMessage<unknown>>;
     shellStream(args: Parameters<NonNullable<ICursorExecHandlers["shellStream"]>>[0], callbacks: CursorShellStreamCallbacks): Promise<ToolResultMessage<unknown>>;
     diagnostics(args: Parameters<NonNullable<ICursorExecHandlers["diagnostics"]>>[0]): Promise<ToolResultMessage<unknown>>;
+    /**
+     * Modern Cursor CLI Pi tool frames (`ExecServerMessage` 45-51).
+     *
+     * These are a separate frame family from the legacy `read`/`shell`/... set,
+     * not aliases: different args, different result oneofs, and no `tool_call_id`
+     * (the provider mints one and passes it in `call.toolCallId`). Each maps onto
+     * the local tool with matching semantics, so the same approval, sandboxing
+     * and event plumbing applies as for a model-issued call.
+     */
+    /**
+     * `offset`/`limit` are a 1-indexed start line plus a line count (verified
+     * against the reference `LocalPiReadExecutor`), which is exactly the local
+     * `read` tool's `:N+K` inline selector — the tool takes no range kwargs, so
+     * the range has to be composed onto the path or ranged reads silently
+     * return the whole file.
+     */
+    piRead(call: Parameters<NonNullable<ICursorExecHandlers["piRead"]>>[0]): Promise<ToolResultMessage<unknown>>;
+    piBash(call: Parameters<NonNullable<ICursorExecHandlers["piBash"]>>[0]): Promise<ToolResultMessage<unknown>>;
+    /**
+     * `PiEditExecArgs` is the local `edit` tool's replace mode verbatim: a path
+     * plus `old_text`/`new_text` pairs. The tool's schema is snake_case, so the
+     * proto's camelCase accessors are mapped back on the way in.
+     *
+     * The replace-mode instance is requested explicitly rather than resolved
+     * from {@link CursorExecBridgeOptions.tools}: the registry's `edit` is in
+     * the session's configured mode, whose schema rejects these arguments.
+     */
+    piEdit(call: Parameters<NonNullable<ICursorExecHandlers["piEdit"]>>[0]): Promise<ToolResultMessage<unknown>>;
+    piWrite(call: Parameters<NonNullable<ICursorExecHandlers["piWrite"]>>[0]): Promise<ToolResultMessage<unknown>>;
+    /**
+     * `literal` makes the pattern a fixed string; the local tool is regex-only,
+     * so the pattern is escaped on the way in (same translation the legacy pi
+     * shim does).
+     *
+     * `context` and `limit` are not expressible in the model-facing schema —
+     * context width comes from settings fixed at tool construction — so the
+     * frame's values are honored by building a per-call `grep` through
+     * {@link CursorExecBridgeOptions.createGrepTool}. Both are `optional int32`,
+     * so a present `0` context means "no context lines", not "use the default".
+     * Without the factory the shared instance runs with session defaults.
+     */
+    piGrep(call: Parameters<NonNullable<ICursorExecHandlers["piGrep"]>>[0]): Promise<ToolResultMessage<unknown>>;
+    /**
+     * `pi_find` is a filename search, which is the local `glob` tool — not
+     * `grep`. Its `pattern` is a glob, joined onto `path` because `glob` takes a
+     * single combined path spec.
+     *
+     * `limit` is `optional int32`, so `0` is present rather than unset; the
+     * reference clamps it with `Math.max(1, limit ?? 1000)`, and an unset limit
+     * leaves the local tool's own default in place.
+     */
+    piFind(call: Parameters<NonNullable<ICursorExecHandlers["piFind"]>>[0]): Promise<ToolResultMessage<unknown>>;
+    /**
+     * Redirected to `read`, which lists directories — same as the legacy `ls`.
+     * The frame's entry `limit` is not mapped; see {@link piLsPath}.
+     */
+    piLs(call: Parameters<NonNullable<ICursorExecHandlers["piLs"]>>[0]): Promise<ToolResultMessage<unknown>>;
+    /**
+     * The resources this client's MCP servers advertise.
+     *
+     * Cursor addresses a later read by `server`, so every entry carries the name
+     * it came from. An absent `server` filter means "all of them".
+     */
+    listMcpResources({ server }: {
+        server?: string;
+    }): Promise<CursorMcpResource[]>;
+    /**
+     * Read one resource, or `null` when the server or uri is unknown.
+     *
+     * MCP returns a list of content items; the wire carries exactly one text or
+     * blob. Text items are joined, since a multi-part text resource is one
+     * document; otherwise the first blob stands in. `blob` arrives base64 and
+     * the wire wants bytes.
+     *
+     * A `downloadPath` frame is a different contract: write the bytes to that
+     * workspace-relative path and answer with the path alone, so a large binary
+     * lands on disk instead of in the model's context. That makes it a workspace
+     * mutation reached without a registry tool, so it is gated exactly like the
+     * native `delete` frame — on the session actually granting a file-writing
+     * tool, and on the user's `write`-tier policy. The gate runs before the read
+     * so a refused download never fetches the resource either.
+     */
+    readMcpResource({ server, uri, downloadPath, }: {
+        server: string;
+        uri: string;
+        downloadPath?: string;
+    }): Promise<CursorMcpResourceContent | null>;
     /**
      * Settle a completed native Cursor todo call, mirroring its list when the
      * server supplied an authoritative one.
@@ -76,5 +252,14 @@ export declare class CursorExecHandlers implements ICursorExecHandlers {
      */
     todoSync(snapshot: CursorTodoSnapshot | null, toolCallId: string, error?: string | null): ToolResultMessage;
     mcp(call: CursorMcpCall): Promise<ToolResultMessage<unknown>>;
+    /**
+     * Resolve an MCP call's approval without running it.
+     *
+     * Same resolution the wrapper applies at execution time, minus the
+     * execution: an unknown tool is not approvable, and a `prompt` is not an
+     * approval — the frame has no way to carry an interactive question, and the
+     * user is asked for real when the call itself arrives.
+     */
+    mcpApprovalPreflight(call: CursorMcpCall): Promise<boolean>;
 }
 export {};

package/dist/types/edit/edit-clipboard.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Session-bound edit clipboard register.
+ *
+ * `CUT`/`PASTE` hashline ops share one {@link Clipboard} per session so
+ * content captured by one edit call can be pasted by a later one (and across
+ * files within one call). The executor works on a fork per batch and commits
+ * it back only after every write lands — see `executeHashlineSingle`.
+ */
+import type { Clipboard } from "@oh-my-pi/hashline";
+interface EditClipboardOwner {
+    editClipboard?: Clipboard;
+}
+/**
+ * Look up (or lazily create) the clipboard register attached to a session.
+ * Storage lives on `session.editClipboard` so it ages out exactly with the
+ * session itself.
+ */
+export declare function getEditClipboard(session: EditClipboardOwner): Clipboard;
+export {};

package/dist/types/edit/hashline/diff.d.ts

@@ -1,4 +1,4 @@
-import { type PatchSection, type SnapshotStore } from "@oh-my-pi/hashline";
+import { type Clipboard, type PatchSection, type SnapshotStore } from "@oh-my-pi/hashline";
 export interface HashlineDiffOptions {
     /**
      * Use the streaming-tolerant applier ({@link PatchSection.applyPartialTo})
@@ -12,6 +12,14 @@ export interface HashlineDiffOptions {
      * authoring input; the final apply path still validates through Patcher.
      */
     skipHashValidation?: boolean;
+    /**
+     * Clipboard register shared across the sections of one patch preview.
+     * `CUT` in an earlier section feeds `PASTE` in a later one, so the preview
+     * matches apply. Multi-section previews MUST thread one register through
+     * sections in patch order; omitted, each section gets a
+     * private register (same-file cut/paste still previews correctly).
+     */
+    clipboard?: Clipboard;
 }
 export declare function computeHashlineSectionDiff(section: PatchSection, cwd: string, snapshots: SnapshotStore, options?: HashlineDiffOptions): Promise<{
     diff: string;

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

@@ -33,7 +33,14 @@ export declare class EditTool implements AgentTool<TInput> {
     readonly loadMode = "essential";
     readonly concurrency = "exclusive";
     readonly strict = true;
-    constructor(session: ToolSession);
+    /**
+     * `mode` pins the edit variant for this instance, for callers whose protocol
+     * fixes the shape of an edit. The Cursor `pi_edit` frame carries
+     * `old_text`/`new_text` pairs, which only `replace` accepts — under the
+     * default `hashline` mode those args do not match the schema at all. Left
+     * unset, the env/settings resolution applies as before.
+     */
+    constructor(session: ToolSession, mode?: EditMode);
     get mode(): EditMode;
     get description(): string;
     get parameters(): TInput;

package/dist/types/edit/streaming.d.ts

@@ -12,7 +12,7 @@
  * The shared renderer / `ToolExecutionComponent` consult the strategy via
  * the injected `editMode` rather than probing argument shape.
  */
-import { type SnapshotStore } from "@oh-my-pi/hashline";
+import { type Clipboard, type SnapshotStore } from "@oh-my-pi/hashline";
 import type { Theme } from "../modes/theme/theme.js";
 import { type EditMode, resolveEditMode } from "../utils/edit-mode.js";
 export interface PerFileDiffPreview {
@@ -34,6 +34,13 @@ export interface StreamingDiffContext {
      * not flicker in the preview.
      */
     isStreaming?: boolean;
+    /**
+     * Session-persistent clipboard register (`CUT`/`PASTE`). Previews
+     * fork it per frame — never mutating it — so a `PASTE` of content cut in
+     * an earlier edit call (or an earlier section of this patch) renders the
+     * real rows.
+     */
+    clipboard?: Clipboard;
 }
 /**
  * Per-file projection of a streamed edit payload. Pairs one target file path

package/dist/types/export/html/index.d.ts

@@ -3,6 +3,8 @@ import type { SessionEntry, SessionHeader } from "../../session/session-entries.
 import { SessionManager } from "../../session/session-manager.js";
 import type { ExportThemeNames } from "./args.js";
 export { type ExportThemeNames, parseExportArgs } from "./args.js";
+/** Resolve a Bun file-loader value without parsing Windows drive letters as URL schemes. */
+export declare function resolveBundledHtmlAssetPath(assetPath: string, moduleDir?: string): string;
 /** Compose the standalone export template: minified CSS, tool renderers, and viewer JS inlined. */
 export declare function getTemplate(): string;
 export interface ExportOptions {

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

@@ -8,9 +8,10 @@ import type { ModelRegistry } from "../../config/model-registry.js";
 import type { Settings } from "../../config/settings.js";
 import type { LocalProtocolOptions } from "../../internal-urls/local-protocol.js";
 import type { MemoryRuntimeContext } from "../../memory-backend/index.js";
+import type { AsyncJobSnapshot } from "../../session/agent-session.js";
 import type { SessionManager } from "../../session/session-manager.js";
 import type { BranchHandler, NavigateTreeHandler, NewSessionHandler } from "../session-handler-types.js";
-import type { AfterProviderResponseEvent, AssistantThinkingRenderer, BeforeAgentStartEvent, BeforeAgentStartEventResult, BeforeProviderRequestEvent, BeforeProviderRequestEventResult, ContextEvent, Extension, ExtensionActions, ExtensionCommandContext, ExtensionCommandContextActions, ExtensionContext, ExtensionContextActions, ExtensionError, ExtensionEvent, ExtensionFlag, ExtensionRuntime, ExtensionShortcut, ExtensionUIContext, InputEvent, InputEventResult, MessageRenderer, RegisteredCommand, RegisteredTool, ResourcesDiscoverEvent, SessionBeforeBranchResult, SessionBeforeCompactResult, SessionBeforeSwitchResult, SessionBeforeTreeResult, SessionCompactingResult, SessionStopEvent, SessionStopEventResult, ToolCallEvent, ToolCallEventResult, ToolResultEvent, ToolResultEventResult, UserBashEvent, UserBashEventResult, UserPythonEvent, UserPythonEventResult } from "./types.js";
+import type { AfterProviderResponseEvent, AssistantThinkingRenderer, BeforeAgentStartEvent, BeforeAgentStartEventResult, BeforeProviderRequestEvent, BeforeProviderRequestEventResult, ContextEvent, Extension, ExtensionActions, ExtensionCommandContext, ExtensionCommandContextActions, ExtensionContext, ExtensionContextActions, ExtensionError, ExtensionEvent, ExtensionFlag, ExtensionRuntime, ExtensionShortcut, ExtensionUIContext, InputEvent, InputEventResult, McpNotificationEvent, MessageRenderer, RegisteredCommand, RegisteredTool, ResourcesDiscoverEvent, SessionBeforeBranchResult, SessionBeforeCompactResult, SessionBeforeSwitchResult, SessionBeforeTreeResult, SessionCompactingResult, SessionStopEvent, SessionStopEventResult, ToolCallEvent, ToolCallEventResult, ToolResultEvent, ToolResultEventResult, UserBashEvent, UserBashEventResult, UserPythonEvent, UserPythonEventResult } from "./types.js";
 /** Combined result from all before_agent_start handlers */
 interface BeforeAgentStartCombinedResult {
     messages?: NonNullable<BeforeAgentStartEventResult["message"]>[];
@@ -73,7 +74,7 @@ export declare class ExtensionRunner {
     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);
+    constructor(extensions: Extension[], runtime: ExtensionRuntime, cwd: string, sessionManager: SessionManager, modelRegistry: ModelRegistry, getMemory?: () => MemoryRuntimeContext | undefined, settings?: Settings | undefined, localProtocolOptions?: LocalProtocolOptions | undefined, getAsyncJobSnapshot?: () => AsyncJobSnapshot | null);
     initialize(actions: ExtensionActions, contextActions: ExtensionContextActions, commandContextActions?: ExtensionCommandContextActions, uiContext?: ExtensionUIContext): void;
     /**
      * Forward a `credential_disabled` event from `AuthStorage` to extension handlers.
@@ -90,6 +91,22 @@ export declare class ExtensionRunner {
      * {@link onError} via {@link emit}'s normal isolation.
      */
     emitCredentialDisabled(event: CredentialDisabledEvent): Promise<void>;
+    /**
+     * Forward an MCP server notification to extension handlers.
+     *
+     * If {@link initialize} has not yet run, the notification is buffered and replayed
+     * once initialize wires the runtime/UI context. Matches the credential-disabled
+     * deferral above: the sdk.ts bridge registers `MCPManager.addNotificationListener`
+     * inside `createAgentSession` — BEFORE the mode controller calls `initialize()` on
+     * this runner — so notification frames drained by the manager (either fresh
+     * arrivals or replay from its own startup buffer) can reach us pre-init. Without
+     * this buffer they would evaporate for a second time here.
+     *
+     * Bounded at {@link MAX_PENDING_MCP_NOTIFICATIONS}; oldest entries drop under
+     * pressure. Never throws; per-handler errors are routed through {@link onError}
+     * via {@link emit}'s normal isolation.
+     */
+    emitMcpNotification(event: Omit<McpNotificationEvent, "type">): Promise<void>;
     /** Emits a session stop pass that can be cancelled with the active settle signal. */
     emitSessionStop(event: Omit<SessionStopEvent, "type">): Promise<SessionStopEventResult | undefined>;
     getUIContext(): ExtensionUIContext;

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

@@ -26,6 +26,7 @@ import type { LocalProtocolOptions } from "../../internal-urls/local-protocol.js
 import type { MemoryRuntimeContext } from "../../memory-backend/index.js";
 import type { CustomEditor } from "../../modes/components/custom-editor.js";
 import type { Theme } from "../../modes/theme/theme.js";
+import type { AsyncJobSnapshot } from "../../session/agent-session.js";
 import type { CompactMode } from "../../session/compact-modes.js";
 import type { CustomMessage, CustomMessagePayload } from "../../session/messages.js";
 import type { ReadonlySessionManager, SessionManager } from "../../session/session-manager.js";
@@ -276,6 +277,8 @@ export interface ExtensionContext {
     ui: ExtensionUIContext;
     /** Get current context usage for the active model. */
     getContextUsage(): ContextUsage | undefined;
+    /** Get a read-only snapshot of async jobs owned by this session. */
+    getAsyncJobSnapshot(): AsyncJobSnapshot | null;
     /** Compact the session context (interactive mode shows UI). */
     compact(instructionsOrOptions?: string | CompactOptions): Promise<void>;
     /** Whether UI is available (false in print/RPC mode) */
@@ -494,6 +497,26 @@ export interface CredentialDisabledEvent {
     /** Verbatim error captured for forensics (truncated upstream). */
     disabledCause: string;
 }
+/**
+ * Fired for every JSON-RPC notification received from a connected MCP server,
+ * AFTER the runtime's own handling of known list/update methods. Unknown or
+ * server-custom methods are delivered too — extensions can bridge them into
+ * session behavior by inspecting `method`/`params` and injecting a follow-up
+ * via `pi.sendMessage(..., { deliverAs })` or `pi.sendUserMessage(...)`.
+ */
+export interface McpNotificationEvent {
+    type: "mcp_notification";
+    /**
+     * Server name as declared in the MCP config (raw, unsanitized). Note this
+     * differs from the sanitized prefix used in `mcp__<sanitized_server>_<tool>`
+     * tool names — filter by this raw name, not by tool-name prefix matching.
+     */
+    server: string;
+    /** JSON-RPC method (e.g. `notifications/tools/list_changed`, or server-custom). */
+    method: string;
+    /** JSON-RPC params, opaque to the runtime. */
+    params: unknown;
+}
 /** Fired when user executes a bash command via ! or !! prefix */
 export interface UserBashEvent {
     type: "user_bash";
@@ -639,7 +662,7 @@ export declare function isToolCallEventType<TName extends string, TInput extends
     input: TInput;
 };
 /** Union of all event types */
-export type ExtensionEvent = ResourcesDiscoverEvent | SessionEvent | ContextEvent | BeforeProviderRequestEvent | AfterProviderResponseEvent | BeforeAgentStartEvent | AgentStartEvent | AgentEndEvent | SessionStopEvent | TurnStartEvent | TurnEndEvent | MessageStartEvent | MessageUpdateEvent | MessageEndEvent | ToolExecutionStartEvent | ToolExecutionUpdateEvent | ToolExecutionEndEvent | AutoCompactionStartEvent | AutoCompactionEndEvent | AutoRetryStartEvent | AutoRetryEndEvent | TtsrTriggeredEvent | TodoReminderEvent | GoalUpdatedEvent | CredentialDisabledEvent | UserBashEvent | UserPythonEvent | InputEvent | ToolCallEvent | ToolResultEvent | ToolApprovalRequestedEvent | ToolApprovalResolvedEvent;
+export type ExtensionEvent = ResourcesDiscoverEvent | SessionEvent | ContextEvent | BeforeProviderRequestEvent | AfterProviderResponseEvent | BeforeAgentStartEvent | AgentStartEvent | AgentEndEvent | SessionStopEvent | TurnStartEvent | TurnEndEvent | MessageStartEvent | MessageUpdateEvent | MessageEndEvent | ToolExecutionStartEvent | ToolExecutionUpdateEvent | ToolExecutionEndEvent | AutoCompactionStartEvent | AutoCompactionEndEvent | AutoRetryStartEvent | AutoRetryEndEvent | TtsrTriggeredEvent | TodoReminderEvent | GoalUpdatedEvent | CredentialDisabledEvent | McpNotificationEvent | UserBashEvent | UserPythonEvent | InputEvent | ToolCallEvent | ToolResultEvent | ToolApprovalRequestedEvent | ToolApprovalResolvedEvent;
 export interface ContextEventResult {
     messages?: AgentMessage[];
 }
@@ -748,6 +771,7 @@ export interface ExtensionAPI {
     on(event: "tool_result", handler: ExtensionHandler<ToolResultEvent, ToolResultEventResult>): void;
     on(event: "user_bash", handler: ExtensionHandler<UserBashEvent, UserBashEventResult>): void;
     on(event: "user_python", handler: ExtensionHandler<UserPythonEvent, UserPythonEventResult>): void;
+    on(event: "mcp_notification", handler: ExtensionHandler<McpNotificationEvent>): void;
     /** Register a tool that the LLM can call. */
     registerTool<TParams extends TSchema = TSchema, TDetails = unknown>(tool: ToolDefinition<TParams, TDetails>): void;
     /** Register a custom command. */

package/dist/types/extensibility/legacy-pi-ai-shim.d.ts

@@ -19,7 +19,7 @@
  * `types.ts` via the `export *` below — pi-ai still exports both as types,
  * only the runtime `Type` builder and `StringEnum()` helper were removed.
  */
-import type { Api, Model } from "@oh-my-pi/pi-ai";
+import type { Api, AssistantMessage, Model } from "@oh-my-pi/pi-ai";
 import type { Effort } from "@oh-my-pi/pi-catalog/effort";
 import { calculateCost, getBundledModel, getBundledModels, getBundledProviders, modelsAreEqual } from "@oh-my-pi/pi-catalog/models";
 import { type TSchema, Type } from "./typebox.js";
@@ -32,6 +32,15 @@ export interface StringEnumOptions<T extends string> {
 export declare function StringEnum<T extends string | number>(values: readonly T[] | Record<string, T>, options?: StringEnumOptions<any>): TSchema;
 /** Clamp a historical Pi thinking level against OMP's model metadata. */
 export declare function clampThinkingLevel<TApi extends Api>(model: Model<TApi>, level: Effort | "off"): Effort | "off";
+/**
+ * Compatibility implementation of historical pi-ai's `isRetryableAssistantError`.
+ *
+ * Classifies whether a failed assistant message looks like a transient provider
+ * or transport error so legacy extensions can decide if the last assistant turn
+ * should be restarted. Account/quota limits are treated as non-retryable. This
+ * does not implement any retry policy; callers own budget, backoff, and reporting.
+ */
+export declare function isRetryableAssistantError(message: AssistantMessage): boolean;
 export * from "@oh-my-pi/pi-ai";
 /**
  * Compatibility re-exports for catalog symbols that pi-ai historically exposed
@@ -45,3 +54,20 @@ export * from "@oh-my-pi/pi-ai";
 export { calculateCost, getBundledModel, getBundledModels, getBundledProviders, modelsAreEqual, Type };
 export declare const getModel: typeof getBundledModel;
 export declare const getModels: typeof getBundledModels;
+/**
+ * Compatibility re-exports for runtime helpers that upstream
+ * `@earendil-works/pi-ai` exposed from its package root but omp's
+ * `@oh-my-pi/pi-ai` barrel no longer forwards. Each symbol still exists in the
+ * host graph — only its root re-export was dropped — so bridging it here keeps
+ * legacy extensions importing it from the pi-ai root resolving through Bun's
+ * static named-export check (e.g. `omp plugin install pi-blackhole`).
+ *
+ * This is the full set derived from an audit of the upstream root surface: the
+ * error-classification predicate `isContextOverflow` (now under
+ * `@oh-my-pi/pi-ai/error`) and the JSON-repair helpers that omp relocated to
+ * `@oh-my-pi/pi-utils`. Upstream root symbols with no omp equivalent are
+ * intentionally not shimmed — the package has diverged and there is nothing to
+ * forward.
+ */
+export { isContextOverflow } from "@oh-my-pi/pi-ai/error";
+export { parseJsonWithRepair, parseStreamingJson, repairJson } from "@oh-my-pi/pi-utils";

package/dist/types/extensibility/legacy-pi-coding-agent-shim.d.ts

@@ -376,6 +376,8 @@ export { getProjectDir } from "@oh-my-pi/pi-utils";
  */
 export declare function getPackageDir(): string;
 export { estimateTokens } from "@oh-my-pi/pi-agent-core/compaction";
+export { CONFIG_DIR_NAME } from "@oh-my-pi/pi-utils";
+export { parseArgs } from "../cli/args.js";
 export * from "../index.js";
 export { formatBytes as formatSize } from "../tools/render-utils.js";
 export { copyToClipboard } from "../utils/clipboard.js";

package/dist/types/internal-urls/local-protocol.d.ts

@@ -47,8 +47,9 @@ export declare class LocalProtocolHandler implements ProtocolHandler {
     readonly immutable = false;
     /**
      * Install a process-global override that wins over the AgentRegistry-based
-     * derivation. Used by SDK consumers that wire `localProtocolOptions` on
-     * `createAgentSession` and by subagents that share their parent's root.
+     * derivation. Used by top-level SDK consumers that wire
+     * `localProtocolOptions` on `createAgentSession`; subagents keep their
+     * inherited mapping session-bound.
      */
     static setOverride(value: LocalProtocolOptions | undefined): void;
     /** Reset the process-global override. Test-only. */

package/dist/types/launch/terminal-output-worker-client.d.ts

@@ -0,0 +1,5 @@
+import type { TerminalOutputOptions } from "./terminal-output.js";
+/** Replay legacy broker PTY bytes without evaluating xterm in the client process. */
+export declare function renderTerminalOutputIsolated(output: string, options: TerminalOutputOptions): Promise<string[] | undefined>;
+/** Distribution smoke for source, npm-bundle, and compiled worker routing. */
+export declare function smokeTestTerminalOutputWorker(): Promise<void>;

package/dist/types/launch/terminal-output-worker-protocol.d.ts

@@ -0,0 +1,14 @@
+import type { TerminalOutputOptions } from "./terminal-output.js";
+/** Hidden CLI selector for legacy PTY replay outside the client process. */
+export declare const TERMINAL_OUTPUT_WORKER_ARG = "__omp_worker_terminal_output";
+export interface TerminalOutputWorkerRequest {
+    output: string;
+    options: TerminalOutputOptions;
+}
+export type TerminalOutputWorkerResult = {
+    ok: true;
+    rows: string[] | undefined;
+} | {
+    ok: false;
+    error: string;
+};

package/dist/types/launch/terminal-output-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/lsp/client.d.ts

@@ -19,6 +19,8 @@ export interface WatchedFileChange {
 export declare function supportsDocumentDiagnostics(client: LspClient): boolean;
 /** Timeout for warmup initialize requests (5 seconds) */
 export declare const WARMUP_TIMEOUT_MS = 5000;
+/** Allow an explicit user reload to retry a matching initialization failure immediately. */
+export declare function clearInitializationFailure(config: ServerConfig, cwd: string): void;
 /**
  * Get or create an LSP client for the given server configuration and working directory.
  * @param config - Server configuration

package/dist/types/main.d.ts

@@ -8,6 +8,7 @@ import type { SubmittedUserInput } from "./modes/types.js";
 import { type CreateAgentSessionOptions, type CreateAgentSessionResult, createAgentSession, discoverAuthStorage } from "./sdk.js";
 import type { AgentSession } from "./session/agent-session.js";
 import type { AuthStorage } from "./session/auth-storage.js";
+import type { ForeignSessionSource, ForeignSessionStore } from "./session/foreign-session-store.js";
 import { type SessionInfo } from "./session/session-listing.js";
 import { SessionManager } from "./session/session-manager.js";
 type RunAcpMode = (createSession: AcpSessionFactory) => Promise<never>;
@@ -65,6 +66,7 @@ interface RunRootCommandDependencies {
     discoverAuthStorage?: typeof discoverAuthStorage;
     selectSession?: typeof selectSession;
     runAcpMode?: RunAcpMode;
+    createForeignSessionStore?: (source: ForeignSessionSource) => ForeignSessionStore;
     settings?: Settings;
     forceSetupWizard?: boolean;
 }

package/dist/types/mcp/manager.d.ts

@@ -61,13 +61,42 @@ export declare class MCPManager {
     static resetForTests(): void;
     constructor(cwd: string, toolCache?: MCPToolCache | null);
     /**
-     * Set a callback to receive all server notifications.
+     * Register a listener for server-initiated MCP notifications.
+     *
+     * The listener is called for every JSON-RPC notification received from any
+     * connected server, AFTER the manager's own handling of known methods
+     * (`notifications/tools/list_changed`, `notifications/resources/list_changed`,
+     * `notifications/resources/updated`, `notifications/prompts/list_changed`).
+     * For list-change methods the internal refresh promise is awaited before
+     * fanout, so listeners observe up-to-date manager and tool state. Unknown
+     * or server-custom methods are also delivered, letting consumers bridge
+     * server-initiated events into session-level behavior (e.g. an extension
+     * injecting a steer via `pi.sendMessage`).
+     *
+     * Notifications received before any listener attached are buffered
+     * (bounded FIFO, cap {@link NOTIFICATION_BUFFER_CAP}, drop-oldest) and
+     * drained into the first subscriber — matches {@link setOnPromptsChanged}'s
+     * replay-on-attach and {@link IrcBus}'s mailbox semantics.
+     *
+     * Returns an unsubscribe function; call it to remove the listener.
+     *
+     * Multiple listeners are allowed; each is invoked with independent error
+     * isolation — a listener that throws does not prevent other listeners from
+     * firing.
      */
-    setOnNotification(handler: (serverName: string, method: string, params: unknown) => void): void;
+    addNotificationListener(listener: (serverName: string, method: string, params: unknown) => void): () => void;
     /**
      * Set a callback to fire when any server's tools change.
-     */
-    setOnToolsChanged(handler: (tools: CustomTool<TSchema, MCPToolDetails>[]) => void): void;
+     *
+     * May return a Promise; if so, {@link refreshServerTools} awaits it so that
+     * downstream consumers (e.g. `mcp_notification` listeners for
+     * `notifications/tools/list_changed`) observe not just the manager's
+     * refreshed tool set but also any session-level rebind driven by the
+     * handler (`session.refreshMCPTools`). Other callsites (initial connect,
+     * disconnect, reconnect) invoke the handler synchronously — their downstream
+     * chains don't need to serialize on the rebind.
+     */
+    setOnToolsChanged(handler: (tools: CustomTool<TSchema, MCPToolDetails>[]) => void | Promise<void>): void;
     /**
      * Set a callback to fire when any server's resources change.
      */