Docs: REST API errors carry a request_id; terminals linked from the docs home and agents overview (#145)
* Docs: REST API errors carry a request_id (#143) Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016q5wwBFck8JHq14gHUM2CL * Docs: terminals linked from the docs home, concepts and the agents overview (#142) Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016q5wwBFck8JHq14gHUM2CL --------- Co-authored-by: Claude <noreply@anthropic.com>
Canberk Demirci authored · GitHub committed signed1 parent 94ad471commit 9d3f4394ee9d3161ccd3ca7453b176112ce684c9Browse files
5 files changed+7−5
Files (5)
modifiedapps/diffinery/docs/agents/overview.md+1−0View file
| @@ -217,6 +217,7 @@ | ||
| 217 | 217 | - **[Agent tasks](/docs/agents/tasks)**: on a repository's **Project** tab, give one of your agents a goal. Diffinery runs Claude Code or Codex (on their own providers, or via [OpenRouter](/docs/agents/tasks#openrouter) on a model you choose) or your own command in a sandbox as that agent, with your own model API key (saved under **Settings → Model access**, and never placed in the sandbox), then pushes a branch and opens a pull request for review. |
| 218 | 218 | - **[Projects](/docs/agents/projects)**: the Project tab shows a repository's tasks on a board, with a conversation, a shared memory every task reads, project instructions, and a limit on how many tasks run at once. Your own coordinator agent can turn your posts there into tasks. |
| 219 | 219 | - **[Agent review](/docs/agents/review)**: one of your agents reviews pull requests for bugs, security issues and logic errors, like Cursor's Bugbot. It posts inline findings and an **Agent review** check, and **Fix it** starts a task that pushes the fix. |
| 220 | +- **[Terminals](/docs/agents/terminal)**: a shell in your browser, in a sandbox with the repository checked out, acting as one of your agents. Start Claude Code or Codex there and sign in with your own Claude or ChatGPT subscription instead of an API key, then work in it yourself or [give it a task](/docs/agents/terminal#give-it-a-task) that runs on that subscription and opens a pull request. | |
| 220 | 221 | - **[Today](/docs/agents/today)**: the first page after signing in, also `GET /api/v3/diffinery/today` and the `today` MCP tool. It shows the pull requests that need you, your agents' open pull requests and tasks, and what merged, was released or failed in the last 24 hours. |
| 221 | 222 | |
| 222 | 223 | ## Set up a coding agent |
modifiedapps/diffinery/docs/agents/terminal.md+2−2View file
| @@ -1,9 +1,9 @@ | ||
| 1 | 1 | --- |
| 2 | 2 | title: Terminals |
| 3 | -description: Open a shell in a sandbox with your repository checked out, right in the browser, and work there with Claude Code or Codex signed in to your own subscription. | |
| 3 | +description: A shell in your browser with the repository checked out, where Claude Code or Codex runs on your own subscription, and that can take agent tasks. | |
| 4 | 4 | --- |
| 5 | 5 | |
| 6 | -A **terminal** is a sandbox with a repository checked out, in your browser. You type into a real shell, and you can start Claude Code or Codex there and sign in with your own Claude or ChatGPT plan, instead of an API key. Whatever you push from it is pushed as one of your agents, so its pull requests need a person's approval like any agent's. | |
| 6 | +A **terminal** is a sandbox with a repository checked out, in your browser. You type into a real shell, and you can start Claude Code or Codex there and sign in with your own Claude or ChatGPT plan, instead of an API key. Whatever you push from it is pushed as one of your agents, so its pull requests need a person's approval like any agent's. Once you're signed in, you can also [give it a task](#give-it-a-task): Diffinery runs the goal with that sign-in, as an [agent task](/docs/agents/tasks), and opens a pull request. | |
| 7 | 7 | |
| 8 | 8 | Terminals are optional. Nothing changes for a repository until someone opens one. |
| 9 | 9 |
modifiedapps/diffinery/docs/concepts.md+1−1View file
| @@ -45,7 +45,7 @@ | ||
| 45 | 45 | - A workflow run whose code came from an agent (the agent triggered it, pushed the branch last, or opened the pull request, and re-runs and `workflow_run` followers of such a run) acts as the agent, so a workflow can't carry agent-written code past these rules. |
| 46 | 46 | - It can import from GitHub only into an organization it or its owner administers, its imports never bypass push protection, and they skip variables, secret names and environments. |
| 47 | 47 | |
| 48 | -Agents work through the [MCP server](/docs/agents/mcp), the REST API, the CLI and Git. Diffinery can also run one for you: an [agent task](/docs/agents/tasks) gives one of your agents a goal and runs Claude Code, Codex or your own command with your own model key, then opens a pull request, a repository's [project](/docs/agents/projects) puts its tasks on a board with shared memory and instructions, and [agent review](/docs/agents/review) has one review pull requests for bugs. [Today](/docs/agents/today), the first page after signing in, shows what needs you and what your agents are doing. See [Agents](/docs/agents/overview). | |
| 48 | +Agents work through the [MCP server](/docs/agents/mcp), the REST API, the CLI and Git. Diffinery can also run one for you: an [agent task](/docs/agents/tasks) gives one of your agents a goal and runs Claude Code, Codex or your own command with your own model key, then opens a pull request, a [terminal](/docs/agents/terminal) gives you a shell in a sandbox where Claude Code or Codex runs on your own subscription and can take tasks too, a repository's [project](/docs/agents/projects) puts its tasks on a board with shared memory and instructions, and [agent review](/docs/agents/review) has one review pull requests for bugs. [Today](/docs/agents/today), the first page after signing in, shows what needs you and what your agents are doing. See [Agents](/docs/agents/overview). | |
| 49 | 49 | |
| 50 | 50 | ### People imported from GitHub |
| 51 | 51 |
modifiedapps/diffinery/docs/index.md+1−0View file
| @@ -15,6 +15,7 @@ | ||
| 15 | 15 | | Run CI | [Actions overview](/docs/actions/overview) and [Workflow syntax](/docs/actions/workflow-syntax) | |
| 16 | 16 | | Connect an AI agent | [Agents](/docs/agents/overview) and [MCP](/docs/agents/mcp) | |
| 17 | 17 | | Give an agent a goal and get a pull request back, with your own model key | [Agent tasks](/docs/agents/tasks) | |
| 18 | +| Work in a browser shell with Claude Code or Codex on your own Claude or ChatGPT subscription, and give it tasks | [Terminals](/docs/agents/terminal) | | |
| 18 | 19 | | Track agent work on a board, with shared memory and project instructions | [Projects](/docs/agents/projects) | |
| 19 | 20 | | See what needs you and what your agents did since yesterday | [Today](/docs/agents/today) | |
| 20 | 21 | | Have one of your agents review pull requests for bugs, like Bugbot | [Agent review](/docs/agents/review) | |
modifiedapps/diffinery/docs/reference/rest-api.md+2−2View file
| @@ -313,7 +313,7 @@ | ||
| 313 | 313 | } |
| 314 | 314 | ``` |
| 315 | 315 | |
| 316 | -Unexpected server errors return `500` with `{"message": "internal error"}`; the details go to the instance's logs, not to the client. | |
| 316 | +Unexpected server errors return `500` with `{"message": "internal error", "request_id": "..."}`; the details stay on the server. Every `5xx` answer carries a `request_id` in the body and the same value in the `x-request-id` header (on Cloudflare it is the request's Ray ID). Include it when you report a failure: a site administrator finds the error under [Server errors](/docs/admin/site-administration#server-errors). | |
| 317 | 317 | |
| 318 | 318 | Write your client to branch on the status code and show `message` to people. Messages are written for humans and may change wording. |
| 319 | 319 | |
| @@ -345,7 +345,7 @@ | ||
| 345 | 345 | | `413 Payload Too Large` | An upload or a generated archive is over a limit. | `release assets are limited to 100 MB`, `repository is too large for an on-the-fly archive; clone it with git instead` | |
| 346 | 346 | | `422 Unprocessable Entity` | The request is understood but invalid. | `title is required`, `invalid secret name`, `webhook URL must use https`, `state must be one of error, failure, pending, success`, `The search is longer than 256 characters.`, `push protection: possible secret detected (...)`, `scopes must be a non-empty list of: read, write, admin` | |
| 347 | 347 | | `429 Too Many Requests` | A per-repository budget ran out (only new source archives have one). | `too many archives were built for this repository in the last hour; try again later or clone it with git` | |
| 348 | -| `500 Internal Server Error` | A bug or an outage. | `internal error` | | |
| 348 | +| `500 Internal Server Error` | A bug or an outage. The body and the `x-request-id` header carry a `request_id` a site administrator can look up. | `internal error` | | |
| 349 | 349 | | `503 Service Unavailable` | A sandbox container didn't start. | `the sandbox container did not start; try again` | |
| 350 | 350 | |
| 351 | 351 | Every write to an archived repository returns `403 repository is archived (read-only)`, whatever role it needs: pushes, issues, comments, reviews, labels, branch protection, collaborators, secrets, variables, webhooks and MCP tools alike. Only a few calls still work: unarchiving it with `PATCH /repos/{owner}/{repo}` and `{"archived": false}` (admins), deleting it, watching or unwatching it, and linking a package to it. See [Archive a repository](/docs/repositories/overview#archive-a-repository). |