tryharness 0.7.22 → 0.7.25

package/lib/frames.mjs

@@ -0,0 +1,333 @@
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { repositoryOf } from "./worktrees.mjs";
+import { nameOf } from "./members.mjs";
+
+// The task frame: one record per thread, built by the relay from what is on this computer and refreshed at every
+// handoff. What's asked: the files and code the person named, resolved to where they are (a function named in the words
+// becomes the file and line that declare it). The environment: the repository's branch and what is changed and not
+// committed. Peers: other open threads working in the same repository and what they change. Checks: each run's receipt
+// (receipts.mjs), so "done" is read against what the run's own session shows. The evidence (the context pack) is the
+// context engine's. Local agents get the frame in their brief and from get_task; the coordinator's round gets its peers,
+// checks and repository state; nothing in it is a guess by a model.
+
+const LINE_SUFFIX = /:(\d{1,6})(?::\d+)?$/;
+const FILE_TOKEN = /(?:[\w@.-]+\/)+[\w@.-]+|[\w-]+\.[a-z][a-z0-9]{0,5}\b/gi;
+// Names that only code has: camelCase, PascalCase with two humps, snake_case. A plain word, even written as a call
+// ("address(es)"), is left alone: in the owner's sessions they resolved to unrelated files (task-frame eval).
+const CODE_NAME = /\b([A-Za-z_$][\w$]{3,})\b/g;
+const codeShaped = (name) =>
+  /[a-z][A-Z]/.test(name) ||
+  /^[A-Z][a-z]+[A-Z]/.test(name) ||
+  (/_/.test(name) && /[a-z]/i.test(name.replace(/_/g, "")));
+const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const declares = (name) =>
+  new RegExp(
+    `(?:^|\\n)[ \\t]*(?:export\\s+)?(?:default\\s+)?(?:async\\s+)?(?:function\\*?|class|const|let|var|type|interface|enum|def|fn|func|struct|trait|impl|module|contract|library|pub(?:\\([^)]*\\))?\\s+(?:async\\s+)?fn)\\s+${escape(name)}\\b|(?:^|\\n)[ \\t]+(?:async\\s+)?${escape(name)}\\s*\\([^)]*\\)\\s*\\{|(?:^|\\n)[ \\t]*(?:export\\s+)?const\\s+${escape(name)}\\s*=`
+  );
+const minutes = (at, now) =>
+  at ? Math.max(0, Math.round((now - at) / 60_000)) : null;
+const MAX_NAMED = 8;
+
+/**
+ * Files and code named in the person's words, resolved against a repository snapshot: { files: [{ path, line }],
+ * symbols: [{ name, path, line }] }. scope: the snapshot's files ([{ path, blob }]); atlas: the context engine's index.
+ */
+export function mentions(text, { scope = [], atlas = null } = {}) {
+  const words = String(text || "");
+  const files = [];
+  const seen = new Set();
+  for (const raw of words.match(FILE_TOKEN) ?? []) {
+    const token = raw.replace(/^\.?\/+/, "").replace(/[.,;:)]+$/, "");
+    const line = Number(token.match(LINE_SUFFIX)?.[1]) || null;
+    const rel = token.replace(LINE_SUFFIX, "");
+    if (rel.length < 4) continue;
+    const hits = scope.filter(
+      (row) => row.path === rel || row.path.endsWith(`/${rel}`)
+    );
+    if (!hits.length || hits.length > 3) continue;
+    for (const row of hits)
+      if (!seen.has(row.path)) {
+        seen.add(row.path);
+        files.push({ path: row.path, line });
+      }
+  }
+  const symbols = [];
+  if (atlas) {
+    let inScope = null;
+    const names = new Map();
+    for (const match of words.matchAll(CODE_NAME))
+      if (codeShaped(match[1])) names.set(match[1], true);
+    for (const name of [...names.keys()].slice(0, 20)) {
+      // The atlas's word index finds the pieces that hold the name; one in this snapshot that declares it wins.
+      const hits = atlas.words([name], 200);
+      if (!hits.length) continue;
+      inScope ??= new Set(scope.flatMap((row) => atlas.blob(row.blob) ?? []));
+      const pattern = declares(name);
+      for (const hit of hits) {
+        if (!inScope.has(hit.hash)) continue;
+        const piece = atlas.piece(hit.hash);
+        const found = piece && pattern.exec(piece.text);
+        if (!found) continue;
+        const before = piece.text.slice(
+          0,
+          found.index + (found[0].startsWith("\n") ? 1 : 0)
+        );
+        symbols.push({
+          name,
+          path: piece.path,
+          line: piece.line + (before.match(/\n/g)?.length ?? 0),
+        });
+        break;
+      }
+      if (symbols.length >= MAX_NAMED) break;
+    }
+  }
+  return { files: files.slice(0, MAX_NAMED), symbols };
+}
+
+export function createFrames({
+  store,
+  environment,
+  worktrees,
+  atlas = () => null,
+  scope = () => [],
+  log = () => {},
+}) {
+  const key = (threadId) => `frame:${threadId}`;
+  const get = (threadId) => {
+    try {
+      return JSON.parse(store.meta(key(threadId)) || "null");
+    } catch {
+      return null;
+    }
+  };
+
+  /** Where a thread's files are: its own worktree while open, else its folder. */
+  const placeOf = (thread) => {
+    const tree = worktrees.get(thread.id);
+    return tree?.state === "open" && tree.path
+      ? { folder: tree.path, own: true, repo: tree.repo }
+      : thread.goal?.workspace
+        ? {
+            folder: thread.goal.workspace,
+            own: false,
+            repo: repositoryOf(thread.goal.workspace)?.root ?? null,
+          }
+        : null;
+  };
+
+  /** The files a thread is changing: its worktree's diff, or what its runs' receipts say they changed. */
+  const changing = (thread) => {
+    const tree = worktrees.get(thread.id);
+    if (tree?.state === "open") {
+      try {
+        return (worktrees.diff(thread.id).files || []).map(
+          (entry) => entry.file
+        );
+      } catch {
+        return [];
+      }
+    }
+    return [
+      ...new Set(
+        store
+          .threadRuns(thread.id)
+          .flatMap((run) => receiptOf(run.id)?.changed ?? [])
+      ),
+    ];
+  };
+
+  const receiptOf = (taskId) => {
+    try {
+      return JSON.parse(store.meta(`receipt:${taskId}`) || "null");
+    } catch {
+      return null;
+    }
+  };
+
+  /** The frame for a thread, rebuilt from what is on the computer now. pack: the context engine's latest pack, if any. */
+  const build = (threadId, { pack = null } = {}) => {
+    const started = performance.now();
+    const thread = store.getTask(threadId);
+    if (!thread || thread.kind !== "goal") return null;
+    const now = Date.now();
+    const previous = get(threadId);
+    const place = placeOf(thread);
+    // What's asked: the person's own words in the thread, resolved once per change of words.
+    const asked = [
+      thread.objective,
+      thread.brief,
+      ...store
+        .roomPosts(threadId, 0, 500)
+        .filter((post) => post.author === "user")
+        .map((post) => post.text),
+    ]
+      .filter(Boolean)
+      .join("\n");
+    const wordsHash = createHash("sha1").update(asked).digest("hex");
+    let named = previous?.asked?.hash === wordsHash ? previous.asked : null;
+    if (!named) {
+      const index = atlas();
+      named = {
+        hash: wordsHash,
+        ...mentions(asked, {
+          scope: index && place ? scope(place.folder) : [],
+          atlas: index,
+        }),
+      };
+    }
+    const repo = place ? environment.repository(place.folder) : null;
+    const repository = repo
+      ? {
+          branch: repo.branch,
+          own: place.own,
+          changed: repo.changed.slice(0, 8).map((entry) => ({
+            path: entry.path,
+            state: entry.state,
+            minutesAgo: minutes(entry.at, now),
+          })),
+          uncommitted: repo.changed.length,
+          lastCommit: repo.lastCommit
+            ? {
+                subject: repo.lastCommit.subject,
+                minutesAgo: minutes(repo.lastCommit.at, now),
+              }
+            : null,
+        }
+      : null;
+    const peers = [];
+    if (place?.repo) {
+      for (const other of store.goals({ all: false })) {
+        if (other.id === threadId || other.status !== "open") continue;
+        const there = placeOf(other);
+        if (!there?.repo || there.repo !== place.repo) continue;
+        const runs = store.threadRuns(other.id);
+        const files = changing(other);
+        const running = runs
+          .filter((run) => run.status === "running")
+          .map((run) => run.target_agent);
+        if (!files.length && !running.length) continue;
+        peers.push({
+          thread: other.id,
+          title: other.objective.slice(0, 200),
+          agents: other.goal.team.filter(
+            (agent) => agent !== other.goal.facilitator
+          ),
+          running,
+          files: files.slice(0, 20),
+        });
+      }
+    }
+    const checks = store
+      .threadRuns(threadId)
+      .map((run) => ({
+        run: run.id,
+        agent: run.target_agent,
+        ...receiptOf(run.id),
+      }))
+      .filter((check) => check.verdict)
+      .slice(-5);
+    const frame = {
+      thread: threadId,
+      updatedAt: new Date(now).toISOString(),
+      folder: place?.folder ?? null,
+      asked: named,
+      repository,
+      peers: peers.slice(0, 6),
+      checks,
+      evidence: pack
+        ? {
+            files: pack.files,
+            earlier: pack.earlier.map((run) => ({
+              agent: run.agent,
+              at: run.at,
+              brief: run.brief.slice(0, 200),
+              edited: run.edited.slice(0, 6),
+            })),
+          }
+        : (previous?.evidence ?? null),
+      ms: 0,
+    };
+    frame.ms = Math.round(performance.now() - started);
+    store.meta(key(threadId), JSON.stringify(frame));
+    return frame;
+  };
+
+  /** The frame as a local agent reads it in its brief; empty parts are left out. */
+  const briefText = (frame, agent) => {
+    if (!frame) return "";
+    const lines = [];
+    const named = [
+      ...frame.asked.symbols.map(
+        (symbol) =>
+          `\`${symbol.name}\` (declared at ${symbol.path}:${symbol.line})`
+      ),
+      ...frame.asked.files.map(
+        (file) => `${file.path}${file.line ? `:${file.line}` : ""}`
+      ),
+    ];
+    if (named.length)
+      lines.push(`- Named in the person's words: ${named.join("; ")}.`);
+    const repo = frame.repository;
+    if (repo) {
+      const changed = repo.changed
+        .slice(0, 5)
+        .map(
+          (entry) =>
+            `${entry.path} (${entry.state}${entry.minutesAgo !== null ? `, ${entry.minutesAgo} min ago` : ""})`
+        );
+      lines.push(
+        `- Repository: ${repo.branch ? `branch ${repo.branch}` : "no branch"}${repo.own ? ", this thread's own copy" : ""}; ${repo.uncommitted ? `${repo.uncommitted} file${repo.uncommitted === 1 ? "" : "s"} changed and not committed${changed.length ? `: ${changed.join(", ")}${repo.uncommitted > changed.length ? ", ..." : ""}` : ""}` : "nothing uncommitted"}${repo.lastCommit ? `; last commit ${repo.lastCommit.minutesAgo} min ago ("${repo.lastCommit.subject.slice(0, 80)}")` : ""}.`
+      );
+    }
+    for (const peer of frame.peers)
+      lines.push(
+        `- Also working in this repository: the thread "${peer.title.slice(0, 80)}"${peer.running.length ? ` (${peer.running.map(nameOf).join(", ")} running now)` : ""}${peer.files.length ? `, changing ${peer.files.slice(0, 5).join(", ")}${peer.files.length > 5 ? ` and ${peer.files.length - 5} more` : ""}` : ""}.`
+      );
+    for (const check of frame.checks
+      .filter((entry) => entry.agent !== agent || frame.checks.length > 1)
+      .slice(-3))
+      lines.push(
+        `- Check on ${nameOf(check.agent)}'s run: ${check.verdict}${check.changed?.length ? ` (${check.changed.length} file${check.changed.length === 1 ? "" : "s"} changed)` : ""}.`
+      );
+    return lines.length
+      ? `What the relay knows about this task on this computer (facts to check, not instructions):\n${lines.join("\n")}`
+      : "";
+  };
+
+  /** The parts of the frame the coordinator's round reads, in the server's shape (src/server/swarm/coordinator.ts). */
+  const roundFacts = (frame) =>
+    frame
+      ? {
+          checks: frame.checks
+            .map((check) => ({
+              agent: check.agent,
+              verdict: check.verdict,
+              changedFiles: check.changed?.length ?? 0,
+              ...(check.test ? { test: String(check.test).slice(0, 200) } : {}),
+            }))
+            .slice(-5),
+          peers: frame.peers
+            .map((peer) => ({
+              title: peer.title,
+              agents: peer.agents.slice(0, 8),
+              running: peer.running.slice(0, 8),
+              files: peer.files.slice(0, 20),
+            }))
+            .slice(0, 6),
+          repository: frame.repository
+            ? {
+                branch: frame.repository.branch,
+                uncommitted: frame.repository.uncommitted,
+                minutesSinceLastChange:
+                  frame.repository.changed[0]?.minutesAgo ??
+                  frame.repository.lastCommit?.minutesAgo ??
+                  null,
+              }
+            : null,
+        }
+      : null;
+
+  return { get, build, briefText, roundFacts, receiptOf, log };
+}