dsh-github

dsh-github

English | 中文

The GitHubRuntime (ctx.github) defines WHAT GitHub access the harness has — search, read issues/PRs/diffs/checks, create issues/comments/PRs — over registered providers, without binding the model contract to one transport's API shape.

This package owns the Service Definition role of the GitHub capability (design: docs/design/design.md, §3–§4):

Package	Role
dsh-github (this)	Service Definition: the service, provider registry, selection policy, read/write vocabulary, seam-enforced diff budgets, the GitHubError taxonomy
dsh-github-rest	Provider: GitHub REST v3 via fetch (M2)
dsh-tool-github	Consumer: the model-facing github_* tool schemas over ctx.github (M3/M4)

Reads and writes are deliberately ONE provider interface (ADR-0003): they share identity, credentials, and rate-limit budget, so splitting them would let authentication state diverge.

Service API (ctx.github)

Member	Semantics
registerProvider(provider)	Register a backend. Throws GitHubError GITHUB_PROVIDER_DUPLICATE on a duplicate id. Returns a disposer. Disposed with the calling fiber.
search(request, signal?)	Resolve the provider and run one search. Enforces request.maxResults on the result (truncates items[], sets truncated).
getIssue / getPullRequest / getComments / getChecks	Normalized on-demand reads. PR metadata never embeds diff or checks — they are separate calls.
getDiff(item, request?, signal?)	Read a PR diff, enforcing the consumer-owned maxFiles / maxPatchChars budgets at the seam (ADR-0005). truncated is honest: true whenever ANY reduction happened, provider-side or seam-side.
getReviews / getReviewComments	Submitted review verdicts, and the line-anchored comments they carry. GitHubReviewComment is deliberately NOT GitHubComment: it has a path and a line, and you act on it by editing that code.
getCheckFailures(item, request?, signal?)	Why the failing checks failed: annotations when the CI tool reported them, otherwise a log tail under the consumer-owned maxLogLines / maxLogChars budgets (ADR-0015). Same honesty rule as getDiff — a provider-truncated log alone marks the whole result truncated.
buildReviewBrief(item, request?, signal?)	The deterministic half of a structured review (ADR-0013): route the dimensions this change actually warrants, carry its diff once, and attach the checklists, severity scale, and finding contract. Routes and packages evidence; never judges.
getMergeability / listPullRequests	Merge readiness with its blockers spelled out, and a capped pull request listing.
submitReview / updatePullRequest / requestReviewers / setLabels	The review-write half. The seam validates inline-comment anchors but does NOT decide whether a verdict is allowed — that policy is about what the MODEL may do, so it lives at the tool layer (ADR-0014).
createIssue / createComment / createPullRequest	Writes. PR creation is idempotent (ADR-0004): an existing open PR for the same head/base comes back with created: false.

Providers register capabilities, not tools. dsh-tool-github is the only owner of model-facing names, descriptions, prompt guidance, JSON schemas, and presentation.

Selection

Selection never depends on registration, config, or HMR order. Either an explicit provider id is configured (config provider, or env $DSH_GITHUB_PROVIDER feeding the same field), or exactly one usable provider auto-selects. Operations resolve the provider at execution time, on EVERY call — never cached — so a credential change flips available() without restart:

Situation	Execution
configured id registered and available()	runs that provider
configured id not registered	GITHUB_PROVIDER_CONFIGURED_MISSING
configured id registered but unavailable	GITHUB_PROVIDER_CONFIGURED_UNAVAILABLE
no id, exactly one registered usable provider	runs it
no id, no usable provider	GITHUB_PROVIDER_UNAVAILABLE
no id, multiple usable providers	GITHUB_PROVIDER_AMBIGUOUS

A provider's available() is a cheap local check (credential ref resolvable) and must not make network calls.

Vocabulary

GitHubRepoRef (owner, repo) and GitHubItemRef (repo, number, url?) are the portable handles the model passes between tools. Read shapes: GitHubIssue, GitHubPullRequest (merged is a first-class state), GitHubComment, GitHubDiff (files[], truncated), GitHubChecksResult. GitHubSearchKind is a CLOSED union (issues | pull-requests | repositories | code) — consumers switch to exhaustiveness. Writes: GitHubIssueCreateRequest, GitHubCommentCreateRequest, GitHubPullRequestCreateRequest → GitHubPullRequestCreateResult (pullRequest, created). The seam validates refs (non-blank owner/repo, positive-integer numbers) and budget parameters as GITHUB_VALIDATION. See src/types.ts for the full contracts and the GitHubError code taxonomy (GITHUB_AUTH, GITHUB_RATE_LIMITED + retryAfterMs, GITHUB_NOT_FOUND, GITHUB_VALIDATION, GITHUB_ABORTED, GITHUB_PROVIDER_*).

Model Experience

Indirectly, through dsh-tool-github, which renders bounded normalized GitHub data or the structured failure codes above (rate limits surface a retry-after hint); this registry contributes no prompt or schema itself.