@zackbart/connecta 0.24.4 → 0.26.0

package/examples/worker/README.md

@@ -2,7 +2,7 @@
 
 A deployable Worker that aggregates a downstream remote MCP and an in-code HTTP
 API connector, guarded by Cloudflare Access, with state in a KV namespace. Its
-required Worker Loader binding backs the seven-tool surface and requires the
+required Worker Loader binding backs the eight-tool surface and requires the
 Workers Paid plan.
 
 This is also the **starting template for a deployment**: a real deployment
@@ -16,15 +16,26 @@ migrations, and secrets.
 | --- | --- |
 | `src/index.ts` | the Worker entrypoint — connector and auth configuration |
 | `src/cloudflare-kv.ts` | `KVStorage` over Workers KV (deployment-owned, not a package export) |
+| `src/d1-storage.ts` | `KVStorage` over D1 with atomic compare-and-set (optional; see below) |
 | `src/d1-activity.ts` | `ActivityStore` over D1 (deployment-owned; see below) |
 | `src/d1-activity-row.ts` | the row ↔ event mapping `d1-activity.ts` uses, including friction derived from `error_code` for rows written before that column existed |
+| `src/r2-artifact-blobs.ts` | artifact bodies in an R2 bucket, beside a D1-backed `kvArtifactStore` (optional) |
 | `wrangler.jsonc` | Worker name, vars, bindings, `compatibility_flags` |
 
-`cloudflare-kv.ts` and `d1-activity.ts` deliberately live here rather than in
-the package: storage backends are deployment-owned, so the package ships only
-the generic `KVStorage` and `ActivityStore` contracts. Workers KV is eventually
-consistent across locations; use a strongly consistent `KVStorage` adapter when
-OAuth disconnect or credential rotation must become globally visible
+Keep `enable_request_signal` in `wrangler.jsonc`. On Workers it lets a live
+response's client disconnect abort its request, so connecta cancels the stream
+and returns the admission permit promptly. The total admitted-request bound in
+`admission.requests.maxDurationMs` (default 300,000 ms) also reclaims capacity
+on a later request if workerd ends one without delivering a signal or stream
+cancellation. Set it above the longest authorization, tool call, and response
+delivery your deployment expects to serve.
+
+`cloudflare-kv.ts`, `d1-storage.ts`, and `d1-activity.ts` deliberately live
+here rather than in the package: storage backends are deployment-owned, so the
+package ships only the generic `KVStorage` and `ActivityStore` contracts.
+Workers KV is eventually consistent across locations; use a strongly consistent
+`KVStorage` adapter, such as [`d1-storage.ts`](#strongly-consistent-storage-optional),
+when OAuth disconnect or credential rotation must become globally visible
 immediately.
 
 ## Deploy
@@ -101,11 +112,106 @@ The checked-in `access.dev` block gives `wrangler dev` a local operator
 identity. Remove the block to test the missing-Access refusal. It has no effect
 on a deployed Worker's production identity.
 
+### Optional resource management with Alchemy
+
+Keep this example's Worker on Wrangler. A copied deployment may use
+[Alchemy](https://alchemy.run) to manage its KV namespace, optional D1 databases
+and R2 bucket, and the Access application without adding Alchemy to connecta or
+changing this template. In that deployment, install `alchemy@2.0.0-beta.79`
+and `effect@4.0.0-rc.117` at exact versions. The latter is connecta's own
+Effect pin; check `npm ls effect` for one resolved copy after installation.
+The following `alchemy.run.ts` is a resource stack, not a Worker deployment:
+
+```ts
+import * as Alchemy from "alchemy";
+import * as Cloudflare from "alchemy/Cloudflare";
+import { adopt } from "alchemy/AdoptPolicy";
+import * as Effect from "effect/Effect";
+
+// Replace this with the immutable ID of the Wrangler-deployed Worker.
+const workerId = "replace-with-worker-id";
+
+export default Alchemy.Stack(
+  "ConnectaResources",
+  { providers: Cloudflare.providers(), state: Cloudflare.state() },
+  Effect.gen(function* () {
+    const kv = yield* Cloudflare.KV.Namespace("ConnectaKV", { title: "connecta-kv" }).pipe(adopt(true));
+    const activity = yield* Cloudflare.D1.Database("ActivityDB", {
+      name: "connecta-activity", migrations: "./migrations/activity",
+    }).pipe(adopt(true));
+    const storage = yield* Cloudflare.D1.Database("StorageDB", {
+      name: "connecta-storage", migrations: "./migrations/storage",
+    }).pipe(adopt(true));
+    const blobs = yield* Cloudflare.R2.Bucket("ArtifactBlobs", { name: "connecta-artifacts" }).pipe(adopt(true));
+    const access = yield* Cloudflare.Access.Application("ConnectaAccess", {
+      type: "self_hosted",
+      name: "Connecta",
+      destinations: [{ type: "worker", workerId }],
+      policies: [{ decision: "allow", include: [{ emailDomain: "example.com" }] }],
+      oauthConfiguration: {
+        enabled: true,
+        dynamicClientRegistration: {
+          enabled: true,
+          allowedUris: [
+            "https://claude.ai/api/mcp/auth_callback",
+            "https://chatgpt.com/connector_platform_oauth_redirect",
+            "https://chatgpt.com/connector/oauth/*",
+          ],
+        },
+      },
+    }).pipe(adopt(true));
+    return { kvId: kv.namespaceId, activityId: activity.databaseId,
+      storageId: storage.databaseId, bucketName: blobs.bucketName,
+      accessId: access.applicationId };
+  }),
+);
+```
+
+Replace the Worker ID and example Access policy before applying this stack.
+Keep only the resources the deployment uses: `STORAGE_DB` replaces
+`CONNECTA_KV`; `ACTIVITY_DB` and R2 are optional. Copy the output IDs into the
+matching `wrangler.jsonc` bindings. Keep `LOADER` in `worker_loaders` and, when
+enabled, the Browser Rendering binding and cron trigger in the Wrangler-owned
+Worker configuration. Configure the main and artifact hostnames as Wrangler
+custom domain `routes` with `custom_domain: true`. The Worker-level Access
+destination covers both hostnames; verify both against the same application
+after domain setup. Continue to set secrets with `wrangler secret put` and to
+deploy the Worker with Wrangler. After its initial `wrangler deploy`, use
+`wrangler versions upload` and `wrangler versions deploy` for code updates;
+apply route and cron changes through Wrangler too.
+
+The `adopt(true)` calls explicitly permit taking over matching existing
+resources; compare their live names, IDs, Access policy, and data before the
+first Alchemy deploy. Remove adoption where a resource is new. Put the D1 SQL
+from this README in the shown migration directories before deploying. With
+`migrations` configured, Alchemy copies an adopted database's Wrangler
+migration history once into `__alchemy_migrations`; the old history stays
+frozen. Review pending SQL before handing migrations over. Remote
+`Cloudflare.state()` bootstraps an account-level state-store Worker backed by a
+Durable Object and Secrets Store entries for its credentials. Retain them:
+deleting the state store loses Alchemy's record of what it owns.
+
+Verification for this optional path stops at the API and types. The fenced
+snippet was copied to an isolated `alchemy.run.ts` and passed `tsc --noEmit`
+with TypeScript 5.9.3, Alchemy 2.0.0-beta.79, and Effect 4.0.0-rc.117; no
+Alchemy deploy or adoption was run.
+[Alchemy's Worker resource](https://alchemy.run/cloudflare/compute/workers/)
+can declare `WorkerLoader`, domains, Browser Rendering, and cron wiring, but
+those properties are coupled to its script deploy. Its current full deploy
+still uses the script-upload endpoint; only a conditional gradual rollout uses
+the versions API. A previous full deploy through that endpoint did not provide
+`ctx.access`, so do not transfer Worker ownership until that path is verified
+end to end. The [Access](https://alchemy.run/cloudflare/security/access/),
+[D1](https://alchemy.run/cloudflare/data/d1/), and
+[state-store](https://alchemy.run/state-store/) guides describe the resources
+above; the typecheck does not prove Cloudflare will accept this particular
+Access adoption or preserve production identity.
+
 ### Copied into its own repository
 
 The `npm install` above is the connecta repository's, which already has every
-dependency this file imports. A copy with its own `package.json` installs three
-things, because two of them are not part of connecta and never install with it:
+dependency this file imports. A copy with its own `package.json` installs
+Connecta and the separately installed `@cloudflare/codemode` peer:
 
 ```sh
 npm install @zackbart/connecta @cloudflare/codemode
@@ -123,7 +229,10 @@ the Clerk path in the Node template.
 
 Then point an MCP client at `<PUBLIC_URL>/mcp`. The example explicitly enables
 `ui: operatorUi()`; open `<PUBLIC_URL>/` for Connections and each connection's
-authentication controls. There is no separate Credentials or Tokens tab.
+authentication controls. The page labels tool safety, offers fixed repair
+prompts for classified failures, and shows client setup commands for endpoints
+the signed-in person may use. Those commands contain no token. There is no
+separate Credentials or Tokens tab.
 
 ## Select optional modules
 
@@ -164,6 +273,8 @@ Reuse the same key and KV namespace during upgrades. Without the secret, omit
 the vault; declared credential slots remain unmanageable. Keep the key outside
 KV because it protects a copied namespace. Credential replacement takes effect
 on the next call without redeploying; no liveness probe runs in the background.
+With this vault, 0.25.0 seals existing downstream OAuth state on first read.
+Rolling back to 0.24.x then requires reauthorizing those OAuth connectors.
 
 The shipped Notion connector uses a deployment-owned static header and echo
 needs no secret. To exercise vault controls, declare a `credential` slot on an
@@ -184,7 +295,7 @@ below. Omit the module and store wiring to record no history and show no
 Activity tab. Diagnostics remain independent; `logger: "silent"` suppresses
 them explicitly.
 
-Verify MCP health and the exact seven tools with:
+Verify MCP health and the exact eight tools with:
 
 ```sh
 CF_ACCESS_CLIENT_ID=… CF_ACCESS_CLIENT_SECRET=… \
@@ -209,11 +320,105 @@ The required Worker Loader binding is checked into `wrangler.jsonc`:
 ```
 
 `src/index.ts` constructs `DynamicWorkerExecutor` with only `env.LOADER` and
-serves the seven-tool surface. Do not add `bindings`, `modules`, or
+serves the eight-tool surface. Do not add `bindings`, `modules`, or
 `globalOutbound`; they grant guest code ambient authority. A copied deployment
 owns the package install — see
 [copied into its own repository](#copied-into-its-own-repository).
 
+## Strongly consistent storage (optional)
+
+`KVStorage` has an optional atomic `compareAndSet`, for a subsystem that must
+claim a key exactly once — resumable writes, where two `resume_execution` calls
+racing for one paused program must send its writes once. **Workers KV cannot
+provide it**, so on KV this example turns resumable writes off
+(`execute: { resumableWrites: false }` in `src/index.ts`) and its programs
+refuse writes. It is eventually
+consistent: two locations can each read a key as absent and both write, so
+`cloudflare-kv.ts` declares no `compareAndSet` rather than fake one with a read
+followed by a write. `src/d1-storage.ts` is a complete `KVStorage` over D1
+that does provide it, one SQL statement per claim, with TTLs honored at read
+time. It replaces the KV namespace rather than sitting beside it: every piece
+of connecta state lives in one store.
+
+1. Create the database and uncomment the `STORAGE_DB` entry of the
+   `d1_databases` binding in `wrangler.jsonc`, pasting in the id it prints:
+
+   ```sh
+   wrangler d1 create connecta-storage
+   ```
+
+2. Apply the schema (keep it in a deployment-owned `migrations/` directory):
+
+   ```sql
+   CREATE TABLE IF NOT EXISTS connecta_kv (
+     key           TEXT PRIMARY KEY,
+     value         TEXT NOT NULL,
+     expires_at_ms INTEGER
+   );
+
+   CREATE INDEX IF NOT EXISTS connecta_kv_expiry
+     ON connecta_kv (expires_at_ms);
+   ```
+
+3. In `src/index.ts`, add `STORAGE_DB: D1Database` to `Env` and build the store
+   from it:
+
+   ```ts
+   import { d1Storage } from "./d1-storage.js";
+
+   const storage = d1Storage(env.STORAGE_DB);
+   ```
+
+   Then delete the `execute: { resumableWrites: false }` line: on D1,
+   resumable writes default on, and programs pause at a write until
+   `resume_execution` approves it.
+
+   Switching an existing deployment starts from empty state: downstream OAuth
+   connections must be re-authorized and vault credentials re-entered, because
+   nothing copies them out of the KV namespace.
+
+## Artifacts (optional)
+
+`artifacts()` from `@zackbart/connecta/artifacts` adds the built-in `artifacts`
+connector: team pages whose data lives in versioned JSON documents. Every write
+commits by compare-and-set, so the store needs the D1 storage above — Workers
+KV is refused at construction. Artifacts share the `connecta_kv` table and need
+no schema of their own. Bodies (page sources and documents) can stay in D1 rows,
+which the default limits keep well under D1's row size, or go to R2 with
+`src/r2-artifact-blobs.ts`:
+
+```ts
+import { artifacts, kvArtifactStore } from "@zackbart/connecta/artifacts";
+import { r2ArtifactBlobs } from "./r2-artifact-blobs.js";
+
+createConnecta({
+  // …
+  publicUrl: env.PUBLIC_URL, // required: artifact links are shared
+  artifacts: artifacts({
+    store: kvArtifactStore(d1Storage(env.STORAGE_DB), {
+      blobs: r2ArtifactBlobs(env.ARTIFACTS_BUCKET), // optional
+    }),
+  }),
+});
+```
+
+For R2, create the bucket (`wrangler r2 bucket create connecta-artifacts`) and
+add `"r2_buckets": [{ "binding": "ARTIFACTS_BUCKET", "bucket_name":
+"connecta-artifacts" }]` to `wrangler.jsonc` and `ARTIFACTS_BUCKET: R2Bucket`
+to `Env`. Nothing ever deletes a body: versions are immutable, a rollback
+points back at an old one, and a body written by a write that lost a conflict
+stays stored unreferenced.
+
+To refresh pages, keep the module in a variable, pass it to `createConnecta`,
+and assign it to `scheduledArtifacts.module` as shown in `src/index.ts`.
+Uncomment the hourly cron in `wrangler.jsonc`. An hourly tick starts at most
+10 due pages; each page's `manual`, `daily`, or `weekly` schedule lives in its
+versioned refresh configuration. Refresh programs use only shared connectors'
+explicitly read-only tools within the program owner's current grants. Revoking
+refresh or pool access stops future runs. D1's compare-and-set prevents two cron invocations
+from claiming the same page. Failed runs keep the last good data and show a
+stale banner without exposing downstream error text to readers.
+
 ## Activity history (optional)
 
 `src/d1-activity.ts` is a complete `ActivityStore` over D1 — keyset paging on
@@ -252,6 +457,7 @@ To enable it:
      attempts       INTEGER NOT NULL,
      error_code     TEXT,
      friction       TEXT,
+     approval       TEXT,
      server_name    TEXT NOT NULL,
      server_version TEXT NOT NULL,
      deployment_id  TEXT
@@ -261,15 +467,19 @@ To enable it:
      ON tool_call_activity (occurred_at_ms DESC, id DESC);
    ```
 
-   **Already have this table?** `actor_namespace` and `friction` were added
-   after the original example, and `CREATE TABLE IF NOT EXISTS` will not add
-   them to a table that already exists. Add them as migrations:
+   **Already have this table?** `actor_namespace`, `friction`, and `approval`
+   were added after the original example, and `CREATE TABLE IF NOT EXISTS`
+   will not add them to a table that already exists. Add them as migrations:
 
    ```sql
    ALTER TABLE tool_call_activity ADD COLUMN actor_namespace TEXT;
    ALTER TABLE tool_call_activity ADD COLUMN friction TEXT;
+   ALTER TABLE tool_call_activity ADD COLUMN approval TEXT;
    ```
 
+   `approval` is set only on an `approved` row — the scope a resumed
+   program's approval covered, `call` or `tool` — and is otherwise null.
+
    `friction` is stored rather than derived because one of its classes belongs
    to a call that *succeeded*: a result too large to return inline is friction
    for the agent and carries no error code. Rows written before the column keep

package/examples/worker/src/d1-activity-row.ts

@@ -18,8 +18,15 @@ export interface ActivityEvent {
     | "call_tool"
     | "call_destructive_tool"
     | "batch_call"
-    | "execute_code";
-  outcome: "success" | "error" | "timeout" | "cancelled";
+    | "execute_code"
+    | "resume_execution";
+  outcome:
+    | "success"
+    | "error"
+    | "timeout"
+    | "cancelled"
+    | "paused"
+    | "approved";
   durationMs: number;
   attempts: number;
   errorCode?: string;
@@ -29,6 +36,7 @@ export interface ActivityEvent {
     | "destructive_reroute"
     | "auth_required"
     | "result_too_large";
+  approval?: "call" | "tool";
   serverName: string;
   serverVersion: string;
   deploymentId?: string;
@@ -76,6 +84,8 @@ export interface ActivityRow {
   attempts: number;
   error_code: string | null;
   friction: ActivityEvent["friction"] | null;
+  /** Absent from tables created before resumable writes; read as null. */
+  approval?: ActivityEvent["approval"] | null;
   server_name: string;
   server_version: string;
   deployment_id: string | null;
@@ -102,6 +112,7 @@ export function activityEventToRow(
     // friction on a call that succeeded, so it has no error code to derive from
     // — and `error_code IS NOT NULL` stays an honest count of failures.
     friction: event.friction ?? null,
+    approval: event.approval ?? null,
     server_name: event.serverName,
     server_version: event.serverVersion,
     deployment_id: event.deploymentId ?? null,
@@ -131,6 +142,7 @@ export function activityRowToEvent(
     attempts: row.attempts,
     ...(row.error_code ? { errorCode: row.error_code } : {}),
     ...(friction ? { friction } : {}),
+    ...(row.approval ? { approval: row.approval } : {}),
     serverName: row.server_name,
     serverVersion: row.server_version,
     ...(row.deployment_id

package/examples/worker/src/d1-activity.ts

@@ -50,8 +50,9 @@ export function d1ActivityStore(db: D1Database): ActivityStore {
             id, occurred_at_ms, request_id, actor_kind, actor_id,
             actor_namespace,
             connector_id, tool_name, source, outcome, duration_ms, attempts,
-            error_code, friction, server_name, server_version, deployment_id
-          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+            error_code, friction, approval, server_name, server_version,
+            deployment_id
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
         )
         .bind(
           row.id,
@@ -68,6 +69,7 @@ export function d1ActivityStore(db: D1Database): ActivityStore {
           row.attempts,
           row.error_code,
           row.friction ?? null,
+          row.approval ?? null,
           row.server_name,
           row.server_version,
           row.deployment_id,

package/examples/worker/src/d1-storage.ts

@@ -0,0 +1,116 @@
+import type { KVStorage } from "@zackbart/connecta";
+
+/**
+ * KVStorage over a D1 database, with the atomic `compareAndSet` that Workers
+ * KV cannot offer. Apply the `connecta_kv` schema in README.md § "Strongly
+ * consistent storage" before first use.
+ *
+ * Every compare-and-set is a single SQL statement. D1 runs one database's
+ * statements one at a time against its primary, so the comparison and the
+ * write cannot interleave with another request's: of fifty concurrent claims
+ * on an absent key, exactly one changes a row.
+ *
+ * Expiry is judged by the Worker's clock at each call, the same `Date.now()`
+ * the core uses. An expired row reads as absent immediately and is removed
+ * physically by later writes, a bounded batch at a time, so no request starts
+ * a background job and no cron is required.
+ */
+export function d1Storage(db: D1Database): KVStorage {
+  // Every statement that tests liveness binds the current time as ?2.
+  const live = "(expires_at_ms IS NULL OR expires_at_ms > ?2)";
+  const expiresAt = (now: number, ttlSeconds?: number) =>
+    ttlSeconds ? now + ttlSeconds * 1000 : null;
+  const changed = (result: D1Result) => result.meta.changes > 0;
+  return {
+    async get(key) {
+      const row = await db
+        .prepare(`SELECT value FROM connecta_kv WHERE key = ?1 AND ${live}`)
+        .bind(key, Date.now())
+        .first<{ value: string }>();
+      return row?.value ?? null;
+    },
+    async set(key, value, opts) {
+      const now = Date.now();
+      await db.batch([
+        db
+          .prepare(
+            `DELETE FROM connecta_kv WHERE key IN (
+              SELECT key FROM connecta_kv WHERE expires_at_ms <= ?1 LIMIT 16
+            )`,
+          )
+          .bind(now),
+        db
+          .prepare(
+            `INSERT INTO connecta_kv (key, value, expires_at_ms)
+             VALUES (?1, ?2, ?3)
+             ON CONFLICT (key) DO UPDATE SET
+               value = excluded.value, expires_at_ms = excluded.expires_at_ms`,
+          )
+          .bind(key, value, expiresAt(now, opts?.ttlSeconds)),
+      ]);
+    },
+    async delete(key) {
+      await db.prepare("DELETE FROM connecta_kv WHERE key = ?1").bind(key).run();
+    },
+    async list(prefix) {
+      const { results } = await db
+        .prepare(
+          `SELECT key FROM connecta_kv
+           WHERE key >= ?1 AND substr(key, 1, length(?1)) = ?1 AND ${live}`,
+        )
+        .bind(prefix, Date.now())
+        .all<{ key: string }>();
+      // Sort in JavaScript: SQLite orders UTF-8 bytes, the contract orders
+      // the UTF-16 code units every other adapter sorts by.
+      return results.map((row) => row.key).sort();
+    },
+    async compareAndSet(key, expected, next, opts) {
+      const now = Date.now();
+      if (next === null && expected === null) {
+        // Nothing to write; the claim holds exactly when no live row exists.
+        const row = await db
+          .prepare(`SELECT 1 AS present FROM connecta_kv WHERE key = ?1 AND ${live}`)
+          .bind(key, now)
+          .first();
+        return row === null;
+      }
+      if (next === null) {
+        return changed(
+          await db
+            .prepare(
+              `DELETE FROM connecta_kv WHERE key = ?1 AND ${live} AND value = ?3`,
+            )
+            .bind(key, now, expected)
+            .run(),
+        );
+      }
+      const expiry = expiresAt(now, opts?.ttlSeconds);
+      if (expected === null) {
+        // Insert, or take over a row that has expired. A live row makes the
+        // upsert's WHERE false, so nothing changes and the claim is refused.
+        return changed(
+          await db
+            .prepare(
+              `INSERT INTO connecta_kv (key, value, expires_at_ms)
+               VALUES (?1, ?3, ?4)
+               ON CONFLICT (key) DO UPDATE SET
+                 value = excluded.value, expires_at_ms = excluded.expires_at_ms
+               WHERE connecta_kv.expires_at_ms IS NOT NULL
+                 AND connecta_kv.expires_at_ms <= ?2`,
+            )
+            .bind(key, now, next, expiry)
+            .run(),
+        );
+      }
+      return changed(
+        await db
+          .prepare(
+            `UPDATE connecta_kv SET value = ?4, expires_at_ms = ?5
+             WHERE key = ?1 AND ${live} AND value = ?3`,
+          )
+          .bind(key, now, expected, next, expiry)
+          .run(),
+      );
+    },
+  };
+}

package/examples/worker/src/index.ts

@@ -8,7 +8,7 @@ import { encryptedCredentialVault } from "@zackbart/connecta/credentials";
  * by Cloudflare Access, with OAuth/cache state in a KV namespace. Access
  * authenticates the request before this Worker runs and supplies the trusted
  * identity through ctx.access. The required Worker Loader binding in
- * wrangler.jsonc backs the seven-tool surface.
+ * wrangler.jsonc backs the eight-tool surface.
  *
  * The operator surface is wired here except for activity history, which needs
  * a database this example does not create for you: sign-in and the credential
@@ -43,6 +43,8 @@ import {
 } from "@zackbart/connecta";
 import { cloudflareAccessAuth } from "@zackbart/connecta/auth/cloudflare-access";
 import { cloudflareKvStorage } from "./cloudflare-kv.js";
+// import { artifacts, kvArtifactStore } from "@zackbart/connecta/artifacts";
+// import { d1Storage } from "./d1-storage.js";
 // Activity history, off by default because it needs a D1 database.
 // import { d1ActivityStore } from "./d1-activity.js";
 
@@ -50,8 +52,8 @@ interface Env {
   CONNECTA_KV: KVNamespace;
   /**
    * Base64 32-byte AES key encrypting operator-managed credentials in KV.
-   * Unset means no vault: /credentials stays read-only and connecta says so at
-   * startup. Never put it in KV — it is what protects KV.
+   * Unset means no vault: credential management is unavailable in the operator
+   * UI. Never put it in KV, since it is what protects KV.
    */
   CREDENTIAL_ENCRYPTION_KEY: string;
   DOWNSTREAM_TOKEN: string;
@@ -67,10 +69,21 @@ interface Env {
 
 function build(env: Env) {
   const storage = cloudflareKvStorage(env.CONNECTA_KV);
+  // Optional refreshable pages need the D1 binding, not Workers KV:
+  // const artifactModule = artifacts({ store: kvArtifactStore(d1Storage(env.STORAGE_DB)) });
+  // scheduledArtifacts.module = artifactModule;
   return createConnecta({
     publicUrl: env.PUBLIC_URL,
     storage,
     executor: new DynamicWorkerExecutor({ loader: env.LOADER }),
+    // Resumable writes — a program pausing at a write until resume_execution
+    // approves it — need storage with an atomic compareAndSet, and Workers KV
+    // cannot provide one. On KV they are off: programs refuse writes and
+    // resume_execution says there is nothing to resume. This line states that
+    // choice (without it connecta would warn once at startup). To let programs
+    // pause, switch to the D1 store in README.md § "Strongly consistent
+    // storage" and delete this line.
+    execute: { resumableWrites: false },
     auth: [
       // Access owns admission policy. A human identity may use MCP and the
       // operator pages; a service token may use MCP but cannot mutate operator
@@ -103,7 +116,24 @@ function build(env: Env) {
     // connector like `notion()`, which declares its own) and the form appears
     // on the next load.
     vault: encryptedCredentialVault(storage, env.CREDENTIAL_ENCRYPTION_KEY),
+    // Branding is code too: name, owner, description, favicon, and five theme
+    // tokens that every other color is mixed from. A value that fails its
+    // check falls back to the default, and the startup warning names it.
+    // ui: operatorUi({
+    //   branding: {
+    //     productName: "Acme Tools",
+    //     ownerName: "Acme",
+    //     theme: {
+    //       accent: "#2f5fe0", // hex only
+    //       radius: 10, // pixels, or a CSS length such as "0.5rem"
+    //       fontFamily: "Inter, system-ui, sans-serif",
+    //       monoFamily: "ui-monospace, monospace",
+    //       colorScheme: "system", // or "light" | "dark"
+    //     },
+    //   },
+    // }),
     ui: operatorUi(),
+    // artifacts: artifactModule,
     identity: { credentialAdministration: () => "all", personalConnection: () => "all" },
     // Payload-free activity at /activity, off until a database exists to hold
     // it. Uncomment the `d1_databases` binding in wrangler.jsonc, apply the
@@ -121,8 +151,8 @@ function build(env: Env) {
           type: "headers",
           headers: { Authorization: `Bearer ${env.DOWNSTREAM_TOKEN}` },
           // The vault-backed alternative for a downstream that authenticates
-          // with a static key: the operator pastes it at /credentials and
-          // rotates it there, so no Worker secret holds it.
+          // with a static key: the operator manages it inside its connection
+          // in the operator UI, so no Worker secret holds it.
           //   type: "credential",
           //   credential: { label: "Notion internal integration token" },
         },
@@ -132,8 +162,8 @@ function build(env: Env) {
       }),
       api("echo", {
         description: "Echo — text transforms",
-        // What a vault-backed connector adds — an operator edits this slot at
-        // /credentials and the handler reads it with
+        // What a vault-backed connector adds — an operator edits this slot
+        // inside its connection in the operator UI and the handler reads it with
         // `await ctx.credential?.get()`, so the secret never lives in source
         // or in a Worker variable:
         //   credential: { label: "API token" },
@@ -162,6 +192,7 @@ function build(env: Env) {
 // Lazy per-isolate singleton: reuses the plain-data tool cache. Downstream MCP
 // clients are request-scoped internally so Worker I/O never crosses requests.
 let connecta: ReturnType<typeof build> | undefined;
+const scheduledArtifacts: { module?: { runDue(): Promise<unknown> } } = {};
 
 export default {
   // Pass `ctx` through: connecta hands deferred work (activity sinks) to
@@ -175,4 +206,8 @@ export default {
     connecta ??= build(env);
     return connecta.fetch(request, env, ctx);
   },
+  async scheduled(_event: ScheduledController, env: Env): Promise<void> {
+    connecta ??= build(env);
+    await scheduledArtifacts.module?.runDue();
+  },
 };

package/examples/worker/src/r2-artifact-blobs.ts

@@ -0,0 +1,29 @@
+import type { ArtifactBlobStore } from "@zackbart/connecta/artifacts";
+
+/**
+ * Artifact bodies — page sources, data documents, refresh programs — in an R2
+ * bucket, beside a D1-backed `kvArtifactStore` that keeps the heads, versions,
+ * and runs. Optional: without it, bodies live in D1 rows, which the default
+ * limits keep well under D1's row size. Use it once pages or documents grow,
+ * or to keep large bodies out of the database a backup copies.
+ *
+ * Keys are content addresses, so writing one twice writes the same bytes, and
+ * nothing here ever deletes one: versions are immutable, and a rollback points
+ * back at an old body rather than copying it.
+ */
+export function r2ArtifactBlobs(
+  bucket: R2Bucket,
+  prefix = "artifacts/blobs/",
+): ArtifactBlobStore {
+  return {
+    async put(key, body) {
+      await bucket.put(`${prefix}${key}`, body, {
+        httpMetadata: { contentType: "text/plain; charset=utf-8" },
+      });
+    },
+    async get(key) {
+      const object = await bucket.get(`${prefix}${key}`);
+      return object ? object.text() : null;
+    },
+  };
+}