@sema-agent/client-core 0.6.0 → 0.8.0

package/dist/toolResult.d.ts

@@ -0,0 +1,118 @@
+/**
+ * 引擎会在 `tool_end.structured` 顶层 `type` 上发的**全部**取值。
+ * 用途**不是**「只处理这些」——下面的 switch 只认得其中一部分,认不得的照旧走 text 回落;
+ * 用途是「**structured 在场**」这个判据本身:顶层 type 命中白名单 ⇒ 引擎这一版是发结构化的,
+ * 于是模型面正文的**正则反解**(T11 bash / T13+T24 task-output / T14 后台回执三代文案)退位。
+ * 反过来,一个 `{type:'something-else'}` 或裸对象**不算** structured 在场 —— 宁可回落到正则,
+ * 也不许把「有个对象」当成「引擎发了结构化」(判据锚在决定结果的量上:决定的是「该不该信正则」)。
+ * ⚠️ 与设计稿的口径差:任务书写「29 项」,[1840] 清单逐条数是 **30 项**(见交接报告「设计稿错漏」)。
+ */
+export declare const STRUCTURED_DETAIL_TYPES: ReadonlySet<string>;
+/** structured 在场判别:顶层 `type` ∈ 白名单 ⇒ 返回该 type,否则 undefined(= 不在场)。 */
+export declare function structuredDetailType(structured: unknown): string | undefined;
+export declare function modelFacingParseCalls(): number;
+export declare function _resetModelFacingParseCountForTest(): void;
+export declare function parseModelFacingBash(text: string): {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+} | null;
+/**
+ * T12 —— 剥引擎的 `delimitUntrusted` 围栏(core untrusted-text.ts:118)**仅供渲染**。
+ * 围栏是给模型看的注入防护,人类转录卡显示正文(clay 07-03 审计 #1/#9 视觉 bug 的修)。
+ */
+export declare function stripUntrustedFence(text: string): {
+    label: string;
+    body: string;
+} | null;
+/**
+ * T13 回落 —— 引擎 TaskOutput 的模型面正文(core task-registry.ts 的 bash/agent 两形,整体
+ * delimitUntrusted 包裹、label = `TaskOutput <id>`)反解回卡片槽位。`kind` 报哪一形命中,
+ * 'unknown' ⇒ 调用方回落原文。
+ */
+export declare function parseModelFacingTaskOutput(text: string): {
+    kind: 'bash' | 'agent' | 'unknown';
+    taskId?: string;
+    status?: string;
+    output?: string;
+};
+/**
+ * T14 回落 —— 后台回执**三代文案**正则(#117a:core ≥1.283 的 `Command running in background` 是
+ * 第三代)。structured bash 在场时由 `background`/`task_id` 位取代(见 `wireOutputToBody`)。
+ */
+export declare function parseBackgroundReceipt(text: string): {
+    taskId: string;
+} | null;
+/**
+ * T8 —— 压平非均匀 §E1 `output`(`string` | `(Text|Image)[]`)。
+ * ⚠️ 真源在 adapt.ts(A 层 settle 报告也用同一份),本文件只 import,别再写第二份。
+ */
+export type FlattenWireOutput = (output: unknown) => string;
+/** wire 没带 output 时的降级原因码(UI 显示决策留端;客户端绝不编造执行结果)。 */
+export declare const TOOL_RESULT_DEGRADED_WIRE_NO_OUTPUT: "wire_carried_no_output";
+export interface ToolResultBody {
+    content: unknown;
+    isError: boolean;
+    toolUseResult?: unknown;
+    /** 只在「wire 没带正文」时出现;在场 = 这张卡**没有真实执行结果**,不是空结果。 */
+    degraded?: typeof TOOL_RESULT_DEGRADED_WIRE_NO_OUTPUT;
+}
+/**
+ * T7 —— `tool_end.output === undefined`(events.d.ts:79 文档化的「工具没有正文」情形)时的卡体。
+ *
+ * cli 旧形:调 mock 注册表 `synthesizeToolIO(name, input)` **反造**一个结果体(stdout/hunks/匹配列表),
+ * 卡片于是显示「看起来像真的、但根本不是这次执行产物」的内容。§8-4 按宪法「诚实优先于产出」裁定
+ * 搬的时候就改掉:**输出诚实缺席 + degraded 标记**,由 UI 决定显示「结果不可用」。
+ * 🔴 `content` 保持**字符串**(件1:tool_result block content 恒字符串,裸对象经 /compact 直发
+ * provider = 400 invalid_request);空串 = 无正文,`degraded` 才是判别位。
+ */
+export declare function degradedToolResultBody(isError: boolean): ToolResultBody;
+/**
+ * 真实 §E1 `tool_end.output` → 卡片读的 typed 正文。
+ *
+ * B5 新增第 5 个入参 `structured`:**structured 在场 ⇒ 正则退位**(①)。
+ * 三臂:`bash`(T11/T14)· `taskoutput|task_output`(T13,无 structured 的老腿)· 泛化兜底。
+ * 🔴 `truncated` 只做中性提示,截断正文**绝不**回喂模型(events.d.ts:80-85)。
+ */
+export declare function wireOutputToBody(toolName: string, output: unknown, isError: boolean, truncated: boolean, flatten: FlattenWireOutput, structured?: unknown): ToolResultBody;
+/**
+ * design/64 CC-parity `toolUseResult`:引擎结构化细节 → 各卡 outputSchema **精确** typed 形
+ * (safeParse 过了才渲富卡,不过就回落 12 行文本兜底)。
+ * `structuredPatch` 在**这里**算(T20,core 裁定:引擎发 originalFile、客户端算 hunks)。
+ * 全部**防御读**:形状不认得 ⇒ null ⇒ 调用方回落 text 路径(降保真,绝不炸)。
+ */
+export declare function structuredToToolUseResult(structured: unknown, 
+/** 压平后的模型面正文 —— 有些形(task-output)只带 identity/status,正文仍在模型面。 */
+modelText?: string): {
+    toolUseResult: unknown;
+    isError?: boolean;
+} | null;
+export interface EngineBgShellRegistration {
+    kind: 'register';
+    /** 回执上的**引擎** task id(`task_id=…`,TaskOutput/TaskStop 的句柄)。 */
+    taskId: string;
+    /** Bash tool_use input 的 command(面板行的命令行)。 */
+    command: string;
+    /** 模型给了 description 才有。 */
+    description?: string;
+    /** 引擎模型面回执原文,逐字 —— 详情视图显示它(里面的 output-file 路径因此可见可复制)。 */
+    receipt: string;
+}
+export declare function detectEngineBgShellReceipt(rawInput: unknown, outputText: string | undefined): EngineBgShellRegistration | null;
+/**
+ * TodoWrite 清单卡:引擎不发 todo structured,全量新表骑在 tool_use INPUT 上 ⇒ 从它合成 typed 结果。
+ * `oldTodos` = 上一次的活体清单(调用方持:一个 session 一份,正是划删线 diff 要的粒度)。
+ */
+export declare function todoWriteToolUseResult(rawInput: unknown, oldTodos: unknown[], isError: boolean): {
+    toolUseResult: unknown;
+    isError: boolean;
+    newTodos: unknown[];
+} | null;
+/**
+ * ReportFindings(core 1.288 [811]b,引擎侧执行的合成回声工具):details 是 `{count, level?, findings}`
+ * **没有 type 判别位**(core synthetic-tools.js)⇒ B 层的 type-keyed switch 认领不了,按**工具名**认。
+ * 双腿:优先 wire structured;引擎没发就从 tool_use INPUT 合成(回声工具:input.findings ≡ output.findings)。
+ */
+export declare function reportFindingsToolUseResult(structured: unknown, rawInput: unknown): {
+    toolUseResult: unknown;
+} | null;