@zackbart/connecta 0.24.4 → 0.25.0

package/dist/catalog.js

@@ -35,11 +35,29 @@ class SchemaWork {
         const visit = this.visit.bind(this);
         const text = this.text.bind(this);
         const ancestors = [];
+        let serializedBytes = 0;
+        const addSerialized = (value) => {
+            serializedBytes += schemaEncoder.encode(value).length;
+            if (serializedBytes > this.byteLimit)
+                throw schemaSizeExceeded;
+        };
         return this.text(JSON.stringify(value, function (key, item) {
             visit();
             text(key);
             if (typeof item === "string")
                 text(item);
+            const omitted = item === undefined || typeof item === "function" || typeof item === "symbol";
+            const root = key === "" && ancestors.length === 0;
+            if (!omitted) {
+                // Array indexes are implicit in JSON. Object keys and primitive values
+                // are the useful lower bound; the final text check remains authoritative
+                // for braces, commas, and values whose encoding is larger than this bound.
+                if (!root && !Array.isArray(this))
+                    addSerialized(JSON.stringify(key));
+                if (typeof item !== "object" || item === null) {
+                    addSerialized(JSON.stringify(item));
+                }
+            }
             if (item !== null && typeof item === "object") {
                 while (ancestors.length && ancestors[ancestors.length - 1] !== this) {
                     ancestors.pop();
@@ -481,17 +499,114 @@ function renderConstraints(base, schema, byteLimit, onTruncated) {
         ? base
         : `${grouped(base)} /* ${kept.join("; ")} */`;
 }
+/**
+ * `grouped` for the TypeScript dialect, whose JSDoc prose and string literals
+ * may carry unbalanced brackets from a downstream description: skipping both
+ * keeps a stray `)` in prose from hiding a real top-level union.
+ */
+function groupedType(part) {
+    let nesting = 0;
+    for (let i = 0; i < part.length; i += 1) {
+        const char = part[i];
+        if (part.startsWith("/*", i)) {
+            const end = part.indexOf("*/", i + 2);
+            if (end < 0)
+                break;
+            i = end + 1;
+        }
+        else if (char === '"') {
+            for (i += 1; i < part.length && part[i] !== '"'; i += 1) {
+                if (part[i] === "\\")
+                    i += 1;
+            }
+        }
+        else if (char === "{" || char === "(" || char === "[" || char === "<") {
+            nesting += 1;
+        }
+        else if (char === "}" || char === ")" || char === "]" || char === ">") {
+            nesting -= 1;
+        }
+        else if (nesting === 0 &&
+            (part.startsWith(" | ", i) || part.startsWith(" & ", i))) {
+            return `(${part})`;
+        }
+    }
+    return part;
+}
+const TYPESCRIPT_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function typescriptKey(key) {
+    return TYPESCRIPT_IDENTIFIER.test(key) ? key : JSON.stringify(key);
+}
+/** One-line JSDoc body; downstream prose can never close the comment early. */
+function typescriptDoc(text) {
+    return text.replace(/\s+/g, " ").trim().replaceAll("*/", "*\\/");
+}
+function typescriptPrimitive(type) {
+    if (type === "integer")
+        return "number";
+    if (type === "array")
+        return "unknown[]";
+    if (type === "object")
+        return "Record<string, unknown>";
+    return ["string", "number", "boolean", "null"].includes(type)
+        ? type
+        : "unknown";
+}
+function boundedParts(work, separator, prefix, suffix) {
+    // Check each addition before joining so a rejected schema never creates a
+    // large intermediate string just to discover that the final result is over.
+    const parts = [];
+    let bytes = schemaEncoder.encode(prefix).length + schemaEncoder.encode(suffix).length;
+    const separatorBytes = schemaEncoder.encode(separator).length;
+    return {
+        get length() {
+            return parts.length;
+        },
+        add(part) {
+            const partBytes = schemaEncoder.encode(part).length;
+            const added = partBytes + (parts.length > 0 ? separatorBytes : 0);
+            if (bytes + added > work.byteLimit)
+                throw schemaSizeExceeded;
+            parts.push(part);
+            bytes += added;
+        },
+        finish() {
+            return `${prefix}${parts.join(separator)}${suffix}`;
+        },
+    };
+}
 function renderSchema(schema, defs, seen, depth, options) {
     options.work.visit();
     return options.work.text(renderSchemaNode(schema, defs, seen, depth, options));
 }
 function renderSchemaNode(schema, defs, seen, depth, options) {
-    if (depth > 4)
-        return "…";
+    const ts = options.typescript === true;
+    const group = ts ? groupedType : grouped;
+    if (depth > 4) {
+        if (!ts)
+            return "…";
+        options.work.truncated = true;
+        return `unknown${COMPACT_DISCOVERY_TRUNCATION}`;
+    }
     if (schema === null || typeof schema !== "object") {
+        if (ts)
+            return schema === false ? "never" : "unknown";
         return options.work.json(schema);
     }
     const s = schema;
+    // OpenAPI 3.0's `nullable` has no JSON Schema meaning, so compact ignores
+    // it; a TypeScript reader writing `null` checks needs it in the type.
+    if (ts && s.nullable === true) {
+        const base = Object.create(null);
+        for (const key of propertyNames(s, options.work)) {
+            if (key !== "nullable")
+                base[key] = s[key];
+        }
+        const rendered = declaresShape(base)
+            ? renderSchema(base, defs, seen, depth, options)
+            : "unknown";
+        return rendered === "unknown" ? rendered : `${rendered} | null`;
+    }
     const constrain = (rendered) => options.renderConstraints
         ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
         : rendered;
@@ -524,29 +639,41 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
             if (key !== "allOf")
                 own[key] = s[key];
         }
-        const parts = declaresShape(own)
-            ? [renderSchema(own, defs, seen, depth, options)]
-            : [];
+        const parts = boundedParts(options.work, " & ", "", "");
+        const groupParts = declaresShape(own)
+            ? s.allOf.length > 0
+            : s.allOf.length > 1;
+        if (declaresShape(own)) {
+            const rendered = renderSchema(own, defs, seen, depth, options);
+            parts.add(groupParts ? group(rendered) : rendered);
+        }
         for (const member of s.allOf) {
-            parts.push(renderSchema(member, defs, seen, depth + 1, options));
+            const rendered = renderSchema(member, defs, seen, depth + 1, options);
+            parts.add(groupParts ? group(rendered) : rendered);
         }
         if (parts.length === 0)
             return "unknown";
-        if (parts.length === 1)
-            return parts[0];
-        return parts.map(grouped).join(" & ");
+        return parts.finish();
     }
     const reference = s.$ref ?? s.$dynamicRef;
     if (typeof reference === "string") {
         const dynamic = s.$ref === undefined;
         const rawName = refName(options.work.text(reference));
         const name = dynamic ? rawName.replace(/^#/, "") : rawName;
-        if (seen.has(name))
-            return name;
+        if (seen.has(name)) {
+            if (!ts)
+                return name;
+            // A cycle has no finite TypeScript expansion, and a bare definition
+            // name would be an undeclared type: degrade and send callers to JSON.
+            options.work.truncated = true;
+            return "unknown /* recursive */";
+        }
         const target = resolveDefinition(defs, name);
         if (target === undefined) {
-            if (dynamic)
+            if (dynamic || ts)
                 options.work.truncated = true;
+            if (ts)
+                return "unknown /* unresolved */";
             return dynamic ? "unknown" : name;
         }
         const cacheKey = JSON.stringify([name, depth, [...seen]]);
@@ -561,10 +688,11 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
     }
     const union = (s.oneOf ?? s.anyOf);
     if (Array.isArray(union)) {
-        const rendered = union
-            .map((u) => renderSchema(u, defs, seen, depth + 1, options))
-            .join(" | ") ||
-            "unknown";
+        const parts = boundedParts(options.work, " | ", "", "");
+        for (const member of union) {
+            parts.add(renderSchema(member, defs, seen, depth + 1, options));
+        }
+        const rendered = parts.finish() || "unknown";
         return constrain(rendered);
     }
     if (Array.isArray(s.enum)) {
@@ -580,21 +708,50 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
         return constrain(rendered);
     }
     const type = s.type;
+    // A type list renders member by member, so `["object", "null"]` beside
+    // `properties` keeps both its shape and its null rather than the object alone.
+    if (ts && Array.isArray(type) && type.length > 0) {
+        const members = new Set();
+        const parts = boundedParts(options.work, " | ", "", "");
+        for (const item of type) {
+            options.work.visit();
+            if (typeof item !== "string")
+                continue;
+            let rendered = "null";
+            if (item !== "null") {
+                const member = Object.create(null);
+                for (const key of propertyNames(s, options.work)) {
+                    if (key !== "type")
+                        member[key] = s[key];
+                }
+                member.type = item;
+                rendered = renderSchema(member, defs, seen, depth, options);
+            }
+            if (members.has(rendered))
+                continue;
+            members.add(rendered);
+            parts.add(rendered);
+        }
+        return parts.length === 0 ? "unknown" : parts.finish();
+    }
     if (Array.isArray(s.prefixItems)) {
-        const parts = s.prefixItems.map((item) => renderSchema(item, defs, seen, depth + 1, options));
+        const parts = boundedParts(options.work, ", ", "[", "]");
+        for (const item of s.prefixItems) {
+            parts.add(renderSchema(item, defs, seen, depth + 1, options));
+        }
         if (s.items !== false) {
             const rest = s.items === undefined || s.items === true
                 ? "unknown"
                 : renderSchema(s.items, defs, seen, depth + 1, options);
-            parts.push(`...${grouped(rest)}[]`);
+            parts.add(`...${group(rest)}[]`);
         }
-        return `[${parts.join(", ")}]`;
+        return parts.finish();
     }
     if (type === "array" || s.items) {
         const items = s.items
             ? renderSchema(s.items, defs, seen, depth + 1, options)
             : "unknown";
-        return `${items}[]`;
+        return ts ? `${groupedType(items)}[]` : `${items}[]`;
     }
     if (type === "object" || s.properties) {
         const props = (s.properties ?? {});
@@ -606,10 +763,17 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
                 ...declaredKeys.filter((key) => !required.has(key)),
             ]
             : declaredKeys;
-        if (keys.length === 0)
-            return "{}";
-        return `{ ${keys
-            .map((key) => {
+        const additional = s.additionalProperties;
+        const index = ts && additional !== null && typeof additional === "object"
+            ? renderSchema(additional, defs, seen, depth + 1, options)
+            : undefined;
+        if (keys.length === 0 && index === undefined) {
+            // In TypeScript `{}` reads as "empty"; an object with no declared
+            // properties is an open map unless it closes itself explicitly.
+            return ts && additional !== false ? "Record<string, unknown>" : "{}";
+        }
+        const parts = boundedParts(options.work, ts ? "; " : ", ", "{ ", " }");
+        for (const key of keys) {
             const optional = required.has(key) ? "" : "?";
             const rendered = renderSchema(props[key], defs, seen, depth + 1, options);
             const description = props[key]?.description;
@@ -617,27 +781,40 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
                 options.work.text(description);
             }
             options.work.text(key);
+            if (ts) {
+                const doc = options.propertyDescriptions && typeof description === "string" &&
+                    description.trim()
+                    ? `/** ${typescriptDoc(description)} */ `
+                    : "";
+                parts.add(`${doc}${typescriptKey(key)}${optional}: ${rendered}`);
+                continue;
+            }
             const comment = options.propertyDescriptions && typeof description === "string"
                 ? ` // ${description}`
                 : "";
-            return `${key}${optional}: ${rendered}${comment}`;
-        })
-            .join(", ")} }`;
+            parts.add(`${key}${optional}: ${rendered}${comment}`);
+        }
+        if (index !== undefined)
+            parts.add(`[key: string]: ${index}`);
+        return parts.finish();
     }
     if (typeof type === "string") {
-        return constrain(options.work.text(type));
+        const text = options.work.text(type);
+        return constrain(ts ? typescriptPrimitive(text) : text);
     }
     if (Array.isArray(type)) {
-        const rendered = type.map((item) => {
+        const parts = boundedParts(options.work, " | ", "", "");
+        for (const item of type) {
             options.work.visit();
-            return options.work.text(String(item));
-        }).join(" | ");
+            parts.add(options.work.text(String(item)));
+        }
+        const rendered = parts.finish();
         return constrain(rendered);
     }
     if (options.renderConstraints && constraintEntries(s).length > 0) {
         return renderConstraints("unknown", s, options.constraintByteLimit, options.onConstraintTruncated);
     }
-    return options.work.json(schema);
+    return ts ? "unknown" : options.work.json(schema);
 }
 const compactSchemas = new WeakMap();
 function resolveDefinition(schema, name) {
@@ -713,10 +890,58 @@ export function compactDiscoverySchema(schema) {
     compactDiscoverySchemas.set(schema, result);
     return result;
 }
-function boundedCompactSchema(schema, description) {
+const typescriptDiscoveryTypes = new WeakMap();
+const typescriptDescriptionTypes = new WeakMap();
+/**
+ * One schema as a TypeScript type, under exactly the compact budgets: search
+ * drops prose and orders required keys first within 1,024 bytes, describe
+ * keeps prose as JSDoc within 8,192, and both share the 2,000-visit walk.
+ */
+function typescriptType(schema, description) {
+    const cache = description ? typescriptDescriptionTypes : typescriptDiscoveryTypes;
+    const cached = cache.get(schema);
+    if (cached)
+        return cached;
+    const result = boundedCompactSchema(schema, description, true);
+    cache.set(schema, result);
+    return result;
+}
+/** Marks runtime evidence inside the signature itself, not only beside it. */
+const OBSERVED_OUTPUT_MARKER = "/* observed, not declared */ ";
+/**
+ * Render a tool as the function `connecta.call(address, args)` resolves to,
+ * for an agent to read — never to execute: code mode still runs JavaScript.
+ *
+ * The input half comes from the declared input schema. The output half is the
+ * declared output schema, else a passively observed shape carrying a leading
+ * marker (runtime evidence is never presented as a contract), else `unknown`.
+ * A zero-field input renders as the optional `args?: {}` that call accepts:
+ * an MCP tool with no parameters rarely closes its schema, and reading its
+ * open `Record<string, unknown>` as "pass anything" would invite guessing.
+ */
+export function typescriptSignature(input, output, options) {
+    const renderedInput = typescriptType(input, options.description);
+    const renderedOutput = output
+        ? typescriptType(output, options.description)
+        : undefined;
+    const args = renderedInput.text === "{}" ||
+        renderedInput.text === "Record<string, unknown>"
+        ? "args?: {}"
+        : `args: ${renderedInput.text}`;
+    const result = renderedOutput
+        ? `${options.observed ? OBSERVED_OUTPUT_MARKER : ""}${renderedOutput.text}`
+        : "unknown";
+    return {
+        text: `(${args}) => Promise<${result}>`,
+        inputTruncated: renderedInput.truncated,
+        outputTruncated: renderedOutput?.truncated === true,
+    };
+}
+function boundedCompactSchema(schema, description, typescript = false) {
     const work = new SchemaWork(description ? MAX_COMPACT_DESCRIPTION_SCHEMA_BYTES : MAX_COMPACT_DISCOVERY_SCHEMA_BYTES);
     const options = {
         work,
+        typescript,
         propertyDescriptions: description,
         requiredFirst: !description,
         enumByteLimit: description ? work.byteLimit : MAX_COMPACT_DISCOVERY_ENUM_BYTES,

package/dist/concurrency.js

@@ -1,30 +1,31 @@
+import { Effect } from "effect";
+import { runEdge } from "./runtime/run.js";
 const DEFAULT_DISCOVERY_CONCURRENCY = 4;
 export function resolveDiscoveryConcurrency(value) {
     return value !== undefined && Number.isInteger(value) && value > 0
         ? value
         : DEFAULT_DISCOVERY_CONCURRENCY;
 }
-/** Run `fn` over `items` with at most `limit` operations in flight. */
-export async function mapSettledWithConcurrency(items, limit, fn) {
-    const settled = Array(items.length);
-    const remaining = items.entries();
-    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
-        for (;;) {
-            const next = remaining.next();
-            if (next.done)
-                return;
-            const [index, item] = next.value;
-            try {
-                settled[index] = {
-                    status: "fulfilled",
-                    value: await fn(item, index),
-                };
-            }
-            catch (reason) {
-                settled[index] = { status: "rejected", reason };
-            }
-        }
-    });
-    await Promise.all(workers);
-    return settled;
+/**
+ * Run `fn` over `items` with at most `limit` operations in flight, settling
+ * every one: a rejection lands in its slot instead of cancelling the rest.
+ * Results keep input order whatever order the work finishes in. A limit below
+ * one runs the items one at a time.
+ */
+export function mapSettledWithConcurrency(items, limit, fn) {
+    return runEdge(Effect.forEach(items, (item, index) => Effect.tryPromise({
+        // Promise.resolve keeps a non-promise return from `fn` working, as
+        // `await` did; a synchronous throw is caught either way.
+        try: () => Promise.resolve(fn(item, index)),
+        catch: (reason) => reason,
+    }).pipe(Effect.match({
+        onSuccess: (value) => ({
+            status: "fulfilled",
+            value,
+        }),
+        onFailure: (reason) => ({
+            status: "rejected",
+            reason,
+        }),
+    })), { concurrency: limit >= 1 ? Math.floor(limit) : 1 }));
 }

package/dist/connector-scope.js

@@ -1,19 +1,5 @@
-import { sleep } from "./timeout.js";
-/** Enough for local transport abort/close without letting cleanup own latency. */
-const CONNECTOR_SCOPE_CLOSE_BUDGET_MS = 100;
-/**
- * Bound on cleanup continued after the caller-facing window expires.
- *
- * `remoteMcp` spends at most one second asking the downstream to terminate its
- * session, leaving another second for the local close. Custom hooks still get a
- * finite background window: handing a never-settling promise to a Worker's
- * `waitUntil` would otherwise keep the invocation alive until the platform cap.
- */
-const CONNECTOR_SCOPE_DEFER_BUDGET_MS = 2_000;
-/** Resolve when `work` settles or `budgetMs` expires; never reject. */
-function waitAtMost(work, budgetMs) {
-    return Promise.race([work, sleep(budgetMs)]).then(() => { });
-}
+import { closeScope } from "./runtime/connector-scope.js";
+import { runEdge } from "./runtime/run.js";
 /**
  * Tell a connector that a scope owned by the core has ended.
  *
@@ -25,25 +11,8 @@ function waitAtMost(work, budgetMs) {
  * window. Callers own the at-most-once guarantee and must not use the scope
  * again after this returns.
  */
-export async function closeConnectorScope(connector, ctx, defer) {
-    try {
-        const closing = connector.closeScope?.(ctx);
-        if (!closing)
-            return;
-        // Attach both handlers before either timer can win, so a late rejection is
-        // consumed rather than becoming an unhandled rejection.
-        const settled = closing.then(() => { }, () => { });
-        if (defer) {
-            try {
-                defer(waitAtMost(settled, CONNECTOR_SCOPE_DEFER_BUDGET_MS));
-            }
-            catch {
-                // A runtime hook is best-effort too; the caller cap still applies.
-            }
-        }
-        await waitAtMost(settled, CONNECTOR_SCOPE_CLOSE_BUDGET_MS);
-    }
-    catch {
-        // The scope is over whether or not the connector managed to clean it up.
-    }
+export function closeConnectorScope(connector, ctx, defer) {
+    // The Promise face of closeScope (src/runtime/connector-scope.ts), which
+    // owns the budgets; an Effect caller registers it as a Scope finalizer.
+    return runEdge(closeScope(connector, ctx, defer));
 }

package/dist/connectors/api.d.ts

@@ -52,9 +52,9 @@ export interface ApiOptions {
      * discovery metadata. See `Connector.usageGuide`.
      */
     usageGuide?: string | ConnectorUsageGuide;
-    /** Optional operator-managed credential exposed through ctx.credential and /credentials. */
+    /** Optional operator-managed credential exposed through ctx.credential and the connection in the operator UI. */
     credential?: ConnectorCredentialConfig;
-    /** Optional validation behind /credentials' Test action. */
+    /** Optional validation behind the connection's Test action in the operator UI. */
     testCredential?: (value: string, ctx: ConnectorContext) => Promise<CredentialTestResult>;
     /** Optional validation for named multi-field credentials. */
     testCredentials?: (values: ConnectorCredentialValues, ctx: ConnectorContext) => Promise<CredentialTestResult>;

package/dist/connectors/remote-mcp.d.ts

@@ -2,8 +2,8 @@ import type { FetchLike, Transport } from "@modelcontextprotocol/client";
 import { ConnectorCallError } from "../errors.js";
 import type { Connector, ConnectorCallAdmissionPolicy, ConnectorContext, ConnectorCredentialConfig, ConnectorUsageGuide, Logger } from "../types.js";
 /**
- * A static downstream credential the operator supplies at `/credentials`
- * rather than the deployment baking into its source.
+ * A static downstream credential supplied through the connection in the
+ * operator UI rather than baked into deployment source.
  *
  * The connector, its endpoint, and the credential *slot* stay declared in
  * code; only the secret arrives through the operator route, exactly as for
@@ -15,8 +15,8 @@ import type { Connector, ConnectorCallAdmissionPolicy, ConnectorContext, Connect
 interface RemoteMcpCredentialAuth {
     type: "credential";
     /**
-     * Operator-facing slot description rendered on `/credentials`. Defaults to
-     * `{ label: "API key" }`; a maintained provider passes the name the provider
+     * Slot description rendered in the connection in the operator UI. Defaults
+     * to `{ label: "API key" }`; a maintained provider passes the name the provider
      * itself uses. Named `fields` are refused — this shape reads the reserved
      * `value` field only.
      */
@@ -122,7 +122,8 @@ export declare class RemoteMcpRedirectError extends ConnectorCallError {
  * Wrap fetch with explicit, bounded redirect handling.
  *
  * The starting URL of each fetch call is trusted by its caller (the configured
- * MCP endpoint, or an OAuth URL discovered by the pinned SDK). Only Location
+ * MCP endpoint, or an OAuth URL the pinned SDK discovered and
+ * `learnedUrlSafeFetch` already admitted). Only Location
  * values are policy-controlled here. No rejected target is ever fetched, so
  * arbitrary static header names receive the same protection as Authorization.
  */