harnery 0.35.0 → 0.37.0

package/src/core/inbox/service.ts

@@ -0,0 +1,305 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { readCrashSafeJsonlFile, updateCrashSafeJsonlFile } from "../storage/durable-history.ts";
+import {
+  HARNERY_INBOX_RECORD_SCHEMA,
+  HARNERY_INBOX_STATUS_SCHEMA,
+  HarneryInboxCapacityError,
+  type HarneryInboxLimits,
+  type HarneryInboxMessageRecordV1,
+  type HarneryInboxRecordV1,
+  type HarneryInboxStatusV1,
+  type HarneryInboxSurfaceBudget,
+  type HarneryInboxSurfaceResult,
+} from "./contract.ts";
+
+export interface HarneryInboxServiceOptions {
+  coord_root: string;
+  limits: HarneryInboxLimits;
+  now?: () => Date;
+  id?: () => string;
+}
+
+export interface HarneryInboxSendInput {
+  sender_instance_id: string;
+  sender_display_name: string;
+  recipient_instance_id: string;
+  recipient_display_name: string;
+  body: string;
+}
+
+export interface HarneryInboxSendReceipt {
+  state: "queued";
+  message_id: string;
+  body_bytes: number;
+  synced: true;
+}
+
+export class HarneryInboxService {
+  readonly #options: HarneryInboxServiceOptions;
+
+  constructor(options: HarneryInboxServiceOptions) {
+    validateLimits(options.limits);
+    this.#options = options;
+  }
+
+  send(input: HarneryInboxSendInput): HarneryInboxSendReceipt {
+    const recipient = opaqueId(input.recipient_instance_id, "recipient instance");
+    const bodyBytes = Buffer.byteLength(input.body);
+    const limits = this.#options.limits;
+    if (bodyBytes === 0 || bodyBytes > limits.max_message_body_bytes) {
+      throw new HarneryInboxCapacityError(
+        "message_body_limit",
+        bodyBytes,
+        limits.max_message_body_bytes,
+      );
+    }
+    const record: HarneryInboxMessageRecordV1 = {
+      schema: HARNERY_INBOX_RECORD_SCHEMA,
+      kind: "message",
+      message_id: `msg_${this.#options.id?.() ?? randomUUID()}`,
+      sender_instance_id: opaqueId(input.sender_instance_id, "sender instance"),
+      sender_display_name: boundedDisplay(input.sender_display_name),
+      recipient_instance_id: recipient,
+      recipient_display_name: boundedDisplay(input.recipient_display_name),
+      created_at: now(this.#options).toISOString(),
+      body: input.body,
+      body_bytes: bodyBytes,
+    };
+    const path = inboxPath(this.#options.coord_root, recipient);
+    return updateCrashSafeJsonlFile<HarneryInboxRecordV1, HarneryInboxSendReceipt>(
+      path,
+      readOptions(limits),
+      (records) => {
+        const projection = project(records);
+        capacityCheck(projection, record, path, limits);
+        return {
+          append: [record],
+          result: {
+            state: "queued",
+            message_id: record.message_id,
+            body_bytes: bodyBytes,
+            synced: true,
+          },
+        };
+      },
+    );
+  }
+
+  records(recipientInstanceId: string): HarneryInboxRecordV1[] {
+    return readCrashSafeJsonlFile<HarneryInboxRecordV1>(
+      inboxPath(this.#options.coord_root, opaqueId(recipientInstanceId, "recipient instance")),
+      readOptions(this.#options.limits),
+    );
+  }
+
+  pending(recipientInstanceId: string): HarneryInboxMessageRecordV1[] {
+    return project(this.records(recipientInstanceId)).pending;
+  }
+
+  status(recipientInstanceId: string): HarneryInboxStatusV1 {
+    const recipient = opaqueId(recipientInstanceId, "recipient instance");
+    const path = inboxPath(this.#options.coord_root, recipient);
+    const projection = project(this.records(recipient));
+    const pendingBytes = projection.pending.reduce((sum, record) => sum + record.body_bytes, 0);
+    const ratio = Math.max(
+      projection.pending.length / this.#options.limits.max_pending_count,
+      pendingBytes / this.#options.limits.max_pending_bytes,
+    );
+    return {
+      schema: HARNERY_INBOX_STATUS_SCHEMA,
+      recipient_instance_id: recipient,
+      pending_count: projection.pending.length,
+      pending_bytes: pendingBytes,
+      total_history_bytes: existsSync(path) ? statSync(path).size : 0,
+      ...(projection.pending[0] ? { oldest_pending_at: projection.pending[0].created_at } : {}),
+      pressure:
+        ratio >= 1
+          ? "exhausted"
+          : ratio >= this.#options.limits.warning_pressure_ratio
+            ? "warning"
+            : "normal",
+      ...(projection.lastSurfaceAt ? { last_surface_at: projection.lastSurfaceAt } : {}),
+    };
+  }
+
+  async surface(
+    recipientInstanceId: string,
+    emit: (messages: readonly HarneryInboxMessageRecordV1[]) => Promise<void> | void,
+    budget: HarneryInboxSurfaceBudget = {
+      max_count: this.#options.limits.max_surface_count,
+      max_bytes: this.#options.limits.max_surface_bytes,
+      max_tokens: this.#options.limits.max_surface_tokens,
+    },
+  ): Promise<HarneryInboxSurfaceResult> {
+    validateSurfaceBudget(budget);
+    const recipient = opaqueId(recipientInstanceId, "recipient instance");
+    const selected = selectOldestFitting(this.pending(recipient), budget);
+    await emit(selected);
+    if (selected.length > 0) {
+      const surfacedAt = now(this.#options).toISOString();
+      updateCrashSafeJsonlFile<HarneryInboxRecordV1, void>(
+        inboxPath(this.#options.coord_root, recipient),
+        readOptions(this.#options.limits),
+        (records) => {
+          const stillPending = new Set(
+            project(records).pending.map(({ message_id }) => message_id),
+          );
+          return {
+            append: selected
+              .filter(({ message_id }) => stillPending.has(message_id))
+              .map(({ message_id }) => ({
+                schema: HARNERY_INBOX_RECORD_SCHEMA,
+                kind: "surfaced" as const,
+                message_id,
+                surfaced_at: surfacedAt,
+              })),
+            result: undefined,
+          };
+        },
+      );
+    }
+    const remaining = this.pending(recipient);
+    return {
+      emitted: selected,
+      remaining_pending_count: remaining.length,
+      remaining_pending_bytes: remaining.reduce((sum, record) => sum + record.body_bytes, 0),
+      repeated_after_crash_possible: true,
+    };
+  }
+}
+
+export function inboxPath(coordRoot: string, recipientInstanceId: string): string {
+  const id = opaqueId(recipientInstanceId, "recipient instance");
+  return join(resolve(coordRoot), ".harnery", "inbox", `${id}.jsonl`);
+}
+
+export function project(records: readonly HarneryInboxRecordV1[]): {
+  pending: HarneryInboxMessageRecordV1[];
+  surfaced: ReadonlySet<string>;
+  lastSurfaceAt?: string;
+} {
+  const messages = new Map<string, HarneryInboxMessageRecordV1>();
+  const surfaced = new Set<string>();
+  let lastSurfaceAt: string | undefined;
+  for (const record of records) {
+    validateRecord(record);
+    if (record.kind === "message") {
+      if (messages.has(record.message_id))
+        throw new Error(`duplicate inbox message ${record.message_id}`);
+      messages.set(record.message_id, record);
+    } else {
+      if (!messages.has(record.message_id))
+        throw new Error(`surfaced marker precedes ${record.message_id}`);
+      surfaced.add(record.message_id);
+      if (!lastSurfaceAt || record.surfaced_at > lastSurfaceAt) lastSurfaceAt = record.surfaced_at;
+    }
+  }
+  return {
+    pending: [...messages.values()].filter(({ message_id }) => !surfaced.has(message_id)),
+    surfaced,
+    ...(lastSurfaceAt ? { lastSurfaceAt } : {}),
+  };
+}
+
+function selectOldestFitting(
+  pending: readonly HarneryInboxMessageRecordV1[],
+  budget: HarneryInboxSurfaceBudget,
+): HarneryInboxMessageRecordV1[] {
+  const selected: HarneryInboxMessageRecordV1[] = [];
+  let bytes = 0;
+  let tokens = 0;
+  for (const record of pending) {
+    const recordTokens = Math.ceil(record.body_bytes / 4);
+    if (
+      selected.length >= budget.max_count ||
+      bytes + record.body_bytes > budget.max_bytes ||
+      tokens + recordTokens > budget.max_tokens
+    ) {
+      break;
+    }
+    selected.push(record);
+    bytes += record.body_bytes;
+    tokens += recordTokens;
+  }
+  return selected;
+}
+
+function capacityCheck(
+  projection: ReturnType<typeof project>,
+  record: HarneryInboxMessageRecordV1,
+  path: string,
+  limits: HarneryInboxLimits,
+): void {
+  const pendingBytes = projection.pending.reduce((sum, item) => sum + item.body_bytes, 0);
+  if (projection.pending.length + 1 > limits.max_pending_count) {
+    throw new HarneryInboxCapacityError(
+      "pending_count_limit",
+      projection.pending.length,
+      limits.max_pending_count,
+    );
+  }
+  if (pendingBytes + record.body_bytes > limits.max_pending_bytes) {
+    throw new HarneryInboxCapacityError(
+      "pending_bytes_limit",
+      pendingBytes,
+      limits.max_pending_bytes,
+    );
+  }
+  const nextHistoryBytes =
+    (existsSync(path) ? statSync(path).size : 0) + Buffer.byteLength(`${JSON.stringify(record)}\n`);
+  if (nextHistoryBytes > limits.max_history_bytes) {
+    throw new HarneryInboxCapacityError(
+      "history_bytes_limit",
+      nextHistoryBytes,
+      limits.max_history_bytes,
+    );
+  }
+}
+
+function readOptions(limits: HarneryInboxLimits) {
+  return {
+    max_record_bytes: Math.max(limits.max_message_body_bytes * 2, 4_096),
+    max_records: limits.max_history_records,
+  };
+}
+
+function now(options: HarneryInboxServiceOptions): Date {
+  return options.now?.() ?? new Date();
+}
+
+function opaqueId(value: string, field: string): string {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(value)) throw new Error(`invalid ${field} id`);
+  return value;
+}
+
+function boundedDisplay(value: string): string {
+  const result = value.trim();
+  if (result.length === 0 || Buffer.byteLength(result) > 256)
+    throw new Error("invalid display name");
+  return result;
+}
+
+function validateRecord(record: HarneryInboxRecordV1): void {
+  if (record.schema !== HARNERY_INBOX_RECORD_SCHEMA) throw new Error("unknown inbox record schema");
+  if (record.kind === "message" && Buffer.byteLength(record.body) !== record.body_bytes) {
+    throw new Error(`inbox message ${record.message_id} has invalid body_bytes`);
+  }
+}
+
+function validateLimits(limits: HarneryInboxLimits): void {
+  for (const [field, value] of Object.entries(limits)) {
+    if (field === "warning_pressure_ratio") continue;
+    if (!Number.isSafeInteger(value) || value <= 0) throw new Error(`invalid inbox limit ${field}`);
+  }
+  if (limits.warning_pressure_ratio <= 0 || limits.warning_pressure_ratio >= 1) {
+    throw new Error("warning_pressure_ratio must be between zero and one");
+  }
+}
+
+function validateSurfaceBudget(budget: HarneryInboxSurfaceBudget): void {
+  for (const value of Object.values(budget)) {
+    if (!Number.isSafeInteger(value) || value <= 0) throw new Error("invalid inbox surface budget");
+  }
+}

package/src/core/inbox/watcher.ts

@@ -0,0 +1,36 @@
+import type { HarneryInboxMessageRecordV1 } from "./contract.ts";
+import type { HarneryInboxService } from "./service.ts";
+
+export async function* watchInbox(
+  service: HarneryInboxService,
+  recipientInstanceId: string,
+  options: { signal: AbortSignal; poll_ms?: number },
+): AsyncGenerator<HarneryInboxMessageRecordV1> {
+  const seen = new Set<string>();
+  while (!options.signal.aborted) {
+    try {
+      for (const message of service.pending(recipientInstanceId)) {
+        if (seen.has(message.message_id)) continue;
+        seen.add(message.message_id);
+        yield message;
+      }
+    } catch {
+      // A transient missing or incomplete source is retried; no cursor is advanced.
+    }
+    await delay(options.poll_ms ?? 250, options.signal);
+  }
+}
+
+function delay(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true },
+    );
+  });
+}

package/src/core/presence/codec-digest.ts

@@ -131,16 +131,22 @@ export function projectPresenceCodecDigests(
         break;
       case "context.observed": {
         const measurement = event.payload.measurement;
-        if (measurement.state === "observed" && measurement.value.limit_tokens > 0) {
+        if (measurement.state === "observed") {
+          const usedPercent =
+            "used_percent" in measurement.value
+              ? measurement.value.used_percent
+              : measurement.value.limit_tokens > 0
+                ? (measurement.value.used_tokens / measurement.value.limit_tokens) * 100
+                : undefined;
+          if (usedPercent === undefined) break;
           slot.context = {
-            used_percent: Math.min(
-              100,
-              Math.max(
-                0,
-                Math.round((measurement.value.used_tokens / measurement.value.limit_tokens) * 100),
-              ),
-            ),
-            confidence: measurement.confidence === "exact" ? "exact" : "reported",
+            used_percent: Math.min(100, Math.max(0, Math.round(usedPercent))),
+            confidence:
+              measurement.attestation === "inferred"
+                ? "estimated"
+                : measurement.confidence === "exact"
+                  ? "exact"
+                  : "reported",
             event_id: event.event_id,
             observed_at: event.time.observed_at,
           };

package/src/core/presence/relay-client.ts

@@ -24,6 +24,7 @@
 
 import { spawn } from "node:child_process";
 import {
+  closeSync,
   existsSync,
   mkdirSync,
   openSync,
@@ -34,9 +35,12 @@ import {
   writeFileSync,
 } from "node:fs";
 import { join } from "node:path";
+import { coordEnv } from "../../lib/env.ts";
 import { resolveMachineLabel } from "../../lib/machine.ts";
 import { presenceRelayUrl } from "../config.ts";
 import { eventV3ActiveWatchPath } from "../events/v3/reader.ts";
+import { closeProcessLoggers, legacyLogFields, processLogger } from "../storage/logger.ts";
+import { RotatingTextSink } from "../storage/process-log.ts";
 import { buildPresenceBlob, type PresenceBlob } from "./blob.ts";
 import { originUrl, rootCommitSha, sanitizeRefComponent } from "./git.ts";
 import {
@@ -127,13 +131,15 @@ export function ensureRelayDaemon(coordRoot: string): void {
     if (!existsSync(harnBin)) return;
 
     mkdirSync(presenceDir(coordRoot), { recursive: true });
-    const log = openSync(logFilePath(coordRoot), "a");
+    const sharedLogs = coordEnv("SHARED_LOGS") !== "0";
+    const log = sharedLogs ? undefined : openSync(logFilePath(coordRoot), "a");
     const child = spawn(harnBin, ["presence", "relay-daemon"], {
       cwd: coordRoot,
       detached: true,
-      stdio: ["ignore", log, log],
+      stdio: log === undefined ? ["ignore", "ignore", "ignore"] : ["ignore", log, log],
       env: { ...process.env, HARNERY_OUTPUT_SESSION_TEE: "0" },
     });
+    if (log !== undefined) closeSync(log);
     child.unref();
   } catch {
     /* best-effort */
@@ -144,17 +150,32 @@ export function ensureRelayDaemon(coordRoot: string): void {
 export async function runRelayDaemon(coordRoot: string): Promise<number> {
   const url = presenceRelayUrl(coordRoot);
   if (!url) {
-    console.error("relay-daemon: no relay configured (presence.relay)");
+    const message = "relay-daemon: no relay configured (presence.relay)";
+    console.error(message);
+    if (coordEnv("SHARED_LOGS") !== "0") {
+      appendPresenceRelayDiagnostic(coordRoot, "relay.configuration_error", { message });
+    }
+    await closeProcessLoggers();
     return 2;
   }
   if (typeof WebSocket === "undefined") {
-    console.error("relay-daemon: no global WebSocket in this runtime (need Bun or Node >= 21)");
+    const message = "relay-daemon: no global WebSocket in this runtime (need Bun or Node >= 21)";
+    console.error(message);
+    if (coordEnv("SHARED_LOGS") !== "0") {
+      appendPresenceRelayDiagnostic(coordRoot, "relay.runtime_error", { message });
+    }
+    await closeProcessLoggers();
     return 2;
   }
   const sha = rootCommitSha(coordRoot);
   const origin = originUrl(coordRoot);
   if (!sha || !origin) {
-    console.error("relay-daemon: repo has no commits or no origin remote");
+    const message = "relay-daemon: repo has no commits or no origin remote";
+    console.error(message);
+    if (coordEnv("SHARED_LOGS") !== "0") {
+      appendPresenceRelayDiagnostic(coordRoot, "relay.repository_error", { message });
+    }
+    await closeProcessLoggers();
     return 2;
   }
 
@@ -184,6 +205,9 @@ export async function runRelayDaemon(coordRoot: string): Promise<number> {
 
   const log = (msg: string) => {
     console.log(`[${new Date().toISOString()}] ${msg}`);
+    if (coordEnv("SHARED_LOGS") !== "0") {
+      appendPresenceRelayDiagnostic(coordRoot, "relay.lifecycle", { message: msg });
+    }
   };
 
   const publishNow = async (force = false): Promise<void> => {
@@ -286,7 +310,8 @@ export async function runRelayDaemon(coordRoot: string): Promise<number> {
       } catch {
         /* ignore */
       }
-      process.exit(0);
+      void closeProcessLoggers().finally(() => process.exit(0));
+      return;
     }
     // Idle machine (no live sessions for a while) → exit; hooks restart us.
     if (idleSince && Date.now() - idleSince > IDLE_EXIT_MS) {
@@ -299,7 +324,7 @@ export async function runRelayDaemon(coordRoot: string): Promise<number> {
       } catch {
         /* ignore */
       }
-      process.exit(0);
+      void closeProcessLoggers().finally(() => process.exit(0));
     }
   }, KEEPALIVE_MS);
 
@@ -307,6 +332,29 @@ export async function runRelayDaemon(coordRoot: string): Promise<number> {
   return await new Promise<number>(() => {});
 }
 
+export function appendPresenceRelayDiagnostic(
+  coordRoot: string,
+  event: string,
+  fields: Record<string, unknown> = {},
+): "shared" | "legacy" {
+  if (coordEnv("SHARED_LOGS") !== "0") {
+    try {
+      const logger = processLogger(coordRoot, "presence-relay");
+      if (event.includes("error")) logger.error(event, legacyLogFields(fields));
+      else logger.info(event, legacyLogFields(fields));
+      return "shared";
+    } catch {
+      // Bootstrap failures retain a bounded text file for process diagnostics.
+    }
+  }
+  const sink = new RotatingTextSink({ path: logFilePath(coordRoot), max_bytes: 512 * 1_024 });
+  sink.append(
+    `${JSON.stringify({ schema_version: 1, ts: new Date().toISOString(), event, ...fields })}\n`,
+  );
+  sink.close();
+  return "legacy";
+}
+
 /** Daemon status for `presence peers`/doctor surfaces. */
 export function relayDaemonStatus(coordRoot: string): {
   running: boolean;

package/src/core/resources/contract.ts

@@ -0,0 +1,98 @@
+export const RESOURCE_SNAPSHOT_SCHEMA_VERSION = 1;
+export const RESOURCE_SERVICE_STATUS_SCHEMA_VERSION = 1;
+
+export type ResourceSupportState = "supported" | "partial" | "unsupported" | "error";
+
+export interface ResourceProcessSample {
+  pid: number;
+  ppid: number;
+  start_id: string;
+  state: string;
+  name: string;
+  command: string;
+  cpu_percent: number | null;
+  rss_bytes: number;
+  age_seconds: number;
+  owner_kind: "agent" | "service" | "unattributed";
+  owner_id: string | null;
+  owner_root_pid: number | null;
+}
+
+export interface ResourceProcessGroup {
+  kind: ResourceProcessSample["owner_kind"];
+  id: string;
+  process_count: number;
+  cpu_percent: number | null;
+  rss_bytes: number;
+  root_pids: number[];
+}
+
+export interface ResourceMachineSample {
+  cpu_percent: number | null;
+  cpu_logical_count: number;
+  load_average: [number, number, number] | null;
+  memory_total_bytes: number | null;
+  memory_available_bytes: number | null;
+  memory_used_bytes: number | null;
+  memory_percent: number | null;
+  swap_total_bytes: number | null;
+  swap_used_bytes: number | null;
+  process_count: number;
+}
+
+export interface ResourceSnapshot {
+  schema_version: typeof RESOURCE_SNAPSHOT_SCHEMA_VERSION;
+  sampled_at: string;
+  interval_ms: number | null;
+  sample_duration_ms: number;
+  collector_cpu_ms: number;
+  platform: NodeJS.Platform;
+  namespace: "host" | "wsl" | "unknown";
+  support: {
+    state: ResourceSupportState;
+    sampler: "procfs" | "unsupported";
+    reason?: string;
+  };
+  machine: ResourceMachineSample;
+  groups: ResourceProcessGroup[];
+  processes: ResourceProcessSample[];
+  visible_process_count: number;
+  omitted_process_count: number;
+  unattributed_process_count: number;
+}
+
+export interface ResourceServiceStatusRecord {
+  schema_version: typeof RESOURCE_SERVICE_STATUS_SCHEMA_VERSION;
+  pid: number;
+  start_token?: string;
+  host: string;
+  nonce: string;
+  state: "starting" | "running" | "stopping" | "stopped" | "error";
+  started_at: string;
+  heartbeat_at: string;
+  stopped_at?: string;
+  interval_ms: number;
+  sample_count: number;
+  last_sample_at?: string;
+  last_error_code?: string;
+}
+
+export interface ResourceServiceStatus {
+  running: boolean;
+  stale: boolean;
+  record?: ResourceServiceStatusRecord;
+  status_path: string;
+  snapshot_path: string;
+}
+
+export interface ResourceSamplerState {
+  sampled_at_ms: number;
+  cpu_total_ticks: number;
+  cpu_idle_ticks: number;
+  process_ticks: Map<string, number>;
+}
+
+export interface ResourceSampleResult {
+  snapshot: ResourceSnapshot;
+  state?: ResourceSamplerState;
+}

package/src/core/resources/index.ts

@@ -0,0 +1,5 @@
+export * from "./contract.ts";
+export * from "./sampler.ts";
+export * from "./service.ts";
+export * from "./service-status.ts";
+export * from "./storage.ts";