@silo-code/sdk 0.45.0 → 0.47.0

package/src/domain-types.ts

@@ -129,6 +129,50 @@ export interface EditorRecord {
   viewType?: string;
 }
 
+/**
+ * The persisted identity and restore state of one dock panel — a
+ * {@link DockPanelKind} panel that declared `persistence: "recorded"` (RFC
+ * 0041).
+ *
+ * This is what makes a dock panel first-class the way an editor or a terminal
+ * is: it exists as a workspace-scoped record ({@link Workspace.panels}), not
+ * merely as opaque geometry inside the saved dock layout. The record list is
+ * the source of truth for *which* recorded panels a workspace has; the dock
+ * layout keeps only *where* they sit, and the two are reconciled on restore
+ * exactly as editors and terminals already are.
+ *
+ * An editor and a terminal are not `DockPanelRecord`s in this release —
+ * {@link EditorRecord} / {@link TerminalRecord} keep their own shape. Folding
+ * the three lists into one is deliberately left for a later phase.
+ *
+ * @category Core Types
+ * @public
+ */
+export interface DockPanelRecord {
+  /**
+   * Stable id, unique within the workspace. This is **not** the transient
+   * dock-view panel id — it survives the panel being closed and reopened from
+   * its record across a restart.
+   */
+  id: string;
+  /** The {@link DockPanelKind} id this panel is an instance of. */
+  kindId: string;
+  /** The id of the workspace this panel belongs to. */
+  workspaceId: string;
+  /**
+   * The panel kind's own restore state — a serializable bag whose shape is the
+   * panel's contract, not the host's (the host never inspects or validates it).
+   * The Agent Chat panel keeps `{ sessionId, profileId, cwd }` here (RFC
+   * 0042); a panel with nothing to restore leaves it `{}`. Handed back to the
+   * kind's component as its params when the panel is recreated on restore.
+   */
+  state: Readonly<Record<string, unknown>>;
+  /** ISO-8601 timestamp of when the panel was first opened. */
+  createdAt: string;
+  /** ISO-8601 timestamp of when the panel was last the active tab. */
+  lastActiveAt: string;
+}
+
 /**
  * The four fixed slots a side dock used to divide into.
  *
@@ -176,6 +220,15 @@ export interface Workspace {
   terminals: readonly TerminalRecord[];
   /** Editor tabs — text editors and diffs alike (a diff is a record with `mode: "diff"`). */
   editors: readonly EditorRecord[];
+  /**
+   * Recorded dock panels — every panel of a {@link DockPanelKind} that declared
+   * `persistence: "recorded"` (RFC 0041). Editors and terminals are **not** in
+   * this list; they keep their own {@link Workspace.editors} /
+   * {@link Workspace.terminals} lists. A transient panel (a picker, a preview)
+   * whose kind did not opt in is absent here — it lives only in the saved dock
+   * layout.
+   */
+  panels: readonly DockPanelRecord[];
 }
 
 /**

package/src/index.ts

@@ -53,6 +53,7 @@ export type {
   Workspace,
   EditorMode,
   EditorRecord,
+  DockPanelRecord,
   SidePanelSlot,
 } from "./domain-types";
 
@@ -106,6 +107,7 @@ export type {
 export type {
   AgentsService,
   AgentInfo,
+  AgentSessionKind,
   AgentActivity,
   AgentIcon,
   AgentIconMode,
@@ -115,6 +117,26 @@ export type {
   LaunchAgentProfileOptions,
   LaunchAgentProfileResult,
   PromptRefusal,
+  AgentSessionsService,
+  AgentSessionHandle,
+  AgentSessionConnectOptions,
+  AgentSessionRestore,
+  ChatResumeState,
+  AgentPromptBlock,
+  AgentPromptResult,
+  AgentStopReason,
+  AgentSessionUpdate,
+  AgentContentBlock,
+  AgentToolCall,
+  AgentToolCallContent,
+  AgentToolCallLocation,
+  AgentPlanEntry,
+  AgentSessionConfigOption,
+  AgentSessionConfigChoice,
+  AgentPermissionRequest,
+  AgentPermissionOption,
+  AgentCommand,
+  AgentPromptCapabilities,
 } from "./agents-service";
 export type {
   TerminalService,

package/src/permissions.ts

@@ -21,6 +21,17 @@
  *   including cross-origin content. Declare it because this reaches into
  *   arbitrary embedded pages, not because it touches the filesystem/network
  *   directly.
+ * - `agents` — use {@link AgentSessionsService} (`ctx.agents.sessions`) to
+ *   start a **Chat session**: the host spawns the process named by a
+ *   user-authored Chat Agent Profile and speaks the Agent Client Protocol to
+ *   it. {@link AgentSessionsService.connect | connect()} throws without this,
+ *   the way {@link FileService} throws {@link PathDeniedError} without
+ *   `fs:read`. Distinct from `process`: the child is spawned by the host from a
+ *   profile the user wrote, not by the extension through
+ *   {@link ExtensionContext.process}. Trusted (built-in) extensions are exempt,
+ *   the same way they're exempt from declaring `fs:*`/`process` — a narrower
+ *   grant than either, since it only launches a profile the user already
+ *   authored.
  *
  * @category Extension Contract
  * @public
@@ -30,7 +41,8 @@ export type Permission =
   | "fs:write"
   | "process"
   | "network"
-  | "webview";
+  | "webview"
+  | "agents";
 
 /**
  * Thrown by {@link FileService} and {@link ProcessService} when an extension

package/src/toolbar-items.ts

@@ -6,17 +6,26 @@ import type { MenuEntry } from "./ui-service";
  * Built-in surfaces that accept {@link ToolbarItemContribution}s. One surface
  * per registration.
  *
- * `"editor"` and `"terminal"` are CenterDock breadcrumb toolbars; `"navigator"`
- * is the header naming the Navigator's active view — the bar between its view
- * list and the view body — where contributions become that view's action
- * buttons. A navigator item's `when` receives the active
+ * `"editor"` is the editor breadcrumb toolbar (beside the Text | Preview view
+ * switcher). `"navigator"` is the header naming the Navigator's active view —
+ * the bar between its view list and the view body — where contributions become
+ * that view's action buttons; a navigator item's `when` receives the active
  * {@link NavigatorView | view}'s id, so an action can be scoped to one view or
  * left unscoped to follow the user across all of them.
  *
+ * `"panel"` is the host-drawn strip above any {@link DockPanelKind} that
+ * declares `toolbar` (RFC 0039) — including the built-in **terminal**. Its
+ * target carries the panel instance id, its `kindId`, its `workspaceId`, and
+ * the panel's own `params`, so an item meant for one kind of panel scopes
+ * itself with
+ * `when: (_keys, t) => t.kindId === "terminal"` and reads instance data off
+ * `t.params` (e.g. `t.params.terminalId`). Without a `kindId` guard a
+ * `"panel"` item shows on every panel that has a strip.
+ *
  * @category Registration
  * @public
  */
-export type ToolbarSurface = "editor" | "terminal" | "navigator";
+export type ToolbarSurface = "editor" | "navigator" | "panel";
 
 /**
  * The typed target each {@link ToolbarSurface} passes to an invoked command
@@ -27,8 +36,21 @@ export type ToolbarSurface = "editor" | "terminal" | "navigator";
  */
 export interface ToolbarItemContext {
   editor: { editorId: string };
-  terminal: { terminalId: string };
   navigator: { viewId: string };
+  /**
+   * `panelId` and `kindId` identify the panel; `workspaceId` is the workspace
+   * whose dock the panel lives in (each workspace has its own dock, and the
+   * host knows which at the time it draws the strip); `params` is the panel's
+   * own serialized parameters (`DockPanelProps["params"]`) — read-only, so an
+   * item can key on instance data (e.g. the terminal's `params.terminalId`) or
+   * act on the owning workspace without a lookup the SDK does not offer.
+   */
+  panel: {
+    panelId: string;
+    kindId: string;
+    workspaceId: string;
+    params: Readonly<Record<string, unknown>>;
+  };
 }
 
 /**
@@ -175,8 +197,9 @@ export interface ToolbarSpacerContribution<
 }
 
 /**
- * Adds a control or chrome element to the trailing cluster of a built-in
- * editor or terminal toolbar. Register via
+ * Adds a control or chrome element to the trailing cluster of a host-drawn
+ * toolbar — the editor breadcrumb, the Navigator header, or a dock panel's
+ * strip (the terminal included; see {@link ToolbarSurface}). Register via
  * {@link ExtensionContext.registerToolbarItem}.
  *
  * Interactive items set exactly one of

package/src/types.ts

@@ -111,6 +111,52 @@ export interface DockPanelApi {
    * state (e.g. the open URL in a web-viewer panel) consistent with the UI.
    */
   updateParameters(params: object): void;
+  /**
+   * Declare — or, with `null`, withdraw — the **Agent Session** this panel is
+   * showing (an `AgentInfo.id` — the `id` on the handle
+   * `ctx.agents.sessions.connect()` returned).
+   *
+   * This is the only thing the host lacks about a Chat panel, and declaring it
+   * is what makes the panel an ordinary *subject* of agent chrome rather than
+   * an author of it. Once declared, the host routes this panel's tab through
+   * the same path a terminal tab takes: an {@link AgentsService.bindActivity} /
+   * {@link AgentsService.bindIcon} binder's `provide(agentSessionId)` reaches
+   * this tab, {@link AgentsService.getActive} reports the session while the tab
+   * is the active one (so a finish the user watched raises no badge), and
+   * {@link AgentsService.close} closes this panel. None of that requires the
+   * panel to know a badge exists.
+   *
+   * Call it once the session is connected, and again with `null` on a teardown
+   * that outlives the panel (switching to a different agent). The host
+   * withdraws it automatically when the panel unmounts.
+   */
+  setAgentSession(agentSessionId: string | null): void;
+  /**
+   * Publish the path this panel is showing, for the host-drawn breadcrumb
+   * strip — or, with `null`, show no path crumbs.
+   *
+   * Only meaningful for a {@link DockPanelKind} that declares
+   * `toolbar: { breadcrumb: true }`; the host draws the strip and this fills in
+   * its crumbs. `null` leaves a strip that carries only contributed
+   * `registerToolbarItem({ surface: "panel" })` items — which is also how a
+   * panel honours a "hide breadcrumbs" setting of its own.
+   *
+   * This is the shape of {@link DockPanelApi.setAgentSession}: the panel states
+   * a fact about itself and the host routes on it. The path is *not* part of
+   * the panel's persisted identity, so it goes here rather than through
+   * {@link DockPanelApi.updateParameters}. The host withdraws it automatically
+   * when the panel unmounts.
+   */
+  setBreadcrumb(
+    crumb: {
+      /** Absolute path shown as workspace-relative crumbs. */
+      filePath: string;
+      /** Workspace folder the path is relativised against, when it is inside one. */
+      workspaceFolder?: string;
+      /** Glyph on the trailing crumb. Defaults to `"file"`. */
+      leafIcon?: "file" | "folder";
+    } | null,
+  ): void;
 }
 
 /**
@@ -127,6 +173,42 @@ export interface DockPanelProps<T extends object = Record<string, unknown>> {
   api: DockPanelApi;
   /** Serializable parameters forwarded to the panel at open time. */
   params: T;
+  /**
+   * The workspace this panel lives in.
+   *
+   * **Not** the same as "the active workspace": every open workspace keeps its
+   * dock mounted, so a background panel can be doing work while the user is
+   * somewhere else. Anything a panel reports about itself — an Agent Session it
+   * connects (`ctx.agents.sessions.connect({ workspaceId })`), a file it opens —
+   * belongs to *this* workspace, and reading `ctx.workspaces` for it instead
+   * files the result wherever the user happened to be standing. Caught live
+   * (2026-09-10): a Chat session moved workspaces mid-session because its
+   * `connect()` defaulted to the active one.
+   */
+  workspaceId: string;
+  /**
+   * Whether this panel's pixels are actually on screen right now — its tab is
+   * the selected one in its group **and** its workspace is the one the user is
+   * looking at. The host resolves both halves; a panel must not reconstruct
+   * this from {@link DockPanelApi.isVisible} plus
+   * {@link ExtensionContext.workspaces} itself.
+   *
+   * Distinct from the two api members it is easy to confuse it with.
+   * {@link DockPanelApi.isVisible} covers only the tab half, so a panel in a
+   * background workspace still reports `isVisible: true`;
+   * {@link DockPanelApi.isActive} is about focus — the single panel in the
+   * whole dock that has it.
+   *
+   * A panel is **never unmounted** for going off screen, which is what makes
+   * this prop load-bearing rather than a convenience. A deselected tab has its
+   * DOM detached and later re-attached — discarding scroll offsets and
+   * anything else the browser keeps on a layout box — while its React state
+   * and refs survive untouched, and a background workspace's dock stays in the
+   * tree as it was. So whatever a panel measures from or restores into the DOM
+   * belongs on a transition of this flag, never on mount: mount happens once,
+   * when the tab is created, and never again.
+   */
+  onScreen: boolean;
 }
 
 /**
@@ -512,6 +594,13 @@ export interface NavigatorViewProps {
    * the view is off screen.
    */
   active: boolean;
+  /**
+   * The {@link SidePanel.id} of the side panel hosting the Navigator. Pass it
+   * to {@link LayoutService.openPanelSheet} so a sheet the view opens anchors
+   * to the column the Navigator is actually docked in, rather than assuming a
+   * fixed side.
+   */
+  panelId: string;
 }
 
 /**
@@ -541,7 +630,9 @@ export interface NavigatorViewProps {
  * ctx.registerNavigatorView({
  *   id: "my-ext.agents",
  *   title: "Agents",
- *   component: ({ active }) => <AgentList paused={!active} />,
+ *   component: ({ active, panelId }) => (
+ *     <AgentList paused={!active} panelId={panelId} />
+ *   ),
  * });
  * ```
  *
@@ -579,6 +670,72 @@ export interface DockPanelKind<T extends object = Record<string, unknown>> {
   id: string;
   /** The React component that renders this panel; receives {@link DockPanelProps}. */
   component: React.ComponentType<DockPanelProps<T>>;
+  /**
+   * Host-drawn chrome above this panel's component (RFC 0039). Omit for a bare
+   * frame — the default, and correct for a panel that fills its own space.
+   *
+   * With it set, the dock frame draws the same strip an editor gets: the
+   * breadcrumb path (fed by {@link DockPanelApi.setBreadcrumb}) plus a
+   * contribution point, so any extension can
+   * `registerToolbarItem({ surface: "panel", when: (_k, t) => t.kindId === "…" })`
+   * and its button lands here. A first-party panel's own controls arrive the
+   * same way — there is no `children` slot past the contribution point. The
+   * built-in terminal declares this, so its toolbar contributions are ordinary
+   * `"panel"` items.
+   *
+   * `toolbar: {}` — declared but empty — still reserves the strip, for a panel
+   * that wants only contributed items.
+   */
+  toolbar?: {
+    /**
+     * Draw path crumbs in the strip, filled in by
+     * {@link DockPanelApi.setBreadcrumb}. Without it the strip carries only
+     * contributed items.
+     */
+    breadcrumb?: boolean;
+  };
+  /**
+   * Declares that this panel kind renders a **Chat session** for an Agent
+   * Profile (RFC 0038), so Silo can open it on the user's behalf.
+   *
+   * A Chat-armed Agent Profile has no terminal to launch — it needs a
+   * transcript UI, and Silo does not own one. With this set, picking such a
+   * profile from the center dock's **+** menu (or running its
+   * `core.newAgent.<id>` command) opens this kind with
+   * `params.profileId` set to that profile's id; your component passes it to
+   * {@link AgentSessionsService.connect}. Terminal-armed profiles are
+   * unaffected and still launch a terminal.
+   *
+   * This is how a third-party Chat panel becomes a first-class way to start an
+   * agent rather than something the user has to reach by a different route: it
+   * is a declaration, not a privilege, and the bundled panel claims it exactly
+   * the same way. With more than one such kind registered, the first
+   * registered wins — disable the one you don't want on Settings → Extensions.
+   *
+   * Requires `params.profileId` to be honoured; a kind that ignores it will be
+   * handed profiles it does not render.
+   */
+  chatProfileHost?: boolean;
+  /**
+   * Opt this kind's panels into being **recorded** (RFC 0041). With
+   * `persistence: "recorded"`, every open panel of this kind gets a
+   * {@link DockPanelRecord} in {@link Workspace.panels}: it is enumerable,
+   * workspace-scoped, and — this is the point — **reopened from its record on
+   * restart**, the same way an editor or a terminal tab is, rather than
+   * surviving only as opaque geometry in the saved dock layout.
+   *
+   * On restore the host recreates the panel and hands
+   * {@link DockPanelRecord.state} back as the component's params, so a panel
+   * that needs to restore itself (a Chat transcript restoring its session —
+   * RFC 0042) writes that state through {@link DockPanelApi.updateParameters}
+   * and reads it back from params on the next launch.
+   *
+   * Omit for a **transient** panel — a picker, a preview, anything that should
+   * not come back on its own. A transient panel still persists its position in
+   * the dock layout for the current session; it just has no record and is not
+   * recreated after a restart.
+   */
+  persistence?: "recorded";
   /**
    * When set, this kind appears as an entry in the center dock's **+** add
    * menu (the per-group header button). Omit to keep the kind internal.
@@ -724,19 +881,20 @@ export interface ExtensionContext {
   ): Disposable;
   /**
    * Register a {@link ToolbarItemContribution} (icon-only, text-only,
-   * icon+text, or dropdown) in the trailing cluster of an editor or terminal
-   * toolbar. Independent of {@link ExtensionContext.registerContextMenuItem}
-   * — register either, both, or neither. Hosts only show items while that
-   * surface's breadcrumbs setting is on. See
-   * {@link ExtensionContext.invalidateToolbarItems}.
+   * icon+text, or dropdown) in the trailing cluster of a host-drawn toolbar —
+   * the editor breadcrumb, the Navigator header, or a dock panel's strip (the
+   * terminal included). Independent of
+   * {@link ExtensionContext.registerContextMenuItem} — register either, both,
+   * or neither. Hosts only show items while that surface's breadcrumbs setting
+   * is on. See {@link ExtensionContext.invalidateToolbarItems}.
    */
   registerToolbarItem<S extends ToolbarSurface>(
     item: ToolbarItemContribution<S>,
   ): Disposable;
   /**
    * Signal that toolbar-item `when` / `checked` data changed. Causes every
-   * toolbar surface — editor, terminal, and the Navigator header — to re-query
-   * contributions and re-render.
+   * toolbar surface — the editor breadcrumb, the Navigator header, and every
+   * dock panel strip — to re-query contributions and re-render.
    */
   invalidateToolbarItems(): void;
   /** Register a {@link Keybinding} (bind a shortcut to a command). */