@github-tools/sdk 1.9.0 → 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 (42) hide show
  1. package/README.md +82 -27
  2. package/dist/connect/eve.d.mts +14 -9
  3. package/dist/connect/eve.d.mts.map +1 -1
  4. package/dist/connect/eve.mjs +14 -9
  5. package/dist/connect/eve.mjs.map +1 -1
  6. package/dist/connect.d.mts +16 -8
  7. package/dist/connect.d.mts.map +1 -1
  8. package/dist/connect.mjs +2 -2
  9. package/dist/eve-runtime-CI4dR_hI.d.mts +54 -0
  10. package/dist/eve-runtime-CI4dR_hI.d.mts.map +1 -0
  11. package/dist/eve-runtime-CIcrt7MD.mjs +674 -0
  12. package/dist/eve-runtime-CIcrt7MD.mjs.map +1 -0
  13. package/dist/eve-runtime.d.mts +4 -0
  14. package/dist/eve-runtime.mjs +3 -0
  15. package/dist/eve.d.mts +5 -34
  16. package/dist/eve.d.mts.map +1 -1
  17. package/dist/eve.mjs +356 -3
  18. package/dist/eve.mjs.map +1 -0
  19. package/dist/{index-CtID5dUi.d.mts → index-B0nL0C00.d.mts} +159 -19
  20. package/dist/index-B0nL0C00.d.mts.map +1 -0
  21. package/dist/index.d.mts +2 -2
  22. package/dist/index.mjs +3 -3
  23. package/dist/{src-D6vC3V8r.mjs → src-v-LjzPpR.mjs} +354 -68
  24. package/dist/src-v-LjzPpR.mjs.map +1 -0
  25. package/dist/{token-sbepWIkd.mjs → token-DDMlEkK-.mjs} +34 -5
  26. package/dist/token-DDMlEkK-.mjs.map +1 -0
  27. package/dist/{types-BVLof-5R.d.mts → types-VW0m0Uxl.d.mts} +3 -3
  28. package/dist/{types-BVLof-5R.d.mts.map → types-VW0m0Uxl.d.mts.map} +1 -1
  29. package/dist/{types-BOnJ0Rou.d.mts → types-Ygt1pw1N.d.mts} +4 -3
  30. package/dist/types-Ygt1pw1N.d.mts.map +1 -0
  31. package/dist/workflow.d.mts +1 -1
  32. package/dist/workflow.mjs +2 -2
  33. package/dist/{write-tools-cg_ialNd.mjs → write-tools-uIVfURVp.mjs} +792 -25
  34. package/dist/write-tools-uIVfURVp.mjs.map +1 -0
  35. package/package.json +5 -1
  36. package/dist/eve-DmiXBuli.mjs +0 -864
  37. package/dist/eve-DmiXBuli.mjs.map +0 -1
  38. package/dist/index-CtID5dUi.d.mts.map +0 -1
  39. package/dist/src-D6vC3V8r.mjs.map +0 -1
  40. package/dist/token-sbepWIkd.mjs.map +0 -1
  41. package/dist/types-BOnJ0Rou.d.mts.map +0 -1
  42. package/dist/write-tools-cg_ialNd.mjs.map +0 -1
package/README.md CHANGED
@@ -33,7 +33,7 @@ They all reach the GitHub API, but none of them were built as an agent's tool la
33
33
  | Production agents that must survive restarts and timeouts | [Durable Agents](#durable-agents-vercel-workflow-sdk) |
34
34
  | A GitHub, Slack, or Discord bot | [Chat SDK docs](https://github-tools.com/frameworks/chat-sdk) |
35
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.
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.
37
37
 
38
38
  ## Installation
39
39
 
@@ -81,7 +81,16 @@ createGithubTools({ token, preset: 'security-audit' })
81
81
  // Release manager: releases, compare diff, commits, workflow runs, pull requests
82
82
  createGithubTools({ token, preset: 'release-manager' })
83
83
 
84
- // Full maintenance: all tools
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)
85
94
  createGithubTools({ token, preset: 'maintainer' })
86
95
  ```
87
96
 
@@ -93,15 +102,18 @@ createGithubTools({ token, preset: ['code-review', 'issue-triage'] })
93
102
 
94
103
  | Preset | Tools included |
95
104
  |---|---|
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) |
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) |
99
108
  | `ci-ops` | `listWorkflows`, `listWorkflowRuns`, `getWorkflowRun`, `listWorkflowJobs`, `listCheckRuns`, `getCombinedStatus`, `getCiFailureContext`, `triggerWorkflow`, `cancelWorkflowRun`, `rerunWorkflowRun`, `getRepository`, `listBranches`, `listCommits`, `getCommit` |
100
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) |
101
- | `release-manager` | `listReleases`, `getLatestRelease`, `getRelease`, `getReleaseContext`, `createRelease`, `compareCommits`, `listCommits`, `getCommit`, `listWorkflowRuns`, `getWorkflowRun`, `listPullRequests`, `getPullRequest`, `getRepository`, `listBranches` |
102
- | `maintainer` | All 57 tools |
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 |
103
115
 
104
- Omit `preset` to get all tools (same as `maintainer`). Full breakdown: [Tools Catalog](https://github-tools.com/api/tools-catalog).
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).
105
117
 
106
118
  ### Cherry-Picking Tools
107
119
 
@@ -146,7 +158,7 @@ createGithubTools({
146
158
  })
147
159
  ```
148
160
 
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`.
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`.
150
162
 
151
163
  All other tools are read-only and never require approval.
152
164
 
@@ -315,7 +327,7 @@ connectGithubTools(
315
327
 
316
328
  ## eve
317
329
 
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.
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).
319
331
 
320
332
  ### eve extension (recommended)
321
333
 
@@ -418,7 +430,11 @@ eve replays completed steps but re-runs steps interrupted mid-execution. Write t
418
430
  | `closeIssue` | Natural when already closed |
419
431
  | `createBranch` | Natural when branch exists at same SHA |
420
432
  | `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 |
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 |
422
438
 
423
439
  Gate non-idempotent writes behind `always()` or `once()` where replay safety matters.
424
440
 
@@ -469,7 +485,10 @@ List tools (`listCommits`, `listPullRequests`, `listIssues`, `listWorkflowRuns`,
469
485
  | `getPullRequestContext` | Fetch PR details plus files, reviews, and optional CI checks in one call |
470
486
  | `createPullRequest` | Open a new PR |
471
487
  | `mergePullRequest` | Merge a PR (merge, squash, or rebase) |
488
+ | `updatePullRequest` | Update a PR's title, body, state, base branch, or draft status |
472
489
  | `addPullRequestComment` | Post a comment on a PR |
490
+ | `updatePullRequestComment` | Edit the body of a PR comment |
491
+ | `deletePullRequestComment` | Permanently delete a PR comment |
473
492
  | `createPullRequestReview` | Submit a formal review (approve, request changes, or comment) with inline comments |
474
493
  | `requestReviewers` | Request reviews from users or teams on a PR |
475
494
 
@@ -479,16 +498,45 @@ List tools (`listCommits`, `listPullRequests`, `listIssues`, `listWorkflowRuns`,
479
498
  |---|---|
480
499
  | `listIssues` | List issues filtered by state and labels |
481
500
  | `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 |
501
+ | `getIssueContext` | Fetch an issue plus label names and recent comments in one call |
483
502
  | `createIssue` | Open a new issue |
484
503
  | `addIssueComment` | Post a comment on an issue |
504
+ | `updateIssueComment` | Edit the body of an issue comment |
505
+ | `deleteIssueComment` | Permanently delete an issue comment |
485
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 |
486
508
  | `listLabels` | List labels available in a repository |
487
509
  | `addLabels` | Add labels to an issue or pull request |
488
510
  | `removeLabel` | Remove a label from an issue or pull request |
489
511
  | `addAssignees` | Assign users to an issue or pull request |
490
512
  | `removeAssignees` | Remove assignees from an issue or pull request |
491
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 |
539
+
492
540
  ### Gists
493
541
 
494
542
  | Tool | Description |
@@ -530,6 +578,8 @@ List tools (`listCommits`, `listPullRequests`, `listIssues`, `listWorkflowRuns`,
530
578
  | `getRelease` | Get a specific release by ID, including its assets |
531
579
  | `getReleaseContext` | Fetch a release plus the previous release and tag comparison in one call |
532
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) |
533
583
 
534
584
  ### Commits
535
585
 
@@ -544,8 +594,9 @@ List tools (`listCommits`, `listPullRequests`, `listIssues`, `listWorkflowRuns`,
544
594
 
545
595
  | Tool | Description |
546
596
  |---|---|
547
- | `searchCode` | Search code across GitHub with qualifier support |
597
+ | `searchCode` | Search code across GitHub with qualifier support (includes matching text snippets when available) |
548
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` |
549
600
 
550
601
  ## GitHub Token
551
602
 
@@ -559,20 +610,23 @@ Create one at **GitHub → Settings → Developer settings → Personal access t
559
610
  |---|---|---|
560
611
  | **Metadata** | Read-only | Always required (auto-included) |
561
612
  | **Contents** | Read-only | `getRepository`, `listBranches`, `getFileContent`, `getRepositoryTree`, `listCommits`, `getCommit`, `getBlame`, `compareCommits`, `listReleases`, `getLatestRelease`, `getRelease`, `getReleaseContext` |
562
- | **Contents** | Read and write | `createBranch`, `createOrUpdateFile`, `createRelease` |
613
+ | **Contents** | Read and write | `createBranch`, `createOrUpdateFile`, `createRelease`, `updateRelease`, `deleteRelease` |
563
614
  | **Administration** | Read and write | `forkRepository`, `createRepository` |
564
615
  | **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` |
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` |
568
621
  | **Gists** | Read-only | `listGists`, `getGist`, `listGistComments` |
569
622
  | **Gists** | Read and write | `createGist`, `updateGist`, `deleteGist`, `createGistComment` |
623
+ | **Notifications** (account) | Read and write | `listNotifications`, `markNotificationRead` |
570
624
  | **Actions** | Read-only | `listWorkflows`, `listWorkflowRuns`, `getWorkflowRun`, `listWorkflowJobs`, `getCiFailureContext` |
571
625
  | **Actions** | Read and write | `triggerWorkflow`, `cancelWorkflowRun`, `rerunWorkflowRun` |
572
626
  | **Checks** | Read-only | `listCheckRuns`, `getCiFailureContext` |
573
627
  | **Commit statuses** | Read-only | `getCombinedStatus`, `getCiFailureContext` |
574
628
 
575
- Search tools (`searchCode`, `searchRepositories`) work with any token.
629
+ Search tools (`searchCode`, `searchRepositories`, `searchIssues`) work with any token.
576
630
 
577
631
  ### Classic token
578
632
 
@@ -597,7 +651,7 @@ type GithubToolsOptions = {
597
651
 
598
652
  type GithubTokenInput = string | (() => Promise<string>)
599
653
 
600
- type GithubToolPreset = 'code-review' | 'issue-triage' | 'repo-explorer' | 'ci-ops' | 'security-audit' | 'release-manager' | 'maintainer'
654
+ type GithubToolPreset = 'code-review' | 'issue-triage' | 'repo-explorer' | 'ci-ops' | 'security-audit' | 'release-manager' | 'discussion-moderator' | 'notification-inbox' | 'pr-author' | 'maintainer'
601
655
  ```
602
656
 
603
657
  ### `createGithubAgent(options)`
@@ -607,13 +661,7 @@ Returns a `ToolLoopAgent` instance with `.generate()` and `.stream()` methods, p
607
661
  ```ts
608
662
  import { createGithubAgent } from '@github-tools/sdk'
609
663
 
610
- // Minimal: all tools, generic prompt
611
- const agent = createGithubAgent({
612
- model: 'anthropic/claude-sonnet-4.6',
613
- token: process.env.GITHUB_TOKEN!,
614
- })
615
-
616
- // With preset: scoped tools + tailored prompt
664
+ // Prefer a preset: scoped tools + tailored prompt
617
665
  const reviewer = createGithubAgent({
618
666
  model: 'anthropic/claude-sonnet-4.6',
619
667
  token: process.env.GITHUB_TOKEN!,
@@ -629,6 +677,13 @@ const triager = createGithubAgent({
629
677
  additionalInstructions: 'Focus on the nuxt/ui repository. Always respond in French.',
630
678
  })
631
679
 
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
+
632
687
  // Full override: replace the built-in prompt entirely
633
688
  const custom = createGithubAgent({
634
689
  model: 'anthropic/claude-sonnet-4.6',
@@ -705,7 +760,7 @@ async function agentTurn(prompt: string) {
705
760
 
706
761
  > See [`examples/pr-review-agent`](../../examples/pr-review-agent) for a complete PR review agent built with Chat SDK and Vercel Workflow.
707
762
 
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`.
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`.
709
764
 
710
765
  ### `resolveGithubToken(token?)`
711
766
 
@@ -1,5 +1,5 @@
1
- import { jt as GithubToolName } from "../index-CtID5dUi.mjs";
2
- import { a as GithubConnectorInput, t as ConnectGithubEveToolsOptions } from "../types-BVLof-5R.mjs";
1
+ import { Yt as GithubToolName } from "../index-B0nL0C00.mjs";
2
+ import { a as GithubConnectorInput, t as ConnectGithubEveToolsOptions } from "../types-VW0m0Uxl.mjs";
3
3
  //#region src/connect/eve.d.ts
4
4
  /**
5
5
  * Register eve GitHub tools backed by a Vercel Connect connector.
@@ -8,15 +8,20 @@ import { a as GithubConnectorInput, t as ConnectGithubEveToolsOptions } from "..
8
8
  * `connector` may be a static name or a resolver function — e.g. to pick a
9
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
12
- * SDK code and code-splits `@vercel/connect` unless the agent sets
13
- * `build.externalDependencies: ['@vercel/connect']` in `agent.ts`. Remove that
14
- * requirement when upstream eve externalizes this path.
15
- *
16
11
  * @deprecated Use the mountable `@github-tools/eve-extension` instead and pass `connector`
17
12
  * 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.
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
+ *
21
+ * TODO(eve-connect-bundle): eve's authored-module bundler inlines workspace-linked
22
+ * SDK code and code-splits `@vercel/connect` unless the agent sets
23
+ * `build.externalDependencies: ['@vercel/connect']` in `agent.ts`. Prefer the
24
+ * eve extension (pre-built) so that workaround is unnecessary.
20
25
  */
21
26
  declare function connectGithubTools(connector: GithubConnectorInput, options?: ConnectGithubEveToolsOptions): import("eve/tools").DynamicSentinel<Partial<Record<GithubToolName, import("eve/tools").ToolDefinition<unknown, unknown>>>>;
22
27
  //#endregion
@@ -1 +1 @@
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
+ {"version":3,"file":"eve.d.mts","names":[],"sources":["../../src/connect/eve.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;iBA2BgB,mBACd,WAAW,sBACX,UAAS,mDAAiC,gBAAA,QAAA,OAAjC,oCAAiC"}
@@ -1,5 +1,5 @@
1
- import { l as createGithubTools } from "../eve-DmiXBuli.mjs";
2
- import { t as connectGithubToken } from "../token-sbepWIkd.mjs";
1
+ import { createGithubTools } from "../eve.mjs";
2
+ import { t as connectGithubToken } from "../token-DDMlEkK-.mjs";
3
3
  //#region src/connect/eve.ts
4
4
  /**
5
5
  * Register eve GitHub tools backed by a Vercel Connect connector.
@@ -8,15 +8,20 @@ import { t as connectGithubToken } from "../token-sbepWIkd.mjs";
8
8
  * `connector` may be a static name or a resolver function — e.g. to pick a
9
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
12
- * SDK code and code-splits `@vercel/connect` unless the agent sets
13
- * `build.externalDependencies: ['@vercel/connect']` in `agent.ts`. Remove that
14
- * requirement when upstream eve externalizes this path.
15
- *
16
11
  * @deprecated Use the mountable `@github-tools/eve-extension` instead and pass `connector`
17
12
  * 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.
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
+ *
21
+ * TODO(eve-connect-bundle): eve's authored-module bundler inlines workspace-linked
22
+ * SDK code and code-splits `@vercel/connect` unless the agent sets
23
+ * `build.externalDependencies: ['@vercel/connect']` in `agent.ts`. Prefer the
24
+ * eve extension (pre-built) so that workaround is unnecessary.
20
25
  */
21
26
  function connectGithubTools(connector, options = {}) {
22
27
  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 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"}
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 * @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 is also **not durable** under multi-turn eve Workflow replay (`defineTool` inside\n * `node_modules` is not hoisted); mount `@github-tools/eve-extension` instead\n * (see https://github.com/vercel-labs/github-tools/issues/51 and\n * https://github-tools.com/frameworks/eve-extension).\n *\n * Shared runtime helpers used by the extension are on `@github-tools/sdk/eve-runtime`\n * (not deprecated).\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`. Prefer the\n * eve extension (pre-built) so that workaround is unnecessary.\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":";;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,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"}
@@ -1,15 +1,15 @@
1
- import { Dt as GithubToolPreset, jt as GithubToolName, mt as GithubTokenInput, ut as AllGithubTools } from "./index-CtID5dUi.mjs";
2
- import { a as GithubConnectorInput, i as GithubConnectParams, n as ConnectGithubTokenOptions, o as resolveGithubConnector, r as ConnectGithubToolsOptions, t as ConnectGithubEveToolsOptions } from "./types-BVLof-5R.mjs";
1
+ import { Gt as GithubToolPreset, Mt as GithubTokenInput, Ot as AllGithubTools, Yt as GithubToolName } from "./index-B0nL0C00.mjs";
2
+ import { a as GithubConnectorInput, i as GithubConnectParams, n as ConnectGithubTokenOptions, o as resolveGithubConnector, r as ConnectGithubToolsOptions, t as ConnectGithubEveToolsOptions } from "./types-VW0m0Uxl.mjs";
3
3
  import "@vercel/connect";
4
4
  //#region src/connect/scopes.d.ts
5
5
  /**
6
6
  * Vercel Connect scope strings mapped to each {@link GithubToolPreset}.
7
7
  *
8
8
  * Scopes mirror GitHub App permissions (`contents`, `pull_requests`, `issues`,
9
- * `actions`, `checks`, `statuses`, `administration`, `metadata`) and must cover
10
- * every read/write family a preset's tools touch, not just its primary domain.
11
- * Release tools fall under the `contents` permission on GitHub Apps, so they
12
- * need no scope of their own.
9
+ * `discussions`, `actions`, `checks`, `statuses`, `administration`, `metadata`)
10
+ * and must cover every read/write family a preset's tools touch, not just its
11
+ * primary domain. Release tools fall under the `contents` permission on GitHub
12
+ * Apps, and reaction tools under `issues`, so neither needs a scope of its own.
13
13
  *
14
14
  * Gist tools in `repo-explorer` and `maintainer` are intentionally left
15
15
  * unscoped: the Gists API only accepts GitHub App *user* access tokens, never
@@ -17,15 +17,23 @@ import "@vercel/connect";
17
17
  * installation tokens. Gist calls made with a Connect-derived token 403
18
18
  * regardless of requested scopes — use a fine-grained PAT with the "Gists"
19
19
  * account permission for those tools instead.
20
+ *
21
+ * Notification tools in `maintainer` and `notification-inbox` are unscoped for
22
+ * the same reason: `notifications` is an account-level GitHub App permission
23
+ * that only applies to user access tokens, so `listNotifications` /
24
+ * `markNotificationRead` need a PAT with the "Notifications" account permission.
20
25
  */
21
26
  declare const PRESET_CONNECT_SCOPES: {
22
- readonly 'repo-explorer': readonly ["contents:read", "metadata:read", "pull_requests:read", "issues:read", "actions:read", "checks:read", "statuses:read"];
27
+ readonly 'repo-explorer': readonly ["contents:read", "metadata:read", "pull_requests:read", "issues:read", "discussions:read", "actions:read", "checks:read", "statuses:read"];
23
28
  readonly 'code-review': readonly ["contents:read", "metadata:read", "pull_requests:read", "pull_requests:write", "checks:read", "statuses:read"];
24
29
  readonly 'issue-triage': readonly ["contents:read", "metadata:read", "issues:read", "issues:write"];
25
30
  readonly 'ci-ops': readonly ["contents:read", "metadata:read", "actions:read", "actions:write", "checks:read", "statuses:read"];
26
31
  readonly 'security-audit': readonly ["contents:read", "metadata:read", "pull_requests:read", "issues:read", "issues:write", "actions:read", "checks:read", "statuses:read"];
27
32
  readonly 'release-manager': readonly ["contents:read", "contents:write", "metadata:read", "pull_requests:read", "actions:read", "actions:write"];
28
- readonly maintainer: readonly ["contents:read", "contents:write", "metadata:read", "pull_requests:read", "pull_requests:write", "issues:read", "issues:write", "actions:read", "actions:write", "checks:read", "statuses:read", "administration:read", "administration:write"];
33
+ readonly 'discussion-moderator': readonly ["contents:read", "metadata:read", "issues:read", "issues:write", "discussions:read", "discussions:write"];
34
+ readonly 'notification-inbox': readonly ["contents:read", "metadata:read", "pull_requests:read", "issues:read"];
35
+ readonly 'pr-author': readonly ["contents:read", "contents:write", "metadata:read", "pull_requests:read", "pull_requests:write"];
36
+ readonly maintainer: readonly ["contents:read", "contents:write", "metadata:read", "pull_requests:read", "pull_requests:write", "issues:read", "issues:write", "discussions:read", "discussions:write", "actions:read", "actions:write", "checks:read", "statuses:read", "administration:read", "administration:write"];
29
37
  };
30
38
  /**
31
39
  * Returns Vercel Connect scopes for a preset or combined presets.
@@ -1 +1 @@
1
- {"version":3,"file":"connect.d.mts","names":[],"sources":["../src/connect/scopes.ts","../src/connect/token.ts","../src/connect/tools.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;cAkBa;;;;;;;;;;;;;iBA4EG,6BACd,SAAS,mBAAmB;;;;;;;;;;;iBCjFd,mBACd,WAAW,sBACX,UAAS,4BACR;;;;;;;;;;iBCLa,mBACd,WAAW,sBACX,UAAS,4BAAA,iBAA8B,KAAA,gBAAA"}
1
+ {"version":3,"file":"connect.d.mts","names":[],"sources":["../src/connect/scopes.ts","../src/connect/token.ts","../src/connect/tools.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;cAuBa;;;;;;;;;;;;;;;;iBAoGG,6BACd,SAAS,mBAAmB;;;;;;;;;;;iBC9Gd,mBACd,WAAW,sBACX,UAAS,4BACR;;;;;;;;;;iBCLa,mBACd,WAAW,sBACX,UAAS,4BAAA,iBAA8B,KAAA,gBAAA"}
package/dist/connect.mjs CHANGED
@@ -1,5 +1,5 @@
1
- import { t as createGithubTools } from "./src-D6vC3V8r.mjs";
2
- import { i as resolveGithubConnector, n as PRESET_CONNECT_SCOPES, r as connectGithubScopesForPreset, t as connectGithubToken } from "./token-sbepWIkd.mjs";
1
+ import { t as createGithubTools } from "./src-v-LjzPpR.mjs";
2
+ import { i as resolveGithubConnector, n as PRESET_CONNECT_SCOPES, r as connectGithubScopesForPreset, t as connectGithubToken } from "./token-DDMlEkK-.mjs";
3
3
  //#region src/connect/tools.ts
4
4
  /**
5
5
  * Create GitHub tools backed by a Vercel Connect connector.
@@ -0,0 +1,54 @@
1
+ import { Gt as GithubToolPreset, Ut as GithubWriteToolName, Wt as CombinedPresetToolNames, Yt as GithubToolName, qt as PresetToolName } from "./index-B0nL0C00.mjs";
2
+ import { i as EveToolFactoryOptions, n as EveApprovalValue, r as EveGithubToolsOptions, t as EveApprovalConfig } from "./types-Ygt1pw1N.mjs";
3
+ import { z } from "zod";
4
+ import { Approval, ToolDefinition, ToolModelOutput } from "eve/tools";
5
+ //#region src/eve/build.d.ts
6
+ type BuildOptions = EveGithubToolsOptions | (EveToolFactoryOptions & {
7
+ preset?: EveGithubToolsOptions['preset'];
8
+ });
9
+ type EveToolMap = Partial<Record<GithubToolName, ToolDefinition>>;
10
+ declare function buildEveToolDefinition(name: GithubToolName, options?: BuildOptions): ToolDefinition;
11
+ declare function buildEveToolMap(options?: EveGithubToolsOptions): EveToolMap;
12
+ declare function createEveGithubToolsDynamic(options?: EveGithubToolsOptions): import("eve/tools").DynamicSentinel<Partial<Record<GithubToolName, ToolDefinition<unknown, unknown>>>>;
13
+ declare function listResolvedEveToolNames(options?: {
14
+ preset?: undefined;
15
+ include?: undefined;
16
+ exclude?: undefined;
17
+ }): GithubToolName[];
18
+ declare function listResolvedEveToolNames<P extends GithubToolPreset>(options: {
19
+ preset: P;
20
+ include?: undefined;
21
+ exclude?: undefined;
22
+ }): PresetToolName<P>[];
23
+ declare function listResolvedEveToolNames<P extends readonly GithubToolPreset[]>(options: {
24
+ preset: P;
25
+ include?: undefined;
26
+ exclude?: undefined;
27
+ }): CombinedPresetToolNames<P>[];
28
+ declare function listResolvedEveToolNames(options: Pick<EveGithubToolsOptions, 'preset' | 'include' | 'exclude'>): GithubToolName[];
29
+ /**
30
+ * Tool descriptors (no `execute`) for authored eve `defineTool` loops.
31
+ * Prefer this when registering tools outside the SDK package so durable transforms can hoist inline execute.
32
+ */
33
+ declare function listEveToolDescriptors(options?: EveGithubToolsOptions): {
34
+ name: GithubToolName;
35
+ description: string;
36
+ inputSchema: import("zod").ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;
37
+ writeTool: GithubWriteToolName | undefined;
38
+ toModelOutput: ((output: unknown) => import("eve/tools").ToolModelOutput) | undefined;
39
+ }[];
40
+ /**
41
+ * Execute a GitHub tool by name with the given eve options (token/context/attribution).
42
+ * Used by `@github-tools/eve-extension` so `execute` only closes over a serializable tool name.
43
+ */
44
+ declare function executeGithubEveTool(name: GithubToolName, input: Record<string, unknown>, options?: EveGithubToolsOptions): Promise<unknown>;
45
+ //#endregion
46
+ //#region src/eve/approval.d.ts
47
+ declare function mapEveApprovalValue(value: EveApprovalValue): Approval;
48
+ declare function resolveEveApproval(toolName: GithubWriteToolName, config: EveApprovalConfig | undefined): Approval | undefined;
49
+ //#endregion
50
+ //#region src/eve/load-eve.d.ts
51
+ declare const MISSING_EVE_MESSAGE = "The \"eve\" package is required to use @github-tools/sdk/eve. Install it with: pnpm add eve";
52
+ //#endregion
53
+ export { buildEveToolMap as a, listEveToolDescriptors as c, buildEveToolDefinition as i, listResolvedEveToolNames as l, mapEveApprovalValue as n, createEveGithubToolsDynamic as o, resolveEveApproval as r, executeGithubEveTool as s, MISSING_EVE_MESSAGE as t };
54
+ //# sourceMappingURL=eve-runtime-CI4dR_hI.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"eve-runtime-CI4dR_hI.d.mts","names":[],"sources":["../src/eve/build.ts","../src/eve/approval.ts","../src/eve/load-eve.ts"],"mappings":";;;;;KASK,eAAe,yBAAyB;EAA0B,SAAS;;KAC3E,aAAa,QAAQ,OAAO,gBAAgB;iBAkCjC,uBACd,MAAM,gBACN,UAAS,eACR;iBA4Ba,gBAAgB,UAAS,wBAA6B;iBAiCtD,4BAA4B,UAAS,4CAA0B,gBAAA,QAAA,OAAA,gBAAA;iBAY/D,yBAAyB;EAAY;EAAoB;EAAqB;IAAwB;iBACtG,yBAAyB,UAAU,kBAAkB;EAAW,QAAQ;EAAG;EAAqB;IAAwB,eAAe;iBACvI,yBAAyB,mBAAmB,oBAAoB;EAAW,QAAQ;EAAG;EAAqB;IAAwB,wBAAwB;iBAC3J,yBAAyB,SAAS,KAAK,2DAA2D;;;;;iBAUlG,uBAAuB,UAAS;;;;;;;;;;;iBAyB1B,qBACpB,MAAM,gBACN,OAAO,yBACP,UAAS,wBAA0B;;;iBC5JrB,oBAAoB,OAAO,mBAAmB;iBAY9C,mBACd,UAAU,qBACV,QAAQ,gCACP;;;cCTU"}