@zackbart/connecta 0.18.3 → 0.19.0

package/dist/invocation.js

@@ -4,7 +4,20 @@ import { classifyCallError, ConnectorCallError, echoedCallArgs, framingError, }
 import { unwrapMcpResult } from "./mcp-result.js";
 import { splitAddress } from "./registry.js";
 import { isExplicitlyReadOnly } from "./tool-safety.js";
+import { sleep, withDeadline } from "./timeout.js";
 import { validateToolInput } from "./validate.js";
+function defined(values) {
+    return Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined));
+}
+async function timed(bucket, fn) {
+    const started = Date.now();
+    try {
+        return await fn();
+    }
+    finally {
+        bucket(Date.now() - started);
+    }
+}
 /**
  * The longest the engine will park a synchronous inbound request in *waiting
  * alone*. The engine already treats ~15 s as the outer bound of one reasonable
@@ -109,18 +122,16 @@ export class InvocationService {
         this.activity = activity;
     }
     async invoke(address, args, context) {
-        return this.invokeWithResolution(address, args, context, () => this.catalog.resolveTool(address, context.requestSignal !== undefined
-            ? { signal: context.requestSignal }
-            : {}));
+        const options = defined({ signal: context.requestSignal });
+        return this.invokeWithResolution(address, args, context, () => this.catalog.resolveTool(address, options));
     }
     /**
      * Code-mode namespace dispatch preserves JavaScript-safe tool aliases while
      * still feeding the resolved catalog entry through the one invocation path.
      */
     async invokeToolAlias(connectorId, toolAlias, aliasFor, args, context) {
-        return this.invokeWithResolution(`${connectorId}.${toolAlias}`, args, context, () => this.catalog.resolveToolAlias(connectorId, toolAlias, aliasFor, context.requestSignal !== undefined
-            ? { signal: context.requestSignal }
-            : {}));
+        const options = defined({ signal: context.requestSignal });
+        return this.invokeWithResolution(`${connectorId}.${toolAlias}`, args, context, () => this.catalog.resolveToolAlias(connectorId, toolAlias, aliasFor, options));
     }
     async invokeWithResolution(address, args, context, resolve) {
         const started = Date.now();
@@ -161,37 +172,35 @@ export class InvocationService {
                 outcome,
                 durationMs: Date.now() - started,
                 attempts,
-                ...(classification.errorCode
-                    ? { errorCode: classification.errorCode }
-                    : {}),
-                ...(classification.friction
-                    ? { friction: classification.friction }
-                    : {}),
+                ...defined({
+                    errorCode: classification.errorCode,
+                    friction: classification.friction,
+                }),
             });
         };
-        const failed = (error) => {
-            const diagnostics = timing();
-            const target = resolved ?? activityTarget;
-            const echoed = error.code === "destructive_tool_requires_approval"
-                ? echoedCallArgs(args)
-                : {};
-            const details = error.code === "destructive_tool_requires_approval" && target
-                ? {
-                    ...error,
-                    nextAction: {
-                        tool: "call_destructive_tool",
-                        arguments: {
-                            address: `${target.connector.id}.${target.toolName}`,
-                            ...echoed,
+        const enrich = (error, target) => {
+            if (!target)
+                return error;
+            switch (error.code) {
+                case "destructive_tool_requires_approval": {
+                    const echoed = echoedCallArgs(args);
+                    return {
+                        ...error,
+                        nextAction: {
+                            tool: "call_destructive_tool",
+                            arguments: {
+                                address: `${target.connector.id}.${target.toolName}`,
+                                ...echoed,
+                            },
+                            purpose: "Ask the MCP host to approve this consequential call. " +
+                                ("args" in echoed
+                                    ? "Re-send these arguments and add a short reason for the human reviewer."
+                                    : "Re-send the arguments you just sent — they are too large to echo back — and add a short reason for the human reviewer."),
                         },
-                        purpose: "Ask the MCP host to approve this consequential call. " +
-                            ("args" in echoed
-                                ? "Re-send these arguments and add a short reason for the human reviewer."
-                                : "Re-send the arguments you just sent — they are too large to echo back — and add a short reason for the human reviewer."),
-                    },
+                    };
                 }
-                : error.code === "auth_required" && target
-                    ? {
+                case "auth_required":
+                    return {
                         ...error,
                         connector: target.connector.id,
                         operation: `${target.connector.id}.${target.toolName}`,
@@ -203,20 +212,28 @@ export class InvocationService {
                         },
                         retry: `Retry ${target.connector.id}.${target.toolName} after ` +
                             "the operator completes recovery.",
-                    }
-                    : error.code === "invalid_args" && error.validation && target
-                        ? {
-                            ...error,
+                    };
+                case "invalid_args":
+                    if (!error.validation)
+                        return error;
+                    return {
+                        ...error,
+                        connector: target.connector.id,
+                        operation: `${target.connector.id}.${target.toolName}`,
+                        nextAction: this.catalog.searchRecovery({
+                            query: target.toolName,
                             connector: target.connector.id,
-                            operation: `${target.connector.id}.${target.toolName}`,
-                            nextAction: this.catalog.searchRecovery({
-                                query: target.toolName,
-                                connector: target.connector.id,
-                            }, "Inspect the current input shape if the validation findings are not sufficient."),
-                            retry: `Correct the listed arguments and retry ` +
-                                `${target.connector.id}.${target.toolName}.`,
-                        }
-                        : error;
+                        }, "Inspect the current input shape if the validation findings are not sufficient."),
+                        retry: `Correct the listed arguments and retry ` +
+                            `${target.connector.id}.${target.toolName}.`,
+                    };
+                default:
+                    return error;
+            }
+        };
+        const failed = (error) => {
+            const diagnostics = timing();
+            const details = enrich(error, resolved ?? activityTarget);
             record(details.code === "timeout"
                 ? "timeout"
                 : details.code === "cancelled"
@@ -227,7 +244,7 @@ export class InvocationService {
                 durationMs: Date.now() - started,
                 attempts,
                 timing: diagnostics,
-                ...(resolved ? { resolved } : {}),
+                ...defined({ resolved }),
                 error: details,
             };
         };
@@ -240,21 +257,8 @@ export class InvocationService {
                     toolName: resolution.toolName,
                 };
             }
-            if (resolution.cause && resolution.connector) {
-                if (context.requestSignal?.aborted) {
-                    return failed(callerCancelledDetails());
-                }
-                // A connector whose catalog cannot be fetched is as unusable as one
-                // whose execution fails, so it feeds health accounting the same way the
-                // attempt catch below does — otherwise a connector every call fails
-                // against (a revoked downstream grant, say) still reads clean in the
-                // deployment's health log.
-                //
-                // Recorded HERE rather than inside the registry's catalog fetch because
-                // a cache hit that avoids a live listTools call records nothing — it is
-                // not evidence of health. Success stays what it has always been: an
-                // actual downstream call that returned.
-                this.registry.recordFailure(resolution.connector.id, Date.now() - started, resolution.cause);
+            if (resolution.cause && context.requestSignal?.aborted) {
+                return failed(callerCancelledDetails());
             }
             return failed(resolution.error);
         }
@@ -292,95 +296,49 @@ export class InvocationService {
         while (true) {
             attempts++;
             let permit;
-            const controller = context.timeoutMs || context.requestSignal
-                ? new AbortController()
-                : undefined;
-            const forwardAbort = () => controller?.abort(context.requestSignal?.reason);
-            if (context.requestSignal?.aborted)
-                forwardAbort();
-            else {
-                context.requestSignal?.addEventListener("abort", forwardAbort, {
-                    once: true,
-                });
-            }
-            let timer;
-            let onAbort;
             let attemptError;
             let attemptFailed = false;
             try {
-                const admissionStarted = Date.now();
-                try {
-                    permit = await this.registry.admitCall(resolved.connector.id, {
-                        toolName: resolved.toolName,
-                        args: args ?? {},
-                        ...(context.requestSignal !== undefined
-                            ? { signal: context.requestSignal }
-                            : {}),
+                permit = await timed((elapsed) => { admissionMs += elapsed; }, () => this.registry.admitCall(resolved.connector.id, {
+                    toolName: resolved.toolName,
+                    args: args ?? {},
+                    ...defined({ signal: context.requestSignal }),
+                }));
+                const raw = await timed((elapsed) => { connectorMs += elapsed; }, () => {
+                    const call = (callSignal) => {
+                        const connectorContext = this.registry.contextFor(resolved.connector.id, this.catalog.baseUrl, this.catalog.requestScope, defined({ signal: callSignal, timeoutMs: context.timeoutMs }));
+                        if (resolved.connector.credential &&
+                            !connectorContext.credential) {
+                            throw new ConnectorCallError("auth_required", "Operator-managed credential storage is not configured. Call " +
+                                `authorize_connector({ connector: "${resolved.connector.id}" }).`);
+                        }
+                        // Cancellation can arrive during admission or context construction.
+                        if (callSignal?.aborted)
+                            throw callSignal.reason;
+                        return resolved.connector.callTool(resolved.toolName, args ?? {}, connectorContext);
+                    };
+                    if (!context.timeoutMs && !context.requestSignal)
+                        return call();
+                    return withDeadline(call, {
+                        ...defined({
+                            timeoutMs: context.timeoutMs,
+                            signal: context.requestSignal,
+                        }),
+                        timeoutError: new ConnectorCallError("timeout", `Tool call timed out after ${context.timeoutMs}ms`),
                     });
-                }
-                finally {
-                    admissionMs += Date.now() - admissionStarted;
-                }
-                const connectorContext = this.registry.contextFor(resolved.connector.id, this.catalog.baseUrl, this.catalog.requestScope, {
-                    ...(controller?.signal !== undefined
-                        ? { signal: controller.signal }
-                        : {}),
-                    ...(context.timeoutMs !== undefined
-                        ? { timeoutMs: context.timeoutMs }
-                        : {}),
                 });
-                if (resolved.connector.credential && !connectorContext.credential) {
-                    throw new ConnectorCallError("auth_required", "Operator-managed credential storage is not configured. Call " +
-                        `authorize_connector({ connector: "${resolved.connector.id}" }).`);
-                }
-                let rejectCancelled;
-                const cancelled = controller
-                    ? new Promise((_, reject) => {
-                        rejectCancelled = reject;
-                    })
-                    : undefined;
-                onAbort = () => {
-                    rejectCancelled(controller?.signal.reason ??
-                        new ConnectorCallError("timeout", "Tool call was cancelled"));
-                };
-                controller?.signal.addEventListener("abort", onAbort, { once: true });
-                if (controller?.signal.aborted)
-                    onAbort();
-                if (controller?.signal.aborted)
-                    await cancelled;
-                if (context.timeoutMs) {
-                    timer = setTimeout(() => {
-                        controller?.abort(new ConnectorCallError("timeout", `Tool call timed out after ${context.timeoutMs}ms`));
-                    }, context.timeoutMs);
-                }
-                const connectorStarted = Date.now();
-                try {
-                    const pending = resolved.connector.callTool(resolved.toolName, args ?? {}, connectorContext);
-                    const raw = cancelled
-                        ? await Promise.race([pending, cancelled])
-                        : await pending;
-                    // isError is checked here for BOTH result shapes so every adapter
-                    // reports the same downstream-failure wording, and the throw lands
-                    // inside the attempt where it stays retry-eligible and feeds health.
-                    assertRawMcpSuccess(resolved.connector.kind, raw);
-                    observedResult = unwrapMcpResult(resolved.connector.kind, raw);
-                    result = context.unwrapResult ? observedResult : raw;
-                }
-                finally {
-                    connectorMs += Date.now() - connectorStarted;
-                }
+                // isError is checked here for BOTH result shapes so every adapter
+                // reports the same downstream-failure wording, and the throw lands
+                // inside the attempt where it stays retry-eligible and feeds health.
+                assertRawMcpSuccess(resolved.connector.kind, raw);
+                observedResult = unwrapMcpResult(resolved.connector.kind, raw);
+                result = context.unwrapResult ? observedResult : raw;
             }
             catch (error) {
                 attemptFailed = true;
                 attemptError = error;
             }
             finally {
-                if (timer)
-                    clearTimeout(timer);
-                if (onAbort) {
-                    controller?.signal.removeEventListener("abort", onAbort);
-                }
-                context.requestSignal?.removeEventListener("abort", forwardAbort);
                 permit?.release();
             }
             if (attemptFailed) {
@@ -394,59 +352,32 @@ export class InvocationService {
                     details.retryable) {
                     const wait = retryBackoffMs(attempts, details.retryAfterMs);
                     if (wait !== undefined) {
-                        const backoffStarted = Date.now();
-                        if (wait > 0) {
-                            const completed = await new Promise((resolve) => {
-                                let settled = false;
-                                const finish = (value) => {
-                                    if (settled)
-                                        return;
-                                    settled = true;
-                                    clearTimeout(timer);
-                                    context.requestSignal?.removeEventListener("abort", cancel);
-                                    resolve(value);
-                                };
-                                const timer = setTimeout(() => finish(true), wait);
-                                const cancel = () => finish(false);
-                                context.requestSignal?.addEventListener("abort", cancel, {
-                                    once: true,
-                                });
-                                if (context.requestSignal?.aborted)
-                                    cancel();
-                            });
-                            backoffMs += Date.now() - backoffStarted;
-                            if (!completed)
-                                return failed(callerCancelledDetails());
-                        }
-                        else {
-                            backoffMs += Date.now() - backoffStarted;
-                        }
+                        const completed = await timed((elapsed) => { backoffMs += elapsed; }, () => sleep(wait, context.requestSignal));
+                        if (!completed)
+                            return failed(callerCancelledDetails());
                         continue;
                     }
                     // The reported window is longer than the engine will park a
                     // synchronous request for. Fall through to failure with
                     // retryAfterMs reported verbatim so the agent can re-issue.
                 }
-                if (!callerCancelled && !isCallAdmissionError(attemptError)) {
-                    this.registry.recordFailure(resolved.connector.id, Date.now() - started, attemptError);
-                }
                 return failed(details);
             }
             break;
         }
-        this.registry.recordSuccess(resolved.connector.id, Date.now() - started);
-        const processingStarted = Date.now();
         try {
-            const value = context.processResult
-                ? await context.processResult(result, resolved)
-                : result;
-            try {
-                this.registry.observeOutputShape(resolved.connector.id, resolved.definition, observedResult);
-            }
-            catch {
-                // Shape learning is advisory. It cannot change a completed call.
-            }
-            resultProcessingMs += Date.now() - processingStarted;
+            const value = await timed((elapsed) => { resultProcessingMs += elapsed; }, async () => {
+                const processed = context.processResult
+                    ? await context.processResult(result, resolved)
+                    : result;
+                try {
+                    this.registry.observeOutputShape(resolved.connector.id, resolved.definition, observedResult);
+                }
+                catch {
+                    // Shape learning is advisory. It cannot change a completed call.
+                }
+                return processed;
+            });
             const diagnostics = timing();
             const friction = context.activityFriction?.(value);
             record("success", friction ? { friction } : {});
@@ -460,7 +391,6 @@ export class InvocationService {
             };
         }
         catch (error) {
-            resultProcessingMs += Date.now() - processingStarted;
             return failed(framingError("result_processing_failed", error instanceof Error ? error.message : String(error)));
         }
     }

package/dist/meta-tools.d.ts

@@ -15,7 +15,7 @@ export interface ToolResult {
     structuredContent?: Record<string, unknown>;
     [x: string]: unknown;
 }
-export declare function jsonResult(obj: unknown): ToolResult;
+export declare function jsonResult(obj: unknown, text?: string): ToolResult;
 export declare function errorResult(message: string): ToolResult;
 /**
  * Move a byte `offset` back to the nearest UTF-8 codepoint boundary in
@@ -30,21 +30,8 @@ export declare function errorResult(message: string): ToolResult;
  * character there to split.
  */
 export declare function alignStartToCharBoundary(bytes: Uint8Array, offset: number): number;
-/**
- * Move a byte `end` back to the nearest UTF-8 codepoint boundary in
- * `(offset, total]`, so decoding `bytes[offset, end)` never splits a codepoint
- * (which would emit U+FFFD and break byte-exact reassembly). If backing up
- * would make no progress — a single codepoint wider than the window — extend
- * forward to the end of that codepoint instead so paging always advances.
- * Assumes `offset` is itself a codepoint boundary (offsets are the prior
- * `nextOffset`, which this function guarantees, and 0 is always a boundary).
- *
- * The return is always `> offset` while `offset < total`, whatever `end` is
- * asked for. That is the belt-and-braces half of issue #32: cap validation
- * keeps an empty window from arising in the first place, and this keeps an
- * empty window from turning into a `nextOffset === offset` paging loop if one
- * ever does. Exported for direct testing of that invariant.
- */
+/** End boundary for UTF-8-safe, forward-progressing result pages. See
+ * documentation/meta-tools.md#result-representation. */
 export declare function alignEndToCharBoundary(bytes: Uint8Array, offset: number, end: number, total: number): number;
 export interface SearchArgs {
     query?: string;
@@ -105,16 +92,16 @@ export interface SkillArgs {
  */
 export declare function createMetaTools(registry: RegistryView, baseUrl: string, opts?: {
     /** Deadline applied when a call passes no `timeoutMs`. Off when unset. */
-    defaultToolTimeoutMs?: number;
+    defaultToolTimeoutMs?: number | undefined;
     /** Per-connector deadline for the search/describe probe fan-out. Default 30_000. */
-    probeTimeoutMs?: number;
+    probeTimeoutMs?: number | undefined;
     /** Maximum simultaneous connector discovery operations. Default 4. */
-    discoveryConcurrency?: number;
-    activity?: ActivityRequestContext;
+    discoveryConcurrency?: number | undefined;
+    activity?: ActivityRequestContext | undefined;
     /** Inbound request cancellation shared by every call this request makes. */
-    requestSignal?: AbortSignal;
+    requestSignal?: AbortSignal | undefined;
     /** Runtime-owned tail for stale catalog refreshes. */
-    defer?: DeferredWork;
+    defer?: DeferredWork | undefined;
 }): {
     skills(args?: SkillArgs): Promise<ToolResult>;
     searchTools(args: SearchArgs): Promise<ToolResult>;
@@ -133,10 +120,10 @@ export declare function createMetaTools(registry: RegistryView, baseUrl: string,
  */
 export declare function registerMetaTools(server: McpServer, registry: RegistryView, ctx: {
     baseUrl: string;
-    defaultToolTimeoutMs?: number;
-    probeTimeoutMs?: number;
-    discoveryConcurrency?: number;
-    activity?: ActivityRequestContext;
-    requestSignal?: AbortSignal;
-    defer?: DeferredWork;
+    defaultToolTimeoutMs?: number | undefined;
+    probeTimeoutMs?: number | undefined;
+    discoveryConcurrency?: number | undefined;
+    activity?: ActivityRequestContext | undefined;
+    requestSignal?: AbortSignal | undefined;
+    defer?: DeferredWork | undefined;
 }): void;