@oh-my-pi/pi-coding-agent 15.1.2 → 15.1.3

package/src/prompts/tools/web-search.md

@@ -1,4 +1,4 @@
-Searches the web for up-to-date information beyond Claude's knowledge cutoff.
+Searches the web for up-to-date information beyond knowledge cutoff.
 
 <instruction>
 - You SHOULD prefer primary sources (papers, official docs) and corroborate key claims with multiple sources

package/src/sdk.ts

@@ -7,7 +7,13 @@ import {
 	INTENT_FIELD,
 	type ThinkingLevel,
 } from "@oh-my-pi/pi-agent-core";
-import type { CredentialDisabledEvent, Message, Model, SimpleStreamOptions } from "@oh-my-pi/pi-ai";
+import {
+	type CredentialDisabledEvent,
+	type Message,
+	type Model,
+	type SimpleStreamOptions,
+	streamSimple,
+} from "@oh-my-pi/pi-ai";
 import {
 	getOpenAICodexTransportDetails,
 	prewarmOpenAICodexResponses,
@@ -93,7 +99,8 @@ import {
 	SecretObfuscator,
 } from "./secrets";
 import { AgentSession } from "./session/agent-session";
-import { AuthStorage } from "./session/auth-storage";
+import { resolveAuthBrokerConfig } from "./session/auth-broker-config";
+import { AuthBrokerClient, AuthStorage, RemoteAuthCredentialStore } from "./session/auth-storage";
 import { convertToLlm } from "./session/messages";
 import { SessionManager } from "./session/session-manager";
 import { closeAllConnections } from "./ssh/connection-manager";
@@ -317,13 +324,37 @@ function getDefaultAgentDir(): string {
 // Discovery Functions
 
 /**
- * Create an AuthStorage instance with fallback support.
- * Reads from primary path first, then falls back to legacy paths (.pi, .claude).
+ * Create an AuthStorage instance.
+ *
+ * Default: local SQLite store at `<agentDir>/agent.db`.
+ *
+ * Broker mode: when `OMP_AUTH_BROKER_URL` is set, credentials are pulled from
+ * a remote auth-broker over the wire. Refresh tokens never leave the broker;
+ * the client receives access tokens with `refresh = "__remote__"` and calls
+ * back into the broker through the {@link AuthStorageOptions.refreshOAuthCredential}
+ * override to re-mint access tokens when needed.
  */
 export async function discoverAuthStorage(agentDir: string = getDefaultAgentDir()): Promise<AuthStorage> {
+	const brokerConfig = await resolveAuthBrokerConfig();
+	if (brokerConfig) {
+		const client = new AuthBrokerClient({ url: brokerConfig.url, token: brokerConfig.token });
+		const initialResult = await client.fetchSnapshot();
+		if (initialResult.status !== 200) throw new Error("Auth broker returned no initial snapshot");
+		const store = new RemoteAuthCredentialStore({ client, initialSnapshot: initialResult.snapshot });
+		// Refresh + usage hooks live on RemoteAuthCredentialStore; AuthStorage
+		// discovers them automatically when no explicit option overrides them.
+		const storage = new AuthStorage(store, {
+			configValueResolver: resolveConfigValue,
+			sourceLabel: `broker ${brokerConfig.url}`,
+		});
+		await storage.reload();
+		return storage;
+	}
 	const dbPath = getAgentDbPath(agentDir);
-
-	const storage = await AuthStorage.create(dbPath, { configValueResolver: resolveConfigValue });
+	const storage = await AuthStorage.create(dbPath, {
+		configValueResolver: resolveConfigValue,
+		sourceLabel: `local ${dbPath}`,
+	});
 	await storage.reload();
 	return storage;
 }
@@ -885,6 +916,13 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		thinkingLevel = logger.time("resolveThinkingLevelForModel", () =>
 			resolveThinkingLevelForModel(resolvedModel, thinkingLevel),
 		);
+		// Fire-and-forget TLS+H2 handshake to the model's host so it overlaps
+		// with the rest of session setup (extension/skill load, tool registry,
+		// system prompt build). Without this, the first `fetch(...)` pays the
+		// full handshake serially — 100–300 ms transcontinental for
+		// api.anthropic.com from a residential IP. Every mode benefits
+		// (interactive, print, rpc, acp).
+		preconnectModelHost(model.baseUrl);
 	}
 
 	let skills: Skill[];
@@ -1763,6 +1801,18 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				}
 				return key;
 			},
+			streamFn: (streamModel, context, streamOptions) =>
+				streamSimple(streamModel, context, {
+					...streamOptions,
+					onAuthError: async (provider, oldKey, error) => {
+						await modelRegistry.authStorage.invalidateCredentialMatching(provider, oldKey, streamOptions?.signal);
+						logger.debug("Retrying provider request after credential invalidation", {
+							provider,
+							error: error instanceof Error ? error.message : String(error),
+						});
+						return modelRegistry.getApiKeyForProvider(provider, agent.sessionId);
+					},
+				}),
 			cursorExecHandlers,
 			transformToolCallArguments: (args, _toolName) => {
 				let result = args;
@@ -1899,8 +1949,12 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		}
 
 		// Start LSP warmup in the background so startup does not block on language server initialization.
+		// Print/script invocations (`hasUI=false`) don't render the warmup status indicator AND typically
+		// finish before LSP servers would have stabilized — warming them just spends CPU parsing big
+		// `initialize` responses concurrently with the LLM stream consumer, jittering perceived latency.
+		// Tools that need an LSP server still spin one up on demand through `getOrCreateClient`.
 		let lspServers: CreateAgentSessionResult["lspServers"];
-		if (enableLsp && settings.get("lsp.diagnosticsOnWrite")) {
+		if (enableLsp && options.hasUI && settings.get("lsp.diagnosticsOnWrite")) {
 			lspServers = discoverStartupLspServers(cwd);
 			if (lspServers.length > 0) {
 				void (async () => {
@@ -2017,3 +2071,20 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		throw error;
 	}
 }
+
+/**
+ * Best-effort preconnect to the model's API host. Bun's `fetch.preconnect`
+ * primes DNS + TCP + TLS + H2 so the first real request reuses the warm
+ * connection. Errors are swallowed: preconnect is an optimization, never a
+ * hard dependency.
+ */
+function preconnectModelHost(baseUrl: string | undefined): void {
+	if (!baseUrl) return;
+	const preconnect = (globalThis.fetch as typeof fetch & { preconnect?: (url: string) => void }).preconnect;
+	if (typeof preconnect !== "function") return;
+	try {
+		preconnect(baseUrl);
+	} catch {
+		// Best effort.
+	}
+}

package/src/session/agent-session.ts

@@ -18,12 +18,15 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { scheduler } from "node:timers/promises";
 import {
+	type AfterToolCallContext,
+	type AfterToolCallResult,
 	type Agent,
 	AgentBusyError,
 	type AgentEvent,
 	type AgentMessage,
 	type AgentState,
 	type AgentTool,
+	resolveTelemetry,
 	ThinkingLevel,
 } from "@oh-my-pi/pi-agent-core";
 import {
@@ -153,6 +156,7 @@ import planModeToolDecisionReminderPrompt from "../prompts/system/plan-mode-tool
 	type: "text",
 };
 import ttsrInterruptTemplate from "../prompts/system/ttsr-interrupt.md" with { type: "text" };
+import ttsrToolReminderTemplate from "../prompts/system/ttsr-tool-reminder.md" with { type: "text" };
 import { type AgentRegistry, MAIN_AGENT_ID } from "../registry/agent-registry";
 import { deobfuscateSessionContext, type SecretObfuscator } from "../secrets/obfuscator";
 import { invalidateHostMetadata } from "../ssh/connection-manager";
@@ -767,6 +771,10 @@ export class AgentSession {
 	// TTSR manager for time-traveling stream rules
 	#ttsrManager: TtsrManager | undefined = undefined;
 	#pendingTtsrInjections: Rule[] = [];
+	/** Per-tool TTSR rules whose `interruptMode` opted out of aborting the stream.
+	 *  These are folded into the matched tool call's `toolResult` content as an
+	 *  in-band system reminder, instead of spawning a separate follow-up turn. */
+	#perToolTtsrInjections = new Map<string, Rule[]>();
 	#ttsrAbortPending = false;
 	#ttsrRetryToken = 0;
 	#ttsrResumePromise: Promise<void> | undefined = undefined;
@@ -880,16 +888,28 @@ export class AgentSession {
 		this.#transformContext = config.transformContext ?? (messages => messages);
 		this.#onPayload = config.onPayload;
 		this.rawSseDebugBuffer = config.rawSseDebugBuffer ?? new RawSseDebugBuffer();
+		// Avoid wrapping in an `async` closure when no user callback is configured: the
+		// outer await on `#onResponse` (provider-response.ts) tolerates a sync void return,
+		// and skipping the wrapper drops a per-event `newPromiseCapability` allocation that
+		// shows up as ~3.5% self time in streaming profiles.
 		const configuredOnResponse = config.onResponse;
-		this.#onResponse = async (response, model) => {
-			this.rawSseDebugBuffer.recordResponse(response, model);
-			await configuredOnResponse?.(response, model);
-		};
+		this.#onResponse = configuredOnResponse
+			? async (response, model) => {
+					this.rawSseDebugBuffer.recordResponse(response, model);
+					await configuredOnResponse(response, model);
+				}
+			: (response, model) => {
+					this.rawSseDebugBuffer.recordResponse(response, model);
+				};
 		const configuredOnSseEvent = config.onSseEvent;
-		this.#onSseEvent = (event, model) => {
-			this.rawSseDebugBuffer.recordEvent(event, model);
-			configuredOnSseEvent?.(event, model);
-		};
+		this.#onSseEvent = configuredOnSseEvent
+			? (event, model) => {
+					this.rawSseDebugBuffer.recordEvent(event, model);
+					configuredOnSseEvent(event, model);
+				}
+			: (event, model) => {
+					this.rawSseDebugBuffer.recordEvent(event, model);
+				};
 		this.agent.setProviderResponseInterceptor(this.#onResponse);
 		this.agent.setRawSseEventInterceptor(this.#onSseEvent);
 		this.#convertToLlm = config.convertToLlm ?? convertToLlm;
@@ -932,6 +952,8 @@ export class AgentSession {
 			this.#preCacheStreamingEditFile(event);
 			this.#maybeAbortStreamingEdit(event);
 		});
+		// Per-tool TTSR reminders are folded into the matched tool's result via this hook.
+		this.agent.afterToolCall = ctx => this.#ttsrAfterToolCall(ctx);
 		this.agent.providerSessionState = this.#providerSessionState;
 		this.#syncAgentSessionId();
 		this.#syncTodoPhasesFromBranch();
@@ -1325,77 +1347,87 @@ export class AgentSession {
 			if (matchContext && "delta" in assistantEvent) {
 				const matches = this.#ttsrManager.checkDelta(assistantEvent.delta, matchContext);
 				if (matches.length > 0) {
-					// Queue rules for injection; mark as injected only after successful enqueue.
-
-					this.#addPendingTtsrInjections(matches);
-
-					if (this.#shouldInterruptForTtsrMatch(matches, matchContext)) {
-						// Abort the stream immediately — do not gate on extension callbacks
-						this.#ttsrAbortPending = true;
-						this.#ensureTtsrResumePromise();
-						this.agent.abort();
-						// Notify extensions (fire-and-forget, does not block abort)
+					// Decide first: a non-interrupting tool-source match attaches to the
+					// specific tool call's result instead of driving a loop-wide follow-up.
+					const shouldInterrupt = this.#shouldInterruptForTtsrMatch(matches, matchContext);
+					const perToolId = shouldInterrupt ? undefined : this.#extractTtsrToolCallId(matchContext);
+					if (perToolId) {
+						this.#addPerToolTtsrInjections(perToolId, matches);
 						this.#emitSessionEvent({ type: "ttsr_triggered", rules: matches }).catch(() => {});
-						// Schedule retry after a short delay
-						const retryToken = ++this.#ttsrRetryToken;
-						const generation = this.#promptGeneration;
-						const targetMessageTimestamp =
-							event.message.role === "assistant" ? event.message.timestamp : undefined;
-						this.#schedulePostPromptTask(
-							async () => {
-								if (this.#ttsrRetryToken !== retryToken) {
-									this.#resolveTtsrResume();
-									return;
-								}
+					} else {
+						// Queue rules for injection; mark as injected only after successful enqueue.
+						this.#addPendingTtsrInjections(matches);
+
+						if (shouldInterrupt) {
+							// Abort the stream immediately — do not gate on extension callbacks
+							this.#ttsrAbortPending = true;
+							this.#ensureTtsrResumePromise();
+							this.agent.abort();
+							// Notify extensions (fire-and-forget, does not block abort)
+							this.#emitSessionEvent({ type: "ttsr_triggered", rules: matches }).catch(() => {});
+							// Schedule retry after a short delay
+							const retryToken = ++this.#ttsrRetryToken;
+							const generation = this.#promptGeneration;
+							const targetMessageTimestamp =
+								event.message.role === "assistant" ? event.message.timestamp : undefined;
+							this.#schedulePostPromptTask(
+								async () => {
+									if (this.#ttsrRetryToken !== retryToken) {
+										this.#resolveTtsrResume();
+										return;
+									}
 
-								const targetAssistantIndex = this.#findTtsrAssistantIndex(targetMessageTimestamp);
-								if (
-									!this.#ttsrAbortPending ||
-									this.#promptGeneration !== generation ||
-									targetAssistantIndex === -1
-								) {
+									const targetAssistantIndex = this.#findTtsrAssistantIndex(targetMessageTimestamp);
+									if (
+										!this.#ttsrAbortPending ||
+										this.#promptGeneration !== generation ||
+										targetAssistantIndex === -1
+									) {
+										this.#ttsrAbortPending = false;
+										this.#pendingTtsrInjections = [];
+										this.#perToolTtsrInjections.clear();
+										this.#resolveTtsrResume();
+										return;
+									}
 									this.#ttsrAbortPending = false;
-									this.#pendingTtsrInjections = [];
-									this.#resolveTtsrResume();
-									return;
-								}
-								this.#ttsrAbortPending = false;
-								const ttsrSettings = this.#ttsrManager?.getSettings();
-								if (ttsrSettings?.contextMode === "discard") {
-									// Remove the partial/aborted assistant turn from agent state
-									this.agent.replaceMessages(this.agent.state.messages.slice(0, targetAssistantIndex));
-								}
-								// Inject TTSR rules as system reminder before retry
-								const injection = this.#getTtsrInjectionContent();
-								if (injection) {
-									const details = { rules: injection.rules.map(rule => rule.name) };
-									this.agent.appendMessage({
-										role: "custom",
-										customType: "ttsr-injection",
-										content: injection.content,
-										display: false,
-										details,
-										attribution: "agent",
-										timestamp: Date.now(),
-									});
-									this.sessionManager.appendCustomMessageEntry(
-										"ttsr-injection",
-										injection.content,
-										false,
-										details,
-										"agent",
-									);
-									this.#markTtsrInjected(details.rules);
-								}
-								try {
-									await this.agent.continue();
-								} catch {
-									this.#resolveTtsrResume();
-								}
-							},
-							{ delayMs: 50 },
-						);
-						return;
+									this.#perToolTtsrInjections.clear();
+									const ttsrSettings = this.#ttsrManager?.getSettings();
+									if (ttsrSettings?.contextMode === "discard") {
+										// Remove the partial/aborted assistant turn from agent state
+										this.agent.replaceMessages(this.agent.state.messages.slice(0, targetAssistantIndex));
+									}
+									// Inject TTSR rules as system reminder before retry
+									const injection = this.#getTtsrInjectionContent();
+									if (injection) {
+										const details = { rules: injection.rules.map(rule => rule.name) };
+										this.agent.appendMessage({
+											role: "custom",
+											customType: "ttsr-injection",
+											content: injection.content,
+											display: false,
+											details,
+											attribution: "agent",
+											timestamp: Date.now(),
+										});
+										this.sessionManager.appendCustomMessageEntry(
+											"ttsr-injection",
+											injection.content,
+											false,
+											details,
+											"agent",
+										);
+										this.#markTtsrInjected(details.rules);
+									}
+									try {
+										await this.agent.continue();
+									} catch {
+										this.#resolveTtsrResume();
+									}
+								},
+								{ delayMs: 50 },
+							);
+							return;
+						}
 					}
 				}
 			}
@@ -1804,6 +1836,61 @@ export class AgentSession {
 		}
 	}
 
+	/** Tool-call id whose argument deltas triggered a TTSR match, when known. */
+	#extractTtsrToolCallId(matchContext: TtsrMatchContext): string | undefined {
+		if (matchContext.source !== "tool") return undefined;
+		const key = matchContext.streamKey;
+		if (typeof key !== "string" || !key.startsWith("toolcall:")) return undefined;
+		const id = key.slice("toolcall:".length);
+		return id.length > 0 ? id : undefined;
+	}
+
+	#addPerToolTtsrInjections(toolCallId: string, rules: Rule[]): void {
+		const bucket = this.#perToolTtsrInjections.get(toolCallId) ?? [];
+		const seen = new Set(bucket.map(rule => rule.name));
+		// Dedupe against rules already bucketed for other tool calls in this
+		// same assistant message so one rule attaches to exactly one tool call.
+		const claimedElsewhere = new Set<string>();
+		for (const [otherId, otherBucket] of this.#perToolTtsrInjections) {
+			if (otherId === toolCallId) continue;
+			for (const rule of otherBucket) claimedElsewhere.add(rule.name);
+		}
+		const newlyAdded: string[] = [];
+		for (const rule of rules) {
+			if (seen.has(rule.name) || claimedElsewhere.has(rule.name)) continue;
+			bucket.push(rule);
+			seen.add(rule.name);
+			newlyAdded.push(rule.name);
+		}
+		if (bucket.length === 0) return;
+		this.#perToolTtsrInjections.set(toolCallId, bucket);
+		// Claim the rules in the TTSR manager so subsequent deltas in this same
+		// turn (e.g. a sibling tool call's argument stream) don't re-match them.
+		// Persistence still happens in #ttsrAfterToolCall when the tool actually
+		// produces a result we can fold the reminder into.
+		if (newlyAdded.length > 0) {
+			this.#ttsrManager?.markInjectedByNames(newlyAdded);
+		}
+	}
+
+	/** `afterToolCall` hook: fold any per-tool TTSR reminders into the result. */
+	#ttsrAfterToolCall(ctx: AfterToolCallContext): AfterToolCallResult | undefined {
+		const rules = this.#perToolTtsrInjections.get(ctx.toolCall.id);
+		if (!rules || rules.length === 0) return undefined;
+		this.#perToolTtsrInjections.delete(ctx.toolCall.id);
+		const reminder = rules
+			.map(r => prompt.render(ttsrToolReminderTemplate, { name: r.name, path: r.path, content: r.content }))
+			.join("\n\n");
+		// The TTSR manager was already claimed at bucket time; only persistence remains.
+		const ruleNames = rules.map(r => r.name.trim()).filter(n => n.length > 0);
+		if (ruleNames.length > 0) {
+			this.sessionManager.appendTtsrInjection(ruleNames);
+		}
+		return {
+			content: [{ type: "text", text: reminder }, ...ctx.result.content],
+		};
+	}
+
 	#extractTtsrRuleNames(details: unknown): string[] {
 		if (!details || typeof details !== "object" || Array.isArray(details)) {
 			return [];
@@ -1854,6 +1941,11 @@ export class AgentSession {
 	}
 
 	#queueDeferredTtsrInjectionIfNeeded(assistantMsg: AssistantMessage): void {
+		if (assistantMsg.stopReason === "aborted" || assistantMsg.stopReason === "error") {
+			// Tools that hadn't started by abort/error will never produce results to
+			// fold injections into — drop their stale per-tool entries.
+			this.#perToolTtsrInjections.clear();
+		}
 		if (this.#ttsrAbortPending || this.#pendingTtsrInjections.length === 0) {
 			return;
 		}
@@ -5249,6 +5341,7 @@ export class AgentSession {
 					convertToLlm,
 					initiatorOverride: "agent",
 					metadata: this.agent.metadataForProvider(model.provider),
+					telemetry: resolveTelemetry(this.agent.telemetry, this.sessionId),
 				},
 				handoffSignal,
 			);
@@ -5961,6 +6054,7 @@ export class AgentSession {
 		options?: SummaryOptions,
 	): Promise<CompactionResult> {
 		const candidates = this.#getCompactionModelCandidates(this.#modelRegistry.getAvailable());
+		const telemetry = resolveTelemetry(this.agent.telemetry, this.sessionId);
 
 		for (const candidate of candidates) {
 			const apiKey = await this.#modelRegistry.getApiKey(candidate, this.sessionId);
@@ -5971,6 +6065,7 @@ export class AgentSession {
 					...options,
 					metadata: this.agent.metadataForProvider(candidate.provider),
 					convertToLlm,
+					telemetry,
 				});
 			} catch (error) {
 				if (!this.#isCompactionAuthFailure(error)) {
@@ -6207,6 +6302,7 @@ export class AgentSession {
 			} else {
 				const candidates = this.#getCompactionModelCandidates(availableModels);
 				const retrySettings = this.settings.getGroup("retry");
+				const telemetry = resolveTelemetry(this.agent.telemetry, this.sessionId);
 				let compactResult: CompactionResult | undefined;
 				let lastError: unknown;
 
@@ -6224,6 +6320,7 @@ export class AgentSession {
 								metadata: this.agent.metadataForProvider(candidate.provider),
 								initiatorOverride: "agent",
 								convertToLlm,
+								telemetry,
 							});
 							break;
 						} catch (error) {
@@ -7828,6 +7925,7 @@ export class AgentSession {
 				reserveTokens: branchSummarySettings.reserveTokens,
 				metadata: this.agent.metadataForProvider(model.provider),
 				convertToLlm,
+				telemetry: resolveTelemetry(this.agent.telemetry, this.sessionId),
 			});
 			this.#branchSummaryAbortController = undefined;
 			if (result.aborted) {
@@ -8063,11 +8161,12 @@ export class AgentSession {
 		};
 	}
 
-	async fetchUsageReports(): Promise<UsageReport[] | null> {
+	async fetchUsageReports(signal?: AbortSignal): Promise<UsageReport[] | null> {
 		const authStorage = this.#modelRegistry.authStorage;
 		if (!authStorage.fetchUsageReports) return null;
 		return authStorage.fetchUsageReports({
 			baseUrlResolver: provider => this.#modelRegistry.getProviderBaseUrl?.(provider),
+			signal,
 		});
 	}
 

package/src/session/agent-storage.ts

@@ -1,7 +1,12 @@
 import { Database, type Statement } from "bun:sqlite";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { type AuthCredential, AuthCredentialStore, type StoredAuthCredential } from "@oh-my-pi/pi-ai";
+import {
+	type AuthCredential,
+	type AuthCredentialStore,
+	SqliteAuthCredentialStore,
+	type StoredAuthCredential,
+} from "@oh-my-pi/pi-ai";
 import { getAgentDbPath, isRecord, logger } from "@oh-my-pi/pi-utils";
 import type { RawSettings as Settings } from "../config/settings";
 
@@ -57,7 +62,7 @@ export class AgentStorage {
 		this.#hardenPermissions(dbPath);
 
 		// Create AuthCredentialStore with our open database
-		this.#authStore = new AuthCredentialStore(this.#db);
+		this.#authStore = new SqliteAuthCredentialStore(this.#db);
 
 		this.#listSettingsStmt = this.#db.prepare("SELECT key, value FROM settings");
 		this.#upsertModelUsageStmt = this.#db.prepare(

package/src/session/auth-broker-config.ts

@@ -0,0 +1,102 @@
+/**
+ * Resolve auth-broker connection configuration for the local omp client.
+ *
+ * Precedence (highest first):
+ *   1. `OMP_AUTH_BROKER_URL` / `OMP_AUTH_BROKER_TOKEN` env vars.
+ *   2. `auth.broker.url` / `auth.broker.token` in `~/.omp/agent/config.yml`
+ *      (hidden from the settings UI; `!command` resolution supported).
+ *   3. Token file `~/.omp/auth-broker.token` (paired with URL from env or config).
+ *
+ * Returns null when no broker URL is configured — caller falls back to the
+ * local SQLite store.
+ *
+ * Reads config.yml directly (instead of going through `Settings.init`) because
+ * `discoverAuthStorage` runs before the settings singleton is initialized in
+ * `runRootCommand`, and we want hand-edited config entries to be honoured at
+ * boot without forcing a startup reorder.
+ */
+import * as path from "node:path";
+import { getAgentDir, getConfigRootDir, isEnoent, logger } from "@oh-my-pi/pi-utils";
+import { YAML } from "bun";
+import { resolveConfigValue } from "../config/resolve-config-value";
+
+export interface AuthBrokerClientConfig {
+	url: string;
+	token: string;
+}
+
+/** Path to the local bearer token file. Created on the broker host by `omp auth-broker token`. */
+export function getAuthBrokerTokenFilePath(): string {
+	return path.join(getConfigRootDir(), "auth-broker.token");
+}
+
+async function readTokenFile(): Promise<string | null> {
+	try {
+		const raw = await Bun.file(getAuthBrokerTokenFilePath()).text();
+		const trimmed = raw.trim();
+		return trimmed.length > 0 ? trimmed : null;
+	} catch (err) {
+		if (isEnoent(err)) return null;
+		logger.warn("auth-broker token file unreadable", { error: String(err) });
+		return null;
+	}
+}
+
+interface ConfigSnapshot {
+	url?: string;
+	token?: string;
+}
+
+async function readConfigYaml(): Promise<ConfigSnapshot> {
+	const configPath = path.join(getAgentDir(), "config.yml");
+	try {
+		const raw = await Bun.file(configPath).text();
+		const parsed = YAML.parse(raw);
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+		const record = parsed as Record<string, unknown>;
+		const url = typeof record["auth.broker.url"] === "string" ? (record["auth.broker.url"] as string) : undefined;
+		const token =
+			typeof record["auth.broker.token"] === "string" ? (record["auth.broker.token"] as string) : undefined;
+		return { url, token };
+	} catch (err) {
+		if (isEnoent(err)) return {};
+		logger.warn("auth-broker config.yml unreadable", { error: String(err) });
+		return {};
+	}
+}
+
+/**
+ * Read broker configuration. Returns null when the URL is missing
+ * (broker disabled — local store is used). Throws when URL is set but no
+ * token is available — the caller cannot fall back silently because the
+ * user explicitly asked to use the broker.
+ */
+export async function resolveAuthBrokerConfig(): Promise<AuthBrokerClientConfig | null> {
+	const envUrl = process.env.OMP_AUTH_BROKER_URL;
+	const envToken = process.env.OMP_AUTH_BROKER_TOKEN;
+
+	let url = envUrl && envUrl.length > 0 ? envUrl : undefined;
+	let configToken: string | undefined;
+	if (!url || !envToken) {
+		const fromConfig = await readConfigYaml();
+		if (!url && fromConfig.url) {
+			const resolved = await resolveConfigValue(fromConfig.url);
+			if (resolved && resolved.length > 0) url = resolved;
+		}
+		if (fromConfig.token) {
+			const resolved = await resolveConfigValue(fromConfig.token);
+			if (resolved && resolved.length > 0) configToken = resolved;
+		}
+	}
+	if (!url) return null;
+
+	const token =
+		(envToken && envToken.length > 0 ? envToken : undefined) ?? configToken ?? (await readTokenFile()) ?? undefined;
+	if (!token) {
+		throw new Error(
+			`OMP_AUTH_BROKER_URL is set (${url}) but no bearer token is available. ` +
+				`Set OMP_AUTH_BROKER_TOKEN, the \`auth.broker.token\` config entry, or place one at ${getAuthBrokerTokenFilePath()}.`,
+		);
+	}
+	return { url, token };
+}

package/src/session/auth-storage.ts

@@ -14,4 +14,10 @@ export type {
 	SerializedAuthStorage,
 	StoredAuthCredential,
 } from "@oh-my-pi/pi-ai";
-export { AuthStorage } from "@oh-my-pi/pi-ai";
+export {
+	AuthBrokerClient,
+	AuthStorage,
+	REMOTE_REFRESH_SENTINEL,
+	RemoteAuthCredentialStore,
+	SqliteAuthCredentialStore,
+} from "@oh-my-pi/pi-ai";

package/src/session/streaming-output.ts

@@ -1,5 +1,5 @@
 import type { AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
-import { sanitizeText } from "@oh-my-pi/pi-natives";
+import { sanitizeText } from "@oh-my-pi/pi-utils";
 import { formatBytes } from "../tools/render-utils";
 import { sanitizeWithOptionalSixelPassthrough } from "../utils/sixel";