Files
deepseek-harness/docs/subsystems/forge.md
T
Yichen Jiang dcbfd8079a feat(experimental): bind code host change requests to Sessions
Add the experimental forge capability seam:

- dsh-experimental-forge: provider-neutral repository and change request
  references, a provider registry, and shared status polling. Watchers of
  one change request share one loop; each forge has one batched fetch in
  flight, and the cadence follows check, mergeability, and lifecycle state.
- dsh-experimental-forge-github: GitHub provider that runs the GitHub CLI
  on the host with a scrubbed environment and reads every due pull request
  of a host in one GraphQL query.
- dsh-experimental-forge-session: a host-only projection derives Session
  bindings from gh pr create and git push shell results and from
  plugin:forge-session/binding records; push results trigger head-branch
  discovery of open pull requests, and Session watchers poll bound change
  requests through ctx.forge.
2026-10-20 11:49:25 +08:00

300 lines
13 KiB
Markdown

# Forges
English | [中文](forge.zh.md)
The experimental forge capability seam reads change requests, meaning pull requests and merge requests, from code hosts. [`dsh-experimental-forge`](../../packages/experimental/forge/README.md) is the Service Definition and provides `ctx.forge`; [`dsh-experimental-forge-github`](../../packages/experimental/forge-github/README.md) is the Service Provider for GitHub hosts; [`dsh-experimental-forge-session`](../../packages/experimental/forge-session/README.md) is the Consumer that binds change requests to Sessions and provides `ctx.forgeSession`. All three load only through explicit composition.
## Providers and change requests
A provider serves one forge family, such as `github`. It maps Git remote URLs to repositories and change request URLs to references, builds canonical change request URLs, finds open change requests by head branch, and reads status in batches. `changeRequestKey` derives one case-insensitive key from a reference, so watchers of differently spelled URLs share one polling loop.
```ts type-equiv
/** One repository on a code host, identified the way its provider addresses it. */
interface ForgeRepository {
/** Provider family that serves the repository, such as `github`. */
readonly forge: string
/** Lowercase host name, such as `github.com`. */
readonly host: string
/** Owner or namespace path as the host spells it. */
readonly owner: string
/** Repository name as the host spells it. */
readonly name: string
}
```
```ts type-equiv
/** One change request (pull request or merge request) in a repository. */
interface ChangeRequestRef {
/** Repository that holds the change request. */
readonly repository: ForgeRepository
/** Host-assigned change request number. */
readonly number: number
}
```
```ts type-equiv
/**
* Host-specific access registered with `ctx.forge`. One provider serves one
* forge family; methods that take a signal must stop work when it aborts.
*/
interface ForgeProvider {
/** Forge family name stored in every repository this provider returns. */
readonly forge: string
/** Map a Git remote URL to its repository, or undefined when this provider does not serve it. */
repositoryFromRemote(url: string): ForgeRepository | undefined
/** Map a change request web URL to its reference, or undefined when this provider does not serve it. */
changeRequestFromUrl(url: string): ChangeRequestRef | undefined
/** Build the canonical web URL of a change request this provider serves. */
changeRequestUrl(ref: ChangeRequestRef): string
/** Read the status of several change requests, returning one result per requested key. */
fetch(
refs: readonly ChangeRequestRef[],
signal: AbortSignal,
): Promise<ReadonlyMap<ChangeRequestKey, ChangeRequestSnapshot | ForgeFailure>>
/** Find open change requests whose head is `branch` in `repository`, excluding the default branch and forks. */
findByHead(repository: ForgeRepository, branch: string, signal: AbortSignal): Promise<readonly ChangeRequestRef[]>
}
```
## Status polling
`ctx.forge.watch` shares one polling loop among the watchers of a change request and delivers every result as an update. Each forge has at most one fetch in flight. The [registry README](../../packages/experimental/forge/README.md#use-this-package) owns the poll cadence, backoff, and timeout rules.
```ts type-equiv
/** Status of one change request at the time its provider read it. */
interface ChangeRequestSnapshot {
/** Change request the snapshot describes. */
readonly ref: ChangeRequestRef
/** Web page of the change request. */
readonly url: string
/** Title as the author wrote it. */
readonly title: string
/** Lifecycle state. */
readonly state: ChangeRequestState
/** Whether the author marked the change request as a draft. */
readonly draft: boolean
/** Author login, or null when the host hides it. */
readonly author: string | null
/** Branch that carries the proposed commits. */
readonly headBranch: string
/** Commit object name at the head of the change request. */
readonly headSha: string
/** Branch the change request merges into. */
readonly baseBranch: string
/** Merge conflict status; `unknown` while the host computes it. */
readonly mergeability: Mergeability
/** Aggregate review outcome. */
readonly reviewDecision: ReviewDecision
/** Checks on the head commit in host order. */
readonly checks: readonly ChangeRequestCheck[]
/** Combined check outcome. */
readonly checksRollup: ChecksRollup
/** Whether the host reported more checks than `checks` contains. */
readonly checksTruncated: boolean
/** Number of review threads that are not resolved. */
readonly unresolvedThreads: number
/** ISO 8601 time of the host's last update to the change request. */
readonly updatedAt: string
}
```
```ts type-equiv
/** Latest polling result delivered to watchers of one change request. */
type ChangeRequestUpdate = {
/** Canonical identity of the watched change request. */
readonly key: ChangeRequestKey
/** Epoch milliseconds when the result settled. */
readonly fetchedAt: number
} & ({
/** Status read from the host. */
readonly snapshot: ChangeRequestSnapshot
} | {
/** Reason the status could not be read. */
readonly failure: ForgeFailure
})
```
```ts type-equiv
/**
* Receives every polling result for one watched change request.
* @param update - the settled result.
*/
type ChangeRequestListener = (update: ChangeRequestUpdate) => void
```
## Session bindings
`ctx.forgeSession` derives each Session's bindings from its own log: `gh pr create` results bind the URLs they print, and `git push` results trigger head-branch discovery through `ctx.forge`. Track, dismiss, and discovery actions are `plugin:forge-session/binding` records, which stay outside the model-visible conversation. The [Session binding README](../../packages/experimental/forge-session/README.md#use-this-package) owns the recognition and discovery rules.
```ts type-equiv
/**
* How a change request became bound to a Session: `created` when a
* `gh pr create` result printed its URL, `discovered` when a lookup after a
* `git push` found it for the pushed branch, `tracked` when a caller bound it
* by URL.
*/
type BindingOrigin = 'created' | 'discovered' | 'tracked'
```
```ts type-equiv
/** Payload of the `plugin:forge-session/binding` record. */
interface BindingRecord {
/** `track` binds or restores, `dismiss` hides, `discover` binds a change request found for a pushed branch. */
readonly action: 'track' | 'dismiss' | 'discover'
/** Web URL of the change request. */
readonly url: string
}
```
```ts type-equiv
/** One change request bound to a Session and not dismissed, with its latest polling result. */
interface SessionChangeRequest {
/** Web URL as first recorded. */
readonly url: string
/** How the change request became bound. */
readonly origin: BindingOrigin
/** Parsed reference, or null when no registered provider serves the URL. */
readonly ref: ChangeRequestRef | null
/** Latest polling result, or null before the first poll and without a provider. */
readonly update: ChangeRequestUpdate | null
}
```
```ts type-equiv
/**
* Receives the complete visible list after a binding change or a polling result.
* @param changeRequests - every visible binding of the watched Session, in first-recorded order.
*/
type SessionChangeRequestsListener = (changeRequests: readonly SessionChangeRequest[]) => void
```
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
<a id="cordis-surface"></a>
## Cordis API
Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
<a id="ctxforge--forgeservice"></a>
### `ctx.forge` — `ForgeService`
Registry of forge providers. Watchers of one change request share a single polling loop; each forge has at most one fetch in flight, which batches every due change request of that forge.
```ts cordis-catalog
/**
* Register the provider of one forge family as an effect on the calling
* fiber. Watches of that forge receive an `unavailable` failure when the
* registration ends.
* @param provider - provider to serve `provider.forge`.
* @returns the disposer that unregisters the provider.
* @throws when another provider already serves the same forge.
*/
register(provider: ForgeProvider): () => void
/**
* Map a Git remote URL to a repository through the first provider that serves it.
* @param url - fetch or push URL as Git reports it.
* @returns the repository, or undefined when no provider serves the URL.
*/
repositoryFromRemote(url: string): ForgeRepository | undefined
/**
* Map a change request web URL through the first provider that serves it.
* @param url - web URL of a pull or merge request.
* @returns the change request, or undefined when no provider serves the URL.
*/
changeRequestFromUrl(url: string): ChangeRequestRef | undefined
/**
* Build the canonical web URL of a change request.
* @param ref - change request served by a registered provider.
* @returns the provider's canonical URL.
* @throws when no provider serves the change request's forge.
*/
changeRequestUrl(ref: ChangeRequestRef): string
/**
* Find open change requests whose head is `branch`, excluding the default branch and forks.
* @param repository - repository served by a registered provider.
* @param branch - head branch name on the host.
* @param signal - cancellation for the lookup.
* @returns matching change requests, newest first as the provider reports them.
* @throws when no provider serves the repository's forge or the lookup fails.
*/
async findByHead(repository: ForgeRepository, branch: string, signal: AbortSignal): Promise<readonly ChangeRequestRef[]>
/**
* Watch one change request as an effect on the calling fiber. The first
* watcher starts polling at once; listeners receive every later result,
* and `latest` returns the current one. Polling stops when the last watcher
* leaves. Listeners must not throw; a thrown error is logged and skipped.
* @param ref - change request to poll.
* @param listener - receives each polling result.
* @returns the disposer that stops this watch.
*/
watch(ref: ChangeRequestRef, listener: ChangeRequestListener): () => void
/**
* Read the latest polling result of a watched change request.
* @param ref - change request to read.
* @returns the latest result, or undefined before the first result or without a watch.
*/
latest(ref: ChangeRequestRef): ChangeRequestUpdate | undefined
```
Source: [`packages/experimental/forge/src/index.ts`](../../packages/experimental/forge/src/index.ts)
<a id="ctxforgesession--forgesessionservice"></a>
### `ctx.forgeSession` — `ForgeSessionService`
Session-scoped change request bindings. The `forgeChangeRequests` projection derives them from `gh pr create` and `git push` results and from `plugin:forge-session/binding` records. After each push result the service looks up open change requests whose head is a pushed branch and records the unbound ones as discovered. Watching a Session polls its visible change requests through `ctx.forge`.
```ts cordis-catalog
/**
* List the change requests bound to a Session and not dismissed.
* @param session - Session whose bindings are read.
* @returns visible bindings in first-recorded order, each with its latest polling result.
*/
changeRequests(session: Session): SessionChangeRequest[]
/**
* Bind a change request to a Session by URL, or restore a dismissed binding.
* Appends a `track` record with the provider's canonical URL unless the
* change request is already visible.
* @param session - Session that receives the binding.
* @param url - web URL of the change request.
* @throws when no registered provider recognizes the URL.
*/
track(session: Session, url: string): void
/**
* Hide a visible binding. Appends a `dismiss` record; a URL that is not
* visibly bound leaves the log unchanged. Discovery never restores a
* dismissed binding; `track` does.
* @param session - Session that owns the binding.
* @param url - web URL of the change request.
*/
dismiss(session: Session, url: string): void
/**
* Watch a Session's visible change requests as an effect on the calling
* fiber. Every visible change request that a provider recognizes is polled
* through `ctx.forge` while the Session has a watcher. Listeners receive the
* complete list after each later binding change or polling result; read the
* current list with {@link changeRequests}. Listeners must not throw; a
* thrown error is logged and skipped.
* @param session - Session to watch.
* @param listener - receives the complete visible list.
* @returns the disposer that stops this watch.
*/
watch(session: Session, listener: SessionChangeRequestsListener): () => void
```
Types: [Session](session.md)
Source: [`packages/experimental/forge-session/src/index.ts`](../../packages/experimental/forge-session/src/index.ts)
<!-- END GENERATED cordis-surface -->