@ryuhq/sdk 0.1.14 → 0.2.2

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,
@@ -26,6 +35,8 @@ export { defineAgent } from "./agent.ts";
 export type { AppToolSpec, DefineAppOptions } from "./app.ts";
 export { appToolId, defineApp } from "./app.ts";
 export type {
+	BackgroundClient,
+	BackgroundProcess,
 	DurableClient,
 	EnginesClient,
 	HttpPrimitiveTransportOptions,
@@ -40,6 +51,7 @@ export type {
 	RealtimeClient,
 	RealtimeSubscription,
 	RyuPrimitives,
+	StorageClient,
 	SttClient,
 	TtsClient,
 } from "./primitives.ts";
@@ -55,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

@@ -316,6 +316,41 @@ export const PRIMITIVE_BINDINGS: Record<string, PrimitiveBinding> = {
 		method: "model.complete",
 		grant: "hook:side-model",
 	},
+	"background.list": {
+		transport: "bridge",
+		method: "background.list",
+		grant: "background:control",
+	},
+	"background.stop": {
+		transport: "bridge",
+		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",
@@ -468,6 +503,56 @@ export interface EnginesClient {
 	}): Promise<number[][]>;
 }
 
+/** One process visible through the shared Core background registry. */
+export interface BackgroundProcess {
+	command: string;
+	cwd: string;
+	description?: string | null;
+	elapsed_ms: number;
+	exit_code?: number | null;
+	exit_signal?: string | null;
+	kind: string;
+	label?: string | null;
+	pid?: number | null;
+	process_id: string;
+	producer: string;
+	running: boolean;
+	shell_id?: string | null;
+	started_at: number;
+}
+
+/** Background-process registry and cooperative stop requests. */
+export interface BackgroundClient {
+	list(input?: {
+		producer?: string;
+		runningOnly?: boolean;
+	}): Promise<BackgroundProcess[]>;
+	stop(input: { processId: string }): Promise<{
+		ok: boolean;
+		requested: boolean;
+		process_id: string;
+	}>;
+}
+
+/** 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 {
 	/**
@@ -513,12 +598,14 @@ export interface ImageClient {
  * Core node) — the same "what runs vs what is allowed" split as `ctx.gateway`.
  */
 export interface RyuPrimitives {
+	background: BackgroundClient;
 	durable: DurableClient;
 	engines: EnginesClient;
 	image: ImageClient;
 	memory: MemoryClient;
 	rag: RagClient;
 	realtime: RealtimeClient;
+	storage: StorageClient;
 	stt: SttClient;
 	tts: TtsClient;
 }
@@ -542,6 +629,35 @@ function brokerCall(
  */
 export function createPrimitives(transport: PrimitiveTransport): RyuPrimitives {
 	return {
+		background: {
+			list: (input) =>
+				transport.bridge("background.list", {
+					producer: input?.producer,
+					running_only: input?.runningOnly,
+				}) as Promise<BackgroundProcess[]>,
+			stop: (input) =>
+				transport.bridge("background.stop", {
+					process_id: input.processId,
+				}) as Promise<{
+					ok: boolean;
+					requested: boolean;
+					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,19 +238,33 @@ 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
  * mirrors Core's `ToolConfig` (`apps/core/src/plugin_manifest/schema.rs`):
  * `{ slug, backend:"inline_deno", code, description?, input_schema }`. Core
- * registers it as `app__<slug>` — discoverable via `/api/tools/search` and
+ * registers it as `app.<slug>` — discoverable via `/api/tools/search` and
  * executed in the grant-gated sandbox.
  *
  * 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".
@@ -154,7 +155,7 @@ export interface DefinePluginOptions {
 	/**
 	 * Inline tools the plugin ships — each a {@link ToolRunnable} from `defineTool`
 	 * whose `run` body is bundled as Core's `inline_deno` backend (registered as
-	 * `app__<tool.id>`). Shipping any tool auto-adds the `tool:execute` grant.
+	 * `app.<tool.id>`). Shipping any tool auto-adds the `tool:execute` grant.
 	 */
 	tools?: ToolRunnable[];
 	/** Turn hooks the plugin contributes. */
@@ -173,6 +174,7 @@ export function definePlugin(options: DefinePluginOptions): PluginManifest {
 		turn_hooks: options.turnHooks ?? [],
 		hook_events: options.hookEvents ?? [],
 		composer_controls: options.composerControls ?? [],
+		chat_features: [],
 		settings_tabs: options.settingsTabs ?? [],
 		slash_commands: options.slashCommands ?? [],
 		lsp_servers: options.lspServers ?? {},
@@ -184,9 +186,12 @@ export function definePlugin(options: DefinePluginOptions): PluginManifest {
 		sidebar_sections: [],
 		sidebar_buttons: [],
 		dock_panels: [],
+		live_activities: [],
 		data_categories: [],
 		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 {
+	SlashCommandContributionSchema,
+	app,
+	defineApp,
+	definePlugin,
+} 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]);
+	});
+});