harnery 0.36.0 → 0.37.0

package/src/core/supervisor/activity.ts

@@ -0,0 +1,193 @@
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import {
+  SUPERVISOR_ACTIVITY_SCHEMA_VERSION,
+  SUPERVISOR_DIAGNOSTIC_LIMITS,
+  SUPERVISOR_FINDING_POLICY,
+  type SupervisorActivitySnapshot,
+  type SupervisorDeclaredActivity,
+  type SupervisorSourceReference,
+} from "./contract.ts";
+
+interface ActivityCache {
+  schema_version?: number;
+  instance_id?: string;
+  session_id?: string;
+  activity?: string;
+  task_state?: string;
+  last_heartbeat?: string;
+  v3_instance_id?: string;
+  v3_generation_id?: string;
+}
+
+interface CandidateFile {
+  name: string;
+  path: string;
+  bytes: number;
+  mtimeMs: number;
+}
+
+/** Read a bounded, generation-bound activity projection without loading Event Ledger V3. */
+export function collectSupervisorActivitySnapshot(
+  coordRoot: string,
+  now = new Date(),
+): SupervisorActivitySnapshot {
+  const observedAt = now.toISOString();
+  const directory = join(resolve(coordRoot), ".harnery", "active");
+  if (!existsSync(directory)) return unavailable(observedAt, "activity-projection-missing");
+
+  const candidates: CandidateFile[] = [];
+  let rejected = 0;
+  try {
+    for (const entry of readdirSync(directory)) {
+      if (!/^[A-Za-z0-9_-]{1,128}\.json$/.test(entry)) {
+        rejected += 1;
+        continue;
+      }
+      const path = join(directory, entry);
+      const stat = lstatSync(path);
+      if (
+        stat.isSymbolicLink() ||
+        !stat.isFile() ||
+        stat.size < 2 ||
+        stat.size > SUPERVISOR_FINDING_POLICY.max_activity_file_bytes
+      ) {
+        rejected += 1;
+        continue;
+      }
+      candidates.push({ name: entry.slice(0, -5), path, bytes: stat.size, mtimeMs: stat.mtimeMs });
+    }
+  } catch {
+    return unavailable(observedAt, "activity-projection-read-failed", "error");
+  }
+
+  candidates.sort(
+    (left, right) => right.mtimeMs - left.mtimeMs || left.name.localeCompare(right.name),
+  );
+  const entries: SupervisorDeclaredActivity[] = [];
+  let totalBytes = 0;
+  let stale = 0;
+  for (const candidate of candidates) {
+    if (
+      entries.length >= SUPERVISOR_DIAGNOSTIC_LIMITS.max_activity_entries ||
+      totalBytes + candidate.bytes > SUPERVISOR_FINDING_POLICY.max_activity_total_bytes
+    ) {
+      rejected += 1;
+      continue;
+    }
+    totalBytes += candidate.bytes;
+    let cache: ActivityCache;
+    try {
+      cache = JSON.parse(readFileSync(candidate.path, "utf8")) as ActivityCache;
+    } catch {
+      rejected += 1;
+      continue;
+    }
+    if (!validCache(cache, candidate.name)) {
+      rejected += 1;
+      continue;
+    }
+    const age = now.getTime() - Date.parse(cache.last_heartbeat!);
+    if (
+      !Number.isFinite(age) ||
+      age < -30_000 ||
+      age > SUPERVISOR_FINDING_POLICY.activity_freshness_ms
+    ) {
+      stale += 1;
+      continue;
+    }
+    entries.push(activityEntry(cache as Required<ActivityCache>));
+  }
+
+  const state = rejected > 0 ? "partial" : "supported";
+  return {
+    schema_version: SUPERVISOR_ACTIVITY_SCHEMA_VERSION,
+    observed_at: observedAt,
+    max_entries: SUPERVISOR_DIAGNOSTIC_LIMITS.max_activity_entries,
+    entries: entries.sort((left, right) => left.scope_id.localeCompare(right.scope_id)),
+    omitted_entry_count: rejected + stale,
+    capability: {
+      source_kind: "coordination.activity-projection",
+      state,
+      ...(state === "partial" ? { reason_code: "bounded-cache-rejection" } : {}),
+      ...(rejected + stale > 0
+        ? { detail: `${rejected} invalid or over-budget and ${stale} stale activity rows omitted.` }
+        : {}),
+    },
+  };
+}
+
+function validCache(cache: ActivityCache, fileId: string): boolean {
+  return (
+    cache.schema_version === 2 &&
+    cache.instance_id === fileId &&
+    typeof cache.session_id === "string" &&
+    cache.session_id.length > 0 &&
+    isActivity(cache.activity) &&
+    isTaskState(cache.task_state) &&
+    typeof cache.last_heartbeat === "string" &&
+    typeof cache.v3_instance_id === "string" &&
+    cache.v3_instance_id.startsWith("inst_") &&
+    typeof cache.v3_generation_id === "string" &&
+    cache.v3_generation_id.startsWith("gen_")
+  );
+}
+
+function activityEntry(cache: Required<ActivityCache>): SupervisorDeclaredActivity {
+  const source = activitySource(cache);
+  return {
+    scope_kind: "agent",
+    scope_id: cache.instance_id,
+    session_id: cache.session_id,
+    declared_activity: cache.activity as SupervisorDeclaredActivity["declared_activity"],
+    task_state: cache.task_state as SupervisorDeclaredActivity["task_state"],
+    observed_at: cache.last_heartbeat,
+    source,
+  };
+}
+
+function activitySource(cache: Required<ActivityCache>): SupervisorSourceReference {
+  const sourceId = `${cache.v3_instance_id}:${cache.v3_generation_id}`;
+  return {
+    id: `src_${digest(`coordination.activity-projection\u0000${sourceId}\u0000${cache.last_heartbeat}`).slice(0, 24)}`,
+    source_kind: "coordination.activity-projection",
+    source_id: sourceId,
+    observed_at: cache.last_heartbeat,
+    schema_version: SUPERVISOR_ACTIVITY_SCHEMA_VERSION,
+    capability: "supported",
+  };
+}
+
+function unavailable(
+  observedAt: string,
+  reasonCode: string,
+  state: "unsupported" | "error" = "unsupported",
+): SupervisorActivitySnapshot {
+  return {
+    schema_version: SUPERVISOR_ACTIVITY_SCHEMA_VERSION,
+    observed_at: observedAt,
+    max_entries: SUPERVISOR_DIAGNOSTIC_LIMITS.max_activity_entries,
+    entries: [],
+    omitted_entry_count: 0,
+    capability: {
+      source_kind: "coordination.activity-projection",
+      state,
+      reason_code: reasonCode,
+    },
+  };
+}
+
+function isActivity(
+  value: string | undefined,
+): value is SupervisorDeclaredActivity["declared_activity"] {
+  return value === "working" || value === "needs_input" || value === "idle" || value === "unknown";
+}
+
+function isTaskState(value: string | undefined): value is SupervisorDeclaredActivity["task_state"] {
+  return value === "active" || value === "blocked" || value === "done";
+}
+
+function digest(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}

package/src/core/supervisor/contract.ts

@@ -0,0 +1,312 @@
+import type { ResourceProcessGroup } from "../resources/contract.ts";
+import type { HarneryLogRecordV1 } from "../storage/jsonl.ts";
+
+export const SUPERVISOR_STATUS_SCHEMA_VERSION = 1 as const;
+export const SUPERVISOR_SNAPSHOT_SCHEMA_VERSION = 2 as const;
+export const SUPERVISOR_HISTORY_SCHEMA_VERSION = 1 as const;
+export const SUPERVISOR_FINDING_SCHEMA_VERSION = 2 as const;
+export const SUPERVISOR_ACTIVITY_SCHEMA_VERSION = 1 as const;
+export const SUPERVISOR_TIMELINE_SCHEMA_VERSION = 2 as const;
+export const SUPERVISOR_EXPLANATION_SCHEMA_VERSION = 1 as const;
+export const SUPERVISOR_LOG_FEED_SCHEMA_VERSION = 1 as const;
+export const SUPERVISOR_CONSUMER_SCHEMA_VERSION = 1 as const;
+
+export const SUPERVISOR_DIAGNOSTIC_LIMITS = {
+  max_findings: 100,
+  max_active_findings: 32,
+  max_evidence_per_finding: 32,
+  max_timeline_entries: 160,
+  max_explanation_items: 24,
+  max_capabilities: 16,
+  max_activity_entries: 64,
+  max_bundle_files: 32,
+  max_bundle_bytes: 8 * 1_024 * 1_024,
+  max_summary_chars: 500,
+  max_excerpt_chars: 2_000,
+} as const;
+
+export const SUPERVISOR_FINDING_POLICY = {
+  episode_gap_ms: 5 * 60_000,
+  activity_freshness_ms: 2 * 60_000,
+  max_activity_file_bytes: 64 * 1_024,
+  max_activity_total_bytes: 512 * 1_024,
+} as const;
+
+export const SUPERVISOR_RESOURCE_BUDGET = {
+  max_rss_bytes: 128 * 1_024 * 1_024,
+  max_cycle_duration_ms: 50,
+  max_startup_duration_ms: 2_000,
+  max_cache_bytes: 8 * 1_024 * 1_024,
+  max_regression_ratio: 1.2,
+} as const;
+
+export type SupervisorProcessState = "starting" | "running" | "stopping" | "stopped" | "error";
+
+export interface SupervisorServiceStatusRecord {
+  schema_version: typeof SUPERVISOR_STATUS_SCHEMA_VERSION;
+  pid: number;
+  start_token?: string;
+  host: string;
+  nonce: string;
+  state: SupervisorProcessState;
+  started_at: string;
+  heartbeat_at: string;
+  interval_ms: number;
+  keep_alive: boolean;
+  idle_exit_ms: number;
+  cycle_count: number;
+  last_cycle_at?: string;
+  last_cycle_duration_ms?: number;
+  idle_since?: string;
+  last_error_code?: string;
+  stopped_at?: string;
+}
+
+export interface SupervisorStatus {
+  running: boolean;
+  stale: boolean;
+  record?: SupervisorServiceStatusRecord;
+  status_path: string;
+  snapshot_path: string;
+}
+
+export interface SupervisorConsumerRecord {
+  schema_version: typeof SUPERVISOR_CONSUMER_SCHEMA_VERSION;
+  id: string;
+  pid: number;
+  start_token?: string;
+  registered_at: string;
+}
+
+export type ObservedServiceState = "running" | "stopped" | "stale" | "unknown";
+
+export interface ObservedServiceHealth {
+  id: "supervisor" | "semantic-reader" | "presence-relay" | "governor" | "dashboard";
+  state: ObservedServiceState;
+  pid?: number;
+  started_at?: string;
+  heartbeat_at?: string;
+  reason?: string;
+}
+
+export interface ObservedHookHealth {
+  pid: number;
+  owner_id: string;
+  state: string;
+  age_seconds: number;
+  cpu_percent: number | null;
+  rss_bytes: number;
+  command: string;
+  long_running: boolean;
+  evidence: "validated-owner-and-exact-entrypoint";
+}
+
+export interface SupervisorHistoryPoint {
+  sampled_at: string;
+  machine: {
+    cpu_percent: number | null;
+    memory_percent: number | null;
+    memory_used_bytes: number | null;
+    swap_used_bytes: number | null;
+    process_count: number;
+  };
+  groups: readonly ResourceProcessGroup[];
+}
+
+export interface SupervisorHistory {
+  schema_version: typeof SUPERVISOR_HISTORY_SCHEMA_VERSION;
+  interval_ms: number;
+  max_points: number;
+  points: readonly SupervisorHistoryPoint[];
+}
+
+export type SupervisorCapabilityState =
+  | "supported"
+  | "partial"
+  | "unsupported"
+  | "error"
+  | "expired"
+  | "malformed"
+  | "redacted";
+export type SupervisorFindingSeverity = "info" | "warning" | "critical";
+export type SupervisorFindingState = "opened" | "resolved";
+
+export interface SupervisorCapability {
+  source_kind: string;
+  state: SupervisorCapabilityState;
+  reason_code?: string;
+  detail?: string;
+}
+
+export interface SupervisorSourceReference {
+  id: string;
+  source_kind: string;
+  source_id: string;
+  observed_at: string;
+  record_id?: string;
+  sequence?: number;
+  schema_version?: number;
+  capability: SupervisorCapabilityState;
+}
+
+export interface SupervisorFindingEvidence {
+  id: string;
+  source: SupervisorSourceReference;
+  summary: string;
+  observed_value?: number;
+  unit?: "percent" | "bytes" | "milliseconds" | "seconds" | "processes" | "count";
+}
+
+export interface SupervisorFindingAttribution {
+  state: "attributed" | "unattributed";
+  owner_kind?: "agent" | "service";
+  owner_id?: string;
+  owner_root_pid?: number;
+  reason_code?: "no-validated-process-anchor";
+}
+
+export interface SupervisorFindingWorkloadContext {
+  relationship: "active-work" | "unexpected-idle-growth" | "unknown";
+  declared_activity: "working" | "needs_input" | "idle" | "unknown";
+  task_state: "active" | "blocked" | "done" | "unknown";
+  observed_at: string;
+  source: SupervisorSourceReference;
+}
+
+export interface SupervisorFinding {
+  schema_version: typeof SUPERVISOR_FINDING_SCHEMA_VERSION;
+  id: string;
+  fingerprint: string;
+  source_kind: string;
+  finding_kind: string;
+  severity: SupervisorFindingSeverity;
+  state: SupervisorFindingState;
+  scope_kind: string;
+  scope_id: string;
+  summary: string;
+  opened_at: string;
+  observed_at: string;
+  resolved_at?: string;
+  occurrence_count: number;
+  peak_observed_value?: number;
+  peak_observed_at?: string;
+  peak_unit?: SupervisorFindingEvidence["unit"];
+  attribution?: SupervisorFindingAttribution;
+  workload_context?: SupervisorFindingWorkloadContext;
+  primary_source: SupervisorSourceReference;
+  evidence: readonly SupervisorFindingEvidence[];
+  capabilities: readonly SupervisorCapability[];
+}
+
+export interface SupervisorDeclaredActivity {
+  scope_kind: "agent";
+  scope_id: string;
+  session_id: string;
+  declared_activity: "working" | "needs_input" | "idle" | "unknown";
+  task_state: "active" | "blocked" | "done";
+  observed_at: string;
+  source: SupervisorSourceReference;
+}
+
+export interface SupervisorActivitySnapshot {
+  schema_version: typeof SUPERVISOR_ACTIVITY_SCHEMA_VERSION;
+  observed_at: string;
+  max_entries: number;
+  entries: readonly SupervisorDeclaredActivity[];
+  omitted_entry_count: number;
+  capability: SupervisorCapability;
+}
+
+export interface SupervisorFindings {
+  schema_version: typeof SUPERVISOR_FINDING_SCHEMA_VERSION;
+  max_findings: number;
+  active: readonly SupervisorFinding[];
+  transitions: readonly SupervisorFinding[];
+}
+
+export type SupervisorTimelineRelation =
+  | "opened"
+  | "observed"
+  | "related"
+  | "resolved"
+  | "capability"
+  | "missing";
+
+export interface SupervisorTimelineEntry {
+  id: string;
+  occurred_at: string;
+  first_occurred_at: string;
+  last_occurred_at: string;
+  occurrence_count: number;
+  relation: SupervisorTimelineRelation;
+  summary: string;
+  source: SupervisorSourceReference;
+  evidence_id?: string;
+}
+
+export interface SupervisorTimeline {
+  schema_version: typeof SUPERVISOR_TIMELINE_SCHEMA_VERSION;
+  finding_id: string;
+  start_at: string;
+  end_at: string;
+  max_entries: number;
+  omitted_entries: number;
+  compacted_entries: number;
+  entries: readonly SupervisorTimelineEntry[];
+  capabilities: readonly SupervisorCapability[];
+}
+
+export interface SupervisorExplanationStatement {
+  id: string;
+  code: string;
+  summary: string;
+  evidence_ids: readonly string[];
+}
+
+export interface SupervisorPossibleExplanation extends SupervisorExplanationStatement {
+  confidence: "low" | "medium" | "high";
+  evidence_against_ids: readonly string[];
+}
+
+export interface SupervisorFindingExplanation {
+  schema_version: typeof SUPERVISOR_EXPLANATION_SCHEMA_VERSION;
+  finding_id: string;
+  generated_at: string;
+  observed: readonly SupervisorExplanationStatement[];
+  related: readonly SupervisorExplanationStatement[];
+  possible: readonly SupervisorPossibleExplanation[];
+  missing_capabilities: readonly SupervisorCapability[];
+}
+
+export interface SupervisorLogLane {
+  family_id: string;
+  owner: string;
+  storage_class: "operational-log" | "debug-log";
+  records: readonly HarneryLogRecordV1[];
+  truncated: boolean;
+  error?: string;
+}
+
+export interface SupervisorLogFeed {
+  schema_version: typeof SUPERVISOR_LOG_FEED_SCHEMA_VERSION;
+  captured_at: string;
+  sequence: number;
+  lanes: readonly SupervisorLogLane[];
+  total_records: number;
+  unavailable_families: number;
+}
+
+export interface SupervisorSnapshot {
+  schema_version: typeof SUPERVISOR_SNAPSHOT_SCHEMA_VERSION;
+  sampled_at: string;
+  sequence: number;
+  collector_duration_ms: number;
+  resource_sample_duration_ms: number;
+  services: readonly ObservedServiceHealth[];
+  hooks: readonly ObservedHookHealth[];
+  active_finding_count: number;
+  history_point_count: number;
+  log_record_count: number;
+  live_consumer_count: number;
+  attributed_agent_count: number;
+}

package/src/core/supervisor/explanations.ts

@@ -0,0 +1,104 @@
+import { createHash } from "node:crypto";
+import {
+  SUPERVISOR_DIAGNOSTIC_LIMITS,
+  SUPERVISOR_EXPLANATION_SCHEMA_VERSION,
+  type SupervisorExplanationStatement,
+  type SupervisorFinding,
+  type SupervisorFindingExplanation,
+  type SupervisorPossibleExplanation,
+} from "./contract.ts";
+
+/** Build evidence-linked statements without presenting correlation as causation. */
+export function explainSupervisorFinding(finding: SupervisorFinding): SupervisorFindingExplanation {
+  const observed = finding.evidence.map((evidence) =>
+    statement("observed.source", evidence.summary, [evidence.id]),
+  );
+  const related = relatedStatements(finding);
+  const possible = possibleStatements(finding);
+  return {
+    schema_version: SUPERVISOR_EXPLANATION_SCHEMA_VERSION,
+    finding_id: finding.id,
+    generated_at: finding.observed_at,
+    observed: observed.slice(0, SUPERVISOR_DIAGNOSTIC_LIMITS.max_explanation_items),
+    related: related.slice(0, SUPERVISOR_DIAGNOSTIC_LIMITS.max_explanation_items),
+    possible: possible.slice(0, SUPERVISOR_DIAGNOSTIC_LIMITS.max_explanation_items),
+    missing_capabilities: finding.capabilities
+      .filter((capability) => capability.state !== "supported")
+      .slice(0, SUPERVISOR_DIAGNOSTIC_LIMITS.max_capabilities),
+  };
+}
+
+function relatedStatements(finding: SupervisorFinding): SupervisorExplanationStatement[] {
+  const sources = new Set(finding.evidence.map((evidence) => evidence.source.source_kind));
+  if (sources.size < 2) return [];
+  return [
+    statement(
+      "related.multi-source",
+      `${sources.size} independent source kinds recorded related observations in this finding window.`,
+      finding.evidence.map((evidence) => evidence.id),
+    ),
+  ];
+}
+
+function possibleStatements(finding: SupervisorFinding): SupervisorPossibleExplanation[] {
+  const evidenceIds = finding.evidence.map((evidence) => evidence.id);
+  const possible: SupervisorPossibleExplanation[] = [];
+  if (finding.finding_kind.includes("memory")) {
+    possible.push({
+      ...statement(
+        "possible.memory-retention-or-workload",
+        "A growing workload, retained objects, or operating-system caching could explain the memory observation; this evidence does not distinguish them.",
+        evidenceIds,
+      ),
+      confidence: "low",
+      evidence_against_ids: [],
+    });
+  } else if (finding.finding_kind.includes("process-pressure")) {
+    possible.push({
+      ...statement(
+        "possible.concurrent-work",
+        "Concurrent local work could explain the process count; the finding does not establish which activity caused it.",
+        evidenceIds,
+      ),
+      confidence: "low",
+      evidence_against_ids: [],
+    });
+  } else if (finding.finding_kind === "hook.long-running") {
+    possible.push({
+      ...statement(
+        "possible.hook-stall",
+        "The hook may be waiting on I/O or blocked work, but elapsed time alone cannot identify the cause.",
+        evidenceIds,
+      ),
+      confidence: "low",
+      evidence_against_ids: [],
+    });
+  } else if (finding.finding_kind === "coordination.ledger-diagnostic") {
+    possible.push({
+      ...statement(
+        "possible.ledger-write-or-read-boundary",
+        "A producer write or reader validation boundary may explain the ledger diagnostic; inspect the referenced V3 record before attributing a cause.",
+        evidenceIds,
+      ),
+      confidence: "low",
+      evidence_against_ids: [],
+    });
+  }
+  return possible;
+}
+
+function statement(
+  code: string,
+  summary: string,
+  evidenceIds: readonly string[],
+): SupervisorExplanationStatement {
+  return {
+    id: `ex_${createHash("sha256")
+      .update(`${code}\u0000${summary}\u0000${evidenceIds.join(",")}`)
+      .digest("hex")
+      .slice(0, 24)}`,
+    code,
+    summary: summary.slice(0, SUPERVISOR_DIAGNOSTIC_LIMITS.max_summary_chars),
+    evidence_ids: [...evidenceIds].slice(0, SUPERVISOR_DIAGNOSTIC_LIMITS.max_evidence_per_finding),
+  };
+}