@zackbart/connecta-eve 0.39.0 → 0.41.0

package/README.md

@@ -4,15 +4,16 @@ Connect an Eve agent to a Connecta agent pool and load its endpoint instructions
 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.90.0 <0.91.0**. Development and consumer
-checks use real Eve 0.90.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.
+Requires **Node 24+** and **Eve 1.0.0-rc.1**. Development and consumer
+checks use that exact release candidate. The peer stays pinned during the RC
+period; later candidates and stable 1.0 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.90.0
+npm install @zackbart/connecta-eve eve@1.0.0-rc.1
 ```
 
 The server must declare your agent, admit it to the named pool and issue its
@@ -89,6 +90,48 @@ 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.
 
+## Gating guidance and connections
+
+Pass `when(ctx)` to load guidance only for eligible callers or turns. The helper
+runs this predicate inside Eve's dynamic definition before selecting a pool,
+reading a token, or using cached guidance. False or a thrown/rejected predicate
+returns no guidance and performs no guidance fetch. It is evaluated before
+every model call, including repeated evaluations within a turn.
+
+```ts
+export default connectaInstructions({
+  pool: "assistant",
+  when: (ctx) => ctx.session.auth.current?.principalId === "alice",
+});
+```
+
+`connectaConnection` accepts the same predicate and returns a dynamic connection
+when it is provided. False or a policy failure removes that connection for the
+current evaluation. The two factories evaluate their predicates independently;
+use consistent trusted policy data as with a dynamic pool selector. This policy
+controls what the app offers; Connecta still enforces endpoint authorization.
+No Eve dynamic-value unwrapping is required.
+
+## Upgrading to Eve 1.0 RC
+
+Update the app to `eve@1.0.0-rc.1` and reinstall to refresh its lockfile.
+The helper's connection, dynamic pool, instructions and approval APIs use Eve's
+stable entry points and require no authoring changes for this RC. Eve's
+[1.0 stability policy](https://eve.dev/docs/reference/typescript-api#stability-policy)
+does not cover `experimental` fields or internal modules.
+
+From 0.90, review the intervening
+[release notes](https://github.com/vercel/eve/blob/eve%401.0.0-rc.1/packages/eve/CHANGELOG.md):
+`session.clear()` now cancels running turns and tasks, and object-form connection
+approvals are now preserved at runtime. RC.1 also requires `@vercel/connect`
+`^2.7.0` when that optional integration is installed; older Connect releases
+reject the prerelease Eve peer.
+
+For older apps, follow Eve's [Upgrade to 1.0](https://eve.dev/docs/guides/upgrade)
+guide for event consumers, saved history, extensions and client APIs.
+Build and test the app before deploying it. The helper does not migrate those
+app-owned surfaces.
+
 ## Upgrading from Eve 0.86
 
 Eve 0.88.1 and later pin undici 8.12.3, so the app no longer needs its own undici
@@ -182,9 +225,9 @@ custom audience, even when Vercel signed them.
 
 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.90.0 with a packed, installed helper against
+on Node 24. This boots real Eve 1.0.0-rc.1 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
+meta, native, and native-plus-code surfaces. Native listings include three
 Connecta tools beyond the downstream count. A 1,001-tool native catalog must
 refuse listing. `--counts 40,1000` selects a smaller matrix.
 
@@ -203,3 +246,30 @@ 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.
+
+### Deferred connector guide (opt-in)
+
+In `agent/skills/crm.ts`:
+
+```ts
+import { connectaSkill } from "@zackbart/connecta-eve";
+
+export default connectaSkill({
+  pool: "crm",
+  name: "connector:crm",
+  description: "Use when working with CRM person identifiers and conventions.",
+  when: (ctx) => ctx.session.auth !== null,
+});
+```
+
+This uses the pinned Eve 1.0.0-rc.1 public `defineSkill` and `defineDynamic`
+APIs. Eve's deferred discovery searches the description; loading adds only
+instructions. It never installs tools. Use the same caller predicate and pool
+selector as the connection. A false or throwing predicate skips selection,
+token resolution and fetching. The public API accepts content rather than a
+load callback, so fetching happens once per endpoint/guide/turn through Eve's
+session memo; inclusion in model context is lazy. Failed responses omit the
+skill, including network, timeout and malformed-response failures; turn
+cancellation still propagates. A successful guide can be reused while the same
+endpoint/guide/turn memo is retained. A new turn fetches again; failure removes
+the skill rather than serving the prior turn's guide. The guide must already be visible through that endpoint's `skills` tool.

package/dist/index.d.ts

@@ -17,9 +17,13 @@ export interface ConnectaEndpointOptions {
 }
 /** App-owned pool policy; use `ctx.memo` when its result should stay fixed. */
 export type ConnectaPoolSelector = (ctx: DynamicContext) => string | Promise<string>;
+/** App-owned caller/turn policy, evaluated before selecting a pool or fetching guidance. */
+export type ConnectaPredicate = (ctx: DynamicContext) => boolean | Promise<boolean>;
 export interface ConnectaConnectionOptions extends Omit<ConnectaEndpointOptions, "pool"> {
     /** A fixed pool, or a policy Eve evaluates before every model call. */
     pool?: string | ConnectaPoolSelector;
+    /** Omit this value when false or when the policy throws. Evaluated every model call. */
+    when?: ConnectaPredicate;
     /** 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()`. */
@@ -34,6 +38,8 @@ export interface ConnectaConnectionOptions extends Omit<ConnectaEndpointOptions,
 export interface ConnectaInstructionsOptions extends Omit<ConnectaEndpointOptions, "pool"> {
     /** A fixed pool, or the same policy used by the connection. */
     pool?: string | ConnectaPoolSelector;
+    /** Omit this value when false or when the policy throws. Evaluated every model call. */
+    when?: ConnectaPredicate;
     /** MCP client name for instruction requests. Default `connecta-eve-instructions`. */
     clientName?: string;
     /** How long fetched instructions are reused. Default ten minutes. */
@@ -52,11 +58,15 @@ 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 & {
+    when: ConnectaPredicate;
+}): ReturnType<typeof defineDynamicConnection>;
 export declare function connectaConnection(options: ConnectaConnectionOptions & {
     pool: ConnectaPoolSelector;
 }): ReturnType<typeof defineDynamicConnection>;
 export declare function connectaConnection(options: ConnectaConnectionOptions & {
     pool?: string;
+    when?: undefined;
 }): McpClientConnectionDefinition;
 export declare function connectaConnection(options: ConnectaConnectionOptions): McpClientConnectionDefinition | ReturnType<typeof defineDynamicConnection>;
 /**
@@ -67,4 +77,18 @@ export declare function connectaConnection(options: ConnectaConnectionOptions):
  * 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, DynamicContext>;
+export declare function connectaInstructions(options?: ConnectaInstructionsOptions): import("eve/skills").DynamicSentinel<import("eve/instructions").DynamicInstructionsResult, DynamicContext>;
+/** One explicitly selected Connecta guide projected as a deferred Eve skill. */
+export interface ConnectaSkillOptions extends ConnectaInstructionsOptions {
+    /** Exact skills-tool name, for example `connector:crm`. */
+    name: string;
+    /** Short task selector Eve can search without loading the guide. */
+    description: string;
+}
+/**
+ * Opt-in deferred instructions, installed from an agent/skills module.
+ * Resolves only after caller policy, with no tools added by loading the skill.
+ * Eve's public API takes content, not a load callback: fetching is per turn;
+ * only model-context inclusion is lazy.
+ */
+export declare function connectaSkill(options: ConnectaSkillOptions): import("eve/skills").DynamicSentinel<import("eve/skills").DynamicSkillResult, DynamicContext>;

package/dist/index.js

@@ -1,3 +1,4 @@
+import { defineDynamic as defineDynamicSkill, defineSkill } from "eve/skills";
 import { defineDynamic as defineDynamicConnection, defineMcpClientConnection, } from "eve/connections";
 import { defineDynamic, defineInstructions } from "eve/instructions";
 import { never } from "eve/tools/approval";
@@ -33,11 +34,18 @@ async function tokenFor(options) {
 export const gateConnectaWrites = ({ toolAnnotations }) => toolAnnotations?.readOnlyHint === true ? "not-applicable" : "user-approval";
 export function connectaConnection(options) {
     const { pool, ...rest } = options;
-    if (typeof pool === "function") {
+    if (typeof pool === "function" || options.when) {
         return defineDynamicConnection(async (ctx) => {
-            const selected = await pool(ctx);
-            validatePool(selected);
-            return connectionDefinition(options, connectaEndpoint({ ...rest, pool: selected }), selected);
+            if (!(await enabled(options.when, ctx)))
+                return null;
+            // Only a static `pool` may be omitted; connectaEndpoint validates it. A
+            // selector must name a valid pool, or the turn fails instead of using the base URL.
+            let selected = pool;
+            if (typeof pool === "function") {
+                selected = await pool(ctx);
+                validatePool(selected);
+            }
+            return connectionDefinition(options, connectaEndpoint({ ...rest, ...(selected === undefined ? {} : { pool: selected }) }), selected);
         });
     }
     return connectionDefinition(options, connectaEndpoint(pool === undefined ? rest : { ...rest, pool }));
@@ -54,6 +62,14 @@ function connectionDefinition(options, endpoint, instanceKey) {
         approval: options.approval ?? (options.gateWrites ? gateConnectaWrites : never()),
     });
 }
+async function enabled(when, ctx) {
+    try {
+        return when ? (await when(ctx)) === true : true;
+    }
+    catch {
+        return false;
+    }
+}
 /** Connecta's MCP `instructions` for one endpoint, or null when unavailable. */
 async function instructionRequest(options, endpoint, method, signal) {
     const modern = method === "server/discover";
@@ -144,6 +160,8 @@ export function connectaInstructions(options = {}) {
         return fresh ?? cached?.content ?? null;
     };
     return defineDynamic(async (ctx) => {
+        if (!(await enabled(options.when, ctx)))
+            return null;
         const { pool, ...rest } = options;
         let endpoint;
         if (typeof pool === "function") {
@@ -164,3 +182,75 @@ export function connectaInstructions(options = {}) {
         return content ? defineInstructions({ content: `Connecta guidance:\n${content}` }) : null;
     });
 }
+/**
+ * Opt-in deferred instructions, installed from an agent/skills module.
+ * Resolves only after caller policy, with no tools added by loading the skill.
+ * Eve's public API takes content, not a load callback: fetching is per turn;
+ * only model-context inclusion is lazy.
+ */
+export function connectaSkill(options) {
+    if (!options.name.trim() || !options.description.trim())
+        throw new Error("A skill needs a name and description.");
+    return defineDynamicSkill(async (ctx) => {
+        if (!(await enabled(options.when, ctx)))
+            return null;
+        const { pool, ...endpointOptions } = options;
+        const selected = typeof pool === "function" ? await pool(ctx) : pool;
+        if (typeof options.pool === "function")
+            validatePool(selected);
+        const endpoint = connectaEndpoint({ ...endpointOptions, ...(selected === undefined ? {} : { pool: selected }) });
+        const content = await ctx.memo(["connecta-skill", endpoint, options.name, ctx.turn?.id ?? null], async ({ abortSignal }) => {
+            try {
+                const response = await (options.fetch ?? fetch)(endpoint, {
+                    method: "POST",
+                    headers: {
+                        Authorization: `Bearer ${await tokenFor(options)}`,
+                        "Content-Type": "application/json",
+                        Accept: "application/json, text/event-stream",
+                        "MCP-Protocol-Version": "2026-07-28",
+                        "Mcp-Method": "tools/call",
+                        "Mcp-Name": "skills",
+                    },
+                    body: JSON.stringify({
+                        jsonrpc: "2.0",
+                        id: 1,
+                        method: "tools/call",
+                        params: {
+                            name: "skills",
+                            arguments: { name: options.name },
+                            _meta: {
+                                "io.modelcontextprotocol/protocolVersion": "2026-07-28",
+                                "io.modelcontextprotocol/clientCapabilities": {},
+                            },
+                        },
+                    }),
+                    signal: AbortSignal.any([abortSignal, AbortSignal.timeout(5_000)]),
+                });
+                if (!response.ok)
+                    return null;
+                const text = await response.text();
+                const json = text.trimStart().startsWith("{")
+                    ? text
+                    : text
+                        .split("\n")
+                        .find((line) => line.startsWith("data:"))
+                        ?.slice(5);
+                if (!json)
+                    return null;
+                const reply = JSON.parse(json);
+                if (!reply.result || reply.result.isError)
+                    return null;
+                return (reply.result.content
+                    ?.filter((block) => block.type === "text")
+                    .map((block) => block.text ?? "")
+                    .join("\n") || null);
+            }
+            catch {
+                // Endpoint failures omit optional guidance; turn cancellation still propagates.
+                abortSignal.throwIfAborted();
+                return null;
+            }
+        });
+        return content ? defineSkill({ description: options.description, content, deferred: true }) : null;
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta-eve",
-  "version": "0.39.0",
+  "version": "0.41.0",
   "type": "module",
   "sideEffects": false,
   "description": "Eve connection and instructions helpers for Connecta agent endpoints.",
@@ -28,11 +28,11 @@
     }
   },
   "peerDependencies": {
-    "eve": ">=0.90.0 <0.91.0"
+    "eve": "1.0.0-rc.1"
   },
   "devDependencies": {
     "@types/node": "^24.19.2",
-    "eve": "0.90.0",
+    "eve": "1.0.0-rc.1",
     "typescript": "^6.0.3",
     "vite": "^8.3.4",
     "vitest": "^5.0.4"