@herbertgao/pi-subagents 0.17.1 → 0.18.0

package/src/workflow/json-schema.ts

@@ -0,0 +1,142 @@
+/**
+ * json-schema.ts — validating a script-supplied JSON Schema.
+ *
+ * `agent(prompt, { schema })` hands us a raw JSON Schema written by a model, to
+ * be used two ways: as a tool's `parameters` (so the provider fills the fields)
+ * and as the check that decides whether what came back is usable.
+ *
+ * ## Which typebox
+ *
+ * **`typebox`, not `@sinclair/typebox`.** They are different packages and both
+ * are installed here. `@sinclair/typebox` (0.34) dispatches on a `Kind` symbol
+ * that a schema arriving over the wire does not carry, so `Value.Check` throws
+ * `Unknown type` on a plain JSON Schema — and `Type.Unsafe` does not help, it
+ * stamps a `Kind` that is not registered. `typebox` v1 is a standards JSON
+ * Schema validator and takes the schema as-is. It is also the package pi itself
+ * types `ToolDefinition.parameters` against, so the same schema object serves
+ * both roles with no conversion.
+ *
+ * ## Why we validate at all
+ *
+ * Nothing in pi checks a tool call's arguments against the tool's `parameters`.
+ * `validateToolCall`/`validateToolArguments` exist in `pi-ai` but are never
+ * called from either shipped package, so a schema on a tool is a *prompt to the
+ * provider*, not an enforcement point. Every guarantee the script gets about
+ * the shape of its result is made here.
+ *
+ * Pure and pi-free on purpose, so `runtime.ts` can import it without dragging
+ * sessions and models into the runtime's tests.
+ */
+
+import { Check, Errors } from "typebox/value"
+
+/** Largest schema we will accept, serialized. */
+const MAX_SCHEMA_BYTES = 64 * 1024
+
+/** How many validation errors are quoted back to the model. */
+const MAX_REPORTED_ERRORS = 5
+
+export interface CompiledSchema {
+  /** The schema as given, for the tool's `parameters` and the journal key. */
+  readonly schema: Record<string, unknown>
+  /** `true`, or a human-readable account of what is wrong. */
+  check(value: unknown): true | string
+}
+
+export type SchemaCompilation =
+  | { ok: true; compiled: CompiledSchema }
+  | { ok: false; message: string }
+
+/**
+ * Turn a script-supplied schema into something we can check against.
+ *
+ * Rejects up front rather than at the first tool call. A schema whose root is
+ * not an object cannot be a tool's input schema at all, so it would break every
+ * request the child makes rather than just the last one — and the author should
+ * hear about that before a model is paid to discover it.
+ */
+export function compileJsonSchema(schema: unknown): SchemaCompilation {
+  if (typeof schema !== "object" || schema === null || Array.isArray(schema)) {
+    return {
+      ok: false,
+      message: "agent() opts.schema must be a JSON Schema object.",
+    }
+  }
+  const root = schema as Record<string, unknown>
+  if (root.type !== "object") {
+    return {
+      ok: false,
+      message:
+        'agent() opts.schema must have `type: "object"` at its root — it becomes the tool\'s input schema, ' +
+        "and a non-object root is not something a model can be asked to fill.",
+    }
+  }
+
+  let serialized: string
+  try {
+    serialized = JSON.stringify(root)
+  } catch {
+    return {
+      ok: false,
+      message: "agent() opts.schema must be JSON-serializable.",
+    }
+  }
+  if (serialized.length > MAX_SCHEMA_BYTES) {
+    return {
+      ok: false,
+      message: `agent() opts.schema is too large (${serialized.length} bytes; the limit is ${MAX_SCHEMA_BYTES}).`,
+    }
+  }
+
+  // Smoke-tested here so a schema the validator cannot walk fails at the call
+  // that wrote it, with the schema in hand, rather than inside a child's tool
+  // handler where the only symptom is an agent that never returns.
+  try {
+    Check(root, {})
+  } catch (error) {
+    return {
+      ok: false,
+      message: `agent() opts.schema is not a schema this runtime can validate: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    }
+  }
+
+  return {
+    ok: true,
+    compiled: { schema: root, check: (value) => checkAgainst(root, value) },
+  }
+}
+
+function checkAgainst(
+  schema: Record<string, unknown>,
+  value: unknown,
+): true | string {
+  let valid: boolean
+  try {
+    valid = Check(schema, value)
+  } catch (error) {
+    // Reported rather than thrown: a schema that compiled but trips on a
+    // particular value must fail that call, not the run.
+    return `the value could not be validated: ${error instanceof Error ? error.message : String(error)}`
+  }
+  if (valid) return true
+
+  const reported: string[] = []
+  try {
+    for (const error of Errors(schema, value)) {
+      // `instancePath` is JSON Pointer (`/a/b`); the model wrote the schema in
+      // JavaScript, so it reads `$.a.b` far more easily.
+      const path = String(error.instancePath ?? "")
+      const where = path === "" ? "$" : `$${path.replace(/\//g, ".")}`
+      reported.push(`${where}: ${error.message}`)
+      if (reported.length >= MAX_REPORTED_ERRORS) break
+    }
+  } catch {
+    // Errors() can trip where Check() merely returned false. A vaguer message
+    // still names the right problem.
+  }
+  return reported.length > 0
+    ? reported.join("; ")
+    : "the value does not match the required schema"
+}

package/src/workflow/meta.ts

@@ -0,0 +1,401 @@
+/**
+ * meta.ts — extract and validate a workflow script's `meta` block.
+ *
+ * Workflow scripts open with `export const meta = { ... }`, but the script body
+ * runs through `node:vm`, which has no module loader — `export` is a syntax
+ * error there. The block also has to be readable *before* execution, because the
+ * declared phases seed the progress groups the UI renders from the first frame.
+ *
+ * Claude Code solves this by parsing with acorn and requiring `meta` to be a
+ * pure literal (no variables, calls, spreads, or template interpolation). We
+ * take the same contract without the dependency: scan to the matching brace,
+ * then evaluate *only* that fragment in an empty vm context. A pure literal has
+ * nothing to call, so evaluating it cannot reach anything — and anything that
+ * isn't a pure literal either throws (unbound identifier) or is rejected below.
+ *
+ * The scanner is string-, comment-, and regex-aware. That matters: a workflow's
+ * `detail` text routinely contains braces, and `phases: [{ title: "a}b" }]` must
+ * not terminate the scan early.
+ */
+
+import { createContext, Script } from "node:vm"
+
+/** A phase declared up front, so the UI can show it before any agent runs. */
+export interface WorkflowPhaseMeta {
+  title: string
+  detail?: string
+  /** Set when a phase pins a model; display-only, the runtime does not read it. */
+  model?: string
+}
+
+export interface WorkflowMeta {
+  name: string
+  description: string
+  /** Shown in the saved-workflow listing. Not used by the runtime. */
+  whenToUse?: string
+  phases?: WorkflowPhaseMeta[]
+}
+
+export interface MetaExtraction {
+  meta: WorkflowMeta
+  /**
+   * The script with the leading `export ` stripped, so `const meta = {...}`
+   * compiles inside the vm. Byte offsets after the keyword are untouched, which
+   * keeps stack-trace line numbers aligned with what the author wrote.
+   */
+  body: string
+}
+
+export class WorkflowMetaError extends Error {}
+
+/**
+ * Wall-clock bound on evaluating the `meta` fragment. Generous for a literal —
+ * this exists only to stop a pathological one from hanging the host thread.
+ */
+const META_EVAL_TIMEOUT_MS = 100
+
+const PURE_LITERAL_HINT =
+  "The `meta` object must be a PURE LITERAL — no variables, function calls, spreads, or template interpolation."
+
+/** Matches `export const meta =` allowing arbitrary inner whitespace. */
+const META_DECLARATION =
+  /(^|[\r\n])[ \t]*export[ \t\r\n]+const[ \t\r\n]+meta[ \t\r\n]*=/
+
+/**
+ * Whether `source` even claims to be a workflow script.
+ *
+ * The cheap half of {@link extractMeta}, exported so a directory of `.js` files
+ * can be told apart from a directory of workflows without evaluating anything.
+ * A saved-workflow folder is a normal folder — it may hold a build artifact, a
+ * config, someone's scratch script — and those should neither be offered as
+ * workflows nor produce a parser error when named.
+ */
+export function hasMetaDeclaration(source: string): boolean {
+  return META_DECLARATION.test(source)
+}
+
+interface ScanResult {
+  /** Index of the literal's closing brace, or -1 when braces never balance. */
+  end: number
+  /**
+   * True when a `${` substitution opened inside a template literal. Reported
+   * separately because such a fragment can still *evaluate* — `` `a${1+1}b` ``
+   * needs no globals — so the impure-literal check below cannot catch it.
+   */
+  sawInterpolation: boolean
+}
+
+/**
+ * Find the index just past the object literal that starts at `open`.
+ *
+ * Tracks string, template, comment, and regex context so braces inside them do
+ * not move the depth counter.
+ */
+function scanObjectLiteral(source: string, open: number): ScanResult {
+  let depth = 0
+  let i = open
+  let sawInterpolation = false
+  // What we are currently inside of. "code" means brace counting is live.
+  let mode:
+    | "code"
+    | "line-comment"
+    | "block-comment"
+    | "single"
+    | "double"
+    | "template"
+    | "regex" = "code"
+  // Template literals nest: `${ {a:1} }` re-enters code, and the closing brace
+  // of that substitution must not be read as the object's. One depth per level.
+  const templateStack: number[] = []
+
+  while (i < source.length) {
+    const c = source[i]
+    const next = source[i + 1]
+
+    if (mode === "line-comment") {
+      if (c === "\n") mode = "code"
+      i++
+      continue
+    }
+    if (mode === "block-comment") {
+      if (c === "*" && next === "/") {
+        mode = "code"
+        i += 2
+        continue
+      }
+      i++
+      continue
+    }
+    if (mode === "single" || mode === "double" || mode === "regex") {
+      if (c === "\\") {
+        i += 2
+        continue
+      }
+      if (mode === "single" && c === "'") mode = "code"
+      else if (mode === "double" && c === '"') mode = "code"
+      else if (mode === "regex" && c === "/") mode = "code"
+      // An unterminated regex/string can't run past a newline; bail to code so a
+      // misdetected regex (see below) cannot swallow the rest of the literal.
+      else if (c === "\n" && mode !== "double") mode = "code"
+      i++
+      continue
+    }
+    if (mode === "template") {
+      if (c === "\\") {
+        i += 2
+        continue
+      }
+      if (c === "`") {
+        mode = "code"
+        i++
+        continue
+      }
+      if (c === "$" && next === "{") {
+        sawInterpolation = true
+        templateStack.push(depth)
+        depth++
+        mode = "code"
+        i += 2
+        continue
+      }
+      i++
+      continue
+    }
+
+    // mode === "code"
+    if (c === "/" && next === "/") {
+      mode = "line-comment"
+      i += 2
+      continue
+    }
+    if (c === "/" && next === "*") {
+      mode = "block-comment"
+      i += 2
+      continue
+    }
+    if (c === "'") {
+      mode = "single"
+      i++
+      continue
+    }
+    if (c === '"') {
+      mode = "double"
+      i++
+      continue
+    }
+    if (c === "`") {
+      mode = "template"
+      i++
+      continue
+    }
+    if (c === "/" && isRegexPosition(source, i)) {
+      mode = "regex"
+      i++
+      continue
+    }
+    if (c === "{") {
+      depth++
+      i++
+      continue
+    }
+    if (c === "}") {
+      depth--
+      i++
+      if (
+        templateStack.length > 0 &&
+        depth === templateStack[templateStack.length - 1]
+      ) {
+        templateStack.pop()
+        mode = "template"
+        continue
+      }
+      if (depth === 0) return { end: i, sawInterpolation }
+      continue
+    }
+    i++
+  }
+  return { end: -1, sawInterpolation }
+}
+
+/**
+ * Decide whether the `/` at `i` opens a regex literal rather than a division.
+ *
+ * Walks back past whitespace and comments to the previous significant char: a
+ * regex can only follow an operator or opener, never a value. This is the usual
+ * heuristic and it is sufficient here, because the only thing riding on it is
+ * not miscounting braces inside a `meta` literal — and a `meta` literal
+ * containing division is already not a pure literal.
+ */
+function isRegexPosition(source: string, i: number): boolean {
+  let j = i - 1
+  while (j >= 0 && /\s/.test(source[j])) j--
+  if (j < 0) return true
+  const prev = source[j]
+  // Identifier/number/closer before `/` means division.
+  return !/[\w$)\]]/.test(prev)
+}
+
+function fail(message: string): never {
+  throw new WorkflowMetaError(message)
+}
+
+function assertPhases(value: unknown): WorkflowPhaseMeta[] | undefined {
+  if (value === undefined) return undefined
+  if (!Array.isArray(value))
+    fail(
+      "`meta.phases` must be an array of { title, detail?, model? } objects.",
+    )
+  return value.map((entry, index) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      fail(`\`meta.phases[${index}]\` must be an object with a \`title\`.`)
+    }
+    const { title, detail, model } = entry as Record<string, unknown>
+    if (typeof title !== "string" || title.trim() === "") {
+      fail(`\`meta.phases[${index}].title\` must be a non-empty string.`)
+    }
+    if (detail !== undefined && typeof detail !== "string") {
+      fail(`\`meta.phases[${index}].detail\` must be a string.`)
+    }
+    if (model !== undefined && typeof model !== "string") {
+      fail(`\`meta.phases[${index}].model\` must be a string.`)
+    }
+    return {
+      title,
+      ...(detail !== undefined ? { detail } : {}),
+      ...(model !== undefined ? { model } : {}),
+    }
+  })
+}
+
+/**
+ * Pull `meta` off the front of a workflow script and hand back the runnable body.
+ *
+ * Throws {@link WorkflowMetaError} with author-facing guidance for every
+ * rejection — these messages are shown verbatim to whoever wrote the script.
+ */
+export function extractMeta(source: string): MetaExtraction {
+  const declaration = META_DECLARATION.exec(source)
+  if (!declaration) {
+    fail(
+      "A workflow script must begin with `export const meta = { name, description }`.\n" +
+        PURE_LITERAL_HINT,
+    )
+  }
+
+  const open = source.indexOf("{", declaration.index + declaration[0].length)
+  if (open === -1)
+    fail(
+      "`export const meta` must be assigned an object literal.\n" +
+        PURE_LITERAL_HINT,
+    )
+
+  const { end: close, sawInterpolation } = scanObjectLiteral(source, open)
+  if (close === -1)
+    fail("`meta` object literal is never closed — check for an unbalanced `{`.")
+
+  // Caught here rather than by evaluation: a self-contained substitution such as
+  // `` `a${1 + 1}b` `` resolves without touching a single global, so it would
+  // sail through the empty-context check below and silently produce "a2b".
+  if (sawInterpolation) {
+    fail(
+      "`meta` must not use template interpolation (`$" +
+        "{...}`).\n" +
+        PURE_LITERAL_HINT,
+    )
+  }
+
+  const fragment = source.slice(open, close)
+  let value: unknown
+  try {
+    // Empty context: a pure literal needs no globals, so anything reaching for
+    // one (a variable, a helper call) throws here and is reported as impure.
+    //
+    // The timeout is not belt-and-braces. An IIFE needs no globals either, so
+    // `name: (() => { while (true); })()` is evaluable — and this runs on the
+    // host thread, before the script ever reaches the worker. Without a bound it
+    // would wedge pi itself. `timeout` only governs synchronous execution, which
+    // is all a literal can contain.
+    value = new Script(`(${fragment})`, {
+      filename: "workflow-meta.js",
+    }).runInContext(createContext({}), { timeout: META_EVAL_TIMEOUT_MS })
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error)
+    if (/timed out|Script execution/i.test(detail)) {
+      fail(
+        `\`meta\` did not finish evaluating within ${META_EVAL_TIMEOUT_MS}ms — it must be a literal, not a computation.\n` +
+          PURE_LITERAL_HINT,
+      )
+    }
+    fail(`\`meta\` could not be evaluated: ${detail}\n${PURE_LITERAL_HINT}`)
+  }
+
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    fail("`meta` must be an object literal.\n" + PURE_LITERAL_HINT)
+  }
+  const raw = value as Record<string, unknown>
+
+  if (typeof raw.name !== "string" || raw.name.trim() === "") {
+    fail("`meta.name` is required and must be a non-empty string.")
+  }
+  if (typeof raw.description !== "string" || raw.description.trim() === "") {
+    fail("`meta.description` is required and must be a non-empty string.")
+  }
+  if (raw.whenToUse !== undefined && typeof raw.whenToUse !== "string") {
+    fail("`meta.whenToUse` must be a string.")
+  }
+  const phases = assertPhases(raw.phases)
+
+  const meta: WorkflowMeta = {
+    name: raw.name,
+    description: raw.description,
+    ...(raw.whenToUse !== undefined
+      ? { whenToUse: raw.whenToUse as string }
+      : {}),
+    ...(phases !== undefined ? { phases } : {}),
+  }
+
+  // Strip only the `export ` keyword. Replacing it with spaces rather than
+  // deleting it keeps every subsequent offset — and therefore every reported
+  // line and column — identical to the source the author wrote.
+  const exportAt = source.indexOf("export", declaration.index)
+  const body = `${source.slice(0, exportAt)}${" ".repeat(6)}${source.slice(exportAt + 6)}`
+
+  return { meta, body }
+}
+
+/**
+ * `meta.name` for a call line, without re-parsing on every frame.
+ *
+ * `renderCall` runs on every repaint, and extraction evaluates a literal in a
+ * vm — cheap, but not free at that cadence. Keyed by the exact source, so an
+ * edit-and-rerun cycle re-reads it and a hit is always the answer a fresh parse
+ * would give.
+ */
+const workflowNames = new Map<string, string>()
+
+/** The label a `SubagentWorkflow` call renders under, from whichever field it carries. */
+export function workflowCallName(args: {
+  script?: string
+  scriptPath?: string
+  name?: string
+}): string {
+  const source = args.script
+  if (source === undefined || source === "") {
+    // A path-only call would need a synchronous file read per repaint to do
+    // better than this, and the file name is what the author will recognize.
+    if (args.scriptPath !== undefined)
+      return args.scriptPath.split(/[/\\]/).pop() ?? "workflow"
+    // A saved workflow is already named by the caller; no read needed at all.
+    return args.name !== undefined && args.name !== "" ? args.name : "workflow"
+  }
+  const cached = workflowNames.get(source)
+  if (cached !== undefined) return cached
+  let name = "workflow"
+  try {
+    name = extractMeta(source).meta.name
+  } catch {
+    // An invalid script still gets a call line; `execute` reports why.
+  }
+  workflowNames.set(source, name)
+  return name
+}