mixdog 1.2.6 → 1.3.0

package/src/runtime/agent/orchestrator/mcp/oauth-provider.mjs

@@ -1,18 +1,33 @@
 import { normalizeMcpTransportUrl } from './client-config.mjs';
+import { withAccountParams } from './oauth-account.mjs';
 import { loginFailed, reauthenticationRequired } from './oauth-shared.mjs';
 
 /**
  * The SDK's OAuth client provider over one connection's credential `cache`
  * and login `flow` state.
  */
-export function createOAuthProvider({ cache, flow, lifetimeSignal }) {
+export function createOAuthProvider({ cache, flow, lifetimeSignal, client = null, credentialStore = null }) {
   const { creds, ready, update } = cache;
   // The SDK saves only inside a login, which holds the lock and has just
   // adopted the stored entry.
   const save = async (change) => {
     if (!(await update(change))) throw loginFailed();
   };
+  // A pre-registered client (oauth-client.mjs) is the static client
+  // information: nothing is registered, and its secret (the user's lives in
+  // the keychain) goes with the token requests.
+  const staticClient = async () => {
+    const secret = client.secretAccount
+      ? await credentialStore?.getSecretAsync(client.secretAccount)
+      : client.clientSecret;
+    return { client_id: client.clientId, ...(secret ? { client_secret: secret } : {}) };
+  };
   return {
+    /** A pre-registered client: a refresh needs no stored registration. */
+    preRegistered: Boolean(client),
+    // A pre-registered client's provider issues tokens for its own APIs
+    // (Google): no RFC 8707 resource indicator is sent.
+    ...(client ? { validateResourceURL: async () => undefined } : {}),
     get redirectUrl() {
       return creds.redirectUrl;
     },
@@ -23,11 +38,13 @@ export function createOAuthProvider({ cache, flow, lifetimeSignal }) {
         grant_types: ['authorization_code', 'refresh_token'],
         response_types: ['code'],
         token_endpoint_auth_method: 'none',
+        ...(client?.scopes ? { scope: client.scopes.join(' ') } : {}),
       };
     },
     state: () => flow.state,
     clientInformation: async () => {
       await ready();
+      if (client) return staticClient();
       // A connect that cannot open a sign-in never registers a client (the
       // SDK registers one after dropping a rejected registration): the next
       // explicit sign-in registers it.
@@ -46,6 +63,11 @@ export function createOAuthProvider({ cache, flow, lifetimeSignal }) {
       lifetimeSignal.throwIfAborted();
       await save(() => {
         creds.tokens = value;
+        // A browser sign-in may be another account: its identity replaces the
+        // stored one (null when the server named nobody). A refresh keeps it
+        // unless the response names the account again.
+        if (flow.browserOpened) creds.identity = flow.identity ?? null;
+        else if (flow.identity) creds.identity = flow.identity;
       });
     },
     saveCodeVerifier: (value) => {
@@ -56,10 +78,11 @@ export function createOAuthProvider({ cache, flow, lifetimeSignal }) {
       return flow.verifier;
     },
     discoveryState: () => creds.discovery,
-    saveDiscoveryState: (value) =>
-      save(() => {
-        creds.discovery = value;
-      }),
+    // Kept in memory and stored with the login's next write (the client
+    // registration or the tokens), sparing a keychain write of its own.
+    saveDiscoveryState: (value) => {
+      creds.discovery = value;
+    },
     // The SDK invalidates 'all' when the token endpoint rejects the client
     // (invalid_client / unauthorized_client) and 'tokens' when it rejects the
     // grant (invalid_grant). The registration goes in both cases: an
@@ -88,8 +111,24 @@ export function createOAuthProvider({ cache, flow, lifetimeSignal }) {
         !flow.verifier
       )
         throw loginFailed();
+      // A pre-registered client is stored with this login's redirect, as a
+      // registration would be: the exchange and later refreshes (and the
+      // revocation on 연결 해제) read them from the entry.
+      if (client) {
+        const issuedTo = await staticClient();
+        await save(() => {
+          creds.clientInformation = issuedTo;
+        });
+      }
       flow.browserOpened = true;
-      await flow.launchBrowser(target.href);
+      // A pre-registered client asks for its own scopes (the server's list
+      // may name far more) plus its provider's parameters (Google's
+      // access_type=offline, without which no refresh token is issued).
+      if (client?.scopes) target.searchParams.set('scope', client.scopes.join(' '));
+      for (const [key, value] of Object.entries(client?.authParams || {})) target.searchParams.set(key, value);
+      // The explicit sign-in's account mode (mcp-oauth-login.mjs) decides the
+      // provider's documented account-choice parameter, if any.
+      await flow.launchBrowser(withAccountParams(target.href, flow.launchBrowser.accountMode || 'connect').href);
     },
   };
 }

package/src/runtime/agent/orchestrator/mcp/oauth.mjs

@@ -1,4 +1,4 @@
-import { createHash } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import keychain from '../../../../lib/keychain-cjs.cjs';
 import { openInBrowser } from '../../../shared/open-url.mjs';
@@ -12,8 +12,10 @@ import {
   TOKENS_FLAG,
   createCredentialCache,
   credentialFile,
+  readIdentityFile,
   readStoredCredentials,
   withCredentialLock,
+  writeIdentityFile,
   writeRevisionMarker,
 } from './oauth-credentials.mjs';
 import { createLoginFlow } from './oauth-login.mjs';
@@ -55,18 +57,198 @@ export function hasStoredMcpOAuthTokens(url) {
   }
 }
 
+/** Who the stored sign-in of one MCP server URL belongs to, without a keychain
+ *  read: `{ account, workspace, forcedChoice }` (empty strings when the server
+ *  named nobody), or null when signed out. */
+export function storedMcpOAuthIdentity(url) {
+  return readIdentityFile(mcpOAuthAccount(normalizeMcpTransportUrl(url)));
+}
+
+// RFC 7009 revocation of the stored grant, only where the authorization server
+// advertises its revocation endpoint (RFC 8414 metadata): it revokes the token
+// this client was issued, nothing workspace-wide. True when the server
+// confirmed it.
+async function revokeStoredGrant(saved, fetchImpl) {
+  let value;
+  try {
+    value = JSON.parse(saved);
+  } catch {
+    return false;
+  }
+  const endpoint = value?.discovery?.authorizationServerMetadata?.revocation_endpoint;
+  const token = value?.tokens?.refresh_token || value?.tokens?.access_token;
+  const clientId = value?.clientInformation?.client_id;
+  if (typeof endpoint !== 'string' || !/^https:\/\//.test(endpoint) || !token || !clientId) return false;
+  const body = new URLSearchParams({
+    token,
+    token_type_hint: value.tokens.refresh_token ? 'refresh_token' : 'access_token',
+    client_id: clientId,
+  });
+  if (value.clientInformation.client_secret) body.set('client_secret', value.clientInformation.client_secret);
+  try {
+    const response = await fetchImpl(endpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body,
+      redirect: 'error',
+      signal: AbortSignal.timeout(5_000),
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
 /** Log out of one MCP server URL: delete its stored tokens and client
  *  registration and drop them from live connections, which then need an
- *  explicit reconnect to log in again. */
-export async function clearMcpOAuth({ url, credentialStore = keychain }) {
+ *  explicit reconnect to log in again. With `revoke`, the grant is first
+ *  revoked at the authorization server where it documents a revocation
+ *  endpoint. Resolves `{ revoked }`. */
+export async function clearMcpOAuth({ url, credentialStore = keychain, revoke = false, fetchImpl = fetch }) {
   url = normalizeMcpTransportUrl(url);
   const account = mcpOAuthAccount(url);
+  let revoked = false;
   await withCredentialLock(account, async () => {
+    const saved = await readStoredCredentials(credentialStore, account);
+    if (revoke && saved != null) revoked = await revokeStoredGrant(saved, fetchImpl);
     await writeRevisionMarker(account, null);
-    if ((await readStoredCredentials(credentialStore, account)) != null)
-      await credentialStore.deleteSecretAsync(account);
+    if (saved != null) await credentialStore.deleteSecretAsync(account);
+    await writeIdentityFile(account, null);
   });
   scopes.get(credentialStore)?.get(url)?.oauth.clear();
+  return { revoked };
+}
+
+async function storeEntry(account, url, value, credentialStore) {
+  const revision = randomBytes(16).toString('hex');
+  const { tokens, clientInformation, redirectUrl, discovery, identity } = value;
+  await writeRevisionMarker(account, revision, Boolean(tokens));
+  await credentialStore.setSecretAsync(
+    account,
+    JSON.stringify({ url, revision, tokens, clientInformation, redirectUrl, discovery, identity })
+  );
+  await writeIdentityFile(account, value);
+}
+
+/**
+ * 계정 바꾸기 for one MCP server URL, transactionally: a browser sign-in with
+ * the provider's documented account choice that runs beside the stored
+ * sign-in, reusing its client registration and discovery but never its tokens,
+ * and stores nothing. `done` resolves the new sign-in (`{ tokens, identity, … }`)
+ * or rejects (cancel, denial, timeout), leaving the stored sign-in and every
+ * live connection as they were. `answer(pasted)` completes it with a pasted
+ * redirect URL (remote sign-in); `cancel()` aborts it.
+ */
+export function startMcpOAuthSwitch({
+  url,
+  launch,
+  serverName,
+  credentialStore = keychain,
+  fetchImpl = fetch,
+  timeoutMs = MCP_OAUTH_TIMEOUT_MS,
+  oauthClient = null,
+}) {
+  url = normalizeMcpTransportUrl(url);
+  const lifetime = new AbortController();
+  const creds = {
+    tokens: undefined,
+    clientInformation: undefined,
+    redirectUrl: undefined,
+    discovery: undefined,
+    identity: undefined,
+    // Never null: the in-memory entry always exists.
+    observed: 'switch',
+  };
+  // An in-memory entry: a registration made during the switch stays here
+  // until the commit stores it with the tokens.
+  const cache = {
+    creds,
+    held: new Set(),
+    ready: async () => {},
+    adoptStored: async () => {},
+    update: async (change) => {
+      change();
+      return true;
+    },
+    withLock: (fn) => fn(),
+  };
+  const flow = {
+    listener: undefined,
+    state: undefined,
+    verifier: undefined,
+    allowBrowser: false,
+    browserOpened: false,
+    launchBrowser: launch,
+    finishCallback: undefined,
+  };
+  const provider = createOAuthProvider({
+    cache,
+    flow,
+    lifetimeSignal: lifetime.signal,
+    client: oauthClient,
+    credentialStore,
+  });
+  const loginFlow = createLoginFlow({
+    url,
+    cache,
+    flow,
+    provider,
+    lifetimeSignal: lifetime.signal,
+    openBrowser: launch,
+    fetchImpl,
+    timeoutMs,
+  });
+  const done = (async () => {
+    const saved = await readStoredCredentials(credentialStore, mcpOAuthAccount(url));
+    if (saved) {
+      const value = JSON.parse(saved);
+      if (value.url === url) {
+        creds.clientInformation = value.clientInformation;
+        creds.redirectUrl = value.redirectUrl;
+        creds.discovery = value.discovery;
+      }
+    }
+    await loginFlow.login({}, lifetime.signal, true, launch, undefined, serverName);
+    const { tokens, clientInformation, redirectUrl, discovery, identity } = creds;
+    if (!tokens) throw new Error('MCP OAuth login failed, cancelled, or timed out');
+    return { tokens, clientInformation, redirectUrl, discovery, identity: identity ?? null };
+  })();
+  return {
+    done,
+    answer(pasted) {
+      if (!flow.finishCallback || !flow.browserOpened || !flow.state || !creds.redirectUrl) {
+        throw new Error(MCP_OAUTH_CALLBACK_NOT_PENDING);
+      }
+      const { code } = parsePastedMcpOAuthCallback(pasted, { redirectUrl: creds.redirectUrl, state: flow.state });
+      loginFlow.stopListening();
+      loginFlow.answerCallback(code);
+    },
+    cancel() {
+      lifetime.abort();
+      flow.finishCallback?.();
+      loginFlow.closeListener();
+    },
+  };
+}
+
+/** Store the sign-in a switch returned as the URL's sign-in; resolves a
+ *  `rollback()` that restores the previous one (or none). Live connections
+ *  adopt either through the revision marker on their next request. */
+export async function commitMcpOAuthSwitch({ url, signIn, credentialStore = keychain }) {
+  url = normalizeMcpTransportUrl(url);
+  const account = mcpOAuthAccount(url);
+  let previous = null;
+  await withCredentialLock(account, async () => {
+    previous = await readStoredCredentials(credentialStore, account);
+    await storeEntry(account, url, signIn, credentialStore);
+  });
+  return () =>
+    withCredentialLock(account, async () => {
+      if (previous) return storeEntry(account, url, JSON.parse(previous), credentialStore);
+      await writeRevisionMarker(account, null);
+      await credentialStore.deleteSecretAsync(account);
+      await writeIdentityFile(account, null);
+    });
 }
 
 // The keychain is the only durable store. Exact URLs, including query strings,
@@ -166,6 +348,7 @@ function createSharedOAuth({
   openBrowser = openInBrowser,
   fetchImpl = fetch,
   timeoutMs = MCP_OAUTH_TIMEOUT_MS,
+  oauthClient = null,
 }) {
   const lifetime = new AbortController();
   const cache = createCredentialCache({ url, credentialStore, account: mcpOAuthAccount(url) });
@@ -179,7 +362,13 @@ function createSharedOAuth({
     launchBrowser: openBrowser,
     finishCallback: undefined,
   };
-  const provider = createOAuthProvider({ cache, flow, lifetimeSignal: lifetime.signal });
+  const provider = createOAuthProvider({
+    cache,
+    flow,
+    lifetimeSignal: lifetime.signal,
+    client: oauthClient,
+    credentialStore,
+  });
   const { login, stopListening, closeListener, answerCallback } = createLoginFlow({
     url,
     cache,

package/src/runtime/agent/orchestrator/mcp/server-connectors.mjs

@@ -0,0 +1,17 @@
+// Which catalog connector each connected MCP server is (connector-catalog.mjs
+// connectorOfServer), recorded by the client as servers connect, so a tool
+// name alone (`mcp__<server>__<tool>`) finds its catalog defaults at dispatch.
+import { connectorOfServer } from '../../../shared/connector-catalog.mjs';
+
+const byServer = new Map();
+
+export function rememberServerConnector(name, cfg) {
+  const id = connectorOfServer(cfg);
+  if (id) byServer.set(String(name), id);
+  else byServer.delete(String(name));
+}
+
+/** The catalog id of connected server `name`, or ''. */
+export function serverConnector(name) {
+  return byServer.get(String(name)) || '';
+}

package/src/runtime/agent/orchestrator/providers/anthropic-oauth-client-version.mjs

@@ -10,7 +10,7 @@ import { createNpmVersionSource, maxSemver } from './npm-cli-version.mjs';
 // source release just to advance the user-agent version.
 // Claude Opus 5.5 requires 2.1.280 or newer. The release workflow raises this
 // to the published CLI version (scripts/sync-client-version-floors.mjs).
-export const DEFAULT_CLI_VERSION = '2.1.302';
+export const DEFAULT_CLI_VERSION = '2.1.304';
 export const CLAUDE_CLI_NPM_PACKAGE = '@anthropic-ai/claude-code';
 
 const CACHE_SCHEMA_VERSION = 1;

package/src/runtime/agent/orchestrator/providers/anthropic-oauth-credentials.mjs

@@ -209,6 +209,7 @@ export function describeAnthropicOAuthCredentials() {
     return {
       ...oauthCredentialStatus({ hasRefresh, expiresAt, detail, refreshSkewMs: TOKEN_REFRESH_SKEW_MS }),
       ...accountIdentityFields(creds.identity),
+      plan: creds.subscriptionType || null,
     };
   } catch (err) {
     return {

package/src/runtime/agent/orchestrator/providers/antigravity-oauth-login.mjs

@@ -218,7 +218,12 @@ async function provisionProject(context, tierId) {
 }
 
 /** Resolve account eligibility and return the project from a fresh status load. */
-export async function discoverProject(
+export async function discoverProject(accessToken, options = {}) {
+  return (await discoverAccount(accessToken, options)).projectId;
+}
+
+/** Project plus the account's tier id (paid tier first), from the same status load. */
+export async function discoverAccount(
   accessToken,
   { fetchFn = fetch, onProgress = null, signal = null, email = '' } = {}
 ) {
@@ -235,7 +240,8 @@ export async function discoverProject(
   const refreshed = await loadProjectState(context);
   const projectId = extractProjectId(refreshed);
   if (!projectId) throw new Error('[antigravity-oauth] loadCodeAssist did not return a cloudaicompanionProject');
-  return projectId;
+  const tierId = refreshed.paidTier?.id || refreshed.currentTier?.id;
+  return { projectId, tierId: typeof tierId === 'string' ? tierId : '' };
 }
 
 export async function exchangeAuthorizationCode({ code, verifier, fetchFn = fetch, onProgress = null, signal = null }) {
@@ -267,12 +273,13 @@ export async function exchangeAuthorizationCode({ code, verifier, fetchFn = fetc
     throw new Error('[antigravity-oauth] token exchange response missing access_token or refresh_token');
   }
   const { email, userId } = await fetchAccountInfo(json.access_token, { fetchFn, signal });
-  const projectId = await discoverProject(json.access_token, { fetchFn, onProgress, signal, email });
+  const { projectId, tierId } = await discoverAccount(json.access_token, { fetchFn, onProgress, signal, email });
   const tokens = {
     access_token: json.access_token,
     refresh_token: json.refresh_token,
     expires_at: typeof json.expires_in === 'number' ? Date.now() + json.expires_in * 1000 : 0,
     project_id: projectId,
+    tier_id: tierId,
     email,
     user_id: userId,
   };

package/src/runtime/agent/orchestrator/providers/antigravity-oauth-tokens.mjs

@@ -204,6 +204,7 @@ export function loadTokens() {
       refresh_token: String(raw.refresh_token),
       expires_at: _normalizeExpiresAt(raw.expires_at ?? raw.expiresAt),
       project_id: String(raw.project_id || raw.projectId || ''),
+      tier_id: String(raw.tier_id || ''),
       email: String(raw.email || ''),
       user_id: String(raw.user_id || raw.userId || ''),
       source: 'own',
@@ -222,6 +223,7 @@ export function saveTokens(tokens) {
       refresh_token: tokens.refresh_token,
       expires_at: tokens.expires_at || 0,
       project_id: tokens.project_id || tokens.projectId || '',
+      tier_id: tokens.tier_id || '',
       email: tokens.email || '',
       user_id: tokens.user_id || tokens.userId || '',
     },
@@ -274,6 +276,7 @@ export function describeAntigravityOAuthCredentials() {
       ...accountIdentityFields({ id: tokens.user_id, email: tokens.email }),
       email: tokens.email || '',
       projectId: tokens.project_id || '',
+      plan: tokens.tier_id || null,
     };
   } catch {
     return credentialsNotSet();
@@ -340,6 +343,7 @@ export function refreshTokens({ fetchFn = fetch } = {}) {
       refresh_token: json.refresh_token || current.refresh_token,
       expires_at: typeof json.expires_in === 'number' ? Date.now() + json.expires_in * 1000 : 0,
       project_id: current.project_id,
+      tier_id: current.tier_id,
       email: current.email,
       user_id: current.user_id,
     };

package/src/runtime/agent/orchestrator/providers/cursor-client-version.mjs

@@ -4,7 +4,7 @@ import { createRemoteVersionSource } from './npm-cli-version.mjs';
 // documented version endpoint; the official installer script embeds the
 // current build (…/lab/<build>/…), parsed best-effort. Any format change or
 // failure falls back to the floor.
-export const CURSOR_CLIENT_VERSION_FLOOR = 'cli-2026.10.16-e3cb207';
+export const CURSOR_CLIENT_VERSION_FLOOR = 'cli-2026.10.19-6bbf2c4';
 const BUILD_PATTERN = /downloads\.cursor\.com\/lab\/(\d{4}\.\d{2}\.\d{2}-[0-9a-f]{6,40})\//;
 export const CURSOR_INSTALL_URL = 'https://cursor.com/install';
 

package/src/runtime/agent/orchestrator/providers/openai-error-contract.mjs

@@ -14,14 +14,6 @@ import { retryAfterMsFromError, sleepWithAbort } from './retry-classifier.mjs';
 
 const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
 
-// Explicit quota / billing refusals: waiting never helps, so no retry layer
-// may treat them as an ordinary rate limit.
-const QUOTA_OR_BILLING_CODE_RE = /quota|billing|usage_limit|usage_not_included/;
-
-export function isQuotaOrBillingCode(code) {
-  return QUOTA_OR_BILLING_CODE_RE.test(String(code || '').toLowerCase());
-}
-
 /**
  * Parse an HTTP error body ONCE into its contract fields. `message` is the
  * body's own message (untruncated); callers truncate for diagnostics.
@@ -211,7 +203,8 @@ export function applyErrorContract(err, { status, headers, code, error, event }
       err.status = n;
       err.httpStatus = n;
     }
-    const wireHeaders = headers ?? error?.headers ?? event?.error?.headers ?? event?.response?.error?.headers ?? event?.headers;
+    const wireHeaders =
+      headers ?? error?.headers ?? event?.error?.headers ?? event?.response?.error?.headers ?? event?.headers;
     if (wireHeaders && typeof wireHeaders === 'object') err.headers = wireHeaders;
     const rawCode = code ?? error?.code ?? error?.type ?? null;
     if (typeof rawCode === 'string' && rawCode.trim()) err.code = rawCode.trim().toLowerCase();
@@ -225,7 +218,13 @@ export function applyErrorContract(err, { status, headers, code, error, event }
       if (err.retryAfterAt == null) err.retryAfterAt = Date.now() + retryAfterMs;
     }
     const type = typeof error?.type === 'string' ? error.type.trim().toLowerCase() : '';
-    const mapped = typedWireErrorMessage({ code: err.code || '', type, error, headers: err.headers, resetAt: err.resetAt });
+    const mapped = typedWireErrorMessage({
+      code: err.code || '',
+      type,
+      error,
+      headers: err.headers,
+      resetAt: err.resetAt,
+    });
     if (mapped) applyTypedWireMessage(err, mapped, error?.message);
   } catch {}
   return err;
@@ -238,7 +237,12 @@ export function applyErrorContract(err, { status, headers, code, error, event }
  * makes unknown codes default-retryable).
  */
 export function markContentFilter(err, reason) {
-  if (String(reason || '').trim().toLowerCase() !== 'content_filter') return err;
+  if (
+    String(reason || '')
+      .trim()
+      .toLowerCase() !== 'content_filter'
+  )
+    return err;
   err.code = 'content_filter';
   err.providerErrorCode = 'content_filter';
   return err;
@@ -260,7 +264,8 @@ export function httpResponseError({ label, status, headers, text, initialRespons
 }
 
 // The route decides the HTTP/SSE label: the api-key `openai` provider is not OAuth.
-export const httpLabel = (auth) => (auth?.type === 'openai-direct' ? 'OpenAI HTTP fallback' : 'OpenAI OAuth HTTP fallback');
+export const httpLabel = (auth) =>
+  auth?.type === 'openai-direct' ? 'OpenAI HTTP fallback' : 'OpenAI OAuth HTTP fallback';
 
 /**
  * Changing transport must not bypass the server's retry deadline.

package/src/runtime/agent/orchestrator/providers/openai-oauth-tokens.mjs

@@ -92,6 +92,15 @@ export function identityFromTokens(...tokens) {
   return normalizeAccountIdentity({ id: [sub, accountId].filter(Boolean).join(':'), email });
 }
 
+/** ChatGPT plan (e.g. plus, pro) from the first token carrying the claim, else null. */
+export function planFromTokens(...tokens) {
+  for (const token of tokens) {
+    const plan = decodeJwtPayload(token)?.['https://api.openai.com/auth']?.chatgpt_plan_type;
+    if (typeof plan === 'string' && plan) return plan;
+  }
+  return null;
+}
+
 /** mtime of the token file, 0 when it is missing or unreadable. */
 export function tokensFileMtimeMs() {
   try {
@@ -165,6 +174,7 @@ export function describeOpenAIOAuthCredentials() {
       ...oauthCredentialStatus({ hasRefresh, expiresAt, detail: source, refreshSkewMs: TOKEN_REFRESH_SKEW_MS }),
       ...accountIdentityFields(tokens.identity),
       ...(accountId ? { accountId } : {}),
+      plan: planFromTokens(tokens.id_token, tokens.access_token),
     };
   } catch (err) {
     return {

package/src/runtime/agent/orchestrator/runtime-core/ask-user-tool-defs.mjs

@@ -1,3 +1,5 @@
+import { loginPageUrl } from '../session/human-gate/requests.mjs';
+
 const ASK_USER_MAX_QUESTIONS = 4;
 export const ASK_USER_MAX_TEXT = 4000;
 
@@ -50,13 +52,106 @@ export const ASK_USER_TOOL_DEFS = Object.freeze([
             required: ['question', 'header', 'options'],
           },
         },
+        handoff: {
+          type: 'object',
+          description:
+            'Instead of questions: secret = the user types a password/token into the focused field (you never see it; result provided/skipped/timeout); takeover = the user does a step (sign-in, CAPTCHA, 2FA) and says done.',
+          properties: {
+            kind: { type: 'string', enum: ['secret', 'takeover'] },
+            surface: { type: 'string', enum: ['browser', 'computer'] },
+            target: { type: 'string', maxLength: 200, description: 'Site/app and form.' },
+            field: { type: 'string', maxLength: 80, description: 'secret: field label.' },
+            instructions: { type: 'string', maxLength: 2000, description: 'takeover: what to do.' },
+            need: {
+              type: 'string',
+              enum: ['sign_in', 'action', 'confirmation'],
+              description:
+                'takeover: sign_in (sign-in, 2FA), action (CAPTCHA, other step), confirmation (identity/payment check). Default action.',
+            },
+            purpose: {
+              type: 'string',
+              enum: ['login'],
+              description: 'browser takeover: login = sign-in window on url.',
+            },
+            url: { type: 'string', maxLength: 2048, description: 'login: sign-in page (https).' },
+            tab: { type: 'string', maxLength: 64, description: 'browser takeover: page ID from list_tabs.' },
+            window_id: { type: 'string', maxLength: 128, description: 'computer takeover: exact window id.' },
+            app: { type: 'string', maxLength: 120, description: 'computer takeover: app name.' },
+          },
+          required: ['kind', 'surface'],
+          additionalProperties: false,
+        },
       },
-      required: ['questions'],
       additionalProperties: false,
     },
   },
 ]);
 
+/** The handoff of an ask_user call ({ kind, surface, target, field, instructions }), or null. */
+export function validateAskUserHandoff(args) {
+  const handoff = args?.handoff;
+  if (handoff == null) return null;
+  if (args.questions != null) throw new Error('ask_user takes questions or a handoff, not both');
+  if (typeof handoff !== 'object' || Array.isArray(handoff)) throw new Error('ask_user handoff must be an object');
+  if (handoff.kind !== 'secret' && handoff.kind !== 'takeover') {
+    throw new Error('ask_user handoff kind is secret or takeover');
+  }
+  if (handoff.surface !== 'browser' && handoff.surface !== 'computer') {
+    throw new Error('ask_user handoff surface is browser or computer');
+  }
+  const text = (key, limit) => (typeof handoff[key] === 'string' ? handoff[key].trim().slice(0, limit) : '');
+  if (handoff.kind === 'takeover' && !text('instructions', 2000)) {
+    throw new Error('ask_user takeover needs instructions');
+  }
+  const login = handoffLogin(handoff);
+  let need = login ? 'sign_in' : 'action';
+  if (['sign_in', 'action', 'confirmation'].includes(handoff.need)) need = handoff.need;
+  return {
+    kind: handoff.kind,
+    surface: handoff.surface,
+    target: text('target', 200),
+    field: text('field', 80),
+    instructions: text('instructions', 2000),
+    ...(handoff.kind === 'takeover' ? { need, identity: handoffIdentity(handoff), ...(login ? { login } : {}) } : {}),
+  };
+}
+
+/** A login takeover's sign-in page ({ url, origin }); null without the
+ *  explicit purpose, so every other takeover keeps the side panel. */
+function handoffLogin(handoff) {
+  if (handoff.purpose == null) return null;
+  if (handoff.purpose !== 'login' || handoff.kind !== 'takeover' || handoff.surface !== 'browser') {
+    throw new Error('ask_user purpose login is a browser takeover');
+  }
+  const page = loginPageUrl(handoff.url);
+  if (!page) throw new Error('ask_user login needs an https url (http only on localhost)');
+  return page;
+}
+
+/** The window a takeover is about, validated per surface: a browser page ID
+ *  (list_tabs p1, v1 or a page name) or a computer window id and app. Shapes
+ *  that are not plain tokens are dropped, never passed on. */
+const TOKEN = /^[\w.:#@-]+$/;
+function handoffIdentity(handoff) {
+  const token = (key, limit) => {
+    const value = typeof handoff[key] === 'string' ? handoff[key].trim() : '';
+    return value && value.length <= limit && TOKEN.test(value) ? value : '';
+  };
+  if (handoff.surface === 'browser') {
+    const tab = token('tab', 64);
+    return tab ? { tab } : {};
+  }
+  const windowId = token('window_id', 128);
+  const app =
+    typeof handoff.app === 'string'
+      ? handoff.app
+          .replace(/[\r\n]+/g, ' ')
+          .trim()
+          .slice(0, 120)
+      : '';
+  return { ...(windowId ? { windowId } : {}), ...(app ? { app } : {}) };
+}
+
 /** Throws a clear error when the questions are malformed; returns the list. */
 export function validateAskUserQuestions(args) {
   const questions = args?.questions;