@zackbart/connecta 0.24.4 → 0.26.0

package/README.md

@@ -10,16 +10,19 @@ writing code instead of loading a thousand tool definitions.
 You ask your agent a question that touches a service — Linear, Stripe, an
 internal API, anything you have connected. Here is what happens:
 
-1. The agent talks to one endpoint, yours, and sees seven tools. Always seven,
+1. The agent talks to one endpoint, yours, and sees eight tools. Always eight,
    no matter how many services sit behind it.
 2. It writes a short JavaScript program. Connecta runs it in a sandbox next to
    your integrations. The program can search for tools, call them, chain the
    calls, and shape the result.
 3. Only the answer comes back into the agent's context — not raw pages of
    API output.
-4. If the agent wants to change something — create, update, delete — it
-   cannot do that from a program. It makes one explicit call, and your MCP
-   client can put that call in front of you first.
+4. If the program wants to change something — create, update, delete — it
+   stops right there, before anything is sent, and hands the agent the exact
+   write. The agent repeats it through `resume_execution`, which your MCP
+   client can put in front of you first. Approve it and the program picks up
+   where it stopped, without re-reading what it already read. A single write
+   can also go straight through `call_destructive_tool`.
 
 Credentials never leave the server. The program never sees them, and neither
 does the agent.
@@ -28,9 +31,9 @@ does the agent.
 flowchart TB
     Client["Your MCP client<br/>Claude, Cursor, …"]
 
-    subgraph Connecta["Connecta — one endpoint, seven tools, your credentials"]
-        Sandbox["execute_code<br/>the agent's program runs here<br/>read-only tools only"]
-        Explicit["call_destructive_tool<br/>one visible call per write<br/>your client can ask you first"]
+    subgraph Connecta["Connecta — one endpoint, eight tools, your credentials"]
+        Sandbox["execute_code<br/>the agent's program runs here<br/>reads run, writes pause"]
+        Explicit["resume_execution · call_destructive_tool<br/>the exact write, visible<br/>your client can ask you first"]
     end
 
     Integrations["The integrations you chose<br/>Linear · Stripe · Notion · Vercel · your HTTP API · any MCP server"]
@@ -38,6 +41,7 @@ flowchart TB
     Client -->|"one connection"| Sandbox
     Client --> Explicit
     Sandbox -->|"reads"| Integrations
+    Sandbox -.->|"paused write"| Explicit
     Explicit -->|"writes"| Integrations
 ```
 
@@ -73,22 +77,35 @@ Fifty issues in, one small object out. Your context window notices.
   retain field names and broad types in bounded runtime memory, never scalar
   values, so later programs can project a remote MCP result its provider never
   documented.
-- **Keep writes deliberate.** Only tools marked read-only run in a program.
-  Everything else is a separate, visible call your client can gate.
-- **Run it where you like.** Node, a Docker container, or a Cloudflare Worker,
-  from the same small deployment file.
+- **Keep large results usable.** Oversized direct calls return a bounded
+  preview with a handle for paging through the rest. For read-only work, the
+  notice also points the agent to reduce or search the result inside a
+  program. Discovery can show compact schemas, exact JSON Schema, or a
+  TypeScript signature to read while writing JavaScript.
+- **Keep writes deliberate.** Only tools marked read-only run in a program
+  unasked. Any other call pauses the program with the exact write, and it
+  runs only once `resume_execution` repeats it — a visible call your client
+  can gate. A paused run is a journal in storage, not a held program, so it
+  survives a restart; it expires, and a write whose outcome is unknown is
+  never sent twice. Config — and only config — can exempt a cheap,
+  reversible write from asking, per tool or per connector.
+- **Run it on Node or Cloudflare Workers.** The core is shared; each deployment
+  supplies its platform's executor and storage. The Node template also runs
+  unchanged in Docker.
 
 Deployments explicitly compose optional features: `operatorUi()` from
 `@zackbart/connecta/ui`, `encryptedCredentialVault()` from `/credentials`,
-`activityHistory()` from `/activity`, and inbound authentication adapters from
-`/auth/*`. Omit a module and its implementation does no runtime work. Core
+`activityHistory()` from `/activity`, `artifacts()` from `/artifacts`, and
+inbound authentication adapters from `/auth/*`. Omit a module and its implementation does no runtime work. Core
 keeps connector discovery, execution, invocation, and enforcement together.
 
 The optional UI shows each person's connections and effective permissions.
 Authentication controls live inside each connection, with optional activity
 history. The configured connection list loads before downstream checks finish;
 a slow provider does not hold up the page. Connector selection and access rules
-remain in deployment code.
+remain in deployment code. It also explains which tools can run in programs or
+need approval, offers a fixed repair prompt for classified failures, and shows
+client setup commands for the endpoints the signed-in person can use.
 
 One deployment may serve several authenticated people inside the same tenant.
 Cloudflare Access supplies Worker identity; Node can use Clerk or the optional
@@ -105,7 +122,7 @@ and why.
 
 Setup is written for an agent. Point yours at [`AGENTS.md`](./AGENTS.md) and
 ask it to set up a Connecta deployment; the
-[documentation](./documentation/) covers the architecture, the seven tools,
+[documentation](./documentation/) covers the architecture, the eight tools,
 code mode, and inbound auth if you want to go deeper. When upgrading an
 existing deployment, each [changelog](./CHANGELOG.md) release opens with what
 breaks and what a deployment can ignore.

package/SECURITY.md

@@ -16,8 +16,9 @@ CI blocks moderate, high, and critical production dependency advisories. Lower
 findings are reviewed for reachability and recorded when an upstream package has
 not yet released a compatible fix.
 
-The MCP TypeScript SDK 2.x packages are exact-pinned. The split client and
-server packages no longer install Hono or `@hono/node-server`, so the temporary
-root-project override used with SDK 1.x is gone. A dependency bump must pass
-both `npm run release:check` and the Node/Workers runtime suites before the pin
-moves.
+The MCP TypeScript SDK 2.x packages and Effect are exact-pinned. Effect is the
+runtime core, and its unstable modules can break in a minor release, so its pin
+moves in a dedicated upgrade. The split client and server packages no longer
+install Hono or `@hono/node-server`, so the temporary root-project override
+used with SDK 1.x is gone. A dependency bump must pass `npm run release:check`
+and the Node/Workers runtime suites before a pin moves.

package/bin/connecta.mjs

@@ -249,6 +249,7 @@ async function doctor() {
     "call_tool",
     "execute_code",
     "get_result",
+    "resume_execution",
     "search_tools",
     "skills",
   ];
@@ -301,7 +302,10 @@ async function doctor() {
   console.log(
     `Connecta doctor passed: ${health.connectors} connector(s), ` +
       `${executorName ? `${executorName} executed` : "code executed"}, ` +
-      "prescribed seven-tool surface" +
+      "prescribed eight-tool surface" +
+      // resume_execution is listed either way; whether programs can write is
+      // what an operator cannot tell from the tool list, so say when not.
+      (health.resumableWrites === false ? ", resumable writes off" : "") +
       (drifted.length > 0
         ? `, catalog drift on ${drifted.length} connector(s).`
         : "."),

package/dist/activity.d.ts

@@ -1,7 +1,9 @@
 import type { ActivityModule } from "./module-contracts.js";
 import type { CatalogDriftCounts, Logger } from "./types.js";
-export type ActivityCallSource = "call_tool" | "call_destructive_tool" | "batch_call" | "execute_code";
-export type ActivityOutcome = "success" | "error" | "timeout" | "cancelled";
+export type ActivityCallSource = "call_tool" | "call_destructive_tool" | "batch_call" | "execute_code" | "resume_execution";
+export type ActivityOutcome = "success" | "error" | "timeout" | "cancelled" | "paused" | "approved";
+/** How much one `resume_execution` approved: this call, or this tool for the run. */
+export type ActivityApproval = "call" | "tool";
 export type AgentFriction = "tool_not_found" | "schema_retry" | "destructive_reroute" | "auth_required" | "result_too_large";
 export { agentFrictionForCode } from "./activity-friction.js";
 /**
@@ -47,6 +49,11 @@ export interface ToolCallActivityEvent {
      * agent while remaining an `outcome: "success"` call with no error code.
      */
     friction?: AgentFriction;
+    /**
+     * Set only on an `approved` event: the scope the approval covered. An enum,
+     * like everything else here — the approved arguments are never recorded.
+     */
+    approval?: ActivityApproval;
     serverName: string;
     serverVersion: string;
     deploymentId?: string;
@@ -142,7 +149,7 @@ export interface ActivityRequestContext {
     defer?: (promise: Promise<unknown>) => void;
     logger: Logger;
 }
-export type ActivityEventInput = Pick<ToolCallActivityEvent, "connectorId" | "toolName" | "address" | "source" | "outcome" | "durationMs" | "attempts" | "errorCode" | "friction">;
+export type ActivityEventInput = Pick<ToolCallActivityEvent, "connectorId" | "toolName" | "address" | "source" | "outcome" | "durationMs" | "attempts" | "errorCode" | "friction" | "approval">;
 /**
  * Best-effort by design: activity storage can never change a tool result.
  * Workers attach async sinks to waitUntil; synchronous sinks such as Analytics

package/dist/activity.js

@@ -49,9 +49,18 @@ export function recordToolActivity(context, input) {
         source: input.source,
         outcome: input.outcome,
         durationMs: Math.max(0, Math.trunc(input.durationMs)),
-        attempts: Math.max(1, Math.trunc(input.attempts)),
+        // A pause and an approval reach nothing downstream, so they are the two
+        // events that honestly carry zero attempts. Every other outcome keeps its
+        // floor of one, as it always has.
+        attempts: input.outcome === "paused" || input.outcome === "approved"
+            ? 0
+            : Math.max(1, Math.trunc(input.attempts)),
         ...(input.errorCode ? { errorCode: input.errorCode } : {}),
         ...(friction ? { friction } : {}),
+        ...(input.outcome === "approved" &&
+            (input.approval === "call" || input.approval === "tool")
+            ? { approval: input.approval }
+            : {}),
         serverName: context.serverInfo.name,
         serverVersion: context.serverInfo.version,
         ...(context.deploymentId

package/dist/advertised-schema.js

@@ -0,0 +1,53 @@
+function deepFreeze(value) {
+    if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}
+/**
+ * A meta-tool input schema whose JSON Schema rendering is derived once per
+ * process, not once per request.
+ *
+ * Every `/mcp` request builds a fresh `McpServer` (stateless per request), and
+ * the SDK renders each registered tool's input schema through
+ * `~standard.jsonSchema` at registration and again for `tools/list`. Zod
+ * re-walks the whole schema on every one of those calls, which made the
+ * rendering most of a `tools/list` request's CPU. The schemas themselves are
+ * module constants — no deployment option, identity, or scoped view reaches
+ * them; what does vary (descriptions) is a string computed per registration
+ * and never passes through here — so the rendering is immutable data that can
+ * outlive a request without being request-bound.
+ *
+ * This is the SDK's own `StandardSchemaWithJSON` contract, not a patch of it:
+ * validation delegates to zod unchanged, so a tool call is checked exactly as
+ * before, and the JSON Schema is zod's own output for the same target,
+ * memoized and deep-frozen so no request can alter what the next one sees.
+ * Conversions with library options are passed through uncached; nothing in
+ * the SDK sends them.
+ */
+export function advertisedSchema(schema) {
+    const standard = schema["~standard"];
+    const rendered = new Map();
+    const convert = (io) => (options) => {
+        if (options.libraryOptions !== undefined) {
+            return standard.jsonSchema[io](options);
+        }
+        const key = `${io}:${options.target}`;
+        let json = rendered.get(key);
+        if (json === undefined) {
+            json = deepFreeze(standard.jsonSchema[io](options));
+            rendered.set(key, json);
+        }
+        return json;
+    };
+    return {
+        "~standard": {
+            version: 1,
+            vendor: standard.vendor,
+            validate: (value) => standard.validate(value),
+            jsonSchema: { input: convert("input"), output: convert("output") },
+        },
+    };
+}

package/dist/artifacts/connector.d.ts

@@ -0,0 +1,55 @@
+import type { Connector } from "../types.js";
+import { type ArtifactOperations } from "./operations.js";
+import { type ArtifactRefreshService } from "./refresh.js";
+import type { ArtifactAllowlist, ArtifactIssue, ArtifactKind, ArtifactLimits } from "./types.js";
+/** What a deployment's render check is handed: exactly what the viewer loads. */
+export interface ArtifactRenderCheckInput {
+    /** The complete frame document, data injected. */
+    document: string;
+    /** The Content-Security-Policy the viewer serves it under. */
+    csp: string;
+    kind: ArtifactKind;
+    /** Aborted when the check's 20-second deadline or the call's own passes. */
+    signal: AbortSignal;
+}
+export type ArtifactRenderCheckResult = {
+    ok: true;
+    warnings?: string[];
+} | {
+    ok: false;
+    errors: string[];
+};
+/**
+ * A real render check — a headless browser, say — run on `validate_artifact`
+ * and on every write that changes what a page renders. It must answer within
+ * 20 seconds; a throw or a timeout fails the write as retryable `unavailable`
+ * and saves nothing.
+ */
+export type ArtifactRenderCheck = (input: ArtifactRenderCheckInput) => Promise<ArtifactRenderCheckResult>;
+type RenderVerdict = {
+    ok: true;
+    warnings: ArtifactIssue[];
+} | {
+    ok: false;
+    errors: ArtifactIssue[];
+} | {
+    ok: false;
+    unavailable: string;
+};
+/** Run a hook under its 20-second deadline and the call's own signal. Never throws. */
+export declare function runRenderCheck(hook: ArtifactRenderCheck, input: {
+    document: string;
+    csp: string;
+    kind: ArtifactKind;
+}, callSignal: AbortSignal | undefined): Promise<RenderVerdict>;
+export interface ArtifactsConnectorOptions {
+    operations: ArtifactOperations;
+    refresh: ArtifactRefreshService;
+    allowlist: ArtifactAllowlist;
+    limits: ArtifactLimits;
+    renderCheck?: ArtifactRenderCheck;
+    /** Where pages are served, when not the deployment's own origin. */
+    origin?: string;
+}
+export declare function artifactsConnector(options: ArtifactsConnectorOptions): Connector;
+export {};