@zackbart/connecta 0.25.0 → 0.26.1

package/ethos.md

@@ -5,12 +5,13 @@ Connecta’s scope, refusals, and invariants. Contradictions require a design de
 ## What this is
 
 - **One MCP endpoint.** Agents reach configured connectors through JavaScript,
-  a required executor, and seven meta-tools, eight planned.
+  a required executor, and eight meta-tools.
 - **Config-as-code.** One tenant and connector set; identities get
   config-derived views. Maintained providers, `remoteMcp()`, and `api()` share
   one connector contract.
-- **Safe by default.** Programs run only explicitly read-only tools unasked;
-  others cross `call_destructive_tool` or, planned, pause. The host owns approval.
+- **Safe by default.** Programs run only read-only or config-exempt tools
+  unasked; others pause for `resume_execution` or cross
+  `call_destructive_tool`. The host owns approval.
 - **One fetch-native core.** Web APIs on Node and Workers; platform code and
   optional features behind explicit subpaths; Effect inside, Promises outside.
 - **Human auth management.** Optional pages show status and payload-free history.
@@ -33,10 +34,11 @@ carries them.
 | --- | --- | --- |
 | OpenAPI / GraphQL ingestion | refused | the disease is a document-authored tool nobody chose; hand-written literals, even through a shared factory, are still authorship |
 | Multi-tenancy / account model | refused | one deployment per tenant; inbound auth owns identity |
-| Approvals and pauses | planned | a program pauses host-side at its first unapproved write until the destructive-annotated `resume_execution` repeats that exact call, the host's prompt approving it or its tool; an expiring journal replays the run, never re-sending unknown outcomes |
+| Approvals and pauses | accepted | a program pauses host-side at its first unapproved write until the destructive-annotated `resume_execution` repeats it; an expiring journal replays it, never re-sending unknown outcomes ([#565](https://github.com/zackbart/connecta/issues/565)) |
+| Approval exemptions | accepted | config-only, program-only, never read-only elsewhere ([#566](https://github.com/zackbart/connecta/issues/566)) |
 | Runtime connector registration | refused | config-as-code is the security model |
 | Optional deployment modules | accepted | typed slots select UI, activity, vault, and inbound auth; core keeps discovery, execution, invocation, and enforcement |
-| Artifacts module | planned | a built-in connector, not a meta-tool: team-only sandboxed pages over stored JSON, never calling tools. Immutable versions let writes skip approval. Supersedes [#287](https://github.com/zackbart/connecta/issues/287) on executor's artifacts |
+| Artifacts module | accepted | a built-in connector for team-only sandboxed pages over stored JSON; immutable versions let writes skip approval. Supersedes [#287](https://github.com/zackbart/connecta/issues/287) |
 | Plugin lifecycle, provider registry, or marketplace | refused | modules are deployment code, not runtime installs; prebuilt connections are imports, discovered in docs ([#297](https://github.com/zackbart/connecta/issues/297)) |
 | Connecta-issued access tokens | removed | inbound providers authenticate clients; bearer auth stays an optional adapter |
 | Expanded Notion page create/update options | refused | different workflows, not missing fields; use `api()` ([#408](https://github.com/zackbart/connecta/issues/408)) |
@@ -57,12 +59,12 @@ carries them.
 | Connector shortcut globals | removed | canonical addresses need no sanitization |
 | `connecta.batch` | removed | JavaScript promises suffice |
 | Automatic direct-call retries | removed | callers own retry timing |
-| Connector HTTP routes | removed | deployments own custom routes; artifact viewing is the planned exception |
+| Connector HTTP routes | removed | deployments own custom routes; the operator UI's artifact viewer is the exception |
 | Caller-selected toolkits | removed | config derives every view, grant-gated `/mcp/<pool>` pools included ([#178](https://github.com/zackbart/connecta/issues/178), [#531](https://github.com/zackbart/connecta/issues/531)) |
 | Proactive credential liveness | removed | fail-at-use is enough ([#179](https://github.com/zackbart/connecta/issues/179)) |
 | Classic (executor-free) surface | removed | an executor is mandatory ([#273](https://github.com/zackbart/connecta/issues/273)) |
 | Per-result lexical query coverage | removed | failed a precommitted response-bytes gate ([#323](https://github.com/zackbart/connecta/issues/323)) |
-| Stabilized workflows | planned | only as artifact refresh: scheduled read-only programs, shared credentials ([#225](https://github.com/zackbart/connecta/issues/225)) |
+| Stabilized workflows | accepted | only as artifact refresh: deployment-triggered read-only programs, shared credentials ([#225](https://github.com/zackbart/connecta/issues/225), [#564](https://github.com/zackbart/connecta/issues/564)) |
 | Semantic tool search | gated | keyword search has not been shown to fail ([#27](https://github.com/zackbart/connecta/issues/27)) |
 | MRTR / `input_required` passthrough | gated | relayable statelessly; no host or downstream emits it yet ([#176](https://github.com/zackbart/connecta/issues/176)) |
 | Downstream `ttlMs` cache hints | gated | needs refresh-churn evidence ([#206](https://github.com/zackbart/connecta/issues/206)) |
@@ -76,7 +78,7 @@ design decision.
 
 - **Fail-closed read-only.** A missing, false, or contradictory annotation never gets the benefit of the doubt.
 - **Generated code cannot mint capabilities.** Admission, credentials, and classification are enforced below the sandbox.
-- **Only explicitly read-only work runs unasked in the sandbox.** Everything else crosses `call_destructive_tool` or, planned, `resume_execution` or a config exemption.
+- **Only explicitly read-only or config-exempt work runs unasked in the sandbox.** Others pause or cross `call_destructive_tool`.
 - **Nothing request-bound survives a request.** No transport, stream, signal, or awaited promise outlives it; a paused journal is data, not a request.
 - **A downstream catalog is complete or it is a failure.** A partial one is never cached, persisted, or served.
 - **Activity is payload-free by construction.** The event type has nowhere to put arguments, results, code, or raw errors.
@@ -84,8 +86,8 @@ design decision.
 - **Credentials never leave the host.** Encrypted at rest, readable only by the owning connector (and principal, for personal auth), rendered by nothing.
 - **Import-graph purity.** Nothing reachable from the root entry imports a `node:` builtin or `effect/testing`.
 - **The published surface is a boundary.** Heavyweight or platform-bound code goes behind an optional-peer subpath; Effect is the one hard dependency, named by no published type.
-- **Human routes manage auth, never capability.** Visibility grants use, not administration. Shared and personal auth mutations need separate config-derived permissions, both denied by default, and activity reads their own. Planned: viewing artifacts.
-- **Omitted modules do no work.** Core imports no UI bundle, vault, activity, or bearer implementation. OAuth callbacks work without UI.
+- **Human routes manage auth, never capability.** Visibility grants use, not administration. Auth mutations need separate config-derived permissions, denied by default; activity reads its own. Artifact viewing respects connector grants and cannot invoke tools.
+- **Omitted modules do no work.** Core imports no UI bundle, vault, activity, artifacts, or bearer implementation. OAuth callbacks work without UI.
 - **Status reads do not start authorization.** Only an explicit authorized action starts OAuth, never a page load.
 - **Structural mistakes throw at construction.** Booting into the wrong shape is worse than not booting.
 

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.1",
   "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