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

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

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

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

@@ -0,0 +1,63 @@
+import type { ToolSession } from "../../sdk";
+import { type BrowserHandle, type BrowserKindTag } 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>;
+}
+export interface TabSession {
+    name: string;
+    browser: BrowserHandle;
+    targetId: string;
+    worker: WorkerHandle;
+    state: "alive" | "dead";
+    info: ReadyInfo;
+    pending: Map<string, PendingRun>;
+    dialogPolicy?: DialogPolicy;
+    kindTag: BrowserKindTag;
+}
+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;
+}
+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>;
+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,19 @@
+import type { HTMLElement } from "linkedom";
+import type { ElementHandle } 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 declare class WorkerCore {
+    #private;
+    constructor(transport: Transport);
+    nextElementId(): number;
+    cacheElement(id: number, handle: ElementHandle): void;
+}

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

@@ -0,0 +1,114 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import * as z from "zod/v4";
+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 { extractReadableFromHtml, type ReadableFormat, type ReadableResult } from "./browser/readable";
+export type { Observation, ObservationEntry } from "./browser/tab-protocol";
+declare const browserSchema: z.ZodObject<{
+    action: z.ZodEnum<{
+        close: "close";
+        open: "open";
+        run: "run";
+    }>;
+    name: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    app: z.ZodOptional<z.ZodObject<{
+        path: z.ZodOptional<z.ZodString>;
+        cdp_url: z.ZodOptional<z.ZodString>;
+        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        target: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        scale: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    wait_until: z.ZodOptional<z.ZodEnum<{
+        domcontentloaded: "domcontentloaded";
+        load: "load";
+        networkidle0: "networkidle0";
+        networkidle2: "networkidle2";
+    }>>;
+    dialogs: z.ZodOptional<z.ZodEnum<{
+        accept: "accept";
+        dismiss: "dismiss";
+    }>>;
+    code: z.ZodOptional<z.ZodString>;
+    timeout: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    all: z.ZodOptional<z.ZodBoolean>;
+    kill: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/** Input schema for the browser tool. */
+export type BrowserParams = z.infer<typeof browserSchema>;
+/** 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 label = "Browser";
+    readonly loadMode = "discoverable";
+    readonly summary = "Control a headless browser to navigate and interact with web pages";
+    readonly parameters: z.ZodObject<{
+        action: z.ZodEnum<{
+            close: "close";
+            open: "open";
+            run: "run";
+        }>;
+        name: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+        app: z.ZodOptional<z.ZodObject<{
+            path: z.ZodOptional<z.ZodString>;
+            cdp_url: z.ZodOptional<z.ZodString>;
+            args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            target: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        viewport: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            scale: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        wait_until: z.ZodOptional<z.ZodEnum<{
+            domcontentloaded: "domcontentloaded";
+            load: "load";
+            networkidle0: "networkidle0";
+            networkidle2: "networkidle2";
+        }>>;
+        dialogs: z.ZodOptional<z.ZodEnum<{
+            accept: "accept";
+            dismiss: "dismiss";
+        }>>;
+        code: z.ZodOptional<z.ZodString>;
+        timeout: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+        all: z.ZodOptional<z.ZodBoolean>;
+        kill: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    readonly strict = true;
+    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/calculator.d.ts

@@ -0,0 +1,76 @@
+import type { AgentTool, AgentToolResult } 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 ".";
+declare const calculatorSchema: z.ZodObject<{
+    calculations: z.ZodArray<z.ZodObject<{
+        expression: z.ZodString;
+        prefix: z.ZodString;
+        suffix: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export interface CalculatorToolDetails {
+    results: Array<{
+        expression: string;
+        value: number;
+        output: string;
+    }>;
+}
+type CalculatorParams = z.infer<typeof calculatorSchema>;
+/**
+ * Calculator tool for evaluating mathematical expressions.
+ *
+ * Supports decimal, hex (0x), binary (0b), octal (0o) literals,
+ * standard arithmetic operators, and parentheses.
+ */
+export declare class CalculatorTool implements AgentTool<typeof calculatorSchema, CalculatorToolDetails> {
+    readonly name = "calc";
+    readonly label = "Calc";
+    readonly summary = "Evaluate a mathematical expression";
+    readonly loadMode = "discoverable";
+    readonly description: string;
+    readonly parameters: z.ZodObject<{
+        calculations: z.ZodArray<z.ZodObject<{
+            expression: z.ZodString;
+            prefix: z.ZodString;
+            suffix: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    readonly strict = true;
+    constructor(_session: ToolSession);
+    execute(_toolCallId: string, { calculations }: CalculatorParams, signal?: AbortSignal): Promise<AgentToolResult<CalculatorToolDetails>>;
+}
+interface CalculatorRenderArgs {
+    calculations?: Array<{
+        expression: string;
+        prefix?: string;
+        suffix?: string;
+    }>;
+}
+/**
+ * TUI renderer for calculator tool calls and results.
+ * Handles both collapsed (preview) and expanded (full) display modes.
+ */
+export declare const calculatorToolRenderer: {
+    /**
+     * Render the tool call header showing the first expression and count.
+     * Format: "Calc <expression> (N calcs)"
+     */
+    renderCall(args: CalculatorRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component;
+    /**
+     * Render calculation results as a tree list.
+     * Collapsed mode shows first N items with expand hint; expanded shows all.
+     */
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: CalculatorToolDetails;
+        isError?: boolean;
+    }, options: RenderResultOptions, uiTheme: Theme, args?: CalculatorRenderArgs): Component;
+    mergeCallAndResult: boolean;
+};
+export {};

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

@@ -0,0 +1,63 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import * as z from "zod/v4";
+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;
+}
+declare const checkpointSchema: z.ZodObject<{
+    goal: z.ZodString;
+}, z.core.$strip>;
+type CheckpointParams = z.infer<typeof checkpointSchema>;
+declare const rewindSchema: z.ZodObject<{
+    report: z.ZodString;
+}, z.core.$strip>;
+type RewindParams = z.infer<typeof rewindSchema>;
+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 label = "Checkpoint";
+    readonly summary = "Create a git-based checkpoint to save and restore session state";
+    readonly description: string;
+    readonly parameters: z.ZodObject<{
+        goal: z.ZodString;
+    }, z.core.$strip>;
+    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 label = "Rewind";
+    readonly summary = "Rewind to a previously created checkpoint";
+    readonly description: string;
+    readonly parameters: z.ZodObject<{
+        report: z.ZodString;
+    }, z.core.$strip>;
+    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 {};

package/dist/types/tools/conflict-detect.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Detect and resolve unresolved git merge conflicts that surface in `read`
+ * output.
+ *
+ * Workflow:
+ *   1. `read` collects lines from disk as usual.
+ *   2. `scanConflictLines` inspects those lines (no extra I/O) for
+ *      well-formed `<<<<<<<` / `=======` / `>>>>>>>` blocks.
+ *   3. Each completed block is registered with the session's
+ *      `ConflictHistory`, which assigns it a stable id.
+ *   4. The read output is returned verbatim with a short footer naming
+ *      every conflict id surfaced, and the agent calls
+ *      `write({ path: "conflict://<id>", content })` to splice the
+ *      recorded region with the chosen content.
+ *
+ * Marker shape is strict: only column-0 markers of the exact prefix length
+ * followed by either EOL or a single space + label count. Lines that
+ * merely start with `<` or `=` never match.
+ */
+import type { ToolSession } from "./index";
+export interface ConflictBlock {
+    /** 1-indexed line of the `<<<<<<<` marker. */
+    startLine: number;
+    /** 1-indexed line of the `=======` separator. */
+    separatorLine: number;
+    /** 1-indexed line of the `>>>>>>>` marker. */
+    endLine: number;
+    /** 1-indexed line of the `|||||||` base marker (diff3 only). */
+    baseLine?: number;
+    oursLabel?: string;
+    baseLabel?: string;
+    theirsLabel?: string;
+    oursLines: string[];
+    baseLines?: string[];
+    theirsLines: string[];
+}
+/**
+ * Scan an already-collected array of file lines for completed conflict
+ * blocks. `firstLineNumber` is the 1-indexed line number of `lines[0]`
+ * (so a windowed read starting at line 200 passes `firstLineNumber: 200`).
+ *
+ * Only fully-closed blocks (opener + separator + closer all present in
+ * the window) are returned. A block whose closer is past the window's
+ * tail is dropped — the agent will see the open marker and can widen
+ * the read.
+ */
+export declare function scanConflictLines(lines: readonly string[], firstLineNumber: number): ConflictBlock[];
+/**
+ * Scan a whole file for unresolved conflict blocks.
+ *
+ * Reads at most `maxBytes` (default 10 MB) so this stays cheap on
+ * pathological files. Files truncated by the cap report
+ * `scanTruncated: true`; only complete blocks within the scanned prefix
+ * are returned, so trailing partial markers never invent fake blocks.
+ */
+export declare function scanFileForConflicts(absolutePath: string, options?: {
+    maxBytes?: number;
+}): Promise<{
+    blocks: ConflictBlock[];
+    scanTruncated: boolean;
+}>;
+/**
+ * Recorded conflict block keyed by a session-stable id. The history is
+ * append-only; ids stay valid even after later writes resolve other
+ * blocks in the same file, so retries don't depend on re-reading.
+ */
+export interface ConflictEntry extends ConflictBlock {
+    id: number;
+    absolutePath: string;
+    displayPath: string;
+}
+/** Per-session log of conflict regions surfaced by `read`. */
+export declare class ConflictHistory {
+    #private;
+    /**
+     * Register a conflict block. Returns the (possibly pre-existing) entry
+     * — if the same `absolutePath`+`startLine` was registered before, the
+     * earlier id is reused so a re-read does not inflate the counter or
+     * orphan the prior id. The recorded region is overwritten on re-read
+     * so the splice always reflects the current marker positions on disk.
+     */
+    register(input: Omit<ConflictEntry, "id">): ConflictEntry;
+    get(id: number): ConflictEntry | undefined;
+    /** Snapshot every registered entry in insertion (id) order. */
+    entries(): ConflictEntry[];
+    /** Drop a single entry by id. Used after a successful resolve. */
+    invalidate(id: number): void;
+    /** Drop every entry referencing `absolutePath`. Used after a successful resolve. */
+    invalidatePath(absolutePath: string): void;
+}
+/** Lazily attach a `ConflictHistory` to the session and return it. */
+export declare function getConflictHistory(session: ToolSession): ConflictHistory;
+/** A side of a conflict block that the `read` tool can render via `conflict://N/<scope>`. */
+export type ConflictScope = "ours" | "theirs" | "base";
+/** Parsed `conflict://<N>` / `conflict://<N>/<scope>` / `conflict://*` URI. */
+export interface ParsedConflictUri {
+    /** `"*"` selects every currently-registered conflict (bulk write only). */
+    id: number | "*";
+    scope?: ConflictScope;
+    /**
+     * When `raw` was a malformed `<file-prefix>:conflict://…` path, the
+     * stripped prefix is preserved here so callers can surface a gentle
+     * "you don't need the file path" note. `undefined` for clean URIs.
+     */
+    recoveredPrefix?: string;
+}
+/**
+ * Parse a `conflict://<N>`, `conflict://<N>/<scope>`, or `conflict://*` URI.
+ *
+ * Returns `null` for non-conflict paths; throws `ToolError` for a
+ * well-formed scheme with an invalid id or scope so the agent gets a
+ * clear actionable message rather than a confusing "not found" later.
+ *
+ * `*` is the bulk-write wildcard — only valid as `conflict://*` (no
+ * scope segment). Use it with `write({ path: "conflict://*", content })`
+ * to apply `content` (with optional `@ours` / `@theirs` / `@base` /
+ * `@both` shorthand) to every currently-registered conflict in one shot.
+ */
+export declare function parseConflictUri(raw: string): ParsedConflictUri | null;
+/**
+ * Splice the conflict region recorded in `entry` out of `originalText`
+ * and replace it with `replacement` (markers and all sides included).
+ *
+ * Works like the edit tool's patch infra: locates the recorded marker
+ * block by content (anchored to `entry.startLine` as the preferred
+ * match), so out-of-band edits earlier in the file that shift line
+ * numbers don't break resolution. Throws clearly when the marker block
+ * has actually been altered or removed.
+ */
+export declare function spliceConflict(originalText: string, entry: ConflictEntry, replacement: string): string;
+/**
+ * Expand `@ours` / `@theirs` / `@base` / `@both` line tokens against the
+ * recorded sections of `entry`. A token only triggers when it is the
+ * entire content of a line (after CRLF normalisation), so `@ours` inside
+ * actual code is left alone. Other lines pass through verbatim.
+ *
+ * - `@ours`    → expands to the recorded `oursLines` (in order).
+ * - `@theirs`  → expands to the recorded `theirsLines` (in order).
+ * - `@base`    → expands to `baseLines`; throws if no base section was
+ *               recorded (i.e. the conflict was 2-way, not diff3).
+ * - `@both`    → expands to `oursLines` then `theirsLines`.
+ */
+export declare function expandContentTokens(content: string, entry: ConflictEntry): string;
+/**
+ * Materialise a conflict block for `conflict://<N>` reads (and their
+ * `/ours` / `/theirs` / `/base` scopes).
+ *
+ * Returns:
+ * - `lines`: the lines to render, ordered top-to-bottom.
+ * - `startLine`: the 1-indexed file line number `lines[0]` corresponds
+ *   to, so the read formatter can label hashline anchors with the
+ *   original file positions.
+ *
+ * Bare (no scope) returns the full block including marker lines. A
+ * scoped view returns only that side's body — `base` throws when the
+ * recorded conflict is a 2-way merge with no base section.
+ */
+export declare function renderConflictRegion(entry: ConflictEntry, scope: ConflictScope | undefined): {
+    lines: string[];
+    startLine: number;
+};
+/**
+ * Build a compact diff-style footer describing the conflicts registered
+ * during a read. Designed to be appended after the file content.
+ *
+ * Format:
+ *
+ *     ⚠ N unresolved conflicts detected
+ *     - ours = HEAD
+ *     - theirs = feature/x
+ *     NOTICE: …
+ *
+ *     ──── #1  L42-48 ────
+ *     <<< ours
+ *     …ours body…
+ *     === base ≡ ours
+ *     >>> theirs
+ *     …theirs body…
+ *
+ * Labels are aggregated once at the top from the first entry that has
+ * them; when a section body equals another section's body the redundant
+ * body is collapsed to `≡ <other>`.
+ */
+export interface FormatConflictWarningOptions {
+    /**
+     * Total number of conflicts in the underlying file. If greater than
+     * `entries.length` the header notes how many are visible vs the total
+     * and points at `:conflicts` for the compact list.
+     */
+    totalInFile?: number;
+    /** Display path used inside the `:conflicts` hint. */
+    displayPath?: string;
+    /** Whether the underlying file scan hit its byte cap. */
+    scanTruncated?: boolean;
+}
+export declare function formatConflictWarning(entries: readonly ConflictEntry[], options?: FormatConflictWarningOptions): string;
+/**
+ * Render a single-line-per-block index of every conflict in a file.
+ * Used by the `<path>:conflicts` read selector to give the agent a cheap overview
+ * of a heavily-conflicted file without dumping every body.
+ */
+export declare function formatConflictSummary(entries: readonly ConflictEntry[], options?: {
+    displayPath: string;
+    scanTruncated?: boolean;
+}): string;