@smooai/smooth-extension-sdk 0.2.0 → 0.4.0

package/package.json

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

@@ -12,10 +12,67 @@
  */
 import { Peer } from './jsonrpc.js';
 import { PROTOCOL_VERSION, method } from './protocol.js';
-import type { Context, EventParams, InitializeParams, InitializeResult, ToolExecuteParams, ToolExecuteResult, ToolUpdateParams } from './protocol.js';
+import type {
+    Context,
+    EventParams,
+    HookOutcome,
+    HookParams,
+    InitializeParams,
+    InitializeResult,
+    ToolExecuteParams,
+    ToolExecuteResult,
+    ToolUpdateParams,
+    UiKind,
+    UiRequestParams,
+    UiRequestResult,
+} from './protocol.js';
 import { toJsonSchema, type ParameterSchema } from './schema.js';
 import { stdioTransport, type Transport } from './transport.js';
 
+/** The intercept hooks (awaited, host-orchestrated); every other `on(...)` name
+ *  is a fire-and-forget observe event. Kept in sync with the engine's HookType. */
+const HOOK_NAMES = new Set(['tool_call', 'tool_result', 'before_agent_start', 'message_end', 'context', 'before_provider_request', 'input', 'user_bash']);
+
+/**
+ * The `ui/request` surface handed to tools (and to event handlers via
+ * `smooth.ui`). Each call is an ext→host request; the frontend renders it and
+ * replies. `select`/`confirm`/`input` return an answer (or `{ cancelled: true }`
+ * if dismissed); `notify`/`setStatus`/`setWidget`/`setTitle` resolve empty. A
+ * headless or uncapable host rejects with an `RpcError` of code -32001 (NoUI) —
+ * gate with `hasUI(kind)` to avoid it.
+ */
+export interface UiApi {
+    select(prompt: string, options: string[]): Promise<UiRequestResult>;
+    confirm(prompt: string): Promise<UiRequestResult>;
+    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>;
+    setTitle(title: string): Promise<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);
+    return {
+        select: (prompt, options) => req({ kind: 'select', prompt, options }),
+        confirm: (prompt) => req({ kind: 'confirm', prompt }),
+        input: (prompt, opts) => req({ kind: 'input', prompt, ...(opts?.default !== undefined ? { default: opts.default } : {}) }),
+        notify: async (message, level) => {
+            await req({ kind: 'notify', message, ...(level ? { level } : {}) });
+        },
+        setStatus: async (status) => {
+            await req({ kind: 'set_status', status });
+        },
+        setWidget: async (widget) => {
+            await req({ kind: 'set_widget', widget });
+        },
+        setTitle: async (title) => {
+            await req({ kind: 'set_title', title });
+        },
+    };
+}
+
 /** Progress + cancellation handed to a tool while it runs. */
 export interface ToolContext {
     /** Correlates `onUpdate` calls with this execution. */
@@ -26,6 +83,10 @@ export interface ToolContext {
     signal: AbortSignal;
     /** Stream a progress notification back to the host. */
     onUpdate(update: Omit<ToolUpdateParams, 'call_id'>): void;
+    /** 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;
 }
 
 /** What a tool's `execute` may return: a full result or just its `content`. */
@@ -44,8 +105,14 @@ export function defineTool<TArgs = Record<string, unknown>>(def: ToolDef<TArgs>)
     return def;
 }
 
-/** Handler for an observe `event`. Fire-and-forget; return value ignored. */
-export type EventHandler = (payload: Record<string, unknown> | undefined, ctx: Context) => void | Promise<void>;
+/** 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> };
+
+/** Handler for an `on(name, ...)` registration. For an observe event the return
+ *  is ignored; for an intercept hook (see {@link HOOK_NAMES}) return a
+ *  {@link HookResult} to veto or patch. Mirrors pi's single `on`. */
+export type EventHandler = (data: Record<string, unknown> | undefined, ctx: Context) => void | HookResult | Promise<void | HookResult>;
 
 /** The builder passed to `defineExtension`'s setup. Mirrors pi's `ExtensionAPI`. */
 export interface SmoothApi {
@@ -54,6 +121,12 @@ export interface SmoothApi {
     registerTool(tool: ToolDef<any>): void;
     on(event: string, handler: EventHandler): void;
     log(level: 'debug' | 'info' | 'warn' | 'error', message: string, fields?: Record<string, unknown>): void;
+    /** 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;
+    /** The `ui/request` surface. Available after the extension connects; throws
+     * if read before then. Gate with [`hasUI`]. */
+    readonly ui: UiApi;
 }
 
 export type ExtensionSetup = (smooth: SmoothApi) => void;
@@ -70,6 +143,8 @@ export class 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[] = [];
 
     constructor(setup: ExtensionSetup) {
         const api: SmoothApi = {
@@ -96,6 +171,11 @@ export class Extension {
             log: (level, message, fields) => {
                 this.live?.notify(method.LOG, { level, message, ...(fields ? { fields } : {}) });
             },
+            hasUI: (kind) => self.hostUiCaps.includes(kind),
+            get ui() {
+                if (!self.live) throw new Error('smooth.ui is only available after the extension connects');
+                return makeUi(self.live);
+            },
         };
         // `self` alias so the getter/setter pair above closes over the instance.
         const self = this;
@@ -114,6 +194,7 @@ export class Extension {
             return {};
         });
         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.setNotificationHandler(method.EVENT, (params) => this.dispatchEvent(params as EventParams));
 
         transport.start((frame) => peer.receive(frame));
@@ -134,17 +215,21 @@ export class Extension {
         });
     }
 
-    private initialize(_params: InitializeParams): InitializeResult {
+    private initialize(params: InitializeParams): InitializeResult {
+        this.hostUiCaps = params.ui_capabilities ?? [];
         const tools = [...this.tools.values()].map((t) => ({
             name: t.name,
             description: t.description,
             parameters: toJsonSchema(t.parameters),
             ...(t.deferred ? { deferred: true } : {}),
         }));
+        // 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));
         return {
             protocol_version: PROTOCOL_VERSION,
             extension: { name: this.name, version: this.version },
-            registrations: { tools, subscriptions: [...this.events.keys()] },
+            registrations: { tools, subscriptions },
         };
     }
 
@@ -156,6 +241,8 @@ export class Extension {
             context: params.context,
             signal,
             onUpdate: (update) => peer.notify(method.TOOL_UPDATE, { call_id: params.call_id, ...update }),
+            ui: makeUi(peer),
+            hasUI: (kind) => this.hostUiCaps.includes(kind),
         };
         const out = await tool.execute(params.arguments, ctx);
         return typeof out === 'string' ? { content: out } : out;
@@ -166,6 +253,23 @@ export class Extension {
             void handler(params.payload, params.context);
         }
     }
+
+    /** Fold this extension's handlers for one `hook` into a single outcome: the
+     *  first `block` short-circuits; `patch`es shallow-merge onto the input and
+     *  thread to the next handler; no result = continue. The host chains the
+     *  outcome across extensions in load order. */
+    private async dispatchHook(params: HookParams): Promise<HookOutcome> {
+        let input = params.input;
+        let modified = false;
+        for (const handler of this.events.get(params.hook) ?? []) {
+            const result = await handler(input, params.context);
+            if (!result) continue;
+            if ('block' in result) return { action: 'block', ...(result.reason ? { reason: result.reason } : {}) };
+            input = { ...input, ...result.patch };
+            modified = true;
+        }
+        return modified ? { action: 'modify', patch: input } : { action: 'continue' };
+    }
 }
 
 /** Define an extension. Set `smooth.name`/`smooth.version` and register tools. */

package/src/index.ts

@@ -9,9 +9,9 @@
  * `runConformance`.
  */
 export { defineExtension, defineTool, Extension } from './extension.js';
-export type { ExtensionSetup, SmoothApi, ToolDef, ToolContext, ToolReturn, EventHandler, ConnectHandle } from './extension.js';
+export type { ExtensionSetup, SmoothApi, ToolDef, ToolContext, ToolReturn, EventHandler, HookResult, ConnectHandle, UiApi } from './extension.js';
 export { createTestHost } from './test-host.js';
-export type { TestHost, CallToolOptions } from './test-host.js';
+export type { TestHost, CallToolOptions, CreateTestHostOptions, UiResponder } 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';
@@ -31,4 +31,9 @@ export type {
     ToolExecuteResult,
     ToolUpdateParams,
     EventParams,
+    HookParams,
+    HookOutcome,
+    UiKind,
+    UiRequestParams,
+    UiRequestResult,
 } from './protocol.js';

package/src/protocol.ts

@@ -18,6 +18,7 @@ export const method = {
     HOOK: 'hook',
     TOOL_EXECUTE: 'tool/execute',
     TOOL_UPDATE: 'tool/update',
+    UI_REQUEST: 'ui/request',
     REGISTRY_UPDATE: 'registry/update',
     LOG: 'log',
     CANCEL: '$/cancel',
@@ -112,6 +113,46 @@ export interface ToolUpdateParams {
 
 export interface EventParams {
     event: string;
+    /** Per-connection monotonic sequence; absent on the `events_lost` marker. */
+    seq?: number;
     context: Context;
     payload?: Record<string, unknown>;
 }
+
+/** Host → ext `hook` request: an awaited intercept the extension can veto/patch. */
+export interface HookParams {
+    hook: string;
+    context: Context;
+    input: Record<string, unknown>;
+}
+
+/** The extension's reply to a `hook`, tagged by `action`. */
+export type HookOutcome =
+    | { action: 'continue' }
+    | { action: 'block'; reason?: string }
+    | { action: 'modify'; patch: Record<string, unknown> };
+
+/** The seven `ui/request` kinds (snake_case wire names). */
+export type UiKind = 'select' | 'confirm' | 'input' | 'notify' | 'set_status' | 'set_widget' | 'set_title';
+
+/** Params of `ui/request` (ext → host), discriminated by `kind`. */
+export type UiRequestParams =
+    | { kind: 'select'; prompt: string; options: string[] }
+    | { kind: 'confirm'; prompt: string }
+    | { 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_title'; title: string };
+
+/**
+ * Reply to a `ui/request`. Which field is set depends on the request `kind`:
+ * `select` → `value`, `confirm` → `confirmed`, `input` → `text`; the rest are
+ * empty. Any kind may set `cancelled` if the user dismissed the UI.
+ */
+export interface UiRequestResult {
+    value?: string;
+    confirmed?: boolean;
+    text?: string;
+    cancelled?: boolean;
+}

package/src/test-host.ts

@@ -5,14 +5,23 @@
  * (with progress + cancellation), events, ping and shutdown directly against a
  * `defineExtension(...)` object.
  */
-import { Peer } from './jsonrpc.js';
-import { PROTOCOL_VERSION, method } from './protocol.js';
-import type { Context, InitializeParams, InitializeResult, ToolExecuteResult, ToolUpdateParams } from './protocol.js';
+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 { Extension } from './extension.js';
 import { linkedPair } from './transport.js';
 
 let callSeq = 0;
 
+/** Answers the extension's `ui/request` calls. Return a result, or throw an
+ * `RpcError` (e.g. code -32001) to simulate a headless/uncapable frontend. */
+export type UiResponder = (params: UiRequestParams) => UiRequestResult | Promise<UiRequestResult>;
+
+export interface CreateTestHostOptions {
+    /** Answers `ui/request`. Default: reject every call with -32001 NoUI. */
+    onUiRequest?: UiResponder;
+}
+
 export interface CallToolOptions {
     /** Receives each `tool/update` the extension streams for this call. */
     onUpdate?: (update: ToolUpdateParams) => void;
@@ -25,6 +34,8 @@ export interface CallToolOptions {
 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>;
     ping(): Promise<Record<string, unknown>>;
     sendEvent(event: string, payload?: Record<string, unknown>, context?: Context): void;
     shutdown(): Promise<void>;
@@ -33,7 +44,7 @@ export interface TestHost {
 
 const DEFAULT_CONTEXT: Context = { token: 'test-epoch', tier: 'command' };
 
-export function createTestHost(extension: Extension): TestHost {
+export function createTestHost(extension: Extension, options: CreateTestHostOptions = {}): TestHost {
     const [hostT, extT] = linkedPair();
     const extHandle = extension.connect(extT);
     /** call_id → the caller's onUpdate, so streamed progress reaches the test. */
@@ -44,6 +55,11 @@ export function createTestHost(extension: Extension): TestHost {
         const p = params as ToolUpdateParams;
         updateSinks.get(p.call_id)?.(p);
     });
+    // Answer ext→host `ui/request`. Default mimics a headless frontend (NoUI).
+    host.setRequestHandler(method.UI_REQUEST, async (params) => {
+        if (!options.onUiRequest) throw new RpcError(errorCode.NoUI, 'no UI available (headless test host)');
+        return options.onUiRequest(params as UiRequestParams);
+    });
     // Extension notifications the host just observes in tests.
     host.setNotificationHandler(method.LOG, () => {});
     host.setNotificationHandler(method.REGISTRY_UPDATE, () => {});
@@ -74,6 +90,9 @@ export function createTestHost(extension: Extension): TestHost {
                 updateSinks.delete(call_id);
             }
         },
+        callHook(hook, input, context) {
+            return host.request<HookOutcome>(method.HOOK, { hook, input, context: context ?? DEFAULT_CONTEXT });
+        },
         ping() {
             return host.request<Record<string, unknown>>(method.PING, {});
         },