@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.
- package/README.md +76 -3
- package/dist/connect/eve.d.mts +17 -0
- package/dist/connect/eve.d.mts.map +1 -0
- package/dist/connect/eve.mjs +27 -0
- package/dist/connect/eve.mjs.map +1 -0
- package/dist/connect.d.mts +46 -0
- package/dist/connect.d.mts.map +1 -0
- package/dist/connect.mjs +22 -0
- package/dist/connect.mjs.map +1 -0
- package/dist/eve-B-LChKzS.mjs +526 -0
- package/dist/eve-B-LChKzS.mjs.map +1 -0
- package/dist/eve.d.mts +3 -45
- package/dist/eve.d.mts.map +1 -1
- package/dist/eve.mjs +2 -521
- package/dist/{index-BRUYe5q0.d.mts → index-SZCaP-y9.d.mts} +44 -44
- package/dist/index-SZCaP-y9.d.mts.map +1 -0
- package/dist/index.d.mts +3 -3
- package/dist/index.mjs +3 -3
- package/dist/{src-BgnkKMD7.mjs → src-CfzZfU82.mjs} +87 -87
- package/dist/src-CfzZfU82.mjs.map +1 -0
- package/dist/token-CW8lQBND.mjs +100 -0
- package/dist/token-CW8lQBND.mjs.map +1 -0
- package/dist/{tool-types-CuirBEc8.d.mts → tool-types-C0kszIwd.d.mts} +35 -30
- package/dist/tool-types-C0kszIwd.d.mts.map +1 -0
- package/dist/types-BTanS_dq.d.mts +49 -0
- package/dist/types-BTanS_dq.d.mts.map +1 -0
- package/dist/types-DOeq0Iia.d.mts +27 -0
- package/dist/types-DOeq0Iia.d.mts.map +1 -0
- package/dist/workflow.d.mts +5 -5
- package/dist/workflow.d.mts.map +1 -1
- package/dist/workflow.mjs +3 -3
- package/dist/workflow.mjs.map +1 -1
- package/dist/{write-tools-vzlewWo5.mjs → write-tools-Dx9LfYlU.mjs} +26 -9
- package/dist/write-tools-Dx9LfYlU.mjs.map +1 -0
- package/package.json +16 -3
- package/dist/eve.mjs.map +0 -1
- package/dist/index-BRUYe5q0.d.mts.map +0 -1
- package/dist/src-BgnkKMD7.mjs.map +0 -1
- package/dist/tool-types-CuirBEc8.d.mts.map +0 -1
- package/dist/write-tools-vzlewWo5.mjs.map +0 -1
package/README.md
CHANGED
|
@@ -7,7 +7,9 @@
|
|
|
7
7
|
[](https://www.typescriptlang.org/)
|
|
8
8
|
[](https://github.com/vercel-labs/github-tools/blob/main/LICENSE)
|
|
9
9
|
|
|
10
|
-
GitHub tools for the [AI SDK](https://ai-sdk.dev)
|
|
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?:
|
|
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
|
|
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"}
|
package/dist/connect.mjs
ADDED
|
@@ -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"}
|