@anthropic-ai/claude-agent-sdk 0.3.224 → 0.3.226

package/bridge.d.ts

@@ -212,18 +212,47 @@ export type RemoteCredentials = {
  * enroll) or `"session_stale_relogin"` (OAuth session older than the
  * freshness window — re-authenticate). `"invalid_session_id"` is
  * client-minted: the session id failed validation (`/^[a-zA-Z0-9_-]+$/`)
- * before any request was sent.
+ * before any request was sent. `"request_rejected"` is any other
+ * authoritative non-retryable 4xx (the server answered; neither time nor a
+ * new credential changes the request). `"malformed_response"` is a 2xx this
+ * client could not parse — the mint SUCCEEDED server-side (each call bumps
+ * `worker_epoch`), so retrying epoch-bumps per attempt; not transient, not
+ * an authoritative denial.
  * @alpha
  */
 export type CredentialsFailure = {
     terminal: true;
     reason: 'untrusted_device' | 'session_stale_relogin' | 'invalid_session_id';
+} | {
+    terminal: true;
+    reason: 'request_rejected' | 'malformed_response';
+    /** HTTP status, for the debug trail and user-facing hints. */
+    status: number;
+};
+/**
+ * Non-terminal classified rejection: the OAuth bearer itself was rejected
+ * (401). Retrying with the SAME credential is pointless, but a DIFFERENT
+ * credential can succeed (post-re-authentication) — distinct from
+ * `CredentialsFailure` (`terminal: true`) and from null, which is reserved
+ * for transient transport-shaped failures (network error / timeout / 5xx).
+ * @alpha
+ */
+export type CredentialsRejection = {
+    terminal: false;
+    reason: 'oauth_rejected';
 };
 /**
  * Type guard for `fetchRemoteCredentials` results.
  * @alpha
  */
-export declare function isCredentialsFailure(r: RemoteCredentials | CredentialsFailure | null): r is CredentialsFailure;
+export declare function isCredentialsFailure(r: RemoteCredentials | CredentialsFailure | CredentialsRejection | null): r is CredentialsFailure;
+/**
+ * Type guard for the non-terminal classified 401 rejection. Accepts
+ * `unknown`: callers hand it unions whose success arm is a plain string
+ * (session ids), and it narrows structurally.
+ * @alpha
+ */
+export declare function isCredentialsRejection(r: unknown): r is CredentialsRejection;
 /**
  * Git source/outcome context attached to a v2 code session on create.
  * @alpha
@@ -254,13 +283,18 @@ export declare type BranchDropLogDedup = {
     lastKey?: string | null;
 };
 /**
- * Terminal 4xx from `POST /v1/code/sessions` for a recognized
- * `session_grouping_id` rejection — retrying with the same inputs fails
- * identically.
+ * Terminal failure from `POST /v1/code/sessions` — retrying with the same
+ * inputs fails identically. `reason` distinguishes the recognized
+ * `session_grouping_id` rejection family (`"grouping_rejected"` — the
+ * caller may retry without the grouping) from any other authoritative
+ * non-retryable 4xx (`"request_rejected"`) and from a 2xx this client
+ * could not parse (`"malformed_response"` — the create SUCCEEDED
+ * server-side, so a retry would orphan one session per attempt).
  * @alpha
  */
 export type CreateSessionFailure = {
     terminal: true;
+    reason: 'grouping_rejected' | 'request_rejected' | 'malformed_response';
     status: number;
     detail: string | undefined;
 };
@@ -268,23 +302,25 @@ export type CreateSessionFailure = {
  * Type guard for `createCodeSession` results.
  * @alpha
  */
-export declare function isCreateSessionFailure(r: string | CreateSessionFailure | null): r is CreateSessionFailure;
+export declare function isCreateSessionFailure(r: string | CreateSessionFailure | CredentialsRejection | null): r is CreateSessionFailure;
 /**
  * `POST /v1/code/sessions` — create a fresh CCR session. Returns the `cse_*`
- * session id on success, a `CreateSessionFailure` for a recognized
- * `session_grouping_id` rejection (terminal — don't retry), or null on any
- * other failure (HTTP error, malformed response).
+ * session id on success, a classified `CreateSessionFailure` (terminal —
+ * don't retry; see its `reason`), a `CredentialsRejection` when the OAuth
+ * bearer was rejected (retry only with a NEW credential), or null on
+ * transient transport-shaped failures (network error / timeout / 5xx).
  *
  * Callers supply their own OAuth token — this is a thin HTTP wrapper with no
  * implicit auth, so it works from any process (not just the CLI).
  * @alpha
  */
-export declare function createCodeSession(baseUrl: string, accessToken: string, title: string, timeoutMs: number, tags?: string[], gitContext?: CodeSessionGitContext, cwd?: string, model?: string, sessionGroupingId?: string, dropLogDedup?: BranchDropLogDedup): Promise<string | CreateSessionFailure | null>;
+export declare function createCodeSession(baseUrl: string, accessToken: string, title: string, timeoutMs: number, tags?: string[], gitContext?: CodeSessionGitContext, cwd?: string, model?: string, sessionGroupingId?: string, dropLogDedup?: BranchDropLogDedup): Promise<string | CreateSessionFailure | CredentialsRejection | null>;
 /**
  * `POST /v1/code/sessions/{id}/bridge` — mint a worker JWT for the session.
- * Returns credentials, a `CredentialsFailure` for terminal authz failures
- * (don't retry — see `CredentialsFailure.reason` for remediation), or null
- * on transient failure. The call IS the worker register (bumps epoch
+ * Returns credentials, a `CredentialsFailure` for terminal failures (don't
+ * retry — see `CredentialsFailure.reason` for remediation), a
+ * `CredentialsRejection` when the OAuth bearer was rejected (retry only
+ * with a NEW credential), or null on transient transport-shaped failure. The call IS the worker register (bumps epoch
  * server-side), so pass `epoch: creds.worker_epoch` to `attachBridgeSession`
  * to skip a redundant register.
  *
@@ -293,4 +329,4 @@ export declare function createCodeSession(baseUrl: string, accessToken: string,
  * (bridge sessions are SecurityTier=ELEVATED). See anthropics/anthropic#274559.
  * @alpha
  */
-export declare function fetchRemoteCredentials(sessionId: string, baseUrl: string, accessToken: string, timeoutMs: number, trustedDeviceToken?: string): Promise<RemoteCredentials | CredentialsFailure | null>;
+export declare function fetchRemoteCredentials(sessionId: string, baseUrl: string, accessToken: string, timeoutMs: number, trustedDeviceToken?: string): Promise<RemoteCredentials | CredentialsFailure | CredentialsRejection | null>;