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

package/src/pi/zen.ts

@@ -67,9 +67,12 @@ const PREFIX_CHARS = 32;
 const MIN_PREFIX = 8;
 const HEADER_LINE = /^\s*(?:#{1,6}\s+\S.*|\*\*[^*]+\*\*)\s*$/;
 const STEP_SECTION = /sequence|steps|order/i;
-const NUMBERED_STEP_LINE = /^\s*\d+[.)]\s+(.*\S)\s*$/;
-const INDENTED_BULLET = /^\s*[*-]\s+(.*\S)\s*$/;
-const TOP_LEVEL_BULLET = /^[*-]\s+(.*\S)\s*$/;
+const NUMBERED_STEP_LINE = /^(\s*)(\d+[.)])\s+(.*\S)\s*$/;
+const BULLET_LINE = /^(\s*)([*-])\s+(.*\S)\s*$/;
+const TOP_LEVEL_BULLET = /^()([*-])\s+(.*\S)\s*$/;
+/** `### Step 2: Wire the API`, `**Step 2 — Wire the API**`, `Phase 3) Tests`: one plan step per heading. */
+const STEP_HEADING = /^\s*(?:#{1,6}\s+)?(?:\*\*)?\s*(?:step|phase|stage)\s+#?\d+\s*(?:\*\*)?\s*[:.)\u2014\u2013-]\s*(?:\*\*)?\s*(.*?)\s*(?:\*\*)?\s*$/i;
+const MIN_STEP_HEADINGS = 2;
 
 export type PlanStepStatus = "done" | "current" | "pending";
 
@@ -78,20 +81,54 @@ export interface PlanStep {
   status: PlanStepStatus;
 }
 
-/** Numbered `1.`/`1)` text, or a bullet inside a step section; undefined otherwise. */
-function stepText(line: string): string | undefined {
-  return NUMBERED_STEP_LINE.exec(line)?.[1] ?? INDENTED_BULLET.exec(line)?.[1];
+interface ListItem {
+  indent: number;
+  /** Column where the item's text starts; deeper items are nested under it. */
+  content: number;
+  text: string;
+}
+
+type ItemMatcher = (line: string) => ListItem | undefined;
+
+function indentOf(line: string): number {
+  return /^\s*/.exec(line)![0].replace(/\t/g, "    ").length;
+}
+
+function itemMatcher(pattern: RegExp): ItemMatcher {
+  return (line) => {
+    const match = pattern.exec(line);
+    if (!match) return undefined;
+    const indent = indentOf(match[1]!);
+    return { indent, content: indent + match[2]!.length + 1, text: match[3]! };
+  };
 }
 
-function topBulletText(line: string): string | undefined {
-  return TOP_LEVEL_BULLET.exec(line)?.[1];
+const numberedItem = itemMatcher(NUMBERED_STEP_LINE);
+const bulletItem = itemMatcher(BULLET_LINE);
+const topBulletItem = itemMatcher(TOP_LEVEL_BULLET);
+
+/** Numbered `1.`/`1)` text, or a bullet inside a step section; undefined otherwise. */
+function sectionItem(line: string): ListItem | undefined {
+  return numberedItem(line) ?? bulletItem(line);
 }
 
-function collectSteps(lines: readonly string[], accept: (line: string) => string | undefined): string[] {
+/**
+ * Top-level list items only. As in CommonMark, an item indented to its parent's
+ * text column is a sub-point of that step, so nested bullets or a nested `1.`
+ * list never inflate the checklist. Prose at a shallower indent ends the parent.
+ */
+function collectSteps(lines: readonly string[], accept: ItemMatcher): string[] {
   const found: string[] = [];
+  let parent: number | undefined;
   for (const line of lines) {
-    const text = accept(line);
-    if (text !== undefined) found.push(text);
+    const item = accept(line);
+    if (!item) {
+      if (parent !== undefined && line.trim() && indentOf(line) < parent) parent = undefined;
+      continue;
+    }
+    if (parent !== undefined && item.indent >= parent) continue;
+    found.push(item.text);
+    parent = item.content;
   }
   return found;
 }
@@ -108,37 +145,143 @@ function stepSection(lines: readonly string[]): string[] | undefined {
   return body;
 }
 
+/** `Step N` headings, when the plan is structured as one heading per step. */
+function headingSteps(lines: readonly string[]): string[] {
+  const found: string[] = [];
+  for (const line of lines) {
+    const match = STEP_HEADING.exec(line);
+    if (match) found.push(match[1] || line.replace(/[#*]/g, "").trim());
+  }
+  return found.length >= MIN_STEP_HEADINGS ? found : [];
+}
+
 /**
- * Step texts from a free-form plan, capped. A `sequence|steps|order` section wins; otherwise
- * numbered lines win; when neither exists, top-level bullets are the last resort, so unrelated
- * bullet lists under other headers never leak into the checklist.
+ * Step texts from a free-form plan, capped. `Step N` headings win; then a
+ * `sequence|steps|order` section; then numbered lines; when none exists,
+ * top-level bullets are the last resort, so unrelated bullet lists under other
+ * headers never leak into the checklist. Only the shallowest items count.
  */
 export function planSteps(plan: string): string[] {
   const lines = plan.split("\n");
+  const headings = headingSteps(lines);
+  if (headings.length > 0) return headings.slice(0, MAX_PLAN_STEPS);
   const section = stepSection(lines);
   if (section) {
-    const sectioned = collectSteps(section, stepText);
+    const sectioned = collectSteps(section, sectionItem);
     if (sectioned.length > 0) return sectioned.slice(0, MAX_PLAN_STEPS);
   }
-  const numbered = collectSteps(lines, (line) => NUMBERED_STEP_LINE.exec(line)?.[1]);
+  const numbered = collectSteps(lines, numberedItem);
   if (numbered.length > 0) return numbered.slice(0, MAX_PLAN_STEPS);
-  return collectSteps(lines, topBulletText).slice(0, MAX_PLAN_STEPS);
+  return collectSteps(lines, topBulletItem).slice(0, MAX_PLAN_STEPS);
 }
 
+/* -------------------------------------------------------------------------
+ * Step matching. A worker instruction names its step explicitly ("Step 3: ...")
+ * or is scored against every step by shared paths, a shared opening phrase and
+ * word overlap. Plans reuse file paths across steps, so near-ties go to the
+ * earliest step still open instead of the first step that ever mentioned the
+ * path -- otherwise every later instruction re-matches step 1 and the tracker
+ * never moves.
+ * ---------------------------------------------------------------------- */
+
+const STEP_REFERENCE = /\bsteps?\s*#?\s*(\d+)(?:\s*(?:-|\u2013|\u2014|to|through|thru|and|&)\s*#?\s*(\d+))?/gi;
+/** Text allowed before a step reference that labels the instruction itself ("Now implement step 3:"). */
+const LEADING_LABEL = /^[\s\W]*(?:(?:now|next|then|please|implement|do|complete|execute|start|begin|finish|work on|continue with|proceed with|plan)\s+)*(?:the\s+)?$/i;
+const MIN_SCORE = 0.5;
+const NEAR_TIE = 0.35;
+const PATH_WEIGHT = 0.75;
+const PREFIX_WEIGHT = 1;
+const WORD = /[a-z0-9_][a-z0-9_./-]*[a-z0-9_]/g;
+const MIN_WORD = 3;
+const STOP_WORDS = new Set([
+  "the", "and", "for", "with", "that", "this", "from", "into", "then", "when", "each", "use", "make",
+  "sure", "new", "all", "any", "its", "are", "not", "but", "now", "via", "per", "our", "your", "you",
+  "has", "have", "will", "should", "must", "also", "only", "step", "steps", "plan", "approved",
+  "implement", "please", "add", "update", "change", "changes", "file", "files", "code",
+]);
+
 function normalize(text: string): string {
   return text.replace(/[`*_]/g, "").replace(/\s+/g, " ").trim().toLowerCase();
 }
 
-function matchesInstruction(step: string, instruction: string): boolean {
-  const hay = normalize(instruction);
-  const path = /`([^`]+)`/.exec(step)?.[1];
-  if (path && hay.includes(normalize(path))) return true;
-  const tail = normalize(step.replace(/`[^`]+`/g, " ").replace(/^[\s:;,.—–-]+/, ""));
+function significantWords(text: string): Set<string> {
+  const words = new Set<string>();
+  for (const word of normalize(text).match(WORD) ?? []) {
+    if (word.length >= MIN_WORD && !STOP_WORDS.has(word)) words.add(word);
+  }
+  return words;
+}
+
+/** Scoring context for one instruction, built once per run and reused for every step. */
+interface InstructionIndex {
+  text: string;
+  words: Set<string>;
+}
+
+function indexInstruction(instruction: string): InstructionIndex {
+  return { text: normalize(instruction), words: significantWords(instruction) };
+}
+
+function prefixMatches(step: string, hay: string): boolean {
+  const tail = normalize(step.replace(/`[^`]+`/g, " ").replace(/^[\s:;,.\u2014\u2013-]+/, ""));
   return tail.length >= MIN_PREFIX && hay.includes(tail.slice(0, PREFIX_CHARS));
 }
 
+function pathShare(step: string, hay: string): number {
+  const paths = [...step.matchAll(/`([^`]+)`/g)].map((match) => normalize(match[1]!)).filter((path) => path.length > 0);
+  if (paths.length === 0) return 0;
+  return paths.filter((path) => hay.includes(path)).length / paths.length;
+}
+
+function wordShare(step: string, words: ReadonlySet<string>): number {
+  const own = significantWords(step);
+  if (own.size === 0) return 0;
+  let shared = 0;
+  for (const word of own) if (words.has(word)) shared += 1;
+  return shared / own.size;
+}
+
+/** How strongly an instruction targets one step; 0 when it shares nothing. */
+function stepScore(step: string, instruction: InstructionIndex): number {
+  const prefix = prefixMatches(step, instruction.text) ? PREFIX_WEIGHT : 0;
+  return prefix + PATH_WEIGHT * pathShare(step, instruction.text) + wordShare(step, instruction.words);
+}
+
+/**
+ * Highest 0-based step an instruction labels itself with ("Step 3: ...", "steps 2-4"),
+ * or -1. A reference counts when it opens the instruction or is the only one
+ * named, so "building on step 1, now do step 3" does not jump back to step 1.
+ */
+export function explicitStepIndex(instruction: string, count: number): number {
+  const refs = [...instruction.matchAll(STEP_REFERENCE)];
+  if (refs.length === 0) return -1;
+  const first = refs[0]!;
+  const leading = LEADING_LABEL.test(instruction.slice(0, first.index ?? 0)) ? first : undefined;
+  const distinct = new Set(refs.map((ref) => ref[0].toLowerCase().replace(/\s+/g, "")));
+  const chosen = leading ?? (distinct.size === 1 ? refs[0] : undefined);
+  if (!chosen) return -1;
+  const last = Math.max(Number(chosen[1]), Number(chosen[2] ?? chosen[1]));
+  return last >= 1 && last <= count ? last - 1 : -1;
+}
+
+/**
+ * The step an instruction targets, given the steps already completed; -1 when
+ * nothing matches. Among near-tied candidates the earliest open step wins.
+ */
+export function targetStep(steps: readonly string[], instruction: string | undefined, completed: ReadonlySet<number> = new Set()): number {
+  if (!instruction || steps.length === 0) return -1;
+  const explicit = explicitStepIndex(instruction, steps.length);
+  if (explicit >= 0) return explicit;
+  const index = indexInstruction(instruction);
+  const scores = steps.map((step) => stepScore(step, index));
+  const best = Math.max(...scores);
+  if (best < MIN_SCORE) return -1;
+  const near = scores.findIndex((score, at) => score >= best - NEAR_TIE && score >= MIN_SCORE && !completed.has(at));
+  return near >= 0 ? near : scores.indexOf(best);
+}
+
 /** The latest worker run carrying an instruction; its step is the current one. */
-export function latestWorkerRun(runs: AgentRun[]): AgentRun | undefined {
+export function latestWorkerRun(runs: readonly AgentRun[]): AgentRun | undefined {
   let latest: AgentRun | undefined;
   for (const run of runs) {
     if (run.role !== "worker" || !run.instruction) continue;
@@ -147,11 +290,6 @@ export function latestWorkerRun(runs: AgentRun[]): AgentRun | undefined {
   return latest;
 }
 
-/** Index of the plan step an instruction targets, -1 when nothing matches. */
-export function currentStepIndex(steps: readonly string[], instruction: string | undefined): number {
-  return instruction ? steps.findIndex((step) => matchesInstruction(step, instruction)) : -1;
-}
-
 function stepStatus(index: number, current: number): PlanStepStatus {
   if (current < 0) return index === 0 ? "current" : "pending";
   if (index < current) return "done";
@@ -168,37 +306,58 @@ function markThrough(completed: Set<number>, index: number): void {
   for (let step = 0; step <= index; step += 1) completed.add(step);
 }
 
+function byStart(runs: readonly AgentRun[]): AgentRun[] {
+  const time = (run: AgentRun) => {
+    const at = Date.parse(run.startedAt);
+    return Number.isFinite(at) ? at : 0;
+  };
+  return runs
+    .map((run, order) => ({ run, order }))
+    .sort((a, b) => time(a.run) - time(b.run) || a.order - b.order)
+    .map((entry) => entry.run);
+}
+
 /**
- * Steps completed by successful worker runs, in start order. A run whose instruction matches
- * a step completes everything up to that step; a run that matches nothing -- the common case
- * for a reworded instruction -- completes the next still-open step, so the count only grows
- * and a failure can never tick one off.
+ * Replays worker runs in start order. A successful run completes everything up
+ * to its target step; a run that matches nothing -- the common case for a
+ * reworded instruction -- completes the next still-open step, so the count only
+ * grows and a failure can never tick one off. The latest worker run's own target
+ * is reported separately so a running or failed step reads current.
  */
-function completedSteps(steps: readonly string[], runs: AgentRun[]): number {
+function replaySteps(steps: readonly string[], runs: readonly AgentRun[]): { completed: number; latest: number } {
   const completed = new Set<number>();
-  for (const run of runs) {
-    if (run.role !== "worker" || run.status !== "success") continue;
-    const matched = currentStepIndex(steps, run.instruction);
+  const latestRun = latestWorkerRun(runs);
+  let latest = -1;
+  for (const run of byStart(runs)) {
+    if (run.role !== "worker") continue;
+    const matched = targetStep(steps, run.instruction, completed);
+    if (run === latestRun) latest = matched >= 0 && run.status === "success" ? matched + 1 : matched;
+    if (run.status !== "success") continue;
     const target = matched >= 0 ? matched : nextOpenStep(steps, completed);
     if (target >= 0) markThrough(completed, target);
   }
-  return completed.size;
+  return { completed: completed.size, latest };
 }
 
+/** One-entry memo: the panel asks for the same checklist several times per frame. */
+let checklistMemo: { plan: string; runs: readonly AgentRun[]; steps: PlanStep[] } | undefined;
+
 /**
- * Done/current/pending per plan step, matched from the latest worker instruction.
- * A succeeded run completes its step, so the next step becomes current (and the
- * last step reads done); running, failed, cancelled and timeout runs keep it current.
- * Progress is monotonic: steps already completed by successful worker runs stay done,
- * and a later call that names an earlier step can never tick it back.
+ * Done/current/pending per plan step. A succeeded run completes its step, so the
+ * next step becomes current (and the last step reads done); running, failed,
+ * cancelled and timeout runs keep it current. Progress is monotonic: steps
+ * already completed by successful worker runs stay done, and a later call that
+ * names an earlier step can never tick it back. Memoized on the exact plan text
+ * and runs array, so callers must not mutate either.
  */
-export function planChecklist(plan: string, runs: AgentRun[]): PlanStep[] {
-  const steps = planSteps(plan);
-  const latest = latestWorkerRun(runs);
-  const matched = currentStepIndex(steps, latest?.instruction);
-  const latestCurrent = matched >= 0 ? (latest?.status === "success" ? matched + 1 : matched) : -1;
-  const current = Math.max(completedSteps(steps, runs), latestCurrent);
-  return steps.map((text, index) => ({ text, status: stepStatus(index, current) }));
+export function planChecklist(plan: string, runs: readonly AgentRun[]): PlanStep[] {
+  if (checklistMemo && checklistMemo.plan === plan && checklistMemo.runs === runs) return checklistMemo.steps;
+  const texts = planSteps(plan);
+  const replay = replaySteps(texts, runs);
+  const current = Math.max(replay.completed, replay.latest);
+  const steps = texts.map((text, index) => ({ text, status: stepStatus(index, current) }));
+  checklistMemo = { plan, runs, steps };
+  return steps;
 }
 
 /** Up to `count` consecutive step indexes centered on the current step, hard-capped at `max`. */
@@ -211,7 +370,7 @@ export function checklistWindow(steps: readonly PlanStep[], count: number, max =
   return Array.from({ length: size }, (_value, offset) => start + offset);
 }
 
-function stepLine(step: PlanStep, ordinal: number): string {
+function checklistRow(step: PlanStep, ordinal: number): string {
   const icon = step.status === "done" ? "✓" : step.status === "current" ? "◐" : "○";
   return `  ${icon} ${ordinal}. ${step.text}`;
 }
@@ -329,7 +488,7 @@ function tailLines(task: Task, runs: AgentRun[], now: number, tick: number, step
 
 function checklistLines(steps: PlanStep[], count: number): string[] {
   if (steps.length === 0 || count <= 0) return [];
-  return checklistWindow(steps, count).map((index) => stepLine(steps[index]!, index + 1));
+  return checklistWindow(steps, count).map((index) => checklistRow(steps[index]!, index + 1));
 }
 
 function compactPanel(
@@ -378,9 +537,9 @@ function sceneSlots(metrics: SceneMetrics, expressions: ExpressionFrames): Large
   }));
 }
 
-function oracleSlot(task: Task, expressions: ExpressionFrames): LargeSceneInput["oracle"] {
+function oracleSlot(task: Task, expressions: ExpressionFrames, motion: OracleMotion): LargeSceneInput["oracle"] {
   const pose = oraclePose(task);
-  return { pose, frame: expressions.oracle ?? REST_FRAME };
+  return { pose, frame: expressions.oracle ?? REST_FRAME, ...motion };
 }
 
 function sceneTasks(steps: readonly PlanStep[]): LargeTaskRow[] {
@@ -397,8 +556,7 @@ function sceneInput(
   quiet: boolean,
   tick: number,
   steps: PlanStep[],
-  expressions: ExpressionFrames,
-  oracleActivity: string | undefined,
+  opts: PanelOptions,
 ): LargeSceneInput {
   const metrics = sceneMetrics(task, runs, now);
   const alert = taskAlert(task);
@@ -411,10 +569,11 @@ function sceneInput(
     tick,
     done: metrics.done,
     total: metrics.total,
-    slots: sceneSlots(metrics, expressions),
+    slots: sceneSlots(metrics, opts.expressions ?? {}),
     tasks: sceneTasks(steps),
-    oracle: oracleSlot(task, expressions),
-    oracleActivity,
+    oracle: oracleSlot(task, opts.expressions ?? {}, opts.oracleMotion ?? {}),
+    oracleActivity: opts.oracleActivity,
+    caption: task.paused ? "task paused" : SCENE_PROPS[task.state],
     alert: alert?.text,
     alertKind: alert?.kind,
   };
@@ -429,8 +588,16 @@ export interface PanelOptions {
   theme?: PanelTheme;
   /** Caller-scheduled expression frame per slot and the oracle; absent means rest. */
   expressions?: ExpressionFrames;
-  /** Live master activity word for the oracle spinner; absent reads "working". */
+  /** Live master activity word for the oracle's speech bubble; absent means it waits on the user. */
   oracleActivity?: string;
+  /** Caller-clocked oracle animation: the expression's sub-step and the lip-sync shape. */
+  oracleMotion?: OracleMotion;
+}
+
+/** The oracle's clocked animation state beyond its expression frame (see expressions.ts). */
+export interface OracleMotion {
+  phase?: number;
+  talk?: number;
 }
 
 /**
@@ -453,7 +620,7 @@ export function panelLines(
   const steps = planChecklist(task.plan ?? "", runs);
   const budget = largeLineBudget(opts.rows ?? DEFAULT_ROWS);
   if (width >= LARGE_MIN_WIDTH && budget >= MIN_LARGE_LINES) {
-    const scene = largeLines(sceneInput(task, runs, now, quiet, tick, steps, opts.expressions ?? {}, opts.oracleActivity), width, budget, opts.theme);
+    const scene = largeLines(sceneInput(task, runs, now, quiet, tick, steps, opts), width, budget, opts.theme);
     return scene.map((line) => truncateToWidth(line, width));
   }
   return compactPanel(task, runs, now, quiet, tick, steps, opts, width);

package/src/schemas/task.ts

@@ -54,6 +54,22 @@ export interface ReviewRecord {
   requiredChanges: string[];
   createdAt: string;
 }
+/**
+ * One finished worker delegation, kept on the task so the plan checklist can be
+ * replayed after a reload instead of resetting to the first step.
+ */
+export interface WorkerRunRecord {
+  runId: string;
+  domain: Domain;
+  instruction: string;
+  status: "running" | "success" | "failed" | "cancelled" | "timeout";
+  startedAt: string;
+  finishedAt?: string;
+}
+
+/** Upper bound on persisted worker records; plans cap at 50 steps. */
+export const MAX_WORKER_RECORDS = 64;
+
 export interface Task {
   id: string;
   title: string;
@@ -71,6 +87,8 @@ export interface Task {
   blockers: Blocker[];
   decisions: Decision[];
   approvals: Approval[];
+  /** Worker delegations in start order; absent on tasks created before tracking. */
+  workerRuns?: WorkerRunRecord[];
   createdAt: string;
   updatedAt: string;
   /** The pi session (ctx.sessionManager id) that owns this task; absent on legacy tasks. */

package/src/workflow/workflow.ts

@@ -1,7 +1,17 @@
 import { join } from "node:path";
 import type { BotLobbyConfig } from "../schemas/configuration.ts";
 import type { AgentRun, Pushback, ResearchResult, ReviewResult } from "../schemas/findings.ts";
-import { TASK_STATES, TERMINAL_STATES, taskRequest, type Approval, type ApprovalKind, type Task, type TaskState } from "../schemas/task.ts";
+import {
+  MAX_WORKER_RECORDS,
+  TASK_STATES,
+  TERMINAL_STATES,
+  taskRequest,
+  type Approval,
+  type ApprovalKind,
+  type Task,
+  type TaskState,
+  type WorkerRunRecord,
+} from "../schemas/task.ts";
 import { isDomain, type Domain } from "../schemas/agent.ts";
 import { transition } from "../state/task-state.ts";
 import { ownerlessTask, readTaskArtifact, removeTaskScratchpads, saveTask, selectTask, taskDirFor, taskReadDirs } from "../state/persistence.ts";
@@ -495,6 +505,19 @@ function workerRequest(deps: WorkflowDeps, task: Task, domain: Domain, instructi
   };
 }
 
+/** Remember a worker delegation so the checklist replays it after a reload. */
+function recordWorkerRun(task: Task, run: AgentRun): void {
+  const record: WorkerRunRecord = {
+    runId: run.runId,
+    domain: run.domain,
+    instruction: run.instruction ?? "",
+    status: run.status,
+    startedAt: run.startedAt,
+    ...(run.finishedAt ? { finishedAt: run.finishedAt } : {}),
+  };
+  task.workerRuns = [...(task.workerRuns ?? []), record].slice(-MAX_WORKER_RECORDS);
+}
+
 async function handleImplement(task: Task, params: OrchestrateParams, deps: WorkflowDeps): Promise<string> {
   requireState(task, ["planning", "implementing", "reviewing"]);
   const domain = parseDomain(params.domain, "implement");
@@ -504,6 +527,7 @@ async function handleImplement(task: Task, params: OrchestrateParams, deps: Work
   if (!task.domains.includes(domain)) task.domains.push(domain);
   if (task.state !== "implementing") transition(task, "implementing");
   const outcome = await runWorker(workerRequest(deps, task, domain, instruction), deps.runProcess ?? spawnPiProcess);
+  recordWorkerRun(task, outcome.run);
   const approvals = recordWorkerApprovals(task, outcome, deps.config);
   const pushback = recordPushback(task, outcome);
   task.blockers = [...task.blockers.filter((blocker) => blocker.domain !== domain), ...outcome.result.blockers];