@github-tools/sdk 1.7.0 → 1.8.1

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 (39) hide show
  1. package/README.md +78 -3
  2. package/dist/connect/eve.d.mts +18 -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-UPaHEGVi.mjs +512 -0
  11. package/dist/eve-UPaHEGVi.mjs.map +1 -0
  12. package/dist/eve.d.mts +47 -89
  13. package/dist/eve.d.mts.map +1 -1
  14. package/dist/eve.mjs +2 -521
  15. package/dist/{tool-types-CuirBEc8.d.mts → index-Cs1Kebmt.d.mts} +251 -32
  16. package/dist/index-Cs1Kebmt.d.mts.map +1 -0
  17. package/dist/index.d.mts +2 -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/types-B0mvQgJf.d.mts +49 -0
  24. package/dist/types-B0mvQgJf.d.mts.map +1 -0
  25. package/dist/types-DwHrGKWO.d.mts +27 -0
  26. package/dist/types-DwHrGKWO.d.mts.map +1 -0
  27. package/dist/workflow.d.mts +4 -5
  28. package/dist/workflow.d.mts.map +1 -1
  29. package/dist/workflow.mjs +3 -3
  30. package/dist/workflow.mjs.map +1 -1
  31. package/dist/{write-tools-vzlewWo5.mjs → write-tools-Dx9LfYlU.mjs} +26 -9
  32. package/dist/write-tools-Dx9LfYlU.mjs.map +1 -0
  33. package/package.json +18 -5
  34. package/dist/eve.mjs.map +0 -1
  35. package/dist/index-BRUYe5q0.d.mts +0 -220
  36. package/dist/index-BRUYe5q0.d.mts.map +0 -1
  37. package/dist/src-BgnkKMD7.mjs.map +0 -1
  38. package/dist/tool-types-CuirBEc8.d.mts.map +0 -1
  39. 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,73 @@ 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
+ `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
+
255
+ Token provider only (custom factories):
256
+
257
+ ```ts
258
+ import { connectGithubToken } from '@github-tools/sdk/connect'
259
+
260
+ createGithubTools({
261
+ preset: 'ci-ops',
262
+ token: connectGithubToken('github/my-connector', { preset: 'ci-ops' }),
263
+ })
264
+ ```
265
+
266
+ Pass the same `preset` to `connectGithubToken` — it derives Connect scopes independently of the `preset` given to `createGithubTools`.
267
+
268
+ Override installation, repositories, or scopes via `connect`:
269
+
270
+ ```ts
271
+ connectGithubTools('github/my-connector', {
272
+ preset: 'issue-triage',
273
+ connect: {
274
+ installationId: 'inst_abc',
275
+ repositories: ['my-org/my-repo'],
276
+ scopes: ['issues:write'],
277
+ },
278
+ })
279
+ ```
280
+
281
+ > `@vercel/connect` is an optional peer dependency — install it only when using the `/connect` subpath.
282
+
214
283
  ## eve
215
284
 
216
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.
@@ -398,11 +467,13 @@ Returns an object of tools, ready to spread into `tools` of any AI SDK call.
398
467
 
399
468
  ```ts
400
469
  type GithubToolsOptions = {
401
- token?: string // defaults to process.env.GITHUB_TOKEN
470
+ token?: GithubTokenInput // defaults to process.env.GITHUB_TOKEN
402
471
  requireApproval?: boolean | Partial<Record<GithubWriteToolName, boolean>>
403
472
  preset?: GithubToolPreset | GithubToolPreset[]
404
473
  }
405
474
 
475
+ type GithubTokenInput = string | (() => Promise<string>)
476
+
406
477
  type GithubToolPreset = 'code-review' | 'issue-triage' | 'repo-explorer' | 'ci-ops' | 'maintainer'
407
478
  ```
408
479
 
@@ -449,7 +520,7 @@ const stream = reviewer.stream({ prompt: 'Review PR #42 on vercel/ai' })
449
520
  | Option | Description |
450
521
  |---|---|
451
522
  | `model` | Language model — string (`'anthropic/claude-sonnet-4.6'`) or provider instance |
452
- | `token` | GitHub personal access token |
523
+ | `token` | GitHub token string or async provider |
453
524
  | `preset` | Optional preset or array of presets to scope tools |
454
525
  | `requireApproval` | Approval config (same as `createGithubTools`) |
455
526
  | `instructions` | Replaces the built-in system prompt entirely |
@@ -509,6 +580,10 @@ async function agentTurn(prompt: string) {
509
580
 
510
581
  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
582
 
583
+ ### `resolveGithubToken(token?)`
584
+
585
+ Resolves a `GithubTokenInput` (token string, async provider, or `process.env.GITHUB_TOKEN`) to a token string. Throws when no token is available.
586
+
512
587
  ### `createOctokit(token)`
513
588
 
514
589
  Returns a configured [`octokit`](https://github.com/octokit/octokit.js) instance. Useful for building custom tools.
@@ -0,0 +1,18 @@
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
+
5
+ //#region src/connect/eve.d.ts
6
+ /**
7
+ * Register eve GitHub tools backed by a Vercel Connect connector.
8
+ * Scopes are derived from `preset` unless overridden in `connect.scopes`.
9
+ *
10
+ * TODO(eve-connect-bundle): eve's authored-module bundler inlines workspace-linked
11
+ * 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.
14
+ */
15
+ declare function connectGithubTools(connector: string, options?: ConnectGithubEveToolsOptions): _$eve_tools0.DynamicSentinel<Partial<Record<GithubToolName, _$eve_tools0.ToolDefinition<unknown, unknown>>>>;
16
+ //#endregion
17
+ export { connectGithubTools };
18
+ //# 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,CAAA,OAAA,CAAA,MAAA,CAAA,cAAA,EAAA,YAAA,CAAA,cAAA"}
@@ -0,0 +1,27 @@
1
+ import { l as createGithubTools } from "../eve-UPaHEGVi.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 { Y as AllGithubTools, at as GithubTokenInput, dt as GithubToolPreset, ht as GithubToolName } from "./index-Cs1Kebmt.mjs";
2
+ import { i as GithubConnectParams, n as ConnectGithubTokenOptions, r as ConnectGithubToolsOptions, t as ConnectGithubEveToolsOptions } from "./types-DwHrGKWO.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"}