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

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

@@ -0,0 +1,95 @@
+/** 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;
+};
+/** Checks grouped by outcome; `other` holds neutral, skipped, and cancelled checks. */
+export interface CheckCounts {
+    readonly failed: number;
+    readonly running: number;
+    readonly passed: 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 the failed 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 @@
+/** Read-only Git inspection of a Session's current directory in the Session's 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 in a fixed directory; output with an exit code outside `allowedExitCodes` throws. */
+export type Git = (name: string, args: readonly string[], allowedExitCodes?: readonly number[]) => 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 a read-only confinement of 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`, under the same confinement as {@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, under the same confinement as {@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 confined Git runner to one Session and directory: every command
+ * runs under a read-only confinement of 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,275 @@
+/** 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 { 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 read-only in the Session's 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 confined to the Session's read-only sandbox.
+     * @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/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>;
+    /**
+     * 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>;
+    /**
+     * 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

package/lib/types/local-diff.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Local changes of a Session's checkout: where the `branch` scope forks, the
+ * patch of one scope with its untracked files, the new-side text of one file,
+ * and the size of the `branch` scope for the panel's card. Git runs through
+ * the confined runner; untracked and working-tree files are read through
+ * `ctx.fs`, both within `maxDiffBytes`.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { Git, GitConfig, Inspection } from './git.ts';
+import type { ForgeLocalChanges, ForgeLocalDiff, ForgeLocalScope, ForgeSessionWorktree } from './types.ts';
+/** Git limits plus the size limits of local diffs. */
+export interface DiffConfig extends GitConfig {
+    /** Largest patch, untracked file, or new-side file in bytes. */
+    readonly maxDiffBytes: number;
+    /** Most untracked files listed. */
+    readonly maxUntrackedFiles: number;
+}
+/** The commit the `branch` scope compares with and the name the panel shows for it. */
+export interface ForkPoint {
+    /** Full commit object name. */
+    readonly commit: string;
+    /** Remote branch such as `origin/master`, the created worktree's base branch, or an abbreviated commit. */
+    readonly label: string;
+}
+/** Thrown when a patch, a file list, or a file exceeds `maxDiffBytes`. */
+export declare class DiffTooLarge extends Error {
+    name: string;
+}
+/** Thrown for the `branch` scope of a checkout without a fork point. */
+export declare class NoForkPoint extends Error {
+    name: string;
+}
+/**
+ * Find where the `branch` scope forks: the base commit of the worktree the
+ * Session created while the checkout is that worktree, else the merge base of
+ * HEAD with the default branch of the first remote that names one, in the
+ * order the panel recognizes code hosts.
+ * @param git - runner bound to the checkout.
+ * @param inspection - the checkout and its remotes.
+ * @param created - worktree the Session created, or null.
+ * @returns the fork point, or null when no remote names a default branch or HEAD shares no history with it.
+ */
+export declare function forkPoint(git: Git, inspection: Inspection, created: ForgeSessionWorktree | null): Promise<ForkPoint | null>;
+/**
+ * Read the changes one scope covers in the checkout at `root`.
+ * @param ctx - context that provides `fs`, `subprocess`, `sandbox`, and `sandboxPolicy`.
+ * @param config - Git and size limits.
+ * @param session - Session whose sandbox policy and execution world apply.
+ * @param root - top-level directory of the checkout.
+ * @param fork - fork point of the `branch` scope, or null without one.
+ * @param scope - which changes to read.
+ * @param signal - cancellation of every command and read.
+ * @returns tracked files in Git's order, then untracked files unless the scope is `staged`.
+ * @throws NoForkPoint for the `branch` scope without `fork`; DiffTooLarge over `maxDiffBytes`; an Error when Git fails.
+ */
+export declare function localDiff(ctx: Context, config: DiffConfig, session: Session, root: string, fork: ForkPoint | null, scope: ForgeLocalScope, signal: AbortSignal): Promise<ForgeLocalDiff>;
+/**
+ * Read the new side of one file in a scope, which supplies the unchanged
+ * lines between hunks: the index for `staged`, else the working tree.
+ * @param ctx - context that provides `fs`, `subprocess`, `sandbox`, and `sandboxPolicy`.
+ * @param config - Git and size limits.
+ * @param session - Session whose sandbox policy and execution world apply.
+ * @param root - top-level directory of the checkout.
+ * @param scope - the scope whose new side to read.
+ * @param path - path relative to `root`, as the diff names it.
+ * @param signal - cancellation.
+ * @returns the text.
+ * @throws DiffTooLarge over `maxDiffBytes`; an Error for a path outside the checkout, binary content, or a failed read.
+ */
+export declare function localText(ctx: Context, config: DiffConfig, session: Session, root: string, scope: ForgeLocalScope, path: string, signal: AbortSignal): Promise<string>;
+/**
+ * Measure the `branch` scope for the panel's card.
+ * @param ctx - context that provides `fs`, `subprocess`, `sandbox`, and `sandboxPolicy`.
+ * @param config - Git and size limits.
+ * @param session - Session whose sandbox policy and execution world apply.
+ * @param inspection - the checkout and its remotes.
+ * @param created - worktree the Session created, or null.
+ * @param signal - cancellation of every command and read.
+ * @returns the base and the changed files, or null without a fork point.
+ * @throws DiffTooLarge when the untracked file list exceeds `maxDiffBytes`; an Error when Git fails.
+ */
+export declare function localChanges(ctx: Context, config: DiffConfig, session: Session, inspection: Inspection, created: ForgeSessionWorktree | null, signal: AbortSignal): Promise<ForgeLocalChanges | null>;
+/**
+ * Count the commits the checkout has beyond a change request's head, which a
+ * change request diff does not show yet.
+ * @param git - runner bound to the Session's directory.
+ * @param branch - the change request's head branch.
+ * @param commit - the change request's head commit.
+ * @returns the count, or null on another branch, outside a checkout, or without the commit locally.
+ */
+export declare function aheadOf(git: Git, branch: string, commit: string): Promise<number | null>;
+//# sourceMappingURL=local-diff.d.ts.map