@hasna/loops 0.4.12 → 0.4.14

package/dist/lib/health.d.ts

@@ -1,10 +1,13 @@
-import type { Loop, LoopRun } from "../types.js";
+import type { Loop, LoopRun, LoopStatus } from "../types.js";
+import type { DaemonStatus } from "../daemon/control.js";
+import type { DoctorCheck, DoctorReport } from "./doctor.js";
 import type { Store } from "./store.js";
-export type RunFailureClassification = "rate_limit" | "auth" | "model_not_found" | "context_length" | "schema_response_format" | "node_init" | "preflight" | "route_functional" | "timeout" | "sigsegv" | "skipped_previous_active" | "circuit_breaker" | "unknown";
+export type RunFailureClassification = "rate_limit" | "auth" | "provider_unavailable" | "model_not_found" | "context_length" | "schema_response_format" | "node_init" | "preflight" | "route_functional" | "timeout" | "sigsegv" | "restart_interrupted" | "skipped_previous_active" | "circuit_breaker" | "unknown";
 export interface RunFailureSignal {
     classification: RunFailureClassification;
     fingerprint: string;
     evidence: {
+        summary?: string;
         error?: string;
         stdout?: string;
         stderr?: string;
@@ -31,7 +34,7 @@ export interface RecommendedTaskUpsert {
     };
 }
 export interface LoopExpectationResult {
-    loop: Pick<Loop, "id" | "name" | "status" | "nextRunAt">;
+    loop: Pick<Loop, "id" | "name" | "status" | "nextRunAt" | "retryScheduledFor">;
     ok: boolean;
     check: {
         id: "latest-run-succeeded" | "route-functional-health";
@@ -62,6 +65,81 @@ export interface LoopsHealthReport {
     classifications: Record<RunFailureClassification, number>;
     expectations: LoopExpectationResult[];
 }
+export type HealthScanStatus = "ok" | "degraded" | "critical";
+export type HealthScanFindingKind = "daemon" | "doctor" | "preflight" | "latest-run" | "stale-running";
+export type HealthScanFindingSeverity = "critical" | "high" | "medium" | "low";
+export interface HealthScanSelfHealAction {
+    kind: "daemon-start";
+    attempted: boolean;
+    ok?: boolean;
+    reason: string;
+    result?: Record<string, unknown>;
+}
+export interface HealthScanFinding {
+    kind: HealthScanFindingKind;
+    severity: HealthScanFindingSeverity;
+    fingerprint: string;
+    title: string;
+    message: string;
+    loop?: Pick<Loop, "id" | "name" | "status" | "nextRunAt"> & {
+        leaseMs?: number;
+    };
+    run?: LoopRun;
+    route?: LoopExpectationResult["route"];
+    ageMs?: number;
+    staleThresholdMs?: number;
+    classification?: RunFailureClassification;
+    doctorCheck?: DoctorCheck;
+    recommendedTask?: RecommendedTaskUpsert;
+}
+export interface LoopsHealthScan {
+    ok: boolean;
+    status: HealthScanStatus;
+    generatedAt: string;
+    includedStatuses: LoopStatus[];
+    counts: {
+        loops: number;
+        active: number;
+        paused: number;
+        stopped: number;
+        expired: number;
+        latestRunFindings: number;
+        staleRunning: number;
+        daemonFindings: number;
+        doctorFindings: number;
+        preflightFindings: number;
+        findings: number;
+        reportedFindings: number;
+        truncatedFindings: number;
+    };
+    daemon?: Pick<DaemonStatus, "running" | "stale" | "pid" | "host" | "loops" | "runs" | "logPath">;
+    doctor?: DoctorReport;
+    health: LoopsHealthReport;
+    selfHeals: HealthScanSelfHealAction[];
+    findings: HealthScanFinding[];
+    reports?: {
+        dir: string;
+        json: string;
+        markdown: string;
+    };
+    todos?: Record<string, unknown>;
+}
+export interface BuildHealthScanOptions {
+    includeStatuses?: LoopStatus[];
+    includeArchived?: boolean;
+    limit?: number;
+    latestRun?: boolean;
+    doctor?: DoctorReport;
+    daemon?: DaemonStatus;
+    selfHeals?: HealthScanSelfHealAction[];
+    maxFindings?: number;
+    staleRunningMs?: number;
+    now?: Date;
+}
+export interface WriteHealthScanReportsOptions {
+    reportDir?: string;
+}
+export declare const RESTART_INTERRUPTED_RUN_PREFIX = "daemon restart interrupted active run";
 export declare function classifyRunFailure(run: LoopRun): RunFailureSignal | undefined;
 export declare function expectationForLoop(store: Store, loop: Loop): LoopExpectationResult;
 export declare function buildHealthReport(store: Store, opts?: {
@@ -69,3 +147,5 @@ export declare function buildHealthReport(store: Store, opts?: {
     includeInactive?: boolean;
     limit?: number;
 }): LoopsHealthReport;
+export declare function buildHealthScan(store: Store, opts?: BuildHealthScanOptions): LoopsHealthScan;
+export declare function writeHealthScanReports(scan: LoopsHealthScan, opts?: WriteHealthScanReportsOptions): LoopsHealthScan;

package/dist/lib/mode.d.ts

@@ -1,6 +1,10 @@
 export declare const LOOP_DEPLOYMENT_MODES: readonly ["local", "self_hosted", "cloud"];
 export type LoopDeploymentMode = (typeof LOOP_DEPLOYMENT_MODES)[number];
 export type LoopSourceOfTruth = "local_sqlite" | "self_hosted_control_plane" | "cloud_control_plane";
+export type LoopRemoteSchedulerBackend = "none" | "unconfigured" | "api_control_plane_contract" | "postgres_contract" | "hosted_control_plane_contract";
+export type LoopRemoteArtifactStore = "none" | "object_store_contract";
+export type LoopRouteAdmissionStateStore = "local_sqlite" | "control_plane_contract";
+export type LoopRouteAdmissionGate = "max_dispatch" | "max_active" | "max_active_per_project" | "max_active_per_project_group" | "max_active_scope" | "max_per_profile";
 export interface LoopModeResolution {
     deploymentMode: LoopDeploymentMode;
     source: string;
@@ -34,8 +38,31 @@ export interface LoopDeploymentStatus {
         required: boolean;
         role: "daemon" | "control_plane_worker";
     };
+    schedulerState: LoopSchedulerStateStatus;
     warnings: string[];
 }
+export interface LoopSchedulerStateStatus {
+    authority: LoopSourceOfTruth;
+    localStore: {
+        backend: "sqlite";
+        role: "authoritative" | "cache_and_spool";
+        runArtifacts: "local_files";
+        routeAdmissionState: "workflow_work_items";
+    };
+    remoteStore: {
+        backend: LoopRemoteSchedulerBackend;
+        configured: boolean;
+        applySupported: boolean;
+        objectArtifacts: LoopRemoteArtifactStore;
+        mutatesAws: false;
+    };
+    routeAdmission: {
+        stateStore: LoopRouteAdmissionStateStore;
+        activeStatuses: readonly ["admitted", "running"];
+        gates: readonly LoopRouteAdmissionGate[];
+        dryRunEvaluatesLiveCounts: false;
+    };
+}
 type Env = Record<string, string | undefined>;
 export declare function normalizeLoopDeploymentMode(value: string): LoopDeploymentMode;
 export declare function resolveLoopDeploymentMode(env?: Env): LoopModeResolution;

package/dist/lib/mode.js

@@ -2,7 +2,7 @@
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.4.12",
+  version: "0.4.14",
   description: "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   type: "module",
   main: "dist/index.js",
@@ -11,6 +11,7 @@ var package_default = {
     loops: "dist/cli/index.js",
     "loops-daemon": "dist/daemon/index.js",
     "loops-api": "dist/api/index.js",
+    "loops-serve": "dist/serve/index.js",
     "loops-runner": "dist/runner/index.js",
     "loops-mcp": "dist/mcp/index.js"
   },
@@ -23,6 +24,14 @@ var package_default = {
       types: "./dist/sdk/index.d.ts",
       import: "./dist/sdk/index.js"
     },
+    "./sdk/http": {
+      types: "./dist/sdk/http.d.ts",
+      import: "./dist/sdk/http.js"
+    },
+    "./serve": {
+      types: "./dist/serve/index.d.ts",
+      import: "./dist/serve/index.js"
+    },
     "./mcp": {
       types: "./dist/mcp/index.d.ts",
       import: "./dist/mcp/index.js"
@@ -68,7 +77,7 @@ var package_default = {
     "LICENSE"
   ],
   scripts: {
-    build: "rm -rf dist && bun build src/cli/index.ts src/daemon/index.ts src/api/index.ts src/runner/index.ts src/mcp/index.ts src/index.ts src/sdk/index.ts src/lib/store.ts src/lib/mode.ts src/lib/storage/index.ts src/lib/storage/contract.ts src/lib/storage/sqlite.ts src/lib/storage/postgres.ts src/lib/storage/postgres-schema.ts --root src --outdir dist --target bun --packages external && chmod +x dist/cli/index.js dist/daemon/index.js dist/api/index.js dist/runner/index.js dist/mcp/index.js && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",
+    build: "rm -rf dist && bun build src/cli/index.ts src/daemon/index.ts src/api/index.ts src/serve/index.ts src/runner/index.ts src/mcp/index.ts src/index.ts src/sdk/index.ts src/sdk/http.ts src/lib/store.ts src/lib/mode.ts src/lib/storage/index.ts src/lib/storage/contract.ts src/lib/storage/sqlite.ts src/lib/storage/postgres.ts src/lib/storage/postgres-schema.ts --root src --outdir dist --target bun --packages external && chmod +x dist/cli/index.js dist/daemon/index.js dist/api/index.js dist/serve/index.js dist/runner/index.js dist/mcp/index.js && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",
     "build:bin": "bun build src/cli/index.ts --compile --outfile dist/loops",
     typecheck: "tsc --noEmit",
     test: "bun test",
@@ -103,11 +112,13 @@ var package_default = {
     bun: ">=1.0.0"
   },
   dependencies: {
+    "@hasna/contracts": "^0.4.1",
     "@hasna/events": "^0.1.9",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@openrouter/ai-sdk-provider": "2.9.1",
     ai: "6.0.204",
     commander: "^13.1.0",
+    pg: "^8.13.1",
     zod: "4.4.3"
   },
   optionalDependencies: {
@@ -115,6 +126,7 @@ var package_default = {
   },
   devDependencies: {
     "@types/bun": "latest",
+    "@types/pg": "^8.11.10",
     typescript: "^5.7.3"
   },
   publishConfig: {
@@ -193,6 +205,50 @@ function sourceOfTruthForMode(mode) {
     return "self_hosted_control_plane";
   return "cloud_control_plane";
 }
+var ROUTE_ADMISSION_GATES = [
+  "max_dispatch",
+  "max_active",
+  "max_active_per_project",
+  "max_active_per_project_group",
+  "max_active_scope",
+  "max_per_profile"
+];
+function remoteSchedulerBackendForMode(mode, config) {
+  if (mode === "local")
+    return "none";
+  if (mode === "cloud")
+    return config.cloudApiUrl ? "hosted_control_plane_contract" : "unconfigured";
+  if (config.databaseUrlPresent)
+    return "postgres_contract";
+  if (config.apiUrl)
+    return "api_control_plane_contract";
+  return "unconfigured";
+}
+function schedulerStateForMode(args) {
+  const nonLocal = args.deploymentMode !== "local";
+  return {
+    authority: args.sourceOfTruth,
+    localStore: {
+      backend: "sqlite",
+      role: args.localRole,
+      runArtifacts: "local_files",
+      routeAdmissionState: "workflow_work_items"
+    },
+    remoteStore: {
+      backend: remoteSchedulerBackendForMode(args.deploymentMode, args.config),
+      configured: nonLocal && args.controlPlaneConfigured,
+      applySupported: false,
+      objectArtifacts: nonLocal ? "object_store_contract" : "none",
+      mutatesAws: false
+    },
+    routeAdmission: {
+      stateStore: nonLocal ? "control_plane_contract" : "local_sqlite",
+      activeStatuses: ["admitted", "running"],
+      gates: ROUTE_ADMISSION_GATES,
+      dryRunEvaluatesLiveCounts: false
+    }
+  };
+}
 function displayControlPlaneUrl(value) {
   if (!value)
     return;
@@ -218,6 +274,9 @@ function buildDeploymentStatus(opts = {}) {
   if (deploymentMode === "self_hosted" && !controlPlaneConfigured) {
     warnings.push("self_hosted mode needs LOOPS_API_URL or LOOPS_DATABASE_URL before it can become authoritative");
   }
+  if (deploymentMode === "self_hosted" && config.databaseUrlPresent && !config.apiUrl) {
+    warnings.push("LOOPS_DATABASE_URL selects the self_hosted storage contract; loops-runner still needs LOOPS_API_URL to claim remote work");
+  }
   if (deploymentMode === "cloud" && config.apiUrl && !config.cloudApiUrl) {
     warnings.push("LOOPS_API_URL selects self_hosted; cloud mode uses LOOPS_CLOUD_API_URL");
   }
@@ -251,6 +310,13 @@ function buildDeploymentStatus(opts = {}) {
       required: deploymentMode !== "local",
       role: deploymentMode === "local" ? "daemon" : "control_plane_worker"
     },
+    schedulerState: schedulerStateForMode({
+      deploymentMode,
+      sourceOfTruth: sourceOfTruthForMode(deploymentMode),
+      localRole: deploymentMode === "local" ? "authoritative" : "cache_and_spool",
+      controlPlaneConfigured,
+      config
+    }),
     warnings
   };
 }
@@ -263,6 +329,7 @@ function deploymentStatusLine(status) {
     `source=${status.deploymentModeSource}`,
     `truth=${status.sourceOfTruth}`,
     `local=${status.localStore.role}`,
+    `scheduler=${status.schedulerState.routeAdmission.stateStore}`,
     `control_plane=${configured}`
   ].join(" ");
 }

package/dist/lib/scheduler.d.ts

@@ -97,8 +97,8 @@ export declare const MAX_SKIPS_PER_LOOP_PER_TICK = 10;
 /**
  * Exponential retry backoff with jitter:
  * delay = retryDelayMs * 2^(attempt-1) * (0.5 + random), capped at 6h.
- * Failures classified as rate_limit/auth back off 4x harder, since hammering
- * a throttled or misconfigured provider only makes things worse.
+ * Failures classified as provider-gated back off 4x harder, since hammering
+ * a throttled, misconfigured, or unavailable provider only makes things worse.
  */
 export declare function retryBackoffDelayMs(loop: Loop, run: LoopRun, random?: () => number): number;
 export interface AdvanceLoopOptions {
@@ -129,6 +129,9 @@ export declare function executeClaimedRun(deps: {
     beforeFinalize?: (loop: Loop, run: LoopRun) => void;
     daemonLeaseId?: string;
     execute?: (loop: Loop, run: LoopRun) => Promise<ExecutorResult>;
+    finalizeResult?: (result: ExecutorResult, loop: Loop, run: LoopRun) => Omit<ExecutorResult, "status"> & {
+        status: LoopRun["status"];
+    };
     onError?: (loop: Loop, error: unknown) => void;
 }): Promise<LoopRun>;
 export declare function claimDueRuns(deps: SchedulerDeps & {

package/dist/lib/storage/index.d.ts

@@ -2,5 +2,6 @@ export type { AppliedStorageMigration, AuditEventRecord, LoopStorageBackend, Loo
 export { SqliteLoopStorage, createSqliteLoopStorage } from "./sqlite.js";
 export { PostgresStorage, createPostgresStorage } from "./postgres.js";
 export type { PostgresQueryExecutor } from "./postgres.js";
+export { PostgresLoopStorage, createPostgresLoopStorage, NotImplementedError, } from "./postgres-loop-storage.js";
 export { POSTGRES_MIGRATION_LEDGER_TABLE, POSTGRES_STORAGE_MIGRATIONS, checksumStorageSql, } from "./postgres-schema.js";
 export { Store } from "../store.js";