@zackbart/connecta 0.24.4 → 0.26.0

package/dist/catalog.js

@@ -14,6 +14,12 @@ class SchemaWork {
     remaining = MAX_SCHEMA_WORK;
     truncated = false;
     refs = new Map();
+    /**
+     * Renderings whose top level is a bare `|` or `&`, recorded as the walk
+     * produces them. Compact carries raw keys and `//` prose, so unlike the
+     * TypeScript dialect its text cannot be rescanned for a top-level operator.
+     */
+    ungrouped = new Set();
     constructor(byteLimit = MAX_COMPACT_DISCOVERY_SCHEMA_BYTES) {
         this.byteLimit = byteLimit;
     }
@@ -35,11 +41,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();
@@ -417,8 +441,11 @@ function renderEnum(values, work, byteLimit, onTruncated) {
         const full = prefix.join(" | ");
         if (schemaEncoder.encode(full).length > limit)
             break;
-        if (index === values.length - 1)
+        if (index === values.length - 1) {
+            if (index > 0)
+                work.ungrouped.add(full);
             return full;
+        }
         const omitted = values.length - prefix.length;
         const candidate = `(${full} | ${marker(omitted)})`;
         if (schemaEncoder.encode(candidate).length <= limit)
@@ -481,20 +508,131 @@ 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;
+    const ungrouped = options.work.ungrouped;
+    // A `[]` suffix binds tighter than `|` and `&`, so an element rendered at
+    // operator level needs parentheses or it reads as its last member's array.
+    const element = (rendered) => ts
+        ? groupedType(rendered)
+        : ungrouped.has(rendered) ? `(${rendered})` : rendered;
+    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;
-    const constrain = (rendered) => options.renderConstraints
-        ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
-        : rendered;
+    // 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) => {
+        if (!options.renderConstraints)
+            return rendered;
+        const result = renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated);
+        // Constraints parenthesize a union before their comment but leave an
+        // intersection bare, and a comment does not group what precedes it.
+        if (ungrouped.has(rendered) && !result.startsWith(`(${rendered})`)) {
+            ungrouped.add(result);
+        }
+        return result;
+    };
     // Conditions cannot be expressed by a single static shape. Preserve the
     // base and send callers to the exact schema instead of hiding the rules.
     if (s.dependentSchemas !== undefined || s.if !== undefined ||
@@ -508,7 +646,10 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
         const rendered = declaresShape(base)
             ? renderSchema(base, defs, seen, depth, options)
             : "unknown";
-        return `${rendered} /* conditional */`;
+        const result = `${rendered} /* conditional */`;
+        if (ungrouped.has(rendered))
+            ungrouped.add(result);
+        return result;
     }
     // allOf composes rather than replaces: it is checked before every other
     // shape keyword, and renders the schema's own shape alongside its members instead
@@ -524,29 +665,44 @@ 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(" & ");
+        const rendered = parts.finish();
+        if (parts.length > 1)
+            ungrouped.add(rendered);
+        return rendered;
     }
     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 +717,13 @@ 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";
+        if (parts.length > 1)
+            ungrouped.add(rendered);
         return constrain(rendered);
     }
     if (Array.isArray(s.enum)) {
@@ -580,21 +739,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(`...${element(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 `${element(items)}[]`;
     }
     if (type === "object" || s.properties) {
         const props = (s.properties ?? {});
@@ -606,10 +794,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 +812,42 @@ 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();
+        if (parts.length > 1)
+            ungrouped.add(rendered);
         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 +923,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,
@@ -734,6 +992,7 @@ function boundedCompactSchema(schema, description) {
         // are memoized only within each pass because their text includes constraints.
         if (error === schemaSizeExceeded && !description) {
             work.refs.clear();
+            work.ungrouped.clear();
             try {
                 return {
                     text: renderSchema(schema, schema, new Set(), 0, {

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-access.d.ts

@@ -9,20 +9,33 @@ export declare const POOL_NAME_RE: RegExp;
 /**
  * One derived view: which connectors, and for connectors granted by address
  * only, which tools. A connector absent from `toolAccess` is visible whole.
+ * `guardedToolAccess` is a subset of `toolAccess` checked against the loaded
+ * catalog each time tools are discovered or invoked.
  */
 export interface ConnectorAccess {
     connectorIds: "all" | readonly string[];
     toolAccess?: ToolAccess;
+    /** Exact tool grants that also require a current explicit read-only annotation. */
+    guardedToolAccess?: ToolAccess;
 }
+interface ReadOnlyToolGrant {
+    tool: string;
+    requireReadOnly: true;
+}
+export type ConnectorGrant = string | ReadOnlyToolGrant;
 /**
  * Normalize a grant list. A bare connector id grants every tool on that
  * connector; a `connector.tool` address grants one tool. Grants are additive,
  * so a bare id beside addresses for the same connector means the whole
- * connector. Anything else — an unknown shape, an empty tool name, a
- * non-string — throws, and the caller decides whether that is a construction
- * failure or a 403: a grant that cannot be parsed must never fail open.
+ * connector. Identity resolution can opt into `{ tool, requireReadOnly: true }`
+ * for a fixed address that also needs a current explicit read-only annotation;
+ * pool declarations remain strings. Anything else throws, and the caller
+ * decides whether that is a construction failure or a 403: a grant that
+ * cannot be parsed must never fail open.
  */
-export declare function parseConnectorAccess(value: unknown): ConnectorAccess;
+export declare function parseConnectorAccess(value: unknown, options?: {
+    allowReadOnly?: boolean;
+}): ConnectorAccess;
 /**
  * The view a pool endpoint serves: the pool's grants, never wider than the
  * identity's own. A connector or tool outside either side is gone; a
@@ -30,3 +43,4 @@ export declare function parseConnectorAccess(value: unknown): ConnectorAccess;
  * only narrow what the identity resolver already allowed.
  */
 export declare function intersectAccess(ceiling: ConnectorAccess, pool: ConnectorAccess): ConnectorAccess;
+export {};