@hasna/loops 0.4.12 → 0.4.14

package/dist/api/index.js

@@ -3,7 +3,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",
@@ -12,6 +12,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"
   },
@@ -24,6 +25,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"
@@ -69,7 +78,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",
@@ -104,11 +113,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: {
@@ -116,6 +127,7 @@ var package_default = {
   },
   devDependencies: {
     "@types/bun": "latest",
+    "@types/pg": "^8.11.10",
     typescript: "^5.7.3"
   },
   publishConfig: {
@@ -194,6 +206,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;
@@ -219,6 +275,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");
   }
@@ -252,6 +311,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
   };
 }
@@ -264,6 +330,7 @@ function deploymentStatusLine(status) {
     `source=${status.deploymentModeSource}`,
     `truth=${status.sourceOfTruth}`,
     `local=${status.localStore.role}`,
+    `scheduler=${status.schedulerState.routeAdmission.stateStore}`,
     `control_plane=${configured}`
   ].join(" ");
 }
@@ -760,8 +827,639 @@ function scrubSecretsDeep(value) {
   }
   return value;
 }
+// openapi/loops.json
+var loops_default = {
+  openapi: "3.1.0",
+  info: {
+    title: "OpenLoops",
+    version: "0.4.14",
+    description: "OpenLoops self-hosted control-plane HTTP API (loops-serve). RDS-direct (Amendment A1). All /v1 routes require an API key (x-api-key or Authorization: Bearer) with a loops:* scope."
+  },
+  servers: [
+    {
+      url: "https://loops.hasna.xyz"
+    }
+  ],
+  paths: {
+    "/health": {
+      get: {
+        operationId: "healthCheck",
+        summary: "Liveness probe",
+        responses: {
+          "200": {
+            description: "alive",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/Foundation"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/ready": {
+      get: {
+        operationId: "readyCheck",
+        summary: "Readiness probe (storage reachable + migrated)",
+        responses: {
+          "200": {
+            description: "ready",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/Foundation"
+                }
+              }
+            }
+          },
+          "503": {
+            description: "not ready",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/Foundation"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/version": {
+      get: {
+        operationId: "getVersion",
+        summary: "Service version",
+        responses: {
+          "200": {
+            description: "version",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/Foundation"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/loops": {
+      get: {
+        operationId: "listLoops",
+        summary: "List loops",
+        parameters: [
+          {
+            name: "status",
+            in: "query",
+            required: false,
+            schema: {
+              type: "string",
+              enum: [
+                "active",
+                "paused",
+                "stopped",
+                "expired"
+              ]
+            }
+          },
+          {
+            name: "limit",
+            in: "query",
+            required: false,
+            schema: {
+              type: "integer"
+            }
+          },
+          {
+            name: "includeArchived",
+            in: "query",
+            required: false,
+            schema: {
+              type: "boolean"
+            }
+          },
+          {
+            name: "archived",
+            in: "query",
+            required: false,
+            schema: {
+              type: "boolean"
+            }
+          }
+        ],
+        responses: {
+          "200": {
+            description: "loops",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/LoopListResponse"
+                }
+              }
+            }
+          }
+        }
+      },
+      post: {
+        operationId: "createLoop",
+        summary: "Create a loop",
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                $ref: "#/components/schemas/CreateLoopInput"
+              }
+            }
+          }
+        },
+        responses: {
+          "201": {
+            description: "created",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/LoopResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/loops/{id}": {
+      get: {
+        operationId: "getLoop",
+        summary: "Get a loop by id",
+        parameters: [
+          {
+            name: "id",
+            in: "path",
+            required: true,
+            schema: {
+              type: "string"
+            }
+          }
+        ],
+        responses: {
+          "200": {
+            description: "loop",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/LoopResponse"
+                }
+              }
+            }
+          }
+        }
+      },
+      patch: {
+        operationId: "updateLoop",
+        summary: "Update a loop (status / schedule fields)",
+        parameters: [
+          {
+            name: "id",
+            in: "path",
+            required: true,
+            schema: {
+              type: "string"
+            }
+          }
+        ],
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                $ref: "#/components/schemas/UpdateLoopInput"
+              }
+            }
+          }
+        },
+        responses: {
+          "200": {
+            description: "loop",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/LoopResponse"
+                }
+              }
+            }
+          }
+        }
+      },
+      delete: {
+        operationId: "deleteLoop",
+        summary: "Delete a loop",
+        parameters: [
+          {
+            name: "id",
+            in: "path",
+            required: true,
+            schema: {
+              type: "string"
+            }
+          }
+        ],
+        responses: {
+          "200": {
+            description: "deleted",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/DeleteResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/loops/{id}/archive": {
+      post: {
+        operationId: "archiveLoop",
+        summary: "Archive a loop",
+        parameters: [
+          {
+            name: "id",
+            in: "path",
+            required: true,
+            schema: {
+              type: "string"
+            }
+          }
+        ],
+        responses: {
+          "200": {
+            description: "loop",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/LoopResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/loops/{id}/unarchive": {
+      post: {
+        operationId: "unarchiveLoop",
+        summary: "Unarchive a loop",
+        parameters: [
+          {
+            name: "id",
+            in: "path",
+            required: true,
+            schema: {
+              type: "string"
+            }
+          }
+        ],
+        responses: {
+          "200": {
+            description: "loop",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/LoopResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/runs": {
+      get: {
+        operationId: "listRuns",
+        summary: "List runs",
+        parameters: [
+          {
+            name: "loopId",
+            in: "query",
+            required: false,
+            schema: {
+              type: "string"
+            }
+          },
+          {
+            name: "status",
+            in: "query",
+            required: false,
+            schema: {
+              type: "string"
+            }
+          },
+          {
+            name: "limit",
+            in: "query",
+            required: false,
+            schema: {
+              type: "integer"
+            }
+          }
+        ],
+        responses: {
+          "200": {
+            description: "runs",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/RunListResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/runs/{id}": {
+      get: {
+        operationId: "getRun",
+        summary: "Get a run by id",
+        parameters: [
+          {
+            name: "id",
+            in: "path",
+            required: true,
+            schema: {
+              type: "string"
+            }
+          }
+        ],
+        responses: {
+          "200": {
+            description: "run",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/RunResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  components: {
+    schemas: {
+      Foundation: {
+        type: "object",
+        properties: {
+          status: {
+            type: "string"
+          },
+          version: {
+            type: "string"
+          },
+          mode: {
+            type: "string"
+          },
+          service: {
+            type: "string"
+          },
+          detail: {
+            type: "string"
+          }
+        },
+        required: [
+          "status",
+          "version",
+          "mode"
+        ]
+      },
+      Loop: {
+        type: "object",
+        properties: {
+          id: {
+            type: "string"
+          },
+          name: {
+            type: "string"
+          },
+          description: {
+            type: "string",
+            nullable: true
+          },
+          status: {
+            type: "string"
+          },
+          schedule: {
+            type: "object",
+            additionalProperties: true
+          },
+          target: {
+            type: "object",
+            additionalProperties: true
+          },
+          nextRunAt: {
+            type: "string",
+            nullable: true
+          },
+          createdAt: {
+            type: "string"
+          },
+          updatedAt: {
+            type: "string"
+          }
+        },
+        required: [
+          "id",
+          "name",
+          "status"
+        ]
+      },
+      CreateLoopInput: {
+        type: "object",
+        properties: {
+          name: {
+            type: "string"
+          },
+          description: {
+            type: "string"
+          },
+          schedule: {
+            type: "object",
+            additionalProperties: true
+          },
+          target: {
+            type: "object",
+            additionalProperties: true
+          }
+        },
+        required: [
+          "name",
+          "schedule",
+          "target"
+        ]
+      },
+      UpdateLoopInput: {
+        type: "object",
+        properties: {
+          status: {
+            type: "string",
+            enum: [
+              "active",
+              "paused",
+              "stopped",
+              "expired"
+            ]
+          },
+          nextRunAt: {
+            type: "string",
+            nullable: true
+          },
+          retryScheduledFor: {
+            type: "string",
+            nullable: true
+          },
+          expiresAt: {
+            type: "string",
+            nullable: true
+          }
+        }
+      },
+      Run: {
+        type: "object",
+        properties: {
+          id: {
+            type: "string"
+          },
+          loopId: {
+            type: "string"
+          },
+          status: {
+            type: "string"
+          },
+          attempt: {
+            type: "integer"
+          },
+          scheduledFor: {
+            type: "string"
+          },
+          startedAt: {
+            type: "string",
+            nullable: true
+          },
+          finishedAt: {
+            type: "string",
+            nullable: true
+          }
+        },
+        required: [
+          "id",
+          "loopId",
+          "status"
+        ]
+      },
+      LoopResponse: {
+        type: "object",
+        properties: {
+          ok: {
+            type: "boolean"
+          },
+          loop: {
+            $ref: "#/components/schemas/Loop"
+          }
+        },
+        required: [
+          "ok",
+          "loop"
+        ]
+      },
+      LoopListResponse: {
+        type: "object",
+        properties: {
+          ok: {
+            type: "boolean"
+          },
+          loops: {
+            type: "array",
+            items: {
+              $ref: "#/components/schemas/Loop"
+            }
+          }
+        },
+        required: [
+          "ok",
+          "loops"
+        ]
+      },
+      RunResponse: {
+        type: "object",
+        properties: {
+          ok: {
+            type: "boolean"
+          },
+          run: {
+            $ref: "#/components/schemas/Run"
+          }
+        },
+        required: [
+          "ok",
+          "run"
+        ]
+      },
+      RunListResponse: {
+        type: "object",
+        properties: {
+          ok: {
+            type: "boolean"
+          },
+          runs: {
+            type: "array",
+            items: {
+              $ref: "#/components/schemas/Run"
+            }
+          }
+        },
+        required: [
+          "ok",
+          "runs"
+        ]
+      },
+      DeleteResponse: {
+        type: "object",
+        properties: {
+          ok: {
+            type: "boolean"
+          },
+          deleted: {
+            type: "boolean"
+          }
+        },
+        required: [
+          "ok",
+          "deleted"
+        ]
+      }
+    },
+    securitySchemes: {
+      apiKey: {
+        type: "apiKey",
+        in: "header",
+        name: "x-api-key"
+      }
+    }
+  },
+  security: [
+    {
+      apiKey: []
+    }
+  ]
+};
 
 // src/api/index.ts
+function openApiDocument() {
+  return { ...loops_default, info: { ...loops_default.info, version: packageVersion() } };
+}
 var program = new Command;
 var DEFAULT_BODY_LIMIT_BYTES = 64 * 1024;
 var DEFAULT_EVIDENCE_LIMIT_BYTES = 256 * 1024;
@@ -811,21 +1509,62 @@ function apiStatus() {
     status: buildDeploymentStatus({ perspective: "self_hosted" })
   };
 }
+function foundationMode() {
+  return buildDeploymentStatus({}).activeDeploymentMode;
+}
+function foundationEnvelope(status, extra = {}) {
+  return { status, version: packageVersion(), mode: foundationMode(), service: "loops", ...extra };
+}
 function createLoopsApiServer(opts = {}) {
   const host = opts.host ?? "127.0.0.1";
   const port = opts.port ?? 8787;
-  if (!isLocalBind(host) && !configuredAuthToken()) {
-    throw new Error("non-local loops-api binds require LOOPS_API_TOKEN or HASNA_LOOPS_API_TOKEN");
+  if (!isLocalBind(host) && !opts.authenticator && !configuredAuthToken()) {
+    throw new Error("non-local loops-serve binds require an API-key authenticator or LOOPS_API_TOKEN");
   }
+  const defaultReady = async () => {
+    if (!opts.storage)
+      return { ready: false, detail: "storage_unconfigured" };
+    try {
+      await opts.storage.listLoops({ limit: 1 });
+      return { ready: true };
+    } catch (error) {
+      return { ready: false, detail: error instanceof Error ? error.message : "storage_unreachable" };
+    }
+  };
+  const readyCheck = opts.readyCheck ?? defaultReady;
   return Bun.serve({
     hostname: host,
     port,
-    fetch(request) {
-      const unauthorized = authorizeRequest(request, host);
-      if (unauthorized)
-        return unauthorized;
+    idleTimeout: 60,
+    async fetch(request) {
       const url = new URL(request.url);
-      if (url.pathname === "/health" || url.pathname === "/status") {
+      if (request.method === "GET" && (url.pathname === "/health" || url.pathname === "/healthz")) {
+        return Response.json(foundationEnvelope("ok"));
+      }
+      if (request.method === "GET" && (url.pathname === "/version" || url.pathname === "/v1/version")) {
+        return Response.json(foundationEnvelope("ok"));
+      }
+      if (request.method === "GET" && (url.pathname === "/ready" || url.pathname === "/readyz")) {
+        const result = await readyCheck();
+        return Response.json(foundationEnvelope(result.ready ? "ready" : "not_ready", result.detail ? { detail: result.detail } : {}), { status: result.ready ? 200 : 503 });
+      }
+      if (request.method === "GET" && url.pathname === "/openapi.json") {
+        return Response.json(openApiDocument());
+      }
+      if (opts.authenticator) {
+        const decision = await opts.authenticator.authenticate(request.headers, {
+          method: request.method,
+          path: url.pathname
+        });
+        if (!decision.ok) {
+          return Response.json({ ok: false, error: decision.reason ?? "unauthorized", message: decision.message }, { status: decision.status || 401 });
+        }
+      } else {
+        const unauthorized = authorizeRequest(request, host);
+        if (unauthorized)
+          return unauthorized;
+      }
+      if (request.method === "GET" && url.pathname === "/status") {
         return Response.json(apiStatus());
       }
       return handleV1Request({
@@ -1286,13 +2025,14 @@ program.command("serve").description("serve the foundation health/status endpoin
   const server = createLoopsApiServer({ host, port });
   console.log(`loops-api listening on http://${server.hostname}:${server.port}`);
 });
-if (import.meta.main) {
+if (import.meta.main && (import.meta.url.endsWith("api/index.ts") || import.meta.url.endsWith("api/index.js"))) {
   main().catch((error) => {
     console.error(error instanceof Error ? error.message : String(error));
     process.exit(1);
   });
 }
 export {
+  openApiDocument,
   main,
   createLoopsApiServer,
   apiStatus