@silo-code/sdk 0.43.0 → 0.45.0

package/dist/terminal-service.d.ts

@@ -21,6 +21,51 @@ export interface OscEvent {
     /** The raw payload string after the code and its separating semicolon. */
     payload: string;
 }
+/**
+ * Where a chunk of terminal output came from in time.
+ *
+ * A terminal session outlives the app, so re-attaching to one replays the
+ * session host's recent scrollback — bytes that are byte-for-byte identical to
+ * live output but describe things that already happened, sometimes long ago.
+ * Treating them as live is what makes a reattached agent terminal announce a
+ * turn that finished before the app started.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface OutputOrigin {
+    /**
+     * `true` when the chunk is scrollback the session host is replaying on
+     * attach, `false` when the session produced it just now.
+     *
+     * Only ever `true` for a subscription that opted in with
+     * {@link SubscribeOutputOptions.includeReplay}.
+     */
+    replay: boolean;
+}
+/**
+ * Options for {@link TerminalService.subscribeOutput} and
+ * {@link TerminalService.subscribeOsc}.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface SubscribeOutputOptions {
+    /**
+     * Deliver the scrollback the session host replays when re-attaching to a
+     * terminal, in addition to live output. Defaults to `false`.
+     *
+     * Leave it off for anything that reads output as *activity* — "the agent is
+     * working", "something just happened", a notification — because replayed
+     * bytes would fire all of it for events that are already over.
+     *
+     * Turn it on for anything that needs the terminal's *history*: rendering the
+     * scrollback, or identifying which program is running in a terminal you have
+     * only just attached to. Each chunk then arrives with an
+     * {@link OutputOrigin} saying which kind it is.
+     */
+    includeReplay?: boolean;
+}
 export type { TerminalKind, TerminalRecord } from "./domain-types.js";
 /**
  * @deprecated Prefer {@link TerminalService.setIndicator} /
@@ -214,8 +259,16 @@ export interface TerminalService extends TabAdornmentMethods {
      * });
      * ctx.subscriptions.push(sub);
      * ```
+     *
+     * @remarks
+     * OSC sequences ride the raw output stream, so the same replay rule applies
+     * as for {@link TerminalService.subscribeOutput}: by default only sequences
+     * from **live** output are delivered, and `{ includeReplay: true }` adds
+     * those found in the scrollback replayed on attach. Status titles are the
+     * usual reason to leave it off — a replayed "busy" title describes a turn
+     * that is already over.
      */
-    subscribeOsc(terminalId: string, handler: (event: OscEvent) => void): Disposable;
+    subscribeOsc(terminalId: string, handler: (event: OscEvent, origin: OutputOrigin) => void, options?: SubscribeOutputOptions): Disposable;
     /**
      * Subscribe to the raw PTY output stream of the terminal identified by
      * `terminalId`. The `handler` is called with every chunk of bytes the PTY
@@ -232,19 +285,42 @@ export interface TerminalService extends TabAdornmentMethods {
      * not the underlying PTY session id, so it survives terminal recreation within
      * the same record.
      *
+     * By default only **live** output is delivered. A terminal session outlives
+     * the app, so attaching to one replays its recent scrollback; without this
+     * default every reattach would look like a burst of activity happening right
+     * now. Pass `{ includeReplay: true }` to receive that history too — each
+     * chunk then arrives with an {@link OutputOrigin} saying which kind it is.
+     *
      * Returns a {@link Disposable} that cancels the subscription.
      *
      * @example
      * ```ts
      * // Track the last time any output arrived to confirm agent activity.
+     * // Replayed scrollback is excluded by default, so re-attaching to a
+     * // long-idle terminal doesn't read as fresh activity.
      * let lastOutputAt = 0;
      * const sub = ctx.terminals.subscribeOutput(terminalId, () => {
      *   lastOutputAt = Date.now();
      * });
      * ctx.subscriptions.push(sub);
      * ```
+     *
+     * @example
+     * ```ts
+     * // Opt in to the replayed scrollback — needed to work out what is running
+     * // in a terminal you just attached to — and keep the two apart.
+     * const sub = ctx.terminals.subscribeOutput(
+     *   terminalId,
+     *   (chunk, { replay }) => {
+     *     identifyProgram(chunk);           // history is evidence
+     *     if (!replay) noteActivity();      // …but only live output is activity
+     *   },
+     *   { includeReplay: true },
+     * );
+     * ctx.subscriptions.push(sub);
+     * ```
      */
-    subscribeOutput(terminalId: string, handler: (data: string) => void): Disposable;
+    subscribeOutput(terminalId: string, handler: (data: string, origin: OutputOrigin) => void, options?: SubscribeOutputOptions): 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

package/dist/terminal-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"terminal-service.d.ts","sourceRoot":"","sources":["../src/terminal-service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"terminal-service.d.ts","sourceRoot":"","sources":["../src/terminal-service.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@silo-code/sdk",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "description": "The public, types-first SDK for building Silo extensions — the only surface third-party extensions import.",
   "license": "MIT",
   "author": "Dave Weaver",

package/src/ActivityGlyph.tsx

@@ -1,6 +1,7 @@
-import type { HTMLAttributes } from "react";
+import type { CSSProperties, HTMLAttributes } from "react";
 import {
   activityClass,
+  activityJitterStyle,
   type Activity as ActivityKind,
   type ActivitySize,
 } from "./activity";
@@ -13,10 +14,14 @@ import {
  * Styled purely via host-provided `.silo-activity*` classes — no stylesheet
  * import is needed in the extension.
  *
+ * Pass `jitterKey` whenever several animated glyphs render together (a list of
+ * agent or workspace rows) so their pulses don't run in lockstep — and so each
+ * one starts mid-cycle instead of freezing on first paint.
+ *
  * @example
  * ```tsx
  * <ActivityGlyph activity="working" size="md" />
- * <ActivityGlyph activity="ready" />
+ * <ActivityGlyph activity="ready" jitterKey={row.id} />
  * <ActivityGlyph size="sm" /> // workspace neutral (omit)
  * ```
  *
@@ -27,15 +32,31 @@ export function ActivityGlyph({
   activity,
   size = "sm",
   className,
+  jitterKey,
+  style,
   ...rest
 }: {
   activity?: ActivityKind;
   size?: ActivitySize;
+  /**
+   * Stable id (a row or terminal id — never an array index) that gives this
+   * glyph a deterministic per-instance animation offset. Desynchronizes its
+   * pulse from other glyphs rendered alongside it, and makes the animation
+   * mount already in progress rather than pausing on first paint (a WebKit
+   * quirk when the glyph appears inside a just-shown container). Inert on
+   * non-animated glyphs.
+   */
+  jitterKey?: string;
 } & Omit<HTMLAttributes<HTMLSpanElement>, "children">) {
   const classes = activityClass(activity, size);
+  const mergedStyle =
+    jitterKey != null
+      ? ({ ...activityJitterStyle(jitterKey), ...style } as CSSProperties)
+      : style;
   return (
     <span
       className={className ? `${classes} ${className}` : classes}
+      style={mergedStyle}
       aria-hidden={rest["aria-label"] == null ? true : undefined}
       {...rest}
     />

package/src/activity.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, it } from "vitest";
-import { activityClass, activityFromAgent } from "./activity";
+import {
+  activityClass,
+  activityFromAgent,
+  activityJitterStyle,
+} from "./activity";
 
 describe("activityClass", () => {
   it("maps kinds and sizes", () => {
@@ -33,3 +37,32 @@ describe("activityFromAgent", () => {
     expect(activityFromAgent("dead")).toBeNull();
   });
 });
+
+describe("activityJitterStyle", () => {
+  const delay = (key: string) =>
+    Number.parseFloat(activityJitterStyle(key)["--silo-activity-jitter"]);
+
+  it("is deterministic for a given key", () => {
+    expect(activityJitterStyle("term-42")).toEqual(
+      activityJitterStyle("term-42"),
+    );
+  });
+
+  it("spreads different keys across the cycle", () => {
+    const keys = ["a", "b", "c", "d", "e", "term-1", "ws:build", "term-2"];
+    const delays = keys.map(delay);
+    // Not all landing on the same offset (the lockstep bug).
+    expect(new Set(delays).size).toBeGreaterThan(1);
+  });
+
+  it("emits a negative delay within one animation period", () => {
+    for (const key of ["", "x", "a-very-long-stable-row-identifier", "ws:1"]) {
+      const d = delay(key);
+      expect(d).toBeLessThanOrEqual(0);
+      expect(d).toBeGreaterThan(-1.8);
+      expect(activityJitterStyle(key)["--silo-activity-jitter"]).toMatch(
+        /^-?\d+\.\d{3}s$/,
+      );
+    }
+  });
+});

package/src/activity.ts

@@ -11,8 +11,11 @@ import type { AgentActivity } from "./agents-service";
 export type Activity = "working" | "ready" | "warn" | "error";
 
 /**
- * Glyph size for {@link Activity}. `"sm"` matches workspace status rows (~6px);
- * `"md"` is slightly larger for CenterDock / SideDock tabs.
+ * Glyph size for {@link Activity}. `"sm"` (8px at the default `uiFontSize`) is
+ * the workbench size — workspace status rows and CenterDock / SideDock tabs;
+ * `"md"` (10px) is the roomier one, for a list that leads with the dot rather
+ * than tucking it into chrome. Both scale with `uiFontSize` rather than being
+ * fixed pixels.
  *
  * @category Core Types
  * @public
@@ -55,3 +58,35 @@ export function activityClass(
   const kind = activity ?? "none";
   return `silo-activity silo-activity-${kind} silo-activity-${size}`;
 }
+
+/**
+ * Deterministic per-instance `animation-delay` (via the `--silo-activity-jitter`
+ * custom property) for an animated {@link Activity} glyph, keyed off a stable id
+ * — a row or terminal id, not an array index. Two purposes:
+ *
+ * - **Desync.** Several `working` / `ready` glyphs rendered side by side would
+ *   otherwise pulse in perfect lockstep; a per-id offset staggers them.
+ * - **Start mid-cycle.** The value is a *negative* delay, so the animation
+ *   mounts already in progress rather than pausing on first paint — a WebKit
+ *   quirk that bites when the glyph is created inside a container that was
+ *   `display: none` moments earlier (e.g. a Navigator view on its first
+ *   activation), where a zero delay can leave the pulse frozen until the next
+ *   show/hide toggle.
+ *
+ * Hashed rather than random so the offset is stable across re-renders. Pinned
+ * by unit tests.
+ *
+ * @internal
+ */
+export function activityJitterStyle(
+  key: string,
+): Record<"--silo-activity-jitter", string> {
+  let hash = 0;
+  for (let i = 0; i < key.length; i++) {
+    hash = (hash * 31 + key.charCodeAt(i)) | 0;
+  }
+  // 1.8s is the longest activity animation period (`silo-activity-wave`), so the
+  // offset spans one full cycle.
+  const delaySeconds = -(((hash >>> 0) % 1000) / 1000) * 1.8;
+  return { "--silo-activity-jitter": `${delaySeconds.toFixed(3)}s` };
+}

package/src/agents-service.ts

@@ -172,6 +172,187 @@ export interface CatalogAgentSummary {
   readonly icon?: AgentIcon;
 }
 
+/**
+ * One **Agent Profile** as an extension may read it through
+ * {@link AgentProfilesService.list} — a named recipe for starting a coding
+ * agent in a terminal, defined by the user on Settings → Agents → Profiles.
+ * Deliberately a summary, never the host's own profile record: the command
+ * line, its config directory, and every other launch detail stay host-owned
+ * (RFC 0033).
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export interface AgentProfileSummary {
+  /** Stable id — pass it to {@link AgentProfilesService.launch}. */
+  readonly id: string;
+  /** The user's own name for this profile, e.g. `"Claude (work)"`. Show this;
+   *  never show or parse the id. */
+  readonly label: string;
+  /** True for the single profile marked default, which is what `launch()`
+   *  starts when no `profileId` is given. False for every profile when the
+   *  user has not chosen one. */
+  readonly isDefault: boolean;
+  /**
+   * Whether this profile's agent can be given an **opening prompt**. A static
+   * fact about the agent, not about any particular launch — so a picker can
+   * grey out or annotate a profile up front instead of discovering
+   * `"agent-takes-none"` after the user has already typed one.
+   */
+  readonly acceptsPrompt: boolean;
+}
+
+/**
+ * Why an opening prompt could not be delivered. Silo refuses rather than
+ * approximating: a prompt it cannot quote exactly is never typed, and no agent
+ * is started without the prompt the caller asked for.
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export type PromptRefusal =
+  /** The profile matches no agent Silo knows, so there is no way to tell how
+   *  its CLI takes a prompt. The user can fix this by setting the agent on the
+   *  profile. */
+  | "no-agent"
+  /** The profile's agent has no way to accept an opening prompt while staying
+   *  interactive. Check {@link AgentProfileSummary.acceptsPrompt} first to
+   *  avoid offering a prompt for such a profile at all. */
+  | "agent-takes-none"
+  /** Silo has no exact quoting rule for the shell this terminal would run and
+   *  will not guess one. bash, zsh, and fish are supported. */
+  | "unsupported-shell"
+  /**
+   * The prompt exceeds Silo's 2 KiB limit — roughly a page of prose.
+   *
+   * The ceiling is low because the prompt is *typed* into the user's shell,
+   * and a shell with syntax highlighting or autosuggestions cannot reliably
+   * consume more than a few KiB in one go. Silo refuses well short of where
+   * delivery starts failing, because a truncated prompt would reach the agent
+   * looking complete. Trim it and retry.
+   */
+  | "too-large";
+
+/**
+ * Options for {@link AgentProfilesService.launch}. Every field is optional —
+ * a bare `launch()` starts the default profile in the active workspace.
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export interface LaunchAgentProfileOptions {
+  /** Which profile to start. Defaults to the one marked default, else the
+   *  first — the same profile the built-in "New Agent" command uses. */
+  profileId?: string;
+  /** Which workspace to start it in. Defaults to the active one. A
+   *  background workspace works: the session is spawned eagerly, since no
+   *  panel will mount to do it. */
+  workspaceId?: string;
+  /** Working directory for the new terminal. Defaults to the workspace folder. */
+  cwd?: string;
+  /**
+   * An opening prompt to hand the agent on its launch line.
+   *
+   * The text is delivered as a literal — it is never interpreted by the
+   * shell, so `$HOME`, backticks, quotes, and newlines are all safe. If Silo
+   * cannot deliver it exactly, the launch is **refused** rather than mangled
+   * or silently dropped: nothing is typed, no terminal is created, and
+   * `launch()` returns the reason.
+   *
+   * Keep it to an opening instruction. The limit is **2 KiB** — about a page —
+   * and anything longer is refused with `"too-large"`; see that member for
+   * why the ceiling is where it is.
+   *
+   * The composed line is typed into the user's own interactive shell, so it
+   * appears in scrollback and in shell history exactly as if they had typed
+   * it. Don't put a secret in one.
+   */
+  prompt?: string;
+  /**
+   * Activate the target workspace and focus the new terminal. Defaults to
+   * `true`. Pass `false` to start an agent without stealing the user's place.
+   */
+  activate?: boolean;
+}
+
+/**
+ * What {@link AgentProfilesService.launch} did. A **result**, never a throw:
+ * every foreseeable reason a launch cannot happen is a value you can branch
+ * on and report to your own user.
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export type LaunchAgentProfileResult =
+  | {
+      readonly ok: true;
+      /** The created terminal's record id — the same id
+       *  {@link AgentsService.getByTerminalId} and `ctx.terminals` take. */
+      readonly terminalId: string;
+    }
+  | {
+      readonly ok: false;
+      /** Why nothing was launched. `"no-profile"` — the named profile does
+       *  not exist, or there are no profiles at all. `"no-workspace"` — the
+       *  named workspace does not exist, or none is open. Otherwise one of the
+       *  {@link PromptRefusal} reasons. */
+      readonly refusal: PromptRefusal | "no-profile" | "no-workspace";
+    };
+
+/**
+ * Read the user's **Agent Profiles** and start one, optionally with an opening
+ * prompt — exposed as `ctx.agents.profiles` (RFC 0033).
+ *
+ * A profile is a way to *start* a terminal, not a way to talk to an agent:
+ * what comes up is a PTY running a real agent CLI, exactly as if the user had
+ * typed the command themselves. There is no agent-agnostic messaging layer
+ * here and there is not meant to be one.
+ *
+ * There is deliberately no `pick()` — build one from `list()` and
+ * `ctx.ui.showMenu`, which is the shared chrome — and no `get()`, which is
+ * `list().find()`.
+ *
+ * @example
+ * ```ts
+ * // Let the user choose a profile, then start it on a task.
+ * const profiles = ctx.agents.profiles.list();
+ * const chosen = await ctx.ui.showMenu(
+ *   profiles.map((p) => ({ id: p.id, label: p.label })),
+ * );
+ * if (chosen) {
+ *   const result = ctx.agents.profiles.launch({
+ *     profileId: chosen,
+ *     prompt: "Fix the failing test in src/foo.test.ts",
+ *   });
+ *   if (!result.ok) ctx.ui.notify("warn", `Couldn't start it: ${result.refusal}`);
+ * }
+ * ```
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export interface AgentProfilesService {
+  /**
+   * Every Agent Profile the user has defined, in the order they appear in
+   * Settings. The returned array is **read-only and deeply frozen**; it is
+   * recomputed when the profile list changes, not on every call.
+   */
+  list(): readonly AgentProfileSummary[];
+  /**
+   * Start a profile in a terminal. Returns the created terminal's id, or a
+   * typed refusal — see {@link LaunchAgentProfileResult}.
+   *
+   * A refused prompt creates nothing at all: no terminal record, no workspace
+   * activation, no focus change.
+   */
+  launch(options?: LaunchAgentProfileOptions): LaunchAgentProfileResult;
+}
+
 /**
  * Host-computed coding-agent observability — exposed as
  * {@link ExtensionContext.agents}. Detection (what OSC/output signals mean
@@ -250,4 +431,13 @@ export interface AgentsService {
    * @public
    */
   catalog(): readonly CatalogAgentSummary[];
+  /**
+   * The user's **Agent Profiles** — read them, and start one, optionally with
+   * an opening prompt. See {@link AgentProfilesService}.
+   *
+   * @category Consumer Services
+   * @public
+   * @beta
+   */
+  readonly profiles: AgentProfilesService;
 }

package/src/extension-storage.ts

@@ -35,6 +35,25 @@ export interface ExtensionStorage {
   subscribe(listener: () => void): Disposable;
 }
 
+/**
+ * One workspace's per-extension storage directory, as returned by
+ * {@link ExtensionStorageScopes.workspaceDirs}: the workspace's id paired with
+ * the absolute path to that workspace's directory for the calling extension.
+ *
+ * @category Core Types
+ * @public
+ */
+export interface WorkspaceStorageDir {
+  /** The workspace this directory belongs to. */
+  readonly workspaceId: string;
+  /**
+   * Absolute path to `~/.config/silo/extension-storage/<your-id>/workspaces/<workspaceId>`.
+   * Readable and writable through {@link ExtensionContext.files} with no
+   * `fs:*` permission, like every other own-storage path.
+   */
+  readonly dir: string;
+}
+
 /**
  * The persisted-storage scopes available to an extension, exposed as
  * {@link ExtensionContext.storage}: two key/value bags for settings-sized
@@ -87,22 +106,53 @@ export interface ExtensionStorageScopes {
    */
   globalDir(): Promise<string>;
   /**
-   * An absolute path to a directory of your own scoped to the **active
-   * workspace** — the filesystem counterpart to
-   * {@link ExtensionStorageScopes.workspace}. Created on first call, at
+   * An absolute path to a directory of your own scoped to a **workspace** — the
+   * filesystem counterpart to {@link ExtensionStorageScopes.workspace}. Lives at
    * `~/.config/silo/extension-storage/<your-id>/workspaces/<workspaceId>`.
    *
    * Everything {@link ExtensionStorageScopes.globalDir} says about permissions
-   * and relative paths applies here too. Call it again after the active
-   * workspace changes — the path changes with it, so don't cache it across a
-   * workspace switch.
+   * and relative paths applies here too.
+   *
+   * @param workspaceId - Which workspace's directory to resolve. Omit for the
+   *   **active** workspace — the path then changes as the active workspace
+   *   switches, so don't cache it across a switch, and the call rejects with
+   *   `NoWorkspaceError` when no workspace is open. Pass an id (from
+   *   {@link ExtensionContext.workspaces}) to resolve **any** workspace's
+   *   directory, active or not — the aggregating case (a view over every
+   *   workspace's data).
+   * @param options - `create` (default `true`) creates the directory if it is
+   *   missing, matching the historical behaviour — every caller that then
+   *   **writes** into the path needs this, because {@link FileService.writeText}
+   *   does not create parent directories. Pass `create: false` when you only
+   *   need the path to **read** from (a missing file already reads as absent);
+   *   nothing is written to disk for a workspace that has no data yet.
    *
    * The directory follows the workspace's **identity**, not its folder path:
    * deleting a workspace and re-adding the same folder gives you a new, empty
    * directory (the same rule {@link ExtensionStorageScopes.workspace} follows).
    * Deleting a workspace leaves the directory on disk.
+   */
+  workspaceDir(
+    workspaceId?: string,
+    options?: { create?: boolean },
+  ): Promise<string>;
+  /**
+   * Resolve a storage directory for **every open workspace** in one call — the
+   * building block for a surface that aggregates per-workspace data (a
+   * cross-workspace list, say) without making a separate
+   * {@link ExtensionStorageScopes.workspaceDir} call per workspace.
+   *
+   * Returns one entry per workspace in
+   * {@link WorkspaceService.getState}`().open`, each `{ workspaceId, dir }`.
+   * There is no ordering guarantee — match entries to workspaces by
+   * `workspaceId`.
    *
-   * Rejects with `NoWorkspaceError` when no workspace is open.
+   * @param options - `create` (default `true`) behaves exactly as it does on
+   *   {@link ExtensionStorageScopes.workspaceDir}. The aggregating case passes
+   *   `create: false`: it only reads each workspace's data, so no directory is
+   *   created for a workspace that has none.
    */
-  workspaceDir(): Promise<string>;
+  workspaceDirs(options?: {
+    create?: boolean;
+  }): Promise<readonly WorkspaceStorageDir[]>;
 }

package/src/index.ts

@@ -110,6 +110,11 @@ export type {
   AgentIcon,
   AgentIconMode,
   CatalogAgentSummary,
+  AgentProfilesService,
+  AgentProfileSummary,
+  LaunchAgentProfileOptions,
+  LaunchAgentProfileResult,
+  PromptRefusal,
 } from "./agents-service";
 export type {
   TerminalService,
@@ -119,6 +124,8 @@ export type {
   TerminalTabDecoration,
   TerminalTabDecorationProvider,
   OscEvent,
+  OutputOrigin,
+  SubscribeOutputOptions,
 } from "./terminal-service";
 export type {
   TabAdornmentColor,
@@ -190,6 +197,7 @@ export type {
 export type {
   ExtensionStorage,
   ExtensionStorageScopes,
+  WorkspaceStorageDir,
 } from "./extension-storage";
 // The drag-and-drop domain: the consumer service + its payload/handler shapes.
 // DND_MIME is a value (the well-known MIME vocabulary), so it's a runtime export.

package/src/process-service.ts

@@ -1,4 +1,5 @@
 import type { Disposable } from "./types";
+import type { OutputOrigin, SubscribeOutputOptions } from "./terminal-service";
 
 // `ctx.process` — persistent process / PTY sessions that survive app restarts.
 // The core primitive under the terminal (and future task runners / REPLs).
@@ -59,8 +60,20 @@ export interface ProcessSession {
   getBuffer(): Promise<string>;
   /** Persist an output buffer for later restore. */
   saveBuffer(data: string): Promise<void>;
-  /** Subscribe to output data. Dispose to stop listening. */
-  onData(listener: (data: string) => void): Disposable;
+  /**
+   * Subscribe to output data. Dispose to stop listening.
+   *
+   * By default only **live** output is delivered. A session survives app
+   * restarts, so re-attaching to one replays its recent scrollback; delivering
+   * that by default would make every reattach look like a burst of output
+   * arriving right now. Pass `{ includeReplay: true }` to receive the replayed
+   * history too — for instance to paint scrollback into a fresh view — and read
+   * `origin.replay` to tell the two apart.
+   */
+  onData(
+    listener: (data: string, origin: OutputOrigin) => void,
+    options?: SubscribeOutputOptions,
+  ): Disposable;
   /** Subscribe to session exit. Dispose to stop listening. */
   onExit(listener: (exitCode: number) => void): Disposable;
 }