@zackbart/connecta-eve 0.36.0 → 0.36.2

package/README.md

@@ -55,6 +55,40 @@ again for each request, so rotation requires no process restart. A `getToken`
 callback can return a string or a promise of one; it overrides the environment.
 No user's identity is forwarded.
 
+## Choosing the pool at runtime
+
+Pass the same selector to both factories when the pool depends on the chat.
+For example, an app that sets trusted `direct` channel metadata can keep its
+choice fixed for a turn:
+
+```ts
+import type { DynamicContext } from "eve/connections";
+
+export const selectPool = (ctx: DynamicContext) =>
+  ctx.memo(["connecta-pool", ctx.turn?.id ?? null], () =>
+    ctx.channel.metadata.direct === true && ctx.session.auth.current?.principalId === "alice"
+      ? "notes_alice"
+      : "assistant",
+  );
+```
+
+Use `pool: selectPool` in both `connectaConnection` and `connectaInstructions`.
+Eve evaluates the dynamic connection before every model call; the selected
+pool is its `instanceKey`, so a parked call cannot replay against a changed
+pool. A string still creates the same static connection.
+
+Both factories call the selector independently. The helper never memoizes its
+result. Memoize selector I/O with `ctx.memo` for your policy's lifetime so the
+connection and instructions agree and repeated evaluations avoid repeated
+lookups. Eve scopes memos per definition, so the two factories each perform
+their first lookup. A turn key fixes each choice for that turn; omit the memo
+to choose again at every evaluation. Ensure both lookups use consistent
+app-owned policy data.
+
+Each selected name must match `[a-z0-9_-]+`. A throwing selector or an invalid
+name fails the turn, even when guidance is cached. Handle lookup failures in
+your selector if it should fall back to a least-privileged pool.
+
 ## Eve 0.84.0 dependency override
 
 Eve 0.84.0 pins undici 8.10.2. Connecta's development/test override does not ship
@@ -93,14 +127,19 @@ Instructions use `server/discover` (MCP 2026-07-28), falling back to legacy
 non-OK status or an unsupported-method response. Network errors and timeouts
 never trigger initialize. Both JSON and SSE replies are accepted. Each request
 has a five-second timeout. Successful guidance is cached for ten minutes per
-resolver; `ttlMs` overrides that duration. Eve evaluates instructions before
-every model call; the helper keeps one result per turn in Eve's memo, so a turn
-sees the same guidance throughout and at most one refresh. A failed refresh
-keeps the last copy, or adds nothing if no fetch has succeeded, and waits 30
-seconds before retrying.
+endpoint in each resolver; `ttlMs` overrides that duration. Eve evaluates
+instructions before every model call; the helper keeps one result per endpoint
+and turn in Eve's memo, with at most one refresh for that endpoint while its
+memo is retained. Switching pools selects that endpoint's guidance, never the
+previous pool's. A failed refresh keeps that endpoint's last copy, or adds
+nothing if none has succeeded, and waits 30 seconds before retrying it. Other
+endpoints keep their own TTL and backoff. Eve retains only memo keys used by the
+latest evaluation; returning to a pool can refresh again if its cache expired.
 When Eve cancels an evaluation, the helper rethrows the cancellation instead of
 counting it as a failure: nothing is kept for that turn and no wait starts.
 Tools remain usable. Instructions do not grant access.
+Set `clientName` on `connectaInstructions` to identify its requests in server
+logs; the default is `connecta-eve-instructions`.
 
 ## Vercel OIDC token source
 
@@ -130,6 +169,8 @@ export default connectaInstructions({ pool: "assistant", getToken: getVercelOidc
 
 Install `@vercel/oidc` in the Eve app when using this variant. The helper has no
 dependency on it and never switches credential types automatically.
+Use the default workload audience: Connecta refuses tokens exchanged for a
+custom audience, even when Vercel signed them.
 
 ## Contributor validation
 
@@ -149,3 +190,10 @@ isolate each matrix cell; Eve startup is separate from turn latency. Reports
 retain actual Eve events and transport inputs. Token usage and model task
 quality remain unmeasured; these results establish local runtime contracts,
 not live Vercel workload admission or production model performance.
+
+For a disposable workload check, use the
+[contributor fixture recipe](https://github.com/zackbart/connecta/blob/main/packages/connecta-eve/scripts/workload-fixture/README.md) from a source
+checkout. Its preparation command packs and installs the current core/helper,
+checks local signed controls and cancellation, and creates no live resources.
+Live execution requires separate owner authorization for the concrete account,
+project, bounds, cost ceiling and cleanup. Keep its evidence outside the checkout.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { type McpClientConnectionDefinition } from "eve/connections";
+import { defineDynamic as defineDynamicConnection, type DynamicContext, type McpClientConnectionDefinition } from "eve/connections";
 import { type Approval, type ApprovalPolicy } from "eve/tools/approval";
 /** Where an Eve agent reaches Connecta and how it proves who it is. */
 export interface ConnectaEndpointOptions {
@@ -15,7 +15,11 @@ export interface ConnectaEndpointOptions {
      */
     getToken?: () => string | Promise<string>;
 }
-export interface ConnectaConnectionOptions extends ConnectaEndpointOptions {
+/** App-owned pool policy; use `ctx.memo` when its result should stay fixed. */
+export type ConnectaPoolSelector = (ctx: DynamicContext) => string | Promise<string>;
+export interface ConnectaConnectionOptions extends Omit<ConnectaEndpointOptions, "pool"> {
+    /** A fixed pool, or a policy Eve evaluates before every model call. */
+    pool?: string | ConnectaPoolSelector;
     /** What the connection offers, for the model choosing which connection to search. */
     description: string;
     /** Eve's approval for every Connecta tool: a policy or configuration. Defaults to `never()`. */
@@ -27,7 +31,11 @@ export interface ConnectaConnectionOptions extends ConnectaEndpointOptions {
      */
     gateWrites?: boolean;
 }
-export interface ConnectaInstructionsOptions extends ConnectaEndpointOptions {
+export interface ConnectaInstructionsOptions extends Omit<ConnectaEndpointOptions, "pool"> {
+    /** A fixed pool, or the same policy used by the connection. */
+    pool?: string | ConnectaPoolSelector;
+    /** MCP client name for instruction requests. Default `connecta-eve-instructions`. */
+    clientName?: string;
     /** How long fetched instructions are reused. Default ten minutes. */
     ttlMs?: number;
     /** Fetch implementation, for tests. */
@@ -44,12 +52,19 @@ export declare const gateConnectaWrites: ApprovalPolicy;
  * The Eve connection for a Connecta agent endpoint, with app-owned auth:
  * one agent token, sent as a bearer and re-read on every request.
  */
-export declare function connectaConnection(options: ConnectaConnectionOptions): McpClientConnectionDefinition;
+export declare function connectaConnection(options: ConnectaConnectionOptions & {
+    pool: ConnectaPoolSelector;
+}): ReturnType<typeof defineDynamicConnection>;
+export declare function connectaConnection(options: ConnectaConnectionOptions & {
+    pool?: string;
+}): McpClientConnectionDefinition;
+export declare function connectaConnection(options: ConnectaConnectionOptions): McpClientConnectionDefinition | ReturnType<typeof defineDynamicConnection>;
 /**
  * Connecta's instructions as Eve system instructions, refreshed once per turn.
  * Eve does not pass an MCP server's `instructions` to the model, so this
  * fetches them and caches each success; a failure keeps the last copy, or adds
  * nothing, and the tools still work. Eve evaluates the resolver before every
- * model call; a memo keyed on the turn keeps one result for the whole turn.
+ * model call; a memo keyed on the endpoint and turn keeps one result for each.
+ * Pool policy runs independently of the connection and owns its memo lifetime.
  */
-export declare function connectaInstructions(options?: ConnectaInstructionsOptions): import("eve/connections").DynamicSentinel<import("eve/instructions").DynamicInstructionsResult, import("eve/connections").DynamicContext>;
+export declare function connectaInstructions(options?: ConnectaInstructionsOptions): import("eve/connections").DynamicSentinel<import("eve/instructions").DynamicInstructionsResult, DynamicContext>;

package/dist/index.js

@@ -1,10 +1,15 @@
-import { defineMcpClientConnection } from "eve/connections";
+import { defineDynamic as defineDynamicConnection, defineMcpClientConnection, } from "eve/connections";
 import { defineDynamic, defineInstructions } from "eve/instructions";
 import { never } from "eve/tools/approval";
 function environment(name) {
     const value = globalThis.process?.env?.[name];
     return value?.trim() || undefined;
 }
+function validatePool(pool) {
+    if (typeof pool !== "string" || !/^[a-z0-9_-]+$/.test(pool)) {
+        throw new Error(`Connecta pool "${pool}" must match [a-z0-9_-]+.`);
+    }
+}
 /** The endpoint URL these options name. */
 export function connectaEndpoint(options = {}) {
     const url = options.url ?? environment("CONNECTA_URL");
@@ -12,8 +17,7 @@ export function connectaEndpoint(options = {}) {
         throw new Error("Connecta needs a url, or CONNECTA_URL in the environment.");
     if (options.pool === undefined)
         return url;
-    if (!/^[a-z0-9_-]+$/.test(options.pool))
-        throw new Error(`Connecta pool "${options.pool}" must match [a-z0-9_-]+.`);
+    validatePool(options.pool);
     return `${url.replace(/\/+$/, "")}/agent/${options.pool}`;
 }
 async function tokenFor(options) {
@@ -27,13 +31,21 @@ async function tokenFor(options) {
  * annotations Connecta derives from its own classification.
  */
 export const gateConnectaWrites = ({ toolAnnotations }) => toolAnnotations?.readOnlyHint === true ? "not-applicable" : "user-approval";
-/**
- * The Eve connection for a Connecta agent endpoint, with app-owned auth:
- * one agent token, sent as a bearer and re-read on every request.
- */
 export function connectaConnection(options) {
+    const { pool, ...rest } = options;
+    if (typeof pool === "function") {
+        return defineDynamicConnection(async (ctx) => {
+            const selected = await pool(ctx);
+            validatePool(selected);
+            return connectionDefinition(options, connectaEndpoint({ ...rest, pool: selected }), selected);
+        });
+    }
+    return connectionDefinition(options, connectaEndpoint(pool === undefined ? rest : { ...rest, pool }));
+}
+function connectionDefinition(options, endpoint, instanceKey) {
     return defineMcpClientConnection({
-        url: connectaEndpoint(options),
+        url: endpoint,
+        ...(instanceKey === undefined ? {} : { instanceKey }),
         description: options.description,
         auth: {
             principalType: "app",
@@ -43,9 +55,10 @@ export function connectaConnection(options) {
     });
 }
 /** Connecta's MCP `instructions` for one endpoint, or null when unavailable. */
-async function instructionRequest(options, method, signal) {
+async function instructionRequest(options, endpoint, method, signal) {
     const modern = method === "server/discover";
-    const response = await (options.fetch ?? fetch)(connectaEndpoint(options), {
+    const clientInfo = { name: options.clientName ?? "connecta-eve-instructions", version: "1" };
+    const response = await (options.fetch ?? fetch)(endpoint, {
         method: "POST",
         headers: {
             Authorization: `Bearer ${await tokenFor(options)}`,
@@ -62,13 +75,13 @@ async function instructionRequest(options, method, signal) {
                     _meta: {
                         "io.modelcontextprotocol/protocolVersion": "2026-07-28",
                         "io.modelcontextprotocol/clientCapabilities": {},
-                        "io.modelcontextprotocol/clientInfo": { name: "connecta-eve-instructions", version: "1" },
+                        "io.modelcontextprotocol/clientInfo": clientInfo,
                     },
                 }
                 : {
                     protocolVersion: "2025-06-18",
                     capabilities: {},
-                    clientInfo: { name: "connecta-eve-instructions", version: "1" },
+                    clientInfo,
                 },
         }),
         signal: AbortSignal.any([signal, AbortSignal.timeout(5_000)]),
@@ -88,32 +101,36 @@ async function instructionRequest(options, method, signal) {
     const instructions = JSON.parse(json).result?.instructions;
     return typeof instructions === "string" && instructions.trim() ? instructions.trim() : null;
 }
-async function fetchConnectaInstructions(options, signal) {
+async function fetchConnectaInstructions(options, endpoint, signal) {
     // Only a completed discovery response can justify legacy negotiation.
     // Network failures and timeouts propagate to the resolver's fail-open path.
-    const discovered = await instructionRequest(options, "server/discover", signal);
-    return discovered ?? instructionRequest(options, "initialize", signal);
+    const discovered = await instructionRequest(options, endpoint, "server/discover", signal);
+    return discovered ?? instructionRequest(options, endpoint, "initialize", signal);
 }
 /**
  * Connecta's instructions as Eve system instructions, refreshed once per turn.
  * Eve does not pass an MCP server's `instructions` to the model, so this
  * fetches them and caches each success; a failure keeps the last copy, or adds
  * nothing, and the tools still work. Eve evaluates the resolver before every
- * model call; a memo keyed on the turn keeps one result for the whole turn.
+ * model call; a memo keyed on the endpoint and turn keeps one result for each.
+ * Pool policy runs independently of the connection and owns its memo lifetime.
  */
 export function connectaInstructions(options = {}) {
     const ttlMs = options.ttlMs ?? 600_000;
-    let cached;
-    let retryAfter = 0;
-    const current = async (signal) => {
+    const endpoints = new Map();
+    const current = async (endpoint, signal) => {
         signal.throwIfAborted();
+        let state = endpoints.get(endpoint);
+        if (!state)
+            endpoints.set(endpoint, (state = { retryAfter: 0 }));
+        const { cached, retryAfter } = state;
         if (cached && Date.now() - cached.at <= ttlMs)
             return cached.content;
         if (Date.now() < retryAfter)
             return cached?.content ?? null;
         let fresh;
         try {
-            fresh = await fetchConnectaInstructions(options, signal);
+            fresh = await fetchConnectaInstructions(options, endpoint, signal);
         }
         catch {
             // Eve's cancellation is not an endpoint failure: rethrowing keeps it out
@@ -122,12 +139,28 @@ export function connectaInstructions(options = {}) {
             fresh = null;
         }
         if (fresh)
-            cached = { at: Date.now(), content: fresh };
-        retryAfter = fresh ? 0 : Date.now() + 30_000;
+            state.cached = { at: Date.now(), content: fresh };
+        state.retryAfter = fresh ? 0 : Date.now() + 30_000;
         return fresh ?? cached?.content ?? null;
     };
     return defineDynamic(async (ctx) => {
-        const content = await ctx.memo(["connecta-instructions", ctx.turn?.id ?? null], ({ abortSignal }) => current(abortSignal));
+        const { pool, ...rest } = options;
+        let endpoint;
+        if (typeof pool === "function") {
+            const selected = await pool(ctx);
+            validatePool(selected);
+            endpoint = connectaEndpoint({ ...rest, pool: selected });
+        }
+        else {
+            // Static configuration errors have always omitted optional guidance.
+            try {
+                endpoint = connectaEndpoint(pool === undefined ? rest : { ...rest, pool });
+            }
+            catch {
+                return null;
+            }
+        }
+        const content = await ctx.memo(["connecta-instructions", endpoint, ctx.turn?.id ?? null], ({ abortSignal }) => current(endpoint, abortSignal));
         return content ? defineInstructions({ content: `Connecta guidance:\n${content}` }) : null;
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta-eve",
-  "version": "0.36.0",
+  "version": "0.36.2",
   "type": "module",
   "sideEffects": false,
   "description": "Eve connection and instructions helpers for Connecta agent endpoints.",