@prometheus-ai/agent 0.5.3 → 0.5.8

package/src/session/streaming-output.ts

@@ -11,6 +11,16 @@ export const DEFAULT_MAX_LINES = 3000;
 export const DEFAULT_MAX_BYTES = 50 * 1024; // 50KB
 export const DEFAULT_MAX_COLUMN = 512; // Max chars per grep match line
 
+/**
+ * Default artifact-on-disk cap for {@link OutputSink}.
+ *
+ * `0` means unbounded: by default, `artifact://<id>` references preserve the
+ * complete raw stream instead of a capped head/tail sample.
+ */
+export const ARTIFACT_DEFAULT_MAX_BYTES = 0;
+/** Default head budget; the remainder becomes the rolling tail window. */
+export const ARTIFACT_DEFAULT_HEAD_BYTES = 3 * 1024 * 1024; // 3 MiB
+
 const NL = "\n";
 const ELLIPSIS = "…";
 
@@ -58,6 +68,20 @@ export interface OutputSinkOptions {
 	onChunk?: (chunk: string) => void;
 	/** Minimum ms between onChunk calls. 0 = every chunk (default). */
 	chunkThrottleMs?: number;
+	/**
+	 * Optional cap on bytes written to the artifact-on-disk file. When the cap
+	 * is hit, the head window is preserved verbatim and subsequent output feeds
+	 * a rolling tail window; on close, the sink writes a single
+	 * `[ARTIFACT TRUNCATED: …]` notice between them. Default
+	 * {@link ARTIFACT_DEFAULT_MAX_BYTES} (unbounded).
+	 */
+	artifactMaxBytes?: number;
+	/**
+	 * Bytes reserved for the head window of the capped artifact file. The
+	 * tail window receives `artifactMaxBytes - artifactHeadBytes`. Default
+	 * {@link ARTIFACT_DEFAULT_HEAD_BYTES}; clamped to `[0, artifactMaxBytes]`.
+	 */
+	artifactHeadBytes?: number;
 }
 
 export interface TruncationResult {
@@ -546,6 +570,66 @@ export function truncateMiddle(content: string, options: TruncationOptions = {})
 	};
 }
 
+// =============================================================================
+// Inline byte cap — final defense at the tool-result boundary
+// =============================================================================
+
+/** Options for {@link enforceInlineByteCap}. */
+export interface InlineByteCapOptions {
+	/** Inline byte budget. Defaults to {@link DEFAULT_MAX_BYTES}. */
+	maxBytes?: number;
+	/** What the text is, for the elision marker (e.g. "bash output"). */
+	label: string;
+	/**
+	 * Persist the full text as a session artifact. When an artifact id is
+	 * returned, a `[raw output: artifact://<id>]` footer is appended so the
+	 * elided bytes stay recoverable.
+	 */
+	saveArtifact?: (full: string) => string | undefined | Promise<string | undefined>;
+}
+
+/** Drop the partial last line of a head window (keep it if there is no newline at all). */
+function trimHeadToLineBoundary(text: string): string {
+	const idx = text.lastIndexOf(NL);
+	return idx > 0 ? text.substring(0, idx) : text;
+}
+
+/** Drop the partial first line of a tail window (keep it if there is no newline at all). */
+function trimTailToLineBoundary(text: string): string {
+	const idx = text.indexOf(NL);
+	if (idx < 0 || idx === text.length - 1) return text;
+	return text.substring(idx + 1);
+}
+
+/**
+ * Final-defense inline size guard for tool results.
+ *
+ * No-op when `text` fits within `maxBytes` (the common path). Otherwise keeps
+ * ~60% of the budget from the head and ~25% from the tail — cut on line
+ * boundaries, never splitting a multi-byte UTF-8 sequence — with an elision
+ * marker between. The remaining ~15% is slack for the marker and the optional
+ * `[raw output: artifact://<id>]` footer, so the result stays under `maxBytes`.
+ */
+export async function enforceInlineByteCap(text: string, options: InlineByteCapOptions): Promise<string> {
+	const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+	if (maxBytes <= 0) return text;
+	const totalBytes = Buffer.byteLength(text, "utf-8");
+	if (totalBytes <= maxBytes) return text;
+
+	const head = trimHeadToLineBoundary(truncateHeadBytes(text, Math.floor(maxBytes * 0.6)).text);
+	const tail = trimTailToLineBoundary(truncateTailBytes(text, Math.floor(maxBytes * 0.25)).text);
+	const elidedBytes = Math.max(0, totalBytes - Buffer.byteLength(head, "utf-8") - Buffer.byteLength(tail, "utf-8"));
+	const marker = `[… elided ${elidedBytes} bytes of ${options.label} …]`;
+	let composed = `${head}\n${marker}\n${tail}`;
+
+	const artifactId = await options.saveArtifact?.(text);
+	if (artifactId) {
+		const sep = composed.endsWith(NL) ? "" : NL;
+		composed += `${sep}[raw output: artifact://${artifactId}]`;
+	}
+	return composed;
+}
+
 // =============================================================================
 // TailBuffer — ring-style tail buffer with lazy joining
 // =============================================================================
@@ -650,6 +734,7 @@ export class OutputSink {
 	#sawData = false;
 	#truncated = false;
 	#lastChunkTime = 0;
+	#pendingChunk = "";
 
 	// Per-line column cap streaming state (persists across `push` calls so a
 	// long line split across chunks still trips the same trigger).
@@ -675,6 +760,21 @@ export class OutputSink {
 	readonly #chunkThrottleMs: number;
 	readonly #maxColumns: number;
 
+	// Optional artifact-on-disk cap. When `#artifactMaxBytes > 0` the file sink
+	// owns a head budget + a rolling tail buffer; once the head is closed,
+	// subsequent chunks are diverted into `#artifactTailRing` (bounded by
+	// `#artifactTailBudget`). On `dump()` the tail is flushed back to the sink
+	// behind a `[ARTIFACT TRUNCATED: …]` notice. The default cap is disabled so
+	// advertised `artifact://<id>` captures are lossless.
+	readonly #artifactMaxBytes: number;
+	readonly #artifactHeadBudget: number;
+	readonly #artifactTailBudget: number;
+	#artifactHeadBytesWritten = 0;
+	#artifactHeadClosed = false;
+	#artifactTailRing = "";
+	#artifactTailRingBytes = 0;
+	#artifactTailIncomingBytes = 0;
+
 	constructor(options?: OutputSinkOptions) {
 		const {
 			artifactPath,
@@ -684,6 +784,8 @@ export class OutputSink {
 			maxColumns = 0,
 			onChunk,
 			chunkThrottleMs = 0,
+			artifactMaxBytes = ARTIFACT_DEFAULT_MAX_BYTES,
+			artifactHeadBytes = ARTIFACT_DEFAULT_HEAD_BYTES,
 		} = options ?? {};
 		this.#artifactPath = artifactPath;
 		this.#artifactId = artifactId;
@@ -692,6 +794,9 @@ export class OutputSink {
 		this.#maxColumns = Math.max(0, maxColumns);
 		this.#onChunk = onChunk;
 		this.#chunkThrottleMs = chunkThrottleMs;
+		this.#artifactMaxBytes = Math.max(0, artifactMaxBytes);
+		this.#artifactHeadBudget = Math.max(0, Math.min(artifactHeadBytes, this.#artifactMaxBytes));
+		this.#artifactTailBudget = Math.max(0, this.#artifactMaxBytes - this.#artifactHeadBudget);
 	}
 
 	/**
@@ -701,14 +806,20 @@ export class OutputSink {
 	push(chunk: string): void {
 		chunk = sanitizeWithOptionalSixelPassthrough(chunk, sanitizeText);
 
-		// Throttled onChunk: only call the callback when enough time has passed.
+		// Throttled onChunk: coalesce chunks arriving inside the throttle window
+		// and flush the buffered concatenation on the next eligible tick (plus a
+		// final flush in dump()) so the preview never has silent gaps.
 		// Live preview gets the raw (pre-cap) chunk so the TUI never lags behind
 		// what reached the sink — the column cap is for the persisted LLM view.
 		if (this.#onChunk) {
 			const now = Date.now();
 			if (now - this.#lastChunkTime >= this.#chunkThrottleMs) {
 				this.#lastChunkTime = now;
-				this.#onChunk(chunk);
+				const merged = this.#pendingChunk + chunk;
+				this.#pendingChunk = "";
+				this.#onChunk(merged);
+			} else {
+				this.#pendingChunk += chunk;
 			}
 		}
 
@@ -858,14 +969,18 @@ export class OutputSink {
 	/**
 	 * Write a chunk to the artifact file. Handles the async file sink creation
 	 * by queuing writes until the sink is ready, then draining synchronously.
+	 * Once the sink is up, every byte flows through {@link #emitToSink} which
+	 * owns the head + tail cap so artifacts cannot grow beyond
+	 * `#artifactMaxBytes` on disk.
 	 */
 	#writeToFile(chunk: string): void {
 		if (this.#fileReady && this.#file) {
-			// Fast path: file sink exists, write synchronously
-			this.#file.sink.write(chunk);
+			this.#emitToSink(chunk);
 			return;
 		}
-		// File sink not yet created — queue this chunk and kick off creation
+		// File sink not yet created — queue this chunk and kick off creation.
+		// The queue is bounded only by how many chunks arrive before the open
+		// resolves (typically <2). The cap is enforced on drain.
 		if (!this.#pendingFileWrites) {
 			this.#pendingFileWrites = [chunk];
 			void this.#createFileSink();
@@ -874,26 +989,99 @@ export class OutputSink {
 		}
 	}
 
+	/**
+	 * Cap-aware sink writer. Bytes flow into the head window verbatim until the
+	 * budget is exhausted; subsequent bytes are diverted into a rolling tail
+	 * ring, evicted from the front so total RAM stays bounded by
+	 * `#artifactTailBudget`. `dump()` replays the ring behind a single notice
+	 * line before closing the sink.
+	 *
+	 * When the cap is disabled (`#artifactMaxBytes === 0`) this collapses to a
+	 * straight pass-through, preserving the historical "stream everything"
+	 * contract.
+	 */
+	#emitToSink(chunk: string): void {
+		if (!this.#file || chunk.length === 0) return;
+		if (this.#artifactMaxBytes === 0) {
+			this.#file.sink.write(chunk);
+			return;
+		}
+		const chunkBytes = Buffer.byteLength(chunk, "utf-8");
+		const room = this.#artifactHeadClosed ? 0 : this.#artifactHeadBudget - this.#artifactHeadBytesWritten;
+		if (room >= chunkBytes) {
+			this.#file.sink.write(chunk);
+			this.#artifactHeadBytesWritten += chunkBytes;
+			return;
+		}
+		let overflow = chunk;
+		if (room > 0) {
+			const headSlice = truncateHeadBytes(chunk, room);
+			if (headSlice.bytes > 0) {
+				this.#file.sink.write(headSlice.text);
+				this.#artifactHeadBytesWritten += headSlice.bytes;
+			}
+			// Even when UTF-8 boundary safety leaves a few bytes of nominal room,
+			// this chunk has already overflowed the head window. Close it now so a
+			// later small ASCII chunk cannot be written before this overflow tail.
+			this.#artifactHeadClosed = true;
+			overflow = chunk.substring(headSlice.text.length);
+		}
+		if (overflow.length === 0 || this.#artifactTailBudget === 0) {
+			// No tail budget: count the dropped bytes so the notice reflects them.
+			if (overflow.length > 0) {
+				this.#artifactTailIncomingBytes += Buffer.byteLength(overflow, "utf-8");
+			}
+			return;
+		}
+		this.#pushArtifactTail(overflow);
+	}
+
+	#pushArtifactTail(chunk: string): void {
+		const chunkBytes = Buffer.byteLength(chunk, "utf-8");
+		this.#artifactTailIncomingBytes += chunkBytes;
+		const budget = this.#artifactTailBudget;
+		if (chunkBytes >= budget) {
+			// Chunk alone dominates — keep only its tail slice.
+			const { text, bytes } = truncateTailBytes(chunk, budget);
+			this.#artifactTailRing = text;
+			this.#artifactTailRingBytes = bytes;
+			return;
+		}
+		this.#artifactTailRing += chunk;
+		this.#artifactTailRingBytes += chunkBytes;
+		if (this.#artifactTailRingBytes > budget) {
+			const { text, bytes } = truncateTailBytes(this.#artifactTailRing, budget);
+			this.#artifactTailRing = text;
+			this.#artifactTailRingBytes = bytes;
+		}
+	}
+
 	async #createFileSink(): Promise<void> {
 		if (!this.#artifactPath || this.#fileReady) return;
 		try {
 			const sink = Bun.file(this.#artifactPath).writer();
 			this.#file = { path: this.#artifactPath, artifactId: this.#artifactId, sink };
+			this.#fileReady = true;
+
+			// Head-retained bytes precede the rolling tail buffer in the capture.
+			// Route through #emitToSink so they count against the artifact head
+			// budget — a direct sink.write would let them escape the cap.
+			if (this.#head.length > 0) {
+				this.#emitToSink(this.#head);
+			}
 
 			// Flush existing buffer to file BEFORE it gets trimmed further.
 			if (this.#buffer.length > 0) {
-				sink.write(this.#buffer);
+				this.#emitToSink(this.#buffer);
 			}
 
-			// Drain any chunks that arrived while the sink was being created
+			// Drain any chunks that arrived while the sink was being created.
 			if (this.#pendingFileWrites) {
 				for (const pending of this.#pendingFileWrites) {
-					sink.write(pending);
+					this.#emitToSink(pending);
 				}
 				this.#pendingFileWrites = undefined;
 			}
-
-			this.#fileReady = true;
 		} catch {
 			try {
 				await this.#file?.sink?.end();
@@ -902,6 +1090,7 @@ export class OutputSink {
 			}
 			this.#file = undefined;
 			this.#pendingFileWrites = undefined;
+			this.#fileReady = false;
 		}
 	}
 
@@ -946,13 +1135,61 @@ export class OutputSink {
 		this.#columnEllipsisAdded = false;
 		this.#columnDroppedBytes = 0;
 		this.#columnTruncatedLines = 0;
+		this.#pendingChunk = "";
+	}
+
+	/**
+	 * Replay the rolling tail ring back into the artifact sink. When bytes
+	 * were actually dropped from the middle (the head budget was exhausted
+	 * *and* the tail ring evicted), a single `[ARTIFACT TRUNCATED: …]`
+	 * notice is injected between head and tail so a reader of
+	 * `artifact://<id>` understands the gap. When the total stream simply
+	 * spilled past the head budget but still fits below `artifactMaxBytes`,
+	 * `droppedBytes` is zero — head + tail together are the verbatim stream
+	 * and the notice is suppressed so we don't corrupt the artifact with a
+	 * misleading "0 B elided" marker (PR #2083 review by codex).
+	 *
+	 * No-op when the cap was never hit at all (head budget never exhausted,
+	 * tail ring empty).
+	 */
+	#flushArtifactTailIfCapped(): void {
+		if (!this.#file) return;
+		if (this.#artifactMaxBytes === 0) return;
+		const tailBytes = this.#artifactTailRingBytes;
+		const droppedBytes = Math.max(0, this.#artifactTailIncomingBytes - tailBytes);
+		if (tailBytes === 0 && droppedBytes === 0) return;
+
+		if (droppedBytes > 0) {
+			const headWritten = this.#artifactHeadBytesWritten;
+			const totalCapped = headWritten + this.#artifactTailIncomingBytes;
+			const headSep = headWritten > 0 ? "\n" : "";
+			const tailSep = tailBytes > 0 && !this.#artifactTailRing.startsWith("\n") ? "\n" : "";
+			const notice =
+				`${headSep}[ARTIFACT TRUNCATED: kept first ${formatBytes(headWritten)} + last ${formatBytes(tailBytes)} ` +
+				`of ${formatBytes(totalCapped)}; ${formatBytes(droppedBytes)} elided from the middle]${tailSep}`;
+			this.#file.sink.write(notice);
+		}
+		if (tailBytes > 0) {
+			this.#file.sink.write(this.#artifactTailRing);
+		}
 	}
 
 	async dump(notice?: string): Promise<OutputSummary> {
 		const noticeLine = notice ? `[${notice}]\n` : "";
+
+		// Flush any chunk still held back by the throttle so the live preview
+		// ends with the complete stream.
+		if (this.#onChunk && this.#pendingChunk.length > 0) {
+			const pending = this.#pendingChunk;
+			this.#pendingChunk = "";
+			this.#onChunk(pending);
+		}
 		const totalLines = this.#sawData ? this.#totalLines + 1 : 0;
 
-		if (this.#file) await this.#file.sink.end();
+		if (this.#file) {
+			this.#flushArtifactTailIfCapped();
+			await this.#file.sink.end();
+		}
 
 		// Compose the visible output. With head retention, splice head + marker
 		// + tail when content was elided. Otherwise return the rolling buffer.

package/src/session/tool-choice-queue.ts

@@ -10,14 +10,14 @@ export interface ResolveInfo {
 export interface RejectInfo {
 	/** The ToolChoice that was yielded but never (or unsuccessfully) served. */
 	choice: ToolChoice;
-	reason: "aborted" | "error" | "cleared" | "removed";
+	reason: "aborted" | "error" | "cleared" | "removed" | "unavailable" | "not_invoked";
 }
 
 /** "requeue" replays the lost yield next turn; "drop" (or void/undefined) discards it. */
 export type RejectOutcome = "requeue" | "drop";
 
 export interface DirectiveCallbacks {
-	/** Fires when the yield was served (LLM call completed). The directive is consumed. */
+	/** Fires when the yield completed; onInvoked directives require the requested tool to run first. */
 	onResolved?: (info: ResolveInfo) => void;
 	/**
 	 * Fires when the yield is being discarded. Return "requeue" to replay the
@@ -62,6 +62,7 @@ export function* onceGen(choice: ToolChoice): Generator<ToolChoice, void, unknow
 interface InFlight {
 	directive: ToolChoiceDirective;
 	yielded: ToolChoice;
+	invoked: boolean;
 }
 
 // ── Queue ───────────────────────────────────────────────────────────────────
@@ -116,7 +117,7 @@ export class ToolChoiceQueue {
 				this.#queue.shift();
 				continue;
 			}
-			this.#inFlight = { directive: head, yielded: result.value };
+			this.#inFlight = { directive: head, yielded: result.value, invoked: false };
 			return result.value;
 		}
 		return undefined;
@@ -125,14 +126,18 @@ export class ToolChoiceQueue {
 	// ── Lifecycle ─────────────────────────────────────────────────────────
 
 	/**
-	 * The in-flight yield was served — the LLM call completed normally.
-	 * Fires onResolved, then clears in-flight state. The directive's generator
-	 * remains in the queue if it has more values to yield.
+	 * The in-flight yield completed normally. Directives with onInvoked are only
+	 * consumed after their requested tool ran; a normal text turn or a different
+	 * tool call requeues/rejects the directive instead.
 	 */
 	resolve(): void {
 		const inFlight = this.#inFlight;
-		this.#inFlight = undefined;
 		if (!inFlight) return;
+		if (inFlight.directive.callbacks.onInvoked && !inFlight.invoked) {
+			this.reject("not_invoked");
+			return;
+		}
+		this.#inFlight = undefined;
 
 		this.#lastResolvedLabel = inFlight.directive.label;
 		inFlight.directive.callbacks.onResolved?.({ choice: inFlight.yielded });
@@ -155,12 +160,13 @@ export class ToolChoiceQueue {
 
 		if (outcome === "requeue") {
 			// Re-queue only the lost yield, not the rest of the sequence. Carry forward
-			// onInvoked and onRejected so the replayed yield still executes correctly
-			// and can requeue itself again if the next turn also aborts.
+			// callbacks so the replayed yield still executes and finalizes correctly,
+			// and can requeue itself again if the next turn also aborts or skips it.
 			this.#queue.unshift({
 				generator: onceGen(inFlight.yielded),
 				label: `${inFlight.directive.label}-requeued`,
 				callbacks: {
+					onResolved: inFlight.directive.callbacks.onResolved,
 					onInvoked: inFlight.directive.callbacks.onInvoked,
 					onRejected: inFlight.directive.callbacks.onRejected,
 				},
@@ -173,9 +179,15 @@ export class ToolChoiceQueue {
 		return this.#inFlight !== undefined;
 	}
 
-	/** Peek the in-flight directive's onInvoked handler, if any. */
+	/** Return the in-flight directive's onInvoked handler and mark it when called. */
 	peekInFlightInvoker(): ((input: unknown) => Promise<unknown> | unknown) | undefined {
-		return this.#inFlight?.directive.callbacks.onInvoked;
+		const inFlight = this.#inFlight;
+		const onInvoked = inFlight?.directive.callbacks.onInvoked;
+		if (!inFlight || !onInvoked) return undefined;
+		return (input: unknown): Promise<unknown> | unknown => {
+			inFlight.invoked = true;
+			return onInvoked(input);
+		};
 	}
 
 	// ── Cleanup ───────────────────────────────────────────────────────────

package/src/session/yield-queue.ts

@@ -10,7 +10,7 @@ export interface YieldDispatcher<P> {
 
 export interface YieldQueueOptions {
 	isStreaming: () => boolean;
-	injectStreaming(msg: AgentMessage): void;
+	injectStreaming?(msg: AgentMessage): void;
 	injectIdle(messages: AgentMessage[]): Promise<void>;
 	scheduleIdleFlush(run: () => Promise<void>): void;
 }
@@ -85,7 +85,7 @@ export class YieldQueue {
 			if (!message) continue;
 			if (mode === "streaming") {
 				try {
-					this.#options.injectStreaming(message);
+					this.#options.injectStreaming?.(message);
 				} catch (error) {
 					logger.warn("Yield queue streaming dispatch failed", { kind, error: formatError(error) });
 				}
@@ -102,6 +102,24 @@ export class YieldQueue {
 		}
 	}
 
+	/**
+	 * Snapshot and remove all queued entries, returning one lazy thunk per kind.
+	 * Each thunk applies the dispatcher's staleness filter and builds the batched
+	 * message only when called — so the consumer (the agent loop) decides, at the
+	 * moment it injects, whether the message is still worth delivering (a thunk may
+	 * return null to skip). Background-job completions and late diagnostics reach
+	 * the model between requests without the agent having to stop.
+	 */
+	drainLazy(): Array<() => AgentMessage | null> {
+		const thunks: Array<() => AgentMessage | null> = [];
+		for (const [kind, dispatcher] of this.#dispatchers) {
+			const entries = this.#drain(kind);
+			if (entries.length === 0) continue;
+			thunks.push(() => this.#build(kind, dispatcher, entries));
+		}
+		return thunks;
+	}
+
 	clear(): void {
 		this.#entries.clear();
 		this.#idleFlushPending = false;

package/src/slash-commands/acp-builtins.ts

@@ -5,13 +5,37 @@ import type { AcpBuiltinSlashCommandResult, SlashCommandRuntime } from "./types"
 
 export type { AcpBuiltinSlashCommandResult } from "./types";
 
+/**
+ * All names (primary + aliases) that are reserved by ACP builtins. Used to
+ * filter out extension commands that would shadow a builtin or its alias at
+ * dispatch time (e.g. `models` is an alias for `/model`, so an extension
+ * registering `models` would appear in the palette but execute the builtin).
+ */
+export const ACP_BUILTIN_RESERVED_NAMES: ReadonlySet<string> = new Set(
+	BUILTIN_SLASH_COMMANDS_INTERNAL.filter(c => c.handle !== undefined).flatMap(c => [c.name, ...(c.aliases ?? [])]),
+);
+
+/**
+ * Whether an extension command named `name` would be captured by ACP builtin
+ * dispatch before reaching the extension handler. Beyond exact name/alias
+ * collisions, `parseSlashCommand` treats `:` as a name/args separator, so a
+ * colon-namespaced name whose prefix is a handled builtin (e.g. `model:foo`)
+ * executes the `/model` builtin with `foo` as args. Such names must not be
+ * advertised to ACP clients.
+ */
+export function isAcpBuiltinShadowedName(name: string): boolean {
+	if (ACP_BUILTIN_RESERVED_NAMES.has(name)) return true;
+	const colon = name.indexOf(":");
+	return colon !== -1 && ACP_BUILTIN_RESERVED_NAMES.has(name.slice(0, colon));
+}
+
 /**
  * Commands advertised to ACP clients. Entries without a text-mode `handle`
  * (e.g. `/quit`, `/login`, dashboards) are filtered out so the client doesn't
  * see commands it cannot drive.
  */
 export const ACP_BUILTIN_SLASH_COMMANDS: AvailableCommand[] = BUILTIN_SLASH_COMMANDS_INTERNAL.filter(
-	command => command.handle !== undefined && command.advertiseInAcp !== false,
+	command => command.handle !== undefined,
 ).map(command => {
 	// Honor mode-specific copy: ACP clients receive concise text-mode
 	// descriptions/hints when the spec sets `acpDescription` / `acpInputHint`,

package/src/slash-commands/available-commands.ts

@@ -0,0 +1,105 @@
+import type { AvailableCommand } from "@agentclientprotocol/sdk";
+import type { SkillsSettings } from "../config/settings";
+import type { LoadedCustomCommand } from "../extensibility/custom-commands";
+import type { ExtensionRunner } from "../extensibility/extensions";
+import { getSkillSlashCommandName, type Skill } from "../extensibility/skills";
+import { type FileSlashCommand, loadSlashCommands } from "../extensibility/slash-commands";
+import { ACP_BUILTIN_RESERVED_NAMES, isAcpBuiltinShadowedName } from "./acp-builtins";
+import { BUILTIN_SLASH_COMMANDS_INTERNAL } from "./builtin-registry";
+
+export type AvailableSlashCommandSource = "builtin" | "skill" | "extension" | "custom" | "mcp_prompt" | "file";
+
+export interface InternalAvailableSlashCommand {
+	name: string;
+	aliases?: string[];
+	description?: string;
+	input?: { hint: string };
+	subcommands?: Array<{ name: string; description?: string; usage?: string }>;
+	source: AvailableSlashCommandSource;
+}
+
+export interface AvailableCommandsSession {
+	readonly extensionRunner?: ExtensionRunner;
+	readonly customCommands: ReadonlyArray<LoadedCustomCommand>;
+	readonly mcpPromptCommands?: ReadonlyArray<LoadedCustomCommand>;
+	readonly skills: ReadonlyArray<Skill>;
+	readonly skillsSettings?: SkillsSettings;
+	setSlashCommands(slashCommands: FileSlashCommand[]): void;
+	sessionManager: { getCwd(): string };
+}
+
+export async function buildAvailableSlashCommands(
+	session: AvailableCommandsSession,
+	loadFileCommands: (cwd: string) => Promise<FileSlashCommand[]> = cwd => loadSlashCommands({ cwd }),
+): Promise<InternalAvailableSlashCommand[]> {
+	const commands: InternalAvailableSlashCommand[] = [];
+	const seenNames = new Set<string>();
+	const appendCommand = (command: InternalAvailableSlashCommand): void => {
+		if (seenNames.has(command.name)) return;
+		seenNames.add(command.name);
+		commands.push(command);
+	};
+
+	for (const command of BUILTIN_SLASH_COMMANDS_INTERNAL) {
+		if (!command.handle) continue;
+		const hint = command.acpInputHint ?? command.inlineHint;
+		appendCommand({
+			name: command.name,
+			aliases: command.aliases,
+			description: command.acpDescription ?? command.description,
+			input: hint ? { hint } : undefined,
+			subcommands: command.subcommands,
+			source: "builtin",
+		});
+	}
+
+	if (session.skillsSettings?.enableSkillCommands) {
+		for (const skill of session.skills) {
+			appendCommand({
+				name: getSkillSlashCommandName(skill),
+				description: skill.description || `Run ${skill.name} skill`,
+				input: { hint: "arguments" },
+				source: "skill",
+			});
+		}
+	}
+
+	const runner = session.extensionRunner;
+	if (runner) {
+		for (const command of runner.getRegisteredCommands(ACP_BUILTIN_RESERVED_NAMES)) {
+			if (isAcpBuiltinShadowedName(command.name)) continue;
+			appendCommand({
+				name: command.name,
+				description: command.description ?? "(extension command)",
+				input: { hint: "arguments" },
+				source: "extension",
+			});
+		}
+	}
+
+	for (const command of session.customCommands) {
+		const source: AvailableSlashCommandSource = command.path?.startsWith("mcp:") ? "mcp_prompt" : "custom";
+		appendCommand({
+			name: command.command.name,
+			description: command.command.description,
+			input: { hint: "arguments" },
+			source,
+		});
+	}
+
+	const fileCommands = await loadFileCommands(session.sessionManager.getCwd());
+	session.setSlashCommands(fileCommands);
+	for (const command of fileCommands) {
+		appendCommand({ name: command.name, description: command.description, source: "file" });
+	}
+
+	return commands;
+}
+
+export function toAcpAvailableCommands(commands: readonly InternalAvailableSlashCommand[]): AvailableCommand[] {
+	return commands.map(command => ({
+		name: command.name,
+		description: command.description ?? "",
+		input: command.input,
+	}));
+}