@smooai/smooth-extension-sdk 0.4.0 → 0.5.0

package/package.json

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

@@ -13,12 +13,20 @@
 import { Peer } from './jsonrpc.js';
 import { PROTOCOL_VERSION, method } from './protocol.js';
 import type {
+    CommandCompleteParams,
+    CommandCompleteResult,
+    CommandExecuteParams,
+    CommandExecuteResult,
+    CommandRegistration,
+    Completion,
     Context,
+    DeliverAs,
     EventParams,
     HookOutcome,
     HookParams,
     InitializeParams,
     InitializeResult,
+    ShortcutRegistration,
     ToolExecuteParams,
     ToolExecuteResult,
     ToolUpdateParams,
@@ -73,6 +81,34 @@ 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>;
+}
+
+/** 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 });
+        },
+    };
+}
+
 /** Progress + cancellation handed to a tool while it runs. */
 export interface ToolContext {
     /** Correlates `onUpdate` calls with this execution. */
@@ -105,6 +141,48 @@ 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;
+}
+
 /** 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 +197,17 @@ 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;
     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,6 +225,9 @@ 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 events = new Map<string, EventHandler[]>();
     private name = 'extension';
     private version = '0.0.0';
@@ -145,6 +235,8 @@ export class Extension {
     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 +255,15 @@ 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);
+            },
             on: (event, handler) => {
                 const list = this.events.get(event) ?? [];
                 list.push(handler);
@@ -171,6 +272,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 +297,8 @@ 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.setNotificationHandler(method.EVENT, (params) => this.dispatchEvent(params as EventParams));
 
         transport.start((frame) => peer.receive(frame));
@@ -217,20 +321,52 @@ 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));
         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 } : {}),
+                subscriptions,
+            },
+        };
+    }
+
+    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> {

package/src/index.ts

@@ -8,8 +8,23 @@
  * `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, Extension } from './extension.js';
+export type {
+    ExtensionSetup,
+    SmoothApi,
+    ToolDef,
+    ToolContext,
+    ToolReturn,
+    CommandDef,
+    CommandContext,
+    CommandReturn,
+    FlagDef,
+    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 { runConformance, DEFAULT_SPEC_DIR } from './conformance.js';
@@ -36,4 +51,15 @@ export type {
     UiKind,
     UiRequestParams,
     UiRequestResult,
+    ShortcutRegistration,
+    CommandRegistration,
+    CommandExecuteParams,
+    CommandExecuteResult,
+    CommandCompleteParams,
+    CommandCompleteResult,
+    Completion,
+    DeliverAs,
+    SessionSendMessageParams,
+    SessionSendUserMessageParams,
+    SessionAppendEntryParams,
 } from './protocol.js';

package/src/protocol.ts

@@ -22,6 +22,11 @@ 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',
 } as const;
 
 /** JSON-RPC + SEP error codes (see spec/extension/envelope.md). */
@@ -62,6 +67,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,10 +85,19 @@ 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 Registrations {
     tools?: ToolRegistration[];
     commands?: CommandRegistration[];
     flags?: string[];
+    shortcuts?: ShortcutRegistration[];
     subscriptions?: string[];
 }
 
@@ -156,3 +172,51 @@ 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>;
+}

package/src/test-host.ts

@@ -7,7 +7,17 @@
  */
 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,
+    ToolExecuteResult,
+    ToolUpdateParams,
+    UiRequestParams,
+    UiRequestResult,
+} from './protocol.js';
 import type { Extension } from './extension.js';
 import { linkedPair } from './transport.js';
 
@@ -17,6 +27,12 @@ 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>;
+}
+
 export interface CreateTestHostOptions {
     /** Answers `ui/request`. Default: reject every call with -32001 NoUI. */
     onUiRequest?: UiResponder;
@@ -36,8 +52,14 @@ export interface TestHost {
     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;
+    /** Every `session/*` request the extension made, in order — for assertions. */
+    readonly sessionCalls: SessionCall[];
     shutdown(): Promise<void>;
     close(): void;
 }
@@ -63,6 +85,24 @@ export function createTestHost(extension: Extension, options: CreateTestHostOpti
     // Extension notifications the host just observes in tests.
     host.setNotificationHandler(method.LOG, () => {});
     host.setNotificationHandler(method.REGISTRY_UPDATE, () => {});
+
+    // 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]) {
+        host.setRequestHandler(m, (params) => {
+            const recorded = sessionHandler(params);
+            sessionCalls.push({ method: m, params: recorded });
+            return {};
+        });
+    }
     hostT.start((frame) => host.receive(frame));
 
     return {
@@ -93,6 +133,17 @@ 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,
         ping() {
             return host.request<Record<string, unknown>>(method.PING, {});
         },