@sayknow-cli/coding-agent 0.3.6 → 0.3.7

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

@@ -0,0 +1,157 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@sayknow-cli/agent-core";
+import type { Component } from "@sayknow-cli/tui";
+import * as z from "zod/v4";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import { type Theme } from "../modes/theme/theme";
+import type { ToolSession } from ".";
+import { type OutputMeta } from "./output-meta";
+export declare const BASH_DEFAULT_PREVIEW_LINES = 10;
+export declare function saveBashOriginalArtifactForTests(session: ToolSession, originalText: string): Promise<string | undefined>;
+declare const bashSchemaBase: z.ZodObject<{
+    command: z.ZodString;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    timeout: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    cwd: z.ZodOptional<z.ZodString>;
+    pty: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+declare const bashSchemaWithAsync: z.ZodObject<{
+    command: z.ZodString;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    timeout: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    cwd: z.ZodOptional<z.ZodString>;
+    pty: z.ZodOptional<z.ZodBoolean>;
+    async: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type BashToolSchema = typeof bashSchemaBase | typeof bashSchemaWithAsync;
+export interface BashToolInput {
+    command: string;
+    env?: Record<string, string>;
+    timeout?: number;
+    cwd?: string;
+    async?: boolean;
+    pty?: boolean;
+}
+export interface BashToolDetails {
+    meta?: OutputMeta;
+    timeoutSeconds?: number;
+    requestedTimeoutSeconds?: number;
+    terminalId?: string;
+    async?: {
+        state: "running" | "completed" | "failed";
+        jobId: string;
+        type: "bash";
+    };
+}
+export interface BashToolOptions {
+}
+/**
+ * Bash tool implementation.
+ *
+ * Executes bash commands with optional timeout and working directory.
+ */
+export declare class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
+    #private;
+    private readonly session;
+    readonly name = "bash";
+    readonly label = "Bash";
+    readonly loadMode = "essential";
+    readonly description: string;
+    readonly parameters: BashToolSchema;
+    readonly concurrency = "exclusive";
+    readonly strict = true;
+    constructor(session: ToolSession);
+    /**
+     * Start a background bash job for the Monitor tool. Reuses the full Bash
+     * pipeline (interceptors, internal-URL expansion, env, cwd, timeout); the
+     * public `monitor` tool itself is ACP-gated by `AgentSession` before this
+     * helper is called. The caller-supplied `onRawLine` callback is invoked once
+     * per newline-terminated stdout chunk, between turns, so the upstream Claude
+     * Code "Each stdout line is a task-notification event" semantics are preserved
+     * through the agent's existing background-task delivery path.
+     */
+    startMonitorJob(input: {
+        command: string;
+        cwd?: string;
+        timeout?: number;
+        env?: Record<string, string>;
+    }, opts?: {
+        ownerId?: string;
+        label?: string;
+        ctx?: AgentToolContext;
+        onRawLine?: (line: string, jobId: string) => void;
+        shouldAcceptRawLine?: (jobId: string) => boolean;
+        lifecycle?: import("../async").AsyncJobLifecycleCleanup;
+    }): Promise<{
+        jobId: string;
+        label: string;
+        commandCwd: string;
+    }>;
+    execute(_toolCallId: string, { command: rawCommand, env: rawEnv, timeout: rawTimeout, cwd, async: asyncRequested, pty }: BashToolInput, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<BashToolDetails>, ctx?: AgentToolContext): Promise<AgentToolResult<BashToolDetails>>;
+}
+export interface BashRenderArgs {
+    command?: string;
+    env?: Record<string, string>;
+    timeout?: number;
+    cwd?: string;
+    __partialJson?: string;
+    [key: string]: unknown;
+}
+export interface BashRenderContext {
+    /** Raw output text */
+    output?: string;
+    /** Whether output came from artifact storage */
+    isFullOutput?: boolean;
+    /** Whether output is expanded */
+    expanded?: boolean;
+    /** Number of preview lines when collapsed */
+    previewLines?: number;
+    /** Timeout in seconds */
+    timeout?: number;
+}
+export interface ShellRendererConfig<TArgs> {
+    resolveTitle: (args: TArgs | undefined, options: RenderResultOptions) => string;
+    resolveCommand?: (args: TArgs | undefined) => string | undefined;
+    resolveCwd?: (args: TArgs | undefined) => string | undefined;
+    resolveEnv?: (args: TArgs | undefined) => Record<string, string> | undefined;
+}
+export declare function getBashEnvForDisplay(args: BashRenderArgs): Record<string, string> | undefined;
+export declare function formatBashCommand(args: BashRenderArgs): string;
+/**
+ * Returns the bash command formatted for the result body: the dim `$ cd … &&`
+ * prefix joined with syntax-highlighted command lines. The prefix is applied
+ * only to the first line so multi-line commands display cleanly — terminals
+ * reset SGR state at line boundaries, which made the previous single-string
+ * `theme.fg("dim", ...)` form render only the first line as dim.
+ */
+export declare function formatBashCommandLines(args: BashRenderArgs, uiTheme: Theme): string[];
+export declare function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>): {
+    renderCall(args: TArgs, options: RenderResultOptions, uiTheme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: BashToolDetails;
+        isError?: boolean;
+    }, options: RenderResultOptions & {
+        renderContext?: BashRenderContext;
+    }, uiTheme: Theme, args?: TArgs): Component;
+    mergeCallAndResult: boolean;
+    inline: boolean;
+};
+export declare const bashToolRenderer: {
+    renderCall(args: BashRenderArgs, options: RenderResultOptions, uiTheme: Theme): Component;
+    renderResult(result: {
+        content: {
+            type: string;
+            text?: string;
+        }[];
+        details?: BashToolDetails;
+        isError?: boolean;
+    }, options: RenderResultOptions & {
+        renderContext?: BashRenderContext;
+    }, uiTheme: Theme, args?: BashRenderArgs | undefined): Component;
+    mergeCallAndResult: boolean;
+    inline: boolean;
+};
+export {};

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

@@ -0,0 +1,54 @@
+/**
+ * Structured browser action space.
+ *
+ * Adapts the SOTA computer-use / browser-use pattern: instead of authoring raw
+ * JavaScript for every interaction, the model emits a list of structured verbs
+ * (navigate / click / type / …) that reference elements by the numeric `id`
+ * returned from {@link Observation}. Each verb is compiled onto the existing
+ * in-tab `tab.*` helpers and executed through the same worker `run` path, so the
+ * worker protocol is unchanged and the raw-JS `run` escape hatch still works.
+ */
+export type BrowserActionVerb = "navigate" | "click" | "type" | "fill" | "select" | "press" | "scroll" | "back" | "wait" | "observe" | "extract" | "screenshot";
+export interface BrowserActionStep {
+    verb: BrowserActionVerb;
+    /** Element id from a prior `observe` (preferred for click/type). */
+    id?: number;
+    /** CSS / puppeteer selector when not addressing by `id`. */
+    selector?: string;
+    /** Text to type. */
+    text?: string;
+    /** Value for `fill`. */
+    value?: string;
+    /** Option value(s) for `select`. */
+    values?: string[];
+    /** URL for `navigate`. */
+    url?: string;
+    /** Key for `press` (e.g. "Enter"). */
+    key?: string;
+    /** Horizontal scroll delta. */
+    dx?: number;
+    /** Vertical scroll delta. */
+    dy?: number;
+    /** Sleep duration for `wait` when no selector is given. */
+    ms?: number;
+    /** Extract format. */
+    format?: "markdown" | "text" | "html";
+    /** Navigation wait condition for `navigate`. */
+    wait_until?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
+    /** Only return interactive/viewport elements for `observe`. */
+    viewport_only?: boolean;
+    include_all?: boolean;
+}
+/**
+ * Validate a single step's required fields. Returns an error string, or
+ * `undefined` when the step is well-formed.
+ */
+export declare function validateActionStep(step: BrowserActionStep, index: number): string | undefined;
+/** Validate the full step list. Throws on the first invalid step. */
+export declare function validateActionSteps(steps: readonly BrowserActionStep[]): void;
+/**
+ * Compile structured steps into a JS program for the in-tab `run` worker. Steps
+ * are embedded as parsed JSON (no string interpolation, so values cannot inject
+ * code) and dispatched by a fixed interpreter against the `tab` / `page` helpers.
+ */
+export declare function compileActionSteps(steps: readonly BrowserActionStep[]): string;

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

@@ -0,0 +1,50 @@
+import type { Browser, Page } from "puppeteer-core";
+/**
+ * Allocate an unused TCP port on 127.0.0.1 by binding to port 0 and reading
+ * back the kernel-assigned port. There's a small race between close and the
+ * subsequent bind in the launched app, but Chromium's listener will retry.
+ */
+export declare function findFreeCdpPort(): Promise<number>;
+/** Poll `${cdpUrl}/json/version` until it responds with 200, with abort + timeout support. */
+export declare function waitForCdp(cdpUrl: string, timeoutMs: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Pull a `--remote-debugging-port=<n>` value out of an argv array (Chromium
+ * accepts both `--flag=value` and `--flag value`). Returns null if absent or
+ * malformed.
+ */
+export declare function findCdpPortInArgsForTest(args: string[]): number | null;
+export declare function findCdpAddressInArgsForTest(args: readonly string[]): string | null;
+export declare function isSafeCdpAddressForTest(address: string | null): boolean;
+export declare function argsMatchChromeProfileForTest(args: readonly string[], profile: {
+    userDataDir: string;
+    profileDirectory: string;
+}): boolean;
+export declare function findReusableCdp(exe: string, signal?: AbortSignal): Promise<{
+    cdpUrl: string;
+    pid: number;
+} | null>;
+export interface RunningChromeProfile {
+    pid: number;
+    cdpUrl: string | null;
+    unsafeCdpReason?: string;
+}
+export declare function findRunningChromeProfile(exe: string, profile: {
+    userDataDir: string;
+    profileDirectory: string;
+}, signal?: AbortSignal): Promise<RunningChromeProfile | null>;
+/**
+ * Pick the best page target on an attached browser. Without a matcher, prefer
+ * a page that doesn't look like a helper window (devtools, request handler,
+ * background pages); with a matcher, return the first url+title substring hit.
+ */
+export declare function pickElectronTarget(browser: Browser, matcher?: string): Promise<Page>;
+/**
+ * SIGTERM the process tree, wait briefly, then SIGKILL anything still alive.
+ * Single-process variant for our own spawned children.
+ */
+export declare function gracefulKillTreeOnce(pid: number, gracePeriodMs?: number): Promise<void>;
+/**
+ * Multi-process variant for attach: find every PID running `executablePath`
+ * (single-instance apps may keep an orphan around) and tear them all down.
+ */
+export declare function killExistingByPath(executablePath: string, signal?: AbortSignal): Promise<number>;

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

@@ -0,0 +1,62 @@
+import type { Browser, CDPSession, Page, default as Puppeteer, Target } from "puppeteer-core";
+export declare const DEFAULT_VIEWPORT: {
+    width: number;
+    height: number;
+    deviceScaleFactor: number;
+};
+/**
+ * Per-CDP-message timeout applied to every puppeteer launch/connect. Set above
+ * `TOOL_TIMEOUTS.browser.max` (30s) so the agent-side wall-clock is the canonical
+ * limit; this constant only catches genuinely stuck CDP sockets (renderer wedged,
+ * connection dropped, etc.).
+ */
+export declare const BROWSER_PROTOCOL_TIMEOUT_MS = 60000;
+export declare function loadPuppeteer(): Promise<typeof Puppeteer>;
+export declare function loadPuppeteerInWorker(safeDir: string): Promise<typeof Puppeteer>;
+export interface LaunchHeadlessOptions {
+    headless: boolean;
+    viewport?: {
+        width: number;
+        height: number;
+        deviceScaleFactor?: number;
+    };
+}
+export declare function launchHeadlessBrowser(opts: LaunchHeadlessOptions): Promise<Browser>;
+export declare function applyViewport(page: Page, viewport?: {
+    width: number;
+    height: number;
+    deviceScaleFactor?: number;
+}): Promise<void>;
+export interface UserAgentOverride {
+    userAgent: string;
+    platform: string;
+    acceptLanguage: string;
+    userAgentMetadata: {
+        brands: Array<{
+            brand: string;
+            version: string;
+        }>;
+        fullVersion: string;
+        platform: string;
+        platformVersion: string;
+        architecture: string;
+        model: string;
+        mobile: boolean;
+    };
+}
+export interface UserAgentSession {
+    override: UserAgentOverride;
+    browserSession: CDPSession | null;
+}
+/** Builds the browser-page stealth bootstrap source for regression tests. */
+export declare function buildStealthInjectionScriptForTest(scripts?: readonly string[]): string;
+/** Apply stealth patches + UA override to a headless page. Idempotent within a tab. */
+export declare function applyStealthPatches(browser: Browser, page: Page, state: {
+    browserSession: CDPSession | null;
+    override: UserAgentOverride | null;
+}): Promise<void>;
+export declare function targetSupportsUserAgentOverrideForTest(target: Target): boolean;
+export declare function configureUserAgentTargetsForTest(browser: Browser, state: {
+    browserSession: CDPSession | null;
+    override: UserAgentOverride;
+}, targetTimeoutMs?: number): Promise<void>;

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

@@ -0,0 +1,17 @@
+export type ReadableFormat = "text" | "markdown";
+export interface ReadableResult {
+    url: string;
+    title?: string;
+    byline?: string;
+    excerpt?: string;
+    contentLength: number;
+    text?: string;
+    markdown?: string;
+}
+/**
+ * Extract readable content from raw HTML.
+ * Tries Readability (article-isolation scoring) first, then falls back to a
+ * CSS selector chain over the same pre-parsed DOM. Returns null if neither
+ * path yields usable content.
+ */
+export declare function extractReadableFromHtml(html: string, url: string, format: ReadableFormat): Promise<ReadableResult | null>;

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

@@ -0,0 +1,57 @@
+import type { Subprocess } from "bun";
+import type { Browser, CDPSession } from "puppeteer-core";
+import { type UserAgentOverride } from "./launch";
+export type BrowserKind = {
+    kind: "headless";
+    headless: boolean;
+} | {
+    kind: "spawned";
+    path: string;
+} | {
+    kind: "chrome-profile";
+    path: string;
+    userDataDir: string;
+    profileDirectory: string;
+    background: boolean;
+    noFocus: boolean;
+    cdpPort?: number;
+} | {
+    kind: "connected";
+    cdpUrl: string;
+};
+export type BrowserKindTag = BrowserKind["kind"];
+export interface BrowserHandle {
+    key: string;
+    kind: BrowserKind;
+    browser: Browser;
+    cdpUrl?: string;
+    pid?: number;
+    subprocess?: Subprocess;
+    refCount: number;
+    stealth: {
+        browserSession: CDPSession | null;
+        override: UserAgentOverride | null;
+    };
+}
+type SpawnedChromeProfileKind = Extract<BrowserKind, {
+    kind: "chrome-profile";
+}>;
+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 buildChromeProfileLaunchArgs(kind: SpawnedChromeProfileKind, appArgs: readonly string[] | undefined, port: number): string[];
+export declare function buildChromeProfileLaunchArgsForTest(kind: SpawnedChromeProfileKind, appArgs: readonly string[] | undefined, port: number): string[];
+export declare function openChromeProfileHandle(kind: SpawnedChromeProfileKind, opts: AcquireBrowserOptions): Promise<BrowserHandle>;
+export declare function holdBrowser(handle: BrowserHandle): void;
+export declare function releaseBrowser(handle: BrowserHandle, opts: {
+    kill: boolean;
+}): Promise<void>;
+export {};

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

@@ -0,0 +1,53 @@
+/**
+ * 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 "@sayknow-cli/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;
+        browser?: string;
+        user_data_dir?: string;
+        profile_directory?: string;
+        target?: 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/tab-protocol.d.ts

@@ -0,0 +1,144 @@
+import type { ImageContent, TextContent } from "@sayknow-cli/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;
+}
+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;
+}