harnery 0.32.0 → 0.34.0

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

@@ -1,38 +1,35 @@
 /**
  * Command/narration event emitter for the coordination layer.
  *
- * `writeSessionEvent` emits command and narration events straight to the
- * **canonical** `.harnery/events.ndjson` (alongside the hook events), which the
- * `/live` web viewer reads.
+ * `writeSessionEvent` records command spans in the canonical V3 ledger.
  */
 
 import { randomBytes } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { resolve } from "node:path";
 // Kept dependency-light: vendored verbatim into a downstream consumer, so no coordEnv import.
-import { normalizeAdapter, resolveEmitRoot } from "./canonical-emit.ts";
-import { emit } from "./events/emit.ts";
+import {
+  LIVE_COMMAND_V3_PRODUCER_ID,
+  liveInstanceIdV3,
+  livePlatformV3,
+  resolveLiveEventLedgerRouteV3,
+} from "../events/v3/live-routing.ts";
+import type { CommandObservationV3, CommandSignalV3 } from "../events/v3/producers/command.ts";
+import { recordCommandSignalV3 } from "../events/v3/producers/command-recorder.ts";
+import { writeProducerDiagnosticV3 } from "../events/v3/producers/intake.ts";
+import { readHookProducerStateByInstanceV3 } from "../events/v3/producers/recorder.ts";
+import { resolveEmitRoot } from "./canonical-emit.ts";
 
 /** Event types accepted by `writeSessionEvent`. */
-export type SessionEventType = "command_start" | "output" | "command_end" | "narration";
+export type SessionEventType = "command.started" | "command.output_observed" | "command.completed";
 
 /**
  * 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 canonicalEventsPath(): string {
-  // Explicit override (tests + non-monorepo invocations).
-  const explicit = process.env.HARNERY_EVENTS_PATH;
-  if (explicit) return explicit;
-  // Superproject-aware root resolution (git first, cwd walk fallback) via
-  // resolveEmitRoot. A plain cwd walk here mis-anchored to a NESTED
-  // `.harnery/` when the shell sat inside a submodule carrying its own
-  // (e.g. an embedded harnery checkout), silently splitting the event
-  // stream. Don't reintroduce CLAUDE.md / .git as anchors, which creates
-  // stray .harnery/ dirs under submodule subtrees.
+export function coordinationRootPath(): string {
   const root = resolveEmitRoot();
-  if (root) return resolve(root, ".harnery", "session-events.ndjson");
-  return resolve(process.env.HOME || "/tmp", ".harnery", "session-events.ndjson");
+  return root ?? resolve(process.env.HOME || "/tmp");
 }
 
 /** Random 8-char hex id for grouping output lines under a single command. */
@@ -50,7 +47,7 @@ export function newCmdId(): string {
  */
 export function readLastIntent(instanceId?: string): string | null {
   if (!instanceId) return null;
-  // Same superproject-aware root resolution as canonicalEventsPath(): the
+  // Same superproject-aware root resolution as coordinationRootPath(): the
   // intent stamp is written by the PreToolUse hook into the SUPERPROJECT's
   // .harnery/, so a nested-`.harnery/` cwd must not redirect the read.
   const root = resolveEmitRoot();
@@ -67,107 +64,143 @@ export function readLastIntent(instanceId?: string): string | null {
   }
 }
 
-const CANONICAL_TYPE: Record<SessionEventType, string> = {
-  command_start: "command.start",
-  output: "command.output",
-  command_end: "command.end",
-  narration: "narration",
-};
-
-interface HeartbeatEnrichment {
-  session_id: string;
-  adapter: "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,
-      adapter: normalizeAdapter(hb.platform),
-      at: now,
-    };
-    enrichCache.set(instanceId, enrichment);
-    return enrichment;
-  } catch {
-    return null;
-  }
-}
-
-/** Project the flat middleware `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 {};
-  }
-}
+const outputSequence = new Map<string, number>();
 
 /** 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. */
-function emitCanonicalCommand(type: SessionEventType, fields: Record<string, unknown>): void {
-  const eventType = CANONICAL_TYPE[type];
-  if (!eventType) return;
+function recordCommandObservation(type: SessionEventType, fields: Record<string, unknown>): void {
   const instanceId = typeof fields.instance_id === "string" ? fields.instance_id : undefined;
   if (!instanceId) return;
   try {
-    // coordRoot = the dir containing `.harnery/`; canonicalEventsPath() anchors it.
-    const coordRoot = dirname(dirname(canonicalEventsPath()));
-    const enrich = enrichFromHeartbeat(coordRoot, instanceId);
-    if (!enrich) return;
-    emit(coordRoot, {
-      event_type: eventType,
-      instance_id: instanceId,
-      session_id: enrich.session_id,
-      adapter: enrich.adapter,
-      data: canonicalData(type, fields),
+    const coordRoot = coordinationRootPath();
+    const route = resolveLiveEventLedgerRouteV3(coordRoot);
+    if (route.state === "blocked") return;
+    const liveInstanceId = liveInstanceIdV3(instanceId);
+    const hook = readHookProducerStateByInstanceV3(coordRoot, liveInstanceId);
+    if (!hook) {
+      writeProducerDiagnosticV3(coordRoot, "command_emit_unjoinable", {
+        type,
+        instance_id: instanceId,
+        reason: "hook_generation_not_found",
+      });
+      return;
+    }
+    const command = commandSignalAndObservation(type, fields);
+    if (!command) return;
+    const result = recordCommandSignalV3({
+      coordRoot,
+      mode: route.mode,
+      signal: command.signal,
+      observation: command.observation,
+      adapter: hook.adapter,
+      instance_id: liveInstanceId,
+      producer_id: LIVE_COMMAND_V3_PRODUCER_ID,
+      build_id: route.build_id,
+      platform: livePlatformV3(),
+      ...(fields.bridge === "codex-wsl" ? { bridge: "codex-wsl" as const } : {}),
+      monotonic_ns: process.hrtime.bigint().toString(),
     });
-  } catch {
-    /* telemetry only, never break the command */
+    if (result.state === "generation_unavailable") {
+      writeProducerDiagnosticV3(coordRoot, "command_emit_unjoinable", {
+        type,
+        instance_id: instanceId,
+        signal: command.signal,
+        reason: result.reason,
+      });
+    } else if (result.state !== "recorded" && result.state !== "already_recorded") {
+      writeProducerDiagnosticV3(coordRoot, "command_emit_rejected", {
+        type,
+        instance_id: instanceId,
+        signal: command.signal,
+        result_state: result.state,
+      });
+    }
+  } catch (error) {
+    // Telemetry must never break the command, but the loss is preserved.
+    try {
+      const coordRoot = coordinationRootPath();
+      writeProducerDiagnosticV3(coordRoot, "command_emit_failed", {
+        type,
+        instance_id: instanceId,
+        error: String(error),
+      });
+    } catch {
+      /* diagnostics are best-effort */
+    }
+  }
+}
+
+function commandSignalAndObservation(
+  type: SessionEventType,
+  fields: Record<string, unknown>,
+): { signal: CommandSignalV3; observation: CommandObservationV3 } | undefined {
+  const commandId = typeof fields.cmd_id === "string" ? fields.cmd_id : undefined;
+  if (!commandId) return undefined;
+  if (type === "command.started") {
+    outputSequence.set(commandId, 0);
+    const command = typeof fields.cmd === "string" ? fields.cmd : "";
+    const executable = command.trim().split(/\s+/, 1)[0] || "unknown";
+    return {
+      signal: "command.started",
+      observation: {
+        native_command_id: commandId,
+        executable,
+        executable_class: "cli",
+        // This module runs inside the command process, so preserve the actual
+        // argument boundaries for the HMAC instead of hashing a clamped line.
+        argv: process.argv.slice(2),
+        intent: typeof fields.intent === "string" ? fields.intent : undefined,
+        intent_kind: typeof fields.intent === "string" ? "declared" : "unknown",
+        sensitive_argument_count: 0,
+      },
+    };
+  }
+  if (type === "command.output_observed") {
+    const sequence = (outputSequence.get(commandId) ?? 0) + 1;
+    outputSequence.set(commandId, sequence);
+    const line = typeof fields.line === "string" ? fields.line : "";
+    const stream =
+      fields.stream === "stdout" || fields.stream === "stderr" ? fields.stream : "combined";
+    return {
+      signal: "command.output_observed",
+      observation: {
+        native_command_id: commandId,
+        native_observation_id: `${commandId}:output:${sequence}`,
+        stream,
+        output: line,
+        output_bytes: Buffer.byteLength(line, "utf8"),
+        output_lines: line ? 1 : 0,
+      },
+    };
   }
+  outputSequence.delete(commandId);
+  const exitCode =
+    typeof fields.exit === "number" && Number.isSafeInteger(fields.exit) ? fields.exit : undefined;
+  return {
+    signal: "command.completed",
+    observation: {
+      native_command_id: commandId,
+      ...(exitCode === undefined ? {} : { exit_code: exitCode }),
+      outcome: exitCode === undefined ? "unknown" : exitCode === 0 ? "succeeded" : "failed",
+      duration_ms:
+        typeof fields.duration_ms === "number" && fields.duration_ms >= 0
+          ? fields.duration_ms
+          : undefined,
+      signal: typeof fields.signal === "string" ? fields.signal : undefined,
+    },
+  };
 }
 
 /**
- * Emit a command or narration event to `.harnery/events.ndjson`. Best-effort,
- * never throws into the caller; telemetry must not break or slow a command.
+ * Record a command event in V3. Best-effort, never throws into the caller;
+ * telemetry must not break or slow a command.
  */
 export function writeSessionEvent(
   type: SessionEventType,
   fields: Record<string, unknown> = {},
 ): void {
-  emitCanonicalCommand(type, fields);
+  recordCommandObservation(type, fields);
 }
 
 /** Trim long values to keep individual events small. */

package/src/core/agents/session-finalization-state-v3.ts

@@ -0,0 +1,90 @@
+import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { ApprovedSessionEndReasonV3 } from "../events/v3/producers/recorder.ts";
+import { EVENT_V3_LEDGER_RELATIVE_ROOT } from "../events/v3/writer.ts";
+
+export const SESSION_FINALIZATION_REQUEST_FORMAT_V3 =
+  "harnery-v3-session-finalization-request" as const;
+export const SESSION_FINALIZATION_REQUEST_VERSION_V3 = 1 as const;
+
+export type SessionFinalizationTriggerV3 =
+  | "explicit_end"
+  | "verified_archive"
+  | "idle_timeout"
+  | "parent_terminal"
+  | "stale_sweep"
+  | "agent_completed"
+  | "run_completed"
+  | "superseded"
+  | "host_disappeared";
+
+export interface SessionFinalizationRequestV3 {
+  format: typeof SESSION_FINALIZATION_REQUEST_FORMAT_V3;
+  format_version: typeof SESSION_FINALIZATION_REQUEST_VERSION_V3;
+  request_id: `sfr_${string}`;
+  instance_id: `inst_${string}`;
+  generation_id: `gen_${string}`;
+  trigger: SessionFinalizationTriggerV3;
+  reason: ApprovedSessionEndReasonV3;
+  outcome:
+    | "succeeded"
+    | "failed"
+    | "cancelled"
+    | "timed_out"
+    | "denied"
+    | "interrupted"
+    | "unknown";
+  observed_at: string;
+  not_before: string;
+  last_event_id: `evt_${string}`;
+  observation_event_id?: `evt_${string}`;
+  requested_turn_id?: `tid_${string}`;
+  allowed_open_span_ids?: `span_${string}`[];
+  coordination_finalized: boolean;
+  status: "pending" | "cancelled" | "completed";
+  cancelled_at?: string;
+  completed_at?: string;
+  terminal_event_id?: `evt_${string}`;
+}
+
+export function sessionFinalizationRequestDirectoryV3(coordRoot: string): string {
+  return join(resolve(coordRoot), EVENT_V3_LEDGER_RELATIVE_ROOT, "finalization", "requests");
+}
+
+export function sessionFinalizationRequestPathV3(coordRoot: string, requestId: string): string {
+  return join(sessionFinalizationRequestDirectoryV3(coordRoot), `${requestId}.json`);
+}
+
+export function listSessionFinalizationRequestsV3(
+  coordRoot: string,
+): SessionFinalizationRequestV3[] {
+  const directory = sessionFinalizationRequestDirectoryV3(coordRoot);
+  if (!existsSync(directory)) return [];
+  const metadata = lstatSync(directory);
+  if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+    throw new Error("V3 session finalization request directory is unsafe");
+  }
+  return readdirSync(directory)
+    .filter((name) => /^sfr_[0-9a-f-]+\.json$/.test(name))
+    .map((name) => readSessionFinalizationRequestV3(join(directory, name)))
+    .sort((left, right) => left.observed_at.localeCompare(right.observed_at));
+}
+
+export function readSessionFinalizationRequestV3(filePath: string): SessionFinalizationRequestV3 {
+  const metadata = lstatSync(filePath);
+  if (!metadata.isFile() || metadata.isSymbolicLink() || (metadata.mode & 0o077) !== 0) {
+    throw new Error("V3 session finalization request is unsafe");
+  }
+  const request = JSON.parse(readFileSync(filePath, "utf8")) as SessionFinalizationRequestV3;
+  if (
+    request.format !== SESSION_FINALIZATION_REQUEST_FORMAT_V3 ||
+    request.format_version !== SESSION_FINALIZATION_REQUEST_VERSION_V3 ||
+    !/^sfr_[0-9a-f-]+$/.test(request.request_id) ||
+    !/^inst_[a-zA-Z0-9._-]+$/.test(request.instance_id) ||
+    !/^gen_[0-9a-f-]+$/.test(request.generation_id) ||
+    !["pending", "cancelled", "completed"].includes(request.status)
+  ) {
+    throw new Error("V3 session finalization request is invalid");
+  }
+  return request;
+}