@smooai/smooth-extension-sdk 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Smoo AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# @smooai/smooth-extension-sdk
+
+Build **SEP** (Smooth Extension Protocol) extensions in TypeScript.
+
+An extension is a long-lived subprocess that speaks JSON-RPC 2.0 over ndjson on
+its stdin/stdout to a SEP host (`smooth-operator-core` and its polyglot servers).
+This SDK is the DX centerpiece: describe your extension declaratively, `serve()`
+it, test it in-process, and gate it against the shared conformance fixtures.
+
+## Quick start
+
+```ts
+import { z } from 'zod';
+import { defineExtension, defineTool } from '@smooai/smooth-extension-sdk';
+
+export const hello = defineExtension((smooth) => {
+    smooth.name = 'hello';
+    smooth.version = '0.1.0';
+
+    smooth.registerTool(
+        defineTool({
+            name: 'greet',
+            description: 'Greet someone by name.',
+            parameters: z.object({ name: z.string() }),
+            async execute(args, ctx) {
+                ctx.onUpdate({ message: `greeting ${args.name}`, progress: 0.5 });
+                return { content: `Hello, ${args.name}!` };
+            },
+        }),
+    );
+});
+
+hello.serve(); // wire to stdin/stdout and run
+```
+
+The host exposes the tool to the LLM as `hello.greet`.
+
+## Schemas
+
+`parameters` accepts three shapes — the wire truth is always JSON Schema:
+
+- a **zod v4** schema → converted with `z.toJSONSchema()`
+- a **TypeBox** schema → TypeBox schemas already ARE JSON Schema, passed through
+- a **raw JSON Schema** object → passed through unchanged
+
+## Tool context
+
+`execute(args, ctx)` receives a `ctx` with:
+
+- `ctx.onUpdate({ message?, progress?, details? })` — stream `tool/update` progress
+- `ctx.signal` — an `AbortSignal` that fires when the host sends `$/cancel`
+- `ctx.callId` / `ctx.context` — the call id and dispatch context (epoch token + tier)
+
+Return a `{ content, is_error?, details? }` result, or just a string shorthand for
+`{ content }`.
+
+## Testing
+
+```ts
+import { createTestHost } from '@smooai/smooth-extension-sdk';
+import { hello } from './hello.js';
+
+const host = createTestHost(hello); // in-process, no subprocess
+await host.initialize();
+const res = await host.callTool('greet', { name: 'Ada' });
+// res === { content: 'Hello, Ada!' }
+host.close();
+```
+
+`runConformance` replays the shared SEP fixtures against a **real** extension
+subprocess, validating every reply against its schema:
+
+```ts
+import { runConformance } from '@smooai/smooth-extension-sdk';
+
+const report = await runConformance({ command: 'node', args: ['./hello.js'] });
+// report.passed === true
+```
+
+## API
+
+- `defineExtension((smooth) => void)` — set `smooth.name`/`version`, `registerTool`, `on(event)`, `log`.
+- `defineTool({ name, description, parameters, deferred?, execute })`
+- `createTestHost(extension)` → `{ initialize, callTool, ping, sendEvent, shutdown, close }`
+- `runConformance({ command, args?, env?, cwd?, specDir? })` → `ConformanceReport`
+- `Peer`, `stdioTransport`, `linkedPair`, `toJsonSchema` — the building blocks
+- `PROTOCOL_VERSION`, `method`, `errorCode` and the wire types
+
+## Scope (Phase 1)
+
+The tool path: registration, execute, streamed progress, cancellation, plus
+observe `on(event)` subscriptions and lifecycle (`initialize`/`ping`/`shutdown`).
+Hooks, commands, ui/kv/session/exec land in later phases — the wire and API were
+shaped to grow into them without breaking the tool path.

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@smooai/smooth-extension-sdk",
+  "version": "0.2.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",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SmooAI/smooth-operator.git",
+    "directory": "typescript/extension-sdk"
+  },
+  "homepage": "https://github.com/SmooAI/smooth-operator/tree/main/typescript/extension-sdk",
+  "keywords": [
+    "smooth-operator",
+    "sep",
+    "extension",
+    "json-rpc",
+    "agent",
+    "tools",
+    "sdk"
+  ],
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/conformance.ts

@@ -0,0 +1,132 @@
+/**
+ * `runConformance` — replay the shared SEP conformance fixtures against a REAL
+ * extension subprocess. Where the schema-only conformance test (in the spec
+ * repo) proves the fixtures match the schemas, this proves a live extension,
+ * spawned and handshaken over stdio, answers each method with a schema-valid
+ * reply. It is the SDK's dogfood gate and the template every polyglot SDK's
+ * conformance runner follows.
+ */
+import { spawn } from 'node:child_process';
+import { readFile, readdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import _Ajv2020, { Ajv2020 as AjvClass, type ErrorObject } from 'ajv/dist/2020.js';
+import _addFormats from 'ajv-formats';
+import { Peer } from './jsonrpc.js';
+import { PROTOCOL_VERSION, method } from './protocol.js';
+import { stdioTransport } from './transport.js';
+
+// ajv/ajv-formats ship CJS with a double-default under NodeNext; normalize both
+// to the actual callable (same trick as the spec repo's validate.ts).
+type Ajv = AjvClass;
+const Ajv2020 = ((_Ajv2020 as unknown as { default?: unknown }).default ?? _Ajv2020) as typeof AjvClass;
+const addFormats = ((_addFormats as unknown as { default?: unknown }).default ?? _addFormats) as (ajv: Ajv) => Ajv;
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** Repo-relative default: <repo>/spec/extension (works from src/ and dist/). */
+export const DEFAULT_SPEC_DIR = join(__dirname, '..', '..', '..', 'spec', 'extension');
+
+export interface ConformanceStep {
+    name: string;
+    ok: boolean;
+    detail?: string;
+}
+export interface ConformanceReport {
+    passed: boolean;
+    steps: ConformanceStep[];
+}
+
+export interface RunConformanceOptions {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    /** Where spec/extension lives; defaults to the in-repo copy. */
+    specDir?: string;
+}
+
+interface Fixture {
+    $schema_ref: string;
+    instance: unknown;
+}
+
+/** Load every methods/*.schema.json under `specDir` into one ajv instance. */
+async function loadValidator(specDir: string): Promise<(ref: string, value: unknown) => ErrorObject[]> {
+    const ajv = new Ajv2020({ allErrors: true, strict: false });
+    addFormats(ajv);
+    const fileToId = new Map<string, string>();
+    const methodsDir = join(specDir, 'methods');
+    for (const e of await readdir(methodsDir, { withFileTypes: true })) {
+        if (!e.isFile() || !e.name.endsWith('.schema.json')) continue;
+        const schema = JSON.parse(await readFile(join(methodsDir, e.name), 'utf8')) as { $id?: string };
+        const id = schema.$id ?? `urn:sep:${e.name}`;
+        if (!ajv.getSchema(id)) ajv.addSchema(schema, id);
+        fileToId.set(e.name, id);
+    }
+    return (ref, value) => {
+        const [path, pointer] = ref.split('#');
+        const file = path!.split('/').pop()!;
+        const id = fileToId.get(file);
+        if (!id) throw new Error(`no schema for ref ${ref}`);
+        const validate = ajv.getSchema(pointer ? `${id}#${pointer}` : id);
+        if (!validate) throw new Error(`ajv could not resolve ${ref}`);
+        return validate(value) ? [] : (validate.errors ?? []);
+    };
+}
+
+function fmt(errors: ErrorObject[]): string {
+    return errors.map((e) => `${e.instancePath || '<root>'} ${e.message ?? ''}`.trim()).join('; ');
+}
+
+/**
+ * Spawn `command`, handshake, and replay the request/reply fixtures against the
+ * live process, validating every reply against its `Result` schema. Resolves a
+ * report; also returns non-zero via `passed: false` rather than throwing so a
+ * caller can assert on the detail.
+ */
+export async function runConformance(opts: RunConformanceOptions): Promise<ConformanceReport> {
+    const specDir = opts.specDir ?? DEFAULT_SPEC_DIR;
+    const validate = await loadValidator(specDir);
+    const fixtures = JSON.parse(await readFile(join(specDir, 'conformance', 'fixtures.json'), 'utf8')) as Record<string, Fixture>;
+
+    const child = spawn(opts.command, opts.args ?? [], {
+        stdio: ['pipe', 'pipe', 'inherit'],
+        env: { ...process.env, ...opts.env },
+        cwd: opts.cwd,
+    });
+    const transport = stdioTransport(child.stdout!, child.stdin!);
+    const peer = new Peer({ send: (frame) => transport.send(frame) });
+    peer.setNotificationHandler(method.TOOL_UPDATE, () => {});
+    peer.setNotificationHandler(method.LOG, () => {});
+    transport.start((frame) => peer.receive(frame));
+
+    const steps: ConformanceStep[] = [];
+    const check = async (name: string, requestMethod: string, params: unknown, resultRef: string) => {
+        try {
+            const result = await peer.request(requestMethod, params);
+            const errors = validate(resultRef, result);
+            steps.push({ name, ok: errors.length === 0, detail: errors.length ? fmt(errors) : undefined });
+        } catch (err) {
+            steps.push({ name, ok: false, detail: err instanceof Error ? err.message : String(err) });
+        }
+    };
+
+    try {
+        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('shutdown', method.SHUTDOWN, {}, 'methods/shutdown.schema.json#/$defs/Result');
+    } finally {
+        peer.close();
+        transport.close();
+        child.kill();
+    }
+
+    return { passed: steps.every((s) => s.ok), steps };
+}
+
+/** Handshake params from the fixture, pinned to the version this SDK speaks. */
+function initParams(fixtures: Record<string, Fixture>): unknown {
+    const base = fixtures.initialize_params!.instance as Record<string, unknown>;
+    return { ...base, protocol_version: PROTOCOL_VERSION };
+}

package/src/extension.ts

@@ -0,0 +1,174 @@
+/**
+ * `defineExtension` / `defineTool` — the DX centerpiece.
+ *
+ * An extension is a long-lived subprocess speaking SEP over its stdio. You
+ * describe it declaratively; `serve()` wires it to `process.stdin/stdout`, and
+ * `createTestHost` (test-host.ts) drives the same object in-process.
+ *
+ * Phase 1 surface: `registerTool` (schema + execute + streaming progress +
+ * cancellation) and `on(event)` observe subscriptions. Hooks, commands, ui/kv/
+ * session/exec land in later phases; the wire and this API were shaped to grow
+ * into them without breaking the tool path.
+ */
+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 { toJsonSchema, type ParameterSchema } from './schema.js';
+import { stdioTransport, type Transport } from './transport.js';
+
+/** Progress + cancellation handed to a tool while it runs. */
+export interface ToolContext {
+    /** Correlates `onUpdate` calls with this execution. */
+    callId: string;
+    /** The dispatch context (epoch token + tier). */
+    context: Context;
+    /** Fires when the host sends `$/cancel` for this call. */
+    signal: AbortSignal;
+    /** Stream a progress notification back to the host. */
+    onUpdate(update: Omit<ToolUpdateParams, 'call_id'>): void;
+}
+
+/** What a tool's `execute` may return: a full result or just its `content`. */
+export type ToolReturn = ToolExecuteResult | string;
+
+export interface ToolDef<TArgs = Record<string, unknown>> {
+    name: string;
+    description: string;
+    parameters: ParameterSchema;
+    deferred?: boolean;
+    execute(args: TArgs, ctx: ToolContext): Promise<ToolReturn> | ToolReturn;
+}
+
+/** Identity for `defineTool` — keeps the generic arg inferred at the call site. */
+export function defineTool<TArgs = Record<string, unknown>>(def: ToolDef<TArgs>): 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>;
+
+/** The builder passed to `defineExtension`'s setup. Mirrors pi's `ExtensionAPI`. */
+export interface SmoothApi {
+    name: string;
+    version: string;
+    registerTool(tool: ToolDef<any>): void;
+    on(event: string, handler: EventHandler): void;
+    log(level: 'debug' | 'info' | 'warn' | 'error', message: string, fields?: Record<string, unknown>): void;
+}
+
+export type ExtensionSetup = (smooth: SmoothApi) => void;
+
+export interface ConnectHandle {
+    peer: Peer;
+    close(): void;
+}
+
+export class Extension {
+    private readonly tools = new Map<string, ToolDef<any>>();
+    private readonly events = new Map<string, EventHandler[]>();
+    private name = 'extension';
+    private version = '0.0.0';
+    /** Set once connected so `log()` before connect is a safe no-op. */
+    private live?: Peer;
+
+    constructor(setup: ExtensionSetup) {
+        const api: SmoothApi = {
+            get name() {
+                return self.name;
+            },
+            set name(v: string) {
+                self.name = v;
+            },
+            get version() {
+                return self.version;
+            },
+            set version(v: string) {
+                self.version = v;
+            },
+            registerTool: (tool) => {
+                this.tools.set(tool.name, tool);
+            },
+            on: (event, handler) => {
+                const list = this.events.get(event) ?? [];
+                list.push(handler);
+                this.events.set(event, list);
+            },
+            log: (level, message, fields) => {
+                this.live?.notify(method.LOG, { level, message, ...(fields ? { fields } : {}) });
+            },
+        };
+        // `self` alias so the getter/setter pair above closes over the instance.
+        const self = this;
+        setup(api);
+    }
+
+    /** Wire this extension to a transport. Returns a handle to close it. */
+    connect(transport: Transport, onShutdown: () => void = () => {}): ConnectHandle {
+        const peer = new Peer({ send: (frame) => transport.send(frame) });
+        this.live = peer;
+
+        peer.setRequestHandler(method.INITIALIZE, (params) => this.initialize(params as InitializeParams));
+        peer.setRequestHandler(method.PING, () => ({}));
+        peer.setRequestHandler(method.SHUTDOWN, () => {
+            queueMicrotask(onShutdown);
+            return {};
+        });
+        peer.setRequestHandler(method.TOOL_EXECUTE, (params, signal) => this.executeTool(params as ToolExecuteParams, peer, signal));
+        peer.setNotificationHandler(method.EVENT, (params) => this.dispatchEvent(params as EventParams));
+
+        transport.start((frame) => peer.receive(frame));
+        return {
+            peer,
+            close() {
+                peer.close();
+                transport.close();
+            },
+        };
+    }
+
+    /** Connect over this process's stdin/stdout and keep the process alive. */
+    serve(): ConnectHandle {
+        return this.connect(stdioTransport(), () => {
+            // Give the shutdown reply a tick to flush, then exit.
+            setTimeout(() => process.exit(0), 10);
+        });
+    }
+
+    private initialize(_params: InitializeParams): InitializeResult {
+        const tools = [...this.tools.values()].map((t) => ({
+            name: t.name,
+            description: t.description,
+            parameters: toJsonSchema(t.parameters),
+            ...(t.deferred ? { deferred: true } : {}),
+        }));
+        return {
+            protocol_version: PROTOCOL_VERSION,
+            extension: { name: this.name, version: this.version },
+            registrations: { tools, subscriptions: [...this.events.keys()] },
+        };
+    }
+
+    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 };
+        const ctx: ToolContext = {
+            callId: params.call_id,
+            context: params.context,
+            signal,
+            onUpdate: (update) => peer.notify(method.TOOL_UPDATE, { call_id: params.call_id, ...update }),
+        };
+        const out = await tool.execute(params.arguments, ctx);
+        return typeof out === 'string' ? { content: out } : out;
+    }
+
+    private dispatchEvent(params: EventParams): void {
+        for (const handler of this.events.get(params.event) ?? []) {
+            void handler(params.payload, params.context);
+        }
+    }
+}
+
+/** Define an extension. Set `smooth.name`/`smooth.version` and register tools. */
+export function defineExtension(setup: ExtensionSetup): Extension {
+    return new Extension(setup);
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * @smooai/smooth-extension-sdk — build SEP (Smooth Extension Protocol)
+ * extensions in TypeScript.
+ *
+ * An extension is a subprocess speaking JSON-RPC 2.0 ndjson over stdio to any
+ * SEP host (smooth-operator-core and its polyglot servers). Describe it with
+ * `defineExtension`/`defineTool`, `serve()` it, test it in-process with
+ * `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, ConnectHandle } from './extension.js';
+export { createTestHost } from './test-host.js';
+export type { TestHost, CallToolOptions } 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';
+export type { ParameterSchema } from './schema.js';
+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 type {
+    Context,
+    InitializeParams,
+    InitializeResult,
+    Registrations,
+    ToolRegistration,
+    ToolExecuteParams,
+    ToolExecuteResult,
+    ToolUpdateParams,
+    EventParams,
+} from './protocol.js';

package/src/jsonrpc.ts

@@ -0,0 +1,192 @@
+/**
+ * A symmetric JSON-RPC 2.0 peer over a message-passing transport.
+ *
+ * Both ends of SEP are peers: each issues requests, replies to the other's
+ * requests, and sends fire-and-forget notifications. This one `Peer` class is
+ * the shared core — the extension runtime and the in-process test host are both
+ * just a `Peer` with different handlers. It is transport-agnostic: it emits
+ * frame objects via `send` and is fed inbound frames via `receive`; a codec
+ * turns those into ndjson lines (see `transport.ts`).
+ *
+ * Cancellation is wired both ways:
+ * - Outbound: pass an `AbortSignal`; on abort the Peer sends `$/cancel { id }`
+ *   and rejects the pending request.
+ * - Inbound: a request handler receives an `AbortSignal` that fires when the
+ *   remote sends `$/cancel` for that request's id.
+ */
+import { errorCode, method } from './protocol.js';
+
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id: number | string;
+    method: string;
+    params?: unknown;
+}
+export interface JsonRpcNotification {
+    jsonrpc: '2.0';
+    method: string;
+    params?: unknown;
+}
+export interface JsonRpcSuccess {
+    jsonrpc: '2.0';
+    id: number | string;
+    result: unknown;
+}
+export interface JsonRpcError {
+    jsonrpc: '2.0';
+    id: number | string;
+    error: { code: number; message: string; data?: unknown };
+}
+export type JsonRpcFrame = JsonRpcRequest | JsonRpcNotification | JsonRpcSuccess | JsonRpcError;
+
+/** An error carrying a JSON-RPC error code, thrown for a remote error reply. */
+export class RpcError extends Error {
+    constructor(
+        public readonly code: number,
+        message: string,
+        public readonly data?: unknown,
+    ) {
+        super(message);
+        this.name = 'RpcError';
+    }
+}
+
+export type RequestHandler = (params: unknown, signal: AbortSignal) => Promise<unknown> | unknown;
+export type NotificationHandler = (params: unknown) => void;
+
+interface Pending {
+    resolve: (value: unknown) => void;
+    reject: (err: Error) => void;
+    onAbort?: () => void;
+    signal?: AbortSignal;
+}
+
+export interface PeerOptions {
+    /** Emit a frame to the remote. */
+    send: (frame: JsonRpcFrame) => void;
+    /** Called for any inbound method with no registered handler. */
+    onUnhandled?: (frame: JsonRpcRequest | JsonRpcNotification) => void;
+}
+
+export class Peer {
+    private nextId = 1;
+    private readonly pending = new Map<number | string, Pending>();
+    private readonly requestHandlers = new Map<string, RequestHandler>();
+    private readonly notificationHandlers = new Map<string, NotificationHandler>();
+    /** In-flight inbound requests we can cancel when the remote sends `$/cancel`. */
+    private readonly inflight = new Map<number | string, AbortController>();
+    private closed = false;
+
+    constructor(private readonly opts: PeerOptions) {}
+
+    setRequestHandler(name: string, handler: RequestHandler): void {
+        this.requestHandlers.set(name, handler);
+    }
+
+    setNotificationHandler(name: string, handler: NotificationHandler): void {
+        this.notificationHandlers.set(name, handler);
+    }
+
+    /** Issue a request; resolves with the remote's result or rejects with RpcError. */
+    request<T = unknown>(name: string, params?: unknown, signal?: AbortSignal): Promise<T> {
+        if (this.closed) return Promise.reject(new Error('peer is closed'));
+        const id = this.nextId++;
+        return new Promise<T>((resolve, reject) => {
+            if (signal?.aborted) {
+                reject(new RpcError(errorCode.Cancelled, 'cancelled before send'));
+                return;
+            }
+            const onAbort = signal
+                ? () => {
+                      const p = this.pending.get(id);
+                      if (!p) return;
+                      this.pending.delete(id);
+                      this.opts.send({ jsonrpc: '2.0', method: method.CANCEL, params: { id } });
+                      reject(new RpcError(errorCode.Cancelled, 'cancelled'));
+                  }
+                : undefined;
+            this.pending.set(id, { resolve: resolve as (v: unknown) => void, reject, onAbort, signal });
+            signal?.addEventListener('abort', onAbort!, { once: true });
+            this.opts.send({ jsonrpc: '2.0', id, method: name, params });
+        });
+    }
+
+    /** Send a fire-and-forget notification. */
+    notify(name: string, params?: unknown): void {
+        if (this.closed) return;
+        this.opts.send({ jsonrpc: '2.0', method: name, params });
+    }
+
+    /** Feed one inbound frame. */
+    receive(frame: JsonRpcFrame): void {
+        if ('id' in frame && 'method' in frame) {
+            void this.handleRequest(frame);
+        } else if ('method' in frame) {
+            this.handleNotification(frame);
+        } else if ('id' in frame) {
+            this.handleResponse(frame);
+        }
+    }
+
+    /** Reject every pending request; used on transport close. */
+    close(reason = 'peer closed'): void {
+        this.closed = true;
+        for (const [id, p] of this.pending) {
+            if (p.onAbort && p.signal) p.signal.removeEventListener('abort', p.onAbort);
+            p.reject(new Error(reason));
+            this.pending.delete(id);
+        }
+        for (const ctrl of this.inflight.values()) ctrl.abort();
+        this.inflight.clear();
+    }
+
+    private async handleRequest(frame: JsonRpcRequest): Promise<void> {
+        const handler = this.requestHandlers.get(frame.method);
+        if (!handler) {
+            this.opts.onUnhandled?.(frame);
+            this.opts.send({ jsonrpc: '2.0', id: frame.id, error: { code: errorCode.MethodNotFound, message: `method not found: ${frame.method}` } });
+            return;
+        }
+        const ctrl = new AbortController();
+        this.inflight.set(frame.id, ctrl);
+        try {
+            const result = await handler(frame.params, ctrl.signal);
+            if (ctrl.signal.aborted) {
+                this.opts.send({ jsonrpc: '2.0', id: frame.id, error: { code: errorCode.Cancelled, message: 'cancelled' } });
+            } else {
+                this.opts.send({ jsonrpc: '2.0', id: frame.id, result: result ?? {} });
+            }
+        } catch (err) {
+            if (ctrl.signal.aborted) {
+                this.opts.send({ jsonrpc: '2.0', id: frame.id, error: { code: errorCode.Cancelled, message: 'cancelled' } });
+            } else if (err instanceof RpcError) {
+                this.opts.send({ jsonrpc: '2.0', id: frame.id, error: { code: err.code, message: err.message, data: err.data } });
+            } else {
+                this.opts.send({ jsonrpc: '2.0', id: frame.id, error: { code: errorCode.InternalError, message: err instanceof Error ? err.message : String(err) } });
+            }
+        } finally {
+            this.inflight.delete(frame.id);
+        }
+    }
+
+    private handleNotification(frame: JsonRpcNotification): void {
+        // `$/cancel` aborts the matching in-flight inbound request.
+        if (frame.method === method.CANCEL) {
+            const id = (frame.params as { id?: number | string } | undefined)?.id;
+            if (id !== undefined) this.inflight.get(id)?.abort();
+            return;
+        }
+        const handler = this.notificationHandlers.get(frame.method);
+        if (handler) handler(frame.params);
+        else this.opts.onUnhandled?.(frame);
+    }
+
+    private handleResponse(frame: JsonRpcSuccess | JsonRpcError): void {
+        const p = this.pending.get(frame.id);
+        if (!p) return; // late reply for a cancelled/unknown request — drop it.
+        this.pending.delete(frame.id);
+        if (p.onAbort && p.signal) p.signal.removeEventListener('abort', p.onAbort);
+        if ('error' in frame) p.reject(new RpcError(frame.error.code, frame.error.message, frame.error.data));
+        else p.resolve(frame.result);
+    }
+}

package/src/protocol.ts

@@ -0,0 +1,117 @@
+/**
+ * SEP (Smooth Extension Protocol) wire types + method/error constants.
+ *
+ * The source of truth is the JSON Schemas in `spec/extension/`; these types are
+ * the hand-maintained TS view of the subset the SDK needs for Phase 1 (the tool
+ * path + lifecycle). Field names are `snake_case` because they ARE the wire.
+ */
+
+/** Highest SEP version this SDK speaks. Effective version = min(host, ext). */
+export const PROTOCOL_VERSION = 1;
+
+/** Method names — namespaced with `/`; `$/` marks JSON-RPC meta methods. */
+export const method = {
+    INITIALIZE: 'initialize',
+    SHUTDOWN: 'shutdown',
+    PING: 'ping',
+    EVENT: 'event',
+    HOOK: 'hook',
+    TOOL_EXECUTE: 'tool/execute',
+    TOOL_UPDATE: 'tool/update',
+    REGISTRY_UPDATE: 'registry/update',
+    LOG: 'log',
+    CANCEL: '$/cancel',
+} as const;
+
+/** JSON-RPC + SEP error codes (see spec/extension/envelope.md). */
+export const errorCode = {
+    ParseError: -32700,
+    InvalidRequest: -32600,
+    MethodNotFound: -32601,
+    InvalidParams: -32602,
+    InternalError: -32603,
+    Blocked: -32000,
+    NoUI: -32001,
+    NotTrusted: -32002,
+    ContextViolation: -32003,
+    CapabilityDisabled: -32004,
+    Cancelled: -32800,
+} as const;
+
+/** The `context` carried by every dispatched event/hook/tool/execute. */
+export interface Context {
+    token: string;
+    tier: 'event' | 'command';
+}
+
+export interface HostInfo {
+    name: string;
+    version: string;
+}
+
+export interface Workspace {
+    root: string;
+    trusted: boolean;
+}
+
+export interface InitializeParams {
+    protocol_version: number;
+    host: HostInfo;
+    workspace: Workspace;
+    session?: { id?: string };
+    mode: 'tui' | 'web' | 'widget' | 'cli' | 'headless';
+    ui_capabilities?: string[];
+    capabilities_enabled?: Record<string, boolean>;
+}
+
+export interface ToolRegistration {
+    name: string;
+    description: string;
+    /** JSON Schema for the tool's arguments. */
+    parameters: Record<string, unknown>;
+    deferred?: boolean;
+}
+
+export interface CommandRegistration {
+    name: string;
+    description: string;
+}
+
+export interface Registrations {
+    tools?: ToolRegistration[];
+    commands?: CommandRegistration[];
+    flags?: string[];
+    subscriptions?: string[];
+}
+
+export interface InitializeResult {
+    protocol_version: number;
+    extension: { name: string; version: string };
+    registrations?: Registrations;
+}
+
+export interface ToolExecuteParams {
+    call_id: string;
+    tool: string;
+    arguments: Record<string, unknown>;
+    context: Context;
+}
+
+export interface ToolExecuteResult {
+    content: string;
+    is_error?: boolean;
+    details?: unknown;
+}
+
+export interface ToolUpdateParams {
+    call_id: string;
+    message?: string;
+    progress?: number;
+    details?: unknown;
+}
+
+export interface EventParams {
+    event: string;
+    context: Context;
+    payload?: Record<string, unknown>;
+}

package/src/schema.ts

@@ -0,0 +1,29 @@
+/**
+ * Turn a tool's declared `parameters` into the JSON Schema that goes on the wire.
+ *
+ * Three accepted shapes (the wire truth is always JSON Schema):
+ * - a **zod v4** schema → converted with zod's built-in `z.toJSONSchema()`.
+ * - a **TypeBox** schema → TypeBox schemas ARE JSON Schema, passed through.
+ * - a **raw JSON Schema** object → passed through unchanged.
+ */
+import { z } from 'zod';
+
+/** Anything acceptable as a tool's `parameters`. */
+export type ParameterSchema = z.ZodType | Record<string, unknown>;
+
+/** A zod v4 schema carries the internal `_zod` marker; nothing else we accept does. */
+function isZodSchema(value: unknown): value is z.ZodType {
+    return typeof value === 'object' && value !== null && '_zod' in value;
+}
+
+/** Normalize `schema` to a JSON Schema object (draft 2020-12 for zod). */
+export function toJsonSchema(schema: ParameterSchema): Record<string, unknown> {
+    if (isZodSchema(schema)) {
+        // `io: 'input'` gives the schema the LLM should fill (pre-transform).
+        return z.toJSONSchema(schema, { io: 'input' }) as Record<string, unknown>;
+    }
+    // TypeBox schemas and raw JSON Schema are already JSON Schema. Round-trip
+    // through JSON to drop any symbol keys (TypeBox's `[Kind]`) that would never
+    // survive the wire anyway.
+    return JSON.parse(JSON.stringify(schema)) as Record<string, unknown>;
+}

package/src/test-host.ts

@@ -0,0 +1,92 @@
+/**
+ * `createTestHost` — an in-process scripted SEP host for unit-testing an
+ * extension without spawning a subprocess. It plays the host side of the
+ * protocol over a `linkedPair`, so tests drive `initialize`, `tool/execute`
+ * (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 type { Extension } from './extension.js';
+import { linkedPair } from './transport.js';
+
+let callSeq = 0;
+
+export interface CallToolOptions {
+    /** Receives each `tool/update` the extension streams for this call. */
+    onUpdate?: (update: ToolUpdateParams) => void;
+    /** Abort the call — the host sends `$/cancel` and the promise rejects. */
+    signal?: AbortSignal;
+    /** Override the dispatch context (defaults to a command-tier test epoch). */
+    context?: Context;
+}
+
+export interface TestHost {
+    initialize(overrides?: Partial<InitializeParams>): Promise<InitializeResult>;
+    callTool(tool: string, args: Record<string, unknown>, opts?: CallToolOptions): Promise<ToolExecuteResult>;
+    ping(): Promise<Record<string, unknown>>;
+    sendEvent(event: string, payload?: Record<string, unknown>, context?: Context): void;
+    shutdown(): Promise<void>;
+    close(): void;
+}
+
+const DEFAULT_CONTEXT: Context = { token: 'test-epoch', tier: 'command' };
+
+export function createTestHost(extension: Extension): TestHost {
+    const [hostT, extT] = linkedPair();
+    const extHandle = extension.connect(extT);
+    /** call_id → the caller's onUpdate, so streamed progress reaches the test. */
+    const updateSinks = new Map<string, (u: ToolUpdateParams) => void>();
+
+    const host = new Peer({ send: (frame) => hostT.send(frame) });
+    host.setNotificationHandler(method.TOOL_UPDATE, (params) => {
+        const p = params as ToolUpdateParams;
+        updateSinks.get(p.call_id)?.(p);
+    });
+    // Extension notifications the host just observes in tests.
+    host.setNotificationHandler(method.LOG, () => {});
+    host.setNotificationHandler(method.REGISTRY_UPDATE, () => {});
+    hostT.start((frame) => host.receive(frame));
+
+    return {
+        initialize(overrides) {
+            const params: InitializeParams = {
+                protocol_version: PROTOCOL_VERSION,
+                host: { name: 'smooth-test-host', version: '0.0.0' },
+                workspace: { root: process.cwd(), trusted: true },
+                mode: 'headless',
+                capabilities_enabled: { tools: true },
+                ...overrides,
+            };
+            return host.request<InitializeResult>(method.INITIALIZE, params);
+        },
+        async callTool(tool, args, opts = {}) {
+            const call_id = `test-call-${++callSeq}`;
+            if (opts.onUpdate) updateSinks.set(call_id, opts.onUpdate);
+            try {
+                return await host.request<ToolExecuteResult>(
+                    method.TOOL_EXECUTE,
+                    { call_id, tool, arguments: args, context: opts.context ?? DEFAULT_CONTEXT },
+                    opts.signal,
+                );
+            } finally {
+                updateSinks.delete(call_id);
+            }
+        },
+        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 shutdown() {
+            await host.request(method.SHUTDOWN, {});
+        },
+        close() {
+            extHandle.close();
+            host.close();
+            hostT.close();
+        },
+    };
+}

package/src/transport.ts

@@ -0,0 +1,88 @@
+/**
+ * Transports carry JSON-RPC frames between two peers.
+ *
+ * - `stdioTransport` — the real wire: ndjson over a process's stdin/stdout,
+ *   byte-for-byte the framing MCP stdio uses.
+ * - `linkedPair` — two in-memory transports wired to each other, for driving an
+ *   extension from an in-process test host with no subprocess.
+ */
+import { createInterface } from 'node:readline';
+import type { Readable, Writable } from 'node:stream';
+import type { JsonRpcFrame } from './jsonrpc.js';
+
+export interface Transport {
+    send(frame: JsonRpcFrame): void;
+    /** Begin delivering inbound frames. Call once. */
+    start(onFrame: (frame: JsonRpcFrame) => void): void;
+    close(): void;
+}
+
+/** ndjson over a readable/writable pair (defaults to this process's stdio). */
+export function stdioTransport(input: Readable = process.stdin, output: Writable = process.stdout): Transport {
+    let rl: ReturnType<typeof createInterface> | undefined;
+    return {
+        send(frame) {
+            output.write(`${JSON.stringify(frame)}\n`);
+        },
+        start(onFrame) {
+            rl = createInterface({ input, terminal: false });
+            rl.on('line', (line) => {
+                if (!line.trim()) return;
+                let frame: JsonRpcFrame;
+                try {
+                    frame = JSON.parse(line) as JsonRpcFrame;
+                } catch {
+                    // A malformed line is not a valid frame; stderr, not the wire.
+                    process.stderr.write(`sep: dropping unparseable line: ${line}\n`);
+                    return;
+                }
+                onFrame(frame);
+            });
+        },
+        close() {
+            rl?.close();
+        },
+    };
+}
+
+/**
+ * Two transports wired to each other. A frame `send`-ed on one is delivered to
+ * the other's `onFrame` on a microtask (mimicking the async wire and avoiding
+ * reentrancy). Frames sent before the peer calls `start` are buffered.
+ */
+export function linkedPair(): [Transport, Transport] {
+    const a = new InMemoryTransport();
+    const b = new InMemoryTransport();
+    a.peer = b;
+    b.peer = a;
+    return [a, b];
+}
+
+class InMemoryTransport implements Transport {
+    peer!: InMemoryTransport;
+    private onFrame?: (frame: JsonRpcFrame) => void;
+    private buffer: JsonRpcFrame[] = [];
+    private closed = false;
+
+    send(frame: JsonRpcFrame): void {
+        if (this.peer.closed) return;
+        this.peer.deliver(frame);
+    }
+
+    start(onFrame: (frame: JsonRpcFrame) => void): void {
+        this.onFrame = onFrame;
+        const pending = this.buffer;
+        this.buffer = [];
+        for (const f of pending) queueMicrotask(() => this.onFrame?.(f));
+    }
+
+    close(): void {
+        this.closed = true;
+    }
+
+    private deliver(frame: JsonRpcFrame): void {
+        if (this.closed) return;
+        if (this.onFrame) queueMicrotask(() => this.onFrame?.(frame));
+        else this.buffer.push(frame);
+    }
+}