@zhushanwen/pi-structured-output 6.2.3 → 6.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-structured-output",
-  "version": "6.2.3",
+  "version": "6.2.4",
   "description": "Structured output tool for Pi — workflow schema enforcement via pi's parameter layer; interactive mode validates self-reported schemas with Ajv",
   "type": "module",
   "main": "index.ts",
@@ -26,7 +26,7 @@
   ],
   "dependencies": {
     "ajv": "^8.17.0",
-    "@zhushanwen/extension-protocol": "0.24.0",
+    "@zhushanwen/extension-protocol": "0.25.0",
     "@zhushanwen/pi-ext-guards": "0.5.0"
   },
   "peerDependencies": {
@@ -51,6 +51,6 @@
   },
   "scripts": {
     "typecheck": "npx tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run --pool=threads"
   }
 }

package/src/schema-guards.ts

@@ -97,7 +97,7 @@ export function isTurnEndEvent(e: unknown): e is { message?: { stopReason?: stri
 /** tool_execution_end event 结构检查（替代直接 cast，配合 taste/no-unsafe-cast）。 */
 export function isToolExecutionEndEvent(
 	e: unknown,
-): e is { toolName: unknown; isError: unknown; result?: unknown } {
+): e is { toolName: unknown; isError: unknown; toolCallId?: unknown; result?: unknown } {
 	return typeof e === "object" && e !== null && "toolName" in e && "isError" in e;
 }
 
@@ -107,4 +107,4 @@ export function isToolExecutionEndEvent(
  * 反向 import tool-definition 会成环。
  */
 export const CORRECT_USAGE_HINT =
-	"Correct: structured-output({schema:{type:'object',properties:{...}}, data:{...actual values}}). ";
+	"Correct: structured_output({schema:{type:'object',properties:{...}}, data:{...actual values}}). ";

package/src/tool-definition.ts

@@ -32,7 +32,12 @@ import {
 	tryParseJson,
 } from "./schema-guards.js";
 
-export const TOOL_NAME = "structured-output";
+// 工具名用下划线（项目工具命名规范）：连字符名在 codemode 沙箱会被 toCodemodeIdentifier
+// 转成下划线形态，同一工具对模型呈现两个名字，弱模型名字形态先验被下划线主导时
+// 会直调连字符变体失败（2026-10-27 fanout 事故：deepseek-flash 直调 structured_output
+// not found → 旁路 codemode 成功 → 父层采不到）。下划线名在 codemode 是恒等映射，
+// 三个通道（LLM 工具表 / addendum / codemode API）名字一致。
+export const TOOL_NAME = "structured_output";
 export const ENV_SCHEMA = "PI_WORKFLOW_SCHEMA";
 
 /**

package/src/workflow-hook.ts

@@ -37,7 +37,7 @@ type PiAPI = ExtensionAPI;
 
 // 与 tool-definition.ts 的 TOOL_NAME 对应（本模块只监听该工具的 execution 事件；
 // 依赖图单向：workflow-hook → schema-guards / loop-gate / text-primitives，不成环）。
-const TOOL_NAME = "structured-output";
+const TOOL_NAME = "structured_output";
 const MAX_HOOK_RETRIES = 2;
 
 /** steer 发送失败告警的 appendEntry customType（session JSONL 持久化，不进 LLM 上下文）。 */
@@ -99,30 +99,33 @@ function buildSteerReminder(
 ): string {
 	if (calledButFailed) {
 		return [
-			"[MANDATORY] Your structured-output call FAILED validation:",
-			truncateText(lastSchemaError ?? "structured-output call failed", STEER_ERROR_MAX_CHARS),
+			"[MANDATORY] Your structured_output call FAILED validation:",
+			truncateText(lastSchemaError ?? "structured_output call failed", STEER_ERROR_MAX_CHARS),
 			"",
 			"The schema is enforced by the system (PI_WORKFLOW_SCHEMA) — this tool's parameter schema IS the required shape of your result.",
 			`The required schema for your result is: ${schemaJson}`,
-			"Fix your arguments to conform to this schema and call the structured-output tool AGAIN.",
+			"Fix your arguments to conform to this schema and call the structured_output tool AGAIN.",
+			"Call it directly as a top-level tool call (NOT via codemode / tools.xxx API) — only a direct tool call is recorded as your result.",
 			"Do NOT output the result as text — call the tool.",
 		].join("\n");
 	}
 	return isObjectRoot
 		? [
-				"[MANDATORY] You MUST call the structured-output tool now.",
+				"[MANDATORY] You MUST call the structured_output tool now.",
 				"Your task requires a structured output. Do NOT respond with plain text.",
-				`Your arguments ARE the data — call structured-output with your result as the tool's arguments, matching this shape: ${schemaJson}`,
+				`Your arguments ARE the data — call structured_output with your result as the tool's arguments, matching this shape: ${schemaJson}`,
 				"The schema is enforced by the system; your arguments are validated against the authoritative schema automatically.",
+				"Call it directly as a top-level tool call (NOT via codemode / tools.xxx API) — only a direct tool call is recorded as your result.",
 				"This is enforced by the workflow system. Just call the tool.",
 			].join("\n")
 		: [
-				"[MANDATORY] You MUST call the structured-output tool now.",
+				"[MANDATORY] You MUST call the structured_output tool now.",
 				"Your task requires a structured output. Do NOT respond with plain text.",
-				`Call structured-output with a single argument \`{value: <data>}\` — put the result itself in \`value\`, and it must conform to this shape: ${schemaJson}`,
+				`Call structured_output with a single argument \`{value: <data>}\` — put the result itself in \`value\`, and it must conform to this shape: ${schemaJson}`,
 				"Non-object schemas are wrapped in a `value` field because tool call arguments must be objects.",
 				"Validation errors may reference paths starting with `value.` (e.g. `value.0`, `value.name`): that prefix addresses the wrapper, not your data — strip it to locate the offending field.",
 				"The schema is enforced by the system; the `value` field is validated against the authoritative schema automatically.",
+				"Call it directly as a top-level tool call (NOT via codemode / tools.xxx API) — only a direct tool call is recorded as your result.",
 				"This is enforced by the workflow system. Just call the tool.",
 			].join("\n");
 }
@@ -181,6 +184,15 @@ export function setupWorkflowHook(pi: PiAPI, schemaJson: string): void {
 	pi.on("tool_execution_end", async (event: unknown, ctx: ExtensionContext) => {
 		if (!isToolExecutionEndEvent(event)) return;
 		if (event.toolName !== TOOL_NAME) return;
+		// 嵌套调用（codemode 沙箱 tools.xxx API 经 ctx.executeTool 执行）不算模型的
+		// 直接产出：pi 不持久化嵌套结果，workflow 引擎只从顶层 toolCalls 采集
+		// parsedOutput——若照常记账，soSucceededEver 被置位 → turn_end 不再 steer →
+		// 父层判「never called」（2026-10-27 fanout 事故形态）。判据 = toolCallId 含
+		// "/"：pi 嵌套管线 id 形态为 `${callerId}/${序号}`（nested-tool-calls.js），
+		// 顶层 id 由 provider 生成（call_xxx，无斜杠）；事件转发层剥掉 parentToolCallId，
+		// toolCallId 是唯一稳定抓手。误判方向安全：provider id 含斜杠被误判成嵌套的
+		// 后果只是少一次 steer，不产生错误行为。
+		if (typeof event.toolCallId === "string" && event.toolCallId.includes("/")) return;
 
 		// errorText 不在此处 fallback——合一状态机记账段/计数段对 undefined 同用
 		// "structured-output call failed" 通用提示（与合一前两 listener 传入形态等价）。