@zackbart/connecta 0.16.0 → 0.17.0

package/dist/catalog.js

@@ -2,6 +2,7 @@ const DEFAULT_DESCRIPTION_LENGTH = 240;
 const DISCOVERY_DESCRIPTION_LENGTH = 160;
 export const MAX_COMPACT_DISCOVERY_SCHEMA_BYTES = 1_024;
 const MAX_COMPACT_DISCOVERY_ENUM_BYTES = MAX_COMPACT_DISCOVERY_SCHEMA_BYTES / 4;
+const MAX_COMPACT_DISCOVERY_CONSTRAINT_BYTES = MAX_COMPACT_DISCOVERY_SCHEMA_BYTES / 4;
 const schemaEncoder = new TextEncoder();
 const COMPACT_DISCOVERY_TRUNCATION = " /* truncated */";
 export function summarizeDescription(text, full) {
@@ -166,6 +167,26 @@ function matchingTokenCandidates(term) {
     }
     return candidates;
 }
+/**
+ * Whether one query term matches a whole token of arbitrary text, under the
+ * same inflection rules the tool index uses.
+ *
+ * Connector identity — an `id` or a `title` — is deliberately not a document in
+ * that index: making it one would move ranking for every query that already
+ * matches tools. This lets a caller ask the index's question of a string that
+ * never became a document, which is what the no-match analysis needs to tell
+ * "nothing like this exists here" from "that word is a connector".
+ */
+export function matchesLexicalTerm(text, term) {
+    const tokens = new Set(lexicalTokens(text));
+    if (tokens.size === 0)
+        return false;
+    for (const candidate of matchingTokenCandidates(term)) {
+        if (tokens.has(candidate))
+            return true;
+    }
+    return false;
+}
 /**
  * Compute query-specific document frequencies across every available catalog.
  * The caller does this once per search and shares the result with each
@@ -303,7 +324,8 @@ function declaresShape(s) {
         s.const !== undefined ||
         s.items !== undefined ||
         s.properties !== undefined ||
-        s.type !== undefined);
+        s.type !== undefined ||
+        constraintEntries(s).length > 0);
 }
 /**
  * Parenthesize a top-level union so it doesn't read as part of a surrounding
@@ -346,6 +368,56 @@ function renderEnum(values, byteLimit, onTruncated) {
     }
     return rendered;
 }
+function safeConstraintValue(value) {
+    return JSON.stringify(value).replaceAll("*/", "*\\/");
+}
+function constraintEntries(schema) {
+    const entries = [];
+    const number = (keyword, label) => {
+        const value = schema[keyword];
+        if (typeof value === "number" && Number.isFinite(value)) {
+            entries.push(`${label} ${value}`);
+        }
+    };
+    const integer = (keyword, label) => {
+        const value = schema[keyword];
+        if (typeof value === "number" && Number.isInteger(value) && value >= 0) {
+            entries.push(`${label} ${value}`);
+        }
+    };
+    number("minimum", ">=");
+    number("exclusiveMinimum", ">");
+    number("maximum", "<=");
+    number("exclusiveMaximum", "<");
+    number("multipleOf", "multiple of");
+    integer("minLength", "length >=");
+    integer("maxLength", "length <=");
+    if (typeof schema.format === "string") {
+        entries.push(`format ${safeConstraintValue(schema.format)}`);
+    }
+    if (typeof schema.pattern === "string") {
+        entries.push(`pattern ${safeConstraintValue(schema.pattern)}`);
+    }
+    return entries;
+}
+function renderConstraints(base, schema, byteLimit, onTruncated) {
+    const entries = constraintEntries(schema);
+    if (entries.length === 0)
+        return base;
+    const kept = [];
+    for (const entry of entries) {
+        const candidate = ` /* ${[...kept, entry].join("; ")} */`;
+        if (byteLimit !== undefined &&
+            schemaEncoder.encode(candidate).length > byteLimit) {
+            onTruncated?.();
+            continue;
+        }
+        kept.push(entry);
+    }
+    return kept.length === 0
+        ? base
+        : `${grouped(base)} /* ${kept.join("; ")} */`;
+}
 function renderSchema(schema, defs, seen, depth, options) {
     if (depth > 4)
         return "…";
@@ -385,24 +457,36 @@ function renderSchema(schema, defs, seen, depth, options) {
         seen.add(name);
         const rendered = renderSchema(target, defs, seen, depth, options);
         seen.delete(name);
-        return rendered;
+        return options.renderConstraints
+            ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
+            : rendered;
     }
     const union = (s.oneOf ?? s.anyOf);
     if (Array.isArray(union)) {
-        return (union
+        const rendered = union
             .map((u) => renderSchema(u, defs, seen, depth + 1, options))
             .join(" | ") ||
-            "unknown");
+            "unknown";
+        return options.renderConstraints
+            ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
+            : rendered;
     }
     if (Array.isArray(s.enum)) {
-        return renderEnum(s.enum, options.enumByteLimit, options.onEnumTruncated);
+        const rendered = renderEnum(s.enum, options.enumByteLimit, options.onEnumTruncated);
+        return options.renderConstraints
+            ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
+            : rendered;
     }
     // Checked before type/properties so a discriminator like
     // { type: "string", const: "emoji" } renders as "emoji" rather than string.
     // JSON.stringify(undefined) returns undefined (not a string), so an explicit
     // `const: undefined` must fall through to the regular type rendering.
-    if (s.const !== undefined)
-        return JSON.stringify(s.const);
+    if (s.const !== undefined) {
+        const rendered = JSON.stringify(s.const);
+        return options.renderConstraints
+            ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
+            : rendered;
+    }
     const type = s.type;
     if (type === "array" || s.items) {
         const items = s.items
@@ -434,10 +518,20 @@ function renderSchema(schema, defs, seen, depth, options) {
         })
             .join(", ")} }`;
     }
-    if (typeof type === "string")
-        return type;
-    if (Array.isArray(type))
-        return type.join(" | ");
+    if (typeof type === "string") {
+        return options.renderConstraints
+            ? renderConstraints(type, s, options.constraintByteLimit, options.onConstraintTruncated)
+            : type;
+    }
+    if (Array.isArray(type)) {
+        const rendered = type.join(" | ");
+        return options.renderConstraints
+            ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
+            : rendered;
+    }
+    if (options.renderConstraints && constraintEntries(s).length > 0) {
+        return renderConstraints("unknown", s, options.constraintByteLimit, options.onConstraintTruncated);
+    }
     return JSON.stringify(schema);
 }
 const compactSchemas = new WeakMap();
@@ -455,6 +549,7 @@ export function compactSchema(schema) {
         rendered = renderSchema(schema, defs, new Set(), 0, {
             propertyDescriptions: true,
             requiredFirst: false,
+            renderConstraints: true,
         });
     }
     catch {
@@ -514,6 +609,7 @@ export function compactDiscoverySchema(schema) {
     };
     let rendered;
     let enumTruncated = false;
+    let constraintTruncated = false;
     try {
         rendered = renderSchema(schema, defs, new Set(), 0, {
             propertyDescriptions: false,
@@ -525,15 +621,41 @@ export function compactDiscoverySchema(schema) {
             onEnumTruncated: () => {
                 enumTruncated = true;
             },
+            renderConstraints: true,
+            constraintByteLimit: MAX_COMPACT_DISCOVERY_CONSTRAINT_BYTES,
+            onConstraintTruncated: () => {
+                constraintTruncated = true;
+            },
         });
     }
     catch {
         rendered = JSON.stringify(schema);
     }
+    if (schemaEncoder.encode(rendered).length >
+        MAX_COMPACT_DISCOVERY_SCHEMA_BYTES) {
+        try {
+            rendered = renderSchema(schema, defs, new Set(), 0, {
+                propertyDescriptions: false,
+                requiredFirst: true,
+                enumByteLimit: MAX_COMPACT_DISCOVERY_ENUM_BYTES,
+                onEnumTruncated: () => {
+                    enumTruncated = true;
+                },
+                renderConstraints: false,
+            });
+            constraintTruncated = true;
+        }
+        catch {
+            rendered = JSON.stringify(schema);
+        }
+    }
     const bytes = schemaEncoder.encode(rendered);
     let result;
     if (bytes.length <= MAX_COMPACT_DISCOVERY_SCHEMA_BYTES) {
-        result = { text: rendered, truncated: enumTruncated };
+        result = {
+            text: rendered,
+            truncated: enumTruncated || constraintTruncated,
+        };
     }
     else {
         result = {

package/dist/errors.d.ts

@@ -1,5 +1,31 @@
-/** Machine-readable classification of a failed connector tool call. */
-export type ConnectorCallErrorCode = "timeout" | "auth_required" | "rate_limited" | "unavailable" | "invalid_args" | "input_required_unsupported" | "connector_call_failed";
+/**
+ * Machine-readable classification of a failed connector tool call.
+ *
+ * A code earns its place by changing what the caller does next, never by
+ * naming a cause — the rule provider conventions call H11.
+ */
+export type ConnectorCallErrorCode = "timeout" | "auth_required" | "rate_limited" | "unavailable" | "invalid_args"
+/**
+ * The downstream answered, and the thing addressed is not there.
+ *
+ * Its own code because the next move is none of the others': not a retry,
+ * not `authorize_connector`, not a reshaped argument object, but
+ * re-addressing — look the identifier up again, or accept the absence and
+ * carry on. Inside `execute_code` a program reads that difference from a
+ * caught error's `code` or a `connecta.batch` entry's `errorDetails.code` —
+ * continue past this one, abort on `connector_call_failed`. Message prose
+ * cannot be classified.
+ *
+ * Use it only where the provider distinguishes absence from a permission
+ * gap. A status that means both "it is not there" and "you cannot see it" —
+ * Notion's `object_not_found` is the worked example — stays
+ * `connector_call_failed` with a message that states the ambiguity, because
+ * inventing certainty here is how an agent concludes a page was deleted when
+ * it was simply never shared. Addresses connecta itself cannot resolve are
+ * already framed as `unknown_address` or `unknown_tool` and never reach a
+ * connector, so this code is always about a resource the downstream owns.
+ */
+ | "not_found" | "input_required_unsupported" | "connector_call_failed";
 /** One bounded, payload-free explanation of an input-schema mismatch. */
 export interface ArgumentValidationIssue {
     /** JSON Pointer into the submitted arguments; "/" means the root value. */

package/dist/errors.js

@@ -108,6 +108,7 @@ const RETRYABLE_BY_CODE = {
     unavailable: true,
     auth_required: false,
     invalid_args: false,
+    not_found: false,
     input_required_unsupported: false,
     connector_call_failed: false,
 };

package/dist/execute.d.ts

@@ -1,5 +1,6 @@
 import type { McpServer } from "@modelcontextprotocol/server";
 import type { ActivityRequestContext } from "./activity.js";
+import type { DeferredWork } from "./connector-scope.js";
 import { type ToolResult } from "./meta-tools.js";
 import { InvocationFailure } from "./invocation.js";
 import type { RegistryView } from "./registry.js";
@@ -157,6 +158,8 @@ export declare function buildSandboxProviders(registry: RegistryView, baseUrl: s
      * blocks nobody will ever return.
      */
     emitCollector?: EmitCollector;
+    /** Runtime-owned tail for stale catalog refreshes. */
+    defer?: DeferredWork;
 }): Promise<ExecutorProvider[]>;
 /** The execute_code handler. Exported for direct testing. */
 export declare function createExecuteTool(registry: RegistryView, baseUrl: string, executor: Executor, logger: Logger, activity?: ActivityRequestContext, config?: {
@@ -164,6 +167,7 @@ export declare function createExecuteTool(registry: RegistryView, baseUrl: strin
     probeTimeoutMs?: number;
     maxEmittedBytes?: number;
     maxEmittedBlocks?: number;
+    defer?: DeferredWork;
 }): ({ code, diagnostics: diagnosticsRequested }: {
     code: string;
     diagnostics?: boolean;
@@ -189,5 +193,6 @@ export declare function registerExecuteTool(server: McpServer, registry: Registr
     maxEmittedBytes?: number;
     /** Block-count budget for connecta.emit. Default 32. */
     maxEmittedBlocks?: number;
+    defer?: DeferredWork;
 }): void;
 export {};