@gethmy/mcp 3.2.0 → 3.4.0

package/src/run-event-forwarder.ts

@@ -0,0 +1,363 @@
+/**
+ * Draining a session's tool-call spool onto the board (#874).
+ *
+ * The `PostToolUse` hook writes; this reads. The split exists because a hook is
+ * a short-lived process — it cannot hold a buffer between tool calls, and a
+ * per-call HTTP round trip would tax every `Read`. The MCP server is already
+ * long-running and already holds the API client, so the batching lives here.
+ *
+ * ## The retry policy, and why it is not the daemon's
+ *
+ * `cli-agent-runner.ts` buffers in memory, re-queues a failed batch at the
+ * front, and caps the buffer at `MAX_BUFFER`. The shape is the same here but
+ * the mechanism is simpler, because the spool is on disk: a batch is deleted
+ * ONLY after the API accepts it, so "re-queue on failure" is just "do not
+ * delete". Nothing has to be held in memory and nothing is lost if this process
+ * dies mid-flush.
+ *
+ * Two bounds keep that from becoming a leak:
+ *
+ * - **Volume** — the hook trims the spool to `MAX_SPOOL_BATCHES` as it writes,
+ *   which is the disk-side equivalent of `MAX_BUFFER`.
+ * - **Time** — a failing flush backs off geometrically to `MAX_INTERVAL_MS`,
+ *   and a batch that has failed `MAX_BATCH_ATTEMPTS` times is dropped. The
+ *   backoff is what makes that attempt count generous in wall-clock terms
+ *   (~10 minutes, not ~40 seconds), so a brief API outage rides through while
+ *   a batch the server will never accept still stops blocking the queue behind
+ *   it.
+ */
+
+import type { HarmonyApiClient } from "./api-client.js";
+import { readDeclaredRunSession } from "./comment-session.js";
+import {
+  clearRunSession,
+  publishRunSession,
+  readSpoolBatches,
+  removeSpoolBatches,
+  runStateDir,
+  spoolDir,
+} from "./run-state.js";
+
+/** Matches `FLUSH_INTERVAL_MS` in the daemon's `cli-agent-runner.ts`. */
+const FLUSH_INTERVAL_MS = 2_000;
+/** Ceiling for the failure backoff. */
+const MAX_INTERVAL_MS = 60_000;
+/** Server-side cap is 1000 events per request; stay under it with room. */
+const MAX_EVENTS_PER_REQUEST = 500;
+/** Batch files read per tick. */
+const MAX_BATCHES_PER_FLUSH = 200;
+/** After this many failed flushes a batch is assumed poisoned and dropped. */
+const MAX_BATCH_ATTEMPTS = 20;
+/** How often the session pointer's `updatedAt` is refreshed. */
+const POINTER_REFRESH_MS = 60_000;
+
+export interface RunEventForwarderOptions {
+  cardId: string;
+  agentSessionId: string;
+  getClient: () => HarmonyApiClient;
+  stateDir?: string;
+  intervalMs?: number;
+}
+
+export class RunEventForwarder {
+  private readonly cardId: string;
+  private readonly agentSessionId: string;
+  private readonly getClient: () => HarmonyApiClient;
+  private readonly stateDir: string;
+  private readonly baseIntervalMs: number;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private flushing = false;
+  private stopped = false;
+  private consecutiveFailures = 0;
+  private lastPointerRefresh = Date.now();
+  /** batch path → how many times posting it has failed. */
+  private readonly attempts = new Map<string, number>();
+
+  constructor(options: RunEventForwarderOptions) {
+    this.cardId = options.cardId;
+    this.agentSessionId = options.agentSessionId;
+    this.getClient = options.getClient;
+    this.stateDir = options.stateDir ?? runStateDir();
+    this.baseIntervalMs = options.intervalMs ?? FLUSH_INTERVAL_MS;
+  }
+
+  private get dir(): string {
+    return spoolDir(this.stateDir, this.agentSessionId);
+  }
+
+  /** Current delay, geometric in the consecutive-failure count. */
+  private nextDelay(): number {
+    if (this.consecutiveFailures === 0) return this.baseIntervalMs;
+    const scaled =
+      this.baseIntervalMs * 2 ** Math.min(this.consecutiveFailures, 6);
+    return Math.min(scaled, MAX_INTERVAL_MS);
+  }
+
+  start(): void {
+    if (this.timer || this.stopped) return;
+    this.schedule();
+  }
+
+  private schedule(): void {
+    if (this.stopped) return;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      void this.flush().finally(() => this.schedule());
+    }, this.nextDelay());
+    // Telemetry must never be the reason the process stays alive.
+    this.timer.unref?.();
+  }
+
+  /**
+   * Post everything currently spooled.
+   *
+   * Returns the number of events accepted, so a test can assert progress
+   * without reaching into private state.
+   */
+  async flush(): Promise<number> {
+    if (this.flushing) return 0;
+    this.flushing = true;
+    try {
+      this.refreshPointer();
+      const batches = readSpoolBatches(this.dir, MAX_BATCHES_PER_FLUSH);
+      if (batches.length === 0) {
+        this.consecutiveFailures = 0;
+        return 0;
+      }
+
+      // Fill one request up to the server's event cap. Whole batches only: a
+      // batch is one tool call's start/end pair, and splitting it across
+      // requests would put the two halves in separate `seq` runs for no gain.
+      const paths: string[] = [];
+      const events: unknown[] = [];
+      for (const batch of batches) {
+        if (
+          events.length > 0 &&
+          events.length + batch.events.length > MAX_EVENTS_PER_REQUEST
+        ) {
+          break;
+        }
+        paths.push(batch.path);
+        events.push(...batch.events);
+      }
+      if (events.length === 0) return 0;
+
+      try {
+        await this.getClient().appendAgentRunEvents(this.cardId, {
+          sessionId: this.agentSessionId,
+          events: events as Parameters<
+            HarmonyApiClient["appendAgentRunEvents"]
+          >[1]["events"],
+        });
+        removeSpoolBatches(paths);
+        for (const path of paths) this.attempts.delete(path);
+        this.consecutiveFailures = 0;
+        return events.length;
+      } catch {
+        // Left on disk on purpose — that IS the re-queue. Only a batch that has
+        // failed repeatedly is dropped, so one unacceptable payload cannot wedge
+        // every later tool call behind it.
+        this.consecutiveFailures++;
+        const poisoned: string[] = [];
+        for (const path of paths) {
+          const next = (this.attempts.get(path) ?? 0) + 1;
+          this.attempts.set(path, next);
+          if (next >= MAX_BATCH_ATTEMPTS) poisoned.push(path);
+        }
+        if (poisoned.length > 0) {
+          removeSpoolBatches(poisoned);
+          for (const path of poisoned) this.attempts.delete(path);
+        }
+        return 0;
+      }
+    } finally {
+      this.flushing = false;
+    }
+  }
+
+  /**
+   * Keep the on-disk pointer young.
+   *
+   * `readPublishedSessions` ignores a pointer older than `MAX_POINTER_AGE_MS`,
+   * which is what stops a crashed publisher's pid — later reused by an
+   * unrelated process — from routing hooks at a session that ended hours ago.
+   * A live session therefore has to say so periodically.
+   */
+  private refreshPointer(): void {
+    const now = Date.now();
+    if (now - this.lastPointerRefresh < POINTER_REFRESH_MS) return;
+    this.lastPointerRefresh = now;
+    // `stateDir` is threaded explicitly rather than left to default. The
+    // default resolves the same value in production, which is exactly what
+    // makes the omission invisible — it only diverges under the
+    // `HARMONY_RUN_STATE_DIR` override, where a refresh would then re-publish
+    // into a different directory than the one it was published in.
+    publishRunSession(
+      { cardId: this.cardId, agentSessionId: this.agentSessionId },
+      { stateDir: this.stateDir },
+    );
+  }
+
+  /**
+   * Final drain, then remove the pointer and the spool.
+   *
+   * `handoverTo` is the agent session that is TAKING OVER this card in this
+   * process. It matters because the pointer file is named for `(pid, cardId)`,
+   * so a successor on the same card publishes over the same filename before
+   * this teardown runs: unlinking it here would blind every hook to a session
+   * that is very much live. On a handover the pointer therefore stays, and the
+   * spool is dropped only when it belongs to a different session — when the
+   * server hands back the SAME session id, that spool is the one the successor
+   * is already draining.
+   */
+  async stop(handover?: { handoverTo?: string }): Promise<void> {
+    if (this.stopped) return;
+    this.stopped = true;
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    // One last attempt so the tail of a run is not silently dropped. A failure
+    // here is terminal by construction: the spool is removed either way,
+    // because the session it belongs to no longer exists to attach events to.
+    try {
+      await this.flush();
+    } catch {
+      // `flush` already swallows; this guards a getClient() that throws.
+    }
+    const handoverTo = handover?.handoverTo;
+    const keepPointer = handoverTo !== undefined;
+    const keepSpool = handoverTo === this.agentSessionId;
+    clearRunSession(this.cardId, {
+      stateDir: this.stateDir,
+      ...(keepSpool ? {} : { agentSessionId: this.agentSessionId }),
+      ...(keepPointer ? { keepPointer: true } : {}),
+    });
+  }
+}
+
+/** cardId → the forwarder draining that card's session. */
+const forwarders = new Map<string, RunEventForwarder>();
+
+/** Operator kill-switch: no tool-call rows from this machine at all. */
+export const DISABLE_RUN_HOOK_ENV = "HARMONY_DISABLE_RUN_HOOK";
+
+/**
+ * Should publishing be skipped entirely?
+ *
+ * Two reasons, and the second is not decoration.
+ *
+ * 1. **`HARMONY_DISABLE_RUN_HOOK`.** A real operator knob: a team may decide
+ *    that tool inputs and outputs do not belong on their board even redacted,
+ *    and turning the stream off should not mean uninstalling the hook.
+ * 2. **A test run, unless it named its own state directory.** `trackActivity`
+ *    publishes as a side effect of an auto-session, so EVERY test that calls a
+ *    trigger tool would otherwise write a pointer into the developer's real
+ *    `~/.harmony/runs/` and start a polling timer against it. That went
+ *    unnoticed here because the sandbox denies writes outside the worktree —
+ *    it is precisely the class of defect that only appears on a machine without
+ *    one. A test that means to exercise this passes `stateDir` and is unaffected.
+ */
+export function hookTimelineDisabled(
+  env: Record<string, string | undefined>,
+  explicitStateDir?: string,
+): boolean {
+  const off = env[DISABLE_RUN_HOOK_ENV]?.trim().toLowerCase();
+  if (off && off !== "0" && off !== "false") return true;
+  if (env.NODE_ENV === "test" && !explicitStateDir) return true;
+  return false;
+}
+
+/**
+ * Begin forwarding a session's spooled tool calls.
+ *
+ * Idempotent per card: a second `harmony_start_agent_session` on the same card
+ * replaces the forwarder rather than running two against one spool. The
+ * replaced forwarder is stopped as a HANDOVER, so its teardown does not unlink
+ * the pointer — or delete the spool — the caller has already published for the
+ * session taking over. See `RunEventForwarder.stop`.
+ */
+export function startRunEventForwarder(
+  options: RunEventForwarderOptions,
+): RunEventForwarder {
+  const existing = forwarders.get(options.cardId);
+  if (existing) void existing.stop({ handoverTo: options.agentSessionId });
+  const forwarder = new RunEventForwarder(options);
+  forwarders.set(options.cardId, forwarder);
+  forwarder.start();
+  return forwarder;
+}
+
+/** Drain and tear down one card's forwarder. Safe when none is running. */
+export async function stopRunEventForwarder(cardId: string): Promise<void> {
+  const forwarder = forwarders.get(cardId);
+  if (!forwarder) return;
+  forwarders.delete(cardId);
+  await forwarder.stop();
+}
+
+/** Drain and tear down every forwarder — process shutdown. */
+export async function stopAllRunEventForwarders(): Promise<void> {
+  const all = [...forwarders.values()];
+  forwarders.clear();
+  await Promise.all(all.map((f) => f.stop().catch(() => undefined)));
+}
+
+/** Test seam: is a forwarder running for this card? */
+export function hasRunEventForwarder(cardId: string): boolean {
+  return forwarders.has(cardId);
+}
+
+/**
+ * Publish this session on disk and begin draining its hook spool.
+ *
+ * The single entry point the tool handlers call, so the two guards below live
+ * in one place instead of being re-derived at each call site.
+ *
+ * **Guard 1 — a daemon run publishes nothing.** When the daemon declared a run
+ * to this process (`HARMONY_AGENT_CARD_ID` / `HARMONY_AGENT_SESSION_ID`, #1035)
+ * the run already self-reports its full stream from `cli-agent-runner.ts`. A
+ * daemon run cannot load the user settings layer, so the hook never fires for
+ * it and the doubling cannot happen — but publishing a pointer it has no reader
+ * for would leave a live-looking file that a NEIGHBOURING `/hmy` session's hook
+ * could then route to. Not publishing is both the cheaper and the safer answer.
+ *
+ * **Guard 2 — no pointer, no forwarder.** If the pointer cannot be written
+ * (read-only home, full disk) no hook will ever find this session, so a
+ * forwarder would poll an empty directory forever. Failing closed here is what
+ * makes "the hook is a no-op, never an error" true on the publisher's side too.
+ */
+export function beginHookTimeline(args: {
+  cardId: string;
+  agentSessionId: string | undefined;
+  getClient: () => HarmonyApiClient;
+  /** Injected in tests. Defaults to the real environment. */
+  env?: Record<string, string | undefined>;
+  stateDir?: string;
+}): RunEventForwarder | null {
+  if (!args.agentSessionId) return null;
+  const env = args.env ?? process.env;
+  if (readDeclaredRunSession(env)) return null;
+  if (hookTimelineDisabled(env, args.stateDir)) return null;
+
+  const published = publishRunSession(
+    { cardId: args.cardId, agentSessionId: args.agentSessionId },
+    args.stateDir ? { stateDir: args.stateDir } : undefined,
+  );
+  if (!published) return null;
+
+  return startRunEventForwarder({
+    cardId: args.cardId,
+    agentSessionId: args.agentSessionId,
+    getClient: args.getClient,
+    ...(args.stateDir ? { stateDir: args.stateDir } : {}),
+  });
+}
+
+/**
+ * Final drain, then unpublish. Call BEFORE the session row is ended: events
+ * appended to an ended session are refused, so the tail would be lost.
+ */
+export async function endHookTimeline(cardId: string): Promise<void> {
+  await stopRunEventForwarder(cardId);
+}

package/src/run-hook-cli.ts

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * The `PostToolUse` hook binary (#874).
+ *
+ * Installed into the USER settings layer (`~/.claude/settings.json`) by
+ * `harmony-mcp hook install`, never the project layer — see `hook-install.ts`
+ * for why that distinction is load-bearing rather than a preference.
+ *
+ * ## What it does, and what it deliberately does not
+ *
+ * It resolves which published MCP session it belongs to, redacts the tool call,
+ * and writes it to that session's spool directory. Then it exits.
+ *
+ * **It performs no network I/O and reads no credential.** The MCP server drains
+ * the spool and posts the batch (`run-event-forwarder.ts`). That split is the
+ * answer to the card's open "process model" question, and it buys three things
+ * at once:
+ *
+ * - **Batching for free.** The forwarder already lives in a long-running
+ *   process with a timer, so hundreds of tool calls become a request every few
+ *   seconds — the acceptance criterion — without this binary holding any state
+ *   between invocations.
+ * - **No credential on the hot path.** A hook that posted would need the API
+ *   key, on every tool call, in a process spawned by the agent. It does not
+ *   have one, so there is nothing to leak and nothing to fail on.
+ * - **A trivially correct failure mode.** With no session, no state directory,
+ *   or a full disk, the worst case is a file that does not get written.
+ *
+ * ## It exits 0. Always.
+ *
+ * A non-zero exit from a `PostToolUse` hook is surfaced to the agent and can
+ * derail the turn. Nothing this binary is for — improving a timeline — is worth
+ * breaking a tool call over, so every path is wrapped and the exit code is
+ * fixed. The card states it as an acceptance criterion: "the hook is a no-op —
+ * never an error".
+ *
+ * ## This file is a shim, on purpose
+ *
+ * The work is in `run-hook-main.ts`. The invocation below is unconditional —
+ * no `import.meta`/`argv[1]` entry check that a bundler could make wrong — and
+ * this file holds nothing else, so a test can exercise the whole hook by
+ * importing the other module. See that file's doc for the full reasoning.
+ */
+
+import { runPostToolUseHook } from "./run-hook-main.js";
+
+// `import.meta.main` is Bun-only; this binary runs under whatever Node the
+// harness has, so the entry check is a plain invocation instead.
+runPostToolUseHook()
+  .catch(() => {
+    // Swallowed on purpose. See the module doc: a hook may not fail a tool call.
+  })
+  .finally(() => {
+    process.exit(0);
+  });

package/src/run-hook-main.ts

@@ -0,0 +1,159 @@
+/**
+ * The body of the `PostToolUse` hook (#874).
+ *
+ * ## Why this is not in `run-hook-cli.ts`
+ *
+ * `run-hook-cli.ts` is a bin: it calls this and exits, unconditionally, at
+ * module load. A test cannot import that file — importing it runs the hook and
+ * then calls `process.exit(0)` out from under the test runner. Review found the
+ * consequence: the one function that ties resolution, redaction and spooling
+ * together had no end-to-end test, and every test was of a part.
+ *
+ * The usual fix is an `import.meta`-vs-`process.argv[1]` entry check in the bin
+ * itself, and it is the wrong one here. It has to be right about a path through
+ * a bundler, and when it is wrong the failure is silent — a hook that runs and
+ * does nothing, which is indistinguishable from the no-op this thing is
+ * designed to be. Splitting the file leaves the bin's invocation unconditional,
+ * so production behaviour is unchanged by construction.
+ *
+ * See `run-hook-cli.ts` for what the hook is for and why it never posts.
+ */
+
+import { buildHookEvents, type PostToolUsePayload } from "./run-hook.js";
+import {
+  ancestorPids,
+  chooseRunSessionForHook,
+  type PublishedRunSession,
+  readPublishedSessions,
+  readRouteMemo,
+  runStateDir,
+  runStateExists,
+  spoolDir,
+  trimSpool,
+  writeRouteMemo,
+  writeSpoolBatch,
+} from "./run-state.js";
+
+/**
+ * Cap on spooled batches per session, mirroring `MAX_BUFFER` in the daemon's
+ * `cli-agent-runner.ts`. The daemon bounds an in-memory buffer; a spool
+ * outlives the process that filled it, so the same bound has to be enforced on
+ * disk or an offline session would grow without limit.
+ */
+export const MAX_SPOOL_BATCHES = 1_000;
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    // A runaway payload is not worth buffering; the redaction caps would throw
+    // most of it away regardless.
+    if (chunks.reduce((n, c) => n + c.length, 0) > 4_000_000) break;
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}
+
+/**
+ * Seams for the test, each defaulting to what the bin actually does.
+ *
+ * Deliberately narrow: only the three things a test process cannot supply —
+ * a home directory it may write to, stdin, and a process tree it controls.
+ * Everything else runs exactly as it does in the bin.
+ */
+export interface HookRuntime {
+  /** Root of the on-disk run state. Defaults to `runStateDir()`. */
+  stateDir?: string;
+  /** Reads the hook payload. Defaults to draining `process.stdin`. */
+  readInput?: () => Promise<string>;
+  /** The hook process's ancestry. Defaults to `ancestorPids(process.pid)`. */
+  hookAncestorPids?: () => number[];
+}
+
+/**
+ * Resolve, redact, spool. Returns nothing and throws nothing worth catching —
+ * the bin swallows anything that escapes and exits 0 regardless.
+ */
+export async function runPostToolUseHook(
+  runtime: HookRuntime = {},
+): Promise<void> {
+  const stateDir = runtime.stateDir ?? runStateDir();
+  // The overwhelmingly common case: nobody has ever started an MCP session on
+  // this machine, so there is no directory. Leave before touching stdin.
+  if (!runStateExists(stateDir)) return;
+
+  const raw = await (runtime.readInput ?? readStdin)();
+  if (!raw.trim()) return;
+
+  let payload: PostToolUsePayload;
+  try {
+    payload = JSON.parse(raw) as PostToolUsePayload;
+  } catch {
+    return;
+  }
+
+  const candidates = readPublishedSessions({ stateDir });
+  if (candidates.length === 0) return;
+
+  const harnessSessionId =
+    typeof payload.session_id === "string" ? payload.session_id : "";
+
+  const payloadCwd = typeof payload.cwd === "string" ? payload.cwd : undefined;
+
+  // Try the memo first — it skips the ancestry walk, which is the only
+  // expensive thing this binary can do.
+  //
+  // The memo is confirmed against the WHOLE identity it recorded, and the `cwd`
+  // condition is re-applied. A pid on its own does not identify a session: one
+  // MCP process routinely publishes two live pointers (an explicit `/hmy`
+  // session on card A survives the card-switch sweep in `auto-session.ts` while
+  // a trigger tool opens an auto-session on card B), and on the hosted
+  // transport one process serves many. Confirming a pid alone picked whichever
+  // pointer was read first and put card B's tool calls on card A — and it
+  // bypassed the `cwd` filter that `chooseRunSessionForHook` treats as
+  // necessary, so a reused pid could route to an unrelated publisher. Anything
+  // the memo cannot confirm falls through to the full resolution below, which
+  // then rewrites it.
+  let chosen: PublishedRunSession | null = null;
+  if (harnessSessionId) {
+    const memo = readRouteMemo(stateDir, harnessSessionId);
+    if (memo !== null) {
+      chosen =
+        candidates.find(
+          (c) =>
+            c.publisherPid === memo.publisherPid &&
+            c.cardId === memo.cardId &&
+            c.agentSessionId === memo.agentSessionId &&
+            (payloadCwd === undefined || c.cwd === payloadCwd),
+        ) ?? null;
+    }
+  }
+
+  if (!chosen) {
+    chosen = chooseRunSessionForHook({
+      candidates,
+      hookAncestorPids: (
+        runtime.hookAncestorPids ?? (() => ancestorPids(process.pid))
+      )(),
+      cwd: payloadCwd,
+    });
+    if (chosen && harnessSessionId) {
+      writeRouteMemo(stateDir, harnessSessionId, {
+        publisherPid: chosen.publisherPid,
+        cardId: chosen.cardId,
+        agentSessionId: chosen.agentSessionId,
+      });
+    }
+  }
+
+  // Genuine ambiguity between two concurrent sessions resolves to "no row".
+  // Attributing one session's work to another session's card would be worse
+  // than the gap this card exists to close.
+  if (!chosen) return;
+
+  const events = buildHookEvents(payload);
+  if (events.length === 0) return;
+
+  const dir = spoolDir(stateDir, chosen.agentSessionId);
+  trimSpool(dir, MAX_SPOOL_BATCHES);
+  writeSpoolBatch(dir, events);
+}