@zackbart/connecta 0.25.0 → 0.26.0

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;
+}