@ryuhq/sdk 0.2.0 → 0.2.3

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 {
 	/**
@@ -76,6 +95,13 @@ export interface AppToolSpec {
 	invoking?: string;
 	/** 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.
@@ -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,
@@ -220,7 +252,7 @@ export function defineApp(options: DefineAppOptions): PluginManifest {
 		hook_events: [],
 		composer_controls: [],
 		settings_tabs: [],
-		slash_commands: [],
+		slash_commands: options.slashCommands ?? [],
 		sidebar_sections: [],
 		sidebar_buttons: [],
 		dock_panels: [],
@@ -238,6 +270,7 @@ export function defineApp(options: DefineAppOptions): PluginManifest {
 		pi_extensions: [],
 		output_styles: [],
 		message_actions: [],
+		selection_actions: [],
 		widgets,
 	};
 
@@ -252,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

package/src/runnable/index.ts

@@ -1,6 +1,7 @@
 /**
- * Runnable — the single contract unifying Agent, Workflow, Tool, and Skill
- * in the Ryu SDK.
+ * Runnable — the execution contract unifying Agent, Workflow, Tool, and Skill
+ * in the Ryu SDK. `defineAction` is the governed business-operation facade over
+ * the Tool kind.
  *
  * Design rules (from the M8 spike doc packages/sdk/README.md):
  *   - An agent may invoke a workflow as a named tool.
@@ -12,6 +13,14 @@
  * import from `@ryuhq/sdk/runnable` as a single entry point.
  */
 
+export type {
+	ActionAnnotations,
+	ActionEffect,
+	ActionManifestOptions,
+	ActionOptions,
+	ActionRunnable,
+} from "./action.ts";
+export { defineAction } from "./action.ts";
 export type {
 	AgentCard,
 	AgentManifestOptions,
@@ -42,6 +51,7 @@ export type {
 	RealtimeClient,
 	RealtimeSubscription,
 	RyuPrimitives,
+	StorageClient,
 	SttClient,
 	TtsClient,
 } from "./primitives.ts";
@@ -57,7 +67,12 @@ export type {
 } from "./runnable-types.ts";
 export type { SkillOptions } from "./skill.ts";
 export { defineSkill } from "./skill.ts";
-export type { JsonSchemaProperty, ToolOptions, ToolSchema } from "./tool.ts";
+export type {
+	InlineToolManifestOptions,
+	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.test.ts

@@ -158,6 +158,35 @@ describe("createPrimitives — transport routing mirrors rpc.ts", () => {
 		expect(ragCall.body).toMatchObject({ op: "retrieve" });
 	});
 
+	it("storage primitives use the grant-gated app-owned KV bridge", async () => {
+		const { transport, calls } = recordingTransport();
+		const p = createPrimitives(transport);
+		await p.storage.get({ namespace: "tickets", key: "t-1" });
+		await p.storage.set({ namespace: "tickets", key: "t-1", value: "open" });
+		await p.storage.delete({ namespace: "tickets", key: "t-1" });
+		await p.storage.keys({ namespace: "tickets" });
+		await p.storage.compareAndSet({
+			namespace: "tickets",
+			key: "t-1",
+			expected: null,
+			value: "open",
+		});
+
+		expect(calls.map((c) => c.target)).toEqual([
+			"storage.get",
+			"storage.set",
+			"storage.delete",
+			"storage.keys",
+			"storage.compareAndSet",
+		]);
+		expect(calls.every((c) => c.op === "bridge")).toBe(true);
+		expect(calls[1]?.body).toEqual({
+			namespace: "tickets",
+			key: "t-1",
+			value: "open",
+		});
+	});
+
 	it("every declared primitive has a binding entry (no silent drift)", () => {
 		const expected = [
 			"engines.complete",
@@ -174,6 +203,11 @@ describe("createPrimitives — transport routing mirrors rpc.ts", () => {
 			"realtime.subscribe",
 			"durable.checkpoint",
 			"durable.resume",
+			"storage.get",
+			"storage.set",
+			"storage.delete",
+			"storage.keys",
+			"storage.compareAndSet",
 		];
 		for (const key of expected) {
 			expect(PRIMITIVE_BINDINGS[key]).toBeDefined();

package/src/runnable/primitives.ts

@@ -326,6 +326,31 @@ export const PRIMITIVE_BINDINGS: Record<string, PrimitiveBinding> = {
 		method: "background.stop",
 		grant: "background:control",
 	},
+	"storage.get": {
+		transport: "bridge",
+		method: "storage.get",
+		grant: "storage:kv",
+	},
+	"storage.set": {
+		transport: "bridge",
+		method: "storage.set",
+		grant: "storage:kv",
+	},
+	"storage.delete": {
+		transport: "bridge",
+		method: "storage.delete",
+		grant: "storage:kv",
+	},
+	"storage.keys": {
+		transport: "bridge",
+		method: "storage.keys",
+		grant: "storage:kv",
+	},
+	"storage.compareAndSet": {
+		transport: "bridge",
+		method: "storage.compareAndSet",
+		grant: "storage:kv",
+	},
 	// Host-direct media data-path (the host holds the node token; returns data: URLs).
 	"image.generate": {
 		transport: "direct",
@@ -509,6 +534,25 @@ export interface BackgroundClient {
 	}>;
 }
 
+/** Durable app-owned key/value state (`storage:kv` via the host bridge). */
+export interface StorageClient {
+	/** Atomically replace a value when it still equals `expected`. */
+	compareAndSet(input: {
+		expected: string | null;
+		key: string;
+		namespace?: string;
+		value: string | null;
+	}): Promise<boolean>;
+	/** Delete one value. */
+	delete(input: { key: string; namespace?: string }): Promise<void>;
+	/** Read one value; missing keys return `null`. */
+	get(input: { key: string; namespace?: string }): Promise<string | null>;
+	/** List keys in an app-owned namespace. */
+	keys(input?: { namespace?: string }): Promise<string[]>;
+	/** Write one string value. JSON can be encoded by the app when needed. */
+	set(input: { key: string; namespace?: string; value: string }): Promise<void>;
+}
+
 /** TTS primitive — speech synthesis (`crates/ryu-tts`). */
 export interface TtsClient {
 	/**
@@ -561,6 +605,7 @@ export interface RyuPrimitives {
 	memory: MemoryClient;
 	rag: RagClient;
 	realtime: RealtimeClient;
+	storage: StorageClient;
 	stt: SttClient;
 	tts: TtsClient;
 }
@@ -599,6 +644,20 @@ export function createPrimitives(transport: PrimitiveTransport): RyuPrimitives {
 					process_id: string;
 				}>,
 		},
+		storage: {
+			get: (input) =>
+				transport.bridge("storage.get", input) as Promise<string | null>,
+			set: (input) =>
+				transport.bridge("storage.set", input).then(() => undefined),
+			delete: (input) =>
+				transport.bridge("storage.delete", input).then(() => undefined),
+			keys: (input) =>
+				transport
+					.bridge("storage.keys", input ?? {})
+					.then((value) => (Array.isArray(value) ? (value as string[]) : [])),
+			compareAndSet: (input) =>
+				transport.bridge("storage.compareAndSet", input) as Promise<boolean>,
+		},
 		rag: {
 			retrieve: (input) =>
 				brokerCall(transport, "rag", "retrieve", input) as Promise<RagChunk[]>,

package/src/runnable/runnable-types.ts

@@ -14,6 +14,7 @@ import type {
 	MemoryClient,
 	RagClient,
 	RealtimeClient,
+	StorageClient,
 	SttClient,
 	TtsClient,
 } from "./primitives.ts";
@@ -81,6 +82,8 @@ export interface RunnableContext {
 	sessionId?: string;
 	/** Signal to abort a long-running run. */
 	signal?: AbortSignal;
+	/** Durable app-owned KV state, gated by the manifest's `storage:kv` grant. */
+	storage?: StorageClient;
 	/** STT primitive: transcribe (`crates/ryu-stt`). */
 	stt?: SttClient;
 	/** TTS primitive: speak (`crates/ryu-tts`). */

package/src/runnable/tool.ts

@@ -55,12 +55,16 @@ export interface ToolSchema {
 	required?: string[];
 	/** Type is always "object" for a tool's top-level input schema. */
 	type: "object";
+	/** Preserve additional JSON Schema keywords for Core/MCP consumers. */
+	[key: string]: unknown;
 }
 
 // ── Options ───────────────────────────────────────────────────────────────────
 
 /** Options accepted by `defineTool`. */
 export interface ToolOptions<TInput extends Record<string, unknown>, TOutput> {
+	/** Optional description surfaced to models and tool discovery. */
+	description?: string;
 	/** Stable unique identifier (e.g. "tool-web-search"). */
 	id: string;
 	/** Human-readable display name. */
@@ -171,6 +175,8 @@ export interface ToolRunnable<
 	 * the sandbox form is the second parameter aliased to `host`.
 	 */
 	readonly code: string;
+	/** Optional description surfaced to models and tool discovery. */
+	readonly description?: string;
 	readonly kind: "tool";
 	/** JSON Schema for this tool's input — compatible with Core's ToolInfo.schema. */
 	readonly schema: ToolSchema;
@@ -211,7 +217,7 @@ export function defineTool<
 	TInput extends Record<string, unknown> = Record<string, unknown>,
 	TOutput = unknown,
 >(options: ToolOptions<TInput, TOutput>): ToolRunnable<TInput, TOutput> {
-	const { id, name, schema, run } = options;
+	const { description, id, name, schema, run } = options;
 
 	// Serialize the run body for Core's `inline_deno` backend — the same approach
 	// `defineTurnHook` uses: the sandbox wraps this in an async IIFE where `input`
@@ -223,6 +229,7 @@ export function defineTool<
 		name,
 		kind: "tool",
 		schema,
+		...(description === undefined ? {} : { description }),
 		code,
 		run(input: TInput, ctx: RunnableContext): Promise<TOutput> {
 			validateInput(input, schema, id);
@@ -231,6 +238,20 @@ export function defineTool<
 	} satisfies ToolRunnable<TInput, TOutput>;
 }
 
+/** Optional metadata lowered alongside a tool's executable backend. */
+export interface InlineToolManifestOptions {
+	/** Marks the entry as a semantic Ryu Action. */
+	action?: boolean;
+	/** MCP-style effect annotations, for example `readOnlyHint`. */
+	annotations?: Record<string, boolean | undefined>;
+	/** Description shown in Core's unified tool catalog. */
+	description?: string;
+	/** Force the human approval gate before the tool runs. */
+	needsApproval?: boolean;
+	/** JSON Schema for the structured result. */
+	outputSchema?: Record<string, unknown>;
+}
+
 /**
  * Convert a {@link ToolRunnable} into a `manifest.json` `kind:"tool"` runnable that
  * ships its `run` body as Core's `inline_deno` backend. The emitted config
@@ -242,8 +263,8 @@ export function defineTool<
  * The plugin must declare the `tool:execute` grant (see `definePlugin`).
  */
 export function inlineToolRunnable(
-	tool: ToolRunnable,
-	options?: { description?: string }
+	tool: Pick<ToolRunnable, "code" | "description" | "id" | "name" | "schema">,
+	options?: InlineToolManifestOptions
 ): RunnableMeta {
 	return {
 		id: tool.id,
@@ -254,7 +275,17 @@ export function inlineToolRunnable(
 			backend: "inline_deno",
 			code: tool.code,
 			input_schema: tool.schema,
-			...(options?.description ? { description: options.description } : {}),
+			...(options?.description === undefined
+				? tool.description === undefined
+					? {}
+					: { description: tool.description }
+				: { description: options.description }),
+			...(options?.outputSchema ? { output_schema: options.outputSchema } : {}),
+			...(options?.annotations ? { annotations: options.annotations } : {}),
+			...(options?.action === undefined ? {} : { action: options.action }),
+			...(options?.needsApproval === undefined
+				? {}
+				: { needs_approval: options.needsApproval }),
 		},
 	};
 }

package/src/runnable/turn-hook.ts

@@ -18,6 +18,7 @@ import type {
 	HookEventContribution,
 	PluginManifest,
 	RunnableMeta,
+	SlashCommandContribution,
 	Surface,
 	TurnHookContribution,
 } from "../manifest.ts";
@@ -144,8 +145,8 @@ export interface DefinePluginOptions {
 	requires?: DefineAppRequires;
 	/** Declarative settings tabs (model pickers, fields), passed verbatim. */
 	settingsTabs?: Record<string, unknown>[];
-	/** Declarative slash commands, passed verbatim. */
-	slashCommands?: Record<string, unknown>[];
+	/** Declarative slash commands, including sequential argument choices. */
+	slashCommands?: SlashCommandContribution[];
 	/**
 	 * Host surfaces this plugin runs on. **Omitted/empty = every surface** (the
 	 * backward-compatible default); it never means "hidden".
@@ -190,6 +191,7 @@ export function definePlugin(options: DefinePluginOptions): PluginManifest {
 		pi_extensions: [],
 		output_styles: [],
 		message_actions: [],
+		selection_actions: [],
 	};
 	// Ship each inline tool as a `kind:"tool"` runnable (Core's `inline_deno`
 	// backend). Shipping tools requires the `tool:execute` grant; add it once.

package/src/slash-command.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, test } from "bun:test";
+import {
+	app,
+	defineApp,
+	definePlugin,
+	SlashCommandContributionSchema,
+} from "./index.ts";
+
+const slashCommand = {
+	args: [
+		{
+			custom: { label: "Use another environment" },
+			name: "environment",
+			options: [
+				{ label: "Staging", value: "staging" },
+				{ label: "Production", value: "production" },
+			],
+		},
+	],
+	command: "/deploy",
+	description: "Deploy the current project",
+};
+
+describe("slash command contributions", () => {
+	test("validate sequential options and custom choices", () => {
+		expect(SlashCommandContributionSchema.parse(slashCommand)).toEqual(
+			slashCommand
+		);
+	});
+
+	test("defineApp publishes slash commands", () => {
+		const manifest = defineApp({
+			id: "com.example.deploy",
+			title: "Deploy",
+			version: "1.0.0",
+			slug: "deploy",
+			uiEntry: "src/deploy.tsx",
+			tools: [{ name: "render", description: "Render deploy status" }],
+			slashCommands: [slashCommand],
+		});
+
+		expect(manifest.contributes?.slash_commands).toEqual([slashCommand]);
+	});
+
+	test("definePlugin publishes slash commands", () => {
+		const manifest = definePlugin({
+			id: "com.example.deploy-plugin",
+			name: "Deploy",
+			version: "1.0.0",
+			slashCommands: [slashCommand],
+		});
+
+		expect(manifest.contributes?.slash_commands).toEqual([slashCommand]);
+	});
+
+	test("AppBuilder publishes slash commands", () => {
+		const manifest = app()
+			.id("com.example.deploy-builder")
+			.title("Deploy")
+			.version("1.0.0")
+			.slug("deploy-builder")
+			.uiEntry("src/deploy.tsx")
+			.tool({ name: "render", description: "Render deploy status" })
+			.slashCommand(slashCommand)
+			.build();
+
+		expect(manifest.contributes?.slash_commands).toEqual([slashCommand]);
+	});
+});