@github-tools/sdk 1.2.0 → 1.4.0

package/README.md

@@ -1,3 +1,5 @@
+<img src="https://github.com/vercel-labs/github-tools/blob/main/assets/banner.jpg" width="100%" alt="GitHub Tools banner" />
+
 # @github-tools/sdk
 
 [![npm version](https://img.shields.io/npm/v/@github-tools/sdk?color=black)](https://npmjs.com/package/@github-tools/sdk)
@@ -7,7 +9,7 @@
 
 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.
 
-18 tools covering repositories, pull requests, issues, commits, and search. Write operations support granular approval control out of the box.
+42 tools covering repositories, branches, pull requests, issues, commits, search, gists, and workflows. Write operations support granular approval control out of the box.
 
 ## Installation
 
@@ -60,10 +62,11 @@ createGithubTools({ token, preset: ['code-review', 'issue-triage'] })
 
 | Preset | Tools included |
 |---|---|
-| `code-review` | `getPullRequest`, `listPullRequests`, `getFileContent`, `listCommits`, `getCommit`, `getRepository`, `listBranches`, `searchCode`, `addPullRequestComment` |
-| `issue-triage` | `listIssues`, `getIssue`, `createIssue`, `addIssueComment`, `closeIssue`, `getRepository`, `searchRepositories`, `searchCode` |
-| `repo-explorer` | All read-only tools (no write operations) |
-| `maintainer` | All 18 tools |
+| `code-review` | `getPullRequest`, `listPullRequests`, `listPullRequestFiles`, `listPullRequestReviews`, `getFileContent`, `listCommits`, `getCommit`, `getBlame`, `getRepository`, `listBranches`, `searchCode`, `addPullRequestComment`, `createPullRequestReview` |
+| `issue-triage` | `listIssues`, `getIssue`, `createIssue`, `addIssueComment`, `closeIssue`, `listLabels`, `addLabels`, `removeLabel`, `getRepository`, `searchRepositories`, `searchCode` |
+| `repo-explorer` | All read-only tools including gists and workflows (no write operations) |
+| `ci-ops` | `listWorkflows`, `listWorkflowRuns`, `getWorkflowRun`, `listWorkflowJobs`, `triggerWorkflow`, `cancelWorkflowRun`, `rerunWorkflowRun`, `getRepository`, `listBranches`, `listCommits`, `getCommit` |
+| `maintainer` | All 42 tools |
 
 Omit `preset` to get all tools (same as `maintainer`).
 
@@ -72,16 +75,18 @@ Omit `preset` to get all tools (same as `maintainer`).
 You can also import individual tool factories for full control:
 
 ```ts
-import { createOctokit, listPullRequests, createIssue } from '@github-tools/sdk'
+import { listPullRequests, createIssue } from '@github-tools/sdk'
 
-const octokit = createOctokit(process.env.GITHUB_TOKEN!)
+const token = process.env.GITHUB_TOKEN!
 
 const tools = {
-  listPullRequests: listPullRequests(octokit),
-  createIssue: createIssue(octokit),
+  listPullRequests: listPullRequests(token),
+  createIssue: createIssue(token),
 }
 ```
 
+Each tool factory accepts a `token` string. Tools use named module-level step functions with `"use step"` internally, ensuring proper step registration and full Node.js access when running inside a Vercel Workflow sandbox. See [Durable Agents](#durable-agents-vercel-workflow-sdk).
+
 ## Approval Control
 
 Write operations (creating issues, merging PRs, pushing files, …) require user approval by default. This is designed for human-in-the-loop agent workflows.
@@ -108,10 +113,81 @@ createGithubTools({
 })
 ```
 
-Write tools: `createOrUpdateFile`, `createPullRequest`, `mergePullRequest`, `addPullRequestComment`, `createIssue`, `addIssueComment`, `closeIssue`.
+Write tools: `createOrUpdateFile`, `createPullRequest`, `mergePullRequest`, `addPullRequestComment`, `createPullRequestReview`, `createIssue`, `addIssueComment`, `closeIssue`, `addLabels`, `removeLabel`, `createGist`, `updateGist`, `deleteGist`, `createGistComment`, `triggerWorkflow`, `cancelWorkflowRun`, `rerunWorkflowRun`.
 
 All other tools are read-only and never require approval.
 
+### Tool overrides
+
+The `overrides` option lets you customize any AI SDK [`tool()`](https://ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling) property on a per-tool basis, keyed by tool name.
+
+```ts
+import type { ToolOverrides } from "@github-tools/sdk";
+```
+
+Supported override properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `description` | `string` | Custom tool description for the model |
+| `title` | `string` | Human-readable title |
+| `strict` | `boolean` | Strict mode for input generation |
+| `needsApproval` | `boolean \| function` | Gate execution behind approval |
+| `providerOptions` | `ProviderOptions` | Provider-specific metadata |
+| `onInputStart` | `function` | Callback when argument streaming starts |
+| `onInputDelta` | `function` | Callback on each streaming delta |
+| `onInputAvailable` | `function` | Callback when full input is available |
+| `toModelOutput` | `function` | Custom mapping of tool result to model output |
+
+Core properties (`execute`, `inputSchema`, `outputSchema`) cannot be overridden.
+
+## Tool Selection with toolpick
+
+With dozens of tools, context window usage adds up. [toolpick](https://github.com/pontusab/toolpick) selects only the most relevant tools per step so the model sees what it needs:
+
+```ts
+import { createGithubTools } from '@github-tools/sdk'
+import { createToolIndex } from 'toolpick'
+import { generateText } from 'ai'
+import { openai } from '@ai-sdk/openai'
+
+const tools = createGithubTools()
+const index = createToolIndex(tools, {
+  embeddingModel: openai.embeddingModel('text-embedding-3-small'),
+})
+
+const result = await generateText({
+  model: openai('gpt-4o'),
+  tools,
+  prepareStep: index.prepareStep(),
+  prompt: 'List open PRs on vercel/ai and summarize them.',
+})
+```
+
+Each step, toolpick picks the best ~5 tools using keyword + semantic search. All tools remain callable — only the visible set changes. See [toolpick docs](https://github.com/pontusab/toolpick) for LLM re-ranking, caching, and model-driven discovery options.
+
+## Durable Agents (Vercel Workflow SDK)
+
+All tools include `"use step"` directives with named, module-level step functions, making them natively compatible with the Vercel Workflow SDK. Each tool execution runs as a properly registered durable step with full Node.js access in the workflow sandbox.
+
+Use `DurableAgent` via the `@github-tools/sdk/workflow` subpath to make every LLM call and tool execution a retryable, crash-safe step:
+
+```ts
+import { createDurableGithubAgent } from '@github-tools/sdk/workflow'
+
+const agent = createDurableGithubAgent({
+  model: 'anthropic/claude-sonnet-4.6',
+  token: process.env.GITHUB_TOKEN!,
+  preset: 'maintainer',
+})
+```
+
+All presets work with `createDurableGithubAgent`.
+
+> **Approval control limitation**: `requireApproval` is accepted for forward-compatibility but is currently ignored by `DurableAgent`. The Workflow SDK does not yet support interactive tool approval — all tools execute immediately. Use `createGithubAgent` (standard `ToolLoopAgent`) when human-in-the-loop approval is required.
+
+> `workflow` and `@workflow/ai` are optional peer dependencies — install them only when using the workflow subpath.
+
 ## Available Tools
 
 ### Repository
@@ -129,9 +205,12 @@ All other tools are read-only and never require approval.
 |---|---|
 | `listPullRequests` | List PRs filtered by state |
 | `getPullRequest` | Get a PR's full details (diff stats, body, merge status) |
+| `listPullRequestFiles` | List files changed in a PR with diff status and patches |
+| `listPullRequestReviews` | List reviews on a PR (approvals, change requests, comments) |
 | `createPullRequest` | Open a new PR |
 | `mergePullRequest` | Merge a PR (merge, squash, or rebase) |
 | `addPullRequestComment` | Post a comment on a PR |
+| `createPullRequestReview` | Submit a formal review (approve, request changes, or comment) with inline comments |
 
 ### Issues
 
@@ -142,6 +221,33 @@ All other tools are read-only and never require approval.
 | `createIssue` | Open a new issue |
 | `addIssueComment` | Post a comment on an issue |
 | `closeIssue` | Close an issue (completed or not planned) |
+| `listLabels` | List labels available in a repository |
+| `addLabels` | Add labels to an issue or pull request |
+| `removeLabel` | Remove a label from an issue or pull request |
+
+### Gists
+
+| Tool | Description |
+|---|---|
+| `listGists` | List gists for the authenticated user or a specific user |
+| `getGist` | Get a gist including file contents |
+| `listGistComments` | List comments on a gist |
+| `createGist` | Create a new gist with one or more files |
+| `updateGist` | Update a gist's description or files |
+| `deleteGist` | Delete a gist permanently |
+| `createGistComment` | Post a comment on a gist |
+
+### Workflows
+
+| Tool | Description |
+|---|---|
+| `listWorkflows` | List GitHub Actions workflows in a repository |
+| `listWorkflowRuns` | List workflow runs filtered by workflow, branch, status, or event |
+| `getWorkflowRun` | Get a workflow run's status, timing, and trigger info |
+| `listWorkflowJobs` | List jobs in a workflow run with step-level status |
+| `triggerWorkflow` | Trigger a workflow via workflow_dispatch event |
+| `cancelWorkflowRun` | Cancel an in-progress workflow run |
+| `rerunWorkflowRun` | Re-run a workflow run, optionally only failed jobs |
 
 ### Commits
 
@@ -149,6 +255,7 @@ All other tools are read-only and never require approval.
 |---|---|
 | `listCommits` | List commits, optionally filtered by file path, author, or date range |
 | `getCommit` | Get a commit's full details including changed files and diffs |
+| `getBlame` | Line-level git blame for a file (GitHub GraphQL) |
 
 ### Search
 
@@ -168,12 +275,17 @@ Create one at **GitHub → Settings → Developer settings → Personal access t
 | Permission | Level | Required for |
 |---|---|---|
 | **Metadata** | Read-only | Always required (auto-included) |
-| **Contents** | Read-only | `getRepository`, `listBranches`, `getFileContent`, `listCommits`, `getCommit` |
+| **Contents** | Read-only | `getRepository`, `listBranches`, `getFileContent`, `listCommits`, `getCommit`, `getBlame` |
 | **Contents** | Read and write | `createOrUpdateFile` |
-| **Pull requests** | Read-only | `listPullRequests`, `getPullRequest` |
-| **Pull requests** | Read and write | `createPullRequest`, `mergePullRequest`, `addPullRequestComment` |
-| **Issues** | Read-only | `listIssues`, `getIssue` |
-| **Issues** | Read and write | `createIssue`, `addIssueComment`, `closeIssue` |
+| **Pull requests** | Read-only | `listPullRequests`, `getPullRequest`, `listPullRequestFiles`, `listPullRequestReviews` |
+| **Pull requests** | Read and write | `createPullRequest`, `mergePullRequest`, `addPullRequestComment`, `createPullRequestReview` |
+| **Issues** | Read-only | `listIssues`, `getIssue`, `listLabels` |
+| **Issues** | Read and write | `createIssue`, `addIssueComment`, `closeIssue`, `addLabels`, `removeLabel` |
+
+| **Gists** | Read-only | `listGists`, `getGist`, `listGistComments` |
+| **Gists** | Read and write | `createGist`, `updateGist`, `deleteGist`, `createGistComment` |
+| **Actions** | Read-only | `listWorkflows`, `listWorkflowRuns`, `getWorkflowRun`, `listWorkflowJobs` |
+| **Actions** | Read and write | `triggerWorkflow`, `cancelWorkflowRun`, `rerunWorkflowRun` |
 
 Search tools (`searchCode`, `searchRepositories`) work with any token.
 
@@ -192,12 +304,12 @@ Returns an object of tools, ready to spread into `tools` of any AI SDK call.
 
 ```ts
 type GithubToolsOptions = {
-  token: string
+  token?: string // defaults to process.env.GITHUB_TOKEN
   requireApproval?: boolean | Partial<Record<GithubWriteToolName, boolean>>
   preset?: GithubToolPreset | GithubToolPreset[]
 }
 
-type GithubToolPreset = 'code-review' | 'issue-triage' | 'repo-explorer' | 'maintainer'
+type GithubToolPreset = 'code-review' | 'issue-triage' | 'repo-explorer' | 'ci-ops' | 'maintainer'
 ```
 
 ### `createGithubAgent(options)`
@@ -251,9 +363,40 @@ const stream = reviewer.stream({ prompt: 'Review PR #42 on vercel/ai' })
 
 All other `ToolLoopAgent` options (`stopWhen`, `toolChoice`, `onStepFinish`, etc.) are passed through.
 
+### `createDurableGithubAgent(options)`
+
+Returns a `DurableAgent` instance for use inside Vercel Workflow SDK functions. Every LLM call and tool execution runs as a durable step with automatic retries and crash recovery.
+
+Requires the optional peer dependencies `workflow` and `@workflow/ai`:
+
+```sh
+pnpm add workflow @workflow/ai
+```
+
+```ts
+import { createDurableGithubAgent } from '@github-tools/sdk/workflow'
+import { getWritable } from 'workflow'
+import type { ModelMessage, UIMessageChunk } from 'ai'
+
+async function chatWorkflow(messages: ModelMessage[], token: string) {
+  "use workflow"
+  const agent = createDurableGithubAgent({
+    model: 'anthropic/claude-sonnet-4.6',
+    token,
+    preset: 'code-review',
+  })
+  const writable = getWritable<UIMessageChunk>()
+  await agent.stream({ messages, writable })
+}
+```
+
+All presets (`code-review`, `issue-triage`, `ci-ops`, `repo-explorer`, `maintainer`) work with `createDurableGithubAgent`. The options are the same as `createGithubAgent` except it returns a `DurableAgent` instead of a `ToolLoopAgent`.
+
+> **Note:** `requireApproval` is accepted but currently ignored by `DurableAgent` — the Workflow SDK does not yet support interactive tool approval.
+
 ### `createOctokit(token)`
 
-Returns a configured [`@octokit/rest`](https://github.com/octokit/rest.js) instance. Useful when cherry-picking individual tools or building custom ones.
+Returns a configured [`octokit`](https://github.com/octokit/octokit.js) instance. Useful for building custom tools.
 
 ## License