@zackbart/connecta-eve 0.40.0 → 0.42.0

package/README.md

@@ -4,7 +4,7 @@ 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 1.0.0-rc.1**. Development and consumer
+Requires **Node 24+** and **Eve 1.0.0-rc.4**. 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
@@ -13,7 +13,7 @@ your server release.
 ## Install and add two files
 
 ```sh
-npm install @zackbart/connecta-eve eve@1.0.0-rc.1
+npm install @zackbart/connecta-eve eve@1.0.0-rc.4
 ```
 
 The server must declare your agent, admit it to the named pool and issue its
@@ -31,10 +31,7 @@ Create `agent/connections/connecta.ts`:
 ```ts
 import { connectaConnection } from "@zackbart/connecta-eve";
 
-export default connectaConnection({
-  pool: "assistant",
-  description: "Shared CRM and tickets for the assistant.",
-});
+export default connectaConnection({ pool: "assistant" });
 ```
 
 Create `agent/instructions/connecta.ts`:
@@ -45,6 +42,25 @@ import { connectaInstructions } from "@zackbart/connecta-eve";
 export default connectaInstructions({ pool: "assistant" });
 ```
 
+`description` is optional. Eve shows it in its catalog listing and matches its
+words against every search query for every tool of the connection, so the default
+is a fixed neutral line. If you set one, describe the domain in prose, such as
+`"Member records, giving and event registration."`. Do not list connectors or
+operations: on a three-connector meta pool, `"CRM, invoices and tickets"` made the
+query `"invoices"` return all six routing tools, 9.4 KB measured, and tells the
+model nothing about the operations behind them. The instructions carry the roster.
+A string such as
+`"Company tools through Connecta"` tells the model nothing, so the helper warns
+at startup.
+
+Eve names a connection after its file. If yours is not `connecta.ts`, say so in
+the instructions, or the model is told tool names that do not exist:
+
+```ts
+// agent/connections/workspace.ts gives the model workspace__* tools.
+export default connectaInstructions({ pool: "assistant", connection: "workspace" });
+```
+
 Both factories accept `url` to override `CONNECTA_URL`. With `pool`, the URL is
 `<url>/agent/<pool>`; without `pool`, supply the complete endpoint URL. Pool
 names must match `[a-z0-9_-]+`. `connectaEndpoint({ url, pool })` returns the same
@@ -56,6 +72,16 @@ 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.
 
+`headers` adds request headers beside the bearer, such as a service token for an
+edge in front of Connecta. Pass the same value to every factory. A function runs
+for each request, so a rotated secret needs no restart. On guidance and skill
+requests, the helper's own `Authorization` and MCP protocol headers always win.
+
+```ts
+const headers = () => ({ "X-Edge-Token": process.env.EDGE_TOKEN ?? "" });
+export default connectaConnection({ pool: "assistant", headers });
+```
+
 ## Choosing the pool at runtime
 
 Pass the same selector to both factories when the pool depends on the chat.
@@ -90,16 +116,62 @@ 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.
 
-## Upgrading to Eve 1.0 RC
+## 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.
 
-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
+```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.0-rc.4
+
+Update the app to `eve@1.0.0-rc.4`, reinstall to refresh its lockfile, then
+rebuild and test it before deploying. 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):
+From rc.1, review Eve's
+[rc.2](https://github.com/vercel/eve/releases/tag/eve%401.0.0-rc.2),
+[rc.3](https://github.com/vercel/eve/releases/tag/eve%401.0.0-rc.3) and
+[rc.4](https://github.com/vercel/eve/releases/tag/eve%401.0.0-rc.4) release notes.
+These change app-owned code and deployments the helper does not manage:
+
+- **Rollback.** Session checkpoints move to version 19 (rc.3). A deployment from
+  before rc.3 refuses to take over a session rc.3 or later wrote, so that session
+  stays on the deployment that wrote it. New runs also use Workflow spec 9; set
+  `WORKFLOW_SPEC_VERSION=8` to keep creating spec 8 runs.
+- **File tools.** Every agent gets a default `edit_file` tool (rc.4) that changes
+  sandbox files without `write_file`. If you disable, wrap or gate `write_file`,
+  do the same for `edit_file`. Connecta's own tools are unaffected.
+- **Builds.** Eve moves to a Nitro 3 release candidate and declares Rolldown
+  itself (rc.3). Importing `nitro/storage`, `nitro/kv` or `nitro/database` from
+  agent code now fails the build, as does an asset import that leaves the authored
+  package.
+- **Code extension.** `code__grep`, `code__worker` and `code__apply_patch` are gone
+  (rc.3, rc.4). Follow Eve's notes if your app mounts `eve/extensions/code`.
+- **Dynamic tools.** A dynamic tool no longer replaces a static tool of the same
+  name (rc.3). Dynamic connections, including this helper's, still override a
+  static connection of the same name.
+
+From 0.90, also review the
+[rc.1 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
@@ -143,12 +215,38 @@ any tool whose `readOnlyHint` is not `true`, including writable `execute_code`.
 `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
-execute the write without a fresh approval. A read-only pool refuses it.
+An agent-wide `approval` in Eve's `agent.ts` runs beside the connection's policy
+and the stricter result wins. It can add a gate to Connecta tools, including under
+the default `never()`, and cannot remove one that `gateWrites` set.
+
+The gate uses the host's cached annotations. If a native tool becomes a write, its cached read name is refused before dispatch. Refresh `tools/list` and use the write's name; approval follows the host's policy. Read-only pools refuse writes.
 
 ## Endpoint instructions
 
+Eve hides MCP tools behind `eve__tool` under a `<connection>__` prefix, and
+`eve__search` covers listed tools only. Connecta's text is host-neutral, so the
+helper places an Eve guide before it, built from the endpoint's
+[facts](https://github.com/zackbart/connecta/blob/main/documentation/meta-tools.md#endpoint-facts):
+
+- **Meta pools:** call `eve__tool({ name: "connecta__execute_code", input })`
+  directly, with a short example program. `eve__search` sees the routing tools and
+  never a downstream operation, so its empty result does not mean a capability is
+  missing. Reachable connectors are listed by id.
+- **Native pools:** a read is `connecta__<connector>__<tool>` and a write
+  `connecta__<connector>__WRITE__<tool>`. Scope a search with
+  `"connecta__<connector>__"`, use `execute_code` for several, dependent or reduced
+  calls (omitted when the pool has none), and when tools are missing get a link from
+  `connecta__authorize_connector` for the user or operator. Eve lists tools again on
+  each step, so the repair needs no reconnect, unlike a host that keeps its first
+  list.
+- **Older servers without facts:** only the naming rule.
+
+The guide adds about 600 bytes with three connectors. Its roster stays under 512
+bytes: titles go first, then whole entries give way to a `+N more` count. Names
+in Connecta's text and in `nextAction` stay unprefixed, and the guide says so.
+The helper warns once per endpoint when a server named `connecta` is on a
+different major or minor release from the helper.
+
 Instructions use `server/discover` (MCP 2026-07-28), falling back to legacy
 `initialize` when discovery returns a response without guidance, including a
 non-OK status or an unsupported-method response. Network errors and timeouts
@@ -203,7 +301,7 @@ 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 1.0.0-rc.1 with a packed, installed helper against
+on Node 24. This boots real Eve 1.0.0-rc.4 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 three
 Connecta tools beyond the downstream count. A 1,001-tool native catalog must
@@ -213,8 +311,11 @@ The probe uses Eve's public language-model interface with a deterministic local
 transport, without model credentials or paid calls. It measures construction,
 cold and warm discovery, schema and result bytes, call counts, concurrent-call
 isolation, bounded-result paging, and process memory. Fresh child processes
-isolate each matrix cell; Eve startup is separate from turn latency. Reports
-retain actual Eve events and transport inputs. Token usage and model task
+isolate each matrix cell; Eve startup is separate from turn latency. Each turn
+also checks what the helper's guide claims about Eve: guidance arrives as its own
+system message on every model call, `eve__search` on a meta pool reaches only
+routing tools, native writes are named `connecta__<connector>__WRITE__<tool>`, and
+every step lists tools again. 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.
 
@@ -224,3 +325,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.4 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

@@ -14,14 +14,31 @@ export interface ConnectaEndpointOptions {
      * no restart. Defaults to the `CONNECTA_ACCESS_TOKEN` environment variable.
      */
     getToken?: () => string | Promise<string>;
+    /**
+     * Extra request headers, such as a service token for an edge in front of
+     * Connecta. A function is resolved on every request. These never replace
+     * the helper's bearer or MCP protocol headers on guidance requests.
+     */
+    headers?: ConnectaHeaders;
 }
+/** Fixed headers, or a resolver called on every request. */
+export type ConnectaHeaders = Readonly<Record<string, string>> | (() => Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>);
 /** 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;
-    /** What the connection offers, for the model choosing which connection to search. */
-    description: string;
+    /** Omit this value when false or when the policy throws. Evaluated every model call. */
+    when?: ConnectaPredicate;
+    /**
+     * What the connection offers, in Eve's catalog listing and in the words every
+     * tool of this connection matches in `eve__search`. Defaults to a fixed
+     * neutral line. Describe the domain in prose; do not list connectors or
+     * operations here, because a query naming one then matches every tool.
+     */
+    description?: string;
     /** Eve's approval for every Connecta tool: a policy or configuration. Defaults to `never()`. */
     approval?: Approval;
     /**
@@ -34,6 +51,13 @@ 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;
+    /**
+     * The Eve connection's name, which is its file under `agent/connections/`.
+     * The model calls `<connection>__<tool>`. Default `connecta`.
+     */
+    connection?: string;
     /** MCP client name for instruction requests. Default `connecta-eve-instructions`. */
     clientName?: string;
     /** How long fetched instructions are reused. Default ten minutes. */
@@ -52,11 +76,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 +95,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 Omit<ConnectaInstructionsOptions, "connection"> {
+    /** 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,6 +1,8 @@
+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";
+import { CONNECTA_VERSION } from "./version.js";
 function environment(name) {
     const value = globalThis.process?.env?.[name];
     return value?.trim() || undefined;
@@ -32,21 +34,43 @@ async function tokenFor(options) {
  */
 export const gateConnectaWrites = ({ toolAnnotations }) => toolAnnotations?.readOnlyHint === true ? "not-applicable" : "user-approval";
 export function connectaConnection(options) {
+    warnOnGenericDescription(options.description);
     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 }));
 }
+/**
+ * Eve matches these words against every search query, and a short word also
+ * matches longer query words ("use" hits "users"), so this avoids common stems.
+ */
+const DEFAULT_DESCRIPTION = "Connecta integration gateway.";
+/** "Company tools through Connecta" and other strings any Connecta connection could claim. */
+const GENERIC_DESCRIPTION = /\b(?:tools?|services?|integrations?|apps?)\s+(?:through|via|from|using|on|in|with)\s+connecta\b|^\W*(?:(?:the|our|all|my|company|connecta|mcp|tools?|services?|integrations?|connections?|gateway|server|access|through|via|using)\W*)*$/i;
+function warnOnGenericDescription(description) {
+    if (description === undefined || !GENERIC_DESCRIPTION.test(description))
+        return;
+    console.warn(`[connecta-eve] Connection description ${JSON.stringify(description)} gives the model no domain information. Omit it, or say what this agent reaches in prose without listing connectors.`);
+}
 function connectionDefinition(options, endpoint, instanceKey) {
+    const { headers } = options;
     return defineMcpClientConnection({
         url: endpoint,
         ...(instanceKey === undefined ? {} : { instanceKey }),
-        description: options.description,
+        description: options.description ?? DEFAULT_DESCRIPTION,
+        ...(headers === undefined ? {} : { headers: typeof headers === "function" ? () => headers() : headers }),
         auth: {
             principalType: "app",
             getToken: async () => ({ token: await tokenFor(options) }),
@@ -54,18 +78,116 @@ function connectionDefinition(options, endpoint, instanceKey) {
         approval: options.approval ?? (options.gateWrites ? gateConnectaWrites : never()),
     });
 }
-/** Connecta's MCP `instructions` for one endpoint, or null when unavailable. */
+async function enabled(when, ctx) {
+    try {
+        return when ? (await when(ctx)) === true : true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Older servers omit the extension; anything malformed reads the same way. */
+function endpointFacts(value) {
+    const facts = value;
+    if (facts?.surface !== "meta" && facts?.surface !== "native")
+        return undefined;
+    if (typeof facts.executeCode !== "boolean" || !Array.isArray(facts.connectors))
+        return undefined;
+    const text = (field) => (typeof field === "string" ? field.replace(/\s+/g, " ").trim() : "");
+    return {
+        surface: facts.surface,
+        executeCode: facts.executeCode,
+        readOnly: facts.readOnly === true,
+        connectors: facts.connectors.flatMap((connector) => {
+            const id = text(connector?.id);
+            if (!id)
+                return [];
+            const title = text(connector.title);
+            const readFirst = text(connector.readFirst);
+            return [{ id, ...(title ? { title } : {}), ...(readFirst ? { readFirst } : {}) }];
+        }),
+    };
+}
+const ROSTER_MAX_BYTES = 512;
+/** Detail degrades before names do, as the server's own inventory does. */
+function connectorRoster(facts, prefix) {
+    const fits = (line) => new TextEncoder().encode(line).length <= ROSTER_MAX_BYTES;
+    const entry = ({ id, title, readFirst }, withTitle) => {
+        const notes = [
+            ...(withTitle && title ? [title] : []),
+            // A native tool's description already carries its guide pointer.
+            ...(readFirst && facts.surface === "meta" ? [`read first: ${prefix}skills { name: "${readFirst}" }`] : []),
+        ];
+        return notes.length ? `${id} (${notes.join("; ")})` : id;
+    };
+    for (const withTitle of [true, false]) {
+        const line = facts.connectors.map((connector) => entry(connector, withTitle)).join(", ");
+        if (fits(line))
+            return line;
+    }
+    const entries = facts.connectors.map((connector) => entry(connector, false));
+    let shown = 0;
+    while (fits(`${entries.slice(0, shown + 1).join(", ")}; +${entries.length - shown - 1} more`))
+        shown++;
+    return `${entries.slice(0, shown).join(", ")}${shown ? "; " : ""}+${entries.length - shown} more`;
+}
+/**
+ * How Eve's deferred catalog reaches this endpoint's tools. Connecta's own text
+ * names tools as MCP lists them; Eve adds the connection prefix and hides them
+ * behind `eve__tool`, and its search covers listed tools only.
+ */
+function eveGuide(connection, facts) {
+    const prefix = `${connection}__`;
+    if (!facts) {
+        return `Connecta tools are deferred: call eve__tool({ name: "${prefix}<tool>", input }). Names in this guidance and in nextAction omit the "${prefix}" prefix.`;
+    }
+    const roster = facts.connectors.length ? connectorRoster(facts, prefix) : undefined;
+    if (facts.surface === "meta") {
+        return `Connecta tools are deferred: call eve__tool({ name: "${prefix}<tool>", input }). Names in this guidance and in nextAction omit the "${prefix}" prefix. Go straight to ${prefix}execute_code without eve__search, input { code: "async () => { const { tools } = await connecta.search({ query: 'list invoices', safety: 'readOnly' }); const r = await connecta.call(tools[0].address, {}); return r.data; }" }. eve__search sees only Connecta's routing tools, never downstream operations, so empty results do not mean a capability is missing; search inside the program.${roster ? ` Reachable: ${roster}.` : ""}`;
+    }
+    return `Connecta tools are deferred: call eve__tool({ name: "${prefix}<connector>__<tool>", input })${facts.readOnly ? "" : `, with writes named "${prefix}<connector>__WRITE__<tool>"`}. Find them with eve__search; scope one connector with "${prefix}<connector>__", not "<connector>__". Names in this guidance and in nextAction omit "${prefix}".${facts.executeCode ? ` For several, dependent or reduced calls, go straight to ${prefix}execute_code with { code: "async () => { ... }" }, using each tool's Program address.` : ""} Tools missing: ${prefix}authorize_connector returns a link; give it to the user or operator once and stop. Eve lists tools again every step, so a repair needs no reconnect.${roster ? ` Connectors: ${roster}.` : ""}`;
+}
+/** Release lines a helper and server must share; a patch difference is compatible. */
+const releaseLine = (version) => typeof version === "string" ? /^(\d+\.\d+)\./.exec(version)?.[1] : undefined;
+/** An endpoint may embed credentials or a token in its URL, path included; logs get only its origin. */
+function loggableEndpoint(endpoint) {
+    try {
+        return new URL(endpoint).origin;
+    }
+    catch {
+        return "the configured endpoint";
+    }
+}
+/** A deployment that renamed its server may version it independently, so only `connecta` is compared. */
+function warnOnVersionSkew(endpoint, server) {
+    if (server?.name !== "connecta")
+        return;
+    const line = releaseLine(server.version);
+    if (line === undefined || line === releaseLine(CONNECTA_VERSION))
+        return;
+    // The version is remote text, so only its validated numeric line reaches logs.
+    console.warn(`[connecta-eve] Helper ${CONNECTA_VERSION} and Connecta ${line}.x at ${loggableEndpoint(endpoint)} are different releases. Install the helper matching your server.`);
+}
+/** Headers for a guidance request. The caller's extras can never replace what the request itself needs. */
+async function guidanceHeaders(options, own) {
+    const extra = typeof options.headers === "function" ? await options.headers() : options.headers;
+    const headers = new Headers(extra);
+    for (const [name, value] of Object.entries(own))
+        headers.set(name, value);
+    return Object.fromEntries(headers);
+}
+/** Connecta's MCP `instructions` and endpoint facts for one endpoint, or null when unavailable. */
 async function instructionRequest(options, endpoint, method, signal) {
     const modern = method === "server/discover";
     const clientInfo = { name: options.clientName ?? "connecta-eve-instructions", version: "1" };
     const response = await (options.fetch ?? fetch)(endpoint, {
         method: "POST",
-        headers: {
+        headers: await guidanceHeaders(options, {
             Authorization: `Bearer ${await tokenFor(options)}`,
             "Content-Type": "application/json",
             Accept: "application/json, text/event-stream",
             ...(modern ? { "MCP-Protocol-Version": "2026-07-28", "Mcp-Method": method } : {}),
-        },
+        }),
         body: JSON.stringify({
             jsonrpc: "2.0",
             id: 1,
@@ -98,8 +220,15 @@ async function instructionRequest(options, endpoint, method, signal) {
             ?.slice("data:".length);
     if (!json)
         return null;
-    const instructions = JSON.parse(json).result?.instructions;
-    return typeof instructions === "string" && instructions.trim() ? instructions.trim() : null;
+    const { result } = JSON.parse(json);
+    const instructions = result?.instructions;
+    if (typeof instructions !== "string" || !instructions.trim())
+        return null;
+    return {
+        instructions: instructions.trim(),
+        facts: endpointFacts(result?.capabilities?.extensions?.["dev.connecta/endpoint"]),
+        server: result?._meta?.["io.modelcontextprotocol/serverInfo"] ?? result?.serverInfo,
+    };
 }
 async function fetchConnectaInstructions(options, endpoint, signal) {
     // Only a completed discovery response can justify legacy negotiation.
@@ -117,6 +246,10 @@ async function fetchConnectaInstructions(options, endpoint, signal) {
  */
 export function connectaInstructions(options = {}) {
     const ttlMs = options.ttlMs ?? 600_000;
+    const connection = options.connection ?? "connecta";
+    if (!/^[A-Za-z0-9._-]+$/.test(connection)) {
+        throw new Error(`Connecta connection "${connection}" must be the file name under agent/connections.`);
+    }
     const endpoints = new Map();
     const current = async (endpoint, signal) => {
         signal.throwIfAborted();
@@ -130,7 +263,13 @@ export function connectaInstructions(options = {}) {
             return cached?.content ?? null;
         let fresh;
         try {
-            fresh = await fetchConnectaInstructions(options, endpoint, signal);
+            const guidance = await fetchConnectaInstructions(options, endpoint, signal);
+            if (guidance && !state.versionChecked) {
+                state.versionChecked = true;
+                warnOnVersionSkew(endpoint, guidance.server);
+            }
+            // Eve's half comes first: it says how to read every name in Connecta's own text.
+            fresh = guidance && `${eveGuide(connection, guidance.facts)}\n${guidance.instructions}`;
         }
         catch {
             // Eve's cancellation is not an endpoint failure: rethrowing keeps it out
@@ -144,6 +283,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 +305,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: await guidanceHeaders(options, {
+                        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/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const CONNECTA_VERSION = "0.42.0";

package/dist/version.js

@@ -0,0 +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.42.0";

package/package.json

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