@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/engine/workflow/journal.mjs

@@ -0,0 +1,188 @@
+/**
+ * lib/engine/workflow/journal.mjs — a workflow run's directory, its journal and
+ * the replay plan a resume is built from.
+ *
+ *   <sessions>/workflows/<session id>/<run id>/
+ *       script.js       the script the run executed (a resume may edit it)
+ *       journal.jsonl   one record per line (appendJsonl: one write per line)
+ *       result.json     the return value, when there is one
+ *
+ * Journal records:
+ *   {type:"run",   runId, sessionId, cwd, pid, name, scriptPath, resumedFrom, args, ts}
+ *   {type:"agent", seq, key, occurrence, label, phase, status:"ok"|"failed", replayed, result, tokens, agentId, error, ts}
+ *   {type:"phase", title, ts}    {type:"log", message, ts}
+ *   {type:"end",   status:"completed"|"failed"|"stopped", error, resultPath, worktrees, ts}
+ *
+ * `end` is the last record a run writes: every agent() call still running when
+ * the script settled has been aborted and journaled before it. `worktrees`
+ * lists the worktrees kept because they changed.
+ *
+ * The call key. An agent() call is identified by `key` = a hash of what
+ * decides its work — the nesting scope, the prompt, and the options that change
+ * the child (schema, model, effort, isolation, agentType) — and `occurrence`,
+ * its position among calls with the same key. `label` and `phase` are display
+ * only and are not part of the key, so renaming a label does not re-run work.
+ *
+ * Replay (`createReplay`, pure). While a resumed run's calls keep matching
+ * completed journal entries by (key, occurrence), each is answered from the
+ * journal at once. The first call whose key the journal has never seen marks
+ * the divergence: it and every later call run live. A call the journal holds
+ * as FAILED runs live again without marking a divergence (a resume is how a
+ * failed step is retried). Replayed results resolve as microtasks, so the
+ * replayed part of a run makes its calls in the same order every time; live
+ * calls after it interleave by completion.
+ *
+ * @module lib/engine/workflow/journal
+ */
+
+import { createHash, randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { appendJsonl } from "../../fs-atomic.mjs";
+import { stableStringify } from "../messages.mjs";
+import { parseTranscript } from "../session/store.mjs";
+
+const RUN_ID_RE = /^wf_[0-9a-f]{12}$/;
+
+export function newRunId() {
+  return `wf_${randomBytes(6).toString("hex")}`;
+}
+
+/** @param {unknown} id @returns {id is string} */
+export function isRunId(id) {
+  return typeof id === "string" && RUN_ID_RE.test(id);
+}
+
+/** @param {string} sessionsDir @param {string} sessionId @param {string} runId */
+export function runDirFor(sessionsDir, sessionId, runId) {
+  return path.join(sessionsDir, "workflows", sessionId, runId);
+}
+
+/**
+ * Where an earlier run lives: this session, or another session's run that was
+ * started in the SAME project directory (`cwd`, recorded in its `run` record).
+ * A run from another project, or one whose journal does not say where it ran,
+ * is not found: its script and results stay out of this session.
+ * @param {string} sessionsDir @param {string} sessionId @param {string} runId
+ * @param {{cwd?:string}} [o]
+ * @returns {string|null}
+ */
+export function findRunDir(sessionsDir, sessionId, runId, { cwd } = {}) {
+  if (!isRunId(runId)) return null;
+  const own = runDirFor(sessionsDir, sessionId, runId);
+  if (existsSync(path.join(own, "journal.jsonl"))) return own;
+  if (typeof cwd !== "string") return null;
+  const root = path.join(sessionsDir, "workflows");
+  let sessions = [];
+  try {
+    sessions = readdirSync(root);
+  } catch {
+    return null;
+  }
+  for (const s of sessions.sort()) {
+    const dir = path.join(root, s, runId);
+    const file = path.join(dir, "journal.jsonl");
+    if (existsSync(file) && runSummary(readJournal(file).records).cwd === cwd) return dir;
+  }
+  return null;
+}
+
+/**
+ * What a journal says about its run. Pure. `ended` is false for a run still
+ * going, or one whose process died before it could write `end`.
+ * @param {any[]} records
+ * `nonce` and `startToken` identify the process beyond its PID (process-identity.mjs).
+ * @returns {{cwd:string|null, pid:number|null, nonce:string|null, startToken:string|null, ended:boolean}}
+ */
+export function runSummary(records) {
+  const run = records.find((r) => r?.type === "run");
+  return {
+    cwd: typeof run?.cwd === "string" ? run.cwd : null,
+    pid: Number.isInteger(run?.pid) ? run.pid : null,
+    nonce: typeof run?.nonce === "string" ? run.nonce : null,
+    startToken: typeof run?.startToken === "string" ? run.startToken : null,
+    ended: records.some((r) => r?.type === "end"),
+  };
+}
+
+/**
+ * The key of an agent() call. Pure.
+ * @param {{scope:string, prompt:string, opts:Record<string, unknown>}} c
+ */
+export function callKey({ scope, prompt, opts }) {
+  const { label: _l, phase: _p, ...decisive } = opts ?? {};
+  return createHash("sha256").update(stableStringify({ scope, prompt, opts: decisive })).digest("hex").slice(0, 32);
+}
+
+/** The key of a nested workflow() call. Pure. @param {{scope:string, source:string, args:unknown}} c */
+export function nestedKey({ scope, source, args }) {
+  return createHash("sha256").update(stableStringify({ scope, workflow: createHash("sha256").update(source).digest("hex"), args: args ?? null })).digest("hex").slice(0, 32);
+}
+
+/**
+ * @param {string} journalPath
+ * @returns {{records:any[], skipped:number}}
+ */
+export function readJournal(journalPath) {
+  try {
+    return parseTranscript(readFileSync(journalPath, "utf8"));
+  } catch {
+    return { records: [], skipped: 0 };
+  }
+}
+
+/**
+ * The replay plan of a journal. Pure.
+ * @param {any[]} records
+ */
+export function createReplay(records) {
+  /** @type {Map<string, any>} */
+  const completed = new Map();
+  const known = new Set();
+  for (const r of records) {
+    if (r.type !== "agent" || typeof r.key !== "string" || !Number.isInteger(r.occurrence)) continue;
+    const k = `${r.key}#${r.occurrence}`;
+    known.add(r.key);
+    if (r.status === "ok") completed.set(k, r);
+  }
+  let diverged = false;
+  return {
+    /**
+     * The journal entry answering this call, or null to run it live.
+     * @param {string} key @param {number} occurrence
+     */
+    take(key, occurrence) {
+      if (diverged) return null;
+      const hit = completed.get(`${key}#${occurrence}`);
+      if (hit) return hit;
+      if (!known.has(key)) diverged = true;
+      return null;
+    },
+    get diverged() {
+      return diverged;
+    },
+    size: completed.size,
+  };
+}
+
+/**
+ * The journal writer of one run. Write failures are counted, never thrown: a
+ * journal that cannot be written costs resumability, not the run.
+ * @param {{dir:string, now:() => number}} o
+ */
+export function createJournal({ dir, now }) {
+  mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, "journal.jsonl");
+  let failures = 0;
+  return {
+    path: file,
+    dir,
+    /** @param {Record<string, unknown>} record */
+    append(record) {
+      if (!appendJsonl(file, { ...record, ts: new Date(now()).toISOString() })) failures++;
+    },
+    get failures() {
+      return failures;
+    },
+  };
+}

package/lib/engine/workflow/json-schema.mjs

@@ -0,0 +1,171 @@
+/**
+ * lib/engine/workflow/json-schema.mjs — validating a structured agent result
+ * against the JSON Schema a workflow script gave `agent(…, {schema})` (pure).
+ *
+ * A deliberate subset of JSON Schema (draft 2020-12 vocabulary names), large
+ * enough for result shapes and small enough to be exactly right:
+ *
+ *   type (a name or a list; "integer" included), enum, const,
+ *   properties, required, additionalProperties (false or a schema),
+ *   items (one schema), minItems, maxItems, uniqueItems,
+ *   minLength, maxLength, pattern,
+ *   minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf,
+ *   anyOf, oneOf, allOf, not, and the boolean schemas true / false.
+ *
+ * Annotations (title, description, default, examples, $schema, $id, $comment,
+ * format, readOnly, writeOnly, deprecated) are accepted and not checked.
+ * Anything else ($ref, if/then/else, patternProperties, prefixItems, …) is
+ * REFUSED up front by `schemaProblems`, so a script learns its schema is not
+ * enforced instead of getting a result that silently skipped a rule.
+ *
+ * maestro takes no validator dependency (see tools/schema.mjs).
+ *
+ * @module lib/engine/workflow/json-schema
+ */
+
+const CHECKED = new Set([
+  "type", "enum", "const", "properties", "required", "additionalProperties", "items", "minItems", "maxItems", "uniqueItems",
+  "minLength", "maxLength", "pattern", "minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "multipleOf",
+  "anyOf", "oneOf", "allOf", "not",
+]);
+const ANNOTATIONS = new Set(["title", "description", "default", "examples", "$schema", "$id", "$comment", "format", "readOnly", "writeOnly", "deprecated"]);
+const TYPES = new Set(["object", "array", "string", "number", "integer", "boolean", "null"]);
+const MAX_ERRORS = 20;
+
+/**
+ * Keywords this validator would not enforce, and malformed keyword values.
+ * @param {unknown} schema @param {string} [at]
+ * @returns {string[]}
+ */
+export function schemaProblems(schema, at = "$") {
+  if (typeof schema === "boolean") return [];
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) return [`${at}: a schema must be an object or a boolean`];
+  const s = /** @type {Record<string, any>} */ (schema);
+  const out = [];
+  for (const k of Object.keys(s)) {
+    if (!CHECKED.has(k) && !ANNOTATIONS.has(k)) out.push(`${at}: "${k}" is not supported`);
+  }
+  if (s.type !== undefined) {
+    const list = Array.isArray(s.type) ? s.type : [s.type];
+    for (const t of list) if (!TYPES.has(t)) out.push(`${at}: unknown type ${JSON.stringify(t)}`);
+  }
+  if (s.properties !== undefined) {
+    if (!s.properties || typeof s.properties !== "object" || Array.isArray(s.properties)) out.push(`${at}.properties must be an object`);
+    else for (const [k, sub] of Object.entries(s.properties)) out.push(...schemaProblems(sub, `${at}.properties.${k}`));
+  }
+  if (s.required !== undefined && (!Array.isArray(s.required) || s.required.some((/** @type unknown */ r) => typeof r !== "string"))) out.push(`${at}.required must be a list of names`);
+  if (s.additionalProperties !== undefined && typeof s.additionalProperties !== "boolean") out.push(...schemaProblems(s.additionalProperties, `${at}.additionalProperties`));
+  if (s.items !== undefined) out.push(...schemaProblems(s.items, `${at}.items`));
+  if (s.not !== undefined) out.push(...schemaProblems(s.not, `${at}.not`));
+  for (const k of ["anyOf", "oneOf", "allOf"]) {
+    if (s[k] === undefined) continue;
+    if (!Array.isArray(s[k]) || s[k].length === 0) out.push(`${at}.${k} must be a non-empty list`);
+    else s[k].forEach((/** @type unknown */ sub, /** @type number */ i) => out.push(...schemaProblems(sub, `${at}.${k}[${i}]`)));
+  }
+  if (s.pattern !== undefined) {
+    try {
+      new RegExp(s.pattern, "u");
+    } catch {
+      out.push(`${at}.pattern is not a valid regular expression`);
+    }
+  }
+  if (s.enum !== undefined && !Array.isArray(s.enum)) out.push(`${at}.enum must be a list`);
+  return out;
+}
+
+/**
+ * @param {unknown} schema @param {unknown} value
+ * @returns {{ok:true}|{ok:false, errors:string[]}}
+ */
+export function validateJsonSchema(schema, value) {
+  /** @type {string[]} */
+  const errors = [];
+  check(schema, value, "$", errors);
+  return errors.length === 0 ? { ok: true } : { ok: false, errors: errors.slice(0, MAX_ERRORS) };
+}
+
+/** @param {unknown} v */
+function typeOf(v) {
+  if (v === null) return "null";
+  if (Array.isArray(v)) return "array";
+  if (typeof v === "number") return Number.isInteger(v) ? "integer" : "number";
+  return typeof v;
+}
+
+/** @param {unknown} a @param {unknown} b */
+function equal(a, b) {
+  return canonical(a) === canonical(b);
+}
+
+/** @param {unknown} v @returns {string} */
+function canonical(v) {
+  if (Array.isArray(v)) return `[${v.map(canonical).join(",")}]`;
+  if (v && typeof v === "object") return `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${canonical(/** @type any */ (v)[k])}`).join(",")}}`;
+  return JSON.stringify(v);
+}
+
+/** @param {unknown} schema @param {unknown} value @param {string} at @param {string[]} errors */
+function check(schema, value, at, errors) {
+  if (errors.length >= MAX_ERRORS) return;
+  if (schema === true || schema === undefined) return;
+  if (schema === false) {
+    errors.push(`${at} is not allowed`);
+    return;
+  }
+  const s = /** @type {Record<string, any>} */ (schema);
+  const t = typeOf(value);
+
+  if (s.type !== undefined) {
+    const list = Array.isArray(s.type) ? s.type : [s.type];
+    const ok = list.some((/** @type string */ want) => want === t || (want === "number" && t === "integer"));
+    if (!ok) {
+      errors.push(`${at} must be ${list.join(" or ")} (got ${t})`);
+      return;
+    }
+  }
+  if (s.const !== undefined && !equal(s.const, value)) errors.push(`${at} must equal ${JSON.stringify(s.const)}`);
+  if (Array.isArray(s.enum) && !s.enum.some((/** @type unknown */ e) => equal(e, value))) errors.push(`${at} must be one of ${s.enum.map((/** @type unknown */ e) => JSON.stringify(e)).join(", ")}`);
+
+  if (t === "string") {
+    const str = /** @type string */ (value);
+    const len = [...str].length;
+    if (typeof s.minLength === "number" && len < s.minLength) errors.push(`${at} must be at least ${s.minLength} characters`);
+    if (typeof s.maxLength === "number" && len > s.maxLength) errors.push(`${at} must be at most ${s.maxLength} characters`);
+    if (typeof s.pattern === "string" && !new RegExp(s.pattern, "u").test(str)) errors.push(`${at} must match ${s.pattern}`);
+  }
+  if (t === "number" || t === "integer") {
+    const n = /** @type number */ (value);
+    if (typeof s.minimum === "number" && n < s.minimum) errors.push(`${at} must be ≥ ${s.minimum}`);
+    if (typeof s.maximum === "number" && n > s.maximum) errors.push(`${at} must be ≤ ${s.maximum}`);
+    if (typeof s.exclusiveMinimum === "number" && n <= s.exclusiveMinimum) errors.push(`${at} must be > ${s.exclusiveMinimum}`);
+    if (typeof s.exclusiveMaximum === "number" && n >= s.exclusiveMaximum) errors.push(`${at} must be < ${s.exclusiveMaximum}`);
+    if (typeof s.multipleOf === "number" && s.multipleOf > 0 && !Number.isInteger(n / s.multipleOf)) errors.push(`${at} must be a multiple of ${s.multipleOf}`);
+  }
+  if (t === "array") {
+    const arr = /** @type unknown[] */ (value);
+    if (typeof s.minItems === "number" && arr.length < s.minItems) errors.push(`${at} must have at least ${s.minItems} items`);
+    if (typeof s.maxItems === "number" && arr.length > s.maxItems) errors.push(`${at} must have at most ${s.maxItems} items`);
+    if (s.uniqueItems === true && new Set(arr.map(canonical)).size !== arr.length) errors.push(`${at} must not repeat items`);
+    if (s.items !== undefined) arr.forEach((item, i) => check(s.items, item, `${at}[${i}]`, errors));
+  }
+  if (t === "object") {
+    const obj = /** @type {Record<string, unknown>} */ (value);
+    for (const r of Array.isArray(s.required) ? s.required : []) {
+      if (!Object.prototype.hasOwnProperty.call(obj, r)) errors.push(`${at}.${r} is required`);
+    }
+    const props = s.properties && typeof s.properties === "object" ? s.properties : {};
+    for (const [k, v] of Object.entries(obj)) {
+      if (Object.prototype.hasOwnProperty.call(props, k)) check(props[k], v, `${at}.${k}`, errors);
+      else if (s.additionalProperties === false) errors.push(`${at}.${k} is not an allowed property`);
+      else if (s.additionalProperties && typeof s.additionalProperties === "object") check(s.additionalProperties, v, `${at}.${k}`, errors);
+    }
+  }
+
+  if (Array.isArray(s.allOf)) for (const sub of s.allOf) check(sub, value, at, errors);
+  if (Array.isArray(s.anyOf) && !s.anyOf.some((/** @type unknown */ sub) => validateJsonSchema(sub, value).ok)) errors.push(`${at} matches none of the anyOf schemas`);
+  if (Array.isArray(s.oneOf)) {
+    const n = s.oneOf.filter((/** @type unknown */ sub) => validateJsonSchema(sub, value).ok).length;
+    if (n !== 1) errors.push(`${at} must match exactly one oneOf schema (matched ${n})`);
+  }
+  if (s.not !== undefined && validateJsonSchema(s.not, value).ok) errors.push(`${at} matches a schema it must not`);
+}

package/lib/engine/workflow/meta.mjs

@@ -0,0 +1,329 @@
+/**
+ * lib/engine/workflow/meta.mjs — reading a workflow script before it runs (pure).
+ *
+ * A workflow script is JavaScript whose first statement is
+ *
+ *   export const meta = { name: "…", description: "…", phases: ["…", …] };
+ *
+ * with the object written as a PURE LITERAL: strings (no `${}` in a template),
+ * numbers, true/false/null, arrays and nested objects with plain keys. No
+ * identifiers, calls, spreads, shorthand properties or methods — the engine
+ * reads `meta` without running anything, so it can list and describe a run
+ * before (and without) executing it.
+ *
+ * `parseWorkflowSource` also refuses, before any execution:
+ *   · a script larger than `MAX_SCRIPT_BYTES`;
+ *   · any use of the `import` keyword as `import(` or `import.` (after
+ *     whitespace or comments). On Node's `vm.Script` a dynamic import always
+ *     rejects with an error object from the HOST realm, whatever loader
+ *     callback is given — and a host object is a way out of the sandbox
+ *     (`e.constructor.constructor("return process")()`). The check is textual
+ *     and fails closed: the same characters inside a string are refused too
+ *     (reword the string), because a scanner that tried to tell strings from
+ *     code could be misled into missing a real call. A static `import`/`export`
+ *     elsewhere is a syntax error when the body is compiled.
+ *
+ * The body handed to the sandbox is the source with the leading `export`
+ * keyword blanked out (same length, so line and column numbers hold), leaving
+ * `const meta = {…}` for the script to read.
+ *
+ * @module lib/engine/workflow/meta
+ */
+
+export const MAX_SCRIPT_BYTES = 256 * 1024;
+const MAX_NAME_CHARS = 200;
+const MAX_DESCRIPTION_CHARS = 2_000;
+const MAX_PHASES = 100;
+
+/**
+ * @typedef {{name:string, description:string, phases:Array<{title:string, detail?:string}>}} WorkflowMeta
+ */
+
+/**
+ * @param {unknown} source
+ * @returns {{ok:true, meta:WorkflowMeta, body:string}|{ok:false, error:string}}
+ */
+export function parseWorkflowSource(source) {
+  if (typeof source !== "string" || source.trim() === "") return { ok: false, error: "the workflow script is empty" };
+  const bytes = Buffer.byteLength(source);
+  if (bytes > MAX_SCRIPT_BYTES) return { ok: false, error: `the workflow script is ${bytes} bytes; the limit is ${MAX_SCRIPT_BYTES}` };
+
+  const imp = findImportUse(source);
+  if (imp !== -1) {
+    const line = source.slice(0, imp).split("\n").length;
+    return { ok: false, error: `line ${line}: workflow scripts cannot use import() or import.meta (nothing can be loaded into a workflow). If "import(" or "import." is text inside a string, reword it.` };
+  }
+
+  const p = { src: source, i: 0 };
+  skipTrivia(p);
+  const exportAt = p.i;
+  const head = /^export\s+const\s+meta\s*=/.exec(source.slice(p.i));
+  if (!head) return { ok: false, error: "a workflow script must begin with `export const meta = { name, description, phases? }`" };
+  p.i += head[0].length;
+  let value;
+  try {
+    value = parseValue(p, 0);
+  } catch (e) {
+    return { ok: false, error: `meta must be a plain literal: ${e instanceof Error ? e.message : String(e)}` };
+  }
+  skipTrivia(p);
+  // Anything that would continue the expression (`{…}.x`, `{…}\n[0]`, `{…} || y`,
+  // `{…} in o`) makes the value something other than the literal: refused, even
+  // across a line break, where automatic semicolon insertion would not end it.
+  const rest = source.slice(p.i);
+  if (/^(?:[.[(+\-*/%?=<>&|^,`]|!=|in(?:stanceof)?\b)/.test(rest)) {
+    return { ok: false, error: `meta must be a plain literal: "${rest.slice(0, 12)}" continues the expression after it` };
+  }
+  const checked = checkMeta(value);
+  if (!checked.ok) return checked;
+  const body = source.slice(0, exportAt) + " ".repeat("export".length) + source.slice(exportAt + "export".length);
+  return { ok: true, meta: checked.meta, body };
+}
+
+/**
+ * The index of the first `import` keyword followed (after whitespace and
+ * comments) by `(` or `.`; -1 when there is none. Fails closed: it does not
+ * try to tell code from strings.
+ * @param {string} src
+ */
+export function findImportUse(src) {
+  const re = /import/g;
+  for (let m = re.exec(src); m; m = re.exec(src)) {
+    const at = m.index;
+    const prev = at > 0 ? src[at - 1] : "";
+    if (prev && /[A-Za-z0-9_$\\]/.test(prev)) continue; // part of a longer identifier (or an escape)
+    const p = { src, i: at + 6 };
+    // Trivia FIRST. Every character JavaScript treats as whitespace (\s is exactly
+    // WhiteSpace and LineTerminator: U+00A0, U+FEFF, U+3000, U+2028 included) separates
+    // the keyword from what follows; none may be taken for part of a longer name.
+    skipTrivia(p, true);
+    if (src[p.i] === "(" || src[p.i] === ".") return at;
+    // Only when nothing was skipped and a real identifier character follows is this a
+    // longer name (imports, importé, import\u200d) rather than the keyword.
+    if (p.i === at + 6 && p.i < src.length && isIdentifierPart(src.codePointAt(p.i) ?? 0)) continue;
+  }
+  return -1;
+}
+
+/** An ID_Continue code point, $, ZWNJ or ZWJ, and never whitespace. @param {number} cp */
+function isIdentifierPart(cp) {
+  const ch = String.fromCodePoint(cp);
+  return !/\s/.test(ch) && /[\p{ID_Continue}$\u200c\u200d]/u.test(ch);
+}
+
+/**
+ * Whitespace and comments. With `htmlComments`, also the script-goal `<!--`
+ * and `-->` single-line comments (Annex B), so `import<!--\n(` is still seen.
+ * @param {{src:string, i:number}} p @param {boolean} [htmlComments]
+ */
+function skipTrivia(p, htmlComments = false) {
+  const s = p.src;
+  for (;;) {
+    while (p.i < s.length && /\s/.test(s[p.i])) p.i++;
+    if (s.startsWith("//", p.i) || (htmlComments && (s.startsWith("<!--", p.i) || s.startsWith("-->", p.i)))) {
+      const nl = s.slice(p.i).search(/[\n\r\u2028\u2029]/);
+      p.i = nl === -1 ? s.length : p.i + nl;
+      continue;
+    }
+    if (s.startsWith("/*", p.i)) {
+      const end = s.indexOf("*/", p.i + 2);
+      p.i = end === -1 ? s.length : end + 2;
+      continue;
+    }
+    return;
+  }
+}
+
+const MAX_DEPTH = 32;
+
+/** @param {{src:string, i:number}} p @param {number} depth @returns {unknown} */
+function parseValue(p, depth) {
+  if (depth > MAX_DEPTH) throw new Error("nested too deeply");
+  skipTrivia(p);
+  const s = p.src;
+  const c = s[p.i];
+  if (c === "{") return parseObject(p, depth);
+  if (c === "[") return parseArray(p, depth);
+  if (c === '"' || c === "'") return parseQuoted(p, c);
+  if (c === "`") return parseTemplate(p);
+  const num = /^-?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?/.exec(s.slice(p.i));
+  if (num && !/[A-Za-z0-9_$]/.test(s[p.i + num[0].length] ?? "")) {
+    p.i += num[0].length;
+    return Number(num[0]);
+  }
+  for (const [word, v] of /** @type {const} */ ([["true", true], ["false", false], ["null", null]])) {
+    if (s.startsWith(word, p.i) && !/[A-Za-z0-9_$]/.test(s[p.i + word.length] ?? "")) {
+      p.i += word.length;
+      return v;
+    }
+  }
+  const found = /^[^\s,}\]]{1,20}/.exec(s.slice(p.i))?.[0] ?? "the end of the script";
+  throw new Error(`found ${JSON.stringify(found)} where a string, number, boolean, null, array or object belongs`);
+}
+
+/** @param {{src:string, i:number}} p @param {number} depth */
+function parseObject(p, depth) {
+  const s = p.src;
+  p.i++; // {
+  /** @type {Record<string, unknown>} */
+  const out = {};
+  for (;;) {
+    skipTrivia(p);
+    if (s[p.i] === "}") {
+      p.i++;
+      return out;
+    }
+    let key;
+    const c = s[p.i];
+    if (c === '"' || c === "'") key = parseQuoted(p, c);
+    else {
+      const id = /^[A-Za-z_$][A-Za-z0-9_$]*/.exec(s.slice(p.i)) ?? /^\d+/.exec(s.slice(p.i));
+      if (!id) throw new Error(`found ${JSON.stringify(s.slice(p.i, p.i + 10) || "the end of the script")} where a property name belongs`);
+      key = id[0];
+      p.i += id[0].length;
+    }
+    if (key === "__proto__") throw new Error('the key "__proto__" is not allowed');
+    skipTrivia(p);
+    if (s[p.i] !== ":") throw new Error(`property "${key}" needs ": value" (shorthand properties and methods are not literals)`);
+    p.i++;
+    out[key] = parseValue(p, depth + 1);
+    skipTrivia(p);
+    if (s[p.i] === ",") {
+      p.i++;
+      continue;
+    }
+    if (s[p.i] === "}") continue;
+    throw new Error(`expected "," or "}" after property "${key}"`);
+  }
+}
+
+/** @param {{src:string, i:number}} p @param {number} depth */
+function parseArray(p, depth) {
+  const s = p.src;
+  p.i++; // [
+  const out = [];
+  for (;;) {
+    skipTrivia(p);
+    if (s[p.i] === "]") {
+      p.i++;
+      return out;
+    }
+    out.push(parseValue(p, depth + 1));
+    skipTrivia(p);
+    if (s[p.i] === ",") {
+      p.i++;
+      continue;
+    }
+    if (s[p.i] === "]") continue;
+    throw new Error('expected "," or "]" in an array');
+  }
+}
+
+/** @param {{src:string, i:number}} p @param {string} quote */
+function parseQuoted(p, quote) {
+  const s = p.src;
+  p.i++;
+  let out = "";
+  for (;;) {
+    if (p.i >= s.length) throw new Error("a string is not closed");
+    const c = s[p.i];
+    if (c === quote) {
+      p.i++;
+      return out;
+    }
+    if (c === "\n" || c === "\r") throw new Error("a quoted string cannot span lines (use a template literal)");
+    if (c === "\\") {
+      out += readEscape(p);
+      continue;
+    }
+    out += c;
+    p.i++;
+  }
+}
+
+/** @param {{src:string, i:number}} p */
+function parseTemplate(p) {
+  const s = p.src;
+  p.i++;
+  let out = "";
+  for (;;) {
+    if (p.i >= s.length) throw new Error("a template literal is not closed");
+    const c = s[p.i];
+    if (c === "`") {
+      p.i++;
+      return out;
+    }
+    if (c === "$" && s[p.i + 1] === "{") throw new Error("a template literal in meta cannot contain ${…}");
+    if (c === "\\") {
+      out += readEscape(p);
+      continue;
+    }
+    out += c;
+    p.i++;
+  }
+}
+
+/** @param {{src:string, i:number}} p */
+function readEscape(p) {
+  const s = p.src;
+  const c = s[p.i + 1];
+  p.i += 2;
+  /** @type {Record<string,string>} */
+  const simple = { n: "\n", t: "\t", r: "\r", b: "\b", f: "\f", v: "\v", 0: "\0" };
+  if (c === undefined) throw new Error("a string ends in a backslash");
+  if (c in simple && !(c === "0" && /\d/.test(s[p.i] ?? ""))) return simple[c];
+  if (c === "\n") return "";
+  if (c === "\r") {
+    if (s[p.i] === "\n") p.i++;
+    return "";
+  }
+  if (c === "x") {
+    const h = /^[0-9a-fA-F]{2}/.exec(s.slice(p.i));
+    if (!h) throw new Error("a \\x escape needs two hex digits");
+    p.i += 2;
+    return String.fromCharCode(parseInt(h[0], 16));
+  }
+  if (c === "u") {
+    const braced = /^\{([0-9a-fA-F]{1,6})\}/.exec(s.slice(p.i));
+    if (braced) {
+      p.i += braced[0].length;
+      const cp = parseInt(braced[1], 16);
+      if (cp > 0x10ffff) throw new Error("a \\u{…} escape is out of range");
+      return String.fromCodePoint(cp);
+    }
+    const h = /^[0-9a-fA-F]{4}/.exec(s.slice(p.i));
+    if (!h) throw new Error("a \\u escape needs four hex digits");
+    p.i += 4;
+    return String.fromCharCode(parseInt(h[0], 16));
+  }
+  if (/[1-9]/.test(c)) throw new Error("octal escapes are not allowed");
+  return c;
+}
+
+/**
+ * @param {unknown} v
+ * @returns {{ok:true, meta:WorkflowMeta}|{ok:false, error:string}}
+ */
+export function checkMeta(v) {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return { ok: false, error: "meta must be an object" };
+  const m = /** @type {Record<string, unknown>} */ (v);
+  if (typeof m.name !== "string" || m.name.trim() === "") return { ok: false, error: "meta.name must be a non-empty string" };
+  if (m.name.length > MAX_NAME_CHARS) return { ok: false, error: `meta.name is longer than ${MAX_NAME_CHARS} characters` };
+  if (typeof m.description !== "string" || m.description.trim() === "") return { ok: false, error: "meta.description must be a non-empty string" };
+  if (m.description.length > MAX_DESCRIPTION_CHARS) return { ok: false, error: `meta.description is longer than ${MAX_DESCRIPTION_CHARS} characters` };
+  /** @type {Array<{title:string, detail?:string}>} */
+  const phases = [];
+  if (m.phases !== undefined) {
+    if (!Array.isArray(m.phases)) return { ok: false, error: "meta.phases must be an array" };
+    if (m.phases.length > MAX_PHASES) return { ok: false, error: `meta.phases has more than ${MAX_PHASES} entries` };
+    for (const [i, ph] of m.phases.entries()) {
+      if (typeof ph === "string" && ph.trim() !== "") phases.push({ title: ph });
+      else if (ph && typeof ph === "object" && !Array.isArray(ph) && typeof (/** @type any */ (ph).title) === "string" && /** @type any */ (ph).title.trim() !== "") {
+        const detail = /** @type any */ (ph).detail;
+        if (detail !== undefined && typeof detail !== "string") return { ok: false, error: `meta.phases[${i}].detail must be a string` };
+        phases.push(detail === undefined ? { title: /** @type any */ (ph).title } : { title: /** @type any */ (ph).title, detail });
+      } else return { ok: false, error: `meta.phases[${i}] must be a title string or {title, detail?}` };
+    }
+  }
+  return { ok: true, meta: { name: m.name.trim(), description: m.description.trim(), phases } };
+}