@ryuhq/sdk 0.2.0 → 0.2.2

package/src/manifest.test.ts

@@ -26,6 +26,7 @@ import { join } from "node:path";
 import { agent, app, PluginBuilder, skill, tool, workflow } from "./builder.ts";
 import { PluginManifestSchema } from "./manifest.ts";
 import { defineApp } from "./runnable/app.ts";
+import { defineTool } from "./runnable/tool.ts";
 
 // ── builder unit tests ────────────────────────────────────────────────────────
 
@@ -363,6 +364,49 @@ describe("defineApp", () => {
 		);
 	});
 
+	it("embeds an executable ToolRunnable in the widget tool", () => {
+		const renderTool = defineTool({
+			id: "support.render",
+			name: "Support answer",
+			schema: {
+				type: "object",
+				properties: { message: { type: "string" } },
+				required: ["message"],
+			},
+			run: async (input) => ({
+				content: [{ type: "text", text: input.message }],
+				structuredContent: { answer: input.message },
+			}),
+		});
+		const manifest = defineApp({
+			id: "com.example.support",
+			title: "Support",
+			version: "1.0.0",
+			slug: "support",
+			uiEntry: "src/widget.html",
+			tools: [
+				{
+					name: "render",
+					description: "Answer a support question",
+					inputSchema: renderTool.schema as unknown as Record<string, unknown>,
+					runnable: renderTool,
+				},
+			],
+		});
+		const render = manifest.runnables[0];
+
+		expect(render?.config).toMatchObject({
+			backend: "inline_deno",
+			code: renderTool.code,
+			input_schema: renderTool.schema,
+			widget: true,
+		});
+		expect(manifest.permission_grants).toEqual([
+			"widget:render",
+			"tool:execute",
+		]);
+	});
+
 	it("round-trips through PluginManifestSchema without stripping widgets", () => {
 		// The load-bearing check: `contributes.widgets` is only preserved because it
 		// was added to `ContributesSchema`. A JSON round-trip proves the field
@@ -805,6 +849,31 @@ describe("contributes.message_actions", () => {
 	});
 });
 
+describe("contributes.selection_actions", () => {
+	it("preserves host-owned selection dispatch args through the pack-path parse", () => {
+		const action = {
+			args: { dispatch: "side-chat.selection", intent: "explain" },
+			id: "side-chats.explain-selection",
+			kind: "button",
+			label: "Explain",
+			order: 110,
+		};
+		const parsed = PluginManifestSchema.safeParse({
+			id: "com.example.side-chats",
+			name: "Side Chats",
+			version: "1.0.0",
+			runnables: [],
+			contributes: { selection_actions: [action] },
+		});
+
+		expect(parsed.success).toBe(true);
+		if (!parsed.success) {
+			return;
+		}
+		expect(parsed.data.contributes?.selection_actions).toEqual([action]);
+	});
+});
+
 describe("mcp_servers OAuth", () => {
 	const manifest = {
 		id: "com.example.mail",

package/src/manifest.ts

@@ -346,28 +346,47 @@ export type WidgetContribution = z.infer<typeof WidgetContributionSchema>;
 
 /** Metadata-only chat affordance. The host owns rendering and dispatch; the
  * manifest carries identifiers and copy only. */
-export const ChatWidgetTemplateSchema = z.object({
-	id: z.string().regex(/^[a-z0-9][a-z0-9._:-]*$/),
-	title: z.string().min(1),
-	description: z.string().optional(),
-	triggers: z.array(z.string()).default([]),
-	examples: z.array(z.string()).default([]),
-	backing: z
-		.object({
-			tool_id: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:/-]*$/).optional(),
-			view_id: z.string().regex(/^[a-z0-9][a-z0-9._:-]*$/).optional(),
+export const ChatWidgetTemplateSchema = z
+	.object({
+		id: z.string().regex(/^[a-z0-9][a-z0-9._:-]*$/),
+		title: z.string().min(1),
+		description: z.string().optional(),
+		triggers: z.array(z.string()).default([]),
+		examples: z.array(z.string()).default([]),
+		backing: z.object({
+			tool_id: z
+				.string()
+				.regex(/^[A-Za-z0-9][A-Za-z0-9._:/-]*$/)
+				.optional(),
+			view_id: z
+				.string()
+				.regex(/^[a-z0-9][a-z0-9._:-]*$/)
+				.optional(),
 		}),
-	display_mode: z.string().min(1),
-	safe_action_ids: z.array(z.string().regex(/^[a-z0-9][a-z0-9._-]*$/)).default([]),
-	availability: z.string().default("available"),
+		display_mode: z.string().min(1),
+		safe_action_ids: z
+			.array(z.string().regex(/^[a-z0-9][a-z0-9._-]*$/))
+			.default([]),
+		availability: z.string().default("available"),
 	})
 	.superRefine((value, ctx) => {
-		const count = Number(Boolean(value.backing.tool_id)) + Number(Boolean(value.backing.view_id));
+		const count =
+			Number(Boolean(value.backing.tool_id)) +
+			Number(Boolean(value.backing.view_id));
 		if (count !== 1 && value.availability === "available") {
-			ctx.addIssue({ code: "custom", path: ["backing"], message: "available templates need exactly one backing tool_id or view_id" });
+			ctx.addIssue({
+				code: "custom",
+				path: ["backing"],
+				message:
+					"available templates need exactly one backing tool_id or view_id",
+			});
 		}
 		if (count > 1) {
-			ctx.addIssue({ code: "custom", path: ["backing"], message: "backing must declare at most one of tool_id or view_id" });
+			ctx.addIssue({
+				code: "custom",
+				path: ["backing"],
+				message: "backing must declare at most one of tool_id or view_id",
+			});
 		}
 	});
 
@@ -406,10 +425,70 @@ export const ToolAppConfigSchema = z.object({
 
 export type ToolAppConfig = z.infer<typeof ToolAppConfigSchema>;
 
+/** One selectable value for a plugin/app slash-command argument. */
+export const SlashCommandOptionSchema = z
+	.object({
+		description: z.string().optional(),
+		label: z.string().min(1),
+		value: z.string().min(1),
+	})
+	.passthrough();
+
+export type SlashCommandOption = z.infer<typeof SlashCommandOptionSchema>;
+
+/** A registered free-form option shown alongside an argument's choices. */
+export const SlashCommandCustomOptionSchema = z.union([
+	z.literal(true),
+	z
+		.object({
+			description: z.string().optional(),
+			label: z.string().min(1).optional(),
+		})
+		.passthrough(),
+]);
+
+export type SlashCommandCustomOption = z.infer<
+	typeof SlashCommandCustomOptionSchema
+>;
+
+/** One sequential argument in a plugin/app slash command. */
+export const SlashCommandArgumentSchema = z
+	.object({
+		allow_custom: z.boolean().optional(),
+		custom: SlashCommandCustomOptionSchema.optional(),
+		description: z.string().optional(),
+		name: z.string().min(1),
+		options: z.array(SlashCommandOptionSchema).optional(),
+	})
+	.passthrough();
+
+export type SlashCommandArgument = z.infer<typeof SlashCommandArgumentSchema>;
+
+/**
+ * A command registered by a plugin or Ryu App. `args` is the preferred key;
+ * `parameters` is accepted as a readable alias for hand-authored manifests.
+ * Each argument's options are plugin-owned, so the shell never needs a closed
+ * enum for app-specific values.
+ */
+export const SlashCommandContributionSchema = z
+	.object({
+		args: z.array(SlashCommandArgumentSchema).optional(),
+		body: z.string().optional(),
+		command: z.string().min(1),
+		description: z.string().optional(),
+		id: z.string().optional(),
+		parameters: z.array(SlashCommandArgumentSchema).optional(),
+	})
+	.passthrough();
+
+export type SlashCommandContribution = z.infer<
+	typeof SlashCommandContributionSchema
+>;
+
 /**
  * The `contributes` block. Mirrors `Contributes` in
  * `apps/core/src/plugin_manifest/mod.rs`. The declarative UI surfaces
- * (`composer_controls` / `chat_features` / `settings_tabs` / `slash_commands`) are passed verbatim
+ * (`composer_controls` / `chat_features` / `settings_tabs`) are passed verbatim
  * to the desktop renderer, so they are typed loosely here (records).
  */
 export const ContributesSchema = z.object({
@@ -426,7 +505,7 @@ export const ContributesSchema = z.object({
 	 * feature declaration before signing. */
 	chat_features: z.array(z.record(z.string(), z.unknown())).default([]),
 	settings_tabs: z.array(z.record(z.string(), z.unknown())).default([]),
-	slash_commands: z.array(z.record(z.string(), z.unknown())).default([]),
+	slash_commands: z.array(SlashCommandContributionSchema).default([]),
 	/** App widgets (Ryu Apps). Each binds a render tool id to its
 	 *  `ui://widget/<slug>.html` template. Mirrors the Rust-side
 	 *  `Contributes.widgets` field, without which the CLI's zod parse would strip
@@ -496,6 +575,9 @@ export const ContributesSchema = z.object({
 	/** Per-message actions contributed by an enabled plugin. Kept as loose records
 	 *  so renderer-specific `kind`/`args` payloads survive `ryu pack` unchanged. */
 	message_actions: z.array(z.record(z.string(), z.unknown())).default([]),
+	/** Buttons contributed to the floating text-selection toolbar. Kept as loose
+	 *  records so host-owned dispatch args survive `ryu pack` unchanged. */
+	selection_actions: z.array(z.record(z.string(), z.unknown())).default([]),
 });
 
 export type Contributes = z.infer<typeof ContributesSchema>;
@@ -765,6 +847,10 @@ export const PluginManifestSchema = z
 				"version must be a valid semver string (e.g. 1.0.0)"
 			),
 
+		/** Core-owned release maturity metadata. The Rust contract validates the
+		 *  richer shape; the SDK authoring parser must preserve it for pack/publish. */
+		stability: z.unknown().optional(),
+
 		/**
 		 * Lower-case hex `sha256(utf8_bytes(ui_code))` binding the plugin's bundled
 		 * sandboxed-UI code to this manifest. `ryu pack` / `ryu publish` compute it and
@@ -785,9 +871,34 @@ export const PluginManifestSchema = z
 		 */
 		permission_grants: z.array(z.string()).default([]),
 
+		/** Deny-by-default sandbox permissions. Core remains authoritative; this
+		 *  schema mirrors the fields so `ryu pack` cannot strip them. */
+		permissions: z
+			.object({
+				fs: z
+					.object({
+						read: z.array(z.string()).default([]),
+						write: z.array(z.string()).default([]),
+					})
+					.optional(),
+				child_process: z.boolean().optional(),
+				run: z.array(z.string()).default([]),
+				network: z.union([z.boolean(), z.array(z.string())]).optional(),
+				tool: z.array(z.string()).default([]),
+			})
+			.optional(),
+
+		/** Core-owned permission presentation levels. Preserved verbatim here and
+		 *  validated by Core's authoritative manifest contract. */
+		permission_levels: z.unknown().optional(),
+
 		/** Remote or stdio MCP servers registered by this plugin. */
 		mcp_servers: z.record(z.string(), McpServerDeclSchema).optional(),
 
+		/** Core-owned sidecar declarations. Their full process/HTTP schema stays in
+		 *  the Rust contract; this authoring layer must never strip them. */
+		sidecars: z.unknown().optional(),
+
 		/**
 		 * Optional Companion surface (an in-desktop overlay or sidebar panel).
 		 * Absent when the plugin has no Companion surface.
@@ -828,6 +939,10 @@ export const PluginManifestSchema = z
 		 */
 		targets: z.array(SurfaceSchema).default([]),
 
+		/** Rich per-surface declarations (`support`, UI, contributed commands, …).
+		 *  Core owns and validates the nested vocabulary. */
+		surfaces: z.unknown().optional(),
+
 		/**
 		 * Host version floors — the semver requirement each surface must satisfy for
 		 * this plugin to install. Mirrors Core's `EnginesReq`
@@ -954,6 +1069,10 @@ export const PluginManifestSchema = z
 		 */
 		setup: z.union([SetupStepSchema, z.array(SetupStepSchema)]).optional(),
 	})
+	// Core's Rust-derived schema is the full wire authority. Keep this deliberately
+	// forward-compatible so a newly-added Core field survives SDK pack/publish even
+	// before the simpler authoring schema grows first-class validation for it.
+	.passthrough()
 	.superRefine((manifest, context) => {
 		const hasOAuthServer = Object.values(manifest.mcp_servers ?? {}).some(
 			(server) => server.auth?.type === "oauth"

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/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;
+}