@adibacsi/pi-jack 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[semantic versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+Nothing yet.
+
+## [1.0.0] - 2025-10-04
+
+First release.
+
+### Added
+
+- The `jack` tool: delegates a task, or a batch of tasks, to subagents that are isolated `pi` subprocesses and must
+  answer in a JSON Schema.
+- Named agents, resolved from the built-in `agents/` directory and from `~/.pi/agent/agents/`; a user's agent of the
+  same name replaces a built-in one. `worker` is the default, `tester` ships alongside it.
+- Per-call overrides for the agent's prompt (`system_prompt`), tools, model, and thinking level.
+- `run_mode: 'sequential' | 'parallel'` for batches, with live per-task progress and an optional `debug_mode` that
+  reports how each subagent was set up and the exact `pi` command line it ran with.
+- `--json-schema <file>`: makes any `pi` run finish with an answer conforming to a JSON Schema, through the
+  `jack_subagent_result` / `jack_subagent_fail` tools. This is how every subagent is started, and it works standalone.
+- A parent stops a child after `MAX_FORMAT_RETRIES` rejected answers, counting both Pi's own argument validation and
+  the tool's re-check.
+- The `/jack-demo` prompt template.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Jakab
+
+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,96 @@
+# JACK: JSON Agent Contractor Kit
+
+A [Pi](https://pi.dev) extension for getting structured answers from agents. It adds:
+
+- **The `jack` tool.** The model delegates one task, or a batch run sequentially or in parallel, to subagents.
+  Each subagent is an isolated `pi` process, and its answer conforms to a JSON Schema you choose.
+- **The `--json-schema <schema>` flag.** It makes any `pi` run finish with an answer that conforms to a schema. The
+  name matches Claude Code's flag for the same purpose.
+- **The `/jack-demo [path]` prompt.** Four subagents survey a folder in parallel while you watch.
+
+## Install
+
+```bash
+pi install npm:@adibacsi/pi-jack             # from npm
+pi install git:github.com/adamjakab/pi-jack   # from GitHub
+pi install /path/to/pi-jack                  # from a local checkout
+```
+
+You can also put the folder, or a symlink to it, in `~/.pi/agent/extensions/`.
+
+## The `jack` tool
+
+| Parameter                       | Meaning                                                                                                                                            |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `task`, or `tasks` + `run_mode` | One task, or a list run `sequential` (default) or `parallel`. Each item in `tasks` can override `agent`, `model`, `thinking` and the other fields. |
+| `agent`                         | A named agent (see below). Leave it out to use the default `worker` agent.                                                                         |
+| `schema`                        | The JSON Schema the answer must conform to: an object, inline JSON, or a path to a `.json` file.                                                   |
+| `model`                         | The model, as for `pi --model`. Overrides the agent's model.                                                                                       |
+| `thinking`                      | `off`, `low`, `medium`, `high`, `xhigh` or `max`. Overrides the agent's level.                                                                     |
+| `system_prompt`, `tools`        | Only apply when no agent is named: extra system prompt and a tool list for the default agent.                                                      |
+| `debug_mode`                    | Shows each subagent's resolved setup (agent, prompt, model, thinking, tools, schema, command line) and what it actually ran with.                  |
+
+The tool returns each subagent's validated answer as `data`, plus `success`, `error`, `attempts`, token usage, and
+`ranWith` (the model and thinking level the subagent actually used).
+
+### Thinking levels
+
+The level is passed to the subagent as `pi --thinking`. When the model doesn't support it, Pi uses the nearest
+higher level the model does support, or else the nearest lower one. Some models can't switch thinking off at all,
+so `off` runs at their lowest level.
+
+## Agents
+
+An agent is a Markdown file with YAML frontmatter. The body becomes the subagent's system prompt.
+
+```markdown
+---
+name: reviewer
+description: Reviews a diff and reports problems.
+tools: read, grep, find, ls
+model: openrouter/~anthropic/claude-haiku-latest
+thinking: medium
+schema: schemas/review.json
+---
+
+You review code changes...
+```
+
+`name` and `description` are required. `tools`, `model`, `thinking` and `schema` are optional. `schema` can be YAML,
+inline JSON, or a path relative to the agent file.
+
+- **Built-in agents** ship in this repo's `agents/` folder: `worker` (the default) and `tester`.
+- **Your agents** go in `~/.pi/agent/agents/`. One with the same name as a built-in agent replaces it.
+- **Broken files:** an agent file that fails to load is reported and skipped. A call that names it fails instead of
+  quietly falling back to another agent.
+
+## The output contract
+
+Every subagent answers in a JSON Schema. JACK picks the call's `schema`, else the agent's `schema`, else a default
+that asks for `success` (boolean) and `result` (string).
+
+- **Shape:** the root must describe an object.
+- **Descriptions:** each property's `description` is how the subagent learns what goes there, so write them carefully.
+- **Checked first:** a schema is checked before any subagent starts. Unknown keywords, unknown type names and
+  wrongly-shaped values (usually typos) are refused rather than silently ignored.
+
+The answer is collected through `--json-schema`. That flag gives the run a `jack_subagent_result` tool whose
+parameters are the schema, with provider-side constrained sampling where the provider supports it. It also adds a
+`jack_subagent_fail` tool for giving up with a reason.
+
+- **Invalid answers** are rejected with their errors, and the subagent fixes them in the same run.
+- **Missing answers:** a subagent that stops without answering is reminded to answer.
+- **Second check:** JACK validates the answer again in the parent. It stops a subagent after too many rejected answers.
+
+### `--json-schema` without the tool
+
+```bash
+pi --mode json -p --json-schema ./schema.json "Summarize this repository"
+pi --mode json -p --json-schema '{"type":"object","properties":{"answer":{"type":"string"}},"required":["answer"]}' "…"
+```
+
+The answer is `result.details` of the last successful `tool_execution_end` event for `jack_subagent_result`.
+
+## License
+
+[MIT](LICENSE)

package/agents/tester.md

@@ -0,0 +1,9 @@
+---
+name: tester
+description: Subagent for jack running in isolated context cabable of code validation.
+tools: read, bash, grep, find, ls
+---
+
+# Worker Agent
+
+You are a code verification agent with non-desturctive capabilities. You operate in an isolated context window to handle delegated tasks without polluting the main conversation. Work autonomously to complete the assigned task. Use all available tools as needed.

package/agents/worker.md

@@ -0,0 +1,11 @@
+---
+name: worker
+description: Default subagent for jack - General-purpose, full capabilities, isolated context.
+tools: read, bash, edit, write, grep, find, ls
+---
+
+# Worker Agent
+
+You are a worker agent with full capabilities. You operate in an isolated context window to handle
+delegated tasks without polluting the main conversation. Work autonomously to complete the assigned task.
+Use all available tools as needed.

package/agents.ts

@@ -0,0 +1,178 @@
+/**
+ * Agent discovery. Loads the agents built into this extension (its own `agents/` folder, e.g. the default `worker`)
+ * and the user's agents (~/.pi/agent/agents/*.md). A user agent with the same name as a built-in one replaces it.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import {
+  isThinkingLevel,
+  THINKING_LEVELS,
+  type ThinkingLevel,
+} from "./contract.ts";
+
+/** Folder of the agents that ship with this extension. */
+export const BUILT_IN_AGENTS_DIR = fileURLToPath(
+  new URL("./agents", import.meta.url),
+);
+
+/** Where an agent comes from: this extension, or the user's agents folder. */
+export type AgentSource = "built-in" | "user";
+
+export interface AgentConfig {
+  name: string;
+  description: string;
+  tools?: string[];
+  model?: string;
+  /** Default thinking level; pi moves an unsupported one to the nearest level the model supports. */
+  thinking?: ThinkingLevel;
+  /**
+   * Default output schema, used when the call doesn't pass one: a JSON Schema written as YAML, inline JSON, or a
+   * path to a `.json` file relative to `dir`. Resolved by contract.ts's resolveSchema().
+   */
+  schema?: unknown;
+  /** Folder of the agent file, which relative paths in its frontmatter resolve against. */
+  dir: string;
+  source: AgentSource;
+  /** Set on a user agent that replaces a built-in agent of the same name. */
+  overridesBuiltIn?: boolean;
+  systemPrompt: string;
+}
+
+function parseToolList(value: unknown): string[] | undefined {
+  const raw = Array.isArray(value)
+    ? value
+    : typeof value === "string"
+      ? value.split(",")
+      : [];
+  const tools = raw
+    .filter((t): t is string => typeof t === "string")
+    .map((t) => t.trim())
+    .filter(Boolean);
+  return tools.length > 0 ? tools : undefined;
+}
+
+function parseSchema(value: unknown): unknown {
+  if (typeof value === "string") return value.trim() || undefined;
+  if (value && typeof value === "object") return value;
+  return undefined;
+}
+
+/** An agent file that could not be loaded, and why. */
+export interface AgentLoadError {
+  /** The file's name, e.g. `worker.md`. */
+  file: string;
+  source: AgentSource;
+  message: string;
+}
+
+/**
+ * Loads the built-in agents, then the user's, which replace built-in agents of the same name. A file that can't be
+ * read or parsed is reported in `errors` instead of throwing, so one broken file never hides the others.
+ */
+export function discoverAgents(builtInDir = BUILT_IN_AGENTS_DIR): {
+  agents: AgentConfig[];
+  errors: AgentLoadError[];
+} {
+  const builtIn = loadAgentDir(builtInDir, "built-in");
+  const user = loadAgentDir(path.join(getAgentDir(), "agents"), "user");
+
+  const userNames = new Set(user.agents.map((a) => a.name));
+  const builtInNames = new Set(builtIn.agents.map((a) => a.name));
+  const agents = [
+    ...builtIn.agents.filter((a) => !userNames.has(a.name)),
+    ...user.agents.map((a) =>
+      builtInNames.has(a.name) ? { ...a, overridesBuiltIn: true } : a,
+    ),
+  ];
+  return { agents, errors: [...builtIn.errors, ...user.errors] };
+}
+
+function loadAgentDir(
+  dir: string,
+  source: AgentSource,
+): { agents: AgentConfig[]; errors: AgentLoadError[] } {
+  const agents: AgentConfig[] = [];
+  const errors: AgentLoadError[] = [];
+
+  if (!fs.existsSync(dir)) return { agents, errors };
+
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (e) {
+    errors.push({
+      file: dir,
+      source,
+      message: e instanceof Error ? e.message : String(e),
+    });
+    return { agents, errors };
+  }
+
+  for (const entry of entries) {
+    if (!entry.name.endsWith(".md")) continue;
+    if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+
+    const filePath = path.join(dir, entry.name);
+    let parsed;
+    try {
+      parsed = parseFrontmatter<{
+        name?: unknown;
+        description?: unknown;
+        tools?: unknown;
+        model?: unknown;
+        thinking?: unknown;
+        schema?: unknown;
+      }>(fs.readFileSync(filePath, "utf-8"));
+    } catch (e) {
+      // Keep only the first line: YAML errors go on to draw the offending line with a caret.
+      const message = (e instanceof Error ? e.message : String(e))
+        .split("\n")[0]
+        .replace(/:$/, "");
+      errors.push({ file: entry.name, source, message });
+      continue;
+    }
+    const { frontmatter, body } = parsed;
+
+    if (
+      typeof frontmatter.name !== "string" ||
+      typeof frontmatter.description !== "string"
+    ) {
+      errors.push({
+        file: entry.name,
+        source,
+        message: "the frontmatter needs a `name` and a `description`",
+      });
+      continue;
+    }
+    if (
+      frontmatter.thinking !== undefined &&
+      !isThinkingLevel(frontmatter.thinking)
+    ) {
+      const levels = THINKING_LEVELS.join(", ");
+      errors.push({
+        file: entry.name,
+        source,
+        message: `\`thinking\` must be one of ${levels}`,
+      });
+      continue;
+    }
+
+    agents.push({
+      name: frontmatter.name,
+      description: frontmatter.description,
+      tools: parseToolList(frontmatter.tools),
+      model:
+        typeof frontmatter.model === "string" ? frontmatter.model : undefined,
+      thinking: frontmatter.thinking,
+      schema: parseSchema(frontmatter.schema),
+      dir,
+      source,
+      systemPrompt: body,
+    });
+  }
+
+  return { agents, errors };
+}

package/contract.ts

@@ -0,0 +1,278 @@
+/**
+ * The output contract between jack (the parent) and its subagents (child pi processes).
+ *
+ * A subagent answers by calling the `jack_subagent_result` tool, whose parameters are the run's JSON Schema, so each
+ * field's `description` reaches the model right where it fills that field. It gives up by calling `jack_subagent_fail`
+ * with a reason instead. Both tools live in json-schema.ts, behind the `--json-schema` flag; this module holds
+ * what both sides share: the tool names, the default schema, schema loading, validation, and thinking levels.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { TSchema } from "typebox";
+import { Value } from "typebox/value";
+
+/** Tool a subagent calls with its answer; its parameters are the run's schema. */
+export const RESULT_TOOL = "jack_subagent_result";
+
+/** Tool a subagent calls, instead of RESULT_TOOL, when it cannot complete the task. */
+export const FAIL_TOOL = "jack_subagent_fail";
+
+/**
+ * CLI flag, registered by json-schema.ts, holding the JSON Schema the final answer must conform to. Named like Claude
+ * Code's flag of the same purpose. The parent passes each child the path of its schema file with it.
+ */
+export const SCHEMA_FLAG = "json-schema";
+
+/**
+ * Thinking levels a subagent can be asked for, lowest first. They are passed to the child as `--thinking`; for a
+ * level the model doesn't support, pi uses the nearest higher level it does, else the nearest lower one.
+ */
+export const THINKING_LEVELS = [
+  "off",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+] as const;
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+
+export const isThinkingLevel = (value: unknown): value is ThinkingLevel =>
+  THINKING_LEVELS.includes(value as ThinkingLevel);
+
+/**
+ * How many invalid answers or nudges a subagent gets after its first try. An invalid `jack_subagent_result` call is
+ * thrown back with its errors so the model can fix it; finishing without calling either tool earns a nudge.
+ */
+export const MAX_FORMAT_RETRIES = 2;
+
+/** Schema used when neither the call nor the agent gives one. */
+export const DEFAULT_SCHEMA = {
+  type: "object",
+  properties: {
+    success: {
+      type: "boolean",
+      description:
+        "True only when all requested operations were finished and nothing is left to do.",
+    },
+    result: {
+      type: "string",
+      description:
+        "A concise description of what was found or achieved during this session.",
+    },
+  },
+  required: ["success", "result"],
+  additionalProperties: true,
+} as const;
+
+/**
+ * Turns a schema given as an object, inline JSON, or a path to a `.json` file into a JSON Schema object.
+ * Relative paths resolve against `baseDir`. Tool parameters must be an object, so the root must describe one.
+ * Throws with a message fit for the caller when the schema can't be used.
+ */
+export function resolveSchema(value: unknown, baseDir: string): TSchema {
+  let schema = value;
+  if (typeof value === "string") {
+    const text = value.trim();
+    if (!text) throw new Error("the schema is empty");
+    if (text.startsWith("{")) {
+      try {
+        schema = JSON.parse(text);
+      } catch (e) {
+        throw new Error(
+          `the inline schema is not valid JSON (${e instanceof Error ? e.message : e})`,
+        );
+      }
+    } else {
+      const filePath = path.resolve(baseDir, text);
+      try {
+        schema = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+      } catch (e) {
+        throw new Error(
+          `could not load the schema file ${filePath} (${e instanceof Error ? e.message : e})`,
+        );
+      }
+    }
+  }
+
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+    throw new Error("the schema must be a JSON Schema object");
+  }
+  const root = schema as Record<string, unknown>;
+  if (root.type !== "object" && root.properties === undefined) {
+    throw new Error(
+      'the root of the schema must describe an object, e.g. {"type": "object", "properties": {...}}',
+    );
+  }
+  const problems = schemaProblems(root);
+  if (problems.length > 0) throw new Error(problems.slice(0, 10).join("; "));
+  return root as TSchema;
+}
+
+const JSON_TYPES = [
+  "string",
+  "number",
+  "integer",
+  "boolean",
+  "object",
+  "array",
+  "null",
+];
+
+type Check = (value: unknown, at: string) => string[];
+
+const isObject = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+const must = (ok: boolean, at: string, what: string): string[] =>
+  ok ? [] : [`${at}: must be ${what}`];
+
+const isString: Check = (v, at) => must(typeof v === "string", at, "a string");
+const isNumber: Check = (v, at) =>
+  must(typeof v === "number" && Number.isFinite(v), at, "a number");
+const isCount: Check = (v, at) =>
+  must(Number.isInteger(v) && (v as number) >= 0, at, "a non-negative integer");
+const isBoolean: Check = (v, at) =>
+  must(typeof v === "boolean", at, "true or false");
+const isAny: Check = () => [];
+const isSchema: Check = (v, at) => schemaProblems(v, at);
+const isSchemaOrBoolean: Check = (v, at) =>
+  typeof v === "boolean" ? [] : schemaProblems(v, at);
+const isStringList: Check = (v, at) =>
+  must(
+    Array.isArray(v) && v.every((x) => typeof x === "string"),
+    at,
+    "a list of strings",
+  );
+const isSchemaList: Check = (v, at) =>
+  Array.isArray(v) && v.length > 0
+    ? v.flatMap((x, i) => schemaProblems(x, `${at}/${i}`))
+    : [`${at}: must be a non-empty list of schemas`];
+const isSchemaMap: Check = (v, at) =>
+  isObject(v)
+    ? Object.entries(v).flatMap(([k, x]) => schemaProblems(x, `${at}/${k}`))
+    : [`${at}: must be an object`];
+
+const isType: Check = (v, at) => {
+  const names = Array.isArray(v) ? v : [v];
+  if (names.length === 0) return [`${at}: must name at least one type`];
+  return names.flatMap((name) =>
+    typeof name === "string" && JSON_TYPES.includes(name)
+      ? []
+      : [
+          `${at}: ${JSON.stringify(name)} is not a JSON Schema type (use ${JSON_TYPES.join(", ")})`,
+        ],
+  );
+};
+
+const isPattern: Check = (v, at) => {
+  if (typeof v !== "string") return [`${at}: must be a string`];
+  try {
+    new RegExp(v, "u");
+    return [];
+  } catch (e) {
+    return [
+      `${at}: is not a valid regular expression (${e instanceof Error ? e.message : e})`,
+    ];
+  }
+};
+
+/** The JSON Schema keywords accepted, each with a check of its value. Anything else is reported as unknown. */
+const KEYWORDS: Record<string, Check> = {
+  // Identity and annotations
+  $schema: isString,
+  $id: isString,
+  $ref: isString,
+  $comment: isString,
+  $defs: isSchemaMap,
+  definitions: isSchemaMap,
+  title: isString,
+  description: isString,
+  default: isAny,
+  examples: (v, at) => must(Array.isArray(v), at, "a list"),
+  deprecated: isBoolean,
+  readOnly: isBoolean,
+  writeOnly: isBoolean,
+  // Any type
+  type: isType,
+  enum: (v, at) =>
+    must(Array.isArray(v) && v.length > 0, at, "a non-empty list"),
+  const: isAny,
+  allOf: isSchemaList,
+  anyOf: isSchemaList,
+  oneOf: isSchemaList,
+  not: isSchema,
+  if: isSchema,
+  then: isSchema,
+  else: isSchema,
+  // Objects
+  properties: isSchemaMap,
+  patternProperties: isSchemaMap,
+  additionalProperties: isSchemaOrBoolean,
+  unevaluatedProperties: isSchemaOrBoolean,
+  propertyNames: isSchema,
+  required: isStringList,
+  minProperties: isCount,
+  maxProperties: isCount,
+  dependentRequired: (v, at) =>
+    isObject(v)
+      ? Object.entries(v).flatMap(([k, x]) => isStringList(x, `${at}/${k}`))
+      : [`${at}: must be an object`],
+  dependentSchemas: isSchemaMap,
+  // Arrays
+  items: (v, at) =>
+    Array.isArray(v) ? isSchemaList(v, at) : isSchemaOrBoolean(v, at),
+  prefixItems: isSchemaList,
+  additionalItems: isSchemaOrBoolean,
+  unevaluatedItems: isSchemaOrBoolean,
+  contains: isSchema,
+  minContains: isCount,
+  maxContains: isCount,
+  minItems: isCount,
+  maxItems: isCount,
+  uniqueItems: isBoolean,
+  // Strings
+  minLength: isCount,
+  maxLength: isCount,
+  pattern: isPattern,
+  format: isString,
+  contentEncoding: isString,
+  contentMediaType: isString,
+  // Numbers
+  minimum: isNumber,
+  maximum: isNumber,
+  exclusiveMinimum: isNumber,
+  exclusiveMaximum: isNumber,
+  multipleOf: (v, at) =>
+    must(typeof v === "number" && v > 0, at, "a positive number"),
+};
+
+/**
+ * Checks that `schema` is well-formed JSON Schema, as "/path: problem" lines; empty when it is.
+ *
+ * Validators silently ignore what they don't understand, so a typo like `"type": "strin"` or `"requried"` would
+ * otherwise turn a rule into no rule at all. This catches those before a subagent is started: unknown keywords,
+ * unknown type names, and keyword values of the wrong shape, recursively.
+ */
+export function schemaProblems(schema: unknown, at = ""): string[] {
+  if (!isObject(schema)) return [`${at || "/"}: a schema must be an object`];
+  return Object.entries(schema).flatMap(([keyword, value]) => {
+    const check = KEYWORDS[keyword];
+    const here = `${at}/${keyword}`;
+    return check
+      ? check(value, here)
+      : [`${here}: unknown JSON Schema keyword`];
+  });
+}
+
+/** Lists how `value` breaks `schema`, as "/path: message" lines (at most 10); empty when it conforms. */
+export function schemaErrors(schema: TSchema, value: unknown): string[] {
+  return [...Value.Errors(schema, value)].slice(0, 10).map((e) => {
+    // TypeBox reports a property that `additionalProperties: false` forbids as "schema is false".
+    const message =
+      e.message === "schema is false"
+        ? "property not allowed by the schema"
+        : e.message;
+    return `${e.instancePath || "/"}: ${message}`;
+  });
+}