@ryuhq/sdk 0.0.5 → 0.0.17

package/src/manifest.test.ts

@@ -167,10 +167,10 @@ describe("round-trip: SDK build → JSON → Core schema parse", () => {
 		}
 	});
 
-	it("emitted plugin.json satisfies PluginManifestSchema (Core compat proof)", () => {
+	it("emitted manifest.json satisfies PluginManifestSchema (Core compat proof)", () => {
 		// 1. Build a manifest using the SDK.
 		const manifest = new PluginBuilder()
-			.id("com.example.research-assistant")
+			.id("@example/research-assistant")
 			.name("Research Assistant")
 			.version("1.0.0")
 			.runnable(agent().id("agent-researcher").name("Researcher").build())
@@ -188,8 +188,8 @@ describe("round-trip: SDK build → JSON → Core schema parse", () => {
 			})
 			.build();
 
-		// 2. Emit to a temp plugin.json (simulating what `ryu pack` writes).
-		const manifestPath = join(tmpDir, "plugin.json");
+		// 2. Emit to a temp manifest.json (simulating what `ryu pack` writes).
+		const manifestPath = join(tmpDir, "manifest.json");
 		writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf8");
 
 		// 3. Read it back and parse through `PluginManifestSchema` — the same
@@ -204,7 +204,7 @@ describe("round-trip: SDK build → JSON → Core schema parse", () => {
 		}
 
 		const loaded = result.data;
-		expect(loaded.id).toBe("com.example.research-assistant");
+		expect(loaded.id).toBe("@example/research-assistant");
 		expect(loaded.runnables).toHaveLength(4);
 		expect(loaded.permission_grants).toEqual([
 			"mcp:web_search",
@@ -213,11 +213,11 @@ describe("round-trip: SDK build → JSON → Core schema parse", () => {
 		expect(loaded.companion?.shortcut).toBe("ctrl+shift+r");
 	});
 
-	it("matches the Core fixture (sample.plugin.json)", () => {
+	it("matches the Core fixture (sample.manifest.json)", () => {
 		// The Core Rust test (`sample_fixture_deserializes_into_app_manifest`)
 		// asserts the same values — this verifies TS schema parity.
 		const fixture = {
-			id: "com.example.research-assistant",
+			id: "@example/research-assistant",
 			name: "Research Assistant",
 			version: "1.0.0",
 			runnables: [
@@ -240,7 +240,7 @@ describe("round-trip: SDK build → JSON → Core schema parse", () => {
 			return;
 		}
 
-		expect(result.data.id).toBe("com.example.research-assistant");
+		expect(result.data.id).toBe("@example/research-assistant");
 		expect(result.data.runnables).toHaveLength(4);
 		const kinds = result.data.runnables.map((r) => r.kind);
 		expect(kinds).toContain("agent");
@@ -424,7 +424,13 @@ describe("AppBuilder", () => {
 		expect(manifest.runnables).toHaveLength(2);
 		expect(manifest.contributes?.widgets).toHaveLength(1);
 		expect(manifest.contributes?.widgets[0]?.tool_id).toBe("checklist__render");
-		expect(manifest.permission_grants).toEqual(["mcp:file_read"]);
+		// The author's own grant, plus the `widget:render` the builder adds because
+		// this app synthesises a widget — without it Core silently degrades the
+		// widget to plain text.
+		expect(manifest.permission_grants).toEqual([
+			"mcp:file_read",
+			"widget:render",
+		]);
 	});
 
 	it("throws on missing id", () => {
@@ -475,15 +481,15 @@ describe("requires / targets", () => {
 			.id("com.example.meetings")
 			.name("Meetings")
 			.version("1.0.0")
-			.dependsOn("com.ryu.spaces", "1.2.0")
-			.dependsOn("com.ryu.voice")
+			.dependsOn("@ryu/spaces", "1.2.0")
+			.dependsOn("@ryu/voice")
 			.requiredGrant("spaces:docs")
 			.build();
 
 		// Survives the builder…
 		expect(manifest.requires?.apps).toEqual([
-			{ id: "com.ryu.spaces", min_version: "1.2.0" },
-			{ id: "com.ryu.voice" },
+			{ id: "@ryu/spaces", min_version: "1.2.0" },
+			{ id: "@ryu/voice" },
 		]);
 		expect(manifest.requires?.grants).toEqual(["spaces:docs"]);
 
@@ -509,7 +515,7 @@ describe("requires / targets", () => {
 			name: "Partial",
 			version: "1.0.0",
 			runnables: [],
-			requires: { apps: [{ id: "com.ryu.spaces" }] },
+			requires: { apps: [{ id: "@ryu/spaces" }] },
 		});
 
 		expect(parsed.success).toBe(true);
@@ -587,11 +593,11 @@ describe("requires / targets", () => {
 			slug: "dep-app",
 			uiEntry: "src/dep-app.tsx",
 			tools: [{ name: "render", description: "Render" }],
-			requires: { apps: [{ id: "com.ryu.spaces", min_version: "1.0.0" }] },
+			requires: { apps: [{ id: "@ryu/spaces", min_version: "1.0.0" }] },
 			targets: ["desktop"],
 		});
 
-		expect(manifest.requires?.apps[0]?.id).toBe("com.ryu.spaces");
+		expect(manifest.requires?.apps[0]?.id).toBe("@ryu/spaces");
 		expect(manifest.requires?.grants).toEqual([]);
 		expect(manifest.targets).toEqual(["desktop"]);
 
@@ -608,3 +614,81 @@ describe("requires / targets", () => {
 		expect(plain.targets).toEqual([]);
 	});
 });
+
+// ── contributes.lsp_servers (Claude Code language-server parity) ──────────────
+//
+// Same load-bearing property as the block above: `ryu pack` / `ryu publish`
+// persist `PluginManifestSchema.safeParse(...).data`, so a contribution family
+// missing from `ContributesSchema` is silently DELETED before the manifest is
+// signed. These assert the declaration SURVIVES the parse — byte-for-byte, since
+// the entry body is Claude Code's own camelCase vocabulary and Ryu is only its
+// courier.
+
+describe("contributes.lsp_servers", () => {
+	/** The `.lsp.json` example from Claude Code's plugins reference, verbatim. */
+	const claudeCodeGoServer = {
+		command: "gopls",
+		args: ["serve"],
+		extensionToLanguage: { ".go": "go" },
+	};
+
+	it("keeps a Claude Code language server through the pack-path parse", () => {
+		const parsed = PluginManifestSchema.safeParse({
+			id: "com.example.go-lsp",
+			name: "Go LSP",
+			version: "1.0.0",
+			runnables: [],
+			contributes: { lsp_servers: { go: claudeCodeGoServer } },
+		});
+
+		expect(parsed.success).toBe(true);
+		if (!parsed.success) {
+			return;
+		}
+		expect(parsed.data.contributes?.lsp_servers.go).toEqual(claudeCodeGoServer);
+	});
+
+	it("keeps an unknown entry key too (Claude Code owns the vocabulary)", () => {
+		// The entry is a loose record on purpose: typing the 13 documented fields
+		// here would strip a field from a newer Claude release on its way through
+		// `ryu pack` — the same silent deletion, one level down.
+		const parsed = PluginManifestSchema.safeParse({
+			id: "com.example.future-lsp",
+			name: "Future LSP",
+			version: "1.0.0",
+			runnables: [],
+			contributes: {
+				lsp_servers: {
+					go: { ...claudeCodeGoServer, someFutureClaudeField: { deep: true } },
+				},
+			},
+		});
+
+		expect(parsed.success).toBe(true);
+		if (!parsed.success) {
+			return;
+		}
+		expect(parsed.data.contributes?.lsp_servers.go).toMatchObject({
+			someFutureClaudeField: { deep: true },
+		});
+	});
+
+	it("yields an empty map, never undefined, when none is declared", () => {
+		const parsed = PluginManifestSchema.safeParse({
+			id: "com.example.legacy",
+			name: "Legacy",
+			version: "1.0.0",
+			runnables: [],
+			contributes: {},
+		});
+
+		expect(parsed.success).toBe(true);
+		if (!parsed.success) {
+			return;
+		}
+		// Core's field is `#[serde(default, skip_serializing_if = "…is_empty")]`, so
+		// an empty map here round-trips to a manifest with no `lsp_servers` key at
+		// all — every plugin predating this surface keeps parsing on both sides.
+		expect(parsed.data.contributes?.lsp_servers).toEqual({});
+	});
+});

package/src/manifest.ts

@@ -24,11 +24,11 @@ import { z } from "zod";
 // must therefore never hard-require the addon at module load. We load it lazily
 // on first use of a helper that needs it, cache it, and throw a descriptive
 // error only if a caller actually invokes those helpers without the addon.
-type NativeAddon = {
-	validatePluginId(id: string): void;
+interface NativeAddon {
 	parseAndValidateManifest(manifestJson: string): string;
 	pluginManifestJsonSchema(): string;
-};
+	validatePluginId(id: string): void;
+}
 
 let cachedNative: NativeAddon | null = null;
 let nativeLoadError: Error | null = null;
@@ -157,20 +157,87 @@ export type CompanionSurface = z.infer<typeof CompanionSurfaceSchema>;
 
 /**
  * A server-side chat turn hook. Mirrors `TurnHookContribution` in
- * `apps/core/src/plugin_manifest/mod.rs`. `code` is a JS body run in the plugin
- * sandbox with `ctx` + `host` in scope; it returns a directive. Authors usually
- * build this via `defineTurnHook` rather than writing the string by hand.
+ * `crates/core/kernel-contracts/src/manifest.rs`. The body is a JS fragment run in
+ * the plugin sandbox with `ctx` + `host` in scope; it returns a directive.
+ *
+ * It arrives one of two ways, and **exactly one** must be present:
+ *
+ * - `code_file` — the authoring form: a path to a real `hooks/<name>.js` file next
+ *   to the manifest. Readable, lintable, diffable, and reviewable for what it
+ *   actually does. Every first-party plugin uses this.
+ * - `code` — the wire form: the body inline. `ryu pack` produces it by reading
+ *   `code_file`, which is what keeps the whole hook body INSIDE the Gateway-signed
+ *   surface; Core also accepts it directly for a hand-written or `defineTurnHook`
+ *   generated manifest.
+ */
+export const TurnHookContributionSchema = z
+	.object({
+		/** Stable id for this hook (unique within the plugin). */
+		id: z.string().min(1),
+		/** Turn boundary this fires on. Today only `"post_assistant_turn"`. */
+		on: z.string().min(1).default("post_assistant_turn"),
+		/** The JS hook body executed in the sandbox (returns a directive). */
+		code: z.string().min(1).optional(),
+		/** Path to the hook body, relative to the plugin root (`hooks/<name>.js`). */
+		code_file: z.string().min(1).optional(),
+		/**
+		 * Cheap pre-gate mirroring Core's `HookMatch` (serde name `match` on
+		 * `TurnHookContribution.run_when`). MUST round-trip through this schema:
+		 * `ryu pack`/`publish` persist `safeParse(...).data`, so a field missing here
+		 * is silently STRIPPED before signing — a tool-gated `pre_tool_use` hook
+		 * (e.g. `tools: ["bash*"]`) would lose its gate and run on EVERY tool call.
+		 */
+		match: z
+			.object({
+				/** Run only if the request set this composer flag true. */
+				flag: z.string().optional(),
+				/** Run if the last user message starts with any of these prefixes. */
+				commands: z.array(z.string()).default([]),
+				/** Run if the plugin has stored state for this conversation. */
+				stateful: z.boolean().default(false),
+				/** Run if `ctx.tool_name` matches any of these `*`-wildcard patterns. */
+				tools: z.array(z.string()).default([]),
+			})
+			.optional(),
+	})
+	// Fail closed, mirroring Core: declaring NEITHER would have the sandbox run an
+	// empty body, which no read site can tell apart from a hook that chose to do
+	// nothing; declaring BOTH gives two sources of truth for what executes.
+	.refine((h) => Boolean(h.code) !== Boolean(h.code_file), {
+		message:
+			"a turn hook must declare exactly one of 'code' (inline body) or 'code_file' (path to hooks/<name>.js)",
+		path: ["code_file"],
+	});
+
+export type TurnHookContribution = z.infer<typeof TurnHookContributionSchema>;
+
+/**
+ * One **app event** this plugin declares it emits. Mirrors `HookEventContribution`
+ * in `crates/core/kernel-contracts/src/manifest.rs`.
+ *
+ * `turn_hooks` is the *consuming* half of the hook system; this is the *providing*
+ * half. Declaring an event here lets any other plugin react to it with a
+ * `turn_hooks[].on` naming the event, and any workflow react to it with an `event`
+ * trigger — without the emitter knowing a consumer exists. The event is raised at
+ * runtime by this plugin's own sidecar calling the `events.emit` host capability.
+ *
+ * `id` MUST be `<this plugin's id>#<event name>`. Core validates the namespace half
+ * against the owning manifest at load and re-checks it on every emit, which is both
+ * what makes collisions with Core's own hook phases impossible (a Core phase never
+ * contains `#`) and what stops one app emitting another's events.
  */
-export const TurnHookContributionSchema = z.object({
-	/** Stable id for this hook (unique within the plugin). */
+export const HookEventContributionSchema = z.object({
+	/** Fully-qualified event id: `<plugin id>#<event name>`, e.g. `@acme/meetings#meeting.ended`. */
 	id: z.string().min(1),
-	/** Turn boundary this fires on. Today only `"post_assistant_turn"`. */
-	on: z.string().min(1).default("post_assistant_turn"),
-	/** The JS hook body executed in the sandbox (returns a directive). */
-	code: z.string().min(1),
+	/** Human-readable title for the event picker. */
+	title: z.string().min(1),
+	/** What the event means and when it fires. */
+	description: z.string().optional(),
+	/** Example of the `ctx.event` payload. Documentation, not a validated schema. */
+	payload_example: z.record(z.string(), z.unknown()).optional(),
 });
 
-export type TurnHookContribution = z.infer<typeof TurnHookContributionSchema>;
+export type HookEventContribution = z.infer<typeof HookEventContributionSchema>;
 
 // ── WidgetContribution (Ryu Apps) ─────────────────────────────────────────────
 
@@ -243,6 +310,11 @@ export type ToolAppConfig = z.infer<typeof ToolAppConfigSchema>;
  */
 export const ContributesSchema = z.object({
 	turn_hooks: z.array(TurnHookContributionSchema).default([]),
+	/** App events this plugin EMITS — the provider half of the hook system, whose
+	 *  consumer half is `turn_hooks`. Mirrors the Rust `Contributes.hook_events`;
+	 *  omitting it here would have `ryu pack` strip every declared event before
+	 *  signing, leaving an app that emits events nothing is allowed to subscribe to. */
+	hook_events: z.array(HookEventContributionSchema).default([]),
 	composer_controls: 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([]),
@@ -251,6 +323,33 @@ export const ContributesSchema = z.object({
 	 *  `Contributes.widgets` field, without which the CLI's zod parse would strip
 	 *  every widget an app authored here declares. */
 	widgets: z.array(WidgetContributionSchema).default([]),
+	/** App-registered sidebar sections (header + live list) and buttons (single nav
+	 *  rows). Loosely typed here — the shell owns the spec vocabulary — matching how
+	 *  `composer_controls`/`settings_tabs` are declared. Mirrors the Rust-side
+	 *  `Contributes.sidebar_sections` / `Contributes.sidebar_buttons`. */
+	sidebar_sections: z.array(z.record(z.string(), z.unknown())).default([]),
+	sidebar_buttons: z.array(z.record(z.string(), z.unknown())).default([]),
+	/** App-registered workspace dock panels (a tab in the desktop's bottom/right
+	 *  dock). Loosely typed for the same reason as the surfaces above — the shell
+	 *  owns the `panel` render-mode vocabulary and the `spec` payload. Mirrors the
+	 *  Rust-side `Contributes.dock_panels`; without it the CLI's zod parse would
+	 *  strip the dock panel an app declares here. */
+	dock_panels: z.array(z.record(z.string(), z.unknown())).default([]),
+	/** Language servers the plugin declares, keyed by server name — the mirror of
+	 *  Claude Code's `.lsp.json` / `lspServers`, so a config written for either host
+	 *  loads in the other. Mirrors the Rust-side `Contributes.lsp_servers`; without
+	 *  it the CLI's zod parse would strip every language server a plugin declares,
+	 *  before the manifest is signed.
+	 *
+	 *  The ENTRY is deliberately a loose record and not a 13-field `z.object()`
+	 *  mirroring `LspServerContribution`. Claude Code owns this field vocabulary,
+	 *  not Ryu: a typed object here would strip a field from a newer Claude release
+	 *  on its way through `ryu pack` — the same silent-deletion bug this field
+	 *  exists to fix, one level down. Core is the layer that types it, because Core
+	 *  is the layer that acts on it. */
+	lsp_servers: z
+		.record(z.string(), z.record(z.string(), z.unknown()))
+		.default({}),
 });
 
 export type Contributes = z.infer<typeof ContributesSchema>;
@@ -382,7 +481,7 @@ export type Surface = z.infer<typeof SurfaceSchema>;
 // ── PluginManifest ───────────────────────────────────────────────────────────
 
 /**
- * Full schema for a `plugin.json` Plugin manifest. Mirrors `PluginManifest` in
+ * Full schema for a `manifest.json` Plugin manifest. Mirrors `PluginManifest` in
  * `apps/core/src/plugin_manifest/mod.rs`.
  *
  * Validation rules (matching Core's `PluginManifestLoader`):
@@ -530,6 +629,27 @@ export const PluginManifestSchema = z.object({
 	license: z.string().optional(),
 	/** Square logo/icon URL for the listing card + detail header. */
 	iconUrl: z.string().optional(),
+	/**
+	 * Icon-primitive id for the listing card (Ryu extension): an Iconify/icons0
+	 * `prefix:name`, a bare Hugeicons name, or a URL, resolved by the shared `Icon`
+	 * primitive. A monochrome GLYPH masked with the current text colour — distinct
+	 * from `iconUrl` (a raster logo). Falls back to `iconUrl` when omitted.
+	 */
+	icon: z.string().optional(),
+	/**
+	 * Dithered-gradient background for the card's icon square (Ryu extension),
+	 * mirroring dither-kit's `DitherGradient` props. `from`/`to` are a palette-colour
+	 * name (`green`, `blue`, `purple`, `pink`, `orange`, `red`, `grey`) or a hue
+	 * number (0–360); `direction` is where `to` ends up. Renders behind the glyph in
+	 * place of a flat `iconBackground`; the render layer validates + falls back.
+	 */
+	iconDither: z
+		.object({
+			from: z.union([z.string(), z.number()]),
+			to: z.union([z.string(), z.number()]).optional(),
+			direction: z.enum(["up", "down", "left", "right"]).optional(),
+		})
+		.optional(),
 	/** Ordered App-Store-style screenshot gallery URLs (Ryu extension). */
 	screenshots: z.array(z.string()).optional(),
 	/** Privacy policy URL surfaced on detail (Ryu extension). */
@@ -561,7 +681,7 @@ export type PluginManifest = z.infer<typeof PluginManifestSchema>;
 // `PluginManifestSchema` above models the SDK's simpler authoring shape
 // (runnables = identity metadata only). Until those shapes are reconciled
 // (follow-up), use the zod schema for SDK authoring and these helpers when you
-// need Core-strict validation of a full `plugin.json`.
+// need Core-strict validation of a full `manifest.json`.
 
 /**
  * Validate a plugin id with Core's strict reverse-domain, path-traversal-safe
@@ -572,7 +692,7 @@ export function validatePluginId(id: string): void {
 }
 
 /**
- * Validate a full `plugin.json` string against Core's authoritative rules
+ * Validate a full `manifest.json` string against Core's authoritative rules
  * (id, semver, per-kind runnable config contracts). Returns the normalized
  * manifest JSON string, or throws.
  */
@@ -581,7 +701,7 @@ export function validateManifestStrict(manifestJson: string): string {
 }
 
 /**
- * The Core-derived JSON Schema for a `plugin.json`, as a parsed object. Stays in
+ * The Core-derived JSON Schema for a `manifest.json`, as a parsed object. Stays in
  * lockstep with the Rust types because it is emitted from them.
  */
 export function coreManifestJsonSchema(): unknown {

package/src/plugin/ryu-plugin.ts

@@ -173,7 +173,7 @@ export interface RyuPlugin {
  *  `subscriptions`; the host disposes them all on `deactivate`. */
 export interface PluginContext {
 	readonly plugin: RyuPlugin;
-	/** The plugin's own id (from `plugin.json`). */
+	/** The plugin's own id (from `manifest.json`). */
 	readonly pluginId: string;
 	/** Disposables auto-cleaned on deactivate. */
 	readonly subscriptions: Disposable[];

package/src/runnable/agent.ts

@@ -117,7 +117,7 @@ export interface AgentRunnable<TInput = unknown, TOutput = unknown>
 	/** The lowered slot card (empty edges when no slots were declared). */
 	readonly card: AgentCard;
 	/**
-	 * Lower this agent (card + run identity) to a single-agent `plugin.json`
+	 * Lower this agent (card + run identity) to a single-agent `manifest.json`
 	 * `PluginManifest`: the agent `RunnableMeta` carries the persona/model
 	 * config; `requires.capabilities` carries the slot edges. Throws if the
 	 * assembled manifest is invalid.
@@ -242,7 +242,7 @@ function cardConfig(card: AgentCard): Record<string, unknown> {
 	return config;
 }
 
-/** Lower an agent to a single-agent `plugin.json` `PluginManifest`. */
+/** Lower an agent to a single-agent `manifest.json` `PluginManifest`. */
 function agentToManifest(
 	agent: Runnable & { card: AgentCard },
 	options: AgentManifestOptions
@@ -288,7 +288,7 @@ function agentToManifest(
  *
  * The returned value satisfies `Runnable<TInput, TOutput>` with `kind = "agent"`
  * and additionally exposes the lowered {@link AgentCard} + a `toManifest()`
- * lowering, so a slot-composed agent round-trips to a valid `plugin.json`.
+ * lowering, so a slot-composed agent round-trips to a valid `manifest.json`.
  *
  * @example Classic (unchanged, back-compat):
  * ```ts

package/src/runnable/app.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "bun:test";
+import { PluginManifestSchema } from "../manifest.ts";
+import { appToolId, defineApp, WIDGET_RENDER_GRANT } from "./app.ts";
+
+/** A minimal single-render-tool app — the shape both scaffold templates emit. */
+function checklistApp(grants?: string[]) {
+	return defineApp({
+		id: "com.example.checklist",
+		slug: "checklist",
+		title: "Checklist",
+		version: "1.0.0",
+		...(grants ? { grants } : {}),
+		tools: [{ name: "render", description: "Render a checklist" }],
+	});
+}
+
+describe("defineApp widget grant", () => {
+	it("declares widget:render for an app that contributes a widget", () => {
+		// The whole point: Core refuses to promote a widget whose owning plugin
+		// lacks this grant, and the refusal is an info-log — the widget just
+		// silently renders as text. An app scaffolded with no `grants` used to hit
+		// that every time.
+		const manifest = checklistApp();
+		expect(manifest.contributes?.widgets ?? []).toHaveLength(1);
+		expect(manifest.permission_grants).toContain(WIDGET_RENDER_GRANT);
+	});
+
+	it("keeps the author's own grants and appends, never replaces", () => {
+		const manifest = checklistApp(["mcp:web_search"]);
+		expect(manifest.permission_grants).toEqual([
+			"mcp:web_search",
+			WIDGET_RENDER_GRANT,
+		]);
+	});
+
+	it("does not duplicate a grant the author already declared", () => {
+		const manifest = checklistApp([WIDGET_RENDER_GRANT]);
+		expect(
+			manifest.permission_grants?.filter((g) => g === WIDGET_RENDER_GRANT)
+		).toHaveLength(1);
+	});
+
+	it("does not add the grant to an app that contributes no widget", () => {
+		// Every tool marked `accessible` is a companion (call target), so nothing
+		// renders — the grant would be an unused capability on the record.
+		const manifest = defineApp({
+			id: "com.example.tools",
+			slug: "tools",
+			title: "Tools",
+			version: "1.0.0",
+			tools: [{ name: "toggle", description: "Toggle", accessible: true }],
+		});
+		expect(manifest.contributes?.widgets ?? []).toHaveLength(0);
+		expect(manifest.permission_grants ?? []).not.toContain(WIDGET_RENDER_GRANT);
+	});
+
+	it("still emits a manifest Core's own schema accepts", () => {
+		expect(() => PluginManifestSchema.parse(checklistApp())).not.toThrow();
+	});
+
+	it("binds the widget to the render tool's fully-qualified id", () => {
+		const manifest = checklistApp();
+		expect(manifest.contributes?.widgets?.[0]?.tool_id).toBe(
+			appToolId("checklist", "render")
+		);
+	});
+});

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,21 @@ 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: {},
 		widgets,
 	};
 
@@ -202,7 +236,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 +275,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 ?? ""}`
 		);
 	};