harnery 0.34.1 → 0.36.0

package/src/core/semantic/routes.ts

@@ -0,0 +1,30 @@
+import type { SemanticConfiguredModel, SemanticHarness } from "./contract.ts";
+
+export interface SemanticReaderRoute {
+  harness: SemanticHarness;
+  binary: string;
+  configured_model: SemanticConfiguredModel;
+  invocation_model_id: string;
+}
+
+/** Pure route data shared by the adapters, CLI status, and read-only Codec path. */
+export const SEMANTIC_READER_ROUTES: Record<SemanticHarness, SemanticReaderRoute> = {
+  "claude-code": {
+    harness: "claude-code",
+    binary: "claude",
+    configured_model: "haiku-4.5",
+    invocation_model_id: "claude-haiku-4-5-20251001",
+  },
+  codex: {
+    harness: "codex",
+    binary: "codex",
+    configured_model: "gpt-5.6-luna",
+    invocation_model_id: "gpt-5.6-luna",
+  },
+  cursor: {
+    harness: "cursor",
+    binary: "cursor-agent",
+    configured_model: "composer-2.5",
+    invocation_model_id: "composer-2.5",
+  },
+};

package/src/core/semantic/scheduler.ts

@@ -0,0 +1,151 @@
+import type { SemanticAgentReadModelV2, SemanticEvidenceV1 } from "./contract.ts";
+import type { SemanticCallReceipt, SemanticPendingItem } from "./storage.ts";
+
+export const SEMANTIC_HARD_CALLS_PER_HOUR = 120;
+export const SEMANTIC_INVALID_RETRY_COOLDOWN_MS = 5 * 60_000;
+export const SEMANTIC_MIN_PRIORITY_GENERATION_CALL_INTERVAL_MS = 2 * 60_000;
+export const SEMANTIC_MIN_AMBIENT_GENERATION_CALL_INTERVAL_MS = 5 * 60_000;
+export const SEMANTIC_MIN_GENERATION_CALL_INTERVAL_MS =
+  SEMANTIC_MIN_PRIORITY_GENERATION_CALL_INTERVAL_MS;
+
+export function semanticPriorityBand(evidence: SemanticEvidenceV1): 1 | 2 {
+  if (
+    evidence.attention ||
+    (evidence.lifecycle && evidence.lifecycle.state !== "active") ||
+    evidence.recent.some((item) => item.kind === "terminal")
+  ) {
+    return 1;
+  }
+  return 2;
+}
+
+export function semanticPendingCallIntervalMs(pending: SemanticPendingItem): number {
+  return pending.band === 1
+    ? SEMANTIC_MIN_PRIORITY_GENERATION_CALL_INTERVAL_MS
+    : SEMANTIC_MIN_AMBIENT_GENERATION_CALL_INTERVAL_MS;
+}
+
+export function enqueueSemanticPending(
+  pending: readonly SemanticPendingItem[],
+  evidence: SemanticEvidenceV1,
+  nowIso: string,
+): SemanticPendingItem[] {
+  const prior = pending.find((item) => item.generation_id === evidence.generation_id);
+  const next: SemanticPendingItem = {
+    generation_id: evidence.generation_id,
+    evidence_digest: evidence.evidence_digest as `sha256:${string}`,
+    band: semanticPriorityBand(evidence),
+    pending_since:
+      prior?.evidence_digest === evidence.evidence_digest ? prior.pending_since : nowIso,
+  };
+  return [...pending.filter((item) => item.generation_id !== evidence.generation_id), next];
+}
+
+export function selectSemanticPending(
+  pending: readonly SemanticPendingItem[],
+  lastFirstBandGenerationId?: string,
+  callHistory: readonly SemanticCallReceipt[] = [],
+): SemanticPendingItem | undefined {
+  const sorted = [...pending].sort(
+    (left, right) =>
+      left.band - right.band ||
+      left.pending_since.localeCompare(right.pending_since) ||
+      left.generation_id.localeCompare(right.generation_id),
+  );
+  const recentlyCalled = new Set(callHistory.map((call) => call.generation_id));
+  const uncovered = sorted.filter((item) => !recentlyCalled.has(item.generation_id));
+  const eligible = uncovered.length > 0 ? uncovered : sorted;
+  const firstBand = eligible.filter((item) => item.band === 1);
+  if (firstBand.length > 0) {
+    const lastIndex = firstBand.findIndex(
+      (item) => item.generation_id === lastFirstBandGenerationId,
+    );
+    return firstBand[lastIndex >= 0 ? (lastIndex + 1) % firstBand.length : 0];
+  }
+  return eligible[0];
+}
+
+export function activeSemanticCallHistory(
+  history: readonly SemanticCallReceipt[],
+  nowMs: number,
+): SemanticCallReceipt[] {
+  return history.filter((call) => {
+    const started = Date.parse(call.started_at);
+    return Number.isFinite(started) && nowMs - started < 60 * 60_000;
+  });
+}
+
+export function semanticRateCap(
+  history: readonly SemanticCallReceipt[],
+  nowMs: number,
+  configuredLimit = SEMANTIC_HARD_CALLS_PER_HOUR,
+): { available: number; eligible_after?: string } {
+  const active = activeSemanticCallHistory(history, nowMs).sort((left, right) =>
+    left.started_at.localeCompare(right.started_at),
+  );
+  const limit = Math.min(SEMANTIC_HARD_CALLS_PER_HOUR, Math.max(1, Math.floor(configuredLimit)));
+  if (active.length < limit) return { available: limit - active.length };
+  return {
+    available: 0,
+    eligible_after: new Date(Date.parse(active[0]!.started_at) + 60 * 60_000).toISOString(),
+  };
+}
+
+export function semanticGenerationCallEligible(
+  history: readonly SemanticCallReceipt[],
+  generationId: string,
+  nowMs: number,
+  minimumIntervalMs = SEMANTIC_MIN_GENERATION_CALL_INTERVAL_MS,
+): boolean {
+  const newest = history
+    .filter((call) => call.generation_id === generationId)
+    .map((call) => Date.parse(call.started_at))
+    .filter(Number.isFinite)
+    .sort((left, right) => right - left)[0];
+  return newest === undefined || nowMs - newest >= Math.max(0, minimumIntervalMs);
+}
+
+export function semanticPendingPassDue(input: {
+  pending: readonly SemanticPendingItem[];
+  callHistory: readonly SemanticCallReceipt[];
+  nowMs: number;
+  debounceMs: number;
+  callsPerHour?: number;
+  minimumGenerationCallIntervalMs?: number;
+}): boolean {
+  const matured = input.pending.filter((item) => {
+    const pendingSince = Date.parse(item.pending_since);
+    return (
+      !Number.isFinite(pendingSince) || input.nowMs - pendingSince >= Math.max(0, input.debounceMs)
+    );
+  });
+  if (matured.length === 0) return false;
+
+  const cap = semanticRateCap(input.callHistory, input.nowMs, input.callsPerHour);
+  // One pass is still required at the cap so runSemanticOnce can publish
+  // deferred receipts and remove the matured items from the pending queue.
+  if (cap.available === 0) return true;
+
+  return matured.some((item) =>
+    semanticGenerationCallEligible(
+      input.callHistory,
+      item.generation_id,
+      input.nowMs,
+      input.minimumGenerationCallIntervalMs ?? semanticPendingCallIntervalMs(item),
+    ),
+  );
+}
+
+export function semanticDocumentEligible(
+  document: SemanticAgentReadModelV2 | undefined,
+  evidence: SemanticEvidenceV1,
+  nowMs: number,
+): boolean {
+  if (!document || document.source.evidence_digest !== evidence.evidence_digest) return true;
+  if (document.reader_outcome === "accepted") return false;
+  if (document.reader_outcome === "deferred") {
+    return Date.parse(document.receipt.eligible_after) <= nowMs;
+  }
+  const generated = Date.parse(document.generated_at);
+  return !Number.isFinite(generated) || nowMs - generated >= SEMANTIC_INVALID_RETRY_COOLDOWN_MS;
+}

package/src/core/semantic/service-status.ts

@@ -0,0 +1,212 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { hostname } from "node:os";
+import { resolve } from "node:path";
+
+import type { SemanticHarness } from "./contract.ts";
+import { SEMANTIC_READER_ROUTES } from "./routes.ts";
+import {
+  activeSemanticCallHistory,
+  SEMANTIC_HARD_CALLS_PER_HOUR,
+  semanticRateCap,
+} from "./scheduler.ts";
+import { readSemanticManifest, type SemanticReaderResolution, semanticPaths } from "./storage.ts";
+import {
+  aggregateSemanticUsage,
+  emptySemanticUsageAggregate,
+  type SemanticUsageAggregate,
+} from "./usage.ts";
+
+export const SEMANTIC_SERVICE_STATUS_SCHEMA_VERSION = 1 as const;
+const FOREIGN_STATUS_STALE_MS = 2 * 60_000;
+const MAX_FILE_BYTES = 512 * 1024;
+
+export type SemanticServiceState = "starting" | "running" | "stopping" | "stopped";
+export type SemanticServiceErrorCode = "ledger_unavailable" | "semantic_pass_failed";
+
+export interface SemanticServiceStatusRecord {
+  schema_version: typeof SEMANTIC_SERVICE_STATUS_SCHEMA_VERSION;
+  pid: number;
+  host: string;
+  nonce: string;
+  state: SemanticServiceState;
+  started_at: string;
+  heartbeat_at: string;
+  calls_per_hour?: number;
+  sweep_count: number;
+  pass_count: number;
+  model_calls: number;
+  cache_hits: number;
+  process_usage?: SemanticUsageAggregate;
+  last_sweep_at?: string;
+  last_pass_at?: string;
+  last_error_code?: SemanticServiceErrorCode;
+  stopped_at?: string;
+}
+
+export interface SemanticServiceStatus {
+  running: boolean;
+  stale: boolean;
+  record?: SemanticServiceStatusRecord;
+  newest_successful_pass?: string;
+  pending_count: number;
+  rolling_calls?: {
+    used: number;
+    limit: number;
+    available: number;
+    eligible_after?: string;
+  };
+  routes?: Array<{
+    harness: keyof typeof SEMANTIC_READER_ROUTES;
+    configured_model: string;
+    invocation_model_id: string;
+    resolved_model_id?: string;
+    model_attestation?: "verified" | "requested-only";
+    available?: boolean;
+    reason_code?: string;
+  }>;
+  rolling_usage?: SemanticUsageAggregate;
+  process_usage?: SemanticUsageAggregate;
+}
+
+/** Read-only service health. This module cannot spawn, signal, or write. */
+export function readSemanticServiceStatus(coordRootRaw: string): SemanticServiceStatus {
+  const coordRoot = resolve(coordRootRaw);
+  const record = readStatusRecord(coordRoot);
+  const manifest = safeManifest(coordRoot);
+  const now = Date.now();
+  const history = activeSemanticCallHistory(manifest?.call_history ?? [], now);
+  const limit = Math.min(
+    SEMANTIC_HARD_CALLS_PER_HOUR,
+    Math.max(1, Math.floor(record?.calls_per_hour ?? SEMANTIC_HARD_CALLS_PER_HOUR)),
+  );
+  const cap = semanticRateCap(history, now, limit);
+  const rollingUsage = aggregateSemanticUsage(
+    history.map((call) => ({
+      source_harness: call.source_harness,
+      configured_model: call.configured_model,
+      resolved_model_id: call.resolved_model_id,
+      model_attestation: call.model_attestation,
+      action: call.outcome,
+      model_call: true,
+      usage: call.usage,
+      invalid_reason_codes: call.invalid_reason_codes,
+    })),
+  );
+  const processUsage = record?.process_usage ?? legacyProcessUsage(record?.model_calls ?? 0);
+  const shared = {
+    ...(manifest?.newest_successful_pass
+      ? { newest_successful_pass: manifest.newest_successful_pass }
+      : {}),
+    pending_count: manifest?.pending.length ?? 0,
+    rolling_calls: {
+      used: history.length,
+      limit,
+      available: cap.available,
+      ...(cap.eligible_after ? { eligible_after: cap.eligible_after } : {}),
+    },
+    routes: semanticStatusRoutes(manifest?.adapter_resolutions),
+    rolling_usage: rollingUsage,
+    process_usage: processUsage,
+  };
+  if (!record) {
+    return {
+      running: false,
+      stale: false,
+      ...shared,
+    };
+  }
+  const running = statusOwnerIsLive(record);
+  return {
+    running,
+    stale: !running && record.state !== "stopped",
+    record,
+    ...shared,
+  };
+}
+
+function semanticStatusRoutes(
+  resolutions: Partial<Record<SemanticHarness, SemanticReaderResolution>> | undefined,
+): NonNullable<SemanticServiceStatus["routes"]> {
+  return (Object.keys(SEMANTIC_READER_ROUTES) as Array<keyof typeof SEMANTIC_READER_ROUTES>).map(
+    (harness) => {
+      const route = SEMANTIC_READER_ROUTES[harness];
+      const resolution = resolutions?.[harness];
+      return {
+        harness,
+        configured_model: route.configured_model,
+        invocation_model_id: route.invocation_model_id,
+        ...(resolution?.resolved_model_id
+          ? { resolved_model_id: resolution.resolved_model_id }
+          : {}),
+        ...(resolution?.model_attestation
+          ? { model_attestation: resolution.model_attestation }
+          : {}),
+        ...(resolution ? { available: resolution.available } : {}),
+        ...(resolution?.reason_code ? { reason_code: resolution.reason_code } : {}),
+      };
+    },
+  );
+}
+
+function legacyProcessUsage(modelCalls: number): SemanticUsageAggregate {
+  const aggregate = emptySemanticUsageAggregate();
+  aggregate.call_count = modelCalls;
+  aggregate.unreported_calls = modelCalls;
+  return aggregate;
+}
+
+function safeManifest(coordRoot: string) {
+  try {
+    return readSemanticManifest(coordRoot);
+  } catch {
+    return undefined;
+  }
+}
+
+function readStatusRecord(coordRoot: string): SemanticServiceStatusRecord | undefined {
+  const path = semanticPaths(coordRoot).service;
+  if (!existsSync(path)) return undefined;
+  try {
+    const value = readBoundedJson<SemanticServiceStatusRecord>(path, "semantic service status");
+    if (
+      value.schema_version !== SEMANTIC_SERVICE_STATUS_SCHEMA_VERSION ||
+      !Number.isSafeInteger(value.pid) ||
+      value.pid < 1 ||
+      typeof value.host !== "string" ||
+      typeof value.nonce !== "string" ||
+      !validTimestamp(value.started_at) ||
+      !validTimestamp(value.heartbeat_at)
+    ) {
+      return undefined;
+    }
+    return value;
+  } catch {
+    return undefined;
+  }
+}
+
+function statusOwnerIsLive(record: SemanticServiceStatusRecord): boolean {
+  if (record.state === "stopped") return false;
+  if (record.host === hostname()) return pidAlive(record.pid);
+  const age = Date.now() - Date.parse(record.heartbeat_at);
+  return Number.isFinite(age) && age < FOREIGN_STATUS_STALE_MS;
+}
+
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+function readBoundedJson<T>(path: string, label: string): T {
+  const size = statSync(path).size;
+  if (size <= 0 || size > MAX_FILE_BYTES) throw new Error(`${label} has invalid size ${size}`);
+  return JSON.parse(readFileSync(path, "utf8")) as T;
+}
+
+function validTimestamp(value: unknown): value is string {
+  return typeof value === "string" && Number.isFinite(Date.parse(value));
+}