@silo-code/sdk 0.21.0 → 0.22.0

package/src/event.ts

@@ -0,0 +1,28 @@
+import type { Disposable } from "./types";
+
+/**
+ * A subscribable event: call it with a listener and receive a
+ * {@link Disposable} that cancels the subscription. Modeled on VS Code's
+ * `Event<T>` convention.
+ *
+ * Services that emit events expose a member typed as `Event<T>` — the
+ * consuming extension calls it directly and pushes the returned disposable
+ * onto `ctx.subscriptions`:
+ *
+ * @example
+ * ```ts
+ * ctx.subscriptions.push(
+ *   ctx.editors.onDidSave(({ editorId, filePath }) => {
+ *     console.log("saved", filePath);
+ *   }),
+ * );
+ * ```
+ *
+ * **Host-side:** the matching emitter (`EventEmitter<T>`) lives in the
+ * extension-host package (not the SDK). Only the subscribable `Event<T>` type
+ * is public — extensions never construct emitters.
+ *
+ * @category Core Types
+ * @public
+ */
+export type Event<T> = (listener: (e: T) => void) => Disposable;

package/src/file-service.ts

@@ -82,15 +82,46 @@ export interface FileService {
   readBytes(path: string): Promise<ArrayBuffer>;
   /** List a directory's immediate entries. */
   readDir(path: string): Promise<FileMeta[]>;
-  /** Resolve true if a file or directory exists at `path`. */
+  /**
+   * Resolve true if a file or directory exists at `path`. Prefer
+   * {@link FileService.stat} when you also need the entry's metadata — `stat`
+   * returning non-`null` subsumes this check in one call.
+   */
   pathExists(path: string): Promise<boolean>;
+  /**
+   * Metadata for a single path, following symlinks, or `null` if nothing
+   * exists there. Resolving `null` (rather than rejecting) for an absent path
+   * is deliberate — it makes `stat` a one-call replacement for
+   * {@link FileService.pathExists} that also returns size / mtime / type.
+   * Rejects only on a real I/O error (e.g. a permission failure).
+   */
+  stat(path: string): Promise<FileMeta | null>;
   /** Write UTF-8 text to a file, creating or overwriting it. */
   writeText(path: string, content: string): Promise<void>;
+  /**
+   * Write raw bytes to a file, creating or overwriting it (and creating any
+   * missing parent directories). The byte-oriented counterpart to
+   * {@link FileService.writeText} / {@link FileService.readBytes} — use it for
+   * binary assets (images, archives) where `writeText` would corrupt the data.
+   */
+  writeBytes(path: string, data: ArrayBuffer | Uint8Array): Promise<void>;
   /** Create a directory (and any missing parents). */
   createDir(path: string): Promise<void>;
+  /**
+   * Copy a file or directory from `src` to `dest`, recursively for
+   * directories, creating any missing parent directories. Requires read access
+   * to `src` and write access to `dest` (both are workspace-scoped). Overwrites
+   * existing files at the destination.
+   */
+  copy(src: string, dest: string): Promise<void>;
   /** Rename / move a file or directory. */
   rename(oldPath: string, newPath: string): Promise<void>;
-  /** Delete a file or directory. */
+  /**
+   * **Permanently** delete a file or directory (directories are removed
+   * recursively). This does **not** move the entry to the OS trash/recycle
+   * bin — the delete is irreversible, so confirm destructive removals with the
+   * user first. Rejects if the path does not exist.
+   */
   delete(path: string): Promise<void>;
   /** Reveal a path in the OS file manager (Finder / Explorer). */
   reveal(path: string): Promise<void>;

package/src/index.ts

@@ -1,10 +1,16 @@
 /**
- * The public Silo extension API surface — the single curated entry point an
- * extension author imports from. This is the seed of the future `@silo-code/sdk`
- * package: it re-exports **only** the blessed, permanently supported types.
- * Anything not re-exported here is host-internal and may change without notice.
+ * The `@silo-code/sdk` public surface — the single curated entry point an
+ * extension author imports from. Re-exports **only** the blessed, permanently
+ * supported types and runtime helpers. Anything not re-exported here is
+ * host-internal and may change without notice.
  *
- * It is also the entry point the API-reference generator (TypeDoc) reads, so
+ * **What's here:** the types-first extension contract (see `types.ts`) plus a
+ * small set of blessed runtime helpers (`Tooltip`, `useFocusGroup`,
+ * `useServiceState`, `DND_MIME`, `PathDeniedError`, `NetworkError`). The SDK
+ * peer-depends on React 19; changes to the runtime helpers can be breaking
+ * even when the types are unchanged.
+ *
+ * This is also the entry point the API-reference generator (TypeDoc) reads, so
  * the published reference is exactly this surface — no more, no less.
  *
  * @packageDocumentation
@@ -66,6 +72,9 @@ export type {
   DiffContent,
   DiffContentRequest,
   DiffContentProvider,
+  ActiveEditorInfo,
+  EditorsState,
+  EditorSaveEvent,
 } from "./editor-service";
 export type {
   LayoutService,
@@ -167,6 +176,7 @@ export type {
   NetworkService,
   NetworkRequestOptions,
   NetworkResponse,
+  NetworkBytesResponse,
 } from "./network-service";
 
 // Static host-platform metadata: OS, CPU arch, and Silo version.
@@ -180,6 +190,15 @@ export type { LogService, LogLevel } from "./output-service";
 // Context keys referenced by `when` predicates on menu items / keybindings.
 export type { ContextKeys } from "./context-keys";
 
+// Typed event primitive: a subscribable Event<T> that returns a Disposable.
+// The matching host-side emitter is internal to the extension-host package.
+export type { Event } from "./event";
+
+// Pure path utilities — cross-platform replacement for `node:path` (banned in
+// extensions). All outputs use forward-slash separators. Both "/" and "\" are
+// accepted as input. Exported as a namespaced `path` object.
+export { path } from "./path";
+
 // Tooltip — the same styled hover popup the host uses in the status bar.
 // Extensions use this instead of native `title` attributes to match host chrome.
 export { Tooltip } from "./Tooltip";

package/src/network-service.ts

@@ -44,8 +44,12 @@ export interface NetworkRequestOptions {
   method?: "GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "PATCH";
   /** Request headers to send. */
   headers?: Record<string, string>;
-  /** Request body (string). Only meaningful for methods that carry a body. */
-  body?: string;
+  /**
+   * Request body. A string is sent as-is; an `ArrayBuffer` / `Uint8Array` is
+   * sent as raw bytes (e.g. uploading a file). Only meaningful for methods that
+   * carry a body.
+   */
+  body?: string | ArrayBuffer | Uint8Array;
   /** Follow HTTP redirects. Defaults to `true`. */
   followRedirects?: boolean;
   /** Request timeout in milliseconds. Omit for the platform default (~30 s). */
@@ -72,6 +76,24 @@ export interface NetworkResponse {
   finalUrl: string;
 }
 
+/**
+ * Response from {@link NetworkService.fetchBytes} — identical to
+ * {@link NetworkResponse} but with the body delivered as raw bytes.
+ *
+ * @category Core Types
+ * @public
+ */
+export interface NetworkBytesResponse {
+  /** HTTP status code. */
+  status: number;
+  /** Response headers, lowercased (multi-value joined with `", "`). */
+  headers: Record<string, string>;
+  /** Response body as raw bytes. */
+  body: ArrayBuffer;
+  /** Final URL after redirects. */
+  finalUrl: string;
+}
+
 /**
  * Server-side HTTP client exposed as {@link ExtensionContext.net}. Requests
  * run in the Rust backend via `reqwest`, so they bypass the browser's CORS
@@ -104,6 +126,33 @@ export interface NetworkService {
    */
   fetch(url: string, options?: NetworkRequestOptions): Promise<NetworkResponse>;
 
+  /**
+   * Like {@link NetworkService.fetch}, but resolves the response body as raw
+   * bytes ({@link NetworkBytesResponse}) instead of decoding it as UTF-8 text —
+   * for downloading images, archives, or any binary payload.
+   *
+   * @param url - The URL to fetch.
+   * @param options - Method, headers, body, redirect and timeout controls. The
+   *   body may itself be binary (`ArrayBuffer` / `Uint8Array`).
+   * @throws {@link NetworkError} if the request fails.
+   *
+   * @remarks
+   * The body rides Tauri's binary IPC channel (no base64), but the whole
+   * response is still buffered in memory on both sides — suitable for typical
+   * asset downloads (up to a few tens of MB), not for streaming multi-hundred-MB
+   * files.
+   *
+   * @example
+   * ```ts
+   * const { body } = await ctx.net.fetchBytes("https://example.com/logo.png");
+   * await ctx.files.writeBytes("logo.png", body);
+   * ```
+   */
+  fetchBytes(
+    url: string,
+    options?: NetworkRequestOptions,
+  ): Promise<NetworkBytesResponse>;
+
   /**
    * Send a `HEAD` request and return only the response headers — no body is
    * downloaded. More efficient than {@link NetworkService.fetch} when you only

package/src/path.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect } from "vitest";
+import { path } from "./path";
+
+describe("path.normalize", () => {
+  it("collapses dot segments", () =>
+    expect(path.normalize("a/./b")).toBe("a/b"));
+  it("resolves dot-dot segments", () =>
+    expect(path.normalize("a/b/../c")).toBe("a/c"));
+  it("converts backslash to forward-slash", () =>
+    expect(path.normalize("a\\b")).toBe("a/b"));
+  it("collapses duplicate slashes", () =>
+    expect(path.normalize("a//b")).toBe("a/b"));
+  it("preserves POSIX absolute", () =>
+    expect(path.normalize("/a/b")).toBe("/a/b"));
+  it("handles Windows drive", () =>
+    expect(path.normalize("C:\\a\\b")).toBe("C:/a/b"));
+  it("handles Windows drive with forward-slash", () =>
+    expect(path.normalize("C:/a/b")).toBe("C:/a/b"));
+  it("stays at root when dot-dot exceeds root", () =>
+    expect(path.normalize("/a/../..")).toBe("/"));
+  it("returns dot for empty-ish relative path", () =>
+    expect(path.normalize("a/..")).toBe("."));
+  it("UNC path is preserved", () =>
+    expect(path.normalize("\\\\server\\share\\foo")).toBe(
+      "//server/share/foo",
+    ));
+});
+
+describe("path.join", () => {
+  it("joins two segments", () => expect(path.join("a", "b")).toBe("a/b"));
+  it("joins many segments", () =>
+    expect(path.join("a", "b", "c")).toBe("a/b/c"));
+  it("resolves dot-dot across join", () =>
+    expect(path.join("a/b", "../c")).toBe("a/c"));
+  it("preserves leading slash from first segment", () =>
+    expect(path.join("/a", "b")).toBe("/a/b"));
+  it("converts backslash", () => expect(path.join("a\\b", "c")).toBe("a/b/c"));
+  it("returns dot for no arguments", () => expect(path.join()).toBe("."));
+  it("ignores empty string segments", () =>
+    expect(path.join("a", "", "b")).toBe("a/b"));
+  it("handles Windows drive", () =>
+    expect(path.join("C:\\a", "b")).toBe("C:/a/b"));
+  it('join("/", rel) produces "/rel" not "//rel" (UNC)', () =>
+    expect(path.join("/", "linked.md")).toBe("/linked.md"));
+  it("join of POSIX root with nested rel stays absolute", () =>
+    expect(path.join("/", "a/b/../c")).toBe("/a/c"));
+});
+
+describe("path.dirname", () => {
+  it("returns parent dir", () => expect(path.dirname("/a/b/c")).toBe("/a/b"));
+  it("returns slash for top-level file", () =>
+    expect(path.dirname("/a")).toBe("/"));
+  it("returns dot for bare filename", () =>
+    expect(path.dirname("a")).toBe("."));
+  it("handles Windows drive", () =>
+    expect(path.dirname("C:\\a\\b")).toBe("C:/a"));
+  it("returns drive root for top-level", () =>
+    expect(path.dirname("C:\\a")).toBe("C:/"));
+  it("resolves trailing slash before computing", () =>
+    expect(path.dirname("/a/b/")).toBe("/a"));
+  it("handles UNC path", () =>
+    expect(path.dirname("//server/share/foo")).toBe("//server/share"));
+  it("returns dot for relative bare name", () =>
+    expect(path.dirname("file.ts")).toBe("."));
+  it("returns relative parent", () => expect(path.dirname("a/b")).toBe("a"));
+});
+
+describe("path.basename", () => {
+  it("returns last segment", () =>
+    expect(path.basename("/a/b/file.ts")).toBe("file.ts"));
+  it("strips provided extension", () =>
+    expect(path.basename("file.ts", ".ts")).toBe("file"));
+  it("does not strip if extension doesn't match", () =>
+    expect(path.basename("file.ts", ".js")).toBe("file.ts"));
+  it("handles trailing slash", () => expect(path.basename("/a/b/")).toBe("b"));
+  it("handles Windows path", () =>
+    expect(path.basename("C:\\a\\b.txt")).toBe("b.txt"));
+  it("returns empty string for root", () =>
+    expect(path.basename("/")).toBe(""));
+  it("returns bare name", () =>
+    expect(path.basename("file.ts")).toBe("file.ts"));
+});
+
+describe("path.extname", () => {
+  it("returns extension with dot", () =>
+    expect(path.extname("file.ts")).toBe(".ts"));
+  it("returns last extension only", () =>
+    expect(path.extname("file.test.ts")).toBe(".ts"));
+  it("returns empty for no extension", () =>
+    expect(path.extname("file")).toBe(""));
+  it("returns empty for dotfile (dot at position 0)", () =>
+    expect(path.extname(".gitignore")).toBe(""));
+  it("returns dot for trailing dot", () =>
+    expect(path.extname("file.")).toBe("."));
+  it("handles full path", () =>
+    expect(path.extname("/a/b/file.md")).toBe(".md"));
+});
+
+describe("path.isAbsolute", () => {
+  it("true for POSIX absolute", () =>
+    expect(path.isAbsolute("/foo")).toBe(true));
+  it("true for Windows drive with backslash", () =>
+    expect(path.isAbsolute("C:\\foo")).toBe(true));
+  it("true for Windows drive with forward-slash", () =>
+    expect(path.isAbsolute("C:/foo")).toBe(true));
+  it("true for UNC backslash", () =>
+    expect(path.isAbsolute("\\\\server\\share")).toBe(true));
+  it("true for UNC forward-slash", () =>
+    expect(path.isAbsolute("//server/share")).toBe(true));
+  it("false for relative path", () =>
+    expect(path.isAbsolute("foo/bar")).toBe(false));
+  it("false for drive-relative (no slash)", () =>
+    expect(path.isAbsolute("C:foo")).toBe(false));
+  it("false for bare filename", () =>
+    expect(path.isAbsolute("file.ts")).toBe(false));
+});
+
+describe("path.relative", () => {
+  it("computes sibling relative path", () =>
+    expect(path.relative("/a/b", "/a/c")).toBe("../c"));
+  it("returns dot for same path", () =>
+    expect(path.relative("/a/b", "/a/b")).toBe("."));
+  it("returns descendant path", () =>
+    expect(path.relative("/a", "/a/b/c")).toBe("b/c"));
+  it("returns parent path", () =>
+    expect(path.relative("/a/b/c", "/a")).toBe("../.."));
+  it("handles root to subpath", () =>
+    expect(path.relative("/", "/a/b")).toBe("a/b"));
+  it("returns normalized `to` for different Windows drives", () =>
+    expect(path.relative("C:/a", "D:/b")).toBe("D:/b"));
+  it("same drive computes relative", () =>
+    expect(path.relative("C:/a/b", "C:/a/c")).toBe("../c"));
+  it("handles backslash inputs", () =>
+    expect(path.relative("C:\\a\\b", "C:\\a\\c")).toBe("../c"));
+});

package/src/path.ts

@@ -0,0 +1,188 @@
+// Pure path utilities for extensions. A cross-platform replacement for
+// `node:path`, which extensions are banned from importing (platform ban).
+// All outputs use forward-slash separators — the form FileService accepts on
+// every platform. Both "/" and "\" are accepted as inputs.
+
+/** Normalize all separators to forward-slash. */
+function normSep(p: string): string {
+  return p.replace(/\\/g, "/");
+}
+
+/** Extract a Windows drive-letter prefix ("C:") from a forward-slash path, or null. */
+function parseDrive(p: string): string | null {
+  const m = /^([A-Za-z]):/.exec(p);
+  return m ? m[1].toUpperCase() + ":" : null;
+}
+
+/**
+ * Normalize segments of a forward-slash path: collapse duplicate slashes,
+ * resolve "." and ".." segments. Preserves leading "/" (POSIX absolute),
+ * "C:/" (Windows drive-letter), and "//" (UNC paths).
+ */
+function normSegments(s: string): string {
+  const drive = parseDrive(s);
+  const afterDrive = drive ? s.slice(2) : s;
+  const isUnc = afterDrive.startsWith("//");
+  const isAbs = isUnc || afterDrive.startsWith("/");
+
+  const stack: string[] = [];
+  for (const seg of afterDrive.split("/")) {
+    if (seg === "" || seg === ".") continue;
+    if (seg === "..") {
+      if (stack.length > 0 && stack[stack.length - 1] !== "..") {
+        stack.pop();
+      } else if (!isAbs) {
+        stack.push("..");
+      }
+    } else {
+      stack.push(seg);
+    }
+  }
+
+  let result = stack.join("/");
+  if (isUnc) result = "//" + result;
+  else if (isAbs) result = "/" + result;
+  if (drive) result = drive + result;
+  if (!result) return isAbs ? (drive ? drive + "/" : "/") : ".";
+  return result;
+}
+
+/**
+ * Path utilities for extensions — a cross-platform replacement for
+ * `node:path`, which extensions are banned from importing. All output paths
+ * use forward-slash separators (the form {@link FileService} accepts on every
+ * platform). Both `/` and `\` are accepted as input separators.
+ *
+ * @example
+ * ```ts
+ * import { path } from "@silo-code/sdk";
+ *
+ * const dir  = path.dirname(filePath);            // "/home/user/docs"
+ * const full = path.join(dir, "images/fig.png");  // "/home/user/docs/images/fig.png"
+ * const rel  = path.relative(dir, full);           // "images/fig.png"
+ * const ext  = path.extname(full);                 // ".png"
+ * ```
+ *
+ * @category Core Types
+ * @public
+ */
+export const path: {
+  /**
+   * Join path segments and normalize the result. Empty segments are ignored;
+   * `\` separators in any segment are treated as `/`.
+   */
+  join(...parts: string[]): string;
+  /**
+   * Return the directory portion of a path — everything up to (not including)
+   * the last `/`. Returns `"."` for a bare filename with no directory component.
+   */
+  dirname(p: string): string;
+  /**
+   * Return the final component of a path. If `ext` is supplied and the
+   * basename ends with that string, it is stripped from the result.
+   */
+  basename(p: string, ext?: string): string;
+  /**
+   * Return the extension of a path — the portion from the last `.` of the
+   * basename, including the dot. Returns `""` for paths with no extension and
+   * for dotfiles with no secondary extension (e.g. `".gitignore"` → `""`).
+   */
+  extname(p: string): string;
+  /**
+   * Compute the relative path from `from` to `to`. Both should be absolute
+   * paths on the same drive. When they are on different Windows drive letters,
+   * `to` (normalized) is returned unchanged — no relative path exists between
+   * drives.
+   */
+  relative(from: string, to: string): string;
+  /**
+   * Return `true` if `p` is an absolute path: starts with `/` (POSIX), has a
+   * drive letter followed by a slash (`C:/`, `C:\`), or is a UNC path
+   * (`\\server\share` / `//server/share`). Note: `C:foo` (drive-relative,
+   * no slash) is NOT absolute.
+   */
+  isAbsolute(p: string): boolean;
+  /**
+   * Normalize a path: convert `\` to `/`, collapse duplicate slashes, and
+   * resolve `.` and `..` segments.
+   */
+  normalize(p: string): string;
+} = {
+  normalize(p) {
+    return normSegments(normSep(p));
+  },
+
+  join(...parts) {
+    const nonEmpty = parts.filter((p) => p.length > 0);
+    if (nonEmpty.length === 0) return ".";
+    // Concatenate without adding "/" when adjacent parts already supply the
+    // boundary, so join("/", "rel") → "/rel" rather than "//rel" (UNC).
+    const raw = nonEmpty.map(normSep).reduce((a, b) => {
+      if (a.endsWith("/") || b.startsWith("/")) return a + b;
+      return a + "/" + b;
+    });
+    return normSegments(raw);
+  },
+
+  dirname(p) {
+    const n = normSegments(normSep(p));
+    const drive = parseDrive(n);
+    const rest = drive ? n.slice(2) : n;
+    const i = rest.lastIndexOf("/");
+    if (i < 0) return drive ? drive + "." : ".";
+    if (i === 0) return drive ? drive + "/" : "/";
+    return drive ? drive + rest.slice(0, i) : rest.slice(0, i);
+  },
+
+  basename(p, ext) {
+    const n = normSep(p);
+    const segs = n.split("/");
+    let name = segs[segs.length - 1] ?? "";
+    // Trailing slash: "foo/" → last segment is "" → fall back to prior segment
+    if (name === "" && segs.length > 1) name = segs[segs.length - 2] ?? "";
+    if (ext !== undefined && name.endsWith(ext)) {
+      name = name.slice(0, name.length - ext.length);
+    }
+    return name;
+  },
+
+  extname(p) {
+    const base = path.basename(normSep(p));
+    const i = base.lastIndexOf(".");
+    // i === 0 means a dotfile like ".gitignore" — no extension
+    if (i <= 0) return "";
+    return base.slice(i);
+  },
+
+  isAbsolute(p) {
+    const n = normSep(p);
+    if (n.startsWith("//")) return true; // UNC (\\server\share or //server/share)
+    if (/^[A-Za-z]:\//.test(n)) return true; // Windows drive with slash (C:/ or C:\)
+    return n.startsWith("/"); // POSIX
+  },
+
+  relative(from, to) {
+    const nFrom = normSegments(normSep(from));
+    const nTo = normSegments(normSep(to));
+    const driveFrom = parseDrive(nFrom);
+    const driveTo = parseDrive(nTo);
+    // Can't express a relative path across different drives
+    if (driveFrom !== driveTo) return nTo;
+    const segsFrom = (driveFrom ? nFrom.slice(2) : nFrom)
+      .split("/")
+      .filter(Boolean);
+    const segsTo = (driveTo ? nTo.slice(2) : nTo).split("/").filter(Boolean);
+    let common = 0;
+    while (
+      common < segsFrom.length &&
+      common < segsTo.length &&
+      segsFrom[common] === segsTo[common]
+    ) {
+      common++;
+    }
+    const ups = segsFrom.length - common;
+    const downs = segsTo.slice(common);
+    const parts = [...Array<string>(ups).fill(".."), ...downs];
+    return parts.join("/") || ".";
+  },
+};

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.