@cr1ms0n/pi-subagent 0.8.1

package/src/schema.ts

@@ -0,0 +1,166 @@
+import { Type, type Static } from "typebox";
+
+const ThinkingLevel = Type.Union([
+  Type.Literal("off"),
+  Type.Literal("minimal"),
+  Type.Literal("low"),
+  Type.Literal("medium"),
+  Type.Literal("high"),
+  Type.Literal("xhigh"),
+]);
+
+const OutputMode = Type.Union([Type.Literal("inline"), Type.Literal("file-only")]);
+const Profile = Type.Union([Type.Literal("explore"), Type.Literal("review"), Type.Literal("general")]);
+const Isolation = Type.Union([Type.Literal("shared"), Type.Literal("worktree")]);
+const Backend = Type.Union([Type.Literal("pi"), Type.Literal("codex"), Type.Literal("claude")]);
+const Action = Type.Union([
+  Type.Literal("status"),
+  Type.Literal("wait"),
+  Type.Literal("cancel"),
+  Type.Literal("steer"),
+  Type.Literal("diff"),
+  Type.Literal("apply"),
+  Type.Literal("discard"),
+  Type.Literal("plan"),
+]);
+
+/** Shared optional task configuration fields. */
+export const TaskFields = {
+  backend: Type.Optional({ ...Backend, description: "Agent CLI powering the child. pi (default) supports every feature. codex uses codex exec with an OS-level read-only sandbox, but reports no cost (max_cost is refused) and cannot be steered. claude uses the claude CLI, reports cost, and cannot be steered. Unsupported combinations are refused with an explanation rather than silently ignored." }),
+  agent: Type.Optional(Type.String({ minLength: 1, description: "Named agent to use (from .pi/agents/<name>.md). Supplies persona system prompt and defaults; explicit params still override." })),
+  description: Type.Optional(Type.String({ description: "Short human label (3-5 words) shown in UIs and result indexes." })),
+  system_prompt: Type.Optional(Type.String({ description: "Extra system prompt appended to the child's prompt (does not replace it)." })),
+  model: Type.Optional(Type.String({ description: "**REQUIRED for every spawn call (task/tasks).** Exact model id from modelPolicy, in provider/model-id form. Calls without an explicit model are rejected; agent-file model, taskDefaults, and parent-session inheritance are ignored. Management actions (status/wait/cancel/steer/diff/apply/discard) do not need it." })),
+  thinking: Type.Optional({ ...ThinkingLevel, description: "Reasoning effort for the child. Defaults to profile config default, then the parent's level." }),
+  tools: Type.Optional(Type.Array(Type.String(), { description: "Optional tool allowlist. explore/review profiles reject write-capable tools." })),
+  profile: Type.Optional({ ...Profile, description: "Capability profile: explore/review are strictly read-only; general inherits the parent's active tools and may write." }),
+  cwd: Type.Optional(Type.String({ description: "Working directory for the child process." })),
+  timeout_ms: Type.Optional(Type.Number({ minimum: 1, maximum: 24 * 60 * 60_000, description: "Total budget in milliseconds including queue time. Timed-out runs report which phase timed out." })),
+  max_turns: Type.Optional(Type.Number({ minimum: 1, maximum: 500, description: "Budget: at this many turns the child is steered to wrap up and given grace turns for a final answer; ends as 'partial' with output preserved." })),
+  max_cost: Type.Optional(Type.Number({ minimum: 0, description: "Soft cost ceiling in dollars; checked after each turn, triggers the same wrap-up flow as max_turns." })),
+  grace_turns: Type.Optional(Type.Number({ minimum: 0, maximum: 20, description: "Wrap-up turns allowed after a budget breach before hard stop. 0 = immediate stop. Default from config (2)." })),
+  fallback_models: Type.Optional(Type.Array(Type.String(), { maxItems: 5, description: "Ordered backup models tried automatically on transient failures (provider error, stall, queue timeout)." })),
+  max_retries: Type.Optional(Type.Number({ minimum: 0, maximum: 5, description: "Extra attempts on transient failures. Defaults to config maxRetries (1). Task-quality failures never retry." })),
+  context: Type.Optional(
+    Type.Union([Type.Literal("fresh"), Type.Literal("fork")], {
+      description: "fork starts the child from a branched copy of the parent conversation (needs a persisted parent session); fresh (default) starts clean. Fork is single-task only.",
+    }),
+  ),
+  output: Type.Optional(Type.String({ description: "File path to write final output." })),
+  output_schema: Type.Optional(
+    Type.Unsafe<Record<string, unknown>>(
+      Type.Object({}, {
+        additionalProperties: true,
+        description: "JSON Schema the child's final result must satisfy. The child ends with a fenced json:result block; validation failures get one steer-based repair round, then end 'partial' with the errors reported.",
+      }),
+    ),
+  ),
+  output_mode: Type.Optional({ ...OutputMode, description: "file-only returns a pointer instead of inline text; use for large reports." }),
+  resume: Type.Optional(Type.String({ description: "Child session id to continue." })),
+  fork_resume: Type.Optional(Type.Boolean({ description: "Fork the resumed session instead of direct resume." })),
+  isolation: Type.Optional({ ...Isolation, description: "worktree runs the task in an isolated git worktree; changed work is preserved on a branch." }),
+  include_wip: Type.Optional(
+    Type.Boolean({ description: "Seed a worktree with the parent checkout's uncommitted changes (staged + unstaged + untracked). Only valid with isolation:'worktree'." }),
+  ),
+  allow_shared_writes: Type.Optional(
+    Type.Boolean({ description: "Unsafe opt-in for parallel writers sharing one checkout." }),
+  ),
+  keep_background: Type.Optional(
+    Type.Boolean({ description: "Keep processes the child backgrounded (e.g. dev servers) alive after a clean exit." }),
+  ),
+} as const;
+
+export const ParallelTaskItem = Type.Object(
+  {
+    task: Type.String({ minLength: 1, description: "Task text for one parallel worker." }),
+    ...TaskFields,
+  },
+  { additionalProperties: false },
+);
+
+/**
+ * Provider-facing tool parameters.
+ *
+ * IMPORTANT: LLM tool APIs (OpenAI-compatible / OpenRouter / Anthropic via many
+ * providers) require the top-level parameters schema to be JSON Schema
+ * `type: "object"`. A Type.Union serializes as `anyOf` without `type: "object"`,
+ * which surfaces as:
+ *   Invalid schema for function 'subagent': schema must be a JSON Schema of
+ *   'type: "object"', got 'type: "None"'.
+ *
+ * Mode exclusivity (action vs task vs tasks) is enforced in policy validation,
+ * not at the JSON Schema layer.
+ */
+export const SubagentParamsSchema = Type.Object(
+  {
+    // Management actions
+    action: Type.Optional({ ...Action, description: "Management action on an existing run: status, wait, cancel, steer (inject guidance into a running child), diff/apply/discard (worktree results). action:\"plan\" dry-runs validation + preflight with task/tasks — no spawn." }),
+    id: Type.Optional(Type.String({ minLength: 1, description: "Run id (or unique prefix) for management actions." })),
+    message: Type.Optional(Type.String({ minLength: 1, description: "Steering message injected into the running child (action: steer)." })),
+    index: Type.Optional(Type.Number({ minimum: 0, description: "Task index within a parallel run for steer/diff/apply/discard. Defaults to the only eligible task." })),
+
+    // Single-task mode
+    task: Type.Optional(Type.String({ minLength: 1, description: "Task to delegate (single mode)." })),
+    ...TaskFields,
+    async: Type.Optional(Type.Boolean({ description: "Run in the background and return a handle immediately." })),
+
+    // Parallel mode
+    tasks: Type.Optional(
+      Type.Array(ParallelTaskItem, {
+        minItems: 1,
+        maxItems: 8,
+        description: "Array of independent tasks for parallel mode. Parallel tasks default to the read-only explore profile; parallel writers need isolation:'worktree'.",
+      }),
+    ),
+    synthesis: Type.Optional(
+      Type.String({
+        minLength: 1,
+        description: "Optional synthesis prompt for parallel mode: after all tasks finish, one read-only child folds their outputs using this instruction and its result is delivered first.",
+      }),
+    ),
+  },
+  {
+    additionalProperties: false,
+    description: "Subagent request: single, parallel, status, wait, or cancel.",
+  },
+);
+
+export type SubagentParams = Static<typeof SubagentParamsSchema>;
+export type ParallelTaskInput = Static<typeof ParallelTaskItem>;
+
+/**
+ * Dedicated blocking-wait tool.
+ *
+ * `subagent` already exposes wait via `action: "wait"`, but collecting a
+ * background run is the one management step a model reaches for reflexively
+ * mid-flow, and burying it behind an action union costs a discovery step.
+ * This mirrors the highest-adoption package in the ecosystem (`pi-subagents`
+ * ships `subagent` + `subagent_wait` for the same reason). It is a thin
+ * front-end over the identical handler — no second delivery path.
+ */
+export const SubagentWaitParamsSchema = Type.Object(
+  {
+    id: Type.String({ minLength: 1, description: "Run id (or unique prefix) of the background run to collect." }),
+    timeout_ms: Type.Optional(
+      Type.Number({
+        minimum: 1,
+        maximum: 24 * 60 * 60_000,
+        description: "Give up waiting after this long and return a still-running notice. The run is NOT cancelled; collect it later with subagent_wait or action:'status'. Omit to wait until the run settles.",
+      }),
+    ),
+  },
+  {
+    additionalProperties: false,
+    description: "Block until a background subagent run settles, then deliver its output.",
+  },
+);
+
+export type SubagentWaitParams = Static<typeof SubagentWaitParamsSchema>;
+
+/** Runtime guard used by tests/docs to assert provider compatibility. */
+export function assertObjectToolSchema(schema: unknown): asserts schema is { type: "object" } {
+  if (!schema || typeof schema !== "object" || (schema as { type?: unknown }).type !== "object") {
+    const type = schema && typeof schema === "object" ? (schema as { type?: unknown }).type : typeof schema;
+    throw new Error(`Tool parameters must be JSON Schema type "object", got ${JSON.stringify(type ?? "None")}`);
+  }
+}

package/src/semaphore.ts

@@ -0,0 +1,123 @@
+/**
+ * Fair, abort-aware semaphore for limiting concurrent Pi subagent processes.
+ *
+ * - maxActive: maximum concurrent processes
+ * - maxQueued: maximum tasks waiting for a slot
+ * - FIFO queue
+ * - Aborted waiters are removed without ever starting work
+ */
+export class Semaphore {
+  private readonly maxActive: number;
+  private readonly maxQueued: number;
+  private active = 0;
+  private queue: Array<{
+    resolve: () => void;
+    reject: (reason?: unknown) => void;
+    onAbort?: () => void;
+    signal?: AbortSignal;
+  }> = [];
+  private releaseListeners = new Set<() => void>();
+
+  constructor(maxActive = 4, maxQueued = 32) {
+    this.maxActive = Math.max(1, maxActive);
+    this.maxQueued = Math.max(0, maxQueued);
+  }
+
+  /**
+   * Acquire a slot. Rejects immediately if the queue is full.
+   * If `signal` is already aborted (or aborts while waiting), rejects without starting work.
+   */
+  async acquire(signal?: AbortSignal): Promise<void> {
+    if (signal?.aborted) {
+      throw new Error("Semaphore acquisition aborted before enqueue");
+    }
+
+    if (this.active < this.maxActive) {
+      this.active++;
+      return;
+    }
+
+    if (this.queue.length >= this.maxQueued) {
+      throw new Error(`Semaphore queue full (${this.maxQueued})`);
+    }
+
+    return new Promise<void>((resolve, reject) => {
+      const entry: {
+        resolve: () => void;
+        reject: (reason?: unknown) => void;
+        onAbort?: () => void;
+        signal?: AbortSignal;
+      } = {
+        resolve: () => {
+          this.detachAbort(entry);
+          resolve();
+        },
+        reject: (reason?: unknown) => {
+          this.detachAbort(entry);
+          reject(reason);
+        },
+        signal,
+      };
+
+      if (signal) {
+        entry.onAbort = () => {
+          const idx = this.queue.indexOf(entry);
+          if (idx === -1) return;
+          this.queue.splice(idx, 1);
+          entry.reject(new Error("Semaphore acquisition aborted before spawn"));
+        };
+        signal.addEventListener("abort", entry.onAbort, { once: true });
+      }
+
+      this.queue.push(entry);
+    });
+  }
+
+  /** Release a slot and wake the next non-aborted waiter. */
+  release(): void {
+    this.active = Math.max(0, this.active - 1);
+
+    while (this.queue.length > 0 && this.active < this.maxActive) {
+      const next = this.queue.shift()!;
+      if (next.signal?.aborted) {
+        next.reject(new Error("Semaphore acquisition aborted before spawn"));
+        continue;
+      }
+      this.active++;
+      next.resolve();
+      break;
+    }
+
+    for (const listener of this.releaseListeners) listener();
+  }
+
+  /** Lightweight EventEmitter-compatible API used by tests. */
+  on(event: "release", listener: () => void): this {
+    if (event === "release") this.releaseListeners.add(listener);
+    return this;
+  }
+
+  off(event: "release", listener: () => void): this {
+    if (event === "release") this.releaseListeners.delete(listener);
+    return this;
+  }
+
+  getStats() {
+    return {
+      active: this.active,
+      queued: this.queue.length,
+      maxActive: this.maxActive,
+      maxQueued: this.maxQueued,
+    };
+  }
+
+  private detachAbort(entry: {
+    onAbort?: () => void;
+    signal?: AbortSignal;
+  }): void {
+    if (entry.signal && entry.onAbort) {
+      entry.signal.removeEventListener("abort", entry.onAbort);
+    }
+    entry.onAbort = undefined;
+  }
+}

package/src/structured.ts

@@ -0,0 +1,169 @@
+/**
+ * Structured output contract: a task may declare an `output_schema` (JSON
+ * Schema subset). The child is instructed to end its final message with a
+ * fenced ```json:result block; the parent extracts and validates it on this
+ * side of the process boundary.
+ *
+ * Validation is a dependency-free JSON-Schema *subset* (type / properties /
+ * required / items / enum / const / nested combinations). Unknown keywords are
+ * ignored rather than rejected so callers can pass richer schemas; we enforce
+ * what we understand and never fail on what we don't.
+ */
+
+export interface SchemaCheckResult {
+  ok: boolean;
+  errors: string[];
+}
+
+const TYPE_CHECKS: Record<string, (value: unknown) => boolean> = {
+  object: (value) => typeof value === "object" && value !== null && !Array.isArray(value),
+  array: (value) => Array.isArray(value),
+  string: (value) => typeof value === "string",
+  number: (value) => typeof value === "number" && Number.isFinite(value),
+  integer: (value) => typeof value === "number" && Number.isInteger(value),
+  boolean: (value) => typeof value === "boolean",
+  null: (value) => value === null,
+};
+
+/** Validate that a caller-supplied schema is a plausible JSON Schema object. */
+export function isPlausibleSchema(schema: unknown): schema is Record<string, unknown> {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) return false;
+  const s = schema as Record<string, unknown>;
+  if (s.type !== undefined && typeof s.type !== "string" && !Array.isArray(s.type)) return false;
+  if (s.properties !== undefined && (typeof s.properties !== "object" || s.properties === null)) return false;
+  if (s.required !== undefined && !Array.isArray(s.required)) return false;
+  return true;
+}
+
+/** Structural validation against the supported JSON-Schema subset. */
+export function checkAgainstSchema(value: unknown, schema: unknown, path = "$"): SchemaCheckResult {
+  const errors: string[] = [];
+  if (!schema || typeof schema !== "object") return { ok: true, errors };
+  const s = schema as Record<string, any>;
+
+  if (s.const !== undefined && JSON.stringify(value) !== JSON.stringify(s.const)) {
+    errors.push(`${path}: expected const ${JSON.stringify(s.const)}`);
+  }
+  if (Array.isArray(s.enum) && !s.enum.some((candidate: unknown) => JSON.stringify(candidate) === JSON.stringify(value))) {
+    errors.push(`${path}: value not in enum [${s.enum.map((e: unknown) => JSON.stringify(e)).join(", ")}]`);
+  }
+
+  const types: string[] = typeof s.type === "string" ? [s.type] : Array.isArray(s.type) ? s.type : [];
+  if (types.length) {
+    const matched = types.some((type) => TYPE_CHECKS[type]?.(value));
+    if (!matched) {
+      errors.push(`${path}: expected type ${types.join("|")}, got ${Array.isArray(value) ? "array" : value === null ? "null" : typeof value}`);
+      return { ok: false, errors }; // wrong type: nested checks would be noise
+    }
+  }
+
+  if (TYPE_CHECKS.object(value)) {
+    const record = value as Record<string, unknown>;
+    for (const key of Array.isArray(s.required) ? s.required : []) {
+      if (typeof key === "string" && !(key in record)) errors.push(`${path}: missing required property "${key}"`);
+    }
+    if (s.properties && typeof s.properties === "object") {
+      for (const [key, propSchema] of Object.entries(s.properties as Record<string, unknown>)) {
+        if (key in record) {
+          errors.push(...checkAgainstSchema(record[key], propSchema, `${path}.${key}`).errors);
+        }
+      }
+    }
+  }
+
+  if (Array.isArray(value) && s.items && typeof s.items === "object" && !Array.isArray(s.items)) {
+    value.forEach((item, index) => {
+      errors.push(...checkAgainstSchema(item, s.items, `${path}[${index}]`).errors);
+    });
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * Extract the structured result from the child's final assistant text.
+ * Preference order: last ```json:result fence → last plain ```json fence →
+ * trailing bare JSON object/array. Returns undefined when nothing parses.
+ */
+export function extractStructuredResult(text: string | undefined): { value?: unknown; raw?: string } {
+  if (!text) return {};
+  const fences = [/```json:result\s*\n([\s\S]*?)```/g, /```json\s*\n([\s\S]*?)```/g];
+  for (const pattern of fences) {
+    let last: string | undefined;
+    for (const match of text.matchAll(pattern)) last = match[1];
+    if (last !== undefined) {
+      try {
+        return { value: JSON.parse(last), raw: last.trim() };
+      } catch {
+        return { raw: last.trim() }; // fence found but unparseable: report it
+      }
+    }
+  }
+  // Trailing bare JSON object/array (last non-empty chunk starting with { or [).
+  const trimmed = text.trimEnd();
+  const start = Math.max(trimmed.lastIndexOf("\n{"), trimmed.lastIndexOf("\n["));
+  const candidate = start >= 0 ? trimmed.slice(start + 1) : trimmed.startsWith("{") || trimmed.startsWith("[") ? trimmed : undefined;
+  if (candidate) {
+    try {
+      return { value: JSON.parse(candidate), raw: candidate };
+    } catch {
+      /* not JSON */
+    }
+  }
+  return {};
+}
+
+/** The contract appended to the child's system prompt (after the persona). */
+export function schemaContract(schema: Record<string, unknown>): string {
+  return [
+    "STRUCTURED OUTPUT CONTRACT",
+    "Your FINAL message MUST end with a fenced code block tagged json:result containing ONLY a JSON value that validates against this schema:",
+    "```json",
+    JSON.stringify(schema, null, 2),
+    "```",
+    "Rules: the fenced block is your machine-readable result — narrative goes before it, never inside. Do not wrap the JSON in prose or stringify it. Example shape:",
+    "```json:result",
+    '{ "your": "result here" }',
+    "```",
+  ].join("\n");
+}
+
+/** Steering message for one repair round after failed validation. */
+export function repairMessage(errors: string[]): string {
+  const detail = errors.slice(0, 10).join("; ");
+  return (
+    `Your structured result failed validation: ${detail}. ` +
+    "Re-emit your COMPLETE final result now as a single fenced ```json:result block that validates against the schema from your instructions. Output only the corrected block."
+  );
+}
+
+// ── Arg repair (double-encoded JSON de-mangling) ─────────────────────────────
+
+/**
+ * LLMs sometimes double-encode natural-language string fields (the value
+ * arrives as a JSON-string-inside-a-string: `"line1\\nline2"` with literal
+ * backslash escapes). Detect structural escape patterns and decode ONCE when
+ * the decoded form is a plausible improvement. Never applied to identifier
+ * fields (agent, model, id) or arrays — only free-text fields.
+ */
+export function repairDoubleEncodedText(value: string): string {
+  if (value.length < 4) return value;
+  // High-signal escapes only: literal \n or \" strongly indicate a
+  // JSON-string-inside-a-string. \t and \\ alone are NOT sufficient — they
+  // occur naturally in Windows paths (C:\temp) and regex/code snippets.
+  const highSignal = /\\n|\\"/.test(value);
+  if (!highSignal) return value;
+  const hasRealNewlines = value.includes("\n");
+  if (hasRealNewlines) return value; // mixed content: too ambiguous, leave it
+  // A lone backslash before a non-escape char (e.g. C:\Users mixed with \n)
+  // would make JSON.parse fail or corrupt — require every backslash to start
+  // a valid JSON escape sequence.
+  if (/\\(?![nrtbf"\\/u])/.test(value)) return value;
+  try {
+    const decoded = JSON.parse(`"${value.replace(/(?<!\\)"/g, '\\"')}"`);
+    if (typeof decoded === "string" && decoded !== value && decoded.length > 0) return decoded;
+  } catch {
+    /* not decodable: leave as-is */
+  }
+  return value;
+}