@oh-my-pi/pi-coding-agent 17.2.4 → 17.2.6

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

@@ -81,6 +81,8 @@ export interface AgentSessionConfig {
     agent: Agent;
     sessionManager: SessionManager;
     settings: Settings;
+    /** Whether the session spawn policy permits the read-only `scout` subagent. Defaults to true. */
+    scoutAllowedBySpawnPolicy?: boolean;
     /** Whether the caller explicitly requested yolo/auto-approve behavior for this session. */
     autoApprove?: boolean;
     /** Models to cycle through with Ctrl+P (from --models flag). */
@@ -213,7 +215,7 @@ export interface AgentSessionConfig {
     /**
      * Build the `replace`-mode `edit` a Cursor `pi_edit` frame needs, against the
      * advisor-scoped tool session. The advisor's ordinary instance follows the
-     * configured `edit.mode` and rejects the frame's `old_text`/`new_text` pairs.
+     * configured `edit.mode` and rejects the frame's `old_string`/`new_string` args.
      */
     advisorCreateEditTool?(): AgentTool | undefined;
     /**
@@ -355,6 +357,11 @@ export interface FreshSessionResult {
     sessionId: string;
     closedProviderSessions: number;
 }
+/** Outcome of an in-place `/reset` conversation-context reset. */
+export interface ResetSessionContextResult {
+    /** Number of live messages dropped from the model's context. */
+    droppedCount: number;
+}
 /** Queued user content restored to the editor. */
 export type RestoredQueuedMessage = {
     text: string;

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

@@ -37,6 +37,7 @@ import { GoalRuntime } from "../goals/runtime.js";
 import type { GoalModeState } from "../goals/state.js";
 import type { HindsightSessionState } from "../hindsight/state.js";
 import type { IrcMessage } from "../irc/bus.js";
+import type { DaemonCompletionNotification } from "../launch/protocol.js";
 import { type MnemopiSessionState } from "../mnemopi/state.js";
 import { type PlanApprovalDetails } from "../plan-mode/approved-plan.js";
 import type { PlanModeState } from "../plan-mode/state.js";
@@ -49,7 +50,7 @@ import type { TodoPhase } from "../tools/todo.js";
 import type { InspectImageMode } from "../utils/inspect-image-mode.js";
 import type { VibeModeState } from "../vibe/state.js";
 import type { AgentSessionEventListener } from "./agent-session-events.js";
-import type { AgentSessionConfig, AgentSessionDisposeOptions, AsyncJobSnapshot, CommandMetadataChangedListener, ContextUsageBreakdown, FollowUpOptions, FreshSessionResult, HandoffResult, ModelCycleResult, Prewalk, PromptOptions, ResolvedRoleModel, RestoredQueuedMessage, RoleModelCycle, RoleModelCycleResult, SessionHandoffOptions, SessionOAuthAccountList, SessionStats, UsageFallbackConfirmation } from "./agent-session-types.js";
+import type { AgentSessionConfig, AgentSessionDisposeOptions, AsyncJobSnapshot, CommandMetadataChangedListener, ContextUsageBreakdown, FollowUpOptions, FreshSessionResult, HandoffResult, ModelCycleResult, Prewalk, PromptOptions, ResetSessionContextResult, ResolvedRoleModel, RestoredQueuedMessage, RoleModelCycle, RoleModelCycleResult, SessionHandoffOptions, SessionOAuthAccountList, SessionStats, UsageFallbackConfirmation } from "./agent-session-types.js";
 import type { ClientBridge } from "./client-bridge.js";
 import { type CustomMessage, type CustomMessagePayload } from "./messages.js";
 import { type AdvisorStats } from "./session-advisors.js";
@@ -180,6 +181,8 @@ export declare class AgentSession {
      * Multiple listeners can be added. Returns unsubscribe function for this listener.
      */
     subscribe(listener: AgentSessionEventListener): () => void;
+    /** Register cleanup that runs when this AgentSession adopts a different session ID. */
+    registerSessionChangeCallback(callback: () => void): () => void;
     subscribeCommandMetadataChanged(listener: CommandMetadataChangedListener): () => void;
     /** Run one abortable auto-learn capture outside the primary agent loop. */
     runAutolearnCapture(capture: (signal: AbortSignal) => Promise<void>): Promise<void>;
@@ -199,6 +202,25 @@ export declare class AgentSession {
     beginDispose(): void;
     dispose(options?: AgentSessionDisposeOptions): Promise<void>;
     freshSession(): FreshSessionResult | undefined;
+    /**
+     * Reset the current conversation in place: drop every message, queued turn,
+     * and pending tool call from the model's context while keeping the session
+     * itself — its id, title, cwd, model, settings, and on-disk transcript all
+     * survive. The next turn is sent with only the base system prompt plus the
+     * project rules/AGENTS.md.
+     *
+     * This is the in-place sibling of {@link newSession}: it reuses the same
+     * conversation-boundary teardown (drop the conversation, rotate provider-side
+     * session state so providers that keep history server-side resume nothing,
+     * re-prime the advisors, and undo any memory promotion) but skips minting a
+     * new session id and opening a fresh transcript file. Unlike
+     * {@link freshSession} (which only rotates provider stream state) it also
+     * clears the conversation.
+     *
+     * Returns `undefined` without mutating anything while a response is
+     * streaming or a foreground bash/python execution is in flight.
+     */
+    resetSessionContext(): Promise<ResetSessionContextResult | undefined>;
     /** Full agent state */
     get state(): AgentState;
     /** Current model (may be undefined if not yet selected) */
@@ -476,6 +498,7 @@ export declare class AgentSession {
      */
     followUp(text: string, images?: ImageContent[], options?: FollowUpOptions): Promise<void>;
     queueDeferredMessage(message: CustomMessage): void;
+    queueLaunchCompletion(notification: DaemonCompletionNotification): Promise<void>;
     /**
      * Send a custom message to the session. Creates a CustomMessageEntry.
      *
@@ -805,7 +828,8 @@ export declare class AgentSession {
         selectedImages: ImageContent[];
         cancelled: boolean;
     }>;
-    branchFromBtw(question: string, assistantMessage: AssistantMessage): Promise<{
+    /** Promotes a completed /btw answer from the explicitly authorized session and leaf. */
+    branchFromBtw(question: string, assistantMessage: AssistantMessage, leafId: string, sessionId: string): Promise<{
         cancelled: boolean;
         sessionFile: string | undefined;
     }>;

package/dist/types/session/indexed-session-storage.d.ts

@@ -56,6 +56,7 @@ declare class IndexedSessionStorageWriter implements SessionStorageWriter {
         flags?: "a" | "w";
         onError?: (err: Error) => void;
     });
+    appendSync(line: string): void;
     append(line: string): Promise<void>;
     flush(): Promise<void>;
     isOpen(): boolean;

package/dist/types/session/launch-completion.d.ts

@@ -0,0 +1,10 @@
+import type { DaemonCompletionNotification } from "../launch/protocol.js";
+import type { CustomMessage } from "./messages.js";
+/** Yield-queue kind for broker-owned supervised process completions. */
+export declare const LAUNCH_COMPLETION_MESSAGE_TYPE = "launch-completion";
+/** One broker completion awaiting injection into its owning session. */
+export type LaunchCompletionEntry = DaemonCompletionNotification;
+/** Whether a broker completion belongs to the primary session or its advisor. */
+export declare function isLaunchCompletionOwner(owner: string, sessionId: string): boolean;
+/** Build one model-visible notification per terminal supervised process exit. */
+export declare function buildLaunchCompletionBatchMessage(entries: LaunchCompletionEntry[]): CustomMessage;

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

@@ -65,7 +65,7 @@ export interface SessionAdvisorsOptions {
     /**
      * Build the `replace`-mode `edit` a Cursor `pi_edit` frame needs. The
      * advisor's own instance follows the configured `edit.mode` (`hashline` by
-     * default), whose schema the frame's `old_text`/`new_text` pairs do not
+     * default), whose schema the frame's `old_string`/`new_string` args do not
      * match, so without this every native advisor edit fails validation.
      */
     createEditTool?(): AgentTool | undefined;

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

@@ -1,5 +1,5 @@
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
-import { type ServiceTierByFamily } from "@oh-my-pi/pi-ai";
+import { type ProviderPayload, type ServiceTierByFamily } from "@oh-my-pi/pi-ai";
 import { type CompactionEntry, type SessionEntry } from "./session-entries.js";
 export interface SessionContext {
     messages: AgentMessage[];
@@ -55,4 +55,5 @@ export interface BuildSessionContextOptions {
 export interface StrippedToolCallsMarker {
     strippedToolCalls?: number;
 }
+export declare function getOpenAiRemoteCompactionPayload(compaction: CompactionEntry | null | undefined): ProviderPayload | undefined;
 export declare function buildSessionContext(entries: SessionEntry[], leafId?: string | null, byId?: Map<string, SessionEntry>, options?: BuildSessionContextOptions): SessionContext;

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

@@ -31,6 +31,8 @@ export interface SessionHeader {
      */
     additionalDirectories?: string[];
     parentSession?: string;
+    /** Prior absolute JSONL locations recorded by successful session moves. */
+    previousSessionFiles?: string[];
     /** Provider prompt-cache identity inherited by exact-route full forks. */
     providerPromptCacheKey?: string;
 }
@@ -102,6 +104,17 @@ export interface BranchSummaryEntry<T = unknown> extends SessionEntryBase {
     /** True if generated by an extension, false if pi-generated */
     fromExtension?: boolean;
 }
+/**
+ * Pure marker entry recorded by `/reset` (resetSessionContext). It carries no
+ * payload — its presence on the branch is a durable boundary the collapsed
+ * live transcript and the model-context rebuild start emission after, so a
+ * rebuild (theme change, focus attach, /shake, resume) does not resurrect the
+ * pre-reset conversation. The on-disk record and the plain `transcript:true`
+ * export path keep the full pre-reset history.
+ */
+export interface ResetBoundaryEntry extends SessionEntryBase {
+    type: "reset_boundary";
+}
 /**
  * Custom entry for extensions to store extension-specific data in the session.
  * Use customType to identify your extension's entries.
@@ -135,6 +148,7 @@ declare module "@oh-my-pi/pi-agent-core/compaction/entries" {
     interface CustomCompactionSessionEntries {
         titleChange: TitleChangeEntry;
         credentialPin: CredentialPinEntry;
+        resetBoundary: ResetBoundaryEntry;
     }
 }
 /** TTSR injection entry - tracks which time-traveling rules have been injected this session. */
@@ -210,7 +224,7 @@ export interface CustomMessageEntry<T = unknown> extends SessionEntryBase {
     attribution?: MessageAttribution;
 }
 /** Session entry - has id/parentId for tree structure (returned by "read" methods in SessionManager) */
-export type SessionEntry = SessionMessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | ServiceTierChangeEntry | CompactionEntry | BranchSummaryEntry | CustomEntry | CustomMessageEntry | LabelEntry | TitleChangeEntry | TtsrInjectionEntry | SessionInitEntry | ModeChangeEntry | CredentialPinEntry;
+export type SessionEntry = SessionMessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | ServiceTierChangeEntry | CompactionEntry | BranchSummaryEntry | CustomEntry | CustomMessageEntry | LabelEntry | TitleChangeEntry | TtsrInjectionEntry | SessionInitEntry | ModeChangeEntry | CredentialPinEntry | ResetBoundaryEntry;
 /** Raw logical file entry after loaders strip any fixed-width title slot. */
 export type FileEntry = SessionHeader | SessionEntry;
 /** Physical JSONL entry before slot-aware loaders fold the title slot. */

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

@@ -87,6 +87,7 @@ export interface SessionMaintenanceHost {
     syncTodoPhasesFromBranch(): void;
     resetAdvisorRuntimes(): void;
     rebaseAfterCompaction(): void;
+    recordAnchoredHistoryRewrite(tokensRemoved: number): void;
     getContextBreakdown(options?: {
         contextWindow?: number;
         pendingMessages?: AgentMessage[];

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

@@ -39,17 +39,22 @@ export declare class SessionPersistenceIndeterminateError extends AggregateError
  * tree by `(id, parentId)`, and the mutable leaf pointer selects which path is
  * active for future appends and for LLM context construction.
  *
- * Durability is software-crash safe but not power-loss safe: appends are normally
- * handed to the OS synchronously in-body but never `fsync`'d. While an in-place
- * atomic rewrite publishes, a synchronous `flushSync` still persists fenced
- * appends by superseding the pending publish against the same (stable) path.
- * A {@link moveTo} relocation is the one exception: the session file is being
- * renamed to a new path, so appends landing in the rename window are held in
- * memory and persisted only by the move's trailing rewrite. A `flushSync` in
- * that narrow window cannot durably place them — writing the vacated source
- * would recreate the orphan the move eliminates, and a queued backend publish
- * (fire-and-forget on `IndexedSessionStorage`) could land after the rename all
- * the same. This gap is inherent to closing the writer for a Windows-safe rename.
+ * Durability is software-crash safe but not power-loss safe: completed entries
+ * (user/assistant/toolResult messages, tool_execution_start markers, custom
+ * entries) are handed to the OS synchronously in-body on append and never
+ * `fsync`'d. In-flight streaming text is intentionally not durable until
+ * `message_end` persists the finished message.
+ *
+ * While an in-place atomic rewrite is publishing, a concurrent completed append
+ * supersedes that publish with a synchronous full-body rewrite so the entry is
+ * software-crash durable before the append returns; the abandoned atomic's
+ * `commitGuard` then refuses to clobber the fresher body.
+ *
+ * During {@link moveTo}, appends write a full body to the live relocation path
+ * (source until rename, destination once the rename has landed) so a crash mid-
+ * move still preserves completed entries without recreating a vacated source.
+ * A trailing atomic rewrite still rewrites the header cwd after the path is
+ * repointed.
  */
 export declare class SessionManager {
     #private;
@@ -228,6 +233,13 @@ export declare class SessionManager {
         readSummarize?: boolean;
     }): string;
     appendCompaction<T = unknown>(summary: string, shortSummary: string | undefined, firstKeptEntryId: string, tokensBefore: number, details?: T, fromExtension?: boolean, preserveData?: Record<string, unknown>): string;
+    /**
+     * Append the durable conversation boundary recorded by `/reset`. The
+     * collapsed live transcript and the model-context rebuild start after the
+     * latest one, while the full history stays on disk (the plain
+     * `transcript:true` export walks it unchanged).
+     */
+    appendResetBoundary(): string;
     appendCustomEntry(customType: string, data?: unknown): string;
     /**
      * Rewrite the session file after in-place entry updates (e.g. pruning old tool

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

@@ -38,6 +38,16 @@ export declare class SessionStatsTracker {
     get revision(): number;
     /** Non-message token count captured for the active provider request. */
     get pendingNonMessageTokens(): number | undefined;
+    /**
+     * Apply an estimated prompt-prefix reduction to the current provider anchor.
+     *
+     * History after the anchor is estimated live by {@link getContextBreakdown};
+     * callers must pass only savings from entries already included in the
+     * anchor's provider-reported prompt. Persisting the correction on the
+     * assistant snapshot keeps reloads accurate, and the next successful
+     * assistant response naturally replaces it with a fresh provider anchor.
+     */
+    recordAnchoredHistoryRewrite(tokensRemoved: number): void;
     /** Sets or clears the in-flight context snapshot. */
     setPendingSnapshot(snapshot: PendingContextSnapshot | undefined): void;
     /** Recomputes an in-flight snapshot after history is compacted or rewritten. */

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

@@ -6,13 +6,25 @@ export interface SessionStorageStat {
 }
 export interface SessionStorageWriter {
     /**
-     * Append one newline-terminated line. File storage batches same-turn appends
-     * until its microtask boundary; memory storage updates in-body; indexed
-     * backends queue in call order.
+     * Append one newline-terminated line.
+     *
+     * File and memory storage apply the line synchronously before the returned
+     * promise settles, so a software crash after `append` returns (or after a
+     * fire-and-forget call begins) still sees the entry on disk / in body. No
+     * `fsync` — power loss may still drop the last page. Indexed backends update
+     * the local index immediately and queue the remote publish in call order.
      *
      * `line` MUST include the trailing newline.
      */
     append(line: string): Promise<void>;
+    /**
+     * Synchronous append when the backend can apply the line before return.
+     * File and memory implement this so {@link SessionManager} can latch the
+     * first write failure before the appending call returns (surfaced by a later
+     * flushSync/close/next append — the turn loop does not throw from append).
+     * Indexed backends update the local index immediately and queue remote I/O.
+     */
+    appendSync?(line: string): void;
     /** Resolve once all queued appends complete. No fsync. */
     flush(): Promise<void>;
     /** Drain synchronously flushable queued work when the backend supports it. No fsync. */

package/dist/types/session/yield-queue.d.ts

@@ -1,4 +1,4 @@
-import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
+import { type AgentMessage } from "@oh-my-pi/pi-agent-core";
 export interface YieldDispatcher<P> {
     /** Drop entries already delivered through another path. Called per-entry at flush time. */
     isStale?(entry: P): boolean;
@@ -19,7 +19,10 @@ export declare class YieldQueue {
     constructor(options: YieldQueueOptions);
     register<P>(kind: string, dispatcher: YieldDispatcher<P>): () => void;
     enqueue<P>(kind: string, entry: P): void;
+    enqueueWithReceipt<P>(kind: string, entry: P): Promise<void>;
     has(kind?: string): boolean;
+    /** Arrange an idle flush for entries queued near the end of a streaming run. */
+    requestIdleFlush(): void;
     flush(mode: YieldFlushMode): Promise<void>;
     /**
      * Snapshot and remove all queued entries, returning one lazy thunk per kind.
@@ -33,5 +36,7 @@ export declare class YieldQueue {
     /** Drop queued entries. With `kind`, drop only that kind's entries (leaving
      *  any pending idle-flush for other kinds intact); otherwise drop everything. */
     clear(kind?: string): void;
+    /** Clear a scheduled-flush latch when its host task is cancelled before running. */
+    cancelIdleFlushScheduling(): void;
 }
 export {};

package/dist/types/system-prompt.d.ts

@@ -77,7 +77,8 @@ export interface BuildSystemPromptOptions {
     /**
      * Whether provider-native tool calling is active (no owned/in-band syntax).
      * When true and `inlineToolDescriptors` is false, the inventory renders as a
-     * compact tool-name list; otherwise it renders full `# Tool:` sections. Default: true
+     * compact tool-name list; otherwise it renders the full Harmony-style
+     * `namespace functions { … }` catalog. Default: true
      */
     nativeTools?: boolean;
     /** Skills settings for discovery. */
@@ -113,6 +114,8 @@ export interface BuildSystemPromptOptions {
     taskMaxConcurrency?: number;
     /** Whether IRC-backed parallel coordination can be included in delegation policy. */
     taskIrcEnabled?: boolean;
+    /** Whether the read-only `scout` subagent is spawnable (not disabled, allowed by spawn policy). Defaults to true. */
+    scoutAvailable?: boolean;
     /** Rules with alwaysApply=true — their full content is injected into the prompt. */
     alwaysApplyRules?: AlwaysApplyRule[];
     /** Whether secret obfuscation is active. When true, explains the redaction format in the prompt. */

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

@@ -25,7 +25,7 @@ export declare function formatResultOutputFallback(result: Pick<SingleResult, "o
  * (DepthCapacity: it currently has the `task` tool). `agentNames` are the
  * per-item resolved agent types. Returns undefined when no nudge applies.
  */
-export declare function buildSpecializationAdvisory(agentNames: string[], depthCapacity: boolean): string | undefined;
+export declare function buildSpecializationAdvisory(agentNames: string[], depthCapacity: boolean, scoutAvailable?: boolean): string | undefined;
 /**
  * Suggestion — never a rejection — nudging the spawner to coordinate via the
  * hub when one call creates ≥2 live siblings and it still holds spawn
@@ -48,6 +48,7 @@ export declare function composeSpawnAdvisory(args: {
     depthCapacity: boolean;
     ircEnabled: boolean;
     willRunAsync: boolean;
+    scoutAvailable?: boolean;
 }): string | undefined;
 /**
  * Task tool - Delegate tasks to specialized agents.

package/dist/types/task/spawn-policy.d.ts

@@ -15,3 +15,8 @@ export interface ResolvedSpawnPolicy {
 }
 /** Resolves spawn frontmatter into the default and prompt/error surfaces. */
 export declare function resolveSpawnPolicy(parentSpawns: string | boolean | null | undefined): ResolvedSpawnPolicy;
+/**
+ * Whether the `scout` agent is spawnable in a session: not disabled via
+ * `task.disabledAgents`, and permitted by the session spawn policy.
+ */
+export declare function isScoutSpawnable(disabledAgents: readonly string[] | undefined, spawns: string | boolean | null | undefined): boolean;

package/dist/types/thinking.d.ts

@@ -1,5 +1,6 @@
 import { type ResolvedThinkingLevel, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import { Effort, type Model } from "@oh-my-pi/pi-ai";
+export { CLI_THINKING_LEVELS } from "./cli/thinking-levels.js";
 /**
  * Metadata used to render thinking selector values in the coding-agent UI.
  */
@@ -81,13 +82,6 @@ export interface ConfiguredThinkingLevelMetadata {
 export declare function parseConfiguredThinkingLevel(value: string | null | undefined): ConfiguredThinkingLevel | undefined;
 /** Returns display metadata for a configured selector, including `auto`. */
 export declare function getConfiguredThinkingLevelMetadata(level: ConfiguredThinkingLevel): ConfiguredThinkingLevelMetadata;
-/**
- * Thinking selectors accepted by the `--thinking` CLI flag, in display order:
- * `off`, every concrete effort (`minimal`..`max`), then `auto`. Single source
- * for the flag's `options` list, shell completions, and the "invalid level"
- * warning so all three stay in sync.
- */
-export declare const CLI_THINKING_LEVELS: readonly string[];
 /**
  * Parses a `--thinking` CLI value. Accepts every {@link parseConfiguredThinkingLevel}
  * selector (`off`, `auto`, `minimal`..`max`) but rejects

package/dist/types/tools/ast-grep.d.ts

@@ -41,7 +41,7 @@ export declare class AstGrepTool implements AgentTool<typeof astGrepSchema, AstG
     readonly approval: "read";
     readonly label = "AST Grep";
     readonly summary = "Search code with AST patterns (structural grep)";
-    readonly description: string;
+    get description(): string;
     readonly parameters: import("arktype/internal/variants/object.ts").ObjectType<{
         pat: string;
         path?: string | undefined;

package/dist/types/tools/browser/registry.d.ts

@@ -3,6 +3,7 @@ import type { Browser, CDPSession } from "puppeteer-core";
 import type { CmuxKind } from "./cmux/rpc.js";
 import { CmuxSocketClient } from "./cmux/socket-client.js";
 import { type UserAgentOverride } from "./launch.js";
+import type { RelayKind } from "./relay/kind.js";
 export type PuppeteerBrowserKind = {
     kind: "headless";
     headless: boolean;
@@ -12,7 +13,7 @@ export type PuppeteerBrowserKind = {
 } | {
     kind: "connected";
     cdpUrl: string;
-};
+} | RelayKind;
 export type BrowserKind = PuppeteerBrowserKind | CmuxKind;
 export type BrowserKindTag = BrowserKind["kind"];
 interface BrowserHandleCommon {

package/dist/types/tools/browser/relay/bridge.d.ts

@@ -0,0 +1,35 @@
+/** Transport-agnostic websocket surface the bridge writes to. */
+export interface RelaySocket {
+    send(text: string): void;
+    close(): void;
+}
+/**
+ * Multiplexing CDP bridge between downstream puppeteer connections and the
+ * relay extension. One instance per relay server; all state lives here so an
+ * extension service-worker restart only has to re-handshake.
+ */
+export declare class RelayBridge {
+    #private;
+    constructor(opts?: {
+        log?: (message: string, data?: Record<string, unknown>) => void;
+        /** Group tabs the agent actively drives under one per-window Chrome tab group. */
+        group?: {
+            title: string;
+            color: string;
+        } | null;
+    });
+    /** True once the extension has completed its hello handshake. */
+    get ready(): boolean;
+    /** Payload for `GET /json/version`. */
+    versionInfo(wsUrl: string): Record<string, string>;
+    /** Payload for `GET /json/list` (debugging aid; per-target endpoints are not served). */
+    listTargets(): Array<Record<string, string>>;
+    /** A new extension socket connected; replaces any previous one. */
+    extConnected(socket: RelaySocket): void;
+    extClosed(socket: RelaySocket): void;
+    extMessage(socket: RelaySocket, raw: string): void;
+    /** Register a downstream CDP websocket; returns the connection id. */
+    cdpConnected(socket: RelaySocket): number;
+    cdpClosed(connId: number): void;
+    cdpMessage(connId: number, raw: string): void;
+}

package/dist/types/tools/browser/relay/daemon.d.ts

@@ -0,0 +1,16 @@
+/** Stable broker daemon name for the relay server. */
+export declare const RELAY_DAEMON_NAME = "omp.browser.relay";
+/** True when the relay HTTP server answers /json/version at all (200 = extension connected, 503 = waiting for it). */
+export declare function probeRelayServer(cdpUrl: string): Promise<boolean>;
+/** Auto-start is only safe for endpoints this machine can own. */
+export declare function isLoopbackRelayUrl(cdpUrl: string): boolean;
+/**
+ * Ensure a relay server answers at `cdpUrl`, starting the broker-owned daemon
+ * when nothing is serving. Returns true once the HTTP endpoint responds — the
+ * extension handshake (503 → 200) is the caller's wait. False when the relay
+ * could not be started (broker unavailable or start rounds exhausted).
+ */
+export declare function ensureRelayDaemon(opts: {
+    cdpUrl: string;
+    signal?: AbortSignal;
+}): Promise<boolean>;

package/dist/types/tools/browser/relay/kind.d.ts

@@ -0,0 +1,19 @@
+/** Browser kind selecting the omp browser relay. */
+export interface RelayKind {
+    kind: "relay";
+    cdpUrl: string;
+}
+/** Default endpoint of the `omp-browser-relay` CLI. */
+export declare const DEFAULT_RELAY_URL = "http://127.0.0.1:9224";
+export interface ResolveRelayKindOptions {
+    /** `browser.relay` setting; `PI_BROWSER_RELAY=0|1` overrides it. */
+    settingEnabled?: boolean;
+    /** `browser.relayUrl` setting; falls back to {@link DEFAULT_RELAY_URL}. */
+    url?: string;
+}
+/**
+ * Resolve the relay browser kind, or null when relay mode is disabled.
+ * Mirrors `resolveCmuxKind`: the setting opts in, the env var is the final
+ * override in both directions.
+ */
+export declare function resolveRelayKind(options?: ResolveRelayKindOptions | null, env?: Record<string, string | undefined>): RelayKind | null;

package/dist/types/tools/browser/relay/protocol.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Wire protocol between the relay server and the Chrome extension.
+ *
+ * The extension dials out to `ws://127.0.0.1:<port>/ext` and exchanges JSON
+ * messages. The relay drives the extension with numbered RPCs; the extension
+ * pushes tab lifecycle and `chrome.debugger` events as they happen.
+ */
+/** Minimal view of a Chrome tab shared between extension and relay. */
+export interface TabSnapshot {
+    tabId: number;
+    url: string;
+    title: string;
+    active: boolean;
+    windowId: number;
+    /** Pinned tabs are never grouped (Chrome would silently unpin them). */
+    pinned: boolean;
+    /** Chrome tab group id; -1 when ungrouped. */
+    groupId: number;
+}
+/** RPCs the relay may ask the extension to perform. */
+export type RelayRpcRequest = {
+    op: "attach";
+    tabId: number;
+} | {
+    op: "detach";
+    tabId: number;
+} | {
+    op: "send";
+    tabId: number;
+    sessionId?: string;
+    method: string;
+    params?: Record<string, unknown>;
+} | {
+    op: "createTab";
+    url: string;
+} | {
+    op: "removeTab";
+    tabId: number;
+} | {
+    op: "activateTab";
+    tabId: number;
+}
+/** Add tabs to the per-window omp group (created/reused by title), remembering prior membership. */
+ | {
+    op: "group";
+    tabIds: number[];
+    title: string;
+    color: string;
+}
+/** Return tabs to their pre-omp group (or ungroup); no-op for tabs the relay never grouped. */
+ | {
+    op: "ungroup";
+    tabIds: number[];
+};
+/** Messages sent relay → extension. */
+export type RelayToExtMessage = ({
+    t: "rpc";
+    id: number;
+} & RelayRpcRequest) | {
+    t: "pong";
+};
+/** Messages sent extension → relay. */
+export type ExtToRelayMessage = {
+    t: "hello";
+    userAgent: string;
+    browserVersion: string;
+    tabs: TabSnapshot[];
+    /** Tabs that already have a `chrome.debugger` attachment (relay reconciles after a service-worker restart). */
+    attachedTabIds: number[];
+} | {
+    t: "cdpEvent";
+    tabId: number;
+    sessionId?: string;
+    method: string;
+    params?: Record<string, unknown>;
+} | {
+    t: "detached";
+    tabId: number;
+    reason: string;
+} | {
+    t: "tabCreated";
+    tab: TabSnapshot;
+} | {
+    t: "tabUpdated";
+    tab: TabSnapshot;
+} | {
+    t: "tabRemoved";
+    tabId: number;
+} | {
+    t: "rpcResult";
+    id: number;
+    ok: boolean;
+    result?: unknown;
+    error?: string;
+} | {
+    t: "ping";
+};

package/dist/types/tools/browser/relay/server.d.ts

@@ -0,0 +1,35 @@
+/**
+ * HTTP + WebSocket server for the browser relay.
+ *
+ * Impersonates Chrome's CDP discovery endpoint so the omp browser tool (and
+ * any puppeteer client) can connect with a plain `browserURL`:
+ * - `GET /json/version` → 200 with `webSocketDebuggerUrl` once the extension
+ *   is connected, 503 before that (clients like `waitForCdp` keep polling).
+ * - `GET /json` / `/json/list` → attachable page targets (debugging aid).
+ * - `WS /cdp` → downstream CDP clients (puppeteer).
+ * - `WS /ext` → the Chrome extension (token-gated when configured).
+ *
+ * Binds loopback only: anything that can reach this port can drive the
+ * user's logged-in browser.
+ */
+import { RelayBridge } from "./bridge.js";
+/** Options for {@link startRelayServer}. */
+export interface RelayServerOptions {
+    port: number;
+    /** Shared secret the extension must present as `?token=`; unset disables the check. */
+    token?: string;
+    /** Group tabs the agent actively drives under one per-window Chrome tab group (default on); `false` disables. */
+    group?: boolean | {
+        title: string;
+        color: string;
+    };
+    log?: (message: string, data?: Record<string, unknown>) => void;
+}
+/** A running relay server. */
+export interface RelayServer {
+    bridge: RelayBridge;
+    port: number;
+    stop(): void;
+}
+/** Start the relay server on 127.0.0.1. Throws if the port is taken. */
+export declare function startRelayServer(opts: RelayServerOptions): RelayServer;

package/dist/types/tools/browser/render.d.ts

@@ -19,6 +19,7 @@ interface BrowserRenderArgs {
     app?: {
         path?: string;
         cdp_url?: string;
+        relay?: boolean;
         target?: string;
         cmux?: boolean;
         surface?: string;