@ryuhq/sdk 0.0.5 → 0.1.2

package/src/runnable/app.ts

@@ -3,7 +3,7 @@
  *
  * 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
+ * complete `manifest.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()`):
  *
@@ -37,6 +37,28 @@ 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";
 
+/**
+ * The grant Core requires before it will promote a tool's result into an inline
+ * chat widget (mirrors Core's `WIDGET_RENDER_GRANT`).
+ */
+export const WIDGET_RENDER_GRANT = "widget:render";
+
+/**
+ * `grants` plus {@link WIDGET_RENDER_GRANT} when the app actually contributes a
+ * widget. Order-preserving and idempotent, so an author who already declared it
+ * gets no duplicate.
+ */
+function withWidgetRenderGrant(
+	grants: readonly string[],
+	widgets: readonly WidgetContribution[]
+): string[] {
+	const out = [...grants];
+	if (widgets.length > 0 && !out.includes(WIDGET_RENDER_GRANT)) {
+		out.push(WIDGET_RENDER_GRANT);
+	}
+	return out;
+}
+
 /** One tool a Ryu App declares. */
 export interface AppToolSpec {
 	/**
@@ -123,7 +145,7 @@ export function appToolId(server: string, name: string): string {
 }
 
 /**
- * Assemble a `plugin.json` manifest for a Ryu App. The result matches Core's
+ * Assemble a `manifest.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`.
  *
@@ -191,9 +213,25 @@ export function defineApp(options: DefineAppOptions): PluginManifest {
 
 	const contributes: Contributes = {
 		turn_hooks: [],
+		// 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: [],
+		sidebar_sections: [],
+		sidebar_buttons: [],
+		dock_panels: [],
+		// 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
+		// servers writes them in a hand-authored `manifest.json`.
+		lsp_servers: {},
+		// Same reason again: a danger-zone category and a Pi extension are both
+		// hand-authored declarations, not something derivable from runnables.
+		data_categories: [],
+		pi_extensions: [],
 		widgets,
 	};
 
@@ -202,7 +240,21 @@ export function defineApp(options: DefineAppOptions): PluginManifest {
 		name: options.title,
 		version: options.version,
 		runnables,
-		permission_grants: options.grants ?? [],
+		// An app that synthesises widgets MUST hold `widget:render`, so this
+		// builder declares it rather than leaving the author to discover it.
+		//
+		// 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.
+		//
+		// 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),
 		activation_events: options.activationEvents ?? ["*"],
 		contributes,
 		// `targets: []` means EVERY surface, so an app that declares none is
@@ -227,7 +279,9 @@ export function defineApp(options: DefineAppOptions): PluginManifest {
 		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}`);
+		throw new Error(
+			`manifest.json validation failed at '${field}': ${message}`
+		);
 	}
 	return result.data;
 }

package/src/runnable/primitives.test.ts

@@ -77,11 +77,7 @@ describe("createPrimitives — transport routing mirrors rpc.ts", () => {
 		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" },
-				})
-			);
+			return Promise.resolve(Response.json({ text: "  hello world  " }));
 		}) as unknown as typeof fetch;
 
 		const transport = httpPrimitiveTransport({

package/src/runnable/primitives.ts

@@ -97,14 +97,17 @@ function dataUrlToBytes(dataUrl: string): {
 		}
 		return { bytes, mediaType };
 	}
-	return { bytes: new TextEncoder().encode(decodeURIComponent(payload)), mediaType };
+	return {
+		bytes: new TextEncoder().encode(decodeURIComponent(payload)),
+		mediaType,
+	};
 }
 
 /** Encode raw bytes as a `data:<mediaType>;base64,...` URL. */
 function bytesToDataUrl(bytes: Uint8Array, mediaType: string): string {
 	let binary = "";
 	// Chunk to stay well under the argument-count ceiling of String.fromCharCode.
-	const chunk = 0x8000;
+	const chunk = 0x80_00;
 	for (let i = 0; i < bytes.length; i += chunk) {
 		binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
 	}
@@ -236,9 +239,7 @@ export function httpPrimitiveTransport(
 			data?: Array<{ url?: string; b64_json?: string }>;
 		};
 		return (parsed.data ?? []).map((item) =>
-			item.url
-				? item.url
-				: `data:image/png;base64,${item.b64_json ?? ""}`
+			item.url ? item.url : `data:image/png;base64,${item.b64_json ?? ""}`
 		);
 	};
 

package/src/runnable/tool.ts

@@ -153,9 +153,6 @@ export interface ToolRunnable<
 	TInput extends Record<string, unknown> = Record<string, unknown>,
 	TOutput = unknown,
 > extends Runnable<TInput, TOutput> {
-	readonly kind: "tool";
-	/** JSON Schema for this tool's input — compatible with Core's ToolInfo.schema. */
-	readonly schema: ToolSchema;
 	/**
 	 * The `run` body serialized for Core's `inline_deno` tool backend — the exact
 	 * same technique `defineTurnHook` uses for its `code`. This is what makes a
@@ -174,6 +171,9 @@ export interface ToolRunnable<
 	 * the sandbox form is the second parameter aliased to `host`.
 	 */
 	readonly code: string;
+	readonly kind: "tool";
+	/** JSON Schema for this tool's input — compatible with Core's ToolInfo.schema. */
+	readonly schema: ToolSchema;
 }
 
 // ── Factory ───────────────────────────────────────────────────────────────────
@@ -232,7 +232,7 @@ export function defineTool<
 }
 
 /**
- * Convert a {@link ToolRunnable} into a `plugin.json` `kind:"tool"` runnable that
+ * 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

package/src/runnable/turn-hook.ts

@@ -15,6 +15,7 @@
 
 import type {
 	Contributes,
+	HookEventContribution,
 	PluginManifest,
 	RunnableMeta,
 	Surface,
@@ -90,9 +91,12 @@ export interface DefineTurnHookOptions {
  * is serialized into the sandbox `code` string and invoked with `ctx`/`host` at
  * run time.
  */
+// `code` is optional on `TurnHookContribution` because a hand-authored manifest may
+// carry `code_file` instead. This builder always produces the inline form, so it
+// narrows the return type — callers get a `code` they need not null-check.
 export function defineTurnHook(
 	options: DefineTurnHookOptions
-): TurnHookContribution {
+): TurnHookContribution & { code: string } {
 	const source = options.run.toString();
 	// The sandbox wraps `code` in an async IIFE where `ctx`/`host` are in scope
 	// and a bare `return` reports the directive — so call the serialized function
@@ -112,8 +116,24 @@ export interface DefinePluginOptions {
 	composerControls?: Record<string, unknown>[];
 	/** Capability grants the hooks need (e.g. `["hook:side-model", "storage:kv"]`). */
 	grants?: string[];
+	/**
+	 * App events this plugin EMITS — the provider half of the hook system whose
+	 * consumer half is {@link DefinePluginOptions.turnHooks}. Each `id` must be
+	 * namespaced to this plugin's own `id`; Core validates that at load and again
+	 * on every emit.
+	 */
+	hookEvents?: HookEventContribution[];
 	/** Reverse-domain id (e.g. `"com.example.my-plugin"`). */
 	id: string;
+	/**
+	 * Language servers the plugin declares, keyed by server name — the same shape
+	 * as Claude Code's `lspServers` / `.lsp.json`, passed verbatim. Loose records
+	 * rather than a typed entry on purpose: Claude Code owns this field
+	 * vocabulary, so typing it here would strip a field from a newer Claude
+	 * release on its way through `ryu pack`. Core types it, because Core acts on
+	 * it.
+	 */
+	lspServers?: Record<string, Record<string, unknown>>;
 	/** Display name. */
 	name: string;
 	/**
@@ -144,19 +164,28 @@ export interface DefinePluginOptions {
 }
 
 /**
- * Assemble a `plugin.json` manifest for a turn-hook plugin. The result matches
+ * Assemble a `manifest.json` manifest for a turn-hook plugin. The result matches
  * Core's `PluginManifest` serde shape and can be written to disk or validated via
  * `validateManifestStrict`.
  */
 export function definePlugin(options: DefinePluginOptions): PluginManifest {
 	const contributes: Contributes = {
 		turn_hooks: options.turnHooks ?? [],
+		hook_events: options.hookEvents ?? [],
 		composer_controls: options.composerControls ?? [],
 		settings_tabs: options.settingsTabs ?? [],
 		slash_commands: options.slashCommands ?? [],
-		// A turn-hook plugin contributes no app widgets; the field is required on the
-		// resolved `Contributes` type (zod default applied), so set it explicitly.
+		lsp_servers: options.lspServers ?? {},
+		// A turn-hook plugin contributes no app widgets, sidebar entries, dock
+		// panels, danger-zone categories or Pi extensions; the fields are required
+		// on the resolved `Contributes` type (zod defaults applied), so set them
+		// explicitly.
 		widgets: [],
+		sidebar_sections: [],
+		sidebar_buttons: [],
+		dock_panels: [],
+		data_categories: [],
+		pi_extensions: [],
 	};
 	// Ship each inline tool as a `kind:"tool"` runnable (Core's `inline_deno`
 	// backend). Shipping tools requires the `tool:execute` grant; add it once.