@ryuhq/sdk 0.0.5 → 0.0.17

package/dist/index.cjs

@@ -194,7 +194,10 @@ function dataUrlToBytes(dataUrl) {
     }
     return { bytes, mediaType };
   }
-  return { bytes: new TextEncoder().encode(decodeURIComponent(payload)), mediaType };
+  return {
+    bytes: new TextEncoder().encode(decodeURIComponent(payload)),
+    mediaType
+  };
 }
 function bytesToDataUrl(bytes, mediaType) {
   let binary = "";
@@ -903,7 +906,39 @@ var TurnHookContributionSchema = import_zod.z.object({
   /** Turn boundary this fires on. Today only `"post_assistant_turn"`. */
   on: import_zod.z.string().min(1).default("post_assistant_turn"),
   /** The JS hook body executed in the sandbox (returns a directive). */
-  code: import_zod.z.string().min(1)
+  code: import_zod.z.string().min(1).optional(),
+  /** Path to the hook body, relative to the plugin root (`hooks/<name>.js`). */
+  code_file: import_zod.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: import_zod.z.object({
+    /** Run only if the request set this composer flag true. */
+    flag: import_zod.z.string().optional(),
+    /** Run if the last user message starts with any of these prefixes. */
+    commands: import_zod.z.array(import_zod.z.string()).default([]),
+    /** Run if the plugin has stored state for this conversation. */
+    stateful: import_zod.z.boolean().default(false),
+    /** Run if `ctx.tool_name` matches any of these `*`-wildcard patterns. */
+    tools: import_zod.z.array(import_zod.z.string()).default([])
+  }).optional()
+}).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"]
+});
+var HookEventContributionSchema = import_zod.z.object({
+  /** Fully-qualified event id: `<plugin id>#<event name>`, e.g. `@acme/meetings#meeting.ended`. */
+  id: import_zod.z.string().min(1),
+  /** Human-readable title for the event picker. */
+  title: import_zod.z.string().min(1),
+  /** What the event means and when it fires. */
+  description: import_zod.z.string().optional(),
+  /** Example of the `ctx.event` payload. Documentation, not a validated schema. */
+  payload_example: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional()
 });
 var DEFAULT_WIDGET_MIME = "text/html+skybridge";
 var DEFAULT_WIDGET_DISPLAY_MODE = "inline";
@@ -941,6 +976,11 @@ var ToolAppConfigSchema = import_zod.z.object({
 });
 var ContributesSchema = import_zod.z.object({
   turn_hooks: import_zod.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: import_zod.z.array(HookEventContributionSchema).default([]),
   composer_controls: import_zod.z.array(import_zod.z.record(import_zod.z.string(), import_zod.z.unknown())).default([]),
   settings_tabs: import_zod.z.array(import_zod.z.record(import_zod.z.string(), import_zod.z.unknown())).default([]),
   slash_commands: import_zod.z.array(import_zod.z.record(import_zod.z.string(), import_zod.z.unknown())).default([]),
@@ -948,7 +988,32 @@ var ContributesSchema = import_zod.z.object({
    *  `ui://widget/<slug>.html` template. Mirrors the Rust-side
    *  `Contributes.widgets` field, without which the CLI's zod parse would strip
    *  every widget an app authored here declares. */
-  widgets: import_zod.z.array(WidgetContributionSchema).default([])
+  widgets: import_zod.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: import_zod.z.array(import_zod.z.record(import_zod.z.string(), import_zod.z.unknown())).default([]),
+  sidebar_buttons: import_zod.z.array(import_zod.z.record(import_zod.z.string(), import_zod.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: import_zod.z.array(import_zod.z.record(import_zod.z.string(), import_zod.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: import_zod.z.record(import_zod.z.string(), import_zod.z.record(import_zod.z.string(), import_zod.z.unknown())).default({})
 });
 var SetupStepSchema = import_zod.z.object({
   /** Card heading (e.g. the companion app name). */
@@ -1129,6 +1194,25 @@ var PluginManifestSchema = import_zod.z.object({
   license: import_zod.z.string().optional(),
   /** Square logo/icon URL for the listing card + detail header. */
   iconUrl: import_zod.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: import_zod.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: import_zod.z.object({
+    from: import_zod.z.union([import_zod.z.string(), import_zod.z.number()]),
+    to: import_zod.z.union([import_zod.z.string(), import_zod.z.number()]).optional(),
+    direction: import_zod.z.enum(["up", "down", "left", "right"]).optional()
+  }).optional(),
   /** Ordered App-Store-style screenshot gallery URLs (Ryu extension). */
   screenshots: import_zod.z.array(import_zod.z.string()).optional(),
   /** Privacy policy URL surfaced on detail (Ryu extension). */
@@ -1162,6 +1246,14 @@ function coreManifestJsonSchema() {
 // src/runnable/app.ts
 var DEFAULT_APP_WIDGET_MIME = "text/html+skybridge";
 var DEFAULT_APP_DISPLAY_MODE = "inline";
+var WIDGET_RENDER_GRANT = "widget:render";
+function withWidgetRenderGrant(grants, widgets) {
+  const out = [...grants];
+  if (widgets.length > 0 && !out.includes(WIDGET_RENDER_GRANT)) {
+    out.push(WIDGET_RENDER_GRANT);
+  }
+  return out;
+}
 function appToolId(server, name) {
   return `${server}__${name}`;
 }
@@ -1203,9 +1295,21 @@ function defineApp(options) {
   }
   const 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
   };
   const raw = {
@@ -1213,7 +1317,21 @@ function defineApp(options) {
     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
@@ -1235,7 +1353,9 @@ function defineApp(options) {
     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;
 }
@@ -1431,7 +1551,7 @@ var PluginBuilder = class {
       const field = first?.path.join(".") ?? "unknown";
       const message = first?.message ?? "validation failed";
       throw new Error(
-        `plugin.json validation failed at '${field}': ${message}`
+        `manifest.json validation failed at '${field}': ${message}`
       );
     }
     return result.data;
@@ -1804,12 +1924,18 @@ function defineTurnHook(options) {
 function definePlugin(options) {
   const 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.
-    widgets: []
+    lsp_servers: options.lspServers ?? {},
+    // A turn-hook plugin contributes no app widgets, sidebar entries or dock
+    // panels; the fields are required on the resolved `Contributes` type (zod
+    // defaults applied), so set them explicitly.
+    widgets: [],
+    sidebar_sections: [],
+    sidebar_buttons: [],
+    dock_panels: []
   };
   const tools = options.tools ?? [];
   const runnables = tools.map((t) => inlineToolRunnable(t));

package/dist/index.d.cts

@@ -1,6 +1,6 @@
-import { R as Runnable, a as RunnableContext, T as ToolRunnable } from './index-CEbS1SlS.cjs';
-export { A as Agent, b as AgentConfig, c as AgentEvent, d as AgentTool, C as ChatDelta, e as ChatMessage, f as ChatResult, D as DurableClient, E as Endpoint, g as EnginesClient, G as GatewayClient, h as GenerateResult, H as HttpPrimitiveTransportOptions, I as ImageClient, J as JsonSchemaProperty, M as MemoryClient, i as MemoryItem, j as ModelClient, k as ModelClientOptions, P as PRIMITIVE_BINDINGS, l as PrimitiveBinding, m as PrimitiveTransport, Q as QueryInput, n as QueryOptions, o as RagChunk, p as RagClient, q as RagRerankResult, r as RealtimeClient, s as RealtimeSubscription, t as RemoteToolRef, u as RyuPrimitives, S as SttClient, v as ToolOptions, w as ToolSchema, x as TtsClient, y as createAgent, z as createPrimitives, B as defineModel, F as defineTool, K as httpPrimitiveTransport, L as inlineToolRunnable, N as query, O as ryuTool } from './index-CEbS1SlS.cjs';
-import { Requires, Surface, PluginManifest, RunnableMeta, CompanionSurface, CapabilityReq, TurnHookContribution } from './manifest.cjs';
+import { R as Runnable, a as RunnableContext, T as ToolRunnable } from './index-BvAB5eMk.cjs';
+export { A as Agent, b as AgentConfig, c as AgentEvent, d as AgentTool, C as ChatDelta, e as ChatMessage, f as ChatResult, D as DurableClient, E as Endpoint, g as EnginesClient, G as GatewayClient, h as GenerateResult, H as HttpPrimitiveTransportOptions, I as ImageClient, J as JsonSchemaProperty, M as MemoryClient, i as MemoryItem, j as ModelClient, k as ModelClientOptions, P as PRIMITIVE_BINDINGS, l as PrimitiveBinding, m as PrimitiveTransport, Q as QueryInput, n as QueryOptions, o as RagChunk, p as RagClient, q as RagRerankResult, r as RealtimeClient, s as RealtimeSubscription, t as RemoteToolRef, u as RyuPrimitives, S as SttClient, v as ToolOptions, w as ToolSchema, x as TtsClient, y as createAgent, z as createPrimitives, B as defineModel, F as defineTool, K as httpPrimitiveTransport, L as inlineToolRunnable, N as query, O as ryuTool } from './index-BvAB5eMk.cjs';
+import { Requires, Surface, PluginManifest, RunnableMeta, CompanionSurface, CapabilityReq, HookEventContribution, TurnHookContribution } from './manifest.cjs';
 export { AppDependency, AppDependencySchema, CapabilityReqSchema, CompanionSurfaceSchema, Contributes, PluginManifestSchema, RequiresSchema, RunnableKind, RunnableKindSchema, RunnableMetaSchema, SurfaceSchema, ToolAppConfig, ToolAppConfigSchema, WidgetContribution, WidgetContributionSchema, coreManifestJsonSchema, validateManifestStrict, validatePluginId } from './manifest.cjs';
 import 'zod';
 
@@ -9,7 +9,7 @@ import 'zod';
  *
  * 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()`):
  *
@@ -107,7 +107,7 @@ interface DefineAppOptions {
 /** Build a fully-qualified tool id from a server namespace and tool name. */
 declare 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`.
  *
@@ -132,7 +132,7 @@ declare function defineApp(options: DefineAppOptions): PluginManifest;
 
 /**
  * Ryu SDK typed builders — one builder per RunnableKind plus a PluginBuilder that
- * assembles a complete, validated `plugin.json` manifest.
+ * assembles a complete, validated `manifest.json` manifest.
  *
  * Each builder follows a fluent interface: construct, chain setter calls, then
  * call `.build()` to get a validated result. Invalid manifests throw a
@@ -174,7 +174,7 @@ declare const tool: () => ToolBuilder;
 /** Create a SkillBuilder. */
 declare const skill: () => SkillBuilder;
 /**
- * Fluent builder for a complete `plugin.json` Plugin manifest. Produces a
+ * Fluent builder for a complete `manifest.json` Plugin manifest. Produces a
  * validated `PluginManifest` on `.build()` or throws a descriptive `Error`
  * naming the first invalid field.
  *
@@ -252,7 +252,7 @@ declare class PluginBuilder {
     build(): PluginManifest;
 }
 /**
- * Fluent builder for a Ryu App — a `plugin.json` whose tools render interactive
+ * Fluent builder for a Ryu App — a `manifest.json` whose tools render interactive
  * widgets inline in chat. Delegates to {@link defineApp} on `.build()`, so it
  * derives the render-vs-companion split and validates through
  * `PluginManifestSchema` (throwing a descriptive `Error` on bad input) exactly
@@ -470,7 +470,7 @@ interface AgentRunnable<TInput = unknown, TOutput = unknown> extends Runnable<TI
     /** 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.
@@ -493,7 +493,7 @@ interface AgentManifestOptions {
  *
  * 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
@@ -651,7 +651,9 @@ interface DefineTurnHookOptions {
  * is serialized into the sandbox `code` string and invoked with `ctx`/`host` at
  * run time.
  */
-declare function defineTurnHook(options: DefineTurnHookOptions): TurnHookContribution;
+declare function defineTurnHook(options: DefineTurnHookOptions): TurnHookContribution & {
+    code: string;
+};
 interface DefinePluginOptions {
     /** Activation events (default `["*"]` — driven by the enabled flag). */
     activationEvents?: string[];
@@ -659,8 +661,24 @@ 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;
     /**
@@ -690,7 +708,7 @@ interface DefinePluginOptions {
     version: string;
 }
 /**
- * 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`.
  */

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { R as Runnable, a as RunnableContext, T as ToolRunnable } from './index-DAxq7Y0R.js';
-export { A as Agent, b as AgentConfig, c as AgentEvent, d as AgentTool, C as ChatDelta, e as ChatMessage, f as ChatResult, D as DurableClient, E as Endpoint, g as EnginesClient, G as GatewayClient, h as GenerateResult, H as HttpPrimitiveTransportOptions, I as ImageClient, J as JsonSchemaProperty, M as MemoryClient, i as MemoryItem, j as ModelClient, k as ModelClientOptions, P as PRIMITIVE_BINDINGS, l as PrimitiveBinding, m as PrimitiveTransport, Q as QueryInput, n as QueryOptions, o as RagChunk, p as RagClient, q as RagRerankResult, r as RealtimeClient, s as RealtimeSubscription, t as RemoteToolRef, u as RyuPrimitives, S as SttClient, v as ToolOptions, w as ToolSchema, x as TtsClient, y as createAgent, z as createPrimitives, B as defineModel, F as defineTool, K as httpPrimitiveTransport, L as inlineToolRunnable, N as query, O as ryuTool } from './index-DAxq7Y0R.js';
-import { Requires, Surface, PluginManifest, RunnableMeta, CompanionSurface, CapabilityReq, TurnHookContribution } from './manifest.js';
+import { R as Runnable, a as RunnableContext, T as ToolRunnable } from './index-B6SkaAjJ.js';
+export { A as Agent, b as AgentConfig, c as AgentEvent, d as AgentTool, C as ChatDelta, e as ChatMessage, f as ChatResult, D as DurableClient, E as Endpoint, g as EnginesClient, G as GatewayClient, h as GenerateResult, H as HttpPrimitiveTransportOptions, I as ImageClient, J as JsonSchemaProperty, M as MemoryClient, i as MemoryItem, j as ModelClient, k as ModelClientOptions, P as PRIMITIVE_BINDINGS, l as PrimitiveBinding, m as PrimitiveTransport, Q as QueryInput, n as QueryOptions, o as RagChunk, p as RagClient, q as RagRerankResult, r as RealtimeClient, s as RealtimeSubscription, t as RemoteToolRef, u as RyuPrimitives, S as SttClient, v as ToolOptions, w as ToolSchema, x as TtsClient, y as createAgent, z as createPrimitives, B as defineModel, F as defineTool, K as httpPrimitiveTransport, L as inlineToolRunnable, N as query, O as ryuTool } from './index-B6SkaAjJ.js';
+import { Requires, Surface, PluginManifest, RunnableMeta, CompanionSurface, CapabilityReq, HookEventContribution, TurnHookContribution } from './manifest.js';
 export { AppDependency, AppDependencySchema, CapabilityReqSchema, CompanionSurfaceSchema, Contributes, PluginManifestSchema, RequiresSchema, RunnableKind, RunnableKindSchema, RunnableMetaSchema, SurfaceSchema, ToolAppConfig, ToolAppConfigSchema, WidgetContribution, WidgetContributionSchema, coreManifestJsonSchema, validateManifestStrict, validatePluginId } from './manifest.js';
 import 'zod';
 
@@ -9,7 +9,7 @@ import 'zod';
  *
  * 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()`):
  *
@@ -107,7 +107,7 @@ interface DefineAppOptions {
 /** Build a fully-qualified tool id from a server namespace and tool name. */
 declare 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`.
  *
@@ -132,7 +132,7 @@ declare function defineApp(options: DefineAppOptions): PluginManifest;
 
 /**
  * Ryu SDK typed builders — one builder per RunnableKind plus a PluginBuilder that
- * assembles a complete, validated `plugin.json` manifest.
+ * assembles a complete, validated `manifest.json` manifest.
  *
  * Each builder follows a fluent interface: construct, chain setter calls, then
  * call `.build()` to get a validated result. Invalid manifests throw a
@@ -174,7 +174,7 @@ declare const tool: () => ToolBuilder;
 /** Create a SkillBuilder. */
 declare const skill: () => SkillBuilder;
 /**
- * Fluent builder for a complete `plugin.json` Plugin manifest. Produces a
+ * Fluent builder for a complete `manifest.json` Plugin manifest. Produces a
  * validated `PluginManifest` on `.build()` or throws a descriptive `Error`
  * naming the first invalid field.
  *
@@ -252,7 +252,7 @@ declare class PluginBuilder {
     build(): PluginManifest;
 }
 /**
- * Fluent builder for a Ryu App — a `plugin.json` whose tools render interactive
+ * Fluent builder for a Ryu App — a `manifest.json` whose tools render interactive
  * widgets inline in chat. Delegates to {@link defineApp} on `.build()`, so it
  * derives the render-vs-companion split and validates through
  * `PluginManifestSchema` (throwing a descriptive `Error` on bad input) exactly
@@ -470,7 +470,7 @@ interface AgentRunnable<TInput = unknown, TOutput = unknown> extends Runnable<TI
     /** 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.
@@ -493,7 +493,7 @@ interface AgentManifestOptions {
  *
  * 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
@@ -651,7 +651,9 @@ interface DefineTurnHookOptions {
  * is serialized into the sandbox `code` string and invoked with `ctx`/`host` at
  * run time.
  */
-declare function defineTurnHook(options: DefineTurnHookOptions): TurnHookContribution;
+declare function defineTurnHook(options: DefineTurnHookOptions): TurnHookContribution & {
+    code: string;
+};
 interface DefinePluginOptions {
     /** Activation events (default `["*"]` — driven by the enabled flag). */
     activationEvents?: string[];
@@ -659,8 +661,24 @@ 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;
     /**
@@ -690,7 +708,7 @@ interface DefinePluginOptions {
     version: string;
 }
 /**
- * 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`.
  */

package/dist/index.js

@@ -12,7 +12,7 @@ import {
   coreManifestJsonSchema,
   validateManifestStrict,
   validatePluginId
-} from "./chunk-GXHL5CO7.js";
+} from "./chunk-SKVIJH5I.js";
 import {
   Agent,
   PRIMITIVE_BINDINGS,
@@ -21,7 +21,7 @@ import {
   httpPrimitiveTransport,
   query,
   ryuTool
-} from "./chunk-KPKMMGVC.js";
+} from "./chunk-MTUBUPIV.js";
 import {
   DEFAULT_GATEWAY_URL,
   ModelClient,
@@ -34,6 +34,14 @@ import {
 // src/runnable/app.ts
 var DEFAULT_APP_WIDGET_MIME = "text/html+skybridge";
 var DEFAULT_APP_DISPLAY_MODE = "inline";
+var WIDGET_RENDER_GRANT = "widget:render";
+function withWidgetRenderGrant(grants, widgets) {
+  const out = [...grants];
+  if (widgets.length > 0 && !out.includes(WIDGET_RENDER_GRANT)) {
+    out.push(WIDGET_RENDER_GRANT);
+  }
+  return out;
+}
 function appToolId(server, name) {
   return `${server}__${name}`;
 }
@@ -75,9 +83,21 @@ function defineApp(options) {
   }
   const 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
   };
   const raw = {
@@ -85,7 +105,21 @@ function defineApp(options) {
     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
@@ -107,7 +141,9 @@ function defineApp(options) {
     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;
 }
@@ -303,7 +339,7 @@ var PluginBuilder = class {
       const field = first?.path.join(".") ?? "unknown";
       const message = first?.message ?? "validation failed";
       throw new Error(
-        `plugin.json validation failed at '${field}': ${message}`
+        `manifest.json validation failed at '${field}': ${message}`
       );
     }
     return result.data;
@@ -676,12 +712,18 @@ function defineTurnHook(options) {
 function definePlugin(options) {
   const 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.
-    widgets: []
+    lsp_servers: options.lspServers ?? {},
+    // A turn-hook plugin contributes no app widgets, sidebar entries or dock
+    // panels; the fields are required on the resolved `Contributes` type (zod
+    // defaults applied), so set them explicitly.
+    widgets: [],
+    sidebar_sections: [],
+    sidebar_buttons: [],
+    dock_panels: []
   };
   const tools = options.tools ?? [];
   const runnables = tools.map((t) => inlineToolRunnable(t));