@github-tools/sdk 1.8.2 → 1.10.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 (50) hide show
  1. package/README.md +247 -78
  2. package/dist/connect/eve.d.mts +18 -7
  3. package/dist/connect/eve.d.mts.map +1 -1
  4. package/dist/connect/eve.mjs +17 -4
  5. package/dist/connect/eve.mjs.map +1 -1
  6. package/dist/connect.d.mts +31 -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-runtime-CI4dR_hI.d.mts +54 -0
  11. package/dist/eve-runtime-CI4dR_hI.d.mts.map +1 -0
  12. package/dist/eve-runtime-CIcrt7MD.mjs +674 -0
  13. package/dist/eve-runtime-CIcrt7MD.mjs.map +1 -0
  14. package/dist/eve-runtime.d.mts +4 -0
  15. package/dist/eve-runtime.mjs +3 -0
  16. package/dist/eve.d.mts +331 -112
  17. package/dist/eve.d.mts.map +1 -1
  18. package/dist/eve.mjs +356 -3
  19. package/dist/eve.mjs.map +1 -0
  20. package/dist/index-B0nL0C00.d.mts +746 -0
  21. package/dist/index-B0nL0C00.d.mts.map +1 -0
  22. package/dist/index.d.mts +2 -2
  23. package/dist/index.mjs +3 -3
  24. package/dist/src-v-LjzPpR.mjs +1371 -0
  25. package/dist/src-v-LjzPpR.mjs.map +1 -0
  26. package/dist/{token-CW8lQBND.mjs → token-DDMlEkK-.mjs} +74 -7
  27. package/dist/token-DDMlEkK-.mjs.map +1 -0
  28. package/dist/types-VW0m0Uxl.d.mts +39 -0
  29. package/dist/types-VW0m0Uxl.d.mts.map +1 -0
  30. package/dist/{types-B0mvQgJf.d.mts → types-Ygt1pw1N.d.mts} +30 -9
  31. package/dist/types-Ygt1pw1N.d.mts.map +1 -0
  32. package/dist/workflow.d.mts +7 -7
  33. package/dist/workflow.d.mts.map +1 -1
  34. package/dist/workflow.mjs +6 -4
  35. package/dist/workflow.mjs.map +1 -1
  36. package/dist/write-tools-uIVfURVp.mjs +3509 -0
  37. package/dist/write-tools-uIVfURVp.mjs.map +1 -0
  38. package/package.json +17 -13
  39. package/dist/eve-UPaHEGVi.mjs +0 -512
  40. package/dist/eve-UPaHEGVi.mjs.map +0 -1
  41. package/dist/index-Cs1Kebmt.d.mts +0 -463
  42. package/dist/index-Cs1Kebmt.d.mts.map +0 -1
  43. package/dist/src-CfzZfU82.mjs +0 -812
  44. package/dist/src-CfzZfU82.mjs.map +0 -1
  45. package/dist/token-CW8lQBND.mjs.map +0 -1
  46. package/dist/types-B0mvQgJf.d.mts.map +0 -1
  47. package/dist/types-DwHrGKWO.d.mts +0 -27
  48. package/dist/types-DwHrGKWO.d.mts.map +0 -1
  49. package/dist/write-tools-Dx9LfYlU.mjs +0 -1840
  50. 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
+ 75 tools cover repositories, branches, pull requests, issues, reactions, discussions, notifications, 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,35 @@ 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
+ // Discussion moderator: Discussions plus light issue context
85
+ createGithubTools({ token, preset: 'discussion-moderator' })
86
+
87
+ // Notification inbox: triage user notifications (needs a Notifications PAT)
88
+ createGithubTools({ token, preset: 'notification-inbox' })
89
+
90
+ // PR author: branches, file edits, and opening PRs
91
+ createGithubTools({ token, preset: 'pr-author' })
92
+
93
+ // Full catalog: all tools (same as omitting preset)
56
94
  createGithubTools({ token, preset: 'maintainer' })
57
95
  ```
58
96
 
59
- Presets are composable — pass an array to combine them:
97
+ Presets are composable, pass an array to combine them:
60
98
 
61
99
  ```ts
62
100
  createGithubTools({ token, preset: ['code-review', 'issue-triage'] })
@@ -64,13 +102,18 @@ createGithubTools({ token, preset: ['code-review', 'issue-triage'] })
64
102
 
65
103
  | Preset | Tools included |
66
104
  |---|---|
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 |
72
-
73
- Omit `preset` to get all tools (same as `maintainer`).
105
+ | `code-review` | `getPullRequest`, `listPullRequests`, `listPullRequestFiles`, `listPullRequestReviews`, `getPullRequestContext`, `getFileContent`, `listCommits`, `getCommit`, `getBlame`, `compareCommits`, `getRepository`, `listBranches`, `searchCode`, `listCheckRuns`, `getCombinedStatus`, `updatePullRequest`, `addPullRequestComment`, `updatePullRequestComment`, `deletePullRequestComment`, `createPullRequestReview`, `requestReviewers` |
106
+ | `issue-triage` | `listIssues`, `getIssueContext`, `createIssue`, `addIssueComment`, `updateIssueComment`, `deleteIssueComment`, `closeIssue`, `updateIssue`, `addLabels`, `removeLabel`, `addAssignees`, `removeAssignees`, `listIssueReactions`, `addIssueReaction`, `listCommentReactions`, `addCommentReaction`, `getRepository`, `searchRepositories`, `searchCode`, `searchIssues` |
107
+ | `repo-explorer` | All read-only tools including discussions, gists, workflows, checks/statuses, and releases (no write operations) |
108
+ | `ci-ops` | `listWorkflows`, `listWorkflowRuns`, `getWorkflowRun`, `listWorkflowJobs`, `listCheckRuns`, `getCombinedStatus`, `getCiFailureContext`, `triggerWorkflow`, `cancelWorkflowRun`, `rerunWorkflowRun`, `getRepository`, `listBranches`, `listCommits`, `getCommit` |
109
+ | `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) |
110
+ | `release-manager` | `listReleases`, `getLatestRelease`, `getRelease`, `getReleaseContext`, `createRelease`, `updateRelease`, `deleteRelease`, `compareCommits`, `listCommits`, `getCommit`, `listWorkflowRuns`, `getWorkflowRun`, `listPullRequests`, `getPullRequest`, `getRepository`, `listBranches` |
111
+ | `discussion-moderator` | `listDiscussions`, `getDiscussion`, `addDiscussionComment`, `getRepository`, `searchIssues`, `getIssueContext`, `addIssueComment` |
112
+ | `notification-inbox` | `listNotifications`, `markNotificationRead`, `getIssue`, `getPullRequest`, `getRepository` (requires a Notifications PAT) |
113
+ | `pr-author` | `getRepository`, `listBranches`, `getFileContent`, `createBranch`, `createOrUpdateFile`, `createPullRequest`, `updatePullRequest`, `getPullRequest`, `listPullRequestFiles`, `compareCommits`, `getCommit` |
114
+ | `maintainer` | All 75 tools |
115
+
116
+ Start with the smallest preset that fits. Use `maintainer` or omit `preset` when you need the full catalog. Full breakdown: [Tools Catalog](https://github-tools.com/api/tools-catalog).
74
117
 
75
118
  ### Cherry-Picking Tools
76
119
 
@@ -115,7 +158,7 @@ createGithubTools({
115
158
  })
116
159
  ```
117
160
 
118
- Write tools: `createOrUpdateFile`, `createPullRequest`, `mergePullRequest`, `addPullRequestComment`, `createPullRequestReview`, `createIssue`, `addIssueComment`, `closeIssue`, `addLabels`, `removeLabel`, `createGist`, `updateGist`, `deleteGist`, `createGistComment`, `triggerWorkflow`, `cancelWorkflowRun`, `rerunWorkflowRun`.
161
+ Write tools: `createBranch`, `forkRepository`, `createRepository`, `createOrUpdateFile`, `createPullRequest`, `mergePullRequest`, `updatePullRequest`, `addPullRequestComment`, `updatePullRequestComment`, `deletePullRequestComment`, `createPullRequestReview`, `requestReviewers`, `createIssue`, `addIssueComment`, `updateIssueComment`, `deleteIssueComment`, `closeIssue`, `updateIssue`, `addLabels`, `removeLabel`, `addAssignees`, `removeAssignees`, `addIssueReaction`, `addCommentReaction`, `addDiscussionComment`, `markNotificationRead`, `createGist`, `updateGist`, `deleteGist`, `createGistComment`, `triggerWorkflow`, `cancelWorkflowRun`, `rerunWorkflowRun`, `createRelease`, `updateRelease`, `deleteRelease`.
119
162
 
120
163
  All other tools are read-only and never require approval.
121
164
 
@@ -191,7 +234,7 @@ const result = await generateText({
191
234
  })
192
235
  ```
193
236
 
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.
237
+ 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
238
 
196
239
  ## Durable Agents (Vercel Workflow SDK)
197
240
 
@@ -209,13 +252,13 @@ const agent = createDurableGithubAgent({
209
252
  })
210
253
  ```
211
254
 
212
- All presets work with `createDurableGithubAgent`. Write tools honor `requireApproval` via `needsApproval` — the workflow pauses until the user approves or denies.
255
+ All presets work with `createDurableGithubAgent`. Write tools honor `requireApproval` via `needsApproval`: the workflow pauses until the user approves or denies.
213
256
 
214
- > `workflow` and `@ai-sdk/workflow` are optional peer dependencies — install them only when using the workflow subpath.
257
+ > `workflow` and `@ai-sdk/workflow` are optional peer dependencies, install them only when using the workflow subpath.
215
258
 
216
259
  ## Vercel Connect
217
260
 
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.
261
+ [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
262
 
220
263
  ```sh
221
264
  pnpm add @vercel/connect
@@ -229,28 +272,21 @@ const tools = connectGithubTools('github/my-connector', {
229
272
  })
230
273
  ```
231
274
 
232
- For eve agents, import from `@github-tools/sdk/connect/eve`:
275
+ 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
276
 
234
277
  ```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
- ```
278
+ // agent/extensions/github.ts
279
+ import githubExtension from '@github-tools/eve-extension'
243
280
 
244
- ```ts
245
- // agent/tools/github.ts
246
- import { connectGithubTools } from '@github-tools/sdk/connect/eve'
247
-
248
- export default connectGithubTools('github/my-connector', {
281
+ export default githubExtension({
282
+ connector: 'github/my-connector',
249
283
  preset: 'maintainer',
250
284
  })
251
285
  ```
252
286
 
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).
287
+ 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).
288
+
289
+ `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
290
 
255
291
  Token provider only (custom factories):
256
292
 
@@ -263,7 +299,7 @@ createGithubTools({
263
299
  })
264
300
  ```
265
301
 
266
- Pass the same `preset` to `connectGithubToken` — it derives Connect scopes independently of the `preset` given to `createGithubTools`.
302
+ Pass the same `preset` to `connectGithubToken`: it derives Connect scopes independently of the `preset` given to `createGithubTools`.
267
303
 
268
304
  Override installation, repositories, or scopes via `connect`:
269
305
 
@@ -278,13 +314,65 @@ connectGithubTools('github/my-connector', {
278
314
  })
279
315
  ```
280
316
 
281
- > `@vercel/connect` is an optional peer dependency — install it only when using the `/connect` subpath.
317
+ > `@vercel/connect` is an optional peer dependency, install it only when using the `/connect` subpath.
318
+
319
+ `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:
320
+
321
+ ```ts
322
+ connectGithubTools(
323
+ () => (process.env.VERCEL_ENV === 'production' ? 'github/prod-connector' : 'github/preview-connector'),
324
+ { preset: 'code-review' },
325
+ )
326
+ ```
282
327
 
283
328
  ## eve
284
329
 
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.
330
+ [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 legacy `createGithubTools` / per-tool factories on `@github-tools/sdk/eve` are **deprecated** for that registration pattern; they keep working and are documented below for existing agents. Shared runtime helpers for the extension live on `@github-tools/sdk/eve-runtime` (not deprecated).
286
331
 
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).
332
+ ### eve extension (recommended)
333
+
334
+ ```sh
335
+ pnpm add @github-tools/eve-extension eve
336
+ ```
337
+
338
+ `eve` is a required peer dependency (itself requiring **`ai` v7**).
339
+
340
+ ```ts
341
+ // agent/extensions/github.ts
342
+ import githubExtension from '@github-tools/eve-extension'
343
+
344
+ export default githubExtension({
345
+ preset: ['code-review', 'issue-triage'],
346
+ requireApproval: {
347
+ mergePullRequest: true,
348
+ createIssue: 'once',
349
+ addPullRequestComment: false,
350
+ createOrUpdateFile: ({ toolInput }) => toolInput?.owner !== 'vercel-labs',
351
+ },
352
+ })
353
+ ```
354
+
355
+ 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.
356
+
357
+ For Vercel Connect, pass `connector` directly, no separate import needed:
358
+
359
+ ```ts
360
+ // agent/extensions/github.ts
361
+ import githubExtension from '@github-tools/eve-extension'
362
+
363
+ export default githubExtension({
364
+ connector: 'github/my-connector',
365
+ preset: 'maintainer',
366
+ })
367
+ ```
368
+
369
+ 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.
370
+
371
+ 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.
372
+
373
+ ### eve, direct import (deprecated)
374
+
375
+ 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
376
 
289
377
  ```sh
290
378
  pnpm add @github-tools/sdk eve ai zod
@@ -307,9 +395,9 @@ export default createGithubTools({
307
395
  })
308
396
  ```
309
397
 
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`.
398
+ 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
399
 
312
- ### Approval (eve)
400
+ #### Approval (eve)
313
401
 
314
402
  | Value | Maps to | Behavior |
315
403
  |---|---|---|
@@ -321,9 +409,9 @@ Dynamic tools are named by their **bare map key** — the model sees `listPullRe
321
409
 
322
410
  Default (no `requireApproval`): all write tools → `always()`. Unlisted write tools keep the `always()` fail-safe default.
323
411
 
324
- Unlike the Workflow SDK subpath, eve approval **works durably** — gated tools pause the session until a human approves.
412
+ Unlike the Workflow SDK subpath, eve approval **works durably**: gated tools pause the session until a human approves.
325
413
 
326
- ### Cherry-picking (one tool per file)
414
+ #### Cherry-picking (one tool per file)
327
415
 
328
416
  ```ts
329
417
  // agent/tools/list_pull_requests.ts
@@ -332,7 +420,7 @@ import { listPullRequests } from '@github-tools/sdk/eve'
332
420
  export default listPullRequests()
333
421
  ```
334
422
 
335
- ### Idempotency
423
+ #### Idempotency
336
424
 
337
425
  eve replays completed steps but re-runs steps interrupted mid-execution. Write tools vary:
338
426
 
@@ -341,13 +429,18 @@ eve replays completed steps but re-runs steps interrupted mid-execution. Write t
341
429
  | `createOrUpdateFile` | Natural when content + `sha` unchanged (skips no-op updates) |
342
430
  | `closeIssue` | Natural when already closed |
343
431
  | `createBranch` | Natural when branch exists at same SHA |
344
- | `addIssueComment`, `createIssue`, `mergePullRequest`, … | **Not** idempotent — each call creates new side effects |
432
+ | `removeAssignees` | Natural: removing an assignee that isn't assigned is a no-op on GitHub |
433
+ | `addIssueReaction`, `addCommentReaction` | Natural: GitHub returns the existing reaction when the user already reacted with the same content |
434
+ | `markNotificationRead` | Natural when the thread is already read |
435
+ | `updateIssue`, `updatePullRequest`, `updateRelease`, `updateIssueComment`, `updatePullRequestComment` | **Not** idempotent: each call applies a new revision |
436
+ | `deleteIssueComment`, `deletePullRequestComment`, `deleteRelease` | **Not** idempotent: deleting an already-deleted resource returns 404 from GitHub |
437
+ | `addIssueComment`, `addDiscussionComment`, `createIssue`, `mergePullRequest`, `createRelease`, … | **Not** idempotent: each call creates new side effects |
345
438
 
346
439
  Gate non-idempotent writes behind `always()` or `once()` where replay safety matters.
347
440
 
348
- ### Vercel Connect
441
+ #### Vercel Connect
349
442
 
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:
443
+ 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
444
 
352
445
  ```ts
353
446
  // agent/tools/github.ts
@@ -358,21 +451,27 @@ export default connectGithubTools('github/my-connector', {
358
451
  })
359
452
  ```
360
453
 
361
- Add `build: { externalDependencies: ['@vercel/connect'] }` to `agent.ts` — see [Vercel Connect](#vercel-connect) above for the full setup checklist.
454
+ Add `build: { externalDependencies: ['@vercel/connect'] }` to `agent.ts`. See [Vercel Connect](#vercel-connect) above for the full setup checklist.
362
455
 
363
- > `eve` is an optional peer dependency — install it only when using the `/eve` subpath.
456
+ > `eve` is an optional peer dependency, install it only when using the `/eve` subpath.
364
457
 
365
458
  See [`examples/eve-agent`](../../examples/eve-agent) for a minimal agent.
366
459
 
367
460
  ## Available Tools
368
461
 
462
+ 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.
463
+
369
464
  ### Repository
370
465
 
371
466
  | Tool | Description |
372
467
  |---|---|
373
468
  | `getRepository` | Get repository metadata (stars, language, default branch, …) |
374
469
  | `listBranches` | List branches |
375
- | `getFileContent` | Read a file or directory listing |
470
+ | `getFileContent` | Read a file or directory listing (prefer `startLine`/`endLine` or `maxLines` for large files) |
471
+ | `getRepositoryTree` | List the file and directory structure at a given ref |
472
+ | `createBranch` | Create a new branch from an existing branch or commit SHA |
473
+ | `forkRepository` | Fork a repository to a user or organization |
474
+ | `createRepository` | Create a new repository for a user or organization |
376
475
  | `createOrUpdateFile` | Create or update a file and commit it |
377
476
 
378
477
  ### Pull Requests
@@ -380,26 +479,63 @@ See [`examples/eve-agent`](../../examples/eve-agent) for a minimal agent.
380
479
  | Tool | Description |
381
480
  |---|---|
382
481
  | `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 |
482
+ | `getPullRequest` | Get a PR's full details (diff stats, body, merge status; body truncated by default) |
483
+ | `listPullRequestFiles` | List files changed in a PR (patches omitted by default; set `includePatch` / `filenames` for diffs) |
385
484
  | `listPullRequestReviews` | List reviews on a PR (approvals, change requests, comments) |
485
+ | `getPullRequestContext` | Fetch PR details plus files, reviews, and optional CI checks in one call |
386
486
  | `createPullRequest` | Open a new PR |
387
487
  | `mergePullRequest` | Merge a PR (merge, squash, or rebase) |
488
+ | `updatePullRequest` | Update a PR's title, body, state, base branch, or draft status |
388
489
  | `addPullRequestComment` | Post a comment on a PR |
490
+ | `updatePullRequestComment` | Edit the body of a PR comment |
491
+ | `deletePullRequestComment` | Permanently delete a PR comment |
389
492
  | `createPullRequestReview` | Submit a formal review (approve, request changes, or comment) with inline comments |
493
+ | `requestReviewers` | Request reviews from users or teams on a PR |
390
494
 
391
495
  ### Issues
392
496
 
393
497
  | Tool | Description |
394
498
  |---|---|
395
499
  | `listIssues` | List issues filtered by state and labels |
396
- | `getIssue` | Get an issue's full details |
500
+ | `getIssue` | Get an issue's details (body truncated by default; set `detail: full` for complete text) |
501
+ | `getIssueContext` | Fetch an issue plus label names and recent comments in one call |
397
502
  | `createIssue` | Open a new issue |
398
503
  | `addIssueComment` | Post a comment on an issue |
504
+ | `updateIssueComment` | Edit the body of an issue comment |
505
+ | `deleteIssueComment` | Permanently delete an issue comment |
399
506
  | `closeIssue` | Close an issue (completed or not planned) |
507
+ | `updateIssue` | Update an issue's title, body, labels, milestone, or assignees — set `state: 'open'` to reopen |
400
508
  | `listLabels` | List labels available in a repository |
401
509
  | `addLabels` | Add labels to an issue or pull request |
402
510
  | `removeLabel` | Remove a label from an issue or pull request |
511
+ | `addAssignees` | Assign users to an issue or pull request |
512
+ | `removeAssignees` | Remove assignees from an issue or pull request |
513
+
514
+ ### Reactions
515
+
516
+ Pull request conversations share the issue numbering, so the issue-level tools work on PRs too.
517
+
518
+ | Tool | Description |
519
+ |---|---|
520
+ | `listIssueReactions` | List reactions on an issue or pull request, with per-emoji counts |
521
+ | `addIssueReaction` | React to an issue or pull request (`+1`, `-1`, `laugh`, `confused`, `heart`, `hooray`, `rocket`, `eyes`) |
522
+ | `listCommentReactions` | List reactions on an issue or pull request comment |
523
+ | `addCommentReaction` | React to an issue or pull request comment |
524
+
525
+ ### Discussions
526
+
527
+ | Tool | Description |
528
+ |---|---|
529
+ | `listDiscussions` | List discussions, most recently updated first, optionally filtered by category name (cursor-paginated) |
530
+ | `getDiscussion` | Get a discussion by number (body truncated by default; set `detail: full` for complete text) |
531
+ | `addDiscussionComment` | Post a comment on a discussion |
532
+
533
+ ### Notifications
534
+
535
+ | Tool | Description |
536
+ |---|---|
537
+ | `listNotifications` | List notification threads for the authenticated user (unread only unless `all: true`) |
538
+ | `markNotificationRead` | Mark a single notification thread as read |
403
539
 
404
540
  ### Gists
405
541
 
@@ -425,6 +561,26 @@ See [`examples/eve-agent`](../../examples/eve-agent) for a minimal agent.
425
561
  | `cancelWorkflowRun` | Cancel an in-progress workflow run |
426
562
  | `rerunWorkflowRun` | Re-run a workflow run, optionally only failed jobs |
427
563
 
564
+ ### Checks and Statuses
565
+
566
+ | Tool | Description |
567
+ |---|---|
568
+ | `listCheckRuns` | List check runs (Checks API: GitHub Actions and other CI providers) for a commit, branch, or tag |
569
+ | `getCombinedStatus` | Get the combined commit status (Statuses API: legacy CI integrations) for a commit, branch, or tag |
570
+ | `getCiFailureContext` | Diagnose CI failures for a ref — combined status, failing checks, and failed workflow jobs in one call |
571
+
572
+ ### Releases
573
+
574
+ | Tool | Description |
575
+ |---|---|
576
+ | `listReleases` | List releases, newest first (includes drafts and prereleases) |
577
+ | `getLatestRelease` | Get the latest published release (body truncated by default; set `detail: full` for complete notes) |
578
+ | `getRelease` | Get a specific release by ID, including its assets |
579
+ | `getReleaseContext` | Fetch a release plus the previous release and tag comparison in one call |
580
+ | `createRelease` | Create a new release (and its tag if needed) |
581
+ | `updateRelease` | Update a release's tag, target, title, notes, draft, or prerelease status |
582
+ | `deleteRelease` | Permanently delete a release (does not delete the underlying git tag) |
583
+
428
584
  ### Commits
429
585
 
430
586
  | Tool | Description |
@@ -432,13 +588,15 @@ See [`examples/eve-agent`](../../examples/eve-agent) for a minimal agent.
432
588
  | `listCommits` | List commits, optionally filtered by file path, author, or date range |
433
589
  | `getCommit` | Get a commit's full details including changed files and diffs |
434
590
  | `getBlame` | Line-level git blame for a file (GitHub GraphQL) |
591
+ | `compareCommits` | Compare two branches, tags, or commits: ahead/behind counts, commits in between, and files that differ |
435
592
 
436
593
  ### Search
437
594
 
438
595
  | Tool | Description |
439
596
  |---|---|
440
- | `searchCode` | Search code across GitHub with qualifier support |
597
+ | `searchCode` | Search code across GitHub with qualifier support (includes matching text snippets when available) |
441
598
  | `searchRepositories` | Search repositories by keyword, topic, language, stars, … |
599
+ | `searchIssues` | Search issues and pull requests using qualifiers like `is:open`, `type:pr`, or `label:bug` |
442
600
 
443
601
  ## GitHub Token
444
602
 
@@ -451,19 +609,24 @@ Create one at **GitHub → Settings → Developer settings → Personal access t
451
609
  | Permission | Level | Required for |
452
610
  |---|---|---|
453
611
  | **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
-
612
+ | **Contents** | Read-only | `getRepository`, `listBranches`, `getFileContent`, `getRepositoryTree`, `listCommits`, `getCommit`, `getBlame`, `compareCommits`, `listReleases`, `getLatestRelease`, `getRelease`, `getReleaseContext` |
613
+ | **Contents** | Read and write | `createBranch`, `createOrUpdateFile`, `createRelease`, `updateRelease`, `deleteRelease` |
614
+ | **Administration** | Read and write | `forkRepository`, `createRepository` |
615
+ | **Pull requests** | Read-only | `listPullRequests`, `getPullRequest`, `listPullRequestFiles`, `listPullRequestReviews`, `getPullRequestContext` |
616
+ | **Pull requests** | Read and write | `createPullRequest`, `mergePullRequest`, `updatePullRequest`, `addPullRequestComment`, `updatePullRequestComment`, `deletePullRequestComment`, `createPullRequestReview`, `requestReviewers` |
617
+ | **Issues** | Read-only | `listIssues`, `getIssue`, `getIssueContext`, `listLabels`, `listIssueReactions`, `listCommentReactions` |
618
+ | **Issues** | Read and write | `createIssue`, `addIssueComment`, `updateIssueComment`, `deleteIssueComment`, `closeIssue`, `updateIssue`, `addLabels`, `removeLabel`, `addAssignees`, `removeAssignees`, `addIssueReaction`, `addCommentReaction` |
619
+ | **Discussions** | Read-only | `listDiscussions`, `getDiscussion` |
620
+ | **Discussions** | Read and write | `addDiscussionComment` |
461
621
  | **Gists** | Read-only | `listGists`, `getGist`, `listGistComments` |
462
622
  | **Gists** | Read and write | `createGist`, `updateGist`, `deleteGist`, `createGistComment` |
463
- | **Actions** | Read-only | `listWorkflows`, `listWorkflowRuns`, `getWorkflowRun`, `listWorkflowJobs` |
623
+ | **Notifications** (account) | Read and write | `listNotifications`, `markNotificationRead` |
624
+ | **Actions** | Read-only | `listWorkflows`, `listWorkflowRuns`, `getWorkflowRun`, `listWorkflowJobs`, `getCiFailureContext` |
464
625
  | **Actions** | Read and write | `triggerWorkflow`, `cancelWorkflowRun`, `rerunWorkflowRun` |
626
+ | **Checks** | Read-only | `listCheckRuns`, `getCiFailureContext` |
627
+ | **Commit statuses** | Read-only | `getCombinedStatus`, `getCiFailureContext` |
465
628
 
466
- Search tools (`searchCode`, `searchRepositories`) work with any token.
629
+ Search tools (`searchCode`, `searchRepositories`, `searchIssues`) work with any token.
467
630
 
468
631
  ### Classic token
469
632
 
@@ -483,11 +646,12 @@ type GithubToolsOptions = {
483
646
  token?: GithubTokenInput // defaults to process.env.GITHUB_TOKEN
484
647
  requireApproval?: boolean | Partial<Record<GithubWriteToolName, boolean>>
485
648
  preset?: GithubToolPreset | GithubToolPreset[]
649
+ context?: GithubToolsContext // default owner / repo / PR / issue / ref
486
650
  }
487
651
 
488
652
  type GithubTokenInput = string | (() => Promise<string>)
489
653
 
490
- type GithubToolPreset = 'code-review' | 'issue-triage' | 'repo-explorer' | 'ci-ops' | 'maintainer'
654
+ type GithubToolPreset = 'code-review' | 'issue-triage' | 'repo-explorer' | 'ci-ops' | 'security-audit' | 'release-manager' | 'discussion-moderator' | 'notification-inbox' | 'pr-author' | 'maintainer'
491
655
  ```
492
656
 
493
657
  ### `createGithubAgent(options)`
@@ -497,17 +661,12 @@ Returns a `ToolLoopAgent` instance with `.generate()` and `.stream()` methods, p
497
661
  ```ts
498
662
  import { createGithubAgent } from '@github-tools/sdk'
499
663
 
500
- // Minimal — all tools, generic prompt
501
- const agent = createGithubAgent({
502
- model: 'anthropic/claude-sonnet-4.6',
503
- token: process.env.GITHUB_TOKEN!,
504
- })
505
-
506
- // With preset — scoped tools + tailored prompt
664
+ // Prefer a preset: scoped tools + tailored prompt
507
665
  const reviewer = createGithubAgent({
508
666
  model: 'anthropic/claude-sonnet-4.6',
509
667
  token: process.env.GITHUB_TOKEN!,
510
668
  preset: 'code-review',
669
+ context: { owner: 'vercel', repo: 'ai', pullNumber: 42 },
511
670
  })
512
671
 
513
672
  // Add context to the built-in prompt
@@ -518,7 +677,14 @@ const triager = createGithubAgent({
518
677
  additionalInstructions: 'Focus on the nuxt/ui repository. Always respond in French.',
519
678
  })
520
679
 
521
- // Full override — replace the built-in prompt entirely
680
+ // Full catalog (omit preset or use maintainer)
681
+ const agent = createGithubAgent({
682
+ model: 'anthropic/claude-sonnet-4.6',
683
+ token: process.env.GITHUB_TOKEN!,
684
+ preset: 'maintainer',
685
+ })
686
+
687
+ // Full override: replace the built-in prompt entirely
522
688
  const custom = createGithubAgent({
523
689
  model: 'anthropic/claude-sonnet-4.6',
524
690
  token: process.env.GITHUB_TOKEN!,
@@ -526,17 +692,18 @@ const custom = createGithubAgent({
526
692
  })
527
693
 
528
694
  // 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' })
695
+ const result = await reviewer.generate({ prompt: 'Review this PR' })
696
+ const stream = reviewer.stream({ prompt: 'Review this PR' })
531
697
  ```
532
698
 
533
699
  | Option | Description |
534
700
  |---|---|
535
- | `model` | Language model — string (`'anthropic/claude-sonnet-4.6'`) or provider instance |
701
+ | `model` | Language model: string (`'anthropic/claude-sonnet-4.6'`) or provider instance |
536
702
  | `token` | GitHub token string or async provider |
537
703
  | `preset` | Optional preset or array of presets to scope tools |
704
+ | `context` | Default owner / repo / pullNumber / issueNumber / ref for tools and the system prompt |
538
705
  | `requireApproval` | Approval config (same as `createGithubTools`) |
539
- | `instructions` | Replaces the built-in system prompt entirely |
706
+ | `instructions` | Replaces the built-in system prompt entirely (`context` is still appended) |
540
707
  | `additionalInstructions` | Appended to the built-in system prompt |
541
708
 
542
709
  All other `ToolLoopAgent` options (`stopWhen`, `toolChoice`, `onStepFinish`, etc.) are passed through.
@@ -556,6 +723,7 @@ pnpm add workflow @workflow/ai
556
723
  #### Streaming (chat UI)
557
724
 
558
725
  ```ts
726
+ // durable-chat.workflow.ts
559
727
  import { createDurableGithubAgent } from '@github-tools/sdk/workflow'
560
728
  import { getWritable } from 'workflow'
561
729
  import type { ModelMessage, UIMessageChunk } from 'ai'
@@ -572,9 +740,10 @@ async function chatWorkflow(messages: ModelMessage[], token: string) {
572
740
  }
573
741
  ```
574
742
 
575
- #### Non-streaming (bot / background job — needs `"use step"`)
743
+ #### Non-streaming (bot / background job, needs `"use step"`)
576
744
 
577
745
  ```ts
746
+ // agent-turn.step.ts
578
747
  import { createGithubAgent } from '@github-tools/sdk'
579
748
 
580
749
  async function agentTurn(prompt: string) {
@@ -591,7 +760,7 @@ async function agentTurn(prompt: string) {
591
760
 
592
761
  > See [`examples/pr-review-agent`](../../examples/pr-review-agent) for a complete PR review agent built with Chat SDK and Vercel Workflow.
593
762
 
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`.
763
+ All presets (`code-review`, `issue-triage`, `ci-ops`, `repo-explorer`, `security-audit`, `release-manager`, `discussion-moderator`, `notification-inbox`, `pr-author`, `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
764
 
596
765
  ### `resolveGithubToken(token?)`
597
766
 
@@ -1,18 +1,29 @@
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 { Yt as GithubToolName } from "../index-B0nL0C00.mjs";
2
+ import { a as GithubConnectorInput, t as ConnectGithubEveToolsOptions } from "../types-VW0m0Uxl.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
+ *
11
+ * @deprecated Use the mountable `@github-tools/eve-extension` instead and pass `connector`
12
+ * directly to `githubExtension(...)` — no separate Connect import is needed. This direct
13
+ * import is also **not durable** under multi-turn eve Workflow replay (`defineTool` inside
14
+ * `node_modules` is not hoisted); mount `@github-tools/eve-extension` instead
15
+ * (see https://github.com/vercel-labs/github-tools/issues/51 and
16
+ * https://github-tools.com/frameworks/eve-extension).
17
+ *
18
+ * Shared runtime helpers used by the extension are on `@github-tools/sdk/eve-runtime`
19
+ * (not deprecated).
20
+ *
10
21
  * TODO(eve-connect-bundle): eve's authored-module bundler inlines workspace-linked
11
22
  * SDK code and code-splits `@vercel/connect` unless the agent sets
12
- * `build.externalDependencies: ['@vercel/connect']` in `agent.ts`. Remove that
13
- * requirement when upstream eve externalizes this path.
23
+ * `build.externalDependencies: ['@vercel/connect']` in `agent.ts`. Prefer the
24
+ * eve extension (pre-built) so that workaround is unnecessary.
14
25
  */
15
- declare function connectGithubTools(connector: string, options?: ConnectGithubEveToolsOptions): _$eve_tools0.DynamicSentinel<Partial<Record<GithubToolName, _$eve_tools0.ToolDefinition<unknown, unknown>>>>;
26
+ declare function connectGithubTools(connector: GithubConnectorInput, options?: ConnectGithubEveToolsOptions): import("eve/tools").DynamicSentinel<Partial<Record<GithubToolName, import("eve/tools").ToolDefinition<unknown, unknown>>>>;
16
27
  //#endregion
17
28
  export { connectGithubTools };
18
29
  //# 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":";;;;;;;;;;;;;;;;;;;;;;;;;iBA2BgB,mBACd,WAAW,sBACX,UAAS,mDAAiC,gBAAA,QAAA,OAAjC,oCAAiC"}