@matthewlam/pi-worker 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Lam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+# pi-worker
+
+Headless worker helpers for `pi -p`.
+
+## Flags
+
+- `--last-message-file <path>` writes the final assistant text on `agent_end`.
+- `--result-schema <path>` enables the `report_result` tool and validates tool args against the JSON Schema file. Gotcha: a `-t` allowlist applies to extension tools too — include `report_result` in it (e.g. `-t read,write,bash,report_result`) or the model cannot call the tool and no result file is written.
+- `--result-file <path>` overrides the structured result output path. Without it, `result.json` is written next to `--last-message-file`.
+- `--worker-heartbeat-file <path>` writes a JSON liveness record on `agent_start`, `tool_execution_end`, and `agent_end`.
+- `--worker-trust` answers project trust with `{ "trusted": "yes" }` for this process.

package/extension/index.ts

@@ -0,0 +1,334 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { Type } from "@earendil-works/pi-ai";
+import {
+  defineTool,
+  type AgentEndEvent,
+  type ExtensionAPI,
+  type ExtensionContext,
+  type ProjectTrustEventResult,
+} from "@earendil-works/pi-coding-agent";
+
+type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
+
+interface JsonSchema {
+  readonly type?: string | readonly string[];
+  readonly properties?: Record<string, JsonSchema>;
+  readonly required?: readonly string[];
+  readonly additionalProperties?: boolean | JsonSchema;
+  readonly items?: JsonSchema;
+  readonly enum?: readonly JsonValue[];
+  readonly const?: JsonValue;
+  readonly minimum?: number;
+  readonly maximum?: number;
+  readonly minLength?: number;
+  readonly maxLength?: number;
+  readonly minItems?: number;
+  readonly maxItems?: number;
+}
+
+interface ValidationResult {
+  readonly ok: boolean;
+  readonly errors: readonly string[];
+}
+
+interface WorkerState {
+  readonly registeredResultTool: { value: boolean };
+  shutdown: boolean;
+}
+
+interface HeartbeatPayload {
+  readonly timestamp: string;
+  readonly lastEvent: "agent_start" | "tool_execution_end" | "agent_end";
+  readonly toolName?: string;
+  readonly tokenTotals?: JsonValue;
+}
+
+const REPORT_RESULT_TOOL = "report_result";
+const RESULT_INSTRUCTION_PREFIX = `
+Structured worker result is enabled. Before finishing, you must call report_result exactly once with arguments matching this JSON Schema. Use report_result as the final action after you have enough information to answer.
+
+JSON Schema:
+`;
+
+export default function piWorkerExtension(pi: ExtensionAPI) {
+  const state: WorkerState = {
+    registeredResultTool: { value: false },
+    shutdown: false,
+  };
+
+  pi.registerFlag("last-message-file", {
+    description: "Write the final assistant message text to this file on agent_end",
+    type: "string",
+  });
+  pi.registerFlag("result-schema", {
+    description: "JSON Schema file for the report_result tool arguments",
+    type: "string",
+  });
+  pi.registerFlag("result-file", {
+    description: "Path for validated report_result JSON; defaults to result.json next to --last-message-file",
+    type: "string",
+  });
+  pi.registerFlag("worker-heartbeat-file", {
+    description: "Write worker liveness JSON on agent_start, tool_execution_end, and agent_end",
+    type: "string",
+  });
+  pi.registerFlag("worker-trust", {
+    description: "Trust the current project for this process without prompting",
+    type: "boolean",
+    default: false,
+  });
+
+  pi.on("project_trust", async (): Promise<ProjectTrustEventResult> => {
+    return pi.getFlag("worker-trust") === true ? { trusted: "yes" as const } : { trusted: "undecided" as const };
+  });
+
+  pi.on("session_start", async () => {
+    state.shutdown = false;
+    registerResultToolIfEnabled(pi, state);
+  });
+
+  pi.on("session_shutdown", async () => {
+    state.shutdown = true;
+  });
+
+  pi.on("before_agent_start", async (event) => {
+    if (!getStringFlag(pi, "result-schema")) return undefined;
+    registerResultToolIfEnabled(pi, state);
+    const schema = await loadResultSchema(pi);
+    return { systemPrompt: event.systemPrompt + RESULT_INSTRUCTION_PREFIX + JSON.stringify(schema, null, 2) };
+  });
+
+  pi.on("agent_start", async (_event, ctx) => {
+    await writeHeartbeatIfEnabled(pi, state, ctx, { lastEvent: "agent_start" });
+  });
+
+  pi.on("tool_execution_end", async (event, ctx) => {
+    await writeHeartbeatIfEnabled(pi, state, ctx, {
+      lastEvent: "tool_execution_end",
+      toolName: event.toolName,
+    });
+  });
+
+  pi.on("agent_end", async (event, ctx) => {
+    await writeLastMessageIfEnabled(pi, state, event);
+    await writeHeartbeatIfEnabled(pi, state, ctx, { lastEvent: "agent_end" });
+  });
+}
+
+function registerResultToolIfEnabled(pi: ExtensionAPI, state: WorkerState): void {
+  if (state.registeredResultTool.value || !getStringFlag(pi, "result-schema")) return;
+
+  state.registeredResultTool.value = true;
+  pi.registerTool(
+    defineTool({
+      name: REPORT_RESULT_TOOL,
+      label: "Report Result",
+      description: "Validate and save the final structured worker result. Call this before finishing when --result-schema is set.",
+      promptSnippet: "Validate and save the final structured worker result",
+      promptGuidelines: [
+        "Use report_result before finishing when structured worker result output is enabled.",
+        "After calling report_result successfully, do not call report_result again.",
+      ],
+      parameters: Type.Object({}, { additionalProperties: true }),
+      executionMode: "sequential",
+      async execute(_toolCallId, params) {
+        const schema = await loadResultSchema(pi);
+        const result = validateJsonSchema(params as JsonValue, schema);
+        if (!result.ok) {
+          throw new Error(`report_result arguments failed schema validation: ${result.errors.join("; ")}`);
+        }
+
+        const outputPath = resultFilePath(pi);
+        await writeJsonFile(outputPath, params as JsonValue);
+        return {
+          content: [{ type: "text", text: `Saved structured worker result to ${outputPath}` }],
+          details: { path: outputPath, result: params },
+          terminate: true,
+        };
+      },
+    }),
+  );
+}
+
+async function writeLastMessageIfEnabled(pi: ExtensionAPI, state: WorkerState, event: AgentEndEvent): Promise<void> {
+  if (state.shutdown) return;
+  const outputPath = getStringFlag(pi, "last-message-file");
+  if (!outputPath) return;
+  await writeTextFile(outputPath, finalAssistantText(event));
+}
+
+async function writeHeartbeatIfEnabled(
+  pi: ExtensionAPI,
+  state: WorkerState,
+  ctx: ExtensionContext,
+  event: Omit<HeartbeatPayload, "timestamp" | "tokenTotals">,
+): Promise<void> {
+  if (state.shutdown) return;
+  const outputPath = getStringFlag(pi, "worker-heartbeat-file");
+  if (!outputPath) return;
+
+  const tokenTotals = readTokenTotals(ctx);
+  const payload: HeartbeatPayload = {
+    timestamp: new Date().toISOString(),
+    ...event,
+    ...(tokenTotals === undefined ? {} : { tokenTotals }),
+  };
+  await writeJsonFile(outputPath, payload as unknown as JsonValue);
+}
+
+function finalAssistantText(event: AgentEndEvent): string {
+  const assistant = [...event.messages].reverse().find((message) => message.role === "assistant");
+  if (!assistant) return "";
+
+  return assistant.content
+    .flatMap((part) => {
+      if (typeof part === "string") return [part];
+      if (part && typeof part === "object" && "type" in part && part.type === "text" && "text" in part) {
+        return [String(part.text)];
+      }
+      return [];
+    })
+    .join("");
+}
+
+async function loadResultSchema(pi: ExtensionAPI): Promise<JsonSchema> {
+  const schemaPath = getStringFlag(pi, "result-schema");
+  if (!schemaPath) throw new Error("--result-schema is required before report_result can run");
+
+  const schema = JSON.parse(await readFile(resolve(schemaPath), "utf8")) as unknown;
+  if (!isRecord(schema)) throw new Error(`Result schema at ${schemaPath} must be a JSON object`);
+  return schema as JsonSchema;
+}
+
+function resultFilePath(pi: ExtensionAPI): string {
+  const explicit = getStringFlag(pi, "result-file");
+  if (explicit) return resolve(explicit);
+
+  const lastMessageFile = getStringFlag(pi, "last-message-file");
+  if (lastMessageFile) return resolve(dirname(lastMessageFile), "result.json");
+
+  return resolve(process.cwd(), "result.json");
+}
+
+function getStringFlag(pi: ExtensionAPI, name: string): string | undefined {
+  const value = pi.getFlag(name);
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+async function writeTextFile(path: string, text: string): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, text, "utf8");
+}
+
+async function writeJsonFile(path: string, value: JsonValue): Promise<void> {
+  await writeTextFile(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function readTokenTotals(ctx: ExtensionContext): JsonValue | undefined {
+  const usage = ctx.getContextUsage?.();
+  if (!usage || !isRecord(usage)) return undefined;
+  return JSON.parse(JSON.stringify(usage)) as JsonValue;
+}
+
+export function validateJsonSchema(value: JsonValue, schema: JsonSchema): ValidationResult {
+  const errors: string[] = [];
+  validateAt(value, schema, "$", errors);
+  return { ok: errors.length === 0, errors };
+}
+
+function validateAt(value: JsonValue, schema: JsonSchema, path: string, errors: string[]): void {
+  if (schema.const !== undefined && !jsonEqual(value, schema.const)) {
+    errors.push(`${path} must equal ${JSON.stringify(schema.const)}`);
+  }
+  if (schema.enum && !schema.enum.some((allowed) => jsonEqual(value, allowed))) {
+    errors.push(`${path} must be one of ${schema.enum.map((allowed) => JSON.stringify(allowed)).join(", ")}`);
+  }
+
+  if (schema.type && !matchesType(value, schema.type)) {
+    errors.push(`${path} must be ${Array.isArray(schema.type) ? schema.type.join(" or ") : schema.type}`);
+    return;
+  }
+
+  if (typeof value === "number") {
+    if (schema.minimum !== undefined && value < schema.minimum) errors.push(`${path} must be >= ${schema.minimum}`);
+    if (schema.maximum !== undefined && value > schema.maximum) errors.push(`${path} must be <= ${schema.maximum}`);
+  }
+
+  if (typeof value === "string") {
+    if (schema.minLength !== undefined && value.length < schema.minLength) {
+      errors.push(`${path} length must be >= ${schema.minLength}`);
+    }
+    if (schema.maxLength !== undefined && value.length > schema.maxLength) {
+      errors.push(`${path} length must be <= ${schema.maxLength}`);
+    }
+  }
+
+  if (Array.isArray(value)) {
+    if (schema.minItems !== undefined && value.length < schema.minItems) {
+      errors.push(`${path} item count must be >= ${schema.minItems}`);
+    }
+    if (schema.maxItems !== undefined && value.length > schema.maxItems) {
+      errors.push(`${path} item count must be <= ${schema.maxItems}`);
+    }
+    if (schema.items) {
+      value.forEach((item, index) => validateAt(item, schema.items!, `${path}[${index}]`, errors));
+    }
+  }
+
+  if (isRecord(value)) {
+    validateObject(value, schema, path, errors);
+  }
+}
+
+function validateObject(value: Record<string, JsonValue>, schema: JsonSchema, path: string, errors: string[]): void {
+  const properties = schema.properties ?? {};
+  for (const property of schema.required ?? []) {
+    if (!(property in value)) errors.push(`${path}.${property} is required`);
+  }
+
+  for (const [key, childValue] of Object.entries(value)) {
+    const childSchema = properties[key];
+    if (childSchema) {
+      validateAt(childValue, childSchema, `${path}.${key}`, errors);
+      continue;
+    }
+    if (schema.additionalProperties === false) {
+      errors.push(`${path}.${key} is not allowed`);
+    } else if (isRecord(schema.additionalProperties)) {
+      validateAt(childValue, schema.additionalProperties, `${path}.${key}`, errors);
+    }
+  }
+}
+
+function matchesType(value: JsonValue, type: string | readonly string[]): boolean {
+  const options = Array.isArray(type) ? type : [type];
+  return options.some((option) => {
+    switch (option) {
+      case "array":
+        return Array.isArray(value);
+      case "boolean":
+        return typeof value === "boolean";
+      case "integer":
+        return typeof value === "number" && Number.isInteger(value);
+      case "null":
+        return value === null;
+      case "number":
+        return typeof value === "number";
+      case "object":
+        return isRecord(value);
+      case "string":
+        return typeof value === "string";
+      default:
+        return true;
+    }
+  });
+}
+
+function isRecord(value: unknown): value is Record<string, JsonValue> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function jsonEqual(left: JsonValue, right: JsonValue): boolean {
+  return JSON.stringify(left) === JSON.stringify(right);
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@matthewlam/pi-worker",
+  "version": "0.1.0",
+  "description": "Headless worker utilities for pi print-mode agents",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "worker",
+    "headless",
+    "automation"
+  ],
+  "pi": {
+    "extensions": [
+      "./extension/index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run typecheck && node test/worker-extension-smoke.mjs"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.80.3",
+    "@earendil-works/pi-coding-agent": "^0.80.3",
+    "@types/node": "^24.0.0",
+    "jiti": "^2.7.0",
+    "typescript": "^5.9.3"
+  },
+  "files": [
+    "extension",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "author": "minghinmatthewlam",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/minghinmatthewlam/pi-worker.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}