@zackbart/connecta-eve 0.0.0 → 0.36.0

package/README.md

@@ -1,5 +1,151 @@
-# Connecta Eve helper
+# @zackbart/connecta-eve
 
-This placeholder establishes the package for trusted publishing. It contains no runtime code. Install version 0.35.0 or later for the supported helper.
+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.
 
-[Package guide](https://github.com/zackbart/connecta/tree/main/packages/connecta-eve).
+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.84.0
+```
+
+The server must declare your agent, admit it to the named pool and issue its
+agent token. See Connecta's [agent token setup](https://github.com/zackbart/connecta/blob/main/documentation/auth.md#issue-rotate-or-revoke-an-agent-token).
+
+Set these in the Eve app's environment:
+
+```sh
+CONNECTA_URL=https://connecta.example.com
+CONNECTA_ACCESS_TOKEN=cta_your_agent_token
+```
+
+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.",
+});
+```
+
+Create `agent/instructions/connecta.ts`:
+
+```ts
+import { connectaInstructions } from "@zackbart/connecta-eve";
+
+export default connectaInstructions({ pool: "assistant" });
+```
+
+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
+URL for other clients. Keep both files pointed at the same endpoint and token
+source.
+
+Auth is app-owned. The default token comes from `CONNECTA_ACCESS_TOKEN`, read
+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.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:
+
+```json
+{ "overrides": { "eve": { "undici": "8.12.3" } } }
+```
+
+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
+separate dependency and keeps its exact pin.
+
+## Approval and writes
+
+The default policy is Eve's `never()`: authorized writes run unattended. Use a
+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`, 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.
+
+## Endpoint instructions
+
+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
+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.
+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.
+
+## Vercel OIDC token source
+
+This variant requires a **Connecta 0.35.0 or later** deployment with Vercel
+workload admission configured for this agent. Workload admission was added in
+[#975](https://github.com/zackbart/connecta/pull/975) and is available from 0.35.0.
+Earlier releases require agent tokens.
+Once configured, use Vercel's token resolver in **both** files:
+
+```ts
+import { getVercelOidcToken } from "@vercel/oidc";
+import { connectaConnection } from "@zackbart/connecta-eve";
+
+export default connectaConnection({
+  pool: "assistant",
+  description: "Shared CRM and tickets for the assistant.",
+  getToken: getVercelOidcToken,
+});
+```
+
+```ts
+import { getVercelOidcToken } from "@vercel/oidc";
+import { connectaInstructions } from "@zackbart/connecta-eve";
+
+export default connectaInstructions({ pool: "assistant", getToken: getVercelOidcToken });
+```
+
+Install `@vercel/oidc` in the Eve app when using this variant. The helper has no
+dependency on it and never switches credential types automatically.
+
+## 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.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
+refuse listing. `--counts 40,1000` selects a smaller matrix.
+
+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
+quality remain unmeasured; these results establish local runtime contracts,
+not live Vercel workload admission or production model performance.

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+import { 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 {
+    /**
+     * The deployment's base URL, or a full endpoint URL when `pool` is absent.
+     * Defaults to the `CONNECTA_URL` environment variable.
+     */
+    url?: string;
+    /** The agent's pool; the endpoint is `<url>/agent/<pool>`. */
+    pool?: string;
+    /**
+     * The agent's bearer token, resolved on every request so a rotation needs
+     * no restart. Defaults to the `CONNECTA_ACCESS_TOKEN` environment variable.
+     */
+    getToken?: () => string | Promise<string>;
+}
+export interface ConnectaConnectionOptions extends ConnectaEndpointOptions {
+    /** 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()`. */
+    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
+     * `approval` is set.
+     */
+    gateWrites?: boolean;
+}
+export interface ConnectaInstructionsOptions extends ConnectaEndpointOptions {
+    /** How long fetched instructions are reused. Default ten minutes. */
+    ttlMs?: number;
+    /** Fetch implementation, for tests. */
+    fetch?: typeof fetch;
+}
+/** The endpoint URL these options name. */
+export declare function connectaEndpoint(options?: ConnectaEndpointOptions): string;
+/**
+ * Approve reads and ask a person about everything else, keyed on the
+ * annotations Connecta derives from its own classification.
+ */
+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;
+/**
+ * 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.
+ */
+export declare function connectaInstructions(options?: ConnectaInstructionsOptions): import("eve/connections").DynamicSentinel<import("eve/instructions").DynamicInstructionsResult, import("eve/connections").DynamicContext>;

package/dist/index.js

@@ -0,0 +1,133 @@
+import { 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;
+}
+/** The endpoint URL these options name. */
+export function connectaEndpoint(options = {}) {
+    const url = options.url ?? environment("CONNECTA_URL");
+    if (!url)
+        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_-]+.`);
+    return `${url.replace(/\/+$/, "")}/agent/${options.pool}`;
+}
+async function tokenFor(options) {
+    const token = options.getToken ? (await options.getToken()).trim() : environment("CONNECTA_ACCESS_TOKEN");
+    if (!token)
+        throw new Error("Connecta needs an agent token: getToken, or CONNECTA_ACCESS_TOKEN in the environment.");
+    return token;
+}
+/**
+ * Approve reads and ask a person about everything else, keyed on the
+ * 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) {
+    return defineMcpClientConnection({
+        url: connectaEndpoint(options),
+        description: options.description,
+        auth: {
+            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, signal) {
+    const modern = method === "server/discover";
+    const response = await (options.fetch ?? fetch)(connectaEndpoint(options), {
+        method: "POST",
+        headers: {
+            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,
+            method,
+            params: modern
+                ? {
+                    _meta: {
+                        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
+                        "io.modelcontextprotocol/clientCapabilities": {},
+                        "io.modelcontextprotocol/clientInfo": { name: "connecta-eve-instructions", version: "1" },
+                    },
+                }
+                : {
+                    protocolVersion: "2025-06-18",
+                    capabilities: {},
+                    clientInfo: { name: "connecta-eve-instructions", version: "1" },
+                },
+        }),
+        signal: AbortSignal.any([signal, AbortSignal.timeout(5_000)]),
+    });
+    if (!response.ok)
+        return null;
+    const text = await response.text();
+    // Streamable HTTP answers as JSON or as one SSE `data:` event.
+    const json = text.trimStart().startsWith("{")
+        ? text
+        : text
+            .split("\n")
+            .find((line) => line.startsWith("data:"))
+            ?.slice("data:".length);
+    if (!json)
+        return null;
+    const instructions = JSON.parse(json).result?.instructions;
+    return typeof instructions === "string" && instructions.trim() ? instructions.trim() : null;
+}
+async function fetchConnectaInstructions(options, 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);
+}
+/**
+ * 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.
+ */
+export function connectaInstructions(options = {}) {
+    const ttlMs = options.ttlMs ?? 600_000;
+    let cached;
+    let retryAfter = 0;
+    const current = async (signal) => {
+        signal.throwIfAborted();
+        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);
+        }
+        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;
+        return fresh ?? cached?.content ?? null;
+    };
+    return defineDynamic(async (ctx) => {
+        const content = await ctx.memo(["connecta-instructions", ctx.turn?.id ?? null], ({ abortSignal }) => current(abortSignal));
+        return content ? defineInstructions({ content: `Connecta guidance:\n${content}` }) : null;
+    });
+}

package/package.json

@@ -1,19 +1,47 @@
 {
   "name": "@zackbart/connecta-eve",
-  "version": "0.0.0",
-  "description": "Bootstrap placeholder for the Connecta Eve helper; use 0.35.0 or later.",
-  "license": "MIT",
+  "version": "0.36.0",
   "type": "module",
+  "sideEffects": false,
+  "description": "Eve connection and instructions helpers for Connecta agent endpoints.",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/zackbart/connecta.git",
     "directory": "packages/connecta-eve"
   },
-  "publishConfig": {
-    "access": "public"
-  },
   "files": [
+    "dist",
     "README.md",
     "LICENSE"
-  ]
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "eve": ">=0.84.0 <0.85.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "eve": "0.84.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.6"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "check": "pnpm run typecheck && pnpm run test && pnpm run build",
+    "prepack": "pnpm run check",
+    "probe:catalog": "node scripts/probe-catalog.mjs"
+  }
 }