@silo-code/sdk 0.51.0 → 0.53.0

package/dist/use-panel-entry-focus.js

@@ -0,0 +1,186 @@
+import { useCallback, useEffect, useRef } from "react";
+// Entry focus for a dock panel — landing the caret in the panel's content when
+// the user enters it.
+//
+// A freshly-mounted or newly-activated dock panel does NOT reliably inherit DOM
+// focus: dockview runs its own focus shuffle when panels mount/activate, and
+// rich content (Monaco, xterm) only accepts focus once its internal textarea
+// has been laid out with non-zero dimensions. A single `focus()` call loses
+// these races, which is why a panel would otherwise need a second click before
+// you can type. We retry across animation frames until the target actually
+// reports focus, the panel is no longer the one we wanted to focus, or we hit a
+// frame cap (~330ms) so we never loop forever when focus legitimately can't be
+// grabbed (panel hidden, content disabled, etc.).
+const DEFAULT_CAP = 20;
+// Every menu implementation whose open state must suppress the retry: Silo's
+// own menus (`ctx.ui.showMenu`, which renders `[data-silo-menu]` with
+// `role="menu"`), a third-party menu that follows the same ARIA role, and
+// Monaco's context menu (`.context-view` / `.monaco-menu`).
+const MENU_SELECTOR = '[data-silo-menu], [role="menu"], .context-view, .monaco-menu';
+/**
+ * Whether focus currently sits inside an open floating menu. Monaco renders its
+ * context menu into a shadow root, where `document.activeElement` resolves only
+ * to the open `shadow-root-host` and the menu nodes hang off its `shadowRoot` —
+ * hence the shadow peek, not just a light-DOM `closest`.
+ */
+function focusInMenu(active) {
+    if (!active)
+        return false;
+    if (active.closest(MENU_SELECTOR))
+        return true;
+    return active.shadowRoot?.querySelector(MENU_SELECTOR) != null;
+}
+/**
+ * Repeatedly call `focus()` on successive animation frames until `isFocused()`
+ * returns true, `stillWanted()` returns false, or `cap` frames have elapsed.
+ *
+ * `stillWanted` is **required**, and must express "this panel is still the one
+ * that should hold focus" — normally `() => api.isActive`, or the center
+ * dock's focus-intent token (`focusGen`). It is deliberately not optional: a
+ * retry loop without it keeps grabbing focus for its entire frame budget no
+ * matter what else happened meanwhile. That matters most on *mount*, because
+ * re-entering a workspace re-mounts its panels — so an unguarded mount-time
+ * grab in a background tab yanks focus away from the tab the user actually
+ * left active. And because DOM focus landing inside a dockview panel makes
+ * dockview mark that panel's group active
+ * (`contentContainer.onDidFocus → doSetGroupActive`), stealing focus silently
+ * changes the visible active tab too. That was symptom 1 in ADR 0034.
+ *
+ * Panel content should reach for {@link usePanelEntryFocus} instead, which
+ * supplies the guard and both entry subscriptions for you. This raw form is
+ * host/`core.*` plumbing for the non-React callers that can't.
+ *
+ * @internal
+ */
+export function retryFocus(focus, isFocused, stillWanted, cap = DEFAULT_CAP) {
+    let attempts = 0;
+    let landed = false;
+    const tick = () => {
+        // Bail before touching focus if we're no longer wanted — a newer focus
+        // intent superseded us (e.g. the user kept pressing the region-cycle chord).
+        // Checked here, not just after the grab below, so a stale retry can't yank
+        // focus back from the area the user actually moved to.
+        if (!stillWanted())
+            return;
+        attempts += 1;
+        if (isFocused()) {
+            landed = true;
+        }
+        else {
+            // Before focus first lands, grab aggressively each frame — Monaco/xterm
+            // only accept focus once their textarea is laid out, so early calls lose.
+            // After it has landed, only re-grab if focus fell to NOTHING (<body>/null):
+            // dockview's show/hide shuffle can bounce focus off the just-focused
+            // content a frame or two later (the "keystrokes dropped after a switch"
+            // symptom). We watch the full frame budget to catch that — but never yank
+            // focus away from another real element the user may have moved to.
+            const active = document.activeElement;
+            // Focus legitimately moved into an open context menu — don't yank it
+            // back, or the menu's focus-out dismiss fires and it flashes shut.
+            // Right-clicking an *inactive* panel activates it, which starts this
+            // retry; without the guard the per-frame `focus()` steals focus from the
+            // just-opened menu (the focused case never starts the retry, which is why
+            // the bug only shows when the panel was unfocused). End the loop: the
+            // menu's owner restores content focus itself once the menu closes.
+            if (focusInMenu(active))
+                return;
+            const lostToNothing = active === null || active === document.body;
+            if (!landed || lostToNothing)
+                focus();
+        }
+        if (attempts >= cap || !stillWanted())
+            return;
+        requestAnimationFrame(tick);
+    };
+    requestAnimationFrame(tick);
+}
+/**
+ * Land keyboard focus in a dock panel's content whenever the user enters the
+ * panel, winning dockview's focus shuffle — and, symmetrically, release it when
+ * the panel's tab is deactivated.
+ *
+ * A panel that puts the cursor somewhere on entry (a chat composer, a search
+ * box, an editor) needs three things that are easy to get individually wrong,
+ * and this hook is all three in one call:
+ *
+ * 1. **Both entry signals.** {@link DockPanelApi.onDidActiveChange} covers real
+ *    activations. {@link DockPanelApi.onDidRequestFocus} covers a click on a
+ *    tab that was *already* active — dockview treats that as a complete no-op
+ *    and fires no active-change event, even though it is the commonest way a
+ *    user asks for the cursor back (they were typing in a side panel, clicked
+ *    the status bar, then clicked your tab).
+ * 2. **A guard.** Focus is only ever taken while the panel is the active one.
+ *    Mount is not "the user just created this panel" — re-entering a workspace
+ *    re-mounts every panel in its dock — and DOM focus landing in a panel makes
+ *    dockview activate its group, so an unguarded grab silently changes the
+ *    visible tab (ADR 0034).
+ * 3. **A retry.** A single `focus()` loses dockview's shuffle, and rich content
+ *    only accepts focus once its internal textarea is laid out. The hook
+ *    retries across frames until focus lands, standing down if the panel stops
+ *    being active or focus moves into an open context menu.
+ *
+ * ```tsx
+ * function AcmeChatPanel({ api }: DockPanelProps) {
+ *   const input = useRef<HTMLTextAreaElement | null>(null);
+ *
+ *   usePanelEntryFocus(api, {
+ *     focus: () => input.current?.focus(),
+ *     isFocused: () => document.activeElement === input.current,
+ *   });
+ *
+ *   return <textarea ref={input} />;
+ * }
+ * ```
+ *
+ * The returned function runs the same guarded retry on demand, for content that
+ * becomes focusable at a moment that is neither a mount nor an activation — a
+ * session finishing its connect, an editor finishing its own mount. It is
+ * referentially stable, so it is safe in a dependency array:
+ *
+ * ```tsx
+ * const focusComposer = usePanelEntryFocus(api, { focus, isFocused });
+ *
+ * useEffect(() => {
+ *   if (ready) focusComposer();
+ * }, [ready, focusComposer]);
+ * ```
+ *
+ * @param api - The surrounding panel's api ({@link DockPanelProps.api}).
+ * @param target - How to focus, test, and release the panel's content.
+ * @returns A stable callback that runs the guarded focus retry on demand.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export function usePanelEntryFocus(api, target) {
+    // Read the callbacks through a ref rather than closing over them: the
+    // subscription effect depends on `api` alone (re-subscribing every render
+    // would be worse), so a captured `target` would freeze at its first render
+    // and an author's inline `() => { if (enabled) … }` would go stale.
+    const latest = useRef(target);
+    useEffect(() => {
+        latest.current = target;
+    });
+    const focusNow = useCallback(() => {
+        if (!api.isActive)
+            return;
+        retryFocus(() => latest.current.focus(), () => latest.current.isFocused(), () => api.isActive);
+    }, [api]);
+    useEffect(() => {
+        const subActive = api.onDidActiveChange(() => {
+            if (api.isActive)
+                focusNow();
+            else
+                latest.current.blur?.();
+        });
+        // `focusNow` guards on `isActive` itself: a Focus Request says only that
+        // the user asked, never that this panel became active.
+        const subRequest = api.onDidRequestFocus(focusNow);
+        return () => {
+            subActive.dispose();
+            subRequest.dispose();
+        };
+    }, [api, focusNow]);
+    return focusNow;
+}
+//# sourceMappingURL=use-panel-entry-focus.js.map

package/dist/use-panel-entry-focus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-panel-entry-focus.js","sourceRoot":"","sources":["../src/use-panel-entry-focus.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@silo-code/sdk",
-  "version": "0.51.0",
+  "version": "0.53.0",
   "description": "The public, types-first SDK for building Silo extensions — the only surface third-party extensions import.",
   "license": "MIT",
   "author": "Dave Weaver",
@@ -36,10 +36,10 @@
     "react": "^19.1.0",
     "react-dom": "^19.1.0"
   },
-  "dependencies": {},
   "devDependencies": {
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.0",
+    "jsdom": "^29.1.1",
     "typescript": "~5.8.3",
     "vitest": "^4.1.7"
   },

package/src/agents-service.ts

@@ -96,6 +96,25 @@ export interface AgentInfo {
   readonly terminalId?: string;
   /** The workspace this session belongs to. */
   readonly workspaceId: string;
+  /**
+   * Where this session is currently working — an absolute path, or `undefined`
+   * while it is not yet known.
+   *
+   * Host-computed for both kinds, which is the point: a Terminal session fills
+   * it from the working directory of its foreground process, and a Chat session
+   * from the **working checkout** the host derives for it. A consumer that
+   * wants to show "where is this agent" reads this one field and does not care
+   * which kind it got.
+   *
+   * For a Chat session this is *not* simply the `cwd` the session was started
+   * with. That value is fixed at `session/new` — the Agent Client Protocol has
+   * no working-directory-change notification — but agents relocate anyway, most
+   * commonly by creating a git worktree and moving into it. The host reports
+   * the session's start directory until it has evidence the agent has moved,
+   * and every moved-to directory is confirmed to be a real checkout before it
+   * is reported here.
+   */
+  readonly cwd?: string;
   /**
    * The session's display label — host-computed, the same string for either
    * kind, and the one a consumer should render. A status row, a navigator row
@@ -192,9 +211,6 @@ export interface AgentInfo {
    *   release — the user runs `resumeCommand` themselves; the flag is the
    *   forward-looking capability signal RFC 0038 replaces the shell-string
    *   `resumeCommand` contract with.
-   * - Chat session: `true` when the agent advertises `session/load`, so a
-   *   fresh process can reload the transcript after the old one died.
-   *
    * - Chat session: `true` when the agent advertises **either**
    *   `sessionCapabilities.resume` or `agentCapabilities.loadSession` (RFC
    *   0042) — the two are distinct capabilities (see {@link ChatResumeState})
@@ -357,6 +373,16 @@ export interface AgentProfileSummary {
    * be offered a profile that cannot work in the surface they are looking at.
    */
   readonly interface: AgentSessionKind;
+  /**
+   * The catalog agent this profile resolves to, if any — the same id
+   * {@link AgentsService.catalog} keys on, and the same resolution
+   * {@link AgentSessionHandle.agentId} reports once a Chat session is live
+   * (the profile's explicit assertion, or an auto-detect match from its
+   * command line). Look up {@link CatalogAgentSummary.icon} with it to show
+   * a profile's brand mark in a picker *before* connecting — `undefined`
+   * when the profile resolves to no known agent.
+   */
+  readonly agentId?: string;
 }
 
 /**
@@ -739,6 +765,30 @@ export interface AgentPlanEntry {
   readonly priority?: string;
 }
 
+/**
+ * Session context/cost state from a `usage_update` — the protocol's own
+ * `used` / `size` naming. **Sender-optional**: many agents never emit this,
+ * and those that do report `used` and `size` differently (recon), so a
+ * missing {@link AgentSessionUpdate.usage} on a given update is normal, not
+ * an error — never synthesize a reading when the agent hasn't sent one.
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export interface AgentSessionUsage {
+  /** Tokens currently consumed in the session context. */
+  readonly used: number;
+  /** Total token capacity for the session. */
+  readonly size: number;
+  /** Cumulative session cost, when the agent reports one. */
+  readonly cost?: {
+    readonly amount: number;
+    /** ISO 4217 currency code, e.g. `"USD"`. */
+    readonly currency: string;
+  };
+}
+
 /**
  * One `session/update` notification from a **Chat session**, lightly
  * normalized. The Agent Client Protocol streams a turn as a sequence of these:
@@ -751,8 +801,9 @@ export interface AgentPlanEntry {
  *
  * Everything a Chat UI must draw to render a transcript is a modelled field:
  * {@link text} / {@link content} for the message kinds, {@link toolCall} for
- * `tool_call` and `tool_call_update`, {@link plan} for `plan`. {@link raw} is
- * for what is deliberately left out — see its own note.
+ * `tool_call` and `tool_call_update`, {@link plan} for `plan`, {@link usage}
+ * for `usage_update`. {@link raw} is for what is deliberately left out — see
+ * its own note.
  *
  * @category Consumer Services
  * @public
@@ -798,13 +849,18 @@ export interface AgentSessionUpdate {
    * showing rather than appending to it. May be empty.
    */
   readonly plan?: readonly AgentPlanEntry[];
+  /**
+   * Session context/cost state, for `kind` `"usage_update"`; `undefined`
+   * otherwise, and also whenever the connected agent doesn't send this
+   * notification at all — see {@link AgentSessionUsage}.
+   */
+  readonly usage?: AgentSessionUsage;
   /**
    * The raw Agent Client Protocol `update` object — the **escape hatch**, for
    * the kinds and fields this surface does not model.
    *
    * What is deliberately not modelled, and why: `available_commands_update`
    * (an agent's slash commands — a menu, not a transcript row),
-   * `usage_update` (token counts, which no agent reports the same way),
    * `current_mode_update` (already surfaced as
    * {@link AgentSessionConfigOption.currentValue}), `session_info_update`
    * (already surfaced as {@link AgentInfo.title}), and vendor extensions such
@@ -1055,6 +1111,11 @@ export interface AgentSessionHandle {
    * after the process dies. Mirrors {@link AgentInfo.canResume}.
    */
   readonly canResume: boolean;
+  /**
+   * Whether the agent advertises `session/list` — whether {@link
+   * listSessions} can be called at all (Session Discovery, RFC 0051).
+   */
+  readonly canList: boolean;
   /**
    * How this handle came to be connected (RFC 0042) — see
    * {@link AgentSessionRestore}:
@@ -1170,6 +1231,20 @@ export interface AgentSessionHandle {
    * changes, so there is no change event for it.
    */
   readonly promptCapabilities: AgentPromptCapabilities;
+  /**
+   * Ask the agent what other sessions it knows about (ACP `session/list`, v1
+   * stable) — **Session Discovery** (RFC 0051). Metadata only, not a live
+   * handle: pass a picked {@link AgentSessionSummary.sessionId} back as
+   * {@link AgentSessionRestore.sessionId} on a fresh {@link
+   * AgentSessionsService.connect} to open it — the same restore flow as any
+   * other resume.
+   *
+   * Rejects when {@link canList} is `false` — check it before calling, the
+   * same way a caller checks {@link canResume} before offering resume. Also
+   * rejects when {@link resumeOutcome} is `"journal-only"` — there is no live
+   * connection to ask.
+   */
+  listSessions(): Promise<readonly AgentSessionSummary[]>;
   /**
    * Tear the session down: kill the agent process and drop it from
    * {@link AgentsService.getState}. Idempotent. The process is a piped child of
@@ -1179,6 +1254,30 @@ export interface AgentSessionHandle {
   dispose(): void;
 }
 
+/**
+ * One session an agent reports via `session/list` (ACP v1 stable) —
+ * **Session Discovery** (RFC 0051). Metadata only, not a live handle.
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export interface AgentSessionSummary {
+  /** What to pass as {@link AgentSessionRestore.sessionId} to resume this
+   *  one. */
+  readonly sessionId: string;
+  /** The working directory this session ran in, when the agent reports one —
+   *  may differ from the current session's own cwd. */
+  readonly cwd?: string;
+  /** A display title, when the agent reports one. */
+  readonly title?: string;
+  /** Last-activity timestamp (ISO 8601), when the agent reports one. */
+  readonly updatedAt?: string;
+  /** The agent's own `SessionInfo` object, untouched — the escape hatch for
+   *  a vendor field this type does not model. */
+  readonly raw: Record<string, unknown>;
+}
+
 /**
  * Options for {@link AgentSessionsService.connect}.
  *

package/src/index.ts

@@ -6,9 +6,9 @@
  *
  * **What's here:** the types-first extension contract (see `types.ts`) plus a
  * small set of blessed runtime helpers (`Tooltip`, the modal design-system
- * kit, `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.
+ * kit, `useFocusGroup`, `usePanelEntryFocus`, `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.
@@ -122,11 +122,13 @@ export type {
   AgentSessionHandle,
   AgentSessionConnectOptions,
   AgentSessionRestore,
+  AgentSessionSummary,
   ChatResumeState,
   AgentPromptBlock,
   AgentPromptResult,
   AgentStopReason,
   AgentSessionUpdate,
+  AgentSessionUsage,
   AgentContentBlock,
   AgentToolCall,
   AgentToolCallContent,
@@ -356,10 +358,19 @@ export type {
   FocusGroupNavQuery,
 } from "./use-focus-group";
 
-// Host/InlineEdit coordination for InlineEdit's two-stage Escape (RFC 0016).
+// Entry focus for a dock panel (RFC 0049): both entry signals + the
+// `isActive`-guarded frame retry that wins dockview's focus shuffle, in one
+// call. The one sanctioned way for panel content to take focus on entry.
+export { usePanelEntryFocus } from "./use-panel-entry-focus";
+export type { PanelEntryFocusTarget } from "./use-panel-entry-focus";
+
+// Host/InlineEdit coordination for InlineEdit's two-stage Escape (RFC 0016),
+// and the raw focus retry behind `usePanelEntryFocus` for the non-React
+// callers that can't use the hook (RFC 0049).
 // @internal — host-only plumbing, not part of the documented reference;
 // extension authors never call these directly.
 export {
   setActiveInlineEditCancel,
   yieldEscapeToInlineEdit,
 } from "./inline-edit-controller";
+export { retryFocus } from "./use-panel-entry-focus";

package/src/types.ts

@@ -90,6 +90,37 @@ export interface DockPanelApi {
   onDidActiveChange(
     listener: (event: { readonly isActive: boolean }) => void,
   ): Disposable;
+  /**
+   * Subscribe to the user asking, by gesture, for keyboard focus in this
+   * panel — fired on every click of its tab, including one that leaves
+   * {@link DockPanelApi.isActive | isActive} unchanged because the tab was
+   * already active.
+   *
+   * That already-active case is why the event exists: it has no other signal.
+   * {@link DockPanelApi.onDidActiveChange | onDidActiveChange} only fires on a
+   * real transition, so clicking back into an already-active tab from
+   * elsewhere (a side panel, the status bar) is otherwise silent even though
+   * the user's intent — "put keyboard focus here" — is identical to a genuine
+   * activation. A panel that drives its own entry focus from
+   * `onDidActiveChange` should drive it from this event too, guarded on
+   * `isActive`, so both paths land focus the same way.
+   *
+   * The name is the intent, but today exactly one gesture carries it:
+   *
+   * - **Fires** on a primary click of this panel's tab, whether or not the
+   *   panel was already the active one.
+   * - **Does not fire** for activation from anywhere else —
+   *   {@link DockPanelApi.setActive | setActive}, a keybinding, a command or
+   *   command-palette jump, or the host restoring a saved layout. Those change
+   *   which panel is active, so they surface as `onDidActiveChange` instead;
+   *   none of them reaches this event.
+   * - **Does not fire** for a click inside the panel's own content (focus
+   *   there is yours to manage), the tab's close button, or a middle-click
+   *   close.
+   *
+   * Returns a {@link Disposable} that cancels the subscription.
+   */
+  onDidRequestFocus(listener: () => 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