@zackbart/connecta 0.27.0 → 0.28.1

package/dist/executors/quickjs.js

@@ -357,7 +357,7 @@ class QuickJsChildPool {
             // Do not copy deployment credentials or Node startup configuration into
             // the process that contains the guest runtime. `TZ` alone is set: the
             // guest's local-time methods read the child's zone, and pinning it to
-            // UTC makes them the same on every host, like a Dynamic Worker's (P6).
+            // UTC makes them the same on every host, like a Dynamic Worker's (X5).
             env: { TZ: "UTC" },
             execArgv: sourceMode ? ["--import", "tsx"] : [],
             stdio: ["ignore", "ignore", "pipe", "ipc"],

package/dist/exempt-writes.js

@@ -0,0 +1,162 @@
+// The writes a program may send: config-exempt ones (#566), and nothing else.
+//
+// Every other write a program attempts is refused
+// `destructive_tool_requires_approval` before it is validated or sent (E4),
+// so the host's prompt on `call_destructive_tool` stays the only approval.
+// An exempt write is still a write, though, and it gets what a write needs:
+// its own budget, a dispatch the run waits for rather than aborts, and a
+// result that never hides a write whose outcome is unknown.
+//
+// Web-API only, like everything reachable from the root entry.
+import { Effect } from "effect";
+import { jsonResult } from "./meta-tools.js";
+/** Writes one program may send (`execute.maxWrites`), unless configured. */
+export const DEFAULT_MAX_WRITES = 10;
+/**
+ * Whether a write landed, as far as anyone can know.
+ *
+ * `unknown` is the outcome a result must never paper over: the call left
+ * connecta and no answer came back, so sending it again could do it twice and
+ * not sending it could leave it undone. That is a dispatched call that timed
+ * out, was cancelled, found the service unavailable, or failed any way that
+ * is not a verdict. A refusal code (`REFUSALS`) or a downstream tool's own
+ * `isError` is an answer, so it is `failed`, except that an `isError` whose text
+ * classifies as a timeout is a gateway reporting that it gave up, and stays
+ * unknown. A call that was never dispatched is `failed`: nothing was sent.
+ * `result_processing_failed` means the downstream call completed.
+ */
+export function classifyWriteOutcome(outcome) {
+    if (outcome.ok)
+        return "ok";
+    if (!outcome.dispatched)
+        return "failed";
+    const code = outcome.error?.code;
+    if (code === "result_processing_failed")
+        return "ok";
+    if (code === "timeout" || code === "cancelled" || code === "unavailable") {
+        return "unknown";
+    }
+    if (code !== undefined && REFUSALS.has(code))
+        return "failed";
+    return outcome.answered === true ? "failed" : "unknown";
+}
+/**
+ * Codes that say the other side refused the call rather than acted on it:
+ * the credential, the arguments, the resource, the rate, or a base version
+ * someone else already moved past (`conflict`). Anything else a
+ * connector reports after dispatch — `connector_call_failed` from a response
+ * too large to read, a redirect it would not follow, a body it could not
+ * parse, a 5xx — may come after the write landed, so only a downstream
+ * tool's own `isError` answer makes it a known failure.
+ */
+const REFUSALS = new Set([
+    "auth_required",
+    "invalid_args",
+    "not_found",
+    "rate_limited",
+    "input_required_unsupported",
+    "conflict",
+]);
+/** What a dispatched write's outcome says about whether it landed. */
+export function writeStateOf(outcome) {
+    return classifyWriteOutcome(outcome.ok
+        ? { ok: true, dispatched: outcome.dispatched }
+        : {
+            ok: false,
+            dispatched: outcome.dispatched,
+            error: outcome.error,
+            ...(outcome.answered !== undefined ? { answered: outcome.answered } : {}),
+        });
+}
+/**
+ * The exempt writes one program sends. The play closes this when the
+ * program settles — a write that reaches the gate after is not sent — and
+ * drains what is on the wire before the run's scope aborts it, so the write
+ * finishes and its activity says how it did. The result never hides a write
+ * whose outcome is unknown, and a program that fails after writing reports
+ * the counts.
+ */
+export class ExemptWrites {
+    closed = false;
+    inFlight = new Set();
+    states = [];
+    /** Whether the program has settled: a write gated now is not sent. */
+    get isClosed() {
+        return this.closed;
+    }
+    close() {
+        this.closed = true;
+    }
+    /** A write is being dispatched; the function returned records how it ended. */
+    begin() {
+        let done = () => { };
+        const settled = new Promise((resolve) => {
+            done = resolve;
+        });
+        this.inFlight.add(settled);
+        let recorded = false;
+        return (state) => {
+            if (recorded)
+                return;
+            recorded = true;
+            this.states.push(state);
+            this.inFlight.delete(settled);
+            done();
+        };
+    }
+    /** Wait for dispatched writes, each bounded by its host-call deadline. */
+    drain() {
+        return Effect.promise(async () => {
+            while (this.inFlight.size > 0)
+                await Promise.all(this.inFlight);
+        });
+    }
+    finish(result) {
+        if (this.states.length === 0)
+            return result;
+        const writes = {
+            succeeded: this.states.filter((state) => state === "ok").length,
+            failed: this.states.filter((state) => state === "failed").length,
+            unknown: this.states.filter((state) => state === "unknown").length,
+        };
+        if (writes.unknown > 0) {
+            return errorEnvelope({
+                code: "write_outcome_unknown",
+                message: "A write this program sent has no known outcome, so that is the result rather than what the program returned. It will not be sent again. Check its target before doing anything that depends on it.",
+                retryable: false,
+                writes,
+            });
+        }
+        return result.isError ? withWrites(result, writes) : result;
+    }
+}
+/**
+ * An error result from a program that sent writes, carrying their counts: a
+ * program that fails after writing is not a program that is safe to repeat.
+ */
+function withWrites(result, writes) {
+    const structured = result.structuredContent;
+    const error = structured?.error;
+    const annotated = errorEnvelope({
+        ...(error !== null && typeof error === "object"
+            ? error
+            : {
+                code: "executor_failed",
+                message: result.content[0]?.text ?? "",
+                retryable: false,
+            }),
+        writes,
+        note: "This run attempted writes, counted in writes; those that succeeded are not undone. Check them before running the task again.",
+    });
+    if (structured && error !== null && typeof error === "object") {
+        const { error: _replaced, ...rest } = structured;
+        annotated.structuredContent = { ...rest, error: annotated.structuredContent?.error };
+        annotated.content = [{ type: "text", text: JSON.stringify(annotated.structuredContent) }];
+    }
+    return annotated;
+}
+function errorEnvelope(error) {
+    const result = jsonResult({ error });
+    result.isError = true;
+    return result;
+}

package/dist/index.d.ts

@@ -92,43 +92,24 @@ export interface ConnectaExecuteConfig {
      */
     watchdogMs?: number;
     /**
-     * Let programs write. A call to a tool that is not explicitly read-only
-     * pauses the run before anything is sent and returns the exact write with
-     * a token; `resume_execution` repeating it is the approval, and the
-     * program replays from a journal to send it and continue. Needs `storage`
-     * with `compareAndSet`, because two resumes of one pause must send its
-     * writes at most once. Omitted, it is on exactly when the storage has one
-     * (a single startup warning says when it is not); `true` over storage
-     * without one refuses to construct; `false` keeps E4's refusal.
-     * `resume_execution` is listed either way.
-     */
-    resumableWrites?: boolean;
-    /**
-     * Consequential calls one run may send, on top of the host-call budget
-     * every call already spends. Default 10. A replayed write spends it again,
-     * so it bounds the run, not each play. Invalid values fall back to the
-     * default.
+     * Config-exempt writes one program may send, on top of the host-call
+     * budget every call already spends. Default 10. Invalid values fall back
+     * to the default.
      */
     maxWrites?: number;
     /**
-     * How long a paused run can be resumed, in seconds from its first pause.
-     * Default 1_800. A later pause in the same run keeps the first deadline, so
-     * a run never replays reads older than this. Invalid values fall back to
-     * the default.
-     */
-    pausedRunTtlSeconds?: number;
-    /**
-     * Which writes a program may make without pausing for approval. Keys are
+     * Which writes a program may make without asking. A program runs only
+     * explicitly read-only tools and these; every other write is refused and
+     * goes through `call_destructive_tool`, where the host asks. Keys are
      * connector ids (all of that connector's tools) or `connector.tool`
      * addresses (that tool); values are `"never"` (never ask) or `"ask"`. The
      * most specific key wins, and `"ask"` switches off a connector's own
-     * default. An exempt write still spends the write budget, is recorded in
-     * activity, and is journaled like any other; it is never read-only
-     * anywhere else — discovery still lists it as approval-required and
-     * `call_tool` still refuses it. Works with resumable writes off too. An
-     * unknown connector id, or an `api()` address its tools do not include,
-     * refuses to construct; a remote connector's tool names load later, so an
-     * address naming one it never serves simply never matches.
+     * default. An exempt write still spends the write budget and is recorded
+     * in activity; it is never read-only anywhere else — discovery still lists
+     * it as approval-required and `call_tool` still refuses it. An unknown
+     * connector id, or an `api()` address its tools do not include, refuses to
+     * construct; a remote connector's tool names load later, so an address
+     * naming one it never serves simply never matches.
      */
     approval?: Readonly<Record<string, "never" | "ask">>;
 }
@@ -290,6 +271,6 @@ export { memoryStorage } from "./storage/memory.js";
 export { CONNECTA_VERSION } from "./version.js";
 export type { Registry } from "./registry.js";
 export type { RemoteMcpOptions, RemoteMcpAuth, RemoteMcpRedirectPolicy, } from "./connectors/remote-mcp.js";
-export type { ApiOptions, ApiTool } from "./connectors/api.js";
+export type { ApiHandlerContext, ApiOAuthAccess, ApiOAuthClientAuthentication, ApiOAuthConfig, ApiOptions, ApiTool, } from "./connectors/api.js";
 export type { CatalogDriftCounts, CatalogDriftReport, ConnectaBranding, ConnectaTheme, Connector, ConnectorCallAdmissionInput, ConnectorCallAdmissionPolicy, ConnectorCallAdmissionRule, ConnectorRollingWindowBudget, ConnectorCredentialAccess, ConnectorCredentialConfig, ConnectorCredentialFieldConfig, ConnectorCredentialValues, ConnectorContext, ConnectorUsageGuide, ConnectorStatus, CredentialTestResult, AdmittingExecutor, AdmissionSnapshot, ExecuteResult, Executor, ExecutorLease, ExecutorProvider, InboundAuth, InboundAuthRuntimeContext, UiAuthConfig, AuthResult, AuthenticatedIdentity, IdentityReference, JsonSchema, KVStorage, Logger, ToolDef, ToolAnnotations, } from "./types.js";
 export type { ActivityActor, ActivityCallSource, ActivityOutcome, ActivityPage, ActivityReadActor, ActivityReadEvent, ActivityReader, ActivityReadGate, ActivityReadPage, ActivitySink, ActivityStore, AgentFriction, CatalogDriftActivityEvent, ToolCallActivityEvent, } from "./activity.js";

package/dist/index.js

@@ -2,12 +2,12 @@ import { credentialTestRule, describeCredentialTestMismatch, } from "./credentia
 import { Registry } from "./registry.js";
 import { intersectAccess, parseConnectorAccess, POOL_NAME_RE } from "./connector-access.js";
 import { createFetchHandler } from "./server.js";
-import { createProgramRunner } from "./execute.js";
+import { createExecuteTool, runClaimMs } from "./execute.js";
 import { droppedBrandingUrls, droppedThemeTokens, droppedUiAuthUrls, } from "./branding.js";
 import { memoryStorage } from "./storage/memory.js";
 import { CONNECTA_VERSION } from "./version.js";
 import { AdmissionController, executorName, isAdmittingExecutor, withExecutorAdmission, } from "./executor-admission.js";
-import { DEFAULT_MAX_WRITES, DEFAULT_PAUSED_RUN_TTL_SECONDS, } from "./resumable.js";
+import { DEFAULT_MAX_WRITES } from "./exempt-writes.js";
 import { disposeEdgeRuntime } from "./runtime/run.js";
 import { NO_EXEMPTIONS } from "./tool-safety.js";
 import { createCoreRuntime, resolveLogger } from "./runtime/services.js";
@@ -92,9 +92,7 @@ const CONFIG_SCHEMA = {
         maxHostCalls: null,
         hostCallTimeoutMs: null,
         watchdogMs: null,
-        resumableWrites: null,
         maxWrites: null,
-        pausedRunTtlSeconds: null,
         approval: null,
     },
     admission: {
@@ -140,13 +138,21 @@ function unknownOptionPaths(value, path, schema) {
     }
     return unknown;
 }
+/** Pause-only options #672 removed with `resume_execution`. */
+const RETIRED_PAUSE_OPTIONS = [
+    "ConnectaConfig.execute.resumableWrites",
+    "ConnectaConfig.execute.pausedRunTtlSeconds",
+];
 function rejectUnknownOptions(paths) {
     if (paths.length === 0)
         return;
     throw new Error(`Unknown Connecta configuration option${paths.length === 1 ? "" : "s"}:\n` +
         paths.map((path) => `- ${path}`).join("\n") +
         (paths.includes("ConnectaConfig.credentials") ? "\nUse vault: encryptedCredentialVault(storage, key) from @zackbart/connecta/credentials." : "") +
-        (paths.includes("ConnectaConfig.branding") ? "\nMove branding into ui: operatorUi({ branding }) from @zackbart/connecta/ui." : ""));
+        (paths.includes("ConnectaConfig.branding") ? "\nMove branding into ui: operatorUi({ branding }) from @zackbart/connecta/ui." : "") +
+        (paths.some((path) => RETIRED_PAUSE_OPTIONS.includes(path))
+            ? "\nPrograms no longer pause at writes, so there is nothing to configure: execute_code runs read-only and config-exempt tools, and every other write goes through call_destructive_tool (issue #672). Delete the option."
+            : ""));
 }
 /** Reject JavaScript typos and removed options before construction does work. */
 function assertKnownConfig(config) {
@@ -333,41 +339,6 @@ function positiveWhole(value, fallback) {
         ? Math.trunc(value)
         : fallback;
 }
-/**
- * Resumable writes' deployment settings, or undefined when they are off.
- * Omitted, they are on exactly when the storage can claim atomically, and a
- * deployment left without them hears so once. Asked for over storage that
- * cannot claim, they throw: at-most-once delivery of an approved write rests
- * on exactly one resume winning the claim, and a read-then-write stand-in
- * would let two win.
- */
-function resolveResumableWrites(execute, storage, logger) {
-    const enabled = execute?.resumableWrites;
-    if (enabled !== undefined && typeof enabled !== "boolean") {
-        throw new Error("ConnectaConfig.execute.resumableWrites must be a boolean");
-    }
-    if (enabled === false)
-        return undefined;
-    if (enabled === undefined && typeof storage.compareAndSet !== "function") {
-        logger.warn("[connecta] resumable writes are off: the configured storage has no " +
-            "compareAndSet, so programs refuse writes (E4) and resume_execution " +
-            "answers resumable_writes_unavailable. Use storage with an atomic " +
-            "compareAndSet (the Worker example's D1 store, fileStorage, " +
-            "memoryStorage) to let programs pause for approval, or set " +
-            "execute.resumableWrites: false to keep this and silence the warning.");
-        return undefined;
-    }
-    if (typeof storage.compareAndSet !== "function") {
-        throw new Error("ConnectaConfig.execute.resumableWrites needs storage with compareAndSet: " +
-            "two resumes of one paused run must send its writes at most once, which " +
-            "takes an atomic claim. memoryStorage() and fileStorage() provide it, as " +
-            "does the Worker example's D1 store; Cloudflare KV cannot.");
-    }
-    return {
-        maxWrites: positiveWhole(execute?.maxWrites, DEFAULT_MAX_WRITES),
-        ttlSeconds: positiveWhole(execute?.pausedRunTtlSeconds, DEFAULT_PAUSED_RUN_TTL_SECONDS),
-    };
-}
 /**
  * One-time construction warnings for deployment shapes that run fine but are
  * usually unintended. Warning-only — never throws and never changes behavior;
@@ -539,9 +510,7 @@ export function createConnecta(config) {
     });
     const inboundAuth = configuredAuth;
     const pools = resolvePools(config.pools, registry);
-    const resumable = resolveResumableWrites(config.execute, storage, logger);
     const approval = resolveApprovalPolicy(config.execute?.approval, registry);
-    // Exempt writes need a budget whether or not programs can pause.
     const maxWrites = positiveWhole(config.execute?.maxWrites, DEFAULT_MAX_WRITES);
     warnInsecureConfig(config, inboundAuth, logger);
     const requestAdmission = admissionController(config.admission?.requests, REQUEST_ADMISSION_DEFAULTS, config.admission?.requests?.maxDurationMs ?? DEFAULT_REQUEST_MAX_DURATION_MS);
@@ -580,10 +549,9 @@ export function createConnecta(config) {
                 tools: new Map(),
             },
         };
-        const refreshRunner = createProgramRunner(registry.scoped({ connectorIds: [] }), config.publicUrl, executor, logger, undefined, refreshConfig);
         config.artifacts.bindRefresh({
             ...(config.ui?.branding ? { branding: config.ui.branding } : {}),
-            claimMs: refreshRunner.claimMs,
+            claimMs: runClaimMs(refreshConfig),
             execute: async (program, owner, signal) => {
                 if (!owner)
                     throw new Error("Refresh owner is missing; reconfigure this program.");
@@ -612,8 +580,8 @@ export function createConnecta(config) {
                 const view = registry.scoped({ connectorIds: access.connectorIds,
                     ...(access.toolAccess ? { toolAccess: access.toolAccess } : {}),
                     ...(access.guardedToolAccess ? { guardedToolAccess: access.guardedToolAccess } : {}) });
-                const runner = createProgramRunner(view, config.publicUrl, executor, logger, undefined, refreshConfig);
-                return runner.execute({ code: program }, { signal });
+                const execute = createExecuteTool(view, config.publicUrl, executor, logger, undefined, refreshConfig);
+                return execute({ code: program }, { signal });
             },
         });
     }
@@ -660,7 +628,6 @@ export function createConnecta(config) {
         maxHostCalls: config.execute?.maxHostCalls,
         hostCallTimeoutMs: config.execute?.hostCallTimeoutMs,
         watchdogMs: config.execute?.watchdogMs,
-        resumable,
         approval,
         maxWrites,
         credentialVault,

package/dist/invocation.js

@@ -152,8 +152,8 @@ export class InvocationService {
             let attempts = 0;
             let dispatchedToConnector = false;
             let answered = false;
-            // How a write gate's refusal is recorded; see WriteGateDecision.
-            let gateActivity;
+            // A write gate's refusal that is no attempt; see WriteGateDecision.
+            let unrecorded = false;
             let resolved;
             let activityTarget;
             // The address as written, used for activity when resolution never reached
@@ -257,15 +257,10 @@ export class InvocationService {
                     ...(dispatchedToConnector ? { answered } : {}),
                     error: details,
                 });
-                // A pause is not a failure: it leaves one payload-free `paused` event
-                // naming the call that waits, and nothing in the operator's log. A call
-                // refused only because its run had already stopped leaves neither.
-                if (gateActivity === "none")
+                // A write refused only because its program had already returned
+                // leaves no event and nothing in the operator's log.
+                if (unrecorded)
                     return outcome();
-                if (gateActivity === "paused") {
-                    record("paused");
-                    return outcome();
-                }
                 // Activity rows stay payload-free by construction; the operator's log is
                 // where the downstream reason goes, bounded and without arguments.
                 if (target && details.code !== "destructive_tool_requires_approval") {
@@ -347,18 +342,10 @@ export class InvocationService {
                 if (gate) {
                     const decision = yield* gate(target, args ?? {});
                     if (decision.kind === "refuse") {
-                        gateActivity = decision.activity;
+                        unrecorded = decision.unrecorded === true;
                         return decision.error;
                     }
                 }
-                try {
-                    context.beforeDispatch?.();
-                }
-                catch (error) {
-                    return error instanceof InvocationFailure
-                        ? error.details
-                        : classifyCallError(error);
-                }
                 if (callSignal?.aborted)
                     return yield* Effect.fail(callSignal.reason);
                 attempts = 1;

package/dist/meta-tools.js

@@ -871,8 +871,7 @@ const GET_RESULT_INPUT = advertisedSchema(z.object({
 }));
 /**
  * Register the six explicit meta-tools onto an McpServer instance.
- * `registerExecuteTool` adds the seventh, `execute_code`, and
- * `registerResumeTool` the eighth, `resume_execution`. Broad discovery and
+ * `registerExecuteTool` adds the seventh, `execute_code`. Broad discovery and
  * multi-call work uses discovery and ordinary JavaScript promises inside a
  * program, which `execute_code` builds over the same
  * `CatalogService` and `InvocationService` these handlers use — one shared

package/dist/oauth-partition.js

@@ -19,6 +19,23 @@ export function retainOAuthPartition(partition) {
             activeWork.set(partition, remaining);
     };
 }
+/**
+ * Wrap one connector operation so its owner partition stays pinned from the
+ * first asynchronous storage read to the end, not only once a refresh flight
+ * exists: an idle personal registry can otherwise be evicted mid-flow. Status
+ * and auth operations take no call admission, so nothing else holds it.
+ */
+export function retainingOAuthPartition(operation, contextIndex) {
+    return async (...args) => {
+        const release = retainOAuthPartition(oauthPartitionFor(args[contextIndex]));
+        try {
+            return await operation(...args);
+        }
+        finally {
+            release();
+        }
+    };
+}
 export function oauthPartitionIdle(partition) {
     return !activeWork.has(partition);
 }