@silo-code/sdk 0.30.0 → 0.32.0

package/src/icon-button-classes.test.ts

@@ -5,9 +5,19 @@ describe("iconButtonClass", () => {
   it("defaults to silo-icon-button", () => {
     expect(iconButtonClass()).toBe("silo-icon-button");
     expect(iconButtonClass("normal")).toBe("silo-icon-button");
+    expect(iconButtonClass("normal", "normal")).toBe("silo-icon-button");
   });
 
   it("adds the sm modifier", () => {
     expect(iconButtonClass("sm")).toBe("silo-icon-button silo-icon-button-sm");
   });
+
+  it("adds the toolbar variant", () => {
+    expect(iconButtonClass("normal", "toolbar")).toBe(
+      "silo-icon-button silo-icon-button-toolbar",
+    );
+    expect(iconButtonClass("sm", "toolbar")).toBe(
+      "silo-icon-button silo-icon-button-sm silo-icon-button-toolbar",
+    );
+  });
 });

package/src/icon-button-classes.ts

@@ -6,14 +6,27 @@
  */
 export type IconButtonSize = "normal" | "sm";
 
+/**
+ * Visual tone for {@link IconButton}. `"toolbar"` matches the local-web-viewer
+ * bar buttons (toolbar-text icons, hover fill only, no press-scale).
+ *
+ * @internal
+ */
+export type IconButtonVariant = "normal" | "toolbar";
+
 /**
  * Resolve the host `.silo-icon-button*` class string for an IconButton's
- * `size`. Default is the 32px standalone size; `sm` adds the 26px modifier.
+ * `size` + `variant`. Default is the standalone size; `sm` adds the compact
+ * modifier; `toolbar` swaps in the breadcrumb/panel-toolbar tone.
  *
  * @internal
  */
-export function iconButtonClass(size: IconButtonSize = "normal"): string {
-  return size === "sm"
-    ? "silo-icon-button silo-icon-button-sm"
-    : "silo-icon-button";
+export function iconButtonClass(
+  size: IconButtonSize = "normal",
+  variant: IconButtonVariant = "normal",
+): string {
+  const parts = ["silo-icon-button"];
+  if (size === "sm") parts.push("silo-icon-button-sm");
+  if (variant === "toolbar") parts.push("silo-icon-button-toolbar");
+  return parts.join(" ");
 }

package/src/index.ts

@@ -100,6 +100,7 @@ export type {
   ProcessStats,
   ProcessTreeNode,
 } from "./processes-service";
+export type { AgentsService, AgentInfo, AgentActivity } from "./agents-service";
 export type {
   TerminalService,
   CreateTerminalInput,
@@ -109,6 +110,37 @@ export type {
   TerminalTabDecorationProvider,
   OscEvent,
 } from "./terminal-service";
+export type {
+  TabAdornmentColor,
+  TabIconAdornment,
+  TabIndicatorAdornment,
+  TabIndicatorFlash,
+  TabActivityAdornment,
+  TabActivityFlash,
+  TabIconContribution,
+  TabIndicatorContribution,
+  TabActivityContribution,
+  TabIconBinder,
+  TabIndicatorBinder,
+  TabActivityBinder,
+  TabAdornmentMethods,
+} from "./tab-adornment";
+export type { Activity, ActivitySize } from "./activity";
+export { activityFromAgent } from "./activity";
+export { ActivityGlyph } from "./ActivityGlyph";
+export type { PhosphorIconName } from "./phosphor-icon";
+export type {
+  ToolbarSurface,
+  ToolbarItemContext,
+  ToolbarItemFields,
+  ToolbarCommandItemContribution,
+  ToolbarMenuItemContribution,
+  ToolbarChromeFields,
+  ToolbarSeparatorContribution,
+  ToolbarSpacerSize,
+  ToolbarSpacerContribution,
+  ToolbarItemContribution,
+} from "./toolbar-items";
 export type {
   FileService,
   FileMeta,
@@ -225,7 +257,7 @@ export { Tooltip } from "./Tooltip";
 export { Button } from "./Button";
 export type { ButtonVariant, ButtonSize } from "./Button";
 export { IconButton } from "./IconButton";
-export type { IconButtonSize } from "./IconButton";
+export type { IconButtonSize, IconButtonVariant } from "./IconButton";
 export { Input } from "./Input";
 export { Textarea } from "./Textarea";
 export { SearchInput } from "./SearchInput";

package/src/phosphor-icon.ts

@@ -0,0 +1,14 @@
+/**
+ * Export name of an icon from `@phosphor-icons/react` — e.g. `"Flag"`,
+ * `"ArrowClockwise"`, `"PushPin"`. The host resolves the name and paints it:
+ * toolbar chrome uses `weight="bold"`; tab decorations use `weight="regular"`
+ * by default (`filled: true` → `weight="fill"`); both use `size="1em"` so
+ * glyphs track UI zoom.
+ *
+ * Use the PascalCase component name from
+ * [Phosphor](https://phosphoricons.com), not a kebab-case path.
+ *
+ * @category Registration
+ * @public
+ */
+export type PhosphorIconName = string;

package/src/tab-adornment.ts

@@ -0,0 +1,208 @@
+import type { ReactNode } from "react";
+import type { Activity } from "./activity";
+import type { PhosphorIconName } from "./phosphor-icon";
+import type { Disposable } from "./types";
+
+/**
+ * Semantic color for a CenterDock tab trailing {@link TabIndicatorAdornment}
+ * (and optional chip background).
+ *
+ * @category Consumer Services
+ * @public
+ */
+export type TabAdornmentColor = "accent" | "warn" | "ok" | "error" | "muted";
+
+/**
+ * Leading identity adornment on a CenterDock tab — arbitrary React artwork
+ * (e.g. an app logo). Set via {@link EditorService.setIcon} /
+ * {@link TerminalService.setIcon}.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface TabIconAdornment {
+  /** Extension-owned key; stacking + {@link EditorService.clearIcon} target. */
+  id: string;
+  /** Leading glyph / logo rendered before the tab title. */
+  icon: ReactNode;
+}
+
+/**
+ * Trailing status adornment on a CenterDock tab — static Phosphor glyph.
+ * For busy/ready/warn/error chrome use {@link TabActivityAdornment} instead
+ * (ADR 0030).
+ *
+ * Set via {@link EditorService.setIndicator} /
+ * {@link TerminalService.setIndicator}.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface TabIndicatorAdornment {
+  /** Extension-owned key; stacking + clear target. */
+  id: string;
+  /**
+   * Glyph as a {@link PhosphorIconName} (e.g. `"Flag"`). The host resolves
+   * and paints it at 1em in regular weight by default. Set
+   * {@link TabIndicatorAdornment.filled | filled} for Phosphor fill weight;
+   * {@link TabIndicatorAdornment.color | color} tints the glyph; set
+   * {@link TabIndicatorAdornment.chip | chip} for a soft tinted background.
+   */
+  icon: PhosphorIconName;
+  /** Tooltip shown when hovering the indicator. */
+  tooltip?: string;
+  /** Semantic color for the glyph (and chip fill). */
+  color?: TabAdornmentColor;
+  /**
+   * When true, paint a soft tinted chip behind the icon. Default is
+   * glyph-only — no background.
+   */
+  chip?: boolean;
+  /**
+   * When true, paint the glyph with Phosphor `weight="fill"`. Default is
+   * regular weight (outline).
+   */
+  filled?: boolean;
+}
+
+/**
+ * Host-owned {@link Activity} on a CenterDock tab. Extensions pick the kind
+ * (+ optional tooltip); never an icon or color (ADR 0030).
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface TabActivityAdornment {
+  /** Extension-owned key; stacking + clear target. */
+  id: string;
+  activity: Activity;
+  tooltip?: string;
+}
+
+/**
+ * Payload for {@link EditorService.flashIndicator} /
+ * {@link TerminalService.flashIndicator} — timed one-shot; no stable `id`
+ * (auto-cleared after `durationMs`).
+ *
+ * @category Consumer Services
+ * @public
+ */
+export type TabIndicatorFlash = TabIndicatorContribution & {
+  /** How long to show the flash. Defaults to host choice (typically ~800ms). */
+  durationMs?: number;
+};
+
+/**
+ * Payload for {@link EditorService.flashActivity} /
+ * {@link TerminalService.flashActivity}.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export type TabActivityFlash = TabActivityContribution & {
+  durationMs?: number;
+};
+
+/**
+ * Fields contributed by a {@link TabIconBinder.provide} call (the binder’s
+ * own `id` is applied by the host).
+ *
+ * @category Consumer Services
+ * @public
+ */
+export type TabIconContribution = Omit<TabIconAdornment, "id">;
+
+/**
+ * Fields contributed by a {@link TabIndicatorBinder.provide} call.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export type TabIndicatorContribution = Omit<TabIndicatorAdornment, "id">;
+
+/**
+ * Fields contributed by a {@link TabActivityBinder.provide} call.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export type TabActivityContribution = Omit<TabActivityAdornment, "id">;
+
+/**
+ * Keep a leading-icon projection in sync for every editor/terminal tab.
+ * Prefer over repeatedly calling {@link EditorService.setIcon}.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface TabIconBinder {
+  /** Extension-owned key — conventionally `"<extension-id>.tab-icon"`. */
+  id: string;
+  /**
+   * Called synchronously per tab during render. Return `null` to contribute
+   * nothing for this target id (editor id or terminal session id).
+   */
+  provide(targetId: string): TabIconContribution | null;
+}
+
+/**
+ * Keep a trailing-indicator projection in sync for every editor/terminal tab.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface TabIndicatorBinder {
+  /** Extension-owned key — conventionally `"<extension-id>.tab-indicator"`. */
+  id: string;
+  /**
+   * Called synchronously per tab during render. Return `null` to contribute
+   * nothing for this target id.
+   */
+  provide(targetId: string): TabIndicatorContribution | null;
+}
+
+/**
+ * Keep a trailing-activity projection in sync for every editor/terminal tab.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface TabActivityBinder {
+  /** Extension-owned key — conventionally `"<extension-id>.tab-activity"`. */
+  id: string;
+  provide(targetId: string): TabActivityContribution | null;
+}
+
+/**
+ * Shared adorn verbs for CenterDock editor and terminal tabs. Implemented by
+ * {@link EditorService} and {@link TerminalService} (target id is the editor
+ * or terminal session id respectively).
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface TabAdornmentMethods {
+  setIcon(targetId: string, adornment: TabIconAdornment): void;
+  clearIcon(targetId: string, adornmentId: string): void;
+  bindIcon(binder: TabIconBinder): Disposable;
+
+  setIndicator(targetId: string, adornment: TabIndicatorAdornment): void;
+  clearIndicator(targetId: string, adornmentId: string): void;
+  flashIndicator(targetId: string, flash: TabIndicatorFlash): void;
+  bindIndicator(binder: TabIndicatorBinder): Disposable;
+
+  setActivity(targetId: string, adornment: TabActivityAdornment): void;
+  clearActivity(targetId: string, adornmentId: string): void;
+  flashActivity(targetId: string, flash: TabActivityFlash): void;
+  bindActivity(binder: TabActivityBinder): Disposable;
+
+  /** All leading icons for `targetId`, in set/bind order. */
+  getIcons(targetId: string): TabIconAdornment[];
+  /** All trailing indicators for `targetId`, in set/bind/flash order. */
+  getIndicators(targetId: string): TabIndicatorAdornment[];
+  /** All trailing activities for `targetId`, in set/bind/flash order. */
+  getActivities(targetId: string): TabActivityAdornment[];
+  /** Signal that binder data changed — re-query `provide` and re-render. */
+  invalidateTabAdornments(): void;
+  subscribeTabAdornments(listener: () => void): Disposable;
+}

package/src/terminal-service.ts

@@ -1,6 +1,9 @@
-import type React from "react";
 import type { Disposable } from "./types";
 import type { TerminalKind, TerminalRecord } from "./domain-types";
+import type {
+  TabAdornmentMethods,
+  TabIndicatorContribution,
+} from "./tab-adornment";
 
 /**
  * A parsed OSC (Operating System Command) escape sequence emitted by a
@@ -26,32 +29,18 @@ export interface OscEvent {
 export type { TerminalKind, TerminalRecord } from "./domain-types";
 
 /**
- * A decoration that an extension can attach to a terminal tab — a small icon
- * with an optional tooltip and semantic color. Registered via
- * {@link TerminalService.registerTabDecoration}.
+ * @deprecated Prefer {@link TerminalService.setIndicator} /
+ * {@link TerminalService.bindIndicator}. Alias for a trailing indicator
+ * contribution (no `id` — the provider id supplies it).
  *
  * @category Consumer Services
  * @public
  */
-export interface TerminalTabDecoration {
-  /**
-   * Small React node rendered as a decoration badge on the tab (≤16 px).
-   * The extension supplies the shape; the host applies `color` via a CSS
-   * data attribute mapped to design tokens.
-   */
-  icon: React.ReactNode;
-  /** Tooltip shown when hovering the decoration icon. */
-  tooltip?: string;
-  /**
-   * Semantic color applied to the icon element. The host maps this to the
-   * matching `--silo-color-*` design token so themes control the exact shade.
-   */
-  color?: "accent" | "warn" | "ok" | "error" | "muted";
-}
+export type TerminalTabDecoration = TabIndicatorContribution;
 
 /**
- * A decoration provider for terminal tabs. Register via
- * {@link TerminalService.registerTabDecoration}.
+ * @deprecated Prefer {@link TerminalService.bindIndicator}. Terminal-only
+ * trailing-indicator provider kept as a shim over the adornment registry.
  *
  * @category Consumer Services
  * @public
@@ -61,8 +50,7 @@ export interface TerminalTabDecorationProvider {
   id: string;
   /**
    * Called synchronously for each terminal tab during render. Return `null`
-   * to contribute nothing for this terminal. When multiple providers are
-   * registered, the first non-null result wins.
+   * to contribute nothing for this terminal.
    */
   provide(terminalId: string): TerminalTabDecoration | null;
 }
@@ -92,10 +80,13 @@ export interface CreateTerminalInput {
  * deleting the workspace. The tab itself is rendered by the core dock from the
  * workspace's terminal records.
  *
+ * Tab chrome adornments (`setIcon` / `setIndicator` / …) take a **terminal
+ * session id** as the target — see {@link TabAdornmentMethods}.
+ *
  * @category Consumer Services
  * @public
  */
-export interface TerminalService {
+export interface TerminalService extends TabAdornmentMethods {
   /**
    * Open a new terminal in a workspace (defaults to the active one). Returns the
    * created {@link TerminalRecord}; the PTY session spawns lazily when its tab
@@ -156,29 +147,24 @@ export interface TerminalService {
   focus(terminalId: string): void;
 
   /**
-   * Register a decoration provider for terminal tabs. The first registered
-   * provider that returns a non-null decoration for a terminal wins; subsequent
-   * providers are not consulted. Returns a {@link Disposable} that unregisters
-   * the provider.
+   * @deprecated Prefer {@link TerminalService.bindIndicator}. Thin shim that
+   * registers a trailing-indicator binder for terminal tabs only.
    */
   registerTabDecoration(provider: TerminalTabDecorationProvider): Disposable;
 
   /**
-   * Get the current decoration for a terminal tab. Returns the first non-null
-   * result from registered providers, or `null` if none apply.
+   * @deprecated Prefer {@link TerminalService.getIndicators}. Returns the first
+   * trailing indicator for a terminal tab, or `null`.
    */
   getTabDecoration(terminalId: string): TerminalTabDecoration | null;
 
   /**
-   * Signal that tab decoration data has changed. Fires all listeners registered
-   * via {@link TerminalService.subscribeTabDecorations}, causing terminal tabs
-   * to re-query providers and re-render their decoration.
+   * @deprecated Prefer {@link TerminalService.invalidateTabAdornments}.
    */
   invalidateTabDecorations(): void;
 
   /**
-   * Subscribe to tab decoration invalidations. Returns a {@link Disposable}
-   * that cancels the subscription.
+   * @deprecated Prefer {@link TerminalService.subscribeTabAdornments}.
    */
   subscribeTabDecorations(listener: () => void): Disposable;
 

package/src/toolbar-items.ts

@@ -0,0 +1,190 @@
+import type { ContextKeys } from "./context-keys";
+import type { PhosphorIconName } from "./phosphor-icon";
+import type { MenuEntry } from "./ui-service";
+
+/**
+ * Built-in CenterDock surfaces that accept
+ * {@link ToolbarItemContribution}s. One surface per registration.
+ *
+ * @category Registration
+ * @public
+ */
+export type ToolbarSurface = "editor" | "terminal";
+
+/**
+ * The typed target each {@link ToolbarSurface} passes to an invoked command
+ * and to `when` / `checked` / {@link ToolbarMenuItemContribution.menu} builders.
+ *
+ * @category Registration
+ * @public
+ */
+export interface ToolbarItemContext {
+  editor: { editorId: string };
+  terminal: { terminalId: string };
+}
+
+/**
+ * Shared fields for interactive toolbar contributions. Render chrome is driven
+ * by {@link ToolbarItemFields.icon | icon} + {@link ToolbarItemFields.title | title}:
+ *
+ * | icon | title | Control        |
+ * | ---- | ----- | -------------- |
+ * | ✓    | —     | icon-only      |
+ * | —    | ✓     | text-only      |
+ * | ✓    | ✓     | icon + text    |
+ *
+ * Icons are Phosphor export names ({@link PhosphorIconName}); the host
+ * resolves and paints them bold at 1em so they match local-web-viewer and
+ * track UI zoom. Pass a React node is no longer supported — use the name.
+ *
+ * @category Registration
+ * @public
+ */
+export interface ToolbarItemFields<S extends ToolbarSurface = ToolbarSurface> {
+  /** Unique id for this contribution. */
+  id: string;
+  /** Which toolbar to contribute to. */
+  surface: S;
+  /**
+   * Leading glyph as a {@link PhosphorIconName} (e.g. `"Flag"`). Omit for a
+   * text-only control (requires {@link ToolbarItemFields.title | title}).
+   */
+  icon?: PhosphorIconName;
+  /**
+   * Visible label painted in the control. Omit for icon-only. When both
+   * `icon` and `title` are set, the host renders icon + text.
+   */
+  title?: string;
+  /** Hover tooltip (falls back to title / label / command label). */
+  tooltip?: string;
+  /**
+   * Accessible name (falls back to title / the command's label). Always used
+   * for `aria-label`; not painted unless {@link ToolbarItemFields.title | title}
+   * is also set.
+   */
+  label?: string;
+  /** Ordering within the trailing cluster; lower sorts first. */
+  order?: number;
+  /**
+   * Visibility predicate. Returning false hides the item for this target.
+   */
+  when?: (ctx: ContextKeys, target: ToolbarItemContext[S]) => boolean;
+  /**
+   * Toggle-state predicate for command items. When provided, the host renders
+   * the control in a pressed/checked visual state whenever this returns true.
+   * Menu items put checks on individual {@link MenuEntry} rows instead.
+   */
+  checked?: (ctx: ContextKeys, target: ToolbarItemContext[S]) => boolean;
+}
+
+/**
+ * Command-backed toolbar control — click runs {@link ToolbarCommandItemContribution.command}.
+ *
+ * @category Registration
+ * @public
+ */
+export interface ToolbarCommandItemContribution<
+  S extends ToolbarSurface = ToolbarSurface,
+> extends ToolbarItemFields<S> {
+  /** The command to run; receives {@link ToolbarItemContext}[S] as its first arg. */
+  command: string;
+  menu?: undefined;
+  type?: undefined;
+}
+
+/**
+ * Menu-backed toolbar control — click opens a host dropdown via
+ * {@link UiService.showMenu} with entries from
+ * {@link ToolbarMenuItemContribution.menu}.
+ *
+ * @category Registration
+ * @public
+ */
+export interface ToolbarMenuItemContribution<
+  S extends ToolbarSurface = ToolbarSurface,
+> extends ToolbarItemFields<S> {
+  /**
+   * Build the dropdown for this target. May be sync or async. The host
+   * anchors the menu on the toolbar control (`align: "end"`, toggle on).
+   */
+  menu: (target: ToolbarItemContext[S]) => MenuEntry[] | Promise<MenuEntry[]>;
+  command?: undefined;
+  type?: undefined;
+}
+
+/**
+ * Shared placement fields for non-interactive toolbar chrome
+ * ({@link ToolbarSeparatorContribution} / {@link ToolbarSpacerContribution}).
+ *
+ * @category Registration
+ * @public
+ */
+export interface ToolbarChromeFields<
+  S extends ToolbarSurface = ToolbarSurface,
+> {
+  id: string;
+  surface: S;
+  order?: number;
+  when?: (ctx: ContextKeys, target: ToolbarItemContext[S]) => boolean;
+}
+
+/**
+ * A light vertical rule between toolbar controls. Softer than the Text |
+ * Preview pipe — host paints it with a low-opacity mix of toolbar text, not
+ * `--silo-color-toolbar-text-disabled`.
+ *
+ * @category Registration
+ * @public
+ */
+export interface ToolbarSeparatorContribution<
+  S extends ToolbarSurface = ToolbarSurface,
+> extends ToolbarChromeFields<S> {
+  type: "separator";
+}
+
+/**
+ * Gap size for {@link ToolbarSpacerContribution}. Maps to em of the toolbar
+ * font (`sm` 0.25em / `md` 0.5em / `lg` 0.75em).
+ *
+ * @category Registration
+ * @public
+ */
+export type ToolbarSpacerSize = "sm" | "md" | "lg";
+
+/**
+ * An empty gap between toolbar controls (no rule). Use to group without a
+ * hard split; prefer {@link ToolbarSeparatorContribution} when a hairline helps.
+ *
+ * @category Registration
+ * @public
+ */
+export interface ToolbarSpacerContribution<
+  S extends ToolbarSurface = ToolbarSurface,
+> extends ToolbarChromeFields<S> {
+  type: "spacer";
+  /** Default `"md"`. */
+  size?: ToolbarSpacerSize;
+}
+
+/**
+ * Adds a control or chrome element to the trailing cluster of a built-in
+ * editor or terminal toolbar. Register via
+ * {@link ExtensionContext.registerToolbarItem}.
+ *
+ * Interactive items set exactly one of
+ * {@link ToolbarCommandItemContribution.command | command} or
+ * {@link ToolbarMenuItemContribution.menu | menu}. Separators and spacers use
+ * `type: "separator" | "spacer"`.
+ *
+ * Contributions are independent of context-menu items — an extension may
+ * register either, both, or neither. Hosts only render items while that
+ * surface's breadcrumbs setting is on.
+ *
+ * @category Registration
+ * @public
+ */
+export type ToolbarItemContribution<S extends ToolbarSurface = ToolbarSurface> =
+  | ToolbarCommandItemContribution<S>
+  | ToolbarMenuItemContribution<S>
+  | ToolbarSeparatorContribution<S>
+  | ToolbarSpacerContribution<S>;

package/src/types.ts

@@ -32,6 +32,7 @@ import type { EditorService } from "./editor-service";
 import type { LayoutService } from "./layout-service";
 import type { ProcessService } from "./process-service";
 import type { ProcessesService } from "./processes-service";
+import type { AgentsService } from "./agents-service";
 import type { TerminalService } from "./terminal-service";
 import type { FileService } from "./file-service";
 import type { SearchService } from "./search-service";
@@ -46,6 +47,7 @@ import type {
   ExtensionStorage,
   ExtensionStorageScopes,
 } from "./extension-storage";
+import type { ToolbarItemContribution, ToolbarSurface } from "./toolbar-items";
 
 /**
  * The teardown handle returned by every `register*` call on
@@ -629,6 +631,22 @@ export interface ExtensionContext {
   registerContextMenuItem<S extends MenuSurface>(
     item: ContextMenuContribution<S>,
   ): 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}.
+   */
+  registerToolbarItem<S extends ToolbarSurface>(
+    item: ToolbarItemContribution<S>,
+  ): Disposable;
+  /**
+   * Signal that toolbar-item `when` / `checked` data changed. Causes editor
+   * and terminal toolbars to re-query contributions and re-render.
+   */
+  invalidateToolbarItems(): void;
   /** Register a {@link Keybinding} (bind a shortcut to a command). */
   registerKeybinding(binding: Keybinding): Disposable;
   /** Register a {@link SidePanel} (a left/right column panel). */
@@ -698,6 +716,16 @@ export interface ExtensionContext {
    * See {@link ProcessesService} for the full API.
    */
   readonly processes: ProcessesService;
+  /**
+   * Host-computed coding-agent activity and resume-identity observability —
+   * a live, read-only view of what each terminal's agent is doing
+   * (`none`/`working`/`idle`/`error`/`dead`) and, once a terminal's
+   * backend is confirmed dead after an unclean shutdown, a resume hint for
+   * it. Detection is fully sealed in the host implementation; there is no
+   * registration API. **@beta** — the shape may still change. See
+   * {@link AgentsService} for the full API.
+   */
+  readonly agents: AgentsService;
   /**
    * Consumer API for the terminal domain — open a terminal tab in a workspace
    * (`create`) or reap a workspace's terminals (`closeWorkspace`). The terminal