@acosmi/sdk-ts 1.1.0 → 1.3.0

package/dist/node/index.d.cts

@@ -1,10 +1,53 @@
-import { S as ServerMetadata, T as TokenResponse, a as TokenSet, C as ClientRegistration, M as ManagedModel, 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, B as BalanceDetail, i as EntitlementItem, j as ConsumeRecordPage, k as ModelByQuotaResponse, l as ModelBucket, m as TokenPackage, n as PayPayload, O as Order, o as OrderStatus, W as WalletStats, p as Transaction, q as SkillStoreQuery, r as SkillStoreItem, s as SkillBrowseResponse, t as SkillBrowseListResponse, u as SkillSummary, v as CertificationStatus, G as GenerateSkillRequest, w as GenerateSkillResult, x as OptimizeSkillRequest, y as OptimizeSkillResult, z as ToolView, N as NotificationList, D as DeviceRegistration, F as NotificationPreference, H as WSEvent } from './index-BI8EgBXu.cjs';
-export { I as APIResponse, J as AnthropicContentBlock, K as AnthropicUsage, L as BucketClassCommercial, R as BucketClassGeneric, U as BucketInfo, V as BucketRow, X as BusinessError, Y as ChatContentBlock, Z as ChatMessage, _ as ChatUsage, $ as ConsumeRecord, a0 as EffortConfig, a1 as GeoLoc, a2 as HTTPError, a3 as ModelNotFoundError, a4 as NetworkError, a5 as Notification, a6 as NotificationUnreadCount, a7 as OpenAIChatChoice, a8 as OpenAIChatMessage, a9 as OpenAIChatResponse, aa as OpenAIFunctionCall, ab as OpenAIStreamChoice, ac as OpenAIStreamChunk, ad as OpenAIStreamDelta, ae as OpenAIStreamToolCall, af as OpenAIToolCall, ag as OpenAIUsage, ah as OrderTerminalError, ai as OutputConfig, aj as ProviderFormat, ak as RateLimitError, al as ServerTool, am as ServerToolTypeWebSearch, an as SkillStoreListItem, ao as StreamError, ap as ThinkingConfig, aq as ThinkingHigh, ar as ThinkingHighMinMaxTokens, as as ThinkingMax, at as ThinkingMaxFallbackMaxTokens, au as ThinkingOff, av as ToolListResponse, aw as ToolProvider, ax as WebSearchConfig, ay as WebSearchSource, az as YudaoPageResult, aA as anthropicResponseTextContent, aB as anthropicResponseThinkingContent, aC as anthropicResponseToolUseBlocks, aD as apiResponseBusinessError, aE as apiResponseGetMessage, aF as bucketInfoIsCommercial, aG as bucketRowIsCommercial, aH as getAdapter, aI as getAdapterForModel, aJ as newThinkingConfig, aK as newWebSearchTool, aL as parseNotificationEvent, aM as parseSettlement, aN as parseSourcesEvent, aO as tokenSetIsExpired } from './index-BI8EgBXu.cjs';
+import { M as ManagedModel, I as InputModality, S as ServerMetadata, T as TokenResponse, a as TokenSet, 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-28x02ITB.cjs';
+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-28x02ITB.cjs';
 import { M as MinimalSanitizeConfig } from './index-nvLKgCm9.cjs';
 export { i as sanitize } from './index-nvLKgCm9.cjs';
 export { AnthropicAdapter } from './adapters/anthropic.cjs';
 export { OpenAIAdapter } from './adapters/openai.cjs';
 
+/**
+ * 判断 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;
+
 /**
  * 从 well-known 端点获取 Desktop OAuth 服务元数据。
  *
@@ -105,8 +148,24 @@ declare const ScopeWallet = "wallet";
 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 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 ScopeComplianceReportsPublish;
 /** 全部分组 scope (推荐) */
 declare function allScopes(): string[];
+/** 全部合规域 scope。OAuth 申请合规权限时使用; 谨慎一次性申请全部, 推荐按业务最小集合申请。 */
+declare function complianceScopes(): ComplianceScope[];
 /** 模型服务相关 scope */
 declare function modelScopes(): string[];
 /** 商城/钱包 scope */
@@ -114,6 +173,340 @@ declare function commerceScopes(): string[];
 /** 技能/工具 scope */
 declare function skillScopes(): string[];
 
+/**
+ * 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;
+
+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;
+}
+interface TimestampVerifyResult {
+    passed: boolean;
+    reason: string;
+}
+interface EvidencePackage {
+    id: number;
+    assetId: number;
+    timestampTokenId?: number | null;
+    chainId: string;
+    packageVersion: string;
+    hashAlgorithm: string;
+    manifestHash: string;
+    packageHash: string;
+    status: 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 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)
@@ -284,196 +677,6 @@ declare function effectivePolicy(p: RetryPolicy | null | undefined): Required<Re
  */
 declare function computeBackoff(p: Required<RetryPolicy>, attempt: number, err: unknown): number;
 
-/** 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];
-
-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';
-    }>);
-}
-
 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;
@@ -505,6 +708,17 @@ interface Config {
      * 计费安全: 自定义 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;
 }
 interface Deferred<T> {
     promise: Promise<T>;
@@ -529,6 +743,8 @@ declare class Client {
     /** SDK 内部使用 — 业务方法 (mixin) 通过 this.* 访问以下字段 */
     /** 服务器根地址 (已 trim 尾随 /) */
     serverURL: string;
+    /** Compliance API 根地址 (已 trim 尾随 /); null = 走默认 ${serverURL}/admin-api */
+    complianceBaseURL: string | null;
     /** OAuth metadata (lazy loaded) */
     meta: ServerMetadata | null;
     /** 当前 token (内存) */
@@ -714,6 +930,16 @@ declare class Client {
         event: StreamSettlement;
     }, void, void>;
     apiURL(path: string): string;
+    /**
+     * Compliance API URL 拼接。
+     *
+     * `complianceBaseURL` 已配置时直接拼接；未配置时默认
+     * `${serverURL}/admin-api` + path，匹配 Java compliance controller 的
+     * `/compliance/...` 路径。
+     *
+     * 不复用 `apiURL`：apiURL 强制追加 `/api/v4`，与 compliance 路径不同。
+     */
+    complianceURL(path: string): string;
     /** GET/POST/... 通用 JSON 调用 (返回 result 已 typed) */
     doJSON<T>(method: string, path: string, body: unknown | null, signal?: AbortSignal): Promise<T>;
     /** 与 doJSON 相同, 但返回响应 Headers (用于提取 X-Token-Remaining 等) */
@@ -762,6 +988,317 @@ declare class Client {
     }, signal?: AbortSignal): Promise<Response>;
 }
 
+declare module '@acosmi/sdk-ts' {
+    interface Client {
+        /** 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>;
+    /**
+     * 公开 verify。隐私边界：返回字段不含 PII / 合同原文 / storage / provider raw。
+     * 服务端不要求 compliance scope（公开端点）；但 SDK 仍带上 token 以便审计。
+     */
+    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 必须）。
+     *
+     * 缺少 step-up 时服务端会返回 `COMPLIANCE_STEP_UP_REQUIRED`（数值码
+     * 1031000013）。SDK 不会自动重试；调用方需要引导用户重新做 OAuth introspection 或
+     * 重新登录后再次调用本方法（使用同一 idempotency-key）。
+     */
+    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 必须）。
+     *
+     * 服务端闸门关闭时会一致返回 `ENVELOPE_GATE_CLOSED` (1031004004)。
+     * SDK 不重试、不伪成功；调用方应该将该错误展示为"功能未开放"。
+     */
+    signEnvelope(envelopeId: number, req: SignEnvelopeRequest, opts?: ComplianceWriteOptions): Promise<void>;
+    /**
+     * 创建 H5 签署短链（写，step-up 必须）。
+     *
+     * 同上：服务端闸门关闭时 SDK 不重试。
+     */
+    createH5SigningUrl(envelopeId: number, req: CreateH5SigningUrlRequest, opts?: ComplianceWriteOptions): Promise<string>;
+    /** 同步 provider 状态（写但只读对账，不创建新 provider 请求）。 */
+    syncSigningEnvelopeStatus(envelopeId: number, opts?: ComplianceWriteOptions): Promise<void>;
+    submitSealApproval(req: SubmitSealApprovalRequest, opts?: ComplianceWriteOptions): Promise<number>;
+    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;
+    /**
+     * 写路径：POST。
+     * - 发送前 ensureToken 一次确保 token fresh。
+     * - 不自动 401 重放：401 → 抛 HTTPError；调用方必须自己刷新 token 后用同一
+     *   idempotency-key 重新发起，避免 provider 侧重复请求。
+     * - 不走 doRequestWithRetry：写操作不允许 5xx/timeout 自动重试。
+     */
+    private write;
+    private executeJson;
+    private poll;
+}
+
+/** 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];
+
+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. */
@@ -1036,4 +1573,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 AuthorizeResult, BalanceDetail, type BlockMeta, type BugReportResult, type BugView, CertificationStatus, ChatRequest, ChatResponse, Client, ClientRegistration, type Config, ConsumeRecordPage, DefaultRetryPolicy, DeviceRegistration, EntitlementBalance, EntitlementItem, ErrAuthDenied, ErrBrowserOpen, ErrDiscovery, ErrRegistration, ErrSSLProxy, ErrTimeout, ErrTokenExchange, EventAuthURL, EventComplete, EventError, FileTokenStore, type FilterStatus, FilterStatusAdminBypass, FilterStatusDisabledByFlag, FilterStatusFallbackMissingUser, FilterStatusFallbackNoBuckets, FilterStatusFallbackTkdistError, FilterStatusFallbackTkdistSkew, FilterStatusInternalBypass, FilterStatusOK, FilterStatusUnknown, GenerateSkillRequest, GenerateSkillResult, InMemoryTokenStore, LocalStorageTokenStore, type LoginErrCode, type LoginEvent, type LoginEventType, type LoginOptions, ManagedModel, ModelBucket, ModelByQuotaResponse, ModelCapabilities, ModelCoefficient, NotificationList, NotificationPreference, OptimizeSkillRequest, OptimizeSkillResult, Order, OrderStatus, PayPayload, ProviderAdapter, QuotaSummary, type RetryPolicy, type RetryRequestInfo, ScopeAI, ScopeAccount, ScopeEntitlements, ScopeModels, ScopeModelsChat, ScopeProfile, ScopeSkillStore, ScopeSkills, ScopeTokenPackages, ScopeTools, ScopeToolsExecute, ScopeWallet, ScopeWalletReadonly, ServerMetadata, SkillBrowseListResponse, SkillBrowseResponse, SkillStoreItem, SkillStoreQuery, SkillSummary, SourcesEvent, StreamEvent, StreamSettlement, TokenPackage, TokenResponse, TokenSet, type TokenStore, ToolView, Transaction, type WSConfig, WSEvent, WalletStats, allScopes, authorize, buildBetas, commerceScopes, computeBackoff, defaultRetryable, defaultSafeToRetry, discover, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, fileLockDefaults, isSSLError, modelScopes, newFileTokenStore, newTokenSet, refreshToken, register, revokeToken, skillScopes, uniqueMerge };
+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 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, DefaultRetryPolicy, DeviceRegistration, EntitlementBalance, EntitlementItem, ErrAuthDenied, ErrBillingCallbackCannotCommit, ErrBillingCommitRequiresLocalVerify, ErrBillingS2sForbidden, ErrBrowserOpen, ErrComplianceStepUpRequired, ErrDiscovery, ErrEnvelopeGateClosed, ErrProviderNotConfigured, ErrProviderUnknownNoRetry, ErrRegistration, ErrSSLProxy, ErrSealApprovalContractHashMismatch, ErrSealApprovalExpired, ErrSealApprovalLocationMismatch, ErrSealApprovalNonceUsed, ErrSealApprovalNotApproved, ErrSealApprovalSealMismatch, ErrSealApprovalTransactorMismatch, ErrSealUseAlreadyConsumed, ErrTimeout, ErrTokenExchange, 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, OptimizeSkillRequest, OptimizeSkillResult, Order, OrderStatus, PayPayload, ProviderAdapter, type ProviderRequestStatusView, type PublicEvidenceVerifyResult, QuotaSummary, type RejectSealApprovalQuery, type ReportDownload, type RetryPolicy, type RetryRequestInfo, ScopeAI, ScopeAccount, ScopeComplianceContractSigningRead, ScopeComplianceContractSigningWrite, ScopeComplianceEvidenceRead, ScopeComplianceEvidenceWrite, ScopeComplianceReportsPublish, ScopeComplianceReportsRead, 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, allScopes, authorize, buildBetas, classifyComplianceError, commerceScopes, complianceScopes, computeBackoff, defaultRetryable, defaultSafeToRetry, discover, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, fileLockDefaults, findDesktopVisualUnderstandingModel, findFirstModelByInputModality, isBillingConfirmable, isComplianceBusinessError, isComplianceTerminalError, isSSLError, modelScopes, modelSupportsImageInput, modelSupportsInputModality, newFileTokenStore, newTokenSet, refreshToken, register, revokeToken, skillScopes, uniqueMerge };