@ryuhq/sdk 0.1.14 → 0.2.2

package/src/mcp/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @ryuhq/sdk/mcp — MCP server + client surfaces.
+ *
+ * `McpServer` handles the MCP `initialize` handshake, `tools/list`,
+ * `tools/call`, and the content-block envelope over stdio; `listTools` /
+ * `callTool` drive a stdio MCP server. Re-exported here so consumers can
+ * import from `@ryuhq/sdk/mcp` (or the narrower `/mcp/server` and
+ * `/mcp/client` subpaths) as a single entry point.
+ */
+
+export type { McpStdioCommand, McpTool } from "./client.ts";
+export { callTool, listTools, MCP_PROTOCOL_VERSION } from "./client.ts";
+export type {
+	JsonSchema,
+	PassthroughRegistration,
+	SdkRunnable,
+} from "./server.ts";
+export { McpServer, unwrapContent } from "./server.ts";

package/src/mcp/server.ts

@@ -28,7 +28,8 @@ import { callTool, listTools, MCP_PROTOCOL_VERSION } from "./client.ts";
 /** JSON Schema fragment — enough to describe a tool's input arguments. */
 export interface JsonSchema {
 	description?: string;
-	properties?: Record<string, JsonSchema>;
+	/** Property schemas may use any JSON Schema dialect or nested shape. */
+	properties?: Record<string, unknown>;
 	required?: string[];
 	type?: string;
 	[key: string]: unknown;

package/src/model/index.ts

@@ -0,0 +1,22 @@
+/**
+ * @ryuhq/sdk/model — the gateway-mandatory model client.
+ *
+ * Every model call routes through the Ryu Gateway, never a direct provider.
+ * Re-exports the `ModelClient` / `defineModel` surface plus the gateway
+ * resolution + egress helpers, so consumers can import from
+ * `@ryuhq/sdk/model` as a single entry point.
+ */
+
+export type {
+	ChatDelta,
+	ChatMessage,
+	ChatResult,
+	ModelClientOptions,
+} from "./client.ts";
+export { defineModel, ModelClient } from "./client.ts";
+export {
+	assertAllowedEgressUrl,
+	DEFAULT_GATEWAY_URL,
+	resolveGatewayToken,
+	resolveGatewayUrl,
+} from "./gateway.ts";

package/src/plugin/ryu-plugin.ts

@@ -125,6 +125,27 @@ export interface ThemeContribution {
  *  are RPCs over the postMessage bridge; the plugin never holds a Core token or
  *  Tauri IPC handle directly. */
 export interface RyuHostServices {
+	/** Read and cooperatively stop Core-visible background processes. */
+	background: {
+		list(input?: { producer?: string; running_only?: boolean }): Promise<
+			{
+				process_id: string;
+				command: string;
+				cwd: string;
+				elapsed_ms: number;
+				running: boolean;
+				[key: string]: unknown;
+			}[]
+		>;
+		stop(input: { process_id: string }): Promise<{
+			ok: boolean;
+			requested: boolean;
+			process_id: string;
+		}>;
+	};
+	/** Read-only feature discovery. Older hosts may omit this method; treat that
+	 * as an empty capability set rather than assuming a native surface exists. */
+	capabilities?(): Promise<RyuHostCapabilities>;
 	/** Run a registered command by id (built-in or contributed). */
 	commands: { execute(id: string, ...args: unknown[]): Promise<unknown> };
 	/** Gateway-governed model access (chat/embed). Mirrors `@ryuhq/sdk` model
@@ -140,6 +161,21 @@ export interface RyuHostServices {
 	 *  or any other agent field (invariant: no capability returns a secret). Gated
 	 *  by the `core:list_agents` grant. */
 	listAgents(): Promise<{ id: string; name: string }[]>;
+	/** Mobile-native effects. These methods remain optional at the type boundary
+	 * because desktop, web, extension, and terminal hosts fail closed. */
+	native?: {
+		haptics(input: RyuNativeHapticsInput): Promise<RyuNativeHapticsResult>;
+		notifications: {
+			create(
+				input: RyuNativeNotificationInput
+			): Promise<RyuNativeNotificationResult>;
+		};
+		liveActivities: {
+			update(
+				input: RyuNativeLiveActivityInput
+			): Promise<RyuNativeLiveActivityResult>;
+		};
+	};
 	/** Open a tab at a path (built-in or a route this plugin contributed). */
 	openTab(path: string): void;
 	/** Read/write the plugin's own Spaces docs (scoped by grant). */
@@ -152,6 +188,52 @@ export interface RyuHostServices {
 	};
 }
 
+/** The token-free, read-only native feature inventory returned by a host. */
+export interface RyuHostCapabilities {
+	androidOngoingNotifications: boolean;
+	browserNotifications: boolean;
+	dynamicIsland: boolean;
+	haptics: boolean;
+	hardwareBleRelay: boolean;
+	liveActivities: boolean;
+	localNotifications: boolean;
+	platform: "android" | "browser" | "ios" | "unknown";
+	pushRegistration: boolean;
+	quickActions: boolean;
+	sounds: boolean;
+}
+
+export type RyuNativeHapticStyle = "light" | "success" | "warning" | "error";
+
+export interface RyuNativeHapticsInput {
+	style: RyuNativeHapticStyle;
+}
+
+export interface RyuNativeNotificationInput {
+	body: string;
+	title: string;
+}
+
+export interface RyuNativeLiveActivityInput {
+	conversationId: string;
+	detail: string;
+	status: "running" | "waiting" | "review" | "done" | "error";
+	title: string;
+}
+
+export interface RyuNativeHapticsResult {
+	signaled: true;
+}
+
+export interface RyuNativeNotificationResult {
+	id: string;
+	scheduled: true;
+}
+
+export interface RyuNativeLiveActivityResult {
+	updated: true;
+}
+
 // ── The host API a plugin's activate() receives ───────────────────────────────
 
 /** Everything a plugin can contribute. Each `register*` returns a

package/src/runnable/action.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, it } from "bun:test";
+import { PluginManifestSchema } from "../manifest.ts";
+import { defineAction } from "./action.ts";
+import type { GatewayClient, RunnableContext } from "./runnable-types.ts";
+
+const gateway: GatewayClient = {
+	chat: async () => ({ content: "ok", finishReason: "stop" }),
+	async *stream() {
+		yield { content: "ok", finishReason: null };
+	},
+};
+
+const context: RunnableContext = { gateway };
+
+const ticketAction = defineAction({
+	id: "action-create-ticket",
+	name: "Create Ticket",
+	description: "Create a support ticket for a customer.",
+	schema: {
+		type: "object",
+		properties: {
+			customer: { type: "string" },
+			summary: { type: "string" },
+		},
+		required: ["customer", "summary"],
+	},
+	outputSchema: {
+		type: "object",
+		properties: {
+			id: { type: "string" },
+		},
+		required: ["id"],
+	},
+	effect: "mutate",
+	needsApproval: true,
+	run: async ({ customer, summary }) => ({
+		id: `${customer}:${summary}`,
+	}),
+});
+
+describe("defineAction", () => {
+	it("returns a governed action with the same Runnable execution contract", async () => {
+		expect(ticketAction.kind).toBe("tool");
+		expect(ticketAction.action).toBe(true);
+		expect(ticketAction.description).toBe(
+			"Create a support ticket for a customer."
+		);
+		expect(ticketAction.schema.required).toEqual(["customer", "summary"]);
+		expect(ticketAction.outputSchema?.required).toEqual(["id"]);
+		expect(ticketAction.annotations).toEqual({
+			destructiveHint: true,
+			readOnlyHint: false,
+		});
+		expect(ticketAction.needsApproval).toBe(true);
+		expect(
+			await ticketAction.run({ customer: "acme", summary: "Login" }, context)
+		).toEqual({ id: "acme:Login" });
+	});
+
+	it("rejects an action whose declared effect conflicts with its annotations", () => {
+		expect(() =>
+			defineAction({
+				id: "action-conflict",
+				name: "Conflicting Action",
+				description: "An invalid action.",
+				schema: { type: "object", properties: {} },
+				effect: "read",
+				annotations: { destructiveHint: true },
+				run: async () => null,
+			})
+		).toThrow(/destructiveHint/);
+	});
+
+	it("lowers to a Core-compatible governed inline tool manifest", () => {
+		const manifest = ticketAction.toManifest({
+			id: "com.example.support",
+			version: "1.0.0",
+			grants: ["storage:kv"],
+		});
+
+		expect(() => PluginManifestSchema.parse(manifest)).not.toThrow();
+		expect(manifest.permission_grants).toEqual(["storage:kv", "tool:execute"]);
+		expect(manifest.runnables).toHaveLength(1);
+		expect(manifest.runnables[0]).toMatchObject({
+			id: "action-create-ticket",
+			name: "Create Ticket",
+			kind: "tool",
+		});
+		expect(manifest.runnables[0]?.config).toMatchObject({
+			slug: "action-create-ticket",
+			backend: "inline_deno",
+			action: true,
+			description: "Create a support ticket for a customer.",
+			input_schema: ticketAction.schema,
+			output_schema: ticketAction.outputSchema,
+			annotations: ticketAction.annotations,
+			needs_approval: true,
+		});
+	});
+
+	it("adapts the same implementation to the SDK MCP server", async () => {
+		const mcpTool = ticketAction.toMcpTool(context);
+
+		expect(mcpTool.name).toBe("action-create-ticket");
+		expect(mcpTool.description).toBe("Create a support ticket for a customer.");
+		expect(mcpTool.inputSchema).toEqual(ticketAction.schema);
+		expect(await mcpTool.run({ customer: "acme", summary: "MCP" })).toEqual({
+			id: "acme:MCP",
+		});
+	});
+
+	it("allows explicit read-only actions without approval", () => {
+		const action = defineAction({
+			id: "action-find-ticket",
+			name: "Find Ticket",
+			description: "Find a ticket by id.",
+			schema: { type: "object", properties: { id: { type: "string" } } },
+			effect: "read",
+			run: async ({ id }) => ({ id }),
+		});
+
+		expect(action.annotations).toEqual({
+			readOnlyHint: true,
+			destructiveHint: false,
+		});
+		expect(action.needsApproval).toBe(false);
+	});
+});

package/src/runnable/action.ts

@@ -0,0 +1,202 @@
+/**
+ * Canonical Ryu Action authoring API.
+ *
+ * An Action is the semantic contract for a business operation: one description,
+ * input schema, output schema, implementation, and effect declaration. It lowers
+ * to Ryu's existing governed `inline_deno` Tool backend, so this adds a coherent
+ * authoring seam without introducing a second Core execution runtime.
+ */
+
+import {
+	type PluginManifest,
+	PluginManifestSchema,
+	type RunnableMeta,
+	type Surface,
+} from "../manifest.ts";
+import type { SdkRunnable } from "../mcp/server.ts";
+import type { RunnableContext } from "./runnable-types.ts";
+import {
+	defineTool,
+	type InlineToolManifestOptions,
+	inlineToolRunnable,
+	type ToolRunnable,
+	type ToolSchema,
+} from "./tool.ts";
+
+/** The two effects Core can enforce from tool annotations. */
+export type ActionEffect = "mutate" | "read";
+
+/** MCP-compatible effect hints plus any future provider-neutral boolean hints. */
+export interface ActionAnnotations {
+	destructiveHint?: boolean;
+	idempotentHint?: boolean;
+	openWorldHint?: boolean;
+	readOnlyHint?: boolean;
+	[key: string]: boolean | undefined;
+}
+
+/** Options for defining a canonical Action. */
+export interface ActionOptions<
+	TInput extends Record<string, unknown>,
+	TOutput,
+> {
+	/** Additional MCP-compatible effect hints. */
+	annotations?: ActionAnnotations;
+	/** Description the agent reads when deciding whether to call the action. */
+	description: string;
+	/** Explicit effect used by read-only and approval enforcement. */
+	effect: ActionEffect;
+	/** Stable action id, also used as the generated Core tool slug. */
+	id: string;
+	/** Human-readable action name. */
+	name: string;
+	/** Require human approval even when global smart mode would not classify it. */
+	needsApproval?: boolean;
+	/** JSON Schema for the structured action result. */
+	outputSchema?: Record<string, unknown>;
+	/** The one implementation used by local callers and the packaged tool body. */
+	run(input: TInput, ctx: RunnableContext): Promise<TOutput>;
+	/** JSON Schema for all action inputs. */
+	schema: ToolSchema;
+}
+
+/** Options for lowering one Action into a standalone Ryu plugin manifest. */
+export interface ActionManifestOptions {
+	/** Plugin activation events; defaults to eager activation. */
+	activationEvents?: readonly string[];
+	/** Extra Gateway grants required by the action body. */
+	grants?: readonly string[];
+	/** Reverse-domain plugin id (for example `com.acme.support`). */
+	id: string;
+	/** Display name; defaults to the Action name. */
+	name?: string;
+	/** Host surfaces this plugin targets. */
+	targets?: readonly Surface[];
+	/** Plugin semver. */
+	version: string;
+}
+
+/** A ToolRunnable with Action semantics and manifest/MCP adapters. */
+export interface ActionRunnable<
+	TInput extends Record<string, unknown> = Record<string, unknown>,
+	TOutput = unknown,
+> extends ToolRunnable<TInput, TOutput> {
+	/** Discriminates this semantic contract from an ordinary ToolRunnable. */
+	readonly action: true;
+	/** Effect hints lowered into Core's existing tool metadata. */
+	readonly annotations: ActionAnnotations;
+	/** Required action description. */
+	readonly description: string;
+	/** Declared effect. */
+	readonly effect: ActionEffect;
+	/** Whether Core must queue approval before execution. */
+	readonly needsApproval: boolean;
+	/** Structured result schema, when the action returns one. */
+	readonly outputSchema?: Record<string, unknown>;
+	/** Lower this Action to a validated, installable plugin manifest. */
+	toManifest(options: ActionManifestOptions): PluginManifest;
+	/** Adapt this Action to the SDK MCP server using the same implementation. */
+	toMcpTool(context: RunnableContext): SdkRunnable;
+}
+
+function deriveAnnotations(
+	effect: ActionEffect,
+	annotations: ActionAnnotations | undefined
+): ActionAnnotations {
+	const resolved = {
+		...annotations,
+		readOnlyHint: annotations?.readOnlyHint ?? effect === "read",
+		destructiveHint: annotations?.destructiveHint ?? effect === "mutate",
+	};
+
+	if (effect === "read" && resolved.destructiveHint) {
+		throw new Error(
+			"[ryu-sdk] read actions cannot set annotations.destructiveHint=true"
+		);
+	}
+	if (effect === "mutate" && resolved.readOnlyHint) {
+		throw new Error(
+			"[ryu-sdk] mutate actions cannot set annotations.readOnlyHint=true"
+		);
+	}
+
+	return resolved;
+}
+
+function actionManifestEntry(action: ActionRunnable): RunnableMeta {
+	const options: InlineToolManifestOptions = {
+		action: true,
+		annotations: action.annotations,
+		description: action.description,
+		needsApproval: action.needsApproval,
+		...(action.outputSchema ? { outputSchema: action.outputSchema } : {}),
+	};
+	return inlineToolRunnable(action, options);
+}
+
+function actionToManifest(
+	action: ActionRunnable,
+	options: ActionManifestOptions
+): PluginManifest {
+	const grants = [...new Set([...(options.grants ?? []), "tool:execute"])];
+	const raw = {
+		id: options.id,
+		name: options.name ?? action.name,
+		version: options.version,
+		runnables: [actionManifestEntry(action)],
+		permission_grants: grants,
+		activation_events: [...(options.activationEvents ?? ["*"])],
+		targets: [...(options.targets ?? [])],
+	};
+	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(
+			`[ryu-sdk] action manifest validation failed at '${field}': ${message}`
+		);
+	}
+	return result.data;
+}
+
+/**
+ * Define one business operation that can be run locally, packaged as a Core
+ * tool, or registered on an SDK MCP server without rewriting its implementation.
+ */
+export function defineAction<
+	TInput extends Record<string, unknown> = Record<string, unknown>,
+	TOutput = unknown,
+>(options: ActionOptions<TInput, TOutput>): ActionRunnable<TInput, TOutput> {
+	const annotations = deriveAnnotations(options.effect, options.annotations);
+	const tool = defineTool({
+		description: options.description,
+		id: options.id,
+		name: options.name,
+		run: options.run,
+		schema: options.schema,
+	});
+
+	const action: ActionRunnable<TInput, TOutput> = {
+		...tool,
+		action: true,
+		annotations,
+		description: options.description,
+		effect: options.effect,
+		needsApproval: options.needsApproval ?? false,
+		...(options.outputSchema ? { outputSchema: options.outputSchema } : {}),
+		toManifest(manifestOptions) {
+			return actionToManifest(action, manifestOptions);
+		},
+		toMcpTool(context) {
+			return {
+				name: action.id,
+				description: action.description,
+				inputSchema: action.schema,
+				run: (input) => action.run(input as TInput, context),
+			};
+		},
+	};
+
+	return action;
+}

package/src/runnable/app.test.ts

@@ -9,6 +9,7 @@ function checklistApp(grants?: string[]) {
 		slug: "checklist",
 		title: "Checklist",
 		version: "1.0.0",
+		uiEntry: "src/checklist.tsx",
 		...(grants ? { grants } : {}),
 		tools: [{ name: "render", description: "Render a checklist" }],
 	});
@@ -48,6 +49,7 @@ describe("defineApp widget grant", () => {
 			slug: "tools",
 			title: "Tools",
 			version: "1.0.0",
+			uiEntry: "src/tools.tsx",
 			tools: [{ name: "toggle", description: "Toggle", accessible: true }],
 		});
 		expect(manifest.contributes?.widgets ?? []).toHaveLength(0);

package/src/runnable/app.ts

@@ -14,11 +14,13 @@
  *   - 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`.
+ * A tool may also attach a `ToolRunnable`. When present, its self-contained run
+ * body is emitted as Core's grant-gated `inline_deno` backend, so the widget and
+ * the behavior ship in one bundle. Without a runnable, the tool remains the
+ * declarative pass-through form: 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 {
@@ -26,11 +28,13 @@ import type {
 	PluginManifest,
 	Requires,
 	RunnableMeta,
+	SlashCommandContribution,
 	Surface,
 	ToolAppConfig,
 	WidgetContribution,
 } from "../manifest.ts";
 import { PluginManifestSchema } from "../manifest.ts";
+import { inlineToolRunnable, type ToolRunnable } from "./tool.ts";
 
 /** The default widget MIME dialect (mirrors Core `default_widget_mime`). */
 const DEFAULT_APP_WIDGET_MIME = "text/html+skybridge";
@@ -59,6 +63,21 @@ function withWidgetRenderGrant(
 	return out;
 }
 
+/** Add the grant required for any executable inline tool body. */
+function withToolExecuteGrant(
+	grants: readonly string[],
+	tools: readonly AppToolSpec[]
+): string[] {
+	const out = [...grants];
+	if (
+		tools.some((tool) => tool.runnable !== undefined) &&
+		!out.includes("tool:execute")
+	) {
+		out.push("tool:execute");
+	}
+	return out;
+}
+
 /** One tool a Ryu App declares. */
 export interface AppToolSpec {
 	/**
@@ -74,8 +93,15 @@ export interface AppToolSpec {
 	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>`. */
+	/** Tool name (unqualified). The wire id is `<server>.<name>`. */
 	name: string;
+	/**
+	 * Optional executable body for this tool. Core receives it as an
+	 * `inline_deno` runnable and runs it in the deny-by-default tool sandbox.
+	 * The body must be self-contained; use the injected `host` capability surface
+	 * for governed model calls and other platform primitives.
+	 */
+	runnable?: Pick<ToolRunnable, "code" | "id" | "name" | "schema">;
 }
 
 /**
@@ -116,6 +142,8 @@ export interface DefineAppOptions {
 	requires?: DefineAppRequires;
 	/** MCP server namespace for the tool ids. Defaults to `slug`. */
 	server?: string;
+	/** Slash commands this app exposes in the chat composer. */
+	slashCommands?: SlashCommandContribution[];
 	/**
 	 * 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.
@@ -141,7 +169,7 @@ export interface DefineAppOptions {
 
 /** Build a fully-qualified tool id from a server namespace and tool name. */
 export function appToolId(server: string, name: string): string {
-	return `${server}__${name}`;
+	return `${server}.${name}`;
 }
 
 /**
@@ -182,8 +210,12 @@ export function defineApp(options: DefineAppOptions): PluginManifest {
 	for (const spec of options.tools) {
 		const isRender = spec.accessible !== true;
 		const id = appToolId(server, spec.name);
+		const executable = spec.runnable
+			? inlineToolRunnable(spec.runnable)
+			: undefined;
 
-		const config: ToolAppConfig = {
+		const config: ToolAppConfig & Record<string, unknown> = {
+			...(executable?.config ?? {}),
 			slug: id,
 			description: spec.description,
 			widget: isRender,
@@ -213,16 +245,18 @@ export function defineApp(options: DefineAppOptions): PluginManifest {
 
 	const contributes: Contributes = {
 		turn_hooks: [],
+		chat_features: [],
 		// This builder synthesises an app from its runnables; an app that emits
 		// events declares them in a hand-authored `manifest.json`, same as
 		// `lsp_servers` below.
 		hook_events: [],
 		composer_controls: [],
 		settings_tabs: [],
-		slash_commands: [],
+		slash_commands: options.slashCommands ?? [],
 		sidebar_sections: [],
 		sidebar_buttons: [],
 		dock_panels: [],
+		live_activities: [],
 		// Empty for the same reason as every sibling family above: this builder
 		// synthesises `widgets` from the app's own runnables and nothing else, and
 		// takes no `contributes` passthrough. An app that wants to declare language
@@ -235,6 +269,8 @@ export function defineApp(options: DefineAppOptions): PluginManifest {
 		data_categories: [],
 		pi_extensions: [],
 		output_styles: [],
+		message_actions: [],
+		selection_actions: [],
 		widgets,
 	};
 
@@ -249,15 +285,15 @@ export function defineApp(options: DefineAppOptions): PluginManifest {
 		// Core gates widget promotion on declared-AND-enabled-AND-granted, and a
 		// missing grant fails as `DeniedNoGrant` — which is an `info!` log and
 		// nothing else. The widget silently renders as plain text, with no error
-		// in the UI and nothing pointing at the manifest. Every app scaffolded
-		// through `defineApp` hit that, because the only fix was a grant string
-		// the templates never mention and the builder never added; the one
-		// working example on disk hand-writes it.
+		// in the UI and nothing pointing at the manifest.
 		//
 		// Added only when there is a widget to render, and unioned rather than
 		// overwritten so an author's own `grants` list survives and re-declaring
 		// it is not an error.
-		permission_grants: withWidgetRenderGrant(options.grants ?? [], widgets),
+		permission_grants: withToolExecuteGrant(
+			withWidgetRenderGrant(options.grants ?? [], widgets),
+			options.tools
+		),
 		activation_events: options.activationEvents ?? ["*"],
 		contributes,
 		// `targets: []` means EVERY surface, so an app that declares none is