@silo-code/sdk 0.20.0 → 0.22.0

package/src/process-service.ts

@@ -67,6 +67,24 @@ export interface ProcessExecOptions {
    * {@link Permission}. First-party (bundled) extensions are unscoped.
    */
   cwd?: string;
+  /**
+   * Extra environment variables, **merged over** the host's environment (the
+   * command inherits the host env; these keys add to or override it). Use it to
+   * set things like `GIT_PAGER=cat` or a locale without clobbering `PATH`.
+   */
+  env?: Record<string, string>;
+  /**
+   * Kill the process and reject after this many milliseconds. The whole process
+   * group is terminated (not just the direct child), so shell wrappers don't
+   * leak orphans. The rejection is an `Error` whose `name` is `"AbortError"`.
+   */
+  timeoutMs?: number;
+  /**
+   * Abort handle. Aborting kills the process (and its group) and rejects the
+   * `exec` promise with an `Error` whose `name` is `"AbortError"` — the same
+   * shape as a `timeoutMs` expiry, so callers branch on `err.name`.
+   */
+  signal?: AbortSignal;
 }
 
 /**
@@ -116,10 +134,12 @@ export interface ProcessService {
    * interactive sessions instead.
    *
    * Runs **off the UI thread**, so a slow or network-bound command never
-   * stutters the app. The returned promise rejects only if the process could
-   * not be spawned (e.g. the command was not found); a command that runs but
-   * exits non-zero **resolves** — check {@link ProcessExecResult.code} and
-   * {@link ProcessExecResult.stderr}.
+   * stutters the app. The returned promise rejects if the process could not be
+   * spawned (e.g. the command was not found), or if a
+   * {@link ProcessExecOptions.timeoutMs | timeout} / {@link ProcessExecOptions.signal | abort}
+   * fires (an `Error` with `name === "AbortError"`); a command that runs to
+   * completion but exits non-zero **resolves** — check
+   * {@link ProcessExecResult.code} and {@link ProcessExecResult.stderr}.
    *
    * @param command - Executable to run (resolved via `PATH`), e.g. `"git"`.
    * @param args - Arguments passed verbatim — not shell-interpreted, so no

package/src/processes-service.ts

@@ -88,7 +88,7 @@ export interface ProcessInfo {
  * // Notify when all agents in the workspace are idle.
  * const sub = ctx.processes.subscribe((procs) => {
  *   const allIdle = procs.every((p) => p.atPrompt);
- *   if (allIdle) ctx.ui.notify({ title: "All agents finished" });
+ *   if (allIdle) ctx.ui.notify("info", "All agents finished");
  * });
  * ctx.subscriptions.push(sub);
  *

package/src/search-service.ts

@@ -43,6 +43,17 @@ export interface SearchOptions {
    * is hit, the search stops early and {@link SearchResponse.truncated} is true.
    */
   maxResults?: number;
+  /**
+   * Cancel the search. When the signal aborts, the promise returned by
+   * {@link SearchService.search} rejects with an `Error` whose `name` is
+   * `"AbortError"` (the `fetch` convention — branch on `err.name`).
+   *
+   * Cancellation is observable immediately, but the native search may still run
+   * to completion in the background — its result is simply discarded. Use this
+   * to abandon a stale query (e.g. superseded by the next keystroke) rather than
+   * to reclaim native CPU the instant you abort.
+   */
+  signal?: AbortSignal;
 }
 
 /**

package/src/system-service.ts

@@ -53,13 +53,13 @@ export interface SystemInfo {
  *       ctx.subscriptions.push(
  *         ctx.registerCommand({
  *           id: "my.reveal-in-finder",
- *           title: "Reveal in Finder",
+ *           label: "Reveal in Finder",
  *           run() { ... },
  *         }),
  *       );
  *     }
  *
- *     ctx.ui.notify({ title: `Running Silo ${siloVersion} on ${os}/${arch}` });
+ *     ctx.ui.notify("info", `Running Silo ${siloVersion} on ${os}/${arch}`);
  *   },
  * };
  * ```

package/src/terminal-service.ts

@@ -98,11 +98,51 @@ export interface TerminalService {
    * 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
    * mounts.
+   *
+   * Returns `undefined` only when `input.workspaceId` is not given and there is
+   * no active workspace at the time of the call — in normal use this does not
+   * happen because activating any workspace happens before extensions run.
    */
   create(input?: CreateTerminalInput): TerminalRecord | undefined;
   /** Close and kill every terminal in a workspace (e.g. on workspace delete). */
   closeWorkspace(workspaceId: string): void;
 
+  /**
+   * Write text to a terminal's PTY as if the user typed it. By default a
+   * carriage return is appended so the line executes; pass `addNewline: false`
+   * to stage text without running it.
+   *
+   * Works even if the terminal tab has never been shown: the PTY spawns lazily
+   * on first mount, and `sendText` force-spawns it on demand (a later mount then
+   * attaches to that same session). No-op for an unknown `terminalId`.
+   *
+   * @param terminalId - The {@link TerminalRecord.id} to write to.
+   * @param text - The text to send.
+   * @param addNewline - Append a carriage return to execute. Defaults to `true`.
+   *
+   * @example
+   * ```ts
+   * const term = ctx.terminals.create({ cwd: workspaceFolder });
+   * if (term) ctx.terminals.sendText(term.id, "npm run build");
+   * ```
+   */
+  sendText(terminalId: string, text: string, addNewline?: boolean): void;
+
+  /**
+   * Close one terminal tab and kill its PTY session. No-op if the id is unknown.
+   * To reap every terminal in a workspace at once use
+   * {@link TerminalService.closeWorkspace}.
+   */
+  close(terminalId: string): void;
+
+  /**
+   * Set a terminal's user-facing name ({@link TerminalRecord.customName}),
+   * shown on its tab and persisted across restarts. Passing an empty string
+   * clears the custom name, letting the PTY-derived title take over again.
+   * No-op for an unknown `terminalId`.
+   */
+  rename(terminalId: string, name: string): void;
+
   /**
    * Switch to the workspace containing this terminal and activate its tab in
    * the center dock. No-ops if the terminal id is unknown.
@@ -168,4 +208,35 @@ export interface TerminalService {
     terminalId: string,
     handler: (event: OscEvent) => void,
   ): Disposable;
+
+  /**
+   * The record id of the terminal tab that is currently active in the active
+   * workspace's center dock, or `null` when an editor tab (or nothing) is
+   * active. "Active" is the dock's single active panel — the tab the user is
+   * looking at and typing into — so a terminal merely visible in a non-active
+   * split does not count.
+   */
+  getActive(): string | null;
+
+  /**
+   * Subscribe to active-terminal changes. The listener receives the terminal
+   * record id whenever a terminal tab becomes the active center-dock panel,
+   * and `null` when activation moves elsewhere (an editor tab, or no panel —
+   * including transiently during a workspace switch, before the incoming
+   * workspace's active tab is published).
+   *
+   * Fires on tab activation, group activation, and workspace switches.
+   * Returns a {@link Disposable} that cancels the subscription.
+   *
+   * @example
+   * ```ts
+   * // Clear a "needs attention" marker once the user views the terminal.
+   * ctx.subscriptions.push(
+   *   ctx.terminals.subscribeActive((terminalId) => {
+   *     if (terminalId) attention.delete(terminalId);
+   *   }),
+   * );
+   * ```
+   */
+  subscribeActive(listener: (terminalId: string | null) => void): Disposable;
 }

package/src/theme-service.ts

@@ -15,11 +15,11 @@ export type {
 } from "./domain-types";
 
 /**
- * A selectable theme contributed via
- * {@link ExtensionContext.registerThemePreset}. Built-in presets (Tokyo Night,
- * Solarized Light, Gruvbox Dark, …) are registered by the `theme-presets`
- * extension; core ships only Dark and Light. A preset's {@link ThemePreset.vars}
- * are injected as CSS custom properties when it is the active theme.
+ * A selectable theme contributed via {@link ThemeService.registerPreset}.
+ * Built-in presets (Tokyo Night, Solarized Light, Gruvbox Dark, …) are
+ * registered by the `theme-presets` extension; core ships only Dark and Light.
+ * A preset's {@link ThemePreset.vars} are injected as CSS custom properties
+ * when it is the active theme.
  *
  * @category Registration
  * @public
@@ -74,8 +74,7 @@ export interface ThemeState {
  * Read via {@link ThemeService.getState | getState} /
  * {@link ThemeService.subscribe | subscribe} (e.g. with `useSyncExternalStore`);
  * drive via {@link ThemeService.setActive | setActive} and the custom-theme
- * methods. Contributing a *new* preset is a separate concern —
- * {@link ExtensionContext.registerThemePreset}.
+ * methods. Contribute a new preset via {@link ThemeService.registerPreset}.
  *
  * @category Consumer Services
  * @public
@@ -99,4 +98,21 @@ export interface ThemeService {
   exportTheme(theme: CustomTheme): ThemeExport;
   /** Validate/parse imported JSON into a custom theme (assigns a fresh id). */
   importTheme(data: unknown): CustomTheme;
+  /**
+   * Register a {@link ThemePreset} (a selectable theme in the picker). The
+   * preset appears immediately and is removed when the returned
+   * {@link Disposable} is disposed (typically when the extension deactivates).
+   *
+   * @example
+   * ```ts
+   * ctx.theme.registerPreset({
+   *   id: "my-theme",
+   *   name: "My Theme",
+   *   base: "dark",
+   *   colorScheme: "dark",
+   *   vars: { "--silo-color-bg": "#1a1a2e" },
+   * });
+   * ```
+   */
+  registerPreset(preset: ThemePreset): Disposable;
 }

package/src/types.ts

@@ -1,5 +1,6 @@
 /**
- * The Silo extension API — types only.
+ * The Silo extension API — types-first contract plus a small set of blessed
+ * runtime helpers.
  *
  * Everything an extension author can see at compile time lives here (plus the
  * service interfaces in the sibling `*-service` files, which this module
@@ -8,6 +9,12 @@
  * never import the host. This is the VS Code (`vscode.d.ts`) / Obsidian
  * (`obsidian-api`) model.
  *
+ * **Runtime exports:** the SDK also ships a small set of blessed runtime
+ * helpers (`Tooltip`, `useFocusGroup`, `useServiceState`, `DND_MIME`,
+ * `PathDeniedError`, `NetworkError`) and peer-depends on React 19. Changes to
+ * these can be breaking even when the types are unchanged — treat them with
+ * the same care as the type surface.
+ *
  * Start with {@link Extension} (the unit you export) and
  * {@link ExtensionContext} (the `ctx` the host hands you).
  *
@@ -18,7 +25,6 @@
  * @packageDocumentation
  */
 import type React from "react";
-import type { IDockviewPanelProps } from "dockview";
 import type { ContextKeys } from "./context-keys";
 import type { WorkspaceService } from "./workspace-service";
 import type { EditorService } from "./editor-service";
@@ -54,26 +60,70 @@ export interface Disposable {
 }
 
 /**
- * The dockview panel API handed to a {@link DockPanelKind} component — used to
- * drive the panel's own tab (title, close, focus). Re-exported from `dockview`
- * so extensions don't take a direct dependency on it.
+ * The panel API handed to a {@link DockPanelKind} component. Use these methods
+ * to drive the panel's own tab (title, close, focus) and update its stored
+ * parameters. The host provides the implementation; extensions never construct
+ * this object directly.
  *
  * @category Core Types
  * @public
  */
-export type DockPanelApi = IDockviewPanelProps["api"];
+export interface DockPanelApi {
+  /** Update the title shown in the panel's tab. */
+  setTitle(title: string): void;
+  /** Programmatically close this panel. */
+  close(): void;
+  /** Bring this panel to focus (make it the active panel in its group). */
+  setActive(): void;
+  /** `true` while this panel is the active one in its dock group. */
+  readonly isActive: boolean;
+  /**
+   * Subscribe to active-state transitions. The listener is called whenever
+   * the panel gains or loses active status, with an event carrying the new
+   * state. Returns a {@link Disposable} that cancels the subscription.
+   */
+  onDidActiveChange(
+    listener: (event: { readonly isActive: boolean }) => void,
+  ): Disposable;
+  /**
+   * `true` while this panel is visible — its tab is the selected one in its
+   * group. Distinct from {@link DockPanelApi.isActive | isActive}: with split
+   * groups, every group's selected tab is visible but only one panel in the
+   * whole dock is active.
+   */
+  readonly isVisible: boolean;
+  /**
+   * Subscribe to visibility transitions (the panel's tab being selected or
+   * deselected in its group). Use to pause expensive work while hidden, or to
+   * re-measure on reveal (e.g. the terminal refits xterm when its tab becomes
+   * visible again). Returns a {@link Disposable} that cancels the subscription.
+   */
+  onDidVisibilityChange(
+    listener: (event: { readonly isVisible: boolean }) => void,
+  ): Disposable;
+  /**
+   * Shallow-merge `params` into this panel's stored parameters. Keys absent
+   * from `params` are left unchanged. Useful for keeping tabs-serializable
+   * state (e.g. the open URL in a web-viewer panel) consistent with the UI.
+   */
+  updateParameters(params: object): void;
+}
 
 /**
  * Props handed to a {@link DockPanelKind} component. Use this type to annotate
- * your component instead of importing `IDockviewPanelProps` from `dockview`
- * directly — the SDK wraps it so extensions remain insulated from dockview
- * version changes. The optional generic `T` narrows the shape of `params`.
+ * your component instead of importing from the underlying dock framework
+ * directly — the SDK owns this surface so extensions remain insulated from
+ * host implementation details. The optional generic `T` narrows `params`.
  *
  * @category Core Types
  * @public
  */
-export type DockPanelProps<T extends object = Record<string, unknown>> =
-  IDockviewPanelProps<T>;
+export interface DockPanelProps<T extends object = Record<string, unknown>> {
+  /** The panel API — drives the tab (title, close, focus, params). */
+  api: DockPanelApi;
+  /** Serializable parameters forwarded to the panel at open time. */
+  params: T;
+}
 
 /**
  * Props passed to an {@link Editor} component. An editor renders the contents of
@@ -164,10 +214,10 @@ export interface NewFileTemplate {
 
 /**
  * Declarative metadata about a file extension — the open-ended counterpart to
- * Viewer (which is purely a renderer). A single source of truth that "New File"
- * surfaces (and, later, tab/explorer icons) can enumerate. Registering a
- * FileType does not register a viewer; the two are matched independently by
- * extension at dispatch time.
+ * {@link Editor} (which is purely a presenter/renderer). A single source of
+ * truth that "New File" surfaces (and, later, tab/explorer icons) can
+ * enumerate. Registering a FileType does not register an Editor; the two are
+ * matched independently by extension at dispatch time.
  *
  * @category Registration
  * @public
@@ -196,8 +246,15 @@ export interface Command {
   id: string;
   /** Human-readable label (shown where the command surfaces in UI). */
   label: string;
-  /** The action. Runs synchronously; do async work inside if needed. */
-  run: () => void;
+  /**
+   * The action. May accept arguments passed through from
+   * {@link ExtensionContext.executeCommand} and may return a value (sync or
+   * async); `executeCommand` resolves with whatever this returns.
+   *
+   * Zero-argument, void-returning commands are still valid — `() => void`
+   * satisfies this type, so existing registrations compile unchanged.
+   */
+  run: (...args: unknown[]) => unknown | Promise<unknown>;
 }
 
 /**
@@ -325,16 +382,19 @@ export interface SidePanel {
 
 /**
  * Registers a kind of dock panel (a tab that can live in the center dock area,
- * e.g. the terminal). Workspaces open panels of registered kinds by id.
+ * e.g. the terminal). Workspaces open panels of registered kinds by id. The
+ * optional generic `T` is the shape of the params this kind's panels are
+ * opened with — annotate your component with `DockPanelProps<T>` and
+ * {@link ExtensionContext.registerDockPanelKind} infers it, no casts needed.
  *
  * @category Registration
  * @public
  */
-export interface DockPanelKind {
+export interface DockPanelKind<T extends object = Record<string, unknown>> {
   /** Unique id for this panel kind. */
   id: string;
-  /** The React component; receives the raw dockview panel props. */
-  component: React.ComponentType<IDockviewPanelProps>;
+  /** The React component that renders this panel; receives {@link DockPanelProps}. */
+  component: React.ComponentType<DockPanelProps<T>>;
   /**
    * 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.
@@ -464,20 +524,39 @@ export interface ExtensionContext {
   registerKeybinding(binding: Keybinding): Disposable;
   /** Register a {@link SidePanel} (a left/right column panel). */
   registerSidePanel(panel: SidePanel): Disposable;
-  /** Register a {@link DockPanelKind} (a center-dock tab kind). */
-  registerDockPanelKind(kind: DockPanelKind): Disposable;
+  /**
+   * Register a {@link DockPanelKind} (a center-dock tab kind). The params
+   * generic `T` is inferred from the component's {@link DockPanelProps}
+   * annotation, so kinds with typed params register without casts.
+   */
+  registerDockPanelKind<T extends object = Record<string, unknown>>(
+    kind: DockPanelKind<T>,
+  ): Disposable;
   /** Register a {@link StatusItem} (a status-bar widget). */
   registerStatusItem(item: StatusItem): Disposable;
   /** Register a {@link SettingsPage} (a page in the Settings dialog). */
   registerSettingsPage(page: SettingsPage): Disposable;
-  /** Register a {@link ThemePreset} (a selectable theme in the picker). */
+  /**
+   * Register a {@link ThemePreset} (a selectable theme in the picker).
+   * @deprecated Use {@link ThemeService.registerPreset | ctx.theme.registerPreset()} instead.
+   *   This method will be removed in a future release.
+   */
   registerThemePreset(preset: ThemePreset): Disposable;
   /**
    * Invoke a registered command by id — including commands contributed by
    * other extensions. The minimal "operate" primitive; pairs with the typed
    * services for read access.
+   *
+   * Optional positional `args` are forwarded to the command's
+   * {@link Command.run} function. The returned `Promise` resolves with the
+   * command's return value, or rejects if the command throws, is async and
+   * rejects, or the id is not registered. Sync commands dispatch synchronously
+   * before the promise settles, so callers that read state the command mutates
+   * immediately after `await executeCommand(…)` see the updated state.
+   *
+   * @typeParam T - Expected return type of the command (defaults to `unknown`).
    */
-  executeCommand(id: string): void;
+  executeCommand<T = unknown>(id: string, ...args: unknown[]): Promise<T>;
   /**
    * Consumer API for driving workspace state — create, rename, reorder,
    * activate, soft close/reopen, and hard delete. Subscribe to a frozen

package/src/workspace-service.ts

@@ -170,6 +170,12 @@ export interface WorkspaceService {
   createFromFolderPicker(): Promise<Workspace | null>;
   create(input: CreateWorkspaceInput): Workspace;
   rename(id: string, name: string): void;
+  /**
+   * Move a workspace to a new position relative to a reference workspace.
+   * @param from - Id of the workspace being dragged / moved.
+   * @param to - Id of the reference workspace (the insertion anchor).
+   * @param position - Whether to place `from` before or after `to`.
+   */
   reorder(from: string, to: string, position: "before" | "after"): void;
   /** Activate (and reopen if closed). */
   activate(id: string): void;
@@ -263,6 +269,13 @@ export interface WorkspaceService {
    *
    * The Workspaces panel subscribes internally to re-render when providers
    * are added or removed.
+   *
+   * **No `invalidateSection` by design.** Unlike status rows and badges, a
+   * section is a live React component that re-renders on its own internal or
+   * context-driven state changes — it is not a snapshot returned from a
+   * `provide()` call, so there is nothing for the host to re-query. If a
+   * section needs to trigger a full workspace-panel refresh (rare), it should
+   * update its own state directly.
    */
   subscribeSection(listener: () => void): Disposable;