/*! * @tansr/sdk — MIT License. * Bundled artifact: compiled code and types from the tansr internal workspace * packages (@tansr/kernel, @tansr/providers, @tansr/protocol, @tansr/i18n) are * inlined into this file and distributed under the MIT license as part of * @tansr/sdk. Third-party runtime dependencies (@vscode/ripgrep, undici, zod, zod-to-json-schema) * are resolved from npm as regular / optional dependencies; any third-party * code compiled into this file is listed in the NOTICE file shipped alongside. */ import { CreateSessionOptions, AgentSession, SessionStore } from './index.js'; import { z } from 'zod'; /** * 内核事件协议(一份数据三用:UI 渲染 / 审计 / 编排) * * 设计要点: * - 事件族与包络分离; * - 一等 error 事件、tombstone→message.retracted; * - 审计 schema 的关联链字段:trace/span/prompt/agent。 * * 兼容规则:消费端必须容忍未知事件 type(向前兼容),据包络 `v` 字段判断。 */ /** 一轮查询的终止原因词表:正常完成、各类上限触顶、模型错误、中断 / 超时 / 关停、hook 阻断等。 */ declare const TerminalReasonSchema: z.ZodEnum<["completed", "blocking_limit", "aborted_streaming", "aborted_tools", "model_error", "prompt_too_long", "max_turns", "max_tool_rounds", "injection_limit", "hook_stopped", "structured_output", "timeout", "shutdown", "budget_exceeded", "stop_hook_limit", "internal_error", "client_gone"]>; /** 一轮查询的终止原因(TerminalReasonSchema 推导)。 */ type TerminalReason = z.infer; interface ArchiveGenerations { readonly historyEpoch: string; readonly deletionGeneration: string; readonly projectionRevision: string; } interface ArchiveTarget { readonly sessionId: string; readonly generations: ArchiveGenerations; readonly sourceSnapshotDigest: string; } interface ArchiveArtifactRef { readonly artifactId: string; readonly sourceId: string; readonly bytes: number; readonly sha256: string; readonly mediaType: string; } interface ArchiveCoverage { readonly fromSequence: string; readonly throughSequence: string; readonly headDigest: string; } interface ArchiveProjection { readonly coverage: ArchiveCoverage; readonly assemblerVersion: string; readonly sourceHeadDigest: string; } interface ArchiveRecord { readonly recordId: string; readonly sequence: string; readonly target: ArchiveTarget; readonly turnId: string; readonly recordKind: 'turn' | 'projection' | 'terminal'; readonly turnState: 'completed' | 'cancelled' | 'incomplete'; readonly predecessorDigest: string; readonly recordDigest: string; readonly payload: ArchiveArtifactRef; readonly attachments: readonly ArchiveArtifactRef[]; readonly payloadDigest: string; readonly sourceEventRange?: { readonly firstSeq: number; readonly lastSeq: number; }; readonly projection?: ArchiveProjection; } /** 内部宿主接口；不是SDK1导出或可由请求提供的授权声明。 */ interface ArchiveBindingScope { readonly applicationScopeId: string; readonly endUserId: string; readonly authorizationRevision: string; } type ArchiveBindingCapability = 'archive-transfer-v1' | 'context-materials-v1'; /** 内部单宿主接线；DTO遵从sdk2-ext-v1，不自行注册HTTP或SDK1入口。 */ interface MaterialRequest { readonly protocol: 'sdk2-ext-v1'; readonly bindingId: string; readonly materialRequestId: string; readonly target: ArchiveTarget; readonly sourceId: string; readonly sourceGeneration: string; readonly requestedRecords: readonly { readonly recordId: string; readonly digest: string; readonly payload: ArchiveArtifactRef; readonly attachments: readonly ArchiveArtifactRef[]; }[]; readonly purpose: 'context-recall' | 'projection-verification'; readonly maxBytes: number; readonly remainingTtlMs: number; readonly chunkBytes: number; } interface MaterialUploadChunk { readonly protocol: 'sdk2-ext-v1'; readonly bindingId: string; readonly materialRequestId: string; readonly target: ArchiveTarget; readonly sourceId: string; readonly sourceGeneration: string; readonly artifactId: string; readonly offset: number; readonly bytes: number; readonly chunkSha256: string; readonly base64: string; } interface MaterialUploadStatus { readonly protocol: 'sdk2-ext-v1'; readonly bindingId: string; readonly materialRequestId: string; readonly uploadId: string; readonly artifact: ArchiveArtifactRef; readonly state: 'receiving' | 'committed'; readonly chunkBytes: number; readonly receivedOffsets: readonly number[]; readonly receivedBytes: number; readonly remainingTtlMs: number; } interface MaterialOperationIdentity { readonly requestId: string; readonly operationEpoch: string; } interface MaterialResponse { readonly protocol: 'sdk2-ext-v1'; readonly bindingId: string; readonly materialRequestId: string; readonly request: MaterialOperationIdentity; readonly target: ArchiveTarget; readonly sourceId: string; readonly sourceGeneration: string; readonly results: readonly { readonly recordId: string; readonly digest: string; readonly payload: { readonly uploadId: string; }; readonly attachments: readonly { readonly uploadId: string; }[]; }[]; } type MaterialRejection = 'source_unavailable' | 'stale_generation' | 'invalid_coverage' | 'request_expired' | 'material_rejected' | 'forbidden' | 'binding_closed'; interface MaterialReceipt { readonly protocol: 'sdk2-ext-v1'; readonly bindingId: string; readonly materialRequestId: string; readonly state: 'pending' | 'received' | 'verified' | 'core-consumed' | 'rejected'; readonly revision: string; readonly acceptedRecordIds: readonly string[]; readonly reason?: MaterialRejection; } interface MaterialIssue { /** 可信宿主在调用前固定；结果未知只能沿原ID重试。 */ readonly materialRequestId: string; readonly recordIds: readonly string[]; readonly purpose: 'context-recall' | 'projection-verification'; readonly lifetimeMs?: number; readonly maxBytes?: number; readonly chunkBytes?: number; } type QueryInputRejectCode = 'invalid_input' | 'turn_mismatch' | 'input_conflict' | 'injection_limit' | 'turn_closed'; type QueryInputReason = TerminalReason | 'input_cancelled' | 'iterator_closed'; interface QueryInputReceipt { readonly inputId: string; readonly turnId: string; readonly ordinal: number; readonly revision: number; readonly source: 'legacy' | 'strict'; /** consumed 仅证明已加入历史，不证明模型收到/回答或历史已经耐久写入。 */ readonly state: 'reserved' | 'accepted' | 'consumed' | 'closed' | 'cancelled'; readonly reason?: QueryInputReason; } /** 会话级输入的目标绑定:历史纪元 + 当前轮句柄,二者皆须与宿主现状一致。 */ interface SessionInputTarget { readonly historyEpoch: string; readonly turnId: string; } /** 会话级输入内容:纯文本,或仅含 text 块的块数组(图片等不受理)。 */ type SessionInputContent = { readonly text: string; } | { readonly blocks: readonly { readonly t: 'text'; readonly text: string; }[]; }; /** 一次会话级输入提交:幂等 inputId、目标绑定、内容与期望的确认级别。 */ interface SessionInputSubmission { readonly inputId: string; readonly target: SessionInputTarget; readonly content: SessionInputContent; readonly ack?: 'memory' | 'durable'; } /** 会话级输入凭据:在查询输入凭据之上附会话 id、历史纪元与耐久性级别(仅 memory)。 */ interface SessionInputReceipt extends QueryInputReceipt { readonly sessionId: string; readonly historyEpoch: string; readonly durability: 'memory'; } /** 会话级输入的拒绝码:查询层拒绝码之外增纪元不符、不支持的确认级别 / 内容 / 输入形态。 */ type SessionInputRejectCode = QueryInputRejectCode | 'epoch_mismatch' | 'durable_unsupported' | 'content_unsupported' | 'input_unsupported'; /** 会话级输入提交的结果:accepted 携凭据;closed / rejected 携拒绝码。 */ type SessionInputResult = { readonly outcome: 'accepted'; readonly receipt: SessionInputReceipt; } | { readonly outcome: 'closed' | 'rejected'; readonly code: SessionInputRejectCode; }; /** 会话级输入能力声明:宿主据此得知受理的内容形态、确认级别、凭据保留窗口与当前目标。 */ interface SessionInputCapabilities { readonly version: 1; readonly text: boolean; readonly textBlocks: boolean; readonly image: false; readonly memoryAck: boolean; readonly durableAck: false; readonly receiptRetention: 'current-and-last-turn'; readonly target: SessionInputTarget | null; } interface ArchiveJournalPage { readonly protocol: 'sdk2-ext-v1'; readonly bindingId: string; readonly generations: ArchiveGenerations; readonly records: readonly ArchiveRecord[]; readonly nextAfterSequence: string | null; readonly complete: boolean; readonly publishedThroughSequence: string | null; } /** 显式宿主登记的来源；原URL仅为查表键，内核不下载URL、不访问文件。 */ interface ArchiveTrustedAttachmentRequest { readonly attachmentSourceId: string; readonly sourceId: string; readonly sourceGeneration: string; readonly target: ArchiveTarget; readonly runKey: string; readonly turnId: string; readonly bodySha256: string; readonly messageIndex: number; readonly blockIndex: number; readonly imageIndex: number; readonly reference: string; } interface ArchiveTrustedAttachmentDescription { readonly mediaType: string; readonly bytes: number; readonly sha256: string; } interface ArchiveTrustedAttachmentSource { readonly sourceId: string; /** 显式新租约才启用音视频；旧租约始终按其持久策略读取。 */ readonly media?: true; readonly signal?: AbortSignal; /** 从可信注册表取得读取前已经固定的见证；不存在/未授权必须返回undefined或拒绝。 */ describe(input: ArchiveTrustedAttachmentRequest): ArchiveTrustedAttachmentDescription | undefined; /** 只读取上述见证指认的对象；遵循signal与maxBytes，不能把任意引用当网络/文件权限。 */ read(input: ArchiveTrustedAttachmentRequest & ArchiveTrustedAttachmentDescription & { readonly maxBytes: number; }, signal?: AbortSignal): Promise; } /** 严格镜像 sdk2-ext-v1.schema.json 的原 21 字段；事件帧帽不在此类型。 */ interface ArchiveInstallationLimits { readonly controlBytes: number; readonly recordBytes: number; readonly pageRecords: number; readonly pageBytes: number; readonly attachmentBytes: number; readonly chunkBytes: number; readonly materialConcurrent: number; readonly materialQueue: number; readonly materialCandidates: number; readonly materialBytes: number; readonly materialDeadlineMs: number; readonly pendingRecords: number; readonly pendingBytes: number; readonly inflightReserveBytes: number; readonly offlineMs: number; readonly eventRetentionMs: number; readonly eventRetentionFrames: number; readonly eventRetentionBytes: number; readonly terminalReceiptRetentionMs: number; readonly epochLifetimeMs: number; readonly materialChunkBytes: number; } interface ArchiveInstallationBindingView { readonly protocol: 'sdk2-ext-v1'; readonly bindingId: string; readonly scope: ArchiveBindingScope; readonly target: ArchiveTarget; readonly revision: string; readonly state: 'active' | 'backpressured' | 'closing' | 'closed'; readonly sourceId: string; readonly acceptedCapabilities: readonly ArchiveBindingCapability[]; readonly rejectedCapabilities: readonly { readonly capability: ArchiveBindingCapability; readonly reason: 'unsupported_capability' | 'not_authorized'; }[]; readonly availability: 'legacy-complete'; readonly operationEpoch: { readonly id: string; readonly issuedAt: string; readonly expiresAt: string; readonly state: 'active'; } | null; readonly limits: ArchiveInstallationLimits; readonly archiveAckFormat: 'split-receipts-v1' | null; } /** 原 sdk2-ext-v1 材料合同；嵌入宿主与远端宿主共用其含义。 */ type ArchiveMaterialIssue = MaterialIssue; /** 限定会话、来源和记录范围的上下文材料请求。 */ type ArchiveMaterialRequest = MaterialRequest; /** 对当前材料请求上传的有界对象分块。 */ type ArchiveMaterialUploadChunk = MaterialUploadChunk; /** 材料对象的上传进度与完整性状态。 */ type ArchiveMaterialUploadStatus = MaterialUploadStatus; /** 终端向当前请求提交的材料及完整性引用。 */ type ArchiveMaterialResponse = MaterialResponse; /** 材料送达及核心消费的分别确认结果。 */ type ArchiveMaterialReceipt = MaterialReceipt; /** 可信宿主登记并供给外置附件字节；缺省不读取路径或 URL。 */ type ArchiveAttachmentSource = ArchiveTrustedAttachmentSource; /** 原归档元数据页、固定来源对象引用及公开绑定视图。 */ type ArchiveRecordPage = ArchiveJournalPage; /** 归档中固定来源、媒体类型、字节数和摘要的对象引用。 */ type ArchiveArtifact = ArchiveArtifactRef; /** 当前用户获准读取的归档绑定与操作代际。 */ type ArchiveBindingView = ArchiveInstallationBindingView; /** Same-turn insertion contract; implementation is the original AgentSession delivery path. */ type ArchiveInputCapabilities = SessionInputCapabilities; /** 当前会话允许插入输入的目标范围。 */ type ArchiveInputTarget = SessionInputTarget; /** 交给当前运行轮处理的一次输入。 */ type ArchiveInputSubmission = SessionInputSubmission; /** 当前输入在内存屏障中的状态。 */ type ArchiveInputReceipt = SessionInputReceipt; /** 当前输入处理完成后的结果。 */ type ArchiveInputResult = SessionInputResult; /** 归档容量上限；字节数和记录数分别计量。 */ interface ArchiveHostQuota { readonly bytes: number; readonly records: number; } /** 归档交接、材料读取与事件留存的有限上限，单位由字段名标明。 */ interface ArchiveHostLimits { readonly controlBytes: number; readonly recordBytes: number; readonly pageRecords: number; readonly pageBytes: number; readonly attachmentBytes: number; readonly chunkBytes: number; readonly materialConcurrent: number; readonly materialQueue: number; readonly materialCandidates: number; readonly materialBytes: number; readonly materialDeadlineMs: number; readonly pendingRecords: number; readonly pendingBytes: number; readonly inflightReserveBytes: number; readonly offlineMs: number; readonly eventRetentionMs: number; readonly eventRetentionFrames: number; readonly eventRetentionBytes: number; readonly terminalReceiptRetentionMs: number; readonly epochLifetimeMs: number; readonly materialChunkBytes: number; } /** 待完成工作的授权请求；仅描述工作身份，本对象不授予权限。 */ interface ArchiveCompletionAuthorization { readonly operation: 'finish-run' | 'finish-rewrite'; readonly scope: { readonly applicationScopeId: string; readonly endUserId: string; readonly authorizationRevision: string; }; readonly sessionId: string; readonly originalOwnerEpoch: string; readonly workId: string; } /** 当前应用内的终端用户与会话标识。 */ interface NodeArchiveSubject { readonly endUserId: string; readonly sessionId: string; } /** 已确认有效历史的有界引用；不含正文，不授予执行/访问权限，不证明模型缓存命中。 */ interface ArchiveEffectiveContextReference { readonly format: 'sdk2-effective-context-v1'; readonly referenceDigest: string; /** 当前读取授权的修订；不是完整模型策略见证。 */ readonly scope: { readonly applicationScopeId: string; readonly endUserId: string; readonly authorizationRevision: string; }; readonly bindingId: string; readonly sourceId: string; readonly sourceGeneration: string; readonly target: { readonly sessionId: string; readonly sourceSnapshotDigest: string; readonly generations: { readonly historyEpoch: string; readonly deletionGeneration: string; readonly projectionRevision: string; }; }; readonly storeCommitId: string; readonly completion: { readonly kind: 'installation' | 'run' | 'rewrite'; readonly eventDigest: string; readonly workId: string | null; }; } /** * 当前归档宿主真实启用的存储策略视图。 * * 这是只读能力声明，不是跨设备同步或多副本耐久证明。SDK2-03 尚未 * 启用共享来源、同步副本或离线删除传播；调用方应据此明确把这些能力 * 视为未配置，而不能从 `source-ack-with-durable-spool` 推导出来。 */ interface ArchiveStorageStrategyView { readonly format: 'sdk2-storage-strategy-v1'; readonly strategy: 'single-authorized-source'; readonly sourceId: string; readonly sourceGeneration: string; readonly durability: 'source-ack-with-durable-spool'; readonly delivery: 'required'; readonly sessionAvailability: 'legacy-complete'; readonly replication: 'none'; readonly synchronization: 'none'; } /** 宿主在执行操作前向应用请求的权限种类。 */ type NodeArchiveOperation = 'open' | 'resume' | 'read' | 'run' | 'transfer' | 'materials' | 'close-overlay' | 'dispose'; /** 本地归档宿主配置；Store 必须来自同一 SDK 实例的文件 Store 工厂且未配置冷层。 */ interface NodeArchiveHostOptions { readonly store: SessionStore; readonly applicationScopeId: string; readonly archive: { readonly directory: string; readonly mode: 'create' | 'reopen'; readonly hostId: string; /** host/application/endUser 为聚合上限；capture/source 为每个会话两座物理库的固定额度。 */ readonly quota: { readonly host: ArchiveHostQuota; readonly application: ArchiveHostQuota; readonly endUser: ArchiveHostQuota; readonly capture: ArchiveHostQuota; readonly source: ArchiveHostQuota; }; readonly maxSessions: number; readonly commandBytes: number; readonly commandDatabasePages: number; readonly spoolDatabasePages: number; readonly limits: ArchiveHostLimits; /** 显式启用原上下文材料链；缺省不增加材料配额篮或材料读写。 */ readonly contextMaterials?: boolean; }; /** 同步核实当前用户权限并返回当前授权修订；拒绝时抛错，不接受异步回调。 */ readonly authorize: (input: { readonly subject: NodeArchiveSubject; readonly operation: NodeArchiveOperation; }) => { readonly authorizationRevision: string; }; /** 独立批准完成已受理的工作；普通读取或恢复授权不会隐式授予此权限。 */ readonly authorizeCompletion?: (input: ArchiveCompletionAuthorization) => void; /** 独立批准原创建续办；在介质读取前同步执行，不由普通恢复权限推导。 */ readonly authorizeContinuation?: (input: { readonly scope: ArchiveCompletionAuthorization['scope']; readonly sessionId: string; }) => void; /** 每会话显式登记可信外置来源；同步选择源，读取仍沿原捕获预算与取消链。 */ readonly trustedAttachmentSourceFor?: (subject: NodeArchiveSubject) => ArchiveAttachmentSource | undefined; } /** 新建会话的选项；持久化 Store 和会话 ID 统一由宿主管理。 */ type NodeArchiveFreshSessionOptions = Omit; /** 恢复会话的选项；从原 Store 读取历史，不额外注入初始历史。 */ type NodeArchiveResumeSessionOptions = Omit; /** 新建或恢复原会话；恢复未完成工作须显式选择 finishPending 并提供独立完成授权。 */ type NodeArchiveOpenRequest = { readonly mode: 'fresh'; readonly subject: NodeArchiveSubject; readonly session: NodeArchiveFreshSessionOptions; } | { readonly mode: 'resume'; readonly subject: NodeArchiveSubject; readonly session: NodeArchiveResumeSessionOptions; readonly finishPending?: boolean; readonly continuePrepared?: boolean; }; /** 归档宿主返回原 AgentSession；归档交接与会话执行使用同一会话和持久化实现。 */ interface NodeArchiveHost { /** 完成归档安装或恢复后返回原会话；构造宿主本身不会创建数据库。 */ open(input: NodeArchiveOpenRequest): Promise; /** 仅空闲已安装会话；重读原Store并核原完成事实，未决时拒绝而不补写或重放。 */ readEffectiveContext(subject: NodeArchiveSubject): Promise; /** 等待持久交接和 ACK；pending 为 true 时还有后续有界批次需要等待。 */ flushArchive(subject: NodeArchiveSubject): Promise<{ readonly pending: boolean; readonly batches: number; }>; /** 当前授权下的公开绑定视图，含原操作代际；不暴露内部所有者或控制事实。 */ readArchiveBinding(subject: NodeArchiveSubject): ArchiveBindingView; /** * 读取当前绑定实际启用的存储策略；`replication`/`synchronization` 为 * `none` 时，不能把本地来源视为已具备多设备共享或备份能力。 */ readArchiveStorageStrategy(subject: NodeArchiveSubject): ArchiveStorageStrategyView; /** 只读取原来源的有界元数据页；不检索全史、不访问任意路径。 */ readArchiveRecords(subject: NodeArchiveSubject, input: { readonly afterSequence: string | null; readonly limit: number; readonly maxBytes: number; }): ArchiveRecordPage; /** 只读取已登记引用的完整字节并复核原 SHA/MIME/长度；单对象沿原 32MiB 帽。 */ readArchiveArtifact(subject: NodeArchiveSubject, artifact: ArchiveArtifact): Uint8Array; /** 查询原会话同轮接纳能力；不创建新轮、不刷新系统提示词。 */ inputCapabilities(subject: NodeArchiveSubject): ArchiveInputCapabilities; /** 读取当前原轮目标；返回 null 表示没有可插入的运行轮。 */ getInputTarget(subject: NodeArchiveSubject): ArchiveInputTarget | null; /** 将输入交给原会话注入屏障；不回落为 cancel+send。 */ submitInput(subject: NodeArchiveSubject, input: ArchiveInputSubmission): Promise; /** 查询原 inputId/target 的内存状态；不把它升级为持久状态。 */ getInputStatus(subject: NodeArchiveSubject, inputId: string, target: ArchiveInputTarget): ArchiveInputReceipt | null; /** 请求已由核心捕获的记录；不改变当前历史或授予工具执行权限。 */ requestMaterials(subject: NodeArchiveSubject, input: ArchiveMaterialIssue): ArchiveMaterialRequest; /** 复用原有界分块上传；只接收当前可信请求承诺的字节。 */ uploadMaterialChunk(subject: NodeArchiveSubject, input: ArchiveMaterialUploadChunk): ArchiveMaterialUploadStatus; materialUploadStatus(subject: NodeArchiveSubject, input: { readonly materialRequestId: string; readonly artifactId: string; }): ArchiveMaterialUploadStatus; /** 材料送达与核心消费分别记账，未知响应沿同一请求身份重试。 */ respondMaterials(subject: NodeArchiveSubject, input: ArchiveMaterialResponse): ArchiveMaterialReceipt; materialStatus(subject: NodeArchiveSubject, materialRequestId: string): ArchiveMaterialReceipt; /** 已收到材料在原查询屏障交给同一个 ContextManager 准入。 */ enqueueMaterials(subject: NodeArchiveSubject, input: { readonly materialRequestId: string; readonly leaseId: string; readonly required?: true; }): void; /** 可信宿主显式取消未持有的等待；确认原拒绝/释放后移队列，未排队返回 null。 */ cancelMaterials(subject: NodeArchiveSubject, input: { readonly materialRequestId: string; }): { readonly receipt: ArchiveMaterialReceipt; readonly releasedBytes: number; } | null; /** 交接完成后关闭归档叠加能力；同一会话仍可运行并写入原 Store，不退还固定额度。 */ closeOverlay(subject: NodeArchiveSubject): Promise; /** 关闭宿主介质；调用前须关闭并排空全部已返回会话，不隐式完成归档关闭或退额。 */ dispose(): Promise; } /** 归档宿主错误；code 表示当前无法完成的操作边界。 */ declare class NodeArchiveHostError extends Error { readonly code: 'invalid_input' | 'unsupported_capability' | 'identity_mismatch' | 'reentrant' | 'reconciliation_required' | 'pending_work' | 'prepared_orphan' | 'dependency_held' | 'capacity_exceeded' | 'closed'; constructor(code: 'invalid_input' | 'unsupported_capability' | 'identity_mismatch' | 'reentrant' | 'reconciliation_required' | 'pending_work' | 'prepared_orphan' | 'dependency_held' | 'capacity_exceeded' | 'closed'); } declare const cacheContinuityAuthority: unique symbol; /** 受信 Node 宿主能力；普通终端不能自行构造，不含发行者私钥。 */ interface NodeCacheContinuityAuthority { readonly [cacheContinuityAuthority]: true; } /** 正式受信后端的短期凭据桥；不能为任意 Electron 本地历史提供盲签服务。 */ interface NodeCacheContinuityBridge { readonly issuerId: string; readonly sourceNamespace: string; readonly runtimePolicy?: 'preserve' | 'renew-on-restore'; /** 必须由持有此原 Store 来源权威的后端签发；字节已耐久，凭据过期只刷新同一意图。 */ readonly credential: (input: { readonly sessionId: string; readonly intentBytes: Uint8Array; readonly signal?: AbortSignal; readonly assertCurrent: () => void; }) => Promise; } /** 显式缓存宿主；本地加密 key 仅保护缓存介质，不是平台发行者签名密钥。 */ interface NodeCacheHostOptions { /** 此显式扩展要求原 createFileSessionStore 的队列/锁和删除保护；普通 SDK 五方法自建 Store 仍沿 createSession 使用。 */ readonly store: SessionStore; readonly applicationScopeId: string; readonly endUserId: string; readonly baseUrl: string; readonly cache: { readonly directory: string; readonly mode: 'create' | 'recover'; readonly storeId: string; readonly key: { readonly id: string; readonly bytes: Uint8Array; }; readonly maxRuntimes?: number; }; /** 每次操作同步核当前权限；抛错拒绝，授权变化使正在等待的见证失效。 */ readonly authorize: (input: { readonly sessionId: string; readonly operation: 'open' | 'resume' | 'cold-new' | 'run' | 'delete'; }) => { readonly authorizationRevision: string; }; /** 仅受信宿主；正式终端跨运行仍须对接受信后端，不能内嵌 issuer key。 */ readonly continuity?: NodeCacheContinuityAuthority | NodeCacheContinuityBridge; } /** 缓存开启只适用于原令牌档；原工具、权限、计费和模型配置保持。 */ type NodeCacheSessionOptions = Omit; /** 新建或恢复原缓存会话；恢复路径沿原 Store 与平台控制意图继续。 */ interface NodeCacheOpenRequest { readonly mode: 'fresh' | 'resume'; readonly sessionId: string; readonly session: NodeCacheSessionOptions; /** 410 是归档终态；只有显式冷新建授权才建立独立新关系，绝不重发旧 unknown。 */ readonly archived?: 'reject' | 'cold-new'; } /** 冷删除或原未决删除续办；只提供当前 app_user 平台认证，不创建模型会话。 */ interface NodeCacheDeleteRequest { readonly sessionId: string; readonly authorization: Required> & Pick; } /** 同一应用/用户的冷维护查询；不创建模型会话或迁移未知请求。 */ interface NodeCacheLookupRequest extends NodeCacheDeleteRequest { readonly requestId: string; readonly signal?: AbortSignal; } /** 原请求受理状态及尚被保留的响应；查询本身不清除未决请求或授权再次执行。 */ interface NodeCacheLookupResult { readonly protocol: 'sdk2-cache-core-v1'; readonly state: 'not-found' | 'accepted' | 'result-unknown' | 'completed' | 'receipt-expired'; readonly result: { readonly status: number; readonly contentType: string; readonly body: string; readonly headers?: { readonly cost?: string; readonly balance?: string; readonly priceTable?: string; }; } | null; } /** * 受信缓存宿主的只读连续性观察。 * * `logicalGroup.id` 只在同一宿主缓存密钥域内稳定，用于跨 runtime 对齐逻辑会话； * 它不是供应商 cache key，也不授予读取历史、执行工具或恢复旧租约的权限。 * provider 三项证据在当前 SDK2 cache-host 合同中没有上游实报，必须保持 unknown。 */ interface NodeCacheContinuityView { readonly format: 'sdk2-cache-continuity-view-v1'; readonly sessionId: string; readonly state: 'absent' | 'ready' | 'pending' | 'deleting' | 'deleted'; readonly continuity: 'disabled' | 'unknown' | 'enrolled' | 'deleted'; readonly logicalGroup: { readonly id: string; readonly lineageCount: number; /** 当前宿主内的逻辑血缘代数；不等同供应商 groupGeneration。 */ readonly lineageGeneration: number; } | null; /** 最近接纳的本地网关投影，仅含版本/状态/原因；未加载、非 ready 或控制未决为 null，不代表实时上游状态。 */ readonly projection?: { readonly revision: string; readonly status: 'current' | 'rebuild-required' | 'missing'; readonly reason: 'unchanged' | 'policy-changed' | 'generation-changed' | 'provider-changed' | 'source-missing' | 'legacy-missing' | 'key-rotated'; } | null; readonly provider: { readonly hit: 'unknown'; readonly usage: 'unknown'; readonly billing: 'unknown'; readonly basis: 'provider-evidence-unavailable'; }; } /** 受信 Node 缓存宿主；显式管理原 Store、加密介质与 continuity 生命周期。 */ interface NodeCacheHost { /** 在原历史确认、原控制意图与 Store 运行号对账后交付同一 AgentSession。 */ open(input: NodeCacheOpenRequest): Promise; /** * 读取当前宿主掌握的逻辑缓存连续性状态；纯本地、无出网、不会读取正文。 * provider 命中、usage 和 billing 没有上游实报时恒为 unknown。 */ readCacheContinuity(sessionId: string): NodeCacheContinuityView; /** 查原Core受理/已存响应；包括completed在内均不清pending，也不把原结果作为新用户轮执行。 */ lookup(input: NodeCacheLookupRequest): Promise; /** 所有宿主会话已 close/drain 后，经原 Store 排他锁确认远端墓碑再删史；未知保留原键供重试。 */ delete(input: NodeCacheDeleteRequest): Promise; /** 仅全部会话已关闭并实际排空后关闭本地介质，保留未决请求与永久身份。 */ dispose(): Promise; } /** 构造不打开介质/不出网；首次显式 open/delete 才打开私有缓存目录。 */ declare function createNodeCacheHost(options: NodeCacheHostOptions): NodeCacheHost; /** 创建显式本地归档宿主；首次 open 才初始化持久介质，会话继续使用 SDK 原执行循环。 */ declare function createNodeArchiveHost(options: NodeArchiveHostOptions): NodeArchiveHost; export { NodeArchiveHostError, createNodeArchiveHost, createNodeCacheHost }; export type { ArchiveArtifact, ArchiveAttachmentSource, ArchiveBindingView, ArchiveCompletionAuthorization, ArchiveEffectiveContextReference, ArchiveHostLimits, ArchiveHostQuota, ArchiveInputCapabilities, ArchiveInputReceipt, ArchiveInputResult, ArchiveInputSubmission, ArchiveInputTarget, ArchiveMaterialIssue, ArchiveMaterialReceipt, ArchiveMaterialRequest, ArchiveMaterialResponse, ArchiveMaterialUploadChunk, ArchiveMaterialUploadStatus, ArchiveRecordPage, ArchiveStorageStrategyView, NodeArchiveFreshSessionOptions, NodeArchiveHost, NodeArchiveHostOptions, NodeArchiveOpenRequest, NodeArchiveOperation, NodeArchiveResumeSessionOptions, NodeArchiveSubject, NodeCacheContinuityAuthority, NodeCacheContinuityBridge, NodeCacheContinuityView, NodeCacheDeleteRequest, NodeCacheHost, NodeCacheHostOptions, NodeCacheLookupRequest, NodeCacheLookupResult, NodeCacheOpenRequest, NodeCacheSessionOptions };