@zackbart/connecta 0.34.1 → 0.36.0

package/README.md

@@ -2,137 +2,97 @@
 
 **One connection between your agent and the services you choose.**
 
-Connecta puts your MCP servers and HTTP APIs behind one endpoint that you run
-yourself. Connect your agent once; decide in code who can reach what.
-
-## How it works
+Connecta puts the services your agent needs behind one connection. It uses
+**Model Context Protocol (MCP)**, a standard that lets AI apps use tools.
+You run Connecta and choose what each agent may access.
 
 ```mermaid
 flowchart LR
-    Agent["Your agent"] <-->|"One connection<br/>six small tools"| Connecta
-
-    subgraph Connecta["Your Connecta deployment"]
-        Sandbox["Sandbox<br/>runs the agent's short programs"]
-        Keys["Credentials<br/>stay on the server"]
+    Agents["Agent apps and people"] --> Pools
+    subgraph Connecta["Your Connecta server"]
+        Pools["Pools<br/>which tools each caller can use"] --> Checks["Access checks<br/>reads · changes · secrets"]
     end
-
-    Connecta <--> Work["Linear, GitHub, Notion"]
-    Connecta <--> Business["Stripe, RevenueCat, Mixpanel"]
-    Connecta <--> Yours["Any remote MCP server<br/>or HTTP API"]
-
-    style Connecta fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b,stroke-width:2px
+    Checks --> Stripe
+    Checks --> Google["Google Workspace"]
+    Checks --> Other["Other services"]
 ```
 
-The agent doesn't load every service's tools into the conversation. It writes
-a short program that gathers, joins, and trims results inside Connecta, so
-only the answer comes back.
+A tool is an action, such as finding a ticket or updating a record. The agent
+can call one action directly or combine several in a short program inside
+Connecta. The program can return a small answer instead of every record.
+Connecta supplies the service credentials, so the agent doesn't need them.
 
 ## What you can connect
 
-Maintained connections: <!-- providers:start -->Basecamp, Breeze ChMS, Church Community Builder, Cloudflare, GitHub, Gmail, Google Docs, Google Drive, Google Forms, Google Sheets, Google Slides, Infisical, Intercom, Linear, Mixpanel, Notion, Overflow, Planning Center, RevenueCat, Stripe, Tithe.ly, Vercel, and Wispr Flow<!-- providers:end -->.
-Plus any remote MCP server or HTTP API you describe.
+Maintained connections: <!-- providers:start -->Breeze ChMS, Church Community Builder, Cloudflare, GitHub, Gmail, Google Docs, Google Drive, Google Forms, Google Sheets, Google Slides, Overflow, Planning Center, QuickBooks Online, Stripe, Tithe.ly, and Vercel<!-- providers:end -->.
 
-## Who can use it
+Maintained API providers pair reviewed vendor contracts with tools built by
+Connecta. See the [API sources and tool inventory](./documentation/providers.md#api-sources-and-tool-inventory)
+for each provider's named workflows and reviewed API tools.
 
-|                   | People                                               | Agents                                   |
-| ----------------- | ---------------------------------------------------- | ---------------------------------------- |
-| What they are     | You and your team                                    | Bots, assistants, CI, scheduled jobs     |
-| How they prove it | Sign in: Clerk (Node) or Cloudflare Access (Workers) | One token Connecta issues to that agent  |
-| Their own logins  | Yes, on personal connections                         | No. An agent uses accounts you assign it |
+You can also connect another hosted MCP tool server through `remoteMcp()`,
+which discovers the server's live tool catalog, or describe an API Connecta
+should call.
 
-**Maintainers** are the people who run the deployment: they reach every tool
-and manage credentials and agent tokens. Everyone else reaches only the pools
-they are listed in.
+## What it protects
 
-### Pools
+| Boundary         | What Connecta does                                                                                                        |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Access           | A pool limits the tools its members can reach.                                                                            |
+| Writes           | For tools marked as writes, once a change is sent, Connecta won't automatically send it again.                            |
+| Secrets          | Known secrets are redacted from agent output. Enable the credential vault to encrypt stored credentials and OAuth tokens. |
+| Read-only access | Read-only endpoints hide writes and refuse attempts to call them.                                                         |
 
-A **pool** is a named set of tools plus a list of who may use it. Each pool
-has its own address, and every caller sees exactly that pool's tools.
+Read-only protection and single-attempt writes depend on truthful tool labels.
+The AI app using Connecta decides when to ask for approval; a writable pool
+can write unattended. [Safety and trust](./guides/safety-and-trust.md)
+explains these boundaries and their limits.
 
-```mermaid
-flowchart LR
-    Maint["Maintainer<br/>(signs in)"] --> Main["/mcp<br/>every tool"]
-    Bob["Bob<br/>(signs in)"] --> Team["/mcp/team<br/>CRM + tickets"]
-    Bot["assistant agent<br/>(token)"] --> AgentPool["/agent/assistant<br/>CRM + tickets"]
+## Try it in three steps
 
-    style Main fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b
-    style Team fill:#dcfce7,stroke:#15803d,color:#14532d
-    style AgentPool fill:#fef3c7,stroke:#b45309,color:#78350f
-```
+You'll need somewhere to run Connecta and permission to connect the service
+accounts you choose. Creating the project is the start of setup; account
+connections and access rules still need configuring.
 
-People use a pool at `/mcp/<pool>` and agents at `/agent/<pool>`. A caller
-outside a pool gets the same "not found" as a pool that doesn't exist, and
-someone in two pools uses two addresses: pools never merge.
+1. **Create a deployment.** Start with the Node template:
 
-### One agent, many people
+   ```sh
+   npx @zackbart/connecta init my-connecta
+   cd my-connecta
+   npm install
+   ```
 
-An assistant that talks to several people keeps **one token and one
-connection**. Its harness, not the model, picks the pool each turn: a chat
-gets the most capable tier that everyone in it is cleared for, and a
-one-on-one gets that person's own pool.
+2. **Choose services and access.** Your operator—the person or team running
+   Connecta—can use a coding assistant as a setup agent. Give that assistant
+   the [operator documentation](./documentation/README.md). It configures
+   services, enables the credential vault, connects accounts, and starts
+   the server with the access rules you choose.
+3. **Connect your AI app.** This app is the MCP client: it uses Connecta's
+   tools on your agent's behalf. Give it the pool address and authentication
+   method supplied by your operator. [Connecting agents](./guides/connecting-agents.md)
+   explains what to ask for; the [deployment guide](./documentation/deploying.md)
+   has runnable steps.
 
 ```mermaid
 flowchart LR
-    Guests["Chat with anyone unknown"] --> Base["/agent/assistant<br/>read-only basics"]
-    Group["Chat of team members"] --> TeamTier["/agent/assistant-team<br/>shared tools"]
-    Leads["Chat of leads only"] --> LeadsTier["/agent/assistant-leads<br/>shared tools + billing"]
-    Alice["One-on-one<br/>with Alice"] --> PA["/agent/assistant-alice<br/>her tier + her accounts"]
-
-    Base -.-> TeamTier -.-> LeadsTier
-
-    style Base fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b
-    style TeamTier fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b
-    style LeadsTier fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b
-    style PA fill:#dcfce7,stroke:#15803d,color:#14532d
+    Create["1 · Create"] --> Configure["2 · Choose services + access"] --> Connect["3 · Connect your AI app"]
 ```
 
-Each tier builds on the one below it. A person's own pool builds on the
-highest tier they are cleared for and holds only the agent, since anyone else
-in it would act as that person. A tier can double as a team's own pool for
-the people cleared for it. [Organizing an agent's pools](./documentation/auth.md#organizing-an-agents-pools)
-has the full layout.
+The package is `@zackbart/connecta` (`npm install @zackbart/connecta`). Run it
+on Node, in Docker, or on Cloudflare Workers. The
+[deployment guide](./documentation/deploying.md#choose-a-deployment) covers each.
 
-### Whose account a connection uses
+## Read a little more
 
-- **Shared** (the default): the deployment's account, connected once by a
-  maintainer.
-- **Personal**: each person's own account. Agents never see these.
-- **Google Workspace**: the signed-in person's account; for an agent, the
-  owner of a person's pool, or one fixed shared account. Without an owner,
-  mapping connections are absent for agents.
-
-## Reads and writes
-
-Every endpoint is writable or read-only, and you choose explicitly. A
-read-only endpoint hides write tools and refuses every write. You can also make
-one connection read-only across all endpoints. On a writable
-one, your agent's host decides what to approve.
-
-## Where it runs
-
-Node or Docker (Clerk sign-in, SQLite) or Cloudflare Workers (Cloudflare
-Access, D1). Both serve the same agent tools. An optional operator UI shows
-a connection map, endpoints, connectors, and activity; integrations and access
-still change only in deployment code.
-
-## Getting started
-
-Give your agent the [agent documentation](./documentation/README.md) and ask
-it to set up Connecta with the integrations you want, where to run it, and who
-should have access.
+| Guide                                               | What you'll understand                                                   |
+| --------------------------------------------------- | ------------------------------------------------------------------------ |
+| [How it works](./guides/how-it-works.md)            | Connectors, pools, people, and how a call reaches a service.             |
+| [Connecting agents](./guides/connecting-agents.md)  | Agent tokens, Vercel identity, and the optional Eve helper.              |
+| [Safety and trust](./guides/safety-and-trust.md)    | Uncertain changes, secrets, read-only access, and your responsibilities. |
+| [Operator documentation](./documentation/README.md) | Setup, feature availability, upgrades, and exact contracts.              |
 
 <a id="existing-client-tokens"></a>
 
-Upgrading? Point your agent at the
-[upgrade guidance](./documentation/deploying.md#upgrade-an-existing-deployment).
-
-## Status
-
-Built for its author's deployments first and published openly. Breaking
-changes are expected before 1.0. See the [changelog](./CHANGELOG.md) and
-[security policy](./SECURITY.md).
-
-[Principles](https://github.com/zackbart/connecta/blob/main/PRINCIPLES.md) ·
-[Decision records](https://github.com/zackbart/connecta/tree/main/decisions) ·
-[Planned work](https://github.com/zackbart/connecta/issues) (a plan is not a
-shipped feature)
+Upgrading? Follow the [upgrade guide](./documentation/deploying.md#upgrade-an-existing-deployment).
+Breaking changes are expected before 1.0. See the [changelog](./CHANGELOG.md)
+and [security policy](./SECURITY.md).

package/SECURITY.md

@@ -17,8 +17,9 @@ findings are reviewed for reachability and recorded when an upstream package has
 not yet released a compatible fix.
 
 The MCP TypeScript SDK 2.x packages and Effect are exact-pinned. Effect is the
-runtime core, and its unstable modules can break in a minor release, so its pin
-moves in a dedicated upgrade. The split client and server packages no longer
+runtime core, and its `effect/http`, `effect/http-api`, and `effect/sql` area
+modules carry `@stability unstable` within the 4.x LTS line, so its pin moves
+in a dedicated upgrade. The split client and server packages no longer
 install Hono or `@hono/node-server`, so the temporary root-project override
 used with SDK 1.x is gone. A dependency bump must pass `pnpm run release:check`
 and the Node/Workers runtime suites before a pin moves.

package/bin/connecta.mjs

@@ -244,32 +244,57 @@ async function doctor() {
     fetch: doctorFetch,
   });
   let negotiatedVersion;
+  let native = false;
+  let executeCode = true;
   try {
     await client.connect(transport);
     negotiatedVersion = client.getNegotiatedProtocolVersion();
     const listed = await client.listTools({}, { timeout: DOCTOR_TIMEOUT_MS });
     const actual = listed.tools.map((tool) => tool.name).sort();
-    const expected = [...META_TOOL_NAMES].sort();
-    if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+    const surface = listed.tools.find((tool) => tool.name === "skills")?._meta?.["dev.connecta/surface"];
+    native = surface?.surface === "native";
+    executeCode = !native || surface.executeCode === true;
+    if (native && surface.catalogErrors?.length)
+      throw new Error(
+        `Native catalogs unavailable: ${surface.catalogErrors.join(", ")}. Inspect connector status and authentication.`,
+      );
+    const expected = native
+      ? ["skills", executeCode ? "execute_code" : "read_result"].sort()
+      : [...META_TOOL_NAMES].sort();
+    if (
+      native
+        ? expected.some((name) => !actual.includes(name)) ||
+          [
+            "search_tools",
+            "call_tool",
+            "call_destructive_tool",
+            "authorize_connector",
+            executeCode ? "read_result" : "execute_code",
+          ].some((name) => actual.includes(name))
+        : JSON.stringify(actual) !== JSON.stringify(expected)
+    ) {
       throw new Error(
         `Unexpected MCP surface. Expected ${expected.join(", ")}; received ` +
           `${Array.isArray(actual) ? actual.join(", ") : "no tool list"}.`,
       );
     }
 
-    const executed = await client.callTool(
-      {
-        name: "execute_code",
-        arguments: { code: "async () => 42" },
-      },
-      undefined,
-      { timeout: DOCTOR_TIMEOUT_MS },
-    );
-    const executionResult = executed.structuredContent ?? JSON.parse(executed.content?.[0]?.text ?? "null");
-    if (executed.isError || executionResult?.result !== 42) {
-      throw new Error(
-        `${executorName ? `${executorName} execution` : "execute_code"} check ` + `failed: ${JSON.stringify(executed)}`,
+    if (executeCode) {
+      const executed = await client.callTool(
+        {
+          name: "execute_code",
+          arguments: { code: "async () => 42" },
+        },
+        undefined,
+        { timeout: DOCTOR_TIMEOUT_MS },
       );
+      const executionResult = executed.structuredContent ?? JSON.parse(executed.content?.[0]?.text ?? "null");
+      if (executed.isError || executionResult?.result !== 42) {
+        throw new Error(
+          `${executorName ? `${executorName} execution` : "execute_code"} check ` +
+            `failed: ${JSON.stringify(executed)}`,
+        );
+      }
     }
   } finally {
     await client.close();
@@ -277,8 +302,8 @@ async function doctor() {
 
   console.log(
     `Connecta doctor passed: ${health.connectors} connector(s), ` +
-      `${executorName ? `${executorName} executed` : "code executed"}, ` +
-      `prescribed ${META_TOOL_NAMES.length}-tool surface, MCP ${negotiatedVersion}, package ${CONNECTA_VERSION}.`,
+      `${executeCode ? (executorName ? `${executorName} executed` : "code executed") : "code disabled"}, ` +
+      `${native ? "native tool surface" : `prescribed ${META_TOOL_NAMES.length}-tool surface`}, MCP ${negotiatedVersion}, package ${CONNECTA_VERSION}.`,
   );
 }
 

package/bin/version.mjs

@@ -1,3 +1,3 @@
 // Generated from package.json by scripts/generate-version.mjs.
 // Workers-safe: no runtime filesystem read or deployment override.
-export const CONNECTA_VERSION = "0.34.1";
+export const CONNECTA_VERSION = "0.36.0";

package/dist/access-tokens.d.ts

@@ -1,5 +1,6 @@
 import type { InboundAuth, KVStorage } from "./types.js";
 import type { AccessTokensModule } from "./module-contracts.js";
+import { type AgentConfig } from "./agent-config.js";
 /**
  * One declared agent's token slot as management sees it. Never secret
  * material. `revision` is opaque: it changes on every commit to the slot and
@@ -69,7 +70,7 @@ export declare class AccessTokenManager {
     private readonly agents;
     private readonly agentOrder;
     constructor(storage: KVStorage, options?: {
-        agents?: readonly string[];
+        agents?: readonly AgentConfig[];
     });
     private declared;
     private read;

package/dist/access-tokens.js

@@ -1,9 +1,14 @@
+import { withAuthenticationDeadline } from "./auth-admission.js";
 import { authorizationCredential, isMachineCredential } from "./inbound-credential.js";
-import { assertKnownOptions, ConfigError, optionsOf } from "./config-schema.js";
+import { assertKnownOptions, ConfigError, optionsOf, readPlain } from "./config-schema.js";
 import { routeAccessTokens } from "./routes/access-tokens.js";
 import { validIdentityReference } from "./identity.js";
 import { accessTokenKeys } from "./storage/keys.js";
-import { AGENT_NAMESPACE, agentSubjectId, assertAgentNames, isAgentName, trustAgentProvider, } from "./agent-identity.js";
+import { AGENT_NAMESPACE, agentSubjectId, isAgentName, trustAgentProvider } from "./agent-identity.js";
+import { keepErrorName } from "./redaction-identity.js";
+import { agentConfig } from "./agent-config.js";
+import { authCall, authCatch, authFlow, authInvoke, authMethod, authOwnMethod, authStorage, registerAuthMethod, } from "./auth/native.js";
+import { runEdge } from "./runtime/run.js";
 const TOKEN_PREFIX = "cta_";
 const TOKEN_BYTES = 32;
 const TOKEN_VALUE_RE = /^cta_[A-Za-z0-9_-]{43}$/;
@@ -31,6 +36,7 @@ export class AccessTokenError extends Error {
         this.code = code;
     }
 }
+keepErrorName(AccessTokenError, "AccessTokenError");
 /** What each operation tells its caller when its outcome cannot be settled. */
 const UNKNOWN = {
     rotate: "Rotation outcome unknown: no secret was returned, so rotate again for a replacement",
@@ -251,8 +257,10 @@ export class AccessTokenManager {
             throw new Error("accessTokens requires storage that implements list and compareAndSet " +
                 "(d1Storage, sqliteStorage, or memoryStorage)");
         }
-        const agents = options.agents ?? [];
-        assertAgentNames(agents, "agents");
+        const input = readPlain(options.agents ?? [], "agents", agentConfig);
+        if (input.unknown.length)
+            throw new ConfigError("agents contains unknown declaration options.");
+        const agents = agentConfig.parse(input.value, "agents").map((agent) => agent.name);
         this.agentOrder = Object.freeze([...agents]);
         this.agents = new Set(agents);
         this.auth = trustAgentProvider({
@@ -270,7 +278,7 @@ export class AccessTokenManager {
                     return undefined;
                 }
             },
-            authorize: (request) => this.authorize(request).catch(() => unauthorized()),
+            authorize: authMethod((request) => authCatch(authInvoke(this, "authorize", [request]), unauthorized)),
         });
     }
     declared(name) {
@@ -779,31 +787,59 @@ export class AccessTokenManager {
             .sort((a, b) => a.createdAt.localeCompare(b.createdAt))
             .map(({ id, name, createdAt }) => ({ id, name, createdAt }));
     }
-    async authorize(request) {
-        const credential = authorizationCredential(request);
-        const token = credential.kind === "bearer" ? credential.token : undefined;
-        if (!token || !TOKEN_VALUE_RE.test(token))
-            return unauthorized();
-        const hash = await hashToken(token);
-        const lookupRaw = await this.storage.get(lookupKey(hash));
-        if (!lookupRaw)
-            return unauthorized();
-        const lookup = parseLookup(lookupRaw);
-        if (!lookup)
-            return unauthorized();
-        const record = await this.read(lookup.id);
-        if (!record || record.revokedAt || record.tokenHash !== hash || record.tokenPrefix !== token.slice(0, 12)) {
-            return unauthorized();
-        }
-        // The slot is the authority: a surviving lookup or record it does not
-        // name is inert. Human-bound and unbound records, and agents no longer in
-        // code, refuse exactly as an unknown token does.
-        if (record.principal || record.agent === undefined || !this.agents.has(record.agent))
-            return unauthorized();
-        const { slot } = await this.readSlot(record.agent);
-        if (slot?.state !== "issued" || slot.tokenId !== record.id)
-            return unauthorized();
-        return { ok: true, subjectId: agentSubjectId(record.agent), agent: record.agent };
+    authorize(request) {
+        return runEdge(authOwnMethod(AccessTokenManager.prototype, this, "authorize", [request]));
+    }
+    static {
+        registerAuthMethod(AccessTokenManager.prototype, "authorize", function (request) {
+            return authFlow(function* () {
+                const credential = authorizationCredential(request);
+                const token = credential.kind === "bearer" ? credential.token : undefined;
+                if (!token || !TOKEN_VALUE_RE.test(token))
+                    return unauthorized();
+                return (yield authCall(withAuthenticationDeadline, [
+                    request,
+                    authMethod((signal) => {
+                        return authFlow(function* () {
+                            signal.throwIfAborted();
+                            const hash = (yield authCall(hashToken, [token]));
+                            signal.throwIfAborted();
+                            const lookupRaw = (yield authStorage(this.storage, "get", [lookupKey(hash)]));
+                            signal.throwIfAborted();
+                            if (!lookupRaw)
+                                return unauthorized();
+                            const lookup = parseLookup(lookupRaw);
+                            if (!lookup)
+                                return unauthorized();
+                            const recordRaw = ID_RE.test(lookup.id)
+                                ? (yield authStorage(this.storage, "get", [recordKey(lookup.id)]))
+                                : null;
+                            const record = recordRaw ? parseRecord(recordRaw) : null;
+                            if (record && record.id !== lookup.id)
+                                throw new Error("Stored access token id mismatch");
+                            signal.throwIfAborted();
+                            if (!record ||
+                                record.revokedAt ||
+                                record.tokenHash !== hash ||
+                                record.tokenPrefix !== token.slice(0, 12)) {
+                                return unauthorized();
+                            }
+                            // The slot is the authority: a surviving lookup or record it does not
+                            // name is inert. Human-bound and unbound records, and agents no longer in
+                            // code, refuse exactly as an unknown token does.
+                            if (record.principal || record.agent === undefined || !this.agents.has(record.agent))
+                                return unauthorized();
+                            const slotRaw = (yield authStorage(this.storage, "get", [slotKey(record.agent)]));
+                            const slot = slotRaw === null ? null : parseSlot(slotRaw, record.agent);
+                            signal.throwIfAborted();
+                            if (slot?.state !== "issued" || slot.tokenId !== record.id)
+                                return unauthorized();
+                            return { ok: true, subjectId: agentSubjectId(record.agent), agent: record.agent };
+                        }.bind(this));
+                    }),
+                ]));
+            }.bind(this));
+        }, AccessTokenManager.prototype.authorize);
     }
 }
 const ACCESS_TOKENS_OPTIONS = optionsOf()({});

package/dist/activity.d.ts

@@ -5,7 +5,7 @@ import type { Logger } from "./types.js";
 export declare function activityClientFact(value: unknown, field: "name" | "version"): string | undefined;
 /** Stored package versions use a bounded release-version grammar, including prereleases. */
 export declare function activityPackageVersion(value: unknown): string | undefined;
-export type ActivityCallSource = "catalog_refresh" | "call_tool" | "call_destructive_tool" | "batch_call" | "execute_code" | "resume_execution";
+export type ActivityCallSource = "catalog_refresh" | "native" | "call_tool" | "call_destructive_tool" | "batch_call" | "execute_code" | "resume_execution";
 export type ActivityOutcome = "success" | "error" | "timeout" | "cancelled" | "paused" | "approved";
 /** Read-only history: how much one `resume_execution` approved (#672). */
 export type ActivityApproval = "call" | "tool";

package/dist/activity.js

@@ -3,6 +3,7 @@ import { assertKnownOptions, keys, optionsOf } from "./config-schema.js";
 import { routeActivity } from "./routes/activity.js";
 import { boundedEchoText, classificationCode } from "./errors.js";
 import { failureRecord, logFailure } from "./operator-record.js";
+import { keepErrorName } from "./redaction-identity.js";
 /**
  * How long an identity field may be before the store stops believing it.
  *
@@ -91,6 +92,7 @@ export class InvalidActivityCursorError extends Error {
         super("invalid activity cursor");
     }
 }
+keepErrorName(InvalidActivityCursorError, "InvalidActivityCursorError");
 /**
  * Best-effort by design: activity storage can never change a tool result.
  * Workers attach async sinks to waitUntil; synchronous sinks such as Analytics

package/dist/agent-config.d.ts

@@ -0,0 +1,23 @@
+import { type Field } from "./config-schema.js";
+type VercelEnvironment = "production" | "preview" | "development";
+/** Vercel workload binding: immutable team_ ID; prefer a prj_ project ID. */
+interface VercelAgentCredential {
+    team: string;
+    project: string;
+    environments?: readonly VercelEnvironment[] | undefined;
+}
+/** A string keeps the existing token-only declaration. */
+export type AgentConfig = string | {
+    name: string;
+    vercel: VercelAgentCredential;
+};
+export interface ResolvedAgent {
+    readonly name: string;
+    readonly vercel?: {
+        readonly team: string;
+        readonly project: string;
+        readonly environments: readonly VercelEnvironment[];
+    };
+}
+export declare const agentConfig: Field<readonly AgentConfig[], readonly ResolvedAgent[], true>;
+export {};

package/dist/agent-config.js

@@ -0,0 +1,59 @@
+import { assertAgentNames } from "./agent-identity.js";
+import { array, ConfigError, object, opaque, required, text } from "./config-schema.js";
+const segment = (kind) => required(opaque({
+    check(value, path) {
+        const pattern = kind === "team" ? /^team_[A-Za-z0-9]+(?![\s\S])/ : /^[A-Za-z0-9._-]+(?![\s\S])/;
+        if (typeof value !== "string" || value.length > 128 || !pattern.test(value)) {
+            throw new ConfigError(`${path} must be ${kind === "team" ? "an immutable Vercel team_ ID" : "an exact Vercel project ID or name"}.`);
+        }
+    },
+}));
+const environments = opaque({
+    check(value, path) {
+        if (!Array.isArray(value) ||
+            value.length === 0 ||
+            value.some((env) => !["production", "preview", "development"].includes(env)) ||
+            new Set(value).size !== value.length) {
+            throw new ConfigError(`${path} must list unique production, preview or development environments.`);
+        }
+    },
+    resolve: (value) => Object.freeze([...(value ?? ["production"])]),
+});
+const declaration = object({
+    name: required(text()),
+    vercel: required(object({ team: segment("team"), project: segment("project"), environments })),
+});
+const entry = {
+    ...declaration,
+    optional: false,
+    parse: (value, path) => (typeof value === "string" ? Object.freeze({ name: value }) : declaration.parse(value, path)),
+    absent: (path) => {
+        throw new ConfigError(`${path} must declare an agent.`);
+    },
+};
+const list = array(entry);
+export const agentConfig = {
+    ...list,
+    parse(value, path) {
+        const agents = list.parse(value, path);
+        assertAgentNames(agents.map((agent) => agent.name), path);
+        for (let i = 0; i < agents.length; i++) {
+            const a = agents[i].vercel;
+            if (!a)
+                continue;
+            for (const prior of agents.slice(0, i)) {
+                const b = prior.vercel;
+                // A project name and an ID can designate the same project. Refuse possible
+                // overlap rather than let declaration order select another identity.
+                if (b &&
+                    a.team === b.team &&
+                    (a.project === b.project || a.project.startsWith("prj_") !== b.project.startsWith("prj_")) &&
+                    a.environments.some((env) => b.environments.includes(env))) {
+                    throw new ConfigError(`${path}[${i}].vercel overlaps another agent's workload binding.`);
+                }
+            }
+        }
+        return agents;
+    },
+    absent: () => Object.freeze([]),
+};

package/dist/agent-description.js

@@ -0,0 +1,16 @@
+const empty = Object.freeze([]);
+const descriptions = new WeakMap();
+export function registerAgentDescriptions(config, agents, tokens) {
+    if (descriptions.has(config))
+        return;
+    descriptions.set(config, Object.freeze(agents.map((agent) => Object.freeze({
+        name: agent.name,
+        credentialTypes: Object.freeze([
+            ...(tokens ? ["access_token"] : []),
+            ...(agent.vercel ? ["vercel_oidc"] : []),
+        ]),
+    }))));
+}
+export function agentDescriptions(config) {
+    return descriptions.get(config) ?? empty;
+}

package/dist/agent-identity.js

@@ -1,6 +1,6 @@
 // Code-declared agents (#837): the names deployment code lists in `agents`,
-// the identity an admitted agent carries, and the one provider trusted to
-// assert it. Pure, so core reads it without reaching the token module.
+// the identity an admitted agent carries, and the built-in providers trusted
+// to assert it. Pure, so core reads it without reaching credential modules.
 import { ConfigError } from "./config-schema.js";
 /** Agent names: lowercase letters, digits, `_` and `-`. */
 const AGENT_NAME_RE = /^[a-z0-9_-]+$/u;
@@ -36,12 +36,12 @@ export function assertAgentNames(value, path) {
     });
 }
 const agentProviders = new WeakSet();
-/** Mark the built-in access-token adapter as the one provider whose `agent` is trusted. */
+/** Mark a built-in credential adapter as trusted to assert `agent`. */
 export function trustAgentProvider(provider) {
     agentProviders.add(provider);
     return provider;
 }
-/** Whether `provider` is the built-in access-token adapter. */
+/** Whether `provider` is a trusted built-in agent credential adapter. */
 export function assertsAgents(provider) {
     return agentProviders.has(provider);
 }