@zackbart/connecta 0.16.1 → 0.18.0

package/dist/invocation.js

@@ -282,7 +282,9 @@ export class InvocationService {
             context.beforeDispatch?.();
         }
         catch (error) {
-            return failed(classifyCallError(error));
+            return failed(error instanceof InvocationFailure
+                ? error.details
+                : classifyCallError(error));
         }
         const maxRetries = Math.min(2, Math.max(0, Math.trunc(context.maxRetries ?? 0)));
         let result;

package/dist/meta-tools.d.ts

@@ -1,6 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/server";
 import type { ActivityRequestContext } from "./activity.js";
 import { MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_SEARCH_LIMIT } from "./catalog-service.js";
+import type { DeferredWork } from "./connector-scope.js";
 import { MAX_RETRY_BACKOFF_MS, retryBackoffMs } from "./invocation.js";
 import { type RegistryView } from "./registry.js";
 export { MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_RETRY_BACKOFF_MS, MAX_SEARCH_LIMIT, retryBackoffMs, };
@@ -112,6 +113,8 @@ export declare function createMetaTools(registry: RegistryView, baseUrl: string,
     activity?: ActivityRequestContext;
     /** Inbound request cancellation shared by every call this request makes. */
     requestSignal?: AbortSignal;
+    /** Runtime-owned tail for stale catalog refreshes. */
+    defer?: DeferredWork;
 }): {
     skills(args?: SkillArgs): Promise<ToolResult>;
     searchTools(args: SearchArgs): Promise<ToolResult>;
@@ -135,4 +138,5 @@ export declare function registerMetaTools(server: McpServer, registry: RegistryV
     discoveryConcurrency?: number;
     activity?: ActivityRequestContext;
     requestSignal?: AbortSignal;
+    defer?: DeferredWork;
 }): void;

package/dist/meta-tools.js

@@ -125,25 +125,41 @@ export function alignEndToCharBoundary(bytes, offset, end, total) {
     }
     return e;
 }
-// --- fields selection (feature 2) -----------------------------------------
-/** Resolve a dot-path (segments) against a value; `key[]` maps the tail over an array. */
+/** Resolve a dot-path and retain misses below every `[]` boundary. */
 function resolvePath(value, segments) {
     const seg = segments[0];
-    if (seg === undefined)
-        return value;
+    if (seg === undefined) {
+        return value === undefined
+            ? { status: "unmatched" }
+            : { status: "matched", value };
+    }
     const rest = segments.slice(1);
     const isArr = seg.endsWith("[]");
     const key = isArr ? seg.slice(0, -2) : seg;
     let next = value;
     if (key !== "") {
-        if (value === null || typeof value !== "object")
-            return undefined;
+        if (value === null || typeof value !== "object") {
+            return { status: "unmatched" };
+        }
         next = value[key];
     }
     if (isArr) {
         if (!Array.isArray(next))
-            return undefined;
-        return next.map((el) => resolvePath(el, rest));
+            return { status: "unmatched" };
+        if (next.length === 0)
+            return { status: "matched", value: [] };
+        const elements = next.map((el) => resolvePath(el, rest));
+        const matched = elements.some((element) => element.status !== "unmatched");
+        const missed = elements.some((element) => element.status !== "matched");
+        if (!matched)
+            return { status: "unmatched" };
+        return {
+            status: missed ? "partial" : "matched",
+            // Undefined placeholders retain the historical array positions in the
+            // partial value. JSON renders them as null; partialFields says they are
+            // unresolved rather than genuine downstream nulls.
+            value: elements.map((element) => element.status === "unmatched" ? undefined : element.value),
+        };
     }
     return resolvePath(next, rest);
 }
@@ -517,14 +533,19 @@ function schemaProjectionFeedback(outputSchema, unmatchedFields) {
 function applyFields(value, fields) {
     const out = {};
     const unmatchedFields = [];
+    const partialFields = [];
     for (const path of fields) {
         const resolved = resolvePath(value, path.split("."));
-        if (resolved === undefined)
+        if (resolved.status === "unmatched") {
             unmatchedFields.push(path);
-        else
-            out[path] = resolved;
+        }
+        else {
+            out[path] = resolved.value;
+            if (resolved.status === "partial")
+                partialFields.push(path);
+        }
     }
-    return { data: out, unmatchedFields };
+    return { data: out, unmatchedFields, partialFields };
 }
 /**
  * Keep the historical flat projection when every path resolves. A miss gets a
@@ -537,16 +558,25 @@ function projectionValue(value, fields, outputSchema) {
     // matched downstream field with that exact name is escaped below `data`, so
     // no user-controlled value can impersonate Connecta's discriminator.
     const reservedCollision = Object.prototype.hasOwnProperty.call(projected.data, "$connecta");
-    if (projected.unmatchedFields.length === 0 && !reservedCollision) {
+    if (projected.unmatchedFields.length === 0 &&
+        projected.partialFields.length === 0 &&
+        !reservedCollision) {
         return projected.data;
     }
+    const problemFields = [
+        ...projected.unmatchedFields,
+        ...projected.partialFields,
+    ];
     return {
         data: projected.data,
         $connecta: {
             type: "field_projection",
             unmatchedFields: projected.unmatchedFields,
+            ...(projected.partialFields.length > 0
+                ? { partialFields: projected.partialFields }
+                : {}),
             ...(outputSchema
-                ? schemaProjectionFeedback(outputSchema, projected.unmatchedFields)
+                ? schemaProjectionFeedback(outputSchema, problemFields)
                 : {}),
         },
     };
@@ -731,6 +761,7 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
         requestScope,
         probeTimeoutMs,
         concurrency: discoveryConcurrency,
+        ...(opts.defer ? { defer: opts.defer } : {}),
         // searchRoute keeps its top-level default. In-program callers use a
         // separate CatalogService configured for connecta.search.
     });
@@ -1013,13 +1044,13 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
         },
     };
 }
-const SEARCH_DESC = `Use top-level search only for exactly one unreduced read, then call_tool, or for write-capable work, then call_destructive_tool. For read-only reduction, dependent or multiple calls, never search here: make one execute_code program that searches and calls. Use 2–4 distinctive action/object terms, not the full request; set connector to the obvious integration id to load one catalog instead of all; omit limit initially (default ${DEFAULT_SEARCH_LIMIT}), page to ${MAX_SEARCH_LIMIT} if needed. safety="readOnly" returns only calls available to call_tool/code; "approvalRequired" returns the rest; omitted/"all" returns all. This filters results, not authority. includeSchemas="compact" adds the input and any declared output shape, bounded; plain objects expose inputKeys, requiredInputKeys, and outputKeys; truncation flags mark incomplete shapes; matches also carry declared annotations. Require purpose/address fit plus compatible inputs, truncation, safety, and outputs — never the first lexical match. Empty or whitespace-only query browses all; non-empty input with no ASCII terms returns no match.`;
-const CALL_DESC = 'Use for ONE tool explicitly annotated readOnlyHint: true — the cheapest path for a single cold call. For two or more calls, dependent steps, loops, joins, or data reduction use execute_code, whose connecta.call and connecta.batch reach the same tools. Unannotated, write-capable, and destructive tools are refused and require call_destructive_tool. fields selects JSON dot-paths; traverse arrays with [] (for example results[].id). Misses return data plus `$connecta` feedback. resultMode "value" unwraps results, timeoutMs sets a deadline, safe maxRetries are annotation-gated, diagnostics adds timing, and large results page through get_result.';
-const CALL_DESTRUCTIVE_DESC = "Invoke any tool that is not explicitly annotated readOnlyHint: true, including unannotated, write-capable, or destructive tools. Include a short reason explaining the intended consequence for the human reviewer; it grants no authority and is never passed downstream. The MCP destructiveHint on this meta-tool lets the host request human approval before execution. Use only after reviewing the downstream tool schema and consequences.";
-const GET_RESULT_DESC = "Page a truncated result stashed by call_tool or call_destructive_tool; a program's oversized return is not paged, so reduce it in code instead. Input { id, offset?, maxBytes? } → { text, offset, nextOffset?, totalBytes } sliced by byte offset. maxBytes is a whole number of bytes >= 1 (omit for the deployment default) and offset a whole number of bytes >= 0; an offset inside a multi-byte character is moved back to that character's first byte and the offset served is returned. Unknown/expired id is an error.";
+const SEARCH_DESC = `Use top-level search for one unknown-address read before call_tool, or for approval-required work before call_destructive_tool. 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. For multiple, dependent, or reduced read-only calls, use one execute_code program instead. Empty query browses.`;
+const CALL_DESC = 'Call one tool explicitly annotated readOnlyHint: true. Use execute_code for multiple, dependent, or reduced read-only calls. Unannotated or write-capable tools fail closed to call_destructive_tool. fields projects JSON dot-paths; use [] through arrays. 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 text, offset, nextOffset when more remains, and totalBytes.";
 const AUTHORIZE_DESC = "Use after auth_required. Returns an OAuth or operator-credential handoff, or reports required deployment configuration. force=true restarts OAuth only; this tool never accepts credentials.";
-const SKILLS_DESC = 'List or fetch concise guidance for choosing among Connecta meta-tools. Call skills({ name: "usage" }) once when the routing workflow is unfamiliar; do not refetch it in the same task.';
-const SEARCH_WITH_DESCRIBE_DESC = `${SEARCH_DESC} Expand an ambiguous compact shape, or read exact JSON constraints, with connecta.describe inside execute_code.`;
+const SKILLS_DESC = 'List or fetch on-demand guidance. Fetch usage once per task for program syntax, selection, repair, examples, and runtime details.';
+const SEARCH_WITH_DESCRIBE_DESC = SEARCH_DESC;
 /**
  * Sentences appended to a meta-tool description only when this connection
  * actually has connector guides. Tool descriptions are always-loaded context,
@@ -1029,9 +1060,9 @@ const SEARCH_WITH_DESCRIBE_DESC = `${SEARCH_DESC} Expand an ambiguous compact sh
  * Registration is per connection and reads the configured connector set.
  */
 const GUIDE_NOTES = {
-    skills: " skills({}) also lists this deployment's scoped connector guides; fetch only an exact name listed there or carried by discovery, never one inferred from a connector id.",
-    search: " A result carrying `guide` also carries a bounded `guideSummary`. `guideRequired: true` is a hard stop: fetch that exact guide before calling. `guideRequiredReasons` explains why — `connector_required` and `approval_required` stand however you expand the schema; `schema_truncated` clears once describe returns the exact one. Otherwise fetch only when the summary names a connector convention relevant to the task. A complete, unambiguous read-only schema needs no otherwise-irrelevant guide fetch.",
-    destructive: " Before a consequential call, inspect the address through discovery or describe and fetch any connector guide it names.",
+    skills: " Also lists this deployment's connector guides by exact name.",
+    search: " A result with guideRequired: true requires its exact named connector guide before the call.",
+    destructive: " Fetch any exact connector guide named by discovery before the call.",
 };
 /** `base`, plus its guide note when any VISIBLE connector carries a guide. */
 function describedFor(registry, base, note) {
@@ -1089,6 +1120,7 @@ export function registerMetaTools(server, registry, ctx) {
         ...(ctx.requestSignal !== undefined
             ? { requestSignal: ctx.requestSignal }
             : {}),
+        ...(ctx.defer !== undefined ? { defer: ctx.defer } : {}),
     });
     server.registerTool("skills", {
         description: describedFor(registry, SKILLS_DESC, "skills"),