@smooai/smooth-extension-sdk 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smooai/smooth-extension-sdk",
-  "version": "0.5.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/extension.ts

@@ -11,7 +11,7 @@
  * 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,
@@ -26,6 +26,16 @@ import type {
     HookParams,
     InitializeParams,
     InitializeResult,
+    BusEventPayload,
+    MessageRendererRegistration,
+    RenderBlock,
+    ProviderCompleteParams,
+    ProviderCompleteResult,
+    ProviderCredentials,
+    ProviderModel,
+    ProviderOAuthParams,
+    ProviderRegistration,
+    ProviderStreamEvent,
     ShortcutRegistration,
     ToolExecuteParams,
     ToolExecuteResult,
@@ -55,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);
@@ -92,6 +116,9 @@ 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`. */
@@ -106,6 +133,14 @@ function makeSession(peer: Peer, context: Context): SessionApi {
         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 } : {}),
+            });
+        },
     };
 }
 
@@ -183,6 +218,58 @@ export interface FlagDef {
     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> };
@@ -203,6 +290,13 @@ export interface SmoothApi {
     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
@@ -228,7 +322,9 @@ export class Extension {
     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. */
@@ -264,6 +360,32 @@ export class Extension {
             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);
@@ -299,6 +421,9 @@ export class Extension {
         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));
@@ -333,6 +458,17 @@ export class Extension {
         // 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 },
@@ -341,11 +477,61 @@ export class Extension {
                 ...(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}` };

package/src/index.ts

@@ -8,10 +8,12 @@
  * `createTestHost`, and gate it against the shared fixtures with
  * `runConformance`.
  */
-export { defineExtension, defineTool, defineCommand, Extension } 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,
@@ -19,6 +21,9 @@ export type {
     CommandContext,
     CommandReturn,
     FlagDef,
+    ProviderDef,
+    ProviderContext,
+    ProviderCompleteRequest,
     SessionApi,
     EventHandler,
     HookResult,
@@ -26,7 +31,7 @@ export type {
     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';
@@ -35,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,
@@ -62,4 +72,15 @@ export type {
     SessionSendMessageParams,
     SessionSendUserMessageParams,
     SessionAppendEntryParams,
+    SessionSetModelParams,
+    ProviderModel,
+    ProviderRegistration,
+    ProviderCompleteParams,
+    ProviderCompleteResult,
+    ProviderDeltaParams,
+    ProviderOAuthParams,
+    ProviderCredentials,
+    ProviderStreamEvent,
+    ProviderToolCall,
+    ProviderUsage,
 } from './protocol.js';

package/src/protocol.ts

@@ -27,6 +27,21 @@ export const method = {
     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). */
@@ -93,12 +108,86 @@ export interface ShortcutRegistration {
     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 {
@@ -158,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 };
 
 /**
@@ -220,3 +309,83 @@ 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

@@ -13,6 +13,10 @@ import type {
     HookOutcome,
     InitializeParams,
     InitializeResult,
+    ProviderCompleteResult,
+    ProviderCredentials,
+    ProviderDeltaParams,
+    ProviderStreamEvent,
     ToolExecuteResult,
     ToolUpdateParams,
     UiRequestParams,
@@ -33,6 +37,12 @@ export interface SessionCall {
     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;
@@ -47,6 +57,19 @@ 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>;
@@ -58,8 +81,17 @@ export interface TestHost {
     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;
 }
@@ -85,6 +117,13 @@ 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
@@ -96,13 +135,20 @@ export function createTestHost(extension: Extension, options: CreateTestHostOpti
         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]) {
+    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 {
@@ -144,12 +190,46 @@ export function createTestHost(extension: Extension, options: CreateTestHostOpti
             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, {});
         },