@ryuhq/sdk 0.0.5

package/src/runnable/app.ts

@@ -0,0 +1,233 @@
+/**
+ * Ryu App authoring factory — `defineApp`.
+ *
+ * A "Ryu App" bundles one or more tools whose results render an interactive
+ * widget inline in chat (the ChatGPT-Apps-style surface). `defineApp` assembles a
+ * complete `plugin.json` `PluginManifest` from a declarative description, deriving
+ * the render-vs-companion split exactly the way Core's in-process provider does
+ * (`apps/core/src/sidecar/mcp/apps/mod.rs` `tools()`):
+ *
+ *   - A **render** tool (`accessible` unset/false) produces the widget: it gets a
+ *     `contributes.widgets[]` entry binding its id to the app's
+ *     `ui://widget/<slug>.html` template, and its runnable config carries
+ *     `widget:true` plus `invoking`/`invoked` status labels.
+ *   - A **companion** tool (`accessible:true`) is a call target a mounted widget
+ *     may invoke: it carries `widget_accessible:true` and gets no widget template.
+ *
+ * v1 boundary: this is **declarative pass-through only** — there is no `run`
+ * handler. Third-party tool code execution needs the plugin runtime (out of
+ * scope); the widget renders from `window.openai.toolInput`/`toolOutput` and Core
+ * echoes the validated arguments as `structuredContent`. `ryu pack` bundles the
+ * `uiEntry` source into the manifest's `ui_code`.
+ */
+
+import type {
+	Contributes,
+	PluginManifest,
+	Requires,
+	RunnableMeta,
+	Surface,
+	ToolAppConfig,
+	WidgetContribution,
+} from "../manifest.ts";
+import { PluginManifestSchema } from "../manifest.ts";
+
+/** The default widget MIME dialect (mirrors Core `default_widget_mime`). */
+const DEFAULT_APP_WIDGET_MIME = "text/html+skybridge";
+/** The default widget display mode (mirrors Core `default_widget_display_mode`). */
+const DEFAULT_APP_DISPLAY_MODE = "inline";
+
+/** One tool a Ryu App declares. */
+export interface AppToolSpec {
+	/**
+	 * True when this is a **companion** tool — a call target a mounted widget may
+	 * `callTool`. False/unset makes it a **render** tool that produces the widget.
+	 */
+	accessible?: boolean;
+	/** Human-readable description the model reads when choosing the tool. */
+	description: string;
+	/** JSON Schema object describing the tool's arguments. Optional. */
+	inputSchema?: Record<string, unknown>;
+	/** Status label shown when a render tool finishes (e.g. `"Chart ready"`). */
+	invoked?: string;
+	/** Status label shown while a render tool runs (e.g. `"Plotting chart…"`). */
+	invoking?: string;
+	/** Tool name (unqualified). The wire id is `<server>__<name>`. */
+	name: string;
+}
+
+/**
+ * The `requires` block as an AUTHOR writes it: both members optional. Distinct
+ * from the parsed {@link Requires} (where zod has applied its `[]` defaults, so
+ * both are present).
+ */
+export interface DefineAppRequires {
+	/** Plugins that must be installed + enabled before this app enables. */
+	apps?: Requires["apps"];
+	/**
+	 * Abstract capability edges the broker binds to a provider at enable time
+	 * (`[{ capability: "rag" }]`). This is what composable agent slots lower to.
+	 */
+	capabilities?: Requires["capabilities"];
+	/** Grants implied by those dependencies (declaration only). */
+	grants?: string[];
+}
+
+/** Options for {@link defineApp}. */
+export interface DefineAppOptions {
+	/** VS-Code-style activation events. Empty = eager (default `["*"]`). */
+	activationEvents?: string[];
+	/** Default widget display mode (`inline` | `fullscreen` | `pip`). */
+	displayMode?: string;
+	/** Permission grants the app declares it needs (e.g. `["mcp:web_search"]`). */
+	grants?: string[];
+	/** Reverse-domain plugin id (e.g. `"com.example.checklist"`). */
+	id: string;
+	/** Widget MIME dialect. Defaults to `text/html+skybridge`. */
+	mime?: string;
+	/**
+	 * Plugin-to-plugin dependencies. Core auto-enables them (in dependency order)
+	 * before this app, and refuses to disable one while this app still needs it.
+	 * Omit for the common case (no dependencies) — the key is then absent from the
+	 * emitted manifest entirely.
+	 */
+	requires?: DefineAppRequires;
+	/** MCP server namespace for the tool ids. Defaults to `slug`. */
+	server?: string;
+	/**
+	 * App slug — used to build the widget uri (`ui://widget/<slug>.html`) and, when
+	 * `server` is omitted, the MCP server namespace that qualifies each tool id.
+	 */
+	slug: string;
+	/**
+	 * Host surfaces this app runs on. **Omitted/empty = every surface** (the
+	 * backward-compatible default); it never means "hidden".
+	 */
+	targets?: Surface[];
+	/** Human-readable display name shown in the app store / launcher. */
+	title: string;
+	/** The tools this app exposes (at least one render tool is expected). */
+	tools: AppToolSpec[];
+	/**
+	 * Source entry (relative to the manifest dir) for the widget UI. `ryu pack`
+	 * bundles it into the manifest's `ui_code` so Core can serve the widget HTML.
+	 */
+	uiEntry: string;
+	/** Semver version string (e.g. `"1.0.0"`). */
+	version: string;
+}
+
+/** Build a fully-qualified tool id from a server namespace and tool name. */
+export function appToolId(server: string, name: string): string {
+	return `${server}__${name}`;
+}
+
+/**
+ * Assemble a `plugin.json` manifest for a Ryu App. The result matches Core's
+ * `PluginManifest` serde shape (validated through `PluginManifestSchema`) and can
+ * be written to disk, packed with `ryu pack`, or published with `ryu publish`.
+ *
+ * @example
+ * ```ts
+ * import { defineApp } from "@ryuhq/sdk"
+ *
+ * const manifest = defineApp({
+ *   id: "com.example.checklist",
+ *   title: "Checklist",
+ *   version: "1.0.0",
+ *   slug: "checklist",
+ *   uiEntry: "src/checklist.tsx",
+ *   tools: [
+ *     { name: "render", description: "Render a checklist", invoking: "Building…", invoked: "Ready" },
+ *     { name: "toggle", description: "Toggle an item", accessible: true },
+ *   ],
+ * })
+ * ```
+ */
+export function defineApp(options: DefineAppOptions): PluginManifest {
+	const server = options.server ?? options.slug;
+	const uri = `ui://widget/${options.slug}.html`;
+	const mime = options.mime ?? DEFAULT_APP_WIDGET_MIME;
+	const displayMode = options.displayMode ?? DEFAULT_APP_DISPLAY_MODE;
+	// Whether the app declares any companion tool. A render tool's widget may call
+	// tools only when the app has at least one companion — mirrors `has_companions`
+	// in Core's `apps::tools()`.
+	const hasCompanions = options.tools.some((t) => t.accessible === true);
+
+	const runnables: RunnableMeta[] = [];
+	const widgets: WidgetContribution[] = [];
+
+	for (const spec of options.tools) {
+		const isRender = spec.accessible !== true;
+		const id = appToolId(server, spec.name);
+
+		const config: ToolAppConfig = {
+			slug: id,
+			description: spec.description,
+			widget: isRender,
+			widget_accessible: isRender ? hasCompanions : true,
+			...(spec.inputSchema ? { input_schema: spec.inputSchema } : {}),
+			...(spec.invoking ? { invoking: spec.invoking } : {}),
+			...(spec.invoked ? { invoked: spec.invoked } : {}),
+		};
+
+		runnables.push({
+			id,
+			name: spec.name,
+			kind: "tool",
+			config,
+		});
+
+		if (isRender) {
+			widgets.push({
+				tool_id: id,
+				uri,
+				ui_entry: options.uiEntry,
+				mime,
+				default_display_mode: displayMode,
+			});
+		}
+	}
+
+	const contributes: Contributes = {
+		turn_hooks: [],
+		composer_controls: [],
+		settings_tabs: [],
+		slash_commands: [],
+		widgets,
+	};
+
+	const raw = {
+		id: options.id,
+		name: options.title,
+		version: options.version,
+		runnables,
+		permission_grants: options.grants ?? [],
+		activation_events: options.activationEvents ?? ["*"],
+		contributes,
+		// `targets: []` means EVERY surface, so an app that declares none is
+		// unrestricted — the backward-compatible default.
+		targets: options.targets ?? [],
+		// `requires` stays ABSENT (not `{apps:[],grants:[]}`) when undeclared, so the
+		// emitted manifest carries no key at all — matching Core's
+		// `Option<Requires>` + `skip_serializing_if = "Option::is_none"`.
+		...(options.requires
+			? {
+					requires: {
+						apps: options.requires.apps ?? [],
+						capabilities: options.requires.capabilities ?? [],
+						grants: options.requires.grants ?? [],
+					},
+				}
+			: {}),
+	};
+
+	const result = PluginManifestSchema.safeParse(raw);
+	if (!result.success) {
+		const first = result.error.issues[0];
+		const field = first?.path.join(".") ?? "unknown";
+		const message = first?.message ?? "validation failed";
+		throw new Error(`plugin.json validation failed at '${field}': ${message}`);
+	}
+	return result.data;
+}

package/src/runnable/index.ts

@@ -0,0 +1,61 @@
+/**
+ * Runnable — the single contract unifying Agent, Workflow, Tool, and Skill
+ * in the Ryu SDK.
+ *
+ * Design rules (from the M8 spike doc packages/sdk/README.md):
+ *   - An agent may invoke a workflow as a named tool.
+ *   - A workflow may orchestrate agents as steps.
+ *   - All model calls MUST go through `ctx.gateway` — never a direct provider.
+ *   - The four kinds are peers, not a hierarchy.
+ *
+ * This module re-exports all factory functions and types so consumers can
+ * import from `@ryuhq/sdk/runnable` as a single entry point.
+ */
+
+export type {
+	AgentCard,
+	AgentManifestOptions,
+	AgentOptions,
+	AgentRunnable,
+	AgentSlots,
+	CapabilitySlot,
+	ChatSlot,
+} from "./agent.ts";
+// biome-ignore lint/performance/noBarrelFile: intentional package entry point for @ryuhq/sdk/runnable
+export { defineAgent } from "./agent.ts";
+export type { AppToolSpec, DefineAppOptions } from "./app.ts";
+export { appToolId, defineApp } from "./app.ts";
+export type {
+	DurableClient,
+	EnginesClient,
+	HttpPrimitiveTransportOptions,
+	ImageClient,
+	MemoryClient,
+	MemoryItem,
+	PrimitiveBinding,
+	PrimitiveTransport,
+	RagChunk,
+	RagClient,
+	RagRerankResult,
+	RealtimeClient,
+	RealtimeSubscription,
+	RyuPrimitives,
+	SttClient,
+	TtsClient,
+} from "./primitives.ts";
+export {
+	createPrimitives,
+	httpPrimitiveTransport,
+	PRIMITIVE_BINDINGS,
+} from "./primitives.ts";
+export type {
+	GatewayClient,
+	Runnable,
+	RunnableContext,
+} from "./runnable-types.ts";
+export type { SkillOptions } from "./skill.ts";
+export { defineSkill } from "./skill.ts";
+export type { JsonSchemaProperty, ToolOptions, ToolSchema } from "./tool.ts";
+export { defineTool } from "./tool.ts";
+export type { WorkflowOptions, WorkflowStep } from "./workflow.ts";
+export { defineWorkflow } from "./workflow.ts";

package/src/runnable/primitives-hostapi.test.ts

@@ -0,0 +1,73 @@
+/**
+ * Lockstep guard: every SDK primitive that binds to a host-bridge RPC method must
+ * name a method that actually exists in the blessed host-API contract, with the
+ * SAME grant.
+ *
+ * `PRIMITIVE_BINDINGS` (`primitives.ts`) is the SDK's mirror of the host↔plugin
+ * method vocabulary. The canonical vocabulary now lives in
+ * `crates/ryu-kernel-contracts/schemas/host-api.json` (blessed from the Rust
+ * table; re-bless with `RYU_REGEN_SCHEMAS=1 cargo test -p ryu-kernel-contracts`).
+ * This test pins the `bridge`-transport bindings to that table so a renamed method
+ * or a drifted grant is caught here rather than at runtime. `direct` bindings hit
+ * Core data-path endpoints (not RPC methods) and `broker` bindings are abstract
+ * capabilities with no method yet, so only `bridge` bindings are checked.
+ *
+ * Deterministic, filesystem-only, no network.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { PRIMITIVE_BINDINGS } from "./primitives";
+
+const HOST_API_PATH = join(
+	import.meta.dir,
+	"../../../../crates/core/kernel-contracts/schemas/host-api.json"
+);
+
+interface HostApiMethodEntry {
+	capability: string;
+	grant: string | null;
+	method: string;
+	streaming: boolean;
+	tsHost: boolean;
+}
+
+const contract = JSON.parse(readFileSync(HOST_API_PATH, "utf8")) as {
+	version: string;
+	methods: HostApiMethodEntry[];
+};
+
+const grantByMethod = new Map<string, string | null>(
+	contract.methods.map((m) => [m.method, m.grant])
+);
+
+describe("PRIMITIVE_BINDINGS lockstep with the blessed host-API contract", () => {
+	test("every bridge binding names a method present in the contract", () => {
+		for (const [name, binding] of Object.entries(PRIMITIVE_BINDINGS)) {
+			if (binding.transport !== "bridge") {
+				continue;
+			}
+			expect(
+				grantByMethod.has(binding.method),
+				`${name} → method "${binding.method}" missing from host-api.json`
+			).toBe(true);
+		}
+	});
+
+	test("every bridge binding's grant matches the contract's grant for that method", () => {
+		for (const [name, binding] of Object.entries(PRIMITIVE_BINDINGS)) {
+			if (binding.transport !== "bridge") {
+				continue;
+			}
+			expect(
+				grantByMethod.get(binding.method),
+				`${name} → grant drift for "${binding.method}"`
+			).toBe(binding.grant);
+		}
+	});
+
+	test("the contract exposes at least one method (sanity)", () => {
+		expect(contract.methods.length).toBeGreaterThan(0);
+	});
+});

package/src/runnable/primitives.test.ts

@@ -0,0 +1,286 @@
+/**
+ * Tests for the composable primitive surface (program §6b).
+ *
+ * These verify the SDK-side contract WITHOUT a live Core node: a fake transport
+ * records which op each primitive method routes to, so we assert the vocabulary
+ * mirror (bridge/direct/broker + method/path/capability) matches `rpc.ts`.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { PluginManifestSchema, validateManifestStrict } from "../manifest.ts";
+import { defineAgent } from "./agent.ts";
+import {
+	createPrimitives,
+	httpPrimitiveTransport,
+	PRIMITIVE_BINDINGS,
+	type PrimitiveTransport,
+} from "./primitives.ts";
+
+interface Call {
+	body: unknown;
+	op: "bridge" | "direct" | "capability";
+	target: string;
+}
+
+function recordingTransport(): {
+	transport: PrimitiveTransport;
+	calls: Call[];
+} {
+	const calls: Call[] = [];
+	const transport: PrimitiveTransport = {
+		bridge(method, args) {
+			calls.push({ op: "bridge", target: method, body: args });
+			return Promise.resolve("bridge-ok");
+		},
+		direct(path, body) {
+			calls.push({ op: "direct", target: path, body });
+			return Promise.resolve(["direct-ok"]);
+		},
+		capability(cap, body) {
+			calls.push({ op: "capability", target: cap, body });
+			return Promise.resolve([]);
+		},
+	};
+	return { transport, calls };
+}
+
+describe("createPrimitives — transport routing mirrors rpc.ts", () => {
+	it("engines.complete routes through the bridge model.complete family", async () => {
+		const { transport, calls } = recordingTransport();
+		const p = createPrimitives(transport);
+		await p.engines.complete({ prompt: "hi", modelPrefKey: "chat" });
+		expect(calls).toHaveLength(1);
+		const [call] = calls;
+		if (!call) {
+			throw new Error("expected one call");
+		}
+		expect(call.op).toBe("bridge");
+		expect(call.target).toBe("model.complete");
+		// camelCase modelPrefKey lowers to the snake_case wire key.
+		expect(call.body).toMatchObject({ prompt: "hi", model_pref_key: "chat" });
+	});
+
+	it("media primitives route host-direct to their Core endpoints", async () => {
+		const { transport, calls } = recordingTransport();
+		const p = createPrimitives(transport);
+		await p.image.generate({ prompt: "a cat" });
+		await p.tts.speak({ text: "hello" });
+		await p.stt.transcribe({ audio: "data:audio/wav;base64,AAAA" });
+		expect(calls.map((c) => `${c.op}:${c.target}`)).toEqual([
+			"direct:/api/images/generate",
+			"direct:/api/voice/speak",
+			"direct:/api/voice/transcribe",
+		]);
+	});
+
+	it("stt.transcribe over the real HTTP transport uploads a multipart `file` (not JSON)", async () => {
+		let seen: { url: string; init: RequestInit } | undefined;
+		const fetchImpl = ((url: string, init: RequestInit) => {
+			seen = { url, init };
+			return Promise.resolve(
+				new Response(JSON.stringify({ text: "  hello world  " }), {
+					headers: { "content-type": "application/json" },
+				})
+			);
+		}) as unknown as typeof fetch;
+
+		const transport = httpPrimitiveTransport({
+			nodeUrl: "http://127.0.0.1:7980",
+			token: "t0k",
+			fetchImpl,
+		});
+		const p = createPrimitives(transport);
+		const text = await p.stt.transcribe({
+			audio: "data:audio/wav;base64,QUFBQQ==",
+			filename: "clip.wav",
+		});
+
+		// The transcript is parsed from Core's `{ text }` JSON and trimmed.
+		expect(text).toBe("hello world");
+		if (!seen) {
+			throw new Error("expected a fetch call");
+		}
+		expect(seen.url).toBe("http://127.0.0.1:7980/api/voice/transcribe");
+		// A JSON body would guarantee a 400 from Core's Multipart extractor.
+		const { body, headers } = seen.init;
+		expect(body).toBeInstanceOf(FormData);
+		const file = (body as FormData).get("file");
+		expect(file).toBeInstanceOf(Blob);
+		// No JSON content-type — FormData must set its own multipart boundary.
+		const ct = new Headers(headers).get("content-type") ?? "";
+		expect(ct.includes("application/json")).toBe(false);
+	});
+
+	it("tts.speak over the real HTTP transport returns a data: URL from audio/wav bytes", async () => {
+		let sentBody: unknown;
+		const fetchImpl = ((_url: string, init: RequestInit) => {
+			sentBody = init.body;
+			return Promise.resolve(
+				new Response(new Uint8Array([1, 2, 3, 4]), {
+					headers: { "content-type": "audio/wav" },
+				})
+			);
+		}) as unknown as typeof fetch;
+
+		const transport = httpPrimitiveTransport({
+			nodeUrl: "http://127.0.0.1:7980",
+			fetchImpl,
+		});
+		const p = createPrimitives(transport);
+		const url = await p.tts.speak({ text: "hi", voice: "alto" });
+
+		// JSON in (not FormData), data: URL out — the shipped type contract.
+		expect(typeof sentBody).toBe("string");
+		expect(JSON.parse(sentBody as string)).toMatchObject({
+			text: "hi",
+			voice: "alto",
+		});
+		expect(url.startsWith("data:audio/wav;base64,")).toBe(true);
+	});
+
+	it("broker-backed primitives POST to the capability broker (@requires-grant)", async () => {
+		const { transport, calls } = recordingTransport();
+		const p = createPrimitives(transport);
+		await p.rag.retrieve({ query: "q" });
+		await p.memory.recall({ query: "q" });
+		await p.realtime.broadcast({ room: "r", event: "e" });
+		await p.durable.checkpoint({ key: "k", state: {} });
+		await p.engines.embed({ input: "x" });
+		expect(calls.map((c) => c.target)).toEqual([
+			"rag",
+			"memory",
+			"realtime",
+			"durable",
+			"engines",
+		]);
+		expect(calls.every((c) => c.op === "capability")).toBe(true);
+		// The broker body carries the discriminating op + input.
+		const [ragCall] = calls;
+		if (!ragCall) {
+			throw new Error("expected a rag call");
+		}
+		expect(ragCall.body).toMatchObject({ op: "retrieve" });
+	});
+
+	it("every declared primitive has a binding entry (no silent drift)", () => {
+		const expected = [
+			"engines.complete",
+			"engines.embed",
+			"image.generate",
+			"tts.speak",
+			"stt.transcribe",
+			"rag.retrieve",
+			"rag.embed",
+			"rag.rerank",
+			"memory.recall",
+			"memory.store",
+			"realtime.broadcast",
+			"realtime.subscribe",
+			"durable.checkpoint",
+			"durable.resume",
+		];
+		for (const key of expected) {
+			expect(PRIMITIVE_BINDINGS[key]).toBeDefined();
+		}
+	});
+});
+
+describe("defineAgent — composable slots lower to a valid manifest", () => {
+	it("classic signature is unchanged (back-compat)", async () => {
+		let seen = "";
+		const a = defineAgent<{ q: string }, string>({
+			id: "agent-classic",
+			name: "Classic",
+			run({ q }, ctx) {
+				seen = q;
+				return ctx.gateway
+					.chat([{ role: "user", content: q }])
+					.then((r) => r.content);
+			},
+		});
+		expect(a.kind).toBe("agent");
+		expect(a.card.capabilities).toEqual([]);
+		const ctx = {
+			gateway: {
+				chat: () => Promise.resolve({ content: "ok", finishReason: null }),
+				async *stream() {
+					/* unused */
+				},
+			},
+		};
+		const out = await a.run({ q: "hello" }, ctx);
+		expect(seen).toBe("hello");
+		expect(out).toBe("ok");
+	});
+
+	it("slots lower to requires.capabilities + persona/model config", () => {
+		const cmo = defineAgent({
+			id: "agent-cmo",
+			name: "CMO",
+			chat: { model: "gpt-4o", persona: "You are a CMO." },
+			rag: true,
+			memory: { minVersion: "1.2.0" },
+			tts: "com.acme.elevenlabs",
+		});
+		expect(cmo.card.model).toBe("gpt-4o");
+		expect(cmo.card.persona).toBe("You are a CMO.");
+		expect(cmo.card.capabilities).toEqual([
+			{ capability: "rag" },
+			{ capability: "memory", min_version: "1.2.0" },
+			{ capability: "tts" },
+		]);
+		expect(cmo.card.providers.tts).toBe("com.acme.elevenlabs");
+
+		const manifest = cmo.toManifest({ id: "com.acme.cmo", version: "1.0.0" });
+		// Lowered manifest must pass the SDK's authoring schema…
+		expect(PluginManifestSchema.safeParse(manifest).success).toBe(true);
+		expect(manifest.requires?.capabilities).toEqual([
+			{ capability: "rag" },
+			{ capability: "memory", min_version: "1.2.0" },
+			{ capability: "tts" },
+		]);
+		const [agentMeta] = manifest.runnables;
+		if (!agentMeta) {
+			throw new Error("expected a lowered agent runnable");
+		}
+		expect(agentMeta.kind).toBe("agent");
+		expect(agentMeta.config).toMatchObject({
+			model: "gpt-4o",
+			persona: "You are a CMO.",
+			capability_providers: { tts: "com.acme.elevenlabs" },
+		});
+		// …and Core-strict validation (native addon when present; skip otherwise).
+		try {
+			validateManifestStrict(JSON.stringify(manifest));
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			if (!message.includes("@ryuhq/sdk-native")) {
+				throw err;
+			}
+		}
+	});
+
+	it("a slot-only agent synthesizes a chat-slot default run", async () => {
+		const bot = defineAgent({
+			id: "agent-bot",
+			name: "Bot",
+			chat: { persona: "Be terse." },
+		});
+		const messages: { role: string; content: string }[] = [];
+		const ctx = {
+			gateway: {
+				chat: (m: { role: string; content: string }[]) => {
+					messages.push(...m);
+					return Promise.resolve({ content: "reply", finishReason: null });
+				},
+				async *stream() {
+					/* unused */
+				},
+			},
+		};
+		const out = await bot.run("ping", ctx);
+		expect(out).toBe("reply");
+		expect(messages[0]).toEqual({ role: "system", content: "Be terse." });
+		expect(messages[1]).toEqual({ role: "user", content: "ping" });
+	});
+});