harnery 0.0.1 → 0.2.0

package/src/core/agents/state/names.ts

@@ -0,0 +1,399 @@
+/**
+ * Hurricane-style name pool for the agent coordination layer. The name-pool
+ * assignment + resolution helpers.
+ *
+ * Layout invariant: 260 entries (10 per starting letter A..Z). Counter N
+ * picks COORD_NAMES[N % 260]; wraps to A at N=260.
+ *
+ * Durable persistence: `.harnery/.name-history` (JSONL, one row per assignment)
+ * + `.harnery/.name-counter` (current counter, atomic temp+rename).
+ *
+ * Recreation rule (mirrors v1):
+ *   1. Own instance_id in name-history → (original name, original kind)
+ *   2. session_id in name-history (owner != session) → (parent's name, "transient")
+ *   3. Else: new assignment, consume a counter slot.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** All 260 names. */
+export const COORD_NAMES = [
+  // Pass 1
+  "Anna",
+  "Bob",
+  "Carlos",
+  "Dalia",
+  "Erika",
+  "Fred",
+  "Gemma",
+  "Hank",
+  "Imelda",
+  "Jerry",
+  "Kirk",
+  "Lee",
+  "Milton",
+  "Nate",
+  "Oscar",
+  "Patty",
+  "Quentin",
+  "Rafael",
+  "Sara",
+  "Tony",
+  "Ulrik",
+  "Valerie",
+  "Whitney",
+  "Xander",
+  "Yara",
+  "Zara",
+  // Pass 2
+  "Adelaide",
+  "Bertha",
+  "Carmen",
+  "Dorian",
+  "Edna",
+  "Francine",
+  "Greta",
+  "Helene",
+  "Ines",
+  "Joyce",
+  "Karen",
+  "Lorenzo",
+  "Mindy",
+  "Nadine",
+  "Odette",
+  "Paulette",
+  "Quinn",
+  "Rebekah",
+  "Sean",
+  "Tammy",
+  "Ursula",
+  "Vinson",
+  "Wallace",
+  "Xanthe",
+  "Yusuf",
+  "Zoe",
+  // Pass 3
+  "Alex",
+  "Beatrice",
+  "Cyrus",
+  "Delia",
+  "Ernesto",
+  "Florence",
+  "Gordon",
+  "Hester",
+  "Isaias",
+  "Jenna",
+  "Klaus",
+  "Larry",
+  "Maxine",
+  "Nicholas",
+  "Otto",
+  "Peter",
+  "Quill",
+  "Renee",
+  "Stella",
+  "Theresa",
+  "Umberto",
+  "Virgil",
+  "Willow",
+  "Xavier",
+  "Yolanda",
+  "Zane",
+  // Pass 4
+  "Anita",
+  "Bruno",
+  "Cora",
+  "Damon",
+  "Edith",
+  "Felix",
+  "Gloria",
+  "Holly",
+  "Iris",
+  "Jasper",
+  "Kaia",
+  "Linda",
+  "Marco",
+  "Nora",
+  "Olive",
+  "Petra",
+  "Querida",
+  "Roman",
+  "Sebastian",
+  "Tobias",
+  "Una",
+  "Vera",
+  "Walter",
+  "Xena",
+  "Yusra",
+  "Zelda",
+  // Pass 5
+  "Aaron",
+  "Bonnie",
+  "Caleb",
+  "Daphne",
+  "Elias",
+  "Fiona",
+  "Galileo",
+  "Hugo",
+  "Ian",
+  "Jude",
+  "Knox",
+  "Leo",
+  "Maya",
+  "Nash",
+  "Owen",
+  "Paxton",
+  "Quetzal",
+  "Rosa",
+  "Sage",
+  "Talia",
+  "Uri",
+  "Vincent",
+  "Wesley",
+  "Ximena",
+  "Yvette",
+  "Zephyr",
+  // Pass 6
+  "Astrid",
+  "Beau",
+  "Celeste",
+  "Dexter",
+  "Ezra",
+  "Fitz",
+  "Genevieve",
+  "Hadley",
+  "Imogen",
+  "Joaquin",
+  "Kira",
+  "Lila",
+  "Mason",
+  "Nila",
+  "Olga",
+  "Pearl",
+  "Quincy",
+  "Royce",
+  "Sterling",
+  "Trent",
+  "Ulysses",
+  "Violet",
+  "Wynne",
+  "Xerxes",
+  "Yael",
+  "Zinnia",
+  // Pass 7
+  "Amelia",
+  "Bianca",
+  "Cody",
+  "Dahlia",
+  "Esme",
+  "Fern",
+  "Greer",
+  "Harriet",
+  "Ivan",
+  "Juno",
+  "Kendrick",
+  "Luther",
+  "Margot",
+  "Nigel",
+  "Orion",
+  "Phillip",
+  "Quenby",
+  "Reagan",
+  "Sienna",
+  "Tessa",
+  "Uma",
+  "Vesper",
+  "Watson",
+  "Xiomara",
+  "Yuri",
+  "Zoltan",
+  // Pass 8
+  "Andre",
+  "Boris",
+  "Cassidy",
+  "Davis",
+  "Evander",
+  "Forrest",
+  "Gibson",
+  "Henry",
+  "Irene",
+  "Justus",
+  "Kasper",
+  "Lainey",
+  "Miles",
+  "Naomi",
+  "Ophelia",
+  "Phoebe",
+  "Quark",
+  "Rylie",
+  "Saul",
+  "Truman",
+  "Ulrich",
+  "Voss",
+  "Winifred",
+  "Xuxa",
+  "Yvonne",
+  "Zia",
+  // Pass 9
+  "Aria",
+  "Brenda",
+  "Crispin",
+  "Dolores",
+  "Estelle",
+  "Felicity",
+  "Goldie",
+  "Hazel",
+  "Ira",
+  "Jovi",
+  "Kestrel",
+  "Lyric",
+  "Mavis",
+  "Nico",
+  "Otis",
+  "Percy",
+  "Querubin",
+  "Rhett",
+  "Scout",
+  "Tatum",
+  "Unity",
+  "Vivian",
+  "Wyatt",
+  "Xan",
+  "Yancy",
+  "Zev",
+  // Pass 10
+  "Atticus",
+  "Barnaby",
+  "Calliope",
+  "Drake",
+  "Eustace",
+  "Foster",
+  "Granger",
+  "Hollis",
+  "Indira",
+  "Jericho",
+  "Kaleb",
+  "Logan",
+  "Magnus",
+  "Noor",
+  "Oakley",
+  "Posy",
+  "Quito",
+  "Rosalind",
+  "Sloane",
+  "Theron",
+  "Upton",
+  "Vance",
+  "Wendell",
+  "Xola",
+  "Yann",
+  "Zora",
+] as const;
+
+if (COORD_NAMES.length !== 260) {
+  throw new Error(`COORD_NAMES table corrupt: expected 260 entries, got ${COORD_NAMES.length}`);
+}
+
+export type NameKind = "session" | "subagent" | "transient";
+
+interface NameHistoryRow {
+  instance_id: string;
+  name: string;
+  kind: NameKind;
+  ts: string;
+}
+
+function atomicWrite(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp.${process.pid}`;
+  writeFileSync(tmp, content, "utf8");
+  renameSync(tmp, path);
+}
+
+function counterPath(coordRoot: string): string {
+  return join(coordRoot, ".harnery", ".name-counter");
+}
+
+function historyPath(coordRoot: string): string {
+  return join(coordRoot, ".harnery", ".name-history");
+}
+
+function readHistory(coordRoot: string): NameHistoryRow[] {
+  const p = historyPath(coordRoot);
+  if (!existsSync(p)) return [];
+  try {
+    return readFileSync(p, "utf8")
+      .split("\n")
+      .filter((line) => line.length > 0)
+      .map((line) => JSON.parse(line) as NameHistoryRow);
+  } catch {
+    return [];
+  }
+}
+
+function appendHistory(coordRoot: string, row: NameHistoryRow): void {
+  const p = historyPath(coordRoot);
+  mkdirSync(dirname(p), { recursive: true });
+  const line = `${JSON.stringify(row)}\n`;
+  // Append is naturally atomic for lines <PIPE_BUF (4096 on Linux).
+  writeFileSync(p, line, { encoding: "utf8", flag: "a" });
+}
+
+/**
+ * Resolve (name, kind) for an existing owner without consuming a counter
+ * slot. Returns null if no history match found.
+ *
+ *   1. Own instance_id → original (name, kind)
+ *   2. session_id (owner != session) → (parent's name, "transient")
+ */
+export function resolveName(
+  coordRoot: string,
+  instanceId: string,
+  sessionId?: string,
+): { name: string; kind: NameKind } | null {
+  const history = readHistory(coordRoot);
+
+  for (const row of history) {
+    if (row.instance_id === instanceId) {
+      return { name: row.name, kind: row.kind };
+    }
+  }
+
+  if (sessionId && sessionId !== instanceId) {
+    for (const row of history) {
+      if (row.instance_id === sessionId) {
+        return { name: row.name, kind: "transient" };
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Assign a name to <instanceId> with the given <kind>. Counter-consuming when
+ * the owner is new. Idempotent: returns existing name on resume.
+ */
+export function assignName(coordRoot: string, instanceId: string, kind: NameKind): string {
+  // Check 1: existing history row → original name.
+  const existing = resolveName(coordRoot, instanceId);
+  if (existing) return existing.name;
+
+  // New owner: consume a counter slot.
+  const cPath = counterPath(coordRoot);
+  let counter = 0;
+  if (existsSync(cPath)) {
+    const raw = readFileSync(cPath, "utf8").trim();
+    if (/^\d+$/.test(raw)) counter = Number.parseInt(raw, 10);
+  }
+  const name = COORD_NAMES[counter % 260]!;
+  atomicWrite(cPath, String(counter + 1));
+  appendHistory(coordRoot, {
+    instance_id: instanceId,
+    name,
+    kind,
+    ts: new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
+  });
+  return name;
+}

package/src/core/agents/state/pidmap.ts

@@ -0,0 +1,38 @@
+/**
+ * Pid-map writer.
+ *
+ * Per-harness pid-map at `.harnery/pid-map/<pid>` containing
+ * `<instance_id>\t<platform>`. `harn agents whoami` walks ppid up 20 hops looking
+ * for a matching entry (preferring the harness, falling back to any platform).
+ *
+ * Atomic temp+rename. Idempotent: re-writing the same row is a no-op.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+function atomicWrite(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp.${process.pid}`;
+  writeFileSync(tmp, content, "utf8");
+  renameSync(tmp, path);
+}
+
+export function writePidmapRow(
+  coordRoot: string,
+  pid: number,
+  instanceId: string,
+  platform: string,
+): void {
+  const path = join(coordRoot, ".harnery", "pid-map", String(pid));
+  const row = `${instanceId}\t${platform}`;
+  // Read-then-write idempotency: skip the rename churn when already current.
+  if (existsSync(path)) {
+    try {
+      if (readFileSync(path, "utf8") === row) return;
+    } catch {
+      /* fall through to write */
+    }
+  }
+  atomicWrite(path, row);
+}

package/src/core/agents/state/scratch.ts

@@ -0,0 +1,121 @@
+/**
+ * Scratchpad mutations: append-only timestamped journal at
+ * `.harnery/scratch/<instance_id>.md`.
+ *
+ * Used by the agents-coord web UI route handlers for both operator-nudge
+ * appends and inline edits.
+ */
+
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+
+const ALLOWED_CATEGORIES = new Set([
+  "note",
+  "plan",
+  "decision",
+  "blocker",
+  "question",
+  "done",
+  "handoff",
+]);
+
+const APPEND_BODY_CAP = 4096;
+
+function nowIsoSeconds(): string {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+function scratchPath(coordRoot: string, instanceId: string): string {
+  return join(coordRoot, ".harnery", "scratch", `${instanceId}.md`);
+}
+
+function archivePath(coordRoot: string, instanceId: string, suffix: string): string {
+  return join(coordRoot, ".harnery", "scratch", "archived", `${instanceId}-${suffix}.md`);
+}
+
+function atomicWriteText(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp.${process.pid}`;
+  writeFileSync(tmp, content, "utf8");
+  renameSync(tmp, path);
+}
+
+/**
+ * Append a timestamped entry to the owner's scratchpad.
+ * Returns true on success, false if validation failed.
+ */
+export function appendScratch(
+  coordRoot: string,
+  instanceId: string,
+  category: string,
+  body: string,
+): { ok: boolean; reason?: string; path?: string } {
+  if (!ALLOWED_CATEGORIES.has(category)) {
+    return { ok: false, reason: `invalid category "${category}"` };
+  }
+  if (!body || body.length === 0) {
+    return { ok: false, reason: "body required" };
+  }
+
+  const trimmedBody =
+    body.length > APPEND_BODY_CAP ? `${body.slice(0, APPEND_BODY_CAP - 3)}...` : body;
+  const target = scratchPath(coordRoot, instanceId);
+  const ts = nowIsoSeconds();
+
+  let prior = "";
+  if (existsSync(target)) {
+    prior = readFileSync(target, "utf8");
+    if (!prior.endsWith("\n")) prior += "\n";
+  }
+  const entry = `## [${ts}] ${category}\n${trimmedBody}\n`;
+  atomicWriteText(target, prior + entry);
+  return { ok: true, path: target };
+}
+
+/**
+ * Replace the scratchpad with new body, archiving prior contents and
+ * appending an "(edited via UI by Ryan)" audit-marker note.
+ */
+export function editScratchpad(
+  coordRoot: string,
+  instanceId: string,
+  newBody: string,
+  summary: string,
+): { ok: boolean; reason?: string; archivePath?: string; path?: string } {
+  if (typeof newBody !== "string") {
+    return { ok: false, reason: "newBody required" };
+  }
+  const target = scratchPath(coordRoot, instanceId);
+  const ts = nowIsoSeconds();
+  const archiveSuffix = `pre-ui-${ts.replace(/:/g, "-")}`;
+  const archive = archivePath(coordRoot, instanceId, archiveSuffix);
+
+  mkdirSync(dirname(archive), { recursive: true });
+
+  let prior = "";
+  if (existsSync(target)) {
+    try {
+      copyFileSync(target, archive);
+    } catch {
+      /* archive optional; continue */
+    }
+    prior = readFileSync(target, "utf8");
+    if (!prior.endsWith("\n")) prior += "\n";
+  }
+
+  const summaryText = summary && summary.length > 0 ? summary : "(no summary)";
+  const auditMarker =
+    `## [${ts}] note (edited via UI by Ryan)\n` +
+    `${summaryText}\n` +
+    `Pre-edit archived at .harnery/scratch/archived/${instanceId}-${archiveSuffix}.md\n\n`;
+
+  atomicWriteText(target, prior + auditMarker + newBody + (newBody.endsWith("\n") ? "" : "\n"));
+  return { ok: true, archivePath: archive, path: target };
+}

package/src/core/agents/state/shell-mutation.ts

@@ -0,0 +1,44 @@
+/**
+ * A heuristic parser that extracts file paths likely to be mutated by a
+ * shell command. Used by
+ * the cursor + codex harness adapters to emit SHELL_CLAIM_CANDIDATE log lines
+ * (warn-only, never blocks).
+ *
+ * Two cases:
+ *   1. Output redirections: `> path` and `>> path`
+ *   2. Common mutators: `sed -i…`, `cp`, `mv`, `touch`: capture the next
+ *      non-space token after the command name (intentionally single-arg even
+ *      though `cp src dest` has two args)
+ *
+ * Caller-supplied `coordRoot` is stripped from absolute paths so the warn
+ * log shows monorepo-relative form.
+ */
+
+export function shellMutationPaths(cmd: string, coordRoot: string | null = null): string[] {
+  if (!cmd) return [];
+  const out: string[] = [];
+
+  // Output redirections: > path / >> path
+  const redirectRe = />>?[ \t]+([^ \t;|&"'`]+)/g;
+  let m: RegExpExecArray | null = redirectRe.exec(cmd);
+  while (m !== null) {
+    out.push(m[1]!);
+    m = redirectRe.exec(cmd);
+  }
+
+  // Common mutators. Capture up to the first whitespace after the command
+  // name and take the final token. For 1-arg commands (touch, sed -i 'expr',
+  // cp WITHOUT a dest) that's the path; for 2-arg commands (`cp src dest`,
+  // `mv src dest`) it's the source, intentionally heuristic-only.
+  const cmdRe = /\b(?:sed -i\S*|cp|mv|touch)[ \t]+([^ \t;|&]+)/g;
+  m = cmdRe.exec(cmd);
+  while (m !== null) {
+    out.push(m[1]!);
+    m = cmdRe.exec(cmd);
+  }
+
+  return out
+    .map((p) => p.replace(/^\.\//, ""))
+    .map((p) => (coordRoot && p.startsWith(`${coordRoot}/`) ? p.slice(coordRoot.length + 1) : p))
+    .filter((p) => p.length > 0);
+}