@zhushanwen/pi-structured-output 5.1.0 → 5.1.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhushanwen/pi-structured-output",
-  "version": "5.1.0",
-  "description": "Structured output tool for Pi — enforces JSON Schema via tool call mechanism with Ajv validation",
+  "version": "5.1.2",
+  "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",
   "xyz-agent": {
@@ -27,7 +27,7 @@
     "ajv": "^8.17.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.1",
+    "@earendil-works/pi-coding-agent": "^0.84.4",
     "typebox": "*"
   },
   "devDependencies": {

package/src/execute.ts

@@ -42,8 +42,8 @@ import {
  * 直接被这些约束校验，故算 object 根。组合根（anyOf/oneOf/allOf/$ref/enum）
  * 可能接受非 object 值，保真起见一律包装（{value} 内可容纳任意成员类型）。
  *
- * [同源锚定] @zhushanwen/pi-subagent-workflow 的 agent-opts-resolver.ts 持有
- * 本函数的本地副本（两包独立 npm 不能直接 import，optional peer 不保证存在），
+ * [同源锚定] packages/subagent-core 的 agent-opts-resolver.ts（src/orchestration/）
+ * 持有本函数的本地副本（两包独立 npm 不能直接 import，optional peer 不保证存在），
  * 其 ASP 文案按本判定同源条件化——改动本函数判定逻辑必须同步该副本。
  */
 export function isObjectRootSchema(schema: unknown): schema is Record<string, unknown> {

package/src/schema-guards.ts

@@ -96,6 +96,10 @@ export function isToolExecutionEndEvent(
 	return typeof e === "object" && e !== null && "toolName" in e && "isError" in e;
 }
 
-/** swap 检测 + keyword-less schema 拒绝的纠错文案前缀，所有相关错误共用。 */
+/**
+ * swap 检测 + keyword-less schema 拒绝的纠错文案前缀，所有相关错误共用。
+ * 工具名逐字拼写（非 ${TOOL_NAME} 引用）：本模块是纯逻辑叶节点（零业务依赖），
+ * 反向 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

@@ -37,9 +37,9 @@ export const ENV_SCHEMA = "PI_WORKFLOW_SCHEMA";
  *
  * 背景：PI_WORKFLOW_SCHEMA 经 spawn childEnv 注入子进程，env 块受 ARG_MAX 约束
  *（Linux E2BIG）——超大 schema 会在 spawn 调用点报难归因的失败。硬拒绝在
- * subagent-workflow 侧（session-runner 的 applySchemaEnvToChildEnv，同值上限
- * SCHEMA_ENV_MAX_BYTES = 256 * 1024，见其 src/shared/schema-env.ts [跨包契约 SSOT]
- * 注释）；本包独立 npm 不能直接 import（isObjectRootSchema 本地副本同例），常量
+ * subagent-core 侧（packages/subagent-core 的 session-runner applySchemaEnvToChildEnv，
+ * 同值上限 SCHEMA_ENV_MAX_BYTES = 256 * 1024，见其 src/shared/schema-env.ts
+ * [跨包契约 SSOT] 注释）；本包独立 npm 不能直接 import（isObjectRootSchema 本地副本同例），常量
  * 各自保留、跨包契约测试锁字节相等（tests/cross-package-contract.test.ts）。
  * 本侧职责仅可见性：注册时超限 logger.warn（无 logger API，stderr 直出惯例）提示
  * env 通道有上限，建议拆分 schema 或精简——不拒绝注册（子进程能收到 env 说明 SW
@@ -47,7 +47,9 @@ export const ENV_SCHEMA = "PI_WORKFLOW_SCHEMA";
  *
  * [跨包契约] 任一端改值必须同步另一端，否则 SW 侧硬拒绝线与 SO 侧提示线漂移。
  */
-export const SO_SCHEMA_SIZE_WARN_BYTES = 256 * 1024;
+const SCHEMA_SIZE_WARN_KIB = 256;
+const BYTES_PER_KIB = 1024;
+export const SO_SCHEMA_SIZE_WARN_BYTES = SCHEMA_SIZE_WARN_KIB * BYTES_PER_KIB;
 
 /**
  * 注册期 schema 体积可见性提示（SO-DATA-4 的 SO 侧职责：提示，不拒绝）。
@@ -59,7 +61,7 @@ function warnIfSchemaOversized(envSchema: string): void {
 	if (bytes <= SO_SCHEMA_SIZE_WARN_BYTES) return;
 	process.stderr.write(
 		`[structured-output] PI_WORKFLOW_SCHEMA is ${bytes} bytes (> ${SO_SCHEMA_SIZE_WARN_BYTES} bytes / `
-			+ `${SO_SCHEMA_SIZE_WARN_BYTES / 1024} KiB). The env channel has a size ceiling: the workflow runner `
+			+ `${SO_SCHEMA_SIZE_WARN_BYTES / BYTES_PER_KIB} KiB). The env channel has a size ceiling: the workflow runner `
 			+ "rejects injection above its own limit (spawn fails, hard to attribute), and oversized values can "
 			+ "hit E2BIG (ARG_MAX) at spawn. "
 			+ "👉 精简 outputSchema（删冗余 description / 收敛深嵌套）或拆分为多个小 schema 步骤。\n",
@@ -192,7 +194,7 @@ export function createDailyToolDefinition() {
 			+ "Call this tool to produce validated JSON data. "
 			+ "Pass `schema` (a JSON Schema draft-07 object) and `data` (the value to validate). "
 			+ "schema describes the shape; data fills the values; they must match.\n\n"
-			+ "✅ Correct (full call): structured_output({schema:{type:'object',properties:{name:{type:'string'},age:{type:'number'}},required:['name']}, data:{name:'Alice',age:30}})\n"
+			+ `✅ Correct (full call): ${TOOL_NAME}({schema:{type:'object',properties:{name:{type:'string'},age:{type:'number'}},required:['name']}, data:{name:'Alice',age:30}})\n`
 			+ "✅ Correct: schema={type:'array',items:{type:'string'}}, data=['a','b','c']\n"
 			+ "✅ Correct: schema={type:'string',enum:['low','medium','high']}, data='medium'\n"
 			+ "✅ Correct: schema={type:'number',minimum:0,maximum:100}, data=42\n"
@@ -200,7 +202,7 @@ export function createDailyToolDefinition() {
 			+ "❌ Wrong: putting the answer in text instead of calling this tool\n"
 			+ "❌ Wrong: data not matching schema (e.g. schema requires number but data is string)\n"
 			+ "❌ Wrong: schema={type:'object'} with data='hello' (string ≠ object)\n"
-			+ "❌ Wrong: structured_output({name:'Alice'}) — missing the schema/data envelope. Wrap as {schema:{...}, data:{name:'Alice'}}.\n"
+			+ `❌ Wrong: ${TOOL_NAME}({name:'Alice'}) — missing the schema/data envelope. Wrap as {schema:{...}, data:{name:'Alice'}}.\n`
 			+ "❌ Wrong: swapping schema and data (passing the answer as schema). The tool detects this as 'likely swapped' and rejects it.\n"
 			+ "❌ Wrong: merging schema and data into one object.\n"
 			+ "❌ Wrong: schema with no recognized JSON Schema keyword (e.g. {} or {answer:42}). The schema must describe shape via draft-07 keywords (type/properties/items/if-then-else/enum/...); a keyword-less object is rejected to prevent silent accept-all compilation.",