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

package/dist/{template-dys3vk5b.js → template-8vdv6xb4.js}

@@ -395,7 +395,7 @@
           }
 
           // Apply filter mode
-          const isSettingsEntry = ['label', 'custom', 'model_change', 'thinking_level_change', 'mode_change', 'ttsr_injection', 'session_init'].includes(entry.type);
+          const isSettingsEntry = ['label', 'custom', 'model_change', 'thinking_level_change', 'mode_change', 'ttsr_injection', 'session_init', 'credential_pin'].includes(entry.type);
           let passesFilter = true;
 
           switch (filterMode) {

package/dist/types/advisor/runtime.d.ts

@@ -38,7 +38,7 @@ export interface AdvisorRuntimeHost {
      * recovery path must never replay the full primary transcript.
      * Optional: hosts that omit it get no proactive maintenance.
      */
-    maintainContext?(incomingTokens: number): Promise<boolean>;
+    maintainContext?(incomingTokens: number, signal: AbortSignal): Promise<boolean>;
     /**
      * Called immediately before each `agent.prompt(batch)` cycle. Lets the host
      * clear per-update advisor state — currently the one-advise-per-update gate
@@ -55,7 +55,7 @@ export interface AdvisorRuntimeHost {
      * failed prompt's appended turns before rollback. Errors thrown here are
      * logged and swallowed.
      */
-    onTurnError?(error: unknown, failedMessages: readonly AgentMessage[]): Promise<boolean | undefined> | boolean | undefined;
+    onTurnError?(error: unknown, failedMessages: readonly AgentMessage[], signal: AbortSignal): Promise<boolean | undefined> | boolean | undefined;
     /** Called after a successful advisor turn so the host can finish fallback lifecycle reporting. */
     onTurnSuccess?(): Promise<void> | void;
     /** Surface a non-recovering advisor failure to the host UI without adding model-visible context. */
@@ -64,6 +64,8 @@ export interface AdvisorRuntimeHost {
      *  recovery (credential switch, fallback chain) declined. Cleared only by
      *  an explicit reset (`/new`, config rebuild, session restart). */
     notifyQuotaExhausted?(): void;
+    /** Stable identity for the live advisor model. Used to restore full transcript rendering after a model switch. */
+    getModelIdentity?(): string;
 }
 /** Signals that an advisor response was discarded before it could become model-visible context. */
 export declare class AdvisorOutputQuarantinedError extends Error {
@@ -116,6 +118,10 @@ export declare class AdvisorRuntime {
      */
     waitForCatchup(maxMs: number, threshold: number, signal?: AbortSignal): Promise<boolean>;
     dispose(): void;
+    /** Stop new advisor work and wait only for the active prompt's recorder-visible events. */
+    pauseForSessionTransition(): Promise<void>;
+    /** Continue queued work after a session transition rolls back or preserves the conversation. */
+    resumeAfterSessionTransition(): void;
     /**
      * Re-prime the advisor after a history rewrite (compaction, session
      * switch/resume, branch). Clears the advisor's own (non-persisted) context

package/dist/types/advisor/transcript-recorder.d.ts

@@ -14,6 +14,21 @@ export declare const ADVISOR_TRANSCRIPT_FILENAME = "__advisor.jsonl";
 export declare function advisorTranscriptFilename(slug: string): string;
 /** Whether a filename is any advisor transcript (`__advisor.jsonl` or `__advisor.<slug>.jsonl`). */
 export declare function isAdvisorTranscriptName(name: string): boolean;
+/**
+ * Sum the advisor spend already persisted next to a primary session transcript,
+ * keyed by advisor slug.
+ *
+ * The ledger a session keeps in memory only covers the current process, so a
+ * resumed session would report zero until the next advisor turn. The recorded
+ * transcripts are the durable copy of exactly the same finalized messages, so
+ * they are read back through the shared loader - no lock, no writer, and no
+ * second parser to keep in step with the session format.
+ *
+ * Only the session's own advisors count: subagent advisors write to
+ * `<session>/<SubId>/__advisor.jsonl`, and their spend belongs to the subagent,
+ * not to this roster. Hence the scan stays at the top level of the directory.
+ */
+export declare function loadAdvisorTranscriptCosts(sessionFile: string | undefined): Promise<Map<string, number>>;
 /**
  * Append-only persister for an advisor agent's transcript.
  *

package/dist/types/auto-thinking/classifier.d.ts

@@ -5,7 +5,8 @@
  * {@link Effort}, clamped into the active model's supported range (never below
  * {@link Effort.Low}). Two backends, selected by `providers.autoThinkingModel`:
  *
- * - `online` (default): a smol model classifies into `low|medium|high|xhigh`.
+ * - `online` (default): a smol model classifies into `low|medium|high|xhigh`,
+ *   plus `max` when the target model exposes that tier.
  * - a local key: an on-device memory model classifies into the coarser
  *   `trivial|moderate|hard` scheme (3-class is more reliable than 4-way ordinal
  *   on sub-2B models), mapped to `low|high|xhigh`.
@@ -31,7 +32,13 @@ export interface ClassifyDifficultyDeps {
  * @throws when the backend cannot produce a usable classification.
  */
 export declare function classifyDifficulty(promptText: string, deps: ClassifyDifficultyDeps): Promise<Effort | undefined>;
-/** Map the online 4-way level keyword to an {@link Effort}; earliest match wins. */
+/**
+ * Map an online level keyword to an {@link Effort}; earliest match wins.
+ *
+ * `max` is only offered to the classifier when the target model exposes that
+ * tier, but it is always parsed: an unsupported `max` is snapped back down by
+ * {@link clampAutoThinkingEffort} rather than failing the turn.
+ */
 export declare function parseDifficultyLevel(text: string): Effort | undefined;
 /** Map the local 3-way bucket keyword to an {@link Effort}; earliest match wins. */
 export declare function parseDifficultyBucket(text: string): Effort | undefined;

package/dist/types/cli/args.d.ts

@@ -27,6 +27,8 @@ export interface Args {
     advisor?: boolean;
     continue?: boolean;
     resume?: string | true;
+    fromClaude?: boolean;
+    fromCodex?: boolean;
     help?: boolean;
     version?: boolean;
     mode?: Mode;

package/dist/types/cli/session-picker.d.ts

@@ -1,11 +1,18 @@
 import type { SessionInfo } from "../session/session-listing.js";
+/** Presentation and capability controls for the standalone session picker. */
+export interface SessionPickerOptions {
+    allSessions?: SessionInfo[];
+    title?: string;
+    scopeLabel?: string | false;
+    showCwd?: boolean;
+    allowDelete?: boolean;
+    allowGlobalScope?: boolean;
+    historySearch?: boolean;
+}
 /**
  * Show the TUI session selector and return the selected session, or null if
- * cancelled. Rendered as a fullscreen overlay on the terminal's alternate
- * screen, so the list scrolls and rows are clickable with the mouse. Tab
- * toggles between current-folder and all-projects scope; the all-projects list
- * is loaded lazily via `SessionManager.listAll`.
+ * cancelled. The default OMP picker supports deletion, transcript-history
+ * search, and an all-projects scope; foreign import pickers disable those
+ * source-owned capabilities.
  */
-export declare function selectSession(sessions: SessionInfo[], options?: {
-    allSessions?: SessionInfo[];
-}): Promise<SessionInfo | null>;
+export declare function selectSession(sessions: SessionInfo[], options?: SessionPickerOptions): Promise<SessionInfo | null>;

package/dist/types/collab/guest.d.ts

@@ -10,6 +10,7 @@ export interface GuestIdleReconcilerCtx {
     statusLine: {
         markActivityEnd: () => void;
     };
+    statusContainer: Pick<InteractiveModeContext["statusContainer"], "disposeChildren">;
     loadingAnimation: {
         stop: () => void;
     } | undefined;
@@ -17,8 +18,8 @@ export interface GuestIdleReconcilerCtx {
 /**
  * Close the guest UI state held open by an earlier `agent_start` whose
  * matching `agent_end` never reached us — most often because a reconnect
- * dropped the event mid-stream. Triggered from {@link CollabGuestLink}'s
- * `state` reconciler when the host reports `isStreaming === false`:
+ * dropped the event mid-stream. Reached via {@link reconcileGuestSnapshotHostState}
+ * (the live `state`-frame and welcome/resync reconciler) when the host reports `isStreaming === false`:
  * folds the in-flight active-time window into the per-session meter (so
  * `time_spent` stops ticking) and stops the `Working…` loader if one is
  * still animating. No-op when the host is still streaming.
@@ -32,7 +33,25 @@ export interface GuestSnapshotActivityReconcilerCtx extends GuestIdleReconcilerC
     statusLine: GuestIdleReconcilerCtx["statusLine"] & {
         markActivityStart: () => void;
     };
+    /**
+     * Start (or re-attach) the live "Working…" loader. Mirrors
+     * `InteractiveModeContext.ensureLoadingAnimation`, which is what
+     * `EventController` calls on `agent_start`. Required so a guest that
+     * missed an earlier `agent_start` (a reconnect dropped it mid-stream)
+     * starts its spinner when the host later reports it is streaming.
+     */
+    ensureLoadingAnimation: InteractiveModeContext["ensureLoadingAnimation"];
+    autoCompactionLoader: InteractiveModeContext["autoCompactionLoader"];
+    retryLoader: InteractiveModeContext["retryLoader"];
 }
+/** Status-area state which cannot outlive removal of its child components. */
+export interface GuestTransientStatusCtx {
+    statusContainer: Pick<InteractiveModeContext["statusContainer"], "clear">;
+    autoCompactionLoader: InteractiveModeContext["autoCompactionLoader"];
+    retryLoader: InteractiveModeContext["retryLoader"];
+}
+/** Stop and forget status-area loaders before detaching their components. */
+export declare function clearGuestTransientStatus(ctx: GuestTransientStatusCtx): void;
 export declare function reconcileGuestSnapshotHostState(ctx: GuestSnapshotActivityReconcilerCtx, isStreaming: boolean): void;
 export declare class CollabGuestLink {
     #private;

package/dist/types/commands/launch.d.ts

@@ -88,6 +88,12 @@ export default class Index extends Command {
             char: string;
             description: string;
         };
+        "from-claude": import("@oh-my-pi/pi-utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
+        "from-codex": import("@oh-my-pi/pi-utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
         "session-dir": import("@oh-my-pi/pi-utils/cli").FlagDescriptor<"string"> & {
             description: string;
         };

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

@@ -839,6 +839,16 @@ export declare const SETTINGS_SCHEMA: {
             readonly description: "Render Mermaid fenced code blocks as ASCII diagrams";
         };
     };
+    readonly "tui.codexResetFireworks": {
+        readonly type: "boolean";
+        readonly default: false;
+        readonly ui: {
+            readonly tab: "appearance";
+            readonly group: "Display";
+            readonly label: "Codex Reset Fireworks";
+            readonly description: "Celebrate unscheduled Codex weekly usage resets and newly banked saved resets with a top-third fireworks overlay that remains until Escape";
+        };
+    };
     readonly "tui.titleState": {
         readonly type: "boolean";
         readonly default: true;
@@ -1796,14 +1806,28 @@ export declare const SETTINGS_SCHEMA: {
             }];
         };
     };
-    readonly collapseChangelog: {
-        readonly type: "boolean";
-        readonly default: false;
+    readonly "startup.changelogMode": {
+        readonly type: "enum";
+        readonly values: readonly ["summary", "expanded", "hidden"];
+        readonly default: "summary";
         readonly ui: {
             readonly tab: "interaction";
             readonly group: "Startup & Updates";
-            readonly label: "Collapse Changelog";
-            readonly description: "Show condensed changelog after updates";
+            readonly label: "Startup Changelog";
+            readonly description: "Choose whether update notes start as a summary, full details, or stay hidden";
+            readonly options: readonly [{
+                readonly value: "summary";
+                readonly label: "Summary";
+                readonly description: "Show release and change counts with a /changelog hint";
+            }, {
+                readonly value: "expanded";
+                readonly label: "Expanded";
+                readonly description: "Show the recent release notes in full";
+            }, {
+                readonly value: "hidden";
+                readonly label: "Hidden";
+                readonly description: "Do not show release notes on startup";
+            }];
         };
     };
     readonly "magicKeywords.enabled": {
@@ -4147,6 +4171,16 @@ export declare const SETTINGS_SCHEMA: {
             readonly description: "Enable the browser tool for scripted Chromium automation (puppeteer)";
         };
     };
+    readonly "browser.cdpUrl": {
+        readonly type: "string";
+        readonly default: undefined;
+        readonly ui: {
+            readonly tab: "tools";
+            readonly group: "Grep & Browser";
+            readonly label: "Browser CDP URL";
+            readonly description: "Default HTTP CDP discovery endpoint (for example http://127.0.0.1:9222) to attach to instead of launching a browser. Explicit app.cdp_url or app.path on the tool call take precedence.";
+        };
+    };
     readonly "browser.headless": {
         readonly type: "boolean";
         readonly default: true;
@@ -4717,7 +4751,7 @@ export declare const SETTINGS_SCHEMA: {
             readonly tab: "tasks";
             readonly group: "Subagents";
             readonly label: "Soft Subagent Request Budget";
-            readonly description: "Soft per-subagent request budget (assistant requests per run). Crossing it injects a wrap-up steering notice (see task.softRequestBudgetNotice); at 1.5x the budget the run is force-stopped and the agent must yield its partial findings. 0 disables the guard. Bundled scout/sonic agents use a lower built-in budget.";
+            readonly description: "Soft per-subagent request budget (assistant requests per run). Crossing it injects a wrap-up steering notice (see task.softRequestBudgetNotice); at 1.5x the budget the run is force-stopped and the agent must yield its partial findings. 0 disables the guard. Bundled scout/sonic agents cap out at a lower built-in budget, so a value below that cap still applies to them.";
             readonly options: readonly [{
                 readonly value: "0";
                 readonly label: "Disabled";
@@ -4970,7 +5004,7 @@ export declare const SETTINGS_SCHEMA: {
             } | {
                 readonly value: "exa";
                 readonly label: "Exa";
-                readonly description: "Uses Exa API when EXA_API_KEY is set; falls back to Exa MCP";
+                readonly description: "API via /login exa or EXA_API_KEY; explicit keyless fallback via MCP";
             } | {
                 readonly value: "tinyfish";
                 readonly label: "TinyFish";
@@ -5074,7 +5108,7 @@ export declare const SETTINGS_SCHEMA: {
             } | {
                 readonly value: "exa";
                 readonly label: "Exa";
-                readonly description: "Uses Exa API when EXA_API_KEY is set; falls back to Exa MCP";
+                readonly description: "API via /login exa or EXA_API_KEY; explicit keyless fallback via MCP";
             } | {
                 readonly value: "tinyfish";
                 readonly label: "TinyFish";
@@ -5580,6 +5614,27 @@ export declare const SETTINGS_SCHEMA: {
             })[];
         };
     };
+    readonly "providers.autoThinkingMaxEffort": {
+        readonly type: "enum";
+        readonly values: readonly ["xhigh", "max"];
+        readonly default: "xhigh";
+        readonly ui: {
+            readonly tab: "model";
+            readonly group: "Thinking";
+            readonly label: "Auto Thinking Ceiling";
+            readonly description: "Highest effort the `auto` classifier may resolve. `xhigh` keeps the classifier one tier below the top, so only an explicit `ultrathink` reaches `max`; `max` lets a turn the classifier judges exceptional bill the top tier on models that expose it.";
+            readonly condition: "autoThinkingActive";
+            readonly options: readonly [{
+                readonly value: "xhigh";
+                readonly label: "xhigh";
+                readonly description: "Classifier stops at xhigh (default)";
+            }, {
+                readonly value: "max";
+                readonly label: "max";
+                readonly description: "Classifier may resolve max where the model supports it";
+            }];
+        };
+    };
     readonly "features.unexpectedStopDetection": {
         readonly type: "boolean";
         readonly default: false;

package/dist/types/cursor-bridge-tools.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Per-call tools the Cursor exec bridge needs but the model-facing registry
+ * cannot supply.
+ *
+ * Both bridge callsites — the primary session and the advisor roster — build
+ * the same instances, and both must apply the session's approval wrapper. A
+ * raw tool here silently escapes the gate every registry call goes through, so
+ * the construction lives in one place rather than being repeated per callsite.
+ */
+import type { AgentTool } from "@oh-my-pi/pi-agent-core";
+import type { ExtensionRunner } from "./extensibility/extensions/index.js";
+import type { GrepToolOptions, ToolSession } from "./tools/index.js";
+/**
+ * Build the bridge's `createGrepTool` factory for one tool session.
+ *
+ * A `pi_grep` frame carries its own context width and total match cap. Neither
+ * is expressible in the model-facing `grep` schema — context comes from
+ * `grep.contextBefore`/`grep.contextAfter`, fixed when the shared instance is
+ * constructed — so honoring them needs a fresh tool per call.
+ *
+ * The result is wrapped exactly like a registry tool: the approval gate runs on
+ * every call site, and a per-call instance is no exception.
+ */
+export declare function createBridgeGrepFactory(session: ToolSession, extensionRunner: ExtensionRunner): (options: GrepToolOptions) => AgentTool;
+/**
+ * Build the `replace`-mode `edit` the bridge answers `pi_edit` with.
+ *
+ * `PiEditExecArgs` carries `old_text`/`new_text` pairs, which is exactly
+ * `replace`'s schema and nothing else's. The session's own instance follows the
+ * configured `edit.mode` — `hashline` by default, whose schema is a single
+ * `input` string — so a frame handed that instance fails validation instead of
+ * editing the file.
+ *
+ * Callers MUST gate this on the session having actually granted `edit`: the
+ * tool is constructed rather than looked up, so building one unconditionally
+ * hands a restricted agent a mutating tool it was denied (issue #5680).
+ */
+export declare function createBridgeEditTool(session: ToolSession, extensionRunner: ExtensionRunner): AgentTool;
+/**
+ * The tool map the exec bridge should run, given the map a caller granted.
+ *
+ * `pi_edit` needs a `replace`-mode instance, but only when `edit` was granted:
+ * the tool is constructed rather than looked up, so substituting
+ * unconditionally would hand a restricted roster a mutating tool it was denied
+ * (issue #5680). The granted map is never mutated: an unsubstituted result is a
+ * copy, so a caller without an `edit` grant cannot accidentally gain one.
+ *
+ * The advisor roster passes its granted map here; the primary session keeps its
+ * instance out of the registry entirely (Cursor does not advertise `edit`) and
+ * serves it through the bridge's `getEditReplaceTool` accessor instead — not
+ * the `getTool` fallback, which doubles as the agent loop's resolver for
+ * unadvertised calls and must stay device-only.
+ */
+export declare function bridgeToolMap(granted: ReadonlyMap<string, AgentTool>, createEditTool: (() => AgentTool | undefined) | undefined): Map<string, AgentTool>;

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 {};