@zackbart/connecta 0.25.0 → 0.26.0

package/examples/worker/AGENTS.md

@@ -37,6 +37,12 @@ This repository is deployment configuration, not a copy of Connecta itself.
   A configured Connecta bearer cannot cross the Access edge alone. Connecta-issued
   tokens are removed. UI, vault, and activity use explicit optional imports;
   auth changes require code-derived shared or personal management permissions.
+- Brand the operator UI in `operatorUi({ branding })`: product and owner names,
+  description, favicon, and `theme` (`accent`, `radius`, `fontFamily`,
+  `monoFamily`, `colorScheme`). Ask the deployment's owner for their brand
+  rather than leaving the default. The commented block above
+  `ui: operatorUi()` in `src/index.ts` shows the shape; README "UI and
+  encrypted credentials" covers the rest.
 - After configuration changes, typecheck: inside the connecta repository that
   is `npm run check:examples`; a copied deployment runs its own `tsc --noEmit`.
   After deployment, connect both Claude and ChatGPT to `<PUBLIC_URL>/mcp` and

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
@@ -19,8 +19,17 @@ migrations, and secrets.
 | `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` |
 
+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.
@@ -103,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
@@ -125,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
 
@@ -166,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
@@ -186,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=… \
@@ -211,7 +320,7 @@ 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).
@@ -219,7 +328,11 @@ owns the package install — see
 ## Strongly consistent storage (optional)
 
 `KVStorage` has an optional atomic `compareAndSet`, for a subsystem that must
-claim a key exactly once. **Workers KV cannot provide it.** It is eventually
+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
@@ -256,10 +369,56 @@ of connecta state lives in one store.
    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
@@ -298,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
@@ -307,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/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";
 
@@ -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
@@ -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;
+    },
+  };
+}

package/examples/worker/wrangler.jsonc

@@ -3,9 +3,13 @@
   "name": "connecta-example",
   "main": "src/index.ts",
   "compatibility_date": "2025-01-01",
-  "compatibility_flags": ["nodejs_compat"],
+  "compatibility_flags": ["nodejs_compat", "enable_request_signal"],
   "observability": { "enabled": true },
 
+  // Uncomment with artifacts and D1 in src/index.ts. Every hourly tick runs
+  // at most 10 due pages; each page's own daily/weekly schedule lives in data.
+  // "triggers": { "crons": ["0 * * * *"] },
+
   // Plain vars. Secrets (CREDENTIAL_ENCRYPTION_KEY, DOWNSTREAM_TOKEN) are set with
   // `wrangler secret put <NAME>`, not here.
   "vars": {

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "type": "module",
   "sideEffects": false,
-  "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of seven meta-tools.",
+  "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of eight meta-tools.",
   "license": "MIT",
   "engines": {
     "node": ">=22.0.0"
@@ -110,6 +110,10 @@
     "./auth/bearer": {
       "types": "./dist/auth/bearer.d.ts",
       "import": "./dist/auth/bearer.js"
+    },
+    "./artifacts": {
+      "types": "./dist/artifacts.d.ts",
+      "import": "./dist/artifacts.js"
     }
   },
   "scripts": {

package/templates/node/AGENTS.md

@@ -3,8 +3,9 @@
 This repository is deployment configuration, not a copy of Connecta itself.
 
 - Edit `src/index.ts` for connectors, authentication, storage, and public URL.
-- Keep `executor: quickJsExecutor()` for the prescribed seven-tool code-first
-  surface.
+- Keep `executor: quickJsExecutor()` for the prescribed eight-tool code-first
+  surface. File storage supports resumable writes, so a program pauses at a
+  write until `resume_execution` approves it.
 - Keep credentials in environment variables or an external secret store.
   Never commit `.env`, `.connecta-state.json`, `.connecta-activity.jsonl`,
   tokens, or credential values.
@@ -19,6 +20,12 @@ This repository is deployment configuration, not a copy of Connecta itself.
   alone never grants it. Configured bearer auth is a client option, not a human
   management identity. Connecta-issued access tokens are removed.
   `src/file-activity.ts` remains the deployment-owned history store.
+- Brand the operator UI in `operatorUi({ branding })`: product and owner names,
+  description, favicon, and `theme` (`accent`, `radius`, `fontFamily`,
+  `monoFamily`, `colorScheme`). Ask the deployment's owner for their brand
+  rather than leaving the default. The commented block above
+  `ui: operatorUi()` in `src/index.ts` shows the shape; README "Select optional
+  modules" covers the rest.
 - Run `npm run typecheck` after configuration changes. With the server running,
   run `CONNECTA_TOKEN=... npm run doctor` before calling setup complete.
 - `Dockerfile` and `docker-compose.yml` containerize *this* source; they are

package/templates/node/README.md

@@ -46,11 +46,32 @@ reproducible `npm ci` path.
 
 ## Select optional modules
 
+For scheduled artifact pages, uncomment the `artifacts()` module and hourly
+`setInterval` block in `src/index.ts`. The module uses the same CAS-capable
+state file and exposes `runDue()` for the timer; core starts no job on its own.
+Each tick starts at most 10 due pages. Refresh programs can call only shared
+connectors' explicitly read-only tools within the program owner's current
+grants. Revoking refresh or pool access stops future runs. Failed runs leave the last good data
+and mark the viewer stale.
+
 The template explicitly enables `ui: operatorUi()` from
 `@zackbart/connecta/ui`. Open `http://localhost:8787/` and supply the configured
 bearer to inspect Connections. Omit that option and import for an API-only
 server. OAuth callbacks remain in core even with no UI.
 
+The page labels whether each tool runs in programs or needs approval. For
+classified connection failures it offers a fixed repair prompt, and its
+endpoint section has client setup commands for `/mcp` and any pool available
+to the signed-in identity. Those commands contain no bearer token.
+
+Branding belongs in `operatorUi({ branding })`: `productName`, `ownerName`,
+their URLs, `description`, `pageTitle`, `favicon`, and `theme`. The theme is
+five tokens — `accent`, `radius`, `fontFamily`, `monoFamily`, and
+`colorScheme` — and every other color is mixed from them, so one accent themes
+the whole page. A value that fails its gate falls back to the default, and the
+startup warning names it. `src/index.ts` carries the full shape commented out
+above `ui: operatorUi()`.
+
 Connection management needs an interactive identity. A configured bearer is a
 client key and never authorizes browser credential mutations. To enable Clerk:
 
@@ -89,6 +110,12 @@ it through `await ctx.credential?.get()`, or use a provider such as `notion()`
 that declares its own slot. Authorized humans manage the slot inside that
 connection on `/`; there is no separate Credentials tab.
 
+In 0.25.0, this vault also seals downstream OAuth tokens on their first read.
+That is a one-way state migration for those tokens: rolling back to 0.24.x
+requires authorizing each OAuth connector again. See the
+[0.25.0 changelog](../../CHANGELOG.md#0250--2026-09-23) before upgrading a
+deployment with existing OAuth connections.
+
 A saved replacement takes effect on the next call. Connecta tests credentials
 only on an explicit action and otherwise fails at use. Without a vault or UI,
 static credential recovery reports unavailable instead of offering a dead link.
@@ -132,16 +159,17 @@ npm run typecheck
 CONNECTA_TOKEN=dev-token npm run doctor
 ```
 
-Doctor checks health, the executor, and the exact prescribed seven-tool
+Doctor checks health, the executor, and the exact prescribed eight-tool
 model-facing surface by running a harmless sandbox program. It reads the bearer
 from `CONNECTA_TOKEN`; it never accepts the secret as a command-line argument.
 Remote URLs must use HTTPS.
 
 A fully-wired deployment reports exactly the same line as a bare one —
-connector count, QuickJS executed, seven tools, plus any catalog drift:
+connector count, QuickJS executed, eight tools, plus any catalog drift, and
+a note if resumable writes are off:
 
 ```text
-Connecta doctor passed: 1 connector(s), QuickJS executed, prescribed seven-tool surface.
+Connecta doctor passed: 1 connector(s), QuickJS executed, prescribed eight-tool surface.
 ```
 
 `QuickJS` is this deployment's sandbox, reported by the deployment itself —

package/templates/node/package.json

@@ -15,7 +15,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zackbart/connecta": "0.25.0",
+    "@zackbart/connecta": "0.26.0",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {

package/templates/node/src/index.ts

@@ -27,6 +27,7 @@ import { operatorUi } from "@zackbart/connecta/ui";
 import { api, createConnecta } from "@zackbart/connecta";
 import { fileStorage, listen } from "@zackbart/connecta/node";
 import { quickJsExecutor } from "@zackbart/connecta/quickjs";
+// import { artifacts, kvArtifactStore } from "@zackbart/connecta/artifacts";
 // Operator sign-in. Needs `npm install @clerk/backend` — it is an optional
 // peer, so it does not install with Connecta.
 // import { clerkAuth } from "@zackbart/connecta/auth/clerk";
@@ -45,6 +46,8 @@ const port = Number(process.env.PORT ?? 8787);
 const stateFile = process.env.CONNECTA_STATE_FILE || "./.connecta-state.json";
 const publicUrl = process.env.PUBLIC_URL || `http://localhost:${port}`;
 const storage = fileStorage(stateFile);
+// Optional artifact pages and refresh jobs use the same CAS-capable state file:
+// const artifactModule = artifacts({ store: kvArtifactStore(storage) });
 
 // Operator sign-in. A bearer token is a client key: it may call tools and read
 // connector status, but only a Clerk-authenticated human may write a visible
@@ -103,7 +106,25 @@ const connecta = createConnecta({
   //   ),
   //   deploymentId: "production",
   // }),
+  // The operator UI at /. Its branding is code, like everything else here:
+  // 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,
   connectors: [
     api("time", {
       description: "Time — current timestamp",
@@ -126,3 +147,9 @@ const connecta = createConnecta({
 
 listen(connecta, port);
 console.log(`connecta listening on port ${port}; MCP at ${publicUrl}/mcp`);
+// The deployment owns this timer; core starts no background work. Uncomment
+// with artifactModule above. Each tick starts at most 10 due pages.
+// const refreshTimer = setInterval(() => {
+//   void artifactModule.runDue().catch((error) => console.error("artifact refresh failed", error));
+// }, 60 * 60 * 1000);
+// refreshTimer.unref();