harnery 0.36.0 → 0.37.0

package/dist/core/supervisor/hook-health.js

@@ -0,0 +1,203 @@
+import { HOOK_HEALTH_EVENT, HOOK_HEALTH_RECEIPT_VERSION, } from "../hooks/health.js";
+export const SUPERVISOR_HOOK_HEALTH_SCHEMA_VERSION = 1;
+export const SUPERVISOR_HOOK_HEALTH_RECENT_LIMIT = 50;
+export const SUPERVISOR_HOOK_HEALTH_AGGREGATE_LIMIT = 40;
+export const SUPERVISOR_SLOW_COMPLETED_HOOK_MS = 30_000;
+export const SUPERVISOR_HIGH_COMPLETED_HOOK_RSS_BYTES = 512 * 1024 * 1024;
+export const SUPERVISOR_HOOK_RETRY_CLUSTER_COUNT = 3;
+export const SUPERVISOR_HOOK_RETRY_CLUSTER_WINDOW_MS = 5 * 60_000;
+export function projectHookHealth(feed, now = new Date()) {
+    const lane = feed.lanes.find((candidate) => candidate.family_id === "agent-hook-debug-log");
+    if (!lane)
+        return unavailable(now, "hook-log-family-not-visible");
+    if (lane.error)
+        return unavailable(now, "hook-log-family-unavailable");
+    const parsed = [];
+    let malformed = 0;
+    for (const record of lane.records) {
+        if (record.event !== HOOK_HEALTH_EVENT)
+            continue;
+        const receipt = parseCompletedHookHealth(record);
+        if (receipt)
+            parsed.push(receipt);
+        else
+            malformed += 1;
+    }
+    parsed.sort((left, right) => Date.parse(right.observed_at) - Date.parse(left.observed_at));
+    const recent = parsed.slice(0, SUPERVISOR_HOOK_HEALTH_RECENT_LIMIT);
+    const aggregates = aggregateHookHealth(parsed).slice(0, SUPERVISOR_HOOK_HEALTH_AGGREGATE_LIMIT);
+    const retryCutoff = now.getTime() - SUPERVISOR_HOOK_RETRY_CLUSTER_WINDOW_MS;
+    return {
+        schema_version: SUPERVISOR_HOOK_HEALTH_SCHEMA_VERSION,
+        captured_at: now.toISOString(),
+        capability: {
+            source_kind: "hook.terminal-log",
+            state: lane.truncated || malformed > 0 ? "partial" : "supported",
+            ...(lane.truncated
+                ? { reason: "bounded-log-window-truncated" }
+                : malformed > 0
+                    ? { reason: "malformed-terminal-records-ignored" }
+                    : {}),
+        },
+        source_record_count: parsed.length,
+        malformed_record_count: malformed,
+        truncated: lane.truncated || parsed.length > SUPERVISOR_HOOK_HEALTH_RECENT_LIMIT,
+        summary: {
+            invocation_count: parsed.length,
+            degraded_count: parsed.filter((receipt) => receipt.outcome === "degraded").length,
+            faulted_count: parsed.filter((receipt) => receipt.outcome === "faulted").length,
+            slow_count: parsed.filter((receipt) => receipt.duration_ms >= SUPERVISOR_SLOW_COMPLETED_HOOK_MS).length,
+            high_memory_count: parsed.filter((receipt) => receipt.rss_end_bytes >= SUPERVISOR_HIGH_COMPLETED_HOOK_RSS_BYTES).length,
+            retry_count: parsed.filter((receipt) => receipt.retry_worker && Date.parse(receipt.observed_at) >= retryCutoff).length,
+        },
+        aggregates,
+        recent,
+    };
+}
+export function parseCompletedHookHealth(record) {
+    if (record.kind !== "record" ||
+        record.component_id !== "agent-hook" ||
+        record.event !== HOOK_HEALTH_EVENT ||
+        record.fields.receipt_version !== HOOK_HEALTH_RECEIPT_VERSION ||
+        record.fields.exit_contract !== "always-zero" ||
+        record.fields.exit_code !== 0) {
+        return undefined;
+    }
+    const hookName = token(record.fields.hook_name);
+    const adapter = adapterValue(record.fields.adapter);
+    const outcome = outcomeValue(record.fields.outcome);
+    const duration = integer(record.fields.duration_ms);
+    const rssStart = integer(record.fields.rss_start_bytes);
+    const rssEnd = integer(record.fields.rss_end_bytes);
+    const rssDelta = signedInteger(record.fields.rss_delta_bytes);
+    const payloadBytes = integer(record.fields.payload_bytes);
+    const pid = integer(record.fields.pid);
+    const errorCount = integer(record.fields.error_count);
+    const retryWorker = record.fields.retry_worker;
+    const errorPhases = tokenArray(record.fields.error_phases);
+    if (!hookName ||
+        !adapter ||
+        !outcome ||
+        duration === undefined ||
+        rssStart === undefined ||
+        rssEnd === undefined ||
+        rssDelta === undefined ||
+        payloadBytes === undefined ||
+        pid === undefined ||
+        errorCount === undefined ||
+        typeof retryWorker !== "boolean" ||
+        !errorPhases ||
+        !Number.isFinite(Date.parse(record.emitted_at))) {
+        return undefined;
+    }
+    return {
+        id: `${record.writer_id}:${record.writer_seq}`,
+        observed_at: record.emitted_at,
+        hook_name: hookName,
+        adapter,
+        outcome,
+        duration_ms: duration,
+        rss_start_bytes: rssStart,
+        rss_end_bytes: rssEnd,
+        rss_delta_bytes: rssDelta,
+        retry_worker: retryWorker,
+        error_count: errorCount,
+        error_phases: errorPhases,
+        payload_bytes: payloadBytes,
+        pid,
+        ...optionalToken("owner_id", record.fields.owner_id),
+        ...optionalToken("skipped_reason", record.fields.skipped_reason),
+        ...optionalToken("v3_state", record.fields.v3_state),
+    };
+}
+function aggregateHookHealth(receipts) {
+    const grouped = new Map();
+    for (const receipt of receipts) {
+        const key = `${receipt.adapter}:${receipt.hook_name}`;
+        const group = grouped.get(key) ?? [];
+        group.push(receipt);
+        grouped.set(key, group);
+    }
+    return [...grouped.entries()]
+        .map(([key, group]) => {
+        const durations = group.map((receipt) => receipt.duration_ms).sort((a, b) => a - b);
+        return {
+            key,
+            hook_name: group[0].hook_name,
+            adapter: group[0].adapter,
+            invocation_count: group.length,
+            completed_count: countOutcome(group, "completed"),
+            skipped_count: countOutcome(group, "skipped"),
+            degraded_count: countOutcome(group, "degraded"),
+            faulted_count: countOutcome(group, "faulted"),
+            retry_count: group.filter((receipt) => receipt.retry_worker).length,
+            duration_p50_ms: percentile(durations, 0.5),
+            duration_p95_ms: percentile(durations, 0.95),
+            duration_max_ms: durations.at(-1) ?? 0,
+            rss_end_max_bytes: Math.max(...group.map((receipt) => receipt.rss_end_bytes)),
+            rss_delta_max_bytes: Math.max(...group.map((receipt) => receipt.rss_delta_bytes)),
+            latest_observed_at: group[0].observed_at,
+            owner_ids: [...new Set(group.flatMap((receipt) => receipt.owner_id ?? []))].slice(0, 8),
+        };
+    })
+        .sort((left, right) => Date.parse(right.latest_observed_at) - Date.parse(left.latest_observed_at) ||
+        left.key.localeCompare(right.key));
+}
+function countOutcome(receipts, outcome) {
+    return receipts.filter((receipt) => receipt.outcome === outcome).length;
+}
+function percentile(sorted, fraction) {
+    if (sorted.length === 0)
+        return 0;
+    return sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * fraction) - 1))];
+}
+function unavailable(now, reason) {
+    return {
+        schema_version: SUPERVISOR_HOOK_HEALTH_SCHEMA_VERSION,
+        captured_at: now.toISOString(),
+        capability: { source_kind: "hook.terminal-log", state: "unavailable", reason },
+        source_record_count: 0,
+        malformed_record_count: 0,
+        truncated: false,
+        summary: {
+            invocation_count: 0,
+            degraded_count: 0,
+            faulted_count: 0,
+            slow_count: 0,
+            high_memory_count: 0,
+            retry_count: 0,
+        },
+        aggregates: [],
+        recent: [],
+    };
+}
+function token(value) {
+    return typeof value === "string" && /^[a-zA-Z0-9][a-zA-Z0-9._:/+-]{0,127}$/.test(value)
+        ? value
+        : undefined;
+}
+function adapterValue(value) {
+    return value === "claude-code" || value === "codex" || value === "cursor" || value === "unknown"
+        ? value
+        : undefined;
+}
+function outcomeValue(value) {
+    return value === "completed" || value === "skipped" || value === "degraded" || value === "faulted"
+        ? value
+        : undefined;
+}
+function integer(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+function signedInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) ? value : undefined;
+}
+function tokenArray(value) {
+    return Array.isArray(value) && value.length <= 8 && value.every((item) => token(item))
+        ? value
+        : undefined;
+}
+function optionalToken(key, value) {
+    const parsed = token(value);
+    return parsed ? { [key]: parsed } : {};
+}

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

@@ -0,0 +1,10 @@
+import type { ResourceSnapshot } from "../resources/contract.js";
+import type { ObservedHookHealth } from "./contract.js";
+export declare const SUPERVISOR_LONG_HOOK_SECONDS = 120;
+/**
+ * Command text may label a process only after PID ancestry proved its agent
+ * owner. It never establishes ownership by itself.
+ */
+export declare function collectHookHealth(resource: ResourceSnapshot): ObservedHookHealth[];
+export declare function exactHookEntrypoint(name: string, command: string): boolean;
+//# sourceMappingURL=hooks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAExD,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,kBAAkB,EAAE,CAoBlF;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAG1E"}

package/dist/core/supervisor/hooks.js

@@ -0,0 +1,28 @@
+export const SUPERVISOR_LONG_HOOK_SECONDS = 120;
+/**
+ * Command text may label a process only after PID ancestry proved its agent
+ * owner. It never establishes ownership by itself.
+ */
+export function collectHookHealth(resource) {
+    return resource.processes
+        .filter((row) => row.owner_kind === "agent" &&
+        row.owner_id !== null &&
+        exactHookEntrypoint(row.name, row.command))
+        .map((row) => ({
+        pid: row.pid,
+        owner_id: row.owner_id,
+        state: row.state,
+        age_seconds: row.age_seconds,
+        cpu_percent: row.cpu_percent,
+        rss_bytes: row.rss_bytes,
+        command: row.command,
+        long_running: row.age_seconds >= SUPERVISOR_LONG_HOOK_SECONDS,
+        evidence: "validated-owner-and-exact-entrypoint",
+    }))
+        .sort((left, right) => right.age_seconds - left.age_seconds || left.pid - right.pid);
+}
+export function exactHookEntrypoint(name, command) {
+    if (name === "agent-hook" || name === "agent-hook.exe")
+        return true;
+    return /(?:^|[\\/\s])agent-hook(?:\.exe)?(?:\s|$)/.test(command);
+}

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

@@ -0,0 +1,15 @@
+export * from "./contract.js";
+export * from "./explanations.js";
+export * from "./findings.js";
+export * from "./history.js";
+export * from "./hook-health.js";
+export * from "./hook-health-alerts.js";
+export * from "./hook-health-storage.js";
+export * from "./hooks.js";
+export * from "./log-feed.js";
+export * from "./service.js";
+export * from "./services.js";
+export * from "./status.js";
+export * from "./storage.js";
+export * from "./timeline.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC"}

package/dist/core/supervisor/index.js

@@ -0,0 +1,14 @@
+export * from "./contract.js";
+export * from "./explanations.js";
+export * from "./findings.js";
+export * from "./history.js";
+export * from "./hook-health.js";
+export * from "./hook-health-alerts.js";
+export * from "./hook-health-storage.js";
+export * from "./hooks.js";
+export * from "./log-feed.js";
+export * from "./service.js";
+export * from "./services.js";
+export * from "./status.js";
+export * from "./storage.js";
+export * from "./timeline.js";

package/dist/core/supervisor/log-feed.d.ts

@@ -0,0 +1,9 @@
+import type { HarneryLogRecordV1 } from "../storage/jsonl.js";
+import { type SupervisorLogFeed } from "./contract.js";
+export declare class SupervisorLogCollector {
+    #private;
+    constructor(coordRoot: string);
+    collect(now?: Date): Promise<SupervisorLogFeed>;
+}
+export declare function recentSupervisorLogs(feed: SupervisorLogFeed, limit?: number): HarneryLogRecordV1[];
+//# sourceMappingURL=log-feed.d.ts.map

package/dist/core/supervisor/log-feed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-feed.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/log-feed.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAO9D,OAAO,EAEL,KAAK,iBAAiB,EAEvB,MAAM,eAAe,CAAC;AAcvB,qBAAa,sBAAsB;;gBAIrB,SAAS,EAAE,MAAM;IAKvB,OAAO,CAAC,GAAG,OAAa,GAAG,OAAO,CAAC,iBAAiB,CAAC;CA4C5D;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,iBAAiB,EAAE,KAAK,SAAK,GAAG,kBAAkB,EAAE,CAK9F"}

package/dist/core/supervisor/log-feed.js

@@ -0,0 +1,103 @@
+import { createStorageCatalog } from "../storage/catalog.js";
+import { HARNERY_STRUCTURED_LOG_PROVIDER_ID, } from "../storage/contract.js";
+import { readLogFollow, readRecentActiveLogs, rotationFollowCursor, } from "../storage/query.js";
+import { SUPERVISOR_LOG_FEED_SCHEMA_VERSION, } from "./contract.js";
+const MAX_RECORDS_PER_FAMILY = 100;
+const MAX_SEED_BYTES_PER_FAMILY = 256 * 1024;
+const MAX_FOLLOW_BYTES_PER_FAMILY = 64 * 1024;
+export class SupervisorLogCollector {
+    #lanes;
+    #sequence = 0;
+    constructor(coordRoot) {
+        const catalog = createStorageCatalog({ coord_root: coordRoot, project_root: coordRoot });
+        this.#lanes = catalog.families.filter(isStructuredLogFamily).map((family) => seedLane(family));
+    }
+    async collect(now = new Date()) {
+        let changed = this.#sequence === 0;
+        for (const lane of this.#lanes) {
+            try {
+                const followed = await readLogFollow(lane.family, lane.cursor, MAX_FOLLOW_BYTES_PER_FAMILY);
+                lane.cursor = followed.cursor;
+                if (followed.records.length > 0 || followed.rotated || followed.history_expired) {
+                    const merged = dedupe([...lane.records, ...followed.records]);
+                    lane.records = merged.slice(-MAX_RECORDS_PER_FAMILY);
+                    lane.truncated =
+                        lane.truncated || followed.history_expired || merged.length > MAX_RECORDS_PER_FAMILY;
+                    changed = true;
+                }
+                if (lane.error)
+                    changed = true;
+                lane.error = undefined;
+            }
+            catch (error) {
+                const next = error instanceof Error ? error.message : String(error);
+                if (next !== lane.error)
+                    changed = true;
+                lane.error = next;
+            }
+        }
+        if (changed)
+            this.#sequence += 1;
+        const lanes = this.#lanes
+            .map((lane) => ({
+            family_id: lane.family.id,
+            owner: lane.family.owner,
+            storage_class: lane.family.storage_class,
+            records: lane.records,
+            truncated: lane.truncated,
+            ...(lane.error ? { error: lane.error } : {}),
+        }))
+            .sort((left, right) => {
+            const activeDelta = Number(right.records.length > 0) - Number(left.records.length > 0);
+            return activeDelta || left.family_id.localeCompare(right.family_id);
+        });
+        return {
+            schema_version: SUPERVISOR_LOG_FEED_SCHEMA_VERSION,
+            captured_at: now.toISOString(),
+            sequence: this.#sequence,
+            lanes,
+            total_records: lanes.reduce((sum, lane) => sum + lane.records.length, 0),
+            unavailable_families: lanes.filter((lane) => lane.error).length,
+        };
+    }
+}
+export function recentSupervisorLogs(feed, limit = 20) {
+    return feed.lanes
+        .flatMap((lane) => lane.records)
+        .sort((left, right) => Date.parse(left.emitted_at) - Date.parse(right.emitted_at))
+        .slice(-Math.max(0, limit));
+}
+function seedLane(family) {
+    try {
+        const seed = readRecentActiveLogs(family, {
+            max_records: MAX_RECORDS_PER_FAMILY,
+            max_bytes: MAX_SEED_BYTES_PER_FAMILY,
+        });
+        return {
+            family,
+            cursor: rotationFollowCursor(family),
+            records: [...seed.records],
+            truncated: seed.truncated,
+        };
+    }
+    catch (error) {
+        return {
+            family,
+            cursor: rotationFollowCursor(family),
+            records: [],
+            truncated: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+function isStructuredLogFamily(family) {
+    return ((family.storage_class === "operational-log" || family.storage_class === "debug-log") &&
+        family.provider.provider_id === HARNERY_STRUCTURED_LOG_PROVIDER_ID);
+}
+function dedupe(records) {
+    const keyed = new Map();
+    for (const record of records) {
+        keyed.set(`${record.family_id}:${record.writer_id}:${record.writer_seq}`, record);
+    }
+    return [...keyed.values()].sort((left, right) => Date.parse(left.emitted_at) - Date.parse(right.emitted_at));
+}

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

@@ -0,0 +1,29 @@
+import { type SupervisorServiceStatusRecord, type SupervisorStatus } from "./contract.js";
+export declare const SUPERVISOR_DEFAULT_INTERVAL_MS = 2000;
+export declare const SUPERVISOR_DEFAULT_IDLE_EXIT_MS: number;
+export interface RunSupervisorInput {
+    coordRoot: string;
+    intervalMs?: number;
+    idleExitMs?: number;
+    keepAlive?: boolean;
+    maxCycles?: number;
+    now?: () => Date;
+    wait?: (milliseconds: number) => Promise<void>;
+}
+export type EnsureSupervisorResult = {
+    state: "running" | "started";
+    status: SupervisorStatus;
+} | {
+    state: "unavailable";
+    status: SupervisorStatus;
+    error: string;
+};
+export declare function spawnSupervisor(coordRootRaw: string, options?: {
+    intervalMs?: number;
+    idleExitMs?: number;
+    keepAlive?: boolean;
+}): Promise<SupervisorStatus>;
+export declare function ensureSupervisorRunning(coordRoot: string): Promise<EnsureSupervisorResult>;
+export declare function requestSupervisorStop(coordRootRaw: string): SupervisorStatus;
+export declare function runSupervisor(input: RunSupervisorInput): Promise<SupervisorServiceStatusRecord>;
+//# sourceMappingURL=service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/service.ts"],"names":[],"mappings":"AA0BA,OAAO,EAGL,KAAK,6BAA6B,EAElC,KAAK,gBAAgB,EACtB,MAAM,eAAe,CAAC;AAavB,eAAO,MAAM,8BAA8B,OAAQ,CAAC;AACpD,eAAO,MAAM,+BAA+B,QAAa,CAAC;AAc1D,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,IAAI,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD;AAED,MAAM,MAAM,sBAAsB,GAC9B;IAAE,KAAK,EAAE,SAAS,GAAG,SAAS,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,GAC1D;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtE,wBAAsB,eAAe,CACnC,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAO,GAC9E,OAAO,CAAC,gBAAgB,CAAC,CAoD3B;AAED,wBAAsB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAahG;AAED,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,gBAAgB,CAiB5E;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,6BAA6B,CAAC,CAsMxC"}