@oh-my-pi/pi-coding-agent 13.5.3 → 13.5.5

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## [Unreleased]
 
+## [13.5.5] - 2026-03-01
+
+### Added
+
+- Added Kagi web search provider (Search API v0) with related searches support and automatic `KAGI_API_KEY` detection
+
+## [13.5.4] - 2026-03-01
+### Added
+
+- Added `authServerUrl` field to `AuthDetectionResult` to capture OAuth server metadata from `Mcp-Auth-Server` headers
+- Added `extractMcpAuthServerUrl()` function to parse and validate `Mcp-Auth-Server` URLs from error messages
+- Added support for `/.well-known/oauth-protected-resource` discovery endpoint to resolve authorization servers
+- Added recursive auth server discovery to follow `authorization_servers` references when discovering OAuth endpoints
+
+- Added `omp agents unpack` CLI subcommand to export bundled subagent definitions to `~/.omp/agent/agents` by default, with `--project` support for `./.omp/agents`
+### Changed
+
+- Enhanced `discoverOAuthEndpoints()` to accept optional `authServerUrl` parameter and query both auth server and resource server for OAuth metadata
+- Improved OAuth metadata extraction to handle additional field name variations (`clientId`, `default_client_id`, `public_client_id`)
+- Refactored OAuth endpoint discovery logic into reusable `findEndpoints()` helper for consistent metadata parsing across multiple sources
+- Task subagents now strip inherited `AGENTS.md` context files and the task tool prompt no longer warns against repeating AGENTS guidance, aligning subagent context with explicit task inputs ([#233](https://github.com/can1357/oh-my-pi/issues/233))
+
+### Fixed
+
+- Fixed MCP OAuth discovery to honor `Mcp-Auth-Server` metadata and resolve authorization endpoints from the declared auth server, restoring Figma MCP login URLs with `client_id` ([#235](https://github.com/can1357/oh-my-pi/issues/235))
+
 ## [13.5.3] - 2026-03-01
 
 ### Added

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "13.5.3",
+	"version": "13.5.5",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/can1357/oh-my-pi",
 	"author": "Can Boluk",
@@ -41,12 +41,12 @@
 	},
 	"dependencies": {
 		"@mozilla/readability": "^0.6",
-		"@oh-my-pi/omp-stats": "13.5.3",
-		"@oh-my-pi/pi-agent-core": "13.5.3",
-		"@oh-my-pi/pi-ai": "13.5.3",
-		"@oh-my-pi/pi-natives": "13.5.3",
-		"@oh-my-pi/pi-tui": "13.5.3",
-		"@oh-my-pi/pi-utils": "13.5.3",
+		"@oh-my-pi/omp-stats": "13.5.5",
+		"@oh-my-pi/pi-agent-core": "13.5.5",
+		"@oh-my-pi/pi-ai": "13.5.5",
+		"@oh-my-pi/pi-natives": "13.5.5",
+		"@oh-my-pi/pi-tui": "13.5.5",
+		"@oh-my-pi/pi-utils": "13.5.5",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",

package/src/cli/agents-cli.ts

@@ -0,0 +1,138 @@
+/**
+ * Agents CLI command handlers.
+ *
+ * Handles `omp agents unpack` for writing bundled agent definitions to disk.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { getAgentDir, getProjectDir, isEnoent } from "@oh-my-pi/pi-utils";
+import { YAML } from "bun";
+import chalk from "chalk";
+import { theme } from "../modes/theme/theme";
+import { loadBundledAgents } from "../task/agents";
+import type { AgentDefinition } from "../task/types";
+
+export type AgentsAction = "unpack";
+
+export interface AgentsCommandArgs {
+	action: AgentsAction;
+	flags: {
+		force?: boolean;
+		json?: boolean;
+		dir?: string;
+		user?: boolean;
+		project?: boolean;
+	};
+}
+
+interface UnpackResult {
+	targetDir: string;
+	total: number;
+	written: string[];
+	skipped: string[];
+}
+
+function writeStdout(line: string): void {
+	process.stdout.write(`${line}\n`);
+}
+
+function resolveTargetDir(flags: AgentsCommandArgs["flags"]): string {
+	if (flags.dir && flags.dir.trim().length > 0) {
+		return path.resolve(getProjectDir(), flags.dir.trim());
+	}
+
+	if (flags.user && flags.project) {
+		throw new Error("Choose either --user or --project, not both.");
+	}
+
+	if (flags.project) {
+		return path.resolve(getProjectDir(), ".omp", "agents");
+	}
+
+	return path.join(getAgentDir(), "agents");
+}
+
+function toFrontmatter(agent: AgentDefinition): Record<string, unknown> {
+	const frontmatter: Record<string, unknown> = {
+		name: agent.name,
+		description: agent.description,
+	};
+
+	if (agent.tools && agent.tools.length > 0) frontmatter.tools = agent.tools;
+	if (agent.spawns !== undefined) frontmatter.spawns = agent.spawns;
+	if (agent.model && agent.model.length > 0) frontmatter.model = agent.model;
+	if (agent.thinkingLevel) frontmatter["thinking-level"] = agent.thinkingLevel;
+	if (agent.output !== undefined) frontmatter.output = agent.output;
+	if (agent.blocking) frontmatter.blocking = true;
+
+	return frontmatter;
+}
+
+function serializeAgent(agent: AgentDefinition): string {
+	const frontmatter = YAML.stringify(toFrontmatter(agent), null, 2).trimEnd();
+	const body = agent.systemPrompt.trim();
+	return `---\n${frontmatter}\n---\n\n${body}\n`;
+}
+
+async function unpackBundledAgents(flags: AgentsCommandArgs["flags"]): Promise<UnpackResult> {
+	const targetDir = resolveTargetDir(flags);
+	await fs.mkdir(targetDir, { recursive: true });
+
+	const bundledAgents = [...loadBundledAgents()].sort((a, b) => a.name.localeCompare(b.name));
+	const written: string[] = [];
+	const skipped: string[] = [];
+
+	for (const agent of bundledAgents) {
+		const filePath = path.join(targetDir, `${agent.name}.md`);
+		if (!flags.force) {
+			try {
+				await fs.stat(filePath);
+				skipped.push(filePath);
+				continue;
+			} catch (error) {
+				if (!isEnoent(error)) throw error;
+			}
+		}
+
+		await Bun.write(filePath, serializeAgent(agent));
+		written.push(filePath);
+	}
+
+	return {
+		targetDir,
+		total: bundledAgents.length,
+		written,
+		skipped,
+	};
+}
+
+export async function runAgentsCommand(cmd: AgentsCommandArgs): Promise<void> {
+	switch (cmd.action) {
+		case "unpack": {
+			const result = await unpackBundledAgents(cmd.flags);
+			if (cmd.flags.json) {
+				writeStdout(JSON.stringify(result, null, 2));
+				return;
+			}
+
+			writeStdout(chalk.bold(`Bundled agents: ${result.total}`));
+			writeStdout(chalk.dim(`Target directory: ${result.targetDir}`));
+			writeStdout(chalk.green(`${theme.status.success} Written: ${result.written.length}`));
+			if (result.skipped.length > 0) {
+				writeStdout(
+					chalk.yellow(
+						`${theme.status.warning} Skipped existing: ${result.skipped.length} (use --force to overwrite)`,
+					),
+				);
+			}
+
+			for (const filePath of result.written) {
+				writeStdout(chalk.dim(`  + ${filePath}`));
+			}
+			for (const filePath of result.skipped) {
+				writeStdout(chalk.dim(`  = ${filePath}`));
+			}
+			return;
+		}
+	}
+}

package/src/cli/args.ts

@@ -247,7 +247,10 @@ ${chalk.bold("Available Tools (all enabled by default):")}
   fetch      - Fetch and process URLs
   web_search - Search the web
   ask        - Ask user questions (interactive mode only)
-`;
+
+${chalk.bold("Useful Commands:")}
+  omp agents unpack           - Export bundled subagents to ~/.omp/agent/agents (default)
+  omp agents unpack --project - Export bundled subagents to ./.omp/agents`;
 }
 
 export function printHelp(): void {

package/src/cli.ts

@@ -16,6 +16,7 @@ process.title = APP_NAME;
 
 const commands: CommandEntry[] = [
 	{ name: "launch", load: () => import("./commands/launch").then(m => m.default) },
+	{ name: "agents", load: () => import("./commands/agents").then(m => m.default) },
 	{ name: "commit", load: () => import("./commands/commit").then(m => m.default) },
 	{ name: "config", load: () => import("./commands/config").then(m => m.default) },
 	{ name: "grep", load: () => import("./commands/grep").then(m => m.default) },

package/src/commands/agents.ts

@@ -0,0 +1,57 @@
+/**
+ * Manage bundled task agents.
+ */
+import { Args, Command, Flags, renderCommandHelp } from "@oh-my-pi/pi-utils/cli";
+import { type AgentsAction, type AgentsCommandArgs, runAgentsCommand } from "../cli/agents-cli";
+import { initTheme } from "../modes/theme/theme";
+
+const ACTIONS: AgentsAction[] = ["unpack"];
+
+export default class Agents extends Command {
+	static description = "Manage bundled task agents";
+
+	static args = {
+		action: Args.string({
+			description: "Agents action",
+			required: false,
+			options: ACTIONS,
+		}),
+	};
+
+	static flags = {
+		force: Flags.boolean({ char: "f", description: "Overwrite existing agent files" }),
+		json: Flags.boolean({ description: "Output JSON" }),
+		dir: Flags.string({ description: "Output directory (overrides --user/--project)" }),
+		user: Flags.boolean({ description: "Write to ~/.omp/agent/agents (default)" }),
+		project: Flags.boolean({ description: "Write to ./.omp/agents" }),
+	};
+
+	static examples = [
+		"# Export bundled agents into user config (default)\n  omp agents unpack",
+		"# Export bundled agents into project config\n  omp agents unpack --project",
+		"# Overwrite existing local agent files\n  omp agents unpack --project --force",
+		"# Export into a custom directory\n  omp agents unpack --dir ./tmp/agents --json",
+	];
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Agents);
+		if (!args.action) {
+			renderCommandHelp("omp", "agents", Agents);
+			return;
+		}
+
+		const cmd: AgentsCommandArgs = {
+			action: args.action as AgentsAction,
+			flags: {
+				force: flags.force,
+				json: flags.json,
+				dir: flags.dir,
+				user: flags.user,
+				project: flags.project,
+			},
+		};
+
+		await initTheme();
+		await runAgentsCommand(cmd);
+	}
+}

package/src/config/settings-schema.ts

@@ -757,6 +757,7 @@ export const SETTINGS_SCHEMA = {
 			"anthropic",
 			"gemini",
 			"codex",
+			"kagi",
 			"synthetic",
 		] as const,
 		default: "auto",

package/src/mcp/oauth-discovery.ts

@@ -16,9 +16,25 @@ export interface AuthDetectionResult {
 	requiresAuth: boolean;
 	authType?: "oauth" | "apikey" | "unknown";
 	oauth?: OAuthEndpoints;
+	authServerUrl?: string;
 	message?: string;
 }
 
+function parseMcpAuthServerUrl(errorMessage: string): string | undefined {
+	const match = errorMessage.match(/Mcp-Auth-Server:\s*([^;\]\s]+)/i);
+	if (!match || !match[1]) return undefined;
+
+	try {
+		return new URL(match[1]).toString();
+	} catch {
+		return undefined;
+	}
+}
+
+export function extractMcpAuthServerUrl(error: Error): string | undefined {
+	return parseMcpAuthServerUrl(error.message);
+}
+
 /**
  * Detect if an error indicates authentication is required.
  * Checks for common auth error patterns.
@@ -178,6 +194,8 @@ export function analyzeAuthError(error: Error): AuthDetectionResult {
 		return { requiresAuth: false };
 	}
 
+	const authServerUrl = extractMcpAuthServerUrl(error);
+
 	// Try to extract OAuth endpoints
 	const oauth = extractOAuthEndpoints(error);
 
@@ -186,6 +204,7 @@ export function analyzeAuthError(error: Error): AuthDetectionResult {
 			requiresAuth: true,
 			authType: "oauth",
 			oauth,
+			authServerUrl,
 			message: "Server requires OAuth authentication. Launching authorization flow...",
 		};
 	}
@@ -201,6 +220,7 @@ export function analyzeAuthError(error: Error): AuthDetectionResult {
 		return {
 			requiresAuth: true,
 			authType: "apikey",
+			authServerUrl,
 			message: "Server requires API key authentication.",
 		};
 	}
@@ -209,6 +229,7 @@ export function analyzeAuthError(error: Error): AuthDetectionResult {
 	return {
 		requiresAuth: true,
 		authType: "unknown",
+		authServerUrl,
 		message: "Server requires authentication but type could not be determined.",
 	};
 }
@@ -217,56 +238,110 @@ export function analyzeAuthError(error: Error): AuthDetectionResult {
  * Try to discover OAuth endpoints by querying the server's well-known endpoints.
  * This is a fallback when error responses don't include OAuth metadata.
  */
-export async function discoverOAuthEndpoints(serverUrl: string): Promise<OAuthEndpoints | null> {
+export async function discoverOAuthEndpoints(
+	serverUrl: string,
+	authServerUrl?: string,
+): Promise<OAuthEndpoints | null> {
 	const wellKnownPaths = [
 		"/.well-known/oauth-authorization-server",
 		"/.well-known/openid-configuration",
+		"/.well-known/oauth-protected-resource",
 		"/oauth/metadata",
 		"/.mcp/auth",
 		"/authorize", // Some MCP servers expose OAuth config here
 	];
+	const urlsToQuery = [authServerUrl, serverUrl].filter((value): value is string => Boolean(value));
+	const visitedAuthServers = new Set<string>();
 
-	for (const path of wellKnownPaths) {
-		try {
-			const url = new URL(path, serverUrl);
-			const response = await fetch(url.toString(), {
-				method: "GET",
-				headers: { Accept: "application/json" },
-			});
+	const findEndpoints = (metadata: Record<string, unknown>): OAuthEndpoints | null => {
+		if (metadata.authorization_endpoint && metadata.token_endpoint) {
+			const scopesSupported = Array.isArray(metadata.scopes_supported)
+				? metadata.scopes_supported.filter((scope): scope is string => typeof scope === "string").join(" ")
+				: undefined;
+			return {
+				authorizationUrl: String(metadata.authorization_endpoint),
+				tokenUrl: String(metadata.token_endpoint),
+				clientId:
+					typeof metadata.client_id === "string"
+						? metadata.client_id
+						: typeof metadata.clientId === "string"
+							? metadata.clientId
+							: typeof metadata.default_client_id === "string"
+								? metadata.default_client_id
+								: typeof metadata.public_client_id === "string"
+									? metadata.public_client_id
+									: undefined,
+				scopes:
+					scopesSupported ||
+					(typeof metadata.scopes === "string"
+						? metadata.scopes
+						: typeof metadata.scope === "string"
+							? metadata.scope
+							: undefined),
+			};
+		}
 
-			if (response.ok) {
-				const metadata = (await response.json()) as Record<string, any>;
+		if (metadata.oauth || metadata.authorization || metadata.auth) {
+			const oauthData = (metadata.oauth || metadata.authorization || metadata.auth) as Record<string, unknown>;
+			if (typeof oauthData.authorization_url === "string" && typeof oauthData.token_url === "string") {
+				return {
+					authorizationUrl: oauthData.authorization_url || String(oauthData.authorizationUrl),
+					tokenUrl: oauthData.token_url || String(oauthData.tokenUrl),
+					clientId:
+						typeof oauthData.client_id === "string"
+							? oauthData.client_id
+							: typeof oauthData.clientId === "string"
+								? oauthData.clientId
+								: typeof oauthData.default_client_id === "string"
+									? oauthData.default_client_id
+									: typeof oauthData.public_client_id === "string"
+										? oauthData.public_client_id
+										: undefined,
+					scopes:
+						typeof oauthData.scopes === "string"
+							? oauthData.scopes
+							: typeof oauthData.scope === "string"
+								? oauthData.scope
+								: undefined,
+				};
+			}
+		}
 
-				// Check for standard OAuth discovery format
-				if (metadata.authorization_endpoint && metadata.token_endpoint) {
-					return {
-						authorizationUrl: metadata.authorization_endpoint,
-						tokenUrl: metadata.token_endpoint,
-						clientId:
-							metadata.client_id || metadata.clientId || metadata.default_client_id || metadata.public_client_id,
-						scopes: metadata.scopes_supported?.join(" ") || metadata.scopes || metadata.scope,
-					};
-				}
+		return null;
+	};
+
+	for (const baseUrl of urlsToQuery) {
+		visitedAuthServers.add(baseUrl);
+		for (const path of wellKnownPaths) {
+			try {
+				const url = new URL(path, baseUrl);
+				const response = await fetch(url.toString(), {
+					method: "GET",
+					headers: { Accept: "application/json" },
+				});
 
-				// Check for MCP-specific format
-				if (metadata.oauth || metadata.authorization || metadata.auth) {
-					const oauthData = metadata.oauth || metadata.authorization || metadata.auth;
-					if (oauthData.authorization_url && oauthData.token_url) {
-						return {
-							authorizationUrl: oauthData.authorization_url || oauthData.authorizationUrl,
-							tokenUrl: oauthData.token_url || oauthData.tokenUrl,
-							clientId:
-								oauthData.client_id ||
-								oauthData.clientId ||
-								oauthData.default_client_id ||
-								oauthData.public_client_id,
-							scopes: oauthData.scopes || oauthData.scope,
-						};
+				if (response.ok) {
+					const metadata = (await response.json()) as Record<string, unknown>;
+					const endpoints = findEndpoints(metadata);
+					if (endpoints) return endpoints;
+
+					if (path === "/.well-known/oauth-protected-resource") {
+						const authServers = Array.isArray(metadata.authorization_servers)
+							? metadata.authorization_servers.filter((entry): entry is string => typeof entry === "string")
+							: [];
+
+						for (const discoveredAuthServer of authServers) {
+							if (visitedAuthServers.has(discoveredAuthServer)) {
+								continue;
+							}
+							const discovered = await discoverOAuthEndpoints(serverUrl, discoveredAuthServer);
+							if (discovered) return discovered;
+						}
 					}
 				}
+			} catch {
+				// Ignore errors, try next path
 			}
-		} catch {
-			// Ignore errors, try next path
 		}
 	}
 

package/src/modes/components/mcp-add-wizard.ts

@@ -947,7 +947,7 @@ export class MCPAddWizard extends Container {
 				let oauth = authResult.authType === "oauth" ? (authResult.oauth ?? null) : null;
 				if (!oauth && this.#state.transport !== "stdio" && this.#state.url) {
 					try {
-						oauth = await discoverOAuthEndpoints(this.#state.url);
+						oauth = await discoverOAuthEndpoints(this.#state.url, authResult.authServerUrl);
 					} catch {
 						// Ignore discovery failures and fallback to manual auth.
 					}

package/src/modes/components/settings-defs.ts

@@ -194,6 +194,7 @@ const OPTION_PROVIDERS: Partial<Record<SettingPath, OptionProvider>> = {
 		{ value: "perplexity", label: "Perplexity", description: "Requires PERPLEXITY_COOKIES or PERPLEXITY_API_KEY" },
 		{ value: "anthropic", label: "Anthropic", description: "Uses Anthropic web search" },
 		{ value: "zai", label: "Z.AI", description: "Calls Z.AI webSearchPrime MCP" },
+		{ value: "kagi", label: "Kagi", description: "Requires KAGI_API_KEY" },
 		{ value: "synthetic", label: "Synthetic", description: "Requires SYNTHETIC_API_KEY" },
 	],
 	"providers.image": [

package/src/modes/controllers/command-controller.ts

@@ -983,19 +983,6 @@ function resolveAggregateStatus(limits: UsageLimit[]): UsageLimit["status"] {
 	return "exhausted";
 }
 
-function isZeroUsage(limit: UsageLimit): boolean {
-	const amount = limit.amount;
-	if (amount.usedFraction !== undefined) return amount.usedFraction <= 0;
-	if (amount.used !== undefined) return amount.used <= 0;
-	if (amount.unit === "percent" && amount.used !== undefined) return amount.used <= 0;
-	if (amount.remainingFraction !== undefined) return amount.remainingFraction >= 1;
-	return false;
-}
-
-function isZeroUsageGroup(limits: UsageLimit[]): boolean {
-	return limits.length > 0 && limits.every(limit => isZeroUsage(limit));
-}
-
 function formatAggregateAmount(limits: UsageLimit[]): string {
 	const fractions = limits
 		.map(limit => resolveFraction(limit))
@@ -1117,13 +1104,6 @@ function renderUsageReports(reports: UsageReport[], uiTheme: typeof theme, nowMs
 			}
 		}
 
-		const providerAllZero = isZeroUsageGroup(Array.from(limitGroups.values()).flatMap(group => group.limits));
-		if (providerAllZero) {
-			const providerTitle = `${resolveStatusIcon("ok", uiTheme)} ${uiTheme.fg("accent", `${providerName} (0%)`)}`;
-			lines.push(uiTheme.bold(providerTitle));
-			continue;
-		}
-
 		lines.push(uiTheme.bold(uiTheme.fg("accent", providerName)));
 
 		for (const group of limitGroups.values()) {
@@ -1144,18 +1124,6 @@ function renderUsageReports(reports: UsageReport[], uiTheme: typeof theme, nowMs
 
 			const status = resolveAggregateStatus(sortedLimits);
 			const statusIcon = resolveStatusIcon(status, uiTheme);
-			if (isZeroUsageGroup(sortedLimits)) {
-				const resetText = resolveResetRange(sortedLimits, nowMs);
-				const resetSuffix = resetText ? ` | ${resetText}` : "";
-				const windowSuffix = formatWindowSuffix(group.label, group.windowLabel, uiTheme);
-				lines.push(
-					`${statusIcon} ${uiTheme.bold(group.label)} ${windowSuffix} ${uiTheme.fg(
-						"dim",
-						`0%${resetSuffix}`,
-					)}`.trim(),
-				);
-				continue;
-			}
 
 			const windowSuffix = formatWindowSuffix(group.label, group.windowLabel, uiTheme);
 			lines.push(`${statusIcon} ${uiTheme.bold(group.label)} ${windowSuffix}`.trim());

package/src/modes/controllers/mcp-command-controller.ts

@@ -264,7 +264,7 @@ export class MCPCommandController {
 						let oauth = authResult.authType === "oauth" ? (authResult.oauth ?? null) : null;
 						if (!oauth && finalConfig.url) {
 							try {
-								oauth = await discoverOAuthEndpoints(finalConfig.url);
+								oauth = await discoverOAuthEndpoints(finalConfig.url, authResult.authServerUrl);
 							} catch {
 								// Ignore discovery error and handle below.
 							}
@@ -574,7 +574,7 @@ export class MCPCommandController {
 		let oauth = authResult.authType === "oauth" ? (authResult.oauth ?? null) : null;
 
 		if (!oauth && (config.type === "http" || config.type === "sse") && config.url) {
-			oauth = await discoverOAuthEndpoints(config.url);
+			oauth = await discoverOAuthEndpoints(config.url, authResult.authServerUrl);
 		}
 
 		if (!oauth) {

package/src/prompts/tools/task.md

@@ -19,7 +19,6 @@ Subagents lack your conversation history. Every decision, file content, and user
 </parameters>
 
 <critical>
-- **MUST NOT** include AGENTS.md rules, coding conventions, or style guidelines — subagents already have them.
 - **MUST NOT** duplicate shared constraints across assignments — put them in `context` once.
 - **MUST NOT** tell tasks to run project-wide build/test/lint. Parallel agents share the working tree; each task edits, stops. Caller verifies after all complete.
 - For large payloads (traces, JSON blobs), write to `local://<path>` and pass the path in context.
@@ -47,7 +46,7 @@ Each task: **at most 3–5 files**. Globs in file paths, "update all", or packag
 ```
 ## Goal         ← one sentence: what the batch accomplishes
 ## Non-goals    ← what tasks must not touch
-## Constraints  ← MUST/MUST NOT rules beyond AGENTS.md; session decisions
+## Constraints  ← MUST/MUST NOT rules and session decisions
 ## API Contract ← exact types/signatures if tasks share an interface (omit if N/A)
 ## Acceptance   ← definition of done; build/lint runs AFTER all tasks complete
 ```
@@ -62,7 +61,7 @@ Each task: **at most 3–5 files**. Globs in file paths, "update all", or packag
 
 <checklist>
 Before invoking:
-- `context` contains only session-specific info not in AGENTS.md
+- `context` contains only session-specific info
 - Every `assignment` follows the template; no one-liners; edge cases covered
 - Tasks are truly parallel — you can articulate why none depends on another's output
 - File paths are explicit; no globs

package/src/session/agent-session.ts

@@ -38,7 +38,13 @@ import type {
 	Usage,
 	UsageReport,
 } from "@oh-my-pi/pi-ai";
-import { isContextOverflow, modelsAreEqual, supportsXhigh } from "@oh-my-pi/pi-ai";
+import {
+	calculateRateLimitBackoffMs,
+	isContextOverflow,
+	modelsAreEqual,
+	parseRateLimitReason,
+	supportsXhigh,
+} from "@oh-my-pi/pi-ai";
 import { abortableSleep, getAgentDbPath, isEnoent, logger } from "@oh-my-pi/pi-utils";
 import type { AsyncJob, AsyncJobManager } from "../async";
 import type { Rule } from "../capability/rule";
@@ -3959,7 +3965,7 @@ Be thorough - include exact file paths, function names, error messages, and tech
 	}
 
 	#isUsageLimitErrorMessage(errorMessage: string): boolean {
-		return /usage.?limit|usage_limit_reached|limit_reached/i.test(errorMessage);
+		return /usage.?limit|usage_limit_reached|limit_reached|quota.?exceeded|resource.?exhausted/i.test(errorMessage);
 	}
 
 	#parseRetryAfterMsFromError(errorMessage: string): number | undefined {
@@ -4004,6 +4010,7 @@ Be thorough - include exact file paths, function names, error messages, and tech
 			}
 		}
 
+		// Smart Fallback if no exact headers found
 		return undefined;
 	}
 
@@ -4043,7 +4050,9 @@ Be thorough - include exact file paths, function names, error messages, and tech
 		let delayMs = retrySettings.baseDelayMs * 2 ** (this.#retryAttempt - 1);
 
 		if (this.model && this.#isUsageLimitErrorMessage(errorMessage)) {
-			const retryAfterMs = this.#parseRetryAfterMsFromError(errorMessage);
+			const retryAfterMs =
+				this.#parseRetryAfterMsFromError(errorMessage) ??
+				calculateRateLimitBackoffMs(parseRateLimitReason(errorMessage));
 			const switched = await this.#modelRegistry.authStorage.markUsageLimitReached(
 				this.model.provider,
 				this.sessionId,
@@ -4054,6 +4063,9 @@ Be thorough - include exact file paths, function names, error messages, and tech
 			);
 			if (switched) {
 				delayMs = 0;
+			} else if (retryAfterMs > delayMs) {
+				// No more accounts to switch to — wait out the backoff
+				delayMs = retryAfterMs;
 			}
 		}
 

package/src/task/index.ts

@@ -691,7 +691,9 @@ export class TaskTool implements AgentTool<TaskSchema, TaskToolDetails, Theme> {
 			// Build full prompts with context prepended
 			const tasksWithContext = tasksWithUniqueIds.map(t => renderTemplate(context, t));
 			const availableSkills = [...(this.session.skills ?? [])];
-			const contextFiles = this.session.contextFiles;
+			const contextFiles = this.session.contextFiles?.filter(
+				file => path.basename(file.path).toLowerCase() !== "agents.md",
+			);
 			const promptTemplates = this.session.promptTemplates;
 
 			// Initialize progress for all tasks

package/src/web/search/index.ts

@@ -34,7 +34,20 @@ export const webSearchSchema = Type.Object({
 	query: Type.String({ description: "Search query" }),
 	provider: Type.Optional(
 		StringEnum(
-			["auto", "exa", "brave", "jina", "kimi", "zai", "anthropic", "perplexity", "gemini", "codex", "synthetic"],
+			[
+				"auto",
+				"exa",
+				"brave",
+				"jina",
+				"kimi",
+				"zai",
+				"anthropic",
+				"perplexity",
+				"gemini",
+				"codex",
+				"kagi",
+				"synthetic",
+			],
 			{
 				description: "Search provider (default: auto)",
 			},
@@ -64,6 +77,7 @@ export type SearchParams = {
 		| "perplexity"
 		| "gemini"
 		| "codex"
+		| "kagi"
 		| "synthetic";
 	recency?: "day" | "week" | "month" | "year";
 	limit?: number;

package/src/web/search/provider.ts

@@ -5,6 +5,7 @@ import { CodexProvider } from "./providers/codex";
 import { ExaProvider } from "./providers/exa";
 import { GeminiProvider } from "./providers/gemini";
 import { JinaProvider } from "./providers/jina";
+import { KagiProvider } from "./providers/kagi";
 import { KimiProvider } from "./providers/kimi";
 import { PerplexityProvider } from "./providers/perplexity";
 import { SyntheticProvider } from "./providers/synthetic";
@@ -24,6 +25,7 @@ const SEARCH_PROVIDERS: Record<SearchProviderId, SearchProvider> = {
 	anthropic: new AnthropicProvider(),
 	gemini: new GeminiProvider(),
 	codex: new CodexProvider(),
+	kagi: new KagiProvider(),
 	synthetic: new SyntheticProvider(),
 } as const;
 
@@ -37,6 +39,7 @@ export const SEARCH_PROVIDER_ORDER: SearchProviderId[] = [
 	"codex",
 	"zai",
 	"exa",
+	"kagi",
 	"synthetic",
 ];
 

package/src/web/search/providers/gemini.ts

@@ -7,6 +7,7 @@
  */
 import {
 	ANTIGRAVITY_SYSTEM_INSTRUCTION,
+	extractRetryDelay,
 	getAntigravityHeaders,
 	getGeminiCliHeaders,
 	refreshGoogleCloudToken,
@@ -23,6 +24,9 @@ const ANTIGRAVITY_DAILY_ENDPOINT = "https://daily-cloudcode-pa.googleapis.com";
 const ANTIGRAVITY_SANDBOX_ENDPOINT = "https://daily-cloudcode-pa.sandbox.googleapis.com";
 const ANTIGRAVITY_ENDPOINT_FALLBACKS = [ANTIGRAVITY_DAILY_ENDPOINT, ANTIGRAVITY_SANDBOX_ENDPOINT] as const;
 const DEFAULT_MODEL = "gemini-2.5-flash";
+const MAX_RETRIES = 3;
+const BASE_DELAY_MS = 1000;
+const RATE_LIMIT_BUDGET_MS = 5 * 60 * 1000;
 
 interface GeminiToolParams {
 	google_search?: Record<string, unknown>;
@@ -270,46 +274,83 @@ async function callGeminiSearch(
 		(requestBody.request as Record<string, unknown>).generationConfig = generationConfig;
 	}
 	let response: Response | undefined;
+	let rateLimitTimeSpent = 0;
+	let lastError: Error | undefined;
+
 	for (let endpointIndex = 0; endpointIndex < endpoints.length; endpointIndex++) {
 		const url = `${endpoints[endpointIndex]}/v1internal:streamGenerateContent?alt=sse`;
-		try {
-			response = await fetch(url, {
-				method: "POST",
-				headers: {
-					Authorization: `Bearer ${auth.accessToken}`,
-					"Content-Type": "application/json",
-					Accept: "text/event-stream",
-					...headers,
-				},
-				body: JSON.stringify(requestBody),
-			});
-		} catch (error) {
-			if (auth.isAntigravity && endpointIndex < endpoints.length - 1) {
-				continue;
+
+		for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+			try {
+				response = await fetch(url, {
+					method: "POST",
+					headers: {
+						Authorization: `Bearer ${auth.accessToken}`,
+						"Content-Type": "application/json",
+						Accept: "text/event-stream",
+						...headers,
+					},
+					body: JSON.stringify(requestBody),
+				});
+			} catch (error) {
+				if (attempt < MAX_RETRIES) {
+					await Bun.sleep(BASE_DELAY_MS * 2 ** attempt);
+					continue;
+				}
+
+				if (auth.isAntigravity && endpointIndex < endpoints.length - 1) {
+					break;
+				}
+
+				throw error;
 			}
-			throw error;
-		}
 
-		if (response.ok) {
-			break;
-		}
+			if (response.ok) {
+				break;
+			}
 
-		const errorText = await response.text();
-		const isRetryableStatus =
-			response.status === 429 ||
-			response.status === 500 ||
-			response.status === 502 ||
-			response.status === 503 ||
-			response.status === 504;
-		if (auth.isAntigravity && isRetryableStatus && endpointIndex < endpoints.length - 1) {
-			continue;
+			const errorText = await response.text();
+			const isRetryableStatus =
+				response.status === 429 ||
+				response.status === 500 ||
+				response.status === 502 ||
+				response.status === 503 ||
+				response.status === 504;
+
+			if (isRetryableStatus && attempt < MAX_RETRIES) {
+				const serverDelay = extractRetryDelay(errorText, response);
+				if (response.status === 429) {
+					if (serverDelay && rateLimitTimeSpent + serverDelay <= RATE_LIMIT_BUDGET_MS) {
+						rateLimitTimeSpent += serverDelay;
+						await Bun.sleep(serverDelay);
+						continue;
+					}
+					if (!serverDelay) {
+						await Bun.sleep(BASE_DELAY_MS * 2 ** attempt);
+						continue;
+					}
+				} else {
+					await Bun.sleep(serverDelay ?? BASE_DELAY_MS * 2 ** attempt);
+					continue;
+				}
+			}
+
+			lastError = new SearchProviderError(
+				"gemini",
+				`Gemini Cloud Code API error (${response.status}): ${errorText}`,
+				response.status,
+			);
+
+			if (auth.isAntigravity && isRetryableStatus && endpointIndex < endpoints.length - 1) {
+				break;
+			}
+
+			throw lastError;
 		}
 
-		throw new SearchProviderError(
-			"gemini",
-			`Gemini Cloud Code API error (${response.status}): ${errorText}`,
-			response.status,
-		);
+		if (response?.ok) {
+			break;
+		}
 	}
 
 	if (!response) {

package/src/web/search/providers/kagi.ts

@@ -0,0 +1,148 @@
+/**
+ * Kagi Web Search Provider
+ *
+ * Calls Kagi's Search API (v0) and maps results into the unified
+ * SearchResponse shape used by the web search tool.
+ */
+import { getEnvApiKey } from "@oh-my-pi/pi-ai";
+import type { SearchResponse, SearchSource } from "../../../web/search/types";
+import { SearchProviderError } from "../../../web/search/types";
+import { clampNumResults, dateToAgeSeconds } from "../utils";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+
+const KAGI_SEARCH_URL = "https://kagi.com/api/v0/search";
+const DEFAULT_NUM_RESULTS = 10;
+const MAX_NUM_RESULTS = 40;
+
+interface KagiSearchResult {
+	t: 0;
+	url: string;
+	title: string;
+	snippet?: string;
+	published?: string;
+	thumbnail?: {
+		url: string;
+		width?: number | null;
+		height?: number | null;
+	};
+}
+
+interface KagiRelatedSearches {
+	t: 1;
+	list: string[];
+}
+
+type KagiSearchObject = KagiSearchResult | KagiRelatedSearches;
+
+interface KagiMeta {
+	id: string;
+	node: string;
+	ms: number;
+	api_balance?: number;
+}
+
+interface KagiSearchResponse {
+	meta: KagiMeta;
+	data: KagiSearchObject[];
+	error?: Array<{ code: number; msg: string; ref?: unknown }>;
+}
+
+/** Find KAGI_API_KEY from environment or .env files. */
+export function findApiKey(): string | null {
+	return getEnvApiKey("kagi") ?? null;
+}
+
+async function callKagiSearch(
+	apiKey: string,
+	query: string,
+	limit: number,
+	signal?: AbortSignal,
+): Promise<KagiSearchResponse> {
+	const url = new URL(KAGI_SEARCH_URL);
+	url.searchParams.set("q", query);
+	url.searchParams.set("limit", String(limit));
+
+	const response = await fetch(url, {
+		headers: {
+			Authorization: `Bot ${apiKey}`,
+			Accept: "application/json",
+		},
+		signal,
+	});
+
+	if (!response.ok) {
+		const errorText = await response.text();
+		throw new SearchProviderError("kagi", `Kagi API error (${response.status}): ${errorText}`, response.status);
+	}
+
+	const data = (await response.json()) as KagiSearchResponse;
+
+	if (data.error && data.error.length > 0) {
+		const firstError = data.error[0];
+		throw new SearchProviderError("kagi", `Kagi API error: ${firstError.msg}`, firstError.code);
+	}
+
+	return data;
+}
+
+/** Execute Kagi web search. */
+export async function searchKagi(params: {
+	query: string;
+	num_results?: number;
+	signal?: AbortSignal;
+}): Promise<SearchResponse> {
+	const numResults = clampNumResults(params.num_results, DEFAULT_NUM_RESULTS, MAX_NUM_RESULTS);
+	const apiKey = findApiKey();
+	if (!apiKey) {
+		throw new Error("KAGI_API_KEY not found. Set it in environment or .env file.");
+	}
+
+	const data = await callKagiSearch(apiKey, params.query, numResults, params.signal);
+
+	const sources: SearchSource[] = [];
+	const relatedQuestions: string[] = [];
+
+	for (const item of data.data) {
+		if (item.t === 0) {
+			sources.push({
+				title: item.title,
+				url: item.url,
+				snippet: item.snippet,
+				publishedDate: item.published ?? undefined,
+				ageSeconds: dateToAgeSeconds(item.published),
+			});
+		} else if (item.t === 1) {
+			relatedQuestions.push(...item.list);
+		}
+	}
+
+	return {
+		provider: "kagi",
+		sources: sources.slice(0, numResults),
+		relatedQuestions: relatedQuestions.length > 0 ? relatedQuestions : undefined,
+		requestId: data.meta.id,
+	};
+}
+
+/** Search provider for Kagi web search. */
+export class KagiProvider extends SearchProvider {
+	readonly id = "kagi";
+	readonly label = "Kagi";
+
+	isAvailable() {
+		try {
+			return !!findApiKey();
+		} catch {
+			return false;
+		}
+	}
+
+	search(params: SearchParams): Promise<SearchResponse> {
+		return searchKagi({
+			query: params.query,
+			num_results: params.numSearchResults ?? params.limit,
+			signal: params.signal,
+		});
+	}
+}

package/src/web/search/types.ts

@@ -15,6 +15,7 @@ export type SearchProviderId =
 	| "perplexity"
 	| "gemini"
 	| "codex"
+	| "kagi"
 	| "synthetic";
 
 /** Source returned by search (all providers) */