@zackbart/connecta 0.25.0 → 0.26.1

package/dist/invocation.js

@@ -64,17 +64,33 @@ function isCallerCancellation(error, signal) {
     return (signal?.aborted === true ||
         (isCallAdmissionError(error) && error.admissionKind === "cancelled"));
 }
+/**
+ * A downstream MCP tool answered with `isError`. Classified exactly as the
+ * plain `Error` it used to be — same message, same heuristics — and marked so
+ * a write's outcome can tell "the service said no" from "nobody answered".
+ */
+class DownstreamToolError extends Error {
+}
 function assertRawMcpSuccess(kind, result) {
     if (kind !== "mcp" || result == null || typeof result !== "object")
         return;
     const mcpResult = result;
     if (!mcpResult.isError)
         return;
-    throw new Error(boundedEchoText(mcpResult.content
+    throw new DownstreamToolError(boundedEchoText(mcpResult.content
         ?.filter((block) => block.type === "text")
         .map((block) => block.text ?? "")
         .join("") || "Downstream tool call failed"));
 }
+/**
+ * Whether a failed attempt is the downstream tool's own answer: an MCP
+ * `isError`. A connector's typed error is not, by itself, one — a response
+ * too large to read or a refused redirect comes after the request was acted
+ * on — so its code decides instead (`classifyWriteOutcome`).
+ */
+function answeredFailure(error) {
+    return error instanceof DownstreamToolError;
+}
 export class InvocationFailure extends Error {
     details;
     code;
@@ -134,6 +150,10 @@ export class InvocationService {
             let connectorMs = 0;
             let resultProcessingMs = 0;
             let attempts = 0;
+            let dispatchedToConnector = false;
+            let answered = false;
+            // How a write gate's refusal is recorded; see WriteGateDecision.
+            let gateActivity;
             let resolved;
             let activityTarget;
             // The address as written, used for activity when resolution never reached
@@ -227,6 +247,25 @@ export class InvocationService {
                 const diagnostics = timing();
                 const target = resolved ?? activityTarget;
                 const details = enrich(error, target);
+                const outcome = () => ({
+                    ok: false,
+                    durationMs: Date.now() - started,
+                    attempts,
+                    timing: diagnostics,
+                    ...defined({ resolved }),
+                    dispatched: dispatchedToConnector,
+                    ...(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")
+                    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") {
@@ -249,14 +288,7 @@ export class InvocationService {
                     : details.code === "cancelled"
                         ? "cancelled"
                         : "error", { errorCode: details.code });
-                return {
-                    ok: false,
-                    durationMs: Date.now() - started,
-                    attempts,
-                    timing: diagnostics,
-                    ...defined({ resolved }),
-                    error: details,
-                };
+                return outcome();
             };
             if (context.requestSignal?.aborted) {
                 // Preserve the cancelled admission-attempt count without starting discovery.
@@ -290,7 +322,11 @@ export class InvocationService {
                 const target = resolution.resolved;
                 resolved = target;
                 activityTarget = target;
-                if (!isExplicitlyReadOnly(target.definition) && !context.allowDestructive) {
+                const consequential = !isExplicitlyReadOnly(target.definition) && !context.allowDestructive;
+                const gate = consequential && (context.gates?.(target) ?? true)
+                    ? context.writeGate
+                    : undefined;
+                if (consequential && !gate) {
                     const canonicalAddress = `${target.connector.id}.${target.toolName}`;
                     return framingError("destructive_tool_requires_approval", `Tool "${canonicalAddress}" is not explicitly read-only. Invoke it through call_destructive_tool so the MCP host can request explicit approval.`);
                 }
@@ -308,6 +344,13 @@ export class InvocationService {
                     if (invalid)
                         return classifyCallError(invalid);
                 }
+                if (gate) {
+                    const decision = yield* gate(target, args ?? {});
+                    if (decision.kind === "refuse") {
+                        gateActivity = decision.activity;
+                        return decision.error;
+                    }
+                }
                 try {
                     context.beforeDispatch?.();
                 }
@@ -329,6 +372,7 @@ export class InvocationService {
                     // Cancellation can arrive during admission or context construction.
                     if (callSignal?.aborted)
                         throw callSignal.reason;
+                    dispatchedToConnector = true;
                     return target.connector.callTool(target.toolName, args ?? {}, connectorContext);
                 };
                 // The permit belongs to this scope, so success, failure, and the
@@ -351,6 +395,7 @@ export class InvocationService {
                     if (callSignal?.aborted)
                         return yield* Effect.fail(callSignal.reason);
                     const attemptError = Cause.squash(attempt.cause);
+                    answered = answeredFailure(attemptError);
                     return isCallerCancellation(attemptError, context.requestSignal)
                         ? callerCancelledDetails()
                         : classifyCallError(attemptError);
@@ -415,6 +460,7 @@ export class InvocationService {
                     durationMs: Date.now() - started,
                     attempts,
                     timing: diagnostics,
+                    dispatched: dispatchedToConnector,
                 };
             }
             catch {

package/dist/meta-tools.js

@@ -400,6 +400,7 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
         concurrency: discoveryConcurrency,
         defer: opts.defer,
         requestSignal: opts.requestSignal,
+        approval: opts.approval,
         // searchRoute keeps its top-level default. In-program callers use a
         // separate CatalogService configured for connecta.search.
     });
@@ -470,6 +471,8 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                 // Sanitized `unavailable` diagnostics ride the structured shape too;
                 // the plain-text path would drop them (#539).
                 outcome.error.details !== undefined ||
+                // So does a conflict's `current`: where things stand is the retry.
+                outcome.error.current !== undefined ||
                 [
                     "auth_required",
                     "invalid_args",
@@ -780,7 +783,7 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
         },
     };
 }
-const SEARCH_DESC = `Use top-level search for catalog inspection or approval-required work before call_destructive_tool. Unknown-address read-only work belongs in one execute_code program that searches, calls, and returns the answer. Use 2–4 action/object terms and includeSchemas="compact"; the default limit is ${DEFAULT_SEARCH_LIMIT}. Set connector when known. safety="readOnly" finds direct or program calls; "approvalRequired" finds the fail-closed complement. These filters grant no authority. Empty query browses.`;
+const SEARCH_DESC = `Use top-level search for catalog inspection or approval-required work before call_destructive_tool. Unknown-address read-only work belongs in one execute_code program that searches, calls, and returns the answer. Use 2–4 action/object terms and includeSchemas="compact"; the default limit is ${DEFAULT_SEARCH_LIMIT}. Set connector when known. safety="readOnly" finds tools that run unasked; "approvalRequired" finds the fail-closed complement. These filters grant no authority. Empty query browses.`;
 const CALL_DESC = 'Call one known-address tool explicitly annotated readOnlyHint: true. Use execute_code for unknown-address, multiple, dependent, or reduced read-only work. Unannotated or write-capable tools fail closed to call_destructive_tool. A truncated result carries a get_result action.';
 const CALL_DESTRUCTIVE_DESC = "Call any tool not explicitly annotated readOnlyHint: true. Include a short reason for the human reviewer after checking the schema and consequences. The reason grants no authority and is not sent downstream.";
 const GET_RESULT_DESC = "Page a truncated direct-call result by id and byte offset. A program result is never paged; reduce it inside execute_code. Returns a one-line JSON header (offset, bytes, totalBytes, hasMore, nextAction) and then the page as raw text. maxBytes is an upper bound, clamped to the result's inline cap.";
@@ -868,7 +871,8 @@ const GET_RESULT_INPUT = advertisedSchema(z.object({
 }));
 /**
  * Register the six explicit meta-tools onto an McpServer instance.
- * `registerExecuteTool` adds the seventh, `execute_code`. Broad discovery and
+ * `registerExecuteTool` adds the seventh, `execute_code`, and
+ * `registerResumeTool` the eighth, `resume_execution`. 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
@@ -884,6 +888,7 @@ export function registerMetaTools(server, registry, ctx) {
         credentialHandoffUrl: ctx.credentialHandoffUrl,
         requestSignal: ctx.requestSignal,
         defer: ctx.defer,
+        approval: ctx.approval,
     });
     server.registerTool("skills", {
         description: describedFor(registry, SKILLS_DESC, "skills"),

package/dist/module-contracts.d.ts

@@ -1,6 +1,7 @@
-import type { ConnectaBranding } from "./types.js";
+import type { ConnectaBranding, Connector } from "./types.js";
 import type { ActivityStore, ActivityReadGate, recordToolActivity, recordCatalogDriftActivity } from "./activity.js";
 import type { RouteContext } from "./routes/shared.js";
+import type { ArtifactRefreshRuntime } from "./artifacts/refresh.js";
 /** Construction-time UI contract. Core never imports the implementation. */
 export interface OperatorSurface {
     readonly branding?: ConnectaBranding;
@@ -17,3 +18,22 @@ export interface ActivityModule {
     readonly recordTool: typeof recordToolActivity;
     readonly recordDrift: typeof recordCatalogDriftActivity;
 }
+/**
+ * The artifacts module, created by `artifacts()` from /artifacts. Core appends
+ * its one prebuilt connector to the configured set — the same catalog,
+ * invocation, admission, and activity paths as any other — and imports none
+ * of its implementation.
+ */
+export interface ArtifactsModule {
+    /** The built-in `artifacts` connector. */
+    readonly connector: Connector;
+    /**
+     * Serve the pages' JSON API (`/artifacts/_api/*`) and the sandboxed frame
+     * (`/artifacts/_frame`); null for any other path. The operator UI delegates
+     * here and serves the page shells itself, so without `ui` there are no
+     * artifact routes at all.
+     */
+    handle(context: RouteContext): Promise<Response | null>;
+    /** Bind the optional refresh runner after core has built its registry and executor. */
+    bindRefresh?(runtime: ArtifactRefreshRuntime): void;
+}

package/dist/oauth-callback-outcome.js

@@ -1,9 +1,17 @@
 import { renderFixPrompt } from "./fix-prompt.js";
 const OUTCOMES = {
-    connected: { status: 200, message: "Connected. You can close this window." },
+    connected: {
+        status: 200,
+        tone: "ok",
+        heading: "{name} is connected",
+        message: "You can close this window.",
+        namesConnector: true,
+    },
     denied: {
         status: 400,
-        message: "Authorization was declined at the provider. Nothing was stored; start authorization again when you are ready.",
+        tone: "declined",
+        heading: "Authorization was declined",
+        message: "Consent was declined at the provider, so nothing was stored. Start authorization again whenever you are ready.",
         fix: {
             problem: "Consent for a downstream OAuth connector was declined at the provider, so no grant was stored.",
             steps: [
@@ -15,7 +23,9 @@ const OUTCOMES = {
     },
     provider_error: {
         status: 400,
-        message: "The provider returned an error instead of an authorization code. Nothing was stored.",
+        tone: "problem",
+        heading: "The provider returned an error",
+        message: "It sent back an error instead of an authorization code, so nothing was stored.",
         fix: {
             problem: "A provider redirected back to the OAuth callback with an OAuth error instead of an authorization code.",
             steps: [
@@ -27,7 +37,9 @@ const OUTCOMES = {
     },
     invalid_callback: {
         status: 400,
-        message: "Authorization could not be completed. The link may be expired, already used, or replaced by a newer attempt. Re-run authorization from connecta and try again.",
+        tone: "problem",
+        heading: "Authorization could not be completed",
+        message: "The link may be expired, already used, or replaced by a newer attempt. Start authorization again from {product}.",
         fix: {
             problem: "An OAuth callback arrived that the deployment could not match to an authorization flow it started: stale, already used, replaced by a newer attempt, or finished in a different session.",
             steps: [
@@ -39,7 +51,9 @@ const OUTCOMES = {
     },
     handoff_failed: {
         status: 500,
-        message: "Authorization could not be completed. Nothing was exchanged; try again shortly.",
+        tone: "problem",
+        heading: "{name} could not be connected",
+        message: "Authorization could not be completed, and nothing was exchanged. Try again shortly.",
         namesConnector: true,
         fix: {
             problem: "The deployment could not consume the stored principal handoff for a personal-auth OAuth flow, so no authorization code was exchanged.",
@@ -51,7 +65,9 @@ const OUTCOMES = {
     },
     exchange_failed: {
         status: 500,
-        message: "Authorization failed: the provider did not accept the authorization code exchange. Nothing was stored.",
+        tone: "problem",
+        heading: "{name} could not be connected",
+        message: "The provider did not accept the authorization code exchange. Nothing was stored.",
         namesConnector: true,
         fix: {
             problem: "A provider returned an authorization code, but exchanging it for tokens failed.",
@@ -63,7 +79,6 @@ const OUTCOMES = {
         },
     },
 };
-const CONNECTOR_ID_RE = /^[a-z0-9_-]+$/;
 /**
  * RFC 6749 names `access_denied` for a declined consent (section 4.1.2.1). Every other
  * value, standard or invented, is the provider refusing the request itself —
@@ -73,22 +88,32 @@ const CONNECTOR_ID_RE = /^[a-z0-9_-]+$/;
 export function providerErrorReason(error) {
     return error === "access_denied" ? "denied" : "provider_error";
 }
-/** Page copy and fix prompt for one reason. Nothing here reads the request. */
-export function oauthCallbackOutcome(reason, connectorId) {
+/**
+ * Page copy and fix prompt for one reason. Nothing here reads the request.
+ *
+ * `connector` is read only for a reason that sets `namesConnector`. The route
+ * passes one only once the state check has proved the flow, and this gate
+ * keeps a caller that passed one earlier from naming it anyway. `productName`
+ * is deployment configuration, the same for every connector, so it cannot
+ * tell one refusal from another.
+ */
+export function oauthCallbackOutcome(reason, connector, productName = "Connecta") {
     const outcome = OUTCOMES[reason];
-    // Success is reached only after the state check proved the id configured,
-    // so it is the one page that may name the connector in its copy.
-    const message = reason === "connected" && connectorId && CONNECTOR_ID_RE.test(connectorId)
-        ? `Connected "${connectorId}". You can close this window.`
-        : outcome.message;
+    const named = outcome.namesConnector ? connector : undefined;
+    const name = named ? displayName(named) : "The connection";
     return {
         reason,
         status: outcome.status,
-        message,
+        tone: outcome.tone,
+        heading: outcome.heading.replace("{name}", () => name),
+        message: outcome.message.replace("{product}", () => productName),
         ...(outcome.fix
-            ? {
-                fixPrompt: renderFixPrompt(outcome.fix, outcome.namesConnector ? connectorId : undefined),
-            }
+            ? { fixPrompt: renderFixPrompt(outcome.fix, named?.id) }
             : {}),
     };
 }
+/** A connector's title when it has a usable one, otherwise its id. */
+function displayName(connector) {
+    const title = typeof connector.title === "string" ? connector.title.trim() : "";
+    return title || connector.id;
+}