@smooai/smooth-extension-sdk 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smooai/smooth-extension-sdk",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "TypeScript SDK for building Smooth Extension Protocol (SEP) extensions: `defineExtension`, `defineTool`, a stdio JSON-RPC transport, an in-process test host, and a conformance runner. Extensions are subprocesses speaking JSON-RPC 2.0 ndjson to any SEP host (smooth-operator-core and its polyglot servers).",
   "license": "MIT",
   "type": "module",

package/src/conformance.ts

@@ -115,6 +115,8 @@ export async function runConformance(opts: RunConformanceOptions): Promise<Confo
         await check('initialize', method.INITIALIZE, initParams(fixtures), 'methods/initialize.schema.json#/$defs/Result');
         await check('ping', method.PING, {}, 'methods/ping.schema.json#/$defs/Result');
         await check('tool/execute', method.TOOL_EXECUTE, fixtures.tool_execute_params!.instance, 'methods/tool-execute.schema.json#/$defs/Result');
+        await check('command/execute', method.COMMAND_EXECUTE, fixtures.command_execute_params!.instance, 'methods/command-execute.schema.json#/$defs/Result');
+        await check('command/complete', method.COMMAND_COMPLETE, fixtures.command_complete_params!.instance, 'methods/command-complete.schema.json#/$defs/Result');
         await check('shutdown', method.SHUTDOWN, {}, 'methods/shutdown.schema.json#/$defs/Result');
     } finally {
         peer.close();

package/src/extension.ts

@@ -11,14 +11,32 @@
  * into them without breaking the tool path.
  */
 import { Peer } from './jsonrpc.js';
-import { PROTOCOL_VERSION, method } from './protocol.js';
+import { PROTOCOL_VERSION, eventName, method } from './protocol.js';
 import type {
+    CommandCompleteParams,
+    CommandCompleteResult,
+    CommandExecuteParams,
+    CommandExecuteResult,
+    CommandRegistration,
+    Completion,
     Context,
+    DeliverAs,
     EventParams,
     HookOutcome,
     HookParams,
     InitializeParams,
     InitializeResult,
+    BusEventPayload,
+    MessageRendererRegistration,
+    RenderBlock,
+    ProviderCompleteParams,
+    ProviderCompleteResult,
+    ProviderCredentials,
+    ProviderModel,
+    ProviderOAuthParams,
+    ProviderRegistration,
+    ProviderStreamEvent,
+    ShortcutRegistration,
     ToolExecuteParams,
     ToolExecuteResult,
     ToolUpdateParams,
@@ -47,10 +65,24 @@ export interface UiApi {
     input(prompt: string, opts?: { default?: string }): Promise<UiRequestResult>;
     notify(message: string, level?: 'info' | 'warn' | 'error'): Promise<void>;
     setStatus(status: string): Promise<void>;
-    setWidget(widget: Record<string, unknown>): Promise<void>;
+    /** Render a Phase 8 render block. Use a `widget`-kind block (with keybindings)
+     *  for the interactive tier and re-call on each `widget/key` to re-render. */
+    setWidget(widget: RenderBlock): Promise<void>;
     setTitle(title: string): Promise<void>;
 }
 
+/**
+ * The inter-extension event bus (Phase 8), mirroring pi's `events`. `publish`
+ * fans a `{topic, payload}` out to every *other* extension subscribed to
+ * `bus/event`; `on` subscribes to one topic (a filtered `bus/event`). Requires
+ * the `bus` capability to publish and a `bus/event` events subscription (added
+ * automatically when you call `on`) to receive.
+ */
+export interface EventsApi {
+    publish(topic: string, payload?: unknown): void;
+    on(topic: string, handler: (payload: unknown, from: string) => void): void;
+}
+
 /** Build a [`UiApi`] that speaks `ui/request` over `peer`. */
 function makeUi(peer: Peer): UiApi {
     const req = (params: UiRequestParams) => peer.request<UiRequestResult>(method.UI_REQUEST, params);
@@ -73,6 +105,45 @@ function makeUi(peer: Peer): UiApi {
     };
 }
 
+/**
+ * Session-mutating ext→host actions. Available only from a COMMAND-tier context
+ * (command handlers) — the host rejects them from an event-tier context with
+ * -32003 ContextViolation. `sendMessage` posts a message, `sendUserMessage`
+ * delivers a user message (steer/follow_up/next_turn), `appendEntry` persists an
+ * LLM-invisible transcript entry.
+ */
+export interface SessionApi {
+    sendMessage(text: string, opts?: { role?: 'user' | 'assistant' }): Promise<void>;
+    sendUserMessage(text: string, opts?: { deliverAs?: DeliverAs }): Promise<void>;
+    appendEntry(entry: Record<string, unknown>): Promise<void>;
+    /** Switch the active model (Phase 7). `provider` targets an extension-
+     *  registered provider; `thinking` sets a reasoning level. */
+    setModel(model: string, opts?: { provider?: string; thinking?: string }): Promise<void>;
+}
+
+/** Build a [`SessionApi`] bound to `context` (must be command-tier) over `peer`. */
+function makeSession(peer: Peer, context: Context): SessionApi {
+    return {
+        sendMessage: async (text, opts) => {
+            await peer.request(method.SESSION_SEND_MESSAGE, { context, text, ...(opts?.role ? { role: opts.role } : {}) });
+        },
+        sendUserMessage: async (text, opts) => {
+            await peer.request(method.SESSION_SEND_USER_MESSAGE, { context, text, ...(opts?.deliverAs ? { deliver_as: opts.deliverAs } : {}) });
+        },
+        appendEntry: async (entry) => {
+            await peer.request(method.SESSION_APPEND_ENTRY, { context, entry });
+        },
+        setModel: async (model, opts) => {
+            await peer.request(method.SESSION_SET_MODEL, {
+                context,
+                model,
+                ...(opts?.provider ? { provider: opts.provider } : {}),
+                ...(opts?.thinking ? { thinking: opts.thinking } : {}),
+            });
+        },
+    };
+}
+
 /** Progress + cancellation handed to a tool while it runs. */
 export interface ToolContext {
     /** Correlates `onUpdate` calls with this execution. */
@@ -105,6 +176,100 @@ export function defineTool<TArgs = Record<string, unknown>>(def: ToolDef<TArgs>)
     return def;
 }
 
+/** What a command handler receives: the command-tier context plus the session,
+ *  ui, and args bound to it. Session actions are valid because a command runs at
+ *  command tier. */
+export interface CommandContext {
+    /** The dispatch context (command tier). */
+    context: Context;
+    /** Free-form arguments parsed from the invocation. */
+    args: Record<string, unknown> | undefined;
+    /** Session-mutating actions, bound to this command's context. */
+    session: SessionApi;
+    /** Ask the frontend to render a dialog/widget. See [`UiApi`]. */
+    ui: UiApi;
+    /** True if the host's frontend can render this `ui/request` kind. */
+    hasUI(kind: UiKind): boolean;
+    /** Structured log line into host tracing. */
+    log(level: 'debug' | 'info' | 'warn' | 'error', message: string, fields?: Record<string, unknown>): void;
+}
+
+/** What a command's `execute` may return: text to surface, a full result, or
+ *  nothing. */
+export type CommandReturn = CommandExecuteResult | string | void;
+
+export interface CommandDef {
+    name: string;
+    description: string;
+    execute(ctx: CommandContext): Promise<CommandReturn> | CommandReturn;
+    /** Optional argument autocomplete: given the partial text, return candidates. */
+    complete?(partial: string, context: Context): Promise<Completion[]> | Completion[];
+}
+
+/** Identity helper for `registerCommand` call sites. */
+export function defineCommand(def: CommandDef): CommandDef {
+    return def;
+}
+
+/** A CLI/slash flag the extension declares. The host delivers its parsed value
+ *  in `initialize`; read it with `smooth.getFlag(name)`. */
+export interface FlagDef {
+    name: string;
+    description?: string;
+}
+
+// --- providers (Phase 7) -------------------------------------------------
+
+/** One LLM completion the host asked this provider to run. `messages`/`tools`
+ *  are the host's opaque serialized shapes. */
+export interface ProviderCompleteRequest {
+    /** Correlates streamed deltas with this request. */
+    requestId: string;
+    model: string;
+    messages: Record<string, unknown>[];
+    tools: Record<string, unknown>[];
+    /** OpenAI-compatible `response_format` when structured output is requested. */
+    responseFormat?: Record<string, unknown>;
+    /** Reasoning/thinking level (`off`/`low`/`medium`/`high`/provider token). */
+    thinking?: string;
+    /** True when the host wants streamed `delta`s. */
+    stream: boolean;
+}
+
+/** Progress + UI handed to a provider `complete`/oauth call. */
+export interface ProviderContext {
+    /** The dispatch context (epoch token + tier). */
+    context: Context;
+    /** Fires if the host `$/cancel`s the request. */
+    signal: AbortSignal;
+    /** Stream one chunk back to the host. Only meaningful when `stream` is set;
+     *  a no-op storm otherwise (the host drops deltas for a non-streamed call). */
+    delta(event: ProviderStreamEvent): void;
+    /** Ask the frontend to render a dialog (OAuth: open a URL, prompt for a code). */
+    ui: UiApi;
+    hasUI(kind: UiKind): boolean;
+    log(level: 'debug' | 'info' | 'warn' | 'error', message: string, fields?: Record<string, unknown>): void;
+}
+
+export interface ProviderDef {
+    name: string;
+    baseUrl?: string;
+    apiKeyEnv?: string;
+    models: ProviderModel[];
+    /** Run one completion. Emit `ctx.delta(...)` while streaming, then return the
+     *  final result. */
+    complete(req: ProviderCompleteRequest, ctx: ProviderContext): Promise<ProviderCompleteResult> | ProviderCompleteResult;
+    /** Run the OAuth login handshake, driving user interaction via `ctx.ui`. */
+    oauthLogin?(ctx: ProviderContext): Promise<ProviderCredentials> | ProviderCredentials;
+    /** Exchange a refresh token for fresh credentials. */
+    oauthRefresh?(refreshToken: string, ctx: ProviderContext): Promise<ProviderCredentials> | ProviderCredentials;
+}
+
+/** Identity helper for `registerProvider` call sites. */
+export function defineProvider(def: ProviderDef): ProviderDef {
+    return def;
+}
+
 /** A hook handler's friendly return: veto the operation, or replace its input
  *  with a patch (shallow-merged onto the input). Returning nothing = continue. */
 export type HookResult = { block: true; reason?: string } | { patch: Record<string, unknown> };
@@ -119,8 +284,24 @@ export interface SmoothApi {
     name: string;
     version: string;
     registerTool(tool: ToolDef<any>): void;
+    /** Register a slash-command surfaced in the host's `/` palette. */
+    registerCommand(command: CommandDef): void;
+    /** Declare a CLI/slash flag; read its delivered value with [`getFlag`]. */
+    registerFlag(flag: FlagDef): void;
+    /** Bind a keyboard shortcut (TUI frontends) to a registered command. */
+    registerShortcut(shortcut: ShortcutRegistration): void;
+    /** Contribute an LLM provider to the host's model surface (Phase 7). */
+    registerProvider(provider: ProviderDef): void;
+    /** Register a declarative custom-message renderer (Phase 8): a message `tag`
+     *  → render-block template with `{{path}}` placeholders. */
+    registerMessageRenderer(tag: string, template: RenderBlock): void;
+    /** The inter-extension event bus (Phase 8). */
+    readonly events: EventsApi;
     on(event: string, handler: EventHandler): void;
     log(level: 'debug' | 'info' | 'warn' | 'error', message: string, fields?: Record<string, unknown>): void;
+    /** The parsed value the host delivered for a declared flag (undefined before
+     * `initialize`, or when the host has no CLI surface). */
+    getFlag(name: string): unknown;
     /** True if the host's frontend can render this `ui/request` kind. Only
      * meaningful after `initialize` — returns false before the handshake. */
     hasUI(kind: UiKind): boolean;
@@ -138,13 +319,20 @@ export interface ConnectHandle {
 
 export class Extension {
     private readonly tools = new Map<string, ToolDef<any>>();
+    private readonly commands = new Map<string, CommandDef>();
+    private readonly flagDefs = new Map<string, FlagDef>();
+    private readonly shortcuts: ShortcutRegistration[] = [];
+    private readonly providers = new Map<string, ProviderDef>();
     private readonly events = new Map<string, EventHandler[]>();
+    private readonly messageRenderers: MessageRendererRegistration[] = [];
     private name = 'extension';
     private version = '0.0.0';
     /** Set once connected so `log()` before connect is a safe no-op. */
     private live?: Peer;
     /** UI kinds the host declared answerable at `initialize`. */
     private hostUiCaps: string[] = [];
+    /** Flag values the host delivered at `initialize` (name → value). */
+    private flagValues: Record<string, unknown> = {};
 
     constructor(setup: ExtensionSetup) {
         const api: SmoothApi = {
@@ -163,6 +351,41 @@ export class Extension {
             registerTool: (tool) => {
                 this.tools.set(tool.name, tool);
             },
+            registerCommand: (command) => {
+                this.commands.set(command.name, command);
+            },
+            registerFlag: (flag) => {
+                this.flagDefs.set(flag.name, flag);
+            },
+            registerShortcut: (shortcut) => {
+                this.shortcuts.push(shortcut);
+            },
+            registerProvider: (provider) => {
+                this.providers.set(provider.name, provider);
+            },
+            registerMessageRenderer: (tag, template) => {
+                this.messageRenderers.push({ tag, template });
+            },
+            get events(): EventsApi {
+                return {
+                    publish: (topic, payload) => {
+                        // A request (not a notification) so it reaches the host's
+                        // bus/publish handler; fire-and-forget — we don't await it.
+                        void self.live?.request(method.BUS_PUBLISH, { topic, ...(payload !== undefined ? { payload } : {}) });
+                    },
+                    on: (topic, handler) => {
+                        // Subscribing to a topic is a filtered `bus/event` observe
+                        // subscription; registering it puts `bus/event` in our
+                        // subscriptions so the host delivers the fanout.
+                        const list = self.events.get(eventName.BUS_EVENT) ?? [];
+                        list.push((payload) => {
+                            const p = payload as BusEventPayload | undefined;
+                            if (p && p.topic === topic) handler(p.payload, p.from);
+                        });
+                        self.events.set(eventName.BUS_EVENT, list);
+                    },
+                };
+            },
             on: (event, handler) => {
                 const list = this.events.get(event) ?? [];
                 list.push(handler);
@@ -171,6 +394,7 @@ export class Extension {
             log: (level, message, fields) => {
                 this.live?.notify(method.LOG, { level, message, ...(fields ? { fields } : {}) });
             },
+            getFlag: (name) => self.flagValues[name],
             hasUI: (kind) => self.hostUiCaps.includes(kind),
             get ui() {
                 if (!self.live) throw new Error('smooth.ui is only available after the extension connects');
@@ -195,6 +419,11 @@ export class Extension {
         });
         peer.setRequestHandler(method.TOOL_EXECUTE, (params, signal) => this.executeTool(params as ToolExecuteParams, peer, signal));
         peer.setRequestHandler(method.HOOK, (params) => this.dispatchHook(params as HookParams));
+        peer.setRequestHandler(method.COMMAND_EXECUTE, (params) => this.executeCommand(params as CommandExecuteParams, peer));
+        peer.setRequestHandler(method.COMMAND_COMPLETE, (params) => this.completeCommand(params as CommandCompleteParams));
+        peer.setRequestHandler(method.PROVIDER_COMPLETE, (params, signal) => this.providerComplete(params as ProviderCompleteParams, peer, signal));
+        peer.setRequestHandler(method.PROVIDER_OAUTH_LOGIN, (params, signal) => this.providerOAuth(params as ProviderOAuthParams, peer, signal, false));
+        peer.setRequestHandler(method.PROVIDER_OAUTH_REFRESH, (params, signal) => this.providerOAuth(params as ProviderOAuthParams, peer, signal, true));
         peer.setNotificationHandler(method.EVENT, (params) => this.dispatchEvent(params as EventParams));
 
         transport.start((frame) => peer.receive(frame));
@@ -217,22 +446,115 @@ export class Extension {
 
     private initialize(params: InitializeParams): InitializeResult {
         this.hostUiCaps = params.ui_capabilities ?? [];
+        this.flagValues = params.flags ?? {};
         const tools = [...this.tools.values()].map((t) => ({
             name: t.name,
             description: t.description,
             parameters: toJsonSchema(t.parameters),
             ...(t.deferred ? { deferred: true } : {}),
         }));
+        const commands: CommandRegistration[] = [...this.commands.values()].map((c) => ({ name: c.name, description: c.description }));
+        const flags = [...this.flagDefs.keys()];
         // Only observe events go in `subscriptions` — hook names are intercepts
         // the host always calls, not events it filters by subscription.
         const subscriptions = [...this.events.keys()].filter((name) => !HOOK_NAMES.has(name));
+        // Declare the hooks we handle (Phase 8) so the host can skip the per-turn
+        // `context` hook when nobody handles it.
+        const hooks = [...this.events.keys()].filter((name) => HOOK_NAMES.has(name));
+        const providers: ProviderRegistration[] = [...this.providers.values()].map((p) => ({
+            name: p.name,
+            ...(p.baseUrl ? { base_url: p.baseUrl } : {}),
+            ...(p.apiKeyEnv ? { api_key_env: p.apiKeyEnv } : {}),
+            // `oauth` is derived: an extension supports it iff it implements login.
+            ...(p.oauthLogin ? { oauth: true } : {}),
+            models: p.models,
+        }));
         return {
             protocol_version: PROTOCOL_VERSION,
             extension: { name: this.name, version: this.version },
-            registrations: { tools, subscriptions },
+            registrations: {
+                tools,
+                ...(commands.length ? { commands } : {}),
+                ...(flags.length ? { flags } : {}),
+                ...(this.shortcuts.length ? { shortcuts: this.shortcuts } : {}),
+                ...(providers.length ? { providers } : {}),
+                ...(hooks.length ? { hooks } : {}),
+                ...(this.messageRenderers.length ? { message_renderers: this.messageRenderers } : {}),
+                subscriptions,
+            },
         };
     }
 
+    /** Build the shared context for a provider request. `delta` is a no-op here —
+     *  only `providerComplete` streams, and it overrides `delta` with the bound
+     *  request_id. */
+    private providerContext(peer: Peer, context: Context, signal: AbortSignal): ProviderContext {
+        return {
+            context,
+            signal,
+            delta: () => {},
+            ui: makeUi(peer),
+            hasUI: (kind) => this.hostUiCaps.includes(kind),
+            log: (level, message, fields) => peer.notify(method.LOG, { level, message, ...(fields ? { fields } : {}) }),
+        };
+    }
+
+    private async providerComplete(params: ProviderCompleteParams, peer: Peer, signal: AbortSignal): Promise<ProviderCompleteResult> {
+        const provider = this.providers.get(params.provider);
+        if (!provider) throw new Error(`unknown provider: ${params.provider}`);
+        const base = this.providerContext(peer, params.context ?? { token: '', tier: 'command' }, signal);
+        // Bind the request_id into delta so handlers can just call `ctx.delta(event)`.
+        const ctx: ProviderContext = {
+            ...base,
+            delta: (event) => peer.notify(method.PROVIDER_DELTA, { request_id: params.request_id, event }),
+        };
+        const req: ProviderCompleteRequest = {
+            requestId: params.request_id,
+            model: params.model,
+            messages: params.messages,
+            tools: params.tools ?? [],
+            ...(params.response_format ? { responseFormat: params.response_format } : {}),
+            ...(params.thinking ? { thinking: params.thinking } : {}),
+            stream: params.stream ?? false,
+        };
+        return provider.complete(req, ctx);
+    }
+
+    private async providerOAuth(params: ProviderOAuthParams, peer: Peer, signal: AbortSignal, refresh: boolean): Promise<ProviderCredentials> {
+        const provider = this.providers.get(params.provider);
+        if (!provider) throw new Error(`unknown provider: ${params.provider}`);
+        const ctx = this.providerContext(peer, params.context ?? { token: '', tier: 'command' }, signal);
+        if (refresh) {
+            if (!provider.oauthRefresh) throw new Error(`provider ${params.provider} does not support oauth refresh`);
+            return provider.oauthRefresh(params.refresh_token ?? '', ctx);
+        }
+        if (!provider.oauthLogin) throw new Error(`provider ${params.provider} does not support oauth login`);
+        return provider.oauthLogin(ctx);
+    }
+
+    private async executeCommand(params: CommandExecuteParams, peer: Peer): Promise<CommandExecuteResult> {
+        const command = this.commands.get(params.command);
+        if (!command) return { content: `unknown command: ${params.command}` };
+        const ctx: CommandContext = {
+            context: params.context,
+            args: params.arguments,
+            session: makeSession(peer, params.context),
+            ui: makeUi(peer),
+            hasUI: (kind) => this.hostUiCaps.includes(kind),
+            log: (level, message, fields) => peer.notify(method.LOG, { level, message, ...(fields ? { fields } : {}) }),
+        };
+        const out = await command.execute(ctx);
+        if (out === undefined) return {};
+        return typeof out === 'string' ? { content: out } : out;
+    }
+
+    private async completeCommand(params: CommandCompleteParams): Promise<CommandCompleteResult> {
+        const command = this.commands.get(params.command);
+        if (!command?.complete) return { completions: [] };
+        const completions = await command.complete(params.partial ?? '', params.context);
+        return { completions };
+    }
+
     private async executeTool(params: ToolExecuteParams, peer: Peer, signal: AbortSignal): Promise<ToolExecuteResult> {
         const tool = this.tools.get(params.tool);
         if (!tool) return { content: `unknown tool: ${params.tool}`, is_error: true };

package/src/index.ts

@@ -8,10 +8,30 @@
  * `createTestHost`, and gate it against the shared fixtures with
  * `runConformance`.
  */
-export { defineExtension, defineTool, Extension } from './extension.js';
-export type { ExtensionSetup, SmoothApi, ToolDef, ToolContext, ToolReturn, EventHandler, HookResult, ConnectHandle, UiApi } from './extension.js';
+export { defineExtension, defineTool, defineCommand, defineProvider, Extension } from './extension.js';
+export { render } from './render.js';
+export type {
+    ExtensionSetup,
+    SmoothApi,
+    EventsApi,
+    ToolDef,
+    ToolContext,
+    ToolReturn,
+    CommandDef,
+    CommandContext,
+    CommandReturn,
+    FlagDef,
+    ProviderDef,
+    ProviderContext,
+    ProviderCompleteRequest,
+    SessionApi,
+    EventHandler,
+    HookResult,
+    ConnectHandle,
+    UiApi,
+} from './extension.js';
 export { createTestHost } from './test-host.js';
-export type { TestHost, CallToolOptions, CreateTestHostOptions, UiResponder } from './test-host.js';
+export type { TestHost, CallToolOptions, CreateTestHostOptions, UiResponder, BusPublish, SessionCall } from './test-host.js';
 export { runConformance, DEFAULT_SPEC_DIR } from './conformance.js';
 export type { ConformanceReport, ConformanceStep, RunConformanceOptions } from './conformance.js';
 export { toJsonSchema } from './schema.js';
@@ -20,12 +40,17 @@ export { Peer, RpcError } from './jsonrpc.js';
 export type { JsonRpcFrame } from './jsonrpc.js';
 export { stdioTransport, linkedPair } from './transport.js';
 export type { Transport } from './transport.js';
-export { PROTOCOL_VERSION, method, errorCode } from './protocol.js';
+export { PROTOCOL_VERSION, eventName, method, errorCode } from './protocol.js';
 export type {
     Context,
     InitializeParams,
     InitializeResult,
     Registrations,
+    MessageRendererRegistration,
+    RenderBlock,
+    Keybinding,
+    BusEventPayload,
+    WidgetKeyPayload,
     ToolRegistration,
     ToolExecuteParams,
     ToolExecuteResult,
@@ -36,4 +61,26 @@ export type {
     UiKind,
     UiRequestParams,
     UiRequestResult,
+    ShortcutRegistration,
+    CommandRegistration,
+    CommandExecuteParams,
+    CommandExecuteResult,
+    CommandCompleteParams,
+    CommandCompleteResult,
+    Completion,
+    DeliverAs,
+    SessionSendMessageParams,
+    SessionSendUserMessageParams,
+    SessionAppendEntryParams,
+    SessionSetModelParams,
+    ProviderModel,
+    ProviderRegistration,
+    ProviderCompleteParams,
+    ProviderCompleteResult,
+    ProviderDeltaParams,
+    ProviderOAuthParams,
+    ProviderCredentials,
+    ProviderStreamEvent,
+    ProviderToolCall,
+    ProviderUsage,
 } from './protocol.js';

package/src/protocol.ts

@@ -22,6 +22,26 @@ export const method = {
     REGISTRY_UPDATE: 'registry/update',
     LOG: 'log',
     CANCEL: '$/cancel',
+    COMMAND_EXECUTE: 'command/execute',
+    COMMAND_COMPLETE: 'command/complete',
+    SESSION_SEND_MESSAGE: 'session/send_message',
+    SESSION_SEND_USER_MESSAGE: 'session/send_user_message',
+    SESSION_APPEND_ENTRY: 'session/append_entry',
+    SESSION_SET_MODEL: 'session/set_model',
+    PROVIDER_COMPLETE: 'provider/complete',
+    PROVIDER_DELTA: 'provider/delta',
+    PROVIDER_OAUTH_LOGIN: 'provider/oauth_login',
+    PROVIDER_OAUTH_REFRESH: 'provider/oauth_refresh',
+    /** Ext → host: publish onto the inter-extension bus (Phase 8). */
+    BUS_PUBLISH: 'bus/publish',
+} as const;
+
+/** SEP observe-event names the host fans out (Phase 8 additions included). */
+export const eventName = {
+    /** Inter-extension bus fanout — payload `{ from, topic, payload }`. */
+    BUS_EVENT: 'bus/event',
+    /** Targeted render-block v2 keypress — payload `{ widget_id?, key }`. */
+    WIDGET_KEY: 'widget/key',
 } as const;
 
 /** JSON-RPC + SEP error codes (see spec/extension/envelope.md). */
@@ -62,6 +82,8 @@ export interface InitializeParams {
     session?: { id?: string };
     mode: 'tui' | 'web' | 'widget' | 'cli' | 'headless';
     ui_capabilities?: string[];
+    /** Parsed values for the flags the extension declares (name → value). */
+    flags?: Record<string, unknown>;
     capabilities_enabled?: Record<string, boolean>;
 }
 
@@ -78,11 +100,94 @@ export interface CommandRegistration {
     description: string;
 }
 
+export interface ShortcutRegistration {
+    /** A human-typed chord, e.g. `ctrl+p`; the frontend parses it. */
+    key: string;
+    /** The registered command this chord invokes (no leading `/`). */
+    command: string;
+    description?: string;
+}
+
+export interface ProviderModel {
+    /** Model id the host passes back in `provider/complete`. */
+    id: string;
+    /** Human-facing label for model pickers. */
+    display_name?: string;
+}
+
+export interface ProviderRegistration {
+    /** Provider name, unique within the host's merged model surface. */
+    name: string;
+    /** Informational upstream base URL (the extension does the real call). */
+    base_url?: string;
+    /** Env var the extension reads its API key from — informational to the host. */
+    api_key_env?: string;
+    /** Whether the extension implements `provider/oauth_login` + `oauth_refresh`. */
+    oauth?: boolean;
+    models?: ProviderModel[];
+}
+
+/** A declarative message renderer (Phase 8, pi's `registerMessageRenderer`):
+ *  a custom message `tag` → render-block `template`. When a session entry carries
+ *  the tag, the frontend renders the template with `{{path}}` placeholders
+ *  resolved against the entry's data. Data-only — the host never runs it. */
+export interface MessageRendererRegistration {
+    tag: string;
+    template: RenderBlock;
+}
+
 export interface Registrations {
     tools?: ToolRegistration[];
     commands?: CommandRegistration[];
     flags?: string[];
+    shortcuts?: ShortcutRegistration[];
     subscriptions?: string[];
+    providers?: ProviderRegistration[];
+    /** Intercept hooks this extension handles (Phase 8) — lets the host skip the
+     *  per-turn `context` hook when no extension handles it. Empty = unknown. */
+    hooks?: string[];
+    /** Declarative custom-message renderers (Phase 8). */
+    message_renderers?: MessageRendererRegistration[];
+}
+
+// --- render blocks (Phase 8) --------------------------------------------
+
+/** One key an interactive `widget` render block declares. The host routes the
+ *  matching keypress back as a `widget/key` event ({@link WidgetKeyPayload}). */
+export interface Keybinding {
+    /** A human chord the frontend matches, e.g. `ArrowUp`, `space`, `q`. */
+    key: string;
+    description?: string;
+}
+
+/**
+ * The declarative render-block DSL (Phase 8) — replaces pi's function renderers.
+ * The host/frontend renders each `kind` natively (TUI/web/widget); `text` is the
+ * always-available plain fallback (frontends may derive one when omitted). The
+ * `widget` kind is the interactive tier: it wraps a `body` block and declares
+ * `keybindings`; the host routes matching keys back as `widget/key` events and
+ * the extension re-renders via `ui.setWidget`.
+ */
+export type RenderBlock =
+    | { kind: 'markdown'; text: string }
+    | { kind: 'keyvalue'; rows: { key: string; value: string }[]; title?: string; text?: string }
+    | { kind: 'table'; columns: string[]; rows: string[][]; text?: string }
+    | { kind: 'diff'; patch: string; text?: string }
+    | { kind: 'progress'; value: number; label?: string; text?: string }
+    | { kind: 'stack'; children: RenderBlock[]; text?: string }
+    | { kind: 'widget'; widget_id: string; body: RenderBlock; keybindings: Keybinding[]; text?: string };
+
+/** Payload of the `bus/event` observe event (inter-extension bus, Phase 8). */
+export interface BusEventPayload {
+    from: string;
+    topic: string;
+    payload?: unknown;
+}
+
+/** Payload of the `widget/key` observe event (render-block v2, Phase 8). */
+export interface WidgetKeyPayload {
+    widget_id?: string;
+    key: string;
 }
 
 export interface InitializeResult {
@@ -142,7 +247,7 @@ export type UiRequestParams =
     | { kind: 'input'; prompt: string; default?: string }
     | { kind: 'notify'; message: string; level?: 'info' | 'warn' | 'error' }
     | { kind: 'set_status'; status: string }
-    | { kind: 'set_widget'; widget: Record<string, unknown> }
+    | { kind: 'set_widget'; widget: RenderBlock }
     | { kind: 'set_title'; title: string };
 
 /**
@@ -156,3 +261,131 @@ export interface UiRequestResult {
     text?: string;
     cancelled?: boolean;
 }
+
+/** Host → ext `command/execute`: run a registered slash-command (command tier). */
+export interface CommandExecuteParams {
+    command: string;
+    context: Context;
+    arguments?: Record<string, unknown>;
+}
+
+export interface CommandExecuteResult {
+    content?: string;
+}
+
+/** Host → ext `command/complete`: argument autocomplete for a slash-command. */
+export interface CommandCompleteParams {
+    command: string;
+    context: Context;
+    partial?: string;
+}
+
+export interface Completion {
+    value: string;
+    description?: string;
+}
+
+export interface CommandCompleteResult {
+    completions: Completion[];
+}
+
+/** How a `session/send_user_message` is delivered relative to the current turn. */
+export type DeliverAs = 'steer' | 'follow_up' | 'next_turn';
+
+/** Ext → host `session/send_message` params (command tier — carries `context`). */
+export interface SessionSendMessageParams {
+    context: Context;
+    text: string;
+    role?: 'user' | 'assistant';
+}
+
+export interface SessionSendUserMessageParams {
+    context: Context;
+    text: string;
+    deliver_as?: DeliverAs;
+}
+
+export interface SessionAppendEntryParams {
+    context: Context;
+    entry: Record<string, unknown>;
+}
+
+export interface SessionSetModelParams {
+    context: Context;
+    model: string;
+    /** Provider name when the model belongs to an extension-registered provider. */
+    provider?: string;
+    /** Reasoning/thinking level, e.g. `off`, `low`, `medium`, `high`. */
+    thinking?: string;
+}
+
+// --- provider/* (Phase 7) ------------------------------------------------
+
+/** A serialized host stream event, tagged by `type`. Emitted as `provider/delta`
+ *  `event` while a streaming `provider/complete` runs. */
+export type ProviderStreamEvent =
+    | { type: 'Delta'; content: string }
+    | { type: 'Reasoning'; content: string }
+    | { type: 'ToolCallStart'; index: number; id: string; name: string }
+    | { type: 'ToolCallArgumentsDelta'; index: number; arguments_chunk: string }
+    | { type: 'Usage'; prompt_tokens?: number; completion_tokens?: number; total_tokens?: number; cached_tokens?: number }
+    | { type: 'Model'; name: string }
+    | { type: 'Done'; finish_reason: string };
+
+/** Host → ext `provider/complete`: run one completion. `messages`/`tools` are the
+ *  host's opaque serialized shapes. */
+export interface ProviderCompleteParams {
+    request_id: string;
+    provider: string;
+    model: string;
+    messages: Record<string, unknown>[];
+    tools?: Record<string, unknown>[];
+    stream?: boolean;
+    response_format?: Record<string, unknown>;
+    thinking?: string;
+    context?: Context;
+}
+
+export interface ProviderToolCall {
+    id: string;
+    name: string;
+    arguments: unknown;
+}
+
+export interface ProviderUsage {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    total_tokens?: number;
+    cached_tokens?: number;
+}
+
+/** The final reply to `provider/complete`, mapping onto the host's LlmResponse. */
+export interface ProviderCompleteResult {
+    content?: string;
+    tool_calls?: ProviderToolCall[];
+    finish_reason?: string;
+    usage?: ProviderUsage;
+    reasoning_content?: string;
+    resolved_model?: string;
+}
+
+/** Ext → host `provider/delta` notification: one streamed chunk. */
+export interface ProviderDeltaParams {
+    request_id: string;
+    event: ProviderStreamEvent;
+}
+
+/** Host → ext `provider/oauth_login` / `provider/oauth_refresh`. */
+export interface ProviderOAuthParams {
+    provider: string;
+    refresh_token?: string;
+    context?: Context;
+}
+
+export interface ProviderCredentials {
+    api_key?: string;
+    access_token?: string;
+    refresh_token?: string;
+    expires_at?: number;
+    extra?: Record<string, unknown>;
+}

package/src/render.ts

@@ -0,0 +1,55 @@
+/**
+ * Typed builders for the Phase 8 render-block DSL. These are thin — a render
+ * block is plain data on the wire — but they keep an extension's UI code
+ * type-checked and let a pi port replace `render*` functions mechanically.
+ */
+
+import type { Keybinding, RenderBlock } from './protocol.js';
+
+export const render = {
+    markdown: (text: string): RenderBlock => ({ kind: 'markdown', text }),
+
+    keyvalue: (rows: { key: string; value: string }[], opts?: { title?: string; text?: string }): RenderBlock => ({
+        kind: 'keyvalue',
+        rows,
+        ...(opts?.title !== undefined ? { title: opts.title } : {}),
+        ...(opts?.text !== undefined ? { text: opts.text } : {}),
+    }),
+
+    table: (columns: string[], rows: string[][], opts?: { text?: string }): RenderBlock => ({
+        kind: 'table',
+        columns,
+        rows,
+        ...(opts?.text !== undefined ? { text: opts.text } : {}),
+    }),
+
+    diff: (patch: string, opts?: { text?: string }): RenderBlock => ({
+        kind: 'diff',
+        patch,
+        ...(opts?.text !== undefined ? { text: opts.text } : {}),
+    }),
+
+    /** `value` is a 0..1 fraction. */
+    progress: (value: number, opts?: { label?: string; text?: string }): RenderBlock => ({
+        kind: 'progress',
+        value,
+        ...(opts?.label !== undefined ? { label: opts.label } : {}),
+        ...(opts?.text !== undefined ? { text: opts.text } : {}),
+    }),
+
+    stack: (children: RenderBlock[], opts?: { text?: string }): RenderBlock => ({
+        kind: 'stack',
+        children,
+        ...(opts?.text !== undefined ? { text: opts.text } : {}),
+    }),
+
+    /** The interactive tier: wraps `body` and declares the keys the host should
+     *  route back as `widget/key` events. Correlate re-renders with `widgetId`. */
+    widget: (widgetId: string, body: RenderBlock, keybindings: Keybinding[], opts?: { text?: string }): RenderBlock => ({
+        kind: 'widget',
+        widget_id: widgetId,
+        body,
+        keybindings,
+        ...(opts?.text !== undefined ? { text: opts.text } : {}),
+    }),
+} as const;

package/src/test-host.ts

@@ -7,7 +7,21 @@
  */
 import { Peer, RpcError } from './jsonrpc.js';
 import { PROTOCOL_VERSION, errorCode, method } from './protocol.js';
-import type { Context, HookOutcome, InitializeParams, InitializeResult, ToolExecuteResult, ToolUpdateParams, UiRequestParams, UiRequestResult } from './protocol.js';
+import type {
+    CommandExecuteResult,
+    Context,
+    HookOutcome,
+    InitializeParams,
+    InitializeResult,
+    ProviderCompleteResult,
+    ProviderCredentials,
+    ProviderDeltaParams,
+    ProviderStreamEvent,
+    ToolExecuteResult,
+    ToolUpdateParams,
+    UiRequestParams,
+    UiRequestResult,
+} from './protocol.js';
 import type { Extension } from './extension.js';
 import { linkedPair } from './transport.js';
 
@@ -17,6 +31,18 @@ let callSeq = 0;
  * `RpcError` (e.g. code -32001) to simulate a headless/uncapable frontend. */
 export type UiResponder = (params: UiRequestParams) => UiRequestResult | Promise<UiRequestResult>;
 
+/** A recorded ext→host `session/*` request the test can assert on. */
+export interface SessionCall {
+    method: string;
+    params: Record<string, unknown>;
+}
+
+/** A recorded ext→host `bus/publish` (Phase 8) the test can assert on. */
+export interface BusPublish {
+    topic: string;
+    payload?: unknown;
+}
+
 export interface CreateTestHostOptions {
     /** Answers `ui/request`. Default: reject every call with -32001 NoUI. */
     onUiRequest?: UiResponder;
@@ -31,13 +57,41 @@ export interface CallToolOptions {
     context?: Context;
 }
 
+export interface CompleteOptions {
+    /** Ask for streaming; each `provider/delta` reaches `onDelta`. */
+    stream?: boolean;
+    /** Receives each streamed `provider/delta` event for this request. */
+    onDelta?: (event: ProviderStreamEvent) => void;
+    /** Tool schemas to offer the model (opaque JSON). */
+    tools?: Record<string, unknown>[];
+    responseFormat?: Record<string, unknown>;
+    thinking?: string;
+    signal?: AbortSignal;
+    context?: Context;
+}
+
 export interface TestHost {
     initialize(overrides?: Partial<InitializeParams>): Promise<InitializeResult>;
     callTool(tool: string, args: Record<string, unknown>, opts?: CallToolOptions): Promise<ToolExecuteResult>;
     /** Drive a `hook` request and get back the extension's folded outcome. */
     callHook(hook: string, input: Record<string, unknown>, context?: Context): Promise<HookOutcome>;
+    /** Dispatch a `command/execute` with a command-tier context by default. */
+    runCommand(command: string, args?: Record<string, unknown>, context?: Context): Promise<CommandExecuteResult>;
+    /** Dispatch a `command/complete` for argument autocomplete. */
+    completeCommand(command: string, partial: string, context?: Context): Promise<{ completions: { value: string; description?: string }[] }>;
     ping(): Promise<Record<string, unknown>>;
     sendEvent(event: string, payload?: Record<string, unknown>, context?: Context): void;
+    /** Drive `provider/complete` against a registered provider, collecting any
+     *  streamed `provider/delta` events via `opts.onDelta`. */
+    complete(provider: string, model: string, messages: Record<string, unknown>[], opts?: CompleteOptions): Promise<ProviderCompleteResult>;
+    /** Drive `provider/oauth_login` for a provider. */
+    oauthLogin(provider: string, context?: Context): Promise<ProviderCredentials>;
+    /** Drive `provider/oauth_refresh` for a provider. */
+    oauthRefresh(provider: string, refreshToken: string, context?: Context): Promise<ProviderCredentials>;
+    /** Every `session/*` request the extension made, in order — for assertions. */
+    readonly sessionCalls: SessionCall[];
+    /** Every `bus/publish` (Phase 8) the extension made, in order. */
+    readonly busPublishes: BusPublish[];
     shutdown(): Promise<void>;
     close(): void;
 }
@@ -63,6 +117,38 @@ export function createTestHost(extension: Extension, options: CreateTestHostOpti
     // Extension notifications the host just observes in tests.
     host.setNotificationHandler(method.LOG, () => {});
     host.setNotificationHandler(method.REGISTRY_UPDATE, () => {});
+    // Route `provider/delta` chunks to the in-flight completion's sink, keyed by
+    // request_id — the in-process mirror of the engine's ProviderStreams.
+    const deltaSinks = new Map<string, (event: ProviderStreamEvent) => void>();
+    host.setNotificationHandler(method.PROVIDER_DELTA, (params) => {
+        const p = params as ProviderDeltaParams;
+        deltaSinks.get(p.request_id)?.(p.event);
+    });
+
+    // Service ext→host `session/*` requests, enforcing the same command-tier
+    // guard the real host does (event-tier → -32003) so a demo's session calls
+    // are exercised realistically. Every call is recorded for assertions.
+    const sessionCalls: SessionCall[] = [];
+    const sessionHandler = (params: unknown) => {
+        const p = (params ?? {}) as Record<string, unknown>;
+        const tier = (p.context as { tier?: string } | undefined)?.tier;
+        if (tier !== 'command') throw new RpcError(errorCode.ContextViolation, 'session action requires a command-tier context');
+        return p;
+    };
+    for (const m of [method.SESSION_SEND_MESSAGE, method.SESSION_SEND_USER_MESSAGE, method.SESSION_APPEND_ENTRY, method.SESSION_SET_MODEL]) {
+        host.setRequestHandler(m, (params) => {
+            const recorded = sessionHandler(params);
+            sessionCalls.push({ method: m, params: recorded });
+            return {};
+        });
+    }
+    // Record ext→host `bus/publish` (Phase 8); a real host would fan it out.
+    const busPublishes: BusPublish[] = [];
+    host.setRequestHandler(method.BUS_PUBLISH, (params) => {
+        const p = (params ?? {}) as { topic?: string; payload?: unknown };
+        busPublishes.push({ topic: p.topic ?? '', ...(p.payload !== undefined ? { payload: p.payload } : {}) });
+        return {};
+    });
     hostT.start((frame) => host.receive(frame));
 
     return {
@@ -93,12 +179,57 @@ export function createTestHost(extension: Extension, options: CreateTestHostOpti
         callHook(hook, input, context) {
             return host.request<HookOutcome>(method.HOOK, { hook, input, context: context ?? DEFAULT_CONTEXT });
         },
+        runCommand(command, args, context) {
+            return host.request<CommandExecuteResult>(method.COMMAND_EXECUTE, {
+                command,
+                context: context ?? DEFAULT_CONTEXT,
+                ...(args ? { arguments: args } : {}),
+            });
+        },
+        completeCommand(command, partial, context) {
+            return host.request(method.COMMAND_COMPLETE, { command, context: context ?? DEFAULT_CONTEXT, partial });
+        },
+        sessionCalls,
+        busPublishes,
         ping() {
             return host.request<Record<string, unknown>>(method.PING, {});
         },
         sendEvent(event, payload, context) {
             host.notify(method.EVENT, { event, context: context ?? { token: DEFAULT_CONTEXT.token, tier: 'event' }, ...(payload ? { payload } : {}) });
         },
+        async complete(provider, model, messages, opts = {}) {
+            const request_id = `test-req-${++callSeq}`;
+            if (opts.onDelta) deltaSinks.set(request_id, opts.onDelta);
+            try {
+                return await host.request<ProviderCompleteResult>(
+                    method.PROVIDER_COMPLETE,
+                    {
+                        request_id,
+                        provider,
+                        model,
+                        messages,
+                        tools: opts.tools ?? [],
+                        stream: opts.stream ?? false,
+                        ...(opts.responseFormat ? { response_format: opts.responseFormat } : {}),
+                        ...(opts.thinking ? { thinking: opts.thinking } : {}),
+                        context: opts.context ?? DEFAULT_CONTEXT,
+                    },
+                    opts.signal,
+                );
+            } finally {
+                deltaSinks.delete(request_id);
+            }
+        },
+        oauthLogin(provider, context) {
+            return host.request<ProviderCredentials>(method.PROVIDER_OAUTH_LOGIN, { provider, context: context ?? DEFAULT_CONTEXT });
+        },
+        oauthRefresh(provider, refreshToken, context) {
+            return host.request<ProviderCredentials>(method.PROVIDER_OAUTH_REFRESH, {
+                provider,
+                refresh_token: refreshToken,
+                context: context ?? DEFAULT_CONTEXT,
+            });
+        },
         async shutdown() {
             await host.request(method.SHUTDOWN, {});
         },