@a-t-h-i/bot-lobby 0.1.0

package/src/master/decisions.ts

@@ -0,0 +1,53 @@
+import type { Decision, Task, Verdict } from "../schemas/task.ts";
+import type { Domain } from "../schemas/agent.ts";
+import type { ScoutOutcome } from "./master.ts";
+import { detectGaps, domainsInvolved } from "./synthesis.ts";
+
+/** §19: everything the engine requires before completion may be declared. */
+export function completionBlockers(task: Task, pendingCount: number): string[] {
+  const blockers: string[] = [];
+  if (!task.plan) blockers.push("no approved plan is recorded");
+  if (task.qaVerdict !== "pass") blockers.push(`QA gate is ${task.qaVerdict ?? "not run"}`);
+  if (pendingCount > 0) blockers.push(`${pendingCount} unresolved approval request(s)`);
+  if (task.blockers.length > 0) blockers.push(`${task.blockers.length} unresolved blocker(s)`);
+  return blockers;
+}
+
+/** Record a Master decision on the task so it survives into knowledge. */
+export function recordDecision(
+  task: Task,
+  text: string,
+  domain: Decision["domain"] = "master",
+  now = new Date().toISOString(),
+): void {
+  task.decisions.push({ domain, text, createdAt: now });
+}
+
+/** §17: a changes-required verdict iterates until the configured limit. */
+export function decideReviewLoop(
+  verdict: Verdict,
+  iterations: number,
+  maxIterations: number,
+): "accept" | "iterate" | "blocked" {
+  if (verdict === "pass") return "accept";
+  if (verdict === "blocked") return "blocked";
+  return iterations < maxIterations ? "iterate" : "blocked";
+}
+
+export interface ReconAssessment {
+  usableDomains: Domain[];
+  warnings: string[];
+  /** False when no scout produced usable evidence at all. */
+  hasEvidence: boolean;
+}
+
+/**
+ * Advisory (not a gate): the Master decides whether to proceed, but the engine
+ * surfaces what reconnaissance is missing so the decision is informed.
+ */
+export function assessReconnaissance(outcomes: ScoutOutcome[]): ReconAssessment {
+  const warnings = detectGaps(outcomes);
+  const usableDomains = domainsInvolved(outcomes);
+  if (outcomes.length === 0) warnings.push("no scouts were run");
+  return { usableDomains, warnings, hasEvidence: usableDomains.length > 0 };
+}

package/src/master/master.ts

@@ -0,0 +1,298 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { BotLobbyConfig } from "../schemas/configuration.ts";
+import type { Domain } from "../schemas/agent.ts";
+import type { AgentRun, ReviewResult, ScoutResult, WorkerResult } from "../schemas/findings.ts";
+import { domainSpec } from "../agents/registry.ts";
+import { runAgent, runParallel, type AgentRequest } from "../execution/agent-runner.ts";
+import { spawnPiProcess, type ProcessRunner } from "../execution/pi-runner.ts";
+import { readAgentKnowledge, writeFileEnsured } from "../knowledge/store.ts";
+import { selectKnowledge, type KnowledgeSelection } from "../knowledge/selector.ts";
+import { summarizeOutcomes } from "./synthesis.ts";
+import { parseWorkerResult, validateWorkerResult } from "../roles/worker.ts";
+import { parseReviewResult, validateReviewResult } from "../roles/reviewer.ts";
+import { truncate } from "../text.ts";
+import { isScoutResultUsable, parseScoutResult, validateScoutResult } from "../roles/scout.ts";
+
+export interface ScoutOutcome {
+  result: ScoutResult;
+  run: AgentRun;
+  issues: string[];
+  usable: boolean;
+}
+
+export interface ScoutRequest {
+  taskId: string;
+  /** Requirements/objective text used for context selection. */
+  taskText: string;
+  /** What the Master wants investigated. */
+  instruction: string;
+  domains: Domain[];
+  cwd: string;
+  dataRoots: readonly string[];
+  taskDir: string;
+  config: BotLobbyConfig;
+  signal?: AbortSignal;
+  onUpdate?: (run: AgentRun) => void;
+}
+
+/** Models are inherited from the session unless the config pins one. */
+export function resolveModel(config: BotLobbyConfig, domain: Domain): string | undefined {
+  const model = config.agents[domain].model;
+  return model === "inherit" ? undefined : model;
+}
+
+function scoutInstruction(request: ScoutRequest, domain: Domain): string {
+  return [
+    request.instruction,
+    "",
+    `Domain focus: ${domainSpec(domain).scoutFocus}.`,
+    "Investigate the repository and report structured findings. Do not modify any file.",
+  ].join("\n");
+}
+
+function scoutContext(request: ScoutRequest, domain: Domain): AgentRequest["context"] {
+  const slices = readAgentKnowledge(request.dataRoots, domain);
+  return {
+    task: request.taskText,
+    ...selectKnowledge(`${request.taskText} ${domainSpec(domain).scoutFocus}`, slices),
+    instructions: request.config.agents[domain].instructions,
+    workflowContext: `Task state: scouting. Domain: ${domain}. Read-only reconnaissance; no implementation.`,
+  };
+}
+
+function toOutcome(run: AgentRun, domain: Domain): ScoutOutcome {
+  if (run.status !== "success") {
+    return {
+      result: parseScoutResult(domain, run.output),
+      run,
+      issues: [`scout ${run.status}: ${run.error ?? "no detail"}`],
+      usable: false,
+    };
+  }
+  const result = parseScoutResult(domain, run.output);
+  return { result, run, issues: validateScoutResult(result), usable: isScoutResultUsable(result) };
+}
+
+/** Run the selected domain scouts concurrently and persist their findings. */
+export async function runScouts(request: ScoutRequest, run: ProcessRunner = spawnPiProcess): Promise<ScoutOutcome[]> {
+  const requests: AgentRequest[] = request.domains.map((domain) => ({
+    taskId: request.taskId,
+    domain,
+    role: "scout",
+    instruction: scoutInstruction(request, domain),
+    context: scoutContext(request, domain),
+    model: resolveModel(request.config, domain),
+    thinking: request.config.agents[domain].thinking,
+    timeoutMs: request.config.workflow.agentTimeoutMs,
+    cwd: request.cwd,
+    signal: request.signal,
+    onUpdate: request.onUpdate,
+    retries: request.config.workflow.maxAgentRetries,
+  }));
+  const runs = await runParallel(requests, request.config.workflow.maxParallelScouts, run);
+  const outcomes = runs.map((agentRun) => toOutcome(agentRun, agentRun.domain));
+  saveScoutResults(request.taskDir, outcomes);
+  return outcomes;
+}
+export function scoutResultPath(taskDir: string, domain: Domain): string {
+  return join(taskDir, `scout-${domain}.json`);
+}
+
+export function saveScoutResults(taskDir: string, outcomes: ScoutOutcome[]): void {
+  for (const outcome of outcomes) {
+    writeFileEnsured(scoutResultPath(taskDir, outcome.result.domain), JSON.stringify(outcome, null, 2));
+  }
+}
+
+/** Re-read persisted scout findings for the given domains; the first dir with a file wins. */
+export function loadScoutResults(taskDirs: string | readonly string[], domains: Domain[]): ScoutOutcome[] {
+  const dirs = typeof taskDirs === "string" ? [taskDirs] : taskDirs;
+  const outcomes: ScoutOutcome[] = [];
+  for (const domain of domains) {
+    const found = readScoutArtifact(dirs, domain);
+    if (found) outcomes.push(found);
+  }
+  return outcomes;
+}
+
+function readScoutArtifact(dirs: readonly string[], domain: Domain): ScoutOutcome | undefined {
+  for (const dir of dirs) {
+    const path = scoutResultPath(dir, domain);
+    if (!existsSync(path)) continue;
+    try {
+      return JSON.parse(readFileSync(path, "utf8")) as ScoutOutcome;
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+export interface WorkerOutcome {
+  result: WorkerResult;
+  run: AgentRun;
+  issues: string[];
+}
+
+export interface WorkerRequest {
+  taskId: string;
+  domain: Domain;
+  /** What the Master wants implemented. */
+  instruction: string;
+  /** Requirements + approved objective + approved plan. */
+  taskText: string;
+  scoutOutcomes: ScoutOutcome[];
+  cwd: string;
+  dataRoots: readonly string[];
+  config: BotLobbyConfig;
+  signal?: AbortSignal;
+  onUpdate?: (run: AgentRun) => void;
+}
+
+function workerWorkflowContext(request: WorkerRequest): string {
+  const spec = domainSpec(request.domain);
+  const own = request.scoutOutcomes.filter(
+    (outcome) => outcome.result.domain === request.domain && outcome.usable,
+  );
+  return [
+    `Task state: implementing. Domain: ${request.domain}.`,
+    `Domain boundary: ${spec.boundary}`,
+    "Dependency policy: never add a dependency or make a significant architectural change yourself; list them under the matching output section and stop that part of the work.",
+    own.length > 0
+      ? `Scout findings for your domain:\n${summarizeOutcomes(own, 1500)}`
+      : "No scout findings were collected for your domain; verify the repository yourself.",
+  ].join("\n\n");
+}
+
+/** Delegate one implementation step to a domain worker. */
+export async function runWorker(
+  request: WorkerRequest,
+  run: ProcessRunner = spawnPiProcess,
+): Promise<WorkerOutcome> {
+  const slices = readAgentKnowledge(request.dataRoots, request.domain);
+  const selected = selectKnowledge(`${request.taskText} ${request.instruction}`, slices);
+  const agentRun = await runAgent(
+    {
+      taskId: request.taskId,
+      domain: request.domain,
+      role: "worker",
+      instruction: request.instruction,
+      context: {
+        task: request.taskText,
+        ...selected,
+        instructions: request.config.agents[request.domain].instructions,
+        workflowContext: workerWorkflowContext(request),
+      },
+      model: resolveModel(request.config, request.domain),
+      thinking: request.config.agents[request.domain].thinking,
+      timeoutMs: request.config.workflow.agentTimeoutMs,
+      cwd: request.cwd,
+      signal: request.signal,
+      onUpdate: request.onUpdate,
+      retries: request.config.workflow.maxAgentRetries,
+    },
+    run,
+  );
+  const result = parseWorkerResult(request.domain, agentRun.output);
+  const issues =
+    agentRun.status === "success"
+      ? validateWorkerResult(result)
+      : [`worker ${agentRun.status}: ${agentRun.error ?? "no detail"}`];
+  return { result, run: agentRun, issues };
+}
+
+export interface ReviewerOutcome {
+  result: ReviewResult;
+  run: AgentRun;
+  issues: string[];
+}
+
+export interface ReviewerRequest {
+  taskId: string;
+  domain: Domain;
+  taskText: string;
+  workerSummary: string;
+  scoutOutcomes: ScoutOutcome[];
+  diff: string;
+  instruction?: string;
+  cwd: string;
+  dataRoots: readonly string[];
+  config: BotLobbyConfig;
+  signal?: AbortSignal;
+  onUpdate?: (run: AgentRun) => void;
+}
+
+function reviewerContext(request: ReviewerRequest): string {
+  const owns = request.scoutOutcomes.filter(
+    (outcome) => outcome.result.domain === request.domain && outcome.usable,
+  );
+  return [
+    `Task state: reviewing. Domain: ${request.domain}.`,
+    "You may not modify implementation. Report required changes instead.",
+    request.workerSummary ? `Worker summary:\n${truncate(request.workerSummary, 2000)}` : "No worker summary available.",
+    owns.length > 0 ? `Scout findings:\n${summarizeOutcomes(owns, 1200)}` : "",
+    `Repository changes:\n${request.diff}`,
+  ]
+    .filter((line) => line.length > 0)
+    .join("\n\n");
+}
+
+/** True when the output carries the reviewer contract's required heading. */
+export function hasReviewVerdict(text: string): boolean {
+  return /##\s*verdict/i.test(text);
+}
+
+/** A success without the Verdict section is off-contract and worth resampling. */
+function isRetryableReviewRun(run: AgentRun): boolean {
+  return run.status !== "cancelled" && (run.status !== "success" || !hasReviewVerdict(run.output));
+}
+
+function reviewerAgentRequest(request: ReviewerRequest, selected: KnowledgeSelection): AgentRequest {
+  return {
+    taskId: request.taskId,
+    domain: request.domain,
+    role: "reviewer",
+    instruction:
+      request.instruction?.trim() ||
+      "Review the current repository changes against the approved requirements and plan.",
+    context: {
+      task: request.taskText,
+      ...selected,
+      instructions: request.config.agents[request.domain].instructions,
+      workflowContext: reviewerContext(request),
+    },
+    model: resolveModel(request.config, request.domain),
+    thinking: request.config.agents[request.domain].thinking,
+    timeoutMs: request.config.workflow.agentTimeoutMs,
+    cwd: request.cwd,
+    signal: request.signal,
+    onUpdate: request.onUpdate,
+    retries: 0,
+  };
+}
+
+function reviewerIssues(run: AgentRun, result: ReviewResult): string[] {
+  return run.status === "success"
+    ? validateReviewResult(result)
+    : [`reviewer ${run.status}: ${run.error ?? "no detail"}`];
+}
+
+/** Independently review the current repository state for one domain. */
+export async function runReviewer(
+  request: ReviewerRequest,
+  run: ProcessRunner = spawnPiProcess,
+): Promise<ReviewerOutcome> {
+  const selected = selectKnowledge(
+    `${request.taskText} ${request.workerSummary}`,
+    readAgentKnowledge(request.dataRoots, request.domain),
+  );
+  const agentRequest = reviewerAgentRequest(request, selected);
+  const attempts = Math.max(1, request.config.workflow.maxAgentRetries + 1);
+  let agentRun = await runAgent(agentRequest, run);
+  for (let attempt = 2; attempt <= attempts && isRetryableReviewRun(agentRun); attempt++) {
+    agentRun = await runAgent(agentRequest, run);
+  }
+  const result = parseReviewResult(request.domain, agentRun.output);
+  return { result, run: agentRun, issues: reviewerIssues(agentRun, result) };
+}

package/src/master/research.ts

@@ -0,0 +1,98 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Domain } from "../schemas/agent.ts";
+import type { BotLobbyConfig } from "../schemas/configuration.ts";
+import type { AgentRun, ResearchResult } from "../schemas/findings.ts";
+import { runAgent, type AgentRequest } from "../execution/agent-runner.ts";
+import { spawnPiProcess, type ProcessRunner } from "../execution/pi-runner.ts";
+import { writeFileEnsured } from "../knowledge/store.ts";
+import { isResearchResultUsable, parseResearchResult, validateResearchResult } from "../roles/researcher.ts";
+import { resolveModel } from "./master.ts";
+
+export interface ResearchOutcome {
+  result: ResearchResult;
+  run: AgentRun;
+  issues: string[];
+  usable: boolean;
+}
+
+export interface ResearchRequest {
+  taskId: string;
+  /** Domain whose model, thinking level, and prompt layers the researcher reuses. */
+  domain: Domain;
+  /** The question or topic the Master wants researched. */
+  instruction: string;
+  cwd: string;
+  taskDir: string;
+  config: BotLobbyConfig;
+  signal?: AbortSignal;
+  onUpdate?: (run: AgentRun) => void;
+}
+
+export function researchResultPath(taskDir: string, domain: Domain): string {
+  return join(taskDir, `research-${domain}.json`);
+}
+
+export function saveResearchResult(taskDir: string, outcome: ResearchOutcome): void {
+  writeFileEnsured(researchResultPath(taskDir, outcome.result.domain), JSON.stringify(outcome, null, 2));
+}
+
+/** Re-read persisted research reports for the given domains. */
+export function loadResearchResults(taskDir: string, domains: Domain[]): ResearchOutcome[] {
+  const outcomes: ResearchOutcome[] = [];
+  for (const domain of domains) {
+    const path = researchResultPath(taskDir, domain);
+    if (!existsSync(path)) continue;
+    try {
+      outcomes.push(JSON.parse(readFileSync(path, "utf8")) as ResearchOutcome);
+    } catch {
+      // Corrupted research artifact: skip it rather than failing the workflow.
+    }
+  }
+  return outcomes;
+}
+
+function researchContext(request: ResearchRequest): AgentRequest["context"] {
+  return {
+    task: request.instruction,
+    instructions: request.config.agents[request.domain].instructions,
+    workflowContext: `Task state: research requested by the Master. Domain: ${request.domain}. Read-only; report cited findings only.`,
+  };
+}
+
+function toOutcome(run: AgentRun, domain: Domain): ResearchOutcome {
+  if (run.status !== "success") {
+    return {
+      result: parseResearchResult(domain, run.output),
+      run,
+      issues: [`research ${run.status}: ${run.error ?? "no detail"}`],
+      usable: false,
+    };
+  }
+  const result = parseResearchResult(domain, run.output);
+  return { result, run, issues: validateResearchResult(result), usable: isResearchResultUsable(result) };
+}
+
+/** Run the researcher for one domain and persist its report for audit. */
+export async function runResearch(request: ResearchRequest, run: ProcessRunner = spawnPiProcess): Promise<ResearchOutcome> {
+  const agentRun = await runAgent(
+    {
+      taskId: request.taskId,
+      domain: request.domain,
+      role: "researcher",
+      instruction: request.instruction,
+      context: researchContext(request),
+      model: resolveModel(request.config, request.domain),
+      thinking: request.config.agents[request.domain].thinking,
+      timeoutMs: request.config.workflow.agentTimeoutMs,
+      cwd: request.cwd,
+      signal: request.signal,
+      onUpdate: request.onUpdate,
+      retries: request.config.workflow.maxAgentRetries,
+    },
+    run,
+  );
+  const outcome = toOutcome(agentRun, agentRun.domain);
+  saveResearchResult(request.taskDir, outcome);
+  return outcome;
+}

package/src/master/synthesis.ts

@@ -0,0 +1,57 @@
+import type { Domain } from "../schemas/agent.ts";
+import { truncate } from "../text.ts";
+import type { ScoutOutcome } from "./master.ts";
+
+/** Domains whose reconnaissance produced usable evidence. */
+export function domainsInvolved(outcomes: ScoutOutcome[]): Domain[] {
+  return [...new Set(outcomes.filter((outcome) => outcome.usable).map((outcome) => outcome.result.domain))];
+}
+
+/** Missing, failed, or low-confidence recon the Master should treat carefully. */
+export function detectGaps(outcomes: ScoutOutcome[]): string[] {
+  const gaps: string[] = [];
+  for (const outcome of outcomes) {
+    const { domain, confidence } = outcome.result;
+    if (!outcome.usable) gaps.push(`${domain}: no usable reconnaissance`);
+    if (outcome.usable && confidence === "low") gaps.push(`${domain}: low confidence, verify claims`);
+    for (const issue of outcome.issues) gaps.push(`${domain}: ${issue}`);
+  }
+  return [...new Set(gaps)];
+}
+
+/** Files reported by more than one domain: likely cross-domain touchpoints. */
+export function detectSharedFiles(outcomes: ScoutOutcome[]): { path: string; domains: Domain[] }[] {
+  const byPath = new Map<string, Set<Domain>>();
+  for (const outcome of outcomes) {
+    for (const file of outcome.result.relevantFiles) {
+      const domains = byPath.get(file.path) ?? new Set<Domain>();
+      domains.add(outcome.result.domain);
+      byPath.set(file.path, domains);
+    }
+  }
+  return [...byPath.entries()]
+    .filter(([, domains]) => domains.size > 1)
+    .map(([path, domains]) => ({ path, domains: [...domains] }));
+}
+
+function describeOutcome(outcome: ScoutOutcome, rawLimit: number): string {
+  const { result } = outcome;
+  const lines = [
+    `### ${result.domain} (${outcome.run.status}${outcome.usable ? "" : ", unusable"}) — confidence: ${result.confidence}`,
+    result.scope ? `Scope: ${result.scope}` : "",
+    ...result.findings.slice(0, 12).map((finding) => `- ${finding}`),
+    ...result.risks.slice(0, 5).map((risk) => `- RISK: ${risk}`),
+    ...result.recommendations.slice(0, 5).map((rec) => `- REC: ${rec}`),
+    result.relevantFiles.length > 0
+      ? `Files: ${result.relevantFiles.slice(0, 10).map((file) => file.path).join(", ")}`
+      : "",
+    outcome.issues.length > 0 ? `Issues: ${outcome.issues.join("; ")}` : "",
+    result.raw.trim() ? `Raw (truncated): ${truncate(result.raw.trim(), rawLimit)}` : "",
+  ];
+  return lines.filter((line) => line.length > 0).join("\n");
+}
+
+/** Compact, bounded view of all scout findings for the Master's context (§36). */
+export function summarizeOutcomes(outcomes: ScoutOutcome[], rawLimit = 2000): string {
+  return outcomes.map((outcome) => describeOutcome(outcome, rawLimit)).join("\n\n");
+}

package/src/pi/activity.ts

@@ -0,0 +1,60 @@
+/**
+ * One-word descriptions of the tool an agent is running: subagents show it as
+ * `[spinner] word - elapsed`, and the oracle names the master's `orchestrate`
+ * action. Pure lookup:
+ * no clock, environment or I/O reads.
+ */
+const ACTIVITY_WORDS: Record<string, string> = {
+  read: "reading",
+  edit: "editing",
+  write: "editing",
+  grep: "searching",
+  find: "searching",
+  bash: "running",
+  orchestrate: "orchestrating",
+  web_search: "researching",
+  web_fetch: "researching",
+  fetch: "researching",
+  fetch_content: "researching",
+  get_search_content: "researching",
+  source_check: "researching",
+};
+
+const FALLBACK_WORD = "working";
+
+export function activityWord(toolName: string): string {
+  return ACTIVITY_WORDS[toolName.trim().toLowerCase()] ?? FALLBACK_WORD;
+}
+
+/** Master `orchestrate` actions -> the word the oracle shows instead of the generic "orchestrating". */
+const ORACLE_ACTION_WORDS: Record<string, string> = {
+  clarify: "asking",
+  scout: "scouting",
+  research: "researching",
+  propose: "proposing",
+  plan: "planning",
+  implement: "delegating",
+  qa: "reviewing",
+  knowledge: "recording",
+  compact: "recording",
+  decide: "deciding",
+  resolve_approval: "deciding",
+  complete: "wrapping up",
+  status: "checking",
+  block: "blocking",
+  resume: "resuming",
+  cancel: "cancelling",
+};
+
+function orchestrateAction(args: unknown): string | undefined {
+  if (!args || typeof args !== "object" || !("action" in args)) return undefined;
+  const action = (args as { action?: unknown }).action;
+  return typeof action === "string" ? action.trim().toLowerCase() : undefined;
+}
+
+/** One word for what the oracle (master) is doing; `orchestrate` maps by its action. */
+export function oracleActivityWord(toolName: string, args?: unknown): string {
+  if (toolName.trim().toLowerCase() !== "orchestrate") return activityWord(toolName);
+  const action = orchestrateAction(args);
+  return (action && ORACLE_ACTION_WORDS[action]) || FALLBACK_WORD;
+}