@nightowlsdev/storage-supabase 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Night Owls contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# @nightowlsdev/storage-supabase
+
+A Supabase/Postgres-backed `StorageAdapter` for `@nightowlsdev/core` — implements the
+`agents` / `runs` / `events` / `messages` seams, a redacted Realtime broadcast event
+bus (`events.subscribe`), and a Postgres-backed Mastra store for cross-process durable
+suspend/resume.
+
+The server adapter authenticates with the **secret** key (`BYPASSRLS`) and is the real
+authorization boundary — it scopes every query by `tenantId`/`org_id` in code. The SQL
+RLS in the packaged `0001_core` migration is defense-in-depth for the browser /
+Realtime read path only.
+
+The tables live in a dedicated **`owl`** schema with **bare names**
+(`nightowls.orgs`, `nightowls.runs`, `nightowls.events`, `nightowls.agents`, …). The adapter pool
+sets `search_path=nightowls,public`, so the adapter's own queries stay unqualified. The
+schema + tables are created by this package's **inlined migrations** (`MIGRATIONS`),
+which `@nightowlsdev/cli` **installs** into your host's `supabase/migrations/` — you apply them
+with your own tooling (`supabase db push`). Night Owls never runs DDL itself.
+
+## Connection rules
+
+### Use the Session/Direct pooler port (5432) — NEVER the Transaction pooler (6543)
+
+`pg` and `@mastra/pg` rely on prepared statements, which **break on the Transaction
+pooler (port 6543)**. Always pass the **Session/Direct** Postgres URL (port **5432**).
+Both `createSupabaseStorage` and `createMastraPgStore` throw if they detect `:6543` in
+the `dbUrl`.
+
+```
+✅  postgresql://…@db.<ref>.supabase.co:5432/postgres   (Session/Direct)
+❌  postgresql://…@…pooler.supabase.com:6543/postgres    (Transaction — breaks pg)
+```
+
+### Two keys, two roles
+
+| Key | Where it goes | Why |
+|---|---|---|
+| **secret** (`sb_secret_…` / `service_role`) | the server **adapter** (`secretKey`) | `BYPASSRLS`; the real authz boundary. Never ships to the browser. |
+| **publishable** (`sb_publishable_…` / `anon`) | the **browser / Realtime** client | RLS-gated; used by the host app to subscribe to `run:<id>` broadcasts as the end user. |
+
+The adapter is server-only. The publishable key is for the host app's browser Realtime
+subscription, which the defense-in-depth RLS policy (`members_receive_run_events`)
+gates by org membership.
+
+## Applying the schema: install via `@nightowlsdev/cli`
+
+This package ships its migrations **inlined** (`MIGRATIONS`: `{ version, name, sql }[]`,
+fully-qualified `nightowls.*`) and exports the `nightOwlsPlugin` manifest that `@nightowlsdev/cli`
+discovers. You don't apply them from this package — instead the CLI **installs** them into
+your host's classic `supabase/migrations/`, and you apply them with your own tooling:
+
+```bash
+owl install storage-supabase   # installs the migrations into supabase/migrations/
+supabase db push                  # apply them (your tooling — Night Owls never runs DDL)
+```
+
+The install writes one `<timestamp>_corale_<version>.sql` per migration and is idempotent
+(already-installed versions are skipped). `owl db install` re-installs after an upgrade.
+
+## Mastra durable resume: `disableInit:true` + the `0002_mastra` migration
+
+On an RLS-enabled Supabase project you do **not** want `PostgresStore` to run its own
+DDL/init at runtime. `createMastraPgStore` defaults to `disableInit: true` and passes
+`schemaName: 'nightowls'`, so the `nightowls.mastra_*` tables **must pre-exist**. They are
+created by the packaged `0002_mastra` migration (the real `@mastra/pg` DDL via
+`exportSchemas('nightowls')`), including the resume-critical
+`nightowls.mastra_workflow_snapshot`. The installed migrations (above) create them.
+
+## Usage
+
+```ts
+import {
+  createSupabaseStorage,
+  createMastraPgStore,
+  publishAgentVersion,
+} from "@nightowlsdev/storage-supabase";
+import { SwarmEngine, allowListModelProvider } from "@nightowlsdev/core";
+
+const storage = createSupabaseStorage({
+  url: process.env.SUPABASE_URL!,        // API_URL — for supabase-js Realtime
+  secretKey: process.env.SUPABASE_SECRET_KEY!, // sb_secret_… / service_role (BYPASSRLS)
+  dbUrl: process.env.SUPABASE_DB_URL!,   // Session/Direct Postgres URL (port 5432)
+  // ssl defaults to `true` (verify cert) for remote dbUrl; localhost is unencrypted.
+});
+
+// Seed/publish an agent version (management helper, not part of the core interface).
+// Pass the adapter's typed internal handle `storage.ctx` (no `as any` coupling).
+await publishAgentVersion(storage.ctx, {
+  tenantId: orgId,
+  slug: "support",
+  role: "specialist",
+  personality: "warm",
+  capabilities: [],
+  skillNames: [],
+  delegateSlugs: [],
+  modelId: "openai/gpt-5.5",
+});
+
+// Cross-process durable suspend/resume: inject the Postgres-backed Mastra store.
+const engine = new SwarmEngine({
+  storage,
+  model: allowListModelProvider({ allow: ["openai/gpt-5.5"] }),
+  modelFactory: (modelId) => /* your LanguageModelV3 for modelId */ undefined as never,
+  cost: { maxSteps: 10, maxCostUsd: 1 },
+  mastraStore: createMastraPgStore({ dbUrl: process.env.SUPABASE_DB_URL! }), // disableInit:true
+});
+
+for await (const e of engine.run({ message: "hi" }, ctx)) {
+  // SwarmEvents are persisted to nightowls.events and broadcast on run:<id>
+}
+
+await storage.close(); // tears down Realtime channels, then ends the pg pool
+```
+
+Subscribe to the live event stream (server-side, BYPASSRLS):
+
+```ts
+for await (const event of storage.events.subscribe(runId)) {
+  // redacted SwarmEvent forwarded from the DB broadcast trigger, with authoritative seq
+}
+```
+
+## Known limitations
+
+- **Multi-tenant read-scoping (C1) deferred.** `events.list`, `runs.loadSnapshot`, and
+  `messages.history` do **not** independently org-scope by `tenantId`, because the core
+  `EventStore.list` / `RunStore.loadSnapshot` / `MessageStore.history` signatures don't
+  pass it. For single-tenant v1 the caller (engine/runner) authorizes the `runId` /
+  `threadId` before reading. Multi-tenant hardening = widening those core signatures to
+  take `tenantId`, tracked for the runner/auth plan (Plan 3).
+- **Cross-instance row-cache bust deferred.** The adapter's per-instance `RowCache`
+  (LRU+TTL) for run→org lookups, and the engine's `AgentVersion` cache, are not busted
+  across instances. A `postgres_changes` subscription on `nightowls.agents.current_version_id`
+  to invalidate caches cluster-wide is deferred to the runner/multi-instance plan; the
+  Plan-1 TTL is sufficient until then.
+- **Other v1 simplifications:** `RunStore.setStatus` ignores its optional `patch`
+  (status-only persistence); `runner` is hardcoded `'nextjs'` (`NewRun` has no runner
+  field); `events.subscribe` shares the adapter's single secret-role `SupabaseClient`
+  (a per-user-token subscription needs its own client because `setAuth` mutates shared
+  state). All are tracked for the runner/auth plan (Plan 3).