@zackbart/connecta 0.25.0 → 0.26.0

package/dist/executor-admission.d.ts

@@ -23,6 +23,8 @@ export declare class ExecutorExecutionError extends ExecutorAdmissionError {
 export interface AdmissionLease {
     /** Time spent waiting behind active work. Zero for immediate admission. */
     readonly waitMs: number;
+    /** Time left in the optional total admitted-request lifetime. */
+    remainingMs(): number | undefined;
     release(): void;
 }
 export interface AdmissionControllerOptions {
@@ -31,6 +33,8 @@ export interface AdmissionControllerOptions {
     queueTimeoutMs: number;
     /** Suggested delay exposed with retryable overload failures. */
     retryAfterMs?: number;
+    /** Hard admitted-request lifetime; omitted for executor admission. */
+    maxDurationMs?: number;
 }
 /**
  * Runtime-portable bounded admission. It deliberately owns no executor or
@@ -42,7 +46,9 @@ export declare class AdmissionController {
     readonly maxQueueSize: number;
     readonly queueTimeoutMs: number;
     readonly retryAfterMs: number;
+    readonly maxDurationMs: number | undefined;
     private active;
+    private readonly leases;
     private closed;
     private readonly waiters;
     private admittedTotal;
@@ -63,7 +69,11 @@ export declare class AdmissionController {
     close(): void;
     private overloaded;
     private makeLease;
-    private release;
+    private releaseSlot;
+    private fillSlots;
+    private pruneExpiredWaiters;
+    private reapExpired;
+    private nextReapDelay;
     private remove;
     private cleanup;
 }

package/dist/executor-admission.js

@@ -54,7 +54,9 @@ export class AdmissionController {
     maxQueueSize;
     queueTimeoutMs;
     retryAfterMs;
+    maxDurationMs;
     active = 0;
+    leases = new Map();
     closed = false;
     waiters = [];
     admittedTotal = 0;
@@ -70,6 +72,12 @@ export class AdmissionController {
         this.maxQueueSize = nonNegativeWhole(options.maxQueueSize, "maxQueueSize");
         this.queueTimeoutMs = positiveWhole(options.queueTimeoutMs, "queueTimeoutMs");
         this.retryAfterMs = nonNegativeWhole(options.retryAfterMs ?? this.queueTimeoutMs, "retryAfterMs");
+        this.maxDurationMs = options.maxDurationMs === undefined
+            ? undefined
+            : positiveWhole(options.maxDurationMs, "maxDurationMs");
+        if (this.maxDurationMs !== undefined && this.maxDurationMs > 2_147_483_647) {
+            throw new TypeError("maxDurationMs must be at most 2,147,483,647 milliseconds.");
+        }
     }
     get activeCount() {
         return this.active;
@@ -78,11 +86,13 @@ export class AdmissionController {
         return this.waiters.length;
     }
     snapshot() {
+        this.reapExpired();
         return {
             concurrency: this.concurrency,
             maxQueueSize: this.maxQueueSize,
             queueTimeoutMs: this.queueTimeoutMs,
             retryAfterMs: this.retryAfterMs,
+            ...(this.maxDurationMs !== undefined ? { maxDurationMs: this.maxDurationMs } : {}),
             active: this.active,
             queued: this.waiters.length,
             closed: this.closed,
@@ -118,32 +128,83 @@ export class AdmissionController {
         });
     }
     makeLease(waitMs) {
-        let released = false;
+        const id = Symbol("admission lease");
+        const record = this.maxDurationMs !== undefined
+            ? { expiresAt: Date.now() + this.maxDurationMs }
+            : {};
+        this.leases.set(id, record);
         return {
             waitMs,
+            remainingMs: () => !this.leases.has(id)
+                ? 0
+                : record.expiresAt === undefined
+                    ? undefined
+                    : Math.max(0, record.expiresAt - Date.now()),
             release: () => {
-                if (released)
+                if (!this.leases.delete(id))
                     return;
-                released = true;
-                this.release();
+                this.releaseSlot();
             },
         };
     }
-    release() {
+    releaseSlot() {
         if (this.active > 0)
             this.active--;
         if (this.closed)
             return;
-        const waiter = this.waiters.shift();
-        if (!waiter)
+        this.fillSlots();
+    }
+    fillSlots() {
+        this.pruneExpiredWaiters();
+        while (this.active < this.concurrency) {
+            const waiter = this.waiters.shift();
+            if (!waiter)
+                return;
+            const waitMs = Math.max(0, Date.now() - waiter.queuedAt);
+            this.admittedTotal++;
+            this.queueWaitCount++;
+            this.queueWaitTotalMs += waitMs;
+            this.queueWaitMaxMs = Math.max(this.queueWaitMaxMs, waitMs);
+            this.active++;
+            Deferred.doneUnsafe(waiter.outcome, Effect.succeed(this.makeLease(waitMs)));
+        }
+    }
+    pruneExpiredWaiters() {
+        const now = Date.now();
+        for (let index = this.waiters.length - 1; index >= 0; index--) {
+            const waiter = this.waiters[index];
+            if (now - waiter.queuedAt < this.queueTimeoutMs)
+                continue;
+            this.waiters.splice(index, 1);
+            this.rejectedTotal++;
+            Deferred.doneUnsafe(waiter.outcome, Effect.fail(this.overloaded(`Executor admission timed out after ${this.queueTimeoutMs}ms.`)));
+        }
+    }
+    reapExpired() {
+        this.pruneExpiredWaiters();
+        if (this.maxDurationMs === undefined)
             return;
-        const waitMs = Math.max(0, Date.now() - waiter.queuedAt);
-        this.admittedTotal++;
-        this.queueWaitCount++;
-        this.queueWaitTotalMs += waitMs;
-        this.queueWaitMaxMs = Math.max(this.queueWaitMaxMs, waitMs);
-        this.active++;
-        Deferred.doneUnsafe(waiter.outcome, Effect.succeed(this.makeLease(waitMs)));
+        const now = Date.now();
+        for (const [id, lease] of this.leases) {
+            if (lease.expiresAt !== undefined && lease.expiresAt <= now) {
+                this.leases.delete(id);
+                this.active--;
+            }
+        }
+        if (!this.closed)
+            this.fillSlots();
+    }
+    nextReapDelay() {
+        let next = Number.POSITIVE_INFINITY;
+        for (const lease of this.leases.values()) {
+            if (lease.expiresAt !== undefined)
+                next = Math.min(next, lease.expiresAt);
+        }
+        // A queued request's own timer reaps the earliest admitted lease. A
+        // fallback check covers a briefly empty lease map after a handoff.
+        return Number.isFinite(next)
+            ? Math.max(1, next - Date.now())
+            : 250;
     }
     remove(waiter) {
         const index = this.waiters.indexOf(waiter);
@@ -173,6 +234,7 @@ export class AdmissionController {
     // this bookkeeping while emitting nothing there.
     static {
         provideAdmissionProgram((controller, signal) => Effect.suspend(() => {
+            controller.reapExpired();
             if (controller.closed) {
                 controller.closedTotal++;
                 return Effect.fail(new ExecutorAdmissionError("executor_closed", "Executor is shutting down."));
@@ -210,6 +272,9 @@ export class AdmissionController {
                 Deferred.await(waiter.outcome),
                 Effect.sleep(Duration.millis(controller.queueTimeoutMs)).pipe(Effect.andThen(giveUp(() => controller.rejectedTotal++, () => controller.overloaded(`Executor admission timed out after ${controller.queueTimeoutMs}ms.`)))),
             ];
+            if (controller.maxDurationMs !== undefined) {
+                contenders.push(Effect.forever(Effect.suspend(() => Effect.sleep(Duration.millis(controller.nextReapDelay()))).pipe(Effect.andThen(Effect.sync(() => controller.reapExpired())))));
+            }
             if (signal) {
                 contenders.push(fromSignal(signal).pipe(Effect.catch(() => giveUp(() => controller.cancelledTotal++, () => new ExecutorAdmissionError("executor_cancelled", "Execution was cancelled while queued.")))));
             }

package/dist/executors/quickjs.js

@@ -355,8 +355,10 @@ class QuickJsChildPool {
         const subprocess = fork(childPath, [], {
             // The child needs only its entry path, exec arguments, and IPC channel.
             // Do not copy deployment credentials or Node startup configuration into
-            // the process that contains the guest runtime.
-            env: {},
+            // 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).
+            env: { TZ: "UTC" },
             execArgv: sourceMode ? ["--import", "tsx"] : [],
             stdio: ["ignore", "ignore", "pipe", "ipc"],
         });

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import type { CredentialVault } from "./credential-contract.js";
 import { Registry } from "./registry.js";
-import type { ActivityModule, OperatorSurface } from "./module-contracts.js";
-export type { ActivityModule, OperatorSurface } from "./module-contracts.js";
+import type { ConnectorGrant } from "./connector-access.js";
+import type { ActivityModule, ArtifactsModule, OperatorSurface } from "./module-contracts.js";
+export type { ActivityModule, ArtifactsModule, OperatorSurface, } from "./module-contracts.js";
 export type { CredentialVault, CredentialMetadata } from "./credential-contract.js";
 import type { AuthenticatedIdentity, Connector, Executor, IdentityReference, InboundAuth, KVStorage, Logger } from "./types.js";
 /** Tool-catalog caching, persistence, stale fallback, and probe deadlines. */
@@ -90,6 +91,46 @@ export interface ConnectaExecuteConfig {
      * fall back to the default.
      */
     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.
+     */
+    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
+     * 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.
+     */
+    approval?: Readonly<Record<string, "never" | "ask">>;
 }
 export interface AdmissionPoolConfig {
     /** Simultaneous work admitted to this pool. */
@@ -101,6 +142,10 @@ export interface AdmissionPoolConfig {
     /** Retry hint returned with overload failures, in milliseconds. */
     retryAfterMs?: number;
 }
+export interface RequestAdmissionConfig extends AdmissionPoolConfig {
+    /** Hard lifetime of an admitted /mcp request. Default 300,000 ms. */
+    maxDurationMs?: number;
+}
 /**
  * Runtime-portable server-memory boundaries. `/health` and operator routes do
  * not consume these permits, so they remain responsive during MCP saturation.
@@ -110,7 +155,7 @@ export interface ConnectaAdmissionConfig {
      * The `/mcp` request boundary. Defaults to 16 active, 32 queued, and a
      * 5-second maximum wait.
      */
-    requests?: AdmissionPoolConfig;
+    requests?: RequestAdmissionConfig;
     /**
      * Fallback pool for an `executor` that does not implement its own `acquire`.
      * Defaults to 2 active, 8 queued, and a 5-second maximum wait. Bounded
@@ -124,10 +169,13 @@ export interface ConnectaIdentityConfig {
     /**
      * What this admitted identity may discover and call: `"all"`, or a list
      * whose entries are connector ids (the whole connector) and `connector.tool`
-     * addresses (that tool only). Grants are additive. An address naming a tool
-     * the catalog lacks is unreachable and warned once, never widened.
+     * addresses (that tool only), or `{ tool: "connector.tool",
+     * requireReadOnly: true }` for an exact tool only while its loaded catalog
+     * explicitly classifies it read-only. Grants are additive: an unrestricted
+     * connector or address grant wins over the guarded form. An address naming
+     * a tool the catalog lacks is unreachable and warned once, never widened.
      */
-    connectorAccess?(identity: Readonly<AuthenticatedIdentity>): "all" | readonly string[] | Promise<"all" | readonly string[]>;
+    connectorAccess?(identity: Readonly<AuthenticatedIdentity>): "all" | readonly ConnectorGrant[] | Promise<"all" | readonly ConnectorGrant[]>;
     /** Global payload-free activity reads. Defaults to interactive humans. */
     activityAccess?(principal: Readonly<IdentityReference>): boolean | Promise<boolean>;
     /** Shared credential and OAuth administration. Defaults to none. */
@@ -176,6 +224,14 @@ export interface ConnectaConfig {
     vault?: CredentialVault;
     /** Optional connection UI, created by operatorUi() from /ui. */
     ui?: OperatorSurface;
+    /**
+     * Optional team pages over stored data, created by artifacts() from
+     * /artifacts. Adds the built-in `artifacts` connector; needs `publicUrl`,
+     * because the links it hands out are shared.
+     */
+    artifacts?: ArtifactsModule;
+    /** Optional dedicated HTTPS origin that serves only artifact pages and their library. */
+    artifactOrigin?: string;
     /** Tool-catalog caching, persistence, stale fallback, and probe deadlines. */
     discovery?: ConnectaDiscoveryConfig;
     /** Deployment-wide call deadlines and result paging threshold. */

package/dist/index.js

@@ -1,12 +1,15 @@
 import { credentialTestRule, describeCredentialTestMismatch, } from "./credential-rules.js";
 import { Registry } from "./registry.js";
-import { parseConnectorAccess, POOL_NAME_RE } from "./connector-access.js";
+import { intersectAccess, parseConnectorAccess, POOL_NAME_RE } from "./connector-access.js";
 import { createFetchHandler } from "./server.js";
+import { createProgramRunner } 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 { disposeEdgeRuntime } from "./runtime/run.js";
+import { NO_EXEMPTIONS } from "./tool-safety.js";
 import { createCoreRuntime, resolveLogger } from "./runtime/services.js";
 const REQUEST_ADMISSION_DEFAULTS = {
     concurrency: 16,
@@ -14,18 +17,20 @@ const REQUEST_ADMISSION_DEFAULTS = {
     queueTimeoutMs: 5_000,
     retryAfterMs: 1_000,
 };
+const DEFAULT_REQUEST_MAX_DURATION_MS = 300_000;
 const CODE_ADMISSION_DEFAULTS = {
     concurrency: 2,
     maxQueueSize: 8,
     queueTimeoutMs: 5_000,
     retryAfterMs: 1_000,
 };
-function admissionController(options, defaults) {
+function admissionController(options, defaults, maxDurationMs) {
     return new AdmissionController({
         concurrency: options?.concurrency ?? defaults.concurrency,
         maxQueueSize: options?.maxQueueSize ?? defaults.maxQueueSize,
         queueTimeoutMs: options?.queueTimeoutMs ?? defaults.queueTimeoutMs,
         retryAfterMs: options?.retryAfterMs ?? defaults.retryAfterMs,
+        ...(maxDurationMs !== undefined ? { maxDurationMs } : {}),
     });
 }
 /** Bearer providers are checked before Clerk (per spec). */
@@ -42,6 +47,10 @@ const admissionPoolSchema = {
     queueTimeoutMs: null,
     retryAfterMs: null,
 };
+const requestAdmissionSchema = {
+    ...admissionPoolSchema,
+    maxDurationMs: null,
+};
 const CONFIG_SCHEMA = {
     connectors: null,
     auth: null,
@@ -58,6 +67,8 @@ const CONFIG_SCHEMA = {
     activity: null,
     vault: null,
     ui: null,
+    artifacts: null,
+    artifactOrigin: null,
     discovery: {
         concurrency: null,
         catalogTtlSeconds: null,
@@ -79,9 +90,13 @@ const CONFIG_SCHEMA = {
         maxHostCalls: null,
         hostCallTimeoutMs: null,
         watchdogMs: null,
+        resumableWrites: null,
+        maxWrites: null,
+        pausedRunTtlSeconds: null,
+        approval: null,
     },
     admission: {
-        requests: admissionPoolSchema,
+        requests: requestAdmissionSchema,
         code: admissionPoolSchema,
     },
     logger: null,
@@ -157,6 +172,47 @@ function assertKnownConfig(config) {
             typeof activity.recordTool !== "function")) {
         throw new Error("ConnectaConfig.activity must be created with activityHistory(...)");
     }
+    const artifacts = config.artifacts;
+    if (artifacts !== undefined) {
+        const connector = artifacts?.connector;
+        if (typeof artifacts !== "object" ||
+            artifacts === null ||
+            !connector ||
+            connector.id !== "artifacts" ||
+            typeof connector.callTool !== "function" ||
+            typeof artifacts.handle !== "function") {
+            throw new Error("ConnectaConfig.artifacts must be created with artifacts(...) from @zackbart/connecta/artifacts");
+        }
+        if (config.connectors?.some((candidate) => candidate?.id === "artifacts")) {
+            throw new Error('Connector id "artifacts" is reserved by the artifacts module; rename ' +
+                "your connector or drop the artifacts option");
+        }
+        if (!config.publicUrl) {
+            throw new Error("ConnectaConfig.artifacts needs publicUrl: artifact links are shared " +
+                "with teammates, so they must name the deployment's own origin, never " +
+                "one taken from a request's Host header");
+        }
+    }
+    if (config.artifactOrigin !== undefined) {
+        if (!config.artifacts || !config.ui || !config.publicUrl) {
+            throw new Error("ConnectaConfig.artifactOrigin needs artifacts, ui, and publicUrl");
+        }
+        if (typeof config.artifactOrigin !== "string") {
+            throw new Error("ConnectaConfig.artifactOrigin must be an HTTPS origin");
+        }
+        let origin;
+        try {
+            origin = new URL(config.artifactOrigin);
+        }
+        catch {
+            throw new Error("ConnectaConfig.artifactOrigin must be an HTTPS origin");
+        }
+        if (origin.protocol !== "https:" ||
+            origin.toString() !== `${origin.origin}/` ||
+            origin.origin === new URL(config.publicUrl).origin) {
+            throw new Error("ConnectaConfig.artifactOrigin must be a distinct HTTPS origin");
+        }
+    }
 }
 /**
  * Validate declared pools against the connector set. Everything checkable at
@@ -219,6 +275,92 @@ function resolvePools(pools, registry) {
     }
     return resolved;
 }
+/**
+ * Validate `execute.approval` against the connector set, like the pools: a
+ * malformed key or value, an unknown connector, and an `api()` address its
+ * tools do not include all throw. Remote catalogs load lazily, so an address
+ * on one is kept and simply never matches a tool it does not serve.
+ */
+function resolveApprovalPolicy(approval, registry) {
+    for (const connector of registry.listConnectors()) {
+        if (connector.approval !== undefined && connector.approval !== "never") {
+            throw new Error(`Connector "${connector.id}": approval must be "never" or omitted`);
+        }
+    }
+    if (approval === undefined)
+        return NO_EXEMPTIONS;
+    if (!approval || typeof approval !== "object" || Array.isArray(approval)) {
+        throw new Error("ConnectaConfig.execute.approval must be an object keyed by connector ids and connector.tool addresses");
+    }
+    const connectors = new Map();
+    const tools = new Map();
+    for (const [key, value] of Object.entries(approval)) {
+        const where = `ConnectaConfig.execute.approval[${JSON.stringify(key)}]`;
+        if (value !== "never" && value !== "ask") {
+            throw new Error(`${where} must be "never" or "ask"`);
+        }
+        const dot = key.indexOf(".");
+        const id = dot === -1 ? key : key.slice(0, dot);
+        const tool = dot === -1 ? undefined : key.slice(dot + 1);
+        if (!id || tool === "") {
+            throw new Error(`${where}: keys are connector ids or connector.tool addresses`);
+        }
+        const connector = registry.getConnector(id);
+        if (!connector)
+            throw new Error(`${where}: unknown connector "${id}"`);
+        if (tool === undefined) {
+            connectors.set(id, value);
+            continue;
+        }
+        if (connector.staticTools &&
+            !connector.staticTools.some((candidate) => candidate.name === tool)) {
+            throw new Error(`${where}: connector "${id}" has no tool "${tool}"`);
+        }
+        tools.set(key, value);
+    }
+    return { connectors, tools };
+}
+/** A positive whole number, or the default when the value is unusable. */
+function positiveWhole(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 1
+        ? 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;
@@ -231,7 +373,7 @@ function warnInsecureConfig(config, inboundAuth, logger) {
     // Static API headers can carry secrets without declaring credential hooks.
     // Any configured connector warrants the open-deployment warning.
     if (inboundAuth.length === 0 &&
-        config.connectors.length > 0) {
+        (config.connectors.length > 0 || config.artifacts)) {
         logger.warn("[connecta] running with no inbound authentication: any caller can " +
             "invoke every shared connector. " +
             (hasCredentialConnector || oauthConnectors.length > 0
@@ -239,6 +381,18 @@ function warnInsecureConfig(config, inboundAuth, logger) {
                 : "") +
             "Configure `auth` (for example bearerToken(...) or Clerk) to gate access.");
     }
+    // Artifact pages mount inside the operator UI and open only for an
+    // authenticated viewer; either missing leaves the connector with no page.
+    if (config.artifacts && !config.ui) {
+        logger.warn("[connecta] artifacts is configured without ui: agents can publish and " +
+            "read artifacts, but there is no viewer, so their links answer 404. " +
+            "Add ui: operatorUi() to serve artifact pages.");
+    }
+    else if (config.artifacts && inboundAuth.length === 0) {
+        logger.warn("[connecta] artifacts is configured with no inbound authentication: " +
+            "artifact pages refuse every request, because there is no team to " +
+            "show them to. Configure `auth` to open them.");
+    }
     // Unset publicUrl with OAuth connectors: the downstream redirect_uri is
     // derived per-request from the attacker-influenced inbound Host header.
     if (oauthConnectors.length > 0 && !config.publicUrl) {
@@ -347,7 +501,12 @@ export function createConnecta(config) {
         name: config.serverInfo?.name ?? "connecta",
         version: config.serverInfo?.version ?? CONNECTA_VERSION,
     };
-    const registry = new Registry(config.connectors, {
+    // The artifacts module contributes one prebuilt connector, appended like any
+    // configured one: same catalog, invocation, admission, and activity.
+    const connectors = config.artifacts
+        ? [...config.connectors, config.artifacts.connector]
+        : config.connectors;
+    const registry = new Registry(connectors, {
         storage,
         logger,
         credentialVault,
@@ -370,8 +529,12 @@ 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);
+    const requestAdmission = admissionController(config.admission?.requests, REQUEST_ADMISSION_DEFAULTS, config.admission?.requests?.maxDurationMs ?? DEFAULT_REQUEST_MAX_DURATION_MS);
     const configuredCodeAdmission = admissionController(config.admission?.code, CODE_ADMISSION_DEFAULTS);
     let codeAdmission;
     let executor = config.executor;
@@ -387,6 +550,62 @@ export function createConnecta(config) {
             "implements acquire() and owns its admission pool; configure that " +
             "executor's concurrency and queue options instead.");
     }
+    if (config.artifacts?.bindRefresh) {
+        const sharedIds = registry.listConnectors()
+            .filter((connector) => connector.id !== "artifacts" && connector.authScope !== "personal")
+            .map((connector) => connector.id);
+        const refreshConfig = {
+            discoveryConcurrency: config.discovery?.concurrency,
+            probeTimeoutMs: config.discovery?.probeTimeoutMs,
+            maxEmittedBytes: config.execute?.maxEmittedBytes,
+            maxEmittedBlocks: config.execute?.maxEmittedBlocks,
+            maxHostCalls: config.execute?.maxHostCalls,
+            hostCallTimeoutMs: config.execute?.hostCallTimeoutMs,
+            watchdogMs: config.execute?.watchdogMs,
+            failOnInvocationFailure: true,
+            // A connector's own `approval: "never"` still applies when policy maps
+            // are empty. Override every shared connector explicitly for refresh.
+            approval: {
+                connectors: new Map(sharedIds.map((id) => [id, "ask"])),
+                tools: new Map(),
+            },
+        };
+        const refreshRunner = createProgramRunner(registry.scoped({ connectorIds: [] }), config.publicUrl, executor, logger, undefined, refreshConfig);
+        config.artifacts.bindRefresh({
+            claimMs: refreshRunner.claimMs,
+            execute: async (program, owner, signal) => {
+                if (!owner)
+                    throw new Error("Refresh owner is missing; reconfigure this program.");
+                let access = parseConnectorAccess(config.identity?.connectorAccess
+                    ? await config.identity.connectorAccess(owner.identity) : "all", { allowReadOnly: true });
+                if (owner.pool) {
+                    const pool = pools.get(owner.pool);
+                    if (!pool || await pool.grant(owner.identity) !== true) {
+                        throw new Error("Refresh owner's pool grant is no longer available.");
+                    }
+                    access = intersectAccess(access, pool.access);
+                }
+                if (access.connectorIds !== "all" && !access.connectorIds.includes("artifacts")) {
+                    throw new Error("Refresh owner no longer has artifact publishing access.");
+                }
+                if (access.toolAccess?.get("artifacts") &&
+                    !access.toolAccess.get("artifacts").has("set_refresh")) {
+                    throw new Error("Refresh owner no longer has refresh configuration access.");
+                }
+                if (access.guardedToolAccess?.get("artifacts")?.has("set_refresh")) {
+                    throw new Error("A read-only guarded grant cannot configure refresh.");
+                }
+                access = intersectAccess(access, { connectorIds: sharedIds });
+                if (signal.aborted)
+                    throw new Error("Refresh deadline expired before execution.");
+                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 });
+            },
+        });
+    }
     // Every structural check has passed, so this is the configuration the
     // deployment runs with. Creating the runtime builds nothing — a Worker may
     // construct its Connecta at global scope, where no fiber may start.
@@ -409,11 +628,13 @@ export function createConnecta(config) {
         identity: config.identity,
         pools,
         publicUrl: config.publicUrl,
+        artifactOrigin: config.artifactOrigin,
         allowedOrigins: config.allowedOrigins,
         serverInfo,
         logger,
         activity: config.activity?.store,
         activityModule: config.activity,
+        artifactsModule: config.artifacts,
         activityReadGate: config.activity?.readGate,
         activityDeploymentId: config.activity?.deploymentId,
         executor,
@@ -427,6 +648,9 @@ export function createConnecta(config) {
         maxHostCalls: config.execute?.maxHostCalls,
         hostCallTimeoutMs: config.execute?.hostCallTimeoutMs,
         watchdogMs: config.execute?.watchdogMs,
+        resumable,
+        approval,
+        maxWrites,
         credentialVault,
         ui: config.ui,
         deploymentInfo: config.deploymentInfo,