@acosmi/sdk-ts 1.4.1 → 1.5.0

package/dist/node/index.d.ts

@@ -1,52 +1,188 @@
-import { M as ManagedModel, I as InputModality, S as ServerMetadata, T as TokenSet, a as TokenResponse, C as ClientRegistration, B as BusinessError, b as ModelCoefficient, Q as QuotaSummary, c as ModelCapabilities, d as ChatRequest, P as ProviderAdapter, e as ChatResponse, A as AnthropicResponse, f as StreamEvent, g as SourcesEvent, h as StreamSettlement, E as EntitlementBalance, i as BalanceDetail, j as EntitlementItem, k as ConsumeRecordPage, l as ModelByQuotaResponse, m as ModelBucket, n as TokenPackage, o as PayPayload, O as Order, p as OrderStatus, W as WalletStats, q as Transaction, r as SkillStoreQuery, s as SkillStoreItem, t as SkillBrowseResponse, u as SkillBrowseListResponse, v as SkillSummary, w as CertificationStatus, G as GenerateSkillRequest, x as GenerateSkillResult, y as OptimizeSkillRequest, z as OptimizeSkillResult, D as ToolView, N as NotificationList, F as DeviceRegistration, H as NotificationPreference, J as WSEvent } from './index-CbG9NqE-.js';
-export { K as APIResponse, L as AnthropicContentBlock, R as AnthropicUsage, U as BucketClassCommercial, V as BucketClassGeneric, X as BucketInfo, Y as BucketRow, Z as ChatContentBlock, _ as ChatMessage, $ as ChatUsage, a0 as ConsumeRecord, a1 as EffortConfig, a2 as GeoLoc, a3 as HTTPError, a4 as ModelNotFoundError, a5 as NetworkError, a6 as Notification, a7 as NotificationUnreadCount, a8 as OpenAIChatChoice, a9 as OpenAIChatMessage, aa as OpenAIChatResponse, ab as OpenAIFunctionCall, ac as OpenAIStreamChoice, ad as OpenAIStreamChunk, ae as OpenAIStreamDelta, af as OpenAIStreamToolCall, ag as OpenAIToolCall, ah as OpenAIUsage, ai as OrderTerminalError, aj as OutputConfig, ak as ProviderFormat, al as RateLimitError, am as ServerTool, an as ServerToolTypeWebSearch, ao as SkillStoreListItem, ap as StreamError, aq as ThinkingConfig, ar as ThinkingHigh, as as ThinkingHighMinMaxTokens, at as ThinkingMax, au as ThinkingMaxFallbackMaxTokens, av as ThinkingOff, aw as ToolListResponse, ax as ToolProvider, ay as WebSearchConfig, az as WebSearchSource, aA as YudaoPageResult, aB as anthropicResponseTextContent, aC as anthropicResponseThinkingContent, aD as anthropicResponseToolUseBlocks, aE as apiResponseBusinessError, aF as apiResponseGetMessage, aG as bucketInfoIsCommercial, aH as bucketRowIsCommercial, aI as getAdapter, aJ as getAdapterForModel, aK as newThinkingConfig, aL as newWebSearchTool, aM as parseNotificationEvent, aN as parseSettlement, aO as parseSourcesEvent, aP as tokenSetIsExpired } from './index-CbG9NqE-.js';
+import { A as AnthropicResponse } from './openai-vfUUgdvL.js';
+export { a as AnthropicContentBlock, b as AnthropicUsage, O as OpenAIAdapter, c as anthropicResponseTextContent, d as anthropicResponseThinkingContent, e as anthropicResponseToolUseBlocks } from './openai-vfUUgdvL.js';
+import { M as ManagedModel, Q as QuotaSummary, a as ModelCapabilities, C as ChatRequest, P as ProviderAdapter, b as ChatResponse, S as StreamEvent, c as SourcesEvent, d as StreamSettlement, I as InputModality } from './index-DEA6LXw6.js';
+export { B as BucketClassCommercial, e as BucketClassGeneric, f as BucketInfo, g as BucketRow, h as ChatContentBlock, i as ChatMessage, j as ChatUsage, E as EffortConfig, G as GeoLoc, O as OutputConfig, k as ProviderFormat, l as ServerTool, m as ServerToolTypeWebSearch, T as ThinkingConfig, n as ThinkingHigh, o as ThinkingHighMinMaxTokens, p as ThinkingMax, q as ThinkingMaxFallbackMaxTokens, r as ThinkingOff, W as WebSearchConfig, s as WebSearchSource, t as bucketInfoIsCommercial, u as bucketRowIsCommercial, v as getAdapter, w as getAdapterForModel, x as newThinkingConfig, y as newWebSearchTool, z as parseSettlement, A as parseSourcesEvent } from './index-DEA6LXw6.js';
 import { M as MinimalSanitizeConfig } from './index-nvLKgCm9.js';
 export { i as sanitize } from './index-nvLKgCm9.js';
 export { AnthropicAdapter } from './adapters/anthropic.js';
-export { OpenAIAdapter } from './adapters/openai.js';
 
+/** 权益余额 (聚合) */
+interface EntitlementBalance {
+    totalTokenQuota: number;
+    totalTokenUsed: number;
+    totalTokenRemaining: number;
+    totalCallQuota: number;
+    totalCallUsed: number;
+    totalCallRemaining: number;
+    activeEntitlements: number;
+}
+/** 单条权益明细 */
+interface EntitlementItem {
+    id: string;
+    type: string;
+    status: string;
+    tokenQuota: number;
+    tokenUsed: number;
+    tokenRemaining: number;
+    callQuota: number;
+    callUsed: number;
+    callRemaining: number;
+    expiresAt?: string;
+    sourceId?: string;
+    sourceType?: string;
+    remark?: string;
+    createdAt: string;
+}
+/** 详细余额 (含每条权益明细) */
+interface BalanceDetail {
+    totalTokenQuota: number;
+    totalTokenUsed: number;
+    totalTokenRemaining: number;
+    totalCallQuota: number;
+    totalCallUsed: number;
+    totalCallRemaining: number;
+    activeEntitlements: number;
+    entitlements: EntitlementItem[];
+}
+/** 核销记录 */
+interface ConsumeRecord {
+    id: string;
+    entitlementId: string;
+    requestId: string;
+    modelId?: string;
+    tokensConsumed: number;
+    status: string;
+    createdAt: string;
+}
+/** 核销记录分页响应 */
+interface ConsumeRecordPage {
+    records: ConsumeRecord[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
 /**
- * 判断 ManagedModel 是否声明支持指定输入模态.
- *
- * 语义:
- *   - model 为 null/undefined → false
- *   - model.inputModalities 缺失或非数组 → false (保守, 未声明不当支持)
- *   - 大小写敏感 (上游契约即小写 'text' | 'image')
- */
-declare function modelSupportsInputModality(model: ManagedModel | null | undefined, modality: InputModality): boolean;
-/** 等价 modelSupportsInputModality(model, 'image') — 调用方常见快捷判定. */
-declare function modelSupportsImageInput(model: ManagedModel | null | undefined): boolean;
-/**
- * 在 catalog 中按 catalog 顺序查找首个支持指定模态的模型.
- *
- * 选择规则:
- *   1. isEnabled !== false (默认开, 显式 false 才剔除)
- *   2. inputModalities 包含指定模态
- *   3. 命中后按 catalog 顺序返回第一个; 未命中返 null
- *
- * 注意: 该 helper 不读 isDefault, 调用方需要 "默认优先" 请用
- * findDesktopVisualUnderstandingModel 或自行排序.
- */
-declare function findFirstModelByInputModality(models: ManagedModel[], modality: InputModality): ManagedModel | null;
-/**
- * 在 catalog 中选出最适合做 "桌面视觉理解 sidecar" 的模型.
- *
- * 设计目的: CrabCode desktop automation 链路里, 主模型不一定多模态;
- * 截图先送 sidecar 解析成结构化 UI 描述, 再喂主模型. 这里选 sidecar 模型
- * 严格走运营标注的 supports_desktop_visual_understanding capability, 不靠
- * 模型名猜.
- *
- * 选择规则 (按用户指定顺序):
- *   1. isEnabled !== false
- *   2. capabilities.supports_desktop_visual_understanding === true
- *   3. inputModalities 包含 'image' (必须真能吃图)
- *   4. 命中集合中优先 isDefault === true; 否则返回 catalog 顺序第一个
+ * 单桶视图 (用户多桶 hero / 模型切换提示用)
  *
- * 全部不满足返 null. 调用方收到 null 应:
- *   - 提示用户在管理后台/网关侧开启桌面视觉 sidecar 模型, 或
- *   - 降级停掉依赖截图的工作流, 而不是硬选一个非视觉模型送图.
+ * 字段名仍叫 ETU 但 T3 死代码清除后 = raw token (V29 系数管理已退役)。
  */
-declare function findDesktopVisualUnderstandingModel(models: ManagedModel[]): ManagedModel | null;
+interface ModelBucket {
+    bucketId: string;
+    entitlementId: string;
+    /** "*" = 通配 */
+    modelId: string;
+    /** COMMERCIAL / GENERIC */
+    bucketClass: string;
+    tokenQuota: number;
+    tokenUsed: number;
+    tokenRemaining: number;
+    callQuota: number;
+    callUsed: number;
+    callRemaining: number;
+    allowedModelsJson?: string;
+}
+/** GetByModel 响应; primaryBucket 在 bucketId 为空时表示无可用桶。 */
+interface ModelByQuotaResponse {
+    modelId: string;
+    /** 折算后剩余 (调度判定用) */
+    etuRemaining: number;
+    /** 反系数估算的原始 token (UI 展示用) */
+    rawTokenRemaining: number;
+    hasQuota: boolean;
+    primaryBucket?: ModelBucket;
+}
+/** 单条模型系数 (SDK TTL 8s 缓存源) */
+interface ModelCoefficient {
+    modelId: string;
+    tenantId: string;
+    inputCoef: number;
+    outputCoef: number;
+    cacheReadCoef: number;
+    cacheCreationCoef: number;
+    version: number;
+    effectiveAt: string;
+}
+/** 流量包商品。price 用 string (Go json.Number) 避免浮点精度丢失。 */
+interface TokenPackage {
+    id: string;
+    name: string;
+    description?: string;
+    tokenQuota: number;
+    callQuota?: number;
+    price: string;
+    validDays: number;
+    isEnabled: boolean;
+    sortOrder?: number;
+}
+/** 订单。amount 用 string (Go json.Number) 避免精度丢失。 */
+interface Order {
+    id: string;
+    packageId: string;
+    packageName?: string;
+    amount: string;
+    status: string;
+    payUrl?: string;
+    createdAt: string;
+}
+/** 订单状态 */
+interface OrderStatus {
+    orderId: string;
+    status: string;
+}
+/** 下单请求 */
+interface PayPayload {
+    payMethod?: string;
+}
+/** 钱包统计。金额使用 string (Go json.Number) 避免浮点精度丢失 (金融安全) */
+interface WalletStats {
+    balance: string;
+    monthlyConsumption: string;
+    monthlyRecharge: string;
+    transactionCount: number;
+}
+/** 交易记录 */
+interface Transaction {
+    id: string;
+    type: string;
+    amount: string;
+    remark?: string;
+    createdAt: string;
+}
+
+/** OAuth Authorization Server 元数据 (RFC 8414) */
+interface ServerMetadata {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    revocation_endpoint: string;
+    registration_endpoint: string;
+    scopes_supported: string[];
+}
+/** OAuth token 响应 */
+interface TokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    refresh_token?: string;
+    scope?: string;
+}
+/** 持久化 token 对 */
+interface TokenSet {
+    access_token: string;
+    refresh_token: string;
+    /** ISO 8601 格式 */
+    expires_at: string;
+    scope: string;
+    client_id: string;
+    server_url: string;
+}
+/** token 是否已过期 (提前 30 秒视为过期) */
+declare function tokenSetIsExpired(t: TokenSet): boolean;
+/** 动态注册响应 */
+interface ClientRegistration {
+    client_id: string;
+    client_secret?: string;
+}
 
 /** OAuth metadata profile — 决定 well-known 端点的路径后缀 */
 type OAuthMetadataProfile = 'web' | 'desktop';
@@ -245,694 +381,311 @@ declare function revokeToken(meta: ServerMetadata, token: string, signal?: Abort
  */
 declare function newTokenSet(resp: TokenResponse, clientID: string, serverURL: string): TokenSet;
 
-declare const ScopeAI = "ai";
-declare const ScopeSkills = "skills";
-declare const ScopeAccount = "account";
-/** @deprecated 旧细粒度 scope, 保留向后兼容, 新代码请用分组 scope */
-declare const ScopeModels = "models";
-/** @deprecated */
-declare const ScopeModelsChat = "models:chat";
-/** @deprecated */
-declare const ScopeEntitlements = "entitlements";
-/** @deprecated */
-declare const ScopeTokenPackages = "token-packages";
-/** @deprecated */
-declare const ScopeSkillStore = "skill_store";
-/** @deprecated */
-declare const ScopeTools = "tools";
-/** @deprecated */
-declare const ScopeToolsExecute = "tools:execute";
-/** @deprecated */
-declare const ScopeWallet = "wallet";
-/** @deprecated */
-declare const ScopeWalletReadonly = "wallet:readonly";
-/** @deprecated */
-declare const ScopeProfile = "profile";
-declare const ScopeComplianceEvidenceRead = "compliance:evidence:read";
-declare const ScopeComplianceEvidenceWrite = "compliance:evidence:write";
-declare const ScopeComplianceTimestampIssue = "compliance:timestamp:issue";
-declare const ScopeComplianceTimestampVerify = "compliance:timestamp:verify";
-declare const ScopeComplianceContractSigningRead = "compliance:contract_signing:read";
-declare const ScopeComplianceContractSigningWrite = "compliance:contract_signing:write";
-declare const ScopeComplianceSealManage = "compliance:seal:manage";
-declare const ScopeComplianceSealApprovalRequest = "compliance:seal_approval:request";
-declare const ScopeComplianceSealApprovalApprove = "compliance:seal_approval:approve";
-declare const ScopeComplianceSealUseExecute = "compliance:seal_use:execute";
-declare const ScopeComplianceReportsRead = "compliance:reports:read";
-declare const ScopeComplianceReportsWrite = "compliance:reports:write";
-declare const ScopeComplianceReportsPublish = "compliance:reports:publish";
-/** 类型联合：合规域细粒度 scope。Java compliance verifier 只按细粒度匹配, 不做分组展开。 */
-type ComplianceScope = typeof ScopeComplianceEvidenceRead | typeof ScopeComplianceEvidenceWrite | typeof ScopeComplianceTimestampIssue | typeof ScopeComplianceTimestampVerify | typeof ScopeComplianceContractSigningRead | typeof ScopeComplianceContractSigningWrite | typeof ScopeComplianceSealManage | typeof ScopeComplianceSealApprovalRequest | typeof ScopeComplianceSealApprovalApprove | typeof ScopeComplianceSealUseExecute | typeof ScopeComplianceReportsRead | typeof ScopeComplianceReportsWrite | typeof ScopeComplianceReportsPublish;
-/** 全部分组 scope (推荐) */
-declare function allScopes(): string[];
-/** 全部合规域 scope。OAuth 申请合规权限时使用; 谨慎一次性申请全部, 推荐按业务最小集合申请。 */
-declare function complianceScopes(): ComplianceScope[];
-/** 模型服务相关 scope */
-declare function modelScopes(): string[];
-/** 商城/钱包 scope */
-declare function commerceScopes(): string[];
-/** 技能/工具 scope */
-declare function skillScopes(): string[];
-
 /**
- * Compliance envelope 稳定业务状态。
+ * Token 持久化接口
+ * 桌面智能体可自行实现 (如 macOS Keychain / Windows Credential Manager)
  *
- * 字面量与 Java {@code EnvelopeStatusEnum} 的 `name()` 一致（这是 enum，是 wire 上的实际
- * 字符串）；前端按这些字符串分支展示文案。
+ * 跨端约定:
+ *   - Save: 写入持久化, 失败抛 Error
+ *   - Load: 读取, 不存在返回 null (与 Go IsNotExist 行为一致)
+ *   - Clear: 删除, 不存在不抛错 (Logout 后 Clear 不应报错, [RC-11])
+ *   - withLock (v1.0.2 新增, 可选): 跨进程临界区. Client 在 refresh token rotation
+ *     场景下用此包裹 "load → check → refresh → save" 整段, 防多进程共享同一 store
+ *     (典型: FileTokenStore 默认 ~/.acosmi/tokens.json) 撞 HTTP 400 refresh token
+ *     not found. 不实现时 Client 自动回退到仅进程内串行 (LocalStorage / InMemory
+ *     单进程语义无需此方法).
  */
-type ComplianceEnvelopeStatus = 'DRAFT' | 'CONTRACT_READY' | 'APPROVED' | 'SIGN_PENDING' | 'PENDING_EVIDENCE' | 'PENDING_RECONCILIATION' | 'SUCCESS' | 'FAILED' | 'CANCELED';
-/** Compliance 用印审批稳定状态。 */
-type ComplianceSealApprovalStatus = 'DRAFT' | 'SUBMITTED' | 'APPROVED' | 'REJECTED' | 'CANCELED' | 'USED' | 'EXPIRED';
-/** Provider 业务状态（前端可见的脱敏视图，不暴露下游内部字段）。 */
-type ComplianceProviderStatus = 'pending' | 'success' | 'failed' | 'unknown' | 'retrying';
+interface TokenStore {
+    save(tokens: TokenSet): Promise<void>;
+    load(): Promise<TokenSet | null>;
+    clear(): Promise<void>;
+    withLock?<T>(fn: () => Promise<T>): Promise<T>;
+}
 /**
- * 计费 / 履约的对外稳定状态视图。distribution compliance-billing 内部 API
- * (quote/reserve/commit/cancel/reconcile) 不暴露给前端 — 前端只能看见这 4 个语义。
+ * 基于文件的 token 存储 (开发/测试用)
+ * 生产环境建议替换为系统钥匙串实现
+ *
+ * 默认路径: ~/.acosmi/tokens.json
+ *
+ * 浏览器环境调用 new FileTokenStore() 会抛错 — 浏览器请用 LocalStorageTokenStore 或 InMemoryTokenStore.
  */
-type ComplianceBillingDisplayStatus = 'reserved' | 'committed' | 'canceled' | 'pending_reconciliation';
-/** 高风险动作 step-up — 重新做 OAuth introspection 或重新登录，提升 token 等级后再尝试。 */
-declare const ErrComplianceStepUpRequired = "COMPLIANCE_STEP_UP_REQUIRED";
-/** envelope 闸门关闭 — 审批 gate 等条件未同时就绪，前端展示"功能开放中"。 */
-declare const ErrEnvelopeGateClosed = "ENVELOPE_GATE_CLOSED";
-/** 履约 provider 未配置 — 受控环境材料缺失时业务路径会一致拒绝，不要前端重试。 */
-declare const ErrProviderNotConfigured = "PROVIDER_NOT_CONFIGURED";
-/** Provider 返回 unknown / retrying — 客户必须等待对账，前端展示"处理中（人工核对）"。 */
-declare const ErrProviderUnknownNoRetry = "PROVIDER_REQUEST_UNKNOWN_NO_RETRY";
-/** callback 不能直接确认扣费 — 后端守门，前端无需处理，记录到审计日志展示即可。 */
-declare const ErrBillingCallbackCannotCommit = "BILLING_CALLBACK_CANNOT_COMMIT";
-/** provider 成功但本地未验证通过，不允许扣费。 */
-declare const ErrBillingCommitRequiresLocalVerify = "BILLING_COMMIT_REQUIRES_LOCAL_VERIFY";
-/** distribution compliance-billing 必须 S2S — 前端误调用时拿到该错误码，禁止 retry。 */
-declare const ErrBillingS2sForbidden = "BILLING_S2S_FORBIDDEN";
-/** 审批 gate 各类失败语义（前端展示"审批中 / 审批已用 / 审批失效"）。 */
-declare const ErrSealApprovalNotApproved = "SEAL_APPROVAL_STATE_NOT_APPROVED";
-declare const ErrSealApprovalExpired = "SEAL_APPROVAL_EXPIRED";
-declare const ErrSealApprovalNonceUsed = "SEAL_APPROVAL_NONCE_USED";
-declare const ErrSealApprovalContractHashMismatch = "SEAL_APPROVAL_CONTRACT_HASH_MISMATCH";
-declare const ErrSealApprovalSealMismatch = "SEAL_APPROVAL_SEAL_MISMATCH";
-declare const ErrSealApprovalLocationMismatch = "SEAL_APPROVAL_LOCATION_MISMATCH";
-declare const ErrSealApprovalTransactorMismatch = "SEAL_APPROVAL_TRANSACTOR_MISMATCH";
-/** 用印重复消费防护 — 前端遇到该错误必须刷新审批单状态，不允许"换一次 nonce 再试"。 */
-declare const ErrSealUseAlreadyConsumed = "SEAL_USE_ALREADY_CONSUMED";
-/** 该错误码联合用于前端选择性展示文案；非穷举式 enum，后端保留新增空间。 */
-type ComplianceClientErrorCode = typeof ErrComplianceStepUpRequired | typeof ErrEnvelopeGateClosed | typeof ErrProviderNotConfigured | typeof ErrProviderUnknownNoRetry | typeof ErrBillingCallbackCannotCommit | typeof ErrBillingCommitRequiresLocalVerify | typeof ErrBillingS2sForbidden | typeof ErrSealApprovalNotApproved | typeof ErrSealApprovalExpired | typeof ErrSealApprovalNonceUsed | typeof ErrSealApprovalContractHashMismatch | typeof ErrSealApprovalSealMismatch | typeof ErrSealApprovalLocationMismatch | typeof ErrSealApprovalTransactorMismatch | typeof ErrSealUseAlreadyConsumed;
+/** 跨进程文件锁配置 (v1.0.2). 公开常量是为了让 caller / 测试可观察, 不建议生产代码改. */
+declare const fileLockDefaults: {
+    /** 获取锁的超时上限 (毫秒). refresh 流程含网络 < 30s, 30s 已远超正常完成时间. */
+    readonly acquireTimeoutMs: 30000;
+    /** 旧锁判定阈值 (毫秒). 锁文件 mtime 早于此值视为 stale 进程崩溃残留, 自动 break. */
+    readonly staleMs: 60000;
+    /** 重试间隔基数 (毫秒). 真实间隔 = base + random(0, jitter). */
+    readonly retryBaseMs: 30;
+    readonly retryJitterMs: 70;
+};
+declare class FileTokenStore implements TokenStore {
+    private path;
+    /** 进程内串行化 (Promise chain) — 与跨进程 flock 配合, 避免单进程内并发持锁产生死锁式互等. */
+    private chain;
+    constructor(path?: string);
+    private resolvePath;
+    /** 进程内串行 (维持 v1.0.1 单进程语义). flock 之外另一层防御: 如果用户自己就是单进程
+     *  并发场景, 不必每次都进 flock 旁路文件 IO. */
+    private withChain;
+    /**
+     * 跨进程临界区. 用 sidecar `<path>.lock` 文件 + O_EXCL 创建语义实现互斥:
+     *   - 创建成功 = 持有锁; 写入 pid+timestamp 便于诊断
+     *   - 创建失败 (EEXIST) = 别的进程持锁, backoff 重试
+     *   - 锁文件 mtime > staleMs = 进程崩溃残留, unlink 后重试
+     *   - acquireTimeoutMs 超时 = 抛错 (caller 应作为 transient error 处理, 上层 retry)
+     *
+     * 注意: O_EXCL 在 NFS 上不保证原子; FileTokenStore 适用于本地文件系统 (典型用户家目录).
+     * 真要跨机共享 token, 应实现自定义 Keychain / 数据库 store, 不要用 FileTokenStore.
+     */
+    withLock<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * 写入 token. 流程:
+     *   1. mkdir -p (默认路径目录)
+     *   2. 写入 `<path>.tmp.<pid>`
+     *   3. fsync 后 rename 到正式路径 (POSIX 上 rename(2) 同分区原子, Windows 上 ReplaceFile)
+     *
+     * 选择 atomic rename 而非直接 writeFile: 多进程并发或本进程崩溃时, 读端永远看到的是
+     * 完整的旧/新 JSON, 不会读到截断半文件 (Client.create.store.load 可能在另一进程
+     * 写入中间触发, atomic rename 避免它解析失败).
+     */
+    save(tokens: TokenSet): Promise<void>;
+    load(): Promise<TokenSet | null>;
+    clear(): Promise<void>;
+}
 /**
- * 判定一个错误码是否属于"需要前端引导用户重新认证/审批"的高级语义，
- * 而不是简单 retry。这类错误前端不允许在 UI 层做自动重试。
+ * 创建文件 token 存储 (与 Go NewFileTokenStore 等价)
+ * @param path 自定义路径; 空则使用默认 ~/.acosmi/tokens.json
  */
-declare function isComplianceTerminalError(code: string): boolean;
+declare function newFileTokenStore(path?: string): FileTokenStore;
 /**
- * "是否允许在 UI 上呈现为'扣费已确认'"的判定。
- * provider 状态为 unknown / retrying / pending 时一律不展示为已确认。
+ * 基于 LocalStorage 的 token 存储 (浏览器)
+ *
+ * 仅在浏览器环境可用 (检测 globalThis.localStorage)。
+ * 不持久化跨设备同步, 适合单机 SPA 使用。
  */
-declare function isBillingConfirmable(providerStatus: ComplianceProviderStatus | undefined, billingStatus: ComplianceBillingDisplayStatus | undefined): boolean;
+declare class LocalStorageTokenStore implements TokenStore {
+    private key;
+    constructor(key?: string);
+    save(tokens: TokenSet): Promise<void>;
+    load(): Promise<TokenSet | null>;
+    clear(): Promise<void>;
+}
+/**
+ * 内存 token 存储 (不持久化, 进程重启即丢失)
+ * 适合: 测试 / Deno script / 短期 SDK 调用 / 不希望落盘的安全场景
+ */
+declare class InMemoryTokenStore implements TokenStore {
+    private tokens;
+    save(tokens: TokenSet): Promise<void>;
+    load(): Promise<TokenSet | null>;
+    clear(): Promise<void>;
+}
 
-type ComplianceAssetType = 'CONTRACT' | 'CODE' | 'IMAGE' | 'DOCUMENT' | 'ARCHIVE' | 'HASH_ONLY' | 'URL_SNAPSHOT' | 'RELEASE' | 'LOG' | 'OTHER';
-type ComplianceHashAlgorithm = 'sha256' | 'sha512' | 'sm3';
-type ComplianceDigestSource = 'CLIENT' | 'COMPLIANCE_SERVICE' | 'PROVIDER';
-type CompliancePrivacyLevel = 'public' | 'private';
-/** 证据资产对外稳定视图。对应后端 EvidenceAssetRespVO。 */
-interface EvidenceAsset {
-    id: number;
-    /** 业务编号；SDK / 前端引用时优先使用 evidenceNo。 */
-    evidenceNo: string;
-    /** publish 后的公开 verify code；DRAFT / 非 public privacy 时为 null。 */
-    publicVerifyCode?: string | null;
-    assetType: ComplianceAssetType | string;
-    name: string;
-    mimeType?: string | null;
-    size?: number | null;
-    hashAlgorithm: ComplianceHashAlgorithm | string;
-    /** 资产 hash（hex 字符串）。 */
-    contentHash: string;
-    canonicalizationProfile?: string | null;
-    digestSource: ComplianceDigestSource | string;
-    privacyLevel: CompliancePrivacyLevel | string;
-    status: string;
-}
-/** 创建证据资产请求；与 Java EvidenceAssetCreateReq 对齐。 */
-interface CreateEvidenceAssetRequest {
-    /** AssetTypeEnum.name()。 */
-    assetType: ComplianceAssetType | string;
-    name: string;
-    mimeType?: string;
-    /** 'sha256' / 'sha512' / 'sm3'。 */
-    hashAlgorithm: ComplianceHashAlgorithm | string;
-    /** hex 字符串；hash-only 资产必填。 */
-    declaredHash?: string;
-    /** CLIENT / COMPLIANCE_SERVICE / PROVIDER。 */
-    digestSource?: ComplianceDigestSource | string;
-    /** 原文 base64；hash-only 时缺省即可。 */
-    contentBase64?: string;
-    /** public / private（默认 private）。 */
-    privacyLevel?: CompliancePrivacyLevel | string;
-    source?: string;
-}
-/** 公开 verify 结果。隐私边界：不暴露 PII / 合同原文 / storage / provider raw。 */
-interface PublicEvidenceVerifyResult {
-    evidenceNo: string;
-    assetType: string;
-    hashAlgorithm: string;
-    contentHash: string;
-    size?: number | null;
-    canonicalizationProfile?: string | null;
-    verifiedAt: string;
-    packageId?: number | null;
-    manifestHash?: string | null;
-    packageHash?: string | null;
-    manifestOfflineVerify: boolean;
-}
-type ComplianceTimestampVerificationStatus = 'PENDING' | 'VERIFIED' | 'FAILED' | 'LOCAL_VERIFY_FAILED' | 'UNKNOWN' | 'RETRYING';
-/** 时间章 token 对外视图（不含 provider/object/tsa 内部字段）。 */
-interface TimestampToken {
-    id: number;
-    assetId: number;
-    policyOid?: string | null;
-    serialNumber?: string | null;
-    /** gen_time ISO-8601；UNKNOWN/PENDING 状态可能为 null。 */
-    genTime?: string | null;
-    accuracy?: string | null;
-    verificationStatus: ComplianceTimestampVerificationStatus | string;
-    verifiedAt?: string | null;
-    verificationError?: string | null;
-}
-/** 申请时间章请求。`provider` 字段已从服务端契约下线；SDK 永远不传。 */
-interface IssueTimestampRequest {
-    name?: string;
-    mimeType?: string;
-    hashAlgorithm: ComplianceHashAlgorithm | string;
-    /** 客户端声明 digest（hex）；contentBase64 非空时作为校验值。 */
-    digest?: string;
-    contentBase64?: string;
-}
-/** verify 请求 / 结果。 */
-interface VerifyTimestampRequest {
-    tokenId: number;
+/** 表示一次 retry 评估的请求快照 — 仅供 SafeToRetry 闸门使用 */
+interface RetryRequestInfo {
+    method: string;
+    url: string;
 }
-interface TimestampVerifyResult {
-    passed: boolean;
-    reason: string;
+/**
+ * 配置 SDK 重试行为.
+ *
+ * undefined 字段使用 DefaultRetryPolicy 对应字段; null/undefined RetryPolicy 自身禁用重试.
+ */
+interface RetryPolicy {
+    /** 总尝试次数 (含首次). 1 = 不重试; 默认 2. */
+    maxAttempts?: number;
+    /** 首次重试退避时长 (毫秒). 默认 200. */
+    backoffMs?: number;
+    /** 退避最大值 (指数增长封顶, 毫秒). 默认 2000. */
+    backoffMaxMs?: number;
+    /** 指数倍数. 默认 2.0. */
+    backoffMul?: number;
+    /**
+     * 错误层闸门: 是否值得重试.
+     * 默认 defaultRetryable: HTTPError 5xx/429, NetworkError Timeout/EOF, 排除 StreamError.
+     */
+    onRetryable?: (err: unknown) => boolean;
+    /**
+     * 请求层闸门 (计费安全核心): 当前请求是否值得重试.
+     * 默认 defaultSafeToRetry: GET/HEAD/OPTIONS true, 其他 false.
+     * chat/messages/upload POST → 默认 false 兜底, 双扣绝不发生.
+     */
+    safeToRetry?: (req: RetryRequestInfo) => boolean;
 }
-interface EvidencePackage {
-    id: number;
-    assetId: number;
-    timestampTokenId?: number | null;
-    chainId: string;
-    packageVersion: string;
-    hashAlgorithm: string;
-    manifestHash: string;
-    packageHash: string;
-    status: string;
+/**
+ * 安全默认值.
+ *
+ * 计费安全红线: safeToRetry 默认 POST=false → chat/messages 用户 0 行为变化.
+ * GET 类查询 (skill-store/models/balance) 自动得 2x 稳定性.
+ */
+declare const DefaultRetryPolicy: Required<Omit<RetryPolicy, never>>;
+/**
+ * 计费安全闸门.
+ *
+ * 仅以下 method 视为幂等:
+ *   - GET / HEAD / OPTIONS: 天然幂等
+ *
+ * POST/PUT/DELETE/PATCH 默认 false (双扣保护). 调用方需要 GET 类 POST 重试可自定义 safeToRetry.
+ */
+declare function defaultSafeToRetry(req: RetryRequestInfo): boolean;
+/**
+ * 错误层闸门.
+ *
+ * 显式排除 (优先级最高):
+ *   - StreamError: V2 P0 SSE 中段错误, 流已部分写出, 重试 = 双 token + 重复消息
+ *   - AbortSignal aborted: 用户主动 abort, 重试无意义 (TS 中由调用方在 onRetryable 之前检查)
+ *
+ * 视为可重试:
+ *   - HTTPError 5xx 或 429
+ *   - NetworkError isTimeout() 或 isEOF()
+ *
+ * 其他 (如 4xx 业务错误 / DNS 失败 / BusinessError): 不重试
+ */
+declare function defaultRetryable(err: unknown): boolean;
+/** 实际生效策略 (undefined → DefaultRetryPolicy 兜底; 字段缺失填默认值) */
+declare function effectivePolicy(p: RetryPolicy | null | undefined): Required<RetryPolicy> | null;
+/**
+ * 计算第 attempt 次重试的退避时长 (毫秒, attempt 从 0 起).
+ * 优先级: HTTPError.retryAfter (上限 60s) > 指数退避 (backoffMs * backoffMul^attempt, 封顶 backoffMaxMs)
+ */
+declare function computeBackoff(p: Required<RetryPolicy>, attempt: number, err: unknown): number;
+
+type FilterStatus = 'ok' | 'admin-bypass' | 'internal-bypass' | 'disabled-by-flag' | 'fallback-tkdist-error' | 'fallback-tkdist-deployment-skew' | 'fallback-no-buckets' | 'fallback-missing-userid' | '';
+declare const FilterStatusOK: FilterStatus;
+declare const FilterStatusAdminBypass: FilterStatus;
+declare const FilterStatusInternalBypass: FilterStatus;
+declare const FilterStatusDisabledByFlag: FilterStatus;
+declare const FilterStatusFallbackTkdistError: FilterStatus;
+declare const FilterStatusFallbackTkdistSkew: FilterStatus;
+declare const FilterStatusFallbackNoBuckets: FilterStatus;
+declare const FilterStatusFallbackMissingUser: FilterStatus;
+declare const FilterStatusUnknown: FilterStatus;
+/** 客户端配置 */
+interface Config {
+    /**
+     * nexus-v4 API 根地址 (默认 https://acosmi.com)。
+     * SDK 自动追加 /api/v4, 无需手动拼接。
+     */
+    serverURL?: string;
+    /** token 持久化实现, 缺省时按平台选 (Node File / Browser LocalStorage / Memory) */
+    store?: TokenStore;
+    /** 自定义 fetch 实现 (默认 globalThis.fetch) */
+    fetchImpl?: typeof fetch;
+    /**
+     * 重试策略 (L6, v0.15)
+     *
+     * undefined = 禁用重试 (v0.14.1 行为, 老调用方 0 影响)
+     * 非 undefined = 启用 — 默认 SafeToRetry POST=false 兜底, chat/messages POST 仍 0 retry
+     * GET 类查询 (skill-store/models/balance) 自动得 2x 稳定性
+     *
+     * 计费安全: 自定义 SafeToRetry 时, 严禁让 POST chat/messages 通过, 否则双扣
+     */
+    retryPolicy?: RetryPolicy;
+    /**
+     * Compliance (时间章 / 电子证据 / 合同签署) API 根地址。
+     *
+     * Java compliance 模块的 controller 注册在 `/compliance/...` 下，部署到
+     * `/admin-api/*` 前缀。未配置时默认 `${serverURL}/admin-api`，也可显式覆盖到
+     * 独立 ingress（如 `https://compliance.example.com`）。
+     *
+     * 该地址不被 `/api/v4` 拼接路径复用，compliance 调用走自己的子 client
+     * `client.compliance.*`，不与既有模型网关 API 冲突。
+     */
+    complianceBaseURL?: string;
+    /**
+     * OAuth metadata profile — 决定 `ensureToken` 刷新 token 时
+     * 发现 metadata 走哪个 well-known 端点。
+     *
+     * - `'desktop'` (默认): `/.well-known/oauth-authorization-server/desktop`
+     *   — 桌面 loopback OAuth (`login()`) 流程。
+     * - `'web'`: `/.well-known/oauth-authorization-server/web`
+     *   — 浏览器 Web OAuth (csign 等第一方 Web 应用) 签发的 token，
+     *   其 refresh 必须走 Web token 端点。
+     *
+     * 未设置时默认 `'desktop'`，对既有调用方行为完全无影响。
+     * `login()` 桌面 loopback 路径不受此配置影响。
+     */
+    oauthMetadataProfile?: OAuthMetadataProfile;
+    /**
+     * Browser refresh strategy for Web OAuth tokens.
+     *
+     * - `'direct'` (default): refresh directly against the OAuth token endpoint.
+     * - `'server-proxy'`: POST the current TokenSet to a same-origin refresh proxy,
+     *   useful when the OAuth issuer intentionally blocks browser CORS.
+     * - `'none'`: do not refresh automatically; expired tokens throw `token_expired`.
+     */
+    browserRefreshMode?: BrowserRefreshMode;
+    /** Same-origin refresh proxy URL used when `browserRefreshMode='server-proxy'`. */
+    refreshProxyURL?: string;
 }
-interface ComplianceReport {
-    id: number;
-    reportNo: string;
-    reportType: string;
-    status: string;
-    assetId?: number | null;
-    packageId?: number | null;
-    publicUrlToken?: string | null;
-    publishedAt?: string | null;
-    bodyHash?: string | null;
+type BrowserRefreshMode = 'direct' | 'server-proxy' | 'none';
+declare const ErrOAuthCORSBlocked: "oauth_cors_blocked";
+declare const ErrRefreshProxyFailed: "refresh_proxy_failed";
+declare const ErrTokenExpired: "token_expired";
+interface Deferred<T> {
+    promise: Promise<T>;
+    resolve: (v: T) => void;
+    reject: (e: unknown) => void;
 }
-interface CreateReportRequest {
-    assetId: number;
-    packageId: number;
-}
-/** 离线复核下载 VO；建议调用方持久化作为长期可重复验证依据。 */
-interface ReportDownload {
-    id: number;
-    reportNo: string;
-    reportType: string;
-    status: string;
-    bodyHash?: string | null;
-    publishedAt?: string | null;
-    assetEvidenceNo?: string | null;
-    assetHashAlgorithm?: string | null;
-    assetContentHash?: string | null;
-    packageManifestHash?: string | null;
-    packageHash?: string | null;
-    packageHashAlgorithm?: string | null;
-    timestampSerialNumber?: string | null;
-    timestampGenTime?: string | null;
-    timestampVerificationStatus?: string | null;
-}
-interface SigningEnvelope {
-    id: number;
-    envelopeNo: string;
-    applicantUserId?: string | null;
-    status: string;
-    primaryContractId?: number | null;
-    contractHash?: string | null;
-    hashAlgorithm?: string | null;
-    billingGroupId?: string | null;
-    chainId?: string | null;
-    requestId?: string | null;
-    pendingReason?: string | null;
-    signedAt?: string | null;
-    evidenceReadyAt?: string | null;
-    committedAt?: string | null;
-}
-/** 创建 envelope 请求；只保留调用方业务字段，内部主体快照和履约通道由后端推导。 */
-interface CreateSigningEnvelopeRequest {
-    envelopeNo?: string;
-    requestId?: string;
-    /** 调用方稳定 idempotency-key（不传则由 Idempotency-Key header 兜底）。 */
-    idempotencyKey?: string;
-    billingGroupId?: string;
-    chainId?: string;
-}
-/** sign 请求；service 默认闸门关闭，SDK 写示例必须处理 ENVELOPE_GATE_CLOSED 错误。 */
-interface SignEnvelopeRequest {
-    approvalRequestId?: number;
-    contractId?: number;
-    contractHash?: string;
-    sealId?: number;
-    signLocationType?: string;
-    signLocationPayload?: string;
-    transactorId?: number;
-    requestId?: string;
-    idempotencyKey?: string;
-}
-/** H5 短链请求。 */
-interface CreateH5SigningUrlRequest extends SignEnvelopeRequest {
-}
-interface SealApproval {
-    id: number;
-    envelopeId?: number | null;
-    contractId?: number | null;
-    contractHash?: string | null;
-    hashAlgorithm?: string | null;
-    sealId?: number | null;
-    applicantUserId?: string | null;
-    approverUserId?: string | null;
-    transactorId?: number | null;
-    signLocationType?: string | null;
-    signLocationPayload?: string | null;
-    reason?: string | null;
-    expiresAt?: string | null;
-    status: string;
-    approvedAt?: string | null;
-    rejectedAt?: string | null;
-    canceledAt?: string | null;
-}
-/** 提交审批；provider 侧字段由后端归一，SDK 调用方不传。 */
-interface SubmitSealApprovalRequest {
-    envelopeId?: number;
-    contractId?: number;
-    contractHash?: string;
-    hashAlgorithm?: string;
-    sealId?: number;
-    approverUserId?: string;
-    transactorId?: number;
-    signLocationType?: string;
-    signLocationPayload?: string;
-    reason?: string;
-}
-interface ApproveSealApprovalQuery {
-    expiresAt?: string;
-    note?: string;
-}
-interface RejectSealApprovalQuery {
-    reason?: string;
-}
-interface CancelSealApprovalQuery {
-    reason?: string;
-}
-type ComplianceProviderRequestStatus = 'PENDING' | 'SUCCESS' | 'FAILED' | 'UNKNOWN' | 'RETRYING';
-interface ProviderRequestStatusView {
-    id: number;
-    status: ComplianceProviderRequestStatus | string;
-    /** SUCCESS / FAILED 终态。 */
-    terminal: boolean;
-    /** 当前状态是否允许 SDK 安全重试请求（仅对 RETRYING 为 true）。 */
-    retryable: boolean;
-    businessNo?: string | null;
-    contractNo?: string | null;
-    sealId?: string | null;
-    attemptCount?: number | null;
-    reconciliationStatus?: string | null;
-    nextRetryAt?: string | null;
-    requestedAt?: string | null;
-    respondedAt?: string | null;
-}
-/** Compliance 写操作选项；写操作不自动 retry，不自动 401 重放。 */
-interface ComplianceWriteOptions {
-    /**
-     * 调用方稳定的幂等键。写操作强烈建议持久化；缺省时服务端按 UUID 兜底，但调用方
-     * 在重试 / 恢复时无法对账。
-     */
-    idempotencyKey?: string;
-    signal?: AbortSignal;
-}
-/** 轮询参数（exponential backoff）。 */
-interface CompliancePollOptions {
-    /** 总超时（ms），缺省 60s。 */
-    timeoutMs?: number;
-    /** 初始 interval（ms），缺省 1000。 */
-    initialIntervalMs?: number;
-    /** interval 倍增上限（ms），缺省 5000。 */
-    maxIntervalMs?: number;
-    /** 倍增系数，缺省 1.5。 */
-    multiplier?: number;
-    signal?: AbortSignal;
-}
-
-/**
- * SDK 内部 symbolic key；用于代码分支判断与文档。**不是 wire contract**。
- */
-type ComplianceErrorKey = 'COMPLIANCE_UNAUTHORIZED' | 'COMPLIANCE_INSUFFICIENT_SCOPE' | 'COMPLIANCE_STEP_UP_REQUIRED' | 'COMPLIANCE_TOKEN_INVALID' | 'SUBJECT_SNAPSHOT_REQUIRED' | 'SUBJECT_SNAPSHOT_NOT_FOUND' | 'SUBJECT_SNAPSHOT_TENANT_MISMATCH' | 'EVIDENCE_ASSET_NOT_FOUND' | 'EVIDENCE_ASSET_HASH_MISMATCH' | 'EVIDENCE_ASSET_PAYLOAD_REQUIRED' | 'TIMESTAMP_TOKEN_NOT_FOUND' | 'TIMESTAMP_PROVIDER_FAILED' | 'TIMESTAMP_PROVIDER_UNKNOWN' | 'TIMESTAMP_LOCAL_VERIFY_FAILED' | 'TIMESTAMP_PROVIDER_NOT_AVAILABLE' | 'EVIDENCE_PACKAGE_NOT_FOUND' | 'EVIDENCE_PACKAGE_TIMESTAMP_REQUIRED' | 'EVIDENCE_PACKAGE_MANIFEST_HASH_MISMATCH' | 'REPORT_NOT_FOUND' | 'REPORT_ALREADY_PUBLISHED' | 'REPORT_DRAFT_REQUIRED' | 'EVIDENCE_VERIFY_TARGET_REQUIRED' | 'EVIDENCE_VERIFY_TARGET_NOT_FOUND' | 'PROVIDER_REQUEST_UNKNOWN_NO_RETRY' | 'PROVIDER_CALLBACK_SOURCE_INVALID' | 'PROVIDER_NOT_CONFIGURED' | 'PROVIDER_REQUEST_NOT_FOUND' | 'PROVIDER_REQUEST_IDEMPOTENCY_REQUIRED' | 'PROVIDER_REQUEST_STATUS_NOT_TERMINAL' | 'ENVELOPE_NOT_FOUND' | 'ENVELOPE_TENANT_MISMATCH' | 'ENVELOPE_STATE_NOT_ALLOWED' | 'ENVELOPE_GATE_CLOSED' | 'CONTRACT_NOT_FOUND' | 'CONTRACT_HASH_MISMATCH' | 'PROVIDER_AUTHORIZATION_NOT_CONFIRMED' | 'ENVELOPE_EVIDENCE_NOT_READY' | 'SEAL_ASSET_NOT_FOUND' | 'SEAL_APPROVAL_NOT_FOUND' | 'SEAL_APPROVAL_STATE_NOT_APPROVED' | 'SEAL_APPROVAL_EXPIRED' | 'SEAL_APPROVAL_ALREADY_USED' | 'SEAL_APPROVAL_NONCE_USED' | 'SEAL_APPROVAL_SEAL_MISMATCH' | 'SEAL_APPROVAL_LOCATION_MISMATCH' | 'SEAL_APPROVAL_TRANSACTOR_MISMATCH' | 'SEAL_APPROVAL_CONTRACT_HASH_MISMATCH' | 'SEAL_APPROVAL_INVALID_TRANSITION' | 'SEAL_USE_ALREADY_CONSUMED' | 'AUDIT_CHAIN_TAMPER_DETECTED' | 'BILLING_COMMIT_REQUIRES_LOCAL_VERIFY' | 'BILLING_COMMIT_REQUIRES_PROVIDER_SUCCESS' | 'BILLING_CALLBACK_CANNOT_COMMIT' | 'BILLING_PROVIDER_UNKNOWN_NOT_COMMITTABLE' | 'BILLING_S2S_FORBIDDEN' | 'UNKNOWN_COMPLIANCE_ERROR';
-/** 单个错误的 SDK 视图。 */
-interface ComplianceErrorInfo {
-    /** Java numeric error code (wire contract)。 */
-    code: number;
-    /** 服务端原始 message（中文，可变）；仅用于日志/展示。 */
-    message: string;
-    /** SDK 分支判断用 symbolic key。 */
-    key: ComplianceErrorKey;
-    /** 是否安全自动重试 — compliance 写接口几乎全为 false。 */
-    retryable: boolean;
-    /** 是否已经是终态 — 用户必须用新 idempotency-key 重新发起。 */
-    terminal: boolean;
-    /** 高风险动作需要 step-up / introspection。 */
-    stepUpRequired: boolean;
-}
-/**
- * 把一个 BusinessError 分类为 compliance 视图。
- * 非 compliance 段位的错误码会回退到 UNKNOWN_COMPLIANCE_ERROR，调用方应该当作业务错误处理。
- */
-declare function classifyComplianceError(err: BusinessError): ComplianceErrorInfo;
-/**
- * 判断 BusinessError 是否属于 compliance 段位（1-031-xxx-xxx）。
- * 不在段位的错误码可能来自其它 yudao 模块，按通用业务错误处理即可。
- */
-declare function isComplianceBusinessError(err: BusinessError): boolean;
-
-/**
- * Token 持久化接口
- * 桌面智能体可自行实现 (如 macOS Keychain / Windows Credential Manager)
- *
- * 跨端约定:
- *   - Save: 写入持久化, 失败抛 Error
- *   - Load: 读取, 不存在返回 null (与 Go IsNotExist 行为一致)
- *   - Clear: 删除, 不存在不抛错 (Logout 后 Clear 不应报错, [RC-11])
- *   - withLock (v1.0.2 新增, 可选): 跨进程临界区. Client 在 refresh token rotation
- *     场景下用此包裹 "load → check → refresh → save" 整段, 防多进程共享同一 store
- *     (典型: FileTokenStore 默认 ~/.acosmi/tokens.json) 撞 HTTP 400 refresh token
- *     not found. 不实现时 Client 自动回退到仅进程内串行 (LocalStorage / InMemory
- *     单进程语义无需此方法).
- */
-interface TokenStore {
-    save(tokens: TokenSet): Promise<void>;
-    load(): Promise<TokenSet | null>;
-    clear(): Promise<void>;
-    withLock?<T>(fn: () => Promise<T>): Promise<T>;
+/**
+ * WebSocket 状态 — 内部使用, 实际方法由 ws.ts mixin 提供
+ * 留作 forward declaration, 避免循环依赖
+ */
+interface WSState {
+    connected: boolean;
+    [key: string]: any;
 }
 /**
- * 基于文件的 token 存储 (开发/测试用)
- * 生产环境建议替换为系统钥匙串实现
- *
- * 默认路径: ~/.acosmi/tokens.json
+ * Acosmi nexus-v4 统一 API 客户端
  *
- * 浏览器环境调用 new FileTokenStore() 会抛错 — 浏览器请用 LocalStorageTokenStore 或 InMemoryTokenStore.
+ * 覆盖全域 API: 模型/权益/商城/钱包/技能/工具/WebSocket
+ * 自动处理 token 刷新, 所有 API 调用线程安全 (基于 Promise chain)
  */
-/** 跨进程文件锁配置 (v1.0.2). 公开常量是为了让 caller / 测试可观察, 不建议生产代码改. */
-declare const fileLockDefaults: {
-    /** 获取锁的超时上限 (毫秒). refresh 流程含网络 < 30s, 30s 已远超正常完成时间. */
-    readonly acquireTimeoutMs: 30000;
-    /** 旧锁判定阈值 (毫秒). 锁文件 mtime 早于此值视为 stale 进程崩溃残留, 自动 break. */
-    readonly staleMs: 60000;
-    /** 重试间隔基数 (毫秒). 真实间隔 = base + random(0, jitter). */
-    readonly retryBaseMs: 30;
-    readonly retryJitterMs: 70;
-};
-declare class FileTokenStore implements TokenStore {
-    private path;
-    /** 进程内串行化 (Promise chain) — 与跨进程 flock 配合, 避免单进程内并发持锁产生死锁式互等. */
-    private chain;
-    constructor(path?: string);
-    private resolvePath;
-    /** 进程内串行 (维持 v1.0.1 单进程语义). flock 之外另一层防御: 如果用户自己就是单进程
-     *  并发场景, 不必每次都进 flock 旁路文件 IO. */
-    private withChain;
-    /**
-     * 跨进程临界区. 用 sidecar `<path>.lock` 文件 + O_EXCL 创建语义实现互斥:
-     *   - 创建成功 = 持有锁; 写入 pid+timestamp 便于诊断
-     *   - 创建失败 (EEXIST) = 别的进程持锁, backoff 重试
-     *   - 锁文件 mtime > staleMs = 进程崩溃残留, unlink 后重试
-     *   - acquireTimeoutMs 超时 = 抛错 (caller 应作为 transient error 处理, 上层 retry)
-     *
-     * 注意: O_EXCL 在 NFS 上不保证原子; FileTokenStore 适用于本地文件系统 (典型用户家目录).
-     * 真要跨机共享 token, 应实现自定义 Keychain / 数据库 store, 不要用 FileTokenStore.
-     */
-    withLock<T>(fn: () => Promise<T>): Promise<T>;
-    /**
-     * 写入 token. 流程:
-     *   1. mkdir -p (默认路径目录)
-     *   2. 写入 `<path>.tmp.<pid>`
-     *   3. fsync 后 rename 到正式路径 (POSIX 上 rename(2) 同分区原子, Windows 上 ReplaceFile)
-     *
-     * 选择 atomic rename 而非直接 writeFile: 多进程并发或本进程崩溃时, 读端永远看到的是
-     * 完整的旧/新 JSON, 不会读到截断半文件 (Client.create.store.load 可能在另一进程
-     * 写入中间触发, atomic rename 避免它解析失败).
-     */
-    save(tokens: TokenSet): Promise<void>;
-    load(): Promise<TokenSet | null>;
-    clear(): Promise<void>;
-}
-/**
- * 创建文件 token 存储 (与 Go NewFileTokenStore 等价)
- * @param path 自定义路径; 空则使用默认 ~/.acosmi/tokens.json
- */
-declare function newFileTokenStore(path?: string): FileTokenStore;
-/**
- * 基于 LocalStorage 的 token 存储 (浏览器)
- *
- * 仅在浏览器环境可用 (检测 globalThis.localStorage)。
- * 不持久化跨设备同步, 适合单机 SPA 使用。
- */
-declare class LocalStorageTokenStore implements TokenStore {
-    private key;
-    constructor(key?: string);
-    save(tokens: TokenSet): Promise<void>;
-    load(): Promise<TokenSet | null>;
-    clear(): Promise<void>;
-}
-/**
- * 内存 token 存储 (不持久化, 进程重启即丢失)
- * 适合: 测试 / Deno script / 短期 SDK 调用 / 不希望落盘的安全场景
- */
-declare class InMemoryTokenStore implements TokenStore {
-    private tokens;
-    save(tokens: TokenSet): Promise<void>;
-    load(): Promise<TokenSet | null>;
-    clear(): Promise<void>;
-}
-
-/** 表示一次 retry 评估的请求快照 — 仅供 SafeToRetry 闸门使用 */
-interface RetryRequestInfo {
-    method: string;
-    url: string;
-}
-/**
- * 配置 SDK 重试行为.
- *
- * undefined 字段使用 DefaultRetryPolicy 对应字段; null/undefined RetryPolicy 自身禁用重试.
- */
-interface RetryPolicy {
-    /** 总尝试次数 (含首次). 1 = 不重试; 默认 2. */
-    maxAttempts?: number;
-    /** 首次重试退避时长 (毫秒). 默认 200. */
-    backoffMs?: number;
-    /** 退避最大值 (指数增长封顶, 毫秒). 默认 2000. */
-    backoffMaxMs?: number;
-    /** 指数倍数. 默认 2.0. */
-    backoffMul?: number;
-    /**
-     * 错误层闸门: 是否值得重试.
-     * 默认 defaultRetryable: HTTPError 5xx/429, NetworkError Timeout/EOF, 排除 StreamError.
-     */
-    onRetryable?: (err: unknown) => boolean;
-    /**
-     * 请求层闸门 (计费安全核心): 当前请求是否值得重试.
-     * 默认 defaultSafeToRetry: GET/HEAD/OPTIONS true, 其他 false.
-     * chat/messages/upload POST → 默认 false 兜底, 双扣绝不发生.
-     */
-    safeToRetry?: (req: RetryRequestInfo) => boolean;
-}
-/**
- * 安全默认值.
- *
- * 计费安全红线: safeToRetry 默认 POST=false → chat/messages 用户 0 行为变化.
- * GET 类查询 (skill-store/models/balance) 自动得 2x 稳定性.
- */
-declare const DefaultRetryPolicy: Required<Omit<RetryPolicy, never>>;
-/**
- * 计费安全闸门.
- *
- * 仅以下 method 视为幂等:
- *   - GET / HEAD / OPTIONS: 天然幂等
- *
- * POST/PUT/DELETE/PATCH 默认 false (双扣保护). 调用方需要 GET 类 POST 重试可自定义 safeToRetry.
- */
-declare function defaultSafeToRetry(req: RetryRequestInfo): boolean;
-/**
- * 错误层闸门.
- *
- * 显式排除 (优先级最高):
- *   - StreamError: V2 P0 SSE 中段错误, 流已部分写出, 重试 = 双 token + 重复消息
- *   - AbortSignal aborted: 用户主动 abort, 重试无意义 (TS 中由调用方在 onRetryable 之前检查)
- *
- * 视为可重试:
- *   - HTTPError 5xx 或 429
- *   - NetworkError isTimeout() 或 isEOF()
- *
- * 其他 (如 4xx 业务错误 / DNS 失败 / BusinessError): 不重试
- */
-declare function defaultRetryable(err: unknown): boolean;
-/** 实际生效策略 (undefined → DefaultRetryPolicy 兜底; 字段缺失填默认值) */
-declare function effectivePolicy(p: RetryPolicy | null | undefined): Required<RetryPolicy> | null;
-/**
- * 计算第 attempt 次重试的退避时长 (毫秒, attempt 从 0 起).
- * 优先级: HTTPError.retryAfter (上限 60s) > 指数退避 (backoffMs * backoffMul^attempt, 封顶 backoffMaxMs)
- */
-declare function computeBackoff(p: Required<RetryPolicy>, attempt: number, err: unknown): number;
-
-type FilterStatus = 'ok' | 'admin-bypass' | 'internal-bypass' | 'disabled-by-flag' | 'fallback-tkdist-error' | 'fallback-tkdist-deployment-skew' | 'fallback-no-buckets' | 'fallback-missing-userid' | '';
-declare const FilterStatusOK: FilterStatus;
-declare const FilterStatusAdminBypass: FilterStatus;
-declare const FilterStatusInternalBypass: FilterStatus;
-declare const FilterStatusDisabledByFlag: FilterStatus;
-declare const FilterStatusFallbackTkdistError: FilterStatus;
-declare const FilterStatusFallbackTkdistSkew: FilterStatus;
-declare const FilterStatusFallbackNoBuckets: FilterStatus;
-declare const FilterStatusFallbackMissingUser: FilterStatus;
-declare const FilterStatusUnknown: FilterStatus;
-/** 客户端配置 */
-interface Config {
-    /**
-     * nexus-v4 API 根地址 (默认 https://acosmi.com)。
-     * SDK 自动追加 /api/v4, 无需手动拼接。
-     */
-    serverURL?: string;
-    /** token 持久化实现, 缺省时按平台选 (Node File / Browser LocalStorage / Memory) */
-    store?: TokenStore;
-    /** 自定义 fetch 实现 (默认 globalThis.fetch) */
-    fetchImpl?: typeof fetch;
-    /**
-     * 重试策略 (L6, v0.15)
-     *
-     * undefined = 禁用重试 (v0.14.1 行为, 老调用方 0 影响)
-     * 非 undefined = 启用 — 默认 SafeToRetry POST=false 兜底, chat/messages POST 仍 0 retry
-     * GET 类查询 (skill-store/models/balance) 自动得 2x 稳定性
-     *
-     * 计费安全: 自定义 SafeToRetry 时, 严禁让 POST chat/messages 通过, 否则双扣
-     */
-    retryPolicy?: RetryPolicy;
-    /**
-     * Compliance (时间章 / 电子证据 / 合同签署) API 根地址。
-     *
-     * Java compliance 模块的 controller 注册在 `/compliance/...` 下，部署到
-     * `/admin-api/*` 前缀。未配置时默认 `${serverURL}/admin-api`，也可显式覆盖到
-     * 独立 ingress（如 `https://compliance.example.com`）。
-     *
-     * 该地址不被 `/api/v4` 拼接路径复用，compliance 调用走自己的子 client
-     * `client.compliance.*`，不与既有模型网关 API 冲突。
-     */
-    complianceBaseURL?: string;
-    /**
-     * OAuth metadata profile — 决定 `ensureToken` 刷新 token 时
-     * 发现 metadata 走哪个 well-known 端点。
-     *
-     * - `'desktop'` (默认): `/.well-known/oauth-authorization-server/desktop`
-     *   — 桌面 loopback OAuth (`login()`) 流程。
-     * - `'web'`: `/.well-known/oauth-authorization-server/web`
-     *   — 浏览器 Web OAuth (csign 等第一方 Web 应用) 签发的 token，
-     *   其 refresh 必须走 Web token 端点。
-     *
-     * 未设置时默认 `'desktop'`，对既有调用方行为完全无影响。
-     * `login()` 桌面 loopback 路径不受此配置影响。
-     */
-    oauthMetadataProfile?: OAuthMetadataProfile;
-    /**
-     * Browser refresh strategy for Web OAuth tokens.
-     *
-     * - `'direct'` (default): refresh directly against the OAuth token endpoint.
-     * - `'server-proxy'`: POST the current TokenSet to a same-origin refresh proxy,
-     *   useful when the OAuth issuer intentionally blocks browser CORS.
-     * - `'none'`: do not refresh automatically; expired tokens throw `token_expired`.
-     */
-    browserRefreshMode?: BrowserRefreshMode;
-    /** Same-origin refresh proxy URL used when `browserRefreshMode='server-proxy'`. */
-    refreshProxyURL?: string;
-}
-type BrowserRefreshMode = 'direct' | 'server-proxy' | 'none';
-declare const ErrOAuthCORSBlocked: "oauth_cors_blocked";
-declare const ErrRefreshProxyFailed: "refresh_proxy_failed";
-declare const ErrTokenExpired: "token_expired";
-interface Deferred<T> {
-    promise: Promise<T>;
-    resolve: (v: T) => void;
-    reject: (e: unknown) => void;
-}
-/**
- * WebSocket 状态 — 内部使用, 实际方法由 ws.ts mixin 提供
- * 留作 forward declaration, 避免循环依赖
- */
-interface WSState {
-    connected: boolean;
-    [key: string]: any;
-}
-/**
- * Acosmi nexus-v4 统一 API 客户端
- *
- * 覆盖全域 API: 模型/权益/商城/钱包/技能/工具/WebSocket
- * 自动处理 token 刷新, 所有 API 调用线程安全 (基于 Promise chain)
- */
-declare class Client {
-    /** SDK 内部使用 — 业务方法 (mixin) 通过 this.* 访问以下字段 */
-    /** 服务器根地址 (已 trim 尾随 /) */
-    serverURL: string;
-    /** Compliance API 根地址 (已 trim 尾随 /); null = 走默认 ${serverURL}/admin-api */
-    complianceBaseURL: string | null;
-    /** OAuth metadata profile — 刷新 token 时发现 metadata 用 (默认 'desktop') */
-    oauthMetadataProfile: OAuthMetadataProfile;
-    /** Browser Web OAuth refresh strategy (default 'direct') */
-    browserRefreshMode: BrowserRefreshMode;
-    /** Same-origin refresh proxy URL for browserRefreshMode='server-proxy' */
-    refreshProxyURL: string | null;
-    /** OAuth metadata (lazy loaded) */
-    meta: ServerMetadata | null;
-    /** 当前 token (内存) */
-    tokens: TokenSet | null;
-    /** token 持久化 */
-    store: TokenStore;
-    /** fetch 实现 (默认 globalThis.fetch) */
-    fetchImpl: typeof fetch;
-    /** 互斥锁 (TS 用 Promise chain 替代 sync.Mutex) */
-    private mu;
-    /** WebSocket 状态 (实际方法由 ws.ts mixin 维护) */
-    ws: WSState | null;
-    /** v0.15.1: token 就绪等待机制 — login 成功后 resolve, 等待方解除阻塞 */
-    tokenReady: Deferred<void>;
-    /** Login 进行中 — 等待方需等而非 fail-fast */
-    loginInFlight: boolean;
-    /** 防止 tokenReady 被多次 resolve (替代 Go sync.Once) */
-    private tokenReadyResolved;
-    /** 模型能力缓存 (CrabCode 扩展) */
-    modelCache: ManagedModel[];
-    modelCacheTimeMs: number;
-    /** sanitize-bridge 配置 (默认禁用) */
-    defensiveCfg: MinimalSanitizeConfig | null;
-    autoStripEphemeral: boolean;
-    /** L6 (v0.15): 重试策略. null = 禁用 (v0.14.1 行为) */
-    retryPolicy: Required<RetryPolicy> | null;
-    /** V29 系数缓存 (TTL 8s, listCoefficients 内部用) */
-    coefCacheData: ModelCoefficient[] | null;
-    coefCacheTimeMs: number;
-    /** 串行化锁 (替代 Go sync.Mutex) */
-    private coefMu;
-    constructor(cfg?: Config);
+declare class Client {
+    /** SDK 内部使用 — 业务方法 (mixin) 通过 this.* 访问以下字段 */
+    /** 服务器根地址 (已 trim 尾随 /) */
+    serverURL: string;
+    /** Compliance API 根地址 (已 trim 尾随 /); null = 走默认 ${serverURL}/admin-api */
+    complianceBaseURL: string | null;
+    /** OAuth metadata profile — 刷新 token 时发现 metadata 用 (默认 'desktop') */
+    oauthMetadataProfile: OAuthMetadataProfile;
+    /** Browser Web OAuth refresh strategy (default 'direct') */
+    browserRefreshMode: BrowserRefreshMode;
+    /** Same-origin refresh proxy URL for browserRefreshMode='server-proxy' */
+    refreshProxyURL: string | null;
+    /** OAuth metadata (lazy loaded) */
+    meta: ServerMetadata | null;
+    /** 当前 token (内存) */
+    tokens: TokenSet | null;
+    /** token 持久化 */
+    store: TokenStore;
+    /** fetch 实现 (默认 globalThis.fetch) */
+    fetchImpl: typeof fetch;
+    /** 互斥锁 (TS 用 Promise chain 替代 sync.Mutex) */
+    private mu;
+    /** WebSocket 状态 (实际方法由 ws.ts mixin 维护) */
+    ws: WSState | null;
+    /** v0.15.1: token 就绪等待机制 — login 成功后 resolve, 等待方解除阻塞 */
+    tokenReady: Deferred<void>;
+    /** Login 进行中 — 等待方需等而非 fail-fast */
+    loginInFlight: boolean;
+    /** 防止 tokenReady 被多次 resolve (替代 Go sync.Once) */
+    private tokenReadyResolved;
+    /** 模型能力缓存 (CrabCode 扩展) */
+    modelCache: ManagedModel[];
+    modelCacheTimeMs: number;
+    /** sanitize-bridge 配置 (默认禁用) */
+    defensiveCfg: MinimalSanitizeConfig | null;
+    autoStripEphemeral: boolean;
+    /** L6 (v0.15): 重试策略. null = 禁用 (v0.14.1 行为) */
+    retryPolicy: Required<RetryPolicy> | null;
+    /** V29 系数缓存 (TTL 8s, listCoefficients 内部用) */
+    coefCacheData: ModelCoefficient[] | null;
+    coefCacheTimeMs: number;
+    /** 串行化锁 (替代 Go sync.Mutex) */
+    private coefMu;
+    constructor(cfg?: Config);
     /**
      * 异步初始化 (从 store 加载已有 token)
      * 替代 Go NewClient (Go 同步 IO, TS 必须 async)
@@ -1147,563 +900,2431 @@ declare class Client {
         body?: string;
     }, signal?: AbortSignal): Promise<Response>;
 }
-
-declare module '@acosmi/sdk-ts' {
-    interface Client {
-        /** SDK-facing 时间章与电子证据 / 合同签署能力。 */
-        readonly compliance: ComplianceClient;
-    }
+
+declare module '@acosmi/sdk-ts' {
+    interface Client {
+        /**
+         * 配置请求前的底线防御 (体积 / deny-list / 深度)。
+         * 传空值 {} 关闭 (所有字段为零 = 禁用)。
+         * 并发安全, 可在任意时间调用。
+         */
+        setDefensiveSanitize(cfg: MinimalSanitizeConfig): void;
+        /**
+         * 开启后, 每次请求前 SDK 会从 rawMessages 中剥除带 acosmi_ephemeral:true 标记的 block,
+         * 并联动剥除引用已剥 tool_use 的 tool_result, 避免 provider 报 "tool_use_id 不存在".
+         *
+         * 标记来源: 网关在响应 content_block_start 中 in-band 注入; 消费者把上一轮 assistant
+         * 回复原样拼回 history 即可触发剥离。
+         */
+        setAutoStripEphemeralHistory(on: boolean): void;
+        /**
+         * 在 buildChatRequest 开头调用, 把配置化的防御策略应用到 req。
+         * 未配置时立即返回, 零开销。
+         *
+         * 失败时抛错 — 调用方应放弃本次请求。
+         */
+        applyRequestSanitizers(req: ChatRequest): void;
+    }
+}
+
+/** 下载限流错误 (429) */
+declare class RateLimitError extends Error {
+    retryAfter: string;
+    raw: string;
+    constructor(message: string, retryAfter: string, raw: string);
+}
+/**
+ * API 业务层错误 (HTTP 200 但 code != 0)
+ * tk-dist 代理透传 yudao 响应, HTTP 状态码为 200, 业务错误在 JSON code 字段
+ */
+declare class BusinessError extends Error {
+    code: number;
+    constructor(code: number, message: string);
+}
+/**
+ * 订单到达非成功终态 (FAILED/CANCELLED/CLOSED/EXPIRED/REFUNDED)
+ * waitForPayment 在订单终态为非成功时抛此错误
+ */
+declare class OrderTerminalError extends Error {
+    orderId: string;
+    status: string;
+    constructor(orderId: string, status: string);
+}
+/**
+ * 模型缓存未命中且 listModels 刷新后仍未找到。
+ *
+ * 历史上 getCachedModel miss 时硬返 ManagedModel{provider:"anthropic"} 占位,
+ * 导致未预热场景下的 chat 请求按 AnthropicAdapter 编码, 被发到错误端点。
+ * v0.13.x 改为 miss → listModels 自动刷新一次; 仍 miss → 抛此错误。
+ */
+declare class ModelNotFoundError extends Error {
+    modelId: string;
+    constructor(modelId: string);
+}
+/**
+ * 结构化 HTTP 非 2xx 错误.
+ *
+ * 用 instanceof 提取:
+ *   try { ... } catch (e) {
+ *     if (e instanceof HTTPError && e.statusCode === 429) { ... }
+ *   }
+ */
+declare class HTTPError extends Error {
+    statusCode: number;
+    /** anthropic.error.type / openai.error.type, 缺失为空 */
+    type: string;
+    /** Retry-After 头解析的秒数, 0 表示未提供或解析失败 */
+    retryAfter: number;
+    /** 原始响应体 (截断到 maxErrorBodySize) */
+    body: string;
+    constructor(statusCode: number, opts?: {
+        type?: string;
+        message?: string;
+        retryAfter?: number;
+        body?: string;
+    });
+}
+/**
+ * 结构化网络层错误 (传输失败, 区别于上游业务错误).
+ *
+ * 包装 fetch 抛出的错误 — 含 timeout / EOF / connection refused / DNS 失败等.
+ * retry policy: isTimeout / isEOF 任一为 true → 默认可重试.
+ */
+declare class NetworkError extends Error {
+    /** 操作描述, e.g. "POST /v1/messages" */
+    op: string;
+    /** 请求 URL (脱敏后) */
+    url: string;
+    cause?: unknown;
+    timeout: boolean;
+    eof: boolean;
+    constructor(op: string, url: string, cause: unknown, opts?: {
+        timeout?: boolean;
+        eof?: boolean;
+    });
+    isTimeout(): boolean;
+    isEOF(): boolean;
+}
+/**
+ * 流式失败事件的结构化表示。
+ *
+ * 由 gateway 的 `managed_model_stream_failed` 事件解析得到。客户端可通过
+ * instanceof 提取并按 code/retryable 决策。
+ */
+declare class StreamError extends Error {
+    /** 例: "empty_response" / "rate_limit" / "overloaded" / "" */
+    code: string;
+    /** 例: "provider" / "settlement" */
+    stage: string;
+    /** 用户友好提示 (中文); 历史字段, 与 rawError 区分 */
+    userMessage: string;
+    /** gateway 原始 error 字符串 */
+    rawError: string;
+    /** 客户端是否值得重试 */
+    retryable: boolean;
+    constructor(opts?: {
+        code?: string;
+        stage?: string;
+        message?: string;
+        rawError?: string;
+        retryable?: boolean;
+    });
+}
+
+/** nexus-v4 标准响应。兼容 yudao 格式 (msg) 和 nexus-v4 格式 (message) */
+interface APIResponse<T> {
+    code: number;
+    message?: string;
+    msg?: string;
+    data: T;
+}
+/** 优先返回 message, 降级到 msg (兼容 yudao 透传) */
+declare function apiResponseGetMessage<T>(r: APIResponse<T>): string;
+/** 检查业务层错误码 — code != 0 时抛 BusinessError */
+declare function apiResponseBusinessError<T>(r: APIResponse<T>): BusinessError | null;
+/** yudao 分页响应格式 (tk-dist 代理透传) */
+interface YudaoPageResult<T> {
+    list: T[];
+    total: number;
+}
+
+/** 排序方向。wire 上为小写字符串。 */
+type SortDirection = 'asc' | 'desc';
+/**
+ * 跨域统一分页【请求】参数。
+ *
+ * 既有域（billing / compliance / skills / notifications）各自内联了
+ * `page` / `pageNo` + `pageSize`，互不一致；本类型是为后续新命名空间
+ * （平台控制面 / `compliance.list*`）提供的统一形态。
+ *
+ * 字段全部可选 —— 调用方省略时由服务端取默认页；排序字段白名单由各命名
+ * 空间各自的 API 文档约定，SDK 不在客户端做字段校验。
+ */
+interface PageRequest {
+    /** 1-based 页码。 */
+    pageNo?: number;
+    /** 每页条数。 */
+    pageSize?: number;
+    /** 排序字段名（领域字段，由各命名空间文档约定白名单）。 */
+    sortBy?: string;
+    /** 排序方向；省略时由服务端决定默认值。 */
+    sortDirection?: SortDirection;
+}
+/**
+ * 跨域统一分页【结果】。
+ *
+ * **刻意做成 `YudaoPageResult<T>` 的别名** —— 全 SDK 单一分页结果结构
+ * `{ list, total }`。新命名空间统一用 `PageResult<T>` 这个对外名，
+ * 底层与 tk-dist 代理透传的 yudao 分页结构完全等价、零转换、零双标准。
+ */
+type PageResult<T> = YudaoPageResult<T>;
+
+type ComplianceProviderRequestStatus = 'PENDING' | 'SUCCESS' | 'FAILED' | 'UNKNOWN' | 'RETRYING';
+interface ProviderRequestStatusView {
+    id: number;
+    status: ComplianceProviderRequestStatus | string;
+    /** SUCCESS / FAILED 终态。 */
+    terminal: boolean;
+    /** 当前状态是否允许 SDK 安全重试请求（仅对 RETRYING 为 true）。 */
+    retryable: boolean;
+    businessNo?: string | null;
+    contractNo?: string | null;
+    sealId?: string | null;
+    attemptCount?: number | null;
+    reconciliationStatus?: string | null;
+    nextRetryAt?: string | null;
+    requestedAt?: string | null;
+    respondedAt?: string | null;
+}
+
+/** 统一操作关联键。贯通控制台 / API / MCP / CrabCode / scheduler 各来源。 */
+type OperationId = string;
+/**
+ * 操作来源。开放联合 —— 平台侧 5 种固定值，合规域可追加自定义来源字符串。
+ * `(string & {})` 在保留 IDE 字面量补全的同时不拒绝未知来源（后端保留新增空间）。
+ */
+type OperationSource = 'console' | 'api' | 'scheduler' | 'crabcode' | 'mcp' | (string & NonNullable<unknown>);
+/**
+ * 操作状态机。开放联合，后端保留新增空间。
+ *
+ * 与 `compliance/status.ts` 的 `ComplianceEnvelopeStatus` 等领域状态【正交】：
+ * 领域状态描述某个履约对象的业务态，`OperationStatus` 描述【一次操作】本身
+ * 的执行进度。
+ */
+type OperationStatus = 'pending' | 'running' | 'retrying' | 'awaiting_callback' | 'awaiting_verify' | 'succeeded' | 'failed' | 'canceled' | 'unknown' | (string & NonNullable<unknown>);
+/**
+ * 本地 verify 状态（§6.4）。
+ *
+ * provider success 仅表示 provider request 终态；时间章 / 签署 / 验签 /
+ * 证据包 / 报告发布须经后端本地 verify / evidence chain verify。`VerifyStatus`
+ * 与 provider 状态是【两个独立维度】，operation projection 必须分别展示
+ * （local verify failed → 业务 failed，不 billing settle）。
+ */
+type VerifyStatus = 'pending' | 'verified' | 'failed' | 'skipped' | 'unknown' | (string & NonNullable<unknown>);
+/**
+ * 幂等键。作用域 = tenant + principal/client + action + product；同 key 同
+ * canonical request 返回原结果，同 key 异 request 拒绝（§6.3 / §2 边界 9）。
+ * SDK 写接口经 `IdempotencyKeyHeader` 透传，调用方必须【持久化】key。
+ */
+type IdempotencyKey = string;
+/** 幂等键 HTTP header 名 —— 全 SDK 写接口的单一真相源。 */
+declare const IdempotencyKeyHeader: "Idempotency-Key";
+/**
+ * Provider request 状态。
+ *
+ * 复核约束（§9.4 勘误）：**不另造同名近似类型** —— 直接复用
+ * `compliance/provider/types.ts` 既有 `ComplianceProviderRequestStatus`
+ * （`PENDING` / `SUCCESS` / `FAILED` / `UNKNOWN` / `RETRYING`）。
+ */
+type ProviderRequestStatus = ComplianceProviderRequestStatus;
+
+/**
+ * SDK 内部 symbolic key；用于代码分支判断与文档。**不是 wire contract**。
+ */
+type ComplianceErrorKey = 'COMPLIANCE_UNAUTHORIZED' | 'COMPLIANCE_INSUFFICIENT_SCOPE' | 'COMPLIANCE_STEP_UP_REQUIRED' | 'COMPLIANCE_TOKEN_INVALID' | 'SUBJECT_SNAPSHOT_REQUIRED' | 'SUBJECT_SNAPSHOT_NOT_FOUND' | 'SUBJECT_SNAPSHOT_TENANT_MISMATCH' | 'EVIDENCE_ASSET_NOT_FOUND' | 'EVIDENCE_ASSET_HASH_MISMATCH' | 'EVIDENCE_ASSET_PAYLOAD_REQUIRED' | 'TIMESTAMP_TOKEN_NOT_FOUND' | 'TIMESTAMP_PROVIDER_FAILED' | 'TIMESTAMP_PROVIDER_UNKNOWN' | 'TIMESTAMP_LOCAL_VERIFY_FAILED' | 'TIMESTAMP_PROVIDER_NOT_AVAILABLE' | 'EVIDENCE_PACKAGE_NOT_FOUND' | 'EVIDENCE_PACKAGE_TIMESTAMP_REQUIRED' | 'EVIDENCE_PACKAGE_MANIFEST_HASH_MISMATCH' | 'REPORT_NOT_FOUND' | 'REPORT_ALREADY_PUBLISHED' | 'REPORT_DRAFT_REQUIRED' | 'EVIDENCE_VERIFY_TARGET_REQUIRED' | 'EVIDENCE_VERIFY_TARGET_NOT_FOUND' | 'PROVIDER_REQUEST_UNKNOWN_NO_RETRY' | 'PROVIDER_CALLBACK_SOURCE_INVALID' | 'PROVIDER_NOT_CONFIGURED' | 'PROVIDER_REQUEST_NOT_FOUND' | 'PROVIDER_REQUEST_IDEMPOTENCY_REQUIRED' | 'PROVIDER_REQUEST_STATUS_NOT_TERMINAL' | 'ENVELOPE_NOT_FOUND' | 'ENVELOPE_TENANT_MISMATCH' | 'ENVELOPE_STATE_NOT_ALLOWED' | 'ENVELOPE_GATE_CLOSED' | 'CONTRACT_NOT_FOUND' | 'CONTRACT_HASH_MISMATCH' | 'PROVIDER_AUTHORIZATION_NOT_CONFIRMED' | 'ENVELOPE_EVIDENCE_NOT_READY' | 'SEAL_ASSET_NOT_FOUND' | 'SEAL_APPROVAL_NOT_FOUND' | 'SEAL_APPROVAL_STATE_NOT_APPROVED' | 'SEAL_APPROVAL_EXPIRED' | 'SEAL_APPROVAL_ALREADY_USED' | 'SEAL_APPROVAL_NONCE_USED' | 'SEAL_APPROVAL_SEAL_MISMATCH' | 'SEAL_APPROVAL_LOCATION_MISMATCH' | 'SEAL_APPROVAL_TRANSACTOR_MISMATCH' | 'SEAL_APPROVAL_CONTRACT_HASH_MISMATCH' | 'SEAL_APPROVAL_INVALID_TRANSITION' | 'SEAL_USE_ALREADY_CONSUMED' | 'AUDIT_CHAIN_TAMPER_DETECTED' | 'BILLING_COMMIT_REQUIRES_LOCAL_VERIFY' | 'BILLING_COMMIT_REQUIRES_PROVIDER_SUCCESS' | 'BILLING_CALLBACK_CANNOT_COMMIT' | 'BILLING_PROVIDER_UNKNOWN_NOT_COMMITTABLE' | 'BILLING_S2S_FORBIDDEN' | 'UNKNOWN_COMPLIANCE_ERROR';
+/** 单个错误的 SDK 视图。 */
+interface ComplianceErrorInfo {
+    /** Java numeric error code (wire contract)。 */
+    code: number;
+    /** 服务端原始 message（中文，可变）；仅用于日志/展示。 */
+    message: string;
+    /** SDK 分支判断用 symbolic key。 */
+    key: ComplianceErrorKey;
+    /** 是否安全自动重试 — compliance 写接口几乎全为 false。 */
+    retryable: boolean;
+    /** 是否已经是终态 — 用户必须用新 idempotency-key 重新发起。 */
+    terminal: boolean;
+    /** 高风险动作需要 step-up / introspection。 */
+    stepUpRequired: boolean;
+}
+/**
+ * 把一个 BusinessError 分类为 compliance 视图。
+ * 非 compliance 段位的错误码会回退到 UNKNOWN_COMPLIANCE_ERROR，调用方应该当作业务错误处理。
+ */
+declare function classifyComplianceError(err: BusinessError): ComplianceErrorInfo;
+/**
+ * 判断 BusinessError 是否属于 compliance 段位（1-031-xxx-xxx）。
+ * 不在段位的错误码可能来自其它 yudao 模块，按通用业务错误处理即可。
+ */
+declare function isComplianceBusinessError(err: BusinessError): boolean;
+
+/**
+ * 失败补救原因。开放枚举的【封闭】部分 —— 这 11 个值覆盖 §6.6 要求的全集。
+ *
+ * 其中 `gate_closed` / `step_up_required` / `tenant_mismatch` /
+ * `insufficient_scope` 与既有错误码登记表同名概念一一对应（见下方映射表），
+ * 不是新造的码。
+ */
+type RetryAdviceReason = 'unknown' | 'retrying' | 'failed' | 'gate_closed' | 'step_up_required' | 'tenant_mismatch' | 'insufficient_scope' | 'quota_exceeded' | 'provider_timeout' | 'local_verify_failed' | 'billing_preflight_failed';
+/** `RetryAdviceReason` 全集（11 项）—— 供迭代 / 校验使用。 */
+declare const RETRY_ADVICE_REASONS: readonly RetryAdviceReason[];
+/**
+ * 失败补救建议统一模型（§6.6）。
+ *
+ * 高风险 / 收费动作失败后，后端 operation projection 产出本结构告诉调用方
+ * 「能不能重试、要不要换幂等键、要不要人工介入」。
+ */
+interface RetryAdvice {
+    /** 是否值得【自动】重试。compliance 写接口几乎恒为 false（双扣红线）。 */
+    retryable: boolean;
+    /** 建议的重试等待时长（秒）；与 `HTTPError.retryAfter` 单位一致。 */
+    retryAfter?: number;
+    /**
+     * 重试时是否必须沿用【同一】幂等键。
+     * 同 key 同 canonical request → 服务端返回原结果（对账语义）；
+     * 终态错误须改用【新】幂等键重新发起（§6.3）。
+     */
+    sameIdempotencyKeyRequired: boolean;
+    /** 是否需要人工介入（重新登录 / step-up / 联系支持），不能纯自动恢复。 */
+    manualActionRequired: boolean;
+    /** 归一化失败原因。 */
+    reason: RetryAdviceReason;
+    /** 面向终端用户的提示文案（调用方可用自有 copy 表覆盖）。 */
+    userMessage?: string;
+    /** 面向开发者的诊断信息（如服务端原始 message）。 */
+    developerMessage?: string;
+    /** 支持工单关联码（如 `compliance:1031004004`）。 */
+    supportCode?: string;
+}
+/** SDK compliance 符号 key → `RetryAdviceReason`。未知 key 兜底 `unknown`。 */
+declare function retryReasonForComplianceKey(key: ComplianceErrorKey): RetryAdviceReason;
+/** Go OAuth 标准错误字符串 → `RetryAdviceReason`。未登记的兜底 `unknown`。 */
+declare function retryReasonForOAuthError(oauthError: string): RetryAdviceReason;
+/**
+ * 把 `ComplianceErrorInfo`（compliance/errors.ts `classifyComplianceError` 的产出）
+ * 投影为统一 `RetryAdvice`。
+ *
+ * 语义：
+ *   - `retryable` 直接透传 `info.retryable`（compliance 写接口恒 false）。
+ *   - 终态错误（`info.terminal`）→ 须改用【新】幂等键 →
+ *     `sameIdempotencyKeyRequired=false`、`manualActionRequired=true`。
+ *   - step-up 错误 → 重新做 OAuth introspection 后用【同一】幂等键重试 →
+ *     `sameIdempotencyKeyRequired=true`、`manualActionRequired=true`。
+ *   - 其余（非终态、非 step-up）→ 沿用同一幂等键对账重发。
+ *
+ * 不读、不写 `ComplianceErrorInfo` 以外的状态；入参不被 mutate。
+ */
+declare function complianceErrorToRetryAdvice(info: ComplianceErrorInfo): RetryAdvice;
+
+/**
+ * 租户轻量引用。
+ *
+ * 完整租户详情（状态 / 类型 / 产品开通 / 主体类型 / 地区 / 组织配置）见
+ * 后续 `tenant` 命名空间。
+ */
+interface TenantRef {
+    tenantId: string;
+    /** 展示名；后端可省略。 */
+    name?: string;
+}
+/**
+ * Principal（操作主体）轻量引用。
+ *
+ * 完整 principal 视图（脱敏联系方式 / 角色 / scope / 认证方式 / token jti /
+ * 登录来源）见后续 `iam` 命名空间。前端【不自解 JWT】推断身份（§1.1 复核
+ * 边界）—— 一律由 SDK 暴露稳定 principal。
+ */
+interface PrincipalRef {
+    principalId: string;
+    /** 关联用户 id；与 `principalId` 可能不同（同一用户多 principal）。 */
+    userId?: string;
+    /** 所属租户 id。 */
+    tenantId?: string;
+    /** 展示名；后端可省略。 */
+    displayName?: string;
+}
+/**
+ * API client 轻量引用。
+ *
+ * 完整 API client 治理（CRUD / secret 轮换 / 回调域名 / IP 白名单 / 调用
+ * 日志）见对外鉴权层独立计划范围 —— 本期不实现（用户决策 2026-05-22）。
+ */
+interface ApiClientRef {
+    clientId: string;
+    /** 展示名；后端可省略。 */
+    name?: string;
+}
+
+/**
+ * 高风险 / 收费动作的 gate 状态机（§U-6）。开放联合，后端保留新增空间。
+ *
+ * `gates.ts`（csign workbench）拿不到能力时 fail-closed 返回 `unknown` —
+ * 与本枚举的 `unknown` 一致。
+ */
+type FeatureGateState = 'executable' | 'scope_missing' | 'not_provisioned' | 'quota_exceeded' | 'step_up_required' | 'gate_closed' | 'unknown' | (string & NonNullable<unknown>);
+/** 配额快照。`FeatureGateStatus.quota` 与 `BillingPreflightResult` 复用。 */
+interface GateQuota {
+    /** 配额上限。 */
+    limit?: number;
+    /** 已用量。 */
+    used?: number;
+    /** 剩余量。 */
+    remaining?: number;
+    /** 配额单位（如 `etu` / `count`）；后端可省略。 */
+    unit?: string;
+}
+/**
+ * step-up（高风险动作二次验证）状态（§6.1）。
+ *
+ * 字段形态先行沉淀；step-up 发起 / 校验的【后端运行期能力】随对外鉴权层
+ * 计划本期不实施。
+ */
+interface StepUpStatus {
+    /** 当前动作是否要求 step-up。 */
+    required: boolean;
+    /** 是否已满足（已完成且未过期）。 */
+    satisfied: boolean;
+    /** step-up 方式（如 `webauthn` / `oauth_introspection`）；后端可省略。 */
+    method?: string;
+    /** 满足态过期时间（ISO 8601）；未满足时省略。 */
+    expiresAt?: string;
+    /** 未满足 / 失败原因；满足时省略。 */
+    reason?: string;
+}
+/**
+ * gate / capability 查询结果（§U-6）。
+ *
+ * 高风险动作（signEnvelope / createH5SigningUrl / publishReport /
+ * approveSealApproval / executeSealUse / claimLeadWithConflictOverride）执行前
+ * 查询本结构，区分「可执行 / scope 缺失 / 未开通 / quota 不足 / 需 step-up /
+ * gate closed」。拿不到时必须 fail-closed（`executable=false`，§2 边界 7）。
+ */
+interface FeatureGateStatus {
+    /** 最终是否可执行。fail-closed：拿不到能力时为 false。 */
+    executable: boolean;
+    /** 不可执行的具体状态。 */
+    state: FeatureGateState;
+    /** 缺失 / 所需 OAuth scope。 */
+    requiredScopes?: string[];
+    /** 是否需要 step-up。 */
+    requiredStepUp?: boolean;
+    /** 缺失的 entitlement / feature 标识。 */
+    missingEntitlements?: string[];
+    /** 配额快照。 */
+    quota?: GateQuota;
+    /** 人类可读原因（诊断 / 展示）。 */
+    reason?: string;
+    /** 失败补救建议（叠加层，见 retry-advice.ts）。 */
+    retryAdvice?: RetryAdvice;
+    /** 关联 operation / preflight id。 */
+    operationId?: OperationId;
+}
+/**
+ * 收费 / 高风险动作的 billing preflight 结果（§4.4 / §4.5）。
+ *
+ * 在动作执行【前】返回可执行性、预估扣费、所需 step-up / scopes。金额字段为
+ * `string`（json.Number 端口，避免 JS number 精度损失 —— 金融安全红线）。
+ */
+interface BillingPreflightResult {
+    /** 是否可执行（含 quota / entitlement / gate 综合判定）。 */
+    executable: boolean;
+    /** 预估扣费金额；`string` 表示，避免浮点精度丢失。 */
+    estimatedCharge?: string;
+    /** 计费单位 / 币种（如 `etu` / `CNY`）。 */
+    currency?: string;
+    /** 所需 OAuth scope。 */
+    requiredScopes?: string[];
+    /** 是否需要 step-up。 */
+    requiredStepUp?: boolean;
+    /** 配额快照。 */
+    quota?: GateQuota;
+    /** 失败补救建议。 */
+    retryAdvice?: RetryAdvice;
+    /** preflight 关联 id —— 后续真实扣费动作回填以串联 hold/settle/release。 */
+    preflightId?: string;
+    /** 不可执行原因（诊断 / 展示）。 */
+    reason?: string;
+}
+
+declare const ScopeAI = "ai";
+declare const ScopeSkills = "skills";
+declare const ScopeAccount = "account";
+/** @deprecated 旧细粒度 scope, 保留向后兼容, 新代码请用分组 scope */
+declare const ScopeModels = "models";
+/** @deprecated */
+declare const ScopeModelsChat = "models:chat";
+/** @deprecated */
+declare const ScopeEntitlements = "entitlements";
+/** @deprecated */
+declare const ScopeTokenPackages = "token-packages";
+/** @deprecated */
+declare const ScopeSkillStore = "skill_store";
+/** @deprecated */
+declare const ScopeTools = "tools";
+/** @deprecated */
+declare const ScopeToolsExecute = "tools:execute";
+/** @deprecated */
+declare const ScopeWallet = "wallet";
+/** @deprecated */
+declare const ScopeWalletReadonly = "wallet:readonly";
+/** @deprecated */
+declare const ScopeProfile = "profile";
+/** 全部分组 scope (推荐) */
+declare function allScopes(): string[];
+/** 模型服务相关 scope */
+declare function modelScopes(): string[];
+/** 商城/钱包 scope */
+declare function commerceScopes(): string[];
+/** 技能/工具 scope */
+declare function skillScopes(): string[];
+
+interface OpenAIChatResponse {
+    id: string;
+    /** "chat.completion" */
+    object: string;
+    model: string;
+    choices: OpenAIChatChoice[];
+    usage: OpenAIUsage;
+}
+interface OpenAIChatChoice {
+    index: number;
+    message: OpenAIChatMessage;
+    /** "stop", "tool_calls", "length" */
+    finish_reason: string;
+}
+interface OpenAIChatMessage {
+    role: string;
+    content: string;
+    tool_calls?: OpenAIToolCall[];
+    /** GLM/DeepSeek thinking */
+    reasoning_content?: string;
+}
+interface OpenAIToolCall {
+    id: string;
+    /** "function" */
+    type: string;
+    function: OpenAIFunctionCall;
+}
+interface OpenAIFunctionCall {
+    name: string;
+    arguments: string;
+}
+interface OpenAIUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+/** OpenAI SSE delta 格式 */
+interface OpenAIStreamChunk {
+    id: string;
+    /** "chat.completion.chunk" */
+    object: string;
+    choices: OpenAIStreamChoice[];
+    usage?: OpenAIUsage;
+}
+interface OpenAIStreamChoice {
+    index: number;
+    delta: OpenAIStreamDelta;
+    finish_reason: string | null;
+}
+interface OpenAIStreamDelta {
+    role?: string;
+    content?: string;
+    reasoning_content?: string;
+    tool_calls?: OpenAIStreamToolCall[];
+}
+interface OpenAIStreamToolCall {
+    index: number;
+    id?: string;
+    type?: string;
+    function: OpenAIFunctionCall;
+}
+
+/**
+ * 判断 ManagedModel 是否声明支持指定输入模态.
+ *
+ * 语义:
+ *   - model 为 null/undefined → false
+ *   - model.inputModalities 缺失或非数组 → false (保守, 未声明不当支持)
+ *   - 大小写敏感 (上游契约即小写 'text' | 'image')
+ */
+declare function modelSupportsInputModality(model: ManagedModel | null | undefined, modality: InputModality): boolean;
+/** 等价 modelSupportsInputModality(model, 'image') — 调用方常见快捷判定. */
+declare function modelSupportsImageInput(model: ManagedModel | null | undefined): boolean;
+/**
+ * 在 catalog 中按 catalog 顺序查找首个支持指定模态的模型.
+ *
+ * 选择规则:
+ *   1. isEnabled !== false (默认开, 显式 false 才剔除)
+ *   2. inputModalities 包含指定模态
+ *   3. 命中后按 catalog 顺序返回第一个; 未命中返 null
+ *
+ * 注意: 该 helper 不读 isDefault, 调用方需要 "默认优先" 请用
+ * findDesktopVisualUnderstandingModel 或自行排序.
+ */
+declare function findFirstModelByInputModality(models: ManagedModel[], modality: InputModality): ManagedModel | null;
+/**
+ * 在 catalog 中选出最适合做 "桌面视觉理解 sidecar" 的模型.
+ *
+ * 设计目的: CrabCode desktop automation 链路里, 主模型不一定多模态;
+ * 截图先送 sidecar 解析成结构化 UI 描述, 再喂主模型. 这里选 sidecar 模型
+ * 严格走运营标注的 supports_desktop_visual_understanding capability, 不靠
+ * 模型名猜.
+ *
+ * 选择规则 (按用户指定顺序):
+ *   1. isEnabled !== false
+ *   2. capabilities.supports_desktop_visual_understanding === true
+ *   3. inputModalities 包含 'image' (必须真能吃图)
+ *   4. 命中集合中优先 isDefault === true; 否则返回 catalog 顺序第一个
+ *
+ * 全部不满足返 null. 调用方收到 null 应:
+ *   - 提示用户在管理后台/网关侧开启桌面视觉 sidecar 模型, 或
+ *   - 降级停掉依赖截图的工作流, 而不是硬选一个非视觉模型送图.
+ */
+declare function findDesktopVisualUnderstandingModel(models: ManagedModel[]): ManagedModel | null;
+
+/** SDK 为单个 content block 缓存的元数据 */
+interface BlockMeta {
+    type: string;
+    ephemeral: boolean;
+}
+/**
+ * 按 Anthropic SSE 事件类型解析 data, 更新 blockTypeMap, 返回 [index, type, ephemeral]。
+ *
+ * 仅当事件为 content_block_start / content_block_delta / content_block_stop
+ * 时返回非空 type; 其他事件返回空 type, 调用方据此判别是否填充 StreamEvent 元数据字段。
+ */
+declare function extractAnthropicBlockMeta(eventType: string, data: string, blockTypeMap: Map<number, BlockMeta>): [number, string, boolean];
+
+/** 根据模型能力和请求参数自动组装 beta header 列表 */
+declare function buildBetas(caps: ModelCapabilities, req: ChatRequest): string[];
+/** 合并两个字符串数组并去重, 保留顺序 */
+declare function uniqueMerge(base: string[], extra: string[]): string[];
+
+declare module '@acosmi/sdk-ts' {
+    interface Client {
+        /** 查询当前用户的权益余额 (聚合) */
+        getBalance(signal?: AbortSignal): Promise<EntitlementBalance>;
+        /** 查询详细余额 (含每条权益明细) */
+        getBalanceDetail(signal?: AbortSignal): Promise<BalanceDetail>;
+        /** 查询当前用户权益列表; status: "ACTIVE" / "EXPIRED" / "" (全部) */
+        listEntitlements(status: string, signal?: AbortSignal): Promise<EntitlementItem[]>;
+        /** 查询核销记录 (分页) */
+        listConsumeRecords(page: number, pageSize: number, signal?: AbortSignal): Promise<ConsumeRecordPage>;
+        /** 领取当月免费额度 — 幂等: 已领取时返回已有权益 */
+        claimMonthlyFree(signal?: AbortSignal): Promise<EntitlementItem>;
+        /** 查询当前用户在指定模型下的剩余 token (raw + ETU) */
+        getByModel(modelID: string, signal?: AbortSignal): Promise<ModelByQuotaResponse>;
+        /** 列出当前用户的全部桶 */
+        listBuckets(signal?: AbortSignal): Promise<ModelBucket[]>;
+        /** 拉取模型系数表; SDK 自带 8s TTL 内存缓存以减小调用风暴. */
+        listCoefficients(signal?: AbortSignal): Promise<ModelCoefficient[]>;
+        /** 手动失效系数缓存 (admin 调价后建议立即调一次) */
+        invalidateCoefficientCache(): void;
+    }
+}
+
+declare module '@acosmi/sdk-ts' {
+    interface Client {
+        /** 获取商城流量包列表 (兼容 yudao 分页和直接数组两种格式) */
+        listTokenPackages(signal?: AbortSignal): Promise<TokenPackage[]>;
+        /** 获取流量包详情 */
+        getTokenPackageDetail(packageID: string, signal?: AbortSignal): Promise<TokenPackage>;
+        /** 购买流量包 (创建订单) */
+        buyTokenPackage(packageID: string, payload: PayPayload | null, signal?: AbortSignal): Promise<Order>;
+        /** 查询订单支付状态 */
+        getOrderStatus(orderID: string, signal?: AbortSignal): Promise<OrderStatus>;
+        /** 查询我的订单列表 */
+        listMyOrders(signal?: AbortSignal): Promise<Order[]>;
+        /**
+         * 轮询订单支付状态直到终态
+         * 成功支付返回 status; 终态失败抛 OrderTerminalError
+         * pollIntervalMs <= 0 时默认 2 秒
+         */
+        waitForPayment(orderID: string, pollIntervalMs: number, signal?: AbortSignal): Promise<OrderStatus>;
+    }
+}
+
+declare module '@acosmi/sdk-ts' {
+    interface Client {
+        /** 获取钱包统计 (余额/月消费/月充值) */
+        getWalletStats(signal?: AbortSignal): Promise<WalletStats>;
+        /** 获取最近交易记录 */
+        getWalletTransactions(signal?: AbortSignal): Promise<Transaction[]>;
+    }
+}
+
+interface SkillStoreItem {
+    id: string;
+    pluginId: string;
+    key: string;
+    name: string;
+    description: string;
+    icon: string;
+    category: string;
+    inputSchema: string;
+    outputSchema: string;
+    timeout: number;
+    retryCount: number;
+    retryDelay: number;
+    version: string;
+    totalCalls: number;
+    avgDurationMs: number;
+    successRate: number;
+    isEnabled: boolean;
+    securityLevel: string;
+    securityScore: number;
+    scope: string;
+    status: string;
+    downloadCount: number;
+    readme: string;
+    tags: string[];
+    author: string;
+    publisherId: string;
+    isPublished: boolean;
+    pluginName: string;
+    pluginIcon: string;
+    updatedAt: string;
+    visibility?: string;
+    certificationStatus?: string;
+    source?: string;
+}
+/** 技能商店搜索参数 (非 wire 类型, 用于 client 方法参数) */
+interface SkillStoreQuery {
+    category?: string;
+    keyword?: string;
+    tag?: string;
+}
+/** 技能统计概览 */
+interface SkillSummary {
+    installed: number;
+    created: number;
+    total: number;
+    storeAvailable: number;
+}
+/** 技能商店分页浏览响应 */
+interface SkillBrowseResponse {
+    items: SkillStoreItem[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+/**
+ * 技能商店列表项（轻量，仅含浏览所需字段）
+ * 配合服务端 fields=minimal 参数使用，响应体积缩减 90%+
+ */
+interface SkillStoreListItem {
+    id: string;
+    key: string;
+    name: string;
+    description: string;
+    icon: string;
+    category: string;
+    version: string;
+    author: string;
+    downloadCount: number;
+    tags: string[];
+    certificationStatus?: string;
+    visibility?: string;
+    source?: string;
+    updatedAt: string;
+}
+/** 技能商店轻量浏览响应 */
+interface SkillBrowseListResponse {
+    items: SkillStoreListItem[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+/** 技能认证状态响应 */
+interface CertificationStatus {
+    skillId: string;
+    certificationStatus: string;
+    certifiedAt?: number;
+    securityLevel?: string;
+    securityScore: number;
+    report?: unknown;
+}
+interface GenerateSkillRequest {
+    purpose: string;
+    examples?: string[];
+    inputHints?: string;
+    outputHints?: string;
+    category?: string;
+    language?: string;
+}
+interface GenerateSkillResult {
+    skillName: string;
+    skillKey: string;
+    description: string;
+    skillMd: string;
+    inputSchema: string;
+    outputSchema: string;
+    testCases: string[];
+    readme: string;
+    category: string;
+    tags: string[];
+    timeout: number;
+}
+interface OptimizeSkillRequest {
+    skillName: string;
+    description?: string;
+    inputSchema?: string;
+    outputSchema?: string;
+    readme?: string;
+    aspects?: string[];
+}
+interface OptimizeSkillResult {
+    optimizedSkill: GenerateSkillResult;
+    changes: string[];
+    score: number;
+}
+interface ToolView {
+    id: string;
+    key: string;
+    name: string;
+    description: string;
+    icon: string;
+    category: string;
+    inputSchema: string;
+    outputSchema: string;
+    timeout: number;
+    isEnabled: boolean;
+    provider?: ToolProvider;
+}
+interface ToolProvider {
+    id: string;
+    name: string;
+    icon: string;
+    sourceType: string;
+    mcpEndpoint?: string;
+    isEnabled: boolean;
+}
+interface ToolListResponse {
+    skills: ToolView[];
+    total: number;
+}
+
+declare module '@acosmi/sdk-ts' {
+    interface Client {
+        /** 浏览技能商店 (公共端点, 无需认证) */
+        browseSkillStore(query: SkillStoreQuery, signal?: AbortSignal): Promise<SkillStoreItem[]>;
+        /** 浏览公共技能商店 (V3 分页接口) */
+        browseSkills(page: number, pageSize: number, category: string, keyword: string, tag: string, source: string, signal?: AbortSignal): Promise<SkillBrowseResponse>;
+        /** 轻量浏览公共技能商店 (fields=minimal, 响应体积缩减 90%+) */
+        browseSkillsList(page: number, pageSize: number, category: string, keyword: string, tag: string, source: string, signal?: AbortSignal): Promise<SkillBrowseListResponse>;
+        /** 获取技能商店中某个技能的详情 (公共端点) */
+        getSkillDetail(skillID: string, signal?: AbortSignal): Promise<SkillStoreItem>;
+        /** 按 key 精确查找公共技能 (公共端点) */
+        resolveSkill(key: string, signal?: AbortSignal): Promise<SkillStoreItem>;
+        /** 安装技能到当前用户的租户空间 (需 OAuth scope: skill_store) */
+        installSkill(skillID: string, signal?: AbortSignal): Promise<SkillStoreItem>;
+        /**
+         * 下载技能 ZIP 包 (公共端点, 双模式)
+         * 有 token 时自动附带 (享受无限流), 无 token 时匿名 (受限流)
+         * @returns [data, filename]; 限流时抛 RateLimitError
+         */
+        downloadSkill(skillID: string, signal?: AbortSignal): Promise<{
+            data: Uint8Array;
+            filename: string;
+        }>;
+        /**
+         * 上传技能 ZIP 包
+         * @param scope "TENANT"
+         * @param intent "PERSONAL" (仅自己用) 或 "PUBLIC_INTENT" (走认证→公开)
+         */
+        uploadSkill(zipData: Uint8Array, scope: string, intent: string, signal?: AbortSignal): Promise<SkillStoreItem>;
+        /** 获取技能统计概览 */
+        getSkillSummary(signal?: AbortSignal): Promise<SkillSummary>;
+        /** 触发技能认证管线 (异步) */
+        certifySkill(skillID: string, signal?: AbortSignal): Promise<void>;
+        /** 查询技能认证状态 */
+        getCertificationStatus(skillID: string, signal?: AbortSignal): Promise<CertificationStatus>;
+        /** 根据自然语言描述生成技能定义 (基于独立 LLM) */
+        generateSkill(req: GenerateSkillRequest, signal?: AbortSignal): Promise<GenerateSkillResult>;
+        /** 优化已有技能定义 */
+        optimizeSkill(req: OptimizeSkillRequest, signal?: AbortSignal): Promise<OptimizeSkillResult>;
+        /** 校验技能定义正确性 */
+        validateSkill(skillName: string, signal?: AbortSignal): Promise<void>;
+    }
+}
+
+declare module '@acosmi/sdk-ts' {
+    interface Client {
+        /** 获取当前用户租户下的所有工具 (Skill 优先 + Plugin 兜底) */
+        listTools(signal?: AbortSignal): Promise<ToolView[]>;
+        /** 获取单个工具详情 */
+        getTool(toolID: string, signal?: AbortSignal): Promise<ToolView>;
+    }
+}
+
+/** 单条通知 */
+interface Notification {
+    id: string;
+    title: string;
+    content: string;
+    /** system | billing | security | task | commission | entitlement */
+    type: string;
+    isRead: boolean;
+    createdAt: string;
+}
+/** 分页通知列表 */
+interface NotificationList {
+    list: Notification[];
+    unreadCount: number;
+    total: number;
+    page: number;
+    pageSize: number;
+}
+/** 未读通知计数 */
+interface NotificationUnreadCount {
+    unreadCount: number;
+}
+/** 通知偏好 (按类型+渠道) */
+interface NotificationPreference {
+    typeCode: string;
+    channelInApp: boolean;
+    channelEmail: boolean;
+    channelSms: boolean;
+    channelPush: boolean;
+}
+/** 推送设备注册 */
+interface DeviceRegistration {
+    /** android | ios | harmony */
+    platform: string;
+    token: string;
+    appVersion: string;
+}
+/** 服务端推送事件 */
+interface WSEvent {
+    type: string;
+    topic?: string;
+    /** json.RawMessage in Go */
+    data?: unknown;
+    connId?: string;
+    timestamp?: string;
+    message?: string;
+}
+/**
+ * 从 WSEvent 中解析通知
+ * 返回 null 表示该事件不是系统通知
+ */
+declare function parseNotificationEvent(ev: WSEvent): Notification | null;
+
+declare module '@acosmi/sdk-ts' {
+    interface Client {
+        /** 分页查询通知列表 */
+        listNotifications(page: number, pageSize: number, typeFilter: string, signal?: AbortSignal): Promise<NotificationList>;
+        /** 获取未读通知数量 */
+        getUnreadCount(signal?: AbortSignal): Promise<number>;
+        /** 标记单条通知已读 */
+        markNotificationRead(id: string, signal?: AbortSignal): Promise<void>;
+        /** 标记全部通知已读 */
+        markAllNotificationsRead(signal?: AbortSignal): Promise<void>;
+        /** 删除通知 */
+        deleteNotification(id: string, signal?: AbortSignal): Promise<void>;
+        /** 注册推送设备 token */
+        registerDevice(reg: DeviceRegistration, signal?: AbortSignal): Promise<void>;
+        /** 注销推送设备 token */
+        unregisterDevice(token: string, signal?: AbortSignal): Promise<void>;
+        /** 获取通知偏好设置 */
+        listNotificationPreferences(signal?: AbortSignal): Promise<NotificationPreference[]>;
+        /** 更新通知偏好 */
+        updateNotificationPreference(typeCode: string, pref: NotificationPreference, signal?: AbortSignal): Promise<void>;
+    }
+}
+
+/** WebSocket 长连接配置 */
+interface WSConfig {
+    /** 收到服务端事件回调 */
+    onEvent?: (ev: WSEvent) => void;
+    /** 连接建立回调 */
+    onConnect?: () => void;
+    /** 断线回调 */
+    onDisconnect?: (err: unknown) => void;
+    /** 自动订阅的主题 */
+    topics?: string[];
+    /** 最小重连间隔 (ms, 默认 2000) */
+    reconnectMinMs?: number;
+    /** 最大重连间隔 (ms, 默认 60000) */
+    reconnectMaxMs?: number;
+    /** 是否自动重连 (默认 true) */
+    autoReconnect?: boolean;
+}
+declare module '@acosmi/sdk-ts' {
+    interface Client {
+        /**
+         * 建立 WebSocket 长连接 — 等待首次连接成功或 abort。
+         */
+        connect(cfg: WSConfig, signal?: AbortSignal): Promise<void>;
+        /** 优雅断开 WebSocket 连接 */
+        disconnect(): Promise<void>;
+        /** WebSocket 是否已连接 */
+        isConnected(): boolean;
+    }
+}
+
+type AgentRunStatus = 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
+interface AgentRunLocalContextPolicy {
+    enabled?: boolean;
+    readonly?: boolean;
+    maxBytes?: number;
+    allowedTools?: string[];
+}
+interface AgentRunArtifactPolicy {
+    enabled?: boolean;
+    maxFiles?: number;
+}
+interface AgentRunCreateRequest {
+    appId: string;
+    mode?: string;
+    sessionId?: string;
+    input: string;
+    messages?: unknown[];
+    model?: string;
+    activeSkillIds?: string[];
+    knowledgeBaseIds?: string[];
+    metadata?: Record<string, string>;
+    localContextPolicy?: AgentRunLocalContextPolicy;
+    artifactPolicy?: AgentRunArtifactPolicy;
+}
+interface AgentRun {
+    runId: string;
+    sessionId: string;
+    appId?: string;
+    mode?: string;
+    status: AgentRunStatus;
+    createdAt?: string;
+    startedAt?: string;
+    completedAt?: string;
+    error?: AgentRunErrorPayload;
+    metadata?: Record<string, string>;
+}
+interface AgentRunCreateResponse {
+    runId: string;
+    sessionId: string;
+    status: AgentRunStatus;
+}
+interface AgentRunArtifact {
+    id: string;
+    filename: string;
+    contentType?: string;
+    size?: number;
+    type?: string;
+    metadata?: Record<string, string>;
+}
+interface AgentRunArtifactList {
+    artifacts: AgentRunArtifact[];
+}
+interface AgentRunDownload {
+    data: Uint8Array;
+    filename: string;
+    contentType?: string;
+}
+interface AgentRunUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    cacheReadTokens?: number;
+    cacheCreateTokens?: number;
+    exact?: boolean;
+    source?: string;
+    [key: string]: unknown;
+}
+interface AgentRunSettlement {
+    requestId?: string;
+    status?: string;
+    consumeStatus?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    cacheReadTokens?: number;
+    cacheCreateTokens?: number;
+    tokenRemaining?: number;
+    callRemaining?: number;
+    retryQueued?: boolean;
+    exact?: boolean;
+    [key: string]: unknown;
+}
+interface AgentRunErrorPayload {
+    code?: string;
+    message: string;
+    stage?: string;
+    retryable?: boolean;
+    raw?: unknown;
+}
+interface AgentRunLocalToolResult {
+    requestId: string;
+    ok: boolean;
+    content?: unknown;
+    error?: string;
+}
+interface AgentRunLocalToolHandlerContext {
+    runId: string;
+    requestId: string;
+    name: string;
+    signal: AbortSignal;
+}
+type AgentRunLocalToolHandler = (input: unknown, context: AgentRunLocalToolHandlerContext) => Promise<unknown> | unknown;
+interface AgentRunStreamOptions {
+    /**
+     * true by default. When enabled, an error event is converted into
+     * AgentRunStreamError after the event has been parsed.
+     */
+    throwOnError?: boolean;
+}
+interface AgentRunRunOptions extends AgentRunStreamOptions {
+}
+interface AgentRunWithLocalToolsOptions extends AgentRunRunOptions {
+    timeoutMs?: number;
+    onEvent?: (event: AgentRunStreamEvent) => void | Promise<void>;
+}
+type AgentRunStreamEvent = {
+    type: 'run_started';
+    runId: string;
+    sessionId: string;
+} | {
+    type: 'status';
+    status: AgentRunStatus | string;
+    message?: string;
+} | {
+    type: 'text_delta';
+    text: string;
+} | {
+    type: 'reasoning_delta';
+    text: string;
+} | {
+    type: 'tool_call';
+    id: string;
+    name: string;
+    input?: unknown;
+} | {
+    type: 'tool_result';
+    id: string;
+    name?: string;
+    result?: unknown;
+    error?: string;
+} | {
+    type: 'local_tool_request';
+    requestId: string;
+    name: string;
+    input: unknown;
+} | {
+    type: 'artifact';
+    artifact: AgentRunArtifact;
+} | {
+    type: 'sources';
+    sources: unknown;
+} | {
+    type: 'usage';
+    usage: AgentRunUsage;
+} | {
+    type: 'settle';
+    settlement: AgentRunSettlement;
+} | {
+    type: 'error';
+    error: AgentRunErrorPayload;
+} | {
+    type: 'done';
+    runId: string;
+    status: AgentRunStatus | string;
+};
+declare class AgentRunStreamError extends Error {
+    event: Extract<AgentRunStreamEvent, {
+        type: 'error';
+    }>;
+    code: string;
+    stage: string;
+    retryable: boolean;
+    constructor(event: Extract<AgentRunStreamEvent, {
+        type: 'error';
+    }>);
+}
+
+declare module '@acosmi/sdk-ts' {
+    interface Client {
+        /** SDK-facing cloud agent run gateway. */
+        readonly agentRuns: AgentRunsClient;
+    }
+}
+declare class AgentRunsClient {
+    private readonly client;
+    constructor(client: Client);
+    create(req: AgentRunCreateRequest, signal?: AbortSignal): Promise<AgentRunCreateResponse>;
+    get(runId: string, signal?: AbortSignal): Promise<AgentRun>;
+    stream(runId: string, opts?: AgentRunStreamOptions, signal?: AbortSignal): AsyncIterable<AgentRunStreamEvent>;
+    cancel(runId: string, signal?: AbortSignal): Promise<AgentRun>;
+    listArtifacts(runId: string, signal?: AbortSignal): Promise<AgentRunArtifact[]>;
+    downloadArtifact(runId: string, artifactId: string, signal?: AbortSignal): Promise<AgentRunDownload>;
+    submitLocalToolResult(runId: string, result: AgentRunLocalToolResult, signal?: AbortSignal): Promise<AgentRun>;
+    run(req: AgentRunCreateRequest, opts?: AgentRunRunOptions, signal?: AbortSignal): AsyncIterable<AgentRunStreamEvent>;
+    runWithLocalTools(req: AgentRunCreateRequest, handlers: Record<string, AgentRunLocalToolHandler>, opts?: AgentRunWithLocalToolsOptions, signal?: AbortSignal): AsyncIterable<AgentRunStreamEvent>;
+    private runGen;
+    private runWithLocalToolsGen;
+    private invokeLocalTool;
+    private streamGen;
+    private requestAPI;
+    private requestRaw;
+}
+
+declare const ScopeComplianceEvidenceRead = "compliance:evidence:read";
+declare const ScopeComplianceEvidenceWrite = "compliance:evidence:write";
+declare const ScopeComplianceTimestampIssue = "compliance:timestamp:issue";
+declare const ScopeComplianceTimestampVerify = "compliance:timestamp:verify";
+declare const ScopeComplianceContractSigningRead = "compliance:contract_signing:read";
+declare const ScopeComplianceContractSigningWrite = "compliance:contract_signing:write";
+declare const ScopeComplianceSealManage = "compliance:seal:manage";
+declare const ScopeComplianceSealApprovalRequest = "compliance:seal_approval:request";
+declare const ScopeComplianceSealApprovalApprove = "compliance:seal_approval:approve";
+declare const ScopeComplianceSealUseExecute = "compliance:seal_use:execute";
+declare const ScopeComplianceReportsRead = "compliance:reports:read";
+declare const ScopeComplianceReportsWrite = "compliance:reports:write";
+declare const ScopeComplianceReportsPublish = "compliance:reports:publish";
+declare const ScopeComplianceContractTemplateRead = "compliance:contract_template:read";
+declare const ScopeComplianceContractTemplateWrite = "compliance:contract_template:write";
+/** 类型联合：合规域细粒度 scope。Java compliance verifier 只按细粒度匹配, 不做分组展开。 */
+type ComplianceScope = typeof ScopeComplianceEvidenceRead | typeof ScopeComplianceEvidenceWrite | typeof ScopeComplianceTimestampIssue | typeof ScopeComplianceTimestampVerify | typeof ScopeComplianceContractSigningRead | typeof ScopeComplianceContractSigningWrite | typeof ScopeComplianceSealManage | typeof ScopeComplianceSealApprovalRequest | typeof ScopeComplianceSealApprovalApprove | typeof ScopeComplianceSealUseExecute | typeof ScopeComplianceReportsRead | typeof ScopeComplianceReportsWrite | typeof ScopeComplianceReportsPublish | typeof ScopeComplianceContractTemplateRead | typeof ScopeComplianceContractTemplateWrite;
+/** 全部合规域 scope。OAuth 申请合规权限时使用; 谨慎一次性申请全部, 推荐按业务最小集合申请。 */
+declare function complianceScopes(): ComplianceScope[];
+
+/**
+ * Compliance envelope 稳定业务状态。
+ *
+ * 字面量与 Java {@code EnvelopeStatusEnum} 的 `name()` 一致（这是 enum，是 wire 上的实际
+ * 字符串）；前端按这些字符串分支展示文案。
+ */
+type ComplianceEnvelopeStatus = 'DRAFT' | 'CONTRACT_READY' | 'APPROVED' | 'SIGN_PENDING' | 'PENDING_EVIDENCE' | 'PENDING_RECONCILIATION' | 'SUCCESS' | 'FAILED' | 'CANCELED';
+/** Compliance 用印审批稳定状态。 */
+type ComplianceSealApprovalStatus = 'DRAFT' | 'SUBMITTED' | 'APPROVED' | 'REJECTED' | 'CANCELED' | 'USED' | 'EXPIRED';
+/** Provider 业务状态（前端可见的脱敏视图，不暴露下游内部字段）。 */
+type ComplianceProviderStatus = 'pending' | 'success' | 'failed' | 'unknown' | 'retrying';
+/**
+ * 计费 / 履约的对外稳定状态视图。distribution compliance-billing 内部 API
+ * (quote/reserve/commit/cancel/reconcile) 不暴露给前端 — 前端只能看见这 4 个语义。
+ */
+type ComplianceBillingDisplayStatus = 'reserved' | 'committed' | 'canceled' | 'pending_reconciliation';
+/** 高风险动作 step-up — 重新做 OAuth introspection 或重新登录，提升 token 等级后再尝试。 */
+declare const ErrComplianceStepUpRequired = "COMPLIANCE_STEP_UP_REQUIRED";
+/** envelope 闸门关闭 — 审批 gate 等条件未同时就绪，前端展示"功能开放中"。 */
+declare const ErrEnvelopeGateClosed = "ENVELOPE_GATE_CLOSED";
+/** 履约 provider 未配置 — 受控环境材料缺失时业务路径会一致拒绝，不要前端重试。 */
+declare const ErrProviderNotConfigured = "PROVIDER_NOT_CONFIGURED";
+/** Provider 返回 unknown / retrying — 客户必须等待对账，前端展示"处理中（人工核对）"。 */
+declare const ErrProviderUnknownNoRetry = "PROVIDER_REQUEST_UNKNOWN_NO_RETRY";
+/** callback 不能直接确认扣费 — 后端守门，前端无需处理，记录到审计日志展示即可。 */
+declare const ErrBillingCallbackCannotCommit = "BILLING_CALLBACK_CANNOT_COMMIT";
+/** provider 成功但本地未验证通过，不允许扣费。 */
+declare const ErrBillingCommitRequiresLocalVerify = "BILLING_COMMIT_REQUIRES_LOCAL_VERIFY";
+/** distribution compliance-billing 必须 S2S — 前端误调用时拿到该错误码，禁止 retry。 */
+declare const ErrBillingS2sForbidden = "BILLING_S2S_FORBIDDEN";
+/** 审批 gate 各类失败语义（前端展示"审批中 / 审批已用 / 审批失效"）。 */
+declare const ErrSealApprovalNotApproved = "SEAL_APPROVAL_STATE_NOT_APPROVED";
+declare const ErrSealApprovalExpired = "SEAL_APPROVAL_EXPIRED";
+declare const ErrSealApprovalNonceUsed = "SEAL_APPROVAL_NONCE_USED";
+declare const ErrSealApprovalContractHashMismatch = "SEAL_APPROVAL_CONTRACT_HASH_MISMATCH";
+declare const ErrSealApprovalSealMismatch = "SEAL_APPROVAL_SEAL_MISMATCH";
+declare const ErrSealApprovalLocationMismatch = "SEAL_APPROVAL_LOCATION_MISMATCH";
+declare const ErrSealApprovalTransactorMismatch = "SEAL_APPROVAL_TRANSACTOR_MISMATCH";
+/** 用印重复消费防护 — 前端遇到该错误必须刷新审批单状态，不允许"换一次 nonce 再试"。 */
+declare const ErrSealUseAlreadyConsumed = "SEAL_USE_ALREADY_CONSUMED";
+/** 该错误码联合用于前端选择性展示文案；非穷举式 enum，后端保留新增空间。 */
+type ComplianceClientErrorCode = typeof ErrComplianceStepUpRequired | typeof ErrEnvelopeGateClosed | typeof ErrProviderNotConfigured | typeof ErrProviderUnknownNoRetry | typeof ErrBillingCallbackCannotCommit | typeof ErrBillingCommitRequiresLocalVerify | typeof ErrBillingS2sForbidden | typeof ErrSealApprovalNotApproved | typeof ErrSealApprovalExpired | typeof ErrSealApprovalNonceUsed | typeof ErrSealApprovalContractHashMismatch | typeof ErrSealApprovalSealMismatch | typeof ErrSealApprovalLocationMismatch | typeof ErrSealApprovalTransactorMismatch | typeof ErrSealUseAlreadyConsumed;
+/**
+ * 判定一个错误码是否属于"需要前端引导用户重新认证/审批"的高级语义，
+ * 而不是简单 retry。这类错误前端不允许在 UI 层做自动重试。
+ */
+declare function isComplianceTerminalError(code: string): boolean;
+/**
+ * "是否允许在 UI 上呈现为'扣费已确认'"的判定。
+ * provider 状态为 unknown / retrying / pending 时一律不展示为已确认。
+ */
+declare function isBillingConfirmable(providerStatus: ComplianceProviderStatus | undefined, billingStatus: ComplianceBillingDisplayStatus | undefined): boolean;
+
+/** Compliance 写操作选项；写操作不自动 retry，不自动 401 重放。 */
+interface ComplianceWriteOptions {
+    /**
+     * 调用方稳定的幂等键。写操作强烈建议持久化；缺省时服务端按 UUID 兜底，但调用方
+     * 在重试 / 恢复时无法对账。
+     */
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+/** 轮询参数（exponential backoff）。 */
+interface CompliancePollOptions {
+    /** 总超时（ms），缺省 60s。 */
+    timeoutMs?: number;
+    /** 初始 interval（ms），缺省 1000。 */
+    initialIntervalMs?: number;
+    /** interval 倍增上限（ms），缺省 5000。 */
+    maxIntervalMs?: number;
+    /** 倍增系数，缺省 1.5。 */
+    multiplier?: number;
+    signal?: AbortSignal;
+}
+
+type ComplianceAssetType = 'CONTRACT' | 'CODE' | 'IMAGE' | 'DOCUMENT' | 'ARCHIVE' | 'HASH_ONLY' | 'URL_SNAPSHOT' | 'RELEASE' | 'LOG' | 'OTHER';
+type ComplianceHashAlgorithm = 'sha256' | 'sha512' | 'sm3';
+type ComplianceDigestSource = 'CLIENT' | 'COMPLIANCE_SERVICE' | 'PROVIDER';
+type CompliancePrivacyLevel = 'public' | 'private';
+/** 证据资产对外稳定视图。对应后端 EvidenceAssetRespVO。 */
+interface EvidenceAsset {
+    id: number;
+    /** 业务编号；SDK / 前端引用时优先使用 evidenceNo。 */
+    evidenceNo: string;
+    /** publish 后的公开 verify code；DRAFT / 非 public privacy 时为 null。 */
+    publicVerifyCode?: string | null;
+    assetType: ComplianceAssetType | string;
+    name: string;
+    mimeType?: string | null;
+    size?: number | null;
+    hashAlgorithm: ComplianceHashAlgorithm | string;
+    /** 资产 hash（hex 字符串）。 */
+    contentHash: string;
+    canonicalizationProfile?: string | null;
+    digestSource: ComplianceDigestSource | string;
+    privacyLevel: CompliancePrivacyLevel | string;
+    status: string;
+}
+/** 创建证据资产请求；与 Java EvidenceAssetCreateReq 对齐。 */
+interface CreateEvidenceAssetRequest {
+    /** AssetTypeEnum.name()。 */
+    assetType: ComplianceAssetType | string;
+    name: string;
+    mimeType?: string;
+    /** 'sha256' / 'sha512' / 'sm3'。 */
+    hashAlgorithm: ComplianceHashAlgorithm | string;
+    /** hex 字符串；hash-only 资产必填。 */
+    declaredHash?: string;
+    /** CLIENT / COMPLIANCE_SERVICE / PROVIDER。 */
+    digestSource?: ComplianceDigestSource | string;
+    /** 原文 base64；hash-only 时缺省即可。 */
+    contentBase64?: string;
+    /** public / private（默认 private）。 */
+    privacyLevel?: CompliancePrivacyLevel | string;
+    source?: string;
+}
+/** 公开 verify 结果。隐私边界：不暴露 PII / 合同原文 / storage / provider raw。 */
+interface PublicEvidenceVerifyResult {
+    evidenceNo: string;
+    assetType: string;
+    hashAlgorithm: string;
+    contentHash: string;
+    size?: number | null;
+    canonicalizationProfile?: string | null;
+    verifiedAt: string;
+    packageId?: number | null;
+    manifestHash?: string | null;
+    packageHash?: string | null;
+    manifestOfflineVerify: boolean;
+}
+interface EvidencePackage {
+    id: number;
+    assetId: number;
+    timestampTokenId?: number | null;
+    chainId: string;
+    packageVersion: string;
+    hashAlgorithm: string;
+    manifestHash: string;
+    packageHash: string;
+    status: string;
+}
+/**
+ * 证据资产分页【列表项】视图。对应后端 G1 `EvidenceAssetPageItem`。
+ *
+ * 与 {@link EvidenceAsset} 一致的 SDK-safe 子集 + `createTime`；时间字段为
+ * ISO-8601 字符串。
+ */
+interface EvidenceAssetPageItem {
+    id: number;
+    evidenceNo: string;
+    publicVerifyCode?: string | null;
+    assetType: ComplianceAssetType | string;
+    name: string;
+    mimeType?: string | null;
+    size?: number | null;
+    hashAlgorithm: ComplianceHashAlgorithm | string;
+    contentHash: string;
+    canonicalizationProfile?: string | null;
+    digestSource: ComplianceDigestSource | string;
+    privacyLevel: CompliancePrivacyLevel | string;
+    status: string;
+    /** 创建时间 ISO-8601。 */
+    createTime: string;
+}
+/**
+ * `listEvidenceAssets` 请求参数。
+ *
+ * 继承 {@link PageRequest} 的 `pageNo` / `pageSize` / `sortBy` / `sortDirection`，
+ * 全部可选；省略时由服务端取默认页。
+ *
+ * `createTimeStart` / `createTimeEnd` 为调用方提供的【原样字符串】，后端按
+ * `yyyy-MM-dd HH:mm:ss` 解析（例如 `'2026-05-01 00:00:00'`）；SDK 不做格式校验、
+ * 不做时区转换，原样透传查询参数。
+ */
+interface ListEvidenceAssetsRequest extends PageRequest {
+    /** 资产类型过滤（`AssetTypeEnum.name()`）。 */
+    assetType?: ComplianceAssetType | string;
+    /** 资产状态过滤。 */
+    status?: string;
+    /** 创建时间下界，`yyyy-MM-dd HH:mm:ss`。 */
+    createTimeStart?: string;
+    /** 创建时间上界，`yyyy-MM-dd HH:mm:ss`。 */
+    createTimeEnd?: string;
+}
+/**
+ * 证据包分页【列表项】视图。对应后端 G1 `EvidencePackagePageItem`。
+ */
+interface EvidencePackagePageItem {
+    id: number;
+    assetId: number;
+    timestampTokenId?: number | null;
+    chainId: string;
+    packageVersion: string;
+    hashAlgorithm: string;
+    manifestHash: string;
+    packageHash: string;
+    status: string;
+    /** 创建时间 ISO-8601。 */
+    createTime: string;
+}
+/**
+ * `listEvidencePackages` 请求参数。`createTimeStart` / `createTimeEnd` 语义见
+ * {@link ListEvidenceAssetsRequest}。
+ */
+interface ListEvidencePackagesRequest extends PageRequest {
+    /** 证据包状态过滤。 */
+    status?: string;
+    /** 创建时间下界，`yyyy-MM-dd HH:mm:ss`。 */
+    createTimeStart?: string;
+    /** 创建时间上界，`yyyy-MM-dd HH:mm:ss`。 */
+    createTimeEnd?: string;
+}
+
+type ComplianceTimestampVerificationStatus = 'PENDING' | 'VERIFIED' | 'FAILED' | 'LOCAL_VERIFY_FAILED' | 'UNKNOWN' | 'RETRYING';
+/** 时间章 token 对外视图（不含 provider/object/tsa 内部字段）。 */
+interface TimestampToken {
+    id: number;
+    assetId: number;
+    policyOid?: string | null;
+    serialNumber?: string | null;
+    /** gen_time ISO-8601；UNKNOWN/PENDING 状态可能为 null。 */
+    genTime?: string | null;
+    accuracy?: string | null;
+    verificationStatus: ComplianceTimestampVerificationStatus | string;
+    verifiedAt?: string | null;
+    verificationError?: string | null;
+}
+/** 申请时间章请求。`provider` 字段已从服务端契约下线；SDK 永远不传。 */
+interface IssueTimestampRequest {
+    name?: string;
+    mimeType?: string;
+    hashAlgorithm: ComplianceHashAlgorithm | string;
+    /** 客户端声明 digest（hex）；contentBase64 非空时作为校验值。 */
+    digest?: string;
+    contentBase64?: string;
+}
+/** verify 请求 / 结果。 */
+interface VerifyTimestampRequest {
+    tokenId: number;
+}
+interface TimestampVerifyResult {
+    passed: boolean;
+    reason: string;
 }
 /**
- * 当 compliance polling 检测到终态失败 / 已过 timeout / step-up 时抛出。
+ * 时间章分页【列表项】视图。对应后端 G1 `TimestampPageItem`。
  *
- * 分类逻辑：终态失败优先于 timeout；timeout 不算 retryable，调用方必须用新 idempotency-key
- * 重新发起整条链路。
+ * 与 {@link TimestampToken} 一致的 SDK-safe 子集 + `createTime`；时间字段为
+ * ISO-8601 字符串。
  */
-declare class CompliancePollError extends Error {
-    readonly kind: 'timeout' | 'terminal_failure' | 'step_up_required' | 'unknown';
-    readonly lastInfo?: ComplianceErrorInfo;
-    constructor(message: string, kind: 'timeout' | 'terminal_failure' | 'step_up_required' | 'unknown', lastInfo?: ComplianceErrorInfo);
+interface TimestampPageItem {
+    id: number;
+    assetId: number;
+    policyOid?: string | null;
+    serialNumber?: string | null;
+    genTime?: string | null;
+    accuracy?: string | null;
+    verificationStatus: ComplianceTimestampVerificationStatus | string;
+    verifiedAt?: string | null;
+    verificationError?: string | null;
+    /** 创建时间 ISO-8601。 */
+    createTime: string;
 }
-declare class ComplianceClient {
-    private readonly client;
-    constructor(client: Client);
-    /** 创建证据资产（写）。 */
-    createEvidenceAsset(req: CreateEvidenceAssetRequest, opts?: ComplianceWriteOptions): Promise<EvidenceAsset>;
-    /** 读 — 证据资产详情。 */
-    getEvidenceAsset(id: number, signal?: AbortSignal): Promise<EvidenceAsset>;
-    /**
-     * 公开 verify。隐私边界：返回字段不含 PII / 合同原文 / storage / provider raw。
-     *
-     * 匿名可调用：未 login 时走匿名请求，不会抛 `not authorized, call login() first`。
-     * 已 login / 已持有 token 时附带 `Authorization` 以保留审计上下文。public 端点不
-     * 应要求认证 — 收到 401 直接抛 HTTPError，不触发 `forceRefresh`，也不做 refresh
-     * replay。
-     */
-    verifyEvidencePublic(params: {
-        evidenceNo?: string;
-        publicVerifyCode?: string;
-    }, signal?: AbortSignal): Promise<PublicEvidenceVerifyResult>;
-    /** 申请时间章（写）。SDK 永远不传 provider 字段。 */
-    issueTimestamp(req: IssueTimestampRequest, opts?: ComplianceWriteOptions): Promise<TimestampToken>;
-    /** 给已有资产申请时间章。SDK 永远不传 provider 字段。 */
-    issueTimestampForAsset(assetId: number, opts?: ComplianceWriteOptions): Promise<TimestampToken>;
-    /** 读 — 时间章 token 详情。 */
-    getTimestamp(id: number, signal?: AbortSignal): Promise<TimestampToken>;
-    /** verify — 本地离线校验已申请的时间章。 */
-    verifyTimestamp(req: VerifyTimestampRequest, opts?: ComplianceWriteOptions): Promise<TimestampVerifyResult>;
-    /**
-     * 轮询到 VERIFIED 终态。
-     * - VERIFIED → 返回 token；
-     * - FAILED / LOCAL_VERIFY_FAILED → 抛 {@link CompliancePollError} kind='terminal_failure'；
-     * - UNKNOWN / RETRYING / PENDING → 继续轮询直到 timeout；
-     * - timeout → 抛 {@link CompliancePollError} kind='timeout'。
-     */
-    waitForTimestampVerified(id: number, opts?: CompliancePollOptions): Promise<TimestampToken>;
-    /** 构建证据包（写）。 */
-    buildEvidencePackage(assetId: number, timestampTokenId?: number, opts?: ComplianceWriteOptions): Promise<EvidencePackage>;
-    /** 创建证据报告（写）。 */
-    createReport(req: CreateReportRequest, opts?: ComplianceWriteOptions): Promise<ComplianceReport>;
-    /** 读 — 报告详情。 */
-    getReport(id: number, signal?: AbortSignal): Promise<ComplianceReport>;
-    /**
-     * 发布报告（写，step-up 必须）。
-     *
-     * `@status gated` — step-up 闸门未闭合前服务端会一致返回
-     * `COMPLIANCE_STEP_UP_REQUIRED`（数值码 1031000013）。SDK 不会自动重试、不伪成功；
-     * 调用方需要引导用户重新做 OAuth introspection 或重新登录后再次调用本方法
-     *（使用同一 idempotency-key）。方法状态分级见 `docs/compliance.md` Method Status。
-     */
-    publishReport(id: number, opts?: ComplianceWriteOptions): Promise<ComplianceReport>;
-    /**
-     * 下载报告（读）。返回 {@link ReportDownload}：报告 hash + 资产 hash + 证据包 hash +
-     * 时间章 serial/genTime，足以离线复核。
-     * 不返回 bodyCanonicalJson / storage key / subject snapshot id。
-     */
-    downloadReport(id: number, signal?: AbortSignal): Promise<ReportDownload>;
-    /** 创建 envelope（写）。返回 envelope id。 */
-    createSigningEnvelope(req: CreateSigningEnvelopeRequest, opts?: ComplianceWriteOptions): Promise<number>;
-    /** 读 — envelope 详情。租户由服务端从 compliance token principal 推导。 */
-    getSigningEnvelope(envelopeId: number, signal?: AbortSignal): Promise<SigningEnvelope>;
-    /**
-     * 正式签署（写，step-up 必须）。
-     *
-     * `@status gated` — 服务端闸门关闭时会一致返回 `ENVELOPE_GATE_CLOSED` (1031004004)。
-     * SDK 不重试、不伪成功；调用方应该将该错误展示为"功能未开放"。
-     */
-    signEnvelope(envelopeId: number, req: SignEnvelopeRequest, opts?: ComplianceWriteOptions): Promise<void>;
-    /**
-     * 创建 H5 签署短链（写，step-up 必须）。
-     *
-     * `@status gated` — 同 {@link signEnvelope}：服务端闸门关闭时 SDK 不重试、不伪成功。
-     */
-    createH5SigningUrl(envelopeId: number, req: CreateH5SigningUrlRequest, opts?: ComplianceWriteOptions): Promise<string>;
-    /** 同步 provider 状态（写但只读对账，不创建新 provider 请求）。 */
-    syncSigningEnvelopeStatus(envelopeId: number, opts?: ComplianceWriteOptions): Promise<void>;
-    /**
-     * 提交用印审批申请（写）。
-     *
-     * `@status production-ready` — 服务端以 `Idempotency-Key` + 业务请求指纹做重放保护：
-     * 同 key + 同请求 → 返回原审批 id；同 key + 不同请求 → 拒绝复用幂等键。强烈建议调用方
-     * 持久化 `idempotencyKey`，网络重试 / 任务恢复时复用，避免重复创建审批单。
-     */
-    submitSealApproval(req: SubmitSealApprovalRequest, opts?: ComplianceWriteOptions): Promise<number>;
-    /**
-     * 审批通过用印申请（写，step-up 必须）。
-     *
-     * `@status gated` — step-up 未闭合前服务端会返回 `COMPLIANCE_STEP_UP_REQUIRED`。
-     * SDK 不重试、不伪成功。方法状态分级见 `docs/compliance.md` Method Status。
-     */
-    approveSealApproval(id: number, query: ApproveSealApprovalQuery, opts?: ComplianceWriteOptions): Promise<void>;
-    rejectSealApproval(id: number, query: RejectSealApprovalQuery, opts?: ComplianceWriteOptions): Promise<void>;
-    cancelSealApproval(id: number, query: CancelSealApprovalQuery, opts?: ComplianceWriteOptions): Promise<void>;
-    listPendingSealApprovals(signal?: AbortSignal): Promise<SealApproval[]>;
-    getSealApproval(id: number, signal?: AbortSignal): Promise<SealApproval>;
-    getProviderRequest(id: number, signal?: AbortSignal): Promise<ProviderRequestStatusView>;
-    /**
-     * 轮询 provider request 到 SUCCESS / FAILED 终态。
-     * - SUCCESS / FAILED → 返回最后视图；
-     * - UNKNOWN / RETRYING / PENDING → 继续轮询；
-     * - timeout → 抛 {@link CompliancePollError} kind='timeout'，不自动重发原 provider 请求。
-     *
-     * SUCCESS 不代表 billing 已 commit；调用方仍需通过业务侧 envelope / asset 终态判断。
-     */
-    waitForProviderRequestTerminal(id: number, opts?: CompliancePollOptions): Promise<ProviderRequestStatusView>;
-    classifyError(err: unknown): ComplianceErrorInfo | null;
-    /**
-     * 读路径：GET / 公开 verify。允许 401 单次刷新后重放（GET 幂等安全）。
-     * 与 client.doJSONFullInternal 行为一致；不复用其代码因为 base URL 不同。
-     */
-    private read;
-    /**
-     * 公开读路径：public verify。
-     *
-     * 与 {@link read} 的区别 — public 端点不应要求认证：
-     *   - 无 token 时匿名请求：ensureToken 抛 `not authorized` 会被吞掉，继续匿名发送。
-     *   - 有 token 时附带 `Authorization`，保留后端审计上下文。
-     *   - 不做 401 refresh replay：401 直接抛 HTTPError，不触发 `forceRefresh`。
-     *
-     * URL 仍走 `client.complianceURL(path)`，不复用 `/api/v4`；底层复用
-     * `client.doRequest`，不新增 fetch/axios 直连。
-     */
-    private publicRead;
-    /**
-     * 写路径：POST。
-     * - 发送前 ensureToken 一次确保 token fresh。
-     * - 不自动 401 重放：401 → 抛 HTTPError；调用方必须自己刷新 token 后用同一
-     *   idempotency-key 重新发起，避免 provider 侧重复请求。
-     * - 不走 doRequestWithRetry：写操作不允许 5xx/timeout 自动重试。
-     */
-    private write;
-    private executeJson;
-    private poll;
+/**
+ * `listTimestamps` 请求参数。
+ *
+ * 继承 {@link PageRequest} 分页 / 排序字段；全部可选。`createTimeStart` /
+ * `createTimeEnd` 为调用方提供的【原样字符串】，后端按 `yyyy-MM-dd HH:mm:ss`
+ * 解析；SDK 不做格式校验或时区转换。
+ */
+interface ListTimestampsRequest extends PageRequest {
+    /** 时间章 provider 过滤（`TsaProviderEnum.name()` 之类）。 */
+    provider?: string;
+    /** 校验状态过滤。 */
+    verificationStatus?: ComplianceTimestampVerificationStatus | string;
+    /** 创建时间下界，`yyyy-MM-dd HH:mm:ss`。 */
+    createTimeStart?: string;
+    /** 创建时间上界，`yyyy-MM-dd HH:mm:ss`。 */
+    createTimeEnd?: string;
 }
-
-/** SDK 为单个 content block 缓存的元数据 */
-interface BlockMeta {
-    type: string;
-    ephemeral: boolean;
+/**
+ * 时间章授权机构（TSA）provider 视图。对应后端 G3 `TsaProviderVO`。
+ *
+ * 描述某个 TSA provider 的对外可见状态——名称、所处环境、当前是否可用。
+ * 只读视图：不含 provider 端点、凭证、证书或其它内部接入材料。
+ */
+interface TsaProvider {
+    /** provider 名称（如 `TsaProviderEnum.name()`）。 */
+    name: string;
+    /** provider 所处环境（如 `production` / `sandbox`）。 */
+    environment: string;
+    /** 该 provider 当前是否可用。 */
+    available: boolean;
 }
 /**
- * 按 Anthropic SSE 事件类型解析 data, 更新 blockTypeMap, 返回 [index, type, ephemeral]。
+ * 时间章统计视图。对应后端 G3 `TsaStatsVO`。
  *
- * 仅当事件为 content_block_start / content_block_delta / content_block_stop
- * 时返回非空 type; 其他事件返回空 type, 调用方据此判别是否填充 StreamEvent 元数据字段。
+ * 只读聚合：时间章总数 + 按校验状态分桶的计数。
  */
-declare function extractAnthropicBlockMeta(eventType: string, data: string, blockTypeMap: Map<number, BlockMeta>): [number, string, boolean];
+interface TsaStats {
+    /** 时间章总数。 */
+    total: number;
+    /**
+     * 按校验状态分桶的计数。键为校验状态枚举名（如 `VERIFIED` / `PENDING` /
+     * `FAILED`），值为该状态下的时间章数量。
+     */
+    byVerificationStatus: Record<string, number>;
+}
 
-type AgentRunStatus = 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
-interface AgentRunLocalContextPolicy {
-    enabled?: boolean;
-    readonly?: boolean;
-    maxBytes?: number;
-    allowedTools?: string[];
+interface ComplianceReport {
+    id: number;
+    reportNo: string;
+    reportType: string;
+    status: string;
+    assetId?: number | null;
+    packageId?: number | null;
+    publicUrlToken?: string | null;
+    publishedAt?: string | null;
+    bodyHash?: string | null;
 }
-interface AgentRunArtifactPolicy {
-    enabled?: boolean;
-    maxFiles?: number;
+interface CreateReportRequest {
+    assetId: number;
+    packageId: number;
 }
-interface AgentRunCreateRequest {
-    appId: string;
-    mode?: string;
-    sessionId?: string;
-    input: string;
-    messages?: unknown[];
-    model?: string;
-    activeSkillIds?: string[];
-    knowledgeBaseIds?: string[];
-    metadata?: Record<string, string>;
-    localContextPolicy?: AgentRunLocalContextPolicy;
-    artifactPolicy?: AgentRunArtifactPolicy;
+/** 离线复核下载 VO；建议调用方持久化作为长期可重复验证依据。 */
+interface ReportDownload {
+    id: number;
+    reportNo: string;
+    reportType: string;
+    status: string;
+    bodyHash?: string | null;
+    publishedAt?: string | null;
+    assetEvidenceNo?: string | null;
+    assetHashAlgorithm?: string | null;
+    assetContentHash?: string | null;
+    packageManifestHash?: string | null;
+    packageHash?: string | null;
+    packageHashAlgorithm?: string | null;
+    timestampSerialNumber?: string | null;
+    timestampGenTime?: string | null;
+    timestampVerificationStatus?: string | null;
 }
-interface AgentRun {
-    runId: string;
-    sessionId: string;
-    appId?: string;
-    mode?: string;
-    status: AgentRunStatus;
-    createdAt?: string;
-    startedAt?: string;
-    completedAt?: string;
-    error?: AgentRunErrorPayload;
-    metadata?: Record<string, string>;
+/**
+ * 证据报告分页【列表项】视图。对应后端 G1 `ReportPageItem`。
+ *
+ * 与 {@link ComplianceReport} 一致的 SDK-safe 子集 + `createTime`；时间字段为
+ * ISO-8601 字符串。
+ */
+interface ReportPageItem {
+    id: number;
+    reportNo: string;
+    reportType: string;
+    status: string;
+    assetId?: number | null;
+    packageId?: number | null;
+    publicUrlToken?: string | null;
+    publishedAt?: string | null;
+    bodyHash?: string | null;
+    /** 创建时间 ISO-8601。 */
+    createTime: string;
 }
-interface AgentRunCreateResponse {
-    runId: string;
-    sessionId: string;
-    status: AgentRunStatus;
+/**
+ * `listReports` 请求参数。
+ *
+ * 继承 {@link PageRequest} 分页 / 排序字段；全部可选。`createTimeStart` /
+ * `createTimeEnd` 为调用方提供的【原样字符串】，后端按 `yyyy-MM-dd HH:mm:ss`
+ * 解析；SDK 不做格式校验或时区转换。
+ */
+interface ListReportsRequest extends PageRequest {
+    /** 报告状态过滤。 */
+    status?: string;
+    /** 创建时间下界，`yyyy-MM-dd HH:mm:ss`。 */
+    createTimeStart?: string;
+    /** 创建时间上界，`yyyy-MM-dd HH:mm:ss`。 */
+    createTimeEnd?: string;
 }
-interface AgentRunArtifact {
-    id: string;
-    filename: string;
-    contentType?: string;
-    size?: number;
-    type?: string;
-    metadata?: Record<string, string>;
+
+interface SigningEnvelope {
+    id: number;
+    envelopeNo: string;
+    applicantUserId?: string | null;
+    status: string;
+    primaryContractId?: number | null;
+    contractHash?: string | null;
+    hashAlgorithm?: string | null;
+    billingGroupId?: string | null;
+    chainId?: string | null;
+    requestId?: string | null;
+    pendingReason?: string | null;
+    signedAt?: string | null;
+    evidenceReadyAt?: string | null;
+    committedAt?: string | null;
 }
-interface AgentRunArtifactList {
-    artifacts: AgentRunArtifact[];
+/** 创建 envelope 请求；只保留调用方业务字段，内部主体快照和履约通道由后端推导。 */
+interface CreateSigningEnvelopeRequest {
+    envelopeNo?: string;
+    requestId?: string;
+    /** 调用方稳定 idempotency-key（不传则由 Idempotency-Key header 兜底）。 */
+    idempotencyKey?: string;
+    billingGroupId?: string;
+    chainId?: string;
 }
-interface AgentRunDownload {
-    data: Uint8Array;
-    filename: string;
-    contentType?: string;
+/** sign 请求；service 默认闸门关闭，SDK 写示例必须处理 ENVELOPE_GATE_CLOSED 错误。 */
+interface SignEnvelopeRequest {
+    approvalRequestId?: number;
+    contractId?: number;
+    contractHash?: string;
+    sealId?: number;
+    signLocationType?: string;
+    signLocationPayload?: string;
+    transactorId?: number;
+    requestId?: string;
+    idempotencyKey?: string;
 }
-interface AgentRunUsage {
-    inputTokens?: number;
-    outputTokens?: number;
-    totalTokens?: number;
-    cacheReadTokens?: number;
-    cacheCreateTokens?: number;
-    exact?: boolean;
-    source?: string;
-    [key: string]: unknown;
+/** H5 短链请求。 */
+interface CreateH5SigningUrlRequest extends SignEnvelopeRequest {
 }
-interface AgentRunSettlement {
-    requestId?: string;
+/**
+ * 签署 envelope 分页【列表项】视图。对应后端 G1 `SigningEnvelopePageItem`。
+ *
+ * 与 {@link SigningEnvelope} 一致的 SDK-safe 子集 + `createTime`；时间字段为
+ * ISO-8601 字符串。
+ */
+interface SigningEnvelopePageItem {
+    id: number;
+    envelopeNo: string;
+    applicantUserId?: string | null;
+    status: string;
+    primaryContractId?: number | null;
+    contractHash?: string | null;
+    hashAlgorithm?: string | null;
+    billingGroupId?: string | null;
+    chainId?: string | null;
+    requestId?: string | null;
+    pendingReason?: string | null;
+    signedAt?: string | null;
+    evidenceReadyAt?: string | null;
+    committedAt?: string | null;
+    /** 创建时间 ISO-8601。 */
+    createTime: string;
+}
+/**
+ * `listSigningEnvelopes` 请求参数。
+ *
+ * 继承 {@link PageRequest} 分页 / 排序字段；全部可选。`createTimeStart` /
+ * `createTimeEnd` 为调用方提供的【原样字符串】，后端按 `yyyy-MM-dd HH:mm:ss`
+ * 解析；SDK 不做格式校验或时区转换。
+ */
+interface ListSigningEnvelopesRequest extends PageRequest {
+    /** envelope 状态过滤。 */
     status?: string;
-    consumeStatus?: string;
-    inputTokens?: number;
-    outputTokens?: number;
-    totalTokens?: number;
-    cacheReadTokens?: number;
-    cacheCreateTokens?: number;
-    tokenRemaining?: number;
-    callRemaining?: number;
-    retryQueued?: boolean;
-    exact?: boolean;
-    [key: string]: unknown;
+    /** 创建时间下界，`yyyy-MM-dd HH:mm:ss`。 */
+    createTimeStart?: string;
+    /** 创建时间上界，`yyyy-MM-dd HH:mm:ss`。 */
+    createTimeEnd?: string;
 }
-interface AgentRunErrorPayload {
-    code?: string;
-    message: string;
-    stage?: string;
-    retryable?: boolean;
-    raw?: unknown;
+/**
+ * 签署 envelope 下挂的合同【列表项】视图。对应后端 G4 `EnvelopeContractItem`。
+ *
+ * 一个 envelope 可挂多份合同；本视图描述合同的元数据与哈希指纹，便于离线复核。
+ * SDK-safe 子集——不含合同原文 / storage key / provider raw payload。时间字段
+ * 为 ISO-8601 字符串。
+ */
+interface EnvelopeContractItem {
+    /** 合同行 id（数值主键）。 */
+    id: number;
+    /** 所属 envelope id。 */
+    envelopeId: number;
+    /** 合同编号。 */
+    contractNo: string;
+    /** 合同标题。 */
+    title: string;
+    /** 合同文件 MIME 类型。 */
+    mimeType: string;
+    /** 合同文件字节数。 */
+    size: number;
+    /** 哈希算法（如 `sha256`）。 */
+    hashAlgorithm: string;
+    /** 合同原文内容哈希。 */
+    contentHash: string;
+    /** 签署后内容哈希（未签署时缺省）。 */
+    signedContentHash?: string;
+    /** 合同状态。 */
+    status: string;
+    /** 创建时间 ISO-8601。 */
+    createTime: string;
 }
-interface AgentRunLocalToolResult {
-    requestId: string;
-    ok: boolean;
-    content?: unknown;
-    error?: string;
+/**
+ * `voidEnvelope` 请求体。作废一个签署 envelope，`reason` 为必填的作废原因。
+ */
+interface VoidEnvelopeRequest {
+    /** 作废原因（必填，随 JSON body 提交）。 */
+    reason: string;
 }
-interface AgentRunLocalToolHandlerContext {
-    runId: string;
-    requestId: string;
-    name: string;
-    signal: AbortSignal;
+
+interface SealApproval {
+    id: number;
+    envelopeId?: number | null;
+    contractId?: number | null;
+    contractHash?: string | null;
+    hashAlgorithm?: string | null;
+    sealId?: number | null;
+    applicantUserId?: string | null;
+    approverUserId?: string | null;
+    transactorId?: number | null;
+    signLocationType?: string | null;
+    signLocationPayload?: string | null;
+    reason?: string | null;
+    expiresAt?: string | null;
+    status: string;
+    approvedAt?: string | null;
+    rejectedAt?: string | null;
+    canceledAt?: string | null;
 }
-type AgentRunLocalToolHandler = (input: unknown, context: AgentRunLocalToolHandlerContext) => Promise<unknown> | unknown;
-interface AgentRunStreamOptions {
-    /**
-     * true by default. When enabled, an error event is converted into
-     * AgentRunStreamError after the event has been parsed.
-     */
-    throwOnError?: boolean;
+/** 提交审批；provider 侧字段由后端归一，SDK 调用方不传。 */
+interface SubmitSealApprovalRequest {
+    envelopeId?: number;
+    contractId?: number;
+    contractHash?: string;
+    hashAlgorithm?: string;
+    sealId?: number;
+    approverUserId?: string;
+    transactorId?: number;
+    signLocationType?: string;
+    signLocationPayload?: string;
+    reason?: string;
 }
-interface AgentRunRunOptions extends AgentRunStreamOptions {
+interface ApproveSealApprovalQuery {
+    expiresAt?: string;
+    note?: string;
 }
-interface AgentRunWithLocalToolsOptions extends AgentRunRunOptions {
-    timeoutMs?: number;
-    onEvent?: (event: AgentRunStreamEvent) => void | Promise<void>;
+interface RejectSealApprovalQuery {
+    reason?: string;
 }
-type AgentRunStreamEvent = {
-    type: 'run_started';
-    runId: string;
-    sessionId: string;
-} | {
-    type: 'status';
-    status: AgentRunStatus | string;
-    message?: string;
-} | {
-    type: 'text_delta';
-    text: string;
-} | {
-    type: 'reasoning_delta';
-    text: string;
-} | {
-    type: 'tool_call';
-    id: string;
-    name: string;
-    input?: unknown;
-} | {
-    type: 'tool_result';
-    id: string;
-    name?: string;
-    result?: unknown;
-    error?: string;
-} | {
-    type: 'local_tool_request';
-    requestId: string;
-    name: string;
-    input: unknown;
-} | {
-    type: 'artifact';
-    artifact: AgentRunArtifact;
-} | {
-    type: 'sources';
-    sources: unknown;
-} | {
-    type: 'usage';
-    usage: AgentRunUsage;
-} | {
-    type: 'settle';
-    settlement: AgentRunSettlement;
-} | {
-    type: 'error';
-    error: AgentRunErrorPayload;
-} | {
-    type: 'done';
-    runId: string;
-    status: AgentRunStatus | string;
-};
-declare class AgentRunStreamError extends Error {
-    event: Extract<AgentRunStreamEvent, {
-        type: 'error';
-    }>;
-    code: string;
-    stage: string;
-    retryable: boolean;
-    constructor(event: Extract<AgentRunStreamEvent, {
-        type: 'error';
-    }>);
+interface CancelSealApprovalQuery {
+    reason?: string;
+}
+/**
+ * 用印审批分页【列表项】视图。对应后端 G1 `SealApprovalPageItem`。
+ *
+ * 与 {@link SealApproval} 一致的 SDK-safe 子集 + `createTime`；时间字段为
+ * ISO-8601 字符串。
+ */
+interface SealApprovalPageItem {
+    id: number;
+    envelopeId?: number | null;
+    contractId?: number | null;
+    contractHash?: string | null;
+    hashAlgorithm?: string | null;
+    sealId?: number | null;
+    applicantUserId?: string | null;
+    approverUserId?: string | null;
+    transactorId?: number | null;
+    signLocationType?: string | null;
+    signLocationPayload?: string | null;
+    reason?: string | null;
+    expiresAt?: string | null;
+    status: string;
+    approvedAt?: string | null;
+    rejectedAt?: string | null;
+    canceledAt?: string | null;
+    /** 创建时间 ISO-8601。 */
+    createTime: string;
 }
-
-declare module '@acosmi/sdk-ts' {
-    interface Client {
-        /** SDK-facing cloud agent run gateway. */
-        readonly agentRuns: AgentRunsClient;
-    }
+/**
+ * `listSealApprovals` 请求参数。
+ *
+ * 继承 {@link PageRequest} 分页 / 排序字段；全部可选。`createTimeStart` /
+ * `createTimeEnd` 为调用方提供的【原样字符串】，后端按 `yyyy-MM-dd HH:mm:ss`
+ * 解析；SDK 不做格式校验或时区转换。
+ */
+interface ListSealApprovalsRequest extends PageRequest {
+    /** 审批状态过滤。 */
+    status?: string;
+    /** 创建时间下界，`yyyy-MM-dd HH:mm:ss`。 */
+    createTimeStart?: string;
+    /** 创建时间上界，`yyyy-MM-dd HH:mm:ss`。 */
+    createTimeEnd?: string;
 }
-declare class AgentRunsClient {
-    private readonly client;
-    constructor(client: Client);
-    create(req: AgentRunCreateRequest, signal?: AbortSignal): Promise<AgentRunCreateResponse>;
-    get(runId: string, signal?: AbortSignal): Promise<AgentRun>;
-    stream(runId: string, opts?: AgentRunStreamOptions, signal?: AbortSignal): AsyncIterable<AgentRunStreamEvent>;
-    cancel(runId: string, signal?: AbortSignal): Promise<AgentRun>;
-    listArtifacts(runId: string, signal?: AbortSignal): Promise<AgentRunArtifact[]>;
-    downloadArtifact(runId: string, artifactId: string, signal?: AbortSignal): Promise<AgentRunDownload>;
-    submitLocalToolResult(runId: string, result: AgentRunLocalToolResult, signal?: AbortSignal): Promise<AgentRun>;
-    run(req: AgentRunCreateRequest, opts?: AgentRunRunOptions, signal?: AbortSignal): AsyncIterable<AgentRunStreamEvent>;
-    runWithLocalTools(req: AgentRunCreateRequest, handlers: Record<string, AgentRunLocalToolHandler>, opts?: AgentRunWithLocalToolsOptions, signal?: AbortSignal): AsyncIterable<AgentRunStreamEvent>;
-    private runGen;
-    private runWithLocalToolsGen;
-    private invokeLocalTool;
-    private streamGen;
-    private requestAPI;
-    private requestRaw;
+/**
+ * 用印执行记录分页【列表项】视图。对应后端 G6 `SealUsePageItem`。
+ *
+ * 一次用印执行（seal use）描述【该次盖章动作本身】的执行进度——envelope /
+ * contract / seal / 审批联动后真正调用 provider 落章的那一笔记录，与
+ * envelope 领域状态正交。SDK-safe 视图——不含 provider raw payload / 证书 /
+ * storage key。时间字段为 ISO-8601 字符串。
+ */
+interface SealUsePageItem {
+    id: number;
+    envelopeId: number;
+    contractId: number;
+    sealId: number;
+    /** 用印执行状态。 */
+    usageStatus: string;
+    /** 签署位置类型（坐标 / 关键字 / 域字段等）。 */
+    signLocationType?: string | null;
+    /** 调起时间 ISO-8601。 */
+    invokedAt?: string | null;
+    /** 成功落章时间 ISO-8601。 */
+    consumedAt?: string | null;
+    /** 失败时的错误原因（如有）。 */
+    failureReason?: string | null;
+    /** 创建时间 ISO-8601。 */
+    createTime: string;
 }
-
-/** 根据模型能力和请求参数自动组装 beta header 列表 */
-declare function buildBetas(caps: ModelCapabilities, req: ChatRequest): string[];
-/** 合并两个字符串数组并去重, 保留顺序 */
-declare function uniqueMerge(base: string[], extra: string[]): string[];
-
-declare module '@acosmi/sdk-ts' {
-    interface Client {
-        /** 查询当前用户的权益余额 (聚合) */
-        getBalance(signal?: AbortSignal): Promise<EntitlementBalance>;
-        /** 查询详细余额 (含每条权益明细) */
-        getBalanceDetail(signal?: AbortSignal): Promise<BalanceDetail>;
-        /** 查询当前用户权益列表; status: "ACTIVE" / "EXPIRED" / "" (全部) */
-        listEntitlements(status: string, signal?: AbortSignal): Promise<EntitlementItem[]>;
-        /** 查询核销记录 (分页) */
-        listConsumeRecords(page: number, pageSize: number, signal?: AbortSignal): Promise<ConsumeRecordPage>;
-        /** 领取当月免费额度 — 幂等: 已领取时返回已有权益 */
-        claimMonthlyFree(signal?: AbortSignal): Promise<EntitlementItem>;
-        /** 查询当前用户在指定模型下的剩余 token (raw + ETU) */
-        getByModel(modelID: string, signal?: AbortSignal): Promise<ModelByQuotaResponse>;
-        /** 列出当前用户的全部桶 */
-        listBuckets(signal?: AbortSignal): Promise<ModelBucket[]>;
-        /** 拉取模型系数表; SDK 自带 8s TTL 内存缓存以减小调用风暴. */
-        listCoefficients(signal?: AbortSignal): Promise<ModelCoefficient[]>;
-        /** 手动失效系数缓存 (admin 调价后建议立即调一次) */
-        invalidateCoefficientCache(): void;
-    }
+/**
+ * `listSealUses` 请求参数。
+ *
+ * 继承 {@link PageRequest} 分页 / 排序字段；全部可选。`createTimeStart` /
+ * `createTimeEnd` 为调用方提供的【原样字符串】，后端按 `yyyy-MM-dd HH:mm:ss`
+ * 解析；SDK 不做格式校验或时区转换。
+ */
+interface ListSealUsesRequest extends PageRequest {
+    /** 印章 id 过滤。 */
+    sealId?: number;
+    /** 签署 envelope id 过滤。 */
+    envelopeId?: number;
+    /** 用印执行状态过滤。 */
+    usageStatus?: string;
+    /** 创建时间下界，`yyyy-MM-dd HH:mm:ss`。 */
+    createTimeStart?: string;
+    /** 创建时间上界，`yyyy-MM-dd HH:mm:ss`。 */
+    createTimeEnd?: string;
 }
 
-declare module '@acosmi/sdk-ts' {
-    interface Client {
-        /** 获取商城流量包列表 (兼容 yudao 分页和直接数组两种格式) */
-        listTokenPackages(signal?: AbortSignal): Promise<TokenPackage[]>;
-        /** 获取流量包详情 */
-        getTokenPackageDetail(packageID: string, signal?: AbortSignal): Promise<TokenPackage>;
-        /** 购买流量包 (创建订单) */
-        buyTokenPackage(packageID: string, payload: PayPayload | null, signal?: AbortSignal): Promise<Order>;
-        /** 查询订单支付状态 */
-        getOrderStatus(orderID: string, signal?: AbortSignal): Promise<OrderStatus>;
-        /** 查询我的订单列表 */
-        listMyOrders(signal?: AbortSignal): Promise<Order[]>;
-        /**
-         * 轮询订单支付状态直到终态
-         * 成功支付返回 status; 终态失败抛 OrderTerminalError
-         * pollIntervalMs <= 0 时默认 2 秒
-         */
-        waitForPayment(orderID: string, pollIntervalMs: number, signal?: AbortSignal): Promise<OrderStatus>;
-    }
+/**
+ * 单个 compliance 高风险 / 收费动作的能力闸门视图。对应后端 G2 `CapabilityVO`。
+ *
+ * 后端为每个动作返回一条：`signEnvelope` / `createH5SigningUrl` /
+ * `publishReport` / `approveSealApproval` / `executeSealUse` / `createSeal`。
+ *
+ * 拿不到能力时调用方必须 fail-closed（视为 `executable=false`）。`state` 复用
+ * 跨域 {@link FeatureGateState} 开放联合——后端保留新增空间。
+ */
+interface ComplianceCapability {
+    /** 动作标识（如 `signEnvelope` / `publishReport`）。 */
+    action: string;
+    /** 该动作当前是否可执行。fail-closed：拿不到能力时按 false 处理。 */
+    executable: boolean;
+    /**
+     * 不可执行的具体状态。后端取值：`executable` / `scope_missing` /
+     * `not_provisioned` / `step_up_required` / `gate_closed` / `unknown`。
+     */
+    state: FeatureGateState;
+    /** 该动作所需的 OAuth scope。 */
+    requiredScopes: string[];
+    /** 该动作是否需要 step-up（高风险动作二次验证）。 */
+    requiredStepUp: boolean;
+    /** 人类可读原因（诊断 / 展示）。 */
+    reason: string;
 }
-
-declare module '@acosmi/sdk-ts' {
-    interface Client {
-        /** 获取钱包统计 (余额/月消费/月充值) */
-        getWalletStats(signal?: AbortSignal): Promise<WalletStats>;
-        /** 获取最近交易记录 */
-        getWalletTransactions(signal?: AbortSignal): Promise<Transaction[]>;
-    }
+/**
+ * compliance 操作投影【列表项】视图。对应后端 G2 `OperationPageItem`。
+ *
+ * 与领域对象状态【正交】：描述【一次操作】本身的执行进度，而非某个履约对象的
+ * 业务态。时间字段为 ISO-8601 字符串。
+ */
+interface OperationPageItem {
+    /** 行 id（数值主键）。 */
+    id: number;
+    /** 操作幂等键（跨来源统一关联键）。 */
+    operationId: string;
+    /** 操作状态。 */
+    status: string;
+    /** 是否终态。 */
+    terminal: boolean;
+    /** 当前状态是否允许 SDK 安全重试。 */
+    retryable: boolean;
+    /** 已尝试次数。 */
+    attemptCount: number;
+    /** 关联业务编号。 */
+    businessNo?: string | null;
+    /** 关联合同编号。 */
+    contractNo?: string | null;
+    /** 关联印章 id。 */
+    sealId?: number | null;
+    /** 对账状态。 */
+    reconciliationStatus?: string | null;
+    /** 下次重试时间 ISO-8601。 */
+    nextRetryAt?: string | null;
+    /** 请求发起时间 ISO-8601。 */
+    requestedAt?: string | null;
+    /** provider 响应时间 ISO-8601。 */
+    respondedAt?: string | null;
+    /** 创建时间 ISO-8601。 */
+    createTime: string;
 }
-
-declare module '@acosmi/sdk-ts' {
-    interface Client {
-        /** 浏览技能商店 (公共端点, 无需认证) */
-        browseSkillStore(query: SkillStoreQuery, signal?: AbortSignal): Promise<SkillStoreItem[]>;
-        /** 浏览公共技能商店 (V3 分页接口) */
-        browseSkills(page: number, pageSize: number, category: string, keyword: string, tag: string, source: string, signal?: AbortSignal): Promise<SkillBrowseResponse>;
-        /** 轻量浏览公共技能商店 (fields=minimal, 响应体积缩减 90%+) */
-        browseSkillsList(page: number, pageSize: number, category: string, keyword: string, tag: string, source: string, signal?: AbortSignal): Promise<SkillBrowseListResponse>;
-        /** 获取技能商店中某个技能的详情 (公共端点) */
-        getSkillDetail(skillID: string, signal?: AbortSignal): Promise<SkillStoreItem>;
-        /** 按 key 精确查找公共技能 (公共端点) */
-        resolveSkill(key: string, signal?: AbortSignal): Promise<SkillStoreItem>;
-        /** 安装技能到当前用户的租户空间 (需 OAuth scope: skill_store) */
-        installSkill(skillID: string, signal?: AbortSignal): Promise<SkillStoreItem>;
-        /**
-         * 下载技能 ZIP 包 (公共端点, 双模式)
-         * 有 token 时自动附带 (享受无限流), 无 token 时匿名 (受限流)
-         * @returns [data, filename]; 限流时抛 RateLimitError
-         */
-        downloadSkill(skillID: string, signal?: AbortSignal): Promise<{
-            data: Uint8Array;
-            filename: string;
-        }>;
-        /**
-         * 上传技能 ZIP 包
-         * @param scope "TENANT"
-         * @param intent "PERSONAL" (仅自己用) 或 "PUBLIC_INTENT" (走认证→公开)
-         */
-        uploadSkill(zipData: Uint8Array, scope: string, intent: string, signal?: AbortSignal): Promise<SkillStoreItem>;
-        /** 获取技能统计概览 */
-        getSkillSummary(signal?: AbortSignal): Promise<SkillSummary>;
-        /** 触发技能认证管线 (异步) */
-        certifySkill(skillID: string, signal?: AbortSignal): Promise<void>;
-        /** 查询技能认证状态 */
-        getCertificationStatus(skillID: string, signal?: AbortSignal): Promise<CertificationStatus>;
-        /** 根据自然语言描述生成技能定义 (基于独立 LLM) */
-        generateSkill(req: GenerateSkillRequest, signal?: AbortSignal): Promise<GenerateSkillResult>;
-        /** 优化已有技能定义 */
-        optimizeSkill(req: OptimizeSkillRequest, signal?: AbortSignal): Promise<OptimizeSkillResult>;
-        /** 校验技能定义正确性 */
-        validateSkill(skillName: string, signal?: AbortSignal): Promise<void>;
-    }
+/**
+ * compliance 操作投影【详情】视图。对应后端 G2 `OperationDetail`。
+ *
+ * 当前与 {@link OperationPageItem} 字段一致——单独成类型以便后端在详情视图
+ * 追加字段时不破坏列表项契约。
+ */
+interface OperationDetail {
+    /** 行 id（数值主键）。 */
+    id: number;
+    /** 操作幂等键（跨来源统一关联键）。 */
+    operationId: string;
+    /** 操作状态。 */
+    status: string;
+    /** 是否终态。 */
+    terminal: boolean;
+    /** 当前状态是否允许 SDK 安全重试。 */
+    retryable: boolean;
+    /** 已尝试次数。 */
+    attemptCount: number;
+    /** 关联业务编号。 */
+    businessNo?: string | null;
+    /** 关联合同编号。 */
+    contractNo?: string | null;
+    /** 关联印章 id。 */
+    sealId?: number | null;
+    /** 对账状态。 */
+    reconciliationStatus?: string | null;
+    /** 下次重试时间 ISO-8601。 */
+    nextRetryAt?: string | null;
+    /** 请求发起时间 ISO-8601。 */
+    requestedAt?: string | null;
+    /** provider 响应时间 ISO-8601。 */
+    respondedAt?: string | null;
+    /** 创建时间 ISO-8601。 */
+    createTime: string;
 }
-
-declare module '@acosmi/sdk-ts' {
-    interface Client {
-        /** 获取当前用户租户下的所有工具 (Skill 优先 + Plugin 兜底) */
-        listTools(signal?: AbortSignal): Promise<ToolView[]>;
-        /** 获取单个工具详情 */
-        getTool(toolID: string, signal?: AbortSignal): Promise<ToolView>;
-    }
+/**
+ * `listOperations` 请求参数。
+ *
+ * 继承 {@link PageRequest} 分页 / 排序字段；全部可选。`createTimeStart` /
+ * `createTimeEnd` 为调用方提供的【原样字符串】，后端按 `yyyy-MM-dd HH:mm:ss`
+ * 解析；SDK 不做格式校验或时区转换。
+ */
+interface ListOperationsRequest extends PageRequest {
+    /** 操作状态过滤。 */
+    status?: string;
+    /** 创建时间下界，`yyyy-MM-dd HH:mm:ss`。 */
+    createTimeStart?: string;
+    /** 创建时间上界，`yyyy-MM-dd HH:mm:ss`。 */
+    createTimeEnd?: string;
 }
 
-declare module '@acosmi/sdk-ts' {
-    interface Client {
-        /** 分页查询通知列表 */
-        listNotifications(page: number, pageSize: number, typeFilter: string, signal?: AbortSignal): Promise<NotificationList>;
-        /** 获取未读通知数量 */
-        getUnreadCount(signal?: AbortSignal): Promise<number>;
-        /** 标记单条通知已读 */
-        markNotificationRead(id: string, signal?: AbortSignal): Promise<void>;
-        /** 标记全部通知已读 */
-        markAllNotificationsRead(signal?: AbortSignal): Promise<void>;
-        /** 删除通知 */
-        deleteNotification(id: string, signal?: AbortSignal): Promise<void>;
-        /** 注册推送设备 token */
-        registerDevice(reg: DeviceRegistration, signal?: AbortSignal): Promise<void>;
-        /** 注销推送设备 token */
-        unregisterDevice(token: string, signal?: AbortSignal): Promise<void>;
-        /** 获取通知偏好设置 */
-        listNotificationPreferences(signal?: AbortSignal): Promise<NotificationPreference[]>;
-        /** 更新通知偏好 */
-        updateNotificationPreference(typeCode: string, pref: NotificationPreference, signal?: AbortSignal): Promise<void>;
-    }
+/** 模板上的可填充字段类型：签名 / 印章 / 文本 / 日期 / 勾选。 */
+type ContractTemplateFieldType = 'signature' | 'seal' | 'text' | 'date' | 'check';
+/**
+ * 模板字段叠加项。一个模板包含一组字段——签名 / 印章 / 文本 / 日期 / 勾选——
+ * 字段在 PDF 上的位置以 `page`（页码）+ `x`/`y`/`width`/`height`（坐标 / 尺寸）
+ * 描述。SDK 不在客户端做几何 / 坐标系校验，原样透传给后端。
+ */
+interface ContractTemplateField {
+    /** 字段稳定 key，调用方业务侧自定。 */
+    key: string;
+    /** 字段类型。 */
+    type: ContractTemplateFieldType;
+    /** 字段在 UI 上展示的标签。 */
+    label: string;
+    /** PDF 页码（1-based 或调用方约定，SDK 原样透传）。 */
+    page: number;
+    /** PDF 坐标系横坐标。 */
+    x: number;
+    /** PDF 坐标系纵坐标。 */
+    y: number;
+    /** 字段宽度。 */
+    width: number;
+    /** 字段高度。 */
+    height: number;
+    /** 字段绑定的角色（签署人角色 key，可选）。 */
+    assignedRole?: string;
+    /** 字段在模板内的排序键。 */
+    order: number;
+    /** 是否为必填字段。 */
+    required: boolean;
+}
+/** 模板状态。DRAFT 可编辑 / 删除 / 上传 PDF / publish；PUBLISHED / ARCHIVED 只读。 */
+type ContractTemplateStatus = 'DRAFT' | 'PUBLISHED' | 'ARCHIVED';
+/**
+ * 合同模板详情。对应后端 G5 `ContractTemplateResp`。
+ *
+ * - `pdfHash` / `pdfPageCount` 在【上传 PDF】之后才有值。
+ * - `currentVersion` 记录【已发布】版本号；DRAFT 阶段为 0。
+ * - `fields` 是【当前编辑中】的字段叠加快照——publish 时会同步固化进版本表。
+ * - 时间字段 `createTime` 为 ISO-8601 字符串。
+ */
+interface ContractTemplateResp {
+    id: number;
+    /** 模板编号（业务编号，区别于数值主键 `id`）。 */
+    templateNo: string;
+    name: string;
+    description?: string | null;
+    status: ContractTemplateStatus;
+    /** 已上传 PDF 的哈希；未上传时缺省。 */
+    pdfHash?: string | null;
+    /** 已上传 PDF 的页数；未上传时缺省。 */
+    pdfPageCount?: number | null;
+    fields: ContractTemplateField[];
+    /** 已发布版本号；DRAFT 阶段为 0。 */
+    currentVersion: number;
+    /** 创建时间 ISO-8601。 */
+    createTime: string;
 }
-
-declare module '@acosmi/sdk-ts' {
-    interface Client {
-        /**
-         * 配置请求前的底线防御 (体积 / deny-list / 深度)。
-         * 传空值 {} 关闭 (所有字段为零 = 禁用)。
-         * 并发安全, 可在任意时间调用。
-         */
-        setDefensiveSanitize(cfg: MinimalSanitizeConfig): void;
-        /**
-         * 开启后, 每次请求前 SDK 会从 rawMessages 中剥除带 acosmi_ephemeral:true 标记的 block,
-         * 并联动剥除引用已剥 tool_use 的 tool_result, 避免 provider 报 "tool_use_id 不存在".
-         *
-         * 标记来源: 网关在响应 content_block_start 中 in-band 注入; 消费者把上一轮 assistant
-         * 回复原样拼回 history 即可触发剥离。
-         */
-        setAutoStripEphemeralHistory(on: boolean): void;
-        /**
-         * 在 buildChatRequest 开头调用, 把配置化的防御策略应用到 req。
-         * 未配置时立即返回, 零开销。
-         *
-         * 失败时抛错 — 调用方应放弃本次请求。
-         */
-        applyRequestSanitizers(req: ChatRequest): void;
-    }
+/**
+ * 合同模板分页【列表项】视图。对应后端 G5 `ContractTemplatePageItem`。
+ *
+ * 与 {@link ContractTemplateResp} 一致的 SDK-safe 子集，**不含 `fields`**——
+ * 字段叠加只在详情 / 版本快照里返回，分页列表不下发，避免大对象 N+1。
+ */
+interface ContractTemplatePageItem {
+    id: number;
+    templateNo: string;
+    name: string;
+    description?: string | null;
+    status: ContractTemplateStatus;
+    pdfHash?: string | null;
+    pdfPageCount?: number | null;
+    currentVersion: number;
+    /** 创建时间 ISO-8601。 */
+    createTime: string;
+}
+/**
+ * 合同模板版本快照。对应后端 G5 `ContractTemplateVersion`。
+ *
+ * 每次 publish 会落一个版本快照，记录当时的 `name` / `pdfHash` / `fields` /
+ * `statusAtSnapshot`（publish 时模板的状态字面量）。版本是【不可变】的离线复核
+ * 依据。
+ */
+interface ContractTemplateVersion {
+    id: number;
+    templateId: number;
+    version: number;
+    name: string;
+    pdfHash?: string | null;
+    fields: ContractTemplateField[];
+    /** publish 时模板状态的字面量快照。 */
+    statusAtSnapshot: string;
+    /** 创建时间 ISO-8601。 */
+    createTime: string;
+}
+/**
+ * 创建合同模板请求。`fields` 可选——通常先在 DRAFT 状态创建模板、再上传 PDF、
+ * 然后再单独 `updateContractTemplate` 设置 / 调整字段叠加。
+ */
+interface CreateContractTemplateRequest {
+    name: string;
+    description?: string;
+    fields?: ContractTemplateField[];
+}
+/**
+ * 更新合同模板请求。仅 DRAFT 状态下允许调用——服务端在 PUBLISHED / ARCHIVED
+ * 状态下会拒绝更新。所有字段可选，缺省的字段视为【不修改】。
+ */
+interface UpdateContractTemplateRequest {
+    name?: string;
+    description?: string;
+    fields?: ContractTemplateField[];
 }
-
-/** WebSocket 长连接配置 */
-interface WSConfig {
-    /** 收到服务端事件回调 */
-    onEvent?: (ev: WSEvent) => void;
-    /** 连接建立回调 */
-    onConnect?: () => void;
-    /** 断线回调 */
-    onDisconnect?: (err: unknown) => void;
-    /** 自动订阅的主题 */
-    topics?: string[];
-    /** 最小重连间隔 (ms, 默认 2000) */
-    reconnectMinMs?: number;
-    /** 最大重连间隔 (ms, 默认 60000) */
-    reconnectMaxMs?: number;
-    /** 是否自动重连 (默认 true) */
-    autoReconnect?: boolean;
+/**
+ * 上传模板 PDF 请求。`pdfBase64` 为 base64 编码的 PDF 原文；SDK 不在客户端做
+ * PDF 解析 / 几何校验。
+ */
+interface UploadContractTemplatePdfRequest {
+    /** base64 编码的 PDF 原文。 */
+    pdfBase64: string;
+}
+/**
+ * `listContractTemplates` 请求参数。
+ *
+ * 继承 {@link PageRequest} 分页 / 排序字段；全部可选。`createTimeStart` /
+ * `createTimeEnd` 为调用方提供的【原样字符串】，后端按 `yyyy-MM-dd HH:mm:ss`
+ * 解析；SDK 不做格式校验或时区转换。
+ */
+interface ListContractTemplatesRequest extends PageRequest {
+    /** 模板状态过滤。 */
+    status?: ContractTemplateStatus | string;
+    /** 创建时间下界，`yyyy-MM-dd HH:mm:ss`。 */
+    createTimeStart?: string;
+    /** 创建时间上界，`yyyy-MM-dd HH:mm:ss`。 */
+    createTimeEnd?: string;
 }
+
 declare module '@acosmi/sdk-ts' {
     interface Client {
-        /**
-         * 建立 WebSocket 长连接 — 等待首次连接成功或 abort。
-         */
-        connect(cfg: WSConfig, signal?: AbortSignal): Promise<void>;
-        /** 优雅断开 WebSocket 连接 */
-        disconnect(): Promise<void>;
-        /** WebSocket 是否已连接 */
-        isConnected(): boolean;
+        /** SDK-facing 时间章与电子证据 / 合同签署能力。 */
+        readonly compliance: ComplianceClient;
     }
 }
+/**
+ * 当 compliance polling 检测到终态失败 / 已过 timeout / step-up 时抛出。
+ *
+ * 分类逻辑：终态失败优先于 timeout；timeout 不算 retryable，调用方必须用新 idempotency-key
+ * 重新发起整条链路。
+ */
+declare class CompliancePollError extends Error {
+    readonly kind: 'timeout' | 'terminal_failure' | 'step_up_required' | 'unknown';
+    readonly lastInfo?: ComplianceErrorInfo;
+    constructor(message: string, kind: 'timeout' | 'terminal_failure' | 'step_up_required' | 'unknown', lastInfo?: ComplianceErrorInfo);
+}
+declare class ComplianceClient {
+    private readonly client;
+    constructor(client: Client);
+    /** 创建证据资产（写）。 */
+    createEvidenceAsset(req: CreateEvidenceAssetRequest, opts?: ComplianceWriteOptions): Promise<EvidenceAsset>;
+    /** 读 — 证据资产详情。 */
+    getEvidenceAsset(id: number, signal?: AbortSignal): Promise<EvidenceAsset>;
+    /**
+     * 读 — 证据资产分页列表（compliance gateway S1）。
+     *
+     * 走 GET 读路径（允许 401 单次刷新重放）。返回 yudao `PageResult<T>`
+     * （`{ total, list }`）。所有过滤项可选；`createTimeStart` / `createTimeEnd`
+     * 由调用方按 `yyyy-MM-dd HH:mm:ss` 提供，SDK 原样透传。
+     */
+    listEvidenceAssets(req?: ListEvidenceAssetsRequest, signal?: AbortSignal): Promise<PageResult<EvidenceAssetPageItem>>;
+    /**
+     * 公开 verify。隐私边界：返回字段不含 PII / 合同原文 / storage / provider raw。
+     *
+     * 匿名可调用：未 login 时走匿名请求，不会抛 `not authorized, call login() first`。
+     * 已 login / 已持有 token 时附带 `Authorization` 以保留审计上下文。public 端点不
+     * 应要求认证 — 收到 401 直接抛 HTTPError，不触发 `forceRefresh`，也不做 refresh
+     * replay。
+     */
+    verifyEvidencePublic(params: {
+        evidenceNo?: string;
+        publicVerifyCode?: string;
+    }, signal?: AbortSignal): Promise<PublicEvidenceVerifyResult>;
+    /** 申请时间章（写）。SDK 永远不传 provider 字段。 */
+    issueTimestamp(req: IssueTimestampRequest, opts?: ComplianceWriteOptions): Promise<TimestampToken>;
+    /** 给已有资产申请时间章。SDK 永远不传 provider 字段。 */
+    issueTimestampForAsset(assetId: number, opts?: ComplianceWriteOptions): Promise<TimestampToken>;
+    /** 读 — 时间章 token 详情。 */
+    getTimestamp(id: number, signal?: AbortSignal): Promise<TimestampToken>;
+    /**
+     * 读 — 时间章分页列表（compliance gateway S1）。
+     *
+     * 走 GET 读路径。返回 yudao `PageResult<T>`。所有过滤项可选；`createTimeStart` /
+     * `createTimeEnd` 由调用方按 `yyyy-MM-dd HH:mm:ss` 提供，SDK 原样透传。
+     */
+    listTimestamps(req?: ListTimestampsRequest, signal?: AbortSignal): Promise<PageResult<TimestampPageItem>>;
+    /** verify — 本地离线校验已申请的时间章。 */
+    verifyTimestamp(req: VerifyTimestampRequest, opts?: ComplianceWriteOptions): Promise<TimestampVerifyResult>;
+    /**
+     * 轮询到 VERIFIED 终态。
+     * - VERIFIED → 返回 token；
+     * - FAILED / LOCAL_VERIFY_FAILED → 抛 {@link CompliancePollError} kind='terminal_failure'；
+     * - UNKNOWN / RETRYING / PENDING → 继续轮询直到 timeout；
+     * - timeout → 抛 {@link CompliancePollError} kind='timeout'。
+     */
+    waitForTimestampVerified(id: number, opts?: CompliancePollOptions): Promise<TimestampToken>;
+    /**
+     * 读 — 时间章授权机构（TSA）provider 列表（compliance gateway S3）。
+     *
+     * 走 GET 读路径（允许 401 单次刷新重放）。后端 G3 为每个 TSA provider 返回
+     * 一条 {@link TsaProvider}：名称、所处环境、当前是否可用。只读视图，不含
+     * provider 端点 / 凭证 / 证书等内部接入材料。
+     */
+    listTsaProviders(signal?: AbortSignal): Promise<TsaProvider[]>;
+    /**
+     * 读 — 时间章统计视图（compliance gateway S3）。
+     *
+     * 走 GET 读路径（允许 401 单次刷新重放）。返回 {@link TsaStats}：时间章总数
+     * + 按校验状态分桶的计数。只读聚合视图。
+     */
+    getTsaStats(signal?: AbortSignal): Promise<TsaStats>;
+    /** 构建证据包（写）。 */
+    buildEvidencePackage(assetId: number, timestampTokenId?: number, opts?: ComplianceWriteOptions): Promise<EvidencePackage>;
+    /**
+     * 读 — 证据包分页列表（compliance gateway S1）。
+     *
+     * 走 GET 读路径。返回 yudao `PageResult<T>`。所有过滤项可选；`createTimeStart` /
+     * `createTimeEnd` 由调用方按 `yyyy-MM-dd HH:mm:ss` 提供，SDK 原样透传。
+     */
+    listEvidencePackages(req?: ListEvidencePackagesRequest, signal?: AbortSignal): Promise<PageResult<EvidencePackagePageItem>>;
+    /** 创建证据报告（写）。 */
+    createReport(req: CreateReportRequest, opts?: ComplianceWriteOptions): Promise<ComplianceReport>;
+    /** 读 — 报告详情。 */
+    getReport(id: number, signal?: AbortSignal): Promise<ComplianceReport>;
+    /**
+     * 读 — 证据报告分页列表（compliance gateway S1）。
+     *
+     * 走 GET 读路径。返回 yudao `PageResult<T>`。所有过滤项可选；`createTimeStart` /
+     * `createTimeEnd` 由调用方按 `yyyy-MM-dd HH:mm:ss` 提供，SDK 原样透传。
+     */
+    listReports(req?: ListReportsRequest, signal?: AbortSignal): Promise<PageResult<ReportPageItem>>;
+    /**
+     * 发布报告（写，step-up 必须）。
+     *
+     * `@status gated` — step-up 闸门未闭合前服务端会一致返回
+     * `COMPLIANCE_STEP_UP_REQUIRED`（数值码 1031000013）。SDK 不会自动重试、不伪成功；
+     * 调用方需要引导用户重新做 OAuth introspection 或重新登录后再次调用本方法
+     *（使用同一 idempotency-key）。方法状态分级见 `docs/compliance.md` Method Status。
+     */
+    publishReport(id: number, opts?: ComplianceWriteOptions): Promise<ComplianceReport>;
+    /**
+     * 下载报告（读）。返回 {@link ReportDownload}：报告 hash + 资产 hash + 证据包 hash +
+     * 时间章 serial/genTime，足以离线复核。
+     * 不返回 bodyCanonicalJson / storage key / subject snapshot id。
+     */
+    downloadReport(id: number, signal?: AbortSignal): Promise<ReportDownload>;
+    /** 创建 envelope（写）。返回 envelope id。 */
+    createSigningEnvelope(req: CreateSigningEnvelopeRequest, opts?: ComplianceWriteOptions): Promise<number>;
+    /** 读 — envelope 详情。租户由服务端从 compliance token principal 推导。 */
+    getSigningEnvelope(envelopeId: number, signal?: AbortSignal): Promise<SigningEnvelope>;
+    /**
+     * 读 — 签署 envelope 分页列表（compliance gateway S1）。
+     *
+     * 走 GET 读路径。返回 yudao `PageResult<T>`。所有过滤项可选；`createTimeStart` /
+     * `createTimeEnd` 由调用方按 `yyyy-MM-dd HH:mm:ss` 提供，SDK 原样透传。
+     */
+    listSigningEnvelopes(req?: ListSigningEnvelopesRequest, signal?: AbortSignal): Promise<PageResult<SigningEnvelopePageItem>>;
+    /**
+     * 正式签署（写，step-up 必须）。
+     *
+     * `@status gated` — 服务端闸门关闭时会一致返回 `ENVELOPE_GATE_CLOSED` (1031004004)。
+     * SDK 不重试、不伪成功；调用方应该将该错误展示为"功能未开放"。
+     */
+    signEnvelope(envelopeId: number, req: SignEnvelopeRequest, opts?: ComplianceWriteOptions): Promise<void>;
+    /**
+     * 创建 H5 签署短链（写，step-up 必须）。
+     *
+     * `@status gated` — 同 {@link signEnvelope}：服务端闸门关闭时 SDK 不重试、不伪成功。
+     */
+    createH5SigningUrl(envelopeId: number, req: CreateH5SigningUrlRequest, opts?: ComplianceWriteOptions): Promise<string>;
+    /** 同步 provider 状态（写但只读对账，不创建新 provider 请求）。 */
+    syncSigningEnvelopeStatus(envelopeId: number, opts?: ComplianceWriteOptions): Promise<void>;
+    /**
+     * 读 — envelope 下挂的合同列表（compliance gateway S4）。
+     *
+     * 走 GET 读路径（允许 401 单次刷新重放）。后端 G4 为每份挂在该 envelope 上的
+     * 合同返回一条 {@link EnvelopeContractItem}：编号 / 标题 / MIME / 大小 / 哈希
+     * 指纹 / 状态。返回普通数组（非 `PageResult`）。SDK-safe 视图——不含合同原文 /
+     * storage key / provider raw payload。
+     */
+    listEnvelopeContracts(envelopeId: number, signal?: AbortSignal): Promise<EnvelopeContractItem[]>;
+    /**
+     * 读 — envelope 关联的 provider 请求列表（compliance gateway S4）。
+     *
+     * 走 GET 读路径（允许 401 单次刷新重放）。后端 G4 复用操作投影
+     * {@link OperationPageItem}：描述每次 provider 请求本身的执行进度，与 envelope
+     * 领域状态正交。返回普通数组（非 `PageResult`）。
+     */
+    listEnvelopeProviderRequests(envelopeId: number, signal?: AbortSignal): Promise<OperationPageItem[]>;
+    /**
+     * 作废 envelope（写，compliance gateway S4）。
+     *
+     * 走 compliance 写路径——发送前 `ensureToken` 一次、不自动重试、`401` 不刷新
+     * 重放；支持 `Idempotency-Key` header（强烈建议调用方持久化幂等键，重试 / 恢复
+     * 时复用，避免重复作废）。`req.reason` 为必填的作废原因，随 JSON body 提交。
+     */
+    voidEnvelope(envelopeId: number, req: VoidEnvelopeRequest, opts?: ComplianceWriteOptions): Promise<boolean>;
+    /**
+     * 提交用印审批申请（写）。
+     *
+     * `@status production-ready` — 服务端以 `Idempotency-Key` + 业务请求指纹做重放保护：
+     * 同 key + 同请求 → 返回原审批 id；同 key + 不同请求 → 拒绝复用幂等键。强烈建议调用方
+     * 持久化 `idempotencyKey`，网络重试 / 任务恢复时复用，避免重复创建审批单。
+     */
+    submitSealApproval(req: SubmitSealApprovalRequest, opts?: ComplianceWriteOptions): Promise<number>;
+    /**
+     * 审批通过用印申请（写，step-up 必须）。
+     *
+     * `@status gated` — step-up 未闭合前服务端会返回 `COMPLIANCE_STEP_UP_REQUIRED`。
+     * SDK 不重试、不伪成功。方法状态分级见 `docs/compliance.md` Method Status。
+     */
+    approveSealApproval(id: number, query: ApproveSealApprovalQuery, opts?: ComplianceWriteOptions): Promise<void>;
+    rejectSealApproval(id: number, query: RejectSealApprovalQuery, opts?: ComplianceWriteOptions): Promise<void>;
+    cancelSealApproval(id: number, query: CancelSealApprovalQuery, opts?: ComplianceWriteOptions): Promise<void>;
+    listPendingSealApprovals(signal?: AbortSignal): Promise<SealApproval[]>;
+    getSealApproval(id: number, signal?: AbortSignal): Promise<SealApproval>;
+    /**
+     * 读 — 用印审批分页列表（compliance gateway S1）。
+     *
+     * 与 {@link listPendingSealApprovals}（仅 pending、不分页）不同，本方法支持分页与
+     * 状态 / 时间过滤。走 GET 读路径。返回 yudao `PageResult<T>`。所有过滤项可选；
+     * `createTimeStart` / `createTimeEnd` 由调用方按 `yyyy-MM-dd HH:mm:ss` 提供，
+     * SDK 原样透传。
+     */
+    listSealApprovals(req?: ListSealApprovalsRequest, signal?: AbortSignal): Promise<PageResult<SealApprovalPageItem>>;
+    /**
+     * 读 — 用印执行记录分页列表（compliance gateway S6）。
+     *
+     * 走 GET 读路径（允许 401 单次刷新重放）。返回 yudao `PageResult<T>`
+     * （`{ total, list }`）。一次用印执行（seal use）描述 envelope / contract /
+     * seal / 审批联动后【真正调用 provider 落章】的那一笔记录，与 envelope
+     * 领域状态正交。所有过滤项可选；`createTimeStart` / `createTimeEnd` 由调用方
+     * 按 `yyyy-MM-dd HH:mm:ss` 提供，SDK 原样透传。
+     *
+     * 与后端复用同一只读 scope `CONTRACT_SIGNING_READ`
+     *（{@link ScopeComplianceContractSigningRead}）——不引入新 scope。
+     */
+    listSealUses(req?: ListSealUsesRequest, signal?: AbortSignal): Promise<PageResult<SealUsePageItem>>;
+    getProviderRequest(id: number, signal?: AbortSignal): Promise<ProviderRequestStatusView>;
+    /**
+     * 轮询 provider request 到 SUCCESS / FAILED 终态。
+     * - SUCCESS / FAILED → 返回最后视图；
+     * - UNKNOWN / RETRYING / PENDING → 继续轮询；
+     * - timeout → 抛 {@link CompliancePollError} kind='timeout'，不自动重发原 provider 请求。
+     *
+     * SUCCESS 不代表 billing 已 commit；调用方仍需通过业务侧 envelope / asset 终态判断。
+     */
+    waitForProviderRequestTerminal(id: number, opts?: CompliancePollOptions): Promise<ProviderRequestStatusView>;
+    /**
+     * 读 — compliance 能力闸门列表（compliance gateway S2）。
+     *
+     * 走 GET 读路径（允许 401 单次刷新重放）。后端 G2 为每个高风险 / 收费动作
+     * （`signEnvelope` / `createH5SigningUrl` / `publishReport` /
+     * `approveSealApproval` / `executeSealUse` / `createSeal`）返回一条
+     * {@link ComplianceCapability}：是否可执行、所处状态、所需 scope / step-up。
+     *
+     * 调用方在高风险动作执行【前】查询本结果做门控；拿不到能力时必须 fail-closed
+     *（按 `executable=false` 处理）。
+     */
+    getCapabilities(signal?: AbortSignal): Promise<ComplianceCapability[]>;
+    /**
+     * 读 — 单个动作的能力闸门视图（便捷方法）。
+     *
+     * 拉取完整 {@link getCapabilities} 列表并返回 `action` 匹配的那一条，无匹配时
+     * 返回 `undefined`。**每次调用产生一次网络请求**——需要门控多个动作时应改用
+     * {@link getCapabilities} 一次性取回再本地查表，避免重复请求。
+     *
+     * 与 {@link getCapabilities} 一致走 GET 读路径（允许 401 单次刷新重放）。
+     */
+    getFeatureGate(action: string, signal?: AbortSignal): Promise<ComplianceCapability | undefined>;
+    /**
+     * 读 — compliance 操作投影分页列表（compliance gateway S2）。
+     *
+     * 走 GET 读路径。返回 yudao `PageResult<T>`（`{ total, list }`）。所有过滤项
+     * 可选；`createTimeStart` / `createTimeEnd` 由调用方按 `yyyy-MM-dd HH:mm:ss`
+     * 提供，SDK 原样透传，不做格式校验或时区转换。
+     *
+     * 操作投影描述【一次操作】本身的执行进度，与履约对象的领域状态正交。
+     */
+    listOperations(req?: ListOperationsRequest, signal?: AbortSignal): Promise<PageResult<OperationPageItem>>;
+    /**
+     * 读 — compliance 操作投影详情（compliance gateway S2）。
+     *
+     * `id` 为数值行主键（非 `operationId` 幂等键）。走 GET 读路径（允许 401 单次
+     * 刷新重放）。
+     */
+    getOperation(id: number, signal?: AbortSignal): Promise<OperationDetail>;
+    /**
+     * 创建合同模板（写）。
+     *
+     * 走 compliance 写路径——发送前 `ensureToken` 一次、不自动重试、`401` 不刷新
+     * 重放；支持 `Idempotency-Key` header（强烈建议调用方持久化幂等键，重试 / 恢复
+     * 时复用，避免重复创建模板）。模板创建后初始状态为 `DRAFT`。
+     */
+    createContractTemplate(req: CreateContractTemplateRequest, opts?: ComplianceWriteOptions): Promise<ContractTemplateResp>;
+    /**
+     * 更新合同模板（写，仅 DRAFT 状态）。
+     *
+     * 走 compliance 写路径——`Idempotency-Key`、不重试、`401` 不刷新重放。所有字段
+     * 可选，缺省字段视为不修改。服务端在 PUBLISHED / ARCHIVED 状态下会拒绝更新。
+     */
+    updateContractTemplate(id: number, req: UpdateContractTemplateRequest, opts?: ComplianceWriteOptions): Promise<ContractTemplateResp>;
+    /**
+     * 删除合同模板（写，仅 DRAFT 状态）。
+     *
+     * 走 compliance 写路径——`Idempotency-Key`、不重试、`401` 不刷新重放。服务端
+     * 在 PUBLISHED / ARCHIVED 状态下会拒绝删除——已发布的模板应改走 `archive`。
+     */
+    deleteContractTemplate(id: number, opts?: ComplianceWriteOptions): Promise<void>;
+    /** 读 — 合同模板详情。 */
+    getContractTemplate(id: number, signal?: AbortSignal): Promise<ContractTemplateResp>;
+    /**
+     * 读 — 合同模板分页列表（compliance gateway S5）。
+     *
+     * 走 GET 读路径（允许 401 单次刷新重放）。返回 yudao `PageResult<T>`
+     * （`{ total, list }`）。所有过滤项可选；`createTimeStart` / `createTimeEnd`
+     * 由调用方按 `yyyy-MM-dd HH:mm:ss` 提供，SDK 原样透传。列表项视图
+     * {@link ContractTemplatePageItem} 不含 `fields`——字段叠加只在详情 / 版本
+     * 快照里返回。
+     */
+    listContractTemplates(req?: ListContractTemplatesRequest, signal?: AbortSignal): Promise<PageResult<ContractTemplatePageItem>>;
+    /**
+     * 上传合同模板 PDF（写）。
+     *
+     * 走 compliance 写路径——`Idempotency-Key`、不重试、`401` 不刷新重放。请求体
+     * 为 `{ pdfBase64 }`；SDK 不在客户端做 PDF 解析 / 几何校验，原样透传给后端。
+     * 返回上传后的最新模板视图（含 `pdfHash` / `pdfPageCount`）。
+     */
+    uploadContractTemplatePdf(id: number, req: UploadContractTemplatePdfRequest, opts?: ComplianceWriteOptions): Promise<ContractTemplateResp>;
+    /**
+     * 发布合同模板（写）。DRAFT → PUBLISHED，落版本快照。
+     *
+     * 走 compliance 写路径——`Idempotency-Key`、不重试、`401` 不刷新重放。
+     * publish 后 `currentVersion` 递增，`fields` 与 `pdfHash` 同步固化进版本表。
+     */
+    publishContractTemplate(id: number, opts?: ComplianceWriteOptions): Promise<ContractTemplateResp>;
+    /**
+     * 归档合同模板（写）。PUBLISHED → ARCHIVED。
+     *
+     * 走 compliance 写路径——`Idempotency-Key`、不重试、`401` 不刷新重放。
+     * 已归档模板只读，不再允许 publish / 编辑 / 删除。
+     */
+    archiveContractTemplate(id: number, opts?: ComplianceWriteOptions): Promise<ContractTemplateResp>;
+    /**
+     * 读 — 合同模板版本快照列表。
+     *
+     * 走 GET 读路径（允许 401 单次刷新重放）。返回 {@link ContractTemplateVersion}
+     * 普通数组（非 `PageResult`）——每次 publish 落一个不可变快照，记录当时的
+     * `name` / `pdfHash` / `fields` / `statusAtSnapshot`，是离线复核 / 版本对账
+     * 的依据。
+     */
+    listContractTemplateVersions(id: number, signal?: AbortSignal): Promise<ContractTemplateVersion[]>;
+    classifyError(err: unknown): ComplianceErrorInfo | null;
+    /**
+     * 读路径：GET / 公开 verify。允许 401 单次刷新后重放（GET 幂等安全）。
+     * 与 client.doJSONFullInternal 行为一致；不复用其代码因为 base URL 不同。
+     */
+    private read;
+    /**
+     * 公开读路径：public verify。
+     *
+     * 与 {@link read} 的区别 — public 端点不应要求认证：
+     *   - 无 token 时匿名请求：ensureToken 抛 `not authorized` 会被吞掉，继续匿名发送。
+     *   - 有 token 时附带 `Authorization`，保留后端审计上下文。
+     *   - 不做 401 refresh replay：401 直接抛 HTTPError，不触发 `forceRefresh`。
+     *
+     * URL 仍走 `client.complianceURL(path)`，不复用 `/api/v4`；底层复用
+     * `client.doRequest`，不新增 fetch/axios 直连。
+     */
+    private publicRead;
+    /**
+     * 写路径：POST。
+     * - 发送前 ensureToken 一次确保 token fresh。
+     * - 不自动 401 重放：401 → 抛 HTTPError；调用方必须自己刷新 token 后用同一
+     *   idempotency-key 重新发起，避免 provider 侧重复请求。
+     * - 不走 doRequestWithRetry：写操作不允许 5xx/timeout 自动重试。
+     */
+    private write;
+    private executeJson;
+    private poll;
+}
 
 /** POST /api/v4/crabcode_cli_feedback 返回体 */
 interface BugReportResult {
@@ -1763,4 +3384,4 @@ declare module '@acosmi/sdk-ts' {
     }
 }
 
-export { type AgentRun, type AgentRunArtifact, type AgentRunArtifactList, type AgentRunArtifactPolicy, type AgentRunCreateRequest, type AgentRunCreateResponse, type AgentRunDownload, type AgentRunErrorPayload, type AgentRunLocalContextPolicy, type AgentRunLocalToolHandler, type AgentRunLocalToolHandlerContext, type AgentRunLocalToolResult, type AgentRunRunOptions, type AgentRunSettlement, type AgentRunStatus, AgentRunStreamError, type AgentRunStreamEvent, type AgentRunStreamOptions, type AgentRunUsage, type AgentRunWithLocalToolsOptions, AgentRunsClient, AnthropicResponse, type ApproveSealApprovalQuery, type AuthorizeResult, BalanceDetail, type BlockMeta, type BrowserRefreshMode, type BugReportResult, type BugView, BusinessError, type CancelSealApprovalQuery, CertificationStatus, ChatRequest, ChatResponse, Client, ClientRegistration, type ComplianceAssetType, type ComplianceBillingDisplayStatus, ComplianceClient, type ComplianceClientErrorCode, type ComplianceDigestSource, type ComplianceEnvelopeStatus, type ComplianceErrorInfo, type ComplianceErrorKey, type ComplianceHashAlgorithm, CompliancePollError, type CompliancePollOptions, type CompliancePrivacyLevel, type ComplianceProviderRequestStatus, type ComplianceProviderStatus, type ComplianceReport, type ComplianceScope, type ComplianceSealApprovalStatus, type ComplianceTimestampVerificationStatus, type ComplianceWriteOptions, type Config, ConsumeRecordPage, type CreateEvidenceAssetRequest, type CreateH5SigningUrlRequest, type CreateReportRequest, type CreateSigningEnvelopeRequest, type CreateWebAuthorizationRequestOptions, DefaultRetryPolicy, DeviceRegistration, EntitlementBalance, EntitlementItem, ErrAuthDenied, ErrBillingCallbackCannotCommit, ErrBillingCommitRequiresLocalVerify, ErrBillingS2sForbidden, ErrBrowserOpen, ErrComplianceStepUpRequired, ErrDiscovery, ErrEnvelopeGateClosed, ErrOAuthCORSBlocked, ErrProviderNotConfigured, ErrProviderUnknownNoRetry, ErrRefreshProxyFailed, ErrRegistration, ErrSSLProxy, ErrSealApprovalContractHashMismatch, ErrSealApprovalExpired, ErrSealApprovalLocationMismatch, ErrSealApprovalNonceUsed, ErrSealApprovalNotApproved, ErrSealApprovalSealMismatch, ErrSealApprovalTransactorMismatch, ErrSealUseAlreadyConsumed, ErrStateMismatch, ErrTimeout, ErrTokenExchange, ErrTokenExpired, EventAuthURL, EventComplete, EventError, type EvidenceAsset, type EvidencePackage, FileTokenStore, type FilterStatus, FilterStatusAdminBypass, FilterStatusDisabledByFlag, FilterStatusFallbackMissingUser, FilterStatusFallbackNoBuckets, FilterStatusFallbackTkdistError, FilterStatusFallbackTkdistSkew, FilterStatusInternalBypass, FilterStatusOK, FilterStatusUnknown, GenerateSkillRequest, GenerateSkillResult, InMemoryTokenStore, InputModality, type IssueTimestampRequest, LocalStorageTokenStore, type LoginErrCode, type LoginEvent, type LoginEventType, type LoginOptions, ManagedModel, ModelBucket, ModelByQuotaResponse, ModelCapabilities, ModelCoefficient, NotificationList, NotificationPreference, type OAuthMetadataProfile, OptimizeSkillRequest, OptimizeSkillResult, Order, OrderStatus, PayPayload, ProviderAdapter, type ProviderRequestStatusView, type PublicEvidenceVerifyResult, QuotaSummary, type RegisterWebOAuthClientOptions, type RejectSealApprovalQuery, type ReportDownload, type RetryPolicy, type RetryRequestInfo, ScopeAI, ScopeAccount, ScopeComplianceContractSigningRead, ScopeComplianceContractSigningWrite, ScopeComplianceEvidenceRead, ScopeComplianceEvidenceWrite, ScopeComplianceReportsPublish, ScopeComplianceReportsRead, ScopeComplianceReportsWrite, ScopeComplianceSealApprovalApprove, ScopeComplianceSealApprovalRequest, ScopeComplianceSealManage, ScopeComplianceSealUseExecute, ScopeComplianceTimestampIssue, ScopeComplianceTimestampVerify, ScopeEntitlements, ScopeModels, ScopeModelsChat, ScopeProfile, ScopeSkillStore, ScopeSkills, ScopeTokenPackages, ScopeTools, ScopeToolsExecute, ScopeWallet, ScopeWalletReadonly, type SealApproval, ServerMetadata, type SignEnvelopeRequest, type SigningEnvelope, SkillBrowseListResponse, SkillBrowseResponse, SkillStoreItem, SkillStoreQuery, SkillSummary, SourcesEvent, StreamEvent, StreamSettlement, type SubmitSealApprovalRequest, type TimestampToken, type TimestampVerifyResult, TokenPackage, TokenResponse, TokenSet, type TokenStore, ToolView, Transaction, type VerifyTimestampRequest, type WSConfig, WSEvent, WalletStats, type WebAuthorizationCallbackParams, type WebAuthorizationPending, type WebAuthorizationRequest, allScopes, authorize, buildBetas, classifyComplianceError, commerceScopes, completeWebAuthorizationRequest, complianceScopes, computeBackoff, createWebAuthorizationRequest, defaultRetryable, defaultSafeToRetry, discover, discoverWebOAuthMetadata, discoverWithProfile, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, fileLockDefaults, findDesktopVisualUnderstandingModel, findFirstModelByInputModality, generateState, isBillingConfirmable, isComplianceBusinessError, isComplianceTerminalError, isSSLError, modelScopes, modelSupportsImageInput, modelSupportsInputModality, newFileTokenStore, newTokenSet, refreshToken, register, registerWebOAuthClient, revokeToken, skillScopes, uniqueMerge };
+export { type APIResponse, type AgentRun, type AgentRunArtifact, type AgentRunArtifactList, type AgentRunArtifactPolicy, type AgentRunCreateRequest, type AgentRunCreateResponse, type AgentRunDownload, type AgentRunErrorPayload, type AgentRunLocalContextPolicy, type AgentRunLocalToolHandler, type AgentRunLocalToolHandlerContext, type AgentRunLocalToolResult, type AgentRunRunOptions, type AgentRunSettlement, type AgentRunStatus, AgentRunStreamError, type AgentRunStreamEvent, type AgentRunStreamOptions, type AgentRunUsage, type AgentRunWithLocalToolsOptions, AgentRunsClient, AnthropicResponse, type ApiClientRef, type ApproveSealApprovalQuery, type AuthorizeResult, type BalanceDetail, type BillingPreflightResult, type BlockMeta, type BrowserRefreshMode, type BugReportResult, type BugView, BusinessError, type CancelSealApprovalQuery, type CertificationStatus, ChatRequest, ChatResponse, Client, type ClientRegistration, type ComplianceAssetType, type ComplianceBillingDisplayStatus, type ComplianceCapability, ComplianceClient, type ComplianceClientErrorCode, type ComplianceDigestSource, type ComplianceEnvelopeStatus, type ComplianceErrorInfo, type ComplianceErrorKey, type ComplianceHashAlgorithm, CompliancePollError, type CompliancePollOptions, type CompliancePrivacyLevel, type ComplianceProviderRequestStatus, type ComplianceProviderStatus, type ComplianceReport, type ComplianceScope, type ComplianceSealApprovalStatus, type ComplianceTimestampVerificationStatus, type ComplianceWriteOptions, type Config, type ConsumeRecord, type ConsumeRecordPage, type ContractTemplateField, type ContractTemplateFieldType, type ContractTemplatePageItem, type ContractTemplateResp, type ContractTemplateStatus, type ContractTemplateVersion, type CreateContractTemplateRequest, type CreateEvidenceAssetRequest, type CreateH5SigningUrlRequest, type CreateReportRequest, type CreateSigningEnvelopeRequest, type CreateWebAuthorizationRequestOptions, DefaultRetryPolicy, type DeviceRegistration, type EntitlementBalance, type EntitlementItem, type EnvelopeContractItem, ErrAuthDenied, ErrBillingCallbackCannotCommit, ErrBillingCommitRequiresLocalVerify, ErrBillingS2sForbidden, ErrBrowserOpen, ErrComplianceStepUpRequired, ErrDiscovery, ErrEnvelopeGateClosed, ErrOAuthCORSBlocked, ErrProviderNotConfigured, ErrProviderUnknownNoRetry, ErrRefreshProxyFailed, ErrRegistration, ErrSSLProxy, ErrSealApprovalContractHashMismatch, ErrSealApprovalExpired, ErrSealApprovalLocationMismatch, ErrSealApprovalNonceUsed, ErrSealApprovalNotApproved, ErrSealApprovalSealMismatch, ErrSealApprovalTransactorMismatch, ErrSealUseAlreadyConsumed, ErrStateMismatch, ErrTimeout, ErrTokenExchange, ErrTokenExpired, EventAuthURL, EventComplete, EventError, type EvidenceAsset, type EvidenceAssetPageItem, type EvidencePackage, type EvidencePackagePageItem, type FeatureGateState, type FeatureGateStatus, FileTokenStore, type FilterStatus, FilterStatusAdminBypass, FilterStatusDisabledByFlag, FilterStatusFallbackMissingUser, FilterStatusFallbackNoBuckets, FilterStatusFallbackTkdistError, FilterStatusFallbackTkdistSkew, FilterStatusInternalBypass, FilterStatusOK, FilterStatusUnknown, type GateQuota, type GenerateSkillRequest, type GenerateSkillResult, HTTPError, type IdempotencyKey, IdempotencyKeyHeader, InMemoryTokenStore, InputModality, type IssueTimestampRequest, type ListContractTemplatesRequest, type ListEvidenceAssetsRequest, type ListEvidencePackagesRequest, type ListOperationsRequest, type ListReportsRequest, type ListSealApprovalsRequest, type ListSealUsesRequest, type ListSigningEnvelopesRequest, type ListTimestampsRequest, LocalStorageTokenStore, type LoginErrCode, type LoginEvent, type LoginEventType, type LoginOptions, ManagedModel, type ModelBucket, type ModelByQuotaResponse, ModelCapabilities, type ModelCoefficient, ModelNotFoundError, NetworkError, type Notification, type NotificationList, type NotificationPreference, type NotificationUnreadCount, type OAuthMetadataProfile, type OpenAIChatChoice, type OpenAIChatMessage, type OpenAIChatResponse, type OpenAIFunctionCall, type OpenAIStreamChoice, type OpenAIStreamChunk, type OpenAIStreamDelta, type OpenAIStreamToolCall, type OpenAIToolCall, type OpenAIUsage, type OperationDetail, type OperationId, type OperationPageItem, type OperationSource, type OperationStatus, type OptimizeSkillRequest, type OptimizeSkillResult, type Order, type OrderStatus, OrderTerminalError, type PageRequest, type PageResult, type PayPayload, type PrincipalRef, ProviderAdapter, type ProviderRequestStatus, type ProviderRequestStatusView, type PublicEvidenceVerifyResult, QuotaSummary, RETRY_ADVICE_REASONS, RateLimitError, type RegisterWebOAuthClientOptions, type RejectSealApprovalQuery, type ReportDownload, type ReportPageItem, type RetryAdvice, type RetryAdviceReason, type RetryPolicy, type RetryRequestInfo, ScopeAI, ScopeAccount, ScopeComplianceContractSigningRead, ScopeComplianceContractSigningWrite, ScopeComplianceContractTemplateRead, ScopeComplianceContractTemplateWrite, ScopeComplianceEvidenceRead, ScopeComplianceEvidenceWrite, ScopeComplianceReportsPublish, ScopeComplianceReportsRead, ScopeComplianceReportsWrite, ScopeComplianceSealApprovalApprove, ScopeComplianceSealApprovalRequest, ScopeComplianceSealManage, ScopeComplianceSealUseExecute, ScopeComplianceTimestampIssue, ScopeComplianceTimestampVerify, ScopeEntitlements, ScopeModels, ScopeModelsChat, ScopeProfile, ScopeSkillStore, ScopeSkills, ScopeTokenPackages, ScopeTools, ScopeToolsExecute, ScopeWallet, ScopeWalletReadonly, type SealApproval, type SealApprovalPageItem, type SealUsePageItem, type ServerMetadata, type SignEnvelopeRequest, type SigningEnvelope, type SigningEnvelopePageItem, type SkillBrowseListResponse, type SkillBrowseResponse, type SkillStoreItem, type SkillStoreListItem, type SkillStoreQuery, type SkillSummary, type SortDirection, SourcesEvent, type StepUpStatus, StreamError, StreamEvent, StreamSettlement, type SubmitSealApprovalRequest, type TenantRef, type TimestampPageItem, type TimestampToken, type TimestampVerifyResult, type TokenPackage, type TokenResponse, type TokenSet, type TokenStore, type ToolListResponse, type ToolProvider, type ToolView, type Transaction, type TsaProvider, type TsaStats, type UpdateContractTemplateRequest, type UploadContractTemplatePdfRequest, type VerifyStatus, type VerifyTimestampRequest, type VoidEnvelopeRequest, type WSConfig, type WSEvent, type WalletStats, type WebAuthorizationCallbackParams, type WebAuthorizationPending, type WebAuthorizationRequest, type YudaoPageResult, allScopes, apiResponseBusinessError, apiResponseGetMessage, authorize, buildBetas, classifyComplianceError, commerceScopes, completeWebAuthorizationRequest, complianceErrorToRetryAdvice, complianceScopes, computeBackoff, createWebAuthorizationRequest, defaultRetryable, defaultSafeToRetry, discover, discoverWebOAuthMetadata, discoverWithProfile, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, fileLockDefaults, findDesktopVisualUnderstandingModel, findFirstModelByInputModality, generateState, isBillingConfirmable, isComplianceBusinessError, isComplianceTerminalError, isSSLError, modelScopes, modelSupportsImageInput, modelSupportsInputModality, newFileTokenStore, newTokenSet, parseNotificationEvent, refreshToken, register, registerWebOAuthClient, retryReasonForComplianceKey, retryReasonForOAuthError, revokeToken, skillScopes, tokenSetIsExpired, uniqueMerge };