@zackbart/connecta 0.34.1 → 0.35.0

package/dist/catalog.js

@@ -155,9 +155,13 @@ const CONVERSATIONAL_QUERY_WORDS = new Set([
  * search into an unfiltered catalog browse.
  */
 export function lexicalSearchQuery(query) {
+    return lexicalSearchContent(query) || query;
+}
+/** Normalized content only; empty means every query word was framing. */
+export function lexicalSearchContent(query) {
     const terms = normalized(query).split(/\s+/).filter(Boolean);
     const contentTerms = terms.filter((term) => !CONVERSATIONAL_QUERY_WORDS.has(term));
-    return contentTerms.length > 0 ? contentTerms.join(" ") : query;
+    return contentTerms.join(" ");
 }
 const searchIndexes = new WeakMap();
 function indexFor(tools) {

package/dist/concurrency.js

@@ -1,30 +1,5 @@
 import { CONFIG_DEFAULTS } from "./config-defaults.js";
-import { Effect } from "effect";
-import { runEdge } from "./runtime/run.js";
 const DEFAULT_DISCOVERY_CONCURRENCY = CONFIG_DEFAULTS.discovery.concurrency;
 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, 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/config-defaults.d.ts

@@ -28,6 +28,7 @@ export declare const CONFIG_DEFAULTS: {
             readonly queueTimeoutMs: 5000;
             readonly retryAfterMs: 1000;
             readonly maxDurationMs: 300000;
+            readonly maxBodyBytes: number;
         };
         readonly code: {
             readonly concurrency: 2;

package/dist/config-defaults.js

@@ -35,6 +35,7 @@ export const CONFIG_DEFAULTS = {
             queueTimeoutMs: 5_000,
             retryAfterMs: 1_000,
             maxDurationMs: 300_000,
+            maxBodyBytes: 4 * 1024 * 1024,
         },
         code: {
             concurrency: 2,

package/dist/config-schema.d.ts

@@ -34,6 +34,8 @@ interface Variants {
     readonly key: readonly string[];
     readonly cases: Readonly<Record<string, Shape>>;
     readonly otherwise?: string;
+    /** Migration guards that throw rather than construct; omit them from valid choices. */
+    readonly rejected?: readonly string[];
 }
 type InputOf<F> = F extends Field<infer In, unknown, boolean> ? In : never;
 type OutputOf<F> = F extends Field<unknown, infer Out, boolean> ? Out : never;
@@ -129,7 +131,7 @@ export declare function instance<F extends AnyField>(field: F): F & {
  * its path and the valid values, so no union falls through to "no case". Only
  * the walk reads variants; the factory validates the remaining values itself.
  */
-export declare function variants(key: string | readonly string[], cases: Readonly<Record<string, Shape>>, otherwise?: string): Field<unknown, unknown, true>;
+export declare function variants(key: string | readonly string[], cases: Readonly<Record<string, Shape>>, otherwise?: string, rejected?: readonly string[]): Field<unknown, unknown, true>;
 /**
  * A closed object for the unknown-key walk only: each named key may hold
  * anything, which its factory validates. For the options of a built-in

package/dist/config-schema.js

@@ -11,10 +11,12 @@
 // Deliberately small. Opaque fields (connectors, modules, functions) are
 // checked by identity or shape and passed through untouched, never cloned, so
 // a private-field receiver or a frozen object reaches core as configured.
+import { keepErrorName } from "./redaction-identity.js";
 /** A structural configuration mistake, thrown before construction does work. */
 export class ConfigError extends TypeError {
     name = "ConfigError";
 }
+keepErrorName(ConfigError, "ConfigError");
 function fail(message) {
     throw new ConfigError(message);
 }
@@ -192,13 +194,18 @@ export function instance(field) {
  * its path and the valid values, so no union falls through to "no case". Only
  * the walk reads variants; the factory validates the remaining values itself.
  */
-export function variants(key, cases, otherwise) {
+export function variants(key, cases, otherwise, rejected) {
     const path = typeof key === "string" ? [key] : [...key];
     if (path.length === 0)
         throw new Error("variants() requires a discriminant key.");
     return {
         ...opaque(),
-        variants: { key: path, cases, ...(otherwise !== undefined ? { otherwise } : {}) },
+        variants: {
+            key: path,
+            cases,
+            ...(otherwise !== undefined ? { otherwise } : {}),
+            ...(rejected ? { rejected } : {}),
+        },
     };
 }
 /**
@@ -233,7 +240,9 @@ export function assertKnownOptions(value, path, field) {
     if (read.unknown.length === 0)
         return read.value;
     return fail(`Unknown option${read.unknown.length === 1 ? "" : "s"}: ${read.unknown.join(", ")}. ` +
-        "Check the spelling against the factory's options type.");
+        (read.unknown.some((key) => key.endsWith(".classify"))
+            ? "classify was removed; use ConnectaConfig.classification."
+            : "Check the spelling against the factory's options type."));
 }
 /**
  * Own property descriptors, read without invoking any accessor. A config
@@ -317,6 +326,7 @@ function inspectRecord(value, path, field) {
 function selectShape(inspected, path, variants) {
     const at = `${path}.${variants.key.join(".")}`;
     const valid = Object.keys(variants.cases)
+        .filter((name) => !variants.rejected?.includes(name))
         .map((name) => JSON.stringify(name))
         .join(", ");
     // Walk the key path one plain object at a time, reading descriptors only.

package/dist/config.d.ts

@@ -90,6 +90,8 @@ declare const codeAdmission: {
     retryAfterMs: import("./config-schema.js").Field<number, number, true>;
 };
 declare const requestAdmission: {
+    /** Authenticated MCP body limit in bytes, checked while reading. Default 4 MiB. */
+    maxBodyBytes: import("./config-schema.js").Field<number, number, true>;
     /** Hard lifetime of an admitted /mcp request. Default 300,000 ms. */
     maxDurationMs: import("./config-schema.js").Field<number, number, true>;
     /** Simultaneous work admitted to this pool. */
@@ -107,12 +109,14 @@ declare const admission: {
      * 5-second maximum wait.
      */
     requests: import("./config-schema.js").Field<{
+        maxBodyBytes?: number | undefined;
         maxDurationMs?: number | undefined;
         concurrency?: number | undefined;
         maxQueueSize?: number | undefined;
         queueTimeoutMs?: number | undefined;
         retryAfterMs?: number | undefined;
     }, {
+        readonly maxBodyBytes: number;
         readonly maxDurationMs: number;
         readonly concurrency: number;
         readonly maxQueueSize: number;
@@ -120,6 +124,8 @@ declare const admission: {
         readonly retryAfterMs: number;
     }, true> & {
         readonly shape: {
+            /** Authenticated MCP body limit in bytes, checked while reading. Default 4 MiB. */
+            maxBodyBytes: import("./config-schema.js").Field<number, number, true>;
             /** Hard lifetime of an admitted /mcp request. Default 300,000 ms. */
             maxDurationMs: import("./config-schema.js").Field<number, number, true>;
             /** Simultaneous work admitted to this pool. */
@@ -194,6 +200,19 @@ declare const pool: {
      * `/mcp` never shows it.
      */
     description: import("./config-schema.js").Field<string, string | undefined, true>;
+    /**
+     * The tools this pool's endpoints list. `"meta"`, the default, is the six
+     * meta-tools. `"native"` lists each downstream tool directly, named
+     * `<connector>__<tool>` and annotated from its classification, for clients
+     * that run their own tool search; calls take the same invocation path.
+     */
+    surface: import("./config-schema.js").Field<"native" | "meta", "native" | "meta" | undefined, true>;
+    /**
+     * `false` drops `execute_code` from a native pool and lists `read_result`
+     * for paging instead. Only valid with `surface: "native"`: the meta surface
+     * always includes it.
+     */
+    executeCode: import("./config-schema.js").Field<boolean, boolean | undefined, true>;
 };
 declare const connectaConfig: {
     connectors: import("./config-schema.js").Field<Connector[], readonly Connector[], false>;
@@ -201,13 +220,16 @@ declare const connectaConfig: {
     auth: import("./config-schema.js").Field<InboundAuth | InboundAuth[], readonly InboundAuth[], true>;
     /**
      * Agents, declared by name: lowercase letters, digits, `_` and `-`, each
-     * unique. Each has one `cta_` token slot that operators issue, rotate, and
+     * unique. With `accessTokens`, each has one `cta_` slot operators issue, rotate, and
      * revoke; nothing outside code adds, renames, or rebinds an agent. Removing
-     * a name stops its token on the next request. Requires `accessTokens`.
+     * a name stops its credentials on the next request. A string name requires
+     * `accessTokens`; `{ name, vercel: { team, project, environments? } }` also
+     * accepts Vercel OIDC. Requires an immutable team_ ID; prefer a prj_ ID for the project. Environments
+     * default to production. Both credential types may coexist.
      * An admitted agent carries `identity.agent` and has no principal, so
      * personal connectors are absent for it. Defaults to none.
      */
-    agents: import("./config-schema.js").Field<readonly string[], readonly string[], true>;
+    agents: import("./config-schema.js").Field<readonly import("./agent-config.js").AgentConfig[], readonly import("./agent-config.js").ResolvedAgent[], true>;
     /**
      * The people who may use plain `/mcp`, which serves the whole catalog with
      * the deployment's `readOnly`, and who administer the deployment. Same
@@ -220,6 +242,8 @@ declare const connectaConfig: {
         readOnly?: boolean | undefined;
         owner?: string | undefined;
         description?: string | undefined;
+        surface?: "native" | "meta" | undefined;
+        executeCode?: boolean | undefined;
         tools: readonly string[];
         members: readonly MemberRef[];
     }>, Readonly<Record<string, {
@@ -228,9 +252,12 @@ declare const connectaConfig: {
         readonly members: readonly MemberRef[];
         readonly owner: string | undefined;
         readonly description: string | undefined;
+        readonly surface: "native" | "meta" | undefined;
+        readonly executeCode: boolean | undefined;
     }>> | undefined, true>;
-    /** Exact connector id -> tool name -> verdict. Unknown names fail at catalog publication. */
-    classification: import("./config-schema.js").Field<Record<string, Record<string, "read" | "write">>, Readonly<Record<string, Readonly<Record<string, "read" | "write">>>> | undefined, true>;
+    /** Exact connector id -> tool name -> verdict. Hidden tools cannot be discovered or called.
+     * Unknown static names fail construction; absent runtime names stay dormant and are reported. */
+    classification: import("./config-schema.js").Field<Record<string, Record<string, "read" | "write" | "hidden">>, Readonly<Record<string, Readonly<Record<string, "read" | "write" | "hidden">>>> | undefined, true>;
     /**
      * The deployment's one store: `d1Storage(env.CONNECTA_DB)` from
      * `@zackbart/connecta/d1` on Workers, `sqliteStorage(path)` from
@@ -391,6 +418,7 @@ declare const connectaConfig: {
      */
     admission: import("./config-schema.js").Field<{
         requests?: {
+            maxBodyBytes?: number | undefined;
             maxDurationMs?: number | undefined;
             concurrency?: number | undefined;
             maxQueueSize?: number | undefined;
@@ -405,6 +433,7 @@ declare const connectaConfig: {
         } | undefined;
     }, {
         readonly requests: {
+            readonly maxBodyBytes: number;
             readonly maxDurationMs: number;
             readonly concurrency: number;
             readonly maxQueueSize: number;
@@ -424,12 +453,14 @@ declare const connectaConfig: {
              * 5-second maximum wait.
              */
             requests: import("./config-schema.js").Field<{
+                maxBodyBytes?: number | undefined;
                 maxDurationMs?: number | undefined;
                 concurrency?: number | undefined;
                 maxQueueSize?: number | undefined;
                 queueTimeoutMs?: number | undefined;
                 retryAfterMs?: number | undefined;
             }, {
+                readonly maxBodyBytes: number;
                 readonly maxDurationMs: number;
                 readonly concurrency: number;
                 readonly maxQueueSize: number;
@@ -437,6 +468,8 @@ declare const connectaConfig: {
                 readonly retryAfterMs: number;
             }, true> & {
                 readonly shape: {
+                    /** Authenticated MCP body limit in bytes, checked while reading. Default 4 MiB. */
+                    maxBodyBytes: import("./config-schema.js").Field<number, number, true>;
                     /** Hard lifetime of an admitted /mcp request. Default 300,000 ms. */
                     maxDurationMs: import("./config-schema.js").Field<number, number, true>;
                     /** Simultaneous work admitted to this pool. */
@@ -566,7 +599,8 @@ type Parsed = ConfigOutput<typeof connectaConfig>;
  * The configuration a Connecta runs with: validated, every default applied,
  * auth ordered, and `serverInfo` named and versioned. Built once by createConnecta; nothing downstream re-derives it.
  */
-export interface ResolvedConfig extends Omit<Parsed, "serverInfo"> {
+export interface ResolvedConfig extends Omit<Parsed, "serverInfo" | "agents"> {
+    readonly agents: readonly string[];
     /** `serverInfo` with its name and version defaults applied. */
     readonly serverInfo: {
         readonly name: string;

package/dist/config.js

@@ -1,19 +1,8 @@
-// ConnectaConfig as one schema.
-//
-// The schema below is the canonical record of the configuration surface. It
-// produces the TypeScript type a deployment writes (`ConnectaConfig`), the
-// unknown-key rejection createConnecta runs before reading anything, every
-// default (src/config-defaults.ts), and one validation policy: a present value
-// that is wrong throws with its path at construction (INV-11). Each field's
-// default and operator-facing meaning belongs in its doc comment here, where a
-// deployment author reads it from the editor.
-//
-// `resolveConfig` turns an accepted config into the `ResolvedConfig` core
-// reads, with defaults applied once, so no later layer re-derives a value or
-// re-plumbs a field.
+import { registerAgentDescriptions } from "./agent-description.js";
 import { CONFIG_DEFAULTS as D } from "./config-defaults.js";
 import { array, ConfigError, object, opaque, record, required, seconds, readPlain, text, whole, } from "./config-schema.js";
-import { assertAgentNames } from "./agent-identity.js";
+import { agentConfig } from "./agent-config.js";
+import { vercelAgentAuth } from "./auth/vercel-agent.js";
 import { assertExecutor } from "./executor-contract.js";
 import { memoryStorage } from "./storage/memory.js";
 import { CONNECTA_VERSION } from "./version.js";
@@ -156,6 +145,8 @@ function admissionPool(defaults) {
 const codeAdmission = admissionPool(D.admission.code);
 const requestAdmission = {
     ...admissionPool(D.admission.requests),
+    /** Authenticated MCP body limit in bytes, checked while reading. Default 4 MiB. */
+    maxBodyBytes: whole({ min: 1, default: D.admission.requests.maxBodyBytes }),
     /** Hard lifetime of an admitted /mcp request. Default 300,000 ms. */
     maxDurationMs: whole({
         min: 1,
@@ -261,6 +252,24 @@ const pool = {
      * `/mcp` never shows it.
      */
     description: opaque({ check: assertPoolDescription }),
+    /**
+     * The tools this pool's endpoints list. `"meta"`, the default, is the six
+     * meta-tools. `"native"` lists each downstream tool directly, named
+     * `<connector>__<tool>` and annotated from its classification, for clients
+     * that run their own tool search; calls take the same invocation path.
+     */
+    surface: opaque({
+        check: (value, path) => {
+            if (value !== "meta" && value !== "native")
+                throw new ConfigError(`${path} must be "meta" or "native".`);
+        },
+    }),
+    /**
+     * `false` drops `execute_code` from a native pool and lists `read_result`
+     * for paging instead. Only valid with `surface: "native"`: the meta surface
+     * always includes it.
+     */
+    executeCode: opaque({ check: assertFlag }),
 };
 const icon = {
     src: required(text()),
@@ -315,16 +324,16 @@ const connectaConfig = {
     }),
     /**
      * Agents, declared by name: lowercase letters, digits, `_` and `-`, each
-     * unique. Each has one `cta_` token slot that operators issue, rotate, and
+     * unique. With `accessTokens`, each has one `cta_` slot operators issue, rotate, and
      * revoke; nothing outside code adds, renames, or rebinds an agent. Removing
-     * a name stops its token on the next request. Requires `accessTokens`.
+     * a name stops its credentials on the next request. A string name requires
+     * `accessTokens`; `{ name, vercel: { team, project, environments? } }` also
+     * accepts Vercel OIDC. Requires an immutable team_ ID; prefer a prj_ ID for the project. Environments
+     * default to production. Both credential types may coexist.
      * An admitted agent carries `identity.agent` and has no principal, so
      * personal connectors are absent for it. Defaults to none.
      */
-    agents: opaque({
-        check: (value, path) => assertAgentNames(value, path),
-        resolve: (value) => Object.freeze([...(value ?? [])]),
-    }),
+    agents: agentConfig,
     /**
      * The people who may use plain `/mcp`, which serves the whole catalog with
      * the deployment's `readOnly`, and who administer the deployment. Same
@@ -334,11 +343,12 @@ const connectaConfig = {
     maintainers: opaque({ check: assertMemberList }),
     /** Named tool pools, each served at `/mcp/<name>` to its members only. */
     pools: record(object(pool)),
-    /** Exact connector id -> tool name -> verdict. Unknown names fail at catalog publication. */
+    /** Exact connector id -> tool name -> verdict. Hidden tools cannot be discovered or called.
+     * Unknown static names fail construction; absent runtime names stay dormant and are reported. */
     classification: record(record(opaque({
         check: (value, path) => {
-            if (value !== "read" && value !== "write") {
-                throw new ConfigError(`${path} must be "read" or "write".`);
+            if (value !== "read" && value !== "write" && value !== "hidden") {
+                throw new ConfigError(`${path} must be "read", "write", or "hidden".`);
             }
         },
     }))),
@@ -566,7 +576,7 @@ function assertCoherent(config) {
         config.discovery.catalogMaxTtlSeconds > 86_400) {
         throw new ConfigError("ConnectaConfig.discovery requires catalogMinTtlSeconds <= catalogMaxTtlSeconds <= 86400.");
     }
-    if (config.agents.length > 0 && !config.accessTokens) {
+    if (config.agents.some((agent) => !agent.vercel) && !config.accessTokens) {
         throw new ConfigError("ConnectaConfig.agents needs accessTokens: accessTokens(storage) from @zackbart/connecta/auth/access-tokens " +
             "holds each agent's token slot.");
     }
@@ -598,14 +608,18 @@ export function readConfig(config) {
         version: parsed.serverInfo.version ?? CONNECTA_VERSION,
     };
     // The token module admits exactly the agents this configuration declares.
-    const accessTokens = parsed.accessTokens?.forAgents(parsed.agents);
+    const agents = Object.freeze(parsed.agents.map((agent) => agent.name));
+    const accessTokens = parsed.accessTokens?.forAgents(agents);
+    const vercel = vercelAgentAuth(parsed.agents, parsed.logger);
     const resolved = Object.freeze({
         ...parsed,
+        agents,
         accessTokens,
         // A managed-token module contributes one more provider, ordered with the rest.
-        auth: accessTokens ? normalizeAuth([accessTokens.auth, ...parsed.auth]) : parsed.auth,
+        auth: normalizeAuth([...(accessTokens ? [accessTokens.auth] : []), ...(vercel ? [vercel] : []), ...parsed.auth]),
         serverInfo: Object.freeze(info),
     });
+    registerAgentDescriptions(resolved, parsed.agents, accessTokens !== undefined);
     return { input, resolved };
 }
 /**

package/dist/connector-caller.d.ts

@@ -18,5 +18,9 @@ export interface ConnectorCaller {
      */
     poolOwner?: string;
 }
+/** Mark a connector whose downstream identity depends on the admitted caller. */
+export declare function tagCallerIdentity<C extends object>(connector: C): C;
+/** Provider construction may wrap a connector in an inheriting object. */
+export declare function usesCallerIdentity(connector: object): boolean;
 export declare function attachCaller(ctx: ConnectorContext, caller: ConnectorCaller | undefined): ConnectorContext;
 export declare function callerOf(ctx: ConnectorContext): ConnectorCaller | undefined;

package/dist/connector-caller.js

@@ -19,12 +19,25 @@
 // through an inbound-auth provider configured to read one (a bearer's asserted
 // principal). A context no request admitted, such as an operator probe, has no caller, and a delegated provider fails closed on it,
 // as it does on the anonymous caller an open deployment admits.
-const callers = new WeakMap();
+import { Caller, serviceFor, setViewService } from "./runtime/call.js";
+const callerIdentities = new WeakSet();
+/** Mark a connector whose downstream identity depends on the admitted caller. */
+export function tagCallerIdentity(connector) {
+    callerIdentities.add(connector);
+    return connector;
+}
+/** Provider construction may wrap a connector in an inheriting object. */
+export function usesCallerIdentity(connector) {
+    for (let current = connector; current; current = Object.getPrototypeOf(current)) {
+        if (callerIdentities.has(current))
+            return true;
+    }
+    return false;
+}
 export function attachCaller(ctx, caller) {
-    if (caller)
-        callers.set(ctx, caller);
+    setViewService(ctx, Caller, caller);
     return ctx;
 }
 export function callerOf(ctx) {
-    return callers.get(ctx);
+    return serviceFor(ctx, Caller);
 }

package/dist/connectors/api-connector.d.ts

@@ -85,9 +85,12 @@ export interface ApiOAuthAccess {
     /**
      * `fetch` with the calling owner's access token as `Authorization: Bearer`.
      * Only to `apiOrigins`; redirects are returned unfollowed. A 401 earns one
-     * coordinated refresh and one replay; a second 401, a refused refresh, or
-     * no grant at all throws `auth_required`, and an authorization-server
-     * outage throws a retryable `unavailable`.
+     * coordinated refresh. Only a positively read-classified GET/HEAD without
+     * method-override headers is sent once more; a write's never is, and the call fails with `connector_call_failed`
+     * whose outcome is unknown, so the agent checks the target before
+     * repeating it. A second 401, a refused refresh, or no grant at all throws
+     * `auth_required`, and an authorization-server outage throws a retryable
+     * `unavailable`.
      */
     fetch(input: string | URL, init?: RequestInit): Promise<Response>;
 }
@@ -209,11 +212,11 @@ export declare const API_OPTIONS: import("../config-schema.js").Field<unknown, u
         };
         tools: import("../config-schema.js").Field<unknown[], readonly unknown[] | undefined, true>;
         title: import("../config-schema.js").Field<unknown, unknown, true>;
+        authScope: import("../config-schema.js").Field<unknown, unknown, true>;
+        maxResultBytes: import("../config-schema.js").Field<unknown, unknown, true>;
         description: import("../config-schema.js").Field<unknown, unknown, true>;
         testCredential: import("../config-schema.js").Field<unknown, unknown, true>;
         testCredentials: import("../config-schema.js").Field<unknown, unknown, true>;
-        authScope: import("../config-schema.js").Field<unknown, unknown, true>;
-        maxResultBytes: import("../config-schema.js").Field<unknown, unknown, true>;
         validateArgs: import("../config-schema.js").Field<unknown, unknown, true>;
     };
 };
@@ -234,8 +237,10 @@ export interface ApiOAuthHooks {
     consumeAuthError(ctx: ConnectorContext): Promise<void>;
     /** Requires callbackParams with a nonempty state, including without PKCE. */
     finishAuth(code: string, ctx: ConnectorContext, callbackParams: URLSearchParams): Promise<void>;
-    /** The handler-facing accessor for one call's context. */
-    access(ctx: ConnectorContext): ApiOAuthAccess;
+    /** The handler-facing accessor for one call's context; a write's request is never resent. */
+    access(ctx: ConnectorContext, call: {
+        write: boolean;
+    }): ApiOAuthAccess;
 }
 /**
  * A static connector; every tool passes {@link checkToolContract} first.