zob-harness 0.1.0

package/.pi/extensions/zob-harness/src/topology/coms.ts

@@ -0,0 +1,211 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+import type { TeamDefinition, ZobComsMessageInput } from "../types.js";
+import { sha256 } from "../utils/hashing.js";
+import { readJsonl } from "../utils/json.js";
+
+function comsDir(repoRoot: string): string {
+  return join(repoRoot, ".pi", "coms");
+}
+
+function comsMessagesPath(repoRoot: string): string {
+  return join(comsDir(repoRoot), "messages.jsonl");
+}
+
+function comsStatusPath(repoRoot: string): string {
+  return join(comsDir(repoRoot), "status.jsonl");
+}
+
+type ZobComsStatusTransitionOptions = {
+  outputHash?: string | null;
+};
+
+function nonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function completionEvidencePresent(repoRoot: string, msgId: string, message: Record<string, unknown>, options: ZobComsStatusTransitionOptions): boolean {
+  if (nonEmptyString(options.outputHash)) return true;
+  if (nonEmptyString(message.outputHash)) return true;
+  const messages = readJsonl(comsMessagesPath(repoRoot));
+  return messages.some((candidate) => candidate.parentId === msgId && nonEmptyString(candidate.outputHash) && (candidate.status === "completed" || candidate.kind === "live_response_ref" || String(candidate.kind ?? "").endsWith("_reply")));
+}
+
+export function validateZobComsEdge(definition: TeamDefinition, sender: string, receiver: string): string[] {
+  const errors: string[] = [];
+  const orchestratorId = definition.orchestrator.id;
+  const leadIds = new Set(definition.leads.map((lead) => lead.id));
+  const workerToLead = new Map(definition.workers.map((worker) => [worker.id, worker.leadId]));
+  const leadToWorkers = new Map(definition.leads.map((lead) => [lead.id, new Set((lead.workerIds ?? definition.workers.filter((worker) => worker.leadId === lead.id).map((worker) => worker.id)))]));
+  const knownIds = new Set([orchestratorId, ...leadIds, ...workerToLead.keys()]);
+  if (!knownIds.has(sender)) errors.push(`Unknown coms sender '${sender}'`);
+  if (!knownIds.has(receiver)) errors.push(`Unknown coms receiver '${receiver}'`);
+  if (errors.length > 0) return errors;
+  if (sender === orchestratorId && leadIds.has(receiver)) return [];
+  if (leadIds.has(sender) && receiver === orchestratorId) return [];
+  if (leadIds.has(sender) && leadToWorkers.get(sender)?.has(receiver)) return [];
+  if (workerToLead.has(sender) && workerToLead.get(sender) === receiver) return [];
+  if (workerToLead.has(sender) && workerToLead.has(receiver)) errors.push("Worker-to-worker coms are blocked by topology guard");
+  else errors.push(`Coms edge not allowed by team topology: ${sender} -> ${receiver}`);
+  return errors;
+}
+
+export function buildZobComsMessage(input: ZobComsMessageInput): Record<string, unknown> {
+  const bodyPolicy = input.bodyPolicy ?? "hash_only";
+  const bodyHash = input.body ? sha256(input.body) : undefined;
+  return {
+    schema: "zob.coms-message.v1",
+    msgId: input.taskId ? `${input.runId}:${input.sender}:${input.receiver}:${input.taskId}` : `${input.runId}:${input.sender}:${input.receiver}:${Date.now()}`,
+    runId: input.runId,
+    parentId: input.parentId,
+    sender: input.sender,
+    receiver: input.receiver,
+    kind: input.kind ?? "handoff",
+    taskId: input.taskId,
+    taskHash: input.taskHash ?? bodyHash,
+    outputHash: input.outputHash ?? null,
+    status: input.status ?? "queued",
+    ack: input.ack ?? "not_sent",
+    bodyPolicy,
+    bodyStored: false,
+    bodyHash,
+    metadata: input.metadata ?? {},
+    timestamp: new Date().toISOString(),
+  };
+}
+
+export function validateZobComsMessage(message: Record<string, unknown>): string[] {
+  const errors: string[] = [];
+  for (const field of ["schema", "msgId", "runId", "sender", "receiver", "kind", "status", "bodyPolicy"]) {
+    if (typeof message[field] !== "string") errors.push(`Coms message missing string field '${field}'`);
+  }
+  if (message.schema !== "zob.coms-message.v1") errors.push("Coms message schema must be zob.coms-message.v1");
+  if ("body" in message || "task" in message || "output" in message || "prompt" in message) errors.push("Coms message must not store prompt/task/output bodies");
+  if (message.bodyStored !== false) errors.push("Coms message bodyStored must be false");
+  if (message.bodyPolicy !== "hash_only" && message.bodyPolicy !== "redacted") errors.push("Coms bodyPolicy must be hash_only or redacted");
+  if (message.taskHash !== undefined && message.taskHash !== null && typeof message.taskHash !== "string") errors.push("Coms taskHash must be string/null");
+  if (message.outputHash !== undefined && message.outputHash !== null && typeof message.outputHash !== "string") errors.push("Coms outputHash must be string/null");
+  if (message.status === "completed" && !nonEmptyString(message.outputHash)) errors.push("Coms completed message requires outputHash evidence");
+  return errors;
+}
+
+export function appendZobComsMessage(repoRoot: string, definition: TeamDefinition, input: ZobComsMessageInput): Record<string, unknown> {
+  const edgeErrors = validateZobComsEdge(definition, input.sender, input.receiver);
+  if (edgeErrors.length > 0) throw new Error(edgeErrors.join("; "));
+  const message = buildZobComsMessage(input);
+  const messageErrors = validateZobComsMessage(message);
+  if (messageErrors.length > 0) throw new Error(messageErrors.join("; "));
+  mkdirSync(comsDir(repoRoot), { recursive: true });
+  appendFileSync(comsMessagesPath(repoRoot), `${JSON.stringify(message)}\n`, "utf8");
+  appendFileSync(comsStatusPath(repoRoot), `${JSON.stringify({ schema: "zob.coms-status.v1", event: "message_appended", msgId: message.msgId, runId: message.runId, sender: message.sender, receiver: message.receiver, status: message.status, ack: message.ack, outputHash: message.outputHash ?? null, timestamp: message.timestamp, bodyStored: false })}\n`, "utf8");
+  return message;
+}
+
+function buildZobComsDerivedMessage(message: Record<string, unknown>, events: Array<Record<string, unknown>>, messages: Array<Record<string, unknown>>): Record<string, unknown> {
+  const msgId = String(message.msgId ?? "");
+  const ownEvents = events.filter((event) => event.msgId === msgId);
+  const latestStatus = [...ownEvents].reverse().find((event) => typeof event.status === "string");
+  const latestAck = [...ownEvents].reverse().find((event) => typeof event.ack === "string");
+  const replyIds = messages.filter((candidate) => candidate.parentId === msgId).map((candidate) => candidate.msgId).filter((replyId): replyId is string => typeof replyId === "string");
+  return {
+    ...message,
+    status: typeof latestStatus?.status === "string" ? latestStatus.status : message.status,
+    ack: typeof latestAck?.ack === "string" ? latestAck.ack : message.ack,
+    replyIds,
+    replies: replyIds.length,
+    lastEvent: ownEvents.length > 0 ? ownEvents[ownEvents.length - 1] : undefined,
+  };
+}
+
+function appendZobComsStatusEvent(repoRoot: string, event: Record<string, unknown>): Record<string, unknown> {
+  if ("body" in event || "task" in event || "output" in event || "prompt" in event || "content" in event || "message" in event || "text" in event || "rationale" in event || "diff" in event || "patch" in event) throw new Error("Coms status event must not store prompt/task/output bodies");
+  mkdirSync(comsDir(repoRoot), { recursive: true });
+  const record = { schema: "zob.coms-status.v1", timestamp: new Date().toISOString(), ...event, bodyStored: false };
+  appendFileSync(comsStatusPath(repoRoot), `${JSON.stringify(record)}\n`, "utf8");
+  return getZobComsMessage(repoRoot, String(event.msgId)) ?? record;
+}
+
+export function listZobComsMessages(repoRoot: string, filter: { runId?: string; receiver?: string; sender?: string; status?: string; limit?: number } = {}): Array<Record<string, unknown>> {
+  const limit = Math.max(1, Math.min(100, Math.floor(filter.limit ?? 20)));
+  const messages = readJsonl(comsMessagesPath(repoRoot));
+  const events = readJsonl(comsStatusPath(repoRoot));
+  return messages
+    .map((message) => buildZobComsDerivedMessage(message, events, messages))
+    .filter((message) => !filter.runId || message.runId === filter.runId)
+    .filter((message) => !filter.receiver || message.receiver === filter.receiver)
+    .filter((message) => !filter.sender || message.sender === filter.sender)
+    .filter((message) => !filter.status || message.status === filter.status)
+    .slice(-limit);
+}
+
+export function getZobComsMessage(repoRoot: string, msgId: string): Record<string, unknown> | undefined {
+  const messages = readJsonl(comsMessagesPath(repoRoot));
+  const message = messages.find((candidate) => candidate.msgId === msgId);
+  return message ? buildZobComsDerivedMessage(message, readJsonl(comsStatusPath(repoRoot)), messages) : undefined;
+}
+
+export function ackZobComsMessage(repoRoot: string, msgId: string, actor: string): Record<string, unknown> {
+  const message = getZobComsMessage(repoRoot, msgId);
+  if (!message) throw new Error(`Coms message not found: ${msgId}`);
+  if (message.receiver !== actor) throw new Error(`Coms ACK actor must be receiver: ${actor}`);
+  return appendZobComsStatusEvent(repoRoot, { event: "ack", msgId, runId: message.runId, actor, ack: "received", status: "acknowledged" });
+}
+
+export function transitionZobComsStatus(repoRoot: string, msgId: string, actor: string, status: string, options: ZobComsStatusTransitionOptions = {}): Record<string, unknown> {
+  const message = getZobComsMessage(repoRoot, msgId);
+  if (!message) throw new Error(`Coms message not found: ${msgId}`);
+  if (message.sender !== actor && message.receiver !== actor) throw new Error(`Coms status actor must be sender or receiver: ${actor}`);
+  if (status === "completed" && !completionEvidencePresent(repoRoot, msgId, message, options)) throw new Error("Coms completed status requires outputHash or live response evidence");
+  const event: Record<string, unknown> = { event: "status", msgId, runId: message.runId, actor, status };
+  if (nonEmptyString(options.outputHash)) event.outputHash = options.outputHash;
+  return appendZobComsStatusEvent(repoRoot, event);
+}
+
+export function replyZobComsMessage(repoRoot: string, definition: TeamDefinition, msgId: string, input: Omit<ZobComsMessageInput, "runId" | "parentId">): Record<string, unknown> {
+  const parent = getZobComsMessage(repoRoot, msgId);
+  if (!parent || typeof parent.runId !== "string") throw new Error(`Coms parent message not found: ${msgId}`);
+  const reply = appendZobComsMessage(repoRoot, definition, { ...input, runId: parent.runId, parentId: msgId, kind: input.kind ?? "reply" });
+  appendZobComsStatusEvent(repoRoot, { event: "reply", msgId, runId: parent.runId, actor: input.sender, replyMsgId: reply.msgId, status: parent.status, outputHash: reply.outputHash ?? null });
+  return reply;
+}
+
+export async function awaitZobComsMessage(repoRoot: string, filter: { runId?: string; receiver?: string; status?: string; timeoutMs?: number; pollMs?: number } = {}): Promise<Record<string, unknown> | undefined> {
+  const timeoutMs = Math.max(0, Math.min(5000, Math.floor(filter.timeoutMs ?? 1000)));
+  const pollMs = Math.max(25, Math.min(1000, Math.floor(filter.pollMs ?? 100)));
+  const deadline = Date.now() + timeoutMs;
+  do {
+    const [message] = listZobComsMessages(repoRoot, { runId: filter.runId, receiver: filter.receiver, status: filter.status, limit: 1 });
+    if (message) return message;
+    if (Date.now() >= deadline) break;
+    await new Promise((resolvePromise) => setTimeout(resolvePromise, Math.min(pollMs, Math.max(0, deadline - Date.now()))));
+  } while (Date.now() <= deadline);
+  return undefined;
+}
+
+function mirrorOrchestrationToComs(repoRoot: string, definition: TeamDefinition, messages: Array<Record<string, unknown>>): number {
+  let mirrored = 0;
+  for (const message of messages) {
+    const sender = typeof message.sender === "string" ? message.sender : "";
+    const receiver = typeof message.receiver === "string" ? message.receiver : "";
+    const edgeErrors = validateZobComsEdge(definition, sender, receiver);
+    if (edgeErrors.length > 0) continue;
+    appendZobComsMessage(repoRoot, definition, {
+      runId: typeof message.runId === "string" ? message.runId : "unknown-run",
+      sender,
+      receiver,
+      kind: "plan_only_handoff",
+      taskId: typeof message.taskId === "string" ? message.taskId : undefined,
+      parentId: typeof message.parentId === "string" ? message.parentId : undefined,
+      taskHash: typeof message.taskHash === "string" ? message.taskHash : undefined,
+      outputHash: typeof message.outputHash === "string" ? message.outputHash : null,
+      status: typeof message.status === "string" ? message.status : "planned",
+      ack: typeof message.ack === "string" ? message.ack : "not_sent",
+      metadata: { source: "orchestrate_run", execution: typeof message.execution === "string" ? message.execution : "plan_only", noExecution: true },
+    });
+    mirrored += 1;
+  }
+  return mirrored;
+}
+
+export { mirrorOrchestrationToComs };

package/.pi/extensions/zob-harness/src/topology/orchestration-profiles.ts

@@ -0,0 +1,204 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { loadProjectAgents } from "../agents.js";
+import { normalizeAdaptiveDelegationPolicy, validateAdaptiveDelegationPolicy } from "../orchestration/adaptive-delegation.js";
+import { validateOutputContractId } from "../output-contracts.js";
+import { validateAllowedPathPolicy, validateDelegateTaskWriteScope, validateForbiddenPathPolicy, validateToolList } from "../safety.js";
+import type { OrchestrateRunInput, OrchestrationProfileDefinition, OrchestrationProfilePhase, OrchestrationProfileRole, TeamDefinition } from "../types.js";
+import { parseJsonFile } from "../utils/json.js";
+import { isSafeArtifactName, safeFileStem } from "../utils/paths.js";
+import { isRecord } from "../utils/records.js";
+import { listZobResourceJsonStems, readableZobResourcePath } from "../utils/resources.js";
+import { isStringArray, loadTeamDefinition, validateTeamDefinition } from "./teams.js";
+
+function orchestrationProfilesDir(repoRoot: string): string {
+  return join(repoRoot, ".pi", "orchestrations");
+}
+
+function isOrchestrationProfileRole(value: unknown): value is OrchestrationProfileRole {
+  return (
+    isRecord(value) &&
+    typeof value.id === "string" &&
+    typeof value.roleType === "string" &&
+    typeof value.agent === "string" &&
+    typeof value.outputContract === "string" &&
+    (value.modelClass === undefined || typeof value.modelClass === "string") &&
+    (value.leadId === undefined || typeof value.leadId === "string") &&
+    (value.canDelegateTo === undefined || isStringArray(value.canDelegateTo)) &&
+    (value.requiredTools === undefined || isStringArray(value.requiredTools)) &&
+    (value.tools === undefined || isStringArray(value.tools)) &&
+    (value.allowedPaths === undefined || isStringArray(value.allowedPaths)) &&
+    (value.forbiddenPaths === undefined || isStringArray(value.forbiddenPaths)) &&
+    (value.rules === undefined || isStringArray(value.rules))
+  );
+}
+
+function isOrchestrationProfilePhase(value: unknown): value is OrchestrationProfilePhase {
+  return (
+    isRecord(value) &&
+    typeof value.id === "string" &&
+    typeof value.type === "string" &&
+    (value.run === undefined || isStringArray(value.run)) &&
+    (value.required === undefined || typeof value.required === "boolean") &&
+    (value.requiresOutputContract === undefined || typeof value.requiresOutputContract === "string") &&
+    (value.modelClassOverride === undefined || typeof value.modelClassOverride === "string") &&
+    (value.noShipOnFail === undefined || typeof value.noShipOnFail === "boolean")
+  );
+}
+
+function isOrchestrationProfileDefinition(value: unknown): value is OrchestrationProfileDefinition {
+  return (
+    isRecord(value) &&
+    (value.schema === undefined || value.schema === "zob.orchestration-profile.v1") &&
+    typeof value.name === "string" &&
+    typeof value.version === "string" &&
+    (value.description === undefined || typeof value.description === "string") &&
+    isOrchestrationProfileRole(value.orchestrator) &&
+    Array.isArray(value.roles) &&
+    value.roles.every(isOrchestrationProfileRole) &&
+    Array.isArray(value.edges) &&
+    value.edges.every((edge) => Array.isArray(edge) && edge.length === 2 && typeof edge[0] === "string" && typeof edge[1] === "string") &&
+    Array.isArray(value.phases) &&
+    value.phases.every(isOrchestrationProfilePhase) &&
+    (value.finalReportRole === undefined || typeof value.finalReportRole === "string")
+  );
+}
+
+export function listOrchestrationProfiles(repoRoot: string): string[] {
+  return listZobResourceJsonStems(repoRoot, "orchestrations");
+}
+
+export function loadOrchestrationProfile(repoRoot: string, profileName: string): { definition?: OrchestrationProfileDefinition; profilePath: string; errors: string[] } {
+  if (!/^[a-zA-Z0-9._-]+$/.test(profileName)) return { profilePath: join(orchestrationProfilesDir(repoRoot), `${safeFileStem(profileName)}.json`), errors: [`Invalid orchestration profile name '${profileName}'`] };
+  const profilePath = readableZobResourcePath(repoRoot, "orchestrations", `${profileName}.json`);
+  if (!existsSync(profilePath)) return { profilePath, errors: [`Orchestration profile not found: ${profilePath}`] };
+  try {
+    const parsed = parseJsonFile(profilePath);
+    if (!isOrchestrationProfileDefinition(parsed)) return { profilePath, errors: [`Invalid orchestration profile: ${profilePath}`] };
+    if (parsed.name !== profileName) return { profilePath, errors: [`Orchestration profile name '${parsed.name}' does not match requested '${profileName}'`] };
+    return { definition: parsed, profilePath, errors: [] };
+  } catch (error) {
+    return { profilePath, errors: [`Could not parse orchestration profile '${profilePath}': ${error instanceof Error ? error.message : String(error)}`] };
+  }
+}
+
+export function validateOrchestrationProfile(repoRoot: string, profile: OrchestrationProfileDefinition | undefined): string[] {
+  const errors: string[] = [];
+  if (!profile) return ["Orchestration profile is missing"];
+  if (!isSafeArtifactName(profile.name)) errors.push(`Orchestration profile name must be path-safe: ${profile.name}`);
+  const agents = new Map(loadProjectAgents(repoRoot).map((agent) => [agent.name.toLowerCase(), agent]));
+  const modelClasses = new Set(Object.keys(profile.modelPolicy?.classes ?? {}));
+  if (modelClasses.size === 0) errors.push("Orchestration profile must define modelPolicy.classes");
+
+  const roleIds = new Set<string>();
+  const allRoles = [profile.orchestrator, ...profile.roles];
+  for (const role of allRoles) {
+    if (roleIds.has(role.id)) errors.push(`Duplicate orchestration role id: ${role.id}`);
+    roleIds.add(role.id);
+    if (!isSafeArtifactName(role.id)) errors.push(`Orchestration role id must be path-safe: ${role.id}`);
+    const agent = agents.get(role.agent.toLowerCase());
+    if (!agent) {
+      errors.push(`Role '${role.id}' references unknown agent '${role.agent}'`);
+    } else {
+      const tools = role.requiredTools ?? role.tools ?? [];
+      errors.push(...validateToolList(agent, tools).map((error) => `Role '${role.id}': ${error}`));
+      errors.push(...validateDelegateTaskWriteScope(tools, role.allowedPaths).map((error) => `Role '${role.id}': ${error}`));
+    }
+    errors.push(...validateAllowedPathPolicy(role.allowedPaths, `Role '${role.id}' allowedPaths`, repoRoot));
+    errors.push(...validateForbiddenPathPolicy(role.forbiddenPaths, `Role '${role.id}' forbiddenPaths`, repoRoot));
+    errors.push(...validateOutputContractId(role.outputContract).map((error) => `Role '${role.id}': ${error}`));
+    if (role.modelClass && !modelClasses.has(role.modelClass)) errors.push(`Role '${role.id}' references unknown modelClass '${role.modelClass}'`);
+  }
+
+  const leadIds = new Set(profile.roles.filter((role) => role.roleType === "lead" || role.canDelegateTo !== undefined).map((role) => role.id));
+  for (const role of profile.roles) {
+    if (role.roleType === "worker" && role.leadId && !leadIds.has(role.leadId)) errors.push(`Worker '${role.id}' references unknown lead '${role.leadId}'`);
+    for (const workerId of role.canDelegateTo ?? []) {
+      if (!roleIds.has(workerId)) errors.push(`Role '${role.id}' canDelegateTo unknown role '${workerId}'`);
+    }
+  }
+
+  const seenEdges = new Set<string>();
+  for (const [sender, receiver] of profile.edges) {
+    const edgeKey = `${sender}->${receiver}`;
+    if (seenEdges.has(edgeKey)) errors.push(`Duplicate orchestration edge: ${edgeKey}`);
+    seenEdges.add(edgeKey);
+    if (!roleIds.has(sender)) errors.push(`Edge sender unknown: ${sender}`);
+    if (!roleIds.has(receiver)) errors.push(`Edge receiver unknown: ${receiver}`);
+    const senderRole = allRoles.find((role) => role.id === sender);
+    const receiverRole = allRoles.find((role) => role.id === receiver);
+    if (senderRole?.roleType === "worker" && receiverRole?.roleType === "worker") errors.push(`Worker-to-worker edge requires explicit future policy gate: ${edgeKey}`);
+  }
+
+  for (const phase of profile.phases) {
+    if (!isSafeArtifactName(phase.id)) errors.push(`Orchestration phase id must be path-safe: ${phase.id}`);
+    for (const roleId of phase.run ?? []) {
+      if (!roleIds.has(roleId)) errors.push(`Phase '${phase.id}' references unknown role '${roleId}'`);
+    }
+    if (phase.requiresOutputContract) errors.push(...validateOutputContractId(phase.requiresOutputContract).map((error) => `Phase '${phase.id}': ${error}`));
+    if (phase.modelClassOverride && !modelClasses.has(phase.modelClassOverride)) errors.push(`Phase '${phase.id}' references unknown modelClassOverride '${phase.modelClassOverride}'`);
+  }
+  if (profile.finalReportRole && !roleIds.has(profile.finalReportRole)) errors.push(`finalReportRole references unknown role '${profile.finalReportRole}'`);
+  return errors;
+}
+
+function roleTools(role: OrchestrationProfileRole): string[] {
+  return role.requiredTools ?? role.tools ?? [];
+}
+
+export function teamDefinitionFromOrchestrationProfile(profile: OrchestrationProfileDefinition): TeamDefinition {
+  const leads = profile.roles.filter((role) => role.roleType === "lead" || role.canDelegateTo !== undefined).map((role) => ({
+    id: role.id,
+    agent: role.agent,
+    description: `Lead role from orchestration profile ${profile.name}`,
+    requiredTools: roleTools(role),
+    outputContract: role.outputContract,
+    workerIds: role.canDelegateTo ?? profile.roles.filter((candidate) => candidate.roleType === "worker" && candidate.leadId === role.id).map((candidate) => candidate.id),
+    responsibilities: role.rules,
+  }));
+  const workers = profile.roles.filter((role) => role.roleType === "worker").map((role) => ({
+    id: role.id,
+    leadId: role.leadId ?? "",
+    agent: role.agent,
+    description: `Worker role from orchestration profile ${profile.name}`,
+    requiredTools: roleTools(role),
+    outputContract: role.outputContract,
+    taskTemplate: `Execute profile worker '${role.id}' for goal: {goal}. Return evidence, blockers, compliance, and deliverable_delivered. Run id: {run.id}.`,
+  }));
+  return {
+    name: profile.name,
+    version: profile.version,
+    description: profile.description ?? `Orchestration profile ${profile.name}`,
+    orchestrator: {
+      id: profile.orchestrator.id,
+      agent: profile.orchestrator.agent,
+      description: `Orchestrator role from orchestration profile ${profile.name}`,
+      requiredTools: roleTools(profile.orchestrator),
+      outputContract: profile.orchestrator.outputContract,
+      responsibilities: profile.orchestrator.rules,
+    },
+    leads,
+    workers,
+  };
+}
+
+export function validateOrchestrateRunInputs(repoRoot: string, input: OrchestrateRunInput): string[] {
+  const errors: string[] = [];
+  if (!input.goal || input.goal.trim().length === 0) errors.push("goal is required");
+  if (input.run_id && safeFileStem(input.run_id) !== input.run_id) errors.push(`run_id must be path-safe: ${input.run_id}`);
+  if (input.execution !== undefined && input.execution !== "plan_only" && input.execution !== "supervised_smoke" && input.execution !== "supervised_readonly") errors.push("orchestrate_run only supports execution=plan_only, execution=supervised_smoke, or execution=supervised_readonly");
+  if (input.max_workers !== undefined && (!Number.isInteger(input.max_workers) || input.max_workers < 1)) errors.push("max_workers must be a positive integer");
+  errors.push(...validateAdaptiveDelegationPolicy(normalizeAdaptiveDelegationPolicy(input.adaptive_delegation)));
+  if (input.team && input.profile) errors.push("orchestrate_run accepts either team or profile, not both");
+  if (input.profile) {
+    const profile = loadOrchestrationProfile(repoRoot, input.profile);
+    errors.push(...profile.errors);
+    errors.push(...validateOrchestrationProfile(repoRoot, profile.definition));
+  } else {
+    const team = loadTeamDefinition(repoRoot, input.team ?? "zob-core");
+    errors.push(...team.errors);
+    errors.push(...validateTeamDefinition(repoRoot, team.definition));
+  }
+  return errors;
+}

package/.pi/extensions/zob-harness/src/topology/teams.ts

@@ -0,0 +1,113 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { loadProjectAgents } from "../agents.js";
+import { validateOutputContractId } from "../output-contracts.js";
+import { validateToolList } from "../safety.js";
+import type { HarnessAgent, TeamDefinition, TeamLead, TeamRoleBase, TeamWorker } from "../types.js";
+import { parseJsonFile } from "../utils/json.js";
+import { isSafeArtifactName, safeFileStem } from "../utils/paths.js";
+import { isRecord } from "../utils/records.js";
+import { readableZobResourcePath } from "../utils/resources.js";
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function isTeamRoleBase(value: unknown): value is TeamRoleBase {
+  return (
+    isRecord(value) &&
+    typeof value.id === "string" &&
+    typeof value.agent === "string" &&
+    isStringArray(value.requiredTools) &&
+    typeof value.outputContract === "string" &&
+    (value.description === undefined || typeof value.description === "string") &&
+    (value.model === undefined || typeof value.model === "string") &&
+    (value.responsibilities === undefined || isStringArray(value.responsibilities))
+  );
+}
+
+function isTeamLead(value: unknown): value is TeamLead {
+  return isTeamRoleBase(value) && (!isRecord(value) || value.workerIds === undefined || isStringArray(value.workerIds));
+}
+
+function isTeamWorker(value: unknown): value is TeamWorker {
+  return isTeamRoleBase(value) && isRecord(value) && typeof value.leadId === "string" && (value.taskTemplate === undefined || typeof value.taskTemplate === "string");
+}
+
+function isTeamDefinition(value: unknown): value is TeamDefinition {
+  return (
+    isRecord(value) &&
+    typeof value.name === "string" &&
+    typeof value.version === "string" &&
+    typeof value.description === "string" &&
+    isTeamRoleBase(value.orchestrator) &&
+    Array.isArray(value.leads) &&
+    value.leads.every(isTeamLead) &&
+    Array.isArray(value.workers) &&
+    value.workers.every(isTeamWorker)
+  );
+}
+
+export function loadTeamDefinition(repoRoot: string, teamName: string): { definition?: TeamDefinition; teamPath: string; errors: string[] } {
+  if (!/^[a-zA-Z0-9._-]+$/.test(teamName)) return { teamPath: join(repoRoot, ".pi", "teams", `${safeFileStem(teamName)}.json`), errors: [`Invalid team name '${teamName}'`] };
+  const teamPath = readableZobResourcePath(repoRoot, "teams", `${teamName}.json`);
+  if (!existsSync(teamPath)) return { teamPath, errors: [`Team topology not found: ${teamPath}`] };
+  try {
+    const parsed = parseJsonFile(teamPath);
+    if (!isTeamDefinition(parsed)) return { teamPath, errors: [`Invalid team topology: ${teamPath}`] };
+    if (parsed.name !== teamName) return { teamPath, errors: [`Team topology name '${parsed.name}' does not match requested '${teamName}'`] };
+    return { definition: parsed, teamPath, errors: [] };
+  } catch (error) {
+    return { teamPath, errors: [`Could not parse team topology '${teamPath}': ${error instanceof Error ? error.message : String(error)}`] };
+  }
+}
+
+function validateTeamRole(role: TeamRoleBase, label: string, agents: Map<string, HarnessAgent>): string[] {
+  const errors: string[] = [];
+  if (!isSafeArtifactName(role.id)) errors.push(`${label} id must be path-safe: ${role.id}`);
+  const agent = agents.get(role.agent.toLowerCase());
+  if (!agent) {
+    errors.push(`${label} references unknown agent '${role.agent}'`);
+  } else {
+    errors.push(...validateToolList(agent, role.requiredTools).map((error) => `${label}: ${error}`));
+  }
+  errors.push(...validateOutputContractId(role.outputContract).map((error) => `${label}: ${error}`));
+  return errors;
+}
+
+export function validateTeamDefinition(repoRoot: string, definition: TeamDefinition | undefined): string[] {
+  const errors: string[] = [];
+  if (!definition) return ["Team topology is missing"];
+  if (!isSafeArtifactName(definition.name)) errors.push(`Team name must be path-safe: ${definition.name}`);
+  const agents = new Map(loadProjectAgents(repoRoot).map((agent) => [agent.name.toLowerCase(), agent]));
+  const ids = new Set<string>();
+  const markId = (id: string, label: string): void => {
+    if (ids.has(id)) errors.push(`Duplicate team role id: ${id}`);
+    ids.add(id);
+    if (!isSafeArtifactName(id)) errors.push(`${label} id must be path-safe: ${id}`);
+  };
+
+  markId(definition.orchestrator.id, "orchestrator");
+  errors.push(...validateTeamRole(definition.orchestrator, `orchestrator '${definition.orchestrator.id}'`, agents));
+  if (definition.leads.length === 0) errors.push("Team topology must define at least one lead");
+  if (definition.workers.length === 0) errors.push("Team topology must define at least one worker");
+
+  const leadIds = new Set(definition.leads.map((lead) => lead.id));
+  const workerIds = new Set(definition.workers.map((worker) => worker.id));
+  for (const lead of definition.leads) {
+    markId(lead.id, "lead");
+    errors.push(...validateTeamRole(lead, `lead '${lead.id}'`, agents));
+    for (const workerId of lead.workerIds ?? []) {
+      if (!workerIds.has(workerId)) errors.push(`Lead '${lead.id}' references unknown worker '${workerId}'`);
+    }
+  }
+  for (const worker of definition.workers) {
+    markId(worker.id, "worker");
+    errors.push(...validateTeamRole(worker, `worker '${worker.id}'`, agents));
+    if (!leadIds.has(worker.leadId)) errors.push(`Worker '${worker.id}' references unknown lead '${worker.leadId}'`);
+  }
+  return errors;
+}
+
+export { isStringArray };

package/.pi/extensions/zob-harness/src/types/core.ts

@@ -0,0 +1,47 @@
+export type ModeName = "explore" | "plan" | "implement" | "oracle" | "factory" | "orchestrator";
+export type AgentScope = "project" | "user" | "both";
+export type ChildThinkingLevel = "low" | "medium" | "high" | "xhigh";
+
+export interface ChildChangedPathRef {
+  path: string;
+  pathHash: string;
+  status: string;
+  contentHash?: string;
+}
+
+export type TextBlock = { type: "text"; text: string };
+export type AssistantLikeMessage = {
+  role?: string;
+  content?: Array<TextBlock | { type: string; [key: string]: unknown }>;
+  usage?: {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    totalTokens?: number;
+    cost?: { total?: number };
+  };
+  model?: string;
+  provider?: string;
+  stopReason?: string;
+  errorMessage?: string;
+};
+
+export type JsonEvent = {
+  type?: string;
+  message?: AssistantLikeMessage;
+  messages?: AssistantLikeMessage[];
+  assistantMessageEvent?: { type?: string; delta?: string };
+  toolName?: string;
+};
+
+export interface HarnessAgent {
+  name: string;
+  description: string;
+  tools?: string[];
+  model?: string;
+  thinking?: ChildThinkingLevel | string;
+  prompt: string;
+  source: "project" | "user";
+  filePath: string;
+}