harnery 0.0.1 → 0.2.0

package/src/core/agents/session-events.ts

@@ -0,0 +1,228 @@
+/**
+ * Command/narration event emitter for the coordination layer.
+ *
+ * `writeSessionEvent` emits command + narration events straight to the
+ * **canonical** `.harnery/events.ndjson` (alongside the hook events), which the
+ * `/live` web viewer reads. The exported surface (`writeSessionEvent`,
+ * `newCmdId`, `clampField`, `readLastIntent`) is stable so the session-tee
+ * middleware callers need no edits.
+ */
+
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+// Kept dependency-light: vendored verbatim into a downstream consumer, so no coordEnv import.
+import { normalizeHarness } from "./canonical-emit.ts";
+import { emit } from "./events/emit.ts";
+
+/** Event types accepted by `writeSessionEvent`. Only the command stream +
+ * narration are emitted canonically; the coord/state types are accepted for
+ * call-site compatibility but are no-ops (the agents CLI emits those itself). */
+export type SessionEventType =
+  | "command_start"
+  | "output"
+  | "command_end"
+  | "end_of_turn"
+  | "hook_event"
+  | "set_task"
+  | "file_claim"
+  | "file_release"
+  | "peer_change"
+  | "narration";
+
+/**
+ * Resolved path of the ndjson sidecar file. Lives inside `.harnery/` so a
+ * containerized reader can pick it up through a single bind mount.
+ */
+export function sessionEventsPath(): string {
+  // Explicit override (tests + non-monorepo invocations).
+  const explicit = process.env.HARNERY_OUTPUT_SESSION_EVENTS;
+  if (explicit) return explicit;
+  // Walk up looking for an EXISTING .harnery/ directory; only match dirs
+  // (submodule .git is a file/gitlink, and CLAUDE.md / AGENTS.md can
+  // proliferate per-subdirectory in many monorepos, so neither is a safe
+  // anchor). Don't reintroduce CLAUDE.md / .git as anchors, which creates
+  // stray .harnery/ dirs under submodule subtrees.
+  let dir = process.cwd();
+  for (let i = 0; i < 10; i++) {
+    const candidate = resolve(dir, ".harnery");
+    try {
+      if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+        return resolve(candidate, "session-events.ndjson");
+      }
+    } catch {
+      /* keep walking */
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return resolve(process.env.HOME || "/tmp", ".harnery", "session-events.ndjson");
+}
+
+/** Random 8-char hex id for grouping output lines under a single command. */
+export function newCmdId(): string {
+  return randomBytes(4).toString("hex");
+}
+
+/**
+ * Read the model's most recent `<intent>...</intent>` declaration from the
+ * intent-stamp file written by the PreToolUse hook. Returns null when the
+ * file is missing, empty, or contains the explicit `(no intent)` sentinel.
+ * Callers fall back to whatever default they want in that case.
+ *
+ * Path: `.harnery/.last-intent.<instance_id>` next to the agent's heartbeat.
+ */
+export function readLastIntent(instanceId?: string): string | null {
+  if (!instanceId) return null;
+  // Walk up from cwd looking for .harnery/, same resolution as
+  // sessionEventsPath() (only match existing directories).
+  let dir = process.cwd();
+  let agentsDir: string | null = null;
+  for (let i = 0; i < 10; i++) {
+    const candidate = resolve(dir, ".harnery");
+    try {
+      if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+        agentsDir = candidate;
+        break;
+      }
+    } catch {
+      /* keep walking */
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  if (!agentsDir) return null;
+  const intentPath = resolve(agentsDir, `.last-intent.${instanceId}`);
+  if (!existsSync(intentPath)) return null;
+  try {
+    const raw = readFileSync(intentPath, "utf8").trim();
+    if (!raw || raw === "(no intent)") return null;
+    return raw;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Dual-write: mirror command/narration session-events
+ * into the canonical `.harnery/events.ndjson` stream so the legacy
+ * session-events.ndjson writer + its web consumers can be retired.
+ * Only the command-stream + narration types migrate; the coord/state types
+ * (`set_task`, `file_claim`, `peer_change`, …) are already emitted canonically
+ * by the agents CLI, so re-emitting them here would double-count.
+ */
+const CANONICAL_TYPE: Partial<Record<SessionEventType, string>> = {
+  command_start: "command.start",
+  output: "command.output",
+  command_end: "command.end",
+  narration: "narration",
+};
+
+interface HeartbeatEnrichment {
+  session_id: string;
+  harness: "claude-code" | "cursor" | "codex";
+  at: number;
+}
+/** Cache heartbeat-derived envelope fields per instance_id so a burst of
+ * `output` lines (one event per stdout line) doesn't re-read + re-parse the
+ * heartbeat JSON each time. Short TTL: picks up platform/session changes
+ * within a few seconds without hammering the disk on a chatty command. */
+const enrichCache = new Map<string, HeartbeatEnrichment>();
+const ENRICH_TTL_MS = 5000;
+
+function enrichFromHeartbeat(coordRoot: string, instanceId: string): HeartbeatEnrichment | null {
+  const now = Date.now();
+  const cached = enrichCache.get(instanceId);
+  if (cached && now - cached.at < ENRICH_TTL_MS) return cached;
+  try {
+    const hbPath = resolve(coordRoot, ".harnery", "active", `${instanceId}.json`);
+    if (!existsSync(hbPath)) return null;
+    const hb = JSON.parse(readFileSync(hbPath, "utf8")) as {
+      session_id?: string;
+      platform?: string;
+    };
+    const enrichment: HeartbeatEnrichment = {
+      session_id: hb.session_id || instanceId,
+      harness: normalizeHarness(hb.platform),
+      at: now,
+    };
+    enrichCache.set(instanceId, enrichment);
+    return enrichment;
+  } catch {
+    return null;
+  }
+}
+
+/** Project the flat legacy `fields` into the canonical event's `data` shape.
+ * Unknown types never reach here, guarded by CANONICAL_TYPE. */
+function canonicalData(
+  type: SessionEventType,
+  fields: Record<string, unknown>,
+): Record<string, unknown> {
+  switch (type) {
+    case "command_start":
+      return { cmd_id: fields.cmd_id, intent: fields.intent, cmd: fields.cmd };
+    case "output":
+      return { cmd_id: fields.cmd_id, stream: fields.stream, line: fields.line };
+    case "command_end":
+      return {
+        cmd_id: fields.cmd_id,
+        exit: fields.exit,
+        duration_ms: fields.duration_ms,
+        ...(fields.signal ? { signal: fields.signal } : {}),
+      };
+    case "narration":
+      return { message: fields.message };
+    default:
+      return {};
+  }
+}
+
+/** Emit a command/narration event to the canonical stream. Swallows every
+ * error and skips when identity can't be resolved: telemetry must never break
+ * (or slow down) a command. Non-command types return early. */
+function emitCanonicalCommand(type: SessionEventType, fields: Record<string, unknown>): void {
+  const eventType = CANONICAL_TYPE[type];
+  if (!eventType) return;
+  const instanceId = typeof fields.instance_id === "string" ? fields.instance_id : undefined;
+  if (!instanceId) return;
+  try {
+    // coordRoot = the dir containing `.harnery/`; sessionEventsPath() anchors it.
+    const coordRoot = dirname(dirname(sessionEventsPath()));
+    const enrich = enrichFromHeartbeat(coordRoot, instanceId);
+    if (!enrich) return;
+    emit(coordRoot, {
+      event_type: eventType,
+      instance_id: instanceId,
+      session_id: enrich.session_id,
+      harness: enrich.harness,
+      data: canonicalData(type, fields),
+    });
+  } catch {
+    /* telemetry only, never break the command */
+  }
+}
+
+/**
+ * Emit a session event. Command + narration events
+ * are written to the canonical `.harnery/events.ndjson`; the coord/state types
+ * are accepted for call-site compatibility but are no-ops here (the agents CLI
+ * emits those itself). Best-effort, never throws into the caller; a command
+ * must never break or slow on telemetry. The `agentName` arg is retained for
+ * the stable call signature (canonical events key on instance_id, not name).
+ */
+export function writeSessionEvent(
+  type: SessionEventType,
+  _agentName: string,
+  fields: Record<string, unknown> = {},
+): void {
+  emitCanonicalCommand(type, fields);
+}
+
+/** Trim long values to keep individual events small. */
+export function clampField(v: string, max = 1024): string {
+  if (v.length <= max) return v;
+  return `${v.slice(0, max - 1)}…`;
+}

package/src/core/agents/state/activity-log.ts

@@ -0,0 +1,33 @@
+/**
+ * Display-name resolution for the coord layer.
+ *
+ * This module once housed `coordLog`, the writer for a human-readable
+ * activity log. That log has been retired; the canonical
+ * `.harnery/events.ndjson` stream is the single source of truth, and the
+ * per-event telemetry that had consumers (heals → health.*, councils →
+ * council.*, shell-mutation candidates → decision.warn) is emitted there
+ * directly. `coordLog` and its call sites are gone; only `resolveShortName`
+ * remains (still used for display-name resolution).
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Resolve `agent-<name>` display string. Looks up the heartbeat's `name`
+ * field; falls back to `agent-<8-char-hex>` if name is empty (mirrors bash
+ * coord_owner_short). Returns `agent-unknown` when instanceId is null.
+ */
+export function resolveShortName(coordRoot: string, instanceId: string | null): string {
+  if (!instanceId) return "agent-unknown";
+  const path = join(coordRoot, ".harnery", "active", `${instanceId}.json`);
+  if (existsSync(path)) {
+    try {
+      const hb = JSON.parse(readFileSync(path, "utf8")) as { name?: string };
+      if (hb.name && hb.name.length > 0) return `agent-${hb.name}`;
+    } catch {
+      /* fall through to short-id */
+    }
+  }
+  return `agent-${instanceId.slice(0, 8)}`;
+}

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

@@ -0,0 +1,265 @@
+/**
+ * Council manifest mutations: lifecycle helpers for the council-* actions.
+ *
+ * A council is a multi-round debate among agents recorded at
+ * `.harnery/councils/<id>.json` (manifest) plus `.harnery/councils/<id>/round-N/<member>.md`
+ * (contributions). Archive moves both into `.harnery/councils/archive/`.
+ *
+ * This module owns: lifecycle (advance, close, archive, unarchive, delete)
+ * and steward reassignment. Council CREATION + contribution writes stay
+ * separate (operator-side, harness-agnostic).
+ */
+
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+
+interface CouncilManifest {
+  council_id: string;
+  status: "active" | "closed" | "archived";
+  current_round: number;
+  round_status: "open" | "closed";
+  members: string[];
+  /** schema_version 2: index-parallel to members; contributions are written as <member_id>.md. */
+  member_ids?: string[];
+  steward?: string;
+  steward_id?: string;
+  closed_at?: string;
+  archived_at?: string;
+  [extra: string]: unknown;
+}
+
+function nowIsoSeconds(): string {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+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);
+}
+
+function councilsDir(coordRoot: string): string {
+  return join(coordRoot, ".harnery", "councils");
+}
+
+function archiveDir(coordRoot: string): string {
+  return join(councilsDir(coordRoot), "archive");
+}
+
+function readManifest(path: string): CouncilManifest | null {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as CouncilManifest;
+  } catch {
+    return null;
+  }
+}
+
+export function advanceCouncil(
+  coordRoot: string,
+  councilId: string,
+  opts: { force?: boolean } = {},
+): { ok: boolean; reason?: string; pendingMember?: string } {
+  const manifestPath = join(councilsDir(coordRoot), `${councilId}.json`);
+  const manifest = readManifest(manifestPath);
+  if (!manifest) return { ok: false, reason: `no manifest at ${manifestPath}` };
+  if (manifest.status !== "active") {
+    return { ok: false, reason: `council is ${manifest.status}, not active` };
+  }
+  const cur = manifest.current_round;
+
+  if (!opts.force) {
+    const roundDir = join(councilsDir(coordRoot), councilId, `round-${cur}`);
+    const memberIds = Array.isArray(manifest.member_ids) ? manifest.member_ids : [];
+    for (const [i, member] of manifest.members.entries()) {
+      // Contribution filename drifted across schema versions: v1 wrote
+      // <agent-Name>.md, v2 (member_ids in the manifest) writes <uuid>.md.
+      // Accept either so lifecycle works on both generations of council.
+      const candidates = [join(roundDir, `${member}.md`)];
+      if (memberIds[i]) candidates.push(join(roundDir, `${memberIds[i]}.md`));
+      if (!candidates.some((p) => existsSync(p))) {
+        return {
+          ok: false,
+          reason: `pending members in round ${cur} (incl. ${member}); pass --force to skip`,
+          pendingMember: member,
+        };
+      }
+    }
+  }
+
+  const next = cur + 1;
+  const nextDir = join(councilsDir(coordRoot), councilId, `round-${next}`);
+  mkdirSync(nextDir, { recursive: true });
+
+  const updated: CouncilManifest = {
+    ...manifest,
+    current_round: next,
+    round_status: "open",
+  };
+  atomicWriteText(manifestPath, JSON.stringify(updated, null, 2));
+  return { ok: true };
+}
+
+export function closeCouncil(
+  coordRoot: string,
+  councilId: string,
+): { ok: boolean; reason?: string } {
+  const manifestPath = join(councilsDir(coordRoot), `${councilId}.json`);
+  const manifest = readManifest(manifestPath);
+  if (!manifest) return { ok: false, reason: `no manifest at ${manifestPath}` };
+  if (manifest.status === "archived") return { ok: false, reason: "council is already archived" };
+
+  const updated: CouncilManifest = {
+    ...manifest,
+    status: "closed",
+    closed_at: nowIsoSeconds(),
+  };
+  atomicWriteText(manifestPath, JSON.stringify(updated, null, 2));
+  return { ok: true };
+}
+
+export function archiveCouncil(
+  coordRoot: string,
+  councilId: string,
+): { ok: boolean; reason?: string } {
+  const manifestPath = join(councilsDir(coordRoot), `${councilId}.json`);
+  const manifest = readManifest(manifestPath);
+  if (!manifest) return { ok: false, reason: `no manifest at ${manifestPath}` };
+
+  const archived: CouncilManifest = {
+    ...manifest,
+    status: "archived",
+    archived_at: nowIsoSeconds(),
+  };
+  const archivedManifest = join(archiveDir(coordRoot), `${councilId}.json`);
+  const archivedBody = join(archiveDir(coordRoot), councilId);
+  const activeBody = join(councilsDir(coordRoot), councilId);
+
+  mkdirSync(archiveDir(coordRoot), { recursive: true });
+  atomicWriteText(manifestPath, JSON.stringify(archived, null, 2));
+
+  try {
+    renameSync(manifestPath, archivedManifest);
+  } catch {
+    /* idempotent; manifest may already be in archive */
+  }
+  if (existsSync(activeBody)) {
+    if (existsSync(archivedBody)) {
+      rmSync(activeBody, { recursive: true, force: true });
+    } else {
+      try {
+        renameSync(activeBody, archivedBody);
+      } catch {
+        // cross-device or permissions: fall back to copy + remove.
+        cpSync(activeBody, archivedBody, { recursive: true });
+        rmSync(activeBody, { recursive: true, force: true });
+      }
+    }
+  }
+  return { ok: true };
+}
+
+export function unarchiveCouncil(
+  coordRoot: string,
+  councilId: string,
+): { ok: boolean; reason?: string } {
+  const archivedManifest = join(archiveDir(coordRoot), `${councilId}.json`);
+  const activeManifest = join(councilsDir(coordRoot), `${councilId}.json`);
+  if (!existsSync(archivedManifest)) {
+    return { ok: false, reason: `no archived manifest at ${archivedManifest}` };
+  }
+  if (existsSync(activeManifest)) {
+    return { ok: false, reason: "active manifest already exists; refusing to clobber" };
+  }
+  const manifest = readManifest(archivedManifest);
+  if (!manifest) return { ok: false, reason: `couldn't parse ${archivedManifest}` };
+
+  const restored: CouncilManifest = { ...manifest };
+  restored.archived_at = undefined;
+  restored.status = manifest.closed_at ? "closed" : "active";
+  atomicWriteText(archivedManifest, JSON.stringify(restored, null, 2));
+
+  try {
+    renameSync(archivedManifest, activeManifest);
+  } catch {
+    /* ignore; idempotent */
+  }
+  const archivedBody = join(archiveDir(coordRoot), councilId);
+  const activeBody = join(councilsDir(coordRoot), councilId);
+  if (existsSync(archivedBody)) {
+    if (existsSync(activeBody)) {
+      rmSync(archivedBody, { recursive: true, force: true });
+    } else {
+      try {
+        renameSync(archivedBody, activeBody);
+      } catch {
+        cpSync(archivedBody, activeBody, { recursive: true });
+        rmSync(archivedBody, { recursive: true, force: true });
+      }
+    }
+  }
+  return { ok: true };
+}
+
+export function deleteCouncil(
+  coordRoot: string,
+  councilId: string,
+): { ok: boolean; reason?: string } {
+  const archivedManifest = join(archiveDir(coordRoot), `${councilId}.json`);
+  const activeManifest = join(councilsDir(coordRoot), `${councilId}.json`);
+  if (existsSync(activeManifest)) {
+    return {
+      ok: false,
+      reason: `council ${councilId} is not archived; archive first`,
+    };
+  }
+  if (!existsSync(archivedManifest)) {
+    return { ok: false, reason: `no archived manifest at ${archivedManifest}` };
+  }
+  const archivedBody = join(archiveDir(coordRoot), councilId);
+
+  rmSync(archivedManifest, { force: true });
+  if (existsSync(archivedBody)) {
+    rmSync(archivedBody, { recursive: true, force: true });
+  }
+  return { ok: true };
+}
+
+export function setCouncilSteward(
+  coordRoot: string,
+  councilId: string,
+  newSteward: string,
+  newStewardId: string,
+): { ok: boolean; reason?: string } {
+  const manifestPath = join(councilsDir(coordRoot), `${councilId}.json`);
+  const manifest = readManifest(manifestPath);
+  if (!manifest) return { ok: false, reason: `no manifest at ${manifestPath}` };
+  if (manifest.status === "archived") {
+    return { ok: false, reason: "council is archived (read-only)" };
+  }
+  if (newSteward && !/^agent-[A-Za-z][A-Za-z0-9_-]*$/.test(newSteward)) {
+    return {
+      ok: false,
+      reason: `invalid steward "${newSteward}" (must match agent-[A-Za-z][A-Za-z0-9_-]*)`,
+    };
+  }
+  const updated: CouncilManifest = { ...manifest };
+  if (!newSteward) {
+    updated.steward = undefined;
+    updated.steward_id = undefined;
+  } else {
+    updated.steward = newSteward;
+    if (newStewardId) updated.steward_id = newStewardId;
+  }
+  atomicWriteText(manifestPath, JSON.stringify(updated, null, 2));
+  return { ok: true };
+}