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

package/dist/types/session/tool-choice-queue.d.ts

@@ -8,14 +8,14 @@ export interface RejectInfo {
     choice: ToolChoice;
     reason: "aborted" | "error" | "cleared" | "removed" | "unavailable" | "not_invoked";
 }
-/** "requeue" replays the lost yield next turn; "drop" (or void/undefined) discards it. */
-export type RejectOutcome = "requeue" | "drop";
+/** Controls whether rejection replays a yield, drops it, or drops its remaining sequence. */
+export type RejectOutcome = "requeue" | "drop" | "drop_sequence";
 export interface DirectiveCallbacks {
     /** Fires when the yield completed; onInvoked directives require the requested tool to run first. */
     onResolved?: (info: ResolveInfo) => void;
     /**
-     * Fires when the yield is being discarded. Return "requeue" to replay the
-     * same value at the head of the queue for the next turn. Default: "drop".
+     * Return "requeue" to replay the same value, or "drop_sequence" to discard
+     * its directive including later yields. Default: drop the rejected yield.
      */
     onRejected?: (info: RejectInfo) => RejectOutcome | undefined;
     /**
@@ -30,6 +30,8 @@ export interface ToolChoiceDirective {
     /** Stable label for targeted removal and debugging (e.g. "user-force"). */
     label: string;
     callbacks: DirectiveCallbacks;
+    /** Original multi-yield directive retained across one-yield replays. */
+    sequenceRoot?: ToolChoiceDirective;
 }
 export interface PushOptions {
     /** Prepend to head instead of appending to tail. Default: false. */

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

@@ -1,8 +1,8 @@
 import { type Agent, type AgentMessage, type ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import type { AssistantMessage, CodexCompactionContext, Model, ToolChoice } from "@oh-my-pi/pi-ai";
+import type { AssistantMessage, CodexCompactionContext, Effort, Model, ToolChoice } from "@oh-my-pi/pi-ai";
 import type { ModelRegistry } from "../config/model-registry.js";
 import type { Settings } from "../config/settings.js";
-import type { ConfiguredThinkingLevel } from "../thinking.js";
+import { type ConfiguredThinkingLevel } from "../thinking.js";
 import type { AgentSessionEvent } from "./agent-session-events.js";
 import type { InitialRetryFallbackState } from "./agent-session-types.js";
 import { type RetryFallbackSelector } from "./retry-fallback-chains.js";
@@ -25,6 +25,8 @@ export interface TurnRecoveryHost {
     thinkingLevel(): ThinkingLevel | undefined;
     configuredThinkingLevel(): ConfiguredThinkingLevel | undefined;
     setThinkingLevel(level: ConfiguredThinkingLevel | undefined): void;
+    /** Hard per-session effort ceiling; fallback recovery must never raise thinking above it. */
+    thinkingLevelCeiling(): Effort | undefined;
     isDisposed(): boolean;
     isStreaming(): boolean;
     isCompacting(): boolean;
@@ -41,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/task/index.d.ts

@@ -71,7 +71,7 @@ export declare class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskT
     readonly mergeCallAndResult = true;
     get parameters(): TaskToolSchemaInstance;
     renderCall(args: unknown, options: Parameters<typeof renderTaskCall>[1], theme: Theme): import("@oh-my-pi/pi-tui").Component;
-    /** Dynamic description that reflects current disabled-agent settings */
+    /** Dynamic description that reflects current task settings. */
     get description(): string;
     private constructor();
     /**

package/dist/types/task/types.d.ts

@@ -83,7 +83,6 @@ export declare const taskItemSchema: import("arktype/internal/variants/object.ts
     name?: string | undefined;
     agent: import("arktype/internal/attributes.ts").Default<string, "task">;
     task: string;
-    effort?: "hi" | "lo" | "med" | undefined;
     outputSchema?: string | boolean | object | null | undefined;
     schemaMode?: "permissive" | "strict" | undefined;
 }, {}>;
@@ -108,7 +107,6 @@ export declare const taskSchema: import("arktype/internal/variants/object.ts").O
     name?: string | undefined;
     agent: import("arktype/internal/attributes.ts").Default<string, "task">;
     task: string;
-    effort?: "hi" | "lo" | "med" | undefined;
     outputSchema?: string | boolean | object | null | undefined;
     schemaMode?: "permissive" | "strict" | undefined;
     isolated?: boolean | undefined;
@@ -117,7 +115,6 @@ declare const ALL_TASK_SCHEMAS: readonly [import("arktype/internal/variants/obje
     name?: string | undefined;
     agent: import("arktype/internal/attributes.ts").Default<string, "task">;
     task: string;
-    effort?: "hi" | "lo" | "med" | undefined;
     outputSchema?: string | boolean | object | null | undefined;
     schemaMode?: "permissive" | "strict" | undefined;
     isolated?: boolean | undefined;
@@ -125,7 +122,6 @@ declare const ALL_TASK_SCHEMAS: readonly [import("arktype/internal/variants/obje
     name?: string | undefined;
     agent: import("arktype/internal/attributes.ts").Default<string, "task">;
     task: string;
-    effort?: "hi" | "lo" | "med" | undefined;
     outputSchema?: string | boolean | object | null | undefined;
     schemaMode?: "permissive" | "strict" | undefined;
 }, {}>, import("arktype/internal/variants/object.ts").ObjectType<{
@@ -134,7 +130,6 @@ declare const ALL_TASK_SCHEMAS: readonly [import("arktype/internal/variants/obje
         name?: string | undefined;
         agent: import("arktype/internal/attributes.ts").Default<string, "task">;
         task: string;
-        effort?: "hi" | "lo" | "med" | undefined;
         outputSchema?: string | boolean | object | null | undefined;
         schemaMode?: "permissive" | "strict" | undefined;
         isolated?: boolean | undefined;
@@ -145,7 +140,6 @@ declare const ALL_TASK_SCHEMAS: readonly [import("arktype/internal/variants/obje
         name?: string | undefined;
         agent: import("arktype/internal/attributes.ts").Default<string, "task">;
         task: string;
-        effort?: "hi" | "lo" | "med" | undefined;
         outputSchema?: string | boolean | object | null | undefined;
         schemaMode?: "permissive" | "strict" | undefined;
     }[];
@@ -154,14 +148,12 @@ type DynamicTaskSchema = (typeof ALL_TASK_SCHEMAS)[number];
 export type TaskSchema = typeof taskSchema;
 /** Active task tool parameter schema for the current isolation / batch flags */
 export type TaskToolSchemaInstance = DynamicTaskSchema | BaseType;
+/** Build the task wire schema for the current settings and spawn policy. */
 export declare function getTaskSchema(options: {
     isolationEnabled: boolean;
     batchEnabled: boolean;
-}): DynamicTaskSchema;
-export declare function getTaskSchema(options: {
-    isolationEnabled: boolean;
-    batchEnabled: boolean;
-    defaultAgent: string;
+    effortEnabled?: boolean;
+    defaultAgent?: string;
 }): TaskToolSchemaInstance;
 /**
  * Runtime params union over both wire shapes. The model sees exactly one shape

package/dist/types/thinking.d.ts

@@ -122,9 +122,28 @@ export type TaskEffort = (typeof TASK_EFFORTS)[number];
  * at — high, xhigh, or max), `med` = the middle (lower of the two middles for
  * an even-sized range). Without a model, maps over the full canonical range.
  * Returns `undefined` when the model has no controllable effort surface, so
- * callers fall back to their default selector (e.g. `auto`).
+ * callers fall back to their default selector (e.g. `auto`). Throws when the
+ * configured ceiling is below the model's lowest supported effort.
  */
-export declare function resolveTaskEffortLevel(model: Model | undefined, effort: TaskEffort): Effort | undefined;
+export declare function resolveTaskEffortLevel(model: Model | undefined, effort: TaskEffort, maxEffort?: Effort): Effort | undefined;
+/**
+ * Clamps a concrete thinking selector to a per-session effort ceiling (e.g. a
+ * task spawn's `task.maxEffort`-capped effort hint). `off`/`inherit`/
+ * `undefined` pass through, as do levels already at or below the ceiling.
+ * Levels above it snap to the highest model-supported effort at or below the
+ * ceiling. A model whose floor exceeds the ceiling has nothing valid to snap
+ * to; the requested level is returned unchanged and the caller is responsible
+ * for rejecting or skipping such models (see {@link modelSupportsEffortCeiling}).
+ */
+export declare function clampThinkingLevelToCeiling(model: Model | undefined, level: Effort | undefined, ceiling: Effort | undefined): Effort | undefined;
+export declare function clampThinkingLevelToCeiling(model: Model | undefined, level: ThinkingLevel | undefined, ceiling: Effort | undefined): ThinkingLevel | undefined;
+/**
+ * True when `model` can honor a thinking-effort ceiling: it either has no
+ * controllable effort surface (nothing to cap) or supports at least one effort
+ * at or below the ceiling. Retry-fallback candidate filtering uses this to
+ * skip models whose floor would force the session above the ceiling.
+ */
+export declare function modelSupportsEffortCeiling(model: Model, ceiling: Effort): boolean;
 /**
  * The provisional concrete level shown while `auto` is configured but before a
  * turn has been classified. Prefers the model's `defaultLevel`, otherwise High,

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;

package/dist/types/utils/inspect-image-mode.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Effective-state resolution for the `inspect_image` tool.
+ *
+ * The tool delegates image understanding to a (possibly different)
+ * vision-capable model. That indirection is only useful when the active model
+ * cannot consume images itself; when it can (`model.input` includes
+ * `"image"`), the tool is redundant and its presence actively degrades the
+ * `read` tool, which reduces image reads to metadata-only plus an
+ * inspect_image suggestion. `auto` mode therefore exposes the tool only for
+ * models without native image input. `on`/`off` force registration regardless
+ * of model capability. A session-scoped override (the `/vision` command)
+ * takes precedence over the persisted setting for the current session only.
+ */
+import type { Model } from "@oh-my-pi/pi-ai";
+import type { Settings } from "../config/settings.js";
+export type InspectImageMode = "auto" | "on" | "off";
+export declare const INSPECT_IMAGE_MODES: readonly ["auto", "on", "off"];
+/** Minimal session surface needed to resolve the effective inspect_image state. */
+export interface InspectImageModeContext {
+    settings: Pick<Settings, "get">;
+    getActiveModel?: () => Model | undefined;
+    getInspectImageModeOverride?: () => InspectImageMode | undefined;
+}
+/**
+ * Whether the `inspect_image` tool should be registered/active right now.
+ * `auto` registers it only when the active model lacks native image input;
+ * an unresolved model is treated as text-only so the tool stays available.
+ */
+export declare function isInspectImageToolActive(session: InspectImageModeContext): boolean;

package/dist/types/utils/profile-tree.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared display-tree machinery for profile summaries (macOS `sample` reports,
+ * V8 `.cpuprofile` files). Callers build {@link ProfileNode} trees with a
+ * domain-specific metric (on-CPU samples, self microseconds, …); this module
+ * merges same-key siblings, flattens direct recursion, collapses pass-through
+ * chains, and renders the pruned hot-path tree.
+ */
+/** Display node: merged, recursion-flattened mirror of a profile subtree. */
+export interface ProfileNode {
+    /** Merge/recursion identity (demangled symbol, function@call-site, …). */
+    key: string;
+    /** Human-readable label; recursion and truncation decorations are applied at render time. */
+    label: string;
+    /** Inclusive metric for this subtree (on-CPU samples, self µs, …); drives pruning and display. */
+    value: number;
+    /** Levels of direct recursion flattened into this node. */
+    recursion: number;
+    children: ProfileNode[];
+}
+/** Merge `b` into `a` (same key), combining values and child lists. */
+export declare function mergeInto(a: ProfileNode, b: ProfileNode): void;
+/**
+ * Flatten direct recursion: children carrying the node's own key are dissolved
+ * into it (their children promoted and merged), so a 15-deep recursive spine
+ * renders as one annotated node.
+ */
+export declare function flattenRecursion(node: ProfileNode): void;
+/** `n` as a percentage of `total`, one decimal (`"12.3%"`); `"0%"` when total is empty. */
+export declare function formatPct(n: number, total: number): string;
+/** Options for {@link renderProfileNode}. */
+export interface RenderTreeContext {
+    out: string[];
+    /** Denominator for percentage annotations. */
+    total: number;
+    /** Minimum subtree value a child needs to stay visible. */
+    minValue: number;
+    /** Format a metric value for the left column. */
+    formatValue: (value: number) => string;
+    /** Left-column width (characters) for formatted values. */
+    valueWidth: number;
+}
+/**
+ * Render one hot-path subtree: pass-through chains (single kept child, no own
+ * contribution above `minValue`) collapse into a single `a › b › c` line, and
+ * children below `minValue` are pruned.
+ */
+export declare function renderProfileNode(node: ProfileNode, indent: number, ctx: RenderTreeContext): void;

package/dist/types/utils/sample-profile.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Parser and renderer for macOS `/usr/bin/sample` call-tree reports
+ * (conventionally saved as `*.sample.txt`).
+ *
+ * The raw report is a 10k+ line ASCII call tree with mangled symbols —
+ * expensive for an agent to digest. `renderSampleProfile` converts it into a
+ * compact bottleneck summary:
+ *
+ * - per-thread hot paths, pruned to frames with meaningful on-CPU samples,
+ *   with pass-through chains collapsed and direct recursion flattened
+ * - blocked/idle threads reduced to a one-line classification
+ * - a process-wide "top functions by self samples" table
+ * - Rust v0 and legacy symbols demangled (best-effort, path extraction)
+ *
+ * Consumed by the read tool: `*.sample.txt` reads show the summary, `:raw`
+ * returns the original bytes.
+ */
+/** Matches paths the read tool should treat as macOS sample reports. */
+export declare function isSampleProfilePath(filePath: string): boolean;
+/** One frame in the sampled call tree. Counts are sample hits (subtree total). */
+export interface SampleFrame {
+    count: number;
+    symbol: string;
+    module?: string;
+    children: SampleFrame[];
+}
+/** One sampled thread: `Thread_<id>` root plus its call tree. */
+export interface SampleThread {
+    id: string;
+    name?: string;
+    total: number;
+    roots: SampleFrame[];
+}
+/** Metadata from the report preamble (everything before `Call graph:`). */
+export interface SampleProfileHeader {
+    process: string;
+    pid: number;
+    intervalMs: number;
+    path?: string;
+    codeType?: string;
+    osVersion?: string;
+    footprint?: string;
+    footprintPeak?: string;
+}
+/** Parsed macOS sample report. */
+export interface SampleProfile {
+    header: SampleProfileHeader;
+    threads: SampleThread[];
+}
+/**
+ * Parse a macOS `sample` report. Returns null when the text does not look
+ * like sample output (missing analysis preamble or `Call graph:` section).
+ */
+export declare function parseSampleProfile(text: string): SampleProfile | null;
+/**
+ * Best-effort demangle of Rust symbols (v0 `_R…` and legacy `_ZN…E`).
+ * For v0 this is a path extractor, not a full demangler: identifiers are
+ * pulled out in order and joined with `::`, so generic arguments appear as
+ * extra path segments. Non-Rust symbols pass through unchanged.
+ */
+export declare function demangleSymbol(raw: string): string;
+/**
+ * Render a macOS sample report as an agent-friendly bottleneck summary.
+ * Returns null when `text` is not sample output (caller falls back to the
+ * plain-text path).
+ */
+export declare function renderSampleProfile(text: string): string | null;

package/dist/types/utils/title-generator.d.ts

@@ -20,39 +20,40 @@ export declare function generateSessionTitle(firstMessage: string, registry: Mod
 export declare function generateTitleOnline(firstMessage: string, registry: ModelRegistry, settings: Settings, sessionId?: string, currentModel?: Model<Api>, metadataResolver?: (provider: string) => Record<string, unknown> | undefined, signal?: AbortSignal, customSystemPrompt?: string): Promise<string | null>;
 export declare function formatSessionTerminalTitle(sessionName: string | undefined, cwd?: string): string;
 /**
- * Set the terminal title using OSC 0 (sets both tab and window title). Unsupported terminals ignore it.
+ * Set the terminal title through the native Win32 API or OSC 0.
+ *
+ * Repeating the same sanitized title is a no-op on every platform.
  */
 export declare function setTerminalTitle(title: string): void;
 export declare function setSessionTerminalTitle(sessionName: string | undefined, cwd?: string): void;
 /**
  * Set a terminal title from an extension's `setTitle()`. Unlike the session base
- * title, this owns the terminal verbatim: the run-state separator will not rewrite
- * it on the next spinner tick or state change. Cleared when the app next sets an
- * authoritative session title via {@link setSessionTerminalTitle}.
+ * title, this owns the terminal verbatim: periodic and run-state updates will not
+ * rewrite it. Cleared when the app next sets an authoritative session title via
+ * {@link setSessionTerminalTitle}.
  */
 export declare function setExtensionTerminalTitle(title: string): void;
 export type TerminalTitleState = "idle" | "working" | "attention";
 /**
- * Compose the terminal title from the `π` brand, a state-carrying SEPARATOR, and
- * the session label. The brand never gains a prefix glyph — the separator slot
- * expresses the run state instead. Pure (no I/O) so the state→separator contract
- * is unit-testable:
- *   - `idle` (user's turn):  `π > label`  — reads like a prompt awaiting input;
- *   - `working`:             `π ⠋ label`  — spinner frames animate the separator;
- *   - `attention`:           `π ! label`  — agent blocked on the user;
- *   - disabled:              `π: label`   — the pre-state layout.
+ * Compose the terminal title from the `π` brand, a state-carrying separator, and
+ * the session label. Pure (no I/O) so the state→separator contract is testable:
+ *   - `idle` (user's turn):  `π > label`;
+ *   - `working`:             `π ⠋ label` (`π : label` on Windows);
+ *   - `attention`:           `π ! label`;
+ *   - disabled:              `π: label`.
  * Without a label the separator trails the brand (`π >`) so the state stays visible.
  */
-export declare function buildTerminalTitleWithState(label: string | undefined, state: TerminalTitleState, frame: number, enabled: boolean): string;
+export declare function buildTerminalTitleWithState(label: string | undefined, state: TerminalTitleState, frame: number, enabled: boolean, platform?: NodeJS.Platform): string;
 /**
  * Reflect the agent run state in the terminal title's separator: `working`
- * animates spinner frames in the separator slot, `idle` shows `>` (your turn),
- * `attention` shows `!` (agent blocked on you). Gated off by `tui.titleState`.
+ * animates outside Windows and stays `:` on Windows, `idle` shows `>` (your
+ * turn), and `attention` shows `!` (agent blocked on you). Gated off by
+ * `tui.titleState`.
  */
 export declare function setTerminalTitleState(state: TerminalTitleState): void;
 /** Enable/disable the run-state separator (driven by the `tui.titleState` setting). */
 export declare function setTerminalTitleStateEnabled(enabled: boolean): void;
-/** Stop the spinner timer; call on session/UI teardown. */
+/** Release terminal-title runtime resources. */
 export declare function disposeTerminalTitleState(): void;
 /**
  * Save the current terminal title on terminals that support xterm window ops.