@prometheus-ai/agent 0.5.3 → 0.5.8

package/src/modes/controllers/tool-args-reveal.ts

@@ -0,0 +1,174 @@
+import { parseStreamingJson } from "@prometheus-ai/ai/utils/json-parse";
+import { nextStep, STREAMING_REVEAL_FRAME_MS } from "./streaming-reveal";
+
+/** Minimal component surface the reveal pushes frames into. */
+type ToolArgsRevealComponent = {
+	updateArgs(args: unknown, toolCallId?: string): void;
+};
+
+type ToolArgsRevealControllerOptions = {
+	getSmoothStreaming(): boolean;
+	requestRender(): void;
+};
+
+type RevealEntry = {
+	component: ToolArgsRevealComponent | undefined;
+	/** Latest raw streamed argument text (JSON for function tools, raw text for custom tools). */
+	target: string;
+	/** Revealed UTF-16 code units of `target`. */
+	revealed: number;
+	/** Custom-tool raw input: display args are `{ input: prefix }`, never parsed as JSON. */
+	rawInput: boolean;
+};
+
+/** Clamp a slice end into `text`, never splitting a surrogate pair: a prefix
+ *  ending on a high surrogate would feed a lone surrogate into the parsed
+ *  preview args (providers decode UTF-8 incrementally, so the raw stream
+ *  itself never contains one). */
+function clampSliceEnd(text: string, end: number): number {
+	if (end <= 0) return 0;
+	if (end >= text.length) return text.length;
+	const code = text.charCodeAt(end - 1);
+	return code >= 0xd800 && code <= 0xdbff ? end + 1 : end;
+}
+
+/** Display args for a revealed raw-stream prefix. Function-tool prefixes are
+ *  re-parsed with the same streaming-tolerant parser providers use, so every
+ *  frame is a state the provider itself could have produced; custom tools
+ *  mirror the provider's `{ input }` shape. `__partialJson` carries the
+ *  matching raw prefix for renderers that read it directly (bash env preview,
+ *  edit strategies). */
+function buildDisplayArgs(prefix: string, rawInput: boolean): Record<string, unknown> {
+	const base: Record<string, unknown> = rawInput ? { input: prefix } : parseStreamingJson(prefix);
+	return { ...base, __partialJson: prefix };
+}
+
+/**
+ * Paces streamed tool-call arguments the same way StreamingRevealController
+ * paces assistant text: providers that deliver `partialJson` in large batches
+ * (or throttle their partial parses) would otherwise make write/edit/bash
+ * streaming previews jump in chunks. Each pending tool call reveals its raw
+ * argument stream at the shared 30fps cadence with the same adaptive
+ * catch-up step, re-parsing the revealed prefix per frame.
+ *
+ * Reveal units are UTF-16 code units of the raw stream, not graphemes —
+ * the prefix goes through a JSON parser rather than straight to the screen,
+ * so only surrogate-pair integrity matters (see {@link clampSliceEnd}).
+ */
+export class ToolArgsRevealController {
+	readonly #getSmoothStreaming: () => boolean;
+	readonly #requestRender: () => void;
+	readonly #entries = new Map<string, RevealEntry>();
+	#timer: NodeJS.Timeout | undefined;
+
+	constructor(options: ToolArgsRevealControllerOptions) {
+		this.#getSmoothStreaming = options.getSmoothStreaming;
+		this.#requestRender = options.requestRender;
+	}
+
+	/**
+	 * Record the latest streamed argument text for a tool call and return the
+	 * args to render right now. With smoothing disabled the full target passes
+	 * through in the caller's legacy shape (`{ ...args, __partialJson }`).
+	 */
+	setTarget(
+		id: string,
+		partialJson: string,
+		rawInput: boolean,
+		fullArgs: Record<string, unknown>,
+	): Record<string, unknown> {
+		if (!this.#getSmoothStreaming()) {
+			// Toggle may flip mid-call: drop any live entry so ticks stop.
+			this.#entries.delete(id);
+			return { ...fullArgs, __partialJson: partialJson };
+		}
+		let entry = this.#entries.get(id);
+		if (!entry) {
+			entry = { component: undefined, target: partialJson, revealed: 0, rawInput };
+			this.#entries.set(id, entry);
+		} else {
+			// Streams only append; a non-prefix target means a rewind — snap into range.
+			if (!partialJson.startsWith(entry.target)) {
+				entry.revealed = Math.min(entry.revealed, partialJson.length);
+			}
+			entry.target = partialJson;
+		}
+		entry.revealed = clampSliceEnd(entry.target, entry.revealed);
+		this.#syncTimer();
+		return buildDisplayArgs(entry.target.slice(0, entry.revealed), entry.rawInput);
+	}
+
+	/** Attach the component future ticks push frames into. */
+	bind(id: string, component: ToolArgsRevealComponent): void {
+		const entry = this.#entries.get(id);
+		if (entry) entry.component = component;
+	}
+
+	/** Final arguments arrived (the JSON closed): drop the reveal so the
+	 *  caller's final-args render wins immediately, mirroring how assistant
+	 *  text snaps to the full message at message_end. */
+	finish(id: string): void {
+		this.#entries.delete(id);
+		if (this.#entries.size === 0) this.#stopTimer();
+	}
+
+	/** Snap every live entry to its full received stream and clear. Used at
+	 *  message_end (abort/error mid-stream) so sealed components freeze showing
+	 *  everything that arrived rather than a mid-reveal prefix. */
+	flushAll(): void {
+		for (const [id, entry] of this.#entries) {
+			if (entry.component && entry.revealed < entry.target.length) {
+				entry.component.updateArgs(buildDisplayArgs(entry.target, entry.rawInput), id);
+			}
+		}
+		this.#entries.clear();
+		this.#stopTimer();
+	}
+
+	/** Clear without pushing (teardown). */
+	stop(): void {
+		this.#entries.clear();
+		this.#stopTimer();
+	}
+
+	#syncTimer(): void {
+		for (const entry of this.#entries.values()) {
+			if (entry.revealed < entry.target.length) {
+				this.#startTimer();
+				return;
+			}
+		}
+		this.#stopTimer();
+	}
+
+	#startTimer(): void {
+		if (this.#timer) return;
+		this.#timer = setInterval(() => {
+			this.#tick();
+		}, STREAMING_REVEAL_FRAME_MS);
+		this.#timer.unref?.();
+	}
+
+	#stopTimer(): void {
+		if (!this.#timer) return;
+		clearInterval(this.#timer);
+		this.#timer = undefined;
+	}
+
+	#tick(): void {
+		let advanced = false;
+		for (const [id, entry] of this.#entries) {
+			const backlog = entry.target.length - entry.revealed;
+			if (backlog <= 0 || !entry.component) continue;
+			entry.revealed = clampSliceEnd(entry.target, entry.revealed + nextStep(backlog));
+			entry.component.updateArgs(buildDisplayArgs(entry.target.slice(0, entry.revealed), entry.rawInput), id);
+			advanced = true;
+		}
+		if (advanced) {
+			this.#requestRender();
+		} else {
+			// Every entry caught up (or unbound); setTarget restarts on growth.
+			this.#stopTimer();
+		}
+	}
+}

package/src/modes/gradient-highlight.ts

@@ -1,10 +1,15 @@
 import { maskNonProse } from "./markdown-prose";
 import { theme } from "./theme/theme";
 
-/** A gradient keyword highlighter. `resetTo` is the SGR foreground sequence
- *  re-emitted after each painted keyword so surrounding text keeps its color;
- *  it defaults to a plain foreground reset (editor / default-colored text). */
-export type KeywordHighlighter = (text: string, resetTo?: string) => string;
+/** A gradient keyword highlighter.
+ *
+ * - `resetTo` is the SGR foreground sequence re-emitted after each painted
+ *   keyword so surrounding text keeps its color; it defaults to a plain
+ *   foreground reset (editor / default-colored text).
+ * - `phase` ∈ [0, 1) rotates the gradient stops cyclically; pass `Date.now()`-
+ *   derived values to animate a shimmer. Defaults to `0` (the static
+ *   sent-bubble palette). */
+export type KeywordHighlighter = (text: string, resetTo?: string, phase?: number) => string;
 
 const FG_RESET = "\x1b[39m";
 
@@ -51,14 +56,19 @@ export function createGradientHighlighter(spec: GradientHighlightSpec): KeywordH
 		return next;
 	};
 
-	/** Paint each character of `word` with the next gradient stop, restoring `resetTo` after. */
-	const paint = (word: string, resetTo: string): string => {
+	/** Paint each character of `word` with the next gradient stop, restoring `resetTo` after.
+	 *  `phase` ∈ [0, 1) cyclically rotates the palette index so successive renders
+	 *  with monotonically increasing phase produce a moving shimmer; `0` yields the
+	 *  static palette. */
+	const paint = (word: string, resetTo: string, phase: number): string => {
 		const stopsArr = palette();
+		const m = stopsArr.length;
 		const n = word.length;
 		let out = "";
 		let prev = "";
 		for (let i = 0; i < n; i++) {
-			const color = stopsArr[Math.floor((i / n) * stopsArr.length)] ?? stopsArr[0] ?? "";
+			const t = (i / n + phase) % 1;
+			const color = stopsArr[Math.floor(t * m) % m] ?? stopsArr[0] ?? "";
 			// Coalesce consecutive characters that resolve to the same stop.
 			if (color !== prev) {
 				out += color;
@@ -69,8 +79,10 @@ export function createGradientHighlighter(spec: GradientHighlightSpec): KeywordH
 		return `${out}${resetTo}`;
 	};
 
-	return (text: string, resetTo: string = FG_RESET): string => {
+	return (text: string, resetTo: string = FG_RESET, phase: number = 0): string => {
 		if (!probe.test(text)) return text;
+		// Wrap phase into [0, 1) so negative inputs and values ≥ 1 stay well-defined.
+		const wrappedPhase = ((phase % 1) + 1) % 1;
 		// Match against a code/markup-masked copy so keywords inside code spans,
 		// fenced blocks, or XML sections never paint; indices still address `text`.
 		const masked = maskNonProse(text);
@@ -79,7 +91,7 @@ export function createGradientHighlighter(spec: GradientHighlightSpec): KeywordH
 		for (const m of masked.matchAll(highlight)) {
 			const start = m.index ?? 0;
 			const end = start + m[0].length;
-			out += text.slice(last, start) + paint(text.slice(start, end), resetTo);
+			out += text.slice(last, start) + paint(text.slice(start, end), resetTo, wrappedPhase);
 			last = end;
 		}
 		return out + text.slice(last);

package/src/modes/image-references.ts

@@ -3,30 +3,56 @@ import { logger } from "@prometheus-ai/utils";
 import { type BlobPutResult, blobExtensionForImageMimeType } from "../session/blob-store";
 import { fileHyperlink } from "../tui/hyperlink";
 
-const IMAGE_REFERENCE_REGEX = /\[Image #([1-9]\d*)\]/g;
+/** Matches `[Image #N]`/`[Image #N, WxH]` and `[Paste #N, +X lines]`/`[Paste #N, Y chars]` tokens.
+ *  Group 1 is the kind (`Image`/`Paste`), group 2 the 1-based index. The optional metadata
+ *  tail (`, …`) is captured loosely (no `]`/newline) so future label tweaks keep matching. */
+export const PLACEHOLDER_REGEX = /\[(Image|Paste) #([1-9]\d*)(?:,[^\]\n]*)?\]/g;
+
+/** Matches a single `[Image #N]` / `[Image #N, WxH]` marker. Group 1 is the
+ *  1-based index, group 2 the optional metadata tail (leading comma, no `]` or
+ *  newline) so future label tweaks keep matching. Paste markers are excluded
+ *  on purpose: their numbering is owned by the editor's paste store, not by
+ *  the pending-image buffer. */
+const IMAGE_MARKER_REGEX = /\[Image #([1-9]\d*)((?:,[^\]\n]*)?)\]/g;
+
+/** Renumber every `[Image #N]` marker in `text` by `offset` (added to the
+ *  existing index), preserving the optional `, WxH` tail. Paste markers are
+ *  left untouched. Used when restoring queued image-messages back into a draft
+ *  that already holds pending images so the merged text's positional markers
+ *  still line up with `pendingImages`. */
+export function shiftImageMarkers(text: string, offset: number): string {
+	if (offset === 0) return text;
+	return text.replace(
+		IMAGE_MARKER_REGEX,
+		(_match, idx: string, tail: string) => `[Image #${Number(idx) + offset}${tail}]`,
+	);
+}
 
 type ImageBlobWriter = (data: Buffer, options?: { extension?: string }) => Promise<BlobPutResult>;
 type ImageBlobWriterSync = (data: Buffer, options?: { extension?: string }) => BlobPutResult;
 
-export interface ImageReferenceRenderers {
+export type PlaceholderKind = "image" | "paste";
+
+export interface PlaceholderRenderers {
 	renderText: (text: string) => string;
-	renderReference: (label: string, index: number) => string;
+	renderReference: (label: string, kind: PlaceholderKind, index: number) => string;
 }
 
-export function renderImageReferences(text: string, renderers: ImageReferenceRenderers): string {
-	IMAGE_REFERENCE_REGEX.lastIndex = 0;
+export function renderPlaceholders(text: string, renderers: PlaceholderRenderers): string {
+	PLACEHOLDER_REGEX.lastIndex = 0;
 	let result = "";
 	let last = 0;
 	let matched = false;
 
 	for (;;) {
-		const match = IMAGE_REFERENCE_REGEX.exec(text);
+		const match = PLACEHOLDER_REGEX.exec(text);
 		if (match === null) break;
 		matched = true;
 		if (match.index > last) {
 			result += renderers.renderText(text.slice(last, match.index));
 		}
-		result += renderers.renderReference(match[0], Number(match[1]));
+		const kind: PlaceholderKind = match[1] === "Paste" ? "paste" : "image";
+		result += renderers.renderReference(match[0], kind, Number(match[2]));
 		last = match.index + match[0].length;
 	}
 

package/src/modes/index.ts

@@ -2,32 +2,15 @@ import { emergencyTerminalRestore } from "@prometheus-ai/tui";
 import { postmortem } from "@prometheus-ai/utils";
 
 /**
- * Run modes for the coding agent.
+ * Interactive mode and embeddable RPC client exports for the coding agent.
+ *
+ * Branch-specific runners live in their concrete modules so importing this
+ * barrel does not pull print, RPC server, or ACP server mode into the normal
+ * TUI graph.
  */
-export { runAcpMode } from "./acp";
-export { InteractiveMode, type InteractiveModeOptions } from "./interactive-mode";
-export { type PrintModeOptions, runPrintMode } from "./print-mode";
-export {
-	defineRpcClientTool,
-	type ModelInfo,
-	RpcClient,
-	type RpcClientCustomTool,
-	type RpcClientOptions,
-	type RpcClientToolContext,
-	type RpcClientToolResult,
-	type RpcEventListener,
-} from "./rpc/rpc-client";
-export { runRpcMode } from "./rpc/rpc-mode";
-export type {
-	RpcCommand,
-	RpcHostToolCallRequest,
-	RpcHostToolCancelRequest,
-	RpcHostToolDefinition,
-	RpcHostToolResult,
-	RpcHostToolUpdate,
-	RpcResponse,
-	RpcSessionState,
-} from "./rpc/rpc-types";
+export * from "./interactive-mode";
+export * from "./rpc/rpc-client";
+export * from "./rpc/rpc-types";
 
 postmortem.register("terminal-restore", () => {
 	emergencyTerminalRestore();