feat(eve): add @github-tools/eve-extension mountable eve extension

.changeset/nine-crickets-sail.md

@@ -0,0 +1,5 @@
+---
+"@github-tools/sdk": patch
+---
+
+Document `@github-tools/eve-extension` — a mountable eve extension distribution for the GitHub tools, built on top of the existing `@github-tools/sdk/eve` subpath. See `packages/github-tools-eve-extension` and the `examples/eve-extension-agent` starter.

.github/workflows/semantic-pull-request.yml

@@ -24,6 +24,7 @@ jobs:
           scopes: |
             sdk
             chat
+            eve
             deps
           types: |
             breaking

apps/docs/content/docs/2.frameworks/1.eve.md

@@ -29,6 +29,10 @@ links:
 
 [eve](https://eve.dev) is Vercel's filesystem-first agent framework: an agent is a folder with instructions, a model config, and tools. With `@github-tools/sdk/eve`, that folder becomes a **complete GitHub agent in 3 files** — all 42 tools registered from a single file, with durable human-in-the-loop approval that actually pauses the session until a person approves.
 
+::callout{icon="i-custom:eve"}
+There are two ways to add the tools to an eve agent: importing `@github-tools/sdk/eve` directly (below), or mounting them as an [eve extension](#eve-extension) via `@github-tools/eve-extension`. Both are supported today — the extension is the direction this integration is moving toward and will become the recommended way to add GitHub tools to an eve agent.
+::
+
 ::prompt
 ---
 description: Add GitHub tools to an eve agent
@@ -216,6 +220,26 @@ export default connectGithubTools('github/my-connector', {
 
 See [Vercel Connect](/guide/vercel-connect#eve-agent) for the connector setup checklist and multi-tenant scoping.
 
+## eve extension
+
+`@github-tools/eve-extension` packages the same tools as a mountable [eve extension](https://eve.dev/docs/extensions) instead of importing `@github-tools/sdk/eve` directly into `agent/tools/`. **This is the recommended direction going forward** — the direct `@github-tools/sdk/eve` import above keeps working and isn't going away, but new agents should prefer the extension:
+
+```ts [agent/extensions/github.ts]
+import githubExtension from '@github-tools/eve-extension'
+
+export default githubExtension({
+  connector: 'github/my-connector', // or token: process.env.GITHUB_TOKEN
+  preset: 'maintainer',
+  requireApproval: {
+    mergePullRequest: true,
+  },
+})
+```
+
+Tools are exposed to the model as `<namespace>__<toolName>`, where `<namespace>` comes from the mount file's name — `agent/extensions/github.ts` yields `github__listPullRequests`, `github__createIssue`, and so on. Not yet published to npm; see [`examples/eve-extension-agent`](https://github.com/vercel-labs/github-tools/tree/main/examples/eve-extension-agent) and [`packages/github-tools-eve-extension`](https://github.com/vercel-labs/github-tools/tree/main/packages/github-tools-eve-extension) to build and consume it from the workspace.
+
+Once published, this extension will become the primary, recommended way to add GitHub tools to an eve agent; `@github-tools/sdk/eve` remains supported for direct imports.
+
 ## External references
 
 - [How to build a GitHub agent with eve and GitHub Tools](https://vercel.com/kb/guide/github-agent-eve)

examples/eve-extension-agent/.gitignore

@@ -0,0 +1,6 @@
+.env
+node_modules
+.eve
+.output
+.vercel
+.env*

examples/eve-extension-agent/README.md

@@ -0,0 +1,68 @@
+# GitHub eve Extension Agent
+
+Minimal [eve](https://eve.dev) agent mounting `@github-tools/eve-extension` with the
+`code-review` preset and a [Vercel Connect](https://vercel.com/docs/connect) connector.
+
+## Setup
+
+### 1. Link the Connect connector
+
+The connector `github/test-github-tools` must be linked to your Vercel project and installed on
+the GitHub org/repos you want the agent to access.
+
+### 2. Pull the OIDC token for local dev
+
+```bash
+pnpm install
+cd examples/eve-extension-agent
+vercel link    # select the github-tools-docs project (or your linked project)
+vercel env pull
+```
+
+This writes `VERCEL_OIDC_TOKEN` into `.env`. Re-run `vercel env pull` when the token expires.
+
+Requires Node 24+ and `ai` v7 (peer of `eve` v0.19+).
+
+## Run
+
+From the example directory:
+
+```bash
+pnpm dev
+# or: npx eve dev
+```
+
+From the monorepo root:
+
+```bash
+pnpm dev:eve-extension-agent
+```
+
+## Project structure
+
+```
+agent/
+  agent.ts               # eve agent config
+  instructions.md        # system prompt
+  extensions/
+    github.ts            # GitHub tools via @github-tools/eve-extension
+```
+
+## Customize
+
+Swap the preset or configure approval:
+
+```ts
+import githubExtension from '@github-tools/eve-extension'
+
+export default githubExtension({
+  connector: 'github/test-github-tools',
+  preset: ['code-review', 'issue-triage'],
+  requireApproval: {
+    mergePullRequest: true,
+    addPullRequestComment: 'once',
+  },
+})
+```
+
+See the [@github-tools/eve-extension README](../../packages/github-tools-eve-extension/README.md).

examples/eve-extension-agent/agent/agent.ts

@@ -0,0 +1,5 @@
+import { defineAgent } from 'eve'
+
+export default defineAgent({
+  model: 'anthropic/claude-sonnet-5',
+})

examples/eve-extension-agent/agent/extensions/github.ts

@@ -0,0 +1,9 @@
+import githubExtension from '@github-tools/eve-extension'
+
+export default githubExtension({
+  connector: 'github/test-github-tools',
+  preset: 'code-review',
+  requireApproval: {
+    addPullRequestComment: ({ toolInput }: { toolInput?: { owner?: string } }) => toolInput?.owner !== 'vercel-labs',
+  },
+})

examples/eve-extension-agent/agent/instructions.md

@@ -0,0 +1,3 @@
+You are a GitHub code-review assistant.
+
+Use the GitHub tools (mounted as `github__*`) to inspect pull requests, read changed files, and post review comments. Be concise and actionable. Ask before merging or closing anything destructive.

examples/eve-extension-agent/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@github-tools/eve-extension-agent",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": "24.x"
+  },
+  "scripts": {
+    "dev": "eve dev"
+  },
+  "dependencies": {
+    "@github-tools/eve-extension": "workspace:*",
+    "ai": "^7.0.0",
+    "eve": "^0.26.2",
+    "zod": "^4.3.6"
+  }
+}

package.json

@@ -9,6 +9,7 @@
     "dev": "turbo run --filter=@github-tools/chat dev",
     "dev:pr-review-agent": "pnpm --filter @github-tools/pr-review-agent dev",
     "dev:eve-agent": "pnpm --filter @github-tools/eve-agent dev",
+    "dev:eve-extension-agent": "pnpm --filter @github-tools/eve-extension-agent dev",
     "docs:dev": "pnpm --filter @github-tools/docs dev",
     "docs:build": "pnpm --filter @github-tools/docs build",
     "docs:generate": "pnpm --filter @github-tools/docs generate",

packages/github-tools-eve-extension/README.md

@@ -0,0 +1,56 @@
+# @github-tools/eve-extension
+
+GitHub tools for [eve](https://eve.dev), packaged as a mountable
+[eve extension](https://eve.dev/docs/extensions).
+
+This is the direction the eve integration is moving toward and will become the recommended way
+to add GitHub tools to an eve agent. The direct `@github-tools/sdk/eve` import remains supported
+in the meantime.
+
+See the runnable consumer at [`examples/eve-extension-agent`](../../examples/eve-extension-agent).
+
+## Structure
+
+```
+extension/
+  extension.ts        # defineExtension() config schema (token, connector, preset, requireApproval, ...)
+  tools/
+    github.ts          # defineDynamic() returning buildEveToolMap(...) filtered by preset
+```
+
+## Build
+
+```sh
+pnpm --filter @github-tools/eve-extension build   # runs `eve extension build`
+```
+
+## Mount it
+
+```ts
+// agent/extensions/github.ts
+import githubExtension from '@github-tools/eve-extension'
+
+export default githubExtension({
+  connector: 'github/my-connector',   // or token: process.env.GITHUB_TOKEN
+  preset: 'maintainer',
+  requireApproval: {
+    mergePullRequest: true,
+    addPullRequestComment: ({ toolInput }) => toolInput?.owner !== 'vercel-labs',
+  },
+})
+```
+
+Tools are exposed to the model as `<namespace>__<toolName>`, where `<namespace>` comes from the
+mount file's name (`extensions/github.ts` → `github__listPullRequests`, `github__createIssue`, ...).
+
+## Config schema (`extension/extension.ts`)
+
+| Field | Type | Notes |
+|---|---|---|
+| `token` | `string?` | Falls back to `GITHUB_TOKEN` when omitted and `connector` is not set |
+| `connector` | `string?` | Vercel Connect connector name; takes priority over `token` |
+| `connect` | `record?` | Passed through to `getToken` when `connector` is set |
+| `preset` | preset name or array | `code-review`, `issue-triage`, `ci-ops`, `repo-explorer`, `maintainer` |
+| `requireApproval` | `boolean \| record` | Global or per-tool; per-tool values may be predicate functions |
+| `overrides` | `record` | Per-tool `description` / `approval` / `toModelOutput` / `outputSchema` |
+| `author` / `committer` / `coAuthors` | commit identity | Attribution for commit-creating tools |

packages/github-tools-eve-extension/extension/extension.ts

@@ -0,0 +1,29 @@
+import { defineExtension } from 'eve/extension'
+import { z } from 'zod'
+
+const presetNameSchema = z.enum(['code-review', 'issue-triage', 'ci-ops', 'repo-explorer', 'maintainer'])
+
+const commitIdentitySchema = z.object({
+  name: z.string(),
+  email: z.string(),
+})
+
+export default defineExtension({
+  config: z.object({
+    /** GitHub PAT. Falls back to `GITHUB_TOKEN` when omitted and `connector` is not set. */
+    token: z.string().optional(),
+    /** Vercel Connect connector name (e.g. `github/my-connector`). Takes priority over `token`. */
+    connector: z.string().optional(),
+    /** Vercel Connect token params passed through to `getToken` when `connector` is set. */
+    connect: z.record(z.string(), z.unknown()).optional(),
+    /** Restrict tools to a preset (or array of presets). Omit for all 42 tools. */
+    preset: z.union([presetNameSchema, z.array(presetNameSchema)]).optional(),
+    /** Global boolean or per-tool approval config — may hold predicate functions. */
+    requireApproval: z.union([z.boolean(), z.record(z.string(), z.unknown())]).optional(),
+    /** Per-tool overrides (description, approval, toModelOutput, outputSchema). */
+    overrides: z.record(z.string(), z.unknown()).optional(),
+    author: commitIdentitySchema.optional(),
+    committer: commitIdentitySchema.optional(),
+    coAuthors: z.array(commitIdentitySchema).optional(),
+  }),
+})

packages/github-tools-eve-extension/extension/tools/github.ts

@@ -0,0 +1,26 @@
+import { connectGithubToken } from '@github-tools/sdk/connect'
+import { buildEveToolMap, type EveApprovalConfig, type EveToolOverrides } from '@github-tools/sdk/eve'
+import { defineDynamic } from 'eve/tools'
+import extension from '../extension'
+
+export default defineDynamic({
+  events: {
+    'session.started': async () => {
+      const { token, connector, connect, preset, requireApproval, overrides, author, committer, coAuthors } = extension.config
+
+      const resolvedToken = connector
+        ? connectGithubToken(connector, { preset, params: connect })
+        : token
+
+      return buildEveToolMap({
+        token: resolvedToken,
+        preset,
+        requireApproval: requireApproval as EveApprovalConfig | undefined,
+        overrides: overrides as EveToolOverrides | undefined,
+        author,
+        committer,
+        coAuthors,
+      })
+    },
+  },
+})

packages/github-tools-eve-extension/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@github-tools/eve-extension",
+  "version": "0.0.0",
+  "private": true,
+  "description": "GitHub tools for eve, distributed as a mountable eve extension (https://eve.dev/docs/extensions)",
+  "type": "module",
+  "engines": {
+    "node": "24.x"
+  },
+  "eve": {
+    "extension": {
+      "source": "./extension",
+      "dist": "./dist/extension"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "eve extension build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@github-tools/sdk": "workspace:*",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "@vercel/connect": ">=0.3.2",
+    "eve": "*"
+  },
+  "peerDependenciesMeta": {
+    "@vercel/connect": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "@vercel/connect": "^0.4.2",
+    "eve": "^0.26.2",
+    "typescript": "^6.0.3"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./tools": {
+      "types": "./dist/tools/index.d.ts",
+      "default": "./dist/tools/index.mjs"
+    }
+  }
+}

packages/github-tools-eve-extension/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "lib": ["ESNext"],
+    "types": ["node"]
+  },
+  "include": ["extension"],
+  "exclude": ["dist", "node_modules"]
+}

packages/github-tools/README.md

@@ -284,6 +284,8 @@ connectGithubTools('github/my-connector', {
 
 [eve](https://eve.dev) is Vercel's filesystem-first agent framework. The `@github-tools/sdk/eve` subpath registers all GitHub tools via `defineDynamic` — one file, zero CLI.
 
+> A mountable [eve extension](https://eve.dev/docs/extensions), `@github-tools/eve-extension`, is also available and is the direction this integration is moving toward — it will become the recommended way to add GitHub tools to an eve agent. The direct import below remains supported. See [`packages/github-tools-eve-extension`](../github-tools-eve-extension) and [`examples/eve-extension-agent`](../../examples/eve-extension-agent).
+
 ```sh
 pnpm add @github-tools/sdk eve ai zod
 ```