@neosh/api 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neosh/api",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "The neosh plugin API. Types are generated from the Rust side and drift-checked in CI.",
   "license": "MIT",
   "type": "module",

package/src/generated/ApiCall.ts

@@ -5,6 +5,7 @@ import type { Capability } from "./Capability";
 import type { CursorMotion } from "./CursorMotion";
 import type { CursorShape } from "./CursorShape";
 import type { DiffTarget } from "./DiffTarget";
+import type { Direction } from "./Direction";
 import type { DriverKind } from "./DriverKind";
 import type { ExtmarkId } from "./ExtmarkId";
 import type { ExtmarkOpts } from "./ExtmarkOpts";
@@ -25,6 +26,7 @@ import type { NodeId } from "./NodeId";
 import type { NoticeKind } from "./NoticeKind";
 import type { OptionSpec } from "./OptionSpec";
 import type { OptionValue } from "./OptionValue";
+import type { PaneId } from "./PaneId";
 import type { PermissionMode } from "./PermissionMode";
 import type { ProjectKey } from "./ProjectKey";
 import type { ProviderEvent } from "./ProviderEvent";
@@ -36,6 +38,7 @@ import type { StatusSegment } from "./StatusSegment";
 import type { StreamId } from "./StreamId";
 import type { SurfaceCell } from "./SurfaceCell";
 import type { SurfaceId } from "./SurfaceId";
+import type { TabId } from "./TabId";
 import type { TextEdit } from "./TextEdit";
 import type { ToolDef } from "./ToolDef";
 import type { UsageResolution } from "./UsageResolution";
@@ -55,6 +58,7 @@ export type ApiCall =
      */
     kind?: string | null;
   }
+  | { "call": "buf_delete"; buf: BufferId }
   | { "call": "buf_line_count"; buf: BufferId }
   | {
     "call": "buf_get_lines";
@@ -110,6 +114,38 @@ export type ApiCall =
   | { "call": "win_get_viewport"; win: WindowId }
   | { "call": "win_scroll_to"; win: WindowId; top_line: number | null }
   | { "call": "win_list" }
+  | {
+    "call": "pane_split";
+    pane: PaneId;
+    /**
+     * Which side of `pane` the new one takes. `Right` and `Down` put it after `pane` in the
+     * split; `Left` and `Up` put it before.
+     */
+    dir: Direction;
+  }
+  | { "call": "pane_close"; pane: PaneId }
+  | { "call": "pane_focus"; pane: PaneId }
+  | { "call": "pane_focus_dir"; view?: ViewId | null; dir: Direction }
+  | { "call": "pane_resize"; pane: PaneId; dir: Direction; delta: number }
+  | { "call": "pane_swap"; pane: PaneId; with: PaneId }
+  | { "call": "pane_move_edge"; pane: PaneId; dir: Direction }
+  | { "call": "pane_equalize"; view?: ViewId | null }
+  | {
+    "call": "tab_new";
+    view?: ViewId | null;
+    title?: string | null;
+    /**
+     * Whether to go to it. A tab opened by a key is; a tab opened by an orchestrator putting
+     * work somewhere is not, for the same reason `SessionNew { activate: false }` exists.
+     */
+    activate: boolean;
+  }
+  | { "call": "tab_close"; tab: TabId }
+  | { "call": "tab_select"; tab: TabId }
+  | { "call": "tab_step"; view?: ViewId | null; delta: number }
+  | { "call": "tab_move"; tab: TabId; to: number }
+  | { "call": "tab_rename"; tab: TabId; title: string | null }
+  | { "call": "tab_list"; view?: ViewId | null }
   | {
     "call": "win_motion";
     win: WindowId;
@@ -370,6 +406,7 @@ export type ApiCall =
   | { "call": "swarm_reconnect"; node: NodeId }
   | { "call": "swarm_disconnect"; node: NodeId }
   | { "call": "swarm_strangers" }
+  | { "call": "swarm_browse"; node: NodeId; prefix: string }
   | { "call": "quota_list" }
   | { "call": "quota_refresh"; instance?: InstanceId | null }
   | { "call": "quota_report"; snapshot: QuotaSnapshot }

package/src/generated/ApiOk.ts

@@ -20,6 +20,7 @@ import type { ModelSelection } from "./ModelSelection";
 import type { NamespaceId } from "./NamespaceId";
 import type { NodeInfo } from "./NodeInfo";
 import type { OptionEntry } from "./OptionEntry";
+import type { PaneId } from "./PaneId";
 import type { PermissionDecision } from "./PermissionDecision";
 import type { PermissionMode } from "./PermissionMode";
 import type { PluginInfo } from "./PluginInfo";
@@ -34,6 +35,8 @@ import type { SurfaceId } from "./SurfaceId";
 import type { SwarmAgent } from "./SwarmAgent";
 import type { SwarmNode } from "./SwarmNode";
 import type { SwarmStranger } from "./SwarmStranger";
+import type { TabId } from "./TabId";
+import type { TabInfo } from "./TabInfo";
 import type { ToolDef } from "./ToolDef";
 import type { UpdateOutcome } from "./UpdateOutcome";
 import type { UpdateStatus } from "./UpdateStatus";
@@ -56,6 +59,9 @@ export type ApiOk =
   | { "ok": "views"; views: Array<ViewInfo> }
   | { "ok": "ns"; ns: NamespaceId }
   | { "ok": "mark"; id: ExtmarkId }
+  | { "ok": "pane"; pane: PaneId | null }
+  | { "ok": "tab"; tab: TabId }
+  | { "ok": "tabs"; tabs: Array<TabInfo>; active: TabId }
   | { "ok": "surface"; surface: SurfaceId }
   | { "ok": "lines"; lines: Array<string> }
   | { "ok": "count"; n: number }
@@ -76,7 +82,7 @@ export type ApiOk =
   | { "ok": "focused_win"; win: WindowId | null }
   | { "ok": "option"; entry: OptionEntry | null }
   | { "ok": "options"; options: Array<OptionEntry> }
-  | { "ok": "paths"; paths: Array<string> }
+  | { "ok": "paths"; paths: Array<string>; denied?: string | null }
   | { "ok": "viewport"; viewport: Viewport | null }
   | { "ok": "sessions"; sessions: Array<SessionInfo> }
   | { "ok": "credentials"; credentials: Array<CredentialInfo> }
@@ -107,6 +113,7 @@ export type ApiOk =
   | { "ok": "swarm_nodes"; nodes: Array<SwarmNode> }
   | { "ok": "swarm_agents"; agents: Array<SwarmAgent> }
   | { "ok": "swarm_strangers"; strangers: Array<SwarmStranger> }
+  | { "ok": "swarm_commanded"; session?: SessionId | null }
   | { "ok": "quotas"; quotas: Array<QuotaSnapshot> }
   | { "ok": "quota_history"; samples: Array<QuotaSample> }
   | { "ok": "usage_history"; history: UsageHistory }

package/src/generated/AscpMessage.ts

@@ -70,4 +70,6 @@ export type AscpMessage =
     session?: SessionId | null;
   }
   | { "type": "refused"; id: string; refusal: Refusal }
+  | { "type": "browse"; id: string; prefix: string }
+  | { "type": "browsed"; id: string; paths: Array<string> }
   | { "type": "goodbye"; message?: string | null };

package/src/generated/AuthRef.ts

@@ -9,6 +9,11 @@
 export type AuthRef =
   | { "kind": "env"; var: string }
   | { "kind": "command"; argv: Array<string> }
-  | { "kind": "cli"; program: string; login?: string | null }
+  | {
+    "kind": "cli";
+    program: string;
+    login?: string | null;
+    retired?: string | null;
+  }
   | { "kind": "inherited" }
   | { "kind": "none" };

package/src/generated/CredentialSource.ts

@@ -9,6 +9,7 @@
 export type CredentialSource =
   | { "kind": "plan"; via: string }
   | { "kind": "plan_missing"; program: string; hint?: string | null }
+  | { "kind": "plan_retired"; program: string; note: string }
   | { "kind": "env"; var: string }
   | { "kind": "keychain" }
   | { "kind": "session" }

package/src/generated/Direction.ts

@@ -0,0 +1,6 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Which way to go, for moving between panes and for growing one.
+ */
+export type Direction = "left" | "right" | "up" | "down";

package/src/generated/Dock.ts

@@ -1,9 +1,15 @@
 // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
 
 /**
- * Where a non-floating window sits.
+ * Which edge of a rectangle a non-floating window sits against.
  *
- * Deliberately *not* an arbitrary split tree: agent UIs do not need one, and a split tree creates
- * layout ambiguity that every plugin then has to reason about.
+ * The rectangle is the screen, or — when the window names a [`PaneId`] — one pane of the main
+ * region. That is the only difference between the two, and it is what let splitting arrive without
+ * a second geometry vocabulary: a composer docked `Bottom` in a pane is the same call as a
+ * composer docked `Bottom` on the screen, asked about a smaller rectangle.
+ *
+ * Still not an arbitrary split tree *here*: a window says which edge of which rectangle it wants,
+ * and the tree that makes those rectangles is [`PaneNode`], one level up. Keeping the two apart is
+ * what stops every plugin from having to reason about nesting to place a status line.
  */
-export type Dock = "left" | "right" | "bottom" | "main";
+export type Dock = "left" | "right" | "top" | "bottom" | "main";

package/src/generated/NodeCapabilities.ts

@@ -23,6 +23,17 @@ export type NodeCapabilities = {
    * Whether [`AscpMessage::Subscribe`] will produce anything.
    */
   streams: boolean;
+  /**
+   * Whether [`AscpMessage::Browse`] will be answered.
+   *
+   * Not a permission — it follows `accepts_commands`, for the reason written on `Browse` — but a
+   * *compatibility* flag, and that is why it is here rather than derived. A node built before
+   * `Browse` existed cannot skip a message it has never heard of: the frame parses or the
+   * connection fails, so a new node that sent one on spec would drop an old peer's link every
+   * time somebody opened a directory picker. It defaults to `false`, which is exactly what an
+   * older node's handshake decodes to, so "does not say" and "cannot" are the same answer.
+   */
+  browse: boolean;
   /**
    * The checkouts this node has, for starting something on it.
    */

package/src/generated/PaneChild.ts

@@ -0,0 +1,18 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { PaneNode } from "./PaneNode";
+
+/**
+ * One child of a split, and how much of the axis it gets.
+ */
+export type PaneChild = {
+  node: PaneNode;
+  /**
+   * Share of the parent's axis, relative to its siblings.
+   *
+   * A weight rather than cells, because the terminal is resized by somebody dragging its corner
+   * and a layout stored in cells has to be recomputed — badly, and with rounding that
+   * accumulates — every time that happens. Weights survive a resize by meaning the same thing at
+   * every size. [`WEIGHT`] is what an even split is made of.
+   */
+  weight: number;
+};

package/src/generated/PaneId.ts

@@ -0,0 +1,15 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * One rectangle of the main region, and everything docked inside it.
+ *
+ * A pane is *where* rather than *what*: it owns no buffer and draws nothing. A chat pane is a
+ * transcript window docked `Main` in it plus a composer docked `Bottom` in it; a pane showing
+ * one thing is one window docked `Main`. That is the whole of why splitting did not need a
+ * second dock vocabulary — [`Dock`](crate::Dock) already answers "where inside this rectangle",
+ * and a pane is just a smaller rectangle to ask it about.
+ *
+ * Panes live in a tree per tab ([`PaneNode`](crate::PaneNode)). The tree says how the main
+ * region is divided; the frontend turns it into rectangles, exactly as it does for docks.
+ */
+export type PaneId = number;

package/src/generated/PaneNode.ts

@@ -0,0 +1,17 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { PaneChild } from "./PaneChild";
+import type { PaneId } from "./PaneId";
+import type { SplitDir } from "./SplitDir";
+
+/**
+ * How the main region of one tab is divided.
+ *
+ * A tree rather than a list because a split of a split is the thing people actually build — a chat
+ * on the left, and on the right a chat above a terminal — and a flat list of rectangles cannot say
+ * that without every consumer re-deriving the nesting from coordinates.
+ */
+export type PaneNode = { "kind": "leaf"; pane: PaneId } | {
+  "kind": "split";
+  dir: SplitDir;
+  children: Array<PaneChild>;
+};

package/src/generated/RemoteProject.ts

@@ -14,6 +14,24 @@ export type RemoteProject = {
   cwd: string;
   /**
    * Whether this node has a conversation open in it now.
+   *
+   * Meant something for exactly as long as this list was derived from live conversations: every
+   * project on it had one, so every one of them said `true` and a board drawing the flag drew
+   * one colour. A node now advertises the places it *works in* — which is the list its own panel
+   * shows, and includes the project you cleared out this morning — so the two states exist and
+   * the flag is worth reading.
    */
   active: boolean;
+  /**
+   * How many conversations are open in it there.
+   */
+  sessions: number;
+  /**
+   * How many of those are mid-turn.
+   *
+   * Separate from `sessions` because they are different questions and a board answers both in
+   * one row: `3 conversations · 1 working` is what the sidebar says about a local project, and a
+   * remote one should not have to say less.
+   */
+  running: number;
 };

package/src/generated/SplitDir.ts

@@ -0,0 +1,12 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Which way a split lays its children out.
+ *
+ * Named for what it does to the screen rather than for the key that made it, because those two
+ * disagree in every editor that has ever shipped one: Vim's `:vsplit` produces panes side by side,
+ * and a `Vertical` that means "stacked" to the layout code and "side by side" to the user is a
+ * bug waiting for its first off-by-one. `Row` is a row of panes; `Column` is a column of them.
+ * The *commands* say `right` and `down`, which is the one description nobody can misread.
+ */
+export type SplitDir = "row" | "column";

package/src/generated/TabId.ts

@@ -0,0 +1,10 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * One tab of one view: a title, and a tree of panes.
+ *
+ * Per view rather than per workspace, for the same reason a window is: what the agent produced
+ * is the workspace's, and where you are looking is yours. Two terminals attached to one
+ * workspace have their own tabs over the same conversations.
+ */
+export type TabId = number;

package/src/generated/TabInfo.ts

@@ -0,0 +1,27 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { PaneId } from "./PaneId";
+import type { PaneNode } from "./PaneNode";
+import type { TabId } from "./TabId";
+
+/**
+ * One tab of one view.
+ */
+export type TabInfo = {
+  id: TabId;
+  /**
+   * What the tab bar calls it.
+   *
+   * `None` is "name it after what is in it" — the conversation's title, the terminal's command —
+   * which is what a tab nobody has renamed should say, and it has to stay `None` to keep saying
+   * it: a title resolved once and stored is a tab still called `main` three conversations later.
+   */
+  title?: string | null;
+  root: PaneNode;
+  /**
+   * Which pane in this tab has the keyboard when the tab does.
+   *
+   * Per tab rather than per view, so that leaving a tab and coming back puts you where you were
+   * rather than in whichever pane happens to be first.
+   */
+  active_pane: PaneId;
+};

package/src/generated/UiEvent.ts

@@ -8,6 +8,8 @@ import type { NoticeKind } from "./NoticeKind";
 import type { Rect } from "./Rect";
 import type { SurfaceCell } from "./SurfaceCell";
 import type { SurfaceId } from "./SurfaceId";
+import type { TabId } from "./TabId";
+import type { TabInfo } from "./TabInfo";
 import type { WindowId } from "./WindowId";
 import type { WindowLayout } from "./WindowLayout";
 
@@ -45,7 +47,9 @@ export type UiEvent =
   | { "type": "surface_claimed"; surface: SurfaceId; win: WindowId; rect: Rect }
   | { "type": "surface_cells"; surface: SurfaceId; cells: Array<SurfaceCell> }
   | { "type": "surface_released"; surface: SurfaceId }
+  | { "type": "panes_changed"; tabs: Array<TabInfo>; active: TabId }
   | { "type": "focus_changed"; win: WindowId | null }
+  | { "type": "home_changed"; win: WindowId | null }
   | {
     "type": "message";
     level: MessageLevel;

package/src/generated/WindowLayout.ts

@@ -2,12 +2,23 @@
 import type { Dock } from "./Dock";
 import type { FloatConfig } from "./FloatConfig";
 import type { Gravity } from "./Gravity";
+import type { PaneId } from "./PaneId";
 
 /**
  * Declarative placement for a window. The frontend turns this into a rectangle.
  */
 export type WindowLayout = {
   "kind": "docked";
+  /**
+   * Which pane's rectangle `dock` is measured against, or the screen's when absent.
+   *
+   * An `Option` rather than a pane that happens to mean "the whole screen", because the two
+   * are different things and one of them outlives the other: a pane is closed when its split
+   * is, and a window docked to the screen — the sidebar, the status line — must not go with
+   * it. A window naming a pane that has gone is not drawn at all, which is the honest answer
+   * and the one the frontend can give without inventing a rectangle.
+   */
+  pane?: PaneId | null;
   dock: Dock;
   /**
    * Preferred extent along the dock's variable axis.

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";
@@ -137,7 +141,8 @@ 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,
@@ -385,6 +390,10 @@ 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;
@@ -558,6 +567,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 +655,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>;
   /**
@@ -1612,8 +1705,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<void>;
+  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.
+   */
+  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 +1820,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 {
@@ -1979,7 +2100,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: {
@@ -2080,7 +2202,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 +2400,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",

package/src/ui.ts

@@ -1352,6 +1352,10 @@ export async function pathPicker(
   title: string,
   opts: { initial?: string; width?: number; height?: number } = {},
 ): Promise<string | null> {
+  // The last refusal said out loud, so a folder the OS is hiding is reported once rather than on
+  // every keystroke into it. `source` runs per character typed, and a notice per character is the
+  // same message forty times for one cause.
+  let saidDenied: string | null = null;
   return picker<string>(neosh, [], {
     title,
     width: Math.max(40, opts.width ?? 72),
@@ -1359,8 +1363,19 @@ export async function pathPicker(
     query: opts.initial ?? "",
     placeholder: "no directory matches — <CR> takes what you typed",
     source: async (query) => {
-      const paths = await neosh.path.complete(query).catch(() => []);
-      return paths.map((path) => ({ label: path, value: path }));
+      const answer = await neosh.path
+        .complete(query)
+        .catch(() => ({ paths: [] as string[], denied: undefined }));
+      // An empty list because nobody was allowed to look is not an empty directory, and the
+      // placeholder under this field can only say the second one. Said the way the remote branch
+      // of the same question says it — a notice, because it is feedback for a key you pressed.
+      if (answer.denied && answer.denied !== saidDenied) {
+        saidDenied = answer.denied;
+        neosh.notify(answer.denied, "warn");
+      } else if (!answer.denied) {
+        saidDenied = null;
+      }
+      return answer.paths.map((path) => ({ label: path, value: path }));
     },
     // What you typed, when it is not one of the offered rows. A completion list that refuses a path
     // it did not think of is a list that gets in the way.
@@ -2755,12 +2770,34 @@ export interface ActionItem {
   on?: string;
 }
 
+/** One coloured run of a badge. A part with no `hl` is the panel's own colour — a separator. */
+export interface BadgePart {
+  text: string;
+  hl?: string;
+}
+
+/**
+ * A mark after a row's name: one coloured run, or several.
+ *
+ * Several, because a badge is often several facts rather than one — `↓2` is not the same news as
+ * `~7`, and a strip of git stats drawn in one colour is a string you have to read rather than a
+ * row you can glance at. The single form stays because most badges *are* one fact.
+ *
+ * `short` is the same badge with less in it, for a row too narrow to carry all of it — the fewest
+ * parts still worth drawing, not a truncation. A panel is what knows how many columns there are;
+ * which fact to give up is the badge's to say, exactly as it is for a status segment. Absent means
+ * there is no shorter true version, and the full badge stands.
+ */
+export type BadgeSpec =
+  | { text: string; hl?: string }
+  | { parts: BadgePart[]; short?: BadgePart[] };
+
 /** A mark on a row a panel already draws, keyed by what the row is about. */
 export interface DecorationItem {
   /** The row it is about, in the panel's own terms: `{ project: cwd }`, `{ task: id }`. */
   target: Record<string, string>;
-  /** A short mark after the name, in `hl`. The name is clipped to make room. */
-  badge?: { text: string; hl?: string };
+  /** A short mark after the name. The name is clipped to make room. */
+  badge?: BadgeSpec;
   /** The row's highlight, when the panel has no opinion of its own. */
   hl?: string;
   /** The right-hand column, on a row that is not busy. */
@@ -2769,11 +2806,43 @@ export interface DecorationItem {
 
 /** Every decoration on one target, merged. */
 export interface Decoration {
-  badge?: { text: string; hl?: string };
+  /** `text` is every part run together — what a caller measuring the badge reads. */
+  badge?: { text: string; hl?: string; parts: BadgePart[]; short: BadgePart[] };
   hl?: string;
   right?: { text: string; hl?: string };
 }
 
+/** A badge in either form, as the run of parts the rest of this file works in. */
+function badgeParts(badge: BadgeSpec | undefined): BadgePart[] {
+  if (!badge || typeof badge !== "object") return [];
+  const many = (badge as { parts?: unknown }).parts;
+  if (Array.isArray(many)) {
+    return many.filter((p): p is BadgePart =>
+      Boolean(p) && typeof p === "object" && typeof (p as BadgePart).text === "string" &&
+      (p as BadgePart).text !== ""
+    );
+  }
+  const one = badge as { text?: unknown; hl?: unknown };
+  if (typeof one.text !== "string" || one.text === "") return [];
+  return [{ text: one.text, hl: typeof one.hl === "string" ? one.hl : undefined }];
+}
+
+/**
+ * A badge's short form, falling back to the whole of it.
+ *
+ * The fallback is what lets several decorations merge without anybody declaring one: a plugin with
+ * nothing to give up keeps all of its parts in both forms, and {@link fitBadge} notices that the
+ * two are the same width and leaves the badge alone.
+ */
+function badgeShort(badge: BadgeSpec | undefined): BadgePart[] {
+  const declared = (badge as { short?: unknown } | undefined)?.short;
+  if (!Array.isArray(declared)) return badgeParts(badge);
+  return declared.filter((p): p is BadgePart =>
+    Boolean(p) && typeof p === "object" && typeof (p as BadgePart).text === "string" &&
+    (p as BadgePart).text !== ""
+  );
+}
+
 /** The key a decoration's `target` files under: `project:/w/x`, `task:17`. */
 export function decorationKey(target: unknown): string | null {
   if (!target || typeof target !== "object") return null;
@@ -2797,11 +2866,16 @@ export function mergeDecorations(
     const key = decorationKey(c.item?.target);
     if (key === null) continue;
     const d = out.get(key) ?? {};
-    const badge = c.item.badge;
-    if (typeof badge?.text === "string" && badge.text !== "") {
-      d.badge = d.badge
-        ? { text: `${d.badge.text} ${badge.text}`, hl: d.badge.hl }
-        : { text: badge.text, hl: badge.hl };
+    const parts = badgeParts(c.item.badge);
+    if (parts.length > 0) {
+      const short = badgeShort(c.item.badge);
+      const merged = d.badge ? [...d.badge.parts, { text: " " }, ...parts] : parts;
+      d.badge = {
+        text: merged.map((p) => p.text).join(""),
+        hl: d.badge?.hl ?? parts[0]?.hl,
+        parts: merged,
+        short: d.badge ? [...d.badge.short, { text: " " }, ...short] : short,
+      };
     }
     if (d.hl === undefined && typeof c.item.hl === "string") d.hl = c.item.hl;
     if (d.right === undefined && typeof c.item.right?.text === "string") {
@@ -2812,9 +2886,41 @@ export function mergeDecorations(
   return out;
 }
 
-/** How many columns a decoration's badge will take, for a row builder to leave free. */
+/**
+ * How many columns a decoration's badge will take, for a row builder to leave free.
+ *
+ * Columns rather than bytes, which is what a row builder is subtracting this from: `●3` is four
+ * bytes and two columns, and a strip of arrows is three bytes each — measured in bytes, a badge
+ * that says `↓2 ↑5 ~7` takes eleven columns off a name to occupy nine.
+ */
 export function badgeWidth(d: Decoration | undefined): number {
-  return d?.badge ? byteLength(` ${d.badge.text}`) : 0;
+  return d?.badge ? width(` ${d.badge.text}`) : 0;
+}
+
+/**
+ * The badge as this row can actually afford it: the whole of it, or its short form.
+ *
+ * **The badge yields before the name does.** A row's name is what the row *is* — a project you
+ * cannot read the name of is not a row you can use — and a badge is news about it. So the full
+ * strip is drawn whenever the name fits beside it, and a name that would be clipped by the badge
+ * gets the short form instead. Only if it still does not fit is the name clipped, which is the
+ * panel's own business and unchanged.
+ *
+ * `room` is every column the name and the badge have between them, `name` the columns the name
+ * wants. A badge whose short form saves nothing is left alone, which is what makes the fallback in
+ * {@link badgeShort} safe: a plugin that declared no short form never has one chosen for it.
+ */
+export function fitBadge(
+  d: Decoration | undefined,
+  room: number,
+  name: number,
+): Decoration | undefined {
+  if (!d?.badge) return d;
+  const full = badgeWidth(d);
+  if (name + full <= room) return d;
+  const short = { ...d.badge, text: d.badge.short.map((p) => p.text).join("") };
+  if (width(` ${short.text}`) >= full) return d;
+  return { ...d, badge: { ...short, parts: d.badge.short } };
 }
 
 /**
@@ -2833,12 +2939,18 @@ export function decorateRow<T>(
   if (!d) return row;
   if (d.badge) {
     const mark = ` ${d.badge.text}`;
-    const from = byteLength(row.text);
+    // Past the space this puts between the name and the badge: it is the panel's colour, not the
+    // badge's, and a span over it would be one colour claiming a column it does not fill.
+    let at = byteLength(row.text) + 1;
     row.text = `${row.text}${mark}`;
     if (row.full !== undefined) row.full = `${row.full}${mark}`;
-    if (d.badge.hl) {
-      row.spans = [...(row.spans ?? []), { from, to: from + byteLength(mark), hl: d.badge.hl }];
+    const spans = [...(row.spans ?? [])];
+    for (const part of d.badge.parts) {
+      const to = at + byteLength(part.text);
+      if (part.hl) spans.push({ from: at, to, hl: part.hl });
+      at = to;
     }
+    if (spans.length > 0) row.spans = spans;
   }
   if (d.hl && row.hl === undefined) row.hl = d.hl;
   if (d.right && !busy) row.right = { text: `${d.right.text} `, hl: d.right.hl };