@adibacsi/pi-jack 1.0.0

package/json-schema.ts

@@ -0,0 +1,165 @@
+/**
+ * `--json-schema <schema>`: makes a pi run finish with an answer that conforms to a JSON Schema. The value is an
+ * inline JSON Schema or a path to a `.json` file (relative to the working directory). Part of JACK: the parent starts
+ * every subagent with it, and it works the same in any pi run, e.g.
+ *
+ *   pi --mode json -p --json-schema ./schema.json "Summarize this repository"
+ *
+ * Registers the two tools such a run finishes with (see contract.ts):
+ *   - `jack_subagent_result`: parameters are the run's JSON Schema, with provider-side constrained sampling requested.
+ *     Pi validates the arguments against it before the tool runs, and the tool checks them again; either way an
+ *     invalid call is thrown back with the errors so the model can fix it. For a subagent, JACK's parent stops the
+ *     child once it has rejected more than MAX_FORMAT_RETRIES answers, since only it sees both kinds of rejection.
+ *   - `jack_subagent_fail({ reason })`: ends the run when the task cannot be completed.
+ * If the agent is about to finish without calling either, a hidden message nudges it, up to MAX_FORMAT_RETRIES times.
+ *
+ * With `--mode json`, the answer is `result.details` of the last successful `tool_execution_end` event of
+ * `jack_subagent_result` (or the reason, for `jack_subagent_fail`); that is where JACK's parent reads it.
+ * Does nothing unless `--json-schema` is set.
+ */
+
+import {
+  defineTool,
+  type ExtensionAPI,
+  type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import {
+  FAIL_TOOL,
+  MAX_FORMAT_RETRIES,
+  RESULT_TOOL,
+  resolveSchema,
+  SCHEMA_FLAG,
+  schemaErrors,
+} from "./contract.ts";
+
+export function registerJsonSchema(pi: ExtensionAPI): void {
+  pi.registerFlag(SCHEMA_FLAG, {
+    description:
+      "JSON Schema (inline JSON or path to a .json file) that the final answer must conform to",
+    type: "string",
+  });
+
+  // Per-run state.
+  let finished = false;
+  let nudges = 0;
+
+  const report = (ctx: ExtensionContext, message: string) => {
+    if (ctx.hasUI) ctx.ui.notify(message, "error");
+    console.error(message);
+  };
+
+  pi.on("session_start", (_event, ctx) => {
+    const schemaPath = pi.getFlag(SCHEMA_FLAG);
+    if (typeof schemaPath !== "string" || !schemaPath) return;
+
+    let schema;
+    try {
+      schema = resolveSchema(schemaPath, ctx.cwd);
+    } catch (e) {
+      report(
+        ctx,
+        `[jack] Could not load the schema: ${e instanceof Error ? e.message : e}`,
+      );
+      return;
+    }
+
+    pi.registerTool(
+      defineTool({
+        name: RESULT_TOOL,
+        label: "Subagent Result",
+        description:
+          "Submit your final answer to the agent that delegated this task. Call it exactly once, as your last " +
+          "action, when the task is done. The parameters are the answer: fill each one as its description says.",
+        promptSnippet: "Submit your final answer as structured data",
+        promptGuidelines: [
+          `Finish by calling ${RESULT_TOOL} exactly once with your answer; its parameters define what to return.`,
+          `Your text replies are not returned to anyone; only the arguments of ${RESULT_TOOL} are.`,
+          `If you cannot complete the task, call ${FAIL_TOOL} with the reason instead of ${RESULT_TOOL}.`,
+        ],
+        parameters: schema,
+        // "prefer" falls back to plain tool calling on providers without strict JSON-schema sampling;
+        // the validation below applies either way.
+        constrainedSampling: { type: "json_schema", strict: "prefer" },
+        async execute(_toolCallId, params) {
+          const errors = schemaErrors(schema, params);
+          if (errors.length === 0) {
+            finished = true;
+            return {
+              content: [{ type: "text", text: JSON.stringify(params) }],
+              details: params,
+              terminate: true,
+            };
+          }
+          const list = errors.map((e) => `- ${e}`).join("\n");
+          throw new Error(
+            `The answer does not match the schema. Fix these and call ${RESULT_TOOL} again:\n${list}`,
+          );
+        },
+      }),
+    );
+
+    pi.registerTool(
+      defineTool({
+        name: FAIL_TOOL,
+        label: "Subagent Fail",
+        description:
+          `Give up on the task. Call it instead of ${RESULT_TOOL}, as your last action, only when the task ` +
+          "cannot be completed; the delegating agent receives the reason as the error.",
+        parameters: Type.Object({
+          reason: Type.String({
+            description:
+              "One or two sentences: what stopped you, and what would unblock it.",
+          }),
+        }),
+        async execute(_toolCallId, params) {
+          finished = true;
+          return {
+            content: [{ type: "text", text: params.reason }],
+            details: params,
+            terminate: true,
+          };
+        },
+      }),
+    );
+
+    // The parent adds both tools to any `--tools` list; this keeps them active under the default tool set too.
+    const active = pi.getActiveTools();
+    const missing = [RESULT_TOOL, FAIL_TOOL].filter((t) => !active.includes(t));
+    if (missing.length > 0) pi.setActiveTools([...active, ...missing]);
+    if (!pi.getActiveTools().includes(RESULT_TOOL)) {
+      report(
+        ctx,
+        `[jack] The ${RESULT_TOOL} tool is not available; it must not be excluded from the tool list.`,
+      );
+    }
+  });
+
+  pi.on("before_agent_start", () => {
+    finished = false;
+    nudges = 0;
+  });
+
+  pi.on("agent_before_settle", () => {
+    if (
+      finished ||
+      !pi.getActiveTools().includes(RESULT_TOOL) ||
+      nudges >= MAX_FORMAT_RETRIES
+    )
+      return;
+    nudges++;
+    return {
+      continue: true,
+      entries: [
+        {
+          type: "custom_message",
+          customType: "jack-result-nudge",
+          display: false,
+          content:
+            `You have not submitted an answer. Call ${RESULT_TOOL} now with your answer as its arguments ` +
+            `(or ${FAIL_TOOL} with the reason if you cannot complete the task).`,
+        },
+      ],
+    };
+  });
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@adibacsi/pi-jack",
+  "version": "1.0.0",
+  "description": "JACK (JSON Agent Contractor Kit): Pi extension for delegating to subagents under a JSON Schema contract, for structured, reliable, and type-safe agent responses.",
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "subagents",
+    "json-schema"
+  ],
+  "homepage": "https://github.com/adamjakab/pi-jack#readme",
+  "bugs": "https://github.com/adamjakab/pi-jack/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adamjakab/pi-jack.git"
+  },
+  "license": "MIT",
+  "author": "Adam Jakab",
+  "type": "module",
+  "main": "index.ts",
+  "exports": "./index.ts",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "index.ts",
+    "agents.ts",
+    "contract.ts",
+    "json-schema.ts",
+    "agents/",
+    "prompts/",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "prompts": [
+      "./prompts/*.md"
+    ]
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "node tests/e2e/run.ts",
+    "typecheck": "node scripts/pi-modules.mjs && tsc -p tsconfig.json",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.4",
+    "prettier": "^3.9.9",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  }
+}

package/prompts/jack-demo.md

@@ -0,0 +1,54 @@
+---
+description: Demo of jack, four read-only subagents surveying a folder in parallel
+argument-hint: "[path]"
+---
+
+# Subagents Demo
+
+Demonstrate the `jack` tool by surveying ${1:-the current folder} with multiple tasks carried out by independent agents.
+
+Call `jack` exactly **once**, with these parameters and nothing else:
+
+- debug_mode: false
+- run_mode: `parallel`
+- agent: `tester`
+- model: `stealth/space-bunny-alpha`
+- thinking: off
+- schema:
+
+  ```json
+  {
+    "type": "object",
+    "properties": {
+      "topic": {
+        "type": "string",
+        "description": "The topic name from the square brackets in your task, e.g. LAYOUT."
+      },
+      "findings": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "What you found, one self-contained item per entry."
+      },
+      "summary": {
+        "type": "string",
+        "description": "One or two sentences summing up the findings."
+      }
+    },
+    "required": ["topic", "findings", "summary"],
+    "additionalProperties": false
+  }
+  ```
+
+- `tasks` (topic names are in the square brackets):
+  - [LAYOUT] Layout of ${1:-the current folder}: list its top-level entries and say in a few words what each one is for.
+  - [FTYPE] File types in ${1:-the current folder}: count files per extension, ignoring .git and node_modules, and report the five most common.
+  - [NOTES] Open notes in ${1:-the current folder}: find TODO, FIXME and HACK comments, ignoring .git and node_modules, and report up to ten as "file:line: text".
+  - [DOCS] Docs in ${1:-the current folder}: read its README.md or AGENTS.md (whichever exists, top level only) and summarize what the project is in three findings. Use `medium` thinking level for this.
+
+Do not do any of this work yourself, before or after the call: the point is to watch the subagents do it.
+
+When the call returns, report:
+
+1. A table with one row per task: task number, topic, and ✓ or ✗.
+2. Each subagent's `summary` and `findings`, under its topic as a heading.
+3. For any failed task, its `error`.