@neosh/api 0.3.0 → 0.4.1

package/src/index.ts

@@ -17,6 +17,10 @@ import type { ApiError } from "./generated/ApiError";
 import type { ApiOk } from "./generated/ApiOk";
 import type { ApiResponse } from "./generated/ApiResponse";
 import type { BranchInfo } from "./generated/BranchInfo";
+import type { Direction } from "./generated/Direction";
+import type { PaneId } from "./generated/PaneId";
+import type { TabId } from "./generated/TabId";
+import type { TabInfo } from "./generated/TabInfo";
 import type { BufferId } from "./generated/BufferId";
 import type { Capability } from "./generated/Capability";
 import type { CommitInfo } from "./generated/CommitInfo";
@@ -32,6 +36,7 @@ import type { CredentialSource } from "./generated/CredentialSource";
 import type { CursorMotion } from "./generated/CursorMotion";
 import type { CursorShape } from "./generated/CursorShape";
 import type { SelectShape } from "./generated/SelectShape";
+import type { ScrollAmount } from "./generated/ScrollAmount";
 import type { DiffTarget } from "./generated/DiffTarget";
 import type { Dock } from "./generated/Dock";
 import type { Gravity } from "./generated/Gravity";
@@ -132,12 +137,16 @@ import type { Viewport } from "./generated/Viewport";
 import type { WindowId } from "./generated/WindowId";
 import type { WindowInfo } from "./generated/WindowInfo";
 import type { WindowLayout } from "./generated/WindowLayout";
+import type { ChecksState } from "./generated/ChecksState";
+import type { PullRequest } from "./generated/PullRequest";
+import type { PullState } from "./generated/PullState";
 import type { WorktreeInfo } from "./generated/WorktreeInfo";
 
 export type {
   AccountKind, Activity, ApiError, BranchInfo, Brand, BufferId, Capability, CommandEntry, CommitInfo,
   AgentCommand, AgentState, AgentSummary,
-  Contribution, CredentialInfo, CredentialSource, CursorShape, DiffTarget, Dock, CursorMotion, ExtmarkId, ExtmarkInfo, ExtmarkOpts, FileChange, FileState, FloatConfig,
+  Contribution, CredentialInfo, CredentialSource, CursorShape, DiffTarget, Direction, Dock, CursorMotion, ExtmarkId, ExtmarkInfo, ExtmarkOpts, FileChange, FileState, FloatConfig,
+  PaneId, TabId, TabInfo,
   Gravity, HighlightDef, HighlightEntry, HighlightSpec, Hint, HlTarget, HookName, HookOutcome, HookPayload, InstanceConfig, KeyContext,
   AttachmentInfo,
   KeymapEntry, KeymapScope, MessageLevel, Mode, ModelEntry, ModelInfo, ModelSelection, ModelTier, NamespaceId,
@@ -148,12 +157,15 @@ export type {
   CostBasis, QuotaCredits, QuotaSample, QuotaSeverity, QuotaSnapshot, QuotaSource, QuotaWindow,
   InstallMethod, UpdateOutcome, UpdateStatus,
   UsageBucket, UsageHistory, UsageResolution, UsageScanSource,
-  Rect, RepoInfo, RepoStatus, SelectShape, SessionId, SessionInfo, StatusAlign, StatusSegment, StopReason,
+  Rect, RepoInfo, RepoStatus, ScrollAmount, SelectShape, SessionId, SessionInfo, StatusAlign, StatusSegment, StopReason,
   SurfaceCell, SurfaceId, TextEdit, ToolCall, ToolDef, ToolResult, TurnRequest, Usage,
   NodeCapabilities, NodeId, NodeInfo, ProjectKey, RemoteProject, StreamEvent,
   SwarmAgent, SwarmNode, SwarmStranger,
   VarScope, ViewId, ViewInfo, Viewport,
   WindowId, WindowInfo, WindowLayout,
+  ChecksState,
+  PullRequest,
+  PullState,
   WorktreeInfo,
 };
 
@@ -363,6 +375,16 @@ export interface FloatOptions {
   border?: FloatConfig["border"];
   borderHl?: string;
   title?: string;
+  /**
+   * A strip on the bottom border: what the keys here do.
+   *
+   * On the border rather than in the buffer, because a key strip written as a row of content is one
+   * that scrolls away exactly when it is wanted, and is the first thing clipped on a terminal too
+   * short for the panel. It costs no content row and cannot be scrolled off.
+   *
+   * Clipped to the border's width like the title, so it is for a legend and not for prose.
+   */
+  footer?: string;
   closeOnBlur?: boolean;
   focusable?: boolean;
   /**
@@ -379,12 +401,34 @@ export interface FloatOptions {
    * control sheet. Not for a hint or a hover card.
    */
   modal?: boolean;
+  /**
+   * This panel is a place you can move in when it does not fit.
+   *
+   * You ask for a height and get whatever there is: `{ kind: "max", n: 30 }` on a twenty-row
+   * terminal is ten rows of panel and twenty rows of content drawn nowhere, with no key pointed at
+   * them and nothing on screen to say they exist. Set this and the workspace's scroll keys resolve
+   * here — `j`/`k`, `^D`/`^U`, `^F`/`^B`, `gg`/`G`, the arrows and the paging keys — along with the
+   * mouse wheel, and a bar appears down the right border while anything is hidden.
+   *
+   * They are ordinary bindings on `{ kind: "buf_kind", name: "neosh.scroll" }`, so `^Z` lists them
+   * and `init.ts` moves them. That scope sits *below* your buffer's own kind, so a key you bind on
+   * your panel is still yours — and above `global`, so it works under `modal` too.
+   *
+   * For a panel of rows you read: a key sheet, a diff, a status, a help screen. **Not** for one with
+   * a cursor of its own — a picker, a list — which already scrolls to keep the cursor on screen and
+   * whose filter would lose `j` and `G` to this.
+   */
+  scroll?: boolean;
 }
 
 export interface Neosh {
   readonly version: number;
   readonly buf: BufferApi;
   readonly win: WindowApi;
+  /** The panes of the main region. See {@link PaneApi}. */
+  readonly pane: PaneApi;
+  /** The tabs each terminal has. See {@link TabApi}. */
+  readonly tab: TabApi;
   readonly float: FloatApi;
   readonly edit: EditApi;
   readonly ns: NamespaceApi;
@@ -406,6 +450,8 @@ export interface Neosh {
   readonly opt: OptionApi;
   readonly state: StateApi;
   readonly vars: VarApi;
+  /** The directories somebody works in. See {@link ProjectApi}. */
+  readonly project: ProjectApi;
   readonly ext: ExtensionApi;
   readonly event: EventApi;
   readonly swarm: SwarmApi;
@@ -558,6 +604,84 @@ export interface BufferApi {
   ): Promise<Disposable>;
 }
 
+/**
+ * The panes of the main region, and the tabs they live in.
+ *
+ * A pane is *where*, not *what*: it owns no buffer and draws nothing. You split one, then dock
+ * windows into it with {@link WindowApi.open} — which is why splitting a chat and splitting a
+ * terminal are the same two calls.
+ *
+ * Everything here is what the workspace's own `<C-w>` keys are built from. There is no private
+ * path: `<C-w>v` is `pane.split(await pane.active(), "right")` and nothing else, so a plugin that
+ * wants a different window manager can have one without forking anything.
+ */
+export interface PaneApi {
+  /** The pane this terminal's keys belong to. */
+  active(view?: ViewId): Promise<PaneId>;
+  /**
+   * Divide a pane in two, and answer with the new one.
+   *
+   * The new pane is *empty* — nothing is drawn in it until something is docked into it. Focus does
+   * not move either: a plugin splitting to show you something and a person pressing a key to go
+   * and work there are different intentions, and only the second one wants the keyboard.
+   */
+  split(pane: PaneId, dir: Direction): Promise<PaneId>;
+  /**
+   * Close a pane and every window docked in it.
+   *
+   * Rejects on the last pane of the last tab: a terminal with nowhere to draw has no key that
+   * would bring a pane back.
+   */
+  close(pane: PaneId): Promise<void>;
+  focus(pane: PaneId): Promise<void>;
+  /**
+   * Move the keyboard to the nearest pane in a direction, and answer with it — or `null` at the
+   * edge of the layout, which is an ordinary outcome of holding a key down rather than an error.
+   * There is deliberately no wrap-around.
+   */
+  focusDir(dir: Direction, view?: ViewId): Promise<PaneId | null>;
+  /**
+   * Move the boundary on a pane's `dir` side. `delta` is in weight units — an even split is
+   * {@link WEIGHT} each — so a resize means the same thing at every terminal size and survives the
+   * terminal being resized under it. A pane with no boundary on that side is a no-op.
+   */
+  resize(pane: PaneId, dir: Direction, delta: number): Promise<void>;
+  /**
+   * Exchange two panes' places, keeping what is in each. The weights belong to the slots, so
+   * swapping into the wide one is how you make a pane wide.
+   */
+  swap(pane: PaneId, withPane: PaneId): Promise<void>;
+  /**
+   * Send a pane to the far edge of its tab — the counterpart to {@link PaneApi.focusDir}, which
+   * moves the keyboard rather than the pane. It arrives with an even share rather than the size it
+   * had: it is among different neighbours now, and carrying the old number over would make it the
+   * odd one out for a reason nobody could see.
+   */
+  moveToEdge(pane: PaneId, dir: Direction): Promise<void>;
+  /** Give every pane of the active tab an equal share, at every level. */
+  equalize(view?: ViewId): Promise<void>;
+}
+
+/** The tabs of one terminal. Each is a title and a tree of panes. */
+export interface TabApi {
+  /** Every tab of a terminal, its panes, and which one is on screen. */
+  list(view?: ViewId): Promise<{ tabs: TabInfo[]; active: TabId }>;
+  /**
+   * Open a tab with one empty pane. `activate` goes to it — `false` is for putting work somewhere
+   * without moving the screen out from under whoever is reading it.
+   */
+  create(opts?: { title?: string; activate?: boolean; view?: ViewId }): Promise<TabId>;
+  /** Close a tab and every pane in it. Rejects on a terminal's last tab. */
+  close(tab: TabId): Promise<void>;
+  select(tab: TabId): Promise<void>;
+  /** Go `delta` tabs along, wrapping — a tab bar is a list you can see all of. */
+  step(delta: number, view?: ViewId): Promise<void>;
+  /** Move a tab along the bar, clamped at the ends. This is a drag; a drag that teleports is a bug. */
+  move(tab: TabId, to: number): Promise<void>;
+  /** Name a tab, or pass `null` to give it back its derived name. */
+  rename(tab: TabId, title: string | null): Promise<void>;
+}
+
 export interface WindowApi {
   /**
    * `gravity` is which end short content settles against: `"start"` (the default) pins it to the
@@ -568,11 +692,17 @@ export interface WindowApi {
    * wrapped a long path would reflow every row below it — but a text field is prose and wants
    * this on. A bottom dock that wraps also grows to show the folded rows, `size` acting as its
    * floor.
+   *
+   * `pane` docks the window inside one pane of the main region rather than against the screen.
+   * The same four edges either way — a composer at the foot of a pane is this call with a `pane`,
+   * and a status line along the foot of the terminal is this call without one. Omit it for
+   * anything that belongs to the whole terminal: a sidebar docked into a pane would be a sidebar
+   * that disappears when you close that split.
    */
   open(
     buf: BufferId,
     dock: Dock,
-    opts?: { size?: number; gravity?: Gravity; wrap?: boolean },
+    opts?: { size?: number; gravity?: Gravity; wrap?: boolean; pane?: PaneId },
   ): Promise<WindowId>;
   close(win: WindowId): Promise<void>;
   /**
@@ -596,6 +726,19 @@ export interface WindowApi {
    * its first row at `0`. Anything else shows the same thing either way.
    */
   scrollTo(win: WindowId, topLine: number | null): Promise<void>;
+  /**
+   * Move a window's scroll by a line, a half screen, a screen, or all the way to an end.
+   *
+   * What {@link scrollTo} cannot express, because the arithmetic is not yours to do: "half a screen"
+   * is counted in the buffer rows the frontend actually drew — which on a wrapping window is fewer
+   * than its height — and the floor is the last screenful rather than the last line, so the bottom
+   * is a full panel and not one row above an empty one. Both numbers are a frame old by the time
+   * {@link viewport} hands them to you; this reads them where they live.
+   *
+   * The keys bound on `neosh.scroll` run exactly this. Call it directly for a scroll a key did not
+   * ask for — following output, or a button on a panel of your own.
+   */
+  scroll(win: WindowId, amount: ScrollAmount): Promise<void>;
   /**
    * How big this window actually is, in cells.
    *
@@ -1059,12 +1202,52 @@ export interface GitApi {
   stage(paths?: string[]): Promise<void>;
   unstage(paths?: string[]): Promise<void>;
   commit(message: string): Promise<CommitInfo>;
+  /**
+   * `git fetch --prune`, answering with where the tree stands *after* it.
+   *
+   * **The one call that makes `ahead` and `behind` mean anything.** `status()` reads them off
+   * `git status --branch`, which compares HEAD with the remote-tracking ref sitting on this disk —
+   * so a panel drawing `↓0` from it is reporting the state of the world as of whenever this
+   * checkout last spoke to a remote. Call this first and the number is news; do not, and it is
+   * archaeology.
+   *
+   * It answers with the fresh {@link RepoStatus} rather than nothing, so "fetch and see where I am"
+   * is one round trip. Prunes, because a picker offering six branches that were deleted when their
+   * pull requests merged is worse than one that is a fetch behind.
+   *
+   * A write, and the reason is the network rather than the working tree, which does not move:
+   * this contacts a remote and writes refs. It fails rather than hangs when there are no
+   * credentials — stdin is closed and every askpass unset — which is what makes it safe to put on
+   * a timer. Expect it to reject routinely: no remote, no network, a key the host will not take.
+   */
+  fetch(opts?: { cwd?: string }): Promise<RepoStatus>;
+  /**
+   * Every pull request the forge knows about for this repository, open and closed.
+   *
+   * **One call answers for every checkout.** They come back keyed by
+   * {@link PullRequest.branch}, so a repository with six worktrees is one request and six lookups
+   * — which is the difference between a panel that costs a round trip every few minutes and one
+   * that costs six.
+   *
+   * Answered by `gh`, the CLI the user has already signed into, so tokens, enterprise hosts, SSO
+   * and rate limits are already handled and the answer is the one they get in their own terminal.
+   *
+   * **Rejects rather than answering empty** when it cannot know — no `gh`, not signed in, no
+   * remote on a forge. An empty list is the claim "this repository has no pull requests", and
+   * three of the four ways this fails would be making it falsely. Catch it, say it once, and do
+   * not say it again every tick.
+   */
+  pulls(opts?: { cwd?: string }): Promise<PullRequest[]>;
   /**
    * `git pull`, answering with git's own summary — "Already up to date.", the fast-forward range —
    * because those are different answers and a caller showing neither is a caller nobody trusts.
    * `cwd` picks the repository, as everywhere; absent means the conversation's own.
+   *
+   * `rebase` replays this branch's commits on top of what arrived instead of merging them. It is
+   * the answer to a diverged branch and it rewrites local commits, so ask before you set it — the
+   * caller this exists for is a panel that has just said "diverged" and offered the choice.
    */
-  pull(opts?: { cwd?: string }): Promise<string>;
+  pull(opts?: { cwd?: string; rebase?: boolean }): Promise<string>;
   addWorktree(
     path: string,
     branch: string,
@@ -1076,6 +1259,60 @@ export interface GitApi {
    * exactly that one.
    */
   removeWorktree(path: string, opts?: { force?: boolean; cwd?: string }): Promise<void>;
+  /**
+   * Move a worktree to `dest` — `git worktree move`, and everything that has to follow it.
+   *
+   * A worktree's path is an identity here, not a coordinate: it is the key of the project facts
+   * every list draws, of the conversations living in it, of the project vars holding a pin and a
+   * fold state, and of the working directory each vendor CLI was started in. This call moves all
+   * of them, which is why it is a call rather than a `git worktree move` you could have run
+   * yourself — the git part is the part that was never hard.
+   *
+   * `dest` is the full path it lands at. Its parent is created; the leaf must not exist.
+   *
+   * Refused while a turn is running anywhere in the tree, because a CLI holds its working
+   * directory from the moment it is spawned and would otherwise write the file it is editing into
+   * the place the tree used to be. Interrupt it and ask again.
+   *
+   * `cwd` names the repository, as everywhere.
+   */
+  moveWorktree(path: string, dest: string, opts?: { cwd?: string }): Promise<void>;
+  /**
+   * Clone `url` into `path`, resolving to the path once it is there.
+   *
+   * The one call here with no `cwd`: everything else asks a repository a question, and this one
+   * arrives before there is a repository to ask. `path` is absolute and its parent need not
+   * exist — cloning into a location you have just invented is the ordinary case.
+   *
+   * **It reports progress while it runs**, on the bus as {@link CLONE_EVENT}, so a caller that
+   * wants to draw a clone rather than block on one subscribes before awaiting this. Keyed by
+   * `path`, because a workspace may be cloning two things at once.
+   *
+   * Needs `vcs_write` in the manifest, like every other call here that changes a disk.
+   */
+  clone(url: string, path: string): Promise<string>;
+}
+
+/**
+ * What {@link GitApi.clone} says about itself while it runs, on {@link EventsApi.on}.
+ *
+ * `phase` is git's own word for what it is doing — `Receiving objects`, `Resolving deltas` — and
+ * `percent` is absent for the phases that have no total, which draw as a spinner rather than as a
+ * bar. `done` arrives exactly once per clone, on success and on failure alike, because a panel
+ * drawing itself from these has no other way to learn it may stop.
+ */
+export const CLONE_EVENT = "neosh.git.clone";
+
+/** One {@link CLONE_EVENT} payload. */
+export interface CloneProgress {
+  /** Which clone this is about. The key, since two may be running. */
+  path: string;
+  url: string;
+  phase: string;
+  percent?: number | null;
+  done?: boolean;
+  /** Present, with git's own last word in it, only when the clone failed. */
+  error?: string;
 }
 
 /**
@@ -1097,6 +1334,32 @@ export interface GenApi {
    * do not each reimplement that. Rejects if there is no JSON in the response at all.
    */
   json<T = unknown>(prompt: string, opts?: { system?: string; selection?: ModelSelection }): Promise<T>;
+  /**
+   * One value, asked for as JSON and accepted however it comes back.
+   *
+   * The shape almost every generating plugin actually wants: a branch name, a thread title, a PR
+   * subject — one string, asked for as `{"branch": …}` because that is how you pin a model down,
+   * and answered as a bare `fix/composer-paste` often enough to matter. Both are the same answer,
+   * and {@link GenApi.json} rejects the second one — which is a correct name thrown away, with
+   * nothing on screen to say so.
+   *
+   * So the key is passed down and a bare reply is read as its value. Everything
+   * {@link GenApi.json} tolerates is tolerated first and unchanged; this is only what happens when
+   * there is no JSON at all. Rejects on an empty answer, or on prose it will not guess at.
+   *
+   * For one value only. A commit message is a subject and a body, and there is no answering the
+   * question of which one a lone paragraph is — that stays {@link GenApi.json}.
+   *
+   * And only for a value you would know was wrong on sight. A branch name is that, and a wrong one
+   * is one rename away; a thread title is any short line, and so is a refusal or a driver's own
+   * error message — where nothing distinguishes an answer from a remark, the envelope is the
+   * evidence, and {@link GenApi.json} is the call.
+   */
+  field(
+    prompt: string,
+    key: string,
+    opts?: { system?: string; selection?: ModelSelection },
+  ): Promise<string>;
 }
 
 /**
@@ -1356,6 +1619,27 @@ export interface VarApi {
   ): Disposable;
 }
 
+/**
+ * The directories somebody works in, and the one thing that can happen to one.
+ *
+ * A project *is* its path everywhere else in this API — `projectScope` keys vars by it, a panel's
+ * list is a list of them, `SessionInfo.cwd` names one. Which is exactly why a path that changes
+ * needs saying out loud rather than inferring: from the outside, a worktree that moved and a
+ * project that was deleted while another was added are the same two facts in the same order.
+ */
+export interface ProjectApi {
+  /**
+   * A project's directory is now somewhere else — a worktree that was relocated.
+   *
+   * The host has already moved everything it owns by the time this arrives: the conversations, the
+   * project vars, the names and branches every list draws. What is left is whatever *you* keyed by
+   * the old path — a list of directories, a cache, a decoration target — and the point of getting
+   * both ends in one event is that you can re-key in place instead of dropping a row and gaining a
+   * stranger.
+   */
+  onMove(cb: (e: { from: string; to: string }) => void): Disposable;
+}
+
 /** Sugar for the two scopes anything with a panel spends its time in. */
 export function projectScope(cwd: string): VarScope {
   return { scope: "project", cwd };
@@ -1612,8 +1896,29 @@ export interface SwarmApi {
    * with the owner's reason when it says no. A node may refuse anything; `NodeCapabilities` on its
    * {@link SwarmNode} says in advance what it is likely to accept, so a menu can grey out a verb
    * rather than offering one that will bounce.
+   *
+   * Answers with the conversation a `new_session` created, and `null` for everything else — which
+   * is what makes starting something over there a place you can then go: pass it to
+   * {@link subscribe}, or to `swarm.open`, without waiting for the next inventory to notice it.
+   */
+  command(node: NodeId, session: string, command: AgentCommand): Promise<string | null>;
+  /**
+   * Which directories on another machine start with `prefix` — `path.complete`, asked over there.
+   *
+   * The same answers in the same shape as the local one: each entry as you would have typed it,
+   * trailing separator and all, so a single field can complete against either machine and the only
+   * thing that changes is which one is asked. Directory names only.
+   *
+   * {@link NodeCapabilities.projects} is what a machine *offers*, and it is the short list of
+   * places it already works in; this is how you reach the directory over there that neither machine
+   * has ever opened. Rejects when the peer is not connected, when it does not accept commands, and
+   * when it is running a neosh too old to have heard of the question — the message says which, and
+   * an empty list is a directory with nothing in it rather than a failure.
+   *
+   * Passing this machine's own node id answers locally, so a picker that walks `nodes()` needs no
+   * special case for the row that is itself.
    */
-  command(node: NodeId, session: string, command: AgentCommand): Promise<void>;
+  browse(node: NodeId, prefix?: string): Promise<string[]>;
   /**
    * Watch a remote conversation: its history now, then everything as it happens, delivered to
    * {@link onStream}.
@@ -1706,8 +2011,15 @@ export interface PathApi {
    *
    * `~` expands against the home directory. A prefix with no `/` completes against the active
    * conversation's directory, which is what someone typing `src` means.
+   *
+   * `denied` is set when the list is empty *because the operating system refused*, rather than
+   * because nothing matched. The two are the same empty array and they are not the same answer:
+   * macOS grants folder access to the **terminal**, so `~/Documents` full of projects reads as
+   * empty until somebody ticks a box, and a field that draws "no directory matches" over that
+   * sends people to go and check a path that was right all along. When it is set it says which
+   * folder, which application and which System Settings pane, and it is meant to be shown.
    */
-  complete(prefix: string): Promise<string[]>;
+  complete(prefix: string): Promise<{ paths: string[]; denied?: string }>;
 }
 
 export interface TimerApi {
@@ -1755,6 +2067,7 @@ interface Registered {
   composerListeners: Array<(e: { text: string }) => void>;
   activityListeners: Array<(e: { session: SessionId; turn: string; activity: Activity }) => void>;
   varListeners: Array<(e: { scope: VarScope; key: string; value: unknown }) => void>;
+  projectMovedListeners: Array<(e: { from: string; to: string }) => void>;
   swarmListeners: Array<() => void>;
   quotaListeners: Array<(snapshot: QuotaSnapshot) => void>;
   swarmStreamListeners: Array<
@@ -1801,6 +2114,7 @@ function reg(plugin: string): Registered {
       composerListeners: [],
       activityListeners: [],
       varListeners: [],
+      projectMovedListeners: [],
       swarmListeners: [],
       quotaListeners: [],
       swarmStreamListeners: [],
@@ -1852,9 +2166,11 @@ function floatConfig(o: FloatOptions = {}): FloatConfig {
     border: o.border ?? "rounded",
     border_hl: o.borderHl ?? null,
     title: o.title ?? null,
+    footer: o.footer ?? null,
     close_on_blur: o.closeOnBlur ?? false,
     focusable: o.focusable ?? true,
     modal: o.modal ?? false,
+    scroll: o.scroll ?? false,
   };
 }
 
@@ -1979,7 +2295,8 @@ function build(
     },
     path: {
       async complete(prefix) {
-        return expect(await c({ call: "path_complete", prefix }), "paths").paths;
+        const answer = expect(await c({ call: "path_complete", prefix }), "paths");
+        return { paths: answer.paths, denied: answer.denied ?? undefined };
       },
     },
     state: {
@@ -2012,6 +2329,11 @@ function build(
         return listener(r.varListeners, cb);
       },
     },
+    project: {
+      onMove(cb) {
+        return listener(r.projectMovedListeners, cb);
+      },
+    },
     ext: {
       async contribute(point, id, item, opts) {
         await c({ call: "ext_contribute", point, id, item, priority: opts?.priority ?? 0 });
@@ -2080,7 +2402,13 @@ function build(
         return expect(await c({ call: "swarm_hosts_of", project }), "names").names;
       },
       async command(node, session, command) {
-        await c({ call: "swarm_command", node, session, command });
+        const done = await c({ call: "swarm_command", node, session, command });
+        // Only `new_session` says anything, so an `ok` of any other shape is an older peer
+        // answering a command that had nothing to report — which is a success, not a mismatch.
+        return done.ok === "swarm_commanded" ? done.session ?? null : null;
+      },
+      async browse(node, prefix) {
+        return expect(await c({ call: "swarm_browse", node, prefix: prefix ?? "" }), "paths").paths;
       },
       async subscribe(node, session) {
         await c({ call: "swarm_subscribe", node, session });
@@ -2272,10 +2600,79 @@ function build(
         return listener(list, cb);
       },
     },
+    pane: {
+      async active(view) {
+        const { tabs, active } = expect(await c({ call: "tab_list", view }), "tabs");
+        // The active tab, or the first — a terminal always has at least one, and a `tabs` that
+        // came back empty is a workspace that has gone wrong in a way this cannot paper over.
+        const tab = tabs.find((t) => t.id === active) ?? tabs[0];
+        if (!tab) throw new Error("this terminal has no tabs");
+        return tab.active_pane;
+      },
+      async split(pane, dir) {
+        const p = expect(await c({ call: "pane_split", pane, dir }), "pane").pane;
+        if (p === null) throw new Error(`pane ${pane} could not be split`);
+        return p;
+      },
+      async close(pane) {
+        await c({ call: "pane_close", pane });
+      },
+      async focus(pane) {
+        await c({ call: "pane_focus", pane });
+      },
+      async focusDir(dir, view) {
+        return expect(await c({ call: "pane_focus_dir", dir, view }), "pane").pane;
+      },
+      async resize(pane, dir, delta) {
+        await c({ call: "pane_resize", pane, dir, delta });
+      },
+      async swap(pane, withPane) {
+        await c({ call: "pane_swap", pane, with: withPane });
+      },
+      async moveToEdge(pane, dir) {
+        await c({ call: "pane_move_edge", pane, dir });
+      },
+      async equalize(view) {
+        await c({ call: "pane_equalize", view });
+      },
+    },
+    tab: {
+      async list(view) {
+        const r = expect(await c({ call: "tab_list", view }), "tabs");
+        return { tabs: r.tabs, active: r.active };
+      },
+      async create(opts) {
+        return expect(
+          await c({
+            call: "tab_new",
+            view: opts?.view,
+            title: opts?.title,
+            activate: opts?.activate ?? true,
+          }),
+          "tab",
+        ).tab;
+      },
+      async close(tab) {
+        await c({ call: "tab_close", tab });
+      },
+      async select(tab) {
+        await c({ call: "tab_select", tab });
+      },
+      async step(delta, view) {
+        await c({ call: "tab_step", delta, view });
+      },
+      async move(tab, to) {
+        await c({ call: "tab_move", tab, to });
+      },
+      async rename(tab, title) {
+        await c({ call: "tab_rename", tab, title });
+      },
+    },
     win: {
       async open(buf, dock, opts) {
         const layout: WindowLayout = {
           kind: "docked",
+          pane: opts?.pane ?? null,
           dock,
           size: opts?.size ?? null,
           gravity: opts?.gravity ?? "start",
@@ -2302,6 +2699,9 @@ function build(
       async scrollTo(win, topLine) {
         await c({ call: "win_scroll_to", win, top_line: topLine });
       },
+      async scroll(win, amount) {
+        await c({ call: "win_scroll", win, amount });
+      },
       async viewport(win) {
         return expect(await c({ call: "win_get_viewport", win }), "viewport").viewport ?? null;
       },
@@ -2620,8 +3020,16 @@ function build(
           cwd: opts?.cwd ?? null,
         });
       },
+      async fetch(opts) {
+        const v = await c({ call: "git_fetch", cwd: opts?.cwd ?? null });
+        return expect(v, "status").status;
+      },
+      async pulls(opts) {
+        const v = await c({ call: "forge_pulls", cwd: opts?.cwd ?? null });
+        return expect(v, "pulls").pulls;
+      },
       async pull(opts) {
-        const v = await c({ call: "git_pull", cwd: opts?.cwd ?? null });
+        const v = await c({ call: "git_pull", cwd: opts?.cwd ?? null, rebase: opts?.rebase ?? false });
         return expect(v, "text").text;
       },
       async removeWorktree(path, opts) {
@@ -2632,6 +3040,13 @@ function build(
           cwd: opts?.cwd ?? null,
         });
       },
+      async moveWorktree(path, dest, opts) {
+        await c({ call: "git_move_worktree", path, dest, cwd: opts?.cwd ?? null });
+      },
+      async clone(url, path) {
+        const v = await c({ call: "git_clone", url, path });
+        return expect(v, "text").text;
+      },
     },
     gen: {
       async complete(prompt, opts) {
@@ -2654,6 +3069,23 @@ function build(
         });
         return expect(v, "json").value as never;
       },
+      async field(prompt, key, opts) {
+        const v = await c({
+          call: "gen_complete",
+          prompt,
+          system: opts?.system ?? null,
+          json: true,
+          field: key,
+          selection: opts?.selection ?? null,
+        });
+        const value = (expect(v, "json").value as Record<string, unknown>)?.[key];
+        // A key that came back as something other than a non-empty string is an answer to a
+        // different question, and the caller is about to name a branch after it.
+        if (typeof value !== "string" || value.trim() === "") {
+          throw new Error(`the model returned no ${key}`);
+        }
+        return value.trim();
+      },
     },
     view: {
       async list() {
@@ -2969,6 +3401,9 @@ async function dispatchEvent(
         for (const cb of r.varListeners)
           cb({ scope: ev.scope, key: ev.key, value: ev.value });
         break;
+      case "project_moved":
+        for (const cb of r.projectMovedListeners) cb({ from: ev.from, to: ev.to });
+        break;
       case "quota":
         for (const cb of [...r.quotaListeners]) cb(ev.snapshot);
         break;