@deepseek-ai/dsh-experimental-client-ui-forge 0.0.0-stage → 0.2.2-alpha.3

package/lib/types/client/source.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Host stream sources (per-Session panel states and the change request states
+ * of the Session list), the store behind action notices, and the tab visibility store.
+ */
+import type { HostObservable } from '@deepseek-ai/dsh-client-ui-slots';
+import type { ForgeChangeRequestListState, ForgeChangeRequestStatesFrame, ForgePanelState } from '../types.ts';
+import type { ForgePanelKey } from './locales.ts';
+/** What a stream source publishes: the value its frames built, and whether the stream ended while read. */
+export interface StreamSnapshot<S> {
+    /** Value built from the frames so far. */
+    readonly state: S;
+    /** Whether the stream ended while surfaces still read it. */
+    readonly disconnected: boolean;
+}
+/** What the panel surfaces of one Session read; `state` is null before the first one arrives. */
+export type PanelSnapshot = StreamSnapshot<ForgePanelState | null>;
+/** One open Host stream. */
+export interface HostStream<F> extends AsyncIterable<F> {
+    /** Close the stream. */
+    dispose: () => void;
+}
+/** One open stream of panel states. */
+export type PanelStream = HostStream<ForgePanelState>;
+/** Stream opener and connection-reset subscription of a source. */
+export interface StreamSourceDeps<F> {
+    /**
+     * Open the Host stream.
+     * @param signal - aborts the stream.
+     * @returns the stream.
+     */
+    readonly open: (signal: AbortSignal) => HostStream<F>;
+    /**
+     * Subscribe to transport resets, after which an open stream no longer delivers.
+     * @param listener - called on each reset.
+     * @returns the unsubscribe function.
+     */
+    readonly subscribeReset: (listener: () => void) => () => void;
+}
+/** Stream opener and connection-reset subscription of one Session's panel source. */
+export type PanelSourceDeps = StreamSourceDeps<ForgePanelState>;
+/** A value built from a Host stream that runs only while a surface subscribes. */
+export interface StreamSource<S> {
+    /** Snapshot observable; the renderer binds it as a selector hook. */
+    readonly observable: HostObservable<StreamSnapshot<S>>;
+    /** Open the stream again after it ended; a no-op while it runs or nobody subscribes. */
+    readonly reconnect: () => void;
+    /** Close the stream and the reset subscription and drop every subscriber. */
+    readonly close: () => void;
+}
+/** Panel state of one Session, streamed only while a surface subscribes. */
+export interface PanelSource {
+    /** Snapshot observable; the renderer binds it as `usePanel`. */
+    readonly hooks: {
+        readonly panel: HostObservable<PanelSnapshot>;
+    };
+    /** Open the stream again after it ended; a no-op while it runs or nobody subscribes. */
+    readonly reconnect: () => void;
+    /** Close the stream and the reset subscription and drop every subscriber. */
+    readonly close: () => void;
+}
+/**
+ * Create a source that folds a Host stream into one value. The first
+ * subscriber opens the stream and the last one closes it; the value stays
+ * readable for the next subscriber. A stream that ends or fails while
+ * subscribed marks the snapshot disconnected until `reconnect` or a transport
+ * reset reopens it.
+ * @param deps - stream opener and reset subscription.
+ * @param initial - value before the first frame.
+ * @param fold - the value after one frame.
+ * @returns the source.
+ */
+export declare function createStreamSource<F, S>(deps: StreamSourceDeps<F>, initial: S, fold: (state: S, frame: F) => S): StreamSource<S>;
+/**
+ * Create the panel source of one Session: the latest state the Host streamed.
+ * @param deps - stream opener and reset subscription.
+ * @returns the source.
+ */
+export declare function createPanelSource(deps: PanelSourceDeps): PanelSource;
+/**
+ * The known change request states after one `changeRequestStates` frame: a
+ * baseline replaces them, and a change replaces the states it carries.
+ * @param states - states by URL before the frame.
+ * @param frame - the frame.
+ * @returns states by URL after the frame.
+ */
+export declare function foldStates(states: ReadonlyMap<string, ForgeChangeRequestListState>, frame: ForgeChangeRequestStatesFrame): ReadonlyMap<string, ForgeChangeRequestListState>;
+/** One action notice; `seq` keys the toast so a repeated notice restarts it. */
+export interface ActionNotice {
+    /** Dictionary key of the notice text. */
+    readonly key: ForgePanelKey;
+    /** Values interpolated into the text. */
+    readonly params: Readonly<Record<string, string | number>>;
+    /** `success` reports a completed action; `failure` a refused or failed one. */
+    readonly tone: 'success' | 'failure';
+    /** Reverts the reported action, or undefined when it cannot be undone. */
+    readonly undo: (() => void) | undefined;
+    /** Increasing report number. */
+    readonly seq: number;
+}
+/** Optional parts of a reported notice. */
+export interface NoticeOptions {
+    /** Values interpolated into the text. */
+    readonly params?: Readonly<Record<string, string | number>>;
+    /** Defaults to `failure`. */
+    readonly tone?: ActionNotice['tone'];
+    /** Reverts the reported action. */
+    readonly undo?: () => void;
+}
+/** Store that action wiring reports into and one `shell.overlay` entry reads. */
+export interface NoticeSource {
+    /** Current notice, or null while none shows; the renderer binds it as `useNotice`. */
+    readonly hooks: {
+        readonly notice: HostObservable<ActionNotice | null>;
+    };
+    /**
+     * Show one notice, replacing the shown one.
+     * @param key - dictionary key of the text.
+     * @param options - interpolated values, tone, and undo action.
+     */
+    readonly report: (key: ForgePanelKey, options?: NoticeOptions) => void;
+    /** Clear the shown notice. */
+    readonly dismiss: () => void;
+}
+/**
+ * Create the action notice store.
+ * @returns the store.
+ */
+export declare function createNoticeSource(): NoticeSource;
+/** Whether one Session's forge tab is visible; the header entry reads it for its pressed state. */
+export interface VisibilitySource {
+    /** Current visibility; the renderer binds it as `useVisible`. */
+    readonly hooks: {
+        readonly visible: HostObservable<boolean>;
+    };
+    /**
+     * Record the tab's visibility.
+     * @param visible - whether the tab is visible.
+     */
+    readonly set: (visible: boolean) => void;
+}
+/**
+ * Create the visibility store of one Session's forge tab, initially hidden.
+ * @returns the store.
+ */
+export declare function createVisibilitySource(): VisibilitySource;
+//# sourceMappingURL=source.d.ts.map

package/lib/types/client/status.d.ts

@@ -0,0 +1,99 @@
+/** Status derivations shared by the header entry, the change request cards, and the changes view. */
+import type { ChangeRequestCheck, ChangeRequestSnapshot } from '@deepseek-ai/dsh-experimental-forge/types';
+import type { ForgePanelChangeRequest, ForgePanelState } from '../types.ts';
+import type { ForgePanelKey } from './locales.ts';
+/**
+ * Glyph tone of a change request: its lifecycle state, `blocked` for an open
+ * one, not a draft, that needs its author, or `unknown` before the first snapshot.
+ */
+export type ChangeRequestTone = 'open' | 'blocked' | 'draft' | 'merged' | 'closed' | 'unknown';
+/** Dictionary key of each tone's state name. */
+export declare const TONE_LABEL: Record<ChangeRequestTone, ForgePanelKey>;
+/** Combined check outcome shown on a collapsed card. */
+export type CiSummary = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'running';
+} | {
+    readonly kind: 'passed';
+}
+/** `count` is the number of failed checks the host listed, which can be zero when the list is truncated. */
+ | {
+    readonly kind: 'failed';
+    readonly count: number;
+} | {
+    readonly kind: 'cancelled';
+    readonly count: number;
+};
+/** Checks grouped by outcome; `other` holds neutral and skipped checks. */
+export interface CheckCounts {
+    readonly failed: number;
+    readonly running: number;
+    readonly passed: number;
+    readonly cancelled: number;
+    readonly other: number;
+}
+/** The most urgent fact of an open change request that the collapsed card names. */
+export type ChangeRequestFlag = 'changesRequested' | 'conflicting' | 'draft';
+/** The facts of a change request that decide its tone. */
+export type ToneFacts = Pick<ChangeRequestSnapshot, 'state' | 'draft' | 'checksRollup' | 'reviewDecision' | 'mergeability'>;
+/**
+ * Pick the glyph tone of a change request: an open draft is always `draft`;
+ * any other open one is `blocked` while its checks failed, changes were
+ * requested, or it conflicts with its base, and running checks, a pending
+ * review, and an unknown mergeability only wait and keep it `open`.
+ * @param snapshot - latest snapshot or listed state, or null before the first one.
+ * @returns the tone.
+ */
+export declare function toneOf(snapshot: ToneFacts | null): ChangeRequestTone;
+/**
+ * Count the listed checks by outcome.
+ * @param checks - checks of the head commit.
+ * @returns the counts.
+ */
+export declare function checkCounts(checks: readonly ChangeRequestCheck[]): CheckCounts;
+/**
+ * Summarize the checks of a change request from the host's combined outcome.
+ * @param snapshot - change request status.
+ * @returns the combined outcome with its failure or cancellation count.
+ */
+export declare function ciSummary(snapshot: ChangeRequestSnapshot): CiSummary;
+/**
+ * Pick the flag a collapsed card names: requested changes before merge
+ * conflicts before draft state; only open change requests carry one.
+ * @param snapshot - change request status.
+ * @returns the flag, or undefined when none applies.
+ */
+export declare function flagOf(snapshot: ChangeRequestSnapshot): ChangeRequestFlag | undefined;
+/**
+ * Whether a change request needs the user, the condition its card draws as `blocked`.
+ * @param entry - bound change request.
+ * @returns whether the header marks it.
+ */
+export declare function needsAttention(entry: ForgePanelChangeRequest): boolean;
+/**
+ * Pick the cards a Session's panel opens before the user expands or collapses
+ * one: the only open change request, drafts included, when exactly one is open.
+ * @param entries - bound change requests.
+ * @returns the URLs of the cards that start expanded.
+ */
+export declare function defaultExpanded(entries: readonly ForgePanelChangeRequest[]): ReadonlySet<string>;
+/**
+ * Find the open change request, drafts included, whose head is the checked-out branch.
+ * @param state - panel state of the Session.
+ * @returns the change request, or undefined without one or while HEAD is detached.
+ */
+export declare function openChangeRequestOf(state: ForgePanelState): ForgePanelChangeRequest | undefined;
+/**
+ * Read the change request number: the provider's reference, else the number at the end of the URL path.
+ * @param entry - bound change request.
+ * @returns the number, or null when neither names one.
+ */
+export declare function numberOf(entry: Pick<ForgePanelChangeRequest, 'ref' | 'url'>): number | null;
+/**
+ * Measure how long a completed check ran.
+ * @param check - one check.
+ * @returns elapsed milliseconds, or undefined when either time is unknown or they are out of order.
+ */
+export declare function checkDuration(check: ChangeRequestCheck): number | undefined;
+//# sourceMappingURL=status.d.ts.map

package/lib/types/diff.d.ts

@@ -0,0 +1,32 @@
+/** Unified patch parsing into the panel's browser-safe diff model, and the diff and size of an untracked file. */
+import type { ForgeChangedFile, ForgeDiffFile } from './types.ts';
+/**
+ * Parse a Git-style unified patch, as `git diff` or a code host prints it,
+ * with `a/` and `b/` path prefixes. Hunk ranges follow jsdiff: a range that
+ * covers no line starts at the line it comes before.
+ * @param patch - the patch text.
+ * @returns one file per patch section in patch order.
+ */
+export declare function parseDiff(patch: string): ForgeDiffFile[];
+/**
+ * Describe an untracked file as added in full.
+ * @param path - path relative to the repository root.
+ * @param content - the file's bytes.
+ * @returns the file with one hunk of added lines, none when it is empty, or none and `binary` when its content is not text.
+ */
+export declare function untrackedFile(path: string, content: Uint8Array): ForgeDiffFile;
+/**
+ * Decode file content as text the way Git decides it is not binary: no NUL
+ * byte among the first 8000 bytes, and, here, valid UTF-8 throughout.
+ * @param content - the bytes.
+ * @returns the text, or undefined for binary content.
+ */
+export declare function decodeText(content: Uint8Array): string | undefined;
+/**
+ * Parse `git diff --numstat -z` output, in which a rename prints its counts,
+ * an empty path, and then the old and new paths as separate fields.
+ * @param output - the command's standard output.
+ * @returns one file per record, named by its new path; a binary file counts no lines.
+ */
+export declare function parseNumstat(output: string): ForgeChangedFile[];
+//# sourceMappingURL=diff.d.ts.map

package/lib/types/git.d.ts

@@ -0,0 +1,93 @@
+/** Git queries in a Session's current directory, using its permissions and execution world. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { GitRemote } from './parse.ts';
+import type { ForgeBranches, ForgeCheckout } from './types.ts';
+/** Resolved Git executable and process limits. */
+export interface GitConfig {
+    /** Git executable name or absolute path. */
+    readonly gitCommand: string;
+    /** Deadline in milliseconds for one command, including executable lookup and confinement. */
+    readonly gitTimeoutMs: number;
+    /** Termination grace period in milliseconds for each process. */
+    readonly graceMs: number;
+    /** Maximum captured bytes per output stream. */
+    readonly maxOutputBytes: number;
+}
+/** Checkout facts with the upstream and remotes used to recognize the code host. */
+export interface Inspection {
+    /** Facts the panel shows. */
+    readonly checkout: ForgeCheckout;
+    /** Canonical Git directory shared by every checkout of the repository. */
+    readonly commonDir: string;
+    /** Upstream branch such as `origin/main`, or null when none is configured or HEAD is detached. */
+    readonly upstream: string | null;
+    /** Remotes in listed order. */
+    readonly remotes: readonly GitRemote[];
+}
+/** Complete output of one Git command that exited with an allowed code. */
+export interface GitOutput {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number;
+}
+/** Runs one Git subcommand with optional command-local configuration; output with an exit code outside `allowedExitCodes` throws. */
+export type Git = (name: string, args: readonly string[], allowedExitCodes?: readonly number[], configOverrides?: Readonly<Record<string, string>>) => Promise<GitOutput>;
+/** Thrown when a Git command prints more than `maxOutputBytes` on standard output. */
+export declare class GitOutputTooLarge extends Error {
+    name: string;
+}
+/**
+ * Inspect the checkout containing `directory`. Every command runs through the
+ * mounted subprocess provider under the Session's sandbox policy and reads
+ * refs and configuration only, never the working tree.
+ * The top-level and shared Git directories Git prints are resolved
+ * through `ctx.fs` into canonical process paths, the form the
+ * working-directory service records.
+ * @param ctx - context that provides `fs`, `subprocess`, `sandbox`, and `sandboxPolicy`.
+ * @param config - executable and process limits.
+ * @param session - Session whose sandbox policy and execution world apply.
+ * @param directory - absolute directory to inspect.
+ * @param signal - cancellation of every command.
+ * @returns the checkout facts, shared Git directory, upstream, and remotes, or undefined when `directory` is not inside a checkout.
+ * @throws when Git cannot run, fails, times out, or prints more than `maxOutputBytes`.
+ */
+export declare function inspectCheckout(ctx: Context, config: GitConfig, session: Session, directory: string, signal: AbortSignal): Promise<Inspection | undefined>;
+/**
+ * List the local branches that can start a worktree of the checkout containing
+ * `directory`, using the Session's permissions as in {@link inspectCheckout}.
+ * @param ctx - context that provides `subprocess`, `sandbox`, and `sandboxPolicy`.
+ * @param config - executable and process limits.
+ * @param session - Session whose sandbox policy and execution world apply.
+ * @param directory - absolute directory inside the checkout.
+ * @param limit - most branch names to return.
+ * @param signal - cancellation of every command.
+ * @returns the checked-out branch and local branches, the checked-out one first and then most recently committed first.
+ * @throws when `directory` is not inside a checkout, or Git cannot run, fails, times out, or prints more than `maxOutputBytes`.
+ */
+export declare function listBranches(ctx: Context, config: GitConfig, session: Session, directory: string, limit: number, signal: AbortSignal): Promise<ForgeBranches>;
+/**
+ * Report whether a local branch exists, using the Session's permissions as in {@link inspectCheckout}.
+ * @param ctx - context that provides `subprocess`, `sandbox`, and `sandboxPolicy`.
+ * @param config - executable and process limits.
+ * @param session - Session whose sandbox policy and execution world apply.
+ * @param repositoryRoot - absolute root of a checkout of the repository.
+ * @param branch - local branch name.
+ * @param signal - cancellation of the command.
+ * @returns whether `refs/heads/<branch>` exists.
+ * @throws when Git cannot run, fails, times out, or prints more than `maxOutputBytes`.
+ */
+export declare function hasBranch(ctx: Context, config: GitConfig, session: Session, repositoryRoot: string, branch: string, signal: AbortSignal): Promise<boolean>;
+/**
+ * Bind the Git runner to one Session and directory: every command
+ * runs under the Session's sandbox policy with the
+ * scrubbed environment, the fixed command prefix, and `config`'s limits.
+ * @param ctx - context that provides `subprocess`, `sandbox`, and `sandboxPolicy`.
+ * @param config - executable and process limits.
+ * @param session - Session whose sandbox policy and execution world apply.
+ * @param directory - working directory of every command.
+ * @param signal - cancellation of every command.
+ * @returns the runner.
+ */
+export declare function gitIn(ctx: Context, config: GitConfig, session: Session, directory: string, signal: AbortSignal): Git;
+//# sourceMappingURL=git.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,296 @@
+/** Host Remote of the forge panel: checkout, code host, sign-in, change request, and worktree state per Session. */
+import { Context, Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { ChangeRequestSnapshot, ForgeReviewRequest, ForgeReviewResult, MergeMethod } from '@deepseek-ai/dsh-experimental-forge';
+import type { Session } from '@deepseek-ai/dsh-session';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import type { Config, ForgeBranches, ForgeChangeRequestDiff, ForgeChangeRequestStatesFrame, ForgeLocalDiff, ForgeLocalScope, ForgePanelState } from './types.ts';
+export type * from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Remote that serves the forge panel of the GUI. */
+        forgePanel: ForgePanelController;
+    }
+}
+/**
+ * Serves the forge panel. Following a Session inspects the checkout of its
+ * current directory using the Session's permissions and execution world, recognizes the
+ * code host of the upstream remote or `origin`, probes sign-in for that host,
+ * and polls the Session's bound change requests through `ctx.forge` until the
+ * last follower of that Session leaves. A worktree request makes the panel
+ * create a branch and checkout through an optional `ctx.worktrees` and enter
+ * it while the Session's first message waits in the inbox, or at the first
+ * step proposal of a message no wait took. After a failed or stopped attempt
+ * the message keeps waiting for another attempt or for the request to be
+ * withdrawn. A message also waits while the worktree the Session works in is
+ * gone, until that worktree is checked out again or left for the source
+ * checkout. Changes to a Session's checkout run as Agent maintenance, so a
+ * message that arrives meanwhile waits for them.
+ */
+export declare class ForgePanelController extends TypertRemoteService {
+    static inject: string[];
+    static Config: z<Config>;
+    private readonly home;
+    private readonly config;
+    private readonly panels;
+    private worktreeStates;
+    private creations;
+    private readonly patches;
+    private states;
+    private readonly stopPanels;
+    private readonly stopStates;
+    constructor(ctx: Context, config: Config);
+    protected [Service.init](): Promise<void>;
+    /**
+     * Stream the panel state of a Session: the current state first, then each
+     * later state. Intermediate states may be skipped when the reader is slower
+     * than the updates. The stream ends when `signal` aborts or the Remote stops.
+     * @param session - Session to follow.
+     * @param signal - ends the stream.
+     * @returns panel states in publication order.
+     */
+    follow(session: Session, signal: AbortSignal): AsyncIterable<ForgePanelState>;
+    /**
+     * Stream the last known state of every change request that a listed
+     * Session the caller may read binds: the stored states first, then each
+     * state a poll changes or a new binding reveals. Listing reads no Session
+     * log: loaded Sessions report their bindings, others the cached Session
+     * summary, and a Session without one shows nothing until it is opened.
+     * Closed requests are polled at the idle cadence so reopening is observed. The
+     * stream ends when `signal` aborts or the Remote stops.
+     * @param signal - ends the stream.
+     * @returns frames in publication order.
+     * @throws when the Host lacks the Session query, projection cache, storage, or Session store service.
+     */
+    changeRequestStates(signal: AbortSignal): AsyncIterable<ForgeChangeRequestStatesFrame>;
+    /**
+     * List the local branches that can start a worktree of the Session's current checkout.
+     * @param session - Session whose current directory is listed.
+     * @param signal - request cancellation.
+     * @returns the checked-out branch and at most `maxBranches` local branches, the checked-out one first.
+     * @throws when the current directory is not inside a checkout or Git fails.
+     */
+    branches(session: Session, signal: AbortSignal): Promise<ForgeBranches>;
+    /**
+     * Bind a change request to a Session by URL, or restore a dismissed binding.
+     * @param session - Session that receives the binding.
+     * @param url - web URL of the change request.
+     * @param signal - request cancellation.
+     * @throws `forgePanel/unrecognized-url` when no registered provider serves the URL.
+     */
+    track(session: Session, url: string, signal: AbortSignal): Promise<void>;
+    /**
+     * Hide a visible binding of a Session; other URLs leave the Session unchanged.
+     * @param session - Session that owns the binding.
+     * @param url - web URL of the change request.
+     * @param signal - request cancellation.
+     */
+    dismiss(session: Session, url: string, signal: AbortSignal): Promise<void>;
+    /**
+     * Reinspect a followed Session's checkout, probe sign-in again, and poll its
+     * change requests at once; an unfollowed Session is unchanged.
+     * @param session - Session whose panel refreshes.
+     * @param signal - request cancellation.
+     * @returns settles once the inspection and the sign-in probe have ended; poll results reach the panel stream later.
+     */
+    refresh(session: Session, signal: AbortSignal): Promise<void>;
+    /**
+     * Read the changes one scope covers in the checkout of the Session's
+     * current directory, with Git using the Session's sandbox policy.
+     * @param session - Session whose checkout is read.
+     * @param scope - which changes to read.
+     * @param signal - request cancellation.
+     * @returns the files, the base of the `branch` scope, and the untracked files left out.
+     * @throws `forgePanel/not-a-checkout` outside a checkout; `forgePanel/no-fork-point` for the `branch`
+     * scope of a checkout without one; `forgePanel/filter-config-failed` when filter configuration cannot be read
+     * completely, before any comparison; `forgePanel/diff-too-large` over `maxDiffBytes`; the Git error when Git fails.
+     */
+    localDiff(session: Session, scope: ForgeLocalScope, signal: AbortSignal): Promise<ForgeLocalDiff>;
+    /**
+     * Read the new side of one changed file in a scope, which supplies the
+     * unchanged lines between its hunks: the index for `staged`, else the working tree.
+     * @param session - Session whose checkout is read.
+     * @param scope - the scope the diff was read in.
+     * @param path - path relative to the checkout's top-level directory, as the diff names it.
+     * @param signal - request cancellation.
+     * @returns the text.
+     * @throws `forgePanel/not-a-checkout` outside a checkout; `forgePanel/diff-too-large` over `maxDiffBytes`;
+     * an error for a path outside the checkout, binary content, or a failed read.
+     */
+    localText(session: Session, scope: ForgeLocalScope, path: string, signal: AbortSignal): Promise<string>;
+    /**
+     * Load complete checks for the change request whose list the user opened.
+     * @param session - Session retaining the visible binding.
+     * @param url - binding URL.
+     * @param headSha - commit displayed by the card; a different head rejects the result.
+     * @param signal - cancellation when the list closes.
+     * @returns the complete snapshot at the displayed head.
+     * @throws `forgePanel/not-bound` for an invisible binding, `forgePanel/stale-head` for a moved head,
+     * or `forgePanel/checks-failed` when the provider cannot complete the read.
+     */
+    changeRequestChecks(session: Session, url: string, headSha: string, signal: AbortSignal): Promise<ChangeRequestSnapshot>;
+    /**
+     * Read the changes of a change request of a Session as its code host
+     * computes them, at the head commit of its latest status. A patch already
+     * read at the same head commit and base branch is reused from memory, for
+     * any Session, until `maxCachedDiffBytes` evicts it.
+     * @param session - Session the change request is bound to.
+     * @param url - binding URL of the change request.
+     * @param signal - request cancellation.
+     * @returns the files, the head commit, each file's web page, and the commits the checkout has beyond the head.
+     * @throws `forgePanel/not-bound` unless the URL is a visible binding of the Session that a provider serves;
+     * `forgePanel/diff-too-large` when the host or its provider refuses the diff over a size limit;
+     * `forgePanel/diff-failed` before its status was read and when the host does not provide the diff otherwise.
+     */
+    changeRequestDiff(session: Session, url: string, signal: AbortSignal): Promise<ForgeChangeRequestDiff>;
+    /**
+     * Read one file of a change request's repository at a commit, which
+     * supplies the unchanged lines between the hunks of its diff.
+     * @param session - Session the change request is bound to.
+     * @param url - binding URL of the change request.
+     * @param commit - commit object name, the head commit of the diff.
+     * @param path - path relative to the repository root.
+     * @param signal - request cancellation.
+     * @returns the text.
+     * @throws `forgePanel/not-bound` unless the URL is a visible binding of the Session that a provider serves;
+     * `forgePanel/diff-too-large` when the host or its provider refuses the file over a size limit;
+     * `forgePanel/diff-failed` when the host does not provide the file otherwise.
+     */
+    changeRequestText(session: Session, url: string, commit: string, path: string, signal: AbortSignal): Promise<string>;
+    /**
+     * Publish a line comment or completed review for a visible Session binding.
+     * @param session - Session retaining the change request.
+     * @param url - visible binding URL.
+     * @param request - reviewed head, ranges, plain text, and explicit review decision.
+     * @param signal - request cancellation.
+     * @returns confirmed publication or a typed failure; unknown outcomes require reconciliation on the host.
+     */
+    submitReview(session: Session, url: string, request: ForgeReviewRequest, signal: AbortSignal): Promise<ForgeReviewResult>;
+    /**
+     * Mark a draft change request of a Session ready for review; the change
+     * request is polled again once the host answers.
+     * @param session - Session the change request is bound to.
+     * @param url - binding URL of the change request.
+     * @param signal - request cancellation.
+     * @throws `forgePanel/not-bound` unless the URL is a visible binding of the Session that a provider serves;
+     * `forgePanel/action-failed` with the host's reason when the host refuses or cannot be reached.
+     */
+    markReady(session: Session, url: string, signal: AbortSignal): Promise<void>;
+    /**
+     * Merge a change request of a Session while its head is still `headSha`;
+     * the change request is polled again once the host answers.
+     * @param session - Session the change request is bound to.
+     * @param url - binding URL of the change request.
+     * @param method - how the commits enter the base branch.
+     * @param headSha - head commit the user confirmed.
+     * @param signal - request cancellation.
+     * @throws `forgePanel/not-bound` unless the URL is a visible binding of the Session that a provider serves;
+     * `forgePanel/stale-head` when the head moved past `headSha`; `forgePanel/action-failed` with the host's
+     * reason when the host refuses otherwise or cannot be reached.
+     */
+    merge(session: Session, url: string, method: MergeMethod, headSha: string, signal: AbortSignal): Promise<void>;
+    /**
+     * Ask for a new worktree before the Session's first turn, replacing an open
+     * request and forgetting a failed attempt. While the next message waits in
+     * the inbox, or else at the first step proposal, the panel creates a branch
+     * from `from`, or from HEAD of the current checkout when it is null, and
+     * enters its checkout. A message that already waits after a failed or
+     * stopped attempt keeps waiting for {@link ForgePanelController.retryWorktree}.
+     * @param session - Session without a started turn.
+     * @param from - local base branch, or null for HEAD.
+     * @param signal - request cancellation.
+     * @throws `forgePanel/invalid-branch` when `from` is empty; `forgePanel/worktrees-unavailable`
+     * without a worktree service; `forgePanel/session-started` after a turn started or the worktree was
+     * created; `forgePanel/session-busy` while the worktree is being created.
+     */
+    requestWorktree(session: Session, from: string | null, signal: AbortSignal): Promise<void>;
+    /**
+     * Withdraw the open worktree request of a Session with its failed attempt,
+     * which lets a waiting message go on in the current checkout; without a
+     * request the Session is unchanged. Withdrawing needs no worktree service.
+     * @param session - Session without a started turn.
+     * @param signal - request cancellation.
+     * @throws `forgePanel/session-started` after a turn started or the worktree was created;
+     * `forgePanel/session-busy` while the worktree is being created.
+     */
+    cancelWorktree(session: Session, signal: AbortSignal): Promise<void>;
+    /**
+     * Stop the creation a message of the Session waits for; the message keeps
+     * waiting with the request still open. Without such a creation the Session
+     * is unchanged.
+     * @param session - Session whose creation stops.
+     * @param signal - request cancellation.
+     */
+    stopCreation(session: Session, signal: AbortSignal): Promise<void>;
+    /**
+     * Make another attempt, with a new branch name, at the worktree a message
+     * of the Session waits for after a failed or stopped attempt.
+     * @param session - Session whose message waits.
+     * @param signal - request cancellation.
+     * @throws `forgePanel/not-waiting` when no message waits or an attempt is running.
+     */
+    retryWorktree(session: Session, signal: AbortSignal): Promise<void>;
+    /**
+     * Check out the created worktree of a Session again at its recorded
+     * directory when that directory is gone: its branch when the branch still
+     * exists, otherwise a new branch of the same name at the base commit. Changes
+     * that were never committed are not recovered. Runs as Agent maintenance,
+     * inside the wait of a message that waits for the restoration, which then
+     * goes on; without a missing directory the Session is unchanged.
+     * @param session - Session whose worktree directory is gone.
+     * @param signal - request cancellation, which aborts the restoration.
+     * @throws `forgePanel/no-worktree` without a created worktree; `forgePanel/worktrees-unavailable`
+     * without a worktree service; `forgePanel/session-busy` while the Session's Agent is not loaded or
+     * has other work; `forgePanel/restore-failed` when Git fails.
+     */
+    restoreWorktree(session: Session, signal: AbortSignal): Promise<void>;
+    /**
+     * Move a Session from its created worktree to the source checkout the
+     * worktree came from; the Session no longer works in the worktree. Runs as
+     * Agent maintenance, inside the wait of a message that waits for the removed
+     * worktree, which then goes on.
+     * @param session - Session with a created worktree.
+     * @param signal - request cancellation.
+     * @throws `forgePanel/no-worktree` without a created worktree; `forgePanel/session-busy` while the
+     * Session's Agent is not loaded or has other work; the working-directory service's error when the
+     * source checkout no longer exists.
+     */
+    continueInProject(session: Session, signal: AbortSignal): Promise<void>;
+    /**
+     * Hold the turn of a message entering a Session's inbox while the
+     * Session's requested worktree does not exist yet, or while the worktree
+     * the Session works in is checked and, when gone, until it is restored or
+     * left. The message is entering, so the delivery has not woken the Agent
+     * yet and its wake waits for the hold.
+     * @param agent - Agent whose inbox receives the message.
+     */
+    private holdTurn;
+    /**
+     * Check whether the worktree the Session works in is gone.
+     * @param session - Session to check.
+     * @param signal - cancellation of the check.
+     * @returns the missing worktree, or null while it exists or once the Session works elsewhere.
+     * @throws when the filesystem or Git cannot answer.
+     */
+    private missingFor;
+    /** Inspect the checkout of the Session's current directory, which local diffs read. */
+    private checkoutOf;
+    /** A visible binding of the Session that a provider serves, which actions and reads are limited to. */
+    private bound;
+    private worktreeState;
+    private editableWorktree;
+    /** The worktree state of a Session whose request may still change: no turn started, nothing created, and no attempt running. */
+    private changeableWorktree;
+    private createdWorktree;
+    /**
+     * Run work as maintenance of the Session's Agent: inside the wait of a
+     * message that waits for the removed worktree, else as a task of its own,
+     * which the Agent refuses while it has other work.
+     */
+    private maintain;
+    /** The shared change request states, created for the first stream from the Host's Session and storage services. */
+    private changeRequestStatesHub;
+    private panelOf;
+}
+export default ForgePanelController;
+//# sourceMappingURL=index.d.ts.map