zob-harness 0.1.0

package/.pi/extensions/zob-harness/src/orchestration/lead-plan.ts

@@ -0,0 +1,192 @@
+import { loadProjectAgents } from "../agents.js";
+import { validateOutputContractId } from "../output-contracts.js";
+import { validateAllowedPathPolicy, validateDelegateTaskWriteScope, validateForbiddenPathPolicy, validateToolList } from "../safety.js";
+import { sha256 } from "../utils/hashing.js";
+import { isRecord } from "../utils/records.js";
+
+export interface LeadPlanWorkerContract {
+  worker_id: string;
+  lead_id?: string;
+  agent: string;
+  task: string;
+  expected_outcome: string;
+  required_tools: string[];
+  output_contract: string;
+  must_do: string[];
+  must_not_do: string[];
+  context: string;
+  allowed_paths?: string[];
+  forbidden_paths?: string[];
+  model_class?: string;
+}
+
+export interface LeadPlanWorkerContractExtraction {
+  schema: "zob.lead-plan-worker-contract-extraction.v1";
+  contracts: LeadPlanWorkerContract[];
+  errors: string[];
+}
+
+export interface LeadPlanWorkerContractValidationOptions {
+  leadId?: string;
+  allowedWorkerIds?: string[];
+  allowedTools?: string[];
+  supervisedReadonly?: boolean;
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function parseJsonCandidate(text: string): unknown | undefined {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+function jsonCandidates(output: string): unknown[] {
+  const candidates: unknown[] = [];
+  const trimmed = output.trim();
+  const whole = parseJsonCandidate(trimmed);
+  if (whole !== undefined) candidates.push(whole);
+
+  for (const match of trimmed.matchAll(/```(?:json)?\s*([\s\S]*?)```/gi)) {
+    const parsed = parseJsonCandidate(match[1].trim());
+    if (parsed !== undefined) candidates.push(parsed);
+  }
+
+  for (const match of trimmed.matchAll(/<worker_contracts>\s*([\s\S]*?)\s*<\/worker_contracts>/gi)) {
+    const parsed = parseJsonCandidate(match[1].trim());
+    if (parsed !== undefined) candidates.push(parsed);
+  }
+
+  return candidates;
+}
+
+function contractsRoot(candidate: unknown): unknown[] | undefined {
+  if (Array.isArray(candidate)) return candidate;
+  if (!isRecord(candidate)) return undefined;
+  if (Array.isArray(candidate.worker_contracts)) return candidate.worker_contracts;
+  if (Array.isArray(candidate.workerContracts)) return candidate.workerContracts;
+  return undefined;
+}
+
+function normalizeContract(value: unknown, index: number): { contract?: LeadPlanWorkerContract; errors: string[] } {
+  const errors: string[] = [];
+  if (!isRecord(value)) return { errors: [`worker_contracts[${index}] must be an object`] };
+
+  const workerId = typeof value.worker_id === "string" ? value.worker_id : typeof value.workerId === "string" ? value.workerId : undefined;
+  const leadId = typeof value.lead_id === "string" ? value.lead_id : typeof value.leadId === "string" ? value.leadId : undefined;
+  const expectedOutcome = typeof value.expected_outcome === "string" ? value.expected_outcome : typeof value.expectedOutcome === "string" ? value.expectedOutcome : undefined;
+  const requiredTools = isStringArray(value.required_tools) ? value.required_tools : isStringArray(value.requiredTools) ? value.requiredTools : undefined;
+  const outputContract = typeof value.output_contract === "string" ? value.output_contract : typeof value.outputContract === "string" ? value.outputContract : undefined;
+  const mustDo = isStringArray(value.must_do) ? value.must_do : isStringArray(value.mustDo) ? value.mustDo : undefined;
+  const mustNotDo = isStringArray(value.must_not_do) ? value.must_not_do : isStringArray(value.mustNotDo) ? value.mustNotDo : undefined;
+  const allowedPaths = isStringArray(value.allowed_paths) ? value.allowed_paths : isStringArray(value.allowedPaths) ? value.allowedPaths : undefined;
+  const forbiddenPaths = isStringArray(value.forbidden_paths) ? value.forbidden_paths : isStringArray(value.forbiddenPaths) ? value.forbiddenPaths : undefined;
+  const modelClass = typeof value.model_class === "string" ? value.model_class : typeof value.modelClass === "string" ? value.modelClass : undefined;
+
+  if (!workerId) errors.push(`worker_contracts[${index}].worker_id is required`);
+  if (leadId !== undefined && leadId.length === 0) errors.push(`worker_contracts[${index}].lead_id must not be empty`);
+  if (typeof value.agent !== "string" || value.agent.length === 0) errors.push(`worker_contracts[${index}].agent is required`);
+  if (typeof value.task !== "string" || value.task.length === 0) errors.push(`worker_contracts[${index}].task is required`);
+  if (!expectedOutcome) errors.push(`worker_contracts[${index}].expected_outcome is required`);
+  if (!requiredTools) errors.push(`worker_contracts[${index}].required_tools must be a string array`);
+  if (!outputContract) errors.push(`worker_contracts[${index}].output_contract is required`);
+  if (!mustDo) errors.push(`worker_contracts[${index}].must_do must be a string array`);
+  if (!mustNotDo) errors.push(`worker_contracts[${index}].must_not_do must be a string array`);
+  if (typeof value.context !== "string" || value.context.length === 0) errors.push(`worker_contracts[${index}].context is required`);
+  if (errors.length > 0) return { errors };
+
+  return {
+    contract: {
+      worker_id: workerId!,
+      lead_id: leadId,
+      agent: value.agent as string,
+      task: value.task as string,
+      expected_outcome: expectedOutcome!,
+      required_tools: requiredTools!,
+      output_contract: outputContract!,
+      must_do: mustDo!,
+      must_not_do: mustNotDo!,
+      context: value.context as string,
+      allowed_paths: allowedPaths,
+      forbidden_paths: forbiddenPaths,
+      model_class: modelClass,
+    },
+    errors: [],
+  };
+}
+
+export function extractLeadPlanWorkerContracts(output: string): LeadPlanWorkerContractExtraction {
+  const candidates = jsonCandidates(output);
+  for (const candidate of candidates) {
+    const root = contractsRoot(candidate);
+    if (!root) continue;
+    const contracts: LeadPlanWorkerContract[] = [];
+    const errors: string[] = [];
+    root.forEach((item, index) => {
+      const normalized = normalizeContract(item, index);
+      if (normalized.contract) contracts.push(normalized.contract);
+      errors.push(...normalized.errors);
+    });
+    return { schema: "zob.lead-plan-worker-contract-extraction.v1", contracts, errors };
+  }
+  return { schema: "zob.lead-plan-worker-contract-extraction.v1", contracts: [], errors: ["No parseable worker_contracts JSON found in lead-plan output"] };
+}
+
+export function redactLeadPlanWorkerContractsForPersistence(contracts: LeadPlanWorkerContract[]): Array<Record<string, unknown>> {
+  return contracts.map((contract) => ({
+    worker_id: contract.worker_id,
+    lead_id: contract.lead_id,
+    agent: contract.agent,
+    taskHash: sha256(contract.task),
+    expected_outcomeHash: sha256(contract.expected_outcome),
+    required_tools: contract.required_tools,
+    output_contract: contract.output_contract,
+    must_doHashes: contract.must_do.map((item) => sha256(item)),
+    must_not_doHashes: contract.must_not_do.map((item) => sha256(item)),
+    contextHash: sha256(contract.context),
+    allowed_paths: contract.allowed_paths,
+    forbidden_paths: contract.forbidden_paths,
+    model_class: contract.model_class,
+    bodyStored: false,
+  }));
+}
+
+export function validateLeadPlanWorkerContracts(repoRoot: string, contracts: LeadPlanWorkerContract[], options: LeadPlanWorkerContractValidationOptions = {}): string[] {
+  const errors: string[] = [];
+  const agents = new Map(loadProjectAgents(repoRoot).map((agent) => [agent.name.toLowerCase(), agent]));
+  const allowedWorkers = options.allowedWorkerIds ? new Set(options.allowedWorkerIds) : undefined;
+  const allowedTools = options.allowedTools ? new Set(options.allowedTools) : undefined;
+
+  contracts.forEach((contract, index) => {
+    const label = `worker_contracts[${index}] '${contract.worker_id}'`;
+    if (options.leadId && contract.lead_id && contract.lead_id !== options.leadId) errors.push(`${label}: lead_id must match '${options.leadId}'`);
+    if (allowedWorkers && !allowedWorkers.has(contract.worker_id)) errors.push(`${label}: worker_id is not delegated by this lead`);
+
+    const agent = agents.get(contract.agent.toLowerCase());
+    if (!agent) {
+      errors.push(`${label}: unknown agent '${contract.agent}'`);
+    } else {
+      errors.push(...validateToolList(agent, contract.required_tools).map((error) => `${label}: ${error}`));
+    }
+
+    if (allowedTools) {
+      const blockedTools = contract.required_tools.filter((tool) => !allowedTools.has(tool));
+      if (blockedTools.length > 0) errors.push(`${label}: tools not allowed by execution boundary: ${blockedTools.join(", ")}`);
+    }
+    if (options.supervisedReadonly) {
+      const writeLike = contract.required_tools.filter((tool) => ["bash", "edit", "write", "delegate_agent", "delegate_task", "orchestrate_run", "factory_run"].includes(tool));
+      if (writeLike.length > 0) errors.push(`${label}: supervised_readonly worker contracts must remain read-only: ${writeLike.join(", ")}`);
+    }
+
+    errors.push(...validateOutputContractId(contract.output_contract).map((error) => `${label}: ${error}`));
+    errors.push(...validateDelegateTaskWriteScope(contract.required_tools, contract.allowed_paths).map((error) => `${label}: ${error}`));
+    errors.push(...validateAllowedPathPolicy(contract.allowed_paths, `${label} allowed_paths`, repoRoot));
+    errors.push(...validateForbiddenPathPolicy(contract.forbidden_paths, `${label} forbidden_paths`, repoRoot));
+  });
+
+  return errors;
+}

package/.pi/extensions/zob-harness/src/orchestration/plan.ts

@@ -0,0 +1,168 @@
+import { SUPERVISED_READONLY_CHILD_TOOLS, SUPERVISED_SMOKE_CHILD_TOOLS } from "../constants.js";
+import type { OrchestrateExecutionMode, OrchestrateRunInput, TeamDefinition } from "../types.js";
+import { normalizeAdaptiveDelegationPolicy } from "./adaptive-delegation.js";
+import { sha256 } from "../utils/hashing.js";
+import { safeFileStem } from "../utils/paths.js";
+import { isRecord } from "../utils/records.js";
+
+function renderOrchestrationTemplate(template: string, values: Record<string, string>): string {
+  return template.replace(/\{([a-zA-Z0-9_.-]+)\}/g, (match, key: string) => values[key] ?? match);
+}
+
+const RAW_PERSISTENCE_KEYS = new Set(["goal", "originalUserAsk", "original_user_ask", "task", "expected_outcome", "context", "taskTemplate", "prompt", "output", "body", "content", "diff", "patch"]);
+const RAW_PERSISTENCE_ARRAY_KEYS = new Set(["must_do", "must_not_do"]);
+
+function redactRawPersistenceFields(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(redactRawPersistenceFields);
+  if (!isRecord(value)) return value;
+  const redacted: Record<string, unknown> = {};
+  for (const [key, child] of Object.entries(value)) {
+    if (RAW_PERSISTENCE_KEYS.has(key)) {
+      if (typeof child === "string") redacted[`${key}Hash`] = sha256(child);
+      else if (child !== undefined && child !== null) redacted[`${key}Hash`] = sha256(JSON.stringify(child));
+      continue;
+    }
+    if (RAW_PERSISTENCE_ARRAY_KEYS.has(key) && Array.isArray(child)) {
+      redacted[`${key}Hashes`] = child.map((item) => sha256(typeof item === "string" ? item : JSON.stringify(item)));
+      continue;
+    }
+    redacted[key] = redactRawPersistenceFields(child);
+  }
+  return redacted;
+}
+
+export function redactBodyLikeFieldsForPersistence(value: Record<string, unknown>): Record<string, unknown> {
+  const redacted = redactRawPersistenceFields(value);
+  return isRecord(redacted) ? { ...redacted, redactedForPersistence: true, bodyStored: false, promptBodiesStored: false, outputBodiesStored: false } : { redactedForPersistence: true, bodyStored: false, promptBodiesStored: false, outputBodiesStored: false };
+}
+
+function redactOrchestrationPlanForPersistence(plan: Record<string, unknown>): Record<string, unknown> {
+  const tasks = Array.isArray(plan.tasks) ? plan.tasks.map((task) => {
+    if (!isRecord(task)) return task;
+    const redacted: Record<string, unknown> = { ...task };
+    for (const field of ["task", "expected_outcome", "context"] as const) {
+      const value = redacted[field];
+      if (typeof value === "string") redacted[`${field}Hash`] = sha256(value);
+      delete redacted[field];
+    }
+    for (const field of ["must_do", "must_not_do"] as const) {
+      const value = redacted[field];
+      if (Array.isArray(value)) redacted[`${field}Hashes`] = value.filter((item): item is string => typeof item === "string").map((item) => sha256(item));
+      delete redacted[field];
+    }
+    return redacted;
+  }) : plan.tasks;
+  return redactBodyLikeFieldsForPersistence({ ...plan, tasks });
+}
+
+function buildOrchestrationPlan(
+  definition: TeamDefinition,
+  input: OrchestrateRunInput,
+  run: { runId: string; runDir: string; execution: OrchestrateExecutionMode },
+): Record<string, unknown> {
+  const workerLimit = input.max_workers ?? definition.workers.length;
+  const selectedWorkers = definition.workers.slice(0, workerLimit);
+  const selectedWorkerIds = new Set(selectedWorkers.map((worker) => worker.id));
+  const tasks: Array<Record<string, unknown>> = [];
+  const goal = input.goal.trim();
+  const originalUserAsk = input.original_user_ask ?? goal;
+  const adaptiveDelegation = normalizeAdaptiveDelegationPolicy(input.adaptive_delegation);
+
+  for (const lead of definition.leads) {
+    const leadWorkerIds = (lead.workerIds ?? selectedWorkers.filter((worker) => worker.leadId === lead.id).map((worker) => worker.id)).filter((workerId) => selectedWorkerIds.has(workerId));
+    tasks.push({
+      id: `${safeFileStem(lead.id)}-lead-plan`,
+      type: "lead_plan",
+      goalId: input.goal_id,
+      todoId: input.todo_id,
+      todoRef: input.todo_id ? { rootTodoId: input.todo_id, attachmentKind: "lead_plan" } : undefined,
+      role: "lead",
+      leadId: lead.id,
+      agent: lead.agent,
+      parent: definition.orchestrator.id,
+      task: `Plan lead lane '${lead.id}' for goal: ${goal}. Propose worker task contracts for: ${leadWorkerIds.join(", ") || "no selected workers"}. Do not execute workers. Return machine-readable worker contracts inside <worker_contracts>{\"worker_contracts\":[...]}</worker_contracts>. Each contract object must include worker_id, lead_id, agent, task, expected_outcome, required_tools, output_contract, must_do, must_not_do, context, and optional allowed_paths, forbidden_paths, model_class. allowed_paths must be repo-relative only; do not include absolute paths, home paths, or '~' paths. forbidden_paths are deny-only patterns and may be repo-local, absolute, or home-relative; broad roots are rejected. The final lead-plan response must include literal fields: lead_id, phase, worker_contracts, required_tools, allowed_paths, forbidden_paths, output_contract, model_class, evidence_needed, no_ship_criteria, evidence, risks/blockers, compliance.`,
+      expected_outcome: `Lead '${lead.id}' produces scoped worker contracts and risk notes in extractable lead-plan.v1 format`,
+      required_tools: lead.requiredTools,
+      must_do: ["Stay in planning mode", "Return worker task contracts only", "Return worker_contracts as parseable JSON inside <worker_contracts> tags", "Use only repo-relative allowed_paths; forbidden_paths are deny-only patterns and may be repo-local, absolute, or home-relative", "Include literal evidence_needed and no_ship_criteria fields", "Cite required evidence and gaps", "Respect parent orchestrator preflight"],
+      must_not_do: ["Do not execute worker tasks", "No edits", "No secrets", "No destructive commands", "No worker-spawns-worker"],
+      context: `Orchestration run ${run.runId}; team ${definition.name}; original ask: ${originalUserAsk}`,
+      output_contract: lead.outputContract,
+      run_in_background: false,
+    });
+  }
+
+  for (const worker of selectedWorkers) {
+    const values = {
+      "goal": goal,
+      "original_user_ask": originalUserAsk,
+      "run.id": run.runId,
+      "run.dir": run.runDir,
+      "team.name": definition.name,
+      "worker.id": worker.id,
+      "lead.id": worker.leadId,
+    };
+    tasks.push({
+      id: `${safeFileStem(worker.leadId)}-${safeFileStem(worker.id)}-worker-contract`,
+      type: "worker_contract",
+      goalId: input.goal_id,
+      todoId: input.todo_id,
+      todoRef: input.todo_id ? { rootTodoId: input.todo_id, attachmentKind: "worker_contract", proposedBy: worker.leadId } : undefined,
+      role: "worker",
+      leadId: worker.leadId,
+      workerId: worker.id,
+      agent: worker.agent,
+      parent: definition.orchestrator.id,
+      proposedBy: worker.leadId,
+      task: renderOrchestrationTemplate(worker.taskTemplate ?? `Execute the bounded worker slice for {goal}. Return evidence, blockers, and next steps.`, values),
+      expected_outcome: `Worker '${worker.id}' returns its contract-compliant deliverable`,
+      required_tools: worker.requiredTools,
+      must_do: ["Use the assigned output contract", "Cite evidence", "Report blockers", "Return deliverable_delivered: yes/no"],
+      must_not_do: ["No secrets", "No destructive commands", "No commits", "No worker-spawns-worker"],
+      context: `Orchestration run ${run.runId}; team ${definition.name}; lead ${worker.leadId}; worker ${worker.id}; original ask: ${originalUserAsk}`,
+      output_contract: worker.outputContract,
+      run_in_background: false,
+    });
+  }
+
+  return {
+    schema: "zob.orchestration-plan.v1",
+    team: definition.name,
+    runId: run.runId,
+    runDir: run.runDir,
+    execution: run.execution,
+    goal,
+    originalUserAsk,
+    goalId: input.goal_id,
+    rootTodoId: input.todo_id,
+    todoGraphBinding: input.todo_id ? { goalId: input.goal_id, rootTodoId: input.todo_id, attachmentPolicy: "messages_delegations_blockers_claims_evidence_attach_to_todo" } : undefined,
+    topology: {
+      orchestrator: definition.orchestrator,
+      leads: definition.leads.map((lead) => ({ ...lead, workerIds: (lead.workerIds ?? selectedWorkers.filter((worker) => worker.leadId === lead.id).map((worker) => worker.id)).filter((workerId) => selectedWorkerIds.has(workerId)) })),
+      workers: selectedWorkers,
+    },
+    invariants: {
+      parentPreflightRequired: true,
+      parentDispatchOnly: true,
+      workerSpawnsWorker: false,
+      freeFormPeerChat: false,
+      networkedComs: false,
+      noExecutionInPlanOnly: true,
+      supervisedSmokeReadOnly: run.execution === "supervised_smoke" ? true : undefined,
+      supervisedSmokeAllowedTools: run.execution === "supervised_smoke" ? [...SUPERVISED_SMOKE_CHILD_TOOLS] : undefined,
+      supervisedReadonly: run.execution === "supervised_readonly" ? true : undefined,
+      supervisedReadonlyAllowedTools: run.execution === "supervised_readonly" ? [...SUPERVISED_READONLY_CHILD_TOOLS] : undefined,
+      supervisedReadonlyDispatcherBoundary: run.execution === "supervised_readonly" ? true : undefined,
+      liveChildExecution: false,
+      adaptiveDelegationDefaultOff: adaptiveDelegation.enabled === false,
+      adaptiveDelegationParentOwned: adaptiveDelegation.enabled ? adaptiveDelegation.parentOwnedDispatch === true : undefined,
+      adaptiveDelegationChildDirectDispatch: adaptiveDelegation.enabled ? adaptiveDelegation.childDirectDispatch : undefined,
+      adaptiveDelegationConfiguredMaxDepth: adaptiveDelegation.enabled ? adaptiveDelegation.configuredMaxDepth : undefined,
+      adaptiveDelegationRuntimeMaxDepth: adaptiveDelegation.enabled ? adaptiveDelegation.runtimeMaxDepth : undefined,
+      adaptiveDelegationDispatch: adaptiveDelegation.enabled ? adaptiveDelegation.dispatch : undefined,
+    },
+    ...(adaptiveDelegation.enabled ? { adaptiveDelegation } : {}),
+    tasks,
+  };
+}
+
+export { buildOrchestrationPlan, redactOrchestrationPlanForPersistence };