@zackbart/connecta-eve 0.35.0 → 0.36.1

package/README.md

@@ -1,18 +1,18 @@
 # @zackbart/connecta-eve
 
 Connect an Eve agent to a Connecta agent pool and load its endpoint instructions
-at the start of each turn. The helper runs in the Eve app; the Connecta server
+once per turn. The helper runs in the Eve app; the Connecta server
 runs separately. No `@zackbart/connecta` dependency is installed by this package.
 
-Requires **Node 24+** and **Eve >=0.83.0 <0.84.0**. Development and consumer
-checks use real Eve 0.83.0. The range covers its patch line; newer minor releases
+Requires **Node 24+** and **Eve >=0.84.0 <0.85.0**. Development and consumer
+checks use real Eve 0.84.0. The range covers its patch line; newer minor releases
 need a compatibility check. Helper releases share Connecta's version and tag;
 choose the helper version matching your server release.
 
 ## Install and add two files
 
 ```sh
-npm install @zackbart/connecta-eve eve@0.83.0
+npm install @zackbart/connecta-eve eve@0.84.0
 ```
 
 The server must declare your agent, admit it to the named pool and issue its
@@ -55,9 +55,43 @@ 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.
 
-## Eve 0.83.0 dependency override
+## Choosing the pool at runtime
 
-Eve 0.83.0 pins undici 8.10.2. Connecta's development/test override does not ship
+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
 with this helper, so the Eve app must apply its own override to 8.12.3 before
 installing. For an npm app, add this to its `package.json`, then reinstall and
 commit the lockfile:
@@ -66,7 +100,7 @@ commit the lockfile:
 { "overrides": { "eve": { "undici": "8.12.3" } } }
 ```
 
-For a pnpm app, add `overrides: { "eve@0.83.0>undici": "8.12.3" }` to its
+For a pnpm app, add `overrides: { "eve@0.84.0>undici": "8.12.3" }` to its
 `pnpm-workspace.yaml`. Check the resolved dependency graph and audit the app.
 Remove this override after upgrading to an Eve release that pins a fixed version
 and validating compatibility. The server's optional undici 6.29.1 peer is a
@@ -79,7 +113,8 @@ read-only Connecta pool when the agent must never write. For an interactive
 agent, add `gateWrites: true` to the connection to request user approval before
 any tool whose `readOnlyHint` is not `true`, including writable `execute_code`.
 `gateConnectaWrites` exports that policy for composition. An explicit Eve
-`approval` policy takes precedence over `gateWrites`.
+`approval`, either a policy or an approval configuration, takes precedence over
+`gateWrites`.
 
 The gate uses the host's cached annotations. If a read becomes a write before
 dispatch, Connecta applies its current classification; a writable pool can
@@ -92,9 +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. 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
 
@@ -124,12 +169,14 @@ 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
 
 In a source checkout with dependencies installed and both packages built, run
 `pnpm --filter @zackbart/connecta-eve run probe:catalog --output /absolute/path/outside/checkout`
-on Node 24. This boots real Eve 0.83.0 with a packed, installed helper against
+on Node 24. This boots real Eve 0.84.0 with a packed, installed helper against
 seeded local catalogs of 40, 100, 250, 500, and 1,000 downstream tools on the
 meta, native, and native-plus-code surfaces. Native listings include two
 Connecta tools beyond the downstream count. A 1,001-tool native catalog must
@@ -143,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,5 +1,5 @@
-import { type McpClientConnectionDefinition } from "eve/connections";
-import { type ApprovalPolicy } from "eve/tools/approval";
+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,11 +15,15 @@ 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 policy for every Connecta tool. Defaults to `never()`. */
-    approval?: ApprovalPolicy;
+    /** Eve's approval for every Connecta tool: a policy or configuration. Defaults to `never()`. */
+    approval?: Approval;
     /**
      * Ask a person before every tool not annotated read-only: each write tool
      * on a native endpoint, and `execute_code` on a writable one. Ignored when
@@ -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,11 +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 at turn start.
+ * 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.
+ * nothing, and the tools still work. Eve evaluates the resolver before every
+ * 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>;
+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,25 +31,34 @@ 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: {
-            credentialOwner: "app",
+            principalType: "app",
             getToken: async () => ({ token: await tokenFor(options) }),
         },
         approval: options.approval ?? (options.gateWrites ? gateConnectaWrites : never()),
     });
 }
 /** Connecta's MCP `instructions` for one endpoint, or null when unavailable. */
-async function instructionRequest(options, method) {
+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,16 +75,16 @@ async function instructionRequest(options, method) {
                     _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.timeout(5_000),
+        signal: AbortSignal.any([signal, AbortSignal.timeout(5_000)]),
     });
     if (!response.ok)
         return null;
@@ -88,39 +101,66 @@ async function instructionRequest(options, method) {
     const instructions = JSON.parse(json).result?.instructions;
     return typeof instructions === "string" && instructions.trim() ? instructions.trim() : null;
 }
-async function fetchConnectaInstructions(options) {
+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");
-    return discovered ?? instructionRequest(options, "initialize");
+    const discovered = await instructionRequest(options, endpoint, "server/discover", signal);
+    return discovered ?? instructionRequest(options, endpoint, "initialize", signal);
 }
 /**
- * Connecta's instructions as Eve system instructions, refreshed at turn start.
+ * 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.
+ * nothing, and the tools still work. Eve evaluates the resolver before every
+ * 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 () => {
+    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;
-        const fresh = await fetchConnectaInstructions(options).catch(() => null);
+        let fresh;
+        try {
+            fresh = await fetchConnectaInstructions(options, endpoint, signal);
+        }
+        catch {
+            // Eve's cancellation is not an endpoint failure: rethrowing keeps it out
+            // of the memo and the backoff, which every session of this resolver shares.
+            signal.throwIfAborted();
+            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({
-        events: {
-            "turn.started": async () => {
-                const content = await current();
-                return content ? defineInstructions({ content: `Connecta guidance:\n${content}` }) : null;
-            },
-        },
+    return defineDynamic(async (ctx) => {
+        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.35.0",
+  "version": "0.36.1",
   "type": "module",
   "sideEffects": false,
   "description": "Eve connection and instructions helpers for Connecta agent endpoints.",
@@ -28,11 +28,11 @@
     }
   },
   "peerDependencies": {
-    "eve": ">=0.83.0 <0.84.0"
+    "eve": ">=0.84.0 <0.85.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
-    "eve": "0.83.0",
+    "eve": "0.84.0",
     "typescript": "^5.9.3",
     "vitest": "^4.1.6"
   },