feat: add streaming server and GitHub toolset

.pre-commit-config.yaml

@@ -5,25 +5,25 @@
 repos:
   - repo: local
     hooks:
-      # Ruff format check (matches CI: uv run ruff format --check src tests)
+      # Ruff format - auto-fixes formatting issues
       - id: ruff-format
         name: ruff format
-        entry: uv run ruff format --check
+        entry: uv run ruff format
         language: system
         types: [python]
         pass_filenames: false
         args: [src, tests]
 
-      # Ruff lint (matches CI: uv run ruff check src tests)
+      # Ruff lint - auto-fixes what it can, fails on unfixable issues
       - id: ruff-lint
         name: ruff lint
-        entry: uv run ruff check
+        entry: uv run ruff check --fix
         language: system
         types: [python]
         pass_filenames: false
         args: [src, tests]
 
-      # Mypy type check (matches CI: uv run mypy src/bond)
+      # Mypy type check (cannot auto-fix, but necessary for safety)
       - id: mypy
         name: mypy
         entry: uv run mypy

docs/api/server.md

@@ -0,0 +1,61 @@
+# Server Module
+
+The Bond server module provides production-ready SSE and WebSocket streaming for any Bond agent.
+
+## Factory Function
+
+::: bond.server.create_bond_server
+    options:
+      show_source: false
+
+---
+
+## Configuration
+
+::: bond.server.ServerConfig
+    options:
+      show_source: true
+
+---
+
+## Request/Response Types
+
+### AskRequest
+
+::: bond.server.AskRequest
+    options:
+      show_source: true
+
+### SessionResponse
+
+::: bond.server.SessionResponse
+    options:
+      show_source: true
+
+### HealthResponse
+
+::: bond.server.HealthResponse
+    options:
+      show_source: true
+
+---
+
+## Session Management
+
+### Session
+
+::: bond.server.Session
+    options:
+      show_source: true
+
+### SessionStatus
+
+::: bond.server.SessionStatus
+    options:
+      show_source: true
+
+### SessionManager
+
+::: bond.server.SessionManager
+    options:
+      show_source: false

docs/api/tools.md

@@ -78,6 +78,90 @@ The schema toolset provides database schema lookup capabilities.
 
 ---
 
+## GitHub Toolset
+
+The GitHub toolset provides tools to browse and analyze any GitHub repository.
+
+### Protocol
+
+::: bond.tools.github.GitHubProtocol
+    options:
+      show_source: true
+
+### Adapter
+
+::: bond.tools.github.GitHubAdapter
+    options:
+      show_source: false
+
+### Types
+
+::: bond.tools.github.RepoInfo
+    options:
+      show_source: true
+
+::: bond.tools.github.TreeEntry
+    options:
+      show_source: true
+
+::: bond.tools.github.FileContent
+    options:
+      show_source: true
+
+::: bond.tools.github.CodeSearchResult
+    options:
+      show_source: true
+
+::: bond.tools.github.Commit
+    options:
+      show_source: true
+
+::: bond.tools.github.CommitAuthor
+    options:
+      show_source: true
+
+::: bond.tools.github.PullRequest
+    options:
+      show_source: true
+
+::: bond.tools.github.PullRequestUser
+    options:
+      show_source: true
+
+### Exceptions
+
+::: bond.tools.github.GitHubError
+    options:
+      show_source: true
+
+::: bond.tools.github.RepoNotFoundError
+    options:
+      show_source: true
+
+::: bond.tools.github.FileNotFoundError
+    options:
+      show_source: true
+
+::: bond.tools.github.PRNotFoundError
+    options:
+      show_source: true
+
+::: bond.tools.github.RateLimitedError
+    options:
+      show_source: true
+
+::: bond.tools.github.AuthenticationError
+    options:
+      show_source: true
+
+### Toolset
+
+::: bond.tools.github.github_toolset
+    options:
+      show_source: false
+
+---
+
 ## GitHunter Toolset
 
 The GitHunter toolset provides forensic code ownership analysis tools.

docs/guides/github.md

@@ -0,0 +1,213 @@
+# GitHub Toolset
+
+The GitHub toolset enables agents to browse and analyze any GitHub repository. Agents can read files, search code, explore commit history, and inspect pull requests.
+
+## Overview
+
+GitHub tools answer questions like:
+
+- **"What's in this repo?"** → `github_get_repo` + `github_list_files`
+- **"Show me this file"** → `github_read_file`
+- **"Where is X defined?"** → `github_search_code`
+- **"What changed recently?"** → `github_get_commits`
+- **"What does this PR do?"** → `github_get_pr`
+
+## Quick Start
+
+```python
+import os
+from bond import BondAgent
+from bond.tools.github import github_toolset, GitHubAdapter
+
+# Create adapter with GitHub token
+adapter = GitHubAdapter(token=os.environ["GITHUB_TOKEN"])
+
+# Create agent with GitHub tools
+agent = BondAgent(
+    name="code-explorer",
+    instructions="""You help users understand GitHub repositories.
+    Browse files, search code, and explain what you find.""",
+    model="openai:gpt-4o",
+    toolsets=[github_toolset],
+    deps=adapter,
+)
+
+# Explore a repository
+result = await agent.ask("What is the facebook/react repository about?")
+```
+
+## Available Tools
+
+### github_get_repo
+
+Get repository metadata.
+
+```python
+github_get_repo({
+    "owner": "facebook",
+    "repo": "react"
+})
+```
+
+**Returns:** `RepoInfo` with description, default branch, topics, stars, forks.
+
+### github_list_files
+
+List directory contents.
+
+```python
+github_list_files({
+    "owner": "facebook",
+    "repo": "react",
+    "path": "packages/react/src",
+    "ref": "main"  # optional: branch, tag, or commit
+})
+```
+
+**Returns:** List of `TreeEntry` with name, path, type (file/dir), size.
+
+### github_read_file
+
+Read file content.
+
+```python
+github_read_file({
+    "owner": "facebook",
+    "repo": "react",
+    "path": "packages/react/package.json",
+    "ref": "main"
+})
+```
+
+**Returns:** `FileContent` with decoded content, size, SHA.
+
+### github_search_code
+
+Search code within a repository.
+
+```python
+github_search_code({
+    "query": "useState",
+    "owner": "facebook",
+    "repo": "react",
+    "limit": 10
+})
+```
+
+**Returns:** List of `CodeSearchResult` with file paths and matching fragments.
+
+### github_get_commits
+
+Get recent commits.
+
+```python
+github_get_commits({
+    "owner": "facebook",
+    "repo": "react",
+    "path": "packages/react/src/React.js",  # optional: filter by file
+    "limit": 10
+})
+```
+
+**Returns:** List of `Commit` with SHA, message, author, date.
+
+### github_get_pr
+
+Get pull request details.
+
+```python
+github_get_pr({
+    "owner": "facebook",
+    "repo": "react",
+    "number": 25000
+})
+```
+
+**Returns:** `PullRequest` with title, body, state, author, merge status.
+
+## Authentication
+
+GitHub tools require a personal access token:
+
+```bash
+export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
+```
+
+Or pass directly:
+
+```python
+adapter = GitHubAdapter(token="ghp_xxxxxxxxxxxx")
+```
+
+**Required scopes:**
+- `repo` - For private repositories
+- `public_repo` - For public repositories only
+
+## Use Cases
+
+| Scenario | Tools | Example Query |
+|----------|-------|---------------|
+| Explore structure | `github_get_repo` + `github_list_files` | "What's the structure of this repo?" |
+| Read documentation | `github_read_file` | "Show me the README" |
+| Find implementations | `github_search_code` | "Where is the login function defined?" |
+| Track changes | `github_get_commits` | "What changed in auth.py recently?" |
+| Review PRs | `github_get_pr` | "Summarize PR #123" |
+| Code review | All tools | "Review the changes in PR #456" |
+
+## Combining with GitHunter
+
+For deeper code forensics, combine GitHub tools with GitHunter:
+
+```python
+from bond.tools import BondToolDeps, github_toolset, githunter_toolset
+
+deps = BondToolDeps(github_token=os.environ["GITHUB_TOKEN"])
+
+agent = BondAgent(
+    name="forensic-analyst",
+    instructions="You investigate code history and ownership.",
+    model="openai:gpt-4o",
+    toolsets=[github_toolset, githunter_toolset],
+    deps=deps,
+)
+
+# Now agent can:
+# - Browse any GitHub repo (github_*)
+# - Blame lines in local repos (blame_line)
+# - Find PR discussions (find_pr_discussion)
+# - Identify file experts (get_file_experts)
+```
+
+## Rate Limiting
+
+The adapter handles GitHub API rate limits automatically with exponential backoff. If rate limited, tools return an `Error`:
+
+```python
+Error(description="GitHub API rate limit exceeded (resets at 1234567890)")
+```
+
+Increase limits by using an authenticated token (5000 requests/hour vs 60 unauthenticated).
+
+## Error Handling
+
+All tools return `Error` on failure:
+
+```python
+from bond.tools.github import Error
+
+result = await agent.ask("Read nonexistent.txt from facebook/react")
+# Agent receives Error(description="File not found: facebook/react/nonexistent.txt")
+```
+
+Common errors:
+- `RepoNotFoundError` - Repository doesn't exist or is private
+- `FileNotFoundError` - Path doesn't exist
+- `PRNotFoundError` - PR number doesn't exist
+- `RateLimitedError` - API rate limit exceeded
+- `AuthenticationError` - Invalid or missing token
+
+## See Also
+
+- [Streaming Server](./streaming-server.md) - Serve agents via SSE/WebSocket
+- [GitHunter Toolset](./githunter.md) - Local git forensics
+- [API Reference: GitHub](../api/tools.md#github-toolset) - Full type definitions