@hasna/loops 0.4.13 → 0.4.22

package/docs/DEPLOYMENT_MODES.md

@@ -5,19 +5,28 @@ defines the mode vocabulary, local cache behavior, API shape, and runner
 contract. Hosted multi-tenant operation is implemented outside this public
 package.
 
+Deployment modes describe **where the OpenLoops runtime stores and executes**
+loops and workflows (`local` SQLite, `self_hosted` control plane, or `cloud`
+contract). They are runtime placement concerns, not the automation product
+surface — specs, queues, approvals, and audit for product automations remain in
+`@hasna/automations` and `@hasna/actions`. See
+[Runtime Boundary](./RUNTIME_BOUNDARY.md).
+
 ## Modes
 
 | Mode | Source of truth | Local storage role | Executor |
 | --- | --- | --- | --- |
 | `local` | SQLite in `LOOPS_DATA_DIR` | Authoritative | `loops-daemon` |
-| `self_hosted` | A user-operated `loops-api` control plane contract | Cache and offline spool | `loops-runner` foundation |
+| `self_hosted` | Hasna-owned AWS/RDS control plane served by `loops-serve`/`loops-api` | Cache and offline spool | `loops-runner` foundation |
 | `cloud` | A configured hosted control plane contract | Cache and offline spool | `loops-runner` foundation |
 
 `local` remains the default. It must keep working without network access,
 tokens, Postgres, or hosted infrastructure.
 
-`self_hosted` is for users or teams running their own control plane. The public
-`@hasna/loops` package owns the API and runner contract for this mode.
+`self_hosted` is the Hasna-owned AWS/RDS control-plane deployment. The public
+`@hasna/loops` package owns `loops-serve`, the embeddable `loops-api` contract,
+the Postgres storage adapter, migrations, HTTP SDK, and runner contract for this
+mode.
 
 `cloud` is the hosted control-plane contract. The public package exposes the
 client and runner contract, but tenant auth, account administration, and hosted
@@ -58,6 +67,8 @@ loops self-hosted runner-register --runner-id <id> --machine-id <machine>
 loops self-hosted runner-register --runner-id <id> --machine-id <machine> --apply
 loops cloud status
 loops-api status
+loops-serve version
+HASNA_LOOPS_DATABASE_URL=... loops-serve migrate --dry-run
 loops-runner status
 loops export --file ./loops-export.json --dry-run
 loops export --file ./loops-export.json
@@ -88,11 +99,12 @@ JSON uses these field names:
 - `schedulerState.localStore`: always names the local SQLite store and local
   run artifact files. In `local` mode this store is authoritative; in
   non-local modes it is a cache, offline spool, and audit copy.
-- `schedulerState.remoteStore`: names the remote scheduler contract:
+- `schedulerState.remoteStore`: names the non-local scheduler contract:
   `api_control_plane_contract`, `postgres_contract`,
   `hosted_control_plane_contract`, `unconfigured`, or `none`. Remote apply is
-  `false` in this public package until a control-plane host wires a full
-  storage adapter.
+  `false` in the standalone CLI until the control-plane API exposes
+  id-preserving import endpoints. `loops-serve` itself wires the Postgres
+  storage adapter for normal control-plane CRUD and runner protocol routes.
 - `schedulerState.remoteStore.objectArtifacts`: `object_store_contract` means
   remote artifact/object storage is a control-plane contract. The public package
   does not create or mutate S3 buckets, AWS resources, or hosted credentials.
@@ -102,13 +114,18 @@ JSON uses these field names:
   Live active counts use admitted/running work items; dry-runs do not open or
   migrate the live store to compute counts.
 
-`loops-api` is a separate process in the same public package. It is not a
-separate package at this stage because self-hosted users and the hosted service
-must share the same public contract. The API server can expose storage-backed
-`/v1` loop CRUD and run listing when an embedding host injects the public
-storage contract. The standalone `loops-api serve` binary still fails closed
-for those routes until a self-hosted storage adapter is wired by the operator or
-platform host.
+`loops-serve` is the self-hosted HTTP control-plane binary in this public
+package. It reads and writes Postgres directly, serves open foundation probes
+(`GET /health`, `/ready`, `/version`, `/openapi.json`), gates `/v1` loop/run and
+runner-protocol routes with API-key auth on non-local binds, and applies the
+Postgres migrations plus the shared `api_keys` table with `loops-serve migrate`.
+
+`loops-api` is the embeddable API contract and local/dev foundation server in
+the same public package. It is not a separate package because self-hosted users
+and the hosted service must share the same public contract. The standalone
+`loops-api serve` path still fails closed for storage-backed routes unless an
+embedding host injects a storage adapter; `loops-serve` is the shipped
+Postgres-backed self-hosted host.
 
 `loops-runner` is the process that connects a machine to a non-local control
 plane. The current public package supports a bounded one-shot protocol:
@@ -166,9 +183,10 @@ would generate new ids, so it is not a no-loss migration. Local SQLite remains
 authoritative until a safe import is applied; in non-local modes it may remain
 a cache, offline spool, and audit copy.
 
-`LOOPS_DATABASE_URL` selects the self-hosted Postgres scheduler-state contract,
-but it does not make the standalone CLI mutate a remote database by itself.
-Remote execution still flows through a configured control-plane API and runner
+`LOOPS_DATABASE_URL` or `HASNA_LOOPS_DATABASE_URL` selects the self-hosted
+Postgres scheduler-state contract and is required by `loops-serve`. It does not
+make the standalone `loops` CLI mutate a remote database by itself. Remote
+execution still flows through a configured control-plane API and runner
 protocol. `loops-runner` needs `LOOPS_API_URL` or `HASNA_LOOPS_API_URL` to claim
 work; a database URL alone is migration/readiness configuration.
 
@@ -203,9 +221,8 @@ mode.
 
 ## Follow-Up Work
 
-Non-local execution needs these follow-up releases before it is live:
+Non-local execution needs these follow-up releases before it is complete:
 
-- A full Postgres control-plane adapter behind the public storage contract.
 - Long-running runner daemon mode with backoff, fleet observability, and
   durable machine registration records.
 - Workflow target execution over the remote protocol.

package/docs/RUNTIME_BOUNDARY.md

@@ -0,0 +1,203 @@
+# OpenLoops Runtime Boundary
+
+OpenLoops is the **runtime, scheduler, and workflow engine** for automations.
+It executes work that external systems have already materialized or explicitly
+handed off. It is **not** the automation domain model: specs, triggers, queue
+ownership, approvals, DLQ/replay, idempotency, and audit evidence live in
+`@hasna/automations`, `@hasna/actions`, and related product packages.
+
+Use this document when you need a single operator-facing boundary reference.
+For the planned upsert/DLQ/strict-mode contract, see
+[`AUTOMATION_RUNTIME_DESIGN.md`](./AUTOMATION_RUNTIME_DESIGN.md). For
+deployment-mode vocabulary (local vs self-hosted vs cloud), see
+[`DEPLOYMENT_MODES.md`](./DEPLOYMENT_MODES.md).
+
+## Ownership Split
+
+| Concern | Owner | OpenLoops role |
+| --- | --- | --- |
+| Automation specs and trigger materialization | `@hasna/automations` | None — do not store specs in OpenLoops |
+| Product automation action queues, leases, DLQ, replay, idempotency, approvals, audit | `@hasna/automations` | Execute claimed actions; complete/fail by action id + runner id |
+| Action compilation and action-target rendering | `@hasna/actions` | Accept planned upsert handoff; do not write SQLite rows directly |
+| Scheduler, daemon, loop/workflow storage | OpenLoops | Authoritative in `local` mode |
+| Workflow invocation, admission, execution, run manifests | OpenLoops | After explicit handoff or todos-task route admission |
+| Provider routing, worktrees, run artifacts | OpenLoops | Bounded by route and template policy |
+| Todos-task route drains (`auto:route`, `route_enabled`, `automation.allowed`) | OpenLoops-native | Opt-in task/event routing — **not** OpenAutomations queue replacement |
+
+The SDK exposes the canonical boundary strings via `openAutomationsRuntimeBinding()`:
+
+```ts
+import { openAutomationsRuntimeBinding } from "@hasna/loops";
+
+const binding = openAutomationsRuntimeBinding();
+// binding.handoff === "claim-queue"
+// binding.queueOwner === "open-automations"
+// binding.runtimeOwner === "open-loops"
+console.log(binding.guarantees);
+console.log(binding.nonGoals);
+```
+
+**Guarantees (summary):**
+
+- OpenAutomations owns automation specs, run materialization, queue state, DLQ,
+  replay, idempotency, and approvals.
+- OpenLoops may execute claimed actions through explicit command or SDK handoff
+  only.
+- OpenLoops may consume exported event envelopes only through explicit
+  `loops routes create` commands.
+- Workers must complete or fail actions by action id and runner id so
+  OpenAutomations can enforce queue leases.
+
+**Non-goals (summary):**
+
+- OpenLoops must not become the OpenAutomations product surface.
+- OpenLoops must not store automation specs or replace the OpenAutomations queue.
+- OpenLoops must not infer automation trigger semantics from event transport
+  alone.
+
+## External Compiler Handoff Paths
+
+External compilers (`@hasna/automations`, `@hasna/actions`, event routers)
+materialize automation intent in their own stores. OpenLoops receives **rendered
+work** through one of the paths below. Do not bypass these boundaries by writing
+OpenLoops SQLite rows from another package.
+
+### 1. OpenAutomations claim-queue (implemented)
+
+OpenAutomations owns the action queue. An OpenLoops worker claims work, runs the
+rendered target, and reports completion back to OpenAutomations.
+
+```bash
+# Worker claims from the OpenAutomations queue
+automations queue claim --runner open-loops:<worker-id>
+
+# After OpenLoops executes the handed-off command/workflow:
+automations queue complete <action-id> --runner open-loops:<worker-id>
+# or on failure:
+automations queue fail <action-id> --runner open-loops:<worker-id> \
+  --code <code> --message <message>
+```
+
+Keep `HASNA_AUTOMATIONS_DIR` pointing at the owning OpenAutomations data root.
+Preserve the runner id in every complete/fail call so OpenAutomations can enforce
+action leases.
+
+SDK reference:
+
+```ts
+const binding = openAutomationsRuntimeBinding();
+console.log(binding.claimCommand);   // "automations queue claim"
+console.log(binding.completeCommand); // "automations queue complete"
+console.log(binding.failCommand);    // "automations queue fail"
+```
+
+### 2. `@hasna/actions` compiler → planned upsert-one-shot (design)
+
+`@hasna/actions` compiles action targets into a fully rendered one-shot workflow
+loop request. The stable handoff is an **idempotent upsert** — not direct
+SQLite access.
+
+**Status:** `loops workflows upsert-one-shot` and the matching SDK method are
+**planned** (see [`AUTOMATION_RUNTIME_DESIGN.md`](./AUTOMATION_RUNTIME_DESIGN.md)).
+The shapes below are the contract target; they are not shipped in this release.
+
+Example request the compiler would send (abbreviated):
+
+```ts
+type WorkflowUpsertRequest = {
+  idempotencyKey: "actions:<action-id>:<version>",
+  source: { kind: "action", id: "<action-id>" },
+  subject: { kind: "repo", path: "/path/to/repo" },
+  workflow: { name: "action-<action-id>", steps: [/* rendered steps */] },
+  loop: { name: "action-<action-id>", schedule: { type: "once", at: "2026-07-01T12:00:00Z" } },
+  mode: "preflight",       // dry-run | preflight | commit
+  dispatch: "schedule",    // schedule | run-now | none
+};
+```
+
+Planned CLI mirror:
+
+```bash
+loops workflows upsert-one-shot ./workflow.json \
+  --idempotency-key actions:<action-id>:<version> \
+  --source-kind action \
+  --source-id <action-id> \
+  --subject-kind repo \
+  --subject-path /path/to/repo \
+  --loop-name action-<action-id> \
+  --at 2026-07-01T12:00:00Z \
+  --mode preflight \
+  --dispatch schedule \
+  --json
+```
+
+OpenLoops returns durable refs (`workflowId`, `loopId`, `runId`, `manifestPath`)
+so `@hasna/actions` can inspect, cancel, or replay without querying SQLite.
+Full semantics (idempotency on `idempotencyKey` + `specHash`, redaction,
+strict-mode policy) are specified in the design doc — not duplicated here.
+
+### 3. Event envelope handoff (implemented, explicit only)
+
+For workflows that should run from a normalized event envelope — **without**
+OpenAutomations materializing automation specs inside OpenLoops — pipe an
+exported envelope into the generic route:
+
+```bash
+automations --json webhooks event <route> --body-json '<json>' \
+  | loops --json routes create generic
+```
+
+This is **not** automation materialization in OpenLoops. OpenAutomations still
+owns deterministic automation specs, webhook normalization, queue state,
+approvals, DLQ, and replay. OpenLoops owns agent workflow invocation after the
+operator routes the envelope to `loops routes create generic`.
+
+```ts
+const { eventHandoff } = openAutomationsRuntimeBinding();
+console.log(eventHandoff.handlerCommand); // "loops routes create generic"
+console.log(eventHandoff.boundary);
+```
+
+## OpenLoops-Native Path: Todos-Task Routes
+
+Todos-task routing is an **OpenLoops-native** admission path. It is separate from
+the OpenAutomations product queue:
+
+```bash
+cat task-created-event.json | loops routes create todos-task \
+  --template task-lifecycle \
+  --worktree-mode required
+```
+
+Tasks must opt in (`auto:route`, `route_enabled=true`, or
+`automation.allowed=true`). OpenLoops admits deduped one-shot workflow loops,
+drains them on a schedule, and writes run manifests under
+`.hasna/loops/runs/<project-slug>/<subject-key>/<run-id>/`.
+
+This path does **not** make OpenAutomations the queue owner for todos task/PR/review
+agent workflows. It also does **not** replace OpenAutomations action queues for
+product automations. Choose the handoff path that matches who owns the queue and
+audit trail for your automation.
+
+See [`USAGE.md`](./USAGE.md) § Templates And Task Events for templates,
+provider rules, and drain examples.
+
+## Anti-Patterns
+
+Do **not**:
+
+- Store automation specs in OpenLoops loop/workflow rows.
+- Infer automation triggers from event transport alone.
+- Replace the OpenAutomations queue with loop/workflow rows.
+- Write OpenLoops SQLite directly from `@hasna/actions` or `@hasna/automations`.
+- Dispatch or paste task prompts into tmux panes from route drains (use headless
+  workflow templates instead).
+
+## Related Docs
+
+- [`AUTOMATION_RUNTIME_DESIGN.md`](./AUTOMATION_RUNTIME_DESIGN.md) — planned
+  upsert SDK, DLQ/replay, strict automation execution mode.
+- [`USAGE.md`](./USAGE.md) — templates, todos-task routes, provider pools.
+- [`DEPLOYMENT_MODES.md`](./DEPLOYMENT_MODES.md) — local/self-hosted/cloud;
+  deployment concerns are runtime placement, not automation product surface.
+- README § OpenAutomations Runtime Binding — short summary and quick references.