jeopi-cli 16.2.14 → 16.2.17

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

@@ -0,0 +1,58 @@
+import type { Subprocess } from "bun";
+import type { Browser, CDPSession } from "puppeteer-core";
+import type { CmuxKind } from "./cmux/rpc";
+import { CmuxSocketClient } from "./cmux/socket-client";
+import { type UserAgentOverride } from "./launch";
+export type PuppeteerBrowserKind = {
+    kind: "headless";
+    headless: boolean;
+} | {
+    kind: "spawned";
+    path: string;
+} | {
+    kind: "connected";
+    cdpUrl: string;
+};
+export type BrowserKind = PuppeteerBrowserKind | CmuxKind;
+export type BrowserKindTag = BrowserKind["kind"];
+interface BrowserHandleCommon {
+    key: string;
+    kind: BrowserKind;
+    refCount: number;
+}
+export interface PuppeteerBrowserHandle extends BrowserHandleCommon {
+    kind: PuppeteerBrowserKind;
+    browser: Browser;
+    cdpUrl?: string;
+    pid?: number;
+    subprocess?: Subprocess;
+    stealth: {
+        browserSession: CDPSession | null;
+        override: UserAgentOverride | null;
+    };
+}
+export interface CmuxBrowserHandle extends BrowserHandleCommon {
+    kind: CmuxKind;
+    client: CmuxSocketClient;
+    surface?: string;
+}
+export type BrowserHandle = PuppeteerBrowserHandle | CmuxBrowserHandle;
+export interface AcquireBrowserOptions {
+    cwd: string;
+    viewport?: {
+        width: number;
+        height: number;
+        deviceScaleFactor?: number;
+    };
+    appArgs?: string[];
+    signal?: AbortSignal;
+}
+export declare function acquireBrowser(kind: BrowserKind, opts: AcquireBrowserOptions): Promise<BrowserHandle>;
+export declare function normalizeConnectedCdpUrl(rawCdpUrl: string): string;
+export declare function holdBrowser(handle: BrowserHandle): void;
+export declare function releaseBrowser(handle: BrowserHandle, opts: {
+    kill: boolean;
+}): Promise<void>;
+/** Test-only accessor for the module-global browsers map. */
+export declare function getBrowsersMapForTest(): ReadonlyMap<string, BrowserHandle>;
+export {};

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

@@ -0,0 +1,52 @@
+/**
+ * TUI renderer for the browser tool.
+ *
+ * Mirrors the `eval` tool look: each `run` invocation is shown as a JS code
+ * cell with status icon, optional output, and expand/collapse handling. `open`
+ * and `close` actions render as compact status lines.
+ */
+import type { Component } from "jeopi-tui";
+import type { RenderResultOptions } from "../../extensibility/custom-tools/types";
+import type { Theme } from "../../modes/theme/theme";
+import type { BrowserToolDetails } from "../browser";
+interface BrowserRenderArgs {
+    action?: "open" | "close" | "run";
+    name?: string;
+    url?: string;
+    code?: string;
+    all?: boolean;
+    kill?: boolean;
+    app?: {
+        path?: string;
+        cdp_url?: string;
+        target?: string;
+        cmux?: boolean;
+        surface?: string;
+    };
+    viewport?: {
+        width: number;
+        height: number;
+        scale?: number;
+    };
+    timeout?: number;
+}
+interface BrowserRenderContext {
+    expanded?: boolean;
+    previewLines?: number;
+}
+export declare const browserToolRenderer: {
+    renderCall(args: BrowserRenderArgs, options: RenderResultOptions, theme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: BrowserToolDetails;
+        isError?: boolean;
+    }, options: RenderResultOptions & {
+        renderContext?: BrowserRenderContext;
+    }, theme: Theme, args?: BrowserRenderArgs): Component;
+    mergeCallAndResult: boolean;
+    inline: boolean;
+};
+export {};

package/dist/types/tools/browser/run-cancellation.d.ts

@@ -0,0 +1,4 @@
+/** Sleeps inside evaluated browser code while honoring the owning run's cancellation signal. */
+export declare function waitForBrowserRun(ms: number, signal: AbortSignal): Promise<void>;
+/** Binds a long-lived browser facade to one evaluated run's abort signal. */
+export declare function bindBrowserRunFacade<T extends object>(target: T, signal: AbortSignal): T;

package/dist/types/tools/browser/tab-protocol.d.ts

@@ -0,0 +1,146 @@
+import type { ImageContent, TextContent } from "jeopi-ai";
+export type Transferable = Bun.Transferable;
+export interface ObservationEntry {
+    id: number;
+    role: string;
+    name?: string;
+    value?: string | number;
+    description?: string;
+    keyshortcuts?: string;
+    states: string[];
+}
+export interface Observation {
+    url: string;
+    title?: string;
+    viewport: {
+        width: number;
+        height: number;
+        deviceScaleFactor?: number;
+    };
+    scroll: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        scrollWidth: number;
+        scrollHeight: number;
+    };
+    elements: ObservationEntry[];
+}
+export interface ScreenshotResult {
+    dest: string;
+    mimeType: string;
+    bytes: number;
+    width: number;
+    height: number;
+}
+export interface SessionSnapshot {
+    cwd: string;
+    browserScreenshotDir?: string;
+    /** Force non-WebP screenshot encoding (e.g. for Ollama). Unset honors `JEOPI_NO_WEBP`. */
+    excludeWebP?: boolean;
+}
+export type WorkerInitPayload = {
+    mode: "headless";
+    browserWSEndpoint: string;
+    safeDir: string;
+    viewport?: {
+        width: number;
+        height: number;
+        deviceScaleFactor?: number;
+    };
+    dialogs?: "accept" | "dismiss";
+    url?: string;
+    waitUntil?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
+    timeoutMs: number;
+} | {
+    mode: "attach";
+    browserWSEndpoint: string;
+    safeDir: string;
+    targetId: string;
+    dialogs?: "accept" | "dismiss";
+};
+export type ToolReply = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: RunErrorPayload;
+};
+export type WorkerInbound = {
+    type: "init";
+    payload: WorkerInitPayload;
+} | {
+    type: "run";
+    id: string;
+    name: string;
+    code: string;
+    timeoutMs: number;
+    session: SessionSnapshot;
+} | {
+    type: "abort";
+    id: string;
+} | {
+    type: "tool-reply";
+    id: string;
+    reply: ToolReply;
+} | {
+    type: "close";
+};
+export interface ReadyInfo {
+    url: string;
+    title?: string;
+    viewport: {
+        width: number;
+        height: number;
+        deviceScaleFactor?: number;
+    };
+    targetId: string;
+}
+export interface RunResultOk {
+    displays: Array<TextContent | ImageContent>;
+    returnValue: unknown;
+    screenshots: ScreenshotResult[];
+}
+export interface RunErrorPayload {
+    name: string;
+    message: string;
+    stack?: string;
+    isToolError: boolean;
+    isAbort: boolean;
+}
+export type WorkerOutbound = {
+    type: "ready";
+    info: ReadyInfo;
+} | {
+    type: "init-failed";
+    error: RunErrorPayload;
+} | {
+    type: "result";
+    id: string;
+    ok: true;
+    payload: RunResultOk;
+} | {
+    type: "result";
+    id: string;
+    ok: false;
+    error: RunErrorPayload;
+} | {
+    type: "tool-call";
+    id: string;
+    runId: string;
+    name: string;
+    args: unknown;
+} | {
+    type: "log";
+    level: "debug" | "warn" | "error";
+    msg: string;
+    meta?: Record<string, unknown>;
+} | {
+    type: "closed";
+};
+export interface Transport {
+    send(msg: WorkerOutbound | WorkerInbound, transferList?: Transferable[]): void;
+    onMessage(handler: (msg: WorkerOutbound | WorkerInbound) => void): () => void;
+    close(): void;
+}

package/dist/types/tools/browser/tab-supervisor.d.ts

@@ -0,0 +1,104 @@
+import type { ToolSession } from "../index";
+import { CmuxTab } from "./cmux/cmux-tab";
+import { type BrowserHandle, type BrowserKindTag, type CmuxBrowserHandle, type PuppeteerBrowserHandle } from "./registry";
+import type { ReadyInfo, RunResultOk, Transferable, WorkerInbound, WorkerInitPayload, WorkerOutbound } from "./tab-protocol";
+interface WorkerHandle {
+    send(msg: WorkerInbound, transferList?: Transferable[]): void;
+    onMessage(handler: (msg: WorkerOutbound) => void): () => void;
+    onError(handler: (error: Error) => void): () => void;
+    terminate(): Promise<void>;
+    readonly mode: "worker" | "inline";
+}
+export type DialogPolicy = "accept" | "dismiss";
+export interface PendingRun {
+    resolve(result: RunResultOk): void;
+    reject(error: unknown): void;
+    session: ToolSession;
+    signal?: AbortSignal;
+    toolCalls: Map<string, AbortController>;
+}
+interface TabSessionBase<TBrowser extends BrowserHandle = BrowserHandle> {
+    name: string;
+    browser: TBrowser;
+    targetId: string;
+    state: "alive" | "dead";
+    info: ReadyInfo;
+    pending: Map<string, PendingRun>;
+    dialogPolicy?: DialogPolicy;
+    kindTag: BrowserKindTag;
+    /**
+     * Session id of the caller that CREATED the tab. Preserved across reuse so
+     * that dispose of the creating session can reap browser resources without
+     * yanking the tab out from under a subagent that only reused it.
+     * Undefined when the acquirer did not identify itself.
+     */
+    ownerSessionId?: string;
+}
+export interface WorkerTabSession extends TabSessionBase<PuppeteerBrowserHandle> {
+    backend: "worker";
+    worker: WorkerHandle;
+}
+export interface CmuxTabSession extends TabSessionBase<CmuxBrowserHandle> {
+    backend: "cmux";
+    cmuxTab: CmuxTab;
+    cmuxOwnsSurface: boolean;
+    cmuxAttachedSurface?: string;
+}
+export type TabSession = WorkerTabSession | CmuxTabSession;
+export interface AcquireTabOptions {
+    url?: string;
+    waitUntil?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
+    viewport?: {
+        width: number;
+        height: number;
+        deviceScaleFactor?: number;
+    };
+    target?: string;
+    signal?: AbortSignal;
+    timeoutMs: number;
+    dialogs?: DialogPolicy;
+    cmuxSurface?: string;
+    /**
+     * Session id of the acquirer. Recorded on the tab when created (never on
+     * reuse) so `releaseTabsForOwner` can walk the shared tabs map on session
+     * dispose. Optional — omitting it opts the tab out of session-scoped reap.
+     */
+    ownerSessionId?: string;
+}
+export interface AcquireTabResult {
+    tab: TabSession;
+    created: boolean;
+}
+export interface RunInTabOptions {
+    code: string;
+    timeoutMs: number;
+    signal?: AbortSignal;
+    session: ToolSession;
+}
+export interface ReleaseTabOptions {
+    kill?: boolean;
+}
+export declare function getTab(name: string): TabSession | undefined;
+export declare function acquireTab(name: string, browser: BrowserHandle, opts: AcquireTabOptions): Promise<AcquireTabResult>;
+export declare function runInTab(name: string, opts: RunInTabOptions): Promise<RunResultOk>;
+export declare function releaseTab(name: string, opts?: ReleaseTabOptions): Promise<boolean>;
+export declare function releaseAllTabs(opts?: ReleaseTabOptions): Promise<number>;
+export declare function dropHeadlessTabs(): Promise<void>;
+/**
+ * Release every tab created by the given session id. Invoked from
+ * `AgentSession.dispose()` so headless/spawned Chromium and workers the
+ * session opened do not leak into the long-lived process — the module-global
+ * `tabs`/`browsers` maps that back this tool are not otherwise walked by
+ * session teardown. (Issue #3963.)
+ *
+ * Ownership is recorded ONLY on tab creation (`acquireTab` with
+ * `ownerSessionId`), never on reuse: a subagent re-driving a tab another
+ * session opened will not yank teardown responsibility away from the
+ * creator. Tabs opened with no owner (e.g. from an SDK caller that doesn't
+ * identify a session) are skipped and must be released explicitly.
+ */
+export declare function releaseTabsForOwner(ownerId: string, opts?: ReleaseTabOptions): Promise<number>;
+/** Test-only accessor for the module-global tabs map. */
+export declare function getTabsMapForTest(): ReadonlyMap<string, TabSession>;
+export declare function initializeTabWorkerForTest(worker: WorkerHandle, payload: WorkerInitPayload, timeoutMs: number): Promise<ReadyInfo>;
+export {};

package/dist/types/tools/browser/tab-worker-entry.d.ts

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

package/dist/types/tools/browser/tab-worker.d.ts

@@ -0,0 +1,56 @@
+import type { HTMLElement } from "linkedom";
+import type { ElementHandle, ImageFormat } from "puppeteer-core";
+import type { Transport } from "./tab-protocol";
+declare global {
+    interface Element extends HTMLElement {
+    }
+    function getComputedStyle(element: Element): Record<string, unknown>;
+    var innerWidth: number;
+    var innerHeight: number;
+    var document: {
+        elementFromPoint(x: number, y: number): Element | null;
+    };
+}
+export interface OpTimeouts {
+    /** Largest per-op deadline allowed — strictly below the cell budget. */
+    budgetBound: number;
+    /** Ceiling for quick page reads. */
+    quickOpMs: number;
+    /** Ceiling for interactive actions + default for waits. */
+    actionOpMs: number;
+}
+/** Resolve the per-op fail-fast ceilings for a given cell budget. */
+export declare function resolveOpTimeouts(cellTimeoutMs: number): OpTimeouts;
+/**
+ * Effective timeout for a wait helper (`waitFor*`). A positive explicit `{ timeout }` is
+ * honored but clamped to the cell budget so it still fails fast + named; raising the tool
+ * `timeout` raises that cap, so a longer budget stays meaningful. No `{ timeout }` → the
+ * action ceiling. Puppeteer's `{ timeout: 0 }` / `Infinity` ("disable") maps to the largest
+ * bounded wait (`budgetBound`) — the harness never permits an unbounded wait. Garbage input
+ * (negative, `NaN`) falls back to the action ceiling rather than the longest wait.
+ */
+export declare function resolveWaitTimeout(cellTimeoutMs: number, explicit?: number): number;
+interface ScreenshotOptions {
+    selector?: string;
+    fullPage?: boolean;
+    save?: string;
+    silent?: boolean;
+}
+export declare function normalizeSelector(selector: string): string;
+export interface InflightOp {
+    label: string;
+    startedAt: number;
+}
+/** Human-readable label for a screenshot op, used in op tracking + timeout errors. */
+export declare function describeScreenshot(opts?: ScreenshotOptions): string;
+/** Map an explicit save path's extension to a puppeteer capture format (default png). */
+export declare function imageFormatForPath(filePath: string): ImageFormat;
+/** Summarize still-running helpers (oldest first) so a cell timeout names what stalled. */
+export declare function describeInflight(inflight: Map<number, InflightOp>): string;
+export declare class WorkerCore {
+    #private;
+    constructor(transport: Transport);
+    nextElementId(): number;
+    cacheElement(id: number, handle: ElementHandle): void;
+}
+export {};

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

@@ -0,0 +1,96 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "jeopi-agent-core";
+import type { ToolExample } from "jeopi-ai";
+import type { ToolSession } from "../sdk";
+import { type BrowserKindTag } from "./browser/registry";
+import type { Observation, ScreenshotResult } from "./browser/tab-protocol";
+import type { OutputMeta } from "./output-meta";
+export { type AriaSnapshotOptions, buildAriaSnapshotScript, parseAriaRefSelector, } from "./browser/aria/aria-snapshot";
+export { cmuxSnapshotToObservation, mapWaitUntil, resolveCmuxKind, serializeEval } from "./browser/cmux/rpc";
+export { CmuxSocketClient } from "./browser/cmux/socket-client";
+export { extractReadableFromHtml, type ReadableFormat, type ReadableResult } from "./browser/readable";
+export type { Observation, ObservationEntry } from "./browser/tab-protocol";
+declare const browserSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    action: "close" | "open" | "run";
+    name?: string | undefined;
+    url?: string | undefined;
+    app?: {
+        path?: string | undefined;
+        cdp_url?: string | undefined;
+        args?: string[] | undefined;
+        target?: string | undefined;
+    } | undefined;
+    viewport?: {
+        width: number;
+        height: number;
+        scale?: number | undefined;
+    } | undefined;
+    wait_until?: "domcontentloaded" | "load" | "networkidle0" | "networkidle2" | undefined;
+    dialogs?: "accept" | "dismiss" | undefined;
+    code?: string | undefined;
+    timeout?: number | undefined;
+    all?: boolean | undefined;
+    kill?: boolean | undefined;
+}, {}>;
+/** Input schema for the browser tool. */
+export type BrowserParams = typeof browserSchema.infer;
+/** Details describing a browser tool execution result (for renderers + transcript). */
+export interface BrowserToolDetails {
+    action: BrowserParams["action"];
+    name?: string;
+    url?: string;
+    browser?: BrowserKindTag;
+    viewport?: {
+        width: number;
+        height: number;
+        deviceScaleFactor?: number;
+    };
+    observation?: Observation;
+    screenshots?: ScreenshotResult[];
+    result?: string;
+    meta?: OutputMeta;
+}
+/**
+ * Browser tool: stateful, multi-tab. Three actions:
+ * - `open`  → acquire/create a named tab on a browser kind (headless | spawned | connected) and optionally goto a url.
+ * - `close` → release a named tab (or all tabs); dispose browser when refcount hits 0.
+ * - `run`   → execute JS code against an existing tab with `page`/`browser`/`tab` helpers in scope.
+ */
+export declare class BrowserTool implements AgentTool<typeof browserSchema, BrowserToolDetails> {
+    #private;
+    private readonly session;
+    readonly name = "browser";
+    readonly approval: "exec";
+    readonly formatApprovalDetails: (args: unknown) => string[];
+    readonly label = "Browser";
+    readonly loadMode = "discoverable";
+    readonly summary = "Control a headless browser to navigate and interact with web pages";
+    readonly parameters: import("arktype/internal/variants/object.ts").ObjectType<{
+        action: "close" | "open" | "run";
+        name?: string | undefined;
+        url?: string | undefined;
+        app?: {
+            path?: string | undefined;
+            cdp_url?: string | undefined;
+            args?: string[] | undefined;
+            target?: string | undefined;
+        } | undefined;
+        viewport?: {
+            width: number;
+            height: number;
+            scale?: number | undefined;
+        } | undefined;
+        wait_until?: "domcontentloaded" | "load" | "networkidle0" | "networkidle2" | undefined;
+        dialogs?: "accept" | "dismiss" | undefined;
+        code?: string | undefined;
+        timeout?: number | undefined;
+        all?: boolean | undefined;
+        kill?: boolean | undefined;
+    }, {}>;
+    readonly strict = true;
+    readonly examples: readonly ToolExample<typeof browserSchema.infer>[];
+    constructor(session: ToolSession);
+    get description(): string;
+    /** Restart browser to apply mode changes (e.g. headless toggle). Drops only headless browsers. */
+    restartForModeChange(): Promise<void>;
+    execute(_toolCallId: string, params: BrowserParams, signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<BrowserToolDetails>, _ctx?: AgentToolContext): Promise<AgentToolResult<BrowserToolDetails>>;
+}

package/dist/types/tools/builtin-names.d.ts

@@ -0,0 +1,6 @@
+export declare const BUILTIN_TOOL_NAMES: readonly ["read", "bash", "edit", "ast_grep", "ast_edit", "ask", "debug", "eval", "ssh", "github", "glob", "grep", "lsp", "inspect_image", "browser", "checkpoint", "rewind", "task", "job", "irc", "todo", "web_search", "search_tool_bm25", "write", "memory_edit", "retain", "recall", "reflect", "learn", "manage_skill"];
+export type BuiltinToolName = (typeof BUILTIN_TOOL_NAMES)[number];
+/** Return the canonical tool name for current and legacy built-in tool IDs. */
+export declare function normalizeToolName(name: string): string;
+/** Normalize and deduplicate tool names while preserving first-seen order. */
+export declare function normalizeToolNames(names: Iterable<string>): string[];

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

@@ -0,0 +1,72 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "jeopi-agent-core";
+import type { ToolSession } from ".";
+import type { OutputMeta } from "./output-meta";
+export interface CheckpointState {
+    /** Number of in-memory messages at checkpoint (AFTER checkpoint tool result is appended) */
+    checkpointMessageCount: number;
+    /** Session entry ID at checkpoint (for session tree branching) */
+    checkpointEntryId: string | null;
+    /** Timestamp */
+    startedAt: string;
+}
+export interface CompletedRewindState {
+    /** Report retained after a successful rewind. */
+    report: string;
+    /** Timestamp for the checkpoint that was rewound. */
+    startedAt: string;
+    /** Timestamp when the rewind completed. */
+    rewoundAt: string;
+}
+declare const checkpointSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    goal: string;
+}, {}>;
+type CheckpointParams = typeof checkpointSchema.infer;
+declare const rewindSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    report: string;
+}, {}>;
+type RewindParams = typeof rewindSchema.infer;
+export interface CheckpointToolDetails {
+    goal: string;
+    startedAt: string;
+    meta?: OutputMeta;
+}
+export interface RewindToolDetails {
+    report: string;
+    rewound: boolean;
+    meta?: OutputMeta;
+}
+export declare class CheckpointTool implements AgentTool<typeof checkpointSchema, CheckpointToolDetails> {
+    private readonly session;
+    readonly name = "checkpoint";
+    readonly approval: "read";
+    readonly label = "Checkpoint";
+    readonly summary = "Create a git-based checkpoint to save and restore session state";
+    readonly description: string;
+    readonly parameters: import("arktype/internal/variants/object.ts").ObjectType<{
+        goal: string;
+    }, {}>;
+    readonly strict = true;
+    readonly loadMode = "discoverable";
+    readonly intent: (args: Partial<CheckpointParams>) => string;
+    constructor(session: ToolSession);
+    static createIf(session: ToolSession): CheckpointTool | null;
+    execute(_toolCallId: string, params: CheckpointParams, _signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<CheckpointToolDetails>, _context?: AgentToolContext): Promise<AgentToolResult<CheckpointToolDetails>>;
+}
+export declare class RewindTool implements AgentTool<typeof rewindSchema, RewindToolDetails> {
+    private readonly session;
+    readonly name = "rewind";
+    readonly approval: "read";
+    readonly label = "Rewind";
+    readonly summary = "Rewind to a previously created checkpoint";
+    readonly description: string;
+    readonly parameters: import("arktype/internal/variants/object.ts").ObjectType<{
+        report: string;
+    }, {}>;
+    readonly strict = true;
+    readonly loadMode = "discoverable";
+    readonly intent: () => string;
+    constructor(session: ToolSession);
+    static createIf(session: ToolSession): RewindTool | null;
+    execute(_toolCallId: string, params: RewindParams, _signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<RewindToolDetails>, _context?: AgentToolContext): Promise<AgentToolResult<RewindToolDetails>>;
+}
+export {};