sh3-core 0.14.0 → 0.15.0

package/dist/shards/types.d.ts

@@ -3,7 +3,8 @@ import type { ZoneSchema, ZoneManager } from '../state/types';
 import type { DocumentHandle, DocumentHandleOptions } from '../documents/types';
 import type { BrowseCapability } from '../documents/browse';
 import type { EnvState } from '../env/types';
-import type { Verb } from '../verbs/types';
+import type { Verb, VerbSchema } from '../verbs/types';
+import type { ScrollbackEntry } from '../shell-shard/scrollback.svelte';
 import type { ShardContextKeys } from '../keys/types';
 import type { ContributionsApi } from '../contributions/types';
 import type { ActionsApi } from '../actions/types';
@@ -251,6 +252,42 @@ export interface ShardContext {
      * entries). Actions are auto-unregistered when the shard deactivates.
      */
     actions: ActionsApi;
+    /**
+     * Read-only snapshot of every verb registered across every active shard.
+     * Returned entries include the contributing `shardId`, the prefixed
+     * `name`, the verb's `summary`, and (when present) its `schema`.
+     * Order is undefined.
+     *
+     * No permission gate — verb names + summaries are already visible via
+     * the `help` verb. Diagnostic and AI-class shards (sh3-ai, sh3-diagnostic)
+     * use this to enumerate the host's action surface.
+     */
+    listVerbs(): Array<{
+        shardId: string;
+        name: string;
+        summary: string;
+        schema?: VerbSchema;
+    }>;
+    /**
+     * Programmatically dispatch a verb by `(shardId, name)`. Resolves with
+     * `{ result, scrollback }` where `scrollback` is the array of entries
+     * the verb pushed during invocation. Rejects on:
+     *   - unknown shardId,
+     *   - unknown verb,
+     *   - target verb not opted in via `programmatic: true`,
+     *   - any error thrown by the verb's `run`.
+     *
+     * Pass `opts.structured` to populate `ctx.structuredArgs` for verbs
+     * that declare `schema.input`. Pass `opts.signal` for cooperative
+     * cancellation (verbs must opt in to honor it).
+     */
+    runVerb(shardId: string, name: string, args: string[], opts?: {
+        signal?: AbortSignal;
+        structured?: unknown;
+    }): Promise<{
+        result: unknown;
+        scrollback: ScrollbackEntry[];
+    }>;
 }
 /**
  * A shard module. Shards are the fundamental unit of contribution in SH3.

package/dist/shell-shard/ScrollbackView.svelte

@@ -11,30 +11,51 @@
   let { scrollback }: Props = $props();
 
   let container: HTMLDivElement | null = $state(null);
+  let content: HTMLDivElement | null = $state(null);
+  let stuck = true;
 
-  // Auto-scroll to bottom on new entries
+  // scrollHeight - scrollTop - clientHeight can settle on small non-zero
+  // values from sub-pixel rounding even when visually at the bottom.
+  const STICK_THRESHOLD_PX = 4;
+
+  function isAtBottom(el: HTMLElement): boolean {
+    return el.scrollHeight - el.scrollTop - el.clientHeight <= STICK_THRESHOLD_PX;
+  }
+
+  function handleScroll(): void {
+    if (container) stuck = isAtBottom(container);
+  }
+
+  // ResizeObserver on the inner content wrapper fires on any layout-affecting
+  // change regardless of source: text-chunk pushes, mutated rich-entry props
+  // (output.stream() / output.rich() handles), image or font load. A reactivity-
+  // driven approach (depending on entries.length or chunk counts) misses rich
+  // streaming because props are mutated via Object.assign and the outer view
+  // never reads them.
   $effect(() => {
-    // Depend on entries length so the effect re-runs
-    const _len = scrollback.entries.length;
-    void _len;
-    if (container) {
-      container.scrollTop = container.scrollHeight;
-    }
+    if (!content || !container) return;
+    const ro = new ResizeObserver(() => {
+      if (container && stuck) container.scrollTop = container.scrollHeight;
+    });
+    ro.observe(content);
+    return () => ro.disconnect();
   });
 </script>
 
-<div class="shell-scrollback" bind:this={container}>
-  {#each scrollback.entries as entry (entry.id)}
-    {#if entry.kind === 'text'}
-      <TextEntry stream={entry.stream} chunks={entry.chunks} />
-    {:else if entry.kind === 'prompt'}
-      <PromptEntry cwd={entry.cwd} line={entry.line} />
-    {:else if entry.kind === 'status'}
-      <StatusEntry text={entry.text} level={entry.level} />
-    {:else if entry.kind === 'rich'}
-      <RichEntry component={entry.component} componentProps={entry.props} />
-    {/if}
-  {/each}
+<div class="shell-scrollback" bind:this={container} onscroll={handleScroll}>
+  <div class="content" bind:this={content}>
+    {#each scrollback.entries as entry (entry.id)}
+      {#if entry.kind === 'text'}
+        <TextEntry stream={entry.stream} chunks={entry.chunks} />
+      {:else if entry.kind === 'prompt'}
+        <PromptEntry cwd={entry.cwd} line={entry.line} />
+      {:else if entry.kind === 'status'}
+        <StatusEntry text={entry.text} level={entry.level} />
+      {:else if entry.kind === 'rich'}
+        <RichEntry component={entry.component} componentProps={entry.props} />
+      {/if}
+    {/each}
+  </div>
 </div>
 
 <style>

package/dist/shell-shard/Terminal.svelte

@@ -9,7 +9,7 @@
   import { TenantFsClient } from './tenant-fs-client';
   import { ShellModeRegistry } from './modes/registry';
   import { registerBuiltinModes } from './modes/builtin';
-  import { resolveInitialMode, writeLastMode } from './modes/prefs';
+  import { readLastMode, resolveInitialMode, writeLastMode } from './modes/prefs';
   import type { ShellMode, ShellRole } from './modes/types';
   import type { ContributionsApi } from '../contributions/types';
   import { SHELL_MODE_CONTRIBUTION_POINT, type ShellModeDescriptor } from './contract';
@@ -22,6 +22,7 @@
   import ModeSlot from './toolbar/slots/ModeSlot.svelte';
   import FocusLockSlot from './toolbar/slots/FocusLockSlot.svelte';
   import TargetShardSlot from './toolbar/slots/TargetShardSlot.svelte';
+  import BusySlot from './toolbar/slots/BusySlot.svelte';
 
   interface Props {
     shell: ShellApi;
@@ -74,9 +75,24 @@
       .map(descriptorToMode),
   ]);
 
-  // Reactive current mode
+  // Resolve against the merged visible set so a persisted contributed-mode
+  // id is honored at boot when its shard activated before this view mounted.
+  // Async activations still land on the role default.
   let mode = $state<ShellMode>(
-    untrack(() => resolveInitialMode(modeRegistry, userId, role)),
+    untrack(() => {
+      const persisted = readLastMode(userId);
+      if (persisted) {
+        const initialVisible: ShellMode[] = [
+          ...modeRegistry.list(role),
+          ...contributedModes
+            .filter((d) => !d.requiresRole || d.requiresRole === role)
+            .map(descriptorToMode),
+        ];
+        const found = initialVisible.find((m) => m.id === persisted);
+        if (found) return found;
+      }
+      return resolveInitialMode(modeRegistry, userId, role);
+    }),
   );
 
   function setMode(id: string): void {
@@ -133,14 +149,44 @@
   // "referenced outside a closure" warning; the URL never changes at runtime.
   const session = untrack(() => new SessionClient(wsUrl));
 
+  // Busy controller — feeds the toolbar spinner. Each call to acquireBusy(label)
+  // adds an entry to the map; the returned disposer removes it. The slot
+  // renders when the map is non-empty.
+  let busyCounter = 0;
+  let busyEntries = $state(new Map<number, string | undefined>());
+
+  function acquireBusy(label?: string): () => void {
+    const id = ++busyCounter;
+    busyEntries.set(id, label);
+    busyEntries = new Map(busyEntries);
+    let cleared = false;
+    return () => {
+      if (cleared) return;
+      cleared = true;
+      busyEntries.delete(id);
+      busyEntries = new Map(busyEntries);
+    };
+  }
+
+  let busyActive = $derived(busyEntries.size > 0);
+  let busyLabel = $derived.by<string | null>(() => {
+    if (busyEntries.size === 0) return null;
+    // Most-recent label wins (insertion-order Map).
+    let last: string | undefined;
+    for (const v of busyEntries.values()) last = v;
+    return last ?? null;
+  });
+
   const { dispatch, cancel: cancelDispatch } = untrack(() => makeDispatch({
     mode: () => mode,
+    role: () => role,
     resolver,
     scrollback,
     session,
     shell: shellWithModes,
     fs,
     cwd: () => session.cwd,
+    busy: acquireBusy,
     customMode: (id: string) => contributedModes.find((d) => d.id === id) ?? null,
   }));
 
@@ -155,8 +201,12 @@
   let focusLocked = $state(false);
   let targetShard = $state<string | null>(null);
 
-  // Toolbar slot registry
+  // Toolbar slot registry. The 'busy' slot is always-visible at the registry
+  // level; the BusySlot component itself gates rendering on `active` so we
+  // don't have to invalidate the toolbar's `slots` derivation when the
+  // spinner toggles (the toolbar re-derives from ctx, not from busyActive).
   const toolbarRegistry = new ToolbarSlotRegistry();
+  toolbarRegistry.register({ id: 'busy', order: 5, visible: () => true, component: BusySlot });
   toolbarRegistry.register({ id: 'mode', order: 10, visible: () => true, component: ModeSlot });
   toolbarRegistry.register({ id: 'focus-lock', order: 20, visible: (ctx) => ctx.mode.id === 'sh3', component: FocusLockSlot });
   toolbarRegistry.register({ id: 'target-shard', order: 30, visible: (ctx) => ctx.mode.id === 'sh3', component: TargetShardSlot });
@@ -271,6 +321,7 @@
     registry={toolbarRegistry}
     ctx={{ mode, role }}
     slotProps={{
+      busy: { active: busyActive, label: busyLabel },
       mode: { mode, modes: visibleModes, onSelect: setMode },
       'focus-lock': { locked: focusLocked, onToggle: () => (focusLocked = !focusLocked) },
       'target-shard': { target: targetShard },

package/dist/shell-shard/contract.d.ts

@@ -50,6 +50,36 @@ export interface ShellModeOutput {
      * or `error()` is called so the renderer can show a loading affordance.
      */
     stream(component: Component<any>, initialProps: Record<string, unknown>): StreamHandle;
+    /**
+     * Show a spinner in the shell header for the duration of a long-running
+     * operation. The optional label is rendered next to the spinner; pass
+     * undefined for an unlabelled indicator. Returns a clear handle — call
+     * clear() exactly once when the operation completes (idempotent).
+     *
+     * The framework already auto-spawns a spinner while a dispatch is in
+     * flight. Use this method for work that runs *outside* a dispatch (e.g.
+     * during the descriptor's `activate()` lifecycle hook, or background
+     * pre-fetching).
+     */
+    busy(label?: string): BusyHandle;
+    /**
+     * Programmatically dispatch a line through another mode's resolution path.
+     *
+     * - `'sh3'` — full sh3 verb resolution (bypasses the mode-gating that
+     *   normally restricts sh3-domain verbs to sh3 mode).
+     * - `'bash'` — forward to the WS session. Lazy-connects on first use.
+     *   Resolves immediately on send (output streams asynchronously to the
+     *   scrollback via the WS protocol).
+     * - any other registered mode id — routes through that mode's `dispatch()`
+     *   handler. Output flows to the same scrollback.
+     *
+     * Throws synchronously on:
+     * - unknown mode id
+     * - role mismatch (e.g. a non-admin context targeting `'bash'`)
+     * - self-invocation (a mode invoking its own id — direct calls into the
+     *   mode's helpers should be used instead)
+     */
+    invoke(modeId: string, line: string): Promise<void>;
 }
 export interface RichEntryHandle {
     /** Patch the entry's props. Triggers Svelte reactivity. */
@@ -63,3 +93,7 @@ export interface StreamHandle {
     /** Mark the stream finished with an error; renders an error status. */
     error(err: unknown): void;
 }
+export interface BusyHandle {
+    /** Remove this busy indicator. Idempotent. */
+    clear(): void;
+}

package/dist/shell-shard/dispatch-custom.test.js

@@ -16,12 +16,14 @@ function makeStubDeps(mode, customMode) {
     return {
         deps: {
             mode: () => mode,
+            role: () => 'user',
             resolver,
             scrollback,
             session,
             shell,
             fs,
             cwd: () => '/',
+            busy: () => () => { },
             customMode,
         },
         pushed,
@@ -102,3 +104,49 @@ describe('dispatch — custom transport', () => {
         expect(err.text).toMatch(/no longer available/);
     });
 });
+describe('dispatch — auto-spinner', () => {
+    it('acquires a busy slot for the duration of a custom-mode dispatch', async () => {
+        let active = 0;
+        let peak = 0;
+        const busy = () => {
+            active++;
+            peak = Math.max(peak, active);
+            return () => { active--; };
+        };
+        let resolveDispatch;
+        const desc = {
+            id: 'gemini',
+            label: 'Gemini',
+            runsOn: 'client',
+            dispatch: () => new Promise((resolve) => {
+                resolveDispatch = resolve;
+            }),
+        };
+        const mode = { id: 'gemini', label: 'Gemini', transport: 'custom', autoRelocate: false };
+        const { deps } = makeStubDeps(mode, () => desc);
+        const { dispatch } = makeDispatch(Object.assign(Object.assign({}, deps), { busy }));
+        const promise = dispatch('hi');
+        // Yield once so the dispatch closure runs through to the await on desc.dispatch
+        await Promise.resolve();
+        expect(peak).toBe(1);
+        expect(active).toBe(1);
+        resolveDispatch();
+        await promise;
+        expect(active).toBe(0);
+    });
+    it('clears busy when the dispatch handler throws', async () => {
+        let active = 0;
+        const busy = () => { active++; return () => { active--; }; };
+        const desc = {
+            id: 'gemini',
+            label: 'Gemini',
+            runsOn: 'client',
+            dispatch: async () => { throw new Error('kaboom'); },
+        };
+        const mode = { id: 'gemini', label: 'Gemini', transport: 'custom', autoRelocate: false };
+        const { deps } = makeStubDeps(mode, () => desc);
+        const { dispatch } = makeDispatch(Object.assign(Object.assign({}, deps), { busy }));
+        await dispatch('hi');
+        expect(active).toBe(0);
+    });
+});

package/dist/shell-shard/dispatch-gating.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shell-shard/dispatch-gating.test.js

@@ -0,0 +1,63 @@
+import { describe, it, expect, vi } from 'vitest';
+import { makeDispatch } from './dispatch';
+const appsVerb = { name: 'apps', summary: '', async run() { } };
+const clearVerb = {
+    name: 'clear',
+    summary: '',
+    globalVerb: true,
+    async run(ctx) {
+        ctx.scrollback.push({ kind: 'status', text: 'cleared', level: 'info', ts: 0 });
+    },
+};
+function scaffold(mode) {
+    const sent = [];
+    const pushed = [];
+    const scrollback = { push: (e) => pushed.push(e), clear: () => { } };
+    const session = { history: { push: vi.fn() }, send: (m) => sent.push(m), cwd: '/', connected: true, connect: vi.fn() };
+    const fs = {};
+    const shell = {};
+    // Real-shape resolver to exercise the new globalOnly path.
+    const resolver = {
+        resolve: (line, opts = {}) => {
+            const head = line.trim().split(/\s+/)[0];
+            const verb = head === 'apps' ? appsVerb : head === 'clear' ? clearVerb : null;
+            if (!verb)
+                return { kind: 'forward', line };
+            if (opts.globalOnly && !verb.globalVerb)
+                return { kind: 'forward', line };
+            return { kind: 'local', verb, args: [], line };
+        },
+    };
+    const { dispatch } = makeDispatch({
+        mode: () => mode,
+        role: () => (mode.requiresRole === 'admin' ? 'admin' : 'user'),
+        resolver,
+        scrollback,
+        session,
+        shell,
+        fs,
+        cwd: () => '/',
+        busy: () => () => { },
+    });
+    return { dispatch, sent, pushed };
+}
+describe('dispatch — mode-gated verb resolution', () => {
+    const sh3Mode = { id: 'sh3', label: 'SH3', transport: 'none', autoRelocate: true };
+    const bashMode = { id: 'bash', label: 'Bash', transport: 'ws', autoRelocate: false, requiresRole: 'admin' };
+    it('sh3 mode resolves sh3-domain verbs locally', async () => {
+        const { dispatch, sent } = scaffold(sh3Mode);
+        await dispatch('apps');
+        expect(sent).toEqual([]);
+    });
+    it('bash mode forwards sh3-domain verbs to ws', async () => {
+        const { dispatch, sent } = scaffold(bashMode);
+        await dispatch('apps');
+        expect(sent.some((m) => m.t === 'submit' && m.line === 'apps')).toBe(true);
+    });
+    it('bash mode runs globalVerb (clear) locally', async () => {
+        const { dispatch, sent, pushed } = scaffold(bashMode);
+        await dispatch('clear');
+        expect(sent.every((m) => m.t !== 'submit')).toBe(true);
+        expect(pushed.some((e) => e.kind === 'status' && e.text === 'cleared')).toBe(true);
+    });
+});

package/dist/shell-shard/dispatch-invoke.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shell-shard/dispatch-invoke.test.js

@@ -0,0 +1,214 @@
+import { describe, it, expect, vi } from 'vitest';
+import { makeDispatch } from './dispatch';
+const openVerb = {
+    name: 'open',
+    summary: '',
+    async run(ctx, args) {
+        var _a;
+        ctx.scrollback.push({ kind: 'status', text: `opened:${(_a = args[0]) !== null && _a !== void 0 ? _a : ''}`, level: 'info', ts: 0 });
+    },
+};
+function scaffold(opts) {
+    const sent = [];
+    const pushed = [];
+    const connectSpy = vi.fn();
+    const scrollback = { push: (e) => pushed.push(e), clear: () => { } };
+    const session = {
+        history: { push: vi.fn() },
+        send: (m) => sent.push(m),
+        cwd: '/',
+        connect: connectSpy,
+    };
+    const fs = {};
+    const shell = {};
+    const resolver = {
+        resolve: (line, _opts = {}) => {
+            const head = line.trim().split(/\s+/)[0];
+            const rest = line.trim().split(/\s+/).slice(1);
+            if (head === 'open')
+                return { kind: 'local', verb: openVerb, args: rest, line };
+            return { kind: 'forward', line };
+        },
+    };
+    const { dispatch } = makeDispatch({
+        mode: () => opts.current,
+        role: () => opts.role,
+        resolver,
+        scrollback,
+        session,
+        shell,
+        fs,
+        cwd: () => '/',
+        busy: () => () => { },
+        customMode: (id) => { var _a, _b; return (_b = (_a = opts.customs) === null || _a === void 0 ? void 0 : _a.find((d) => d.id === id)) !== null && _b !== void 0 ? _b : null; },
+    });
+    return { dispatch, sent, pushed, connectSpy };
+}
+const customMode = (id) => ({ id, label: id, transport: 'custom', autoRelocate: false });
+describe('output.invoke — sh3 target', () => {
+    it('runs an sh3 verb when invoked from a custom mode', async () => {
+        const captured = [];
+        const customs = [{
+                id: 'gemini',
+                label: 'Gemini',
+                runsOn: 'client',
+                dispatch: async (_input, output) => {
+                    await output.invoke('sh3', 'open foo.md');
+                    captured.push('after-invoke');
+                },
+            }];
+        const { dispatch, pushed } = scaffold({
+            current: customMode('gemini'),
+            role: 'user',
+            customs,
+        });
+        await dispatch('hello');
+        expect(pushed.some((e) => e.kind === 'status' && e.text === 'opened:foo.md')).toBe(true);
+        expect(captured).toEqual(['after-invoke']);
+    });
+    it('throws for unknown sh3 verb', async () => {
+        let caught;
+        const customs = [{
+                id: 'gemini',
+                label: 'Gemini',
+                runsOn: 'client',
+                dispatch: async (_input, output) => {
+                    try {
+                        await output.invoke('sh3', 'nonexistent');
+                    }
+                    catch (e) {
+                        caught = e;
+                    }
+                },
+            }];
+        const { dispatch } = scaffold({ current: customMode('gemini'), role: 'user', customs });
+        await dispatch('hello');
+        expect(caught).toBeInstanceOf(Error);
+        expect(caught.message).toMatch(/unknown sh3 verb/);
+    });
+});
+describe('output.invoke — bash target', () => {
+    it('admin invocation lazy-connects and forwards', async () => {
+        const customs = [{
+                id: 'gemini',
+                label: 'Gemini',
+                runsOn: 'client',
+                dispatch: async (_input, output) => {
+                    await output.invoke('bash', 'ls');
+                },
+            }];
+        const { dispatch, sent, connectSpy } = scaffold({
+            current: customMode('gemini'),
+            role: 'admin',
+            customs,
+        });
+        await dispatch('hello');
+        expect(connectSpy).toHaveBeenCalledTimes(1);
+        expect(sent.some((m) => m.t === 'submit' && m.line === 'ls')).toBe(true);
+    });
+    it('lazy-connect only fires once across multiple invokes', async () => {
+        const customs = [{
+                id: 'gemini',
+                label: 'Gemini',
+                runsOn: 'client',
+                dispatch: async (_input, output) => {
+                    await output.invoke('bash', 'ls');
+                    await output.invoke('bash', 'pwd');
+                },
+            }];
+        const { dispatch, connectSpy } = scaffold({
+            current: customMode('gemini'),
+            role: 'admin',
+            customs,
+        });
+        await dispatch('hello');
+        expect(connectSpy).toHaveBeenCalledTimes(1);
+    });
+    it('non-admin invoking bash throws', async () => {
+        let caught;
+        const customs = [{
+                id: 'gemini',
+                label: 'Gemini',
+                runsOn: 'client',
+                dispatch: async (_input, output) => {
+                    try {
+                        await output.invoke('bash', 'ls');
+                    }
+                    catch (e) {
+                        caught = e;
+                    }
+                },
+            }];
+        const { dispatch } = scaffold({ current: customMode('gemini'), role: 'user', customs });
+        await dispatch('hello');
+        expect(caught).toBeInstanceOf(Error);
+        expect(caught.message).toMatch(/admin role/);
+    });
+});
+describe('output.invoke — guards', () => {
+    it('self-invoke throws', async () => {
+        let caught;
+        const customs = [{
+                id: 'gemini',
+                label: 'Gemini',
+                runsOn: 'client',
+                dispatch: async (_input, output) => {
+                    try {
+                        await output.invoke('gemini', 'foo');
+                    }
+                    catch (e) {
+                        caught = e;
+                    }
+                },
+            }];
+        const { dispatch } = scaffold({ current: customMode('gemini'), role: 'user', customs });
+        await dispatch('hello');
+        expect(caught).toBeInstanceOf(Error);
+        expect(caught.message).toMatch(/cannot invoke own mode/);
+    });
+    it('unknown custom mode throws', async () => {
+        let caught;
+        const customs = [{
+                id: 'gemini',
+                label: 'Gemini',
+                runsOn: 'client',
+                dispatch: async (_input, output) => {
+                    try {
+                        await output.invoke('claude', 'foo');
+                    }
+                    catch (e) {
+                        caught = e;
+                    }
+                },
+            }];
+        const { dispatch } = scaffold({ current: customMode('gemini'), role: 'user', customs });
+        await dispatch('hello');
+        expect(caught).toBeInstanceOf(Error);
+        expect(caught.message).toMatch(/unknown mode/);
+    });
+});
+describe('output.invoke — custom target', () => {
+    it('routes through the target descriptor dispatch with the same scrollback', async () => {
+        const customs = [
+            {
+                id: 'gemini',
+                label: 'Gemini',
+                runsOn: 'client',
+                dispatch: async (_input, output) => {
+                    await output.invoke('claude', 'hi');
+                },
+            },
+            {
+                id: 'claude',
+                label: 'Claude',
+                runsOn: 'client',
+                dispatch: async (input, output) => {
+                    output.text('stdout', `claude:${input.line}\n`);
+                },
+            },
+        ];
+        const { dispatch, pushed } = scaffold({ current: customMode('gemini'), role: 'user', customs });
+        await dispatch('hello');
+        expect(pushed.some((e) => { var _a, _b; return e.kind === 'text' && ((_b = (_a = e.chunks) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.includes('claude:hi')); })).toBe(true);
+    });
+});

package/dist/shell-shard/dispatch.d.ts

@@ -2,16 +2,24 @@ import type { VerbRegistry, ShellApi } from './registry';
 import type { Scrollback } from './scrollback.svelte';
 import type { SessionClient } from './session-client.svelte';
 import type { TenantFsClient } from './tenant-fs-client';
-import type { ShellMode } from './modes/types';
+import type { ShellMode, ShellRole } from './modes/types';
 import type { ShellModeDescriptor } from './contract';
 export interface DispatchDeps {
     mode: () => ShellMode;
+    /** Current shell role — used by invoke() role-gating. */
+    role: () => ShellRole;
     resolver: VerbRegistry;
     scrollback: Scrollback;
     session: SessionClient;
     shell: ShellApi;
     fs: TenantFsClient;
     cwd: () => string;
+    /**
+     * Acquire a busy indicator. Returns a clear handle. Calling clear()
+     * multiple times is safe (idempotent). Used internally to auto-spawn
+     * a spinner around custom-mode dispatch and exposed via output.busy().
+     */
+    busy: (label?: string) => () => void;
     /**
      * Look up a contributed mode descriptor by id. Called only when the active
      * mode has `transport: 'custom'`. Returns null if the descriptor has been