harnery 0.18.0 → 0.19.1

package/src/core/supervisor/read.ts

@@ -1,5 +1,11 @@
-export { readSupervisorPlan, readSupervisorPlans } from "./plan-read.ts";
 export {
+  readSupervisorPlan,
+  readSupervisorPlanReviewReceipt,
+  readSupervisorPlans,
+} from "./plan-read.ts";
+export {
+  MAX_SUPERVISOR_PLAN_REVIEWERS,
+  MAX_SUPERVISOR_PLAN_REVISION_ROUNDS,
   SUPERVISOR_PLAN_SCHEMA_VERSION,
   type SupervisorPlanEvent,
   type SupervisorPlanEventType,
@@ -9,6 +15,13 @@ export {
   type SupervisorPlanProposal,
   type SupervisorPlanRecord,
   type SupervisorPlanRequest,
+  type SupervisorPlanReviewFinding,
+  type SupervisorPlanReviewReceipt,
+  type SupervisorPlanReviewReviewer,
+  type SupervisorPlanReviewRound,
+  type SupervisorPlanReviewStatus,
+  type SupervisorPlanReviewSummary,
+  type SupervisorPlanReviewVerdict,
   type SupervisorPlanStatus,
   type SupervisorPlanTemplate,
   type SupervisorPlanWorkSpec,

package/src/core/supervisor/state.ts

@@ -20,6 +20,8 @@ import type { WorkflowSpecialistProfile } from "../workflow/types.ts";
 import { readSupervisorPlans } from "./plan-read.ts";
 import {
   type CreateSupervisorReplanningInput,
+  MAX_SUPERVISOR_PLAN_REVIEWERS,
+  MAX_SUPERVISOR_PLAN_REVISION_ROUNDS,
   type SupervisorPlanHistory,
   type SupervisorPlanRecord,
   type SupervisorReplanningPolicy,
@@ -157,8 +159,9 @@ export function createSupervisor(input: CreateSupervisorInput): SupervisorRecord
   }
   if (input.rootWorkId) assertWorkId(input.rootWorkId);
   const root = input.rootWorkId ? readWorkItem(coordRoot, input.rootWorkId) : undefined;
+  const limits = normalizeLimits(input.limits);
   const replanning = input.replanning
-    ? normalizeReplanning(input.replanning, input.specialists)
+    ? normalizeReplanning(input.replanning, input.specialists, limits)
     : undefined;
   if (
     mission &&
@@ -180,7 +183,7 @@ export function createSupervisor(input: CreateSupervisorInput): SupervisorRecord
     ),
     root_work_id: input.rootWorkId ?? missionRootId(id),
     specialists: normalizeWorkflowSpecialists(input.specialists),
-    limits: normalizeLimits(input.limits),
+    limits,
     automation: normalizeAutomation(input.automation),
     ...(mission ? { mission } : {}),
     ...(replanning ? { replanning } : {}),
@@ -655,7 +658,7 @@ function validateIntent(intent: SupervisorIntent, goalId: string): void {
   ) {
     throw new Error(`supervisor intent ${goalId} automation policy is not canonical`);
   }
-  if (intent.replanning) validateReplanning(intent.replanning, specialists, goalId);
+  if (intent.replanning) validateReplanning(intent.replanning, specialists, intent.limits, goalId);
 }
 
 function normalizeMission(input: CreateSupervisorMissionInput): SupervisorMission {
@@ -720,6 +723,7 @@ function normalizeAutomation(
 function normalizeReplanning(
   input: CreateSupervisorReplanningInput,
   specialistsInput: Readonly<Record<string, WorkflowSpecialistProfile>>,
+  limits: SupervisorLimits,
 ): SupervisorReplanningPolicy {
   const specialists = normalizeWorkflowSpecialists(specialistsInput);
   const plannerSpecialist = bounded(input.plannerSpecialist, "planner specialist", 100);
@@ -769,6 +773,9 @@ function normalizeReplanning(
   if (maxWorkItemsPerPlan > maxTotalWorkItems) {
     throw new Error("replanning max_work_items_per_plan cannot exceed max_total_work_items");
   }
+  const review = input.review
+    ? normalizeReviewPolicy(input.review, specialists, plannerSpecialist, limits)
+    : undefined;
   return {
     planner_specialist: plannerSpecialist,
     auto_apply: boolean(input.autoApply ?? false, "replanning auto_apply"),
@@ -776,12 +783,60 @@ function normalizeReplanning(
     max_work_items_per_plan: maxWorkItemsPerPlan,
     max_total_work_items: maxTotalWorkItems,
     templates,
+    ...(review ? { review } : {}),
+  };
+}
+
+function normalizeReviewPolicy(
+  input: NonNullable<CreateSupervisorReplanningInput["review"]>,
+  specialists: Record<string, WorkflowSpecialistProfile>,
+  plannerSpecialist: string,
+  limits: SupervisorLimits,
+): NonNullable<SupervisorReplanningPolicy["review"]> {
+  if (!Array.isArray(input.reviewerSpecialists) || input.reviewerSpecialists.length < 1) {
+    throw new Error("replanning review requires at least one reviewer specialist");
+  }
+  if (input.reviewerSpecialists.length > MAX_SUPERVISOR_PLAN_REVIEWERS) {
+    throw new Error(
+      `replanning review cannot exceed ${MAX_SUPERVISOR_PLAN_REVIEWERS} reviewer specialists`,
+    );
+  }
+  const reviewerSpecialists = input.reviewerSpecialists.map((specialist, index) =>
+    bounded(specialist, `reviewer specialist[${index}]`, 100),
+  );
+  if (new Set(reviewerSpecialists).size !== reviewerSpecialists.length) {
+    throw new Error("replanning reviewer specialists must be unique");
+  }
+  for (const specialist of reviewerSpecialists) {
+    if (!specialists[specialist]) {
+      throw new Error(`reviewer specialist ${specialist} is not present in the frozen team`);
+    }
+    if (specialist === plannerSpecialist) {
+      throw new Error("reviewer specialist cannot be the planner specialist");
+    }
+  }
+  const maxRevisionRounds = nonNegative(
+    input.maxRevisionRounds,
+    "replanning review max_revision_rounds",
+    MAX_SUPERVISOR_PLAN_REVISION_ROUNDS,
+  );
+  const worstCaseAgents =
+    1 + reviewerSpecialists.length * (maxRevisionRounds + 1) + maxRevisionRounds;
+  if (worstCaseAgents > limits.max_agents_per_work) {
+    throw new Error(
+      `replanning review worst-case ${worstCaseAgents} agents exceeds max_agents_per_work ${limits.max_agents_per_work}`,
+    );
+  }
+  return {
+    reviewer_specialists: reviewerSpecialists,
+    max_revision_rounds: maxRevisionRounds,
   };
 }
 
 function validateReplanning(
   policy: SupervisorReplanningPolicy,
   specialists: Record<string, WorkflowSpecialistProfile>,
+  limits: SupervisorLimits,
   goalId: string,
 ): void {
   if (!specialists[policy.planner_specialist]) {
@@ -814,6 +869,37 @@ function validateReplanning(
     rootCapable ||= template.root;
   }
   if (!rootCapable) throw new Error(`supervisor ${goalId} has no root-capable replanning template`);
+  if (policy.review !== undefined) {
+    const review = policy.review;
+    if (
+      !Array.isArray(review.reviewer_specialists) ||
+      review.reviewer_specialists.length < 1 ||
+      review.reviewer_specialists.length > MAX_SUPERVISOR_PLAN_REVIEWERS ||
+      !Number.isSafeInteger(review.max_revision_rounds) ||
+      review.max_revision_rounds < 0 ||
+      review.max_revision_rounds > MAX_SUPERVISOR_PLAN_REVISION_ROUNDS
+    ) {
+      throw new Error(`supervisor ${goalId} replanning review policy is invalid`);
+    }
+    if (new Set(review.reviewer_specialists).size !== review.reviewer_specialists.length) {
+      throw new Error(`supervisor ${goalId} replanning reviewers are not unique`);
+    }
+    for (const specialist of review.reviewer_specialists) {
+      if (!specialists[specialist]) {
+        throw new Error(`supervisor ${goalId} reviewer specialist is not in the frozen team`);
+      }
+      if (specialist === policy.planner_specialist) {
+        throw new Error(`supervisor ${goalId} reviewer specialist cannot be planner`);
+      }
+    }
+    const worstCaseAgents =
+      1 +
+      review.reviewer_specialists.length * (review.max_revision_rounds + 1) +
+      review.max_revision_rounds;
+    if (worstCaseAgents > limits.max_agents_per_work) {
+      throw new Error(`supervisor ${goalId} review policy exceeds the agent budget`);
+    }
+  }
 }
 
 function collectGovernedWork(
@@ -915,6 +1001,13 @@ function positive(value: unknown, field: string, max: number): number {
   return value as number;
 }
 
+function nonNegative(value: unknown, field: string, max: number): number {
+  if (!Number.isSafeInteger(value) || (value as number) < 0 || (value as number) > max) {
+    throw new Error(`${field} must be an integer between 0 and ${max}`);
+  }
+  return value as number;
+}
+
 function boolean(value: unknown, field: string): boolean {
   if (typeof value !== "boolean") throw new Error(`supervisor ${field} must be boolean`);
   return value;

package/src/core/workflow/engine.ts

@@ -58,6 +58,7 @@ import type {
   HarnessName,
   RunReport,
   SpawnResult,
+  StageSchema,
   WorkflowAgentProof,
   WorkflowContext,
   WorkflowEvidenceRecord,
@@ -423,6 +424,9 @@ async function executeWorkflow(
     const assignment = resolveSpecialistAssignment(specialists, prompt, requestedOpts);
     const agentOpts = assignment.opts;
     const assignmentPrompt = assignment.prompt;
+    const dispatchPrompt = agentOpts.schema
+      ? withSchemaContract(assignmentPrompt, agentOpts.schema)
+      : assignmentPrompt;
     let reservedForDispatch = 0;
     let spawnCountClaimed = false;
     const harness = agentOpts.harness ?? defaultHarness;
@@ -487,7 +491,7 @@ async function executeWorkflow(
         max_attempts: maxAttempts,
         max_turns: agentOpts.maxTurns ?? DEFAULT_MAX_TURNS,
         timeout_ms: agentOpts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-        prompt_bytes: Buffer.byteLength(assignmentPrompt),
+        prompt_bytes: Buffer.byteLength(dispatchPrompt),
         isolation,
         network_access: networkAccess,
         current_cost_usd: round4(costUsd + reservedCostUsd),
@@ -609,7 +613,7 @@ async function executeWorkflow(
       });
       log(`[${name}] ${currentStage || "(no stage)"} → ${id} [${harness}] ${label}`);
 
-      let attemptPrompt = assignmentPrompt;
+      let attemptPrompt = dispatchPrompt;
       let last: SpawnResult | null = null;
       let agentCostUsd = 0;
       for (let attempt = 1; attempt <= maxAttempts; attempt++) {
@@ -678,12 +682,16 @@ async function executeWorkflow(
         }
 
         journal("agent.schema_retry", { id, attempt, problems });
-        // Feed the validation failure back verbatim — the retry prompt carries
-        // exactly what was wrong, which is what makes bounded retry converge.
+        // Keep the original cache identity while making the actual output
+        // contract explicit. A full bounded copy of the rejected value lets the
+        // child repair omissions instead of reconstructing an unseen object.
         attemptPrompt =
-          `${assignmentPrompt}\n\nYour previous reply failed validation:\n` +
+          `${dispatchPrompt}\n\nYour previous reply failed validation. ` +
+          `Return a complete replacement value, not a patch.\n\n` +
+          `Previous reply (JSON string): ${JSON.stringify(boundedSchemaReply(last.text))}\n\n` +
+          `Validation problems:\n` +
           `${problems.map((p) => `  - ${p}`).join("\n")}\n` +
-          `Reply with ONLY the corrected JSON object. No prose, no code fences.`;
+          `Reply with ONLY the corrected JSON value. No prose, no code fences.`;
       }
 
       const reason = last?.ok
@@ -892,6 +900,21 @@ async function executeWorkflow(
   }
 }
 
+const MAX_SCHEMA_RETRY_REPLY = 16_000;
+
+function withSchemaContract(prompt: string, schema: StageSchema): string {
+  return (
+    `${prompt}\n\nOutput contract:\n` +
+    `Return ONLY one JSON value matching this schema. Do not use prose or code fences.\n` +
+    `${JSON.stringify(schema)}`
+  );
+}
+
+function boundedSchemaReply(value: string): string {
+  if (value.length <= MAX_SCHEMA_RETRY_REPLY) return value;
+  return `${value.slice(0, MAX_SCHEMA_RETRY_REPLY)}\n[truncated by Harnery]`;
+}
+
 /** Stable identity for one agent() call, for the resume cache. The ORIGINAL
  * prompt (never a retry-mutated one) plus everything that changes behavior. */
 function agentCallKey(

package/src/core/workflow/types.ts

@@ -201,11 +201,20 @@ export interface HarnessEvidenceCapability {
 /** JSON-schema *subset* accepted by stage gates (see validate.ts). */
 export interface StageSchema {
   type: "object" | "array" | "string" | "number" | "boolean";
+  /** Exact-one branch selection, evaluated before the base schema. */
+  oneOf?: StageSchema[];
   /** type=object */
   properties?: Record<string, StageSchema>;
   required?: string[];
+  additionalProperties?: boolean;
   /** type=array */
   items?: StageSchema;
+  minItems?: number;
+  maxItems?: number;
+  /** type=string */
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
   /** any type: closed value set (compared with ===) */
   enum?: Array<string | number | boolean>;
 }

package/src/core/workflow/validate.ts

@@ -1,9 +1,11 @@
 /**
  * Minimal validator for the StageSchema JSON-schema subset. Deliberately tiny:
  * a full JSON Schema implementation would pull a dependency (ajv) for
- * validation depth workflow gates don't need. Supported: type, properties,
- * required, items, enum. Returns a list of human-readable problems (empty =
- * valid) so the engine can feed failures back into the retry prompt verbatim.
+ * validation depth workflow gates don't need. Supported: type, oneOf,
+ * properties, required, additionalProperties, items, minItems/maxItems,
+ * minLength/maxLength, pattern, and enum.
+ * Returns a list of human-readable problems (empty = valid) so the engine can
+ * feed failures back into the retry prompt verbatim.
  */
 
 import type { StageSchema } from "./types.ts";
@@ -11,6 +13,23 @@ import type { StageSchema } from "./types.ts";
 export function validateAgainstSchema(value: unknown, schema: StageSchema, path = "$"): string[] {
   const problems: string[] = [];
 
+  if (schema.oneOf) {
+    const branches = schema.oneOf.map((branch) => validateAgainstSchema(value, branch, path));
+    const matches = branches.filter((branch) => branch.length === 0).length;
+    if (matches !== 1) {
+      if (matches > 1) {
+        return [`${path}: expected exactly one schema option to match, got ${matches}`];
+      }
+      return [
+        `${path}: expected exactly one schema option to match`,
+        ...branches.map(
+          (branch, index) =>
+            `${path}: option ${index + 1}: ${branch.slice(0, 4).join("; ") || "did not match"}`,
+        ),
+      ];
+    }
+  }
+
   if (schema.enum) {
     if (!schema.enum.some((v) => v === value)) {
       problems.push(`${path}: expected one of ${JSON.stringify(schema.enum)}, got ${short(value)}`);
@@ -30,10 +49,22 @@ export function validateAgainstSchema(value: unknown, schema: StageSchema, path
       for (const [key, sub] of Object.entries(schema.properties ?? {})) {
         if (key in obj) problems.push(...validateAgainstSchema(obj[key], sub, `${path}.${key}`));
       }
+      if (schema.additionalProperties === false) {
+        const allowed = new Set(Object.keys(schema.properties ?? {}));
+        for (const key of Object.keys(obj)) {
+          if (!allowed.has(key)) problems.push(`${path}.${key}: unexpected property`);
+        }
+      }
       return problems;
     }
     case "array": {
       if (!Array.isArray(value)) return [`${path}: expected array, got ${short(value)}`];
+      if (schema.minItems !== undefined && value.length < schema.minItems) {
+        problems.push(`${path}: expected at least ${schema.minItems} item(s), got ${value.length}`);
+      }
+      if (schema.maxItems !== undefined && value.length > schema.maxItems) {
+        problems.push(`${path}: expected at most ${schema.maxItems} item(s), got ${value.length}`);
+      }
       if (schema.items) {
         for (const [i, item] of value.entries()) {
           problems.push(
@@ -43,7 +74,31 @@ export function validateAgainstSchema(value: unknown, schema: StageSchema, path
       }
       return problems;
     }
-    case "string":
+    case "string": {
+      if (typeof value !== "string") {
+        return [`${path}: expected string, got ${short(value)}`];
+      }
+      if (schema.minLength !== undefined && value.length < schema.minLength) {
+        problems.push(
+          `${path}: expected at least ${schema.minLength} character(s), got ${value.length}`,
+        );
+      }
+      if (schema.maxLength !== undefined && value.length > schema.maxLength) {
+        problems.push(
+          `${path}: expected at most ${schema.maxLength} character(s), got ${value.length}`,
+        );
+      }
+      if (schema.pattern !== undefined) {
+        try {
+          if (!new RegExp(schema.pattern).test(value)) {
+            problems.push(`${path}: expected string matching ${JSON.stringify(schema.pattern)}`);
+          }
+        } catch {
+          problems.push(`${path}: schema pattern is invalid`);
+        }
+      }
+      return problems;
+    }
     case "number":
     case "boolean": {
       if (typeof value !== schema.type) {

package/src/lib/browser/client.ts

@@ -1,6 +1,7 @@
 import { mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
+import axe from "axe-core";
 import {
   type BrowserContext,
   type ConsoleMessage,
@@ -10,6 +11,13 @@ import {
   type Request,
 } from "playwright";
 import type { CookieJar, Cookie as JarCookie } from "../cookies/index.ts";
+import {
+  buildClearLayoutLintAnnotationsScript,
+  buildLayoutLintAnnotateScript,
+  buildLayoutLintCheck,
+  type LayoutLintRequest,
+  type LayoutLintResult,
+} from "./geometry.js";
 import {
   buildClearLayoutAnnotationsScript,
   buildLayoutAnnotateScript,
@@ -24,6 +32,13 @@ import {
   buildRuntsCheck,
   type RuntsResult,
 } from "./runts.js";
+import {
+  buildClearTargetSizeAnnotationsScript,
+  buildTargetSizeAnnotateScript,
+  buildTargetSizeCheck,
+  type TargetSizeProfile,
+  type TargetSizeResult,
+} from "./target-size.js";
 import {
   buildAnnotateScript,
   buildClearAnnotationsScript,
@@ -441,6 +456,53 @@ export class Browser {
     await this.currentPage.evaluate(buildClearLayoutAnnotationsScript());
   }
 
+  /** Run the selector-scoped rendered-geometry rule family in one page evaluation. */
+  async checkLayoutLint(request: LayoutLintRequest): Promise<LayoutLintResult> {
+    return await this.currentPage.evaluate(buildLayoutLintCheck(), request);
+  }
+
+  /** Draw one document-space annotation layer for rendered-geometry results. */
+  async annotateLayoutLint(result: LayoutLintResult): Promise<void> {
+    await this.currentPage.evaluate(buildLayoutLintAnnotateScript(), result);
+  }
+
+  /** Remove rendered-geometry annotations. */
+  async clearLayoutLintAnnotations(): Promise<void> {
+    await this.currentPage.evaluate(buildClearLayoutLintAnnotationsScript());
+  }
+
+  /**
+   * Run the target-size rule against the page or explicit scopes. The
+   * dependency's browser bundle is evaluated directly in the page context so
+   * a document CSP cannot silently block a script element.
+   */
+  async checkTargetSize(
+    selectors: Array<string | null>,
+    profile: TargetSizeProfile,
+  ): Promise<TargetSizeResult[]> {
+    await this.currentPage.evaluate(axe.source);
+    const results: TargetSizeResult[] = [];
+    for (const selector of selectors) {
+      results.push(
+        await this.currentPage.evaluate(buildTargetSizeCheck(), {
+          selector,
+          profile,
+        }),
+      );
+    }
+    return results;
+  }
+
+  /** Draw target-size failures and unknowns on the screenshot. */
+  async annotateTargetSize(results: TargetSizeResult[]): Promise<void> {
+    await this.currentPage.evaluate(buildTargetSizeAnnotateScript(), results);
+  }
+
+  /** Remove target-size annotations. */
+  async clearTargetSizeAnnotations(): Promise<void> {
+    await this.currentPage.evaluate(buildClearTargetSizeAnnotationsScript());
+  }
+
   /**
    * Inject a script that runs in every page context before page scripts
    * execute. Useful for seeding localStorage before an SSR/CSR comparison;