zidane 6.4.4 → 6.5.1

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 import { d as ClassifiedErrorKind, i as AgentContextExceededError, l as CONTEXT_EXCEEDED_MESSAGE_PATTERNS, n as AgentAbortedError, o as AgentProviderError, p as matchesContextExceeded, r as AgentBudgetExceededError, s as AgentToolNotAllowedError, u as ClassifiedError } from "./timeout-DEaqslLO.js";
-import { $m as ToolDef, $p as DEFAULT_AGENT_CLOCK, Ah as SessionRun, As as SpawnToolOptions, Bm as ToolResultDocumentContent, C as SuccessfulMutationOutcome, Cm as RunHookMap, Dh as Session, Dm as SessionMessage, Em as SessionHookContext, Gi as AgentHookMap, Gm as ToolResultTextContent, Hm as ToolResultImageContent, Hp as AgentClock, Im as ToolHookContext, Jm as TurnUsage, Jp as ChildRunStats, Kf as OpenAIParams, Ki as AgentHooks, Km as ToolResultVideoContent, Lm as ToolOutcome, Mm as StreamHookContext, Oh as SessionData, Om as SessionTurn, Pm as ThinkingLevel, Qm as ToolContext, Rm as ToolResultAudioContent, Rr as InteractionToolOptions, S as MutationValidationResult, Sf as OpenRouterParams, Sh as SkillResource, Sm as RetryConfig, Th as CreateSessionOptions, Tm as SessionEndStatus, Ts as ChildAgent, Um as ToolResultImageRefContent, Up as AgentRunOptions, Vh as RemoteStoreOptions, Vm as ToolResultDocumentRefContent, Vp as AgentBehavior, Wi as Agent, Wm as ToolResultMetadata, Wp as AgentStats, Xm as toolOutputByteLength, Ym as toolOutputBudgetByteLength, Zm as toolResultToText, _ as statsByModel, _m as PromptVideoPart, af as StreamCallbacks, am as McpToolHookContext, b as MutationValidationHooksOptions, bg as McpConnection, bh as SkillConfig, bm as ResolveContentRef, cf as ToolCall, df as TurnResult, dh as StagedToolState, dm as ProgressNudgeMessage, eh as ToolMap, fh as ToolStateController, fm as PromptAudioPart, gm as PromptTextPart, h as flattenTurns, hh as ToolStateView, hm as PromptPart, if as ProviderCapabilities, im as McpServerConfig, ip as CerebrasParams, jh as SessionStore, js as SpawnToolState, km as SpawnHookContext, lf as ToolResult, lm as OAuthRefreshHookContext, mh as ToolStateStore, mm as PromptImagePart, nh as ReadStateEntry, of as StreamOptions, p as ModelUsage, ph as ToolStateOp, pm as PromptDocumentPart, pp as AnthropicParams, qi as AgentOptions, qm as TurnFinishReason, rf as Provider, rh as ReadStateMap, t as Preset, uf as ToolSpec, um as ProgressNudgeKind, v as MutationValidationBatch, vm as RepeatGuardConfig, vr as ValidationResult, wh as SkillsConfig, wm as SessionContentBlock, x as MutationValidationMutation, xm as ResolveContentRefBlock, y as MutationValidationFailure, ym as RepeatGuardToolMatcher, zm as ToolResultContent } from "./index-C-Nd2ZbV.js";
+import { $h as SkillsConfig, $m as SessionContentBlock, Bf as TurnResult, Bh as StagedToolState, Bm as ProgressNudgeMessage, C as SuccessfulMutationOutcome, Ch as TurnUsage, Cm as ChildRunStats, Dh as ToolContext, Eh as toolResultToText, Ff as StreamOptions, Gi as AgentHookMap, Gm as PromptTextPart, Hh as ToolStateOp, Hm as PromptDocumentPart, Hp as AnthropicParams, Jm as RepeatGuardToolMatcher, Ki as AgentHooks, Km as PromptVideoPart, Lf as ToolCall, Mf as Provider, Mh as ReadStateMap, Nf as ProviderCapabilities, Nm as McpServerConfig, Np as CerebrasParams, Ns as SpawnToolOptions, Oh as ToolDef, Om as DEFAULT_AGENT_CLOCK, Os as ChildAgent, Pf as StreamCallbacks, Pm as McpToolHookContext, Ps as SpawnToolState, Qm as RunHookMap, Rf as ToolResult, Rm as OAuthRefreshHookContext, Rr as InteractionToolOptions, S as MutationValidationResult, Sh as TurnFinishReason, Th as toolOutputByteLength, Uh as ToolStateStore, Um as PromptImagePart, Vh as ToolStateController, Vm as PromptAudioPart, Wh as ToolStateView, Wi as Agent, Wm as PromptPart, Xm as ResolveContentRefBlock, Yg as McpConnection, Yh as SkillConfig, Ym as ResolveContentRef, Zf as OpenRouterParams, Zh as SkillResource, Zm as RetryConfig, _ as statsByModel, _h as ToolResultImageContent, _m as AgentClock, ag as SessionRun, b as MutationValidationHooksOptions, bh as ToolResultTextContent, dh as ToolHookContext, eg as CreateSessionOptions, eh as SessionEndStatus, fh as ToolOutcome, gg as RemoteStoreOptions, gh as ToolResultDocumentRefContent, gm as AgentBehavior, h as flattenTurns, hh as ToolResultDocumentContent, ih as SpawnHookContext, jh as ReadStateEntry, kh as ToolMap, lh as ThinkingLevel, mh as ToolResultContent, ng as Session, nh as SessionMessage, og as SessionStore, p as ModelUsage, ph as ToolResultAudioContent, qi as AgentOptions, qm as RepeatGuardConfig, rg as SessionData, rh as SessionTurn, sh as StreamHookContext, t as Preset, th as SessionHookContext, v as MutationValidationBatch, vh as ToolResultImageRefContent, vm as AgentRunOptions, vr as ValidationResult, wh as toolOutputBudgetByteLength, x as MutationValidationMutation, xh as ToolResultVideoContent, xp as OpenAIParams, y as MutationValidationFailure, yh as ToolResultMetadata, ym as AgentStats, zf as ToolSpec, zm as ProgressNudgeKind } from "./index-CWBSrqI6.js";
 import { _ as TaskHandle, a as ContextType, c as ExecutionContext, g as TaskExitInfo, h as TaskEntry, l as ExecutionHandle, n as ContextCapabilities, o as DetachedTasksCapability, p as SpawnConfig, r as ContextHardening, s as ExecResult, t as BackgroundTaskStatus, v as TaskStallInfo } from "./types-M2DauK2D.js";
 import { t as SandboxProvider } from "./sandbox-DLY6uah7.js";
 export { type Agent, AgentAbortedError, type AgentBehavior, AgentBudgetExceededError, type AgentClock, AgentContextExceededError, type AgentHookMap, type AgentHooks, type AgentOptions, AgentProviderError, type AgentRunOptions, type AgentStats, AgentToolNotAllowedError, type AnthropicParams, type BackgroundTaskStatus, CONTEXT_EXCEEDED_MESSAGE_PATTERNS, type CerebrasParams, type ChildAgent, type ChildRunStats, type ClassifiedError, type ClassifiedErrorKind, type ContextCapabilities, type ContextHardening, type ContextType, type CreateSessionOptions, DEFAULT_AGENT_CLOCK, type DetachedTasksCapability, type ExecResult, type ExecutionContext, type ExecutionHandle, type InteractionToolOptions, type McpConnection, type McpServerConfig, type McpToolHookContext, type ModelUsage, type MutationValidationBatch, type MutationValidationFailure, type MutationValidationHooksOptions, type MutationValidationMutation, type MutationValidationResult, type OAuthRefreshHookContext, type OpenAIParams, type OpenRouterParams, type Preset, type ProgressNudgeKind, type ProgressNudgeMessage, type PromptAudioPart, type PromptDocumentPart, type PromptImagePart, type PromptPart, type PromptTextPart, type PromptVideoPart, type Provider, type ProviderCapabilities, type ReadStateEntry, type ReadStateMap, type RemoteStoreOptions, type RepeatGuardConfig, type RepeatGuardToolMatcher, type ResolveContentRef, type ResolveContentRefBlock, type RetryConfig, type RunHookMap, type SandboxProvider, type Session, type SessionContentBlock, type SessionData, type SessionEndStatus, type SessionHookContext, type SessionMessage, type SessionRun, type SessionStore, type SessionTurn, type SkillConfig, type SkillResource, type SkillsConfig, type SpawnConfig, type SpawnHookContext, type SpawnToolOptions, type SpawnToolState, type StagedToolState, type StreamCallbacks, type StreamHookContext, type StreamOptions, type SuccessfulMutationOutcome, type TaskEntry, type TaskExitInfo, type TaskHandle, type TaskStallInfo, type ThinkingLevel, type ToolCall, type ToolContext, type ToolDef, type ToolHookContext, type ToolMap, type ToolOutcome, type ToolResult, type ToolResultAudioContent, type ToolResultContent, type ToolResultDocumentContent, type ToolResultDocumentRefContent, type ToolResultImageContent, type ToolResultImageRefContent, type ToolResultMetadata, type ToolResultTextContent, type ToolResultVideoContent, type ToolSpec, type ToolStateController, type ToolStateOp, type ToolStateStore, type ToolStateView, type TurnFinishReason, type TurnResult, type TurnUsage, type ValidationResult, flattenTurns, matchesContextExceeded, statsByModel, toolOutputBudgetByteLength, toolOutputByteLength, toolResultToText };

package/dist/{xai-BPwMQSuF.js → xai-Du6Wfnlb.js}

@@ -1,4 +1,4 @@
-import { m as openaiCompat } from "./openai-compat-B3c_hzwf.js";
+import { m as openaiCompat } from "./openai-compat-CnHeo4Lz.js";
 import { i as isOAuthAccessToken, r as extractRuntimeCredentials, s as resolveOAuthApiKey } from "./oauth-bkEOybqm.js";
 import { createServer } from "node:http";
 //#region src/chat/oauth-page/pkce.ts
@@ -376,4 +376,4 @@ function xai(params) {
 //#endregion
 export { createXaiOAuthProvider as n, generatePkce as r, xai as t };
 
-//# sourceMappingURL=xai-BPwMQSuF.js.map
+//# sourceMappingURL=xai-Du6Wfnlb.js.map

package/dist/{xai-BPwMQSuF.js.map → xai-Du6Wfnlb.js.map}

@@ -1 +1 @@
-{"version":3,"file":"xai-BPwMQSuF.js","names":[],"sources":["../src/chat/oauth-page/pkce.ts","../src/chat/oauth-page/xai.ts","../src/providers/xai.ts"],"sourcesContent":["/**\n * PKCE helper. Inlined here (rather than imported from pi-ai) because\n * `@earendil-works/pi-ai/oauth` does not re-export it, and we don't want\n * to reach into `node_modules/.../utils/oauth/pkce.js` — that's an\n * implementation-detail path that breaks on minor upstream rearrangements.\n *\n * Web Crypto API only. Works under Bun + Node 22+ without any node:crypto\n * import (matches pi-ai's own behavior). Output is base64url per RFC 7636.\n */\n\nfunction base64UrlEncode(bytes: Uint8Array): string {\n  let binary = ''\n  for (const byte of bytes)\n    binary += String.fromCharCode(byte)\n  return btoa(binary).replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=/g, '')\n}\n\nexport interface PkcePair {\n  /** Random verifier used in the token-exchange step. */\n  verifier: string\n  /** SHA-256(verifier) sent on the authorize URL. */\n  challenge: string\n}\n\nexport async function generatePkce(): Promise<PkcePair> {\n  const verifierBytes = new Uint8Array(32)\n  crypto.getRandomValues(verifierBytes)\n  const verifier = base64UrlEncode(verifierBytes)\n\n  const data = new TextEncoder().encode(verifier)\n  const hashBuffer = await crypto.subtle.digest('SHA-256', data)\n  const challenge = base64UrlEncode(new Uint8Array(hashBuffer))\n\n  return { verifier, challenge }\n}\n","/**\n * xAI Grok OAuth flow (SuperGrok / X Premium+).\n *\n * xAI is **not** built into pi-ai, so — like Cursor — we implement the flow\n * here and register it with pi-ai's OAuth registry (`registerXaiOAuthProvider`)\n * so `getOAuthApiKey('xai-oauth', …)` resolves to it during lazy token refresh.\n *\n * Auth shape: OAuth 2.0 + PKCE with a loopback callback server, against xAI's\n * OIDC issuer (`https://auth.x.ai`). Differs from the Anthropic / Codex flows\n * (which use the shared `startCallbackServer`) on three points, so it gets its\n * own login impl rather than reusing that primitive:\n *\n *   1. The `redirect_uri` must be `http://127.0.0.1:56121/callback` verbatim\n *      (xAI matches the registered loopback IP, not `localhost`).\n *   2. Endpoints come from OIDC discovery, not hard-coded constants.\n *   3. Token exchange + refresh are `application/x-www-form-urlencoded`\n *      (the Anthropic flow posts JSON).\n *\n * The callback page still routes through {@link OAuthCallbackPageRenderer} so\n * the post-redirect HTML matches the rest of zidane's themed flows.\n *\n * Flow + constants adapted from the public reference implementations\n * (`stnly/pi-grok`, `BlockedPath/pi-xai-oauth`) and the Hermes Agent docs.\n * xAI's OAuth surface is unofficial/undocumented — re-verify the client id,\n * scopes, and callback port if login starts failing.\n */\n\nimport type {\n  OAuthCredentials,\n  OAuthLoginCallbacks,\n} from '@earendil-works/pi-ai/oauth'\nimport type { IncomingMessage, ServerResponse } from 'node:http'\nimport type { OAuthProviderInterface } from '../../providers/oauth-registry'\nimport type { OAuthCallbackPageRenderer } from './render'\nimport { createServer } from 'node:http'\nimport { generatePkce } from './pkce'\n\n/** pi-ai / zidane OAuth provider id. Also the credentials-file key. */\nexport const XAI_OAUTH_PROVIDER_ID = 'xai-oauth'\n\nconst DEFAULT_BASE_URL = 'https://api.x.ai/v1'\nconst ISSUER = 'https://auth.x.ai'\nconst DISCOVERY_URL = `${ISSUER}/.well-known/openid-configuration`\n/** Public client id used by the Grok CLI OAuth surface. */\nconst DEFAULT_CLIENT_ID = 'b1a00492-073a-47ea-816f-4c329264a828'\nconst DEFAULT_SCOPE = 'openid profile email offline_access grok-cli:access api:access'\n/** xAI matches the registered loopback IP exactly — `localhost` is rejected. */\nconst DEFAULT_CALLBACK_HOST = '127.0.0.1'\nconst DEFAULT_CALLBACK_PORT = 56121\nconst CALLBACK_PATH = '/callback'\nconst PROVIDER_NAME = 'xAI Grok'\n/** Refresh slightly early so requests don't race expiry. */\nconst REFRESH_SKEW_MS = 120_000\nconst CALLBACK_TIMEOUT_MS = 180_000\n\nfunction xaiOAuthClientId(): string {\n  return process.env.PI_XAI_OAUTH_CLIENT_ID || DEFAULT_CLIENT_ID\n}\n\nfunction xaiOAuthScope(): string {\n  return process.env.PI_XAI_OAUTH_SCOPE || DEFAULT_SCOPE\n}\n\nfunction xaiOAuthCallbackHost(): string {\n  return process.env.PI_XAI_OAUTH_CALLBACK_HOST || DEFAULT_CALLBACK_HOST\n}\n\nfunction xaiOAuthCallbackPort(): number {\n  const parsed = Number.parseInt(process.env.PI_XAI_OAUTH_CALLBACK_PORT || String(DEFAULT_CALLBACK_PORT), 10)\n  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_CALLBACK_PORT\n}\n\n/** Resolve the xAI API base URL (env override → default). */\nexport function xaiBaseUrl(): string {\n  return (process.env.PI_XAI_BASE_URL || process.env.XAI_BASE_URL || DEFAULT_BASE_URL)\n    .replace(/\\/+$/, '')\n}\n\ninterface XaiDiscovery {\n  authorization_endpoint: string\n  token_endpoint: string\n}\n\n/**\n * xAI OAuth credentials. Extends the base `{ access, refresh, expires }` with\n * the resolved `token_endpoint` so refresh doesn't need a second discovery\n * round-trip, plus the cached discovery doc for validation.\n */\nexport interface XaiOAuthCredentials extends OAuthCredentials {\n  tokenEndpoint?: string\n  discovery?: XaiDiscovery\n}\n\nfunction base64Url(bytes: Uint8Array): string {\n  let binary = ''\n  for (const b of bytes)\n    binary += String.fromCharCode(b)\n  return btoa(binary).replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '')\n}\n\nfunction randomToken(byteLength = 16): string {\n  return base64Url(crypto.getRandomValues(new Uint8Array(byteLength)))\n}\n\n/**\n * Refuse any OIDC endpoint that isn't HTTPS on an xAI origin.\n *\n * The discovery doc is cached long-term in `credentials.json`. A single MITM\n * during initial login could otherwise pin a malicious `token_endpoint` that\n * receives every subsequent refresh token. Validating scheme + host keeps the\n * endpoint on `x.ai` / `*.x.ai`.\n */\nfunction validateEndpoint(value: string, field: string): string {\n  let url: URL\n  try {\n    url = new URL(value)\n  }\n  catch {\n    throw new Error(`xAI OAuth discovery returned an invalid ${field}: ${value}`)\n  }\n  if (url.protocol !== 'https:')\n    throw new Error(`xAI OAuth ${field} must use HTTPS: ${value}`)\n  const host = url.hostname.toLowerCase()\n  if (host !== 'x.ai' && !host.endsWith('.x.ai'))\n    throw new Error(`Refusing non-xAI OAuth ${field}: ${value}`)\n  return url.toString()\n}\n\nasync function discover(): Promise<XaiDiscovery> {\n  let response: Response\n  try {\n    response = await fetch(DISCOVERY_URL, {\n      headers: { Accept: 'application/json' },\n      signal: AbortSignal.timeout(15_000),\n    })\n  }\n  catch (cause) {\n    throw new Error(`xAI OIDC discovery failed: ${cause instanceof Error ? cause.message : String(cause)}`)\n  }\n  if (!response.ok)\n    throw new Error(`xAI OIDC discovery returned ${response.status}`)\n\n  const payload = await response.json() as Record<string, unknown>\n  return {\n    authorization_endpoint: validateEndpoint(String(payload.authorization_endpoint ?? ''), 'authorization_endpoint'),\n    token_endpoint: validateEndpoint(String(payload.token_endpoint ?? ''), 'token_endpoint'),\n  }\n}\n\ninterface CallbackResult {\n  code?: string\n  state?: string\n  error?: string\n  errorDescription?: string\n}\n\ninterface XaiCallbackServer {\n  redirectUri: string\n  waitForCallback: (timeoutMs: number) => Promise<CallbackResult>\n  close: () => void\n}\n\n/**\n * Start the loopback callback server on `127.0.0.1:56121`. Falls back to an\n * OS-assigned port if 56121 is taken — xAI accepts any loopback port as long\n * as the `redirect_uri` we send on the authorize URL matches the listener.\n */\nasync function startXaiCallbackServer(renderPage: OAuthCallbackPageRenderer): Promise<XaiCallbackServer> {\n  const callbackHost = xaiOAuthCallbackHost()\n  const callbackPort = xaiOAuthCallbackPort()\n  let settle: ((value: CallbackResult) => void) | undefined\n  let settled = false\n  const callbackPromise = new Promise<CallbackResult>((resolve) => {\n    settle = (value) => {\n      if (settled)\n        return\n      settled = true\n      resolve(value)\n    }\n  })\n\n  const server = createServer((req: IncomingMessage, res: ServerResponse) => {\n    try {\n      // accounts.x.ai may issue a CORS preflight against the loopback listener.\n      const origin = req.headers.origin\n      if (origin === 'https://accounts.x.ai' || origin === 'https://auth.x.ai') {\n        res.setHeader('Access-Control-Allow-Origin', origin)\n        res.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS')\n        res.setHeader('Access-Control-Allow-Headers', 'Content-Type')\n        res.setHeader('Access-Control-Allow-Private-Network', 'true')\n        res.setHeader('Vary', 'Origin')\n      }\n      if (req.method === 'OPTIONS') {\n        res.statusCode = 204\n        res.end()\n        return\n      }\n\n      const url = new URL(req.url ?? '/', `http://${callbackHost}`)\n      if (url.pathname !== CALLBACK_PATH) {\n        res.statusCode = 404\n        res.end('Not found')\n        return\n      }\n\n      const result: CallbackResult = {\n        code: url.searchParams.get('code') ?? undefined,\n        state: url.searchParams.get('state') ?? undefined,\n        error: url.searchParams.get('error') ?? undefined,\n        errorDescription: url.searchParams.get('error_description') ?? undefined,\n      }\n\n      res.statusCode = result.error ? 400 : 200\n      res.setHeader('Content-Type', 'text/html; charset=utf-8')\n      res.end(renderPage(result.error\n        ? {\n            kind: 'error',\n            provider: PROVIDER_NAME,\n            message: `${PROVIDER_NAME} authentication did not complete.`,\n            details: result.errorDescription ?? result.error,\n          }\n        : {\n            kind: 'success',\n            provider: PROVIDER_NAME,\n            message: 'xAI authentication completed. You can close this window.',\n          }))\n      settle?.(result)\n    }\n    catch {\n      res.statusCode = 500\n      res.end('Internal error')\n    }\n  })\n\n  const listen = (port: number) => new Promise<number>((resolve, reject) => {\n    server.once('error', reject)\n    server.listen(port, callbackHost, () => {\n      server.removeListener('error', reject)\n      const addr = server.address()\n      resolve(typeof addr === 'object' && addr ? addr.port : port)\n    })\n  })\n\n  let actualPort: number\n  try {\n    actualPort = await listen(callbackPort)\n  }\n  catch {\n    actualPort = await listen(0)\n  }\n\n  return {\n    redirectUri: `http://${callbackHost}:${actualPort}${CALLBACK_PATH}`,\n    waitForCallback: timeoutMs => Promise.race([\n      callbackPromise,\n      new Promise<CallbackResult>(resolve =>\n        setTimeout(\n          resolve,\n          timeoutMs,\n          { error: 'timeout', errorDescription: 'Timed out waiting for the xAI OAuth callback.' },\n        )),\n    ]),\n    close: () => {\n      try { server.close() }\n      catch { /* already closed */ }\n    },\n  }\n}\n\nfunction expiryFromPayload(payload: Record<string, unknown>): number {\n  const expiresIn = typeof payload.expires_in === 'number'\n    ? payload.expires_in\n    : Number(payload.expires_in ?? 3600)\n  return Date.now() + expiresIn * 1000 - REFRESH_SKEW_MS\n}\n\nasync function exchangeCode(\n  tokenEndpoint: string,\n  code: string,\n  redirectUri: string,\n  verifier: string,\n  discovery: XaiDiscovery,\n): Promise<XaiOAuthCredentials> {\n  const clientId = xaiOAuthClientId()\n  const response = await fetch(tokenEndpoint, {\n    method: 'POST',\n    headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'Accept': 'application/json' },\n    body: new URLSearchParams({\n      grant_type: 'authorization_code',\n      client_id: clientId,\n      code,\n      redirect_uri: redirectUri,\n      code_verifier: verifier,\n    }),\n    signal: AbortSignal.timeout(30_000),\n  })\n  if (!response.ok)\n    throw new Error(`xAI token exchange failed: ${response.status} ${await response.text().catch(() => '')}`)\n\n  const payload = await response.json() as Record<string, unknown>\n  const access = String(payload.access_token ?? '')\n  const refresh = String(payload.refresh_token ?? '')\n  if (!access)\n    throw new Error('xAI token exchange did not return an access_token.')\n  if (!refresh)\n    throw new Error('xAI token exchange did not return a refresh_token.')\n\n  return { access, refresh, expires: expiryFromPayload(payload), tokenEndpoint, discovery }\n}\n\nexport async function loginXai(\n  renderPage: OAuthCallbackPageRenderer,\n  callbacks: OAuthLoginCallbacks,\n): Promise<XaiOAuthCredentials> {\n  const discovery = await discover()\n  const { verifier, challenge } = await generatePkce()\n  const state = randomToken()\n  const nonce = randomToken()\n  const server = await startXaiCallbackServer(renderPage)\n\n  try {\n    const authUrl = new URL(discovery.authorization_endpoint)\n    authUrl.searchParams.set('response_type', 'code')\n    authUrl.searchParams.set('client_id', xaiOAuthClientId())\n    authUrl.searchParams.set('redirect_uri', server.redirectUri)\n    authUrl.searchParams.set('scope', xaiOAuthScope())\n    authUrl.searchParams.set('code_challenge', challenge)\n    authUrl.searchParams.set('code_challenge_method', 'S256')\n    authUrl.searchParams.set('state', state)\n    authUrl.searchParams.set('nonce', nonce)\n    // Opt into xAI's generic OAuth plan tier (SuperGrok / X Premium+).\n    authUrl.searchParams.set('plan', 'generic')\n    authUrl.searchParams.set('referrer', 'zidane')\n\n    callbacks.onAuth({\n      url: authUrl.toString(),\n      instructions: `Sign in to xAI and approve access. If the browser is on another machine, the callback listener is ${server.redirectUri}.`,\n    })\n\n    const result = await server.waitForCallback(CALLBACK_TIMEOUT_MS)\n    if (result.error)\n      throw new Error(result.errorDescription ?? result.error)\n    if (result.state !== state)\n      throw new Error('xAI OAuth state mismatch — possible CSRF. Please retry.')\n    if (!result.code)\n      throw new Error('xAI OAuth callback did not include an authorization code.')\n\n    callbacks.onProgress?.('Exchanging authorization code for tokens...')\n    return await exchangeCode(discovery.token_endpoint, result.code, server.redirectUri, verifier, discovery)\n  }\n  finally {\n    server.close()\n  }\n}\n\nexport async function refreshXaiToken(credentials: OAuthCredentials): Promise<XaiOAuthCredentials> {\n  const xai = credentials as XaiOAuthCredentials\n  const clientId = xaiOAuthClientId()\n  if (!credentials.refresh)\n    throw new Error('xAI credentials are missing a refresh token — re-login required.')\n\n  const tokenEndpoint = xai.tokenEndpoint\n    ?? xai.discovery?.token_endpoint\n    ?? (await discover()).token_endpoint\n  validateEndpoint(tokenEndpoint, 'token_endpoint')\n\n  const response = await fetch(tokenEndpoint, {\n    method: 'POST',\n    headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'Accept': 'application/json' },\n    body: new URLSearchParams({\n      grant_type: 'refresh_token',\n      client_id: clientId,\n      refresh_token: credentials.refresh,\n    }),\n    signal: AbortSignal.timeout(30_000),\n  })\n  if (!response.ok)\n    throw new Error(`xAI token refresh failed: ${response.status} ${await response.text().catch(() => '')}`)\n\n  const payload = await response.json() as Record<string, unknown>\n  const access = String(payload.access_token ?? '')\n  if (!access)\n    throw new Error('xAI token refresh did not return an access_token.')\n\n  return {\n    ...xai,\n    access,\n    // xAI may omit a rotated refresh token — keep the existing one.\n    refresh: String(payload.refresh_token ?? credentials.refresh),\n    expires: expiryFromPayload(payload),\n    tokenEndpoint,\n  }\n}\n\n/**\n * Build an xAI `OAuthProviderInterface`. Shape matches Anthropic / Codex /\n * Cursor so it drops into `BUILTIN_PROVIDERS` and `src/auth.ts` unchanged.\n *\n * `usesCallbackServer: true` — the loopback flow has a real callback server,\n * so the TUI doesn't need to prompt for a manual code paste.\n */\nexport function createXaiOAuthProvider(renderPage: OAuthCallbackPageRenderer): OAuthProviderInterface {\n  return {\n    id: XAI_OAUTH_PROVIDER_ID,\n    name: 'xAI Grok (SuperGrok / X Premium+)',\n    usesCallbackServer: true,\n    login: callbacks => loginXai(renderPage, callbacks),\n    refreshToken: refreshXaiToken,\n    getApiKey: credentials => credentials.access,\n  }\n}\n","import type { Provider, ProviderCapabilities, StreamCallbacks, StreamOptions, TurnResult } from '.'\nimport type { OAuthParams } from './oauth'\nimport { XAI_OAUTH_PROVIDER_ID, xaiBaseUrl } from '../chat/oauth-page/xai'\nimport { extractRuntimeCredentials, isOAuthAccessToken, resolveOAuthApiKey } from './oauth'\nimport { openaiCompat } from './openai-compat'\n\nconst DEFAULT_MODEL = 'grok-4.3'\n\n/**\n * xAI Grok provider — supports both a static API key (`XAI_API_KEY`) and the\n * SuperGrok / X Premium+ OAuth subscription.\n *\n * Both auth modes hit the same OpenAI-compatible endpoint (`https://api.x.ai/v1`),\n * so the wire handling is entirely {@link openaiCompat}. The only difference is\n * the bearer:\n *\n *   - **API key**: `XAI_API_KEY` (or `params.apiKey`) → used verbatim.\n *   - **OAuth**:   no static key → {@link resolveOAuthApiKey} resolves + lazily\n *     refreshes the stored `xai-oauth` token on every turn.\n *\n * `resolveOAuthApiKey` unifies the two: a real API key in `XAI_API_KEY` is\n * returned as-is, while an OAuth access token (or no env value at all) falls\n * through to the refreshable stored credentials. So this single factory serves\n * both paths without branching at construction time.\n */\nexport interface XaiParams extends OAuthParams {\n  defaultModel?: string\n  /**\n   * Provider capability flags. Grok models are vision-capable; default\n   * `{ vision: true, imageInToolResult: false }`. Override for text-only\n   * deployments.\n   */\n  capabilities?: ProviderCapabilities\n  /** Extra HTTP headers sent on every request. */\n  extraHeaders?: Record<string, string>\n}\n\nexport function xai(params?: XaiParams): Provider {\n  const defaultModel = params?.defaultModel || DEFAULT_MODEL\n  const baseURL = xaiBaseUrl()\n  const capabilities: ProviderCapabilities = params?.capabilities ?? {\n    vision: true,\n    imageInToolResult: false,\n  }\n  const baseCredentials = extractRuntimeCredentials(params)\n  let runtimeCredentials = baseCredentials\n\n  // Factory-time snapshot for the static `meta.isOAuth` display flag only (the\n  // terminal header's `oauth`/`key` badge). The real bearer resolves per turn\n  // in `stream`, so this is best-effort, mirroring anthropic's pattern. It's\n  // OAuth unless a genuine static API key is present: a `xai-…` key → key mode;\n  // runtime OAuth creds, a JWT access token, or no static key (stored creds\n  // used) → oauth mode.\n  const staticKey = params?.apiKey ?? process.env.XAI_API_KEY\n  const isOAuth = baseCredentials !== undefined || !staticKey || isOAuthAccessToken(staticKey)\n\n  /**\n   * Build the openai-compat delegate for a resolved bearer. Cheap — the factory\n   * only wires closures — so we re-create it per turn with the freshly resolved\n   * (possibly refreshed) OAuth token rather than baking a stale key in once.\n   */\n  function delegateFor(apiKey: string): Provider {\n    return openaiCompat({\n      name: 'xai',\n      apiKey,\n      baseURL,\n      defaultModel,\n      capabilities,\n      extraHeaders: params?.extraHeaders,\n    })\n  }\n\n  // A delegate built with a placeholder key supplies the non-stream methods\n  // (formatTools, userMessage, message builders, classifyError). Only `stream`\n  // resolves the real bearer, so the placeholder never reaches the wire.\n  const skeleton = delegateFor('placeholder-resolved-at-stream')\n\n  return {\n    ...skeleton,\n    name: 'xai',\n    // Reuse the delegate's normalized capability flags (openaiCompat fills the\n    // audio/video/documents defaults) so the advertised shape matches the wire.\n    meta: { ...skeleton.meta, defaultModel, isOAuth },\n\n    async stream(options: StreamOptions, callbacks: StreamCallbacks): Promise<TurnResult> {\n      const apiKey = await resolveOAuthApiKey(\n        {\n          provider: 'xai',\n          providerId: XAI_OAUTH_PROVIDER_ID,\n          params: runtimeCredentials ? { ...params, ...runtimeCredentials } : params,\n          envKey: 'XAI_API_KEY',\n          missingError: 'No xAI credentials found. Set XAI_API_KEY or run `bun run auth --xai` first.',\n          refreshError: reason => `xAI OAuth token refresh failed. Run \\`bun run auth --xai\\` again. ${reason}`,\n        },\n        {\n          ...callbacks,\n          async onOAuthRefresh(ctx) {\n            // Keep param-sourced credentials current so a long-lived provider\n            // instance reuses the rotated token instead of re-refreshing.\n            if (ctx.source === 'params') {\n              runtimeCredentials = {\n                access: ctx.credentials.access,\n                refresh: ctx.credentials.refresh,\n                expires: ctx.credentials.expires,\n              }\n            }\n            await callbacks.onOAuthRefresh?.(ctx)\n          },\n        },\n      )\n\n      return delegateFor(apiKey).stream(options, callbacks)\n    },\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"xai-Du6Wfnlb.js","names":[],"sources":["../src/chat/oauth-page/pkce.ts","../src/chat/oauth-page/xai.ts","../src/providers/xai.ts"],"sourcesContent":["/**\n * PKCE helper. Inlined here (rather than imported from pi-ai) because\n * `@earendil-works/pi-ai/oauth` does not re-export it, and we don't want\n * to reach into `node_modules/.../utils/oauth/pkce.js` — that's an\n * implementation-detail path that breaks on minor upstream rearrangements.\n *\n * Web Crypto API only. Works under Bun + Node 22+ without any node:crypto\n * import (matches pi-ai's own behavior). Output is base64url per RFC 7636.\n */\n\nfunction base64UrlEncode(bytes: Uint8Array): string {\n  let binary = ''\n  for (const byte of bytes)\n    binary += String.fromCharCode(byte)\n  return btoa(binary).replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=/g, '')\n}\n\nexport interface PkcePair {\n  /** Random verifier used in the token-exchange step. */\n  verifier: string\n  /** SHA-256(verifier) sent on the authorize URL. */\n  challenge: string\n}\n\nexport async function generatePkce(): Promise<PkcePair> {\n  const verifierBytes = new Uint8Array(32)\n  crypto.getRandomValues(verifierBytes)\n  const verifier = base64UrlEncode(verifierBytes)\n\n  const data = new TextEncoder().encode(verifier)\n  const hashBuffer = await crypto.subtle.digest('SHA-256', data)\n  const challenge = base64UrlEncode(new Uint8Array(hashBuffer))\n\n  return { verifier, challenge }\n}\n","/**\n * xAI Grok OAuth flow (SuperGrok / X Premium+).\n *\n * xAI is **not** built into pi-ai, so — like Cursor — we implement the flow\n * here and register it with pi-ai's OAuth registry (`registerXaiOAuthProvider`)\n * so `getOAuthApiKey('xai-oauth', …)` resolves to it during lazy token refresh.\n *\n * Auth shape: OAuth 2.0 + PKCE with a loopback callback server, against xAI's\n * OIDC issuer (`https://auth.x.ai`). Differs from the Anthropic / Codex flows\n * (which use the shared `startCallbackServer`) on three points, so it gets its\n * own login impl rather than reusing that primitive:\n *\n *   1. The `redirect_uri` must be `http://127.0.0.1:56121/callback` verbatim\n *      (xAI matches the registered loopback IP, not `localhost`).\n *   2. Endpoints come from OIDC discovery, not hard-coded constants.\n *   3. Token exchange + refresh are `application/x-www-form-urlencoded`\n *      (the Anthropic flow posts JSON).\n *\n * The callback page still routes through {@link OAuthCallbackPageRenderer} so\n * the post-redirect HTML matches the rest of zidane's themed flows.\n *\n * Flow + constants adapted from the public reference implementations\n * (`stnly/pi-grok`, `BlockedPath/pi-xai-oauth`) and the Hermes Agent docs.\n * xAI's OAuth surface is unofficial/undocumented — re-verify the client id,\n * scopes, and callback port if login starts failing.\n */\n\nimport type {\n  OAuthCredentials,\n  OAuthLoginCallbacks,\n} from '@earendil-works/pi-ai/oauth'\nimport type { IncomingMessage, ServerResponse } from 'node:http'\nimport type { OAuthProviderInterface } from '../../providers/oauth-registry'\nimport type { OAuthCallbackPageRenderer } from './render'\nimport { createServer } from 'node:http'\nimport { generatePkce } from './pkce'\n\n/** pi-ai / zidane OAuth provider id. Also the credentials-file key. */\nexport const XAI_OAUTH_PROVIDER_ID = 'xai-oauth'\n\nconst DEFAULT_BASE_URL = 'https://api.x.ai/v1'\nconst ISSUER = 'https://auth.x.ai'\nconst DISCOVERY_URL = `${ISSUER}/.well-known/openid-configuration`\n/** Public client id used by the Grok CLI OAuth surface. */\nconst DEFAULT_CLIENT_ID = 'b1a00492-073a-47ea-816f-4c329264a828'\nconst DEFAULT_SCOPE = 'openid profile email offline_access grok-cli:access api:access'\n/** xAI matches the registered loopback IP exactly — `localhost` is rejected. */\nconst DEFAULT_CALLBACK_HOST = '127.0.0.1'\nconst DEFAULT_CALLBACK_PORT = 56121\nconst CALLBACK_PATH = '/callback'\nconst PROVIDER_NAME = 'xAI Grok'\n/** Refresh slightly early so requests don't race expiry. */\nconst REFRESH_SKEW_MS = 120_000\nconst CALLBACK_TIMEOUT_MS = 180_000\n\nfunction xaiOAuthClientId(): string {\n  return process.env.PI_XAI_OAUTH_CLIENT_ID || DEFAULT_CLIENT_ID\n}\n\nfunction xaiOAuthScope(): string {\n  return process.env.PI_XAI_OAUTH_SCOPE || DEFAULT_SCOPE\n}\n\nfunction xaiOAuthCallbackHost(): string {\n  return process.env.PI_XAI_OAUTH_CALLBACK_HOST || DEFAULT_CALLBACK_HOST\n}\n\nfunction xaiOAuthCallbackPort(): number {\n  const parsed = Number.parseInt(process.env.PI_XAI_OAUTH_CALLBACK_PORT || String(DEFAULT_CALLBACK_PORT), 10)\n  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_CALLBACK_PORT\n}\n\n/** Resolve the xAI API base URL (env override → default). */\nexport function xaiBaseUrl(): string {\n  return (process.env.PI_XAI_BASE_URL || process.env.XAI_BASE_URL || DEFAULT_BASE_URL)\n    .replace(/\\/+$/, '')\n}\n\ninterface XaiDiscovery {\n  authorization_endpoint: string\n  token_endpoint: string\n}\n\n/**\n * xAI OAuth credentials. Extends the base `{ access, refresh, expires }` with\n * the resolved `token_endpoint` so refresh doesn't need a second discovery\n * round-trip, plus the cached discovery doc for validation.\n */\nexport interface XaiOAuthCredentials extends OAuthCredentials {\n  tokenEndpoint?: string\n  discovery?: XaiDiscovery\n}\n\nfunction base64Url(bytes: Uint8Array): string {\n  let binary = ''\n  for (const b of bytes)\n    binary += String.fromCharCode(b)\n  return btoa(binary).replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '')\n}\n\nfunction randomToken(byteLength = 16): string {\n  return base64Url(crypto.getRandomValues(new Uint8Array(byteLength)))\n}\n\n/**\n * Refuse any OIDC endpoint that isn't HTTPS on an xAI origin.\n *\n * The discovery doc is cached long-term in `credentials.json`. A single MITM\n * during initial login could otherwise pin a malicious `token_endpoint` that\n * receives every subsequent refresh token. Validating scheme + host keeps the\n * endpoint on `x.ai` / `*.x.ai`.\n */\nfunction validateEndpoint(value: string, field: string): string {\n  let url: URL\n  try {\n    url = new URL(value)\n  }\n  catch {\n    throw new Error(`xAI OAuth discovery returned an invalid ${field}: ${value}`)\n  }\n  if (url.protocol !== 'https:')\n    throw new Error(`xAI OAuth ${field} must use HTTPS: ${value}`)\n  const host = url.hostname.toLowerCase()\n  if (host !== 'x.ai' && !host.endsWith('.x.ai'))\n    throw new Error(`Refusing non-xAI OAuth ${field}: ${value}`)\n  return url.toString()\n}\n\nasync function discover(): Promise<XaiDiscovery> {\n  let response: Response\n  try {\n    response = await fetch(DISCOVERY_URL, {\n      headers: { Accept: 'application/json' },\n      signal: AbortSignal.timeout(15_000),\n    })\n  }\n  catch (cause) {\n    throw new Error(`xAI OIDC discovery failed: ${cause instanceof Error ? cause.message : String(cause)}`)\n  }\n  if (!response.ok)\n    throw new Error(`xAI OIDC discovery returned ${response.status}`)\n\n  const payload = await response.json() as Record<string, unknown>\n  return {\n    authorization_endpoint: validateEndpoint(String(payload.authorization_endpoint ?? ''), 'authorization_endpoint'),\n    token_endpoint: validateEndpoint(String(payload.token_endpoint ?? ''), 'token_endpoint'),\n  }\n}\n\ninterface CallbackResult {\n  code?: string\n  state?: string\n  error?: string\n  errorDescription?: string\n}\n\ninterface XaiCallbackServer {\n  redirectUri: string\n  waitForCallback: (timeoutMs: number) => Promise<CallbackResult>\n  close: () => void\n}\n\n/**\n * Start the loopback callback server on `127.0.0.1:56121`. Falls back to an\n * OS-assigned port if 56121 is taken — xAI accepts any loopback port as long\n * as the `redirect_uri` we send on the authorize URL matches the listener.\n */\nasync function startXaiCallbackServer(renderPage: OAuthCallbackPageRenderer): Promise<XaiCallbackServer> {\n  const callbackHost = xaiOAuthCallbackHost()\n  const callbackPort = xaiOAuthCallbackPort()\n  let settle: ((value: CallbackResult) => void) | undefined\n  let settled = false\n  const callbackPromise = new Promise<CallbackResult>((resolve) => {\n    settle = (value) => {\n      if (settled)\n        return\n      settled = true\n      resolve(value)\n    }\n  })\n\n  const server = createServer((req: IncomingMessage, res: ServerResponse) => {\n    try {\n      // accounts.x.ai may issue a CORS preflight against the loopback listener.\n      const origin = req.headers.origin\n      if (origin === 'https://accounts.x.ai' || origin === 'https://auth.x.ai') {\n        res.setHeader('Access-Control-Allow-Origin', origin)\n        res.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS')\n        res.setHeader('Access-Control-Allow-Headers', 'Content-Type')\n        res.setHeader('Access-Control-Allow-Private-Network', 'true')\n        res.setHeader('Vary', 'Origin')\n      }\n      if (req.method === 'OPTIONS') {\n        res.statusCode = 204\n        res.end()\n        return\n      }\n\n      const url = new URL(req.url ?? '/', `http://${callbackHost}`)\n      if (url.pathname !== CALLBACK_PATH) {\n        res.statusCode = 404\n        res.end('Not found')\n        return\n      }\n\n      const result: CallbackResult = {\n        code: url.searchParams.get('code') ?? undefined,\n        state: url.searchParams.get('state') ?? undefined,\n        error: url.searchParams.get('error') ?? undefined,\n        errorDescription: url.searchParams.get('error_description') ?? undefined,\n      }\n\n      res.statusCode = result.error ? 400 : 200\n      res.setHeader('Content-Type', 'text/html; charset=utf-8')\n      res.end(renderPage(result.error\n        ? {\n            kind: 'error',\n            provider: PROVIDER_NAME,\n            message: `${PROVIDER_NAME} authentication did not complete.`,\n            details: result.errorDescription ?? result.error,\n          }\n        : {\n            kind: 'success',\n            provider: PROVIDER_NAME,\n            message: 'xAI authentication completed. You can close this window.',\n          }))\n      settle?.(result)\n    }\n    catch {\n      res.statusCode = 500\n      res.end('Internal error')\n    }\n  })\n\n  const listen = (port: number) => new Promise<number>((resolve, reject) => {\n    server.once('error', reject)\n    server.listen(port, callbackHost, () => {\n      server.removeListener('error', reject)\n      const addr = server.address()\n      resolve(typeof addr === 'object' && addr ? addr.port : port)\n    })\n  })\n\n  let actualPort: number\n  try {\n    actualPort = await listen(callbackPort)\n  }\n  catch {\n    actualPort = await listen(0)\n  }\n\n  return {\n    redirectUri: `http://${callbackHost}:${actualPort}${CALLBACK_PATH}`,\n    waitForCallback: timeoutMs => Promise.race([\n      callbackPromise,\n      new Promise<CallbackResult>(resolve =>\n        setTimeout(\n          resolve,\n          timeoutMs,\n          { error: 'timeout', errorDescription: 'Timed out waiting for the xAI OAuth callback.' },\n        )),\n    ]),\n    close: () => {\n      try { server.close() }\n      catch { /* already closed */ }\n    },\n  }\n}\n\nfunction expiryFromPayload(payload: Record<string, unknown>): number {\n  const expiresIn = typeof payload.expires_in === 'number'\n    ? payload.expires_in\n    : Number(payload.expires_in ?? 3600)\n  return Date.now() + expiresIn * 1000 - REFRESH_SKEW_MS\n}\n\nasync function exchangeCode(\n  tokenEndpoint: string,\n  code: string,\n  redirectUri: string,\n  verifier: string,\n  discovery: XaiDiscovery,\n): Promise<XaiOAuthCredentials> {\n  const clientId = xaiOAuthClientId()\n  const response = await fetch(tokenEndpoint, {\n    method: 'POST',\n    headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'Accept': 'application/json' },\n    body: new URLSearchParams({\n      grant_type: 'authorization_code',\n      client_id: clientId,\n      code,\n      redirect_uri: redirectUri,\n      code_verifier: verifier,\n    }),\n    signal: AbortSignal.timeout(30_000),\n  })\n  if (!response.ok)\n    throw new Error(`xAI token exchange failed: ${response.status} ${await response.text().catch(() => '')}`)\n\n  const payload = await response.json() as Record<string, unknown>\n  const access = String(payload.access_token ?? '')\n  const refresh = String(payload.refresh_token ?? '')\n  if (!access)\n    throw new Error('xAI token exchange did not return an access_token.')\n  if (!refresh)\n    throw new Error('xAI token exchange did not return a refresh_token.')\n\n  return { access, refresh, expires: expiryFromPayload(payload), tokenEndpoint, discovery }\n}\n\nexport async function loginXai(\n  renderPage: OAuthCallbackPageRenderer,\n  callbacks: OAuthLoginCallbacks,\n): Promise<XaiOAuthCredentials> {\n  const discovery = await discover()\n  const { verifier, challenge } = await generatePkce()\n  const state = randomToken()\n  const nonce = randomToken()\n  const server = await startXaiCallbackServer(renderPage)\n\n  try {\n    const authUrl = new URL(discovery.authorization_endpoint)\n    authUrl.searchParams.set('response_type', 'code')\n    authUrl.searchParams.set('client_id', xaiOAuthClientId())\n    authUrl.searchParams.set('redirect_uri', server.redirectUri)\n    authUrl.searchParams.set('scope', xaiOAuthScope())\n    authUrl.searchParams.set('code_challenge', challenge)\n    authUrl.searchParams.set('code_challenge_method', 'S256')\n    authUrl.searchParams.set('state', state)\n    authUrl.searchParams.set('nonce', nonce)\n    // Opt into xAI's generic OAuth plan tier (SuperGrok / X Premium+).\n    authUrl.searchParams.set('plan', 'generic')\n    authUrl.searchParams.set('referrer', 'zidane')\n\n    callbacks.onAuth({\n      url: authUrl.toString(),\n      instructions: `Sign in to xAI and approve access. If the browser is on another machine, the callback listener is ${server.redirectUri}.`,\n    })\n\n    const result = await server.waitForCallback(CALLBACK_TIMEOUT_MS)\n    if (result.error)\n      throw new Error(result.errorDescription ?? result.error)\n    if (result.state !== state)\n      throw new Error('xAI OAuth state mismatch — possible CSRF. Please retry.')\n    if (!result.code)\n      throw new Error('xAI OAuth callback did not include an authorization code.')\n\n    callbacks.onProgress?.('Exchanging authorization code for tokens...')\n    return await exchangeCode(discovery.token_endpoint, result.code, server.redirectUri, verifier, discovery)\n  }\n  finally {\n    server.close()\n  }\n}\n\nexport async function refreshXaiToken(credentials: OAuthCredentials): Promise<XaiOAuthCredentials> {\n  const xai = credentials as XaiOAuthCredentials\n  const clientId = xaiOAuthClientId()\n  if (!credentials.refresh)\n    throw new Error('xAI credentials are missing a refresh token — re-login required.')\n\n  const tokenEndpoint = xai.tokenEndpoint\n    ?? xai.discovery?.token_endpoint\n    ?? (await discover()).token_endpoint\n  validateEndpoint(tokenEndpoint, 'token_endpoint')\n\n  const response = await fetch(tokenEndpoint, {\n    method: 'POST',\n    headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'Accept': 'application/json' },\n    body: new URLSearchParams({\n      grant_type: 'refresh_token',\n      client_id: clientId,\n      refresh_token: credentials.refresh,\n    }),\n    signal: AbortSignal.timeout(30_000),\n  })\n  if (!response.ok)\n    throw new Error(`xAI token refresh failed: ${response.status} ${await response.text().catch(() => '')}`)\n\n  const payload = await response.json() as Record<string, unknown>\n  const access = String(payload.access_token ?? '')\n  if (!access)\n    throw new Error('xAI token refresh did not return an access_token.')\n\n  return {\n    ...xai,\n    access,\n    // xAI may omit a rotated refresh token — keep the existing one.\n    refresh: String(payload.refresh_token ?? credentials.refresh),\n    expires: expiryFromPayload(payload),\n    tokenEndpoint,\n  }\n}\n\n/**\n * Build an xAI `OAuthProviderInterface`. Shape matches Anthropic / Codex /\n * Cursor so it drops into `BUILTIN_PROVIDERS` and `src/auth.ts` unchanged.\n *\n * `usesCallbackServer: true` — the loopback flow has a real callback server,\n * so the TUI doesn't need to prompt for a manual code paste.\n */\nexport function createXaiOAuthProvider(renderPage: OAuthCallbackPageRenderer): OAuthProviderInterface {\n  return {\n    id: XAI_OAUTH_PROVIDER_ID,\n    name: 'xAI Grok (SuperGrok / X Premium+)',\n    usesCallbackServer: true,\n    login: callbacks => loginXai(renderPage, callbacks),\n    refreshToken: refreshXaiToken,\n    getApiKey: credentials => credentials.access,\n  }\n}\n","import type { Provider, ProviderCapabilities, StreamCallbacks, StreamOptions, TurnResult } from '.'\nimport type { OAuthParams } from './oauth'\nimport { XAI_OAUTH_PROVIDER_ID, xaiBaseUrl } from '../chat/oauth-page/xai'\nimport { extractRuntimeCredentials, isOAuthAccessToken, resolveOAuthApiKey } from './oauth'\nimport { openaiCompat } from './openai-compat'\n\nconst DEFAULT_MODEL = 'grok-4.3'\n\n/**\n * xAI Grok provider — supports both a static API key (`XAI_API_KEY`) and the\n * SuperGrok / X Premium+ OAuth subscription.\n *\n * Both auth modes hit the same OpenAI-compatible endpoint (`https://api.x.ai/v1`),\n * so the wire handling is entirely {@link openaiCompat}. The only difference is\n * the bearer:\n *\n *   - **API key**: `XAI_API_KEY` (or `params.apiKey`) → used verbatim.\n *   - **OAuth**:   no static key → {@link resolveOAuthApiKey} resolves + lazily\n *     refreshes the stored `xai-oauth` token on every turn.\n *\n * `resolveOAuthApiKey` unifies the two: a real API key in `XAI_API_KEY` is\n * returned as-is, while an OAuth access token (or no env value at all) falls\n * through to the refreshable stored credentials. So this single factory serves\n * both paths without branching at construction time.\n */\nexport interface XaiParams extends OAuthParams {\n  defaultModel?: string\n  /**\n   * Provider capability flags. Grok models are vision-capable; default\n   * `{ vision: true, imageInToolResult: false }`. Override for text-only\n   * deployments.\n   */\n  capabilities?: ProviderCapabilities\n  /** Extra HTTP headers sent on every request. */\n  extraHeaders?: Record<string, string>\n}\n\nexport function xai(params?: XaiParams): Provider {\n  const defaultModel = params?.defaultModel || DEFAULT_MODEL\n  const baseURL = xaiBaseUrl()\n  const capabilities: ProviderCapabilities = params?.capabilities ?? {\n    vision: true,\n    imageInToolResult: false,\n  }\n  const baseCredentials = extractRuntimeCredentials(params)\n  let runtimeCredentials = baseCredentials\n\n  // Factory-time snapshot for the static `meta.isOAuth` display flag only (the\n  // terminal header's `oauth`/`key` badge). The real bearer resolves per turn\n  // in `stream`, so this is best-effort, mirroring anthropic's pattern. It's\n  // OAuth unless a genuine static API key is present: a `xai-…` key → key mode;\n  // runtime OAuth creds, a JWT access token, or no static key (stored creds\n  // used) → oauth mode.\n  const staticKey = params?.apiKey ?? process.env.XAI_API_KEY\n  const isOAuth = baseCredentials !== undefined || !staticKey || isOAuthAccessToken(staticKey)\n\n  /**\n   * Build the openai-compat delegate for a resolved bearer. Cheap — the factory\n   * only wires closures — so we re-create it per turn with the freshly resolved\n   * (possibly refreshed) OAuth token rather than baking a stale key in once.\n   */\n  function delegateFor(apiKey: string): Provider {\n    return openaiCompat({\n      name: 'xai',\n      apiKey,\n      baseURL,\n      defaultModel,\n      capabilities,\n      extraHeaders: params?.extraHeaders,\n    })\n  }\n\n  // A delegate built with a placeholder key supplies the non-stream methods\n  // (formatTools, userMessage, message builders, classifyError). Only `stream`\n  // resolves the real bearer, so the placeholder never reaches the wire.\n  const skeleton = delegateFor('placeholder-resolved-at-stream')\n\n  return {\n    ...skeleton,\n    name: 'xai',\n    // Reuse the delegate's normalized capability flags (openaiCompat fills the\n    // audio/video/documents defaults) so the advertised shape matches the wire.\n    meta: { ...skeleton.meta, defaultModel, isOAuth },\n\n    async stream(options: StreamOptions, callbacks: StreamCallbacks): Promise<TurnResult> {\n      const apiKey = await resolveOAuthApiKey(\n        {\n          provider: 'xai',\n          providerId: XAI_OAUTH_PROVIDER_ID,\n          params: runtimeCredentials ? { ...params, ...runtimeCredentials } : params,\n          envKey: 'XAI_API_KEY',\n          missingError: 'No xAI credentials found. Set XAI_API_KEY or run `bun run auth --xai` first.',\n          refreshError: reason => `xAI OAuth token refresh failed. Run \\`bun run auth --xai\\` again. ${reason}`,\n        },\n        {\n          ...callbacks,\n          async onOAuthRefresh(ctx) {\n            // Keep param-sourced credentials current so a long-lived provider\n            // instance reuses the rotated token instead of re-refreshing.\n            if (ctx.source === 'params') {\n              runtimeCredentials = {\n                access: ctx.credentials.access,\n                refresh: ctx.credentials.refresh,\n                expires: ctx.credentials.expires,\n              }\n            }\n            await callbacks.onOAuthRefresh?.(ctx)\n          },\n        },\n      )\n\n      return delegateFor(apiKey).stream(options, callbacks)\n    },\n  }\n}\n"],"mappings":"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"}

package/docs/PLUGINS.md

@@ -0,0 +1,340 @@
+# Agent Plugins
+
+Support for [Agent Plugins](https://agent-plugins.org) 1.0.0 — an open, vendor-neutral package format for reusable agent components. A plugin is a directory with a manifest and its components at fixed locations; any conformant client can load it.
+
+```
+my-plugin/
+├── plugin.json      manifest (required)
+├── skills/          one directory per Agent Skill
+│   └── deploy/
+│       └── SKILL.md
+└── mcp.json         MCP server configuration
+```
+
+```ts
+import { loadAgentPlugin } from 'zidane/plugins'
+
+const plugin = await loadAgentPlugin('./my-plugin')
+if (plugin.ok) {
+  console.log(plugin.manifest.name, plugin.skills.length, plugin.mcpServers.length)
+}
+```
+
+Agent Plugins deliberately does **not** redefine either component format — skills are Agent Skills, MCP config is MCP config. So `zidane/plugins` owns only the packaging contract and hands back plain `SkillConfig[]` / `McpServerConfig[]` that every other zidane surface already consumes.
+
+## Why a separate loader
+
+zidane already reads both component types, but both existing readers are deliberately *lenient*: `discoverSkills` recurses into nested category directories, and `normalizeMcpServers` infers a transport from the presence of `command` / `url` and accepts `httpUrl` / `sseUrl` / `type: "http"` aliases. That leniency is correct for a file the user wrote, and wrong for a third-party package — guessing on behalf of a stranger's `mcp.json` is how you spawn a command the author never wrote.
+
+`zidane/plugins` is the strict layer: closed schemas, immediate-children-only discovery, and a filesystem boundary. It never loosens the existing readers; it wraps them.
+
+## Discovery
+
+Plugins are found in four locations, in precedence order — the same project/user pair every other zidane discovery surface uses:
+
+1. `{project}/.agents/plugins/`
+2. `{project}/.zidane/plugins/`
+3. `~/.agents/plugins/`
+4. `~/.zidane/plugins/`
+
+Each **immediate child directory** is one plugin. Nothing is searched below that, and a child with no `plugin.json` is silently ignored — dropping a README next to your plugins is not an error.
+
+`.agents/plugins/` is the portable location: Agent Plugins is vendor-neutral, so there is no foreign-agent or Ruler import variant the way there is for skills and MCP servers.
+
+Identity is the **manifest** name, not the directory name. Two directories called `tools/` shipping different plugins are two plugins; the same plugin vendored at two scopes is one, and the project copy wins.
+
+Discovered plugins are enabled by default and gated by `enabledPlugins` in settings. A plugin that fails to load still appears — as a read-only row explaining why — rather than vanishing.
+
+### Extra roots for development
+
+`ZIDANE_PLUGIN_DIRS` adds scan roots, mirroring `ZIDANE_EXTENSION_DIRS`:
+
+```sh
+ZIDANE_PLUGIN_DIRS=/repo/plugins zidane
+```
+
+Each entry is a **root** whose immediate children are plugins (`<root>/<name>/plugin.json`), not a single plugin directory. Multiple roots use the platform path delimiter.
+
+This exists because all four default roots are dot-directories and `.zidane/` is gitignored — so a repo has nowhere *tracked* to keep example or first-party plugins. Extra roots are appended **after** the four defaults and scoped `project`, so a real project or user plugin always wins a name collision against a dev root.
+
+This repo uses it to dogfood both load paths in `npm run tui`:
+
+| Plugin | Route | Origin shown |
+| --- | --- | --- |
+| `plugins/hello-plugin` | disk, via `ZIDANE_PLUGIN_DIRS=../plugins` | `[project: plugins/hello-plugin]` |
+| `extensions/plugin-host/vendor/vendored-plugin` | `ctx.loadAgentPlugin` | `[via extension: plugin-host]` |
+
+Their skills (`plugin-smoke-test`, `vendored-smoke-test`) double as the manual verification scripts for plugin loading.
+
+### Project-scope trust
+
+A project plugin's stdio MCP servers run, the same as those in a project `.zidane/mcps.json` beside them. There is no extra gate, deliberately: holding plugins to a stricter rule than the MCP config sitting next to them would be inconsistent rather than safer, since both are things you or your repo placed on purpose.
+
+Stated plainly, the exposure that comes with that: a cloned repo carrying `.agents/plugins/evil/mcp.json` gets its stdio command spawned on the first agent bootstrap. That is today's behavior for project `mcps.json` too. If you don't want it, disable the plugin in settings, or set `enabledPlugins` to an allowlist that omits it.
+
+(The `dropStdio` carve-out in `chat/mcps-discovery.ts` is narrower than it looks — it applies to **Ruler** files specifically, because `importRulerConfigs` defaults on and would otherwise execute a repo-committed foreign config unprompted.)
+
+## Loading a plugin
+
+### From an extension
+
+The primary entry point. One call registers everything the plugin ships:
+
+```ts
+import { defineExtension } from 'zidane'
+
+export default defineExtension({
+  name: 'my-toolkit',
+  capabilities: ['plugins'],
+  async setup(ctx) {
+    const plugin = await ctx.loadAgentPlugin('./vendor/deploy-tools')
+    if (!plugin.ok)
+      ctx.logger.warn('deploy-tools failed to load')
+  },
+})
+```
+
+`dir` may be absolute or relative to the extension's own directory, so an extension can vendor plugins inside itself. Inline extensions (no directory) resolve against `ctx.paths.cwd`.
+
+Options, when you need them:
+
+```ts
+await ctx.loadAgentPlugin({
+  dir: './vendor/deploy-tools',
+  skills: true,        // register skills/          (default true)
+  mcp: true,           // register mcp.json servers (default true)
+  namePrefix: 'acme',  // rename to `acme-<name>`   (default none)
+})
+```
+
+Three things worth knowing:
+
+- **It never throws for plugin-level problems.** A malformed manifest, an escaping symlink or an invalid skill comes back as `ok: false` / diagnostics and is logged to the extension's logger. One bad package cannot fail your `setup()`.
+- **Await it inside `setup()`.** Registration closes when `setup()` resolves. A load still in flight at that point is dropped with a warning rather than mutating an already-published registry.
+- **Components inherit the extension's scope.** A project-scoped extension's plugin is project-scoped, exactly as `ctx.registerSkill` behaves.
+
+### From the SDK
+
+```ts
+import { loadAgentPlugin } from 'zidane/plugins'
+
+const plugin = await loadAgentPlugin(dir, {
+  source: 'user',      // scope stamped on discovered skills (default 'project')
+  skills: true,        // discover skills/          (default true)
+  mcp: true,           // discover mcp.json         (default true)
+  namePrefix: 'acme',  // rename to `acme-<name>`   (default none)
+  dataRoot: '/custom/parent',   // ${PLUGIN_DATA} parent; name is appended
+  dataDir: '/exact/dir',        // or pin one plugin's directory outright
+})
+```
+
+## `plugin.json`
+
+The manifest is a **closed** schema, validated locally — the spec forbids retrieving a schema while loading. `$schema` and `name` are required; everything else is optional metadata.
+
+```json
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "deploy-tools",
+  "version": "1.2.0",
+  "description": "Deployment skills and a release MCP server",
+  "author": { "name": "Acme", "email": "dev@acme.example" },
+  "homepage": "https://acme.example",
+  "repository": "https://github.com/acme/deploy-tools",
+  "license": "MIT",
+  "keywords": ["deploy", "release"],
+  "extensions": { "dev.example": { "anything": true } }
+}
+```
+
+`name` is 1–64 characters: lowercase letters, digits, `-` and `.`, alphanumeric at both ends, no `--` or `..`.
+
+Metadata strings are type-checked only. A `license` that isn't valid SPDX, or a `homepage` that isn't a valid URL, does **not** reject the plugin — the spec keeps identity portable and leaves semantic policing to registries.
+
+Exactly two violations are non-fatal, per spec:
+
+| Violation | Behavior |
+|---|---|
+| Unknown top-level field | Reported, ignored, loading continues |
+| `extensions` is not an object | Reported, ignored, loading continues |
+
+Every other schema violation **rejects the whole plugin**, and rejection happens *before* component discovery — a plugin with a broken manifest never has its skills read or its servers spawned.
+
+`extensions` member *values* are never validated. The spec says to ignore namespaces the client does not implement without inspecting them, so a client validates only its own namespace at the point of use.
+
+## `skills/`
+
+Each immediate child directory containing a `SKILL.md` that resolves to a regular file is one skill. The format is plain [Agent Skills](./SKILL.md) — same parser as `~/.agents/skills`.
+
+Nested descendants are **not** searched. `skills/category/nested/SKILL.md` is invisible, even though zidane's own skill discovery would find it. Bundling a non-skill directory under `skills/` is legal and silently ignored.
+
+Every discovered skill is stamped with `metadata['zidane.plugin']` naming the plugin that shipped it.
+
+## `mcp.json`
+
+```json
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "release": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["release-mcp", "--root", "${PLUGIN_ROOT}"],
+      "env": { "CACHE_DIR": "${PLUGIN_DATA}/cache" },
+      "cwd": "${PLUGIN_ROOT}"
+    },
+    "registry": {
+      "type": "streamable-http",
+      "url": "https://mcp.acme.example/v1",
+      "headers": { "X-Client": "zidane" }
+    }
+  }
+}
+```
+
+`$schema` must declare the **same** Agent Plugins version as `plugin.json`.
+
+`type` is required and never inferred. Each transport has a closed key set:
+
+| `type` | Permitted keys |
+|---|---|
+| `stdio` | `type`, `command`, `args`, `env`, `cwd` |
+| `streamable-http` | `type`, `url`, `headers` |
+| `sse` | `type`, `url`, `headers` |
+
+An unknown field, an unknown transport, or a missing required field invalidates **that one entry**; its siblings still load. A malformed document, a version mismatch, or an unknown top-level field disables the MCP component for that plugin only — its skills are unaffected.
+
+### Plugin variables
+
+Two placeholders, and only two:
+
+| Variable | Value |
+|---|---|
+| `${PLUGIN_ROOT}` | Symlink-resolved plugin root |
+| `${PLUGIN_DATA}` | Dedicated writable directory, persistent across plugin updates |
+
+They expand in `args`, `env` values and `cwd` — **nowhere else**. In `command`, `url` and `headers` the text stays literal, so a `${PLUGIN_ROOT}` in `command` is rejected rather than handed to the OS verbatim.
+
+Expansion is single-pass and non-recursive: an expanded value containing `${PLUGIN_DATA}` does not expand again. Unknown `${...}` text is left alone — zidane's wider `${VAR}` / `${VAR:-default}` / `${env:VAR}` handling does **not** apply to plugin configs (they carry `preExpanded`, which suppresses it). That is deliberate: it keeps an ambient `PLUGIN_ROOT` environment variable from reaching fields the spec says must stay literal.
+
+Both variables are always present in a stdio server's `env`, written last, and a plugin that tries to set either itself has that entry rejected.
+
+`${PLUGIN_DATA}` defaults to `<dataDir>/plugin-data/<plugin-name>/` from `resolveStorageDirs` (honouring `ZIDANE_STORAGE_DIR` and XDG). It sits **outside** the plugin root so a plugin update — which replaces the package tree — cannot wipe it. Extension-loaded plugins get it inside the loading extension's storage root instead, so two extensions loading the same plugin don't share state.
+
+The directory is created at **spawn** time, not load time. Loading is not consent: a host has to load every plugin it finds just to learn its name (identity lives in the manifest, so it can't filter first), and `enabledPlugins` only applies afterwards — creating on load left a directory behind for every plugin the user had switched off, on every discovery pass. A `cwd` inside `${PLUGIN_DATA}` is created along with it, since spawning into a non-existent directory fails with a bare `ENOENT`; a `cwd` under `${PLUGIN_ROOT}` is not, because that path is package content the author was supposed to ship.
+
+Note the honest consequence: `ZIDANE_PREFIX` is *not* read by `resolveStorageDirs` — callers thread `prefix` explicitly, which disk discovery does.
+
+### stdio commands
+
+`command` is exactly one executable token — no shell, no argv splitting:
+
+- **Bare name** (`uvx`, `node`) → PATH lookup by the OS.
+- **`./`-relative** → resolved inside the plugin root, and it must exist.
+- **Absolute** → rejected. It is neither a PATH lookup nor a package file.
+
+`cwd` defaults to the plugin root and must stay inside the root or the data directory, checked both lexically and after symlink resolution.
+
+### Remote servers
+
+- HTTPS required unless the host is loopback.
+- No userinfo credentials, no fragment.
+- Configured headers are pinned to the URL's origin: redirects are followed manually and credentials are dropped the moment a hop leaves that origin. `authorization` is always protected, including the header the SDK's OAuth provider injects rather than reading from config.
+- A redirect to non-loopback cleartext is refused outright, not merely stripped.
+
+## The package boundary
+
+Every package file must stay inside the symlink-resolved plugin root. Lexical checks are not enough — a `skills` symlink pointing at `~/.ssh` passes every one of them — so each path is resolved through `realpath` and re-tested, and required filesystem kinds are asserted.
+
+Failures are isolated at the narrowest level that still holds:
+
+| Problem | Consequence |
+|---|---|
+| Invalid manifest, or manifest outside the root | Whole plugin rejected, no components discovered |
+| `skills/` or `mcp.json` invalid, wrong kind, or outside the root | That component type disabled; the other still loads |
+| One skill invalid, unreadable, or outside the root | That skill skipped; siblings load |
+| One `mcp.json` entry invalid | That server skipped; siblings load |
+| Any other escaping path | Access denied for that path |
+
+A **missing** fixed location is not an error. `components.skills === 'absent'` means the plugin ships no skills; `'invalid'` means they were rejected.
+
+## Results and diagnostics
+
+```ts
+interface LoadedPlugin {
+  ok: boolean                    // false ⇒ plugin rejected, components never discovered
+  dir: string                    // root as requested, made absolute
+  root: string                   // symlink-resolved root — the boundary
+  manifest?: PluginManifest      // absent iff !ok
+  skills: SkillConfig[]
+  mcpServers: McpServerConfig[]
+  components: {
+    skills: 'absent' | 'loaded' | 'invalid' | 'unsupported'
+    mcp: 'absent' | 'loaded' | 'invalid' | 'unsupported'
+  }
+  diagnostics: PluginDiagnostic[]
+}
+```
+
+Each diagnostic carries a `severity`, a stable machine-readable `code` (`manifest-unknown-field`, `skill-escapes-root`, `mcp-entry-transport-invalid`, …), a message, and optionally the `field` or `path` involved. `severity: 'error'` on a plugin that still returned `ok: true` means a narrow boundary fired, not that the plugin failed.
+
+## Naming and collisions
+
+zidane's skill catalog and MCP server names are single flat namespaces, so two plugins each shipping a `deploy` skill or a `github` server would collide. The spec leaves the policy to the client; zidane's default is first-found-wins with a collision diagnostic, plus opt-in `namePrefix` for the cases where you know you're loading several.
+
+Server names are validated in the form they actually take in the tool catalog — `mcp_<server>_<tool>` — which means *after* `namePrefix` is applied, since a bad prefix can invalidate a name the plugin got right.
+
+Collisions are resolved at the merge, not at load, so a plugin's settings row counts what the **package ships** rather than what ended up live. A plugin server whose name matches one in `mcps.json` is dropped (first-wins, `mcps.json` first), and a plugin skill whose name matches an extension's is shadowed. The MCPs and Skills tabs are the authority on what actually loaded; skill collisions emit `name-collision-shadowed`, server collisions are logged under `ZIDANE_DEBUG`. Pass `namePrefix` when loading plugins that might collide.
+
+### The same plugin from both routes
+
+A plugin present *both* on disk and vendored inside an extension is **one** plugin: the disk copy wins, and the extension's copy contributes nothing. One settings row, one checkbox, one set of skills and servers.
+
+This has to hold on the contribution side, not just the display side. If both copies stayed live, that single checkbox would govern two of them, and the skills are the sharp end: both sets reach the catalog, where one shadows the other and earns a `name-collision-shadowed` warning about a collision the user never created.
+
+The MCP half is the same shape but milder — both configs reach the merge, where a first-wins dedupe by name collapses them, so nothing is spawned twice. What's wrong there is that one checkbox nominally governs two records, and which copy survives is decided by merge order rather than by anything the user chose.
+
+Disk wins even when the disk copy is *rejected*, so a broken installed copy doesn't quietly fall back to a vendored one while the row reads `rejected`.
+
+## Settings
+
+Plugins live in the **Extensions & Plugins** tab, interleaved alphabetically with extensions rather than in a separate section. They aren't parallel categories — a plugin can be loaded *by* an extension — so each row carries a kind badge and an origin instead:
+
+```
+[✓] git-flow v2.1.0  ext
+    Git helpers · [project: .zidane/extensions/git-flow]
+[✓] deploy-tools v1.2.0  plugin
+    Deploy skills · [project: .agents/plugins/deploy-tools] · 3 skills, 1 server
+[✓] registry-mcp v0.4.0  plugin
+    Registry access · [via extension: my-toolkit] · 1 server
+✗   broken-thing  plugin
+    rejected: manifest-name-invalid · [user: ~/.agents/plugins/broken-thing]
+```
+
+The kind badge is a filled pill trailing the title line, so names stay left-aligned instead of being pushed right by a fixed-width column. Extensions get the neutral `border` tier because they're the majority — a saturated pill on nearly every row is noise — and plugins get the `model` accent so they stand out of that field.
+
+Both colors derive from `ThemeColors` / `ThemeSurfaces` members every theme must define, rather than from `surfaces.chips` entries: that map is keyed by completion-provider id, and a third-party theme that never opted in would fall back to `chips.default` for both kinds, collapsing the very distinction the badge exists to draw.
+
+Errored extensions and rejected plugins lead the list. A rejected plugin has no checkbox — there is nothing to enable — matching how an errored extension renders.
+
+Searching matches a plugin's name, description and origin, plus the literal word `plugin`: type `plugin` to narrow to plugins, or an extension's name to find the plugins it loaded.
+
+`ctrl+r` on this tab re-scans the plugin directories, so a package you just dropped into `.agents/plugins/` appears without a restart. It refreshes **plugins only** — an extension's `setup()` runs once per process, so extensions genuinely cannot be re-scanned in place, and calling it a generic refresh would over-promise. Extension-loaded plugins likewise only reload with their extension.
+
+Toggling writes `enabledPlugins`, which gates the plugin's skills **and** its MCP servers together — for disk plugins and for extension-loaded ones alike. Extension-loaded plugins need a second filter pass to achieve that (`filterRegistryPlugins`), because their contributions are fanned into the loading extension's own sinks and `enabledExtensions` can only express whole-extension on/off.
+
+Skills from an *enabled* plugin are force-included into `enabledSkills` when you have an allowlist there — enabling the plugin is the consent, and `enabledPlugins` is where you withhold it.
+
+The gate is plugin-level only. A plugin's skills **are** listed in the Skills tab, badged `plugin:<name>`, but they carry no checkbox: the agent build force-includes every enabled plugin's skills, so a per-skill "off" would be persisted, flip the box, and then be overridden on the next build. Rather than ship a control whose off state doesn't hold, the row is read-only and the badge points at the plugin row that owns the switch. Turning off one skill of a plugin means disabling the plugin.
+
+Extension-registered skills work the same way, badged `ext:<name>` and gated by `enabledExtensions`.
+
+Real per-skill control would mean dropping that force-include and seeding contributed skill names into `enabledSkills` at enable time — a persistence change, not a rendering one.
+
+## Conformance
+
+zidane implements Agent Plugins 1.0.0: manifest validation, both component types, both required MCP transports plus legacy HTTP+SSE, plugin variables, and the failure-isolation ladder. Supported versions are listed in `SUPPORTED_AGENT_PLUGINS_VERSIONS`; a plugin targeting anything else is rejected with a diagnostic rather than loaded on a guess.
+
+`test/plugins/conformance.test.ts` maps 1:1 to the [published checklist](https://agent-plugins.org/client-implementers/conformance) — one test per line, same order, same headings. Behavioral depth lives in the sibling suites; that file exists so conformance can be verified item by item instead of inferred from three test files. A checklist line with no test there is a claim nobody checked.
+
+Not yet implemented: installing a plugin from a git/npm spec (`/plugin install`). Drop a package into one of the discovery directories, load it from an extension, or call `loadAgentPlugin` directly.