@zackbart/connecta 0.18.2 → 0.19.0

package/dist/meta-tools.js

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { boundedDiscoveryText, CatalogService, DEFAULT_SEARCH_LIMIT, DiscoveryPolicyError, groupedSearchResult, MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_SEARCH_LIMIT, } from "./catalog-service.js";
 import { resolveDiscoveryConcurrency } from "./concurrency.js";
+import { msg } from "./errors.js";
+import { serializeResultText } from "./executor-result.js";
 import { InvocationService, MAX_RETRY_BACKOFF_MS, retryBackoffMs, } from "./invocation.js";
 import { isValidMaxResultBytes, MIN_MAX_RESULT_BYTES, resolveMaxResultBytes, } from "./registry.js";
 import { hasConnectorGuides, listSkills, resolveSkill, } from "./skills.js";
@@ -9,9 +11,9 @@ export { MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_RETRY_BACKOFF_M
 const RESULT_TTL_SECONDS = 900;
 const enc = new TextEncoder();
 const dec = new TextDecoder();
-export function jsonResult(obj) {
+export function jsonResult(obj, text = JSON.stringify(obj)) {
     return {
-        content: [{ type: "text", text: JSON.stringify(obj) }],
+        content: [{ type: "text", text }],
         ...(obj !== null && typeof obj === "object" && !Array.isArray(obj)
             ? { structuredContent: obj }
             : {}),
@@ -20,9 +22,6 @@ export function jsonResult(obj) {
 export function errorResult(message) {
     return { content: [{ type: "text", text: message }], isError: true };
 }
-function msg(err) {
-    return err instanceof Error ? err.message : String(err);
-}
 function discoveryErrorResult(error) {
     const result = jsonResult({
         error: {
@@ -38,12 +37,7 @@ async function discoveryResult(operation, hint) {
     try {
         const value = await operation();
         const text = boundedDiscoveryText(value, hint);
-        return {
-            content: [{ type: "text", text }],
-            ...(value !== null && typeof value === "object" && !Array.isArray(value)
-                ? { structuredContent: value }
-                : {}),
-        };
+        return jsonResult(value, text);
     }
     catch (err) {
         if (err instanceof DiscoveryPolicyError) {
@@ -58,20 +52,8 @@ function isContinuationByte(b) {
 }
 /** Smallest accepted `get_result` byte offset. */
 const MIN_RESULT_OFFSET = 0;
-/**
- * The one definition of a usable `get_result` offset: a whole number of bytes
- * at or past {@link MIN_RESULT_OFFSET}. Shared by the registered zod schema and
- * the handler's own check, the way `isValidMaxResultBytes` is shared across the
- * cap's intake points (issue #32) — so a value valid at the wire is valid in
- * process, and the two cannot drift.
- *
- * Everything else is rejected rather than coerced, because coercion is how an
- * out-of-domain offset used to void a result silently: `Math.max(0, NaN)` is
- * `NaN`, which slices to nothing, serializes as `"offset": null`, and reports
- * no `nextOffset` — a caller sees a successful, empty result instead of an
- * error. An offset past the end of the payload stays legal: it is a whole
- * number of bytes, and it answers with an empty final page.
- */
+/** Whole-byte offset accepted by the result representation documented in
+ * documentation/meta-tools.md#result-representation. */
 function isValidResultOffset(value) {
     return Number.isInteger(value) && value >= MIN_RESULT_OFFSET;
 }
@@ -93,21 +75,8 @@ export function alignStartToCharBoundary(bytes, offset) {
         o--;
     return o;
 }
-/**
- * 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 function alignEndToCharBoundary(bytes, offset, end, total) {
     if (end >= total)
         return total;
@@ -615,10 +584,6 @@ function applyFieldsToContent(content, fields, outputSchema) {
  * the three give one answer to the same question. A value JSON cannot serialize
  * at all (a BigInt) still throws, as before, and is reported as a failure.
  */
-function serializeResultText(value) {
-    const serialized = JSON.stringify(value);
-    return serialized === undefined ? String(value) : serialized;
-}
 /**
  * Stash `text` under `result:<uuid>` (ttl 900s) and describe it as the
  * truncation notice every over-cap path hands back.
@@ -761,7 +726,7 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
         requestScope,
         probeTimeoutMs,
         concurrency: discoveryConcurrency,
-        ...(opts.defer ? { defer: opts.defer } : {}),
+        defer: opts.defer,
         // searchRoute keeps its top-level default. In-program callers use a
         // separate CatalogService configured for connecta.search.
     });
@@ -792,19 +757,18 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                 // override the registry already warned about at startup is dropped
                 // here, so the connector simply inherits `globalCap`.
                 const cap = resolveMaxResultBytes(resolved.connector.maxResultBytes, globalCap);
+                const processed = (toolResult, truncated, value) => ({
+                    toolResult,
+                    ...value,
+                    ...(truncated ? { friction: "result_too_large" } : {}),
+                });
                 if (call.resultMode === "value") {
                     let value = fields
                         ? projectionValue(result, fields, resolved.definition.outputSchema)
                         : result;
                     const guarded = await guardValue(value, results, cap);
                     value = guarded.result;
-                    return {
-                        toolResult: jsonResult({ ok: true, data: value }),
-                        value,
-                        ...(guarded.truncated
-                            ? { friction: "result_too_large" }
-                            : {}),
-                    };
+                    return processed(jsonResult({ ok: true, data: value }), guarded.truncated, { value });
                 }
                 if (resolved.connector.kind === "mcp") {
                     const mcpResult = result;
@@ -813,33 +777,25 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                         content = applyFieldsToContent(content, fields, resolved.definition.outputSchema);
                     }
                     const guarded = await guardContent(content, results, cap);
-                    return {
-                        toolResult: guarded.result,
-                        ...(guarded.truncated
-                            ? { friction: "result_too_large" }
-                            : {}),
-                    };
+                    return processed(guarded.result, guarded.truncated);
                 }
                 const value = fields
                     ? projectionValue(result, fields, resolved.definition.outputSchema)
                     : result;
                 const guarded = await guardText(serializeResultText(value), results, cap);
-                return {
-                    toolResult: guarded.result,
-                    value,
-                    ...(guarded.truncated
-                        ? { friction: "result_too_large" }
-                        : {}),
-                };
+                return processed(guarded.result, guarded.truncated, { value });
             },
             activityFriction: (processed) => processed.friction,
         });
         if (!outcome.ok) {
             const structuredRecovery = outcome.error.nextAction !== undefined;
-            const failedResult = structuredRecovery ||
-                outcome.error.code === "auth_required" ||
-                outcome.error.code === "invalid_args" ||
-                outcome.error.code === "input_required_unsupported" ||
+            const recoveryRequired = structuredRecovery ||
+                [
+                    "auth_required",
+                    "invalid_args",
+                    "input_required_unsupported",
+                ].includes(outcome.error.code);
+            const failedResult = recoveryRequired ||
                 call.resultMode === "value"
                 ? jsonResult({
                     ok: false,
@@ -849,10 +805,7 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                     ...(call.diagnostics ? { timing: outcome.timing } : {}),
                 })
                 : errorResult(outcome.error.message);
-            if (structuredRecovery ||
-                outcome.error.code === "auth_required" ||
-                outcome.error.code === "invalid_args" ||
-                outcome.error.code === "input_required_unsupported") {
+            if (recoveryRequired) {
                 failedResult.isError = true;
             }
             return {
@@ -1050,7 +1003,6 @@ const CALL_DESTRUCTIVE_DESC = "Call any tool not explicitly annotated readOnlyHi
 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 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,
@@ -1107,20 +1059,12 @@ const CALL_INPUT_SCHEMA = {
  */
 export function registerMetaTools(server, registry, ctx) {
     const mt = createMetaTools(registry, ctx.baseUrl, {
-        ...(ctx.defaultToolTimeoutMs !== undefined
-            ? { defaultToolTimeoutMs: ctx.defaultToolTimeoutMs }
-            : {}),
-        ...(ctx.probeTimeoutMs !== undefined
-            ? { probeTimeoutMs: ctx.probeTimeoutMs }
-            : {}),
-        ...(ctx.discoveryConcurrency !== undefined
-            ? { discoveryConcurrency: ctx.discoveryConcurrency }
-            : {}),
-        ...(ctx.activity !== undefined ? { activity: ctx.activity } : {}),
-        ...(ctx.requestSignal !== undefined
-            ? { requestSignal: ctx.requestSignal }
-            : {}),
-        ...(ctx.defer !== undefined ? { defer: ctx.defer } : {}),
+        defaultToolTimeoutMs: ctx.defaultToolTimeoutMs,
+        probeTimeoutMs: ctx.probeTimeoutMs,
+        discoveryConcurrency: ctx.discoveryConcurrency,
+        activity: ctx.activity,
+        requestSignal: ctx.requestSignal,
+        defer: ctx.defer,
     });
     server.registerTool("skills", {
         description: describedFor(registry, SKILLS_DESC, "skills"),
@@ -1129,7 +1073,7 @@ export function registerMetaTools(server, registry, ctx) {
         _meta: { ui: { visibility: ["model"] } },
     }, async (args) => mt.skills(args));
     server.registerTool("search_tools", {
-        description: describedFor(registry, SEARCH_WITH_DESCRIBE_DESC, "search"),
+        description: describedFor(registry, SEARCH_DESC, "search"),
         inputSchema: z.object({
             query: z.string().optional(),
             connector: z.string().optional(),

package/dist/providers/cloudflare.d.ts

@@ -3,25 +3,9 @@ import type { Connector, ConnectorCredentialConfig } from "../types.js";
 export declare const CLOUDFLARE_API_BASE = "https://api.cloudflare.com/client/v4";
 /** Authentication schemes accepted by Cloudflare's v4 API. */
 export type CloudflareAuthentication = "apiToken" | "globalApiKey";
-/**
- * Every DNS record type the records API accepts, for filtering a list.
- * Enumerated in the schema so an agent picks a legal type without reading
- * Cloudflare's documentation.
- */
+/** See documentation/cloudflare.md#dns-record-types. */
 export declare const CLOUDFLARE_DNS_RECORD_TYPES: readonly ["A", "AAAA", "CAA", "CERT", "CNAME", "DNSKEY", "DS", "HTTPS", "LOC", "MX", "NAPTR", "NS", "OPENPGPKEY", "PTR", "SMIMEA", "SRV", "SSHFP", "SVCB", "TLSA", "TXT", "URI"];
-/**
- * The record types whose value is a single `content` string — the eight this
- * connection can create and update.
- *
- * The other thirteen (CAA, CERT, DNSKEY, DS, HTTPS, LOC, NAPTR, SMIMEA, SRV,
- * SSHFP, SVCB, TLSA, URI) carry a per-type structured `data` object instead,
- * each with its own field set. Accepting them here would mean either a
- * free-form `data` passthrough — exactly the untyped `{}` this connection
- * exists to avoid — or thirteen more hand-written schemas for record types
- * that are rare in the day-to-day work this surface is for. They remain fully
- * readable and filterable; only the named create/update tools omit them. The
- * guarded raw mutation tool remains available for their documented bodies.
- */
+/** Content-valued types only; see documentation/cloudflare.md#dns-record-types. */
 export declare const CLOUDFLARE_CONTENT_DNS_RECORD_TYPES: readonly ["A", "AAAA", "CNAME", "MX", "NS", "OPENPGPKEY", "PTR", "TXT"];
 export interface CloudflareOptions {
     /** Human-readable display name; defaults to "Cloudflare". */