@prometheus-ai/agent 0.5.4 → 0.5.8

package/src/collab/protocol.ts

@@ -0,0 +1,241 @@
+/**
+ * Collab live-session wire protocol.
+ *
+ * Hub topology: the host is authoritative, guests never peer. All session
+ * payloads (`CollabFrame`) travel AES-256-GCM sealed; the relay only sees the
+ * plaintext envelope (`[4B uint32 BE peerId][sealed payload]`) plus TEXT JSON
+ * control messages that carry no session data.
+ */
+
+import type { ImageContent, Model } from "@prometheus-ai/ai";
+import type {
+	BusChannel,
+	GuestFrame,
+	ParsedCollabLink,
+	Participant,
+	SessionState,
+	AgentSnapshot as WireAgentSnapshot,
+} from "@prometheus-ai/wire";
+import {
+	DEFAULT_RELAY_URL,
+	ENVELOPE_HEADER_LENGTH,
+	ROOM_ID_BYTES,
+	ROOM_KEY_BYTES,
+	WRITE_TOKEN_BYTES,
+} from "@prometheus-ai/wire";
+import type { ContextUsage } from "../extensibility/extensions/types";
+import type { AgentSessionEvent } from "../session/agent-session";
+import type { SessionEntry, SessionHeader } from "../session/session-entries";
+
+export type {
+	CollabPromptDetails,
+	ParsedCollabLink,
+	RelayControlMessage,
+	RelayControlToGuest,
+	RelayControlToHost,
+} from "@prometheus-ai/wire";
+export { COLLAB_PROMPT_MESSAGE_TYPE, COLLAB_PROTO } from "@prometheus-ai/wire";
+export { DEFAULT_RELAY_URL, ENVELOPE_HEADER_LENGTH, ROOM_ID_BYTES };
+
+export type CollabParticipant = Participant;
+export type AgentSnapshot = WireAgentSnapshot;
+
+/** Debounced footer snapshot broadcast by the host. */
+export type CollabSessionState = SessionState & {
+	/**
+	 * Host model (full catalog object). Guests apply it to their replica
+	 * agent state so model display and context-window math are native.
+	 */
+	model?: Model;
+	/** Host status-line context numbers (guest system prompt/tools differ, so local estimates drift). */
+	contextUsage?: ContextUsage;
+};
+
+/**
+ * Encrypted payload frames (inside AES-GCM, JSON). The wire package pins the
+ * JSON skeleton (`WireFrame`); host-side frames carry the rich session types
+ * that serialize into those shapes.
+ */
+export type CollabFrame =
+	// guest -> host (hello/abort/agent-cmd/fetch-transcript are taken verbatim from the wire grammar)
+	| Exclude<GuestFrame, { t: "prompt" }>
+	| { t: "prompt"; text: string; images?: ImageContent[] }
+	// host -> guest
+	| {
+			t: "welcome";
+			proto: number;
+			header: SessionHeader;
+			entries: SessionEntry[];
+			state: CollabSessionState;
+			agents: AgentSnapshot[];
+			/** True when this peer joined through a read-only (view) link. */
+			readOnly?: boolean;
+	  }
+	| { t: "entry"; entry: SessionEntry }
+	| { t: "event"; event: AgentSessionEvent }
+	| { t: "state"; state: CollabSessionState }
+	/** Mirrored EventBus traffic (task subagent lifecycle/progress channels only). */
+	| { t: "bus"; channel: BusChannel; data: unknown }
+	/** Full agent-registry snapshot (debounced on registry change). */
+	| { t: "agents"; agents: AgentSnapshot[] }
+	/** Targeted reply to fetch-transcript; `text` is decoded JSONL from `fromByte`, `newSize` the next offset base. */
+	| { t: "transcript"; reqId: number; text: string; newSize: number; error?: string }
+	| { t: "bye"; reason: string }
+	| { t: "error"; message: string };
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Wire envelope: [4B uint32 BE peerId][sealed payload]
+// Host→relay: peerId 0 broadcasts to all guests; peerId N targets guest N.
+// Guest→relay: always 0; the relay rewrites it to the sender's id.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export function packEnvelope(peerId: number, sealed: Uint8Array): Uint8Array {
+	const out = new Uint8Array(ENVELOPE_HEADER_LENGTH + sealed.byteLength);
+	new DataView(out.buffer).setUint32(0, peerId, false);
+	out.set(sealed, ENVELOPE_HEADER_LENGTH);
+	return out;
+}
+
+export function unpackEnvelope(data: Uint8Array): { peerId: number; payload: Uint8Array } | null {
+	if (data.byteLength < ENVELOPE_HEADER_LENGTH) return null;
+	const peerId = new DataView(data.buffer, data.byteOffset, ENVELOPE_HEADER_LENGTH).getUint32(0, false);
+	return { peerId, payload: data.subarray(ENVELOPE_HEADER_LENGTH) };
+}
+
+/** Rewrite the peerId in place without copying the payload. */
+export function rewriteEnvelopePeer(data: Uint8Array, peerId: number): void {
+	new DataView(data.buffer, data.byteOffset, ENVELOPE_HEADER_LENGTH).setUint32(0, peerId, false);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Link format: wss://<host[:port]>/r/<roomId>.<base64url-32-byte-key>
+// ═══════════════════════════════════════════════════════════════════════════
+
+const ROOM_PATH_RE = /^\/r\/([A-Za-z0-9_-]{10,64})(?:\.([A-Za-z0-9_-]+))?$/;
+const BARE_LINK_RE = /^([A-Za-z0-9_-]{10,64})[#.]([A-Za-z0-9_-]+)$/;
+const B64URL_RE = /^[A-Za-z0-9_-]+$/;
+const LOCAL_HOSTNAMES: Record<string, true> = { localhost: true, "127.0.0.1": true, "::1": true, "[::1]": true };
+
+export function generateRoomId(): string {
+	const bytes = new Uint8Array(ROOM_ID_BYTES);
+	crypto.getRandomValues(bytes);
+	return Buffer.from(bytes).toString("base64url");
+}
+
+/** Normalize a relay base URL (ws/wss/http/https) into a ws/wss origin, or an error. */
+function normalizeRelayOrigin(relayUrl: string): { origin: string } | { error: string } {
+	let url: URL;
+	try {
+		url = new URL(relayUrl);
+	} catch {
+		return { error: `Invalid relay URL: ${relayUrl}` };
+	}
+	let scheme: string;
+	switch (url.protocol) {
+		case "wss:":
+		case "https:":
+			scheme = "wss:";
+			break;
+		case "ws:":
+		case "http:":
+			scheme = "ws:";
+			break;
+		default:
+			return { error: `Unsupported relay URL scheme: ${url.protocol}` };
+	}
+	if (scheme === "ws:" && !LOCAL_HOSTNAMES[url.hostname]) {
+		return { error: "relay link must be wss:// (plain ws:// is only allowed for localhost)" };
+	}
+	const port = url.port ? `:${url.port}` : "";
+	return { origin: `${scheme}//${url.hostname}${port}` };
+}
+
+/**
+ * Render the shareable link. Compact forms: the default relay collapses to
+ * `<roomId>.<key>`, other wss relays drop the scheme (`host[:port]/r/…`);
+ * only localhost ws:// links keep their full URL so parsing cannot
+ * mis-infer wss.
+ *
+ * The room secret is dot-joined (`<roomId>.<key>`) rather than `#`-joined:
+ * RFC 3986 forbids a raw `#` inside a fragment, so strict URL stacks (macOS
+ * Foundation behind terminal click-to-open) percent-encode a second `#` to
+ * `%23` and break the link. Parsers still accept the legacy `#` form and the
+ * mangled `%23` form.
+ *
+ * Full links append the write token to the key
+ * (`base64url(key ∥ writeToken)`); read-only (view) links carry the bare
+ * 32-byte key, which is also the pre-token link format.
+ */
+export function formatCollabLink(relayUrl: string, roomId: string, key: Uint8Array, writeToken?: Uint8Array): string {
+	const normalized = normalizeRelayOrigin(relayUrl);
+	if ("error" in normalized) throw new Error(normalized.error);
+	const secret = writeToken ? Buffer.concat([key, writeToken]) : Buffer.from(key);
+	const keyText = secret.toString("base64url");
+	if (normalized.origin === DEFAULT_RELAY_URL) return `${roomId}.${keyText}`;
+	const compact = normalized.origin.startsWith("wss://")
+		? normalized.origin.slice("wss://".length)
+		: normalized.origin;
+	return `${compact}/r/${roomId}.${keyText}`;
+}
+
+/**
+ * Render the browser deep link: `http(s)://<relay-host>/#<collab-link>`. The
+ * relay serves the web client at `/`, and the whole collab link (including the
+ * room key) rides in the fragment, so it never appears in any HTTP request.
+ * Terminals auto-link the https form, making it click-to-join.
+ */
+export function formatCollabWebLink(
+	relayUrl: string,
+	roomId: string,
+	key: Uint8Array,
+	writeToken?: Uint8Array,
+): string {
+	const normalized = normalizeRelayOrigin(relayUrl);
+	if ("error" in normalized) throw new Error(normalized.error);
+	const httpOrigin = normalized.origin.startsWith("wss://")
+		? `https://${normalized.origin.slice("wss://".length)}`
+		: `http://${normalized.origin.slice("ws://".length)}`;
+	return `${httpOrigin}/#${formatCollabLink(relayUrl, roomId, key, writeToken)}`;
+}
+
+export function parseCollabLink(link: string): ParsedCollabLink | { error: string } {
+	// Lenient input: terminals that open OSC 8 links through strict URL stacks
+	// (macOS Foundation) percent-encode the legacy second `#` to `%23`.
+	let text = link.trim().replace(/%23/gi, "#");
+	// Bare `<roomId>.<key>` (legacy `<roomId>#<key>`) → default relay.
+	const bare = BARE_LINK_RE.exec(text);
+	if (bare) text = `${DEFAULT_RELAY_URL}/r/${bare[1]}.${bare[2]}`;
+	// Scheme-less `host[:port]/r/…` → wss.
+	else if (!text.includes("://")) text = `wss://${text}`;
+	let url: URL;
+	try {
+		url = new URL(text);
+	} catch {
+		return { error: `Invalid collab link: ${link}` };
+	}
+	const normalized = normalizeRelayOrigin(url.origin);
+	if ("error" in normalized) return normalized;
+	const match = ROOM_PATH_RE.exec(url.pathname);
+	if (!match) {
+		// Web deep link: `http(s)://<relay>/#<collab-link>` — the fragment holds
+		// the whole link, so recurse on it. The recursion terminates because
+		// the inner text is a strict suffix of the input.
+		const inner = url.hash.startsWith("#") ? url.hash.slice(1) : url.hash;
+		if (inner) return parseCollabLink(inner);
+		return { error: "Collab link must contain a /r/<roomId> path" };
+	}
+	const roomId = match[1]!;
+	// Key rides dot-joined in the path (`/r/<roomId>.<key>`); legacy links
+	// carry it in the fragment (`/r/<roomId>#<key>`).
+	const fragment = match[2] ?? (url.hash.startsWith("#") ? url.hash.slice(1) : url.hash);
+	if (!fragment) {
+		return { error: "Collab link is missing the <key> part" };
+	}
+	const secret = B64URL_RE.test(fragment) ? new Uint8Array(Buffer.from(fragment, "base64url")) : null;
+	if (!secret || (secret.byteLength !== ROOM_KEY_BYTES && secret.byteLength !== ROOM_KEY_BYTES + WRITE_TOKEN_BYTES)) {
+		return { error: "Collab link key must be 32 (view) or 48 (full) base64url bytes" };
+	}
+	const key = secret.subarray(0, ROOM_KEY_BYTES);
+	const writeToken = secret.byteLength > ROOM_KEY_BYTES ? secret.subarray(ROOM_KEY_BYTES) : undefined;
+	return { wsUrl: `${normalized.origin}/r/${roomId}`, roomId, key, writeToken };
+}

package/src/collab/relay-client.ts

@@ -0,0 +1,216 @@
+/**
+ * Client-side WebSocket wrapper for collab live-session sharing.
+ *
+ * Connects to a relay room, seals/opens AES-GCM frames, and reconnects with
+ * exponential backoff on transient drops. Fatal relay close codes (room gone,
+ * host conflict, room full) and decryption failures never reconnect.
+ */
+import { logger } from "@prometheus-ai/utils";
+import { open, seal } from "./crypto";
+import type { CollabFrame, RelayControlMessage } from "./protocol";
+import { packEnvelope, unpackEnvelope } from "./protocol";
+
+const FATAL_CLOSE_REASONS: Record<number, string> = {
+	4001: "room closed",
+	4004: "no such room",
+	4009: "a host is already connected for this room",
+	4029: "room is full",
+};
+
+const BACKOFF_BASE_MS = 1_000;
+const BACKOFF_MAX_MS = 30_000;
+/** Max enveloped frames buffered while a reconnect is pending; overflow is dropped. */
+const MAX_PENDING_SENDS = 256;
+
+export interface CollabSocketOptions {
+	/** wss://host[:port]/r/<roomId> — no query string. */
+	wsUrl: string;
+	role: "host" | "guest";
+	key: CryptoKey;
+}
+
+export class CollabSocket {
+	/** Fires after every successful (re)connect. */
+	onOpen?: () => void;
+	onFrame?: (frame: CollabFrame, fromPeer: number) => void;
+	onControl?: (msg: RelayControlMessage) => void;
+	/** Fires once per terminal close (intentional, fatal code, or bad key). willReconnect=true for transient drops that will retry. */
+	onClose?: (reason: string, willReconnect: boolean) => void;
+
+	readonly #opts: CollabSocketOptions;
+	#ws: WebSocket | null = null;
+	#retryTimer: NodeJS.Timeout | undefined;
+	#attempt = 0;
+	/** Terminal state: intentional close or fatal failure. Cleared by connect(). */
+	#closed = false;
+	/** Serializes seal() so frames hit the wire in send() order. */
+	#sendChain: Promise<void> = Promise.resolve();
+	/** Serializes open() so frames are delivered in arrival order. */
+	#recvChain: Promise<void> = Promise.resolve();
+	/** Envelopes sealed while disconnected, flushed on the next open. */
+	#pendingSends: Uint8Array[] = [];
+
+	constructor(opts: CollabSocketOptions) {
+		this.#opts = opts;
+	}
+
+	get isOpen(): boolean {
+		return this.#ws?.readyState === WebSocket.OPEN;
+	}
+
+	connect(): void {
+		if (this.#ws || this.#retryTimer) return;
+		this.#closed = false;
+		this.#attempt = 0;
+		this.#openSocket();
+	}
+
+	send(frame: CollabFrame, targetPeer = 0): void {
+		this.#sendChain = this.#sendChain
+			.then(async () => {
+				if (this.#closed) {
+					logger.debug("collab: dropping frame, socket closed", { t: frame.t });
+					return;
+				}
+				const sealed = await seal(this.#opts.key, frame);
+				const envelope = packEnvelope(targetPeer, sealed);
+				const ws = this.#ws;
+				if (ws && ws.readyState === WebSocket.OPEN) {
+					ws.send(envelope);
+					return;
+				}
+				if (this.#pendingSends.length >= MAX_PENDING_SENDS) {
+					logger.debug("collab: dropping frame, reconnect buffer full", { t: frame.t });
+					return;
+				}
+				this.#pendingSends.push(envelope);
+			})
+			.catch((err: unknown) => {
+				logger.debug("collab: send failed", { error: String(err) });
+			});
+	}
+
+	/** Intentional close: clears any retry timer, suppresses reconnect. A later connect() starts fresh. */
+	close(): void {
+		const hadActivity = this.#ws !== null || this.#retryTimer !== undefined;
+		this.#clearRetry();
+		const wasClosed = this.#closed;
+		this.#closed = true;
+		this.#pendingSends.length = 0;
+		const ws = this.#ws;
+		this.#ws = null;
+		if (ws) {
+			try {
+				ws.close(1000);
+			} catch {
+				// already closing/closed
+			}
+		}
+		if (hadActivity && !wasClosed) this.onClose?.("closed", false);
+	}
+
+	#openSocket(): void {
+		const ws = new WebSocket(`${this.#opts.wsUrl}?role=${this.#opts.role}`);
+		ws.binaryType = "arraybuffer";
+		this.#ws = ws;
+		ws.onopen = () => {
+			if (this.#ws !== ws) return;
+			this.#attempt = 0;
+			for (const envelope of this.#pendingSends) ws.send(envelope);
+			this.#pendingSends.length = 0;
+			this.onOpen?.();
+		};
+		ws.onmessage = (event: MessageEvent) => {
+			if (this.#ws !== ws) return;
+			this.#handleMessage(ws, event.data);
+		};
+		ws.onerror = () => {
+			// The paired close event carries the actionable state; nothing to do here.
+		};
+		ws.onclose = (event: CloseEvent) => {
+			if (this.#ws !== ws) return;
+			this.#ws = null;
+			this.#handleClose(event.code, event.reason);
+		};
+	}
+
+	#handleMessage(ws: WebSocket, data: unknown): void {
+		if (typeof data === "string") {
+			try {
+				this.onControl?.(JSON.parse(data) as RelayControlMessage);
+			} catch {
+				logger.debug("collab: ignoring malformed control message");
+			}
+			return;
+		}
+		const bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : data instanceof Uint8Array ? data : null;
+		if (!bytes) return;
+		const envelope = unpackEnvelope(bytes);
+		if (!envelope) return;
+		this.#recvChain = this.#recvChain
+			.then(async () => {
+				if (this.#ws !== ws) return;
+				let frame: CollabFrame;
+				try {
+					frame = await open(this.#opts.key, envelope.payload);
+				} catch {
+					this.#failFatal("bad key or corrupted frame");
+					return;
+				}
+				if (this.#ws !== ws) return;
+				this.onFrame?.(frame, envelope.peerId);
+			})
+			.catch((err: unknown) => {
+				logger.debug("collab: frame handler failed", { error: String(err) });
+			});
+	}
+
+	#handleClose(code: number, reason: string): void {
+		if (this.#closed) return;
+		const fatalReason = FATAL_CLOSE_REASONS[code];
+		if (fatalReason !== undefined) {
+			this.#closed = true;
+			this.#pendingSends.length = 0;
+			this.onClose?.(fatalReason, false);
+			return;
+		}
+		this.onClose?.(reason || `connection lost (code ${code})`, true);
+		this.#scheduleRetry();
+	}
+
+	/** Decryption failure: wrong key or corrupted frame. Never reconnect. */
+	#failFatal(reason: string): void {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.#clearRetry();
+		this.#pendingSends.length = 0;
+		const ws = this.#ws;
+		this.#ws = null;
+		if (ws) {
+			try {
+				ws.close(1000);
+			} catch {
+				// already closing/closed
+			}
+		}
+		this.onClose?.(reason, false);
+	}
+
+	#scheduleRetry(): void {
+		const base = Math.min(BACKOFF_BASE_MS * 2 ** this.#attempt, BACKOFF_MAX_MS);
+		this.#attempt++;
+		const delay = base * (0.75 + Math.random() * 0.5);
+		this.#retryTimer = setTimeout(() => {
+			this.#retryTimer = undefined;
+			if (this.#closed) return;
+			this.#openSocket();
+		}, delay);
+	}
+
+	#clearRetry(): void {
+		if (this.#retryTimer !== undefined) {
+			clearTimeout(this.#retryTimer);
+			this.#retryTimer = undefined;
+		}
+	}
+}

package/src/commands/bench.ts

@@ -0,0 +1,42 @@
+import { Args, Command, Flags } from "@prometheus-ai/utils/cli";
+import { runBenchCommand } from "../cli/bench-cli";
+
+export default class Bench extends Command {
+	static description =
+		"Benchmark models with the same prompt: time-to-first-token and generation throughput (tokens/s)";
+
+	static args = {
+		models: Args.string({
+			description: "Model selectors (provider/model or fuzzy id, e.g. opus)",
+			required: true,
+			multiple: true,
+		}),
+	};
+
+	static flags = {
+		runs: Flags.integer({ description: "Requests per model (results are averaged)", default: 1 }),
+		"max-tokens": Flags.integer({ description: "Max output tokens per request", default: 512 }),
+		prompt: Flags.string({ description: "Custom prompt text (default: bundled bench prompt)" }),
+		json: Flags.boolean({ description: "Output JSON" }),
+	};
+
+	static examples = [
+		"# Compare two models\n  prometheus bench anthropic/claude-opus-4-5 openai/gpt-5.2",
+		"# Fuzzy selectors work\n  prometheus bench opus sonnet",
+		"# Average over 3 runs each\n  prometheus bench opus gpt-5.2 --runs 3",
+		"# Machine-readable output\n  prometheus bench opus --json",
+	];
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Bench);
+		await runBenchCommand({
+			models: args.models ?? [],
+			flags: {
+				runs: flags.runs,
+				maxTokens: flags["max-tokens"],
+				prompt: flags.prompt,
+				json: flags.json,
+			},
+		});
+	}
+}

package/src/commands/complete.ts

@@ -8,7 +8,7 @@
  * first field. The import surface is kept deliberately narrow so a TAB press
  * doesn't pay for the full agent boot.
  */
-import { type GeneratedProvider, getBundledModels, getBundledProviders } from "@prometheus-ai/ai/models";
+import { type GeneratedProvider, getBundledModels, getBundledProviders } from "@prometheus-ai/catalog/models";
 import { Command } from "@prometheus-ai/utils/cli";
 import { SessionManager } from "../session/session-manager";
 

package/src/commands/gallery.ts

@@ -0,0 +1,52 @@
+/**
+ * Render every built-in tool's renderer across its lifecycle states.
+ */
+import { Command, Flags } from "@prometheus-ai/utils/cli";
+import { GALLERY_STATES, type GalleryState, runGalleryCommand } from "../cli/gallery-cli";
+
+export default class Gallery extends Command {
+	static description = "Preview tool renderers across streaming, in-progress, success, and failure states";
+
+	static flags = {
+		tool: Flags.string({ char: "t", description: "Render a single tool by name" }),
+		state: Flags.string({
+			char: "s",
+			description: "Render only the given lifecycle state(s)",
+			options: [...GALLERY_STATES],
+			multiple: true,
+		}),
+		width: Flags.integer({ char: "w", description: "Render width in columns" }),
+		expanded: Flags.boolean({
+			char: "e",
+			description: "Render the expanded variant of each renderer",
+			default: false,
+		}),
+		plain: Flags.boolean({ description: "Strip ANSI styling from the output", default: false }),
+		screenshot: Flags.boolean({
+			description:
+				"Capture the rendered output as PNG screenshot(s) via VHS instead of printing ANSI (requires vhs)",
+			default: false,
+		}),
+		out: Flags.string({
+			char: "o",
+			description: "Screenshot output path (with --screenshot); suffixed per image when split across multiple",
+		}),
+		font: Flags.string({ description: "Screenshot font family (default: JetBrainsMono Nerd Font)" }),
+		"font-size": Flags.integer({ description: "Screenshot font size in points (default: 18)" }),
+	};
+
+	async run(): Promise<void> {
+		const { flags } = await this.parse(Gallery);
+		await runGalleryCommand({
+			tool: flags.tool,
+			states: flags.state as GalleryState[] | undefined,
+			width: flags.width,
+			expanded: flags.expanded,
+			plain: flags.plain,
+			screenshot: flags.screenshot,
+			out: flags.out,
+			font: flags.font,
+			fontSize: flags["font-size"],
+		});
+	}
+}

package/src/commands/install.ts

@@ -2,7 +2,7 @@
  * `prometheus install <target>` — top-level convenience over `prometheus plugin install` /
  * `prometheus plugin link`.
  *
- * The docs (prometheus.trivlab.com/docs/extension-authoring) advertise
+ * The docs (prometheus.sh/docs/extension-authoring) advertise
  *
  *   prometheus install ./my-extension
  *

package/src/commands/join.ts

@@ -0,0 +1,39 @@
+/**
+ * Join a shared collab session from the CLI: launches the interactive TUI and
+ * immediately runs `/join <link>`.
+ */
+import { APP_NAME } from "@prometheus-ai/utils";
+import { Args, Command } from "@prometheus-ai/utils/cli";
+import { parseArgs } from "../cli/args";
+import { runRootCommand } from "../main";
+
+export default class Join extends Command {
+	static description = "Join a shared collab session (same as /join)";
+
+	static args = {
+		link: Args.string({
+			description: "Collab link shared by the host (/collab)",
+			required: true,
+		}),
+	};
+
+	static examples = [`${APP_NAME} join "relay.example.sh/abc123#key"`];
+
+	async run(): Promise<void> {
+		const { args } = await this.parse(Join);
+		const link = args.link?.trim();
+		if (!link) {
+			process.stderr.write(`Usage: ${APP_NAME} join <link>\n`);
+			process.exitCode = 1;
+			return;
+		}
+		if (!process.stdin.isTTY || !process.stdout.isTTY) {
+			process.stderr.write(`${APP_NAME} join requires an interactive terminal\n`);
+			process.exitCode = 1;
+			return;
+		}
+		const parsed = parseArgs([]);
+		parsed.join = link;
+		await runRootCommand(parsed, []);
+	}
+}

package/src/commands/launch.ts

@@ -2,7 +2,7 @@
  * Root command for the coding agent CLI.
  */
 
-import { THINKING_EFFORTS } from "@prometheus-ai/ai";
+import { THINKING_EFFORTS } from "@prometheus-ai/catalog/effort";
 import { APP_NAME } from "@prometheus-ai/utils";
 import { Args, Command, Flags } from "@prometheus-ai/utils/cli";
 import { parseArgs } from "../cli/args";
@@ -49,10 +49,17 @@ export default class Index extends Command {
 		"allow-home": Flags.boolean({
 			description: "Allow starting in ~ without auto-switching to a temp dir",
 		}),
+		cwd: Flags.string({
+			description: "Directory to start in (overrides the launch cwd)",
+		}),
 		mode: Flags.string({
 			description: "Output mode: text (default), json, rpc, or rpc-ui",
 			options: ["text", "json", "rpc", "acp", "rpc-ui"],
 		}),
+		config: Flags.string({
+			description: "Load an extra config.yml-style overlay for this run (repeatable)",
+			multiple: true,
+		}),
 		print: Flags.boolean({
 			char: "p",
 			description: "Non-interactive mode: process prompt and exit",
@@ -117,9 +124,6 @@ export default class Index extends Command {
 		export: Flags.string({
 			description: "Export session file to HTML and exit",
 		}),
-		"list-models": Flags.string({
-			description: "List available models (with optional fuzzy search)",
-		}),
 		"no-title": Flags.boolean({
 			description: "Disable title auto-generation",
 		}),