@vellumai/assistant 0.12.1 → 0.12.2-staging.2

package/src/acp/acp-claude-oauth.ts

@@ -8,18 +8,29 @@
  * builds one against the manual redirect page and parses the `code#state`
  * string the user copies back. Both converge on `storeAcpClaudeToken`, which
  * writes the `acp/claude_oauth_token` vault field the ACP broker reads at
- * spawn time and provisions the `acp_spawn` read policy.
+ * spawn time, persists any refresh token and expiry the exchange returned,
+ * and provisions the `acp_spawn` read policy.
+ *
+ * Refresh, expiry, and the bound-access digest are stored without credential
+ * metadata so the broker cannot hand them to a spawned agent. The policy for
+ * when to spend the refresh token lives in `claude-token-refresh.ts`.
  */
 
+import { computeExpiresAt, isTokenExpired } from "@vellumai/credential-storage";
+
 import { credentialKey } from "../security/credential-key.js";
 import type { OAuth2Config } from "../security/oauth2.js";
 import {
+  deleteSecureKeyAsync,
   getSecureKeyAsync,
   setSecureKeyAsync,
 } from "../security/secure-keys.js";
 import { getLogger } from "../util/logger.js";
 import { claudeTokenDigest } from "./acp-auth-marker-store.js";
 import {
+  ACP_OAUTH_ACCESS_DIGEST_FIELD,
+  ACP_OAUTH_EXPIRES_AT_FIELD,
+  ACP_OAUTH_REFRESH_TOKEN_FIELD,
   ACP_OAUTH_TOKEN_FIELD,
   ACP_SERVICE,
   classifyAnthropicToken,
@@ -32,6 +43,22 @@ import {
 
 const log = getLogger("acp:claude-oauth");
 
+/**
+ * Serializes every Claude OAuth token-set write (Connect, renewal persist,
+ * companion clear) so a compare-and-write cannot interleave with another
+ * writer. The network refresh itself stays outside this queue.
+ */
+let tokenWriteQueue: Promise<unknown> = Promise.resolve();
+
+function withAcpClaudeTokenWrite<T>(fn: () => Promise<T>): Promise<T> {
+  const run = tokenWriteQueue.then(fn, fn);
+  tokenWriteQueue = run.then(
+    () => undefined,
+    () => undefined,
+  );
+  return run;
+}
+
 /**
  * Verified Claude Code public OAuth client. PKCE-only (no client secret);
  * the single `user:inference` scope is what the ACP adapter's
@@ -137,20 +164,103 @@ export async function storedClaudeTokenDigest(): Promise<string | undefined> {
   return token ? claudeTokenDigest(token) : undefined;
 }
 
+/** Tokens as returned by an authorization-code exchange or a refresh. */
+export interface AcpClaudeTokens {
+  accessToken: string;
+  refreshToken?: string;
+  /** Lifetime in seconds, as the provider reports it. */
+  expiresIn?: number;
+}
+
+function vaultKey(field: string): string {
+  return credentialKey(ACP_SERVICE, field);
+}
+
+/**
+ * Write a companion field, or delete it when there is no value.
+ *
+ * Both outcomes are checked. The store signals failure by return value rather
+ * than by throwing (`setSecureKeyAsync` returns false, `deleteSecureKeyAsync`
+ * returns `"error"` on timeout), so ignoring them would let a backend hiccup
+ * report success while leaving the token-set fields out of sync: an access
+ * token with no way to renew it, or a new access token still paired with a
+ * previous connect's refresh token.
+ */
+async function writeOrClear(
+  field: string,
+  value: string | undefined,
+): Promise<void> {
+  if (value) {
+    const stored = await setSecureKeyAsync(vaultKey(field), value);
+    if (!stored) {
+      throw new Error(
+        `Failed to store Claude OAuth ${field} in secure storage.`,
+      );
+    }
+    return;
+  }
+  const result = await deleteSecureKeyAsync(vaultKey(field));
+  if (result === "error") {
+    throw new Error(
+      `Failed to clear Claude OAuth ${field} from secure storage.`,
+    );
+  }
+}
+
+/**
+ * Write a Claude OAuth token set to the `acp/claude_oauth_*` vault fields.
+ * Throws when the backing store rejects any of the writes.
+ *
+ * The refresh token and expiry are written as a set with the access token:
+ * when the provider returns neither, any previously stored values are cleared
+ * rather than left behind. A stale refresh token paired with a newly connected
+ * access token would otherwise renew into the credential from a previous
+ * connect.
+ *
+ * Only the access-token field gets credential metadata. `serverUse` refuses
+ * any field without metadata, so the refresh token and expiry stay
+ * unreachable through the broker and cannot be injected into a spawned
+ * agent's env.
+ */
+async function writeConnectedTokenSet(tokens: AcpClaudeTokens): Promise<void> {
+  await withAcpClaudeTokenWrite(async () => {
+    const stored = await setSecureKeyAsync(
+      vaultKey(ACP_OAUTH_TOKEN_FIELD),
+      tokens.accessToken,
+    );
+    if (!stored) {
+      throw new Error("Failed to store Claude OAuth token in secure storage.");
+    }
+
+    await writeOrClear(ACP_OAUTH_REFRESH_TOKEN_FIELD, tokens.refreshToken);
+    const expiresAt = computeExpiresAt(tokens.expiresIn);
+    await writeOrClear(
+      ACP_OAUTH_EXPIRES_AT_FIELD,
+      expiresAt == null ? undefined : String(expiresAt),
+    );
+    const hasRenewal = Boolean(tokens.refreshToken) || expiresAt != null;
+    await writeOrClear(
+      ACP_OAUTH_ACCESS_DIGEST_FIELD,
+      hasRenewal ? claudeTokenDigest(tokens.accessToken) : undefined,
+    );
+  });
+}
+
 /**
- * Store a captured Claude OAuth token in the `acp/claude_oauth_token` vault
- * field and provision the policy the broker applies at spawn time: grant the
+ * Store a captured Claude OAuth token set in the `acp/claude_oauth_*` vault
+ * fields and provision the policy the broker applies at spawn time: grant the
  * `acp_spawn` read and lift any domain restriction. Throws when the backing
  * store rejects the write.
+ *
+ * A string argument is treated as an access-token-only write and clears any
+ * companion refresh or expiry fields so they cannot describe a previous token.
  */
-export async function storeAcpClaudeToken(token: string): Promise<void> {
-  const stored = await setSecureKeyAsync(
-    credentialKey(ACP_SERVICE, ACP_OAUTH_TOKEN_FIELD),
-    token,
-  );
-  if (!stored) {
-    throw new Error("Failed to store Claude OAuth token in secure storage.");
-  }
+export async function storeAcpClaudeToken(
+  tokens: string | AcpClaudeTokens,
+): Promise<void> {
+  const tokenSet: AcpClaudeTokens =
+    typeof tokens === "string" ? { accessToken: tokens } : tokens;
+  await writeConnectedTokenSet(tokenSet);
   // Repair rather than merely ensure the policy: an explicit Connect is a
   // deliberate opt-in to ACP, so this widens a credential the broker would
   // otherwise keep denying the spawn read on, which would dead-loop the Connect
@@ -241,6 +351,11 @@ export async function notifyAcpConnectRetired(): Promise<void> {
  * spawn-time broker read applies, so "connected" means precisely "the spawn
  * would get this token". The token-shape guard stays here instead: the broker
  * knows nothing about Anthropic token formats.
+ *
+ * An expired token with no refresh token is the same shape of problem, and is
+ * likewise NOT connected: the card has to stay up so the user can reconnect.
+ * An expired token that still has a refresh token IS connected, because
+ * `ensureFreshAcpClaudeToken` renews it on the next spawn.
  */
 export async function hasAcpClaudeToken(): Promise<boolean> {
   return (await usableStoredClaudeToken()) !== undefined;
@@ -257,9 +372,7 @@ export async function hasAcpClaudeToken(): Promise<boolean> {
  * card and no working token.
  */
 async function usableStoredClaudeToken(): Promise<string | undefined> {
-  const token = await getSecureKeyAsync(
-    credentialKey(ACP_SERVICE, ACP_OAUTH_TOKEN_FIELD),
-  );
+  const token = await getSecureKeyAsync(vaultKey(ACP_OAUTH_TOKEN_FIELD));
   if (token == null || token.length === 0) {
     return undefined;
   }
@@ -274,6 +387,15 @@ async function usableStoredClaudeToken(): Promise<string | undefined> {
     );
     return undefined;
   }
+  if (await isAcpClaudeTokenExpiring()) {
+    const boundDigest = await readBoundAccessDigest();
+    if (boundDigest && boundDigest !== claudeTokenDigest(token)) {
+      return token;
+    }
+    if (!(await hasAcpClaudeRefreshToken())) {
+      return undefined;
+    }
+  }
   return token;
 }
 
@@ -326,3 +448,195 @@ export async function acpConnectCardStillWarranted(
     await import("./acp-auth-marker-store.js");
   return claudeCredentialRefused(resolved);
 }
+
+/**
+ * Persist a token set obtained by renewing an existing credential, leaving
+ * the read policy exactly as it was.
+ *
+ * A renewal happens on a passive spawn with no user in the loop, so it must
+ * not widen what the credential is allowed to do. Granting `acp_spawn` here
+ * would let a background refresh restore a permission a user or admin had
+ * removed from `allowedTools`.
+ *
+ * A rotated refresh token is written when the provider returns one. When the
+ * response omits a refresh token, the stored refresh token is kept so a
+ * non-rotating grant does not lose its renewal material. A missing or
+ * non-positive `expiresIn` clears the recorded expiry so a stale past expiry
+ * cannot condemn the new access token.
+ *
+ * `expectedRefreshToken` is the refresh token this request spent. If the
+ * vault no longer holds that value, the access-token field is gone, or the
+ * stored access token is not the one this refresh material was written
+ * with, the persist is skipped so a newer token set is not overwritten and
+ * a deleted or pasted credential is not replaced. Returns whether the write
+ * happened.
+ */
+export async function persistRefreshedAcpClaudeTokens(
+  tokens: AcpClaudeTokens,
+  expectedRefreshToken: string,
+): Promise<boolean> {
+  if (!tokens.accessToken) {
+    throw new Error("Refreshed Claude OAuth response had no access token.");
+  }
+  return withAcpClaudeTokenWrite(async () => {
+    const current = await readAcpClaudeRefreshToken();
+    if (current !== expectedRefreshToken) {
+      log.info(
+        "Skipping Claude OAuth refresh persist because the stored refresh token changed while the request was in flight",
+      );
+      return false;
+    }
+    const access = await getSecureKeyAsync(vaultKey(ACP_OAUTH_TOKEN_FIELD));
+    if (access == null || access.length === 0) {
+      log.info(
+        "Skipping Claude OAuth refresh persist because the access token is no longer stored",
+      );
+      return false;
+    }
+    if (!(await renewalIsBoundTo(access))) {
+      log.info(
+        "Skipping Claude OAuth refresh persist because the stored access token is not the one this refresh material was written with",
+      );
+      return false;
+    }
+    const stored = await setSecureKeyAsync(
+      vaultKey(ACP_OAUTH_TOKEN_FIELD),
+      tokens.accessToken,
+    );
+    if (!stored) {
+      throw new Error("Failed to store Claude OAuth token in secure storage.");
+    }
+    if (tokens.refreshToken) {
+      await writeOrClear(ACP_OAUTH_REFRESH_TOKEN_FIELD, tokens.refreshToken);
+    }
+    const expiresAt = computeExpiresAt(tokens.expiresIn);
+    await writeOrClear(
+      ACP_OAUTH_EXPIRES_AT_FIELD,
+      expiresAt == null ? undefined : String(expiresAt),
+    );
+    await writeOrClear(
+      ACP_OAUTH_ACCESS_DIGEST_FIELD,
+      claudeTokenDigest(tokens.accessToken),
+    );
+    return true;
+  });
+}
+
+/**
+ * The stored absolute expiry in epoch milliseconds, or null when unknown.
+ *
+ * Unknown is the norm for tokens connected before expiry was recorded, and is
+ * treated as "assume usable": we cannot tell fresh from expired, and guessing
+ * expired would refresh or discard a perfectly good token.
+ */
+async function readExpiresAt(): Promise<number | null> {
+  const raw = await getSecureKeyAsync(vaultKey(ACP_OAUTH_EXPIRES_AT_FIELD));
+  if (!raw) {
+    return null;
+  }
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+
+/**
+ * Whether the stored access token is past its recorded expiry, or close
+ * enough that it should be renewed before use. False when no expiry was
+ * recorded.
+ */
+export async function isAcpClaudeTokenExpiring(): Promise<boolean> {
+  return isTokenExpired(await readExpiresAt());
+}
+
+/** The stored refresh token, or null when none was captured. */
+export async function readAcpClaudeRefreshToken(): Promise<string | null> {
+  const token = await getSecureKeyAsync(vaultKey(ACP_OAUTH_REFRESH_TOKEN_FIELD));
+  return token != null && token.length > 0 ? token : null;
+}
+
+/** Whether renewal material is on hand, without revealing it. */
+export async function hasAcpClaudeRefreshToken(): Promise<boolean> {
+  return (await readAcpClaudeRefreshToken()) != null;
+}
+
+/**
+ * Whether the access-token vault field is present. Presence only: not
+ * whether the value is usable, expired, or readable by the spawn broker.
+ *
+ * Renewal spends a refresh token to replace this field. If the field is
+ * gone, there is no credential to renew.
+ */
+export async function hasStoredAcpClaudeAccessToken(): Promise<boolean> {
+  const token = await getSecureKeyAsync(vaultKey(ACP_OAUTH_TOKEN_FIELD));
+  return token != null && token.length > 0;
+}
+
+async function readBoundAccessDigest(): Promise<string | null> {
+  const digest = await getSecureKeyAsync(
+    vaultKey(ACP_OAUTH_ACCESS_DIGEST_FIELD),
+  );
+  return digest != null && digest.length > 0 ? digest : null;
+}
+
+async function renewalIsBoundTo(accessToken: string): Promise<boolean> {
+  const digest = await readBoundAccessDigest();
+  return digest != null && digest === claudeTokenDigest(accessToken);
+}
+
+async function clearRenewalFields(): Promise<void> {
+  await writeOrClear(ACP_OAUTH_REFRESH_TOKEN_FIELD, undefined);
+  await writeOrClear(ACP_OAUTH_EXPIRES_AT_FIELD, undefined);
+  await writeOrClear(ACP_OAUTH_ACCESS_DIGEST_FIELD, undefined);
+}
+
+/**
+ * Drop the refresh token, keeping the recorded expiry and the access token.
+ * Called when the provider rejects the refresh token.
+ *
+ * The expiry has to survive. `hasAcpClaudeToken()` reads "not connected" from
+ * the combination of an expired token and no refresh token. Clearing the
+ * expiry as well would make `readExpiresAt()` return null, which
+ * {@link isAcpClaudeTokenExpiring} treats as "assume usable", and the dead
+ * credential would report itself connected.
+ */
+export async function clearAcpClaudeRefreshToken(
+  expectedRefreshToken?: string,
+): Promise<void> {
+  await withAcpClaudeTokenWrite(async () => {
+    if (expectedRefreshToken !== undefined) {
+      const current = await readAcpClaudeRefreshToken();
+      if (current !== expectedRefreshToken) {
+        log.info(
+          "Skipping Claude OAuth refresh-token clear because the stored refresh token changed while the request was in flight",
+        );
+        return;
+      }
+    }
+    await writeOrClear(ACP_OAUTH_REFRESH_TOKEN_FIELD, undefined);
+  });
+}
+
+/**
+ * Drop refresh, expiry, and the bound-access digest when they do not describe
+ * the access token currently stored.
+ *
+ * Connect and persist write those fields as a set with the access token. A
+ * later paste or CLI write replaces only the access-token field. Spending the
+ * leftover refresh token would overwrite that replacement.
+ */
+export async function forgetAcpClaudeRenewalStateIfUnbound(): Promise<void> {
+  await withAcpClaudeTokenWrite(async () => {
+    const access = await getSecureKeyAsync(vaultKey(ACP_OAUTH_TOKEN_FIELD));
+    const refresh = await readAcpClaudeRefreshToken();
+    const expiresAt = await readExpiresAt();
+    const digest = await readBoundAccessDigest();
+    const hasRenewal = refresh != null || expiresAt != null || digest != null;
+    if (!hasRenewal) {
+      return;
+    }
+    if (access && digest && digest === claudeTokenDigest(access)) {
+      return;
+    }
+    await clearRenewalFields();
+  });
+}
+

package/src/acp/acp-credentials.ts

@@ -14,6 +14,25 @@
 export const ACP_SERVICE = "acp";
 export const ACP_OAUTH_TOKEN_FIELD = "claude_oauth_token";
 
+/**
+ * Refresh and expiry for {@link ACP_OAUTH_TOKEN_FIELD}, written by the Connect
+ * Claude exchange that stored that access token. Expiry is epoch milliseconds,
+ * matching `computeExpiresAt` and `isTokenExpired` in
+ * `@vellumai/credential-storage`.
+ *
+ * {@link ACP_OAUTH_ACCESS_DIGEST_FIELD} is a digest of the access token those
+ * fields were written with, so a later paste of a different access token cannot
+ * spend leftover refresh material.
+ *
+ * These fields are given no credential metadata. `credentialBroker.serverUse`
+ * refuses any field without metadata, so they stay unreachable through the
+ * broker and cannot be injected into a spawned agent's env. Only the access
+ * token crosses into the child process.
+ */
+export const ACP_OAUTH_REFRESH_TOKEN_FIELD = "claude_oauth_refresh_token";
+export const ACP_OAUTH_EXPIRES_AT_FIELD = "claude_oauth_expires_at";
+export const ACP_OAUTH_ACCESS_DIGEST_FIELD = "claude_oauth_access_digest";
+
 /**
  * True for the ACP vault field the "Connect Claude" flow owns
  * (`acp/claude_oauth_token`). Used to route this credential to the inline

package/src/acp/agent-process.test.ts

@@ -194,7 +194,10 @@ describe("AcpAgentProcess.createSession auth_required handling", () => {
       },
     });
 
-    await expect(proc.createSession("/tmp")).resolves.toBe("session-1");
+    await expect(proc.createSession("/tmp")).resolves.toEqual({
+      sessionId: "session-1",
+      configOptions: [],
+    });
     expect(authenticateCalls()).toBe(1);
   });
 

package/src/acp/agent-process.ts

@@ -6,6 +6,7 @@
  */
 
 import { type ChildProcess, spawn } from "node:child_process";
+import { basename } from "node:path";
 import { Readable, Writable } from "node:stream";
 
 import type {
@@ -14,14 +15,25 @@ import type {
   AuthMethodEnvVar,
   Client,
   InitializeResponse,
+  LoadSessionResponse,
   NewSessionResponse,
   PromptResponse,
+  ResumeSessionResponse,
+  SessionConfigOption,
+  SetSessionConfigOptionRequest,
 } from "@agentclientprotocol/sdk";
 import * as acp from "@agentclientprotocol/sdk";
 
 import { getLogger } from "../util/logger.js";
-import { AcpAuthRequiredError, isAcpAuthRequired } from "./auth-required.js";
-import type { AcpAgentConfig } from "./types.js";
+import { safeStringSlice } from "../util/unicode.js";
+import {
+  AcpAuthRequiredError,
+  CLAUDE_ACP_COMMAND,
+  isAcpAuthRequired,
+  isClaudeAuthFailureMessage,
+  requestErrorReason,
+} from "./auth-required.js";
+import { type AcpAgentConfig, AcpConfigOptionRefusedError } from "./types.js";
 
 const log = getLogger("acp");
 
@@ -32,6 +44,16 @@ const log = getLogger("acp");
  */
 const STDERR_RETENTION_BYTES = 4096;
 
+/**
+ * Normalizes the SDK's optional-and-nullable config-option field to an array,
+ * so every session call hands its caller the same shape.
+ */
+function normalizeConfigOptions(
+  configOptions: SessionConfigOption[] | null | undefined,
+): SessionConfigOption[] {
+  return configOptions ?? [];
+}
+
 function isEnvVarMethod(
   method: AuthMethod,
 ): method is AuthMethodEnvVar & { type: "env_var" } {
@@ -142,7 +164,7 @@ export class AcpAgentProcess {
     // deriveFailureError reads from the end, so dropping the head is lossless.
     const line =
       text.length > STDERR_RETENTION_BYTES
-        ? text.slice(-STDERR_RETENTION_BYTES)
+        ? safeStringSlice(text, text.length - STDERR_RETENTION_BYTES)
         : text;
     this.stderrSeq += 1;
     this.stderrRing.push({ seq: this.stderrSeq, text: line });
@@ -355,16 +377,21 @@ export class AcpAgentProcess {
 
   /**
    * Creates a new ACP session in the specified working directory.
-   * Returns the session ID.
+   * Returns the session ID and the config options the agent reported.
    */
-  async createSession(cwd: string): Promise<string> {
+  async createSession(
+    cwd: string,
+  ): Promise<{ sessionId: string; configOptions: SessionConfigOption[] }> {
     log.info({ agentId: this.agentId, cwd }, "Creating ACP session");
 
     const result: NewSessionResponse = await this.withAuthRetry(() =>
       this.requireConnection().newSession({ cwd, mcpServers: [] }),
     );
 
-    return result.sessionId;
+    return {
+      sessionId: result.sessionId,
+      configOptions: normalizeConfigOptions(result.configOptions),
+    };
   }
 
   /**
@@ -375,12 +402,17 @@ export class AcpAgentProcess {
    * callers should suppress forwarding of those replayed updates (see
    * VellumAcpClientHandler.beginReplaySuppression).
    */
-  async loadSession(sessionId: string, cwd: string): Promise<void> {
+  async loadSession(
+    sessionId: string,
+    cwd: string,
+  ): Promise<{ configOptions: SessionConfigOption[] }> {
     log.info({ agentId: this.agentId, sessionId, cwd }, "Loading ACP session");
 
-    await this.withAuthRetry(() =>
+    const result: LoadSessionResponse = await this.withAuthRetry(() =>
       this.requireConnection().loadSession({ sessionId, cwd, mcpServers: [] }),
     );
+
+    return { configOptions: normalizeConfigOptions(result.configOptions) };
   }
 
   /**
@@ -390,16 +422,70 @@ export class AcpAgentProcess {
    * preferred when the agent advertises the capability
    * (see supportsSessionResume).
    */
-  async resumeSession(sessionId: string, cwd: string): Promise<void> {
+  async resumeSession(
+    sessionId: string,
+    cwd: string,
+  ): Promise<{ configOptions: SessionConfigOption[] }> {
     log.info({ agentId: this.agentId, sessionId, cwd }, "Resuming ACP session");
 
-    await this.withAuthRetry(() =>
+    const result: ResumeSessionResponse = await this.withAuthRetry(() =>
       this.requireConnection().resumeSession({
         sessionId,
         cwd,
         mcpServers: [],
       }),
     );
+
+    return { configOptions: normalizeConfigOptions(result.configOptions) };
+  }
+
+  /**
+   * Sets one session config option (e.g. the model selector) via
+   * `session/set_config_option`. The agent answers with the full refreshed
+   * option set, which is returned to the caller.
+   *
+   * A boolean value sends the `type: "boolean"` request variant; a string
+   * sends the value-id variant.
+   */
+  async setConfigOption(
+    sessionId: string,
+    configId: string,
+    value: string | boolean,
+  ): Promise<SessionConfigOption[]> {
+    log.info(
+      { agentId: this.agentId, sessionId, configId, value },
+      "Setting ACP session config option",
+    );
+
+    const request: SetSessionConfigOptionRequest =
+      typeof value === "boolean"
+        ? { sessionId, configId, type: "boolean", value }
+        : { sessionId, configId, value };
+
+    const response = await this.withAuthRetry(async () => {
+      try {
+        return await this.requireConnection().setSessionConfigOption(request);
+      } catch (err) {
+        // Wrapped here, at the request itself, so `withAuthRetry` still sees
+        // an auth_required answer and a caller cannot confuse the adapter's
+        // refusal with a transport or authentication failure. Claude's
+        // expired-token failure travels as a generic error whose reason is
+        // the only signal, so under the Claude adapter it is left for the
+        // caller to classify.
+        if (err instanceof acp.RequestError && !isAcpAuthRequired(err)) {
+          const reason = requestErrorReason(err);
+          const claudeAuthFailure =
+            basename(this.config.command) === CLAUDE_ACP_COMMAND &&
+            isClaudeAuthFailureMessage(reason);
+          if (!claudeAuthFailure) {
+            throw new AcpConfigOptionRefusedError(reason);
+          }
+        }
+        throw err;
+      }
+    });
+
+    return normalizeConfigOptions(response.configOptions);
   }
 
   /**

package/src/acp/auth-required.ts

@@ -8,7 +8,8 @@
  * 2. Credentials present but rejected (the expired/revoked case): the CLI
  *    surfaces the API 401 as an error message it authors, and the adapter
  *    relays it as a generic -32603 internal error, NOT as `auth_required`.
- *    {@link isClaudeAuthFailureMessage}.
+ *    {@link isClaudeAuthFailureMessage}, over the text
+ *    {@link requestErrorReason} decodes out of the rejection.
  *
  * A positive detection becomes {@link ACP_CLAUDE_AUTH_REQUIRED_CODE} on the
  * `acp_auth_required` event, which the client turns into the inline
@@ -81,6 +82,54 @@ export function isClaudeAuthFailureMessage(
   );
 }
 
+/** Messages the SDK's `RequestError` factories build when given no text. */
+const GENERIC_RPC_MESSAGES: ReadonlySet<string> = new Set([
+  "Parse error",
+  "Invalid request",
+  "Invalid params",
+  "Internal error",
+  "Request cancelled",
+  "Authentication required",
+  "Resource not found",
+]);
+
+/**
+ * The sentence behind a JSON-RPC rejection. An adapter that throws a plain
+ * Error reaches the client as a bare "Internal error" whose real text the
+ * agent-side SDK moved into `data.details`. An adapter that raises
+ * `RequestError.internalError(data, text)` keeps its words in the message and
+ * only supplemental context in `data`, so a specific message wins. Behind a
+ * generic message such as "Invalid params", `data.details` or the serialized
+ * payload supplies the reason instead. Duck-typed like
+ * {@link isAcpAuthRequired}:
+ * `message` is read as a property, so a rejection that arrives as a plain
+ * object off the wire decodes the same as an `Error` instance.
+ */
+export function requestErrorReason(err: unknown): string {
+  if (typeof err !== "object" || err === null) {
+    return String(err);
+  }
+  const { data, message } = err as { data?: unknown; message?: unknown };
+  const own = typeof message === "string" ? message : String(err);
+  if (data == null) {
+    return own;
+  }
+  if (
+    typeof message === "string" &&
+    message.length > 0 &&
+    !GENERIC_RPC_MESSAGES.has(message)
+  ) {
+    return message;
+  }
+  const details = (data as { details?: unknown }).details;
+  if (typeof details === "string" && details.length > 0) {
+    return details;
+  }
+  // JSON.stringify answers undefined for a value it cannot represent.
+  const serialized: string | undefined = JSON.stringify(data);
+  return serialized ?? own;
+}
+
 /** The adapter whose auth failures the Connect Claude flow can repair. */
 export const CLAUDE_ACP_COMMAND = "claude-agent-acp";