@ryuhq/sdk 0.0.5 → 0.1.2

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,122 @@ 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>;
+
+// ── PiExtensionContribution ───────────────────────────────────────────────────
+
+/**
+ * One Pi extension the plugin ships — a TypeScript file the managed `ryu` (Pi)
+ * agent loads at process start. Mirrors Rust `PiExtensionContribution`.
+ *
+ * Carries a PATH, never a body: unlike `turn_hooks` there is no inline `code`
+ * twin, because nothing downstream reads the source as a string.
+ *
+ * That makes it a SIDECAR FILE, and `ryu pack` emits a single JSON bundle — so a
+ * plugin installed from a packed bundle arrives without its `pi-extensions/`
+ * directory and Core resolves the declaration to a visible skip. Same open gap as
+ * `skills/**`, which the bundle likewise does not carry. Today the path that works
+ * is a plugin whose directory is on disk (a built-in, a satellite checkout, a dev
+ * tree). Do not "fix" this by inlining the source into the manifest: a 50 KB
+ * TypeScript program escaped into a JSON string is the unauditable form the whole
+ * `code_file` extraction exists to prevent.
+ *
+ * Note this is UNSANDBOXED code: it runs inside the agent process with full host
+ * privilege, so Core gates it behind the operator-only `pi:extension` grant for
+ * any non-built-in plugin.
+ */
+export const PiExtensionContributionSchema = z.object({
+	/** Stable id for this extension within the plugin (`[a-z0-9][a-z0-9._-]*`). */
+	id: z.string().min(1),
+	/** Path to the source, relative to the plugin root: `pi-extensions/<name>.ts`. */
+	file: z.string().min(1),
+	/** Optional one-liner describing what the extension adds to the agent. */
+	description: z.string().optional(),
+});
+
+export type PiExtensionContribution = z.infer<
+	typeof PiExtensionContributionSchema
+>;
 
 // ── WidgetContribution (Ryu Apps) ─────────────────────────────────────────────
 
@@ -243,6 +345,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 +358,50 @@ 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([]),
+	/** Deletable data categories the app owns — one "Delete all X" row in Settings
+	 *  → Danger Zone. Mirrors the Rust-side `Contributes.data_categories`; without
+	 *  it the CLI's zod parse would strip the declaration before signing, and the
+	 *  app's danger-zone row would simply never appear on any node that installed
+	 *  the packed bundle. Loosely typed here for the same reason as the surfaces
+	 *  above — Core is the layer that types it, because Core is the layer that has
+	 *  to resolve the id to something that can actually delete the rows. */
+	data_categories: 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({}),
+	/** Pi extensions the plugin ships — TypeScript the managed `ryu` (Pi) agent
+	 *  loads at process start. Mirrors the Rust-side `Contributes.pi_extensions`;
+	 *  without it the CLI's zod parse would strip the declaration before signing,
+	 *  and the packed plugin would ship a `pi-extensions/` folder nothing loads.
+	 *
+	 *  Typed (not a loose record) because Ryu owns this vocabulary — three fields,
+	 *  all of them Core-interpreted — unlike `lsp_servers`, whose entry shape is
+	 *  Claude Code's to extend. */
+	pi_extensions: z.array(PiExtensionContributionSchema).default([]),
 });
 
 export type Contributes = z.infer<typeof ContributesSchema>;
@@ -382,7 +533,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 +681,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 +733,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 +744,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 +753,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")
+		);
+	});
+});