@zackbart/connecta 0.31.0 → 0.33.0

package/dist/config.js

@@ -12,10 +12,12 @@
 // reads, with defaults applied once, so no later layer re-derives a value or
 // re-plumbs a field.
 import { CONFIG_DEFAULTS as D } from "./config-defaults.js";
-import { array, ConfigError, fn, object, opaque, record, required, seconds, readPlain, text, whole, } from "./config-schema.js";
+import { array, ConfigError, object, opaque, record, required, seconds, readPlain, text, whole, } from "./config-schema.js";
+import { assertAgentNames } from "./agent-identity.js";
 import { assertExecutor } from "./executor-contract.js";
 import { memoryStorage } from "./storage/memory.js";
 import { CONNECTA_VERSION } from "./version.js";
+import { isWorkspaceAddress } from "./workspace-address.js";
 const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const STORAGE_METHODS = ["get", "set", "delete", "list", "compareAndSet"];
 const hasMethods = (value, methods) => isObject(value) && methods.every((method) => typeof value[method] === "function");
@@ -134,7 +136,7 @@ const execute = {
      */
     watchdogMs: whole({ min: 1, default: D.execute.watchdogMs }),
     /**
-     * Trusted-pool writes one program may send, on top of the host-call
+     * Writes one program may send on a writable endpoint, on top of the host-call
      * budget every call already spends. Default 10.
      */
     maxWrites: whole({ min: 1, default: D.execute.maxWrites }),
@@ -175,37 +177,27 @@ const admission = {
      */
     code: object(codeAdmission),
 };
-const identity = {
+/** The choice every deployment makes explicitly while `trust` migrates (#820). */
+const READ_ONLY_REQUIRED = (path) => `${path} is required. Choose readOnly: true to refuse every write on /mcp, or readOnly: false to let ` +
+    "call_destructive_tool and programs write with MCP client approval. Pools inherit it unless they set their own.";
+function assertFlag(value, path) {
+    if (typeof value !== "boolean")
+        throw new ConfigError(`${path} must be true or false.`);
+}
+/** Shape only; each reference resolves against auth and agents in createConnecta. */
+function assertMemberList(value, path) {
+    if (!Array.isArray(value)) {
+        throw new ConfigError(`${path} must be an array of principal ids, { namespace, id }, or "agent:<name>".`);
+    }
+}
+const pool = {
     /**
-     * What this admitted identity may discover and call: `"all"`, or a list
-     * whose entries are connector ids (the whole connector) and `connector.tool`
-     * addresses (that tool only), or `{ tool: "connector.tool",
-     * requireReadOnly: true }` for an exact tool only while its loaded catalog
-     * explicitly classifies it read-only. Grants are additive: an unrestricted
-     * connector or address grant wins over the guarded form. An address naming
-     * a tool the catalog lacks is unreachable and warned once, never widened.
+     * Whether this pool's endpoint refuses every write: write tools are absent
+     * from search_tools, tool listings, and describe, and every write call is
+     * refused. Inherits the deployment's `readOnly` unless set here, in either
+     * direction.
      */
-    connectorAccess: fn(),
-    /** Global payload-free activity reads. Defaults to interactive humans. */
-    activityAccess: fn(),
-    /** Shared credential and OAuth administration. Defaults to none. */
-    credentialAdministration: fn(),
-    /** Client-token lifecycle management by interactive humans. Defaults to false. */
-    accessTokenManagement: fn(),
-    /** Connecting or changing the caller's personal account. Defaults to none. */
-    personalConnection: fn(),
-};
-const trust = () => opaque({
-    check: (value, path) => {
-        if (value !== "trusted" && value !== "read-only") {
-            throw new ConfigError(`${path} must be "trusted" or "read-only".`);
-        }
-    },
-    resolve: (value) => value ?? "read-only",
-});
-const pool = {
-    /** Programs may write only in trusted pools. Default read-only. */
-    trust: trust(),
+    readOnly: opaque({ check: assertFlag }),
     /** Connector ids and exact `connector.tool` addresses in this pool. */
     tools: required(opaque({
         check: (value, path) => {
@@ -215,11 +207,26 @@ const pool = {
         },
     })),
     /**
-     * Whether this admitted identity may open the pool. Denied by default:
-     * a pool with no grant serves nobody. A false return, a throw, and an
-     * undeclared pool name are the same 404.
+     * Who may open `/mcp/<name>`: principal ids in the namespace of the one
+     * interactive auth provider, `{ namespace, id }`, or `"agent:<name>"` for a
+     * declared agent. Required and non-empty; the pool serves exactly its
+     * `tools` to these members and the same 404 to everyone else.
+     */
+    members: required(opaque({ check: assertMemberList }), (path) => `${path} is required: list who may open this pool, as principal ids, { namespace, id }, or "agent:<name>".`),
+    /**
+     * The Google Workspace address agents in this pool act as, on a Workspace
+     * connector whose `subject` is a mapping function. Humans always act as
+     * themselves through that mapping, and a fixed `subject` address applies to
+     * everyone. Without an owner, an agent's Workspace calls fail
+     * `auth_required`.
      */
-    grant: fn(),
+    owner: opaque({
+        check: (value, path) => {
+            if (typeof value !== "string" || !isWorkspaceAddress(value.trim())) {
+                throw new ConfigError(`${path} must be a Google Workspace email address.`);
+            }
+        },
+    }),
 };
 const icon = {
     src: required(text()),
@@ -240,7 +247,7 @@ const connectaConfig = {
     connectors: required(array(opaque({
         check: (value, path) => {
             if (isObject(value) && Object.hasOwn(value, "approval")) {
-                throw new ConfigError(`${path}.approval was removed; configure pool trust instead.`);
+                throw new ConfigError(`${path}.approval was removed; the MCP client owns approval. Set readOnly: true to refuse writes.`);
             }
             if (!isObject(value) ||
                 typeof value.id !== "string" ||
@@ -272,12 +279,27 @@ const connectaConfig = {
         },
         resolve: (value) => normalizeAuth(value === undefined ? [] : Array.isArray(value) ? value : [value]),
     }),
-    /** Code-derived connection visibility and independent management permissions. */
-    identity: object(identity),
-    /** Named tool pools, each served at `/mcp/<name>` to identities its grant admits. */
+    /**
+     * Agents, declared by name: lowercase letters, digits, `_` and `-`, each
+     * unique. Each has one `cta_` token slot that 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`.
+     * 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 ?? [])]),
+    }),
+    /**
+     * The people who may use plain `/mcp`, which serves the whole catalog with
+     * the deployment's `readOnly`, and who administer the deployment. Same
+     * reference forms as pool `members`, people only. Required with inbound
+     * auth; a maintainer opens no pool unless listed among its members.
+     */
+    maintainers: opaque({ check: assertMemberList }),
+    /** Named tool pools, each served at `/mcp/<name>` to its members only. */
     pools: record(object(pool)),
-    /** Trust of the default /mcp endpoint. Default read-only. */
-    trust: trust(),
     /** Exact connector id -> tool name -> verdict. Unknown names fail at catalog publication. */
     classification: record(record(opaque({
         check: (value, path) => {
@@ -356,11 +378,11 @@ const connectaConfig = {
             }
         },
     }),
-    /** Optional managed client tokens, created by accessTokens() from /auth/access-tokens. */
+    /** Optional agent tokens for the declared `agents`, created by accessTokens() from /auth/access-tokens. */
     accessTokens: opaque({
         check: (value) => {
             const auth = isObject(value) ? value.auth : undefined;
-            if (!hasMethods(value, ["handle"]) ||
+            if (!hasMethods(value, ["handle", "slots", "forAgents"]) ||
                 !isObject(auth) ||
                 typeof auth.authorize !== "function" ||
                 auth.interactiveOperator) {
@@ -415,10 +437,59 @@ const connectaConfig = {
         '"@zackbart/connecta/quickjs" on Node, or ' +
         "workerExecutor({ loader: env.LOADER }) from " +
         '"@zackbart/connecta/worker" around DynamicWorkerExecutor on Workers.'),
+    /**
+     * Required. Whether the default /mcp endpoint refuses every write. `true`:
+     * write tools are absent from search_tools, tool listings, and describe,
+     * and call_tool, call_destructive_tool, and program writes are refused.
+     * `false`: call_destructive_tool and programs may write, and the MCP
+     * client owns approval. Pools inherit it unless they set their own. It has
+     * no default while deployments migrate from `trust` (#820).
+     */
+    readOnly: required(opaque({ check: assertFlag }), (path) => READ_ONLY_REQUIRED(path)),
 };
 const CONFIG = object(connectaConfig);
 /** Pause-only options #672 removed with `resume_execution`. */
 const RETIRED_PAUSE_OPTIONS = ["ConnectaConfig.execute.resumableWrites", "ConnectaConfig.execute.pausedRunTtlSeconds"];
+/** Access options pools replaced (#837, decisions/0006). */
+const isRetiredPoolGrant = (path) => /^ConnectaConfig\.pools\.[^.]+\.grant$/.test(path);
+/** Management resolvers maintainers and pool membership replaced (#837, decisions/0006). */
+const RETIRED_IDENTITY = [
+    ["credentialAdministration", "maintainers administer shared credentials and OAuth grants. List them in maintainers."],
+    [
+        "personalConnection",
+        "pool members connect and disconnect their own personal connectors in their pools, and maintainers their own. Add people to a pool's members.",
+    ],
+    [
+        "accessTokenManagement",
+        "maintainers issue, rotate, and revoke agent tokens from an interactive session. List them in maintainers.",
+    ],
+    ["activityAccess", "maintainers read activity; activity.readGate can still narrow it. List them in maintainers."],
+];
+/** `trust`, on the deployment or a pool, was replaced by `readOnly` (#820). */
+const isRetiredTrust = (path) => path === "ConnectaConfig.trust" || (path.startsWith("ConnectaConfig.pools.") && path.endsWith(".trust"));
+/**
+ * `identity` was removed whole (#837), so the walk reports only the section.
+ * Name each key it still holds, read by descriptor without running a getter
+ * or echoing a value, so a retired resolver's message names its replacement.
+ */
+function expandRetiredIdentity(config, paths) {
+    if (!paths.includes("ConnectaConfig.identity"))
+        return paths;
+    let keys = [];
+    try {
+        const descriptor = Reflect.getOwnPropertyDescriptor(config, "identity");
+        const value = descriptor && "value" in descriptor ? descriptor.value : undefined;
+        if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+            keys = Reflect.ownKeys(value).filter((key) => typeof key === "string");
+        }
+    }
+    catch {
+        keys = [];
+    }
+    if (keys.length === 0)
+        return paths;
+    return paths.flatMap((path) => path === "ConnectaConfig.identity" ? keys.map((key) => `ConnectaConfig.identity.${key}`) : [path]);
+}
 function rejectUnknownOptions(paths) {
     if (paths.length === 0)
         return;
@@ -431,10 +502,28 @@ function rejectUnknownOptions(paths) {
             ? "\nMove branding into ui: operatorUi({ branding }) from @zackbart/connecta/ui."
             : "") +
         (paths.includes("ConnectaConfig.execute.approval")
-            ? '\nexecute.approval was removed. Set trust: "trusted" on a pool to allow program writes; the default is read-only.'
+            ? "\nexecute.approval was removed. The MCP client owns approval; set readOnly: true on the deployment or a pool to refuse writes."
             : "") +
         (paths.some((path) => RETIRED_PAUSE_OPTIONS.includes(path))
-            ? "\nPrograms no longer pause at writes, so there is nothing to configure: read-only pools route writes through call_destructive_tool; trusted pools allow program writes (issue #672). Delete the option."
+            ? "\nPrograms no longer pause at writes, so there is nothing to configure: writable endpoints let programs and call_destructive_tool write; readOnly endpoints refuse every write (issue #672). Delete the option."
+            : "") +
+        (paths.includes("ConnectaConfig.identity.connectorAccess")
+            ? "\nidentity.connectorAccess was removed (#837): pools are the access model. List who may use plain /mcp in maintainers, and give each pool its tools and members. A guarded { tool, requireReadOnly: true } grant becomes a pool with readOnly: true."
+            : "") +
+        RETIRED_IDENTITY.filter(([key]) => paths.includes(`ConnectaConfig.identity.${key}`))
+            .map(([key, replacement]) => `\nidentity.${key} was removed (#837): ${replacement}`)
+            .join("") +
+        (paths.some((path) => path === "ConnectaConfig.identity" || path.startsWith("ConnectaConfig.identity."))
+            ? "\nThe identity section was removed (#837): maintainers and pool members decide access and management. Delete it."
+            : "") +
+        (paths.includes("ConnectaConfig.grant")
+            ? "\nThe top-level grant was removed (#837); list the people who may use plain /mcp in maintainers."
+            : "") +
+        (paths.some(isRetiredPoolGrant)
+            ? "\nPool grant was removed (#837); list who may open the pool in its members."
+            : "") +
+        (paths.some(isRetiredTrust)
+            ? '\ntrust was removed (#820); set readOnly, which every deployment now chooses explicitly. trust: "read-only" becomes readOnly: true, which now also refuses call_destructive_tool. trust: "trusted" becomes readOnly: false. A pool inherits the deployment readOnly unless it sets its own.'
             : ""));
 }
 /** Checks that span fields; each value is already individually valid. */
@@ -443,6 +532,10 @@ function assertCoherent(config) {
         config.discovery.catalogMaxTtlSeconds > 86_400) {
         throw new ConfigError("ConnectaConfig.discovery requires catalogMinTtlSeconds <= catalogMaxTtlSeconds <= 86400.");
     }
+    if (config.agents.length > 0 && !config.accessTokens) {
+        throw new ConfigError("ConnectaConfig.agents needs accessTokens: accessTokens(storage) from @zackbart/connecta/auth/access-tokens " +
+            "holds each agent's token slot.");
+    }
 }
 /**
  * Validate a configuration and apply every default. Unknown keys are refused
@@ -461,7 +554,7 @@ export function resolveConfig(config) {
  */
 export function readConfig(config) {
     const read = readPlain(config, "ConnectaConfig", CONFIG);
-    rejectUnknownOptions(read.unknown);
+    rejectUnknownOptions(expandRetiredIdentity(config, read.unknown));
     const input = read.value;
     const parsed = CONFIG.parse(input, "ConnectaConfig");
     assertCoherent(parsed);
@@ -470,10 +563,13 @@ export function readConfig(config) {
         name: parsed.serverInfo.name ?? "connecta",
         version: parsed.serverInfo.version ?? CONNECTA_VERSION,
     };
+    // The token module admits exactly the agents this configuration declares.
+    const accessTokens = parsed.accessTokens?.forAgents(parsed.agents);
     const resolved = Object.freeze({
         ...parsed,
+        accessTokens,
         // A managed-token module contributes one more provider, ordered with the rest.
-        auth: parsed.accessTokens ? normalizeAuth([parsed.accessTokens.auth, ...parsed.auth]) : parsed.auth,
+        auth: accessTokens ? normalizeAuth([accessTokens.auth, ...parsed.auth]) : parsed.auth,
         serverInfo: Object.freeze(info),
     });
     return { input, resolved };

package/dist/connector-access.d.ts

@@ -1,47 +1,18 @@
 import type { ToolAccess } from "./registry.js";
-import type { AuthenticatedIdentity } from "./types.js";
-/** A declared pool after construction-time validation. */
-export interface ResolvedPool {
-    trust: import("./tool-safety.js").PoolTrust;
-    access: ConnectorAccess;
-    grant(identity: Readonly<AuthenticatedIdentity>): boolean | Promise<boolean>;
-}
 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
+ * Normalize a pool's `tools`. 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. 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, 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
- * connector whose tool intersection is empty is gone too, so the pool can
- * only narrow what the identity resolver already allowed.
+ * connector. Anything else throws: a grant that cannot be parsed must never
+ * fail open.
  */
-export declare function intersectAccess(ceiling: ConnectorAccess, pool: ConnectorAccess): ConnectorAccess;
-export {};
+export declare function parseConnectorAccess(value: unknown): ConnectorAccess;

package/dist/connector-access.js

@@ -2,121 +2,37 @@ import { hasControlCharacters } from "./tool-name.js";
 export const POOL_NAME_RE = /^[a-z0-9_-]+$/;
 const CONNECTOR_ID_RE = /^[a-z0-9_-]+$/;
 // MCP does not restrict tool names, and remote servers ship spaced and
-// non-ASCII ones. Only control characters are refused, so a grant for a
-// legitimately named tool cannot 403 the whole identity at request time.
+// non-ASCII ones. Only control characters are refused, so a pool naming a
+// legitimately named tool still constructs.
 const TOOL_ADDRESS_RE = /^[a-z0-9_-]+\..{1,256}$/su;
 /**
- * Normalize a grant list. A bare connector id grants every tool on that
+ * Normalize a pool's `tools`. 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. 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.
+ * connector. Anything else throws: a grant that cannot be parsed must never
+ * fail open.
  */
-export function parseConnectorAccess(value, options = {}) {
-    if (value === "all")
-        return { connectorIds: "all" };
+export function parseConnectorAccess(value) {
     if (!Array.isArray(value))
         throw new Error("invalid connector permission");
     const whole = new Set();
-    const plain = new Map();
-    const guarded = new Map();
-    for (const entry of value) {
-        if (typeof entry === "string" && CONNECTOR_ID_RE.test(entry)) {
-            whole.add(entry);
+    const partial = new Map();
+    for (const address of value) {
+        if (typeof address === "string" && CONNECTOR_ID_RE.test(address)) {
+            whole.add(address);
             continue;
         }
-        const isGuarded = typeof entry !== "string";
-        if (isGuarded &&
-            (!options.allowReadOnly ||
-                entry === null ||
-                typeof entry !== "object" ||
-                Array.isArray(entry) ||
-                !Object.hasOwn(entry, "tool") ||
-                !Object.hasOwn(entry, "requireReadOnly") ||
-                Object.keys(entry).length !== 2 ||
-                entry.requireReadOnly !== true)) {
-            throw new Error("invalid connector permission");
-        }
-        const address = isGuarded ? entry.tool : entry;
         if (typeof address !== "string" || !TOOL_ADDRESS_RE.test(address) || hasControlCharacters(address)) {
             throw new Error("invalid connector permission");
         }
         const dot = address.indexOf(".");
         const connectorId = address.slice(0, dot);
-        const target = isGuarded ? guarded : plain;
-        const tools = target.get(connectorId) ?? new Set();
+        const tools = partial.get(connectorId) ?? new Set();
         tools.add(address.slice(dot + 1));
-        target.set(connectorId, tools);
-    }
-    for (const id of whole) {
-        plain.delete(id);
-        guarded.delete(id);
-    }
-    for (const [id, names] of plain) {
-        const restricted = guarded.get(id);
-        if (!restricted)
-            continue;
-        for (const name of names)
-            restricted.delete(name);
-        if (restricted.size === 0)
-            guarded.delete(id);
-    }
-    const partial = new Map(plain);
-    for (const [id, names] of guarded) {
-        const combined = partial.get(id) ?? new Set();
-        for (const name of names)
-            combined.add(name);
-        partial.set(id, combined);
+        partial.set(connectorId, tools);
     }
+    for (const id of whole)
+        partial.delete(id);
     const connectorIds = [...new Set([...whole, ...partial.keys()])];
-    return {
-        connectorIds,
-        ...(partial.size > 0 ? { toolAccess: partial } : {}),
-        ...(guarded.size > 0 ? { guardedToolAccess: guarded } : {}),
-    };
-}
-/**
- * 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
- * connector whose tool intersection is empty is gone too, so the pool can
- * only narrow what the identity resolver already allowed.
- */
-export function intersectAccess(ceiling, pool) {
-    if (pool.connectorIds === "all")
-        return ceiling;
-    const allowedIds = ceiling.connectorIds === "all" ? null : new Set(ceiling.connectorIds);
-    const connectorIds = [];
-    const toolAccess = new Map();
-    const guardedToolAccess = new Map();
-    for (const id of pool.connectorIds) {
-        if (allowedIds && !allowedIds.has(id))
-            continue;
-        const fromPool = pool.toolAccess?.get(id);
-        const fromCeiling = ceiling.toolAccess?.get(id);
-        if (fromPool && fromCeiling) {
-            const both = new Set([...fromPool].filter((name) => fromCeiling.has(name)));
-            if (both.size === 0)
-                continue;
-            toolAccess.set(id, both);
-        }
-        else if (fromPool ?? fromCeiling) {
-            toolAccess.set(id, (fromPool ?? fromCeiling));
-        }
-        const guarded = ceiling.guardedToolAccess?.get(id);
-        if (guarded) {
-            const allowed = toolAccess.get(id);
-            const retained = allowed ? new Set([...guarded].filter((name) => allowed.has(name))) : guarded;
-            if (retained.size > 0)
-                guardedToolAccess.set(id, retained);
-        }
-        connectorIds.push(id);
-    }
-    return {
-        connectorIds,
-        ...(toolAccess.size > 0 ? { toolAccess } : {}),
-        ...(guardedToolAccess.size > 0 ? { guardedToolAccess } : {}),
-    };
+    return { connectorIds, ...(partial.size > 0 ? { toolAccess: partial } : {}) };
 }

package/dist/connector-caller.d.ts

@@ -9,8 +9,14 @@ export interface ConnectorCaller {
      * with or without a subject, a Connecta-issued access token.
      */
     authenticated: boolean;
-    /** The `/mcp/<pool>` the call arrived on, when it was a pool. */
+    /** The pool the call arrived on, at `/mcp/<pool>` or `/agent/<pool>`. */
     pool?: string;
+    /**
+     * That pool's configured `owner`, the Workspace address an agent acts as
+     * (decisions/0006). Core copies it from the admitted pool's config; no
+     * request can set it, and humans never act as it.
+     */
+    poolOwner?: string;
 }
 export declare function attachCaller(ctx: ConnectorContext, caller: ConnectorCaller | undefined): ConnectorContext;
 export declare function callerOf(ctx: ConnectorContext): ConnectorCaller | undefined;

package/dist/connector-caller.js

@@ -8,8 +8,9 @@
 // - maintained providers that act *as* the caller downstream — Google
 //   Workspace through domain-wide delegation (`src/providers/_shared/google/`) — which
 //   hand the identity to a deployment-config function that names the
-//   downstream subject (PRINCIPLES.md INV-3, #678). The
-//   provider never decides whose account to open; config does, from this.
+//   downstream subject (PRINCIPLES.md INV-3, #678), or, for an agent, use the
+//   admitted pool's configured owner (decisions/0006). The provider never
+//   decides whose account to open; config does, from this.
 //
 // Core sets it from the authorization that admitted the request, on the scoped
 // registry view that request receives, and `api()` hands handlers that same

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

@@ -146,10 +146,33 @@ export interface ApiOptions {
 /** The closed options api() accepts; see `assertKnownOptions`. */
 export declare const API_OPTIONS: import("../config-schema.js").Field<unknown, unknown, true> & {
     readonly shape: {
-        callAdmission: import("../config-schema.js").Field<unknown, unknown, true> & {
-            readonly shape: {
-                rules: import("../config-schema.js").Field<unknown[], readonly unknown[] | undefined, true>;
-                maxPartitions: import("../config-schema.js").Field<unknown, unknown, true>;
+        callAdmission: Omit<import("../config-schema.js").Field<unknown, ConnectorCallAdmissionPolicy | undefined, true>, "parse"> & {
+            parse(value: unknown, path: string): ConnectorCallAdmissionPolicy;
+            readonly shape: import("../config-schema.js").Shape & {
+                maxPartitions: import("../config-schema.js").Field<number, number | undefined, true>;
+                rules: import("../config-schema.js").Field<{
+                    maxConcurrency?: number | undefined;
+                    maxQueueSize?: number | undefined;
+                    queueTimeoutMs?: number | undefined;
+                    retryAfterMs?: number | undefined;
+                    partitionKey?: ((input: Readonly<import("../types.js").ConnectorCallAdmissionInput>) => string) | undefined;
+                    budget?: {
+                        kind: "rolling-window";
+                        maxCalls: number;
+                        windowMs: number;
+                    } | undefined;
+                }[], readonly {
+                    readonly maxConcurrency: number | undefined;
+                    readonly maxQueueSize: number | undefined;
+                    readonly queueTimeoutMs: number | undefined;
+                    readonly retryAfterMs: number | undefined;
+                    readonly partitionKey: ((input: Readonly<import("../types.js").ConnectorCallAdmissionInput>) => string) | undefined;
+                    readonly budget: {
+                        readonly kind: "rolling-window";
+                        readonly maxCalls: number;
+                        readonly windowMs: number;
+                    } | undefined;
+                }[], false>;
             };
         };
         usageGuide: import("../config-schema.js").Field<unknown, unknown, true> & {

package/dist/connectors/api-connector.js

@@ -90,6 +90,8 @@ function describedApiAuth(opts) {
  */
 export function apiConnector(id, opts, oauth) {
     opts = assertKnownOptions(opts, `api(${JSON.stringify(id)})`, API_OPTIONS);
+    if (opts.callAdmission !== undefined)
+        CALL_ADMISSION.parse(opts.callAdmission, `api(${JSON.stringify(id)}).callAdmission`);
     assertStaticToolNames(opts.tools, `api(${JSON.stringify(id)}).tools`);
     if (opts.oauth !== undefined && oauth === undefined) {
         throw new Error(`api() connector "${id}" declares oauth but was built without its grant; construct it with api().`);

package/dist/connectors/guarded-fetch.d.ts

@@ -56,6 +56,8 @@ interface GuardedResponse {
     readonly status: number;
     readonly ok: boolean;
     readonly headers: Headers;
+    /** Cancel an unread body without waiting for the vendor to emit a chunk. */
+    cancel(): Promise<void>;
     /** The body as bytes. */
     bytes(): Promise<Uint8Array>;
     /** The body decoded as UTF-8. */
@@ -124,6 +126,13 @@ export interface GuardedFetchOptions {
      * absurd response is a fact about the API, not about HTTP.
      */
     maxResponseBytes: number;
+    /**
+     * Inspect the exact URL about to be fetched — confined, normalized, with its
+     * query encoded — and throw to refuse it. A policy that reads this URL reads
+     * what the downstream server will route, not a spelling of it. Runs before
+     * authentication, so a refused request never resolves a credential.
+     */
+    admit?: (url: URL, request: GuardedRequest) => void;
 }
 /** Sends one already-guarded request on behalf of one call's context. */
 type GuardedFetcher = (url: string, init: RequestInit, ctx: ConnectorContext) => Promise<Response>;

package/dist/connectors/guarded-fetch.js

@@ -181,6 +181,9 @@ function boundedResponse(provider, response, limit) {
             status: response.status,
             ok: response.ok,
             headers: response.headers,
+            cancel: async () => {
+                await response.body?.cancel();
+            },
             bytes: async () => new Uint8Array(),
             text: async () => "",
             json: emptyJson,
@@ -228,6 +231,9 @@ function boundedResponse(provider, response, limit) {
         status: response.status,
         ok: response.ok,
         headers: response.headers,
+        cancel: async () => {
+            await response.body?.cancel();
+        },
         bytes,
         text,
         json,
@@ -307,6 +313,7 @@ export function guardedFetch(options) {
             throw new Error(`A ${provider} request cannot carry both a JSON body and a raw body.`);
         }
         const url = confinedUrl(provider, base, basePath, request);
+        options.admit?.(url, request);
         const headers = { ...constantHeaders };
         for (const [name, value] of Object.entries(request.headers ?? {})) {
             if (value !== undefined)

package/dist/connectors/remote-mcp.js

@@ -1024,6 +1024,8 @@ function registrationErrorCode(body) {
  */
 export function remoteMcp(id, opts) {
     opts = assertKnownOptions(opts, `remoteMcp(${JSON.stringify(id)})`, REMOTE_MCP_OPTIONS);
+    if (opts.callAdmission !== undefined)
+        CALL_ADMISSION.parse(opts.callAdmission, `remoteMcp(${JSON.stringify(id)}).callAdmission`);
     const skillsEnabled = opts.skills;
     if (skillsEnabled !== undefined && typeof skillsEnabled !== "boolean") {
         throw new Error(`[connecta] connector "${id}" skills must be a boolean.`);