@ryuhq/sdk 0.0.5

package/src/mcp/server.ts

@@ -0,0 +1,351 @@
+/**
+ * SDK MCP stdio server — exposes a set of SDK Runnables (and optional
+ * passthrough registrations from Ghost / Shadow) as MCP tools over stdio,
+ * so any MCP host can discover and call them.
+ *
+ * The server speaks the same JSON-RPC 2.0 / newline-delimited protocol as
+ * `apps/core/src/sidecar/mcp/client.rs` and as `client.ts` in this package.
+ *
+ * POLICY NOTE: this server does NOT implement tool-approval, permission grants,
+ * or any Gateway-level policy.  Approval stays in the chat layer; policy stays
+ * in the Gateway (per issue #86).  Callers must not route policy decisions
+ * through this server.
+ *
+ * ## Minimal Runnable contract
+ *
+ * The full `defineAgent / defineWorkflow / defineTool / defineSkill` authoring
+ * API is delivered by issue #205.  This unit only needs the *consume side*:
+ * an executable object with a name and a `run()` method.  Once #205 ships, its
+ * builders will produce objects that satisfy this same interface.
+ */
+
+import { createInterface } from "node:readline";
+import type { McpStdioCommand, McpTool } from "./client.ts";
+import { callTool, listTools, MCP_PROTOCOL_VERSION } from "./client.ts";
+
+// ── Minimal Runnable contract ─────────────────────────────────────────────────
+
+/** JSON Schema fragment — enough to describe a tool's input arguments. */
+export interface JsonSchema {
+	description?: string;
+	properties?: Record<string, JsonSchema>;
+	required?: string[];
+	type?: string;
+	[key: string]: unknown;
+}
+
+/**
+ * The minimal executable Runnable interface consumed by this bridge.
+ *
+ * When #205 ships its `defineAgent / defineTool / ...` API, those builders must
+ * return objects that satisfy this interface so they plug straight in here
+ * without any adapter.
+ */
+export interface SdkRunnable {
+	/** Human-readable description shown to MCP hosts. */
+	description?: string;
+	/** JSON Schema for the tool's input arguments. */
+	inputSchema?: JsonSchema;
+	/** Stable, unique tool name (no spaces; used as the MCP tool name). */
+	name: string;
+	/**
+	 * Execute the runnable with the given arguments and return a result.
+	 * The result is JSON-encoded into an MCP `text` content block.
+	 */
+	run(args: unknown): Promise<unknown>;
+}
+
+// ── Passthrough (Ghost / Shadow) ──────────────────────────────────────────────
+
+/**
+ * A passthrough registration forwards `tools/list` + `tools/call` to a remote
+ * MCP server (e.g. Ghost at its stdio command, or Shadow at :3030).  The tools
+ * are re-advertised under their original names; calls are forwarded verbatim.
+ *
+ * This is the mechanism by which orphaned Ghost (29 computer-use tools) and
+ * Shadow (:3030 capture/search tools) can be advertised to any MCP host without
+ * embedding their implementation in the SDK.
+ */
+export interface PassthroughRegistration {
+	/** Command descriptor for the upstream MCP stdio server. */
+	command: McpStdioCommand;
+	/** Label used in error messages (e.g. "ghost", "shadow"). */
+	label: string;
+}
+
+// ── JSON-RPC helpers ──────────────────────────────────────────────────────────
+
+interface JsonRpcRequest {
+	id?: number | string | null;
+	jsonrpc: "2.0";
+	method: string;
+	params?: unknown;
+}
+
+interface JsonRpcResponse {
+	error?: { code: number; message: string };
+	id: number | string | null;
+	jsonrpc: "2.0";
+	result?: unknown;
+}
+
+function respond(
+	id: number | string | null | undefined,
+	result: unknown
+): JsonRpcResponse {
+	return { jsonrpc: "2.0", id: id ?? null, result };
+}
+
+function respondError(
+	id: number | string | null | undefined,
+	code: number,
+	message: string
+): JsonRpcResponse {
+	return { jsonrpc: "2.0", id: id ?? null, error: { code, message } };
+}
+
+/** Wrap a `run()` result in the MCP `tools/call` content-block envelope. */
+function wrapContent(value: unknown): {
+	content: { type: string; text: string }[];
+} {
+	return {
+		content: [
+			{
+				type: "text",
+				text: typeof value === "string" ? value : JSON.stringify(value),
+			},
+		],
+	};
+}
+
+/**
+ * Unwrap an MCP `tools/call` content-block envelope back to a plain value.
+ * If the text is valid JSON it is parsed; otherwise the raw string is returned.
+ *
+ * This is exported so tests can verify that `decode(wrapContent(x))` round-trips
+ * back to `x` and that `client.callTool()` output matches a direct `run()`.
+ */
+export function unwrapContent(raw: unknown): unknown {
+	const r = raw as { content?: { type: string; text: string }[] } | null;
+	const text = r?.content?.[0]?.text;
+	if (text === undefined) {
+		return raw;
+	}
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+
+// ── McpServer ─────────────────────────────────────────────────────────────────
+
+/**
+ * An MCP stdio server that exposes SDK Runnables and optional passthrough
+ * registrations as MCP tools.
+ *
+ * @example
+ * ```ts
+ * import { McpServer } from "@ryuhq/sdk/mcp/server"
+ *
+ * const server = new McpServer()
+ *   .register({ name: "greet", run: (a) => Promise.resolve(`Hello!`) })
+ *
+ * await server.serve()  // reads stdin, writes stdout until EOF
+ * ```
+ */
+export class McpServer {
+	private readonly runnables = new Map<string, SdkRunnable>();
+	private readonly passthroughs: PassthroughRegistration[] = [];
+
+	/**
+	 * Register an SDK Runnable as an MCP tool.
+	 * Returns `this` for chaining.
+	 */
+	register(runnable: SdkRunnable): this {
+		this.runnables.set(runnable.name, runnable);
+		return this;
+	}
+
+	/**
+	 * Register a passthrough to an external MCP stdio server (e.g. Ghost or
+	 * Shadow).  Tools from that server are fetched lazily and re-advertised.
+	 * Returns `this` for chaining.
+	 */
+	passthrough(registration: PassthroughRegistration): this {
+		this.passthroughs.push(registration);
+		return this;
+	}
+
+	/** Fetch all tools: local Runnables + passthrough tools. */
+	private async allTools(): Promise<McpTool[]> {
+		const local: McpTool[] = [...this.runnables.values()].map((r) => ({
+			name: r.name,
+			description: r.description,
+			inputSchema: r.inputSchema,
+		}));
+
+		const remote: McpTool[] = [];
+		for (const pt of this.passthroughs) {
+			try {
+				const tools = await listTools(pt.command);
+				remote.push(...tools);
+			} catch (err) {
+				// Degrade gracefully: log but don't crash the server.
+				process.stderr.write(
+					`[mcp-server] passthrough '${pt.label}' list_tools failed: ${err}\n`
+				);
+			}
+		}
+
+		return [...local, ...remote];
+	}
+
+	/** Handle a `tools/call` request. */
+	private async handleCallTool(name: string, args: unknown): Promise<unknown> {
+		const local = this.runnables.get(name);
+		if (local) {
+			const result = await local.run(args);
+			return wrapContent(result);
+		}
+
+		// Not a local Runnable — try passthrough servers in order.
+		for (const pt of this.passthroughs) {
+			try {
+				const tools = await listTools(pt.command);
+				if (tools.some((t) => t.name === name)) {
+					return await callTool(pt.command, name, args);
+				}
+			} catch {
+				// continue to next passthrough
+			}
+		}
+
+		throw new Error(`Unknown tool: ${name}`);
+	}
+
+	/**
+	 * Handle a single parsed JSON-RPC request line. Returns the response to write
+	 * (or null for notifications that require no response).
+	 */
+	private async handleRequest(
+		req: JsonRpcRequest,
+		initialized: { value: boolean },
+		write: (obj: unknown) => void
+	): Promise<void> {
+		const { id, method, params } = req;
+
+		if (method === "initialize") {
+			initialized.value = true;
+			write(
+				respond(id, {
+					protocolVersion: MCP_PROTOCOL_VERSION,
+					capabilities: { tools: {} },
+					serverInfo: { name: "ryu-sdk-server", version: "0.0.1" },
+				})
+			);
+			return;
+		}
+
+		if (method === "notifications/initialized") {
+			// Notification — no response required.
+			return;
+		}
+
+		if (!initialized.value) {
+			write(respondError(id, -32_002, "Server not initialized"));
+			return;
+		}
+
+		if (method === "tools/list") {
+			try {
+				const tools = await this.allTools();
+				write(respond(id, { tools }));
+			} catch (err) {
+				write(respondError(id, -32_603, String(err)));
+			}
+			return;
+		}
+
+		if (method === "tools/call") {
+			await this.handleToolsCall(id, params, write);
+			return;
+		}
+
+		write(respondError(id, -32_601, `Method not found: ${method}`));
+	}
+
+	/** Handle a `tools/call` JSON-RPC request. */
+	private async handleToolsCall(
+		id: number | string | null | undefined,
+		params: unknown,
+		write: (obj: unknown) => void
+	): Promise<void> {
+		const p = params as { name?: string; arguments?: unknown } | undefined;
+		const toolName = p?.name;
+		const toolArgs = p?.arguments ?? {};
+		if (typeof toolName !== "string") {
+			write(respondError(id, -32_602, "tools/call requires 'name'"));
+			return;
+		}
+		try {
+			const result = await this.handleCallTool(toolName, toolArgs);
+			write(respond(id, result));
+		} catch (err) {
+			write(
+				respond(id, {
+					content: [{ type: "text", text: String(err) }],
+					isError: true,
+				})
+			);
+		}
+	}
+
+	/**
+	 * Start reading JSON-RPC requests from the given readable stream and writing
+	 * responses to the given writable stream.
+	 *
+	 * Defaults to `process.stdin` / `process.stdout`.  Passing explicit streams
+	 * lets tests inject a pair of in-process pipes.
+	 *
+	 * Resolves when the input stream ends (EOF).
+	 */
+	serve(
+		input: NodeJS.ReadableStream = process.stdin,
+		output: NodeJS.WritableStream = process.stdout
+	): Promise<void> {
+		const write = (obj: unknown) => {
+			output.write(`${JSON.stringify(obj)}\n`);
+		};
+
+		const initialized = { value: false };
+
+		return new Promise<void>((resolve) => {
+			const rl = createInterface({
+				input,
+				crlfDelay: Number.POSITIVE_INFINITY,
+			});
+
+			rl.on("line", (rawLine) => {
+				const line = rawLine.trim();
+				if (!line) {
+					return;
+				}
+
+				let req: JsonRpcRequest;
+				try {
+					req = JSON.parse(line) as JsonRpcRequest;
+				} catch {
+					write(respondError(null, -32_700, "Parse error"));
+					return;
+				}
+
+				this.handleRequest(req, initialized, write).catch((err) => {
+					write(respondError(req.id, -32_603, String(err)));
+				});
+			});
+
+			rl.on("close", resolve);
+		});
+	}
+}

package/src/model/client.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Unit tests for the gateway-mandatory model client (TS layer).
+ *
+ * The transport is now the Rust core (`@ryuhq/sdk-native` → `crates/ryu-sdk`), so
+ * the wire-shape and SSE-parsing assertions live in the Rust crate's tests
+ * (`cargo test -p ryu-sdk`) — they cannot be exercised here by mocking JS
+ * `fetch`, because the native client uses reqwest, not `fetch`. These tests
+ * cover what the TS layer is responsible for: egress enforcement (delegated to
+ * Rust), the public client/factory shape, and base-URL/model resolution.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { defineModel } from "./client.ts";
+import { assertAllowedEgressUrl } from "./gateway.ts";
+
+// Top-level regex constant (avoids lint/performance/useTopLevelRegex)
+const RE_EGRESS_BLOCKED = /egress is not allowed/i;
+
+const MOCK_GATEWAY = "http://127.0.0.1:7981";
+
+// ── Egress enforcement (delegated to the Rust core) ───────────────────────────
+
+describe("egress enforcement", () => {
+	it("rejects api.openai.com as a base URL", () => {
+		expect(() =>
+			defineModel("gpt-4o", { baseUrl: "https://api.openai.com/v1" })
+		).toThrow(RE_EGRESS_BLOCKED);
+	});
+
+	it("rejects api.anthropic.com as a base URL", () => {
+		expect(() =>
+			defineModel("claude-3-5-sonnet", {
+				baseUrl: "https://api.anthropic.com/v1",
+			})
+		).toThrow(RE_EGRESS_BLOCKED);
+	});
+
+	it("rejects generativelanguage.googleapis.com", () => {
+		expect(() =>
+			defineModel("gemini-2.5-flash", {
+				baseUrl: "https://generativelanguage.googleapis.com/v1beta",
+			})
+		).toThrow(RE_EGRESS_BLOCKED);
+	});
+
+	it("rejects openrouter.ai", () => {
+		expect(() =>
+			defineModel("gpt-4o", { baseUrl: "https://openrouter.ai/api/v1" })
+		).toThrow(RE_EGRESS_BLOCKED);
+	});
+
+	it("allows a loopback gateway URL", () => {
+		expect(() =>
+			defineModel("gpt-4o", { baseUrl: "http://127.0.0.1:7981" })
+		).not.toThrow();
+	});
+
+	it("allows localhost gateway URL", () => {
+		expect(() =>
+			defineModel("gpt-4o", { baseUrl: "http://localhost:7981" })
+		).not.toThrow();
+	});
+
+	it("assertAllowedEgressUrl throws on direct provider URL", () => {
+		expect(() => assertAllowedEgressUrl("https://api.openai.com/v1")).toThrow(
+			RE_EGRESS_BLOCKED
+		);
+	});
+
+	it("assertAllowedEgressUrl passes for loopback", () => {
+		expect(() => assertAllowedEgressUrl("http://127.0.0.1:7981")).not.toThrow();
+	});
+});
+
+// ── Client / factory shape ────────────────────────────────────────────────────
+
+describe("ModelClient shape", () => {
+	it("exposes chat() and stream() backed by the native core", () => {
+		const client = defineModel("gpt-4o", { baseUrl: MOCK_GATEWAY });
+		expect(typeof client.chat).toBe("function");
+		expect(typeof client.stream).toBe("function");
+	});
+
+	it("reports the configured model id", () => {
+		const client = defineModel("claude-3-5-sonnet", { baseUrl: MOCK_GATEWAY });
+		expect(client.model).toBe("claude-3-5-sonnet");
+	});
+});
+
+// ── defineModel factory ───────────────────────────────────────────────────────
+
+describe("defineModel", () => {
+	it("returns a ModelClient with the given model id", () => {
+		const client = defineModel("claude-3-5-sonnet", { baseUrl: MOCK_GATEWAY });
+		expect(client.model).toBe("claude-3-5-sonnet");
+	});
+
+	it("uses the default gateway URL when no baseUrl is given", () => {
+		const prev = process.env.RYU_GATEWAY_URL;
+		process.env.RYU_GATEWAY_URL = "";
+
+		const client = defineModel("gpt-4o");
+		expect(client.baseUrl).toBe("http://127.0.0.1:7981");
+
+		process.env.RYU_GATEWAY_URL = prev ?? "";
+	});
+});

package/src/model/client.ts

@@ -0,0 +1,179 @@
+/**
+ * Gateway-mandatory model client for the Ryu SDK.
+ *
+ * Rust-cored: this is a thin TypeScript wrapper over the `@ryuhq/sdk-native`
+ * addon's `ModelClient`, which is the `crates/ryu-sdk` Rust core. Every model
+ * call is routed by the Rust core to the Ryu gateway's OpenAI-compatible
+ * `/v1/chat/completions` endpoint; direct-provider base URLs are rejected at
+ * construction. No provider SDK or base URL is ever imported here.
+ *
+ * Usage:
+ *
+ *   const model = defineModel("gpt-4o");
+ *   const reply = await model.chat([{ role: "user", content: "hello" }]);
+ *   for await (const delta of model.stream([{ role: "user", content: "hi" }])) {
+ *     process.stdout.write(delta.content);
+ *   }
+ */
+
+import * as native from "@ryuhq/sdk-native";
+
+// ── Wire types (OpenAI-compat subset) ─────────────────────────────────────────
+
+/** A single message in a chat conversation. */
+export interface ChatMessage {
+	/** The message text. */
+	content: string;
+	/** The speaker: "system", "user", or "assistant". */
+	role: "system" | "user" | "assistant";
+}
+
+/** A streaming chat completion delta. */
+export interface ChatDelta {
+	/** Incremental text fragment from the model. */
+	content: string | null;
+	/** Non-null on the final chunk when `finish_reason` is set. */
+	finishReason: string | null;
+}
+
+/** Non-streaming chat completion result. */
+export interface ChatResult {
+	/** The full assistant reply text. */
+	content: string;
+	/** The gateway/model-reported finish reason. */
+	finishReason: string | null;
+	/** Usage stats as reported by the gateway (optional — gateway may omit). */
+	usage?: {
+		promptTokens: number;
+		completionTokens: number;
+		totalTokens: number;
+	};
+}
+
+/** Options accepted by `defineModel`. */
+export interface ModelClientOptions {
+	/**
+	 * Gateway base URL (no trailing `/v1`). Defaults to `RYU_GATEWAY_URL` then
+	 * the Rust core's default. Direct provider URLs are rejected at construction.
+	 */
+	baseUrl?: string;
+	/**
+	 * Bearer token forwarded to the gateway. Defaults to `RYU_GATEWAY_TOKEN`.
+	 * This is the gateway token, never a provider API key.
+	 */
+	token?: string;
+}
+
+// ── ModelClient ───────────────────────────────────────────────────────────────
+
+/**
+ * A gateway-mandatory model client backed by the Rust core.
+ *
+ * All calls go through the native `ModelClient`; if the configured base URL is a
+ * direct provider, construction throws.
+ */
+export class ModelClient {
+	readonly model: string;
+	readonly baseUrl: string;
+	private readonly native: native.ModelClient;
+
+	constructor(model: string, options: ModelClientOptions = {}) {
+		// Constructing the native client validates egress and resolves the base
+		// URL/token in the Rust core.
+		this.native = new native.ModelClient(
+			model,
+			options.baseUrl ?? null,
+			options.token ?? null
+		);
+		this.model = model;
+		this.baseUrl = options.baseUrl ?? native.resolveGatewayUrl();
+	}
+
+	/** Send a non-streaming chat completion request to the gateway. */
+	async chat(messages: ChatMessage[]): Promise<ChatResult> {
+		const res = await this.native.chat(messages);
+		const usage =
+			res.promptTokens === undefined &&
+			res.completionTokens === undefined &&
+			res.totalTokens === undefined
+				? undefined
+				: {
+						promptTokens: res.promptTokens ?? 0,
+						completionTokens: res.completionTokens ?? 0,
+						totalTokens: res.totalTokens ?? 0,
+					};
+		return {
+			content: res.content,
+			finishReason: res.finishReason ?? null,
+			usage,
+		};
+	}
+
+	/** Send a streaming chat completion request, yielding deltas as they arrive. */
+	async *stream(messages: ChatMessage[]): AsyncGenerator<ChatDelta> {
+		// Bridge the native push-callback into a pull async-generator via a small
+		// queue. The native side calls back with `null` to signal clean end and
+		// with an Error on failure.
+		const queue: ChatDelta[] = [];
+		let done = false;
+		let failure: Error | null = null;
+		let wake: (() => void) | null = null;
+		const notify = () => {
+			if (wake) {
+				const w = wake;
+				wake = null;
+				w();
+			}
+		};
+
+		this.native.stream(messages, (err, delta) => {
+			if (err) {
+				failure = err;
+				done = true;
+			} else if (delta === null || delta === undefined) {
+				done = true;
+			} else {
+				queue.push({
+					content: delta.content ?? null,
+					finishReason: delta.finishReason ?? null,
+				});
+			}
+			notify();
+		});
+
+		while (true) {
+			while (queue.length > 0) {
+				const next = queue.shift();
+				if (next) {
+					yield next;
+				}
+			}
+			if (failure) {
+				throw failure;
+			}
+			if (done) {
+				return;
+			}
+			await new Promise<void>((resolve) => {
+				wake = resolve;
+			});
+		}
+	}
+}
+
+// ── Factory ─────────────────────────────────────────────────────────────────
+
+/**
+ * Create a gateway-mandatory model client for `modelId`.
+ *
+ *   const model = defineModel("gpt-4o");
+ *   const model = defineModel("claude-3-5-sonnet", { baseUrl: "http://my-gateway:7981" });
+ *
+ * A direct provider URL throws immediately (egress enforcement in the Rust core).
+ */
+export function defineModel(
+	modelId: string,
+	options: ModelClientOptions = {}
+): ModelClient {
+	return new ModelClient(modelId, options);
+}

package/src/model/gateway.ts

@@ -0,0 +1,41 @@
+/**
+ * Gateway configuration + egress enforcement for the Ryu SDK model client.
+ *
+ * Rust-cored: every function here delegates to the `@ryuhq/sdk-native` addon, so
+ * the gateway URL/token resolution and the direct-provider egress blocklist are
+ * the exact same implementation (`crates/ryu-sdk/src/gateway.rs`) used by the
+ * Go/Python bindings and Core itself — one source of truth, no drift.
+ */
+
+import * as native from "@ryuhq/sdk-native";
+
+/** Default base URL for the local Ryu gateway — matches Core's DEFAULT_GATEWAY_URL. */
+export const DEFAULT_GATEWAY_URL = "http://127.0.0.1:7981";
+
+/**
+ * Resolve the effective gateway base URL.
+ *
+ * Resolution order (in the Rust core):
+ *   1. `RYU_GATEWAY_URL` env var (when non-empty).
+ *   2. `DEFAULT_GATEWAY_URL`.
+ */
+export function resolveGatewayUrl(): string {
+	return native.resolveGatewayUrl();
+}
+
+/**
+ * Resolve the optional gateway bearer token (`RYU_GATEWAY_TOKEN`), or
+ * `undefined` when unset/empty.
+ */
+export function resolveGatewayToken(): string | undefined {
+	return native.resolveGatewayToken() ?? undefined;
+}
+
+/**
+ * Validate that `baseUrl` is an allowed egress target. Throws a descriptive
+ * `Error` (from the Rust core) when the URL matches a known direct-provider
+ * pattern, enforcing the BYOK-at-the-gateway rule.
+ */
+export function assertAllowedEgressUrl(baseUrl: string): void {
+	native.assertAllowedEgress(baseUrl);
+}