@hyperdreamer/pi-webui 1.10.7 → 1.11.0-beta.10

package/optional-skills/deterministic-subagent-driven-development/scripts/lib/plan-policy.mjs

@@ -0,0 +1,350 @@
+/**
+ * Plan parsing and tier derivation for the deterministic SDD controller.
+ *
+ * The acceptance grammar below is the single source of truth. Documentation may
+ * restate it but never redefines it.
+ */
+
+/**
+ * The frozen tier ladder, in ascending capability order.
+ *
+ * Lowercase is the identifier, matching `MODEL_TIERS` in PI WEBUI's shared API
+ * types, the `modelTiers` config keys, and the `tier` parameter that
+ * `spawn_subsession` accepts. TitleCase exists only for display: plan files
+ * write `**Implementer tier:** Advanced` because a human writes and reviews
+ * them, and the parser normalizes that to `advanced` at the boundary. Keeping
+ * one conversion point here means no dispatch site needs to remember to
+ * lowercase a tier before handing it to the tool.
+ */
+export const TIERS = Object.freeze([
+  "economy",
+  "fast",
+  "standard",
+  "advanced",
+  "capable",
+  "frontier",
+]);
+
+/** Display labels, mirroring the settings panel's tier label map. */
+const TIER_LABELS = Object.freeze({
+  economy: "Economy",
+  fast: "Fast",
+  standard: "Standard",
+  advanced: "Advanced",
+  capable: "Capable",
+  frontier: "Frontier",
+});
+
+const TASK_HEADING = /^## Task ([1-9][0-9]*): (\S(?:.*\S)?)$/u;
+const TIER_FIELD = /^\*\*Implementer tier:\*\* (Economy|Fast|Standard|Advanced|Capable|Frontier)$/u;
+const GLOBAL_HEADING = /^## Global Constraints$/u;
+const TASK_LIKE_ATX = /^ {0,3}#{1,}[ \t]+Task\b/u;
+const BACKTICK_OPEN = /^ {0,3}(`{3,})([^`]*)$/u;
+const TILDE_OPEN = /^ {0,3}(~{3,})(.*)$/u;
+const ANY_H2 = /^## /u;
+const INDENTED_CODE = /^ {4,}/u;
+
+const STANDARD_FLOOR_INDEX = TIERS.indexOf("standard");
+const FRONTIER_INDEX = TIERS.length - 1;
+
+/** Rungs added to the implementer tier for each fix round. */
+const FIX_ROUND_ESCALATION = Object.freeze({ 1: 0, 2: 0, 3: 0, 4: 1, 5: 2 });
+
+/**
+ * The single validating tier lookup every formula resolves through.
+ *
+ * Accepts only the lowercase identifier. A TitleCase value reaching this point
+ * means a caller bypassed the parser's normalization, which is a defect worth
+ * failing on rather than silently coercing.
+ */
+function tierIndex(tier) {
+  const index = TIERS.indexOf(tier);
+  if (index < 0) throw new Error(`unknown tier: ${String(tier)}`);
+  return index;
+}
+
+/** The display label for a tier, for prose and human-facing output. */
+export function tierLabel(tier) {
+  return TIER_LABELS[TIERS[tierIndex(tier)]];
+}
+
+function cap(index) {
+  return TIERS[Math.min(index, FRONTIER_INDEX)];
+}
+
+/**
+ * Reviewers sit one rung above the implementer, never below Standard and never
+ * above Frontier.
+ */
+export function reviewerTier(implementer) {
+  return cap(Math.max(STANDARD_FLOOR_INDEX, tierIndex(implementer) + 1));
+}
+
+/** Re-reviewers use the same derivation as reviewers. */
+export function reReviewerTier(implementer) {
+  return reviewerTier(implementer);
+}
+
+/** Fixers match the implementer through round 3, then escalate. */
+export function fixerTier(implementer, round) {
+  const index = tierIndex(implementer);
+  if (!Number.isInteger(round) || round < 1 || round > 5) {
+    throw new Error(`fix round must be an integer from 1 through 5, received ${String(round)}`);
+  }
+  return cap(index + FIX_ROUND_ESCALATION[round]);
+}
+
+/** The final reviewer always runs at the top of the ladder. */
+export function finalReviewerTier() {
+  return TIERS[FRONTIER_INDEX];
+}
+
+/**
+ * The human-readable tier echo.
+ *
+ * This is display text, not a control channel. `spawn_subsession` selects a
+ * model from its typed `tier` parameter; a `Model tier: <tier>` line in a
+ * rendered prompt has no effect on which model runs. It exists so a human
+ * reading a transcript can see the intended tier, and so renderer/formula
+ * divergence is detectable.
+ */
+export function tierEcho(tier) {
+  return `Model tier: ${TIERS[tierIndex(tier)]}`;
+}
+
+/** @deprecated Use `tierEcho`; retained for older controller instructions. */
+export function tierDirective(tier) {
+  return tierEcho(tier);
+}
+
+const ROLES = Object.freeze({
+  implementer: { needsRound: false, resolve: (tier) => TIERS[tierIndex(tier)] },
+  "task-reviewer": { needsRound: false, resolve: reviewerTier },
+  "re-reviewer": { needsRound: false, resolve: reReviewerTier },
+  final: { needsRound: false, resolve: () => finalReviewerTier() },
+  fixer: { needsRound: true, resolve: fixerTier },
+});
+
+/**
+ * Resolve one role's tier and its display echo.
+ *
+ * The round argument is required for the fixer role and rejected for every
+ * other role, so a caller cannot silently pass a round that has no effect.
+ * `directive` is a compatibility alias for controllers written before the
+ * display line stopped looking like a slash command.
+ */
+export function roleTier({ implementer, role, round }) {
+  const definition = ROLES[role];
+  if (definition === undefined) throw new Error(`unknown role: ${String(role)}`);
+
+  if (definition.needsRound && round === undefined) {
+    throw new Error(`role ${role} requires a fix round`);
+  }
+  if (!definition.needsRound && round !== undefined) {
+    throw new Error(`role ${role} does not accept a fix round`);
+  }
+
+  const tier = definition.needsRound
+    ? definition.resolve(implementer, round)
+    : definition.resolve(implementer);
+  const echo = tierEcho(tier);
+  return { tier, echo, directive: echo };
+}
+
+class PlanError extends Error {
+  constructor(message, planPath, lineNumber) {
+    super(`${planPath}:${String(lineNumber)}: ${message}`);
+    this.name = "PlanError";
+    this.planPath = planPath;
+    this.lineNumber = lineNumber;
+  }
+}
+
+/**
+ * Detect a fence opener. Returns `{ marker, length }`, `"invalid"` for a
+ * marker-like line that violates its opener grammar, or `null` for prose.
+ */
+function fenceOpener(line) {
+  // Four-or-more-space indented code is ordinary content, never a fence.
+  if (INDENTED_CODE.test(line)) return null;
+
+  const backtick = BACKTICK_OPEN.exec(line);
+  if (backtick !== null) return { marker: "`", length: backtick[1].length };
+
+  const tilde = TILDE_OPEN.exec(line);
+  if (tilde !== null) return { marker: "~", length: tilde[1].length };
+
+  // A line that starts with three or more markers but matched no opener grammar
+  // is rejected rather than silently treated as prose.
+  if (/^ {0,3}`{3,}/u.test(line) || /^ {0,3}~{3,}/u.test(line)) return "invalid";
+  return null;
+}
+
+/** Does `line` close a fence opened with `opener`? */
+function closesFence(line, opener) {
+  if (INDENTED_CODE.test(line)) return false;
+  const pattern = opener.marker === "`"
+    ? /^ {0,3}(`{3,})[ \t]*$/u
+    : /^ {0,3}(~{3,})[ \t]*$/u;
+  const match = pattern.exec(line);
+  return match !== null && match[1].length >= opener.length;
+}
+
+export function parsePlanText(planText, planPath = "<plan>") {
+  const lines = String(planText).replaceAll("\r\n", "\n").split("\n");
+
+  let globalConstraints = null;
+  let sawGlobalConstraints = false;
+  const tasks = [];
+  /** The section currently collecting body lines, or null. */
+  let current = null;
+  let openFence = null;
+  let openFenceLine = 0;
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    const lineNumber = index + 1;
+
+    if (openFence !== null) {
+      // Inside a fence, test the closer before any opener logic.
+      if (closesFence(line, openFence)) {
+        openFence = null;
+      }
+      if (current !== null) current.body.push(line);
+      continue;
+    }
+
+    const opener = fenceOpener(line);
+    if (opener === "invalid") {
+      throw new PlanError("malformed fence opener", planPath, lineNumber);
+    }
+    if (opener !== null) {
+      openFence = opener;
+      openFenceLine = lineNumber;
+      if (current !== null) current.body.push(line);
+      continue;
+    }
+
+    const taskMatch = TASK_HEADING.exec(line);
+    if (taskMatch !== null) {
+      current = {
+        kind: "task",
+        number: Number(taskMatch[1]),
+        title: taskMatch[2],
+        implementerTier: null,
+        tierLine: 0,
+        body: [],
+        headingLine: lineNumber,
+      };
+      tasks.push(current);
+      continue;
+    }
+
+    if (GLOBAL_HEADING.test(line)) {
+      if (sawGlobalConstraints) {
+        throw new PlanError("duplicate Global Constraints section", planPath, lineNumber);
+      }
+      if (tasks.length > 0) {
+        throw new PlanError("Global Constraints must precede the first task", planPath, lineNumber);
+      }
+      sawGlobalConstraints = true;
+      current = { kind: "global", body: [] };
+      globalConstraints = current;
+      continue;
+    }
+
+    // Any task-like ATX heading outside a fence that is not canonical is an
+    // error. The diagnostic names the depth found, the depth required, and the
+    // tier line, because the most common source of a non-canonical plan is the
+    // `writing-plans` skill, which emits `### Task N:` with no tier field. A bare
+    // "not canonical" would leave the operator guessing at two separate repairs.
+    if (TASK_LIKE_ATX.test(line) && !INDENTED_CODE.test(line)) {
+      const depth = /^ {0,3}(#+)/u.exec(line)?.[1] ?? "#";
+      const title = line.replace(/^ {0,3}#+[ \t]+/u, "");
+      throw new PlanError(
+        [
+          `task-like heading is not canonical: ${line}`,
+          `found heading depth "${depth}" but the deterministic controller requires "##"`,
+          `rewrite it as: ## ${title.startsWith("Task") ? title : `Task N: ${title}`}`,
+          'and give every task a tier line on its own: **Implementer tier:** Advanced',
+          "a tier-annotated plan is a precondition of tiered dispatch; the controller never guesses a tier",
+        ].join("\n  "),
+        planPath,
+        lineNumber,
+      );
+    }
+
+    // A non-canonical H2 terminates the open section without being captured.
+    if (ANY_H2.test(line)) {
+      current = null;
+      continue;
+    }
+
+    if (current === null) continue;
+
+    if (current.kind === "task") {
+      const tierMatch = TIER_FIELD.exec(line);
+      if (tierMatch !== null) {
+        if (current.implementerTier !== null) {
+          throw new PlanError(
+            `duplicate Implementer tier for Task ${String(current.number)}`,
+            planPath,
+            lineNumber,
+          );
+        }
+        // Plan files carry TitleCase for readability; the identifier is
+        // lowercase everywhere past this boundary.
+        current.implementerTier = tierMatch[1].toLowerCase();
+        current.tierLine = lineNumber;
+        continue;
+      }
+      // A tier-like line that failed the exact grammar is a hard error.
+      if (/^\s*\*\*Implementer tier:\*\*/u.test(line)) {
+        throw new PlanError(`malformed Implementer tier field: ${line}`, planPath, lineNumber);
+      }
+    }
+
+    current.body.push(line);
+  }
+
+  if (openFence !== null) {
+    throw new PlanError("unterminated fence", planPath, openFenceLine);
+  }
+  if (tasks.length === 0) {
+    throw new PlanError("plan declares no tasks", planPath, lines.length);
+  }
+
+  for (let position = 0; position < tasks.length; position += 1) {
+    const task = tasks[position];
+    const expected = position + 1;
+    if (task.number !== expected) {
+      throw new PlanError(
+        `expected Task ${String(expected)} but found Task ${String(task.number)}`,
+        planPath,
+        task.headingLine,
+      );
+    }
+    if (task.implementerTier === null) {
+      throw new PlanError(
+        `Task ${String(task.number)} has no Implementer tier
+  add a line reading exactly: **Implementer tier:** <Economy|Fast|Standard|Advanced|Capable|Frontier>
+  a tier-annotated plan is a precondition of tiered dispatch; the controller never guesses a tier`,
+        planPath,
+        task.headingLine,
+      );
+    }
+  }
+
+  return {
+    planPath,
+    globalConstraints: globalConstraints === null
+      ? null
+      : globalConstraints.body.join("\n").trim(),
+    tasks: tasks.map((task) => ({
+      number: task.number,
+      title: task.title,
+      implementerTier: task.implementerTier,
+      body: task.body.join("\n").trim(),
+    })),
+  };
+}

package/optional-skills/deterministic-subagent-driven-development/scripts/lib/prompt-renderer.mjs

@@ -0,0 +1,290 @@
+/**
+ * Deterministic prompt rendering.
+ *
+ * A rendered prompt is dispatch input whose exact bytes are stored in state and
+ * reissued verbatim on recovery. Rendering is therefore a pure function of
+ * (tier, role, context): no clock, no working directory, no environment, no
+ * template evaluation.
+ *
+ * There is deliberately no general-purpose templating here. A template engine
+ * would let a context value introduce a tier label, a heading, or another
+ * placeholder, and the prompt is the one artifact a child treats as instructions.
+ * Role contracts are static files copied verbatim; context is emitted as a
+ * validated, escaped key/value list.
+ */
+
+import { readFileSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+
+import { TIERS } from "./plan-policy.mjs";
+
+/** Maximum bytes for a rendered prompt, matching the dispatch-intent bound. */
+const MAX_PROMPT_BYTES = 384 * 1024;
+
+/** Maximum UTF-8 bytes for any single path. */
+const MAX_PATH_BYTES = 4096;
+
+/** Maximum finding records the contract allows in one ledger. */
+const MAX_FINDING_IDS = 256;
+
+const TIER_SET = new Set(TIERS);
+
+/** A rejected render. */
+export class RenderError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RenderError";
+  }
+}
+
+const fail = (message) => {
+  throw new RenderError(message);
+};
+
+/**
+ * Role definitions.
+ *
+ * `paths` and `scalars` are the complete accepted key set for each role. Anything
+ * else is rejected rather than ignored, so a typo in a context file fails loudly
+ * instead of silently omitting information a child needed.
+ */
+const ROLES = Object.freeze({
+  implementer: {
+    template: "implementer.md",
+    paths: ["briefPath", "reportPath"],
+    scalars: ["task"],
+    optional: ["contextPath", "findingPackagePath", "baseSha", "headSha", "round"],
+  },
+  "task-reviewer": {
+    template: "task-reviewer.md",
+    paths: ["briefPath", "reportPath"],
+    scalars: ["task"],
+    optional: ["baseSha", "headSha", "reviewPackagePath"],
+  },
+  "re-reviewer": {
+    template: "re-reviewer.md",
+    paths: ["briefPath", "reportPath"],
+    scalars: ["task"],
+    optional: ["baseSha", "headSha", "reviewPackagePath", "findingIds", "round"],
+  },
+  "final-reviewer": {
+    template: "final-reviewer.md",
+    paths: ["briefPath", "reportPath"],
+    scalars: ["task"],
+    optional: ["baseSha", "headSha", "reviewPackagePath", "findingIds", "ledgerPath"],
+  },
+});
+
+/** Keys every role pins, naming the roots that confine every other path. */
+const ROOT_KEYS = Object.freeze(["worktree", "runRoot"]);
+
+/** Emission order. Fixed, because byte-exact output cannot depend on key order. */
+const FIELD_ORDER = Object.freeze([
+  "worktree",
+  "runRoot",
+  "task",
+  "round",
+  "baseSha",
+  "headSha",
+  "briefPath",
+  "contextPath",
+  "reportPath",
+  "reviewPackagePath",
+  "findingPackagePath",
+  "ledgerPath",
+  "findingIds",
+]);
+
+const SHA = /^[0-9a-f]{40}$/u;
+const FINDING_ID = /^[A-Za-z0-9._:-]{1,64}$/u;
+
+/** Reject control characters anywhere in a rendered value. */
+const requireClean = (value, field) => {
+  // eslint-disable-next-line no-control-regex -- rejecting these is the point.
+  if (/[\u0000-\u001f\u007f]/u.test(value)) {
+    fail(`${field} must not contain a control character`);
+  }
+  return value;
+};
+
+/**
+ * Validate a path: absolute, normalized, bounded, and confined to a pinned root.
+ *
+ * When the path already exists its real path is checked too, so a symlink cannot
+ * point a "confined" path at content outside the run. For an output path the real
+ * parent is checked, since the file itself will not exist yet.
+ */
+const validatePath = (value, field, roots, { mustExist = false } = {}) => {
+  if (typeof value !== "string" || value.length === 0) {
+    fail(`${field} must be a non-empty string`);
+  }
+  requireClean(value, field);
+  if (Buffer.byteLength(value, "utf8") > MAX_PATH_BYTES) {
+    fail(`${field} exceeds ${String(MAX_PATH_BYTES)} bytes`);
+  }
+  if (!isAbsolute(value)) fail(`${field} must be an absolute path: ${value}`);
+  if (value.split("/").includes("..")) {
+    fail(`${field} must be normalized and contain no ".." segment`);
+  }
+
+  const within = (candidate) =>
+    roots.some((root) => candidate === root || candidate.startsWith(`${root}/`));
+
+  if (!within(resolve(value))) {
+    fail(`${field} must live beneath a pinned root: ${value}`);
+  }
+
+  let real;
+  try {
+    real = realpathSync(value);
+  } catch {
+    real = null;
+  }
+  if (real === null && mustExist) fail(`${field} does not exist: ${value}`);
+  if (real !== null && !within(real)) {
+    fail(`${field} resolves outside the pinned roots via a symlink: ${value} -> ${real}`);
+  }
+  if (real === null) {
+    // The file may legitimately not exist yet; its parent still must not escape.
+    let parentReal;
+    try {
+      parentReal = realpathSync(dirname(value));
+    } catch {
+      fail(`${field} names a directory that does not exist: ${dirname(value)}`);
+    }
+    if (!within(parentReal)) {
+      fail(`${field} has a real parent outside the pinned roots: ${parentReal}`);
+    }
+  }
+  return value;
+};
+
+/** Render one context value as a single line. */
+const renderValue = (key, value) => {
+  if (Array.isArray(value)) return `- ${key}: ${value.join(", ")}`;
+  if (typeof value === "number") return `- ${key}: ${String(value)}`;
+  return `- ${key}: ${value}`;
+};
+
+/**
+ * Validate a context object against its role.
+ *
+ * Returns the accepted subset in a fixed emission order.
+ */
+const validateContext = (role, context) => {
+  const definition = ROLES[role];
+  const accepted = new Set([
+    ...ROOT_KEYS,
+    ...definition.paths,
+    ...definition.scalars,
+    ...definition.optional,
+  ]);
+
+  const unexpected = Object.keys(context).filter((key) => !accepted.has(key));
+  if (unexpected.length > 0) {
+    fail(`unexpected context key(s) for role ${role}: ${unexpected.join(", ")}`);
+  }
+
+  for (const key of ROOT_KEYS) {
+    const value = context[key];
+    if (typeof value !== "string" || !isAbsolute(value)) {
+      fail(`${key} must be a pinned absolute path`);
+    }
+  }
+  const roots = ROOT_KEYS.map((key) => resolve(context[key]));
+
+  for (const key of definition.paths) {
+    if (context[key] === undefined) fail(`role ${role} requires ${key}`);
+    validatePath(context[key], key, roots);
+  }
+  for (const key of definition.scalars) {
+    const value = context[key];
+    if (!Number.isInteger(value) || value < 1) {
+      fail(`${key} must be a positive integer for role ${role}`);
+    }
+  }
+
+  for (const key of definition.optional) {
+    const value = context[key];
+    if (value === undefined) continue;
+    if (key.endsWith("Path")) {
+      validatePath(value, key, roots);
+    } else if (key === "baseSha" || key === "headSha") {
+      if (typeof value !== "string" || !SHA.test(value)) {
+        fail(`${key} must be a 40-character lowercase hex object name`);
+      }
+    } else if (key === "round") {
+      if (!Number.isInteger(value) || value < 1 || value > 5) {
+        fail("round must be an integer from 1 to 5");
+      }
+    } else if (key === "findingIds") {
+      if (!Array.isArray(value)) fail("findingIds must be an array");
+      if (value.length > MAX_FINDING_IDS) {
+        fail(
+          `findingIds holds ${String(value.length)} entries, exceeding the ${String(MAX_FINDING_IDS)}-finding bound`,
+        );
+      }
+      for (const [index, id] of value.entries()) {
+        if (typeof id !== "string" || !FINDING_ID.test(id)) {
+          fail(`findingIds[${String(index)}] must match ^[A-Za-z0-9._:-]{1,64}$`);
+        }
+      }
+    } else {
+      fail(`no validation rule for optional key ${key}`);
+    }
+  }
+
+  return FIELD_ORDER.filter((key) => context[key] !== undefined).map((key) => [key, context[key]]);
+};
+
+/**
+ * Render a prompt.
+ *
+ * Byte layout, fixed by contract because dispatch stores and reissues these bytes:
+ *
+ *   Model tier: <tier>\n
+ *   \n
+ *   <role contract, trailing whitespace trimmed>\n
+ *   \n
+ *   ## Dispatch Context\n\n<one "- key: value" line each>\n
+ *   \n
+ *   ## Return Channel\n\n<two lines>\n
+ */
+export function renderPrompt({ tier, role, context, skillRoot }) {
+  if (!TIER_SET.has(tier)) {
+    fail(`unknown tier: ${String(tier)} (expected one of ${TIERS.join(", ")})`);
+  }
+  const definition = ROLES[role];
+  if (definition === undefined) {
+    fail(`unknown role: ${String(role)} (expected one of ${Object.keys(ROLES).join(", ")})`);
+  }
+
+  const fields = validateContext(role, context);
+  const template = readFileSync(join(skillRoot, "prompts", definition.template), "utf8");
+
+  const rendered = [
+    `Model tier: ${tier}`,
+    "",
+    template.trimEnd(),
+    "",
+    "## Dispatch Context",
+    "",
+    ...fields.map(([key, value]) => renderValue(key, value)),
+    "",
+    "## Return Channel",
+    "",
+    `Write exactly one report at ${context.reportPath}.`,
+    "Return exactly one status token defined by your role contract above.",
+    "",
+  ].join("\n");
+
+  if (Buffer.byteLength(rendered, "utf8") > MAX_PROMPT_BYTES) {
+    fail(
+      `rendered prompt is ${String(Buffer.byteLength(rendered, "utf8"))} bytes, exceeding ${String(MAX_PROMPT_BYTES)} (384 KiB)`,
+    );
+  }
+  if (rendered.includes("{{")) {
+    fail("rendered prompt contains an unresolved template marker");
+  }
+  return rendered;
+}