@github-tools/sdk 1.8.2 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/README.md +184 -70
  2. package/dist/connect/eve.d.mts +11 -5
  3. package/dist/connect/eve.d.mts.map +1 -1
  4. package/dist/connect/eve.mjs +10 -2
  5. package/dist/connect/eve.mjs.map +1 -1
  6. package/dist/connect.d.mts +23 -11
  7. package/dist/connect.d.mts.map +1 -1
  8. package/dist/connect.mjs +6 -3
  9. package/dist/connect.mjs.map +1 -1
  10. package/dist/eve-DmiXBuli.mjs +864 -0
  11. package/dist/eve-DmiXBuli.mjs.map +1 -0
  12. package/dist/eve.d.mts +338 -90
  13. package/dist/eve.d.mts.map +1 -1
  14. package/dist/eve.mjs +3 -3
  15. package/dist/index-CtID5dUi.d.mts +606 -0
  16. package/dist/index-CtID5dUi.d.mts.map +1 -0
  17. package/dist/index.d.mts +2 -2
  18. package/dist/index.mjs +3 -3
  19. package/dist/{src-CfzZfU82.mjs → src-D6vC3V8r.mjs} +293 -20
  20. package/dist/src-D6vC3V8r.mjs.map +1 -0
  21. package/dist/{token-CW8lQBND.mjs → token-sbepWIkd.mjs} +45 -7
  22. package/dist/token-sbepWIkd.mjs.map +1 -0
  23. package/dist/{types-B0mvQgJf.d.mts → types-BOnJ0Rou.d.mts} +28 -8
  24. package/dist/types-BOnJ0Rou.d.mts.map +1 -0
  25. package/dist/types-BVLof-5R.d.mts +39 -0
  26. package/dist/types-BVLof-5R.d.mts.map +1 -0
  27. package/dist/workflow.d.mts +7 -7
  28. package/dist/workflow.d.mts.map +1 -1
  29. package/dist/workflow.mjs +6 -4
  30. package/dist/workflow.mjs.map +1 -1
  31. package/dist/{write-tools-Dx9LfYlU.mjs → write-tools-cg_ialNd.mjs} +1009 -107
  32. package/dist/write-tools-cg_ialNd.mjs.map +1 -0
  33. package/package.json +13 -13
  34. package/dist/eve-UPaHEGVi.mjs +0 -512
  35. package/dist/eve-UPaHEGVi.mjs.map +0 -1
  36. package/dist/index-Cs1Kebmt.d.mts +0 -463
  37. package/dist/index-Cs1Kebmt.d.mts.map +0 -1
  38. package/dist/src-CfzZfU82.mjs.map +0 -1
  39. package/dist/token-CW8lQBND.mjs.map +0 -1
  40. package/dist/types-B0mvQgJf.d.mts.map +0 -1
  41. package/dist/types-DwHrGKWO.d.mts +0 -27
  42. package/dist/types-DwHrGKWO.d.mts.map +0 -1
  43. package/dist/write-tools-Dx9LfYlU.mjs.map +0 -1
package/README.md CHANGED
@@ -1,4 +1,4 @@
1
- <img src="https://github.com/vercel-labs/github-tools/blob/main/assets/banner.jpg" width="100%" alt="GitHub Tools banner" />
1
+ <img src="https://github.com/vercel-labs/github-tools/blob/main/assets/banner.jpg" width="100%" alt="GitHub tools banner" />
2
2
 
3
3
  # @github-tools/sdk
4
4
 
@@ -7,11 +7,33 @@
7
7
  [![TypeScript](https://img.shields.io/badge/TypeScript-black?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
8
8
  [![license](https://img.shields.io/github/license/vercel-labs/github-tools?color=black)](https://github.com/vercel-labs/github-tools/blob/main/LICENSE)
9
9
 
10
- **Connect GitHub to any agent.** 42 typed GitHub tools with presets, human approval, and durable execution — for the [AI SDK](https://ai-sdk.dev), [eve](https://eve.dev), Vercel Workflow, and [Chat SDK](https://chat-sdk.dev).
10
+ **Give any agent GitHub access.** A typed tool layer for GitHub AI agents, with presets, human approval, and durable execution. Works with [eve](https://eve.dev), the [AI SDK](https://ai-sdk.dev), Vercel Workflow, and [Chat SDK](https://chat-sdk.dev).
11
11
 
12
12
  Docs: **[github-tools.com](https://github-tools.com)**
13
13
 
14
- 42 tools covering repositories, branches, pull requests, issues, commits, search, gists, and workflows. Write operations support granular approval control out of the box.
14
+ ## Why not the GitHub MCP server, `gh` CLI, or raw Octokit?
15
+
16
+ They all reach the GitHub API, but none of them were built as an agent's tool layer. An agent still needs a schema it can fill reliably, a safety gate before it merges a PR, output shaped to fit a context window, and a way to survive a crash mid-task.
17
+
18
+ | | `@github-tools/sdk` | GitHub MCP server | `gh` CLI | Raw Octokit |
19
+ |---|---|---|---|---|
20
+ | Integration | Native AI SDK `tool()` objects | MCP wire protocol via a separate process | Shell-out from the agent | Hand-written per call |
21
+ | Human approval | Built in, on by default | Host-dependent, inconsistent | None | You build it |
22
+ | Durable / retryable | Every call is a `"use step"` | No | No | No |
23
+ | Scoped by task | Presets (7 built-in) | Full server surface, or manual filtering | Full CLI surface | You build it |
24
+ | Token-efficient output | Shaped and truncated by design | Raw API responses | Raw text, needs parsing | Raw API responses |
25
+ | Native eve / Workflow / Chat SDK | Yes | No | No | No |
26
+
27
+ ## Pick your path
28
+
29
+ | What are you building | Start here |
30
+ |---|---|
31
+ | A standalone GitHub agent, fast: 3 files, durable approval | [eve extension](#eve-extension-recommended) |
32
+ | Scripts, chat backends, or an existing AI SDK app | Quick Start below |
33
+ | Production agents that must survive restarts and timeouts | [Durable Agents](#durable-agents-vercel-workflow-sdk) |
34
+ | A GitHub, Slack, or Discord bot | [Chat SDK docs](https://github-tools.com/frameworks/chat-sdk) |
35
+
36
+ 53 tools cover repositories, branches, pull requests, issues, commits, releases, checks and statuses, search, gists, and workflows. See the full [Tools Catalog](https://github-tools.com/api/tools-catalog). Write operations support granular approval control out of the box.
15
37
 
16
38
  ## Installation
17
39
 
@@ -28,6 +50,7 @@ pnpm add ai zod
28
50
  ## Quick Start
29
51
 
30
52
  ```ts
53
+ // list-prs.ts
31
54
  import { createGithubTools } from '@github-tools/sdk'
32
55
  import { generateText } from 'ai'
33
56
 
@@ -43,20 +66,26 @@ const result = await generateText({
43
66
  Use `preset` to get only the tools relevant to a specific use case:
44
67
 
45
68
  ```ts
46
- // Code-review agent — PRs, commits, file content, and comments
69
+ // Code-review agent: PRs, commits, file content, and comments
47
70
  createGithubTools({ token, preset: 'code-review' })
48
71
 
49
- // Issue triage — read/create/close issues, search
72
+ // Issue triage: read/create/close issues, search
50
73
  createGithubTools({ token, preset: 'issue-triage' })
51
74
 
52
- // Read-only exploration — browse repos without write access
75
+ // Read-only exploration: browse repos without write access
53
76
  createGithubTools({ token, preset: 'repo-explorer' })
54
77
 
55
- // Full maintenance — all tools
78
+ // Security audit: read-only exploration, PR/CI visibility, plus issue creation to report findings
79
+ createGithubTools({ token, preset: 'security-audit' })
80
+
81
+ // Release manager: releases, compare diff, commits, workflow runs, pull requests
82
+ createGithubTools({ token, preset: 'release-manager' })
83
+
84
+ // Full maintenance: all tools
56
85
  createGithubTools({ token, preset: 'maintainer' })
57
86
  ```
58
87
 
59
- Presets are composable — pass an array to combine them:
88
+ Presets are composable, pass an array to combine them:
60
89
 
61
90
  ```ts
62
91
  createGithubTools({ token, preset: ['code-review', 'issue-triage'] })
@@ -64,13 +93,15 @@ createGithubTools({ token, preset: ['code-review', 'issue-triage'] })
64
93
 
65
94
  | Preset | Tools included |
66
95
  |---|---|
67
- | `code-review` | `getPullRequest`, `listPullRequests`, `listPullRequestFiles`, `listPullRequestReviews`, `getFileContent`, `listCommits`, `getCommit`, `getBlame`, `getRepository`, `listBranches`, `searchCode`, `addPullRequestComment`, `createPullRequestReview` |
68
- | `issue-triage` | `listIssues`, `getIssue`, `createIssue`, `addIssueComment`, `closeIssue`, `listLabels`, `addLabels`, `removeLabel`, `getRepository`, `searchRepositories`, `searchCode` |
69
- | `repo-explorer` | All read-only tools including gists and workflows (no write operations) |
70
- | `ci-ops` | `listWorkflows`, `listWorkflowRuns`, `getWorkflowRun`, `listWorkflowJobs`, `triggerWorkflow`, `cancelWorkflowRun`, `rerunWorkflowRun`, `getRepository`, `listBranches`, `listCommits`, `getCommit` |
71
- | `maintainer` | All 42 tools |
96
+ | `code-review` | `getPullRequest`, `listPullRequests`, `listPullRequestFiles`, `listPullRequestReviews`, `getPullRequestContext`, `getFileContent`, `listCommits`, `getCommit`, `getBlame`, `compareCommits`, `getRepository`, `listBranches`, `searchCode`, `listCheckRuns`, `getCombinedStatus`, `addPullRequestComment`, `createPullRequestReview`, `requestReviewers` |
97
+ | `issue-triage` | `listIssues`, `getIssue`, `getIssueContext`, `createIssue`, `addIssueComment`, `closeIssue`, `listLabels`, `addLabels`, `removeLabel`, `addAssignees`, `removeAssignees`, `getRepository`, `searchRepositories`, `searchCode` |
98
+ | `repo-explorer` | All read-only tools including gists, workflows, checks/statuses, and releases (no write operations) |
99
+ | `ci-ops` | `listWorkflows`, `listWorkflowRuns`, `getWorkflowRun`, `listWorkflowJobs`, `listCheckRuns`, `getCombinedStatus`, `getCiFailureContext`, `triggerWorkflow`, `cancelWorkflowRun`, `rerunWorkflowRun`, `getRepository`, `listBranches`, `listCommits`, `getCommit` |
100
+ | `security-audit` | Read-only exploration (`getFileContent`, `getRepositoryTree`, `searchCode`, `listCommits`, `getCommit`, `getBlame`, `compareCommits`), PR and CI visibility, plus `createIssue`, `addIssueComment`, `addLabels` to report findings (no destructive writes) |
101
+ | `release-manager` | `listReleases`, `getLatestRelease`, `getRelease`, `getReleaseContext`, `createRelease`, `compareCommits`, `listCommits`, `getCommit`, `listWorkflowRuns`, `getWorkflowRun`, `listPullRequests`, `getPullRequest`, `getRepository`, `listBranches` |
102
+ | `maintainer` | All 57 tools |
72
103
 
73
- Omit `preset` to get all tools (same as `maintainer`).
104
+ Omit `preset` to get all tools (same as `maintainer`). Full breakdown: [Tools Catalog](https://github-tools.com/api/tools-catalog).
74
105
 
75
106
  ### Cherry-Picking Tools
76
107
 
@@ -115,7 +146,7 @@ createGithubTools({
115
146
  })
116
147
  ```
117
148
 
118
- Write tools: `createOrUpdateFile`, `createPullRequest`, `mergePullRequest`, `addPullRequestComment`, `createPullRequestReview`, `createIssue`, `addIssueComment`, `closeIssue`, `addLabels`, `removeLabel`, `createGist`, `updateGist`, `deleteGist`, `createGistComment`, `triggerWorkflow`, `cancelWorkflowRun`, `rerunWorkflowRun`.
149
+ Write tools: `createBranch`, `forkRepository`, `createRepository`, `createOrUpdateFile`, `createPullRequest`, `mergePullRequest`, `addPullRequestComment`, `createPullRequestReview`, `requestReviewers`, `createIssue`, `addIssueComment`, `closeIssue`, `addLabels`, `removeLabel`, `addAssignees`, `removeAssignees`, `createGist`, `updateGist`, `deleteGist`, `createGistComment`, `triggerWorkflow`, `cancelWorkflowRun`, `rerunWorkflowRun`, `createRelease`.
119
150
 
120
151
  All other tools are read-only and never require approval.
121
152
 
@@ -191,7 +222,7 @@ const result = await generateText({
191
222
  })
192
223
  ```
193
224
 
194
- Each step, toolpick picks the best ~5 tools using keyword + semantic search. All tools remain callable — only the visible set changes. See [toolpick docs](https://github.com/pontusab/toolpick) for LLM re-ranking, caching, and model-driven discovery options.
225
+ Each step, toolpick picks the best ~5 tools using keyword + semantic search. All tools remain callable, only the visible set changes. See [toolpick docs](https://github.com/pontusab/toolpick) for LLM re-ranking, caching, and model-driven discovery options.
195
226
 
196
227
  ## Durable Agents (Vercel Workflow SDK)
197
228
 
@@ -209,13 +240,13 @@ const agent = createDurableGithubAgent({
209
240
  })
210
241
  ```
211
242
 
212
- All presets work with `createDurableGithubAgent`. Write tools honor `requireApproval` via `needsApproval` — the workflow pauses until the user approves or denies.
243
+ All presets work with `createDurableGithubAgent`. Write tools honor `requireApproval` via `needsApproval`: the workflow pauses until the user approves or denies.
213
244
 
214
- > `workflow` and `@ai-sdk/workflow` are optional peer dependencies — install them only when using the workflow subpath.
245
+ > `workflow` and `@ai-sdk/workflow` are optional peer dependencies, install them only when using the workflow subpath.
215
246
 
216
247
  ## Vercel Connect
217
248
 
218
- [Vercel Connect](https://vercel.com/docs/connect) mints short-lived GitHub tokens from a connector — no PAT to store. The `@github-tools/sdk/connect` subpath derives scopes from your preset automatically.
249
+ [Vercel Connect](https://vercel.com/docs/connect) mints short-lived GitHub tokens from a connector, with no PAT to store. The `@github-tools/sdk/connect` subpath derives scopes from your preset automatically.
219
250
 
220
251
  ```sh
221
252
  pnpm add @vercel/connect
@@ -229,28 +260,21 @@ const tools = connectGithubTools('github/my-connector', {
229
260
  })
230
261
  ```
231
262
 
232
- For eve agents, import from `@github-tools/sdk/connect/eve`:
263
+ For eve agents, pass `connector` directly to the [eve extension](#eve-extension-recommended) (recommended): no separate Connect import, and no `build.externalDependencies` workaround needed:
233
264
 
234
265
  ```ts
235
- // agent/agent.ts — TODO(eve-connect-bundle): drop externalDependencies when eve fixes upstream
236
- import { defineAgent } from 'eve'
237
-
238
- export default defineAgent({
239
- model: 'anthropic/claude-sonnet-5',
240
- build: { externalDependencies: ['@vercel/connect'] },
241
- })
242
- ```
243
-
244
- ```ts
245
- // agent/tools/github.ts
246
- import { connectGithubTools } from '@github-tools/sdk/connect/eve'
266
+ // agent/extensions/github.ts
267
+ import githubExtension from '@github-tools/eve-extension'
247
268
 
248
- export default connectGithubTools('github/my-connector', {
269
+ export default githubExtension({
270
+ connector: 'github/my-connector',
249
271
  preset: 'maintainer',
250
272
  })
251
273
  ```
252
274
 
253
- `connectGithubTools` mints tokens lazily at tool execution — do not `await getToken(...)` at module top level in `agent/tools/` (that runs at import/build time).
275
+ For the deprecated direct import, use `connectGithubTools` from `@github-tools/sdk/connect/eve` the same way inside `agent/tools/github.ts`. That path does need `build: { externalDependencies: ['@vercel/connect'] }` in `agent.ts` (see [eve, direct import](#eve-direct-import-deprecated) below).
276
+
277
+ `connectGithubTools` mints tokens lazily at tool execution. Do not `await getToken(...)` at module top level in `agent/tools/` (that runs at import/build time).
254
278
 
255
279
  Token provider only (custom factories):
256
280
 
@@ -263,7 +287,7 @@ createGithubTools({
263
287
  })
264
288
  ```
265
289
 
266
- Pass the same `preset` to `connectGithubToken` — it derives Connect scopes independently of the `preset` given to `createGithubTools`.
290
+ Pass the same `preset` to `connectGithubToken`: it derives Connect scopes independently of the `preset` given to `createGithubTools`.
267
291
 
268
292
  Override installation, repositories, or scopes via `connect`:
269
293
 
@@ -278,13 +302,65 @@ connectGithubTools('github/my-connector', {
278
302
  })
279
303
  ```
280
304
 
281
- > `@vercel/connect` is an optional peer dependency — install it only when using the `/connect` subpath.
305
+ > `@vercel/connect` is an optional peer dependency, install it only when using the `/connect` subpath.
306
+
307
+ `connector` accepts a `() => string | Promise<string>` resolver instead of a static name, re-resolved on every call. Useful to pick a connector per environment or tenant:
308
+
309
+ ```ts
310
+ connectGithubTools(
311
+ () => (process.env.VERCEL_ENV === 'production' ? 'github/prod-connector' : 'github/preview-connector'),
312
+ { preset: 'code-review' },
313
+ )
314
+ ```
282
315
 
283
316
  ## eve
284
317
 
285
- [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.
318
+ [eve](https://eve.dev) is Vercel's filesystem-first agent framework. `@github-tools/eve-extension` is the **recommended** way to add GitHub tools to an eve agent: a mountable [eve extension](https://eve.dev/docs/extensions), no CLI setup, no direct SDK import in `agent/tools/`. The lower-level `@github-tools/sdk/eve` subpath (`defineDynamic`) is **deprecated** in its favor; it keeps working and is documented below for existing agents.
286
319
 
287
- > 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).
320
+ ### eve extension (recommended)
321
+
322
+ ```sh
323
+ pnpm add @github-tools/eve-extension eve
324
+ ```
325
+
326
+ `eve` is a required peer dependency (itself requiring **`ai` v7**).
327
+
328
+ ```ts
329
+ // agent/extensions/github.ts
330
+ import githubExtension from '@github-tools/eve-extension'
331
+
332
+ export default githubExtension({
333
+ preset: ['code-review', 'issue-triage'],
334
+ requireApproval: {
335
+ mergePullRequest: true,
336
+ createIssue: 'once',
337
+ addPullRequestComment: false,
338
+ createOrUpdateFile: ({ toolInput }) => toolInput?.owner !== 'vercel-labs',
339
+ },
340
+ })
341
+ ```
342
+
343
+ 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.
344
+
345
+ For Vercel Connect, pass `connector` directly, no separate import needed:
346
+
347
+ ```ts
348
+ // agent/extensions/github.ts
349
+ import githubExtension from '@github-tools/eve-extension'
350
+
351
+ export default githubExtension({
352
+ connector: 'github/my-connector',
353
+ preset: 'maintainer',
354
+ })
355
+ ```
356
+
357
+ No `build.externalDependencies` workaround is needed here. Unlike the deprecated direct import below, the extension is pre-built via `eve extension build` and loaded through eve's extension mechanism rather than inlined from a workspace-linked source import.
358
+
359
+ See [`packages/github-tools-eve-extension`](../github-tools-eve-extension) and [`examples/eve-extension-agent`](../../examples/eve-extension-agent) for the full package README and a runnable agent.
360
+
361
+ ### eve, direct import (deprecated)
362
+
363
+ The `@github-tools/sdk/eve` subpath registers all GitHub tools via `defineDynamic`: one file, zero CLI. This keeps working but new agents should use the extension above.
288
364
 
289
365
  ```sh
290
366
  pnpm add @github-tools/sdk eve ai zod
@@ -307,9 +383,9 @@ export default createGithubTools({
307
383
  })
308
384
  ```
309
385
 
310
- Dynamic tools are named by their **bare map key** — the model sees `listPullRequests`, `createIssue`, and so on (same names as the AI SDK package). There is no automatic file-slug prefix when returning a tool map from `defineDynamic`.
386
+ Dynamic tools are named by their **bare map key**: the model sees `listPullRequests`, `createIssue`, and so on (same names as the AI SDK package). There is no automatic file-slug prefix when returning a tool map from `defineDynamic`.
311
387
 
312
- ### Approval (eve)
388
+ #### Approval (eve)
313
389
 
314
390
  | Value | Maps to | Behavior |
315
391
  |---|---|---|
@@ -321,9 +397,9 @@ Dynamic tools are named by their **bare map key** — the model sees `listPullRe
321
397
 
322
398
  Default (no `requireApproval`): all write tools → `always()`. Unlisted write tools keep the `always()` fail-safe default.
323
399
 
324
- Unlike the Workflow SDK subpath, eve approval **works durably** — gated tools pause the session until a human approves.
400
+ Unlike the Workflow SDK subpath, eve approval **works durably**: gated tools pause the session until a human approves.
325
401
 
326
- ### Cherry-picking (one tool per file)
402
+ #### Cherry-picking (one tool per file)
327
403
 
328
404
  ```ts
329
405
  // agent/tools/list_pull_requests.ts
@@ -332,7 +408,7 @@ import { listPullRequests } from '@github-tools/sdk/eve'
332
408
  export default listPullRequests()
333
409
  ```
334
410
 
335
- ### Idempotency
411
+ #### Idempotency
336
412
 
337
413
  eve replays completed steps but re-runs steps interrupted mid-execution. Write tools vary:
338
414
 
@@ -341,13 +417,14 @@ eve replays completed steps but re-runs steps interrupted mid-execution. Write t
341
417
  | `createOrUpdateFile` | Natural when content + `sha` unchanged (skips no-op updates) |
342
418
  | `closeIssue` | Natural when already closed |
343
419
  | `createBranch` | Natural when branch exists at same SHA |
344
- | `addIssueComment`, `createIssue`, `mergePullRequest`, … | **Not** idempotent — each call creates new side effects |
420
+ | `removeAssignees` | Natural: removing an assignee that isn't assigned is a no-op on GitHub |
421
+ | `addIssueComment`, `createIssue`, `mergePullRequest`, `createRelease`, … | **Not** idempotent: each call creates new side effects |
345
422
 
346
423
  Gate non-idempotent writes behind `always()` or `once()` where replay safety matters.
347
424
 
348
- ### Vercel Connect
425
+ #### Vercel Connect
349
426
 
350
- Mint the token from a Connect connector instead of `GITHUB_TOKEN` — `connectGithubTools` derives scopes from `preset` and fetches the token lazily inside each tool call:
427
+ Mint the token from a Connect connector instead of `GITHUB_TOKEN`. `connectGithubTools` derives scopes from `preset` and fetches the token lazily inside each tool call:
351
428
 
352
429
  ```ts
353
430
  // agent/tools/github.ts
@@ -358,21 +435,27 @@ export default connectGithubTools('github/my-connector', {
358
435
  })
359
436
  ```
360
437
 
361
- Add `build: { externalDependencies: ['@vercel/connect'] }` to `agent.ts` — see [Vercel Connect](#vercel-connect) above for the full setup checklist.
438
+ Add `build: { externalDependencies: ['@vercel/connect'] }` to `agent.ts`. See [Vercel Connect](#vercel-connect) above for the full setup checklist.
362
439
 
363
- > `eve` is an optional peer dependency — install it only when using the `/eve` subpath.
440
+ > `eve` is an optional peer dependency, install it only when using the `/eve` subpath.
364
441
 
365
442
  See [`examples/eve-agent`](../../examples/eve-agent) for a minimal agent.
366
443
 
367
444
  ## Available Tools
368
445
 
446
+ List tools (`listCommits`, `listPullRequests`, `listIssues`, `listWorkflowRuns`, `listCheckRuns`, `listReleases`) accept an optional `maxPages` alongside `perPage`. Set it to sequentially fetch and combine up to that many pages in one call, stopping early once a page comes back short.
447
+
369
448
  ### Repository
370
449
 
371
450
  | Tool | Description |
372
451
  |---|---|
373
452
  | `getRepository` | Get repository metadata (stars, language, default branch, …) |
374
453
  | `listBranches` | List branches |
375
- | `getFileContent` | Read a file or directory listing |
454
+ | `getFileContent` | Read a file or directory listing (prefer `startLine`/`endLine` or `maxLines` for large files) |
455
+ | `getRepositoryTree` | List the file and directory structure at a given ref |
456
+ | `createBranch` | Create a new branch from an existing branch or commit SHA |
457
+ | `forkRepository` | Fork a repository to a user or organization |
458
+ | `createRepository` | Create a new repository for a user or organization |
376
459
  | `createOrUpdateFile` | Create or update a file and commit it |
377
460
 
378
461
  ### Pull Requests
@@ -380,26 +463,31 @@ See [`examples/eve-agent`](../../examples/eve-agent) for a minimal agent.
380
463
  | Tool | Description |
381
464
  |---|---|
382
465
  | `listPullRequests` | List PRs filtered by state |
383
- | `getPullRequest` | Get a PR's full details (diff stats, body, merge status) |
384
- | `listPullRequestFiles` | List files changed in a PR with diff status and patches |
466
+ | `getPullRequest` | Get a PR's full details (diff stats, body, merge status; body truncated by default) |
467
+ | `listPullRequestFiles` | List files changed in a PR (patches omitted by default; set `includePatch` / `filenames` for diffs) |
385
468
  | `listPullRequestReviews` | List reviews on a PR (approvals, change requests, comments) |
469
+ | `getPullRequestContext` | Fetch PR details plus files, reviews, and optional CI checks in one call |
386
470
  | `createPullRequest` | Open a new PR |
387
471
  | `mergePullRequest` | Merge a PR (merge, squash, or rebase) |
388
472
  | `addPullRequestComment` | Post a comment on a PR |
389
473
  | `createPullRequestReview` | Submit a formal review (approve, request changes, or comment) with inline comments |
474
+ | `requestReviewers` | Request reviews from users or teams on a PR |
390
475
 
391
476
  ### Issues
392
477
 
393
478
  | Tool | Description |
394
479
  |---|---|
395
480
  | `listIssues` | List issues filtered by state and labels |
396
- | `getIssue` | Get an issue's full details |
481
+ | `getIssue` | Get an issue's details (body truncated by default; set `detail: full` for complete text) |
482
+ | `getIssueContext` | Fetch an issue plus available labels and recent comments in one call |
397
483
  | `createIssue` | Open a new issue |
398
484
  | `addIssueComment` | Post a comment on an issue |
399
485
  | `closeIssue` | Close an issue (completed or not planned) |
400
486
  | `listLabels` | List labels available in a repository |
401
487
  | `addLabels` | Add labels to an issue or pull request |
402
488
  | `removeLabel` | Remove a label from an issue or pull request |
489
+ | `addAssignees` | Assign users to an issue or pull request |
490
+ | `removeAssignees` | Remove assignees from an issue or pull request |
403
491
 
404
492
  ### Gists
405
493
 
@@ -425,6 +513,24 @@ See [`examples/eve-agent`](../../examples/eve-agent) for a minimal agent.
425
513
  | `cancelWorkflowRun` | Cancel an in-progress workflow run |
426
514
  | `rerunWorkflowRun` | Re-run a workflow run, optionally only failed jobs |
427
515
 
516
+ ### Checks and Statuses
517
+
518
+ | Tool | Description |
519
+ |---|---|
520
+ | `listCheckRuns` | List check runs (Checks API: GitHub Actions and other CI providers) for a commit, branch, or tag |
521
+ | `getCombinedStatus` | Get the combined commit status (Statuses API: legacy CI integrations) for a commit, branch, or tag |
522
+ | `getCiFailureContext` | Diagnose CI failures for a ref — combined status, failing checks, and failed workflow jobs in one call |
523
+
524
+ ### Releases
525
+
526
+ | Tool | Description |
527
+ |---|---|
528
+ | `listReleases` | List releases, newest first (includes drafts and prereleases) |
529
+ | `getLatestRelease` | Get the latest published release (body truncated by default; set `detail: full` for complete notes) |
530
+ | `getRelease` | Get a specific release by ID, including its assets |
531
+ | `getReleaseContext` | Fetch a release plus the previous release and tag comparison in one call |
532
+ | `createRelease` | Create a new release (and its tag if needed) |
533
+
428
534
  ### Commits
429
535
 
430
536
  | Tool | Description |
@@ -432,6 +538,7 @@ See [`examples/eve-agent`](../../examples/eve-agent) for a minimal agent.
432
538
  | `listCommits` | List commits, optionally filtered by file path, author, or date range |
433
539
  | `getCommit` | Get a commit's full details including changed files and diffs |
434
540
  | `getBlame` | Line-level git blame for a file (GitHub GraphQL) |
541
+ | `compareCommits` | Compare two branches, tags, or commits: ahead/behind counts, commits in between, and files that differ |
435
542
 
436
543
  ### Search
437
544
 
@@ -451,17 +558,19 @@ Create one at **GitHub → Settings → Developer settings → Personal access t
451
558
  | Permission | Level | Required for |
452
559
  |---|---|---|
453
560
  | **Metadata** | Read-only | Always required (auto-included) |
454
- | **Contents** | Read-only | `getRepository`, `listBranches`, `getFileContent`, `listCommits`, `getCommit`, `getBlame` |
455
- | **Contents** | Read and write | `createOrUpdateFile` |
456
- | **Pull requests** | Read-only | `listPullRequests`, `getPullRequest`, `listPullRequestFiles`, `listPullRequestReviews` |
457
- | **Pull requests** | Read and write | `createPullRequest`, `mergePullRequest`, `addPullRequestComment`, `createPullRequestReview` |
458
- | **Issues** | Read-only | `listIssues`, `getIssue`, `listLabels` |
459
- | **Issues** | Read and write | `createIssue`, `addIssueComment`, `closeIssue`, `addLabels`, `removeLabel` |
460
-
561
+ | **Contents** | Read-only | `getRepository`, `listBranches`, `getFileContent`, `getRepositoryTree`, `listCommits`, `getCommit`, `getBlame`, `compareCommits`, `listReleases`, `getLatestRelease`, `getRelease`, `getReleaseContext` |
562
+ | **Contents** | Read and write | `createBranch`, `createOrUpdateFile`, `createRelease` |
563
+ | **Administration** | Read and write | `forkRepository`, `createRepository` |
564
+ | **Pull requests** | Read-only | `listPullRequests`, `getPullRequest`, `listPullRequestFiles`, `listPullRequestReviews`, `getPullRequestContext` |
565
+ | **Pull requests** | Read and write | `createPullRequest`, `mergePullRequest`, `addPullRequestComment`, `createPullRequestReview`, `requestReviewers` |
566
+ | **Issues** | Read-only | `listIssues`, `getIssue`, `getIssueContext`, `listLabels` |
567
+ | **Issues** | Read and write | `createIssue`, `addIssueComment`, `closeIssue`, `addLabels`, `removeLabel`, `addAssignees`, `removeAssignees` |
461
568
  | **Gists** | Read-only | `listGists`, `getGist`, `listGistComments` |
462
569
  | **Gists** | Read and write | `createGist`, `updateGist`, `deleteGist`, `createGistComment` |
463
- | **Actions** | Read-only | `listWorkflows`, `listWorkflowRuns`, `getWorkflowRun`, `listWorkflowJobs` |
570
+ | **Actions** | Read-only | `listWorkflows`, `listWorkflowRuns`, `getWorkflowRun`, `listWorkflowJobs`, `getCiFailureContext` |
464
571
  | **Actions** | Read and write | `triggerWorkflow`, `cancelWorkflowRun`, `rerunWorkflowRun` |
572
+ | **Checks** | Read-only | `listCheckRuns`, `getCiFailureContext` |
573
+ | **Commit statuses** | Read-only | `getCombinedStatus`, `getCiFailureContext` |
465
574
 
466
575
  Search tools (`searchCode`, `searchRepositories`) work with any token.
467
576
 
@@ -483,11 +592,12 @@ type GithubToolsOptions = {
483
592
  token?: GithubTokenInput // defaults to process.env.GITHUB_TOKEN
484
593
  requireApproval?: boolean | Partial<Record<GithubWriteToolName, boolean>>
485
594
  preset?: GithubToolPreset | GithubToolPreset[]
595
+ context?: GithubToolsContext // default owner / repo / PR / issue / ref
486
596
  }
487
597
 
488
598
  type GithubTokenInput = string | (() => Promise<string>)
489
599
 
490
- type GithubToolPreset = 'code-review' | 'issue-triage' | 'repo-explorer' | 'ci-ops' | 'maintainer'
600
+ type GithubToolPreset = 'code-review' | 'issue-triage' | 'repo-explorer' | 'ci-ops' | 'security-audit' | 'release-manager' | 'maintainer'
491
601
  ```
492
602
 
493
603
  ### `createGithubAgent(options)`
@@ -497,17 +607,18 @@ Returns a `ToolLoopAgent` instance with `.generate()` and `.stream()` methods, p
497
607
  ```ts
498
608
  import { createGithubAgent } from '@github-tools/sdk'
499
609
 
500
- // Minimal — all tools, generic prompt
610
+ // Minimal: all tools, generic prompt
501
611
  const agent = createGithubAgent({
502
612
  model: 'anthropic/claude-sonnet-4.6',
503
613
  token: process.env.GITHUB_TOKEN!,
504
614
  })
505
615
 
506
- // With preset — scoped tools + tailored prompt
616
+ // With preset: scoped tools + tailored prompt
507
617
  const reviewer = createGithubAgent({
508
618
  model: 'anthropic/claude-sonnet-4.6',
509
619
  token: process.env.GITHUB_TOKEN!,
510
620
  preset: 'code-review',
621
+ context: { owner: 'vercel', repo: 'ai', pullNumber: 42 },
511
622
  })
512
623
 
513
624
  // Add context to the built-in prompt
@@ -518,7 +629,7 @@ const triager = createGithubAgent({
518
629
  additionalInstructions: 'Focus on the nuxt/ui repository. Always respond in French.',
519
630
  })
520
631
 
521
- // Full override — replace the built-in prompt entirely
632
+ // Full override: replace the built-in prompt entirely
522
633
  const custom = createGithubAgent({
523
634
  model: 'anthropic/claude-sonnet-4.6',
524
635
  token: process.env.GITHUB_TOKEN!,
@@ -526,17 +637,18 @@ const custom = createGithubAgent({
526
637
  })
527
638
 
528
639
  // Use the agent
529
- const result = await reviewer.generate({ prompt: 'Review PR #42 on vercel/ai' })
530
- const stream = reviewer.stream({ prompt: 'Review PR #42 on vercel/ai' })
640
+ const result = await reviewer.generate({ prompt: 'Review this PR' })
641
+ const stream = reviewer.stream({ prompt: 'Review this PR' })
531
642
  ```
532
643
 
533
644
  | Option | Description |
534
645
  |---|---|
535
- | `model` | Language model — string (`'anthropic/claude-sonnet-4.6'`) or provider instance |
646
+ | `model` | Language model: string (`'anthropic/claude-sonnet-4.6'`) or provider instance |
536
647
  | `token` | GitHub token string or async provider |
537
648
  | `preset` | Optional preset or array of presets to scope tools |
649
+ | `context` | Default owner / repo / pullNumber / issueNumber / ref for tools and the system prompt |
538
650
  | `requireApproval` | Approval config (same as `createGithubTools`) |
539
- | `instructions` | Replaces the built-in system prompt entirely |
651
+ | `instructions` | Replaces the built-in system prompt entirely (`context` is still appended) |
540
652
  | `additionalInstructions` | Appended to the built-in system prompt |
541
653
 
542
654
  All other `ToolLoopAgent` options (`stopWhen`, `toolChoice`, `onStepFinish`, etc.) are passed through.
@@ -556,6 +668,7 @@ pnpm add workflow @workflow/ai
556
668
  #### Streaming (chat UI)
557
669
 
558
670
  ```ts
671
+ // durable-chat.workflow.ts
559
672
  import { createDurableGithubAgent } from '@github-tools/sdk/workflow'
560
673
  import { getWritable } from 'workflow'
561
674
  import type { ModelMessage, UIMessageChunk } from 'ai'
@@ -572,9 +685,10 @@ async function chatWorkflow(messages: ModelMessage[], token: string) {
572
685
  }
573
686
  ```
574
687
 
575
- #### Non-streaming (bot / background job — needs `"use step"`)
688
+ #### Non-streaming (bot / background job, needs `"use step"`)
576
689
 
577
690
  ```ts
691
+ // agent-turn.step.ts
578
692
  import { createGithubAgent } from '@github-tools/sdk'
579
693
 
580
694
  async function agentTurn(prompt: string) {
@@ -591,7 +705,7 @@ async function agentTurn(prompt: string) {
591
705
 
592
706
  > See [`examples/pr-review-agent`](../../examples/pr-review-agent) for a complete PR review agent built with Chat SDK and Vercel Workflow.
593
707
 
594
- All presets (`code-review`, `issue-triage`, `ci-ops`, `repo-explorer`, `maintainer`) work with `createDurableGithubAgent`. Options mirror `createGithubAgent` with additional pass-through for `WorkflowAgentOptions` fields like `experimental_telemetry`, `onStepEnd`, `onEnd`, and `prepareStep`. Write tools honor `requireApproval` via `needsApproval`.
708
+ All presets (`code-review`, `issue-triage`, `ci-ops`, `repo-explorer`, `security-audit`, `release-manager`, `maintainer`) work with `createDurableGithubAgent`. Options mirror `createGithubAgent` with additional pass-through for `WorkflowAgentOptions` fields like `experimental_telemetry`, `onStepEnd`, `onEnd`, and `prepareStep`. Write tools honor `requireApproval` via `needsApproval`.
595
709
 
596
710
  ### `resolveGithubToken(token?)`
597
711
 
@@ -1,18 +1,24 @@
1
- import { ht as GithubToolName } from "../index-Cs1Kebmt.mjs";
2
- import { t as ConnectGithubEveToolsOptions } from "../types-DwHrGKWO.mjs";
3
- import * as _$eve_tools0 from "eve/tools";
4
-
1
+ import { jt as GithubToolName } from "../index-CtID5dUi.mjs";
2
+ import { a as GithubConnectorInput, t as ConnectGithubEveToolsOptions } from "../types-BVLof-5R.mjs";
5
3
  //#region src/connect/eve.d.ts
6
4
  /**
7
5
  * Register eve GitHub tools backed by a Vercel Connect connector.
8
6
  * Scopes are derived from `preset` unless overridden in `connect.scopes`.
9
7
  *
8
+ * `connector` may be a static name or a resolver function — e.g. to pick a
9
+ * different connector per environment (production vs. preview) or tenant.
10
+ *
10
11
  * TODO(eve-connect-bundle): eve's authored-module bundler inlines workspace-linked
11
12
  * SDK code and code-splits `@vercel/connect` unless the agent sets
12
13
  * `build.externalDependencies: ['@vercel/connect']` in `agent.ts`. Remove that
13
14
  * requirement when upstream eve externalizes this path.
15
+ *
16
+ * @deprecated Use the mountable `@github-tools/eve-extension` instead and pass `connector`
17
+ * directly to `githubExtension(...)` — no separate Connect import is needed. This direct
18
+ * import keeps working but is no longer the recommended path. See
19
+ * https://github-tools.com/frameworks/eve-extension#vercel-connect.
14
20
  */
15
- declare function connectGithubTools(connector: string, options?: ConnectGithubEveToolsOptions): _$eve_tools0.DynamicSentinel<Partial<Record<GithubToolName, _$eve_tools0.ToolDefinition<unknown, unknown>>>>;
21
+ declare function connectGithubTools(connector: GithubConnectorInput, options?: ConnectGithubEveToolsOptions): import("eve/tools").DynamicSentinel<Partial<Record<GithubToolName, import("eve/tools").ToolDefinition<unknown, unknown>>>>;
16
22
  //#endregion
17
23
  export { connectGithubTools };
18
24
  //# sourceMappingURL=eve.d.mts.map
@@ -1 +1 @@
1
- {"version":3,"file":"eve.d.mts","names":[],"sources":["../../src/connect/eve.ts"],"mappings":";;;;;;;;;AAaA;;;;;iBAAgB,kBAAA,CACd,SAAA,UACA,OAAA,GAAS,4BAAA,GAAiC,YAAA,CAAA,eAAA,CAAA,OAAA,CAAA,MAAA,CAAA,cAAA,EAAA,YAAA,CAAA,cAAA"}
1
+ {"version":3,"file":"eve.d.mts","names":[],"sources":["../../src/connect/eve.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;iBAsBgB,mBACd,WAAW,sBACX,UAAS,mDAAiC,gBAAA,QAAA,OAAjC,oCAAiC"}
@@ -1,14 +1,22 @@
1
- import { l as createGithubTools } from "../eve-UPaHEGVi.mjs";
2
- import { t as connectGithubToken } from "../token-CW8lQBND.mjs";
1
+ import { l as createGithubTools } from "../eve-DmiXBuli.mjs";
2
+ import { t as connectGithubToken } from "../token-sbepWIkd.mjs";
3
3
  //#region src/connect/eve.ts
4
4
  /**
5
5
  * Register eve GitHub tools backed by a Vercel Connect connector.
6
6
  * Scopes are derived from `preset` unless overridden in `connect.scopes`.
7
7
  *
8
+ * `connector` may be a static name or a resolver function — e.g. to pick a
9
+ * different connector per environment (production vs. preview) or tenant.
10
+ *
8
11
  * TODO(eve-connect-bundle): eve's authored-module bundler inlines workspace-linked
9
12
  * SDK code and code-splits `@vercel/connect` unless the agent sets
10
13
  * `build.externalDependencies: ['@vercel/connect']` in `agent.ts`. Remove that
11
14
  * requirement when upstream eve externalizes this path.
15
+ *
16
+ * @deprecated Use the mountable `@github-tools/eve-extension` instead and pass `connector`
17
+ * directly to `githubExtension(...)` — no separate Connect import is needed. This direct
18
+ * import keeps working but is no longer the recommended path. See
19
+ * https://github-tools.com/frameworks/eve-extension#vercel-connect.
12
20
  */
13
21
  function connectGithubTools(connector, options = {}) {
14
22
  const { connect, preset, ...rest } = options;
@@ -1 +1 @@
1
- {"version":3,"file":"eve.mjs","names":["createEveGithubTools"],"sources":["../../src/connect/eve.ts"],"sourcesContent":["import { createGithubTools as createEveGithubTools } from '../eve'\nimport { connectGithubToken } from './token'\nimport type { ConnectGithubEveToolsOptions } from './types'\n\n/**\n * Register eve GitHub tools backed by a Vercel Connect connector.\n * Scopes are derived from `preset` unless overridden in `connect.scopes`.\n *\n * TODO(eve-connect-bundle): eve's authored-module bundler inlines workspace-linked\n * SDK code and code-splits `@vercel/connect` unless the agent sets\n * `build.externalDependencies: ['@vercel/connect']` in `agent.ts`. Remove that\n * requirement when upstream eve externalizes this path.\n */\nexport function connectGithubTools(\n connector: string,\n options: ConnectGithubEveToolsOptions = {},\n) {\n const { connect, preset, ...rest } = options\n\n return createEveGithubTools({\n ...rest,\n preset,\n token: connectGithubToken(connector, { preset, params: connect }),\n })\n}\n"],"mappings":";;;;;;;;;;;;AAaA,SAAgB,mBACd,WACA,UAAwC,EAAE,EAC1C;CACA,MAAM,EAAE,SAAS,QAAQ,GAAG,SAAS;AAErC,QAAOA,kBAAqB;EAC1B,GAAG;EACH;EACA,OAAO,mBAAmB,WAAW;GAAE;GAAQ,QAAQ;GAAS,CAAC;EAClE,CAAC"}
1
+ {"version":3,"file":"eve.mjs","names":["createEveGithubTools"],"sources":["../../src/connect/eve.ts"],"sourcesContent":["import { createGithubTools as createEveGithubTools } from '../eve'\nimport type { GithubConnectorInput } from './connector'\nimport { connectGithubToken } from './token'\nimport type { ConnectGithubEveToolsOptions } from './types'\n\n/**\n * Register eve GitHub tools backed by a Vercel Connect connector.\n * Scopes are derived from `preset` unless overridden in `connect.scopes`.\n *\n * `connector` may be a static name or a resolver function — e.g. to pick a\n * different connector per environment (production vs. preview) or tenant.\n *\n * TODO(eve-connect-bundle): eve's authored-module bundler inlines workspace-linked\n * SDK code and code-splits `@vercel/connect` unless the agent sets\n * `build.externalDependencies: ['@vercel/connect']` in `agent.ts`. Remove that\n * requirement when upstream eve externalizes this path.\n *\n * @deprecated Use the mountable `@github-tools/eve-extension` instead and pass `connector`\n * directly to `githubExtension(...)` — no separate Connect import is needed. This direct\n * import keeps working but is no longer the recommended path. See\n * https://github-tools.com/frameworks/eve-extension#vercel-connect.\n */\nexport function connectGithubTools(\n connector: GithubConnectorInput,\n options: ConnectGithubEveToolsOptions = {},\n) {\n const { connect, preset, ...rest } = options\n\n return createEveGithubTools({\n ...rest,\n preset,\n token: connectGithubToken(connector, { preset, params: connect }),\n })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,mBACd,WACA,UAAwC,CAAC,GACzC;CACA,MAAM,EAAE,SAAS,QAAQ,GAAG,SAAS;CAErC,OAAOA,kBAAqB;EAC1B,GAAG;EACH;EACA,OAAO,mBAAmB,WAAW;GAAE;GAAQ,QAAQ;EAAQ,CAAC;CAClE,CAAC;AACH"}