@zackbart/connecta 0.26.2 → 0.27.0

package/AGENTS.md

@@ -141,14 +141,14 @@ an unclassified, double-classified, stale, or reasonless entry.
   Promise-based and name no Effect type: a deployment author should never need
   a second async paradigm to write a connector, so convert at the boundary,
   not in the caller. Effect is a hard dependency pinned to one exact version,
-  never a range, and it is the version Alchemy pins, so a deployment that uses
-  both resolves one Effect rather than two. `effect/unstable/*` modules are
-  allowed, which is exactly why the pin is exact: they break in minor releases,
+  never a range, and compatible with Alchemy's peer requirement, so a deployment
+  that uses both resolves one Effect rather than two. Modules tagged
+  `@stability unstable` are allowed behind subpaths: they can break in minor releases,
   so an upgrade is its own deliberate pull request, never a drive-by in another
   change. `effect/testing` stays out of `src/` (see import-graph purity). The
   MCP edges do not move with the core — `@modelcontextprotocol/server` upward,
-  the SDK client downstream; Effect's `McpServer` is parked until the Effect
-  core is stable and those edges are re-proven.
+  the SDK client downstream. Replacing either requires separate proof of the
+  wire contracts and request lifetimes; the stable core release is not that proof.
 - **Style.** There is no formatter. Match the surrounding code. The docs voice
   is precise, occasionally wry, and always explains *why* — don't flatten it
   into boilerplate.

package/CHANGELOG.md

@@ -2,7 +2,92 @@
 
 All notable changes to this package are documented here.
 
-## Unreleased
+## 0.27.0 — 2026-10-01
+
+This minor release moves the runtime to stable Effect v4 and fixes execution,
+OAuth, storage, and operator recovery. Deployment APIs and the eight MCP tools
+keep their existing contracts, and the Node template now pins 0.27.0.
+Development requires TypeScript 5.9.3 or newer within 5.x.
+
+Duplicate API tool names now fail at construction. Memory, file, and D1 storage
+refuse TTLs that cannot produce finite expirations. Artifact quotas reserve 8 KiB
+for frame metadata, reducing the available content allowance by 4 KiB, and apply
+to historical snapshots too. Artifact render checks use the deployment's viewer
+theme.
+
+### Changed
+
+- Pin Effect to `4.0.0`, replacing `4.0.0-rc.117`, and align the optional
+  Alchemy setup instructions with the stable pin.
+- Require TypeScript 5.9.3 or newer within 5.x for repository and Node-template
+  development, matching Effect v4's TypeScript 5.9 minimum.
+
+### Fixed
+
+- Refuse already-aborted deadline operations and preserve explicit `null`
+  cancellation reasons (#660) (#661).
+- Return structured failures for malformed executor replies (#662).
+- Close callback and credential-test connector scopes after their final use,
+  keeping cleanup bounded and best-effort (#663) (#664).
+- Prevent concurrent OAuth state handoffs from replacing another owner on
+  storage that supports atomic claims (#665).
+- Show retryable Activity errors for unreadable pages and discard superseded
+  pagination responses (#666) (#667).
+- Reject invalid TTLs in memory and D1 storage before mutation, and match NUL
+  bytes literally in D1 list prefixes (#668) (#669).
+- Enforce catalog count and byte ceilings even when discovery is invalidated
+  while the listing is in flight (#644).
+- Retain OAuth cleanup lineage after uncertain storage commits, preserve
+  concurrent token rotation and revocation during issuer migration, and isolate
+  refresh coordination by credential owner (#645) (#646) (#648).
+- Return `null` for absent prototype-named credential fields (#647).
+- Reserve enough artifact frame metadata for valid document names and titles,
+  enforce current quotas on historical snapshots, and reject refresh scan
+  cursors that fail to advance (#649) (#658) (#650).
+- Reconcile connector state after failed operator mutations, ignore older data
+  reloads, and keep malformed collection responses recoverable (#651) (#652)
+  (#653).
+- Keep committed file snapshots consistent after rename, quarantine malformed
+  entries, and reject TTLs that cannot produce finite expirations (#654) (#655)
+  (#656).
+- Reject unreadable successful responses and malformed build-log streams from
+  named Vercel tools, preserving raw API response bodies and no-content
+  mutations (#657).
+- Keep queued catalog mutations alive across Worker requests while preserving
+  cancellation and storage ordering (#623).
+- Release failed access-token reservations before lookup publication, close
+  failed OAuth callback transports, and persist accepted rotating refresh tokens
+  after owner cancellation without reviving disconnected generations (#624)
+  (#625) (#626).
+- Count historical writes across divergent resumptions and bound resumed write
+  answers by the journal limit, retaining truthful outcomes for writes already
+  sent (#627) (#628).
+- Roll back rejected file-storage mutations, preserve prototype-named keys,
+  expire entries at their TTL boundary, and quarantine invalid snapshot roots
+  without losing their original bytes (#629) (#630) (#631) (#632).
+- Ignore superseded artifact-list responses, preserve newly created tokens when
+  an older list finishes, and reload a confined artifact shell when signing in
+  again (#633) (#634) (#635).
+- Advance artifact listings through empty continuation pages, refuse already
+  cancelled render checks, and validate Markdown with the viewer's theme across
+  writes and refreshes (#636) (#637) (#638).
+- Prevent doctor redirects from forwarding Cloudflare Access credentials,
+  reject unreadable successful Notion responses, and reject duplicate API tool
+  names before classification and dispatch can disagree (#639) (#640) (#641).
+
+## 0.26.3 — 2026-09-28
+
+This patch lets downstream OAuth connections use a public client metadata
+URL when a server supports URL-based client IDs but restricts dynamic
+registration. Existing OAuth configurations keep their current behavior.
+The Node template now pins 0.26.3.
+
+### Added
+
+- `remoteMcp` OAuth auth accepts `clientMetadataUrl` and default `scope`.
+  The SDK negotiates URL-based client IDs, falling back to dynamic registration
+  when unsupported. Existing PKCE, issuer binding, encrypted storage, refresh,
+  and disconnect remain in use. Invalid settings fail at construction.
 
 ## 0.26.2 — 2026-09-27
 

package/bin/connecta.mjs

@@ -132,10 +132,18 @@ const DOCTOR_TIMEOUT_MS = 10_000;
 
 async function doctorFetch(url, init = {}) {
   try {
-    return await fetch(url, {
+    const response = await fetch(url, {
       ...init,
+      redirect: "manual",
       signal: AbortSignal.timeout(DOCTOR_TIMEOUT_MS),
     });
+    if ([301, 302, 303, 307, 308].includes(response.status)) {
+      await response.body?.cancel().catch(() => {});
+      throw new Error(
+        `HTTP ${response.status} redirect refused: doctor sends authentication only to the configured deployment URL.`,
+      );
+    }
+    return response;
   } catch (error) {
     if (
       error instanceof Error &&

package/dist/access-tokens.js

@@ -191,8 +191,19 @@ export class AccessTokenManager {
                 ? {}
                 : { principal: { ...createdBy } }),
         };
-        await this.updateActive(record.id, true);
-        await this.storage.set(recordKey(record.id), JSON.stringify(record));
+        try {
+            await this.updateActive(record.id, true);
+            await this.storage.set(recordKey(record.id), JSON.stringify(record));
+        }
+        catch (error) {
+            // No lookup write has started, so this secret can never authenticate.
+            // A failed record or reservation write may still have committed: revoke
+            // whatever metadata exists and release the reservation even on a miss.
+            const revoked = await this.revoke(record.id, record.createdBy);
+            if (!revoked)
+                await this.updateActive(record.id, false);
+            throw error;
+        }
         // A failed lookup write may have committed. Keep its reservation and
         // metadata, so a manager can revoke it without ever returning the secret.
         await this.storage.set(lookupKey(hash), JSON.stringify({ version: 1, id: record.id }));

package/dist/artifacts/connector.d.ts

@@ -1,3 +1,4 @@
+import { type ResolvedTheme } from "../branding.js";
 import type { Connector } from "../types.js";
 import { type ArtifactOperations } from "./operations.js";
 import { type ArtifactRefreshService } from "./refresh.js";
@@ -50,6 +51,8 @@ export interface ArtifactsConnectorOptions {
     renderCheck?: ArtifactRenderCheck;
     /** Where pages are served, when not the deployment's own origin. */
     origin?: string;
+    /** Resolved deployment theme, available after the module binds to core. */
+    theme?: () => ResolvedTheme | undefined;
 }
 export declare function artifactsConnector(options: ArtifactsConnectorOptions): Connector;
 export {};

package/dist/artifacts/connector.js

@@ -9,6 +9,7 @@
 import { api } from "../connectors/api.js";
 import { callerOf } from "../connector-caller.js";
 import { ConnectorCallError } from "../errors.js";
+import { resolveTheme } from "../branding.js";
 import { buildFrameDocument, frameCsp } from "./document.js";
 import { buildGuide, GUIDE_SUMMARY } from "./guide.js";
 import { invalidContent, } from "./operations.js";
@@ -56,6 +57,9 @@ function renderFindings(values) {
 }
 /** Run a hook under its 20-second deadline and the call's own signal. Never throws. */
 export async function runRenderCheck(hook, input, callSignal) {
+    if (callSignal?.aborted) {
+        return { ok: false, unavailable: "The render check's call was cancelled; nothing was saved." };
+    }
     const controller = new AbortController();
     let timer;
     const onAbort = () => controller.abort(callSignal?.reason);
@@ -162,6 +166,7 @@ export function artifactsConnector(options) {
                 document: buildFrameDocument({
                     kind: head.kind,
                     source,
+                    theme: options.theme?.() ?? resolveTheme(),
                     global: globalFor(artifactId, head, head.view, liveOf(head), false),
                     data,
                 }),
@@ -450,6 +455,7 @@ export function artifactsConnector(options) {
                         document: buildFrameDocument({
                             kind: args.kind,
                             source: args.source,
+                            theme: options.theme?.() ?? resolveTheme(),
                             global: {
                                 id: "preview",
                                 title: "Preview",

package/dist/artifacts/document.js

@@ -8,6 +8,12 @@
 import { scanHtml } from "./html-scan.js";
 import { scriptSafeJson } from "./json.js";
 import { markdownPage, MarkdownNestingError } from "./markdown.js";
+/**
+ * Reserve for the injected global and Markdown theme beyond source and data.
+ * Sixteen 64-character document names appear twice, alongside timestamps and
+ * versions, and a 160-character title can expand sixfold when script-escaped.
+ */
+export const FRAME_OVERHEAD_BYTES = 8192;
 /**
  * The frame's Content-Security-Policy. `sandbox allow-scripts` without
  * `allow-same-origin` gives the page an opaque origin — no cookies, no

package/dist/artifacts/module.js

@@ -1,4 +1,5 @@
 // artifacts(): the typed module a deployment passes as `ConnectaConfig.artifacts`.
+import { resolveBranding } from "../branding.js";
 import { artifactsConnector } from "./connector.js";
 import { ArtifactOperations } from "./operations.js";
 import { artifactRoutes } from "./routes.js";
@@ -43,17 +44,22 @@ export function artifacts(options) {
         limits,
     });
     const refresh = new ArtifactRefreshService(operations);
+    let theme;
     const connector = artifactsConnector({
         operations,
         refresh,
         allowlist,
         limits,
+        theme: () => theme,
         ...(options.renderCheck ? { renderCheck: options.renderCheck } : {}),
     });
     return Object.freeze({
         connector,
         handle: artifactRoutes({ operations, allowlist }),
-        bindRefresh: (runtime) => refresh.bind(runtime),
+        bindRefresh: (runtime) => {
+            refresh.bind(runtime);
+            theme = resolveBranding(runtime.branding).theme;
+        },
         refresh: (id, by) => refresh.run(id, { manual: by }),
         runDue: () => refresh.runDue(),
     });

package/dist/artifacts/operations.d.ts

@@ -1,3 +1,4 @@
+import type { ResolvedTheme } from "../branding.js";
 import { type CheckContext } from "./validate.js";
 import type { ArtifactActor, ArtifactHeadRecord, ArtifactIssue, ArtifactKind, ArtifactStore, ArtifactValidation, ArtifactVersionRecord, ArtifactRefreshSchedule, ArtifactRunRecord } from "./types.js";
 type ArtifactFailureCode = "conflict" | "invalid_args" | "not_found" | "unavailable";
@@ -164,10 +165,11 @@ export declare class ArtifactOperations {
     page(id: string, pin?: {
         view?: number;
         documents?: Record<string, number>;
-    }): Promise<Result<{
+    }, theme?: ResolvedTheme): Promise<Result<{
         head: ArtifactHeadRecord;
         view: ArtifactVersionRecord;
         source: string;
+        document: string;
         documents: Record<string, {
             record: ArtifactVersionRecord;
             value: unknown;

package/dist/artifacts/operations.js

@@ -15,6 +15,7 @@
 // `{ ok: false, code, message }`, and the connector turns that into its typed
 // error; a throw means storage failed.
 import { sha256Hex, utf8Bytes } from "../run-journal.js";
+import { buildFrameDocument, FRAME_OVERHEAD_BYTES } from "./document.js";
 import { markdownPage, MarkdownNestingError } from "./markdown.js";
 import { ARTIFACT_ID, checkDocument, checkDocumentTotals, checkView, finish, validDocumentName, } from "./validate.js";
 /** Physical head moves a write absorbs before giving up as busy. */
@@ -23,8 +24,6 @@ const MAX_SWAP_ATTEMPTS = 8;
 const HISTORY_LIMIT = 20;
 /** Heads one listing call may examine while searching. */
 const LIST_SCAN_LIMIT = 1000;
-/** What the viewer adds around a page beyond its source and documents. */
-const FRAME_OVERHEAD_BYTES = 4096;
 /** Tombstones keep version numbers, so distinct names need their own bound. */
 const DOCUMENT_NAMES_LIMIT = 64;
 const fail = (code, message, extra = {}) => ({ ok: false, code, message, ...extra });
@@ -827,7 +826,7 @@ export class ArtifactOperations {
         return { ok: true, head: current.head, record, value, history };
     }
     /** The page a viewer renders: a view version and exactly the documents asked for (all current ones by default). */
-    async page(id, pin = {}) {
+    async page(id, pin = {}, theme) {
         const badId = this.#checkId(id);
         if (badId)
             return badId;
@@ -841,7 +840,10 @@ export class ArtifactOperations {
         const wanted = pin.documents
             ? Object.entries(pin.documents)
             : liveDocuments(head).map(([name, record]) => [name, record.version]);
-        const documents = {};
+        // Historical streams were each valid when written, but their selected
+        // versions may never have coexisted. Bound the selection before loading
+        // its bodies, then check the actual bodies against today's configuration.
+        const selected = [];
         for (const [name, version] of wanted) {
             const badName = this.#checkDocumentName(name);
             if (badName)
@@ -849,11 +851,58 @@ export class ArtifactOperations {
             const record = await this.#version(id, `doc:${name}`, head.documents[name], version);
             if (!record)
                 return this.#notFound(id);
-            if (record.removed)
-                continue;
-            documents[name] = { record, value: JSON.parse(await this.#body(record.body)) };
+            if (!record.removed)
+                selected.push([name, record]);
+        }
+        const { limits } = this.#context;
+        const tooMany = checkDocumentTotals(selected.length, 0, limits);
+        if (tooMany)
+            return invalidContent("The snapshot", finish({ errors: [tooMany], warnings: [] }));
+        const source = await this.#body(view.body);
+        const sourceBytes = utf8Bytes(source);
+        if (sourceBytes > limits.sourceBytes) {
+            return invalidContent("The snapshot", finish({ errors: [{
+                        code: "E_TOO_LARGE", severity: "error",
+                        message: `The view is ${sourceBytes} bytes; the limit is ${limits.sourceBytes}.`,
+                    }], warnings: [] }));
         }
-        return { ok: true, head, view, source: await this.#body(view.body), documents };
+        const documents = {};
+        const data = {};
+        let dataBytes = 0;
+        for (const [name, record] of selected) {
+            const value = JSON.parse(await this.#body(record.body));
+            const checked = checkDocument(name, value, limits);
+            if (checked.error)
+                return invalidContent("The snapshot", finish({ errors: [checked.error], warnings: [] }));
+            dataBytes += checked.bytes;
+            const totals = checkDocumentTotals(selected.length, dataBytes, limits);
+            if (totals)
+                return invalidContent("The snapshot", finish({ errors: [totals], warnings: [] }));
+            documents[name] = { record, value };
+            data[name] = checked.text;
+        }
+        const tooLarge = () => invalidContent("The snapshot", finish({ errors: [{
+                    code: "E_TOO_LARGE", severity: "error",
+                    message: `The rendered page exceeds the current limit of ${limits.renderedBytes} bytes.`,
+                }], warnings: [] }));
+        // For HTML, source plus data is a lower bound before frame construction.
+        // Markdown can shrink or expand, so its final document decides the bound.
+        if (dataBytes + (head.kind === "html" ? sourceBytes : 0) > limits.renderedBytes)
+            return tooLarge();
+        const rendered = buildFrameDocument({
+            kind: head.kind, source, ...(theme ? { theme } : {}),
+            global: {
+                id, title: head.title, view: { version: view.version },
+                documents: Object.fromEntries(selected.map(([name, record]) => [name, {
+                        version: record.version, updatedAt: record.at,
+                    }])),
+                snapshot: pin.view !== undefined || pin.documents !== undefined,
+            },
+            data,
+        });
+        if (utf8Bytes(rendered) > limits.renderedBytes)
+            return tooLarge();
+        return { ok: true, head, view, source, document: rendered, documents };
     }
     async list(options) {
         if (options.cursor !== undefined && !ARTIFACT_ID.test(options.cursor)) {
@@ -864,9 +913,11 @@ export class ArtifactOperations {
         let after = options.cursor;
         let scanned = 0;
         for (;;) {
+            const limit = Math.min(100, LIST_SCAN_LIMIT - scanned);
+            const previous = after;
             const page = await this.#store.heads({
                 ...(after === undefined ? {} : { after }),
-                limit: Math.min(100, LIST_SCAN_LIMIT - scanned),
+                limit,
             });
             for (const item of page.heads) {
                 scanned++;
@@ -885,8 +936,15 @@ export class ArtifactOperations {
             }
             if (page.next === undefined)
                 return { ok: true, items };
+            if (previous !== undefined && page.next <= previous) {
+                return fail("unavailable", "Artifact head scan did not advance; retry the listing.");
+            }
+            // Listed keys can disappear before the store reads them. Its cursor
+            // still consumed the whole page, including those missing head records.
+            after = page.next;
+            scanned += Math.max(0, limit - page.heads.length);
             if (scanned >= LIST_SCAN_LIMIT) {
-                return after === undefined ? { ok: true, items } : { ok: true, items, nextCursor: after };
+                return { ok: true, items, nextCursor: after };
             }
         }
     }

package/dist/artifacts/refresh.d.ts

@@ -28,6 +28,8 @@ export interface ArtifactRefreshRuntime {
         isError?: boolean;
     }>;
     claimMs: number;
+    /** UI branding shared by the viewer and every render check. */
+    branding?: import("../types.js").ConnectaBranding;
 }
 export type RefreshOutcome = {
     status: "skipped";

package/dist/artifacts/refresh.js

@@ -179,10 +179,11 @@ export class ArtifactRefreshService {
                 ...(after ? { after } : {}),
                 limit,
             });
+            if (page.next !== undefined && after !== undefined && page.next <= after) {
+                throw new Error("Artifact head scan did not advance.");
+            }
             if (!page.heads.length) {
                 if (page.next) {
-                    if (page.next === after)
-                        throw new Error("Artifact head scan did not advance.");
                     after = page.next;
                     scanned += limit;
                     continue;

package/dist/artifacts/routes.js

@@ -13,7 +13,7 @@ import { resolveActorLabels, actorKey } from "../routes/actor-labels.js";
 import { authorize, mayViewArtifacts, privateJson, validateAuthPermissions, } from "../routes/shared.js";
 import { resolveBranding, schemeAttribute, themeCss } from "../branding.js";
 import { TOKENS_CSS } from "../page-styles.js";
-import { buildFrameDocument, frameCsp } from "./document.js";
+import { frameCsp } from "./document.js";
 import { scriptSafeJson } from "./json.js";
 import { freshnessOf } from "./refresh.js";
 import { ARTIFACT_ID } from "./validate.js";
@@ -142,7 +142,8 @@ export function artifactRoutes(options) {
             }
             pin = { view: Number(pinned), documents };
         }
-        const page = await ops.page(id, pin ?? {});
+        const theme = resolveBranding(context.opts.branding).theme;
+        const page = await ops.page(id, pin ?? {}, theme);
         if (!page.ok)
             return notFound();
         const origin = new URL(context.baseUrl).origin;
@@ -170,19 +171,7 @@ export function artifactRoutes(options) {
             freshness: freshnessOf(page.head),
             url,
             snapshotUrl: `${url}/v/${page.view.version}${pins.length ? `?${pins.join("&")}` : ""}`,
-            document: buildFrameDocument({
-                kind: page.head.kind,
-                source: page.source,
-                theme: resolveBranding(context.opts.branding).theme,
-                global: {
-                    id,
-                    title: page.head.title,
-                    view: { version: page.view.version },
-                    documents: Object.fromEntries(documents.map(({ name, version, updatedAt }) => [name, { version, updatedAt }])),
-                    snapshot: pin !== undefined,
-                },
-                data: Object.fromEntries(Object.entries(page.documents).map(([name, { value }]) => [name, scriptSafeJson(value)])),
-            }),
+            document: page.document,
         });
     };
     return async (context) => {

package/dist/artifacts/validate.js

@@ -10,6 +10,7 @@ import { boundedEchoText } from "../errors.js";
 import { utf8Bytes } from "../run-journal.js";
 import { lineLocator, scanHtml } from "./html-scan.js";
 import { jsonProblem, scriptSafeJson } from "./json.js";
+import { FRAME_OVERHEAD_BYTES } from "./document.js";
 import { markdownPage, MarkdownNestingError } from "./markdown.js";
 import { DEFAULT_ARTIFACT_ALLOWLIST, DEFAULT_ARTIFACT_LIMITS, } from "./types.js";
 /** An artifact id: the URL slug. No leading `_`, so `_api` and `_frame` stay free. */
@@ -23,8 +24,6 @@ export function validDocumentName(name) {
 }
 const MAX_REPORTED = 20;
 const QUOTE_BYTES = 120;
-/** What the viewer adds around a page beyond its source and documents. */
-const FRAME_OVERHEAD_BYTES = 4096;
 const quote = (text) => boundedEchoText(text, QUOTE_BYTES);
 const count = (n) => n.toLocaleString("en-US");
 const kib = (bytes) => bytes % (1024 * 1024) === 0