jeopi-cli 16.2.14 → 16.2.17

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

@@ -0,0 +1,221 @@
+/**
+ * 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;
+/**
+ * True when two registered blocks record the same marker-block content
+ * (labels and all sides). Out-of-band edits can shift a block's line
+ * numbers between reads, registering a fresh id while the stale one
+ * persists; callers use content identity to treat a locate-miss for the
+ * stale twin as "already resolved" instead of a hard failure.
+ */
+export declare function conflictRegionsEqual(a: ConflictBlock, b: ConflictBlock): boolean;
+/**
+ * True when the entry's recorded marker block still occurs in `content`
+ * (LF-normalized — recorded sections are stored LF). Distinguishes a stale
+ * re-registration of a just-resolved region (no longer present) from a
+ * DISTINCT conflict block that happens to be byte-identical (still present
+ * elsewhere in the file and must stay addressable).
+ */
+export declare function conflictRegionPresent(content: string, entry: ConflictBlock): boolean;
+/**
+ * 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;

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

@@ -0,0 +1,19 @@
+import type { AgentToolContext, ToolCallContext } from "jeopi-agent-core";
+import type { CustomToolContext } from "../extensibility/custom-tools/types";
+import type { ExtensionUIContext } from "../extensibility/extensions/types";
+declare module "jeopi-agent-core" {
+    interface AgentToolContext extends CustomToolContext {
+        ui?: ExtensionUIContext;
+        hasUI?: boolean;
+        toolNames?: string[];
+        toolCall?: ToolCallContext;
+    }
+}
+export declare class ToolContextStore {
+    #private;
+    private readonly getBaseContext;
+    constructor(getBaseContext: () => CustomToolContext);
+    getContext(toolCall?: ToolCallContext): AgentToolContext;
+    setUIContext(uiContext: ExtensionUIContext, hasUI: boolean): void;
+    setToolNames(names: string[]): void;
+}

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

@@ -0,0 +1,156 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback, RenderResultOptions, ToolApprovalDecision } from "jeopi-agent-core";
+import type { ToolExample } from "jeopi-ai";
+import { type Component } from "jeopi-tui";
+import { type DapBreakpointRecord, type DapContinueOutcome, type DapDataBreakpointInfoResponse, type DapDataBreakpointRecord, type DapDisassembledInstruction, type DapEvaluateResponse, type DapFunctionBreakpointRecord, type DapInstructionBreakpointRecord, type DapModule, type DapScope, type DapSessionSummary, type DapSource, type DapStackFrame, type DapThread, type DapVariable } from "../dap";
+import type { Theme } from "../modes/theme/theme";
+import type { ToolSession } from ".";
+import type { OutputMeta } from "./output-meta";
+/**
+ * DAP debug actions that only read program state (no mutation, no execution).
+ * Execution-side actions (`launch`, `attach`, `continue`, `step_*`, `pause`,
+ * `evaluate`, breakpoint mutations, memory writes) are exec-tier.
+ */
+export declare const DEBUG_READONLY_ACTIONS: ReadonlySet<string>;
+declare const debugSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    action: "attach" | "continue" | "custom_request" | "data_breakpoint_info" | "disassemble" | "evaluate" | "launch" | "loaded_sources" | "modules" | "output" | "pause" | "read_memory" | "remove_breakpoint" | "remove_data_breakpoint" | "remove_instruction_breakpoint" | "scopes" | "sessions" | "set_breakpoint" | "set_data_breakpoint" | "set_instruction_breakpoint" | "stack_trace" | "step_in" | "step_out" | "step_over" | "terminate" | "threads" | "variables" | "write_memory";
+    program?: string | undefined;
+    args?: string[] | undefined;
+    adapter?: string | undefined;
+    cwd?: string | undefined;
+    file?: string | undefined;
+    line?: number | undefined;
+    function?: string | undefined;
+    name?: string | undefined;
+    condition?: string | undefined;
+    hit_condition?: string | undefined;
+    expression?: string | undefined;
+    context?: string | undefined;
+    frame_id?: number | undefined;
+    scope_id?: number | undefined;
+    variable_ref?: number | undefined;
+    pid?: number | undefined;
+    port?: number | undefined;
+    host?: string | undefined;
+    levels?: number | undefined;
+    memory_reference?: string | undefined;
+    instruction_reference?: string | undefined;
+    instruction_count?: number | undefined;
+    instruction_offset?: number | undefined;
+    count?: number | undefined;
+    data?: string | undefined;
+    data_id?: string | undefined;
+    access_type?: "read" | "readWrite" | "write" | undefined;
+    command?: string | undefined;
+    arguments?: {
+        [x: string]: unknown;
+    } | undefined;
+    offset?: number | undefined;
+    resolve_symbols?: boolean | undefined;
+    allow_partial?: boolean | undefined;
+    start_module?: number | undefined;
+    module_count?: number | undefined;
+    timeout?: number | undefined;
+}, {}>;
+export type DebugParams = typeof debugSchema.infer;
+export type DebugAction = DebugParams["action"];
+interface DebugToolDetails {
+    action: DebugAction;
+    success: boolean;
+    snapshot?: DapSessionSummary;
+    sessions?: DapSessionSummary[];
+    stackFrames?: DapStackFrame[];
+    threads?: DapThread[];
+    scopes?: DapScope[];
+    variables?: DapVariable[];
+    sources?: DapSource[];
+    modules?: DapModule[];
+    evaluation?: DapEvaluateResponse;
+    breakpoints?: DapBreakpointRecord[];
+    functionBreakpoints?: DapFunctionBreakpointRecord[];
+    instructionBreakpoints?: DapInstructionBreakpointRecord[];
+    dataBreakpoints?: DapDataBreakpointRecord[];
+    dataBreakpointInfo?: DapDataBreakpointInfoResponse;
+    disassembly?: DapDisassembledInstruction[];
+    memoryAddress?: string;
+    memoryData?: string;
+    unreadableBytes?: number;
+    bytesWritten?: number;
+    customBody?: unknown;
+    output?: string;
+    adapter?: string;
+    state?: DapContinueOutcome["state"];
+    timedOut?: boolean;
+    meta?: OutputMeta;
+}
+interface DebugRenderArgs extends Partial<DebugParams> {
+}
+export declare const debugToolRenderer: {
+    renderCall(args: DebugRenderArgs, _options: RenderResultOptions, theme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: DebugToolDetails;
+        isError?: boolean;
+    }, options: RenderResultOptions, theme: Theme, args?: DebugRenderArgs): Component;
+    mergeCallAndResult: boolean;
+    inline: boolean;
+};
+export declare class DebugTool implements AgentTool<typeof debugSchema, DebugToolDetails> {
+    private readonly session;
+    readonly name = "debug";
+    readonly approval: (args: unknown) => ToolApprovalDecision;
+    readonly formatApprovalDetails: (args: unknown) => string[];
+    readonly label = "Debug";
+    readonly summary = "Debug a running process with DAP (debugger adapter protocol)";
+    readonly description: string;
+    readonly parameters: import("arktype/internal/variants/object.ts").ObjectType<{
+        action: "attach" | "continue" | "custom_request" | "data_breakpoint_info" | "disassemble" | "evaluate" | "launch" | "loaded_sources" | "modules" | "output" | "pause" | "read_memory" | "remove_breakpoint" | "remove_data_breakpoint" | "remove_instruction_breakpoint" | "scopes" | "sessions" | "set_breakpoint" | "set_data_breakpoint" | "set_instruction_breakpoint" | "stack_trace" | "step_in" | "step_out" | "step_over" | "terminate" | "threads" | "variables" | "write_memory";
+        program?: string | undefined;
+        args?: string[] | undefined;
+        adapter?: string | undefined;
+        cwd?: string | undefined;
+        file?: string | undefined;
+        line?: number | undefined;
+        function?: string | undefined;
+        name?: string | undefined;
+        condition?: string | undefined;
+        hit_condition?: string | undefined;
+        expression?: string | undefined;
+        context?: string | undefined;
+        frame_id?: number | undefined;
+        scope_id?: number | undefined;
+        variable_ref?: number | undefined;
+        pid?: number | undefined;
+        port?: number | undefined;
+        host?: string | undefined;
+        levels?: number | undefined;
+        memory_reference?: string | undefined;
+        instruction_reference?: string | undefined;
+        instruction_count?: number | undefined;
+        instruction_offset?: number | undefined;
+        count?: number | undefined;
+        data?: string | undefined;
+        data_id?: string | undefined;
+        access_type?: "read" | "readWrite" | "write" | undefined;
+        command?: string | undefined;
+        arguments?: {
+            [x: string]: unknown;
+        } | undefined;
+        offset?: number | undefined;
+        resolve_symbols?: boolean | undefined;
+        allow_partial?: boolean | undefined;
+        start_module?: number | undefined;
+        module_count?: number | undefined;
+        timeout?: number | undefined;
+    }, {}>;
+    readonly strict = true;
+    readonly examples: readonly ToolExample<typeof debugSchema.infer>[];
+    readonly concurrency = "exclusive";
+    readonly loadMode = "discoverable";
+    constructor(session: ToolSession);
+    static createIf(session: ToolSession): DebugTool | null;
+    execute(_toolCallId: string, params: DebugParams, signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<DebugToolDetails>, _context?: AgentToolContext): Promise<AgentToolResult<DebugToolDetails>>;
+}
+export {};

package/dist/types/tools/eval-backends.d.ts

@@ -0,0 +1,15 @@
+import type { ToolSession } from ".";
+export interface EvalBackendsAllowance {
+    python: boolean;
+    js: boolean;
+    ruby: boolean;
+    julia: boolean;
+}
+/** Read per-backend allowance from settings (py/js default on; rb/jl opt-in, default off). */
+export declare function readEvalBackendsAllowance(session: ToolSession): EvalBackendsAllowance;
+/**
+ * Materialize the active eval backend allowance: PI_PY / PI_JS / PI_RB / PI_JL
+ * env flags override the per-key settings; otherwise settings win (py/js default
+ * on, rb/jl default off).
+ */
+export declare function resolveEvalBackends(session: ToolSession): EvalBackendsAllowance;

package/dist/types/tools/eval-render.d.ts

@@ -0,0 +1,58 @@
+/**
+ * TUI rendering for the eval tool.
+ *
+ * Split out from `eval.ts` so the renderer can be imported by `renderers.ts`
+ * without dragging the eval *runtime* (JS/Python/Ruby/Julia backends ->
+ * agent bridge -> task executor -> sdk -> extension loader -> root barrel)
+ * into the renderer module graph. That transitive chain re-enters
+ * `renderers.ts` while `eval.ts` is still initializing, which previously
+ * crashed module load with a TDZ `Cannot access 'evalToolRenderer' before
+ * initialization`.
+ */
+import type { Component } from "jeopi-tui";
+import type { EvalStatusEvent, EvalToolDetails } from "../eval/types";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import { type Theme } from "../modes/theme/theme";
+export declare const EVAL_DEFAULT_PREVIEW_LINES = 10;
+interface EvalRenderCellArg {
+    language?: string;
+    code?: string;
+    title?: string;
+}
+interface EvalRenderArgs {
+    language?: string;
+    code?: string;
+    title?: string;
+    cells?: EvalRenderCellArg[];
+    __partialJson?: string;
+}
+interface EvalRenderContext {
+    output?: string;
+    expanded?: boolean;
+    previewLines?: number;
+    timeout?: number;
+}
+/**
+ * Append or replace a status event. `agent` events are progress snapshots keyed
+ * by `id`, so they coalesce in place (preserving first-seen order); every other
+ * op is a discrete action and simply appends. Keeps the persisted event list
+ * bounded even when a subagent emits hundreds of throttled progress ticks.
+ */
+export declare function upsertStatusEvent(events: EvalStatusEvent[], event: EvalStatusEvent): void;
+export declare const evalToolRenderer: {
+    renderCall(args: EvalRenderArgs, options: RenderResultOptions, uiTheme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: EvalToolDetails;
+    }, options: RenderResultOptions & {
+        renderContext?: EvalRenderContext;
+    }, uiTheme: Theme, _args?: EvalRenderArgs): Component;
+    mergeCallAndResult: boolean;
+    inline: boolean;
+    provisionalPendingPreview: string;
+    provisionalPartialResult: boolean;
+};
+export {};

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

@@ -0,0 +1,66 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "jeopi-agent-core";
+import type { ToolExample } from "jeopi-ai";
+import type { EvalToolDetails } from "../eval/types";
+import type { ToolSession } from ".";
+export { EVAL_DEFAULT_PREVIEW_LINES, evalToolRenderer } from "./eval-render";
+/** Language tokens the eval tool accepts, in stable display order. */
+export type EvalLanguageToken = "py" | "js" | "rb" | "jl";
+/**
+ * Per-call input: a single cell. State persists within a language across
+ * separate eval calls and across tool calls, so each call is one logical step
+ * and later calls reuse what earlier ones defined. This static schema carries
+ * the full language union for typing; {@link buildEvalSchema} narrows the wire
+ * copy per session so disabled backends are never advertised to the model.
+ */
+export declare const evalSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    title?: string | undefined;
+    timeout?: number | undefined;
+    reset?: boolean | undefined;
+    language: "jl" | "js" | "py" | "rb";
+    code: string;
+}, {}>;
+export type EvalToolParams = typeof evalSchema.infer;
+export type EvalCellInput = EvalToolParams;
+export type EvalToolResult = {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    details: EvalToolDetails | undefined;
+};
+export type EvalProxyExecutor = (params: EvalToolParams, signal?: AbortSignal) => Promise<EvalToolResult>;
+export interface EvalToolDescriptionOptions {
+    py?: boolean;
+    js?: boolean;
+    rb?: boolean;
+    jl?: boolean;
+    /**
+     * Parent spawn policy (`getSessionSpawns`). `true`/omitted means unrestricted,
+     * `false`/`""` hides `agent()`, and a comma list drives the advertised default.
+     */
+    spawns?: boolean | string | null;
+}
+export declare function getEvalToolDescription(options?: EvalToolDescriptionOptions): string;
+export interface EvalToolOptions {
+    proxyExecutor?: EvalProxyExecutor;
+}
+export declare class EvalTool implements AgentTool<typeof evalSchema> {
+    #private;
+    private readonly session;
+    readonly name = "eval";
+    readonly approval: "exec";
+    readonly formatApprovalDetails: (args: unknown) => string[];
+    get summary(): string;
+    readonly loadMode = "essential";
+    readonly label = "Eval";
+    get description(): string;
+    /** All reuse-chain examples; the `examples` getter filters by enabled languages. */
+    private static readonly ALL_EXAMPLES;
+    get examples(): readonly ToolExample<typeof evalSchema.infer>[];
+    get parameters(): typeof evalSchema;
+    readonly concurrency = "exclusive";
+    readonly strict = true;
+    readonly intent: (args: Partial<typeof evalSchema.infer>) => string | undefined;
+    constructor(session: ToolSession | null, options?: EvalToolOptions);
+    execute(_toolCallId: string, params: typeof evalSchema.infer, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback, _ctx?: AgentToolContext): Promise<AgentToolResult<EvalToolDetails | undefined>>;
+}

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

@@ -0,0 +1,99 @@
+import type { AgentToolResult } from "jeopi-agent-core";
+import type { FetchImpl } from "jeopi-ai";
+import { type Component } from "jeopi-tui";
+import type { Settings } from "../config/settings";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import { type Theme } from "../modes/theme/theme";
+import type { ToolSession } from "../sdk";
+import type { AgentStorage } from "../session/agent-storage";
+import { type OutputMeta } from "./output-meta";
+import { type LineRange } from "./path-utils";
+export interface ParsedReadUrlTarget {
+    path: string;
+    raw: boolean;
+    offset?: number;
+    limit?: number;
+    /** Populated only when the selector carries 2+ ranges. Single-range stays on offset/limit. */
+    ranges?: readonly LineRange[];
+}
+export declare function parseReadUrlTarget(readPath: string): ParsedReadUrlTarget | null;
+/** Reader backends for {@link renderHtmlToText}, in default priority order. */
+export type FetchProvider = "native" | "trafilatura" | "lynx" | "parallel" | "jina";
+/**
+ * Render HTML to markdown by trying reader backends in priority order: native
+ * (in-process), trafilatura, lynx, Parallel, then Jina. The `providers.fetch`
+ * setting picks the order — `auto` uses the default above; any specific backend
+ * is tried first, then the remaining backends as fallbacks. Every backend's
+ * output must clear the same quality gate (>100 non-whitespace chars and not
+ * {@link isLowQualityOutput}) before it is accepted, otherwise the next backend
+ * is tried.
+ *
+ * The overall `timeout` budget bounds the whole call; remote backends (Parallel,
+ * Jina) are additionally capped at `REMOTE_READER_MAX_MS` so a hung endpoint
+ * cannot starve later renderers — especially the purely-local native converter,
+ * which always works on already-loaded HTML. Only a real `userSignal`
+ * cancellation aborts the chain (#1449).
+ */
+export declare function renderHtmlToText(url: string, html: string, timeout: number, settings: Settings, userSignal: AbortSignal | undefined, storage: AgentStorage | null, fetchOverride?: FetchImpl): Promise<{
+    content: string;
+    ok: boolean;
+    method: string;
+}>;
+interface FetchImagePayload {
+    data: string;
+    mimeType: string;
+}
+export interface ReadUrlToolDetails {
+    kind: "url";
+    url: string;
+    finalUrl: string;
+    contentType: string;
+    method: string;
+    truncated: boolean;
+    notes: string[];
+    meta?: OutputMeta;
+}
+interface ReadUrlCacheEntry {
+    artifactId?: string;
+    artifactPath?: string;
+    contentPath?: string;
+    details: ReadUrlToolDetails;
+    image?: FetchImagePayload;
+    output: string;
+    content: string;
+}
+export declare function loadReadUrlCacheEntry(session: ToolSession, params: {
+    path: string;
+    raw?: boolean;
+}, signal?: AbortSignal, options?: {
+    ensureArtifact?: boolean;
+    preferCached?: boolean;
+}): Promise<ReadUrlCacheEntry>;
+/** Materialize rendered URL body text to a local file for tools that require filesystem paths. */
+export declare function materializeReadUrlToFile(session: ToolSession, params: {
+    path: string;
+    raw?: boolean;
+}, signal?: AbortSignal): Promise<{
+    path: string;
+    details: ReadUrlToolDetails;
+}>;
+export declare function executeReadUrl(session: ToolSession, params: {
+    path: string;
+    raw?: boolean;
+}, signal?: AbortSignal): Promise<AgentToolResult<ReadUrlToolDetails>>;
+/** Render URL read call (URL preview) */
+export declare function renderReadUrlCall(args: {
+    path?: string;
+    url?: string;
+    raw?: boolean;
+}, _options: RenderResultOptions, uiTheme?: Theme): Component;
+/** Render URL read result with tree-based layout */
+export declare function renderReadUrlResult(result: {
+    content: Array<{
+        type: string;
+        text?: string;
+    }>;
+    details?: ReadUrlToolDetails;
+    isError?: boolean;
+}, options: RenderResultOptions, uiTheme?: Theme): Component;
+export {};

package/dist/types/tools/file-recorder.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Creates a deduplicating recorder for relative file paths.
+ * Preserves insertion order in `list`; subsequent duplicates are ignored.
+ */
+export declare function createFileRecorder(): {
+    record: (relativePath: string) => void;
+    list: string[];
+};
+/**
+ * Strip native virtual-root prefixes and format file paths relative to cwd when
+ * they are inside cwd. Paths outside cwd remain absolute.
+ */
+export declare function formatResultPath(filePath: string, isDirectory: boolean, basePath: string, cwd: string): string;

package/dist/types/tools/fs-cache-invalidation.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Invalidate shared filesystem scan caches after a content write/update.
+ */
+export declare function invalidateFsScanAfterWrite(path: string): void;
+/**
+ * Invalidate shared filesystem scan caches after deleting a file.
+ */
+export declare function invalidateFsScanAfterDelete(path: string): void;
+/**
+ * Invalidate shared filesystem scan caches after a rename/move.
+ *
+ * Some watchers care about the disappearance at the old path; others about the
+ * appearance at the new one. Bust both to keep callers honest.
+ */
+export declare function invalidateFsScanAfterRename(oldPath: string, newPath: string): void;

package/dist/types/tools/gh-cache-invalidation.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Drop `github-cache` rows for any `gh issue|pr <mutating-subcmd>` call
+ * embedded in `command`. Safe to invoke unconditionally; no-op when the
+ * command does not touch GitHub state.
+ */
+export declare function invalidateGithubCacheForBashCommand(command: string): void;