@wahack/pi-coding-agent 15.11.0

package/src/irc/bus.ts

@@ -0,0 +1,292 @@
+/**
+ * IrcBus - Process-global mailbox bus for agent-to-agent messaging.
+ *
+ * Replaces the old auto-reply model: a `send` never blocks on the recipient
+ * generating anything. Delivery resolves the recipient via the global
+ * AgentRegistry — parked agents are revived through the
+ * AgentLifecycleManager, idle agents are woken with a real turn, and busy
+ * agents receive the message as a non-interrupting aside at the next step
+ * boundary (see AgentSession.deliverIrcMessage). Replies are real turns by
+ * the recipient, observed via `wait`.
+ */
+
+import { logger, Snowflake } from "@oh-my-pi/pi-utils";
+import { AgentLifecycleManager } from "../registry/agent-lifecycle";
+import { AgentRegistry, MAIN_AGENT_ID } from "../registry/agent-registry";
+import type { CustomMessage } from "../session/messages";
+
+export interface IrcMessage {
+	id: string;
+	/** Sender agent id. */
+	from: string;
+	/** Recipient agent id (resolved; "all" is expanded by the tool, not stored). */
+	to: string;
+	body: string;
+	ts: number;
+	/** Message id being answered. */
+	replyTo?: string;
+}
+
+export interface IrcDeliveryReceipt {
+	to: string;
+	outcome: "injected" | "woken" | "revived" | "failed";
+	error?: string;
+}
+
+interface IrcWaiter {
+	from?: string;
+	resolve: (msg: IrcMessage) => void;
+	cancel: () => void;
+}
+
+/** Mailbox cap per agent; oldest messages are dropped beyond it. */
+const MAILBOX_CAP = 100;
+
+export class IrcBus {
+	static #global: IrcBus | undefined;
+
+	static global(): IrcBus {
+		if (!IrcBus.#global) {
+			IrcBus.#global = new IrcBus();
+		}
+		return IrcBus.#global;
+	}
+
+	/** Reset the global bus. Test-only. */
+	static resetGlobalForTests(): void {
+		IrcBus.#global = undefined;
+	}
+
+	readonly #registry: AgentRegistry;
+	readonly #lifecycle: () => AgentLifecycleManager;
+	readonly #mailboxes = new Map<string, IrcMessage[]>();
+	readonly #waiters = new Map<string, IrcWaiter[]>();
+
+	constructor(registry: AgentRegistry = AgentRegistry.global(), lifecycle?: AgentLifecycleManager) {
+		this.#registry = registry;
+		// Lazy: the lifecycle global self-constructs against the global registry,
+		// so only touch it when a parked recipient actually needs reviving.
+		this.#lifecycle = () => lifecycle ?? AgentLifecycleManager.global();
+	}
+
+	/**
+	 * Fire-and-forget delivery. Never blocks on the recipient generating
+	 * anything: the receipt reports how the message reached the recipient
+	 * (waiter/aside = "injected", idle wake = "woken", park revival =
+	 * "revived"), not what they did with it.
+	 *
+	 * Mailbox semantics: a successfully delivered message never lingers in
+	 * the recipient's mailbox — injection/wake puts the full body into their
+	 * context, so buffering it too would double-deliver via a later
+	 * `wait`/`inbox` and inflate unread counts. Only a failed live hand-off
+	 * is buffered for the recipient to drain later.
+	 */
+	async send(msg: Omit<IrcMessage, "id" | "ts">): Promise<IrcDeliveryReceipt> {
+		const message: IrcMessage = { ...msg, id: Snowflake.next(), ts: Date.now() };
+		const ref = this.#registry.get(message.to);
+		if (!ref || ref.status === "aborted") {
+			return { to: message.to, outcome: "failed", error: `Unknown or terminated agent "${message.to}".` };
+		}
+
+		let revived = false;
+		if (ref.status === "parked") {
+			try {
+				await this.#lifecycle().ensureLive(message.to);
+				revived = true;
+			} catch (error) {
+				return {
+					to: message.to,
+					outcome: "failed",
+					error: error instanceof Error ? error.message : String(error),
+				};
+			}
+		}
+
+		// A pending `wait` from the recipient consumes the message directly —
+		// it is returned from their irc tool call and never hits the inbox or
+		// the session injection path.
+		const waiter = this.#takeMatchingWaiter(message.to, message.from);
+		if (waiter) {
+			waiter.resolve(message);
+			this.#relayToMainUi(message);
+			return { to: message.to, outcome: revived ? "revived" : "injected" };
+		}
+
+		const session = this.#registry.get(message.to)?.session;
+		if (!session) {
+			return { to: message.to, outcome: "failed", error: `Agent "${message.to}" has no live session.` };
+		}
+
+		try {
+			const delivery = await session.deliverIrcMessage(message);
+			this.#relayToMainUi(message);
+			return { to: message.to, outcome: revived ? "revived" : delivery };
+		} catch (error) {
+			// Live hand-off failed (e.g. recipient disposed mid-shutdown): buffer
+			// the message so a later `wait`/`inbox` from the recipient can still
+			// pick it up. The receipt stays "failed" — the recipient has not
+			// seen it.
+			this.#enqueue(message);
+			return {
+				to: message.to,
+				outcome: "failed",
+				error: error instanceof Error ? error.message : String(error),
+			};
+		}
+	}
+
+	/**
+	 * Block until a message for `agentId` (optionally from `filter.from`)
+	 * arrives; consume + return it. Null on timeout (`timeoutMs <= 0` waits
+	 * forever). Rejects when `signal` aborts. By default, already-buffered
+	 * mail satisfies the wait before parking a future waiter; callers that
+	 * need a strictly future reply can disable that drain.
+	 */
+	async wait(
+		agentId: string,
+		filter: { from?: string },
+		timeoutMs: number,
+		signal?: AbortSignal,
+		options?: { drainPending?: boolean },
+	): Promise<IrcMessage | null> {
+		if (signal?.aborted) {
+			throw signal.reason instanceof Error ? signal.reason : new Error("IRC wait aborted");
+		}
+
+		if (options?.drainPending !== false) {
+			// Already-pending mail satisfies the wait without parking a waiter.
+			const pending = this.#takeFromMailbox(agentId, filter.from);
+			if (pending) return pending;
+		}
+
+		const { promise, resolve, reject } = Promise.withResolvers<IrcMessage | null>();
+		let timer: NodeJS.Timeout | undefined;
+		let onAbort: (() => void) | undefined;
+
+		const waiter: IrcWaiter = {
+			from: filter.from,
+			resolve: msg => {
+				cleanup();
+				resolve(msg);
+			},
+			cancel: () => {
+				cleanup();
+			},
+		};
+		const cleanup = (): void => {
+			this.#removeWaiter(agentId, waiter);
+			clearTimeout(timer);
+			if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+		};
+
+		if (signal) {
+			onAbort = () => {
+				cleanup();
+				reject(signal.reason instanceof Error ? signal.reason : new Error("IRC wait aborted"));
+			};
+			signal.addEventListener("abort", onAbort, { once: true });
+		}
+		if (timeoutMs > 0) {
+			timer = setTimeout(() => {
+				cleanup();
+				resolve(null);
+			}, timeoutMs);
+			timer.unref?.();
+		}
+
+		let waiters = this.#waiters.get(agentId);
+		if (!waiters) {
+			waiters = [];
+			this.#waiters.set(agentId, waiters);
+		}
+		waiters.push(waiter);
+		return promise;
+	}
+
+	/** Drain (or peek) pending messages for `agentId`. */
+	inbox(agentId: string, opts?: { peek?: boolean }): IrcMessage[] {
+		const mailbox = this.#mailboxes.get(agentId);
+		if (!mailbox || mailbox.length === 0) return [];
+		if (opts?.peek) return [...mailbox];
+		this.#mailboxes.delete(agentId);
+		return mailbox;
+	}
+
+	unreadCount(agentId: string): number {
+		return this.#mailboxes.get(agentId)?.length ?? 0;
+	}
+
+	#enqueue(message: IrcMessage): void {
+		let mailbox = this.#mailboxes.get(message.to);
+		if (!mailbox) {
+			mailbox = [];
+			this.#mailboxes.set(message.to, mailbox);
+		}
+		mailbox.push(message);
+		if (mailbox.length > MAILBOX_CAP) {
+			const dropped = mailbox.shift();
+			logger.debug("IrcBus: mailbox full, dropped oldest message", {
+				agentId: message.to,
+				droppedId: dropped?.id,
+				droppedFrom: dropped?.from,
+			});
+		}
+	}
+
+	/** Resolve the OLDEST waiter for `agentId` whose from-filter accepts `from`. */
+	#takeMatchingWaiter(agentId: string, from: string): IrcWaiter | undefined {
+		const waiters = this.#waiters.get(agentId);
+		if (!waiters) return undefined;
+		const index = waiters.findIndex(waiter => !waiter.from || waiter.from === from);
+		if (index === -1) return undefined;
+		const [waiter] = waiters.splice(index, 1);
+		if (waiters.length === 0) this.#waiters.delete(agentId);
+		return waiter;
+	}
+
+	#removeWaiter(agentId: string, waiter: IrcWaiter): void {
+		const waiters = this.#waiters.get(agentId);
+		if (!waiters) return;
+		const index = waiters.indexOf(waiter);
+		if (index !== -1) waiters.splice(index, 1);
+		if (waiters.length === 0) this.#waiters.delete(agentId);
+	}
+
+	#takeFromMailbox(agentId: string, from?: string): IrcMessage | undefined {
+		const mailbox = this.#mailboxes.get(agentId);
+		if (!mailbox) return undefined;
+		const index = from ? mailbox.findIndex(msg => msg.from === from) : 0;
+		if (index === -1 || mailbox.length === 0) return undefined;
+		const [message] = mailbox.splice(index, 1);
+		if (mailbox.length === 0) this.#mailboxes.delete(agentId);
+		return message;
+	}
+
+	/**
+	 * Surface agent↔agent traffic as a display-only card on the main session
+	 * UI. Skipped when the main agent is either endpoint: as recipient its
+	 * own `deliverIrcMessage` (or `wait` tool result) already shows the
+	 * message, and as sender the irc send tool call already rendered the
+	 * outbound body — relaying it again would duplicate it in the transcript.
+	 */
+	#relayToMainUi(message: IrcMessage): void {
+		if (message.to === MAIN_AGENT_ID || message.from === MAIN_AGENT_ID) return;
+		const mainSession = this.#registry.get(MAIN_AGENT_ID)?.session;
+		if (!mainSession) return;
+		const record: CustomMessage = {
+			role: "custom",
+			customType: "irc:relay",
+			content: `[IRC \`${message.from}\` → \`${message.to}\`]\n\n${message.body}`,
+			display: true,
+			details: { from: message.from, to: message.to, body: message.body },
+			attribution: "agent",
+			timestamp: message.ts,
+		};
+		try {
+			mainSession.emitIrcRelayObservation(record);
+		} catch (error) {
+			// Display-only forwarding must never affect delivery semantics.
+			logger.debug("IrcBus: main UI relay failed", { to: message.to, error: String(error) });
+		}
+	}
+}

package/src/lib/xai-http.ts

@@ -0,0 +1,124 @@
+// Ported from NousResearch/hermes-agent (MIT) — tools/xai_http.py.
+
+import { getBundledModels } from "@oh-my-pi/pi-catalog/models";
+import { $env } from "@oh-my-pi/pi-utils";
+import type { ModelRegistry } from "../config/model-registry";
+
+const DEFAULT_BASE_URL = "https://api.x.ai/v1";
+
+interface XAICredentials {
+	provider: "xai-oauth" | "xai";
+	apiKey: string;
+	baseURL: string;
+}
+
+export function ohMyPiXAIUserAgent(): string {
+	return "oh-my-pi/xai";
+}
+
+type XAIProvider = "xai-oauth" | "xai";
+
+/**
+ * Resolve the HTTP base URL for an xAI tool call.
+ *
+ * Precedence:
+ *   1. `model.baseUrl` from the registry IF the user pinned a per-model
+ *      override — i.e. `merged.baseUrl` differs from the seeded/bundled
+ *      default for the (provider, id) pair. Mirrors the chat path's per-model
+ *      contract (`openai-responses.ts: model.baseUrl`).
+ *   2. `ModelRegistry.getProviderBaseUrl(provider)` — provider-level override
+ *      (e.g. `providers.xai-oauth.baseUrl` from models.yml). Reached when the
+ *      modelId does not appear in the registry under this provider, which
+ *      happens for tool-only ids like `grok-imagine-image` that
+ *      `applyXAIOAuthCuration` filters out via `XAI_NON_CHAT_PREFIXES`.
+ *      Without this leg, a registry-configured proxy is silently bypassed for
+ *      image/TTS traffic.
+ *   3. `XAI_BASE_URL` env var (legacy global override, preserved).
+ *   4. `DEFAULT_BASE_URL = "https://api.x.ai/v1"`.
+ *
+ * The override gate at step 1 uses `bundled?.baseUrl ?? DEFAULT_BASE_URL` as
+ * the canonical default sentinel. For xai (which has bundled entries) this
+ * compares against the bundled value; for xai-oauth (no bundled entries —
+ * models.json carries no xai-oauth records when the seed is absent, the
+ * picker is seeded statically from `xaiOAuthModelManagerOptions` with
+ * `baseUrl: DEFAULT_BASE_URL`) the sentinel falls back to DEFAULT_BASE_URL
+ * so the env leg remains reachable. Without that fallback, every xai-oauth
+ * model id forces `!bundled === true` and short-circuits XAI_BASE_URL
+ * silently. Lookup is scoped to (provider, id); matching by id alone would
+ * let xai-oauth entries hijack a xai tool call (or vice versa) when the
+ * same model id ships under both descriptors.
+ */
+function resolveXAIBaseURL(modelRegistry: ModelRegistry, provider: XAIProvider, modelId: string | undefined): string {
+	if (modelId) {
+		const merged = modelRegistry.getAll().find(m => m.id === modelId && m.provider === provider);
+		if (merged?.baseUrl) {
+			const bundled = getBundledModels(provider as Parameters<typeof getBundledModels>[0]).find(
+				m => m.id === modelId,
+			);
+			const providerDefault = bundled?.baseUrl ?? DEFAULT_BASE_URL;
+			if (merged.baseUrl !== providerDefault) {
+				return merged.baseUrl.replace(/\/$/, "");
+			}
+		}
+	}
+	const providerBaseUrl = modelRegistry.getProviderBaseUrl(provider);
+	if (providerBaseUrl) {
+		const normalized = providerBaseUrl.replace(/\/$/, "");
+		if (normalized !== DEFAULT_BASE_URL) return normalized;
+	}
+	return ($env.XAI_BASE_URL || DEFAULT_BASE_URL).replace(/\/$/, "");
+}
+
+/**
+ * Resolve xAI credentials for HTTP tool calls.
+ *
+ * Credential priority:
+ *   1. xai-oauth — only when a *dedicated* xai-oauth source exists. Composed
+ *      of two checks against the registry layer:
+ *        a. `authStorage.hasNonEnvCredential("xai-oauth")` covers stored
+ *           credentials (OAuth or api_key), runtime overrides (CLI
+ *           `--api-key` for xai-oauth), config overrides (models.yml
+ *           `providers.xai-oauth.apiKey`), and fallback resolvers.
+ *        b. `$env.XAI_OAUTH_TOKEN` covers the xai-oauth-specific env var.
+ *      `XAI_API_KEY` is intentionally NOT a signal here, even though the
+ *      env-fallback map (`stream.ts: "xai-oauth"`) lets xai-oauth borrow it
+ *      as a back-compat convenience: the borrow lets API-key-only setups
+ *      satisfy the xai-oauth branch and then resolve baseUrl under
+ *      xai-oauth instead of xai, silently bypassing `providers.xai.baseUrl`
+ *      overrides for image/TTS traffic. The gate routes the borrow case to
+ *      step 2 while preserving every dedicated xai-oauth path.
+ *   2. xai (plain API key). Delegates to ModelRegistry.getApiKeyForProvider
+ *      which runs AuthStorage.getApiKey's full cascade: runtime override →
+ *      models.yml config override → stored api_key credential → OAuth
+ *      resolution → XAI_API_KEY env var → custom fallback resolver.
+ *
+ * baseURL: see `resolveXAIBaseURL` above. Resolved AFTER the credential
+ * decision so the scoped (provider, id) lookup is unambiguous. `modelId`
+ * is optional; probes / tool-availability checks pass `undefined` and fall
+ * through to env/default.
+ *
+ * Returns null when neither credential is available. Caller is responsible
+ * for surfacing an actionable error message in that case.
+ */
+export async function resolveXAIHttpCredentials(
+	modelRegistry: ModelRegistry,
+	modelId?: string,
+): Promise<XAICredentials | null> {
+	const hasDedicatedXaiOAuth =
+		modelRegistry.authStorage.hasNonEnvCredential("xai-oauth") || Boolean($env.XAI_OAUTH_TOKEN);
+	if (hasDedicatedXaiOAuth) {
+		const oauthKey = await modelRegistry.getApiKeyForProvider("xai-oauth");
+		if (oauthKey) {
+			const baseURL = resolveXAIBaseURL(modelRegistry, "xai-oauth", modelId);
+			return { provider: "xai-oauth", apiKey: oauthKey, baseURL };
+		}
+	}
+
+	const apiKey = await modelRegistry.getApiKeyForProvider("xai");
+	if (apiKey) {
+		const baseURL = resolveXAIBaseURL(modelRegistry, "xai", modelId);
+		return { provider: "xai", apiKey, baseURL };
+	}
+
+	return null;
+}