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

package/dist/types/modes/components/assistant-message.d.ts

@@ -63,6 +63,8 @@ export declare class AssistantMessageComponent extends Container {
     messagePersistenceKey(): string | undefined;
     /** Toggle rendering for assistant-native and tool-result images. */
     setImagesVisible(visible: boolean): void;
+    /** Toggle only images produced by tool results; assistant-native images remain governed by setImagesVisible. */
+    setToolResultImagesVisible(visible: boolean): void;
     setToolResultImages(toolCallId: string, images: ImageContent[]): void;
     updateContent(message: AssistantMessage, opts?: {
         transient?: boolean;

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

@@ -1,7 +1,7 @@
 import type { ImageContent } from "@oh-my-pi/pi-ai";
 import { Editor, type KeyId, TUI } from "@oh-my-pi/pi-tui";
 import type { AppKeybinding } from "../../config/keybindings.js";
-type ConfigurableEditorAction = Extract<AppKeybinding, "app.interrupt" | "app.clear" | "app.exit" | "app.suspend" | "app.display.reset" | "app.thinking.cycle" | "app.model.cycleForward" | "app.model.cycleBackward" | "app.model.select" | "app.model.selectTemporary" | "app.tools.expand" | "app.thinking.toggle" | "app.editor.external" | "app.history.search" | "app.message.dequeue" | "app.retry" | "app.clipboard.pasteImage" | "app.clipboard.pasteTextRaw" | "app.clipboard.copyPrompt">;
+type ConfigurableEditorAction = Extract<AppKeybinding, "app.interrupt" | "app.clear" | "app.exit" | "app.suspend" | "app.display.reset" | "app.thinking.cycle" | "app.model.cycleForward" | "app.model.cycleBackward" | "app.model.select" | "app.model.selectTemporary" | "app.tools.expand" | "app.tools.toggleVisibility" | "app.thinking.toggle" | "app.editor.external" | "app.history.search" | "app.message.dequeue" | "app.retry" | "app.clipboard.pasteImage" | "app.clipboard.pasteTextRaw" | "app.clipboard.copyPrompt">;
 /** Max gap (ms) between two spaces for the later one to count as OS key auto-repeat rather than a
  *  deliberate press. OS auto-repeat is fast; a deliberate tap (even a fast one) is slower. */
 export declare const SPACE_REPEAT_MAX_GAP_MS = 120;
@@ -141,6 +141,7 @@ export declare class CustomEditor extends Editor {
     onCycleModelBackward?: () => void;
     onSelectModel?: () => void;
     onExpandTools?: () => void;
+    onToggleToolActivity?: () => void;
     onToggleThinking?: () => void;
     onExternalEditor?: () => void;
     onHistorySearch?: () => void;

package/dist/types/modes/components/read-tool-group.d.ts

@@ -27,6 +27,7 @@ type ReadToolGroupOptions = {
 export declare class ReadToolGroupComponent extends Container implements ToolExecutionHandle {
     #private;
     constructor(options?: ReadToolGroupOptions);
+    render(width: number): readonly string[];
     isTranscriptBlockFinalized(): boolean;
     finalize(): void;
     /**
@@ -60,6 +61,7 @@ export declare class ReadToolGroupComponent extends Container implements ToolExe
     attachUsage(toolCallIds: readonly string[], usage: Usage, durationMs?: number, ttftMs?: number, timestamp?: number): boolean;
     setArgsComplete(_toolCallId?: string): void;
     setExpanded(expanded: boolean): void;
+    setToolActivityVisible(visible: boolean): void;
     getComponent(): Component;
 }
 export {};

package/dist/types/modes/components/stripped-tool-calls-placeholder.d.ts

@@ -0,0 +1,12 @@
+import { Text } from "@oh-my-pi/pi-tui";
+/**
+ * Dim transcript marker for tool calls stripped from the resolved branch
+ * (failed/retried turns, results on sibling branches). It is tool activity,
+ * so it hides and reappears with the `display.hideToolActivity` toggle.
+ */
+export declare class StrippedToolCallsPlaceholder extends Text {
+    #private;
+    constructor(strippedToolCalls: number, toolActivityVisible: boolean);
+    setToolActivityVisible(visible: boolean): void;
+    render(width: number): readonly string[];
+}

package/dist/types/modes/components/tool-execution.d.ts

@@ -48,6 +48,7 @@ export interface ToolExecutionHandle extends Component {
     }, isPartial?: boolean, toolCallId?: string): void;
     setArgsComplete(toolCallId?: string): void;
     setExpanded(expanded: boolean): void;
+    setToolActivityVisible(visible: boolean): void;
     /** Freeze the block as final history: stop spinners and let it commit to scrollback. */
     seal(): void;
 }
@@ -139,6 +140,7 @@ export declare class ToolExecutionComponent extends Container implements NativeS
      */
     stopAnimation(): void;
     setExpanded(expanded: boolean): void;
+    setToolActivityVisible(visible: boolean): void;
     setShowImages(show: boolean): void;
     invalidate(): void;
     render(width: number): readonly string[];

package/dist/types/modes/controllers/input-controller.d.ts

@@ -66,6 +66,7 @@ export declare class InputController {
     cycleThinkingLevel(): void;
     cycleRoleModel(direction?: "forward" | "backward"): Promise<void>;
     toggleToolOutputExpansion(): void;
+    toggleToolActivityVisibility(): void;
     setToolsExpanded(expanded: boolean): void;
     toggleThinkingBlockVisibility(): void;
     openExternalEditor(): Promise<void>;

package/dist/types/modes/interactive-mode.d.ts

@@ -103,6 +103,7 @@ export declare class InteractiveMode implements InteractiveModeContext {
     initialChatRendered: boolean;
     isBashMode: boolean;
     toolOutputExpanded: boolean;
+    hideToolActivity: boolean;
     todoExpanded: boolean;
     planModeEnabled: boolean;
     planModePaused: boolean;

package/dist/types/modes/types.d.ts

@@ -141,6 +141,7 @@ export interface InteractiveModeContext {
     initialChatRendered: boolean;
     isBashMode: boolean;
     toolOutputExpanded: boolean;
+    hideToolActivity: boolean;
     todoExpanded: boolean;
     planModeEnabled: boolean;
     vibeModeEnabled: boolean;

package/dist/types/modes/workflow.d.ts

@@ -2,8 +2,9 @@ import { type KeywordHighlighter } from "./gradient-highlight.js";
 /** WORKFLOW_NOTICE is the default hidden notice for sessions with batched task calls enabled. */
 export declare const WORKFLOW_NOTICE: string;
 /** renderWorkflowNotice renders the workflow notice for the active task schema. */
-export declare function renderWorkflowNotice({ taskBatch }: {
+export declare function renderWorkflowNotice({ taskBatch, scoutAvailable, }: {
     taskBatch: boolean;
+    scoutAvailable?: boolean;
 }): string;
 /**
  * Whether `text` contains the standalone keyword "workflowz"

package/dist/types/sdk.d.ts

@@ -1,5 +1,5 @@
 import { Agent, type AgentOptions, type AgentTelemetryConfig, type AgentTool, type ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import type { Effort, Model, SimpleStreamOptions } from "@oh-my-pi/pi-ai";
+import type { Effort, Model, ServiceTier, SimpleStreamOptions } from "@oh-my-pi/pi-ai";
 import type { Dialect } from "@oh-my-pi/pi-ai/dialect";
 import { type Rule } from "./capability/rule.js";
 import { ModelRegistry } from "./config/model-registry.js";
@@ -61,6 +61,8 @@ export interface CreateAgentSessionOptions {
     thinkingLevel?: ConfiguredThinkingLevel;
     /** Hard ceiling on the session's thinking effort (e.g. a task spawn's `task.maxEffort`-capped hint); retry-fallback recovery re-clamps to it. */
     thinkingLevelCeiling?: Effort;
+    /** OpenAI service-tier override for this session. `null` omits `service_tier`. */
+    openAIServiceTier?: ServiceTier | null;
     /** Models available for cycling (Ctrl+P in interactive mode) */
     scopedModels?: Array<{
         model: Model;

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

@@ -31,7 +31,7 @@ export declare function collectEnvSecrets(): SecretEntry[];
  * API keys) that are NOT configured via secrets.yml or the environment. Without
  * these, such a token in a tool result falls through to pi-ai's irreversible
  * provider-boundary redaction (`[openai_token_redacted]`); the model then echoes
- * that placeholder into edit-tool `old_text`, which can never match the real
+ * that placeholder into edit-tool `old_string`, which can never match the real
  * bytes on disk (issue #6968). Routing the same shapes through the obfuscator
  * mints reversible keyed placeholders that `deobfuscateToolArguments` restores
  * before tool execution, keeping exact-match edits working while the credential

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;
     /**

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/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-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;

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/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;

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

@@ -8,6 +8,7 @@ export { type AriaSnapshotOptions, buildAriaSnapshotScript, parseAriaRefSelector
 export { cmuxSnapshotToObservation, mapWaitUntil, resolveCmuxKind, serializeEval } from "./browser/cmux/rpc.js";
 export { CmuxSocketClient } from "./browser/cmux/socket-client.js";
 export { extractReadableFromHtml, type ReadableFormat, type ReadableResult } from "./browser/readable.js";
+export { DEFAULT_RELAY_URL, type RelayKind, resolveRelayKind } from "./browser/relay/kind.js";
 export type { Observation, ObservationEntry } from "./browser/tab-protocol.js";
 declare const browserSchema: import("arktype/internal/variants/object.ts").ObjectType<{
     action: "close" | "open" | "run";
@@ -16,6 +17,7 @@ declare const browserSchema: import("arktype/internal/variants/object.ts").Objec
     app?: {
         path?: string | undefined;
         cdp_url?: string | undefined;
+        relay?: boolean | undefined;
         args?: string[] | undefined;
         target?: string | undefined;
     } | undefined;
@@ -71,6 +73,7 @@ export declare class BrowserTool implements AgentTool<typeof browserSchema, Brow
         app?: {
             path?: string | undefined;
             cdp_url?: string | undefined;
+            relay?: boolean | undefined;
             args?: string[] | undefined;
             target?: string | undefined;
         } | undefined;