harnery 0.35.0 → 0.37.0

package/dist/core/supervisor/contract.d.ts

@@ -0,0 +1,268 @@
+import type { ResourceProcessGroup } from "../resources/contract.js";
+import type { HarneryLogRecordV1 } from "../storage/jsonl.js";
+export declare const SUPERVISOR_STATUS_SCHEMA_VERSION: 1;
+export declare const SUPERVISOR_SNAPSHOT_SCHEMA_VERSION: 2;
+export declare const SUPERVISOR_HISTORY_SCHEMA_VERSION: 1;
+export declare const SUPERVISOR_FINDING_SCHEMA_VERSION: 2;
+export declare const SUPERVISOR_ACTIVITY_SCHEMA_VERSION: 1;
+export declare const SUPERVISOR_TIMELINE_SCHEMA_VERSION: 2;
+export declare const SUPERVISOR_EXPLANATION_SCHEMA_VERSION: 1;
+export declare const SUPERVISOR_LOG_FEED_SCHEMA_VERSION: 1;
+export declare const SUPERVISOR_CONSUMER_SCHEMA_VERSION: 1;
+export declare const SUPERVISOR_DIAGNOSTIC_LIMITS: {
+    readonly max_findings: 100;
+    readonly max_active_findings: 32;
+    readonly max_evidence_per_finding: 32;
+    readonly max_timeline_entries: 160;
+    readonly max_explanation_items: 24;
+    readonly max_capabilities: 16;
+    readonly max_activity_entries: 64;
+    readonly max_bundle_files: 32;
+    readonly max_bundle_bytes: number;
+    readonly max_summary_chars: 500;
+    readonly max_excerpt_chars: 2000;
+};
+export declare const SUPERVISOR_FINDING_POLICY: {
+    readonly episode_gap_ms: number;
+    readonly activity_freshness_ms: number;
+    readonly max_activity_file_bytes: number;
+    readonly max_activity_total_bytes: number;
+};
+export declare const SUPERVISOR_RESOURCE_BUDGET: {
+    readonly max_rss_bytes: number;
+    readonly max_cycle_duration_ms: 50;
+    readonly max_startup_duration_ms: 2000;
+    readonly max_cache_bytes: number;
+    readonly max_regression_ratio: 1.2;
+};
+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;
+}
+//# sourceMappingURL=contract.d.ts.map

package/dist/core/supervisor/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/contract.ts"],"names":[],"mappings":"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"}

package/dist/core/supervisor/contract.js

@@ -0,0 +1,35 @@
+export const SUPERVISOR_STATUS_SCHEMA_VERSION = 1;
+export const SUPERVISOR_SNAPSHOT_SCHEMA_VERSION = 2;
+export const SUPERVISOR_HISTORY_SCHEMA_VERSION = 1;
+export const SUPERVISOR_FINDING_SCHEMA_VERSION = 2;
+export const SUPERVISOR_ACTIVITY_SCHEMA_VERSION = 1;
+export const SUPERVISOR_TIMELINE_SCHEMA_VERSION = 2;
+export const SUPERVISOR_EXPLANATION_SCHEMA_VERSION = 1;
+export const SUPERVISOR_LOG_FEED_SCHEMA_VERSION = 1;
+export const SUPERVISOR_CONSUMER_SCHEMA_VERSION = 1;
+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,
+};
+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,
+};
+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,
+};

package/dist/core/supervisor/explanations.d.ts

@@ -0,0 +1,4 @@
+import { type SupervisorFinding, type SupervisorFindingExplanation } from "./contract.js";
+/** Build evidence-linked statements without presenting correlation as causation. */
+export declare function explainSupervisorFinding(finding: SupervisorFinding): SupervisorFindingExplanation;
+//# sourceMappingURL=explanations.d.ts.map

package/dist/core/supervisor/explanations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explanations.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/explanations.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,4BAA4B,EAElC,MAAM,eAAe,CAAC;AAEvB,oFAAoF;AACpF,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,iBAAiB,GAAG,4BAA4B,CAiBjG"}

package/dist/core/supervisor/explanations.js

@@ -0,0 +1,71 @@
+import { createHash } from "node:crypto";
+import { SUPERVISOR_DIAGNOSTIC_LIMITS, SUPERVISOR_EXPLANATION_SCHEMA_VERSION, } from "./contract.js";
+/** Build evidence-linked statements without presenting correlation as causation. */
+export function explainSupervisorFinding(finding) {
+    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) {
+    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) {
+    const evidenceIds = finding.evidence.map((evidence) => evidence.id);
+    const possible = [];
+    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, summary, evidenceIds) {
+    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),
+    };
+}

package/dist/core/supervisor/findings.d.ts

@@ -0,0 +1,20 @@
+import type { CoordinationHealthSnapshot } from "../agents/health.js";
+import type { ResourceSnapshot } from "../resources/contract.js";
+import { type ObservedHookHealth, type ObservedServiceHealth, type SupervisorActivitySnapshot, type SupervisorFinding, type SupervisorFindings, type SupervisorHistory, type SupervisorLogFeed } from "./contract.js";
+import type { SupervisorHookHealth } from "./hook-health.js";
+export interface SupervisorFindingEvaluationInput {
+    previous?: SupervisorFindings;
+    resource: ResourceSnapshot;
+    services: readonly ObservedServiceHealth[];
+    hooks: readonly ObservedHookHealth[];
+    history: SupervisorHistory;
+    logFeed: SupervisorLogFeed;
+    hookHealth?: SupervisorHookHealth;
+    coordination?: CoordinationHealthSnapshot;
+    activity?: SupervisorActivitySnapshot;
+    now?: Date;
+}
+/** Pure deterministic evaluator used by the live supervisor and replay. */
+export declare function evaluateSupervisorFindings(input: Omit<SupervisorFindingEvaluationInput, "previous">): readonly SupervisorFinding[];
+export declare function updateSupervisorFindings(input: SupervisorFindingEvaluationInput): SupervisorFindings;
+//# sourceMappingURL=findings.d.ts.map

package/dist/core/supervisor/findings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"findings.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/findings.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AACtE,OAAO,KAAK,EAGV,gBAAgB,EACjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAI1B,KAAK,0BAA0B,EAE/B,KAAK,iBAAiB,EAItB,KAAK,kBAAkB,EAEvB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EAEvB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AA8B7D,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,QAAQ,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC3C,KAAK,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACrC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,UAAU,CAAC,EAAE,oBAAoB,CAAC;IAClC,YAAY,CAAC,EAAE,0BAA0B,CAAC;IAC1C,QAAQ,CAAC,EAAE,0BAA0B,CAAC;IACtC,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,2EAA2E;AAC3E,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,IAAI,CAAC,gCAAgC,EAAE,UAAU,CAAC,GACxD,SAAS,iBAAiB,EAAE,CAE9B;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,gCAAgC,GACtC,kBAAkB,CAwEpB"}