@prometheus-ai/agent 0.5.0

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

@@ -0,0 +1,65 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@prometheus-ai/agent-core";
+import type { Component } from "@prometheus-ai/tui";
+import * as z from "zod/v4";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import { type FileDiagnosticsResult } from "../lsp";
+import { type Theme } from "../modes/theme/theme";
+import type { ToolSession } from "../sdk";
+import { type OutputMeta } from "./output-meta";
+declare const writeSchema: z.ZodObject<{
+    path: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strip>;
+export type WriteToolInput = z.infer<typeof writeSchema>;
+/** Details returned by the write tool for TUI rendering */
+export interface WriteToolDetails {
+    diagnostics?: FileDiagnosticsResult;
+    meta?: OutputMeta;
+    /** Set when the file was auto-chmod'd because content begins with a `#!` shebang. */
+    madeExecutable?: boolean;
+}
+type WriteParams = WriteToolInput;
+/**
+ * Write tool implementation.
+ *
+ * Creates or overwrites files with optional LSP formatting and diagnostics.
+ */
+export declare class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails> {
+    #private;
+    private readonly session;
+    readonly name = "write";
+    readonly approval: (args: unknown) => "read" | "write";
+    readonly formatApprovalDetails: (args: unknown) => string[];
+    readonly label = "Write";
+    readonly description: string;
+    readonly parameters: z.ZodObject<{
+        path: z.ZodString;
+        content: z.ZodString;
+    }, z.core.$strip>;
+    readonly nonAbortable = true;
+    readonly strict = true;
+    readonly concurrency = "exclusive";
+    readonly loadMode = "discoverable";
+    readonly summary = "Write content to a file (creates or overwrites)";
+    /** Stream matchers should see the real file content, not its JSON-escaped argument encoding. */
+    matcherDigest(args: unknown): string | undefined;
+    constructor(session: ToolSession);
+    execute(_toolCallId: string, { path, content }: WriteParams, signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<WriteToolDetails>, context?: AgentToolContext): Promise<AgentToolResult<WriteToolDetails>>;
+}
+interface WriteRenderArgs {
+    path?: string;
+    file_path?: string;
+    content?: string;
+}
+export declare const writeToolRenderer: {
+    renderCall(args: WriteRenderArgs, options: RenderResultOptions, uiTheme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: WriteToolDetails;
+    }, options: RenderResultOptions, uiTheme: Theme, args?: WriteRenderArgs): Component;
+    mergeCallAndResult: boolean;
+};
+export {};

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

@@ -0,0 +1,26 @@
+/**
+ * Submit result tool for structured subagent output.
+ *
+ * Subagents must call this tool to finish and return structured JSON output.
+ */
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@prometheus-ai/agent-core";
+import type { TSchema } from "@prometheus-ai/ai/types";
+import type { ToolSession } from ".";
+export interface YieldDetails {
+    data: unknown;
+    status: "success" | "aborted";
+    error?: string;
+}
+export declare class YieldTool implements AgentTool<TSchema, YieldDetails> {
+    #private;
+    readonly name = "yield";
+    readonly approval: "read";
+    readonly label = "Submit Result";
+    readonly description: string;
+    readonly parameters: TSchema;
+    strict: boolean;
+    readonly intent: "omit";
+    lenientArgValidation: boolean;
+    constructor(session: ToolSession);
+    execute(_toolCallId: string, params: unknown, _signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<YieldDetails>, _context?: AgentToolContext): Promise<AgentToolResult<YieldDetails>>;
+}

package/dist/types/tui/code-cell.d.ts

@@ -0,0 +1,40 @@
+import { type Theme } from "../modes/theme/theme";
+export interface CodeCellOptions {
+    code: string;
+    language?: string;
+    index?: number;
+    total?: number;
+    title?: string;
+    status?: "pending" | "running" | "warning" | "complete" | "error";
+    spinnerFrame?: number;
+    duration?: number;
+    output?: string;
+    outputMaxLines?: number;
+    codeMaxLines?: number;
+    /**
+     * Show the LAST `codeMaxLines` rows (the live streaming edge) instead of the
+     * first, with a "… N earlier lines" marker on top. Lets a pending preview
+     * follow code as it is written while staying bounded. Ignored when `expanded`.
+     */
+    codeTail?: boolean;
+    expanded?: boolean;
+    /** Animate the cell border with a sweeping segment while pending/running. */
+    animate?: boolean;
+    width: number;
+}
+export declare function renderCodeCell(options: CodeCellOptions, theme: Theme): string[];
+export interface MarkdownCellOptions {
+    content: string;
+    index?: number;
+    total?: number;
+    title?: string;
+    status?: "pending" | "running" | "warning" | "complete" | "error";
+    spinnerFrame?: number;
+    duration?: number;
+    output?: string;
+    outputMaxLines?: number;
+    contentMaxLines?: number;
+    expanded?: boolean;
+    width: number;
+}
+export declare function renderMarkdownCell(options: MarkdownCellOptions, theme: Theme): string[];

package/dist/types/tui/file-list.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Render file listings with optional icons and metadata.
+ */
+import type { Theme } from "../modes/theme/theme";
+export interface FileEntry {
+    path: string;
+    /** Absolute filesystem path. When provided together with {@link FileListOptions.hyperlinkFn}, the
+     * rendered path text is wrapped in an OSC 8 hyperlink. */
+    absPath?: string;
+    isDirectory?: boolean;
+    meta?: string;
+}
+export interface FileListOptions {
+    files: FileEntry[];
+    expanded?: boolean;
+    maxCollapsed?: number;
+    showIcons?: boolean;
+    /** When provided, called with the entry's absolute path and the ANSI-styled display string to
+     * optionally wrap the path in an OSC 8 hyperlink. Only invoked when {@link FileEntry.absPath} is set. */
+    hyperlinkFn?: (absPath: string, displayText: string) => string;
+}
+export declare function renderFileList(options: FileListOptions, theme: Theme): string[];

package/dist/types/tui/hyperlink.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Returns true when OSC 8 hyperlinks should be emitted.
+ *
+ * Respects `tui.hyperlinks` setting:
+ * - `"off"`: never
+ * - `"auto"`: when `process.stdout.isTTY`, `NO_COLOR` is unset, and the detected terminal reports hyperlink support
+ * - `"always"`: unconditionally (useful for viewers that support OSC 8 without advertising it)
+ */
+export declare function isHyperlinkEnabled(): boolean;
+/**
+ * Wrap `displayText` in an OSC 8 hyperlink pointing at `uri`.
+ *
+ * Returns `displayText` unchanged when hyperlinks are disabled, `uri` contains
+ * terminal control bytes, or `displayText` already contains an OSC 8 sequence.
+ */
+export declare function uriHyperlink(uri: string, displayText: string): string;
+/**
+ * Wrap `displayText` in an OSC 8 hyperlink pointing at an HTTP(S) URL.
+ * `www.example.com` inputs are linked as `https://www.example.com`.
+ */
+export declare function urlHyperlink(url: string, displayText: string): string;
+/**
+ * Wrap `displayText` in an OSC 8 hyperlink pointing at the given absolute file path.
+ *
+ * Returns `displayText` unchanged when hyperlinks are disabled or when
+ * the text already contains an OSC 8 sequence (prevents double-wrapping).
+ *
+ * The caller is responsible for passing an absolute path. Relative paths
+ * produce invalid `file://` URIs and are accepted silently to avoid runtime
+ * errors in renderer hot paths.
+ *
+ * @param absPath - Absolute filesystem path
+ * @param displayText - Text to render as the hyperlink anchor (may contain ANSI codes)
+ * @param opts - Optional line/col position appended as `?line=N&col=M` query params
+ */
+export declare function fileHyperlink(absPath: string, displayText: string, opts?: {
+    line?: number;
+    col?: number;
+}): string;
+/**
+ * Synchronously resolve a filesystem-backed internal URL (e.g. `local://foo.md`,
+ * `memory://root/notes.md`) to its absolute filesystem path. Returns `undefined`
+ * for inputs that aren't fs-backed, aren't resolvable in the current session
+ * registry, or fail to parse.
+ *
+ * Used by renderers to wrap fs-backed internal URLs in OSC 8 hyperlinks even
+ * when the resolved path isn't yet available from tool result details (e.g.
+ * during the call/streaming phase before a result lands).
+ *
+ * Async-resolved schemes (`artifact://`, `agent://`, `skill://`, `rule://`,
+ * `prometheus://`) are not handled here — those rely on `details.resolvedPath` set
+ * by the read tool's router resolution.
+ */
+export declare function tryResolveInternalUrlSync(input: string): string | undefined;

package/dist/types/tui/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Public exports for shared TUI components.
+ */
+export * from "./code-cell";
+export * from "./file-list";
+export * from "./hyperlink";
+export * from "./output-block";
+export * from "./status-line";
+export * from "./tree-list";
+export * from "./types";
+export * from "./utils";

package/dist/types/tui/output-block.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Bordered output container with optional header and sections.
+ */
+import type { Component } from "@prometheus-ai/tui";
+import type { Theme } from "../modes/theme/theme";
+import type { State } from "./types";
+export interface OutputBlockOptions {
+    header?: string;
+    headerMeta?: string;
+    state?: State;
+    sections?: Array<{
+        label?: string;
+        lines: string[];
+    }>;
+    width: number;
+    applyBg?: boolean;
+    /** Animate the border with a sweeping dark segment (pending/running state). */
+    animate?: boolean;
+}
+declare const FRAMED_BLOCK_COMPONENT: unique symbol;
+export type FramedBlockComponent = Component & {
+    [FRAMED_BLOCK_COMPONENT]?: true;
+};
+export declare function markFramedBlockComponent<T extends Component>(component: T): T & FramedBlockComponent;
+export declare function isFramedBlockComponent(component: Component): boolean;
+/**
+ * Monotonic frame counter for animated borders, quantized to the TUI's ~16ms
+ * render cap so the cache key advances once per ~60fps frame — fine enough for a
+ * smooth segment sweep, coarse enough to coalesce multiple render passes that
+ * land inside the same frame.
+ */
+export declare function borderShimmerTick(): number;
+/**
+ * Column of the travelling segment's center on the bottom edge for a box of
+ * inner width `W` at time `now`. The segment bounces left → right → left across
+ * the bottom border: a triangle wave over one full there-and-back cycle, eased
+ * per leg so it slows as it nears each wall before reversing. Position is
+ * derived from the wall clock against a fixed cycle, so a resize shifts the
+ * center proportionally — no reset.
+ */
+export declare function borderSegmentHeadCol(W: number, now: number): number;
+export declare function renderOutputBlock(options: OutputBlockOptions, theme: Theme): string[];
+/**
+ * Cached wrapper around `renderOutputBlock`.
+ *
+ * Since output blocks are re-rendered on every frame (via `render(width)` closures),
+ * but their content rarely changes, this cache avoids redundant `visibleWidth()` and
+ * `padding()` computations on ~99% of render calls.
+ */
+export declare class CachedOutputBlock {
+    #private;
+    /** Render with caching. Returns cached result if options haven't changed. */
+    render(options: OutputBlockOptions, theme: Theme): string[];
+    /** Invalidate the cache, forcing a rebuild on next render. */
+    invalidate(): void;
+}
+export {};

package/dist/types/tui/status-line.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Standardized status header rendering for tool output.
+ */
+import type { Theme, ThemeColor } from "../modes/theme/theme";
+import type { ToolUIStatus } from "../tools/render-utils";
+export interface StatusLineOptions {
+    icon?: ToolUIStatus;
+    spinnerFrame?: number;
+    title: string;
+    titleColor?: ThemeColor;
+    description?: string;
+    badge?: {
+        label: string;
+        color: ThemeColor;
+    };
+    meta?: string[];
+}
+export declare function renderStatusLine(options: StatusLineOptions, theme: Theme): string;

package/dist/types/tui/tree-list.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Hierarchical tree list rendering helper.
+ */
+import type { Theme } from "../modes/theme/theme";
+import type { TreeContext } from "./types";
+export interface TreeListOptions<T> {
+    items: T[];
+    expanded?: boolean;
+    maxCollapsed?: number;
+    /** Strict total-line budget for collapsed mode. When set (and not expanded),
+     *  rendered item lines plus the trailing summary line must fit within this budget.
+     */
+    maxCollapsedLines?: number;
+    itemType?: string;
+    /** Called once per item with `isLast: false` during budget calculation;
+     *  line count MUST NOT vary based on `isLast`. */
+    renderItem: (item: T, context: TreeContext) => string | string[];
+}
+export declare function renderTreeList<T>(options: TreeListOptions<T>, theme: Theme): string[];

package/dist/types/tui/types.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared types for TUI rendering components.
+ */
+import type { Theme } from "../modes/theme/theme";
+export type State = "pending" | "running" | "success" | "error" | "warning";
+export interface TreeContext {
+    index: number;
+    isLast: boolean;
+    depth: number;
+    theme: Theme;
+    prefix: string;
+    continuePrefix: string;
+}

package/dist/types/tui/utils.d.ts

@@ -0,0 +1,36 @@
+import type { Theme, ThemeBg } from "../modes/theme/theme";
+import type { State } from "./types";
+export { Ellipsis, truncateToWidth } from "@prometheus-ai/tui";
+/**
+ * Incremental xxHash64 key builder.
+ *
+ * Chains `Bun.hash.xxHash64` calls via seeding — each fed value
+ * mixes into the running hash without intermediate string allocations.
+ * Accepts strings, numbers (u32), booleans, bigints, and `undefined`/`null`
+ * (hashed as a sentinel byte) natively.
+ */
+export declare class Hasher {
+    #private;
+    /** Feed a string. */
+    str(s: string): this;
+    /** Feed an unsigned 32-bit integer. */
+    u32(n: number): this;
+    /** Feed a 64-bit bigint. */
+    u64(n: bigint): this;
+    /** Feed a boolean (single byte: 1 = true, 0 = false). */
+    bool(b: boolean): this;
+    /** Feed a value that may be `undefined` or `null` (hashed as a 0xFF sentinel byte). */
+    optional(v: string | undefined | null): this;
+    /** Return the final hash digest. */
+    digest(): bigint;
+}
+/** Render-cache entry used by tool renderers. */
+export interface RenderCache {
+    key: bigint;
+    lines: string[];
+}
+export declare function buildTreePrefix(ancestors: boolean[], theme: Theme): string;
+export declare function getTreeBranch(isLast: boolean, theme: Theme): string;
+export declare function getTreeContinuePrefix(isLast: boolean, theme: Theme): string;
+export declare function padToWidth(text: string, width: number, bgFn?: (s: string) => string): string;
+export declare function getStateBgColor(state: State): ThemeBg;

package/dist/types/utils/changelog.d.ts

@@ -0,0 +1,25 @@
+export interface ChangelogEntry {
+    major: number;
+    minor: number;
+    patch: number;
+    content: string;
+}
+/**
+ * Parse changelog entries from the file at `changelogPath`. Scans for `## [x.y.z]`
+ * headings and collects each block until the next heading or EOF.
+ *
+ * Returns `[]` when `changelogPath` is `undefined` (package directory not
+ * resolvable — see `getChangelogPath`) or the file is missing. Callers MUST NOT
+ * synthesize a fallback path from the host project's cwd; doing so caused issue
+ * #1423 (the host project's `CHANGELOG.md` was rendered as prometheus's).
+ */
+export declare function parseChangelog(changelogPath: string | undefined): Promise<ChangelogEntry[]>;
+/**
+ * Compare versions. Returns: -1 if v1 < v2, 0 if v1 === v2, 1 if v1 > v2
+ */
+export declare function compareVersions(v1: ChangelogEntry, v2: ChangelogEntry): number;
+/**
+ * Get entries newer than lastVersion
+ */
+export declare function getNewEntries(entries: ChangelogEntry[], lastVersion: string): ChangelogEntry[];
+export { getChangelogPath } from "../config";

package/dist/types/utils/clipboard.d.ts

@@ -0,0 +1,26 @@
+import type { ClipboardImage } from "@prometheus-ai/natives";
+/**
+ * Copy text to the system clipboard.
+ *
+ * Emits OSC 52 first when running in a real terminal (works over SSH/mosh),
+ * then attempts native clipboard copy as best-effort for local sessions.
+ * On Termux, tries `termux-clipboard-set` before native.
+ *
+ * @param text - UTF-8 text to place on the clipboard.
+ */
+export declare function copyToClipboard(text: string): Promise<void>;
+/**
+ * Read an image from the system clipboard.
+ *
+ * Returns null on Termux (no image clipboard support) or when no display
+ * server is available (headless/SSH without forwarding). Under WSL the
+ * Windows clipboard is reached through `powershell.exe`, since WSLg's
+ * Wayland clipboard does not carry image payloads through to `arboard`.
+ *
+ * @returns PNG payload or null when no image is available.
+ */
+export declare function readImageFromClipboard(): Promise<ClipboardImage | null>;
+/**
+ * Read plain text from the system clipboard.
+ */
+export declare function readTextFromClipboard(): Promise<string>;

package/dist/types/utils/command-args.d.ts

@@ -0,0 +1,9 @@
+export declare function parseCommandArgs(argsString: string): string[];
+/**
+ * Substitute argument placeholders in template content
+ * Supports $1, $2, ... for positional args, $@ and $ARGUMENTS for all args
+ *
+ * Note: Replacement happens on the template string only. Argument values
+ * containing patterns like $1, $@, or $ARGUMENTS are NOT recursively substituted.
+ */
+export declare function substituteArgs(content: string, args: string[]): string;

package/dist/types/utils/commit-message-generator.d.ts

@@ -0,0 +1,7 @@
+import type { ModelRegistry } from "../config/model-registry";
+import type { Settings } from "../config/settings";
+/**
+ * Generate a commit message from a unified diff.
+ * Returns null if generation fails (caller should fall back to generic message).
+ */
+export declare function generateCommitMessage(diff: string, registry: ModelRegistry, settings: Settings, sessionId?: string): Promise<string | null>;

package/dist/types/utils/edit-mode.d.ts

@@ -0,0 +1,13 @@
+export type EditMode = "replace" | "patch" | "hashline" | "apply_patch";
+export declare const DEFAULT_EDIT_MODE: EditMode;
+export declare const EDIT_MODES: EditMode[];
+export declare function normalizeEditMode(mode?: string | null): EditMode | undefined;
+export interface EditModeSettingsLike {
+    get(key: "edit.mode"): unknown;
+    getEditVariantForModel?(model: string | undefined): EditMode | null;
+}
+export interface EditModeSessionLike {
+    settings: EditModeSettingsLike;
+    getActiveModelString?: () => string | undefined;
+}
+export declare function resolveEditMode(session: EditModeSessionLike): EditMode;

package/dist/types/utils/event-bus.d.ts

@@ -0,0 +1,6 @@
+export declare class EventBus {
+    #private;
+    emit(channel: string, data: unknown): void;
+    on(channel: string, handler: (data: unknown) => void): () => void;
+    clear(): void;
+}

package/dist/types/utils/external-editor.d.ts

@@ -0,0 +1,17 @@
+/** Returns the user's preferred editor command, or undefined if not configured. */
+export declare function getEditorCommand(): string | undefined;
+export interface OpenInEditorOptions {
+    /** File extension for the temp file (default: ".md"). */
+    extension?: string;
+    /** Custom stdio configuration (default: all "inherit"). */
+    stdio?: [number | "inherit", number | "inherit", number | "inherit"];
+    /** Keep the file's trailing newline instead of trimming it from the returned text. */
+    trimTrailingNewline?: boolean;
+}
+/**
+ * Opens `content` in the user's external editor and returns the edited text.
+ * Returns `null` if the editor exits with a non-zero code.
+ *
+ * The caller is responsible for stopping/starting the TUI around this call.
+ */
+export declare function openInEditor(editorCmd: string, content: string, options?: OpenInEditorOptions): Promise<string | null>;

package/dist/types/utils/file-display-mode.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Resolve line-display mode for file-like outputs (read, grep, @file mentions).
+ */
+export interface FileDisplayMode {
+    lineNumbers: boolean;
+    hashLines: boolean;
+}
+/** Session-like object providing settings and tool availability for display mode resolution. */
+export interface FileDisplayModeSession {
+    /** Whether the edit tool is available. Hashlines are suppressed without it. */
+    hasEditTool?: boolean;
+    settings: {
+        get(key: "readLineNumbers" | "readHashLines" | "edit.mode"): unknown;
+    };
+}
+/**
+ * Computes effective line display mode from session settings/env.
+ * Hashline mode takes precedence and implies line-addressed output everywhere.
+ * Hashlines are suppressed when the edit tool is not available (e.g. explore agents),
+ * when the caller signals a `raw` read, and when the source is `immutable`
+ * (e.g. internal URLs like artifact://, agent://, memory:// — there is no edit
+ * path that could consume the anchors). Raw output is returned as-is.
+ */
+export declare function resolveFileDisplayMode(session: FileDisplayModeSession, options?: {
+    raw?: boolean;
+    immutable?: boolean;
+}): FileDisplayMode;

package/dist/types/utils/file-mentions.d.ts

@@ -0,0 +1,13 @@
+import type { AgentMessage } from "@prometheus-ai/agent-core";
+import { type SnapshotStore } from "@prometheus-ai/hashline";
+/** Extract all @filepath mentions from text */
+export declare function extractFileMentions(text: string): string[];
+/**
+ * Generate a FileMentionMessage containing the contents of mentioned files.
+ * Returns empty array if no files could be read.
+ */
+export declare function generateFileMentionMessages(filePaths: string[], cwd: string, options?: {
+    autoResizeImages?: boolean;
+    useHashLines?: boolean;
+    snapshotStore?: SnapshotStore;
+}): Promise<AgentMessage[]>;