@oh-my-pi/pi-coding-agent 15.1.0 → 15.1.2

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

@@ -0,0 +1,72 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { Component } from "@oh-my-pi/pi-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";
+declare const astEditSchema: z.ZodObject<{
+    ops: z.ZodArray<z.ZodObject<{
+        pat: z.ZodString;
+        out: z.ZodString;
+    }, z.core.$strip>>;
+    paths: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export interface AstEditToolDetails {
+    totalReplacements: number;
+    filesTouched: number;
+    filesSearched: number;
+    applied: boolean;
+    limitReached: boolean;
+    parseErrors?: string[];
+    scopePath?: string;
+    files?: string[];
+    fileReplacements?: Array<{
+        path: string;
+        count: number;
+    }>;
+    meta?: OutputMeta;
+    /** Pre-formatted text for the user-visible TUI render. Mirrors `result.text` lines but uses
+     * a `│` gutter (no model-only hashline anchors). The TUI uses this directly so it never parses model-facing text. */
+    displayContent?: string;
+}
+export declare class AstEditTool implements AgentTool<typeof astEditSchema, AstEditToolDetails> {
+    private readonly session;
+    readonly name = "ast_edit";
+    readonly label = "AST Edit";
+    readonly summary = "Perform AST-aware code edits (structural refactoring)";
+    readonly description: string;
+    readonly parameters: z.ZodObject<{
+        ops: z.ZodArray<z.ZodObject<{
+            pat: z.ZodString;
+            out: z.ZodString;
+        }, z.core.$strip>>;
+        paths: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    readonly strict = true;
+    readonly deferrable = true;
+    readonly loadMode = "discoverable";
+    constructor(session: ToolSession);
+    execute(_toolCallId: string, params: z.infer<typeof astEditSchema>, signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<AstEditToolDetails>, _context?: AgentToolContext): Promise<AgentToolResult<AstEditToolDetails>>;
+}
+interface AstEditRenderArgs {
+    ops?: Array<{
+        pat?: string;
+        out?: string;
+    }>;
+    paths?: string[];
+}
+export declare const astEditToolRenderer: {
+    inline: boolean;
+    renderCall(args: AstEditRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: AstEditToolDetails;
+        isError?: boolean;
+    }, options: RenderResultOptions, uiTheme: Theme, args?: AstEditRenderArgs): Component;
+    mergeCallAndResult: boolean;
+};
+export {};

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

@@ -0,0 +1,64 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { Component } from "@oh-my-pi/pi-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";
+declare const astGrepSchema: z.ZodObject<{
+    pat: z.ZodString;
+    paths: z.ZodArray<z.ZodString>;
+    skip: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+}, z.core.$strip>;
+export interface AstGrepToolDetails {
+    matchCount: number;
+    fileCount: number;
+    filesSearched: number;
+    limitReached: boolean;
+    parseErrors?: string[];
+    scopePath?: string;
+    files?: string[];
+    fileMatches?: Array<{
+        path: string;
+        count: number;
+    }>;
+    meta?: OutputMeta;
+    /** Pre-formatted text for the user-visible TUI render. Mirrors `result.text` lines but uses
+     * a `│` gutter and `*` to mark match lines. The TUI uses this directly so it never parses model-facing text. */
+    displayContent?: string;
+}
+export declare class AstGrepTool implements AgentTool<typeof astGrepSchema, AstGrepToolDetails> {
+    private readonly session;
+    readonly name = "ast_grep";
+    readonly label = "AST Grep";
+    readonly summary = "Search code with AST patterns (structural grep)";
+    readonly description: string;
+    readonly parameters: z.ZodObject<{
+        pat: z.ZodString;
+        paths: z.ZodArray<z.ZodString>;
+        skip: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    }, z.core.$strip>;
+    readonly strict = true;
+    readonly loadMode = "discoverable";
+    constructor(session: ToolSession);
+    execute(_toolCallId: string, params: z.infer<typeof astGrepSchema>, signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<AstGrepToolDetails>, _context?: AgentToolContext): Promise<AgentToolResult<AstGrepToolDetails>>;
+}
+interface AstGrepRenderArgs {
+    pat?: string;
+    paths?: string[];
+    skip?: number;
+}
+export declare const astGrepToolRenderer: {
+    inline: boolean;
+    renderCall(args: AstGrepRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: AstGrepToolDetails;
+        isError?: boolean;
+    }, options: RenderResultOptions, uiTheme: Theme, args?: AstGrepRenderArgs): Component;
+    mergeCallAndResult: boolean;
+};
+export {};

package/dist/types/tools/auto-generated-guard.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Check if a file is auto-generated by examining its content.
+ * Throws ToolError if the file appears to be auto-generated.
+ *
+ * @param absolutePath - Absolute path to the file
+ * @param displayPath - Path to show in error messages (relative or as provided)
+ */
+export declare function assertEditableFile(absolutePath: string, displayPath?: string): Promise<void>;
+/**
+ * Check if file content is auto-generated.
+ * Uses only the first CHECK_BYTE_COUNT characters of the content.
+ * Throws ToolError if the content appears to be auto-generated.
+ *
+ * @param content - File content to check (can be full content or prefix)
+ * @param displayPath - Path to show in error messages
+ */
+export declare function assertEditableFileContent(content: string, displayPath: string): void;

package/dist/types/tools/bash-command-fixup.d.ts

@@ -0,0 +1,16 @@
+export interface BashFixupResult {
+    /** Possibly-rewritten command. */
+    command: string;
+    /** Substrings that were stripped, in the order they were removed. */
+    stripped: string[];
+}
+/**
+ * Apply both fixups to a bash command. On any parse failure, multi-line input,
+ * or no-op transform, returns the input verbatim with `stripped: []`.
+ */
+export declare function applyBashFixups(command: string): BashFixupResult;
+/**
+ * Human-readable notice for the fixups that fired. Mirrors the shape of
+ * `formatTimeoutClampNotice` so it can ride alongside the other bash notices.
+ */
+export declare function formatBashFixupNotice(stripped: readonly string[]): string | undefined;

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

@@ -0,0 +1,16 @@
+import type { AgentToolContext } from "@oh-my-pi/pi-agent-core";
+import { type OutputSummary } from "../session/streaming-output";
+export interface BashInteractiveResult extends OutputSummary {
+    exitCode: number | undefined;
+    cancelled: boolean;
+    timedOut: boolean;
+}
+export declare function runInteractiveBashPty(ui: NonNullable<AgentToolContext["ui"]>, options: {
+    command: string;
+    cwd: string;
+    timeoutMs: number;
+    signal?: AbortSignal;
+    env?: Record<string, string>;
+    artifactPath?: string;
+    artifactId?: string;
+}): Promise<BashInteractiveResult>;

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

@@ -0,0 +1,24 @@
+/**
+ * Bash intent interceptor - redirects common shell patterns to proper tools.
+ *
+ * When an LLM calls bash with patterns like `grep`, `cat`, `find`, etc.,
+ * this interceptor provides helpful error messages directing them to use
+ * the specialized tools instead.
+ */
+import { type BashInterceptorRule } from "../config/settings-schema";
+export interface InterceptionResult {
+    /** If true, the bash command should be blocked */
+    block: boolean;
+    /** Error message to return instead of executing */
+    message?: string;
+    /** Suggested tool to use instead */
+    suggestedTool?: string;
+}
+/**
+ * Check if a bash command should be intercepted.
+ *
+ * @param command The bash command to check
+ * @param availableTools Set of tool names that are available
+ * @returns InterceptionResult indicating if the command should be blocked
+ */
+export declare function checkBashInterception(command: string, availableTools: string[], rules?: BashInterceptorRule[]): InterceptionResult;

package/dist/types/tools/bash-pty-selection.d.ts

@@ -0,0 +1,7 @@
+/** Minimal UI-capability fields needed to decide whether bash can use the local PTY overlay. */
+export interface BashPtyContext {
+    hasUI?: boolean;
+    ui?: unknown;
+}
+/** Return whether a bash tool call should use the local interactive PTY overlay. */
+export declare function canUseInteractiveBashPty(pty: boolean, ctx: BashPtyContext | undefined): boolean;

package/dist/types/tools/bash-skill-urls.d.ts

@@ -0,0 +1,31 @@
+import type { Skill } from "../extensibility/skills";
+import { type LocalProtocolOptions } from "../internal-urls";
+import type { InternalResource } from "../internal-urls/types";
+interface InternalUrlResolver {
+    canHandle(input: string): boolean;
+    resolve(input: string): Promise<InternalResource>;
+}
+export interface InternalUrlExpansionOptions {
+    skills: readonly Skill[];
+    noEscape?: boolean;
+    internalRouter?: InternalUrlResolver;
+    localOptions?: LocalProtocolOptions;
+    ensureLocalParentDirs?: boolean;
+}
+/**
+ * Resolve a single skill:// URL to its absolute filesystem path.
+ * Does NOT read file content or verify existence.
+ */
+export declare function resolveSkillUrlToPath(url: string, skills: readonly Skill[]): string;
+/**
+ * Expand all skill:// URIs in a bash command string.
+ * Returns the command with URIs replaced by shell-escaped absolute paths.
+ * Throws ToolError if any URI cannot be resolved.
+ */
+export declare function expandSkillUrls(command: string, skills: readonly Skill[]): string;
+/**
+ * Expand supported internal URLs in a bash command string to shell-escaped absolute paths.
+ * Supported schemes: skill://, agent://, artifact://, memory://, rule://, local://
+ */
+export declare function expandInternalUrls(command: string, options: InternalUrlExpansionOptions): Promise<string>;
+export {};

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

@@ -0,0 +1,130 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { Component } from "@oh-my-pi/pi-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;
+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);
+    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/attach.d.ts

@@ -0,0 +1,34 @@
+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>;
+/**
+ * If any running instance of `exe` was launched with `--remote-debugging-port`
+ * and that endpoint actually answers, return it so attach can reuse it instead
+ * of killing and respawning. Idempotent re-attaches are the common case.
+ */
+export declare function findReusableCdp(exe: string, signal?: AbortSignal): Promise<{
+    cdpUrl: string;
+    pid: number;
+} | 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,60 @@
+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;
+}
+/** 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,42 @@
+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: "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;
+    };
+}
+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 holdBrowser(handle: BrowserHandle): void;
+export declare function releaseBrowser(handle: BrowserHandle, opts: {
+    kill: boolean;
+}): Promise<void>;

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

@@ -0,0 +1,50 @@
+/**
+ * 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 "@oh-my-pi/pi-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;
+    };
+    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 {};