@github-tools/sdk 1.7.0 → 1.8.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 (40) hide show
  1. package/README.md +76 -3
  2. package/dist/connect/eve.d.mts +17 -0
  3. package/dist/connect/eve.d.mts.map +1 -0
  4. package/dist/connect/eve.mjs +27 -0
  5. package/dist/connect/eve.mjs.map +1 -0
  6. package/dist/connect.d.mts +46 -0
  7. package/dist/connect.d.mts.map +1 -0
  8. package/dist/connect.mjs +22 -0
  9. package/dist/connect.mjs.map +1 -0
  10. package/dist/eve-B-LChKzS.mjs +526 -0
  11. package/dist/eve-B-LChKzS.mjs.map +1 -0
  12. package/dist/eve.d.mts +3 -45
  13. package/dist/eve.d.mts.map +1 -1
  14. package/dist/eve.mjs +2 -521
  15. package/dist/{index-BRUYe5q0.d.mts → index-SZCaP-y9.d.mts} +44 -44
  16. package/dist/index-SZCaP-y9.d.mts.map +1 -0
  17. package/dist/index.d.mts +3 -3
  18. package/dist/index.mjs +3 -3
  19. package/dist/{src-BgnkKMD7.mjs → src-CfzZfU82.mjs} +87 -87
  20. package/dist/src-CfzZfU82.mjs.map +1 -0
  21. package/dist/token-CW8lQBND.mjs +100 -0
  22. package/dist/token-CW8lQBND.mjs.map +1 -0
  23. package/dist/{tool-types-CuirBEc8.d.mts → tool-types-C0kszIwd.d.mts} +35 -30
  24. package/dist/tool-types-C0kszIwd.d.mts.map +1 -0
  25. package/dist/types-BTanS_dq.d.mts +49 -0
  26. package/dist/types-BTanS_dq.d.mts.map +1 -0
  27. package/dist/types-DOeq0Iia.d.mts +27 -0
  28. package/dist/types-DOeq0Iia.d.mts.map +1 -0
  29. package/dist/workflow.d.mts +5 -5
  30. package/dist/workflow.d.mts.map +1 -1
  31. package/dist/workflow.mjs +3 -3
  32. package/dist/workflow.mjs.map +1 -1
  33. package/dist/{write-tools-vzlewWo5.mjs → write-tools-Dx9LfYlU.mjs} +26 -9
  34. package/dist/write-tools-Dx9LfYlU.mjs.map +1 -0
  35. package/package.json +16 -3
  36. package/dist/eve.mjs.map +0 -1
  37. package/dist/index-BRUYe5q0.d.mts.map +0 -1
  38. package/dist/src-BgnkKMD7.mjs.map +0 -1
  39. package/dist/tool-types-CuirBEc8.d.mts.map +0 -1
  40. package/dist/write-tools-vzlewWo5.mjs.map +0 -1
package/README.md CHANGED
@@ -7,7 +7,9 @@
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
- GitHub tools for the [AI SDK](https://ai-sdk.dev) — wrap GitHub's REST API as ready-to-use tools for any agent or `generateText` / `streamText` call.
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).
11
+
12
+ Docs: **[github-tools.com](https://github-tools.com)**
11
13
 
12
14
  42 tools covering repositories, branches, pull requests, issues, commits, search, gists, and workflows. Write operations support granular approval control out of the box.
13
15
 
@@ -211,6 +213,71 @@ All presets work with `createDurableGithubAgent`. Write tools honor `requireAppr
211
213
 
212
214
  > `workflow` and `@ai-sdk/workflow` are optional peer dependencies — install them only when using the workflow subpath.
213
215
 
216
+ ## Vercel Connect
217
+
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.
219
+
220
+ ```sh
221
+ pnpm add @vercel/connect
222
+ ```
223
+
224
+ ```ts
225
+ import { connectGithubTools } from '@github-tools/sdk/connect'
226
+
227
+ const tools = connectGithubTools('github/my-connector', {
228
+ preset: 'code-review',
229
+ })
230
+ ```
231
+
232
+ For eve agents, import from `@github-tools/sdk/connect/eve`:
233
+
234
+ ```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'
247
+
248
+ export default connectGithubTools('github/my-connector', {
249
+ preset: 'maintainer',
250
+ })
251
+ ```
252
+
253
+ Token provider only (custom factories):
254
+
255
+ ```ts
256
+ import { connectGithubToken } from '@github-tools/sdk/connect'
257
+
258
+ createGithubTools({
259
+ preset: 'ci-ops',
260
+ token: connectGithubToken('github/my-connector', { preset: 'ci-ops' }),
261
+ })
262
+ ```
263
+
264
+ Pass the same `preset` to `connectGithubToken` — it derives Connect scopes independently of the `preset` given to `createGithubTools`.
265
+
266
+ Override installation, repositories, or scopes via `connect`:
267
+
268
+ ```ts
269
+ connectGithubTools('github/my-connector', {
270
+ preset: 'issue-triage',
271
+ connect: {
272
+ installationId: 'inst_abc',
273
+ repositories: ['my-org/my-repo'],
274
+ scopes: ['issues:write'],
275
+ },
276
+ })
277
+ ```
278
+
279
+ > `@vercel/connect` is an optional peer dependency — install it only when using the `/connect` subpath.
280
+
214
281
  ## eve
215
282
 
216
283
  [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.
@@ -398,11 +465,13 @@ Returns an object of tools, ready to spread into `tools` of any AI SDK call.
398
465
 
399
466
  ```ts
400
467
  type GithubToolsOptions = {
401
- token?: string // defaults to process.env.GITHUB_TOKEN
468
+ token?: GithubTokenInput // defaults to process.env.GITHUB_TOKEN
402
469
  requireApproval?: boolean | Partial<Record<GithubWriteToolName, boolean>>
403
470
  preset?: GithubToolPreset | GithubToolPreset[]
404
471
  }
405
472
 
473
+ type GithubTokenInput = string | (() => Promise<string>)
474
+
406
475
  type GithubToolPreset = 'code-review' | 'issue-triage' | 'repo-explorer' | 'ci-ops' | 'maintainer'
407
476
  ```
408
477
 
@@ -449,7 +518,7 @@ const stream = reviewer.stream({ prompt: 'Review PR #42 on vercel/ai' })
449
518
  | Option | Description |
450
519
  |---|---|
451
520
  | `model` | Language model — string (`'anthropic/claude-sonnet-4.6'`) or provider instance |
452
- | `token` | GitHub personal access token |
521
+ | `token` | GitHub token string or async provider |
453
522
  | `preset` | Optional preset or array of presets to scope tools |
454
523
  | `requireApproval` | Approval config (same as `createGithubTools`) |
455
524
  | `instructions` | Replaces the built-in system prompt entirely |
@@ -509,6 +578,10 @@ async function agentTurn(prompt: string) {
509
578
 
510
579
  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`.
511
580
 
581
+ ### `resolveGithubToken(token?)`
582
+
583
+ Resolves a `GithubTokenInput` (token string, async provider, or `process.env.GITHUB_TOKEN`) to a token string. Throws when no token is available.
584
+
512
585
  ### `createOctokit(token)`
513
586
 
514
587
  Returns a configured [`octokit`](https://github.com/octokit/octokit.js) instance. Useful for building custom tools.
@@ -0,0 +1,17 @@
1
+ import { t as ConnectGithubEveToolsOptions } from "../types-DOeq0Iia.mjs";
2
+ import * as _$eve_tools0 from "eve/tools";
3
+
4
+ //#region src/connect/eve.d.ts
5
+ /**
6
+ * Register eve GitHub tools backed by a Vercel Connect connector.
7
+ * Scopes are derived from `preset` unless overridden in `connect.scopes`.
8
+ *
9
+ * TODO(eve-connect-bundle): eve's authored-module bundler inlines workspace-linked
10
+ * SDK code and code-splits `@vercel/connect` unless the agent sets
11
+ * `build.externalDependencies: ['@vercel/connect']` in `agent.ts`. Remove that
12
+ * requirement when upstream eve externalizes this path.
13
+ */
14
+ declare function connectGithubTools(connector: string, options?: ConnectGithubEveToolsOptions): _$eve_tools0.DynamicSentinel;
15
+ //#endregion
16
+ export { connectGithubTools };
17
+ //# sourceMappingURL=eve.d.mts.map
@@ -0,0 +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"}
@@ -0,0 +1,27 @@
1
+ import { l as createGithubTools } from "../eve-B-LChKzS.mjs";
2
+ import { t as connectGithubToken } from "../token-CW8lQBND.mjs";
3
+ //#region src/connect/eve.ts
4
+ /**
5
+ * Register eve GitHub tools backed by a Vercel Connect connector.
6
+ * Scopes are derived from `preset` unless overridden in `connect.scopes`.
7
+ *
8
+ * TODO(eve-connect-bundle): eve's authored-module bundler inlines workspace-linked
9
+ * SDK code and code-splits `@vercel/connect` unless the agent sets
10
+ * `build.externalDependencies: ['@vercel/connect']` in `agent.ts`. Remove that
11
+ * requirement when upstream eve externalizes this path.
12
+ */
13
+ function connectGithubTools(connector, options = {}) {
14
+ const { connect, preset, ...rest } = options;
15
+ return createGithubTools({
16
+ ...rest,
17
+ preset,
18
+ token: connectGithubToken(connector, {
19
+ preset,
20
+ params: connect
21
+ })
22
+ });
23
+ }
24
+ //#endregion
25
+ export { connectGithubTools };
26
+
27
+ //# sourceMappingURL=eve.mjs.map
@@ -0,0 +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"}
@@ -0,0 +1,46 @@
1
+ import { _ as GithubToolPreset, d as GithubTokenInput, t as AllGithubTools, x as GithubToolName } from "./tool-types-C0kszIwd.mjs";
2
+ import { i as GithubConnectParams, n as ConnectGithubTokenOptions, r as ConnectGithubToolsOptions, t as ConnectGithubEveToolsOptions } from "./types-DOeq0Iia.mjs";
3
+ //#region src/connect/scopes.d.ts
4
+ /**
5
+ * Vercel Connect scope strings mapped to each {@link GithubToolPreset}.
6
+ *
7
+ * Scopes mirror GitHub App permissions (`contents`, `pull_requests`, `issues`,
8
+ * `actions`, `administration`, `metadata`) and must cover every read/write
9
+ * family a preset's tools touch, not just its primary domain.
10
+ *
11
+ * Gist tools in `repo-explorer` and `maintainer` are intentionally left
12
+ * unscoped: the Gists API only accepts GitHub App *user* access tokens, never
13
+ * installation tokens, and Connect always mints `subject: { type: 'app' }`
14
+ * installation tokens. Gist calls made with a Connect-derived token 403
15
+ * regardless of requested scopes — use a fine-grained PAT with the "Gists"
16
+ * account permission for those tools instead.
17
+ */
18
+ declare const PRESET_CONNECT_SCOPES: {
19
+ readonly 'repo-explorer': readonly ["contents:read", "metadata:read", "pull_requests:read", "issues:read", "actions:read"];
20
+ readonly 'code-review': readonly ["contents:read", "metadata:read", "pull_requests:read", "pull_requests:write"];
21
+ readonly 'issue-triage': readonly ["contents:read", "metadata:read", "issues:read", "issues:write"];
22
+ readonly 'ci-ops': readonly ["contents:read", "metadata:read", "actions:read", "actions:write"];
23
+ readonly maintainer: readonly ["contents:read", "contents:write", "metadata:read", "pull_requests:read", "pull_requests:write", "issues:read", "issues:write", "actions:read", "actions:write", "administration:read", "administration:write"];
24
+ };
25
+ /**
26
+ * Returns Vercel Connect scopes for a preset or combined presets.
27
+ * Without a preset, returns the union of all preset scopes (full tool set).
28
+ */
29
+ declare function connectGithubScopesForPreset(preset?: GithubToolPreset | GithubToolPreset[]): string[];
30
+ //#endregion
31
+ //#region src/connect/token.d.ts
32
+ /**
33
+ * Returns a lazy GitHub token provider backed by a Vercel Connect connector.
34
+ * Scopes are derived from `preset` unless overridden in `params.scopes`.
35
+ */
36
+ declare function connectGithubToken(connector: string, options?: ConnectGithubTokenOptions): GithubTokenInput;
37
+ //#endregion
38
+ //#region src/connect/tools.d.ts
39
+ /**
40
+ * Create GitHub tools backed by a Vercel Connect connector.
41
+ * Scopes are derived from `preset` unless overridden in `connect.scopes`.
42
+ */
43
+ declare function connectGithubTools(connector: string, options?: ConnectGithubToolsOptions): AllGithubTools | Pick<AllGithubTools, GithubToolName>;
44
+ //#endregion
45
+ export { type ConnectGithubEveToolsOptions, type ConnectGithubTokenOptions, type ConnectGithubToolsOptions, type GithubConnectParams, PRESET_CONNECT_SCOPES, connectGithubScopesForPreset, connectGithubToken, connectGithubTools };
46
+ //# sourceMappingURL=connect.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"connect.d.mts","names":[],"sources":["../src/connect/scopes.ts","../src/connect/token.ts","../src/connect/tools.ts"],"mappings":";;;;;;;;AAgBA;;;;;;;;;cAAa,qBAAA;EAAA;;;;;;;;;;iBAkDG,4BAAA,CACd,MAAA,GAAS,gBAAA,GAAmB,gBAAA;;;;;;AAnD9B;iBCPgB,kBAAA,CACd,SAAA,UACA,OAAA,GAAS,yBAAA,GACR,gBAAA;;;;;;;iBCJa,kBAAA,CACd,SAAA,UACA,OAAA,GAAS,yBAAA,GAA8B,cAAA,GAAA,IAAA,CAAA,cAAA,EAAA,cAAA"}
@@ -0,0 +1,22 @@
1
+ import { t as createGithubTools } from "./src-CfzZfU82.mjs";
2
+ import { n as PRESET_CONNECT_SCOPES, r as connectGithubScopesForPreset, t as connectGithubToken } from "./token-CW8lQBND.mjs";
3
+ //#region src/connect/tools.ts
4
+ /**
5
+ * Create GitHub tools backed by a Vercel Connect connector.
6
+ * Scopes are derived from `preset` unless overridden in `connect.scopes`.
7
+ */
8
+ function connectGithubTools(connector, options = {}) {
9
+ const { connect, preset, ...rest } = options;
10
+ return createGithubTools({
11
+ ...rest,
12
+ preset,
13
+ token: connectGithubToken(connector, {
14
+ preset,
15
+ params: connect
16
+ })
17
+ });
18
+ }
19
+ //#endregion
20
+ export { PRESET_CONNECT_SCOPES, connectGithubScopesForPreset, connectGithubToken, connectGithubTools };
21
+
22
+ //# sourceMappingURL=connect.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"connect.mjs","names":[],"sources":["../src/connect/tools.ts"],"sourcesContent":["import { createGithubTools } from '../index'\nimport { connectGithubToken } from './token'\nimport type { ConnectGithubToolsOptions } from './types'\n\n/**\n * Create GitHub tools backed by a Vercel Connect connector.\n * Scopes are derived from `preset` unless overridden in `connect.scopes`.\n */\nexport function connectGithubTools(\n connector: string,\n options: ConnectGithubToolsOptions = {},\n) {\n const { connect, preset, ...rest } = options\n\n return createGithubTools({\n ...rest,\n preset,\n token: connectGithubToken(connector, { preset, params: connect }),\n })\n}\n"],"mappings":";;;;;;;AAQA,SAAgB,mBACd,WACA,UAAqC,EAAE,EACvC;CACA,MAAM,EAAE,SAAS,QAAQ,GAAG,SAAS;AAErC,QAAO,kBAAkB;EACvB,GAAG;EACH;EACA,OAAO,mBAAmB,WAAW;GAAE;GAAQ,QAAQ;GAAS,CAAC;EAClE,CAAC"}