@hasna/loops 0.4.13 → 0.4.22

package/dist/lib/cloud/mode.d.ts

@@ -0,0 +1,17 @@
+export type StorageMode = "local" | "cloud";
+/** Deprecated mode aliases that all normalize to `cloud`. */
+export declare const DEPRECATED_STORAGE_MODE_ALIASES: readonly ["remote", "hybrid", "self_hosted"];
+export type Env = Record<string, string | undefined>;
+export interface StorageModeNormalization {
+    mode: StorageMode;
+    /** The deprecated alias that was normalized to `cloud`, if any. */
+    deprecatedAlias: string | null;
+}
+/**
+ * Normalize a raw storage-mode string to the `local | cloud` runtime enum.
+ * Accepts deprecated aliases (`remote`, `hybrid`, `self_hosted`) and maps them
+ * to `cloud`. Throws on any other value.
+ */
+export declare function normalizeStorageMode(value: string): StorageModeNormalization;
+/** Upper-snake env token for an app name, e.g. `todos` -> `TODOS`. */
+export declare function envToken(name: string): string;

package/dist/lib/cloud/resolve.d.ts

@@ -0,0 +1,16 @@
+import { type Env } from "./mode.js";
+import { type HasnaStorageClient } from "./storage.js";
+export type CloudStorageResolution = {
+    transport: "local";
+    client: null;
+} | {
+    transport: "cloud-http";
+    client: HasnaStorageClient;
+    baseUrl: string;
+};
+/**
+ * Resolve whether `name`'s data lives in the cloud (hosted `/v1` API) or the
+ * local store for the current environment. Never returns partially-built cloud
+ * state and never exposes the API key.
+ */
+export declare function resolveCloudStorage(name: string, env?: Env): CloudStorageResolution;

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

@@ -0,0 +1,82 @@
+import type { Env } from "./mode.js";
+import { createClientTransport, type HasnaHttpTransport, type HasnaRequestOptions, type QueryParams } from "./transport.js";
+/** Options for a list() call: filters/pagination as query params. */
+export interface StorageListOptions extends Pick<HasnaRequestOptions, "timeoutMs" | "headers" | "retry" | "signal"> {
+    /** Query params (limit, offset, cursor, filters, ...). */
+    query?: QueryParams;
+}
+/** Options for a get() call. */
+export type StorageGetOptions = Pick<HasnaRequestOptions, "timeoutMs" | "headers" | "retry" | "signal" | "query">;
+/** Options for a create() call. */
+export interface StorageCreateOptions extends Pick<HasnaRequestOptions, "timeoutMs" | "headers" | "retry" | "signal" | "query"> {
+    /**
+     * Idempotency key for the create. Defaults to a fresh UUID so a transparently
+     * retried POST is deduped by the server instead of creating a duplicate. Pass
+     * a stable value to make an app-level operation idempotent across calls.
+     */
+    idempotencyKey?: string;
+}
+/** Options for an update() call. */
+export interface StorageUpdateOptions extends Pick<HasnaRequestOptions, "timeoutMs" | "headers" | "retry" | "signal" | "query"> {
+    /** HTTP verb for the update. Default `PATCH` (partial); use `PUT` for replace. */
+    method?: "PATCH" | "PUT";
+    /** Idempotency key. PUT is idempotent by definition; set this to make PATCH retry-safe too. */
+    idempotencyKey?: string;
+}
+/** Options for a delete() call. */
+export type StorageDeleteOptions = Pick<HasnaRequestOptions, "timeoutMs" | "headers" | "retry" | "signal" | "query">;
+/** Result of a list() call. `items` is the extracted array; `raw` is the full envelope. */
+export interface StorageListResult<T> {
+    items: T[];
+    /** Total count when the server reports one (`total`/`count`), else null. */
+    total: number | null;
+    /** Opaque pagination cursor when the server reports one, else null. */
+    cursor: string | null;
+    /** The full parsed response body (envelope preserved). */
+    raw: unknown;
+}
+/**
+ * The app storage interface, HTTP edition. This is deliberately the same small
+ * CRUD surface a local store exposes, so an app's resolver can return either a
+ * local implementation or this one behind one interface.
+ */
+export interface HasnaStorageClient {
+    /** App slug this client targets. */
+    readonly name: string;
+    /** `<origin>/v1` base URL. */
+    readonly baseUrl: string;
+    /** The underlying HTTP transport (escape hatch for non-CRUD routes). */
+    readonly transport: HasnaHttpTransport;
+    /** List a collection. Returns extracted `items` plus the raw envelope. */
+    list<T = unknown>(resource: string, options?: StorageListOptions): Promise<StorageListResult<T>>;
+    /** Fetch one entity by id. Returns `null` on 404. */
+    get<T = unknown>(resource: string, id: string, options?: StorageGetOptions): Promise<T | null>;
+    /** Create one entity. Retry-safe via an auto `Idempotency-Key`. */
+    create<T = unknown>(resource: string, body: unknown, options?: StorageCreateOptions): Promise<T>;
+    /** Update one entity by id (PATCH by default). */
+    update<T = unknown>(resource: string, id: string, patch: unknown, options?: StorageUpdateOptions): Promise<T>;
+    /** Delete one entity by id. Resolves for 2xx and 404 (already gone). */
+    delete(resource: string, id: string, options?: StorageDeleteOptions): Promise<void>;
+}
+/**
+ * Wrap an HTTP transport with the resource CRUD storage interface. Use this when
+ * you already have a transport (e.g. from `createClientTransport`).
+ */
+export declare function createHasnaStorageClient(name: string, transport: HasnaHttpTransport): HasnaStorageClient;
+/** Result of {@link resolveStorageClient}. */
+export type ResolveStorageClientResult = {
+    transport: "local";
+    client: null;
+} | {
+    transport: "cloud-http";
+    client: HasnaStorageClient;
+};
+/**
+ * The one call an app's storage resolver makes. Reads the client-flip env for
+ * `name`; when it resolves to `cloud-http` (mode=cloud/self_hosted + API_URL +
+ * API_KEY), returns a ready {@link HasnaStorageClient}. Otherwise returns
+ * `{ transport: 'local', client: null }` so the app uses its local store.
+ * Throws if cloud was requested but is misconfigured (so callers never silently
+ * read the wrong dataset).
+ */
+export declare function resolveStorageClient(name: string, env?: Env, overrides?: Parameters<typeof createClientTransport>[2]): ResolveStorageClientResult;

package/dist/lib/cloud/transport.d.ts

@@ -0,0 +1,148 @@
+import { type Env } from "./mode.js";
+import type { StorageMode } from "./mode.js";
+/** Default cloud host template. `<app>` is the app slug. */
+export declare function defaultCloudBaseUrl(name: string): string;
+export interface ClientTransportEnvKeys {
+    /** Mode keys, in precedence order. */
+    modeKeys: string[];
+    /** API base-URL keys, in precedence order. */
+    apiUrlKeys: string[];
+    /** API-key keys, in precedence order. */
+    apiKeyKeys: string[];
+}
+/** Resolve the canonical client-flip env-key spec for an app. */
+export declare function clientTransportEnvKeys(name: string): ClientTransportEnvKeys;
+/** Normalize a base URL to `<origin>/v1` (dropping any trailing slash or existing /v1). */
+export declare function toV1BaseUrl(apiUrl: string): string;
+export type ClientTransportKind = "local" | "cloud-http";
+export interface ClientTransportResolution {
+    /** Where the client should read/write from. */
+    transport: ClientTransportKind;
+    /** Resolved storage mode (`local` | `cloud`). */
+    mode: StorageMode;
+    /** Deprecated mode alias that was normalized (e.g. `self_hosted`), if any. */
+    deprecatedAlias: string | null;
+    /** Env key the mode was read from, or `"default"`. */
+    modeSource: string;
+    /** `<origin>/v1` base for the cloud API when transport is cloud-http, else null. */
+    baseUrl: string | null;
+    /** Env key the API URL came from, `"default"` (host template), or null. */
+    apiUrlSource: string | null;
+    /** Whether an API key is present (value never exposed). */
+    apiKeyPresent: boolean;
+    /** Env key the API key came from, or null. */
+    apiKeySource: string | null;
+    /**
+     * True when the operator asked for cloud but the config is incomplete (no API
+     * key), so we fell back to local. Callers SHOULD treat this as an error rather
+     * than silently reading local data.
+     */
+    misconfigured: boolean;
+    /** Human-readable warning, or null. Never contains secret values. */
+    warning: string | null;
+}
+/**
+ * Resolve how a client should reach an app's data given the environment.
+ *
+ * Precedence for the mode: the first present of `HASNA_<NAME>_STORAGE_MODE`,
+ * `HASNA_<NAME>_MODE`, `<NAME>_STORAGE_MODE`, `<NAME>_MODE`, else `local`.
+ */
+export declare function resolveClientTransport(name: string, env?: Env): ClientTransportResolution;
+/** Thrown when a cloud HTTP request returns a non-2xx status. */
+export declare class HasnaHttpError extends Error {
+    readonly status: number;
+    readonly method: string;
+    readonly path: string;
+    readonly body: unknown;
+    constructor(method: string, path: string, status: number, body: unknown);
+}
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/** Query params for a request. Nullish values are dropped; arrays repeat the key. */
+export type QueryParams = URLSearchParams | Record<string, string | number | boolean | null | undefined | ReadonlyArray<string | number | boolean>>;
+/** Retry policy for transient failures (network errors, timeouts, 5xx, 429). */
+export interface HasnaRetryOptions {
+    /** Max RETRY attempts after the first try. Default 2 (=> up to 3 total tries). */
+    retries?: number;
+    /** Base backoff in ms for exponential backoff. Default 200. */
+    baseDelayMs?: number;
+    /** Backoff ceiling in ms. Default 2000. */
+    maxDelayMs?: number;
+    /** HTTP statuses that trigger a retry. Default 408, 425, 429, 500, 502, 503, 504. */
+    retryStatuses?: number[];
+}
+/** Per-call request options: query, idempotency, timeout, retry, extra headers. */
+export interface HasnaRequestOptions {
+    /** Query string params appended to the URL. */
+    query?: QueryParams;
+    /**
+     * Idempotency key sent as `Idempotency-Key`. When set, unsafe methods (POST)
+     * become safe to retry: the server dedupes replays. Auto-generated for
+     * `create()` in the storage client.
+     */
+    idempotencyKey?: string;
+    /** Override the transport timeout for this call (ms). */
+    timeoutMs?: number;
+    /** Extra headers merged into this call (override transport headers). */
+    headers?: Record<string, string>;
+    /** Override or disable retry for this call. `false` disables retries. */
+    retry?: HasnaRetryOptions | false;
+    /** Caller abort signal, combined with the internal timeout. */
+    signal?: AbortSignal;
+}
+export interface HasnaHttpTransportOptions {
+    /** App slug (for error context / default host). */
+    name: string;
+    /** `<origin>/v1` base. Usually from `resolveClientTransport().baseUrl`. */
+    baseUrl: string;
+    /** The API key (secret). Sent as both `x-api-key` and `Authorization: Bearer`. */
+    apiKey: string;
+    /** Override fetch (tests). Defaults to global fetch. */
+    fetchImpl?: FetchLike;
+    /** Extra headers merged into every request. */
+    headers?: Record<string, string>;
+    /** Per-request timeout in ms. Default 30000. */
+    timeoutMs?: number;
+    /** Default retry policy for all requests. Pass `false` to disable. */
+    retry?: HasnaRetryOptions | false;
+    /** Injectable sleep (tests). Defaults to a real timer. */
+    sleepImpl?: (ms: number) => Promise<void>;
+}
+export interface HasnaHttpTransport {
+    readonly baseUrl: string;
+    request<T = unknown>(method: string, path: string, body?: unknown, opts?: HasnaRequestOptions): Promise<T>;
+    get<T = unknown>(path: string, opts?: HasnaRequestOptions): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown, opts?: HasnaRequestOptions): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown, opts?: HasnaRequestOptions): Promise<T>;
+    patch<T = unknown>(path: string, body?: unknown, opts?: HasnaRequestOptions): Promise<T>;
+    del<T = unknown>(path: string, body?: unknown, opts?: HasnaRequestOptions): Promise<T>;
+}
+/** Append query params to a `/v1`-relative path (no-op when empty). */
+export declare function appendQuery(path: string, query?: QueryParams): string;
+/**
+ * Build an authenticated HTTP transport for an app's cloud `/v1` API. Sends the
+ * API key on every request as BOTH `x-api-key` and `Authorization: Bearer`
+ * (serve apps accept either), returns parsed JSON, times out, and retries
+ * transient failures with exponential backoff + jitter. Never logs the key.
+ *
+ * Retry safety: idempotent methods (GET/HEAD/PUT/DELETE/OPTIONS) are always
+ * retried on transient failure; POST/PATCH are retried ONLY when an
+ * `Idempotency-Key` is supplied, so replays can't create duplicates.
+ */
+export declare function createHasnaHttpTransport(options: HasnaHttpTransportOptions): HasnaHttpTransport;
+/**
+ * Convenience: resolve transport from env and, when cloud-http, build the HTTP
+ * client in one call. Returns `{ transport: 'local', resolution }` for local, or
+ * `{ transport: 'cloud-http', client, resolution }` for cloud. Throws if the
+ * config is `misconfigured` (cloud requested but unusable) so callers can't drift
+ * onto local data by accident.
+ */
+export declare function createClientTransport(name: string, env?: Env, overrides?: Partial<Pick<HasnaHttpTransportOptions, "fetchImpl" | "headers" | "timeoutMs" | "retry" | "sleepImpl">>): {
+    transport: "local";
+    client: null;
+    resolution: ClientTransportResolution;
+} | {
+    transport: "cloud-http";
+    client: HasnaHttpTransport;
+    resolution: ClientTransportResolution;
+};
+export {};

package/dist/lib/format.d.ts

@@ -1,4 +1,4 @@
-import type { ExecutorResult, Goal, GoalRun, Loop, LoopRun, WorkflowEvent, WorkflowInvocation, WorkflowRun, WorkflowSpec, WorkflowStepRun, WorkflowWorkItem } from "../types.js";
+import type { ExecutorResult, Goal, GoalRun, Loop, LoopRun, RunReceipt, WorkflowEvent, WorkflowInvocation, WorkflowRun, WorkflowSpec, WorkflowStepRun, WorkflowWorkItem } from "../types.js";
 export declare function redact(value: string | undefined, visible?: number): string | undefined;
 export declare function textOutputBlocks(value: Pick<LoopRun | WorkflowStepRun, "stdout" | "stderr">, opts?: {
     indent?: string;
@@ -7,6 +7,7 @@ export declare function publicLoop(loop: Loop): Record<string, unknown>;
 export declare function publicRun(run: LoopRun, showOutput?: boolean, opts?: {
     redactError?: boolean;
 }): Record<string, unknown>;
+export declare function publicRunReceipt(receipt: RunReceipt): Record<string, unknown>;
 export declare function publicExecutorResult(result: ExecutorResult, showOutput?: boolean): Record<string, unknown>;
 export declare function publicWorkflow(workflow: WorkflowSpec): Record<string, unknown>;
 export declare function publicWorkflowRun(run: WorkflowRun): Record<string, unknown>;

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/migration.d.ts

@@ -104,6 +104,46 @@ export declare function validateLoopsMigrationBundle(value: unknown): LoopsMigra
 export declare function buildImportMigrationPlan(store: Store, bundle: LoopsMigrationBundle, opts?: ImportLoopsMigrationOptions): LoopsMigrationPlan;
 export declare function applyImportMigrationBundle(store: Store, bundle: LoopsMigrationBundle, opts?: ImportLoopsMigrationOptions): ApplyLoopsMigrationResult;
 export declare function buildSelfHostedMigrationPlan(store: Store, opts: SelfHostedPlanOptions): Promise<LoopsMigrationPlan>;
+export interface SelfHostedPushOptions {
+    apiUrl?: string;
+    apiToken?: string;
+    includeRuns?: boolean;
+    replace?: boolean;
+    fetchImpl?: typeof fetch;
+    env?: NodeJS.ProcessEnv;
+    /** Max rows per workflow/loop batch (default 200). */
+    batchRows?: number;
+    /** Approx max JSON bytes per run batch (default 4 MiB). */
+    runBatchBytes?: number;
+    onProgress?: (event: {
+        phase: "workflows" | "loops" | "runs";
+        sent: number;
+        requests: number;
+    }) => void;
+}
+export interface SelfHostedPushResult {
+    ok: boolean;
+    apiUrl: string;
+    applied: {
+        workflows: number;
+        loops: number;
+        runs: number;
+    };
+    skipped: {
+        runningRuns: number;
+        orphanRuns: number;
+    };
+    requests: number;
+}
+/**
+ * Apply a local->self-hosted backfill through the control plane's id-preserving
+ * `/v1/import` endpoint. Rows are pushed FK-safe (workflows, loops, then runs).
+ * Runs are streamed in bounded pages so a busy host's multi-hundred-MB run
+ * history never loads into memory at once; volatile `running` runs and orphan
+ * runs (whose parent loop is absent) are dropped and counted. Idempotent: the
+ * endpoint upserts by id, so re-running never duplicates rows.
+ */
+export declare function applySelfHostedPush(store: Store, opts: SelfHostedPushOptions): Promise<SelfHostedPushResult>;
 export declare function registerSelfHostedRunner(opts: RunnerRegistrationOptions): Promise<RunnerRegistrationResult>;
 export declare function publicMigrationBundle(bundle: LoopsMigrationBundle): Record<string, unknown>;
 export declare function selfHostedControlPlaneSummary(env?: NodeJS.ProcessEnv): Record<string, unknown>;

package/dist/lib/mode.js

@@ -2,7 +2,7 @@
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.4.13",
+  version: "0.4.22",
   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",
@@ -108,13 +117,16 @@ var package_default = {
     "@openrouter/ai-sdk-provider": "2.9.1",
     ai: "6.0.204",
     commander: "^13.1.0",
+    pg: "^8.13.1",
     zod: "4.4.3"
   },
   optionalDependencies: {
-    "@hasna/machines": "0.0.49"
+    "@hasna/machines": "0.0.49",
+    "@hasna/contracts": "^0.4.2"
   },
   devDependencies: {
     "@types/bun": "latest",
+    "@types/pg": "^8.11.10",
     typescript: "^5.7.3"
   },
   publishConfig: {

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

@@ -9,6 +9,7 @@ export { eventData, eventMetadata, objectField, slugSegment, stableHash, stableS
 export { routeCursorKey, selectRouteItems, writeRouteCursor, writeRouteEvidence, type RouteSelection } from "./cursors.js";
 export { GateError, normalizeLoopTargetForStorage, normalizeWorkflowForStorage, preflightLoopTarget, preflightStoredWorkflow, workflowBodyFromFile, workflowSpecForPreflight, } from "./gates.js";
 export { accountPoolFromOpts, normalizeAgentProvider, permissionModeFromOpts, providerAuthProfileFromOpts, providerRoutingPublic, resolveProviderRouting, roleAccountFromOpts, sandboxFromOpts, SUPPORTED_AGENT_PROVIDERS, type ProviderRoutingDecision, } from "./provider.js";
+export { checkProviderAdmission, parseCodewithAdmissionDiagnostics, providerActiveCapFromOpts, providerAdmissionPlanFromOpts, type CodewithAdmissionDiagnostics, type ProviderAdmissionDecision, type ProviderAdmissionPlan, } from "./provider-admission.js";
 export { prReviewRoutingDecision, type PrReviewRoutingDecision } from "./pr-review.js";
 export { hasThrottleLimits, normalizeRoutePath, routeThrottleDecision, routeThrottleLimitsFromOpts, type RouteThrottleDecision, type RouteThrottleLimits, } from "./throttle.js";
 export { generatedRouteSandboxPreflight, readEventEnvelopeInput, routeEventByKind, routeGenericEvent, routeTodosTaskEvent, todosTaskRouteTemplateId, } from "./route-event.js";
@@ -16,3 +17,4 @@ export { drainTodosTaskRoutes, type DrainResult } from "./drain.js";
 export { buildHygieneRouteTasks, parseHygieneChecks, taskAutoRoute, upsertRouteTasks, type HygieneCheckKind, type HygieneRouteTask, type RouteTaskSpec, type UpsertRouteTasksOptions, } from "./route-tasks.js";
 export { defaultLoopsProject, ensureTodosTaskList, runLocalCommand, runLocalCommandWithStdoutFile } from "./todos-cli.js";
 export { addAgentRoutingOptions, addRouteEventOptions, addTodosDrainOptions, routeDrainArgs, type AgentRoutingOptionConfig } from "./options.js";
+export { applyRoutePolicyToDrainOptions, applyRoutePolicyToScheduleOptions, getRoutePolicy, listRoutePolicies, renderRoutePolicy, routePolicyEvidenceFromOptions, validateRoutePolicy, type RoutePolicyDefinition, type RoutePolicyId, type RoutePolicyRender, } from "./policies.js";

package/dist/lib/route/policies.d.ts

@@ -0,0 +1,51 @@
+import type { TodosDrainOptions } from "./types.js";
+/** Named route-drain policies keep recurring task routes auditable and replayable. */
+export type RoutePolicyId = "repoops-pr-queue" | "oss" | "pilot" | "machine-sync";
+export type RoutePolicySafety = "unattended" | "manual-break-glass";
+export interface RoutePolicySchedule {
+    every?: string;
+    cron?: string;
+    at?: string;
+    dynamic?: boolean;
+    catchUp?: string;
+    catchUpLimit?: string;
+    overlap?: string;
+    attempts?: string;
+    retryDelay?: string;
+    lease?: string;
+}
+export interface RoutePolicyGuard {
+    kind: string;
+    description: string;
+    [key: string]: unknown;
+}
+export interface RoutePolicyDefinition {
+    id: RoutePolicyId;
+    title: string;
+    description: string;
+    routeKind: "todos-task";
+    safety: RoutePolicySafety;
+    source: string;
+    aliases?: string[];
+    drain: Partial<TodosDrainOptions>;
+    schedule: RoutePolicySchedule;
+    guards?: RoutePolicyGuard[];
+    notes?: string[];
+    requiresExplicitOptions?: Array<keyof TodosDrainOptions>;
+}
+export interface RoutePolicyRender {
+    policy: RoutePolicyDefinition;
+    drain: Partial<TodosDrainOptions>;
+    schedule: RoutePolicySchedule;
+    args: string[];
+    command: string;
+}
+export declare function listRoutePolicies(): RoutePolicyDefinition[];
+export declare function getRoutePolicy(idOrAlias: string | undefined): RoutePolicyDefinition | undefined;
+export declare function applyRoutePolicyToDrainOptions<T extends TodosDrainOptions>(opts: T, applyOpts?: {
+    requireExplicitSafety?: boolean;
+}): T;
+export declare function applyRoutePolicyToScheduleOptions<T extends TodosDrainOptions & Record<string, unknown>>(opts: T): T;
+export declare function routePolicyEvidenceFromOptions(opts: TodosDrainOptions): Record<string, unknown> | undefined;
+export declare function renderRoutePolicy(idOrAlias: string): RoutePolicyRender;
+export declare function validateRoutePolicy(idOrAlias: string): RoutePolicyRender;

package/dist/lib/route/provider-admission.d.ts

@@ -0,0 +1,37 @@
+import type { AgentProvider } from "../../types.js";
+import type { TodosTaskRouteOptions } from "./types.js";
+/** Provider-native admission checks for routes that create background agents. */
+export interface CodewithAdmissionDiagnostics {
+    activeRunCount?: number;
+    maxActiveRunsPerUser?: number;
+    availableActiveRunSlots?: number;
+}
+export interface ProviderAdmissionPlan {
+    provider: AgentProvider;
+    authProfile?: string;
+    authProfiles?: Array<string | undefined>;
+    activeCap?: number;
+    admissionCheck: boolean;
+}
+export interface ProviderAdmissionDecision {
+    allowed: boolean;
+    provider: AgentProvider;
+    checked: boolean;
+    check: "codewith-agent-diagnostics" | "unsupported-provider" | "dry-run";
+    reason?: string;
+    authProfile?: string;
+    authProfiles?: string[];
+    activeCap?: number;
+    fatal?: boolean;
+    diagnostics?: CodewithAdmissionDiagnostics | Record<string, unknown>;
+}
+export declare function parseCodewithAdmissionDiagnostics(stdout: string): CodewithAdmissionDiagnostics;
+export declare function providerActiveCapFromOpts(opts: Pick<TodosTaskRouteOptions, "providerActiveCap" | "codewithActiveCap">): number | undefined;
+export declare function providerAdmissionPlanFromOpts(opts: TodosTaskRouteOptions, args: {
+    provider: AgentProvider;
+    authProfile?: string;
+    authProfiles?: Array<string | undefined>;
+}): ProviderAdmissionPlan | undefined;
+export declare function providerAdmissionPlanWithAuthProfiles(plan: ProviderAdmissionPlan | undefined, authProfiles: Array<string | undefined>): ProviderAdmissionPlan | undefined;
+export declare function providerAdmissionDryRunPreview(plan: ProviderAdmissionPlan | undefined): ProviderAdmissionDecision | undefined;
+export declare function checkProviderAdmission(plan: ProviderAdmissionPlan | undefined): ProviderAdmissionDecision | undefined;

package/dist/lib/route/throttle.d.ts

@@ -2,8 +2,10 @@ import type { Store } from "../store.js";
 /** Active-workflow admission throttles and canonical project-path handling. */
 export interface RouteThrottleLimits {
     maxActive?: number;
+    maxActiveScope?: string;
     maxActivePerProject?: number;
     maxActivePerProjectGroup?: number;
+    maxPerProfile?: number;
 }
 export interface RouteThrottleDecision {
     allowed: boolean;
@@ -19,8 +21,10 @@ export interface RouteThrottleDecision {
 }
 export declare function routeThrottleLimitsFromOpts(opts: {
     maxActive?: string;
+    maxActiveScope?: string;
     maxActivePerProject?: string;
     maxActivePerProjectGroup?: string;
+    maxPerProfile?: string;
 }): RouteThrottleLimits;
 export declare function hasThrottleLimits(limits: RouteThrottleLimits): boolean;
 export declare function normalizeRoutePath(value: string | undefined): string | undefined;

package/dist/lib/route/types.d.ts

@@ -2,6 +2,9 @@
 export interface TodosTaskRouteOptions {
     eventFile?: string;
     eventJson?: string;
+    policy?: string;
+    preset?: string;
+    routePolicyEvidence?: string;
     template?: string;
     provider?: string;
     providerRule?: string[];
@@ -33,6 +36,9 @@ export interface TodosTaskRouteOptions {
     maxActivePerProject?: string;
     maxActivePerProjectGroup?: string;
     maxActiveScope?: string;
+    providerActiveCap?: string;
+    codewithActiveCap?: string;
+    providerAdmissionCheck?: boolean;
     maxPerProfile?: string;
     worktreeMode?: string;
     worktreeRoot?: string;
@@ -86,6 +92,8 @@ export interface TodosDrainOptions extends TodosTaskRouteOptions {
     limit?: string;
     scanLimit?: string;
     maxDispatch?: string;
+    launchGate?: string;
+    launchGateBlocker?: string[];
     evidenceDir?: string;
     compact?: boolean;
 }