@zackbart/connecta 0.26.3 → 0.28.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 eight-tool surface and requires the
+required Worker Loader binding backs the seven-tool surface and requires the
 Workers Paid plan.
 
 This is also the **starting template for a deployment**: a real deployment
@@ -118,7 +118,7 @@ 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
+and `effect@4.0.0` 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:
 
@@ -193,8 +193,9 @@ 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.
+with TypeScript 5.9.3, Alchemy 2.0.0-beta.79, and Effect 4.0.0, with
+`npm ls effect` confirming one resolved copy. 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
@@ -295,7 +296,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 eight tools with:
+Verify MCP health and the exact seven tools with:
 
 ```sh
 CF_ACCESS_CLIENT_ID=… CF_ACCESS_CLIENT_SECRET=… \
@@ -320,7 +321,7 @@ The required Worker Loader binding is checked into `wrangler.jsonc`:
 ```
 
 `src/index.ts` constructs `DynamicWorkerExecutor` with only `env.LOADER` and
-serves the eight-tool surface. Do not add `bindings`, `modules`, or
+serves the seven-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).
@@ -328,11 +329,9 @@ 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 — 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
+claim a key exactly once: artifacts commit every write by it, issuing access
+tokens requires it, and an OAuth handoff binds its owner with it when it is
+there. **Workers KV cannot provide it.** 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
@@ -369,10 +368,6 @@ 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.
@@ -477,8 +472,10 @@ To enable it:
    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.
+   `approval` is history: it is set only on an `approved` row written before
+   0.28.0 removed program pauses — the scope a resumed program's approval
+   covered, `call` or `tool` — and is null on every row since. Keep the
+   column; the Activity tab still renders those older rows.
 
    `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

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

@@ -19,12 +19,14 @@ export interface ActivityEvent {
     | "call_destructive_tool"
     | "batch_call"
     | "execute_code"
+    // History only: rows written before 0.28.0 removed program pauses.
     | "resume_execution";
   outcome:
     | "success"
     | "error"
     | "timeout"
     | "cancelled"
+    // History only, like `resume_execution` above.
     | "paused"
     | "approved";
   durationMs: number;
@@ -36,6 +38,7 @@ export interface ActivityEvent {
     | "destructive_reroute"
     | "auth_required"
     | "result_too_large";
+  /** History only: the scope an `approved` row covered, before 0.28.0. */
   approval?: "call" | "tool";
   serverName: string;
   serverVersion: string;
@@ -84,7 +87,7 @@ export interface ActivityRow {
   attempts: number;
   error_code: string | null;
   friction: ActivityEvent["friction"] | null;
-  /** Absent from tables created before resumable writes; read as null. */
+  /** Absent from tables created before 0.26.0; null on every row since 0.28.0. */
   approval?: ActivityEvent["approval"] | null;
   server_name: string;
   server_version: string;

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

@@ -18,8 +18,17 @@ import type { KVStorage } from "@zackbart/connecta";
 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 expiresAt = (now: number, ttlSeconds?: number): number | null => {
+    if (ttlSeconds !== undefined && !Number.isFinite(ttlSeconds)) {
+      throw new RangeError("ttlSeconds must produce a finite expiration timestamp");
+    }
+    if (!ttlSeconds) return null;
+    const expiry = now + ttlSeconds * 1000;
+    if (!Number.isFinite(expiry)) {
+      throw new RangeError("ttlSeconds must produce a finite expiration timestamp");
+    }
+    return expiry;
+  };
   const changed = (result: D1Result) => result.meta.changes > 0;
   return {
     async get(key) {
@@ -31,6 +40,7 @@ export function d1Storage(db: D1Database): KVStorage {
     },
     async set(key, value, opts) {
       const now = Date.now();
+      const expiry = expiresAt(now, opts?.ttlSeconds);
       await db.batch([
         db
           .prepare(
@@ -46,7 +56,7 @@ export function d1Storage(db: D1Database): KVStorage {
              ON CONFLICT (key) DO UPDATE SET
                value = excluded.value, expires_at_ms = excluded.expires_at_ms`,
           )
-          .bind(key, value, expiresAt(now, opts?.ttlSeconds)),
+          .bind(key, value, expiry),
       ]);
     },
     async delete(key) {
@@ -56,7 +66,7 @@ export function d1Storage(db: D1Database): KVStorage {
       const { results } = await db
         .prepare(
           `SELECT key FROM connecta_kv
-           WHERE key >= ?1 AND substr(key, 1, length(?1)) = ?1 AND ${live}`,
+           WHERE key >= ?1 AND substr(CAST(key AS BLOB), 1, length(CAST(?1 AS BLOB))) = CAST(?1 AS BLOB) AND ${live}`,
         )
         .bind(prefix, Date.now())
         .all<{ key: string }>();
@@ -84,7 +94,19 @@ export function d1Storage(db: D1Database): KVStorage {
             .run(),
         );
       }
-      const expiry = expiresAt(now, opts?.ttlSeconds);
+      let expiry: number | null;
+      try {
+        expiry = expiresAt(now, opts?.ttlSeconds);
+      } catch (error) {
+        // Invalid write options do not change a failed comparison's result.
+        // Ordinary claims still use one atomic statement without this read.
+        const current = await db
+          .prepare(`SELECT value FROM connecta_kv WHERE key = ?1 AND ${live}`)
+          .bind(key, now)
+          .first<{ value: string }>();
+        if ((current?.value ?? null) !== expected) return false;
+        throw error;
+      }
       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.

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 eight-tool surface.
+ * wrangler.jsonc backs the seven-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
@@ -76,14 +76,6 @@ function build(env: Env) {
     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

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.26.3",
+  "version": "0.28.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 eight meta-tools.",
+  "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of seven meta-tools.",
   "license": "MIT",
   "engines": {
     "node": ">=22.0.0"
@@ -154,7 +154,7 @@
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/client": "2.0.0",
     "@modelcontextprotocol/server": "2.0.0",
-    "effect": "4.0.0-rc.117",
+    "effect": "4.0.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
@@ -186,7 +186,7 @@
     "preact": "^10.29.8",
     "quickjs-emscripten": "^0.32.0",
     "tsx": "^4.23.1",
-    "typescript": "^5.6.0",
+    "typescript": "^5.9.3",
     "vitest": "^4.1.6",
     "wrangler": "^4.114.0"
   }

package/templates/node/AGENTS.md

@@ -3,9 +3,10 @@
 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 eight-tool code-first
-  surface. File storage supports resumable writes, so a program pauses at a
-  write until `resume_execution` approves it.
+- Keep `executor: quickJsExecutor()` for the prescribed seven-tool code-first
+  surface. Programs run read-only tools and any writes `execute.approval`
+  exempts; every other write is its own `call_destructive_tool` call, which
+  the MCP host asks about.
 - Keep credentials in environment variables or an external secret store.
   Never commit `.env`, `.connecta-state.json`, `.connecta-activity.jsonl`,
   tokens, or credential values.

package/templates/node/README.md

@@ -159,17 +159,16 @@ npm run typecheck
 CONNECTA_TOKEN=dev-token npm run doctor
 ```
 
-Doctor checks health, the executor, and the exact prescribed eight-tool
+Doctor checks health, the executor, and the exact prescribed seven-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, eight tools, plus any catalog drift, and
-a note if resumable writes are off:
+connector count, QuickJS executed, seven tools, plus any catalog drift:
 
 ```text
-Connecta doctor passed: 1 connector(s), QuickJS executed, prescribed eight-tool surface.
+Connecta doctor passed: 1 connector(s), QuickJS executed, prescribed seven-tool surface.
 ```
 
 `QuickJS` is this deployment's sandbox, reported by the deployment itself —

package/templates/node/package.json

@@ -15,12 +15,12 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zackbart/connecta": "0.26.3",
+    "@zackbart/connecta": "0.28.0",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "tsx": "^4.23.1",
-    "typescript": "^5.6.0"
+    "typescript": "^5.9.3"
   }
 }