@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.
- package/README.md +78 -3
- package/dist/connect/eve.d.mts +18 -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-UPaHEGVi.mjs +512 -0
- package/dist/eve-UPaHEGVi.mjs.map +1 -0
- package/dist/eve.d.mts +47 -89
- package/dist/eve.d.mts.map +1 -1
- package/dist/eve.mjs +2 -521
- package/dist/{tool-types-CuirBEc8.d.mts → index-Cs1Kebmt.d.mts} +251 -32
- package/dist/index-Cs1Kebmt.d.mts.map +1 -0
- package/dist/index.d.mts +2 -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/types-B0mvQgJf.d.mts +49 -0
- package/dist/types-B0mvQgJf.d.mts.map +1 -0
- package/dist/types-DwHrGKWO.d.mts +27 -0
- package/dist/types-DwHrGKWO.d.mts.map +1 -0
- package/dist/workflow.d.mts +4 -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 +18 -5
- package/dist/eve.mjs.map +0 -1
- package/dist/index-BRUYe5q0.d.mts +0 -220
- 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,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?:
|
|
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
|
|
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"}
|
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"}
|