@ryuhq/sdk 0.0.5 → 0.1.2

package/dist/manifest.cjs

@@ -24,6 +24,8 @@ __export(manifest_exports, {
   CapabilityReqSchema: () => CapabilityReqSchema,
   CompanionSurfaceSchema: () => CompanionSurfaceSchema,
   ContributesSchema: () => ContributesSchema,
+  HookEventContributionSchema: () => HookEventContributionSchema,
+  PiExtensionContributionSchema: () => PiExtensionContributionSchema,
   PluginManifestSchema: () => PluginManifestSchema,
   RequiresSchema: () => RequiresSchema,
   RunnableKindSchema: () => RunnableKindSchema,
@@ -122,7 +124,47 @@ 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 PiExtensionContributionSchema = import_zod.z.object({
+  /** Stable id for this extension within the plugin (`[a-z0-9][a-z0-9._-]*`). */
+  id: import_zod.z.string().min(1),
+  /** Path to the source, relative to the plugin root: `pi-extensions/<name>.ts`. */
+  file: import_zod.z.string().min(1),
+  /** Optional one-liner describing what the extension adds to the agent. */
+  description: import_zod.z.string().optional()
 });
 var DEFAULT_WIDGET_MIME = "text/html+skybridge";
 var DEFAULT_WIDGET_DISPLAY_MODE = "inline";
@@ -160,6 +202,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([]),
@@ -167,7 +214,49 @@ 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([]),
+  /** 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: 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({}),
+  /** 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: import_zod.z.array(PiExtensionContributionSchema).default([])
 });
 var SetupStepSchema = import_zod.z.object({
   /** Card heading (e.g. the companion app name). */
@@ -348,6 +437,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). */
@@ -383,6 +491,8 @@ function coreManifestJsonSchema() {
   CapabilityReqSchema,
   CompanionSurfaceSchema,
   ContributesSchema,
+  HookEventContributionSchema,
+  PiExtensionContributionSchema,
   PluginManifestSchema,
   RequiresSchema,
   RunnableKindSchema,

package/dist/manifest.d.cts

@@ -67,16 +67,80 @@ declare const CompanionSurfaceSchema: z.ZodObject<{
 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.
  */
 declare const TurnHookContributionSchema: z.ZodObject<{
     id: z.ZodString;
     on: z.ZodDefault<z.ZodString>;
-    code: z.ZodString;
+    code: z.ZodOptional<z.ZodString>;
+    code_file: z.ZodOptional<z.ZodString>;
+    match: z.ZodOptional<z.ZodObject<{
+        flag: z.ZodOptional<z.ZodString>;
+        commands: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        stateful: z.ZodDefault<z.ZodBoolean>;
+        tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 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.
+ */
+declare const HookEventContributionSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    payload_example: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+type HookEventContribution = z.infer<typeof HookEventContributionSchema>;
+/**
+ * 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.
+ */
+declare const PiExtensionContributionSchema: z.ZodObject<{
+    id: z.ZodString;
+    file: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type PiExtensionContribution = z.infer<typeof PiExtensionContributionSchema>;
 /**
  * One app-widget contribution (Ryu Apps). Binds the render tool that produces the
  * widget to its `ui://widget/<slug>.html` template. Shape-identical to Core's
@@ -121,7 +185,20 @@ declare const ContributesSchema: z.ZodObject<{
     turn_hooks: z.ZodDefault<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         on: z.ZodDefault<z.ZodString>;
-        code: z.ZodString;
+        code: z.ZodOptional<z.ZodString>;
+        code_file: z.ZodOptional<z.ZodString>;
+        match: z.ZodOptional<z.ZodObject<{
+            flag: z.ZodOptional<z.ZodString>;
+            commands: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            stateful: z.ZodDefault<z.ZodBoolean>;
+            tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    hook_events: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        payload_example: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>>;
     composer_controls: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
     settings_tabs: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
@@ -133,6 +210,16 @@ declare const ContributesSchema: z.ZodObject<{
         mime: z.ZodDefault<z.ZodString>;
         default_display_mode: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>>;
+    sidebar_sections: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    sidebar_buttons: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    dock_panels: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    data_categories: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    lsp_servers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    pi_extensions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        file: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 type Contributes = z.infer<typeof ContributesSchema>;
 /**
@@ -218,7 +305,7 @@ declare const SurfaceSchema: z.ZodEnum<{
 }>;
 type Surface = z.infer<typeof SurfaceSchema>;
 /**
- * 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`):
@@ -255,7 +342,20 @@ declare const PluginManifestSchema: z.ZodObject<{
         turn_hooks: z.ZodDefault<z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             on: z.ZodDefault<z.ZodString>;
-            code: z.ZodString;
+            code: z.ZodOptional<z.ZodString>;
+            code_file: z.ZodOptional<z.ZodString>;
+            match: z.ZodOptional<z.ZodObject<{
+                flag: z.ZodOptional<z.ZodString>;
+                commands: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                stateful: z.ZodDefault<z.ZodBoolean>;
+                tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
+        hook_events: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            title: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            payload_example: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strip>>>;
         composer_controls: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
         settings_tabs: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
@@ -267,6 +367,16 @@ declare const PluginManifestSchema: z.ZodObject<{
             mime: z.ZodDefault<z.ZodString>;
             default_display_mode: z.ZodDefault<z.ZodString>;
         }, z.core.$strip>>>;
+        sidebar_sections: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        sidebar_buttons: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        dock_panels: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        data_categories: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        lsp_servers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        pi_extensions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            file: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
     }, z.core.$strip>>;
     requires: z.ZodOptional<z.ZodObject<{
         apps: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -317,6 +427,17 @@ declare const PluginManifestSchema: z.ZodObject<{
     category: z.ZodOptional<z.ZodString>;
     license: z.ZodOptional<z.ZodString>;
     iconUrl: z.ZodOptional<z.ZodString>;
+    icon: z.ZodOptional<z.ZodString>;
+    iconDither: z.ZodOptional<z.ZodObject<{
+        from: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        to: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        direction: z.ZodOptional<z.ZodEnum<{
+            up: "up";
+            down: "down";
+            left: "left";
+            right: "right";
+        }>>;
+    }, z.core.$strip>>;
     screenshots: z.ZodOptional<z.ZodArray<z.ZodString>>;
     privacyPolicyUrl: z.ZodOptional<z.ZodString>;
     termsOfServiceUrl: z.ZodOptional<z.ZodString>;
@@ -341,15 +462,15 @@ type PluginManifest = z.infer<typeof PluginManifestSchema>;
  */
 declare 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.
  */
 declare 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.
  */
 declare function coreManifestJsonSchema(): unknown;
 
-export { type AppDependency, AppDependencySchema, type CapabilityReq, CapabilityReqSchema, type CompanionSurface, CompanionSurfaceSchema, type Contributes, ContributesSchema, type PluginManifest, PluginManifestSchema, type Requires, RequiresSchema, type RunnableKind, RunnableKindSchema, type RunnableMeta, RunnableMetaSchema, type SetupStep, SetupStepSchema, type Surface, SurfaceSchema, type ToolAppConfig, ToolAppConfigSchema, type TurnHookContribution, TurnHookContributionSchema, type WidgetContribution, WidgetContributionSchema, coreManifestJsonSchema, labelImpersonatesSystemChrome, validateManifestStrict, validatePluginId };
+export { type AppDependency, AppDependencySchema, type CapabilityReq, CapabilityReqSchema, type CompanionSurface, CompanionSurfaceSchema, type Contributes, ContributesSchema, type HookEventContribution, HookEventContributionSchema, type PiExtensionContribution, PiExtensionContributionSchema, type PluginManifest, PluginManifestSchema, type Requires, RequiresSchema, type RunnableKind, RunnableKindSchema, type RunnableMeta, RunnableMetaSchema, type SetupStep, SetupStepSchema, type Surface, SurfaceSchema, type ToolAppConfig, ToolAppConfigSchema, type TurnHookContribution, TurnHookContributionSchema, type WidgetContribution, WidgetContributionSchema, coreManifestJsonSchema, labelImpersonatesSystemChrome, validateManifestStrict, validatePluginId };

package/dist/manifest.d.ts

@@ -67,16 +67,80 @@ declare const CompanionSurfaceSchema: z.ZodObject<{
 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.
  */
 declare const TurnHookContributionSchema: z.ZodObject<{
     id: z.ZodString;
     on: z.ZodDefault<z.ZodString>;
-    code: z.ZodString;
+    code: z.ZodOptional<z.ZodString>;
+    code_file: z.ZodOptional<z.ZodString>;
+    match: z.ZodOptional<z.ZodObject<{
+        flag: z.ZodOptional<z.ZodString>;
+        commands: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        stateful: z.ZodDefault<z.ZodBoolean>;
+        tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 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.
+ */
+declare const HookEventContributionSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    payload_example: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+type HookEventContribution = z.infer<typeof HookEventContributionSchema>;
+/**
+ * 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.
+ */
+declare const PiExtensionContributionSchema: z.ZodObject<{
+    id: z.ZodString;
+    file: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type PiExtensionContribution = z.infer<typeof PiExtensionContributionSchema>;
 /**
  * One app-widget contribution (Ryu Apps). Binds the render tool that produces the
  * widget to its `ui://widget/<slug>.html` template. Shape-identical to Core's
@@ -121,7 +185,20 @@ declare const ContributesSchema: z.ZodObject<{
     turn_hooks: z.ZodDefault<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         on: z.ZodDefault<z.ZodString>;
-        code: z.ZodString;
+        code: z.ZodOptional<z.ZodString>;
+        code_file: z.ZodOptional<z.ZodString>;
+        match: z.ZodOptional<z.ZodObject<{
+            flag: z.ZodOptional<z.ZodString>;
+            commands: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            stateful: z.ZodDefault<z.ZodBoolean>;
+            tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    hook_events: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        payload_example: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>>;
     composer_controls: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
     settings_tabs: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
@@ -133,6 +210,16 @@ declare const ContributesSchema: z.ZodObject<{
         mime: z.ZodDefault<z.ZodString>;
         default_display_mode: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>>;
+    sidebar_sections: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    sidebar_buttons: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    dock_panels: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    data_categories: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    lsp_servers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    pi_extensions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        file: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 type Contributes = z.infer<typeof ContributesSchema>;
 /**
@@ -218,7 +305,7 @@ declare const SurfaceSchema: z.ZodEnum<{
 }>;
 type Surface = z.infer<typeof SurfaceSchema>;
 /**
- * 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`):
@@ -255,7 +342,20 @@ declare const PluginManifestSchema: z.ZodObject<{
         turn_hooks: z.ZodDefault<z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             on: z.ZodDefault<z.ZodString>;
-            code: z.ZodString;
+            code: z.ZodOptional<z.ZodString>;
+            code_file: z.ZodOptional<z.ZodString>;
+            match: z.ZodOptional<z.ZodObject<{
+                flag: z.ZodOptional<z.ZodString>;
+                commands: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                stateful: z.ZodDefault<z.ZodBoolean>;
+                tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
+        hook_events: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            title: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            payload_example: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strip>>>;
         composer_controls: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
         settings_tabs: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
@@ -267,6 +367,16 @@ declare const PluginManifestSchema: z.ZodObject<{
             mime: z.ZodDefault<z.ZodString>;
             default_display_mode: z.ZodDefault<z.ZodString>;
         }, z.core.$strip>>>;
+        sidebar_sections: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        sidebar_buttons: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        dock_panels: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        data_categories: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        lsp_servers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        pi_extensions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            file: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
     }, z.core.$strip>>;
     requires: z.ZodOptional<z.ZodObject<{
         apps: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -317,6 +427,17 @@ declare const PluginManifestSchema: z.ZodObject<{
     category: z.ZodOptional<z.ZodString>;
     license: z.ZodOptional<z.ZodString>;
     iconUrl: z.ZodOptional<z.ZodString>;
+    icon: z.ZodOptional<z.ZodString>;
+    iconDither: z.ZodOptional<z.ZodObject<{
+        from: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        to: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        direction: z.ZodOptional<z.ZodEnum<{
+            up: "up";
+            down: "down";
+            left: "left";
+            right: "right";
+        }>>;
+    }, z.core.$strip>>;
     screenshots: z.ZodOptional<z.ZodArray<z.ZodString>>;
     privacyPolicyUrl: z.ZodOptional<z.ZodString>;
     termsOfServiceUrl: z.ZodOptional<z.ZodString>;
@@ -341,15 +462,15 @@ type PluginManifest = z.infer<typeof PluginManifestSchema>;
  */
 declare 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.
  */
 declare 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.
  */
 declare function coreManifestJsonSchema(): unknown;
 
-export { type AppDependency, AppDependencySchema, type CapabilityReq, CapabilityReqSchema, type CompanionSurface, CompanionSurfaceSchema, type Contributes, ContributesSchema, type PluginManifest, PluginManifestSchema, type Requires, RequiresSchema, type RunnableKind, RunnableKindSchema, type RunnableMeta, RunnableMetaSchema, type SetupStep, SetupStepSchema, type Surface, SurfaceSchema, type ToolAppConfig, ToolAppConfigSchema, type TurnHookContribution, TurnHookContributionSchema, type WidgetContribution, WidgetContributionSchema, coreManifestJsonSchema, labelImpersonatesSystemChrome, validateManifestStrict, validatePluginId };
+export { type AppDependency, AppDependencySchema, type CapabilityReq, CapabilityReqSchema, type CompanionSurface, CompanionSurfaceSchema, type Contributes, ContributesSchema, type HookEventContribution, HookEventContributionSchema, type PiExtensionContribution, PiExtensionContributionSchema, type PluginManifest, PluginManifestSchema, type Requires, RequiresSchema, type RunnableKind, RunnableKindSchema, type RunnableMeta, RunnableMetaSchema, type SetupStep, SetupStepSchema, type Surface, SurfaceSchema, type ToolAppConfig, ToolAppConfigSchema, type TurnHookContribution, TurnHookContributionSchema, type WidgetContribution, WidgetContributionSchema, coreManifestJsonSchema, labelImpersonatesSystemChrome, validateManifestStrict, validatePluginId };

package/dist/manifest.js

@@ -3,6 +3,8 @@ import {
   CapabilityReqSchema,
   CompanionSurfaceSchema,
   ContributesSchema,
+  HookEventContributionSchema,
+  PiExtensionContributionSchema,
   PluginManifestSchema,
   RequiresSchema,
   RunnableKindSchema,
@@ -16,12 +18,14 @@ import {
   labelImpersonatesSystemChrome,
   validateManifestStrict,
   validatePluginId
-} from "./chunk-GXHL5CO7.js";
+} from "./chunk-XTUK5I6I.js";
 export {
   AppDependencySchema,
   CapabilityReqSchema,
   CompanionSurfaceSchema,
   ContributesSchema,
+  HookEventContributionSchema,
+  PiExtensionContributionSchema,
   PluginManifestSchema,
   RequiresSchema,
   RunnableKindSchema,

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@ryuhq/sdk",
-  "version": "0.0.5",
+  "version": "0.1.2",
   "type": "module",
-  "description": "Ryu developer SDK: typed builders and CLI for authoring plugin.json Plugin bundles",
+  "description": "Ryu developer SDK: typed builders and CLI for authoring manifest.json Plugin bundles",
   "main": "./dist/index.cjs",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -44,11 +44,11 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@ryuhq/sdk-native": "0.1.0",
+    "@ryuhq/sdk-native": "workspace:*",
     "zod": "^4.1.13"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.4",
+    "@types/bun": "catalog:",
     "json-schema-to-typescript": "^15.0.4",
     "tsup": "^8.5.1",
     "typescript": "^5"

package/src/builder.ts

@@ -1,6 +1,6 @@
 /**
  * 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
@@ -125,7 +125,7 @@ export const skill = () => new SkillBuilder();
 // ── PluginBuilder ─────────────────────────────────────────────────────────────
 
 /**
- * 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.
  *
@@ -279,7 +279,7 @@ export class PluginBuilder {
 			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;
@@ -289,7 +289,7 @@ export class PluginBuilder {
 // ── AppBuilder (Ryu Apps) ─────────────────────────────────────────────────────
 
 /**
- * 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