@sema-agent/sdk 9.8.1 → 9.10.0

package/dist/types.d.ts

@@ -674,6 +674,24 @@ export interface TaskRequest {
      *  narrows honestly. Tighten-only: core's inheritance invariant unions it into EVERY child spawn path.
      *  Malformed (non-array / empty-string items) → 400 fail-loud at submit. */
     excludeTools?: string[];
+    /** server ≥7.90.0 (core 7.8.0 design/388 的**请求面**;契约 G.9b / 判据 G-40): **整只工具面卸载** ——
+     *  这一 run 里调用方工具、脚手架、手(Bash/Edit/Write…)、MCP、A2A、skills 一个都不挂,模型没有任何
+     *  工具可调,终局必然是**纯文本**。wire 上看得见的样子:`wiring_manifest.tools` 的 `count === 0` 且
+     *  `entries` 为空(披露**一次**,一条 leg 一帧),整条流上零 `tool_start` / `tool_end` / `tool_disclosure`。
+     *
+     *  🔴 **与 {@link excludeTools} 是两种语义,刻意不折叠**:`"*"` 是一个**合法的调用方工具名**,所以
+     *  「卸全部」不能写成 `excludeTools:["*"]`(那会把「卸全部」与「卸一只叫 `*` 的工具」塌成一件事)。
+     *  两键**同带各自生效**,不冲突、不拒(全卸之后名单里那几只本来也不在)。
+     *  🔴 **类型只收字面 `true`**:server 只把 literal `true` 写上 `TaskSpec` —— 挂一个 `false` 上去等于
+     *  替引擎重申一次它自己的缺省,而那个缺省的属主是引擎。要动态开关就写
+     *  `...(off ? { excludeAllTools: true } : {})`,别送 `false`。
+     *  🔴 **探测靠键闭集,没有能力位**:没接线的 server(≤7.89.x)把它当**未知顶层键**,400
+     *  `request.body_shape` 并在 `unknownKeys` 里逐字列名 ⇒ trial-by-400 就是探测路(一个键一条探测路,
+     *  刻意不长第二条)。坏形(非 boolean)在同步提交腿是 400 `request.field_invalid`;**耐久 resume 腿
+     *  不拒**(重放存量 body,4xx 会砖死已 park 的任务)⇒ 在那条腿上降级为「键缺席」。
+     *  ⚠️ **辖域**:A2A 入站面(`message/send`)**不承载本键** —— 那条腿的提交体是服务端从协议消息重建的
+     *  闭四字段,消息里放这个键**无效且不报错**,名册照旧。A2A peer 要零工具面就走 skill 路由。 */
+    excludeAllTools?: true;
     /** server ≥1.221 (core 1.314): DEFERRED DISCLOSURE list — the named MOUNTED tools (built-ins included)
      *  ride the wire as a placeholder (schema bytes out of the cache prefix) and materialize via ToolSearch
      *  on demand. The carrier for the shell's "Workflow on by default but not exposed" posture. Same
@@ -3886,6 +3904,9 @@ export interface SessionSummary {
      *  真实带这个字段——会话自动摘要(session-titler.ts,首次提交后台起一次廉价模型调用生成,IS NULL 门控幂等,
      *  SESSION_AUTO_TITLE 默认开)。null = 未生成(自动摘要关闭 / 该 session 首次提交后台任务还没跑完)。 */
     title: string | null;
+    /** server ≥7.91.0(additive,老 server 缺席):会话活动词,由最近 run 的状态经 server 与 peer 目录**同一张**映射表派生
+     *  (running → `active`;suspended / needs_review → `blocked`;无非终态 run → `idle`)。壳的会话列表 / peer 行 tempo 同源。 */
+    tempo?: "active" | "idle" | "blocked";
     [k: string]: unknown;
 }
 /** `GET /v1/sessions` 的分页信封（service handleSessionList,keyset）。`nextCursor` 缺 = 末页。 */
@@ -4898,6 +4919,342 @@ export interface MemoryCaptureOptOutResult {
     sessionId: string;
     outcome: "created" | "existed";
 }
+/** core 的 `transfers.jsonl` 托管事件行 —— **OPEN 判别形**:三个基键是契约,其余是变体载荷。
+ *  🔴 **消费义务**:容忍未知 `channel`(报告 / 跳过 / 原样显示),**绝不**写一个会抛的穷举 `switch` ——
+ *  通道词表由写这条链的那个二进制定,一条由更新的引擎写下的链照样要在这里读得出来。 */
+export interface MemoryTransferEvidence {
+    /** 事件唯一 id(证据链的追加幂等键)。 */
+    ev: string;
+    /** 事件种类 —— **故意开集**(见顶注的消费义务)。 */
+    channel: string;
+    /** 事件时刻(ms epoch)。 */
+    at: number;
+    [k: string]: unknown;
+}
+/** 已提交账的**绑定半场**(core `CommittedBinding` 的 tagged 形)。`"unbound"` 是一个**合法的过渡态**
+ *  (v1→v2 迁移行推导不出投影坐标),不是一次拒绝。 */
+export type MemoryCommittedBinding = {
+    state: "bound";
+    scope: string;
+    slug: string;
+    at?: number;
+    prev?: {
+        scope: string;
+        slug: string;
+        at: number;
+    };
+} | {
+    state: "unbound";
+};
+/**
+ * 一条 entry 的绑定状态,**四形不折叠**(契约 §9.2)。
+ * 🔴 `{state:"unknown"}`(这个后端没有审计快照面 ⇒ **判不了**)**绝不**折叠成 `{state:"absent"}`
+ * (**确实不存在**):两句话的合规结论相反。
+ */
+export type MemoryProvenanceBinding = MemoryCommittedBinding | {
+    state: "absent";
+} | {
+    state: "unknown";
+    reason: "audit-snapshot-capability-absent";
+};
+/**
+ * `GET /v1/memory/entries/{entryId}/provenance` 的 200 体 —— core `EntryProvenanceAccount` **本身**
+ * (server 不包一层、不投影、不补键;契约 §9.2)。
+ *
+ * 🔴 **`binding` 与 `custody` 是判别式,消费方必须按判别位分支**;`contentState` 与 `custody.state` 同族
+ * 三值(`capability-absent` = 面缺席、`unavailable`/`damaged` = 面在但答不全),core 从不自造事件行。
+ * 🔴 `v` 是版本信封:读到 `v > 1` 必须**拒绝**,绝不重新解释 —— 本型只描述 `v: 1` 这一代的字段律,
+ * 所以判别位写在运行时(读 `v` 再用),不是靠类型帮你挡住。
+ * 失败面:控制面账本损坏 ⇒ 500 `internal.memory_control_plane_corrupt`(fail-closed:完整性未知时 core
+ * 宁可不答,也不在说不清的账上拼一个答案),core 的诊断文案原样透传。
+ */
+export interface EntryProvenanceAccount {
+    v: 1;
+    id: string;
+    binding: MemoryProvenanceBinding;
+    /** 已提交 lineage 的 by-entry 投影,每行与它那条会话的污染记录 join。**未结算的 lineage 行不是贡献**
+     *  —— 它们以 `exclusion.code: "lineage_pending"` 露面。 */
+    contributors: Array<{
+        sessionId: string;
+        lastRev: string;
+        lastAt?: number;
+        polluted?: {
+            at: number;
+            reason: string;
+        };
+    }>;
+    /** 模型可见读面对这条 id 的**扣留**状态(有才在场)。 */
+    exclusion?: {
+        code: "challenged" | "lineage_pending";
+        generation?: number;
+        at?: number;
+    };
+    /** 内容半场,与 {@link binding} **按构造联动**:`absent` ⇔ binding `absent`;`capability-absent` ⇔
+     *  binding `unknown`;有行时是 `present`(只有它在场 {@link ingest} 才骑得上)或 `unavailable`。 */
+    contentState: "present" | "unavailable" | "capability-absent" | "absent";
+    /** 已提交内容的 frontmatter 携带的 repo 文件 ingest 出处(含洗不掉的 `trust` 标)。 */
+    ingest?: {
+        kind: "repo_file";
+        path: string;
+        contentHash: string;
+        ingestedAt: number;
+        trust?: "untrusted";
+    };
+    /** 按 id 的证据链读数。`damaged` = 链的完整性被弹劾、但仍有一份说得通的读法(断尾 / 证据缺失 /
+     *  ev 身份矛盾,`reason` 在已知时带出);`capability-absent` = 这个后端没有托管面(事件必为空数组 ——
+     *  core 从不伪造)。 */
+    custody: {
+        state: "complete" | "damaged" | "capability-absent";
+        events: MemoryTransferEvidence[];
+        reason?: string;
+    };
+    [k: string]: unknown;
+}
+/**
+ * `POST /v1/memory/erase` 的请求体(契约 §9.3)。
+ *
+ * 🔴 **`requestId` 是这次抹除的幂等身份,server 与引擎都从不替你铸一个** —— 重试**必须**带**同一个**
+ * id(一个丢失的 ack 不得开出第二次真删)。缺席 / 空串 ⇒ 400 `request.request_id_required`(与
+ * `request.body_shape` 刻意分家:两句话的运维动作不同)。
+ * ⚠️ 与 {@link MemoryOriginClearRequest.requestId} **同名不同义**,别把两边的重试纪律互相套用。
+ */
+export interface MemoryErasureRequest {
+    requestId: string;
+    /**
+     * 选择子 —— 文档化的三形是 `{ids: string[]}` / `{scope: string}` / `{sessionId: string}`,**恰好一个**。
+     *
+     * 🔴 类型故意写成开放 record 而**不是**三形联合:这条规则的**单一属主是 core**
+     * (`erasureRequestInvalid`),server 自己也只验顶层结构(zod 的 `z.record(z.string(), z.unknown())`)。
+     * 在 SDK 里再写一遍字段表就是第二真源 —— 而且 TS 的联合表达不出「恰好一个」,却能把 core 将来长出的
+     * 第四形提前拒掉。`{ids:[…], scope:…}` 这种**形对义错**的请求拿到的是 400 `config.memory_erasure_request`。
+     */
+    select: Record<string, unknown>;
+    /**
+     * **证据面缺席时的降级授权**,一次**人的**签字。
+     * 🔴 缺席时 SDK **不会替你补一个 `false`**(server 侧同律:递交给引擎的就是调用方发的那个体)——
+     * 中间层替调用方勾上就是替他签字。
+     */
+    allowUnevidenced?: boolean;
+}
+/** 一条被抹除行的坐标(core `ErasedBinding`:快照的 tagged 绑定律,不带账本 trace 的额外键)。 */
+export type MemoryErasedBinding = {
+    state: "bound";
+    scope: string;
+    slug: string;
+} | {
+    state: "unbound";
+};
+/**
+ * `POST /v1/memory/erase` 的 200 体 —— core `MemoryErasureAttestation` **本身**(契约 §9.3)。
+ *
+ * 🔴 **幂等有两条腿,契约不同 —— 先读 {@link evidenceCapability} 再决定能不能重试**:
+ *  · `"journal"`(**证据腿**):`requestId` 是幂等身份,重发同一个 id 会**读回**托管链上那条 anchor
+ *    pinned 的 id 集、绝不重新解析;换了选择子还用同一个 id ⇒ 409 `memory.erasure_selector_mismatch`;
+ *  · `"none"`(**降级腿**):core 的原话逐字是 *"same requestId = a NEW request (re-resolved — replay
+ *    convergence is not promised)"* —— **重发就是第二次真删**。这条腿上 {@link erasedPreviously} 与
+ *    `erased[].evidenceEv` 永不出现,每一行 {@link notFound} 都带 `historyUnknown`(「从没存在过」与
+ *    「无证据地被删过」不可判别)。
+ * 🔴 **不要给这一口配自动重试策略**:`"none"` 时任何重发都必须是人做的决定。
+ */
+export interface MemoryErasureAttestation {
+    /** 版本信封 —— 读到 `v > 1` 必须拒绝,绝不重新解释。 */
+    v: 1;
+    requestId: string;
+    at: number;
+    /** `"complete"` ⇔ 冲突为空 ∧ 每个 pinned id 都落在 erased ∪ erasedPreviously ∪(`custodyState`
+     *  为 `complete` 的 notFound)里;其余一律 `"partial"`(重放会把它收敛)。 */
+    status: "complete" | "partial";
+    evidenceCapability: "journal" | "none";
+    /** 证据链在组装时刻的完整性。`"damaged"` ⇒ 每一行 notFound 都带 `historyUnknown` 且永不产出
+     *  `erasedPreviously`(「没有行」这件事无法在一条有已知缺口的链上做历史判定)。 */
+    custodyState: "complete" | "damaged" | "capability-absent";
+    /** 选择子,原样回显(形与请求体的同一条:判决属主是 core)。 */
+    select: Record<string, unknown>;
+    /** 选择子 canonical JSON 的 sha256 hex。 */
+    selectHash: string;
+    /** pinned id 集(= anchor 行的 `ids`;重放读回它,绝不重新解析)。 */
+    resolvedIds: string[];
+    erased: Array<{
+        id: string;
+        rev: string;
+        binding: MemoryErasedBinding;
+        /** 删除证据行的 `ev` —— `"none"` 腿上缺席。 */
+        evidenceEv?: string;
+        /** 本事务**物理删掉**的、经普查确认的投影文件数(清扫臂可以 >1)。 */
+        projectionsRemoved: number;
+        /** 贡献会话(`"none"` 腿答 `[]`)。崩溃后的重放带的是链上那一份 —— **诚实降级,绝不伪造重建**。 */
+        sessions: string[];
+    }>;
+    /** 判决时刻没有行、且不能在**这次请求**名下主张为已抹除。涵盖「从没存在过 / 自然删除 / 被另一次请求
+     *  删掉」—— 链分得出来,收执不假装分得出来。`historyUnknown` ⇔ `custodyState !== "complete"`。 */
+    notFound: Array<{
+        id: string;
+        historyUnknown?: true;
+    }>;
+    /** 链读出来的行:带**本** requestId 的、origin 缺席的删除行。非空才在场;`"none"` 腿与受损链上永不产出。 */
+    erasedPreviously?: Array<{
+        id: string;
+        ev: string;
+        at: number;
+        from?: {
+            scope: string;
+            slug: string;
+        };
+    }>;
+    /** 按 id 的**计划期**故障(锁内的 io/plan 错;单锁跨度里没有 CAS 输家)。非致命,重放会收敛。 */
+    conflicts: Array<{
+        id: string;
+        reason: string;
+    }>;
+    residuals: {
+        /** frontmatter id 落在 pinned 集里的隔离区文件(**保留不删**:收执负责枚举,清理是另一个显式动作)。 */
+        quarantineHits: string[];
+        /** 归因不了的隔离区文件(碎片 / 非条目形)—— 这次枚举**诚实的上界**。 */
+        quarantineOpaque: number;
+        /** 抹除时的索引清扫读不到 / 写不动的派生 `MEMORY.md`(可能仍挂着被删条目的行)。非空才在场。 */
+        indexUncleared?: string[];
+        /** **自陈的传播边界,恒在场**:删除是**本店**的事实;远端 peer 的收敛是同步部署自己要证的另一半。 */
+        propagation: "local-store-only";
+    };
+    [k: string]: unknown;
+}
+/** 外源标记的成因词表(core `MemoryOriginCause`)。🔴 **缺席合法且绝不猜**:标记铸于本词表存在之前的
+ *  条目就是诚实地没有 cause。 */
+export type MemoryOriginCause = "observed" | "derived" | "static" | "unattributed";
+/**
+ * 一条 entry 的**外源标记**:这条记忆的内容来自模型看到的**外部材料**(网页、第三方文档、别人的仓),
+ * 而不是这次会话里的一手事实。语义不是「有毒」而是「**用前先核**」—— 它跟着条目一路走到每一次模型挂载。
+ *
+ * 🔴 **三键是契约,但这只对象是开集**,而且三条读面给的**保证强度不同**,别按最强的那条写围栏:
+ *  · {@link MemoryOriginExternalEntry.origin} —— core 的窄重建(`committedOriginOf` 逐字只铸 taint/cause?/at);
+ *  · {@link MemoryOriginClearanceRow.origin} —— server 的深投影(三键之外的成员**剥值留名**到 `originUnknownKeys`);
+ *  · {@link MemoryOriginClearReceipt.origin} —— **原样转发**。新开行时它是上面那个窄重建,但**恢复腿**
+ *    回的是账本**原始对象**(core `clearEntryOrigin` 读到 pending 行即 `origin: row.origin`),于是版本
+ *    偏斜 / core 日后加键 / core 明写的手工恢复都可能让它多带成员 —— 那是一次**已经成功提交**的清标,
+ *    消费端不许判它违约。
+ */
+export interface MemoryEntryOriginMark {
+    taint: "external";
+    cause?: MemoryOriginCause;
+    at: number;
+    [k: string]: unknown;
+}
+/** `GET /v1/memory/origin/external` 的一行:标记 + **完整出处账**(契约 §11.2)。 */
+export interface MemoryOriginExternalEntry {
+    id: string;
+    slug: string;
+    scope: string;
+    origin: MemoryEntryOriginMark;
+    /** **就是** {@link EntryProvenanceAccount} 本身(同一条判别式,同一条透传纪律)。
+     *  一条被**挑战**的标记条目照样列在这里 —— 排除态骑在这份账的 `exclusion` 里,人要先看见才能裁。 */
+    provenance: EntryProvenanceAccount;
+    [k: string]: unknown;
+}
+/**
+ * `GET /v1/memory/origin/external?scopes=…` 的 200 体(契约 §11.2)。
+ *
+ * 🔴 **答案只覆盖你点名的那些 scope,空结果绝不读作「本店干净」。** server 这一代**没有 scope 枚举
+ * 读面**,所以 scope 名由调用方给;不完备是**静默**的(空数组与「这些 scope 干净」在 wire 上同形),
+ * 这句话就是它唯一的告示。审计脚本必须自己保证名单完备(scope 键与 `GET /v1/memory/export?scope=`
+ * 用的是同一套)。
+ * {@link scopes} 是**这次真正被审的那一份**(服务端归一化之后:逐段去空白、去空段、保序去重)——
+ * 回显它是为了让**覆盖面可观察**,消费端不该靠自己记得发了什么去反推答案的边界。
+ */
+export interface MemoryOriginExternalResult {
+    scopes: string[];
+    entries: MemoryOriginExternalEntry[];
+    [k: string]: unknown;
+}
+/** 一条清标**终态事件**(who / when / to / detail 四件正是「事件」这个概念的全部)。
+ *  `detail` 缺席时键**不出现** —— 审计面上「没写细节」与「细节是空」不同义。 */
+export interface MemoryOriginClearanceEvent {
+    eventId: string;
+    at: number;
+    to: "done" | "failed";
+    /** **这条事件**的解决者(正常路径上是开行者;崩溃路径上是后来的恢复者)。 */
+    requestId: string;
+    detail?: string;
+    [k: string]: unknown;
+}
+/**
+ * 一条清标行的 wire 形 —— core `OriginClearanceRow` 的**显式白名单投影**(契约 §11.3)。
+ *
+ * 🔴 **`entryText` 恒不上 wire,但它的在场用 {@link custodyBytes} 如实披露。** core 的行上有一个
+ * `entryText` = 被清标条目的**完整正文**:它是**崩溃恢复席**(墓碑批与重录批之间崩了,这一行是那条
+ * 记忆世界上唯一的一份),而恢复的手段是**再调一次 `originClear`**(引擎自己从行里重放),不是让人
+ * 把字节读出来贴回去 —— 把整条记忆的正文放上一个审计**列表**面,等于给每一次「看看清标记录」都附赠
+ * 一份全文导出。⇒ 剥掉。但**剥了要说**:`custodyBytes > 0` 的 `pending` 行 = 恢复席里还揣着一条记忆,
+ * **要人处置**。
+ * 🔴 `entryText` **不在本型的具名键集上** —— 这是 SDK 侧「不承诺自己没见过的东西」的机器面。它与
+ * **索引签名在场**(容得下未知键)不矛盾:前者说「我不替 server 承诺发什么」,后者说「生产方先走一步
+ * 时我不判它违约」。全文见本族顶注的「响应体一律宽进」段。
+ */
+export interface MemoryOriginClearanceRow {
+    clearanceId: string;
+    /** 被清标的条目。清标**保留同一个 id**,所以这个键把清标与条目的一生 join 起来。 */
+    entryId: string;
+    scope: string;
+    slug: string;
+    /** 判决所锚的已提交 rev(墓碑的 CAS 锚)。 */
+    baseRev: string;
+    /** **被清掉的那个标记**,深投影成文档化的三键(审计:宿主到底替什么担了保)。 */
+    origin: MemoryEntryOriginMark;
+    /** 磁盘上那行的 `origin` 携带了三键之外的成员时,**只列它们的键名**(值永不上 wire);正常行没有这个键。 */
+    originUnknownKeys?: string[];
+    /** **谁**清的 —— 强制审计归属,core 从不替调用方铸。
+     *  🔴 它是**自称**的、不是已验证的:任一够得着这口的 operator 都能把一次不可逆的清标记到别人名下。
+     *  部署侧的对照物在 server 日志(`memory_origin_cleared`,同时带**已验证的** principal 与调用方自称的
+     *  requestId,按 `clearanceId` 可 join)—— **合规结论不要只读账本**。 */
+    requestId: string;
+    /** **为什么** —— 宿主陈述的理由,core 从不填默认值(自由文本)。 */
+    reason: string;
+    /** 开行时刻。 */
+    at: number;
+    status: "pending" | "done" | "failed";
+    /** 本次清标的墓碑提交时刻(**在场才发**);缺席的行在恢复腿上会保守拒。 */
+    tombstonedAt?: number;
+    events: MemoryOriginClearanceEvent[];
+    /** **托管 UTF-8 字节数**(不是 JS 字符串长度)。`0` = 这行没揣着字节;`>0` = 恢复席里还有一条记忆的正文。 */
+    custodyBytes: number;
+    [k: string]: unknown;
+}
+/** `GET /v1/memory/origin/clearances` 的 200 体(契约 §11.3)。 */
+export interface MemoryOriginClearancesResult {
+    clearances: MemoryOriginClearanceRow[];
+    [k: string]: unknown;
+}
+/**
+ * `POST /v1/memory/origin/entries/{entryId}/clear` 的请求体(契约 §11.4)。
+ *
+ * 🔴 **`requestId` 是审计归属,不是幂等键。** 与 {@link MemoryErasureRequest.requestId} **语义不同**:
+ * 那边是幂等身份(重试必须复用同一个 id);这边是「**谁**清的标」,它会原样落进审计行与终态事件。
+ * 恢复一条 pending 行时传一个**新的** requestId 是合法且常见的(后来的恢复者就是另一个人)。
+ * 缺席 / 空串 ⇒ 400 `request.request_id_required`。**不设长度上限**(体积由请求体上限兜)。
+ * 🔴 `reason` 只验**形**(必须是串);**空串合不合法是引擎的判决** ⇒ 422 `memory.origin_clear_invalid`。
+ * SDK 在这一层不加 min(1):那就是第二真源,而且会把一个 core 明确铸了码的拒因永久挡在 wire 之外。
+ */
+export interface MemoryOriginClearRequest {
+    requestId: string;
+    reason: string;
+}
+/**
+ * `POST /v1/memory/origin/entries/{entryId}/clear` 的 200 收执(契约 §11.4)。
+ *
+ * 🔴 **收执里没有「这是一次恢复」的判别位。** 引擎读到同一条 entry 上的 pending 行就**恢复它**,
+ * 你写的 `reason` 一个字都不看 —— 账上留下的仍是**开行者**的理由与 requestId,只有终态**事件**里那条
+ * requestId 是你的。于是按 409 `memory.origin_clear_pending` 的指示重发、拿到 200 的那个人,完成的
+ * 可能是别人的行。⇒ **拿到 200 之后回读 `originClearances()` 对一次 `reason` / `requestId`**,别把 200
+ * 读成「我的理由已入账」;{@link clearanceId} 就是那一行的键。
+ */
+export interface MemoryOriginClearReceipt {
+    entryId: string;
+    clearanceId: string;
+    /** 刚被清掉的那个标记,逐字。 */
+    origin: MemoryEntryOriginMark;
+    /** 重录后条目的落点。 */
+    landedSlug: string;
+    [k: string]: unknown;
+}
 /** `POST /v1/approvals/{sessionId}/decide` 的 200 体(spec `ApprovalDecisionResult` 的型面镜像;此前 SDK 只给 `unknown`)。
  *  三种真实形共用这只信封(spec 长注有全文):**受理形**(server ≥7.37 durable 部署默认)`{taskId, sessionId,
  *  status:"resuming", bindingEnforced:true}` —— `errorCode`/`errorMessage`/`retriable` **从不**上这形,失败落 run 行与