@acosmi/sdk-ts 2.19.0 → 2.19.1

package/dist/node/index.cjs

@@ -149,6 +149,55 @@ var init_types = __esm({
 });
 
 // src/shared/errors.ts
+function nullableID(value) {
+  return value === null || typeof value === "string";
+}
+function decodeGatewayErrorContract(value) {
+  if (value == null || typeof value !== "object") return null;
+  const v = value;
+  const version = v.errorContractVersion;
+  const domain = v.faultDomain;
+  const disposition = v.requestDisposition;
+  const errorCode = v.errorCode;
+  if (version !== 1 || typeof domain !== "string" || !gatewayFaultDomains.includes(domain)) return null;
+  if (typeof errorCode !== "string" || errorCode.length === 0) return null;
+  if (disposition !== "not_accepted" && disposition !== "accepted" && disposition !== "unknown") return null;
+  if (!nullableID(v.transportRequestId) || !nullableID(v.consumeRequestId) || !nullableID(v.providerRequestId)) return null;
+  if (typeof v.retryable !== "boolean") return null;
+  return {
+    errorContractVersion: 1,
+    faultDomain: domain,
+    errorCode,
+    transportRequestId: v.transportRequestId,
+    consumeRequestId: v.consumeRequestId,
+    providerRequestId: v.providerRequestId,
+    requestDisposition: disposition,
+    retryable: v.retryable
+  };
+}
+function readGatewayErrorContract(error) {
+  const direct = decodeGatewayErrorContract(error);
+  if (direct) return direct;
+  if (error == null || typeof error !== "object") return null;
+  const e = error;
+  const axios = decodeGatewayErrorContract(e.response?.data);
+  if (axios) return axios;
+  if (typeof e.body === "string") {
+    try {
+      return decodeGatewayErrorContract(JSON.parse(e.body));
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+function isUserAccessTokenRejected(error) {
+  if (error == null || typeof error !== "object") return false;
+  const e = error;
+  const status = e.statusCode ?? e.response?.status;
+  const contract = readGatewayErrorContract(error);
+  return status === 401 && contract?.faultDomain === "user_auth" && contract.errorCode === "USER_ACCESS_TOKEN_INVALID" && contract.requestDisposition === "not_accepted";
+}
 function isWindowLimitError(err) {
   if (!(err instanceof exports.HTTPError)) return false;
   if (err.errorCode === windowLimitErrorCode) return true;
@@ -176,7 +225,7 @@ function getWindowLimitStreamDetails(err) {
     windowOverridable: typeof e.windowOverridable === "boolean" ? e.windowOverridable : void 0
   };
 }
-exports.RateLimitError = void 0; exports.BusinessError = void 0; exports.OrderTerminalError = void 0; exports.ModelNotFoundError = void 0; exports.HTTPError = void 0; exports.NetworkError = void 0; exports.StreamError = void 0; var windowLimitErrorCode, windowLimitStreamCode;
+exports.RateLimitError = void 0; exports.BusinessError = void 0; exports.OrderTerminalError = void 0; exports.ModelNotFoundError = void 0; exports.HTTPError = void 0; exports.NetworkError = void 0; exports.StreamError = void 0; var gatewayFaultDomains, windowLimitErrorCode, windowLimitStreamCode;
 var init_errors = __esm({
   "src/shared/errors.ts"() {
     exports.RateLimitError = class extends Error {
@@ -235,6 +284,13 @@ var init_errors = __esm({
        * false/缺失 = 周窗/显式禁止/灰度关 (硬等待, 无豁免路径, 老网关不返回时为 undefined)。
        */
       windowOverridable;
+      errorContractVersion;
+      faultDomain;
+      requestDisposition;
+      transportRequestId;
+      consumeRequestId;
+      providerRequestId;
+      retryable;
       constructor(statusCode, opts = {}) {
         let msg;
         if (opts.type) {
@@ -256,6 +312,13 @@ var init_errors = __esm({
         this.windowKind = opts.windowKind;
         this.windowResetAt = opts.windowResetAt;
         this.windowOverridable = opts.windowOverridable;
+        this.errorContractVersion = opts.errorContractVersion;
+        this.faultDomain = opts.faultDomain;
+        this.requestDisposition = opts.requestDisposition;
+        this.transportRequestId = opts.transportRequestId;
+        this.consumeRequestId = opts.consumeRequestId;
+        this.providerRequestId = opts.providerRequestId;
+        this.retryable = opts.retryable === true && opts.requestDisposition === "not_accepted";
       }
     };
     exports.NetworkError = class extends Error {
@@ -266,6 +329,7 @@ var init_errors = __esm({
       cause;
       timeout;
       eof;
+      requestDisposition = "unknown";
       constructor(op, url, cause, opts = {}) {
         const causeMsg = cause instanceof Error ? cause.message : cause != null ? String(cause) : "network error";
         super(`${op} ${url}: ${causeMsg}`);
@@ -286,6 +350,8 @@ var init_errors = __esm({
     exports.StreamError = class extends Error {
       /** 例: "empty_response" / "rate_limit" / "overloaded" / "" */
       code;
+      /** D23 gateway machine code; mirrors the legacy `code` field. */
+      errorCode;
       /** 例: "provider" / "settlement" */
       stage;
       /** 用户友好提示 (中文); 历史字段, 与 rawError 区分 */
@@ -294,23 +360,47 @@ var init_errors = __esm({
       rawError;
       /** 客户端是否值得重试 */
       retryable;
+      errorContractVersion;
+      faultDomain;
+      requestDisposition;
+      transportRequestId;
+      consumeRequestId;
+      providerRequestId;
       constructor(opts = {}) {
         const code = opts.code ?? "";
         const stage = opts.stage ?? "";
         const userMessage = opts.message ?? "";
         const rawError = opts.rawError ?? "";
-        const retryable = opts.retryable ?? false;
+        const retryable = opts.retryable === true && opts.requestDisposition === "not_accepted";
         const body = rawError !== "" ? rawError : userMessage;
         const msg = stage !== "" ? `stream failed: ${stage}: ${body}` : `stream failed: ${body}`;
         super(msg);
         this.name = "StreamError";
         this.code = code;
+        this.errorCode = code;
         this.stage = stage;
         this.userMessage = userMessage;
         this.rawError = rawError;
         this.retryable = retryable;
+        this.errorContractVersion = opts.errorContractVersion;
+        this.faultDomain = opts.faultDomain;
+        this.requestDisposition = opts.requestDisposition;
+        this.transportRequestId = opts.transportRequestId;
+        this.consumeRequestId = opts.consumeRequestId;
+        this.providerRequestId = opts.providerRequestId;
       }
     };
+    gatewayFaultDomains = [
+      "user_auth",
+      "caller_credentials",
+      "account_quota",
+      "account_permission",
+      "provider",
+      "gateway",
+      "transport",
+      "stream_ticket",
+      "protocol"
+    ];
     windowLimitErrorCode = "WINDOW_LIMIT_EXCEEDED";
     windowLimitStreamCode = "window_limit_exceeded";
   }
@@ -893,16 +983,90 @@ var init_openai = __esm({
        *  可能已被 text/tool 推进的 this.blockIndex (否则 content_block_stop 索引错配)。 */
       thinkingBlockIndex = 0;
       textStarted = false;
-      /** OpenAI tool_call index → Anthropic block index */
+      /** OpenAI tool_call 键 → Anthropic block index。键正常是 `tc.index`；上游省略
+       *  index 时退化为 `id:<tool_call_id>`，两者都没有时沿用上一个键（见
+       *  {@link resolveToolKey}）。 */
       toolBlockIndex = /* @__PURE__ */ new Map();
       blockIndex = 0;
+      /** 每个 tool block 已发出的 `partial_json` 累积，用于识别「每片重发全量参数」
+       *  的上游（见 tool_calls 分支的累计判别）。 */
+      toolArgsAccum = /* @__PURE__ */ new Map();
+      /** 上一次解析出的 tool 键，供缺 index 且缺 id 的后续增量沿用。 */
+      lastToolKey = null;
+      /** 已发出 message_delta/message_stop，避免 finish_reason 与 `[DONE]` 各收一次。 */
+      messageClosed = false;
+      /**
+       * 解析一条 tool_call delta 归属的块键。
+       *
+       * OpenAI 流式规范里 `index` 是必填，但兼容实现常有省略。此前这里直接用
+       * `tc.index` 做 Map 键：两个都省略 index 的 tool_call 会共用键 `undefined`，
+       * 于是只开一个块、两段参数拼进同一条 `partial_json` 流，产出 `{…}{…}` 这种
+       * 必然非法的 JSON。这里按「index → id → 沿用上一个」三级降级，让至少一种
+       * 稳定标识生效。
+       */
+      resolveToolKey(tc) {
+        if (typeof tc.index === "number" && Number.isFinite(tc.index)) {
+          this.lastToolKey = tc.index;
+          return tc.index;
+        }
+        if (typeof tc.id === "string" && tc.id !== "") {
+          const key = `id:${tc.id}`;
+          this.lastToolKey = key;
+          return key;
+        }
+        if (this.lastToolKey !== null) return this.lastToolKey;
+        this.lastToolKey = 0;
+        return 0;
+      }
+      /**
+       * 关闭仍打开的 text / thinking / tool 块，并收口 message。
+       *
+       * 由 `finish_reason` 分支与 `[DONE]` 分支共用：上游断流或只发 `[DONE]` 而不发
+       * `finish_reason` 时，此前一个 `content_block_stop` 都不会发，下游拿到的是一个
+       * 永不闭合的 tool_use 块。
+       */
+      closeOpenBlocks(events, stopReason) {
+        if (this.messageClosed) return;
+        this.messageClosed = true;
+        if (this.textStarted) {
+          events.push({
+            event: "content_block_stop",
+            data: JSON.stringify({ type: "content_block_stop", index: this.blockIndex })
+          });
+          this.textStarted = false;
+        } else if (this.thinkingStarted && !this.thinkingStopped) {
+          this.thinkingStopped = true;
+          events.push({
+            event: "content_block_stop",
+            data: JSON.stringify({ type: "content_block_stop", index: this.thinkingBlockIndex })
+          });
+        }
+        for (const idx of this.toolBlockIndex.values()) {
+          events.push({
+            event: "content_block_stop",
+            data: JSON.stringify({ type: "content_block_stop", index: idx })
+          });
+        }
+        events.push({
+          event: "message_delta",
+          data: JSON.stringify({ type: "message_delta", delta: { stop_reason: stopReason } })
+        });
+        events.push({
+          event: "message_stop",
+          data: JSON.stringify({ type: "message_stop" })
+        });
+      }
       /**
        * 将一行 OpenAI SSE data 转换为零或多个 Anthropic 格式 StreamEvent
        * 返回 { events, done }
        */
       convert(data) {
         if (data === "[DONE]") {
-          return { events: [], done: true };
+          const events2 = [];
+          if (this.messageStarted) {
+            this.closeOpenBlocks(events2, "end_turn");
+          }
+          return { events: events2, done: true };
         }
         let chunk;
         try {
@@ -974,7 +1138,9 @@ var init_openai = __esm({
           events.push({ event: "content_block_delta", data: deltaJSON });
         }
         for (const tc of choice.delta.tool_calls ?? []) {
-          if (!this.toolBlockIndex.has(tc.index)) {
+          const fn = tc.function;
+          const toolKey = this.resolveToolKey(tc);
+          if (!this.toolBlockIndex.has(toolKey)) {
             if (this.thinkingStarted && !this.thinkingStopped) {
               this.thinkingStopped = true;
               const stopJSON = JSON.stringify({
@@ -993,56 +1159,46 @@ var init_openai = __esm({
               this.blockIndex++;
               this.textStarted = false;
             }
-            this.toolBlockIndex.set(tc.index, this.blockIndex);
+            this.toolBlockIndex.set(toolKey, this.blockIndex);
             const blockJSON = JSON.stringify({
               type: "content_block_start",
               index: this.blockIndex,
               content_block: {
                 type: "tool_use",
                 id: tc.id,
-                name: tc.function.name,
+                name: fn?.name,
                 input: {}
               }
             });
             events.push({ event: "content_block_start", data: blockJSON });
             this.blockIndex++;
           }
-          if (tc.function.arguments && tc.function.arguments !== "") {
-            const idx = this.toolBlockIndex.get(tc.index);
-            const deltaJSON = JSON.stringify({
-              type: "content_block_delta",
-              index: idx,
-              delta: {
-                type: "input_json_delta",
-                partial_json: tc.function.arguments
-              }
-            });
-            events.push({ event: "content_block_delta", data: deltaJSON });
+          if (fn?.arguments !== void 0 && fn.arguments !== null && fn.arguments !== "") {
+            const rawArgs = typeof fn.arguments === "string" ? fn.arguments : JSON.stringify(fn.arguments);
+            const accum = this.toolArgsAccum.get(toolKey) ?? "";
+            let emit = rawArgs;
+            if (accum !== "" && rawArgs.length > accum.length && rawArgs.startsWith(accum)) {
+              emit = rawArgs.slice(accum.length);
+              this.toolArgsAccum.set(toolKey, rawArgs);
+            } else {
+              this.toolArgsAccum.set(toolKey, accum + rawArgs);
+            }
+            if (emit !== "") {
+              const idx = this.toolBlockIndex.get(toolKey);
+              const deltaJSON = JSON.stringify({
+                type: "content_block_delta",
+                index: idx,
+                delta: {
+                  type: "input_json_delta",
+                  partial_json: emit
+                }
+              });
+              events.push({ event: "content_block_delta", data: deltaJSON });
+            }
           }
         }
         if (choice.finish_reason != null && choice.finish_reason !== "") {
-          if (this.textStarted) {
-            const stopJSON2 = JSON.stringify({
-              type: "content_block_stop",
-              index: this.blockIndex
-            });
-            events.push({ event: "content_block_stop", data: stopJSON2 });
-          } else if (this.thinkingStarted && !this.thinkingStopped) {
-            this.thinkingStopped = true;
-            const stopJSON2 = JSON.stringify({
-              type: "content_block_stop",
-              index: this.thinkingBlockIndex
-            });
-            events.push({ event: "content_block_stop", data: stopJSON2 });
-          }
-          for (const idx of this.toolBlockIndex.values()) {
-            const stopJSON2 = JSON.stringify({
-              type: "content_block_stop",
-              index: idx
-            });
-            events.push({ event: "content_block_stop", data: stopJSON2 });
-          }
-          let stopReason = "end_turn";
+          let stopReason;
           switch (choice.finish_reason) {
             case "tool_calls":
               stopReason = "tool_use";
@@ -1050,14 +1206,13 @@ var init_openai = __esm({
             case "length":
               stopReason = "max_tokens";
               break;
+            case "stop":
+              stopReason = "end_turn";
+              break;
+            default:
+              stopReason = choice.finish_reason;
           }
-          const deltaJSON = JSON.stringify({
-            type: "message_delta",
-            delta: { stop_reason: stopReason }
-          });
-          events.push({ event: "message_delta", data: deltaJSON });
-          const stopJSON = JSON.stringify({ type: "message_stop" });
-          events.push({ event: "message_stop", data: stopJSON });
+          this.closeOpenBlocks(events, stopReason);
         }
         return { events, done: false };
       }
@@ -1118,6 +1273,560 @@ var init_adapters = __esm({
   }
 });
 
+// src/core/credentials.ts
+var uuid = () => globalThis.crypto.randomUUID();
+var pause = () => new Promise((resolve) => setTimeout(resolve, 25));
+var abort = (signal) => {
+  if (signal?.aborted) throw new Error("aborted");
+};
+var sameRequestOwner = (snapshot, expected) => snapshot.storeInstanceId === expected.storeInstanceId && snapshot.authSessionId === expected.authSessionId && snapshot.principal?.issuer === expected.principal?.issuer && snapshot.principal?.subject === expected.principal?.subject && snapshot.principal?.organizationId === expected.principal?.organizationId;
+var CredentialLifecycle = class {
+  constructor(store, protocol) {
+    this.store = store;
+    this.protocol = protocol;
+  }
+  store;
+  protocol;
+  listeners = /* @__PURE__ */ new Set();
+  notificationKey = "";
+  observations = /* @__PURE__ */ new Map();
+  read(signal) {
+    return this.store.readSnapshot(signal);
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  async notify(snapshot) {
+    let current;
+    try {
+      current = await this.read();
+    } catch {
+      return;
+    }
+    if (current.storeInstanceId !== snapshot.storeInstanceId || current.revision !== snapshot.revision)
+      return;
+    const projection = {
+      storeInstanceId: snapshot.storeInstanceId,
+      authorityConfig: snapshot.authorityConfig && {
+        serverURL: snapshot.authorityConfig.serverURL,
+        issuer: snapshot.authorityConfig.issuer,
+        oauthProfile: "desktop",
+        authContractVersion: 2,
+        errorContractVersion: 1
+      },
+      revision: snapshot.revision,
+      authSessionId: snapshot.authSessionId,
+      credentialState: snapshot.credentialState,
+      reason: snapshot.reason,
+      principal: snapshot.principal && {
+        issuer: snapshot.principal.issuer,
+        subject: snapshot.principal.subject,
+        organizationId: snapshot.principal.organizationId
+      },
+      refreshOperation: snapshot.refreshOperation && {
+        operationId: snapshot.refreshOperation.operationId,
+        sessionId: snapshot.refreshOperation.sessionId,
+        baseRevision: snapshot.refreshOperation.baseRevision,
+        phase: snapshot.refreshOperation.phase,
+        returnState: snapshot.refreshOperation.returnState,
+        startedAt: snapshot.refreshOperation.startedAt,
+        dispatchedAt: snapshot.refreshOperation.dispatchedAt,
+        deadlineAt: snapshot.refreshOperation.deadlineAt
+      },
+      loginAttempt: snapshot.loginAttempt && {
+        attemptId: snapshot.loginAttempt.attemptId,
+        baseSessionId: snapshot.loginAttempt.baseSessionId,
+        startedAt: snapshot.loginAttempt.startedAt
+      },
+      lastMutation: snapshot.lastMutation && {
+        mutationId: snapshot.lastMutation.mutationId,
+        operationId: snapshot.lastMutation.operationId,
+        resultRevision: snapshot.lastMutation.resultRevision
+      },
+      lastLoginAttemptId: snapshot.lastLoginAttemptId,
+      verifiedIdentity: snapshot.verifiedIdentity && {
+        authSessionId: snapshot.verifiedIdentity.authSessionId,
+        principal: {
+          issuer: snapshot.verifiedIdentity.principal.issuer,
+          subject: snapshot.verifiedIdentity.principal.subject,
+          organizationId: snapshot.verifiedIdentity.principal.organizationId
+        },
+        displayName: snapshot.verifiedIdentity.displayName,
+        avatarUrl: snapshot.verifiedIdentity.avatarUrl,
+        email: snapshot.verifiedIdentity.email,
+        imageUrl: snapshot.verifiedIdentity.imageUrl,
+        accountCreatedAt: snapshot.verifiedIdentity.accountCreatedAt,
+        requiresPhoneBinding: snapshot.verifiedIdentity.requiresPhoneBinding,
+        hasExtraUsageEnabled: snapshot.verifiedIdentity.hasExtraUsageEnabled,
+        billingType: snapshot.verifiedIdentity.billingType,
+        subscriptionCreatedAt: snapshot.verifiedIdentity.subscriptionCreatedAt,
+        rateLimitTier: snapshot.verifiedIdentity.rateLimitTier,
+        organizationName: snapshot.verifiedIdentity.organizationName,
+        verifiedAt: snapshot.verifiedIdentity.verifiedAt
+      }
+    };
+    const key = JSON.stringify({ ...projection, revision: void 0, lastMutation: void 0 });
+    if (key === this.notificationKey) return;
+    this.notificationKey = key;
+    for (const listener of this.listeners) {
+      try {
+        listener(structuredClone(projection));
+      } catch {
+      }
+    }
+  }
+  async reconcile(signal) {
+    const s = await this.read(signal);
+    await this.notify(s);
+    return s;
+  }
+  cas(s, changes, mutationId = uuid(), signal) {
+    return this.store.compareAndSwap(
+      {
+        storeInstanceId: s.storeInstanceId,
+        revision: s.revision,
+        authSessionId: s.authSessionId,
+        state: s.credentialState,
+        operationId: s.refreshOperation?.operationId ?? s.loginAttempt?.attemptId ?? null
+      },
+      { ...s, ...changes },
+      mutationId,
+      signal
+    );
+  }
+  async commit(s, changes, signal) {
+    const r = await this.cas(s, changes, uuid(), signal);
+    if (r.status === "storage_error") throw new Error("storage_unavailable");
+    if (r.status === "committed") await this.notify(r.snapshot);
+    return r;
+  }
+  async metadata(s, signal) {
+    const m = await this.protocol.metadata(signal);
+    if (m.crabcode_auth_contract_version !== 2 || m.gateway_error_contract_version !== 1 || !m.issuer)
+      throw new Error("auth_contract_unsupported");
+    if (s.authorityConfig && (s.authorityConfig.serverURL !== this.protocol.serverURL || s.authorityConfig.issuer !== m.issuer || s.authorityConfig.oauthProfile !== "desktop" || s.authorityConfig.authContractVersion !== 2 || s.authorityConfig.errorContractVersion !== 1))
+      throw new Error("auth_contract_unsupported");
+    return m;
+  }
+  async reserveLogin(signal) {
+    const attemptId = uuid();
+    let reserved;
+    for (; ; ) {
+      abort(signal);
+      const s = await this.read(signal);
+      if (s.credentialState !== "signed_out") throw new Error("local_logout_required");
+      const r = await this.commit(s, { loginAttempt: { attemptId, baseSessionId: s.authSessionId, startedAt: (/* @__PURE__ */ new Date()).toISOString() } }, signal);
+      if (r.status === "committed") {
+        reserved = r.snapshot;
+        break;
+      }
+    }
+    try {
+      const m = await this.metadata(reserved, signal);
+      for (; ; ) {
+        abort(signal);
+        const current = await this.read(signal);
+        if (current.storeInstanceId !== reserved.storeInstanceId || current.loginAttempt?.attemptId !== attemptId) throw new Error("superseded");
+        if (current.authorityConfig) return { attemptId, metadata: m };
+        const r = await this.commit(current, { authorityConfig: { serverURL: this.protocol.serverURL, issuer: m.issuer, oauthProfile: "desktop", authContractVersion: 2, errorContractVersion: 1 } }, signal);
+        if (r.status === "committed") return { attemptId, metadata: m };
+      }
+    } catch (error) {
+      await this.cancelLogin(attemptId);
+      throw error;
+    }
+  }
+  async installLogin(attemptId, tokens, signal) {
+    this.validateTokens(tokens);
+    for (; ; ) {
+      abort(signal);
+      const s = await this.read(signal);
+      if (s.loginAttempt?.attemptId !== attemptId || s.loginAttempt.baseSessionId !== s.authSessionId)
+        throw new Error("superseded");
+      const r = await this.commit(
+        s,
+        {
+          authSessionId: uuid(),
+          tokenSet: tokens,
+          credentialState: "pending_identity",
+          principal: null,
+          verifiedIdentity: null,
+          loginAttempt: null,
+          lastLoginAttemptId: attemptId,
+          reason: "identity_unavailable"
+        },
+        signal
+      );
+      if (r.status === "committed") return this.bindIdentity(r.snapshot.authSessionId, signal);
+    }
+  }
+  async assertLogin(attemptId, signal) {
+    abort(signal);
+    const s = await this.read(signal);
+    if (s.loginAttempt?.attemptId !== attemptId) throw new Error("superseded");
+  }
+  async cancelLogin(attemptId) {
+    const s = await this.read();
+    if (s.loginAttempt?.attemptId === attemptId) await this.commit(s, { loginAttempt: null });
+  }
+  validateTokens(t) {
+    if (!t.access_token?.trim() || !t.refresh_token?.trim() || !t.client_id?.trim() || t.server_url !== this.protocol.serverURL || !Number.isFinite(Date.parse(t.expires_at)) || Date.parse(t.expires_at) <= Date.now())
+      throw new Error("invalid_response");
+  }
+  usable(s) {
+    return !!s.tokenSet && Date.parse(s.tokenSet.expires_at) > Date.now() + 3e5;
+  }
+  async bindIdentity(sessionId, signal) {
+    const s = await this.ensureSnapshot(signal, void 0, true);
+    if (s.authSessionId !== sessionId) throw new Error("superseded");
+    if (s.credentialState === "ready") return s;
+    await this.metadata(s, signal);
+    const beforeProfile = await this.read(signal);
+    if (beforeProfile.storeInstanceId !== s.storeInstanceId || beforeProfile.authSessionId !== sessionId || beforeProfile.revision !== s.revision || beforeProfile.credentialState !== "pending_identity")
+      throw new Error("superseded");
+    let identity;
+    try {
+      identity = await this.protocol.profile(s.tokenSet, signal);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "";
+      if (message === "invalid_scope" || message === "auth_contract_unsupported")
+        await this.commit(s, { credentialState: "configuration_error", reason: message });
+      throw error;
+    }
+    abort(signal);
+    const current = await this.read(signal);
+    if (current.storeInstanceId !== s.storeInstanceId || current.authSessionId !== sessionId || current.revision !== s.revision)
+      throw new Error("superseded");
+    if (!identity.subject) throw new Error("invalid_response");
+    const principal = {
+      issuer: s.authorityConfig.issuer,
+      subject: identity.subject,
+      organizationId: identity.organizationId
+    };
+    const r = await this.commit(
+      s,
+      {
+        principal,
+        verifiedIdentity: {
+          authSessionId: sessionId,
+          principal,
+          displayName: identity.displayName,
+          avatarUrl: identity.avatarUrl,
+          email: identity.email,
+          imageUrl: identity.imageUrl,
+          accountCreatedAt: identity.accountCreatedAt,
+          requiresPhoneBinding: identity.requiresPhoneBinding,
+          hasExtraUsageEnabled: identity.hasExtraUsageEnabled,
+          billingType: identity.billingType,
+          subscriptionCreatedAt: identity.subscriptionCreatedAt,
+          rateLimitTier: identity.rateLimitTier,
+          organizationName: identity.organizationName,
+          verifiedAt: (/* @__PURE__ */ new Date()).toISOString()
+        },
+        credentialState: "ready",
+        reason: null
+      },
+      signal
+    );
+    if (r.status !== "committed") throw new Error("superseded");
+    return r.snapshot;
+  }
+  async ensure(signal, rejected, expected) {
+    const snapshot = await this.ensureSnapshot(signal, rejected, false, expected);
+    this.observations.set(snapshot.tokenSet.access_token, snapshot);
+    if (this.observations.size > 128)
+      this.observations.delete(this.observations.keys().next().value);
+    return snapshot.tokenSet.access_token;
+  }
+  async forceRefresh(signal, rejectedToken, expected) {
+    const rejected = rejectedToken ? this.observations.get(rejectedToken) : await this.read(signal);
+    if (rejectedToken && !rejected) throw new Error("credential_observation_unavailable");
+    return this.ensure(signal, rejected, expected);
+  }
+  async ensureSnapshot(signal, rejected, pending = false, expected) {
+    let session;
+    let instance;
+    let initialRevision;
+    let refreshed = false;
+    let initialAccess;
+    for (; ; ) {
+      abort(signal);
+      const s = await this.read(signal);
+      if (expected && !sameRequestOwner(s, expected)) throw new Error("superseded");
+      if (s.authorityConfig && s.authorityConfig.serverURL !== this.protocol.serverURL)
+        throw new Error("auth_contract_unsupported");
+      if (session === void 0) {
+        session = s.authSessionId;
+        instance = s.storeInstanceId;
+        initialRevision = s.revision;
+        initialAccess = s.tokenSet?.access_token;
+      }
+      if (s.storeInstanceId !== instance || s.authSessionId !== session || rejected && (s.authSessionId !== rejected.authSessionId || s.storeInstanceId !== rejected.storeInstanceId))
+        throw new Error("superseded");
+      if (s.credentialState === "refresh_dispatched") {
+        if (Date.now() >= Date.parse(s.refreshOperation.deadlineAt))
+          await this.commit(s, {
+            credentialState: "reauth_required",
+            tokenSet: null,
+            refreshOperation: null,
+            reason: "refresh_outcome_unknown"
+          });
+        else await pause();
+        continue;
+      }
+      if (s.credentialState === "refresh_reserved") {
+        if (Date.now() >= Date.parse(s.refreshOperation.startedAt) + 3e4)
+          await this.commit(s, {
+            credentialState: s.refreshOperation.returnState,
+            refreshOperation: null
+          });
+        else await pause();
+        continue;
+      }
+      if (s.credentialState !== "ready" && !(pending && s.credentialState === "pending_identity"))
+        throw new Error(`credential_unavailable:${s.credentialState}:${s.reason ?? ""}`);
+      const live = !!s.tokenSet && Date.parse(s.tokenSet.expires_at) > Date.now();
+      if (live && (refreshed || s.revision !== (rejected?.revision ?? initialRevision) && (rejected !== void 0 || s.tokenSet.access_token !== initialAccess)))
+        return s;
+      if (this.usable(s) && !rejected) return s;
+      const metadata = await this.metadata(s, signal);
+      abort(signal);
+      const operationId = uuid();
+      const r = await this.commit(
+        s,
+        {
+          credentialState: "refresh_reserved",
+          refreshOperation: {
+            operationId,
+            sessionId: s.authSessionId,
+            baseRevision: s.revision,
+            phase: "reserved",
+            returnState: s.credentialState,
+            startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+            dispatchedAt: null,
+            deadlineAt: null
+          }
+        },
+        signal
+      );
+      if (r.status !== "committed") continue;
+      const owner = this.refresh(r.snapshot, metadata);
+      await this.wait(owner, signal);
+      refreshed = true;
+      rejected = void 0;
+    }
+  }
+  wait(promise, signal) {
+    if (!signal) return promise;
+    return new Promise((resolve, reject) => {
+      const onAbort = () => {
+        signal.removeEventListener("abort", onAbort);
+        reject(new Error("aborted"));
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+      promise.then(
+        (value) => {
+          signal.removeEventListener("abort", onAbort);
+          resolve(value);
+        },
+        (error) => {
+          signal.removeEventListener("abort", onAbort);
+          reject(error);
+        }
+      );
+      if (signal.aborted) onAbort();
+    });
+  }
+  async refresh(reserved, metadata) {
+    const dispatchedAt = Date.now();
+    const r = await this.commit(reserved, {
+      credentialState: "refresh_dispatched",
+      refreshOperation: {
+        ...reserved.refreshOperation,
+        phase: "dispatched",
+        dispatchedAt: new Date(dispatchedAt).toISOString(),
+        deadlineAt: new Date(dispatchedAt + 3e4).toISOString()
+      }
+    });
+    if (r.status !== "committed") return;
+    const s = r.snapshot;
+    const ctl = new AbortController();
+    const timeout = setTimeout(() => ctl.abort(), 3e4);
+    let tokens;
+    try {
+      const result = await this.wait(
+        (async () => {
+          const response = await this.protocol.fetch(metadata.token_endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+              grant_type: "refresh_token",
+              client_id: s.tokenSet.client_id,
+              refresh_token: s.tokenSet.refresh_token
+            }),
+            signal: ctl.signal
+          });
+          const body2 = await response.json();
+          return { response, body: body2 };
+        })(),
+        ctl.signal
+      );
+      if (!result.response.ok) {
+        const code = result.body.error;
+        let reason = "refresh_outcome_unknown";
+        let state = "reauth_required";
+        if (code === "invalid_grant") reason = code;
+        else if (["invalid_client", "invalid_scope", "unsupported_grant_type"].includes(code)) {
+          reason = code;
+          state = "configuration_error";
+        } else if (result.body.rotationOutcome === "not_committed" && ["temporarily_unavailable", "server_error"].includes(code)) {
+          await this.commit(s, {
+            credentialState: s.refreshOperation.returnState,
+            refreshOperation: null
+          });
+          throw new Error("refresh_temporarily_unavailable");
+        }
+        await this.commit(s, {
+          credentialState: state,
+          tokenSet: null,
+          refreshOperation: null,
+          reason
+        });
+        throw new Error(reason);
+      }
+      const body = result.body;
+      if (!Number.isFinite(body.expires_in) || body.expires_in <= 0)
+        throw new Error("invalid_response");
+      tokens = {
+        ...s.tokenSet,
+        access_token: body.access_token,
+        refresh_token: body.refresh_token,
+        expires_at: new Date(Date.now() + body.expires_in * 1e3).toISOString(),
+        scope: body.scope ?? s.tokenSet.scope
+      };
+      this.validateTokens(tokens);
+    } catch (error) {
+      await this.commit(s, {
+        credentialState: "reauth_required",
+        tokenSet: null,
+        refreshOperation: null,
+        reason: "refresh_outcome_unknown"
+      });
+      throw error;
+    } finally {
+      clearTimeout(timeout);
+    }
+    const started = performance.now(), mutationId = uuid();
+    for (; ; ) {
+      if (Date.now() >= Date.parse(s.refreshOperation.deadlineAt)) {
+        await this.commit(s, {
+          credentialState: "reauth_required",
+          tokenSet: null,
+          refreshOperation: null,
+          reason: "refresh_outcome_unknown"
+        });
+        void this.revoke(tokens, metadata);
+        throw new Error("refresh_outcome_unknown");
+      }
+      const result = await this.cas(
+        s,
+        {
+          tokenSet: tokens,
+          credentialState: s.refreshOperation.returnState,
+          refreshOperation: null
+        },
+        mutationId
+      );
+      if (result.status === "committed") {
+        await this.notify(result.snapshot);
+        return;
+      }
+      if (result.status === "superseded") {
+        void this.revoke(tokens, metadata);
+        return;
+      }
+      if (performance.now() - started >= 2e3) throw new Error("credential_persist_failed");
+      await pause();
+    }
+  }
+  async revoke(tokens, metadata, authority) {
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), 3e4);
+    try {
+      const m = metadata ?? await this.wait(authority ? this.metadata(authority, ctl.signal) : this.protocol.metadata(ctl.signal), ctl.signal);
+      if (!m.revocation_endpoint) return "unsupported";
+      const response = await this.wait(this.protocol.fetch(m.revocation_endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({ token: tokens.refresh_token, token_type_hint: "refresh_token" }),
+        signal: ctl.signal
+      }), ctl.signal);
+      return response.ok ? "confirmed" : "failed";
+    } catch {
+      return "failed";
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  async logout(signal, expected) {
+    let s = await this.read(signal);
+    if (expected && (s.storeInstanceId !== expected.storeInstanceId || s.authSessionId !== expected.authSessionId)) {
+      return {
+        logoutOperationId: uuid(),
+        expectedAuthSessionId: expected.authSessionId,
+        storeInstanceId: expected.storeInstanceId,
+        revision: s.revision,
+        status: "superseded"
+      };
+    }
+    const session = s.authSessionId, instance = s.storeInstanceId, started = performance.now(), logoutOperationId = uuid();
+    const receipt = () => ({
+      logoutOperationId,
+      expectedAuthSessionId: session,
+      storeInstanceId: instance,
+      revision: s.revision
+    });
+    for (; ; ) {
+      abort(signal);
+      if (s.storeInstanceId !== instance || s.authSessionId !== session)
+        return { ...receipt(), status: "superseded" };
+      if (s.credentialState === "signed_out" && !s.loginAttempt)
+        return { ...receipt(), status: "already_signed_out" };
+      const r = await this.cas(
+        s,
+        {
+          credentialState: "signed_out",
+          authSessionId: null,
+          principal: null,
+          tokenSet: null,
+          refreshOperation: null,
+          loginAttempt: null,
+          lastLoginAttemptId: null,
+          verifiedIdentity: null,
+          reason: null
+        },
+        logoutOperationId,
+        signal
+      );
+      if (r.status === "committed") {
+        await this.notify(r.snapshot);
+        return {
+          ...receipt(),
+          revision: r.snapshot.revision,
+          status: "committed",
+          revocation: s.tokenSet ? this.revoke(s.tokenSet, void 0, s) : Promise.resolve("unsupported")
+        };
+      }
+      if (performance.now() - started >= 2e3) throw new Error("storage_busy");
+      await pause();
+      s = await this.read(signal);
+    }
+  }
+};
+
 // src/core/client.ts
 init_types();
 
@@ -1557,33 +2266,35 @@ async function revokeToken(meta, token, signal, fetchImpl = globalThis.fetch) {
 }
 async function postToken(endpoint, data, signal, fetchImpl = globalThis.fetch) {
   const ctl = withTimeout(authTimeoutMs, signal);
-  let resp;
   try {
-    resp = await fetchImpl(endpoint, {
-      method: "POST",
-      headers: { "Content-Type": "application/x-www-form-urlencoded" },
-      body: data,
-      signal: ctl.signal
-    });
-  } catch (e) {
-    throw new Error(`token request: ${e instanceof Error ? e.message : String(e)}`);
-  } finally {
-    ctl.dispose();
-  }
-  if (!resp.ok) {
-    let errBody = {};
+    let resp;
     try {
-      errBody = await resp.json();
-    } catch {
+      resp = await fetchImpl(endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: data,
+        signal: ctl.signal
+      });
+    } catch (e) {
+      throw new Error(`token request: ${e instanceof Error ? e.message : String(e)}`);
     }
-    const oauthError = typeof errBody.error === "string" ? errBody.error : "";
-    const errorDescription = typeof errBody.error_description === "string" ? errBody.error_description : "";
-    throw new OAuthTokenEndpointError(resp.status, oauthError, errorDescription);
-  }
-  try {
-    return await resp.json();
-  } catch (e) {
-    throw new Error(`token: decode: ${e instanceof Error ? e.message : String(e)}`);
+    if (!resp.ok) {
+      let errBody = {};
+      try {
+        errBody = await resp.json();
+      } catch {
+      }
+      const oauthError = typeof errBody.error === "string" ? errBody.error : "";
+      const errorDescription = typeof errBody.error_description === "string" ? errBody.error_description : "";
+      throw new OAuthTokenEndpointError(resp.status, oauthError, errorDescription);
+    }
+    try {
+      return await resp.json();
+    } catch (e) {
+      throw new Error(`token: decode: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  } finally {
+    ctl.dispose();
   }
 }
 function newTokenSet(resp, clientID, serverURL) {
@@ -2066,10 +2777,31 @@ function parseHTTPErrorWithHeader(statusCode, body, header) {
       } else if (typeof top.message === "string") {
         message = top.message;
       }
+      const contractSource = errObj && typeof errObj === "object" ? errObj : top;
       if (typeof top.errorCode === "string") errorCode = top.errorCode;
+      else if (typeof contractSource.errorCode === "string") errorCode = contractSource.errorCode;
       if (top.windowKind === "FIVE_HOUR" || top.windowKind === "WEEKLY") windowKind = top.windowKind;
       if (typeof top.windowResetAt === "string") windowResetAt = top.windowResetAt;
       if (typeof top.windowOverridable === "boolean") windowOverridable = top.windowOverridable;
+      const disposition = contractSource.requestDisposition === "not_accepted" || contractSource.requestDisposition === "accepted" || contractSource.requestDisposition === "unknown" ? contractSource.requestDisposition : void 0;
+      const domains = ["user_auth", "caller_credentials", "account_quota", "account_permission", "provider", "gateway", "transport", "stream_ticket", "protocol"];
+      return new exports.HTTPError(statusCode, {
+        type,
+        message,
+        retryAfter,
+        body: bodyStr,
+        errorCode,
+        windowKind,
+        windowResetAt,
+        windowOverridable,
+        errorContractVersion: contractSource.errorContractVersion === 1 ? 1 : void 0,
+        faultDomain: typeof contractSource.faultDomain === "string" && domains.includes(contractSource.faultDomain) ? contractSource.faultDomain : void 0,
+        requestDisposition: disposition,
+        transportRequestId: typeof contractSource.transportRequestId === "string" ? contractSource.transportRequestId : null,
+        consumeRequestId: typeof contractSource.consumeRequestId === "string" ? contractSource.consumeRequestId : null,
+        providerRequestId: typeof contractSource.providerRequestId === "string" ? contractSource.providerRequestId : null,
+        retryable: contractSource.retryable === true
+      });
     }
   } catch {
   }
@@ -2131,7 +2863,19 @@ function parseStreamError(data) {
       if (code === "" && errObj.type) code = errObj.type;
     }
   }
-  return new exports.StreamError({ code, stage, message, rawError, retryable });
+  return new exports.StreamError({
+    code,
+    stage,
+    message,
+    rawError,
+    retryable,
+    errorContractVersion: payload.errorContractVersion,
+    faultDomain: payload.faultDomain,
+    requestDisposition: payload.requestDisposition,
+    transportRequestId: payload.transportRequestId,
+    consumeRequestId: payload.consumeRequestId,
+    providerRequestId: payload.providerRequestId
+  });
 }
 function isOrderSuccess(status) {
   switch (status) {
@@ -2365,6 +3109,13 @@ var Client = class _Client {
   tokens = null;
   /** token 持久化 */
   store;
+  credentialMode;
+  versionedCredentialStore;
+  accessTokenProvider;
+  beforeCredentialInstall;
+  credentialAuthority;
+  credentialRequestOwner;
+  lifecycle = null;
   /** fetch 实现 (默认 globalThis.fetch) */
   fetchImpl;
   /** 互斥锁 (TS 用 Promise chain 替代 sync.Mutex) */
@@ -2395,6 +3146,7 @@ var Client = class _Client {
   /** V29 系数缓存 (TTL 8s, listCoefficients 内部用) */
   coefCacheData = null;
   coefCacheTimeMs = 0;
+  credentialOwnerKey = null;
   /** 串行化锁 (替代 Go sync.Mutex) */
   coefMu = Promise.resolve();
   constructor(cfg = {}) {
@@ -2405,8 +3157,92 @@ var Client = class _Client {
     this.oauthMetadataProfile = cfg.oauthMetadataProfile ?? "desktop";
     this.browserRefreshMode = cfg.browserRefreshMode ?? "direct";
     this.refreshProxyURL = cfg.refreshProxyURL ?? null;
-    this.store = cfg.store ?? defaultTokenStore();
+    this.credentialMode = cfg.credentialMode ?? "legacy";
+    this.credentialAuthority = new URL(this.serverURL).origin;
+    if (this.credentialMode === "versioned" && !cfg.versionedCredentialStore) {
+      throw new Error("versionedCredentialStore is required for credentialMode=versioned");
+    }
+    if (cfg.credentialRequestOwner && this.credentialMode !== "versioned") {
+      throw new Error("credentialRequestOwner requires credentialMode=versioned");
+    }
+    if (this.credentialMode === "legacy" && cfg.versionedCredentialStore) {
+      throw new Error("credentialMode=versioned is required when versionedCredentialStore is provided");
+    }
+    if (this.credentialMode === "external" && cfg.versionedCredentialStore) {
+      throw new Error("versionedCredentialStore is incompatible with credentialMode=external");
+    }
+    if (this.credentialMode !== "external" && cfg.accessTokenProvider) {
+      throw new Error("accessTokenProvider requires credentialMode=external");
+    }
+    if (this.credentialMode === "external" && !cfg.accessTokenProvider) {
+      throw new Error("accessTokenProvider is required for credentialMode=external");
+    }
+    if (this.credentialMode !== "versioned" && cfg.beforeCredentialInstall) {
+      throw new Error("beforeCredentialInstall requires credentialMode=versioned");
+    }
+    if (this.credentialMode !== "legacy") {
+      const authority = new URL(this.serverURL).origin;
+      for (const [name, override] of [["apiBaseURL", this.apiBaseURL], ["complianceBaseURL", this.complianceBaseURL]]) {
+        if (override && new URL(override).origin !== authority) {
+          throw new Error(`${name} must use the credential authority ${authority}`);
+        }
+      }
+    }
+    this.accessTokenProvider = cfg.accessTokenProvider;
+    this.beforeCredentialInstall = cfg.beforeCredentialInstall;
+    this.credentialRequestOwner = cfg.credentialRequestOwner ? {
+      storeInstanceId: cfg.credentialRequestOwner.storeInstanceId,
+      authSessionId: cfg.credentialRequestOwner.authSessionId,
+      principal: cfg.credentialRequestOwner.principal ? {
+        issuer: cfg.credentialRequestOwner.principal.issuer,
+        subject: cfg.credentialRequestOwner.principal.subject,
+        organizationId: cfg.credentialRequestOwner.principal.organizationId
+      } : null
+    } : null;
     this.fetchImpl = cfg.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    this.versionedCredentialStore = cfg.versionedCredentialStore ?? null;
+    if (this.versionedCredentialStore) this.lifecycle = new CredentialLifecycle(this.versionedCredentialStore, {
+      serverURL: this.serverURL,
+      fetch: this.fetchImpl,
+      metadata: (signal) => discoverWithProfile(this.serverURL, "desktop", signal, this.fetchImpl),
+      profile: async (tokens, signal) => {
+        const gatewayRoot = this.serverURL.replace(/\/api\/v4$/, "");
+        const profileURL = `${gatewayRoot}/api/oauth/profile`;
+        this.assertCredentialURL(profileURL);
+        const response = await this.fetchImpl(profileURL, { headers: { Authorization: `Bearer ${tokens.access_token}` }, signal });
+        if (!response.ok) {
+          const bodyBytes = response.body ? await readLimited(response.body, maxErrorBodySize) : new Uint8Array();
+          const failure = parseHTTPErrorWithHeader(response.status, bodyBytes, response.headers);
+          const contract = readGatewayErrorContract(failure);
+          const code = contract?.errorCode ?? null;
+          if (code === "INVALID_SCOPE") throw new Error("invalid_scope");
+          if (code === "AUTH_CONTRACT_UNSUPPORTED") throw new Error("auth_contract_unsupported");
+          if (code === "ACCOUNT_NOT_FOUND") throw new Error("account_permission");
+          throw new Error("identity_unavailable");
+        }
+        const body = await response.json();
+        const subject = body.account?.uuid;
+        if (typeof subject !== "string" || !subject) throw new Error("invalid_response");
+        const account = body.account;
+        const organization = body.organization;
+        return {
+          subject,
+          organizationId: organization?.uuid || null,
+          ...typeof account.display_name === "string" ? { displayName: account.display_name } : {},
+          ...[account.avatar_url, account.picture, account.image, body.avatar_url, body.picture, body.image].find((value) => typeof value === "string") !== void 0 ? { avatarUrl: [account.avatar_url, account.picture, account.image, body.avatar_url, body.picture, body.image].find((value) => typeof value === "string") } : {},
+          ...typeof account.email === "string" ? { email: account.email } : {},
+          ...typeof account.image_url === "string" ? { imageUrl: account.image_url } : {},
+          ...typeof account.created_at === "string" ? { accountCreatedAt: account.created_at } : {},
+          ...typeof account.requires_phone_binding === "boolean" ? { requiresPhoneBinding: account.requires_phone_binding } : {},
+          ...typeof organization?.has_extra_usage_enabled === "boolean" ? { hasExtraUsageEnabled: organization.has_extra_usage_enabled } : {},
+          ...typeof organization?.billing_type === "string" ? { billingType: organization.billing_type } : {},
+          ...typeof organization?.subscription_created_at === "string" ? { subscriptionCreatedAt: organization.subscription_created_at } : {},
+          ...typeof organization?.rate_limit_tier === "string" ? { rateLimitTier: organization.rate_limit_tier } : {},
+          ...typeof organization?.name === "string" ? { organizationName: organization.name } : {}
+        };
+      }
+    });
+    this.store = cfg.store ?? defaultTokenStore();
     this.retryPolicy = effectivePolicy(cfg.retryPolicy ?? null);
   }
   /**
@@ -2415,6 +3251,11 @@ var Client = class _Client {
    */
   static async create(cfg = {}) {
     const c = new _Client(cfg);
+    if (c.credentialMode === "external") return c;
+    if (c.credentialMode === "versioned") {
+      await c.reconcileCredentials();
+      return c;
+    }
     try {
       const tokens = await c.store.load();
       if (tokens) {
@@ -2428,6 +3269,63 @@ var Client = class _Client {
     }
     return c;
   }
+  /** Read the durable authority. Available only in explicit versioned mode. */
+  async getCredentialSnapshot(signal) {
+    if (!this.versionedCredentialStore) {
+      throw new Error("getCredentialSnapshot requires credentialMode=versioned");
+    }
+    return this.versionedCredentialStore.readSnapshot(signal);
+  }
+  /** Reconcile memory from durable state; storage errors never clear confirmed memory. */
+  async reconcileCredentials(signal) {
+    const snapshot = await this.lifecycle.reconcile(signal);
+    this.adoptCredentialOwner(snapshot);
+    this.tokens = snapshot.credentialState === "ready" ? snapshot.tokenSet : null;
+    return snapshot;
+  }
+  ownerKey(snapshot) {
+    return `${snapshot.storeInstanceId}\0${snapshot.authSessionId ?? ""}\0${snapshot.principal?.issuer ?? ""}\0${snapshot.principal?.subject ?? ""}\0${snapshot.principal?.organizationId ?? ""}`;
+  }
+  adoptCredentialOwner(snapshot) {
+    const next = this.ownerKey(snapshot);
+    if (this.credentialOwnerKey !== null && this.credentialOwnerKey !== next) {
+      this.modelCache = [];
+      this.modelCacheTimeMs = 0;
+      this.coefCacheData = null;
+      this.coefCacheTimeMs = 0;
+    }
+    this.credentialOwnerKey = next;
+  }
+  async ensureCredential(signal) {
+    if (!this.lifecycle) return this.ensureToken(signal);
+    const token = await this.lifecycle.ensure(signal, void 0, this.credentialRequestOwner ?? void 0);
+    const snapshot = await this.lifecycle.read(signal);
+    this.adoptCredentialOwner(snapshot);
+    this.tokens = snapshot.credentialState === "ready" ? snapshot.tokenSet : null;
+    return token;
+  }
+  subscribeCredentialState(listener) {
+    if (!this.lifecycle) throw new Error("subscribeCredentialState requires credentialMode=versioned");
+    return this.lifecycle.subscribe(listener);
+  }
+  async retryCredentialIdentity(signal) {
+    const snapshot = await this.getCredentialSnapshot(signal);
+    if (!snapshot.authSessionId) throw new Error("not authorized");
+    const ready = await this.lifecycle.bindIdentity(snapshot.authSessionId, signal);
+    this.adoptCredentialOwner(ready);
+    this.tokens = ready.credentialState === "ready" ? ready.tokenSet : null;
+    return ready;
+  }
+  async logoutCredential(signal, expected) {
+    if (!this.lifecycle) throw new Error("logoutCredential requires credentialMode=versioned");
+    const result = await this.lifecycle.logout(signal, expected);
+    if (result.status === "committed" || result.status === "already_signed_out") {
+      const current = await this.lifecycle.read(signal);
+      this.adoptCredentialOwner(current);
+      this.tokens = null;
+    }
+    return result;
+  }
   // ===========================================================================
   // 授权生命周期
   // ===========================================================================
@@ -2478,6 +3376,44 @@ var Client = class _Client {
     return this.loginInternal(appName, scopes, { handler, ...opts }, signal);
   }
   async loginInternal(appName, scopes, opts, signal) {
+    if (this.lifecycle) {
+      const attempt = await this.lifecycle.reserveLogin(signal);
+      let installHookRejected = false;
+      try {
+        const registration = await register(attempt.metadata, appName, signal, this.fetchImpl);
+        await this.lifecycle.assertLogin(attempt.attemptId, signal);
+        const authorization = await authorize(attempt.metadata, registration.client_id, scopes, { ...opts, handler: opts?.handler ?? void 0, signal });
+        await this.lifecycle.assertLogin(attempt.attemptId, signal);
+        const response = await exchangeCode(attempt.metadata, registration.client_id, authorization.result.code, authorization.result.redirectURI, authorization.verifier, signal, this.fetchImpl);
+        if (!Number.isFinite(response.expires_in) || response.expires_in <= 0) throw new Error("invalid_response");
+        await this.lifecycle.assertLogin(attempt.attemptId, signal);
+        try {
+          await this.beforeCredentialInstall?.({
+            accessToken: response.access_token,
+            attemptId: attempt.attemptId,
+            serverURL: this.serverURL,
+            clientId: registration.client_id
+          }, signal);
+        } catch (error) {
+          installHookRejected = true;
+          throw error;
+        }
+        await this.lifecycle.assertLogin(attempt.attemptId, signal);
+        const ready = await this.lifecycle.installLogin(attempt.attemptId, newTokenSet(response, registration.client_id, this.serverURL), signal);
+        const current = await this.getCredentialSnapshot(signal);
+        if (current.revision !== ready.revision || current.authSessionId !== ready.authSessionId) throw new Error("superseded");
+        this.tokens = ready.tokenSet;
+        opts?.handler?.({ type: EventComplete, attemptId: attempt.attemptId });
+      } catch (error) {
+        const current = await this.getCredentialSnapshot();
+        if (current.loginAttempt?.attemptId === attempt.attemptId || current.lastLoginAttemptId === attempt.attemptId) {
+          opts?.handler?.(installHookRejected ? { type: EventError, attemptId: attempt.attemptId, err_code: "credential_install_rejected", error: "credential_install_rejected" } : { type: EventError, attemptId: attempt.attemptId, error: "credential_login_failed" });
+        }
+        await this.lifecycle.cancelLogin(attempt.attemptId);
+        throw error;
+      }
+      return;
+    }
     const handler = opts?.handler ?? void 0;
     const emit = (e) => {
       if (handler) handler(e);
@@ -2586,6 +3522,11 @@ var Client = class _Client {
   }
   /** 吊销 token 并清除本地存储 */
   async logout(signal) {
+    if (this.lifecycle) {
+      await this.logoutCredential(signal);
+      await this.reconcileCredentials(signal);
+      return;
+    }
     const tokens = this.tokens;
     let meta = this.meta;
     this.tokens = null;
@@ -2623,6 +3564,13 @@ var Client = class _Client {
    * 避免应用启动期 "login + 多个 API 调用" 并发场景下 4+ 条 "not authorized" 误报.
    */
   async ensureToken(signal) {
+    if (this.credentialMode === "external") {
+      if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
+      const token = await this.accessTokenProvider(signal);
+      if (typeof token !== "string" || token.length === 0) throw new Error("external access token unavailable");
+      return token;
+    }
+    if (this.lifecycle) return this.lifecycle.ensure(signal, void 0, this.credentialRequestOwner ?? void 0);
     let tokens = this.tokens;
     const ready = this.tokenReady.promise;
     const inFlight = this.loginInFlight;
@@ -2670,7 +3618,14 @@ var Client = class _Client {
     );
   }
   /** 强制刷新 token (用于 401 重试) */
-  async forceRefresh(signal) {
+  async forceRefresh(signal, rejectedToken) {
+    if (this.credentialMode === "external") throw new Error("external credentials cannot be refreshed by the SDK");
+    if (this.lifecycle) {
+      await this.lifecycle.forceRefresh(signal, rejectedToken, this.credentialRequestOwner ?? void 0);
+      const snapshot = await this.lifecycle.read(signal);
+      this.tokens = snapshot.credentialState === "ready" ? snapshot.tokenSet : null;
+      return;
+    }
     return this.withMu(
       () => this.storeWithLock(async () => {
         await this.syncFromDisk();
@@ -2865,6 +3820,7 @@ var Client = class _Client {
    */
   async listModelsWithStatus(signal, opts) {
     const includeLocked = opts?.includeLocked === true;
+    const requestOwner = this.lifecycle ? this.ownerKey(await this.getCredentialSnapshot(signal)) : null;
     const path = includeLocked ? "/managed-models?picker=1" : "/managed-models";
     const { result, headers } = await this.doJSONFull(
       "GET",
@@ -2873,6 +3829,11 @@ var Client = class _Client {
       signal
     );
     const normalized = normalizeInputModalities(result.data);
+    if (requestOwner !== null) {
+      const current = await this.getCredentialSnapshot(signal);
+      if (this.ownerKey(current) !== requestOwner) throw new Error("superseded");
+      this.adoptCredentialOwner(current);
+    }
     if (!includeLocked) {
       this.modelCache = normalized;
       this.modelCacheTimeMs = Date.now();
@@ -3292,12 +4253,11 @@ var Client = class _Client {
       throw classifyTransport("POST " + endpoint, url, e);
     }
     if (resp.status === 401 && !retried) {
+      const bodyBytes = resp.body ? await readLimited(resp.body, maxErrorBodySize) : new Uint8Array();
+      const authError = parseHTTPErrorWithHeader(resp.status, bodyBytes, resp.headers);
+      if (!isUserAccessTokenRejected(authError)) throw authError;
       try {
-        await resp.body?.cancel();
-      } catch {
-      }
-      try {
-        await this.forceRefresh(signal);
+        await this.forceRefresh(signal, token);
       } catch (refreshErr) {
         throw new Error(
           `stream: unauthorized and refresh failed: ${refreshErr instanceof Error ? refreshErr.message : String(refreshErr)}`
@@ -3363,12 +4323,11 @@ var Client = class _Client {
       throw classifyTransport("POST " + endpoint, url, e);
     }
     if (resp.status === 401 && !retried) {
+      const bodyBytes = resp.body ? await readLimited(resp.body, maxErrorBodySize) : new Uint8Array();
+      const authError = parseHTTPErrorWithHeader(resp.status, bodyBytes, resp.headers);
+      if (!isUserAccessTokenRejected(authError)) throw authError;
       try {
-        await resp.body?.cancel();
-      } catch {
-      }
-      try {
-        await this.forceRefresh(signal);
+        await this.forceRefresh(signal, token);
       } catch (refreshErr) {
         throw new Error(
           `messages stream: unauthorized and refresh failed: ${refreshErr instanceof Error ? refreshErr.message : String(refreshErr)}`
@@ -3458,7 +4417,9 @@ var Client = class _Client {
     if (!base.endsWith("/api/v4")) {
       base += "/api/v4";
     }
-    return base + path;
+    const url = base + path;
+    this.assertCredentialURL(url);
+    return url;
   }
   /**
    * Compliance API URL 拼接。
@@ -3471,7 +4432,14 @@ var Client = class _Client {
    */
   complianceURL(path) {
     const base = this.complianceBaseURL ?? this.serverURL + "/admin-api";
-    return base + path;
+    const url = base + path;
+    this.assertCredentialURL(url);
+    return url;
+  }
+  assertCredentialURL(url) {
+    if (this.credentialMode !== "legacy" && new URL(url).origin !== this.credentialAuthority) {
+      throw new Error("credential request authority changed");
+    }
   }
   /** GET/POST/... 通用 JSON 调用 (返回 result 已 typed) */
   async doJSON(method, path, body, signal) {
@@ -3500,12 +4468,11 @@ var Client = class _Client {
         ctl.signal
       );
       if (resp.status === 401 && !retried) {
+        const bodyBytes = resp.body ? await readLimited(resp.body, maxErrorBodySize) : new Uint8Array();
+        const authError = parseHTTPErrorWithHeader(resp.status, bodyBytes, resp.headers);
+        if (!isUserAccessTokenRejected(authError)) throw authError;
         try {
-          await resp.body?.cancel();
-        } catch {
-        }
-        try {
-          await this.forceRefresh(ctl.signal);
+          await this.forceRefresh(ctl.signal, token);
         } catch (refreshErr) {
           throw new Error(
             `unauthorized and refresh failed: ${refreshErr instanceof Error ? refreshErr.message : String(refreshErr)}`
@@ -3570,12 +4537,11 @@ var Client = class _Client {
         ctl.signal
       );
       if (resp.status === 401 && !retried) {
+        const bodyBytes = resp.body ? await readLimited(resp.body, maxErrorBodySize) : new Uint8Array();
+        const authError = parseHTTPErrorWithHeader(resp.status, bodyBytes, resp.headers);
+        if (!isUserAccessTokenRejected(authError)) throw authError;
         try {
-          await resp.body?.cancel();
-        } catch {
-        }
-        try {
-          await this.forceRefresh(ctl.signal);
+          await this.forceRefresh(ctl.signal, token);
         } catch (refreshErr) {
           throw new Error(
             `unauthorized and refresh failed: ${refreshErr instanceof Error ? refreshErr.message : String(refreshErr)}`
@@ -3650,6 +4616,7 @@ var Client = class _Client {
    * 6 处原始 fetch() 全部走此 helper
    */
   async doRequest(req, signal) {
+    if (new Headers(req.headers).has("Authorization")) this.assertCredentialURL(req.url);
     try {
       return await this.fetchImpl(req.url, {
         method: req.method,
@@ -4647,12 +5614,11 @@ async function uploadSkillInternal(c, zipData, scope, intent, retried, signal) {
       throw classifyTransport("POST /skill-store/upload", url, e);
     }
     if (resp.status === 401 && !retried) {
+      const bodyBytes = resp.body ? await readLimited(resp.body, maxErrorBodySize) : new Uint8Array();
+      const authError = parseHTTPErrorWithHeader(resp.status, bodyBytes, resp.headers);
+      if (!isUserAccessTokenRejected(authError)) throw authError;
       try {
-        await resp.body?.cancel();
-      } catch {
-      }
-      try {
-        await c.forceRefresh(ctl.signal);
+        await c.forceRefresh(ctl.signal, token);
       } catch (refreshErr) {
         throw new Error(
           `upload: unauthorized and refresh failed: ${refreshErr instanceof Error ? refreshErr.message : String(refreshErr)}`
@@ -4823,9 +5789,7 @@ Client.prototype.updateNotificationPreference = async function(typeCode, pref, s
 
 // src/notifications/ws.ts
 Client.prototype.connect = async function(cfg, signal) {
-  if (this.ws) {
-    await this.disconnect();
-  }
+  const oldDisconnect = this.ws ? this.disconnect() : Promise.resolve();
   const noop = () => {
   };
   const filledCfg = {
@@ -4841,21 +5805,31 @@ Client.prototype.connect = async function(cfg, signal) {
   const done = new Promise((r) => {
     resolveDone = r;
   });
-  const abort = new AbortController();
+  const abort2 = new AbortController();
   if (signal) {
-    if (signal.aborted) abort.abort();
-    else signal.addEventListener("abort", () => abort.abort());
+    if (signal.aborted) abort2.abort();
+    else signal.addEventListener("abort", () => abort2.abort());
   }
   const ws = {
     conn: null,
     cfg: filledCfg,
-    abort,
+    abort: abort2,
     done,
     doneResolve: resolveDone,
-    connected: false
+    connected: false,
+    owner: null
   };
-  await wsConnectOnce(this, ws);
   this.ws = ws;
+  try {
+    await oldDisconnect;
+    await assertCurrent(this, ws);
+    await wsConnectOnce(this, ws);
+  } catch (error) {
+    ws.abort.abort();
+    if (this.ws === ws) this.ws = null;
+    ws.doneResolve();
+    throw error;
+  }
   void wsLoop(this, ws);
 };
 Client.prototype.disconnect = async function() {
@@ -4893,15 +5867,47 @@ function getWebSocketCtor() {
   }
   return WSCtor;
 }
+function sameOwner(a, b) {
+  return a?.storeInstanceId === b?.storeInstanceId && a?.authSessionId === b?.authSessionId && a?.principal?.issuer === b?.principal?.issuer && a?.principal?.subject === b?.principal?.subject && a?.principal?.organizationId === b?.principal?.organizationId;
+}
+async function readOwner(c, signal) {
+  if (c.credentialMode !== "versioned") return null;
+  const snapshot = await c.getCredentialSnapshot(signal);
+  return {
+    storeInstanceId: snapshot.storeInstanceId,
+    authSessionId: snapshot.authSessionId,
+    principal: snapshot.principal
+  };
+}
+async function assertCurrent(c, ws) {
+  if (ws.abort.signal.aborted || c.ws !== ws) throw new Error("websocket connection superseded");
+  if (ws.owner !== null && !sameOwner(ws.owner, await readOwner(c, ws.abort.signal))) {
+    ws.abort.abort();
+    throw new Error("websocket credential owner changed");
+  }
+}
 async function wsConnectOnce(c, ws) {
+  const observedOwner = await readOwner(c, ws.abort.signal);
+  if (ws.owner === null) ws.owner = observedOwner;
+  else if (!sameOwner(ws.owner, observedOwner)) throw new Error("websocket credential owner changed");
+  await assertCurrent(c, ws);
   const url = wsURL(c);
   const WSCtor = getWebSocketCtor();
-  const ticketResp = await c.doJSON(
-    "POST",
-    "/ws/stream-ticket",
-    null,
-    ws.abort.signal
-  );
+  const token = await c.ensureToken(ws.abort.signal);
+  await assertCurrent(c, ws);
+  const ticketURL = c.apiURL("/ws/stream-ticket");
+  await assertCurrent(c, ws);
+  const ticketHTTP = await c.doRequest({
+    method: "POST",
+    url: ticketURL,
+    headers: { Authorization: `Bearer ${token}` }
+  }, ws.abort.signal);
+  if (!ticketHTTP.ok) {
+    const body = ticketHTTP.body ? await readLimited(ticketHTTP.body, maxErrorBodySize) : new Uint8Array();
+    throw parseHTTPErrorWithHeader(ticketHTTP.status, body, ticketHTTP.headers);
+  }
+  const ticketResp = await ticketHTTP.json();
+  await assertCurrent(c, ws);
   const ticket = ticketResp.data.ticket;
   const u = new URL(url);
   u.searchParams.set("ticket", ticket);
@@ -4922,11 +5928,28 @@ async function wsConnectOnce(c, ws) {
         reject(new Error("dial: handshake timeout"));
       }
     }, 3e4);
+    const abortHandshake = () => {
+      clearTimeout(handshakeTimer);
+      try {
+        conn.close();
+      } catch {
+      }
+      reject(new Error("websocket connection aborted"));
+    };
+    ws.abort.signal.addEventListener("abort", abortHandshake, { once: true });
     conn.addEventListener("open", () => {
+      if (ws.abort.signal.aborted || c.ws !== ws) {
+        try {
+          conn.close();
+        } catch {
+        }
+        return;
+      }
       opened = true;
     });
     conn.addEventListener("error", (e) => {
       clearTimeout(handshakeTimer);
+      ws.abort.signal.removeEventListener("abort", abortHandshake);
       reject(new Error(`dial: ${e.message ?? "connection error"}`));
     });
     conn.addEventListener("message", (e) => {
@@ -4935,6 +5958,7 @@ async function wsConnectOnce(c, ws) {
         const welcome = JSON.parse(msg);
         if (welcome.type !== "welcome") {
           clearTimeout(handshakeTimer);
+          ws.abort.signal.removeEventListener("abort", abortHandshake);
           try {
             conn.close();
           } catch {
@@ -4942,31 +5966,34 @@ async function wsConnectOnce(c, ws) {
           reject(new Error(`unexpected first message: ${welcome.type}`));
           return;
         }
-        clearTimeout(handshakeTimer);
-        ws.conn = conn;
-        ws.connected = true;
-        if (ws.cfg.topics.length > 0) {
-          try {
-            conn.send(
-              JSON.stringify({
-                type: "subscribe",
-                topics: ws.cfg.topics
-              })
-            );
-          } catch (sendErr) {
-            ws.conn = null;
-            ws.connected = false;
+        void assertCurrent(c, ws).then(() => {
+          clearTimeout(handshakeTimer);
+          ws.abort.signal.removeEventListener("abort", abortHandshake);
+          ws.conn = conn;
+          ws.connected = true;
+          if (ws.cfg.topics.length > 0) {
             try {
-              conn.close();
-            } catch {
+              conn.send(
+                JSON.stringify({
+                  type: "subscribe",
+                  topics: ws.cfg.topics
+                })
+              );
+            } catch (sendErr) {
+              ws.conn = null;
+              ws.connected = false;
+              try {
+                conn.close();
+              } catch {
+              }
+              reject(new Error(`send subscribe: ${sendErr instanceof Error ? sendErr.message : String(sendErr)}`));
+              return;
             }
-            reject(new Error(`send subscribe: ${sendErr instanceof Error ? sendErr.message : String(sendErr)}`));
-            return;
           }
-        }
-        ws.cfg.onConnect();
-        console.log(`[acosmi-sdk] websocket connected, connId=${welcome.connId ?? ""}`);
-        resolve();
+          ws.cfg.onConnect();
+          console.log(`[acosmi-sdk] websocket connected, connId=${welcome.connId ?? ""}`);
+          resolve();
+        }).catch(reject);
       } catch (parseErr) {
         clearTimeout(handshakeTimer);
         try {
@@ -4981,7 +6008,7 @@ async function wsConnectOnce(c, ws) {
 async function wsLoop(c, ws) {
   try {
     while (true) {
-      await wsReadLoop(ws);
+      await wsReadLoop(c, ws);
       if (ws.abort.signal.aborted) return;
       if (ws.conn) {
         try {
@@ -5012,7 +6039,7 @@ async function wsLoop(c, ws) {
     ws.doneResolve();
   }
 }
-async function wsReadLoop(ws) {
+async function wsReadLoop(c, ws) {
   const conn = ws.conn;
   if (!conn) return;
   return new Promise((resolve) => {
@@ -5020,10 +6047,17 @@ async function wsReadLoop(ws) {
       try {
         const data = e.data;
         const event = JSON.parse(data);
-        try {
-          ws.cfg.onEvent(event);
-        } catch {
-        }
+        void assertCurrent(c, ws).then(() => {
+          try {
+            ws.cfg.onEvent(event);
+          } catch {
+          }
+        }).catch(() => {
+          try {
+            conn.close();
+          } catch {
+          }
+        });
       } catch {
       }
     };
@@ -5236,6 +6270,7 @@ function isTerminalRemoteEvent(ev) {
 }
 
 // src/agent-runs/client.ts
+init_errors();
 var agentRunsByClient = /* @__PURE__ */ new WeakMap();
 Object.defineProperty(Client.prototype, "agentRuns", {
   configurable: true,
@@ -5615,11 +6650,10 @@ var AgentRunsClient = class {
     }
     const resp = await this.client.doRequest({ method, url, headers, body: bodyStr }, signal);
     if (resp.status === 401 && opts.retryOn401 && !retried) {
-      try {
-        await resp.body?.cancel();
-      } catch {
-      }
-      await this.client.forceRefresh(signal);
+      const bodyBytes = resp.body ? await readLimited(resp.body, maxErrorBodySize) : new Uint8Array();
+      const authError = parseHTTPErrorWithHeader(resp.status, bodyBytes, resp.headers);
+      if (!isUserAccessTokenRejected(authError)) throw authError;
+      await this.client.forceRefresh(signal, token);
       return this.requestRawInner(method, path, body, signal, opts, true);
     }
     if (resp.status < 200 || resp.status >= 300) {
@@ -6246,6 +7280,7 @@ function isComplianceBusinessError(err) {
 }
 
 // src/compliance/client.ts
+init_errors();
 var cache = /* @__PURE__ */ new WeakMap();
 Object.defineProperty(Client.prototype, "compliance", {
   configurable: true,
@@ -7062,11 +8097,10 @@ var ComplianceClient = class {
     }
     const resp = await this.client.doRequest({ method, url, headers, body: bodyStr }, signal);
     if (resp.status === 401 && opts.retryOn401 && !retried) {
-      try {
-        await resp.body?.cancel();
-      } catch {
-      }
-      await this.client.forceRefresh(signal);
+      const bodyBytes = resp.body ? await readLimited(resp.body, maxErrorBodySize) : new Uint8Array();
+      const authError = parseHTTPErrorWithHeader(resp.status, bodyBytes, resp.headers);
+      if (!isUserAccessTokenRejected(authError)) throw authError;
+      await this.client.forceRefresh(signal, token);
       return this.executeJsonInner(method, path, body, signal, opts, true);
     }
     if (resp.status < 200 || resp.status >= 300) {
@@ -7987,6 +9021,7 @@ exports.isRegion = isRegion;
 exports.isSSECommentLine = isSSECommentLine;
 exports.isSSLError = isSSLError;
 exports.isTerminalRemoteEvent = isTerminalRemoteEvent;
+exports.isUserAccessTokenRejected = isUserAccessTokenRejected;
 exports.isValidTokenSet = isValidTokenSet;
 exports.isWindowLimitError = isWindowLimitError;
 exports.isWindowLimitStreamError = isWindowLimitStreamError;
@@ -8004,6 +9039,7 @@ exports.parseNotificationEvent = parseNotificationEvent;
 exports.parseRemoteControlEvent = parseRemoteControlEvent;
 exports.parseSettlement = parseSettlement;
 exports.parseSourcesEvent = parseSourcesEvent;
+exports.readGatewayErrorContract = readGatewayErrorContract;
 exports.refreshToken = refreshToken;
 exports.register = register;
 exports.registerWebOAuthClient = registerWebOAuthClient;