@ryuhq/sdk 0.0.17 → 0.1.3

package/dist/{chunk-SKVIJH5I.js → chunk-XTUK5I6I.js}

@@ -110,6 +110,14 @@ var HookEventContributionSchema = z.object({
   /** Example of the `ctx.event` payload. Documentation, not a validated schema. */
   payload_example: z.record(z.string(), z.unknown()).optional()
 });
+var 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()
+});
 var DEFAULT_WIDGET_MIME = "text/html+skybridge";
 var DEFAULT_WIDGET_DISPLAY_MODE = "inline";
 var WidgetContributionSchema = z.object({
@@ -171,6 +179,14 @@ var ContributesSchema = z.object({
    *  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
@@ -183,7 +199,16 @@ var ContributesSchema = z.object({
    *  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({})
+  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([])
 });
 var SetupStepSchema = z.object({
   /** Card heading (e.g. the companion app name). */
@@ -420,6 +445,7 @@ export {
   CompanionSurfaceSchema,
   TurnHookContributionSchema,
   HookEventContributionSchema,
+  PiExtensionContributionSchema,
   WidgetContributionSchema,
   ToolAppConfigSchema,
   ContributesSchema,

package/dist/cli.cjs

@@ -396,6 +396,14 @@ var HookEventContributionSchema = import_zod.z.object({
   /** 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";
 var WidgetContributionSchema = import_zod.z.object({
@@ -457,6 +465,14 @@ var ContributesSchema = import_zod.z.object({
    *  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
@@ -469,7 +485,16 @@ var ContributesSchema = import_zod.z.object({
    *  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({})
+  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). */

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import {
   PluginManifestSchema
-} from "./chunk-SKVIJH5I.js";
+} from "./chunk-XTUK5I6I.js";
 import {
   ModelClient,
   resolveGatewayUrl

package/dist/index.cjs

@@ -940,6 +940,14 @@ var HookEventContributionSchema = import_zod.z.object({
   /** 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";
 var WidgetContributionSchema = import_zod.z.object({
@@ -1001,6 +1009,14 @@ var ContributesSchema = import_zod.z.object({
    *  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
@@ -1013,7 +1029,16 @@ var ContributesSchema = import_zod.z.object({
    *  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({})
+  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). */
@@ -1310,6 +1335,10 @@ function defineApp(options) {
     // takes no `contributes` passthrough. An app that wants to declare language
     // servers writes them in a hand-authored `manifest.json`.
     lsp_servers: {},
+    // Same reason again: a danger-zone category and a Pi extension are both
+    // hand-authored declarations, not something derivable from runnables.
+    data_categories: [],
+    pi_extensions: [],
     widgets
   };
   const raw = {
@@ -1929,13 +1958,16 @@ function definePlugin(options) {
     settings_tabs: options.settingsTabs ?? [],
     slash_commands: options.slashCommands ?? [],
     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.
+    // A turn-hook plugin contributes no app widgets, sidebar entries, dock
+    // panels, danger-zone categories or Pi extensions; the fields are required
+    // on the resolved `Contributes` type (zod defaults applied), so set them
+    // explicitly.
     widgets: [],
     sidebar_sections: [],
     sidebar_buttons: [],
-    dock_panels: []
+    dock_panels: [],
+    data_categories: [],
+    pi_extensions: []
   };
   const tools = options.tools ?? [];
   const runnables = tools.map((t) => inlineToolRunnable(t));

package/dist/index.js

@@ -12,7 +12,7 @@ import {
   coreManifestJsonSchema,
   validateManifestStrict,
   validatePluginId
-} from "./chunk-SKVIJH5I.js";
+} from "./chunk-XTUK5I6I.js";
 import {
   Agent,
   PRIMITIVE_BINDINGS,
@@ -98,6 +98,10 @@ function defineApp(options) {
     // takes no `contributes` passthrough. An app that wants to declare language
     // servers writes them in a hand-authored `manifest.json`.
     lsp_servers: {},
+    // Same reason again: a danger-zone category and a Pi extension are both
+    // hand-authored declarations, not something derivable from runnables.
+    data_categories: [],
+    pi_extensions: [],
     widgets
   };
   const raw = {
@@ -717,13 +721,16 @@ function definePlugin(options) {
     settings_tabs: options.settingsTabs ?? [],
     slash_commands: options.slashCommands ?? [],
     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.
+    // A turn-hook plugin contributes no app widgets, sidebar entries, dock
+    // panels, danger-zone categories or Pi extensions; the fields are required
+    // on the resolved `Contributes` type (zod defaults applied), so set them
+    // explicitly.
     widgets: [],
     sidebar_sections: [],
     sidebar_buttons: [],
-    dock_panels: []
+    dock_panels: [],
+    data_categories: [],
+    pi_extensions: []
   };
   const tools = options.tools ?? [];
   const runnables = tools.map((t) => inlineToolRunnable(t));

package/dist/manifest.cjs

@@ -25,6 +25,7 @@ __export(manifest_exports, {
   CompanionSurfaceSchema: () => CompanionSurfaceSchema,
   ContributesSchema: () => ContributesSchema,
   HookEventContributionSchema: () => HookEventContributionSchema,
+  PiExtensionContributionSchema: () => PiExtensionContributionSchema,
   PluginManifestSchema: () => PluginManifestSchema,
   RequiresSchema: () => RequiresSchema,
   RunnableKindSchema: () => RunnableKindSchema,
@@ -157,6 +158,14 @@ var HookEventContributionSchema = import_zod.z.object({
   /** 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";
 var WidgetContributionSchema = import_zod.z.object({
@@ -218,6 +227,14 @@ var ContributesSchema = import_zod.z.object({
    *  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
@@ -230,7 +247,16 @@ var ContributesSchema = import_zod.z.object({
    *  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({})
+  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). */
@@ -466,6 +492,7 @@ function coreManifestJsonSchema() {
   CompanionSurfaceSchema,
   ContributesSchema,
   HookEventContributionSchema,
+  PiExtensionContributionSchema,
   PluginManifestSchema,
   RequiresSchema,
   RunnableKindSchema,

package/dist/manifest.d.cts

@@ -115,6 +115,32 @@ declare const HookEventContributionSchema: z.ZodObject<{
     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
@@ -187,7 +213,13 @@ declare const ContributesSchema: z.ZodObject<{
     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>;
 /**
@@ -338,7 +370,13 @@ declare const PluginManifestSchema: z.ZodObject<{
         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<{
@@ -365,8 +403,8 @@ declare const PluginManifestSchema: z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         rule: z.ZodOptional<z.ZodObject<{
             type: z.ZodEnum<{
-                flat: "flat";
                 percent: "percent";
+                flat: "flat";
             }>;
             value: z.ZodNumber;
             recurring: z.ZodDefault<z.ZodBoolean>;
@@ -435,4 +473,4 @@ declare function validateManifestStrict(manifestJson: string): string;
  */
 declare function coreManifestJsonSchema(): unknown;
 
-export { type AppDependency, AppDependencySchema, type CapabilityReq, CapabilityReqSchema, type CompanionSurface, CompanionSurfaceSchema, type Contributes, ContributesSchema, type HookEventContribution, HookEventContributionSchema, 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

@@ -115,6 +115,32 @@ declare const HookEventContributionSchema: z.ZodObject<{
     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
@@ -187,7 +213,13 @@ declare const ContributesSchema: z.ZodObject<{
     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>;
 /**
@@ -338,7 +370,13 @@ declare const PluginManifestSchema: z.ZodObject<{
         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<{
@@ -365,8 +403,8 @@ declare const PluginManifestSchema: z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         rule: z.ZodOptional<z.ZodObject<{
             type: z.ZodEnum<{
-                flat: "flat";
                 percent: "percent";
+                flat: "flat";
             }>;
             value: z.ZodNumber;
             recurring: z.ZodDefault<z.ZodBoolean>;
@@ -435,4 +473,4 @@ declare function validateManifestStrict(manifestJson: string): string;
  */
 declare function coreManifestJsonSchema(): unknown;
 
-export { type AppDependency, AppDependencySchema, type CapabilityReq, CapabilityReqSchema, type CompanionSurface, CompanionSurfaceSchema, type Contributes, ContributesSchema, type HookEventContribution, HookEventContributionSchema, 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

@@ -4,6 +4,7 @@ import {
   CompanionSurfaceSchema,
   ContributesSchema,
   HookEventContributionSchema,
+  PiExtensionContributionSchema,
   PluginManifestSchema,
   RequiresSchema,
   RunnableKindSchema,
@@ -17,13 +18,14 @@ import {
   labelImpersonatesSystemChrome,
   validateManifestStrict,
   validatePluginId
-} from "./chunk-SKVIJH5I.js";
+} from "./chunk-XTUK5I6I.js";
 export {
   AppDependencySchema,
   CapabilityReqSchema,
   CompanionSurfaceSchema,
   ContributesSchema,
   HookEventContributionSchema,
+  PiExtensionContributionSchema,
   PluginManifestSchema,
   RequiresSchema,
   RunnableKindSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuhq/sdk",
-  "version": "0.0.17",
+  "version": "0.1.3",
   "type": "module",
   "description": "Ryu developer SDK: typed builders and CLI for authoring manifest.json Plugin bundles",
   "main": "./dist/index.cjs",
@@ -44,7 +44,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@ryuhq/sdk-native": "0.1.0",
+    "@ryuhq/sdk-native": "0.1.3",
     "zod": "^4.1.13"
   },
   "devDependencies": {

package/src/generated/plugin-manifest.ts

@@ -49,7 +49,7 @@ export type ProviderTarget = "local-machine" | "remote-desktop";
  * An **empty/absent** `targets` list means the plugin runs on *every* surface —
  * that is the backward-compatible default and MUST NOT be read as "hidden".
  */
-export type Surface = "gateway" | "core" | "desktop" | "island" | "mobile" | "extension" | "web" | "cli";
+export type Surface = "gateway" | "core" | "desktop" | "island" | "mobile" | "extension" | "web" | "cli" | "unknown";
 
 /**
  * An installable Ryu App manifest (`manifest.json`).
@@ -226,8 +226,48 @@ export interface PluginManifest {
 	 * Permission grants this app declares it needs (e.g. `"mcp:web_search"`).
 	 * These are *declarations only* at this layer — no enforcement happens here;
 	 * the Gateway owns grant enforcement.
+	 *
+	 * This is the **app→host** lane and has nothing to do with
+	 * [`permission_levels`], the **app→human** lane. See that field's doc comment
+	 * for the three-way table; conflating the two is the likeliest future bug here.
+	 *
+	 * [`permission_levels`]: PluginManifest::permission_levels
 	 */
 	permission_grants?: string[];
+	/**
+	 * **The user-facing permission vocabulary this app declares** — the set of
+	 * levels ("read", "edit", …) an administrator can later grant to a person or a
+	 * team *inside* this app. Absent/empty = the app declares no vocabulary, which
+	 * is every manifest predating this field.
+	 *
+	 * Spaces declaring `read` and `edit` is what makes "team X may edit in Spaces"
+	 * expressible at all: a grant has to name a level, and a UI has to render a
+	 * list of them. Without a declaration there is nothing to bind to.
+	 *
+	 * # Three lanes, one prefix — do not conflate them
+	 *
+	 * | field | direction | who decides | what it means |
+	 * |---|---|---|---|
+	 * | [`permission_grants`] | app → host | the **Gateway**, at install/enable | which host capabilities the app may *ask* for |
+	 * | [`permissions`] ([`PermissionSet`]) | app → sandbox | **Core**, at spawn/exec | what the app's code may *touch* (FS paths, hosts, subprocess) |
+	 * | `permission_levels` | app → human | an **admin**, per person/team | what a *person* may do inside the app |
+	 *
+	 * Only the first two are enforced today. This field is **declaration only**:
+	 * nothing consumes it yet, so declaring `edit` gates nothing by itself. It is
+	 * the vocabulary the ACL layer will bind grants against.
+	 *
+	 * # Ordering and implication
+	 *
+	 * Declaration order is display order — render the list as written. Strength is
+	 * expressed with [`PermissionLevel::implies`] rather than a separate rank, so
+	 * there is exactly one ordering and it cannot contradict itself: `edit` implying
+	 * `read` means granting `edit` already conveys `read`, and no admin has to grant
+	 * the same person both.
+	 *
+	 * [`permission_grants`]: PluginManifest::permission_grants
+	 * [`permissions`]: PluginManifest::permissions
+	 */
+	permission_levels?: PermissionLevel[];
 	/**
 	 * **Unified, deny-by-default runtime permission set** — the single typed
 	 * grammar (`{fs, child_process, network, tool}`) Core lowers to every sandbox
@@ -236,17 +276,21 @@ export interface PluginManifest {
 	 * predating this field), so an app that declares nothing keeps today's exact
 	 * zero-permission sandbox posture.
 	 *
-	 * # Relationship to [`permission_grants`]
+	 * # Relationship to [`permission_grants`] and [`permission_levels`]
 	 *
-	 * These are **two distinct lanes** that must not be conflated:
+	 * These are **three distinct lanes** that must not be conflated:
 	 * - [`permission_grants`] are opaque strings the **Gateway** approves at
 	 *   install/enable time — the *approval* lane (who is allowed to ask).
 	 * - `permissions` is the typed set **Core** lowers into the actual sandbox at
 	 *   spawn/exec time — the *runtime-enforcement* lane (what the code can touch).
+	 * - [`permission_levels`] is the app's *user-facing* vocabulary an admin grants
+	 *   to a person or team — it never reaches the sandbox at all.
 	 *
 	 * A grant says "this app may use the filesystem capability"; `permissions.fs`
 	 * says "…and here are the exact read/write paths the sandbox is opened with."
 	 *
+	 * [`permission_levels`]: PluginManifest::permission_levels
+	 *
 	 * # Altitude (manifest-level, per-runnable override is a followup)
 	 *
 	 * Declared at the manifest root because **both** current enforcement sites
@@ -487,6 +531,40 @@ export interface Contributes {
 	 * older shells" instead of breaking the composer.
 	 */
 	composer_controls?: unknown[];
+	/**
+	 * **Deletable data categories** the app owns — one "Delete all X" row in
+	 * Settings → Danger Zone (see [`DataCategoryContribution`]).
+	 *
+	 * The danger zone used to be two hardcoded lists that had to be edited
+	 * together: a `DataCategory` enum in Core and a `CATEGORIES` array carrying the
+	 * user-facing copy in the closed desktop source. Monitors and Meetings are
+	 * app-owned data, so both lists named apps — which meant a node where Monitors
+	 * was never enabled still offered to delete monitors, and the count was always
+	 * 0. Declaring the category here makes the owning app the single source of both
+	 * its existence and its wording, and makes the row appear and disappear with
+	 * the app instead of with a client-side feature-detect.
+	 *
+	 * # Core-interpreted, so a typed struct — and NOT on the contributions endpoint
+	 *
+	 * Core has to resolve the id to something that can actually count and delete
+	 * the rows, so per this type's own doc comment this gets a typed struct rather
+	 * than opaque JSON, and it is gathered at its consumption site
+	 * (`GET /api/data/counts`, which serves each category's descriptor next to its
+	 * live count) rather than at `GET /api/plugins/contributions` — the same
+	 * disposition as [`Contributes::tool_filters`] and [`Contributes::lsp_servers`].
+	 *
+	 * # Declaration, not implementation
+	 *
+	 * A declared category is served only when Core knows how to clear it; an id
+	 * Core does not implement is skipped with a warn rather than being offered as a
+	 * button that 400s. That split is deliberate and not a stepping stone to a
+	 * generic HTTP truncate: clearing monitors has to tear down each monitor's
+	 * backing scheduler job, and clearing meetings has to broadcast on the meetings
+	 * SSE stream, so a blind `DELETE /monitors` would leave jobs ticking forever.
+	 * The manifest owns *whether the row exists and what it says*; Core owns *what
+	 * deleting actually entails*.
+	 */
+	data_categories?: DataCategoryContribution[];
 	/**
 	 * App-registered **workspace dock panels** — a tab in the desktop's bottom or
 	 * right dock (Terminal / Code Review / Browser / Simulator live there today).
@@ -582,6 +660,45 @@ export interface Contributes {
 	lsp_servers?: {
 		[k: string]: LspServerContribution;
 	};
+	/**
+	 * **Pi extensions** the plugin ships — TypeScript files the managed `ryu` (Pi)
+	 * agent loads at process start:
+	 *
+	 * ```json
+	 * "pi_extensions": [
+	 *   { "id": "shell", "file": "pi-extensions/ryu-shell.ts",
+	 *     "description": "background bash for the managed Pi agent" }
+	 * ]
+	 * ```
+	 *
+	 * Pi ships none of plan mode, sub-agents, permission prompts or background bash
+	 * and says so deliberately in its own docs — "you can build or install those
+	 * workflows as extensions or packages". This surface is that seam: the
+	 * capabilities Core used to hardcode into the spawn path become plugins the user
+	 * can enable and disable, and a third party can ship one at all.
+	 *
+	 * # This is UNSANDBOXED code, and the tier gate is not optional
+	 *
+	 * A [`Contributes::turn_hooks`] body runs in the deny-by-default Deno sandbox
+	 * behind capability-gated `host.*` calls. A file named here runs **inside the Pi
+	 * process** with full host privilege: the first-party ones spawn children and
+	 * POST to Core. That is the same arbitrary-code-execution class as
+	 * [`PluginManifest::mcp_servers`], so Core gates it identically — Core tier is
+	 * auto-allowed, Community tier needs an operator-allowlisted grant, and the gate
+	 * sits at the materializer, because writing the file is what makes it run.
+	 *
+	 * # Core-interpreted, so a typed struct — and NOT on the contributions endpoint
+	 *
+	 * Core resolves each `file` and projects it into the managed Pi's config dir, so
+	 * per this type's own doc comment it gets a typed struct and is gathered at its
+	 * consumption site (`pi_config::app_extensions`) rather than served from
+	 * `GET /api/plugins/contributions` — the same disposition as
+	 * [`Contributes::lsp_servers`].
+	 *
+	 * The `file` is deliberately NOT hydrated into an inline string the way a
+	 * `code_file` is; see [`PluginManifest::pi_extension_refs`] for why.
+	 */
+	pi_extensions?: PiExtensionContribution[];
 	/**
 	 * Gateway policies the plugin contributes (referenced by runnable id).
 	 */
@@ -699,6 +816,42 @@ export interface ContributionId {
 	 */
 	title?: string | null;
 }
+/**
+ * One **deletable data category** an app owns (see [`Contributes::data_categories`]).
+ *
+ * Everything the Danger Zone needs to draw and arm one destructive row, so the copy
+ * lives with the app whose data it describes rather than in the desktop's source.
+ */
+export interface DataCategoryContribution {
+	/**
+	 * The word the user must type to arm the delete. Absent = the [`noun`], which is
+	 * the right default often enough that requiring it would just be ceremony.
+	 * Matched case-insensitively by the client.
+	 *
+	 * [`noun`]: DataCategoryContribution::noun
+	 */
+	confirm_word?: string | null;
+	/**
+	 * Exactly what disappears, shown in the confirm dialog. Required, and required
+	 * to be specific: this is the last thing the user reads before an irreversible
+	 * delete, and "this cannot be undone" tells them nothing they did not know.
+	 */
+	detail: string;
+	/**
+	 * Stable id — this is the `category` a `POST /api/data/clear` names, so it is
+	 * the app's half of the delete contract and renaming it breaks the button.
+	 */
+	id: string;
+	/**
+	 * Plural noun for the live count line ("42 monitors" / "No monitors") and the
+	 * "N deleted" toast. Lower-case: it is used mid-sentence.
+	 */
+	noun: string;
+	/**
+	 * The destructive button label and confirm-dialog title ("Delete all monitors").
+	 */
+	title: string;
+}
 /**
  * One app-registered **workspace dock panel** — a tab in the desktop's bottom or
  * right dock (see [`Contributes::dock_panels`]).
@@ -955,6 +1108,31 @@ export interface LspServerContribution {
 	 */
 	workspaceFolder?: string | null;
 }
+/**
+ * One **Pi extension** a plugin ships (a [`Contributes::pi_extensions`] row).
+ *
+ * Carries a path, never a body: unlike [`TurnHookContribution`] there is no inline
+ * `code` twin, because nothing downstream reads the source as a string.
+ */
+export interface PiExtensionContribution {
+	/**
+	 * Optional human-facing one-liner (what the extension adds to the agent).
+	 */
+	description?: string | null;
+	/**
+	 * Path to the TypeScript source, relative to the plugin root — exactly
+	 * `pi-extensions/<name>.ts`. See [`validate_pi_extension_path`].
+	 */
+	file: string;
+	/**
+	 * Stable id for this extension within the plugin (`[a-z0-9][a-z0-9._-]*`).
+	 *
+	 * Part of the materialized file name, so it is what makes one plugin's
+	 * extensions distinguishable from another's on disk — and why it is validated
+	 * with the same alphabet as an event name rather than left free-form.
+	 */
+	id: string;
+}
 /**
  * One **settings tab** a plugin contributes (see [`Contributes::settings_tabs`]).
  *
@@ -1369,6 +1547,51 @@ export interface McpServerDecl {
 		[k: string]: string;
 	};
 }
+/**
+ * One entry in an app's **user-facing permission vocabulary** — a level an admin
+ * can grant to a person or a team inside that app (see
+ * [`PluginManifest::permission_levels`], which also explains why this is a
+ * different axis from `permission_grants` and `permissions`).
+ *
+ * Deliberately self-describing: an admin UI renders the grant picker from `label`
+ * + `description` alone, so a level whose meaning lives only in the app's own docs
+ * cannot exist.
+ */
+export interface PermissionLevel {
+	/**
+	 * One sentence telling an admin what granting this level actually allows.
+	 * Required for the same reason as [`label`]: the admin deciding is usually
+	 * not the person who wrote the app.
+	 *
+	 * [`label`]: PermissionLevel::label
+	 */
+	description: string;
+	/**
+	 * Stable machine id (e.g. `"read"`). Lower-case ASCII alphanumerics plus
+	 * `-`, `_` and `.`, at most [`MAX_PLUGIN_ID_LEN`] bytes, and unique within the
+	 * manifest.
+	 *
+	 * The alphabet is narrower than a plugin id's on purpose: these ids end up in
+	 * API paths and in persisted grant strings, so `Read` and `read` must not be
+	 * two levels that look identical to a human granting them.
+	 */
+	id: string;
+	/**
+	 * Ids of other levels in **this same manifest** that this level subsumes.
+	 *
+	 * This is the whole ordering mechanism — there is no separate rank, so the
+	 * order can never contradict itself. `edit` implying `read` means a person
+	 * granted `edit` already holds `read`; granting both is redundant, never
+	 * required. Resolved transitively by
+	 * [`resolve_implied_permission_levels`].
+	 */
+	implies?: string[];
+	/**
+	 * Short human label for the grant picker (e.g. `"Can edit"`). Required —
+	 * an unlabelled level is unrenderable.
+	 */
+	label: string;
+}
 /**
  * The single, typed, **deny-by-default** permission set a plugin manifest
  * declares, lowered by Core to every sandbox backend.
@@ -2109,6 +2332,44 @@ export interface RouteSpec {
 	 * sidecar's REST routes (`/inboxes/:id`) can be declared faithfully.
 	 */
 	path: string;
+	/**
+	 * The [`PluginManifest::permission_levels`] id a caller must hold to reach this
+	 * route. Absent (the default) = ungated: Core forwards exactly as it always did,
+	 * so annotating is opt-in and no existing app changes behaviour.
+	 *
+	 * This is the only place a route→permission mapping can honestly live: Core
+	 * cannot know that an app's `/tabs/:id/close` is destructive, and the sidecar
+	 * cannot enforce it (it never sees the caller's identity, only Core's minted
+	 * hop token). Declaring it HERE — on the same [`RouteSpec`] the proxy already
+	 * matches to decide forward-or-404 — means the gate and the forward can never
+	 * disagree about which route is in play.
+	 *
+	 * Must name a level THIS manifest declares (enforced by
+	 * [`crate::manifest::validate_route_permissions`]); an app cannot gate its
+	 * routes on another app's vocabulary or on a level nobody can see to grant.
+	 *
+	 * Never annotate an [`RouteAuth::Public`] route: a public route exists for a
+	 * caller who holds no identity at all (an external webhook), and on an
+	 * org-bound node an anonymous caller is refused outright — the annotation would
+	 * turn a working inbound webhook into a permanent 403.
+	 *
+	 * [`PluginManifest::permission_levels`]: crate::manifest::PluginManifest::permission_levels
+	 */
+	permission?: string | null;
+	/**
+	 * Which `:param` of [`path`] names the resource [`permission`] is checked
+	 * against, so one route can be granted per-object (`"id"` on `/tabs/:id` gates
+	 * each tab separately). Absent = the whole app is the resource, which is what an
+	 * admin grants when the route identifies nothing (a `/settings` POST).
+	 *
+	 * Only meaningful alongside [`permission`], and the named param must actually
+	 * appear in [`path`] — both enforced at validation, because a typo here would
+	 * silently widen a rule the author wrote as per-object into a per-app one.
+	 *
+	 * [`path`]: RouteSpec::path
+	 * [`permission`]: RouteSpec::permission
+	 */
+	resource_param?: string | null;
 }
 /**
  * A single downloaded executable: fetched (checksum-verified) into the
@@ -2209,7 +2470,7 @@ export interface SurfaceEntry {
 	/**
 	 * How much of the plugin this surface supports.
 	 */
-	support?: "full" | "limited" | "list" | "commands" | "none";
+	support?: "full" | "limited" | "list" | "commands" | "none" | "unknown";
 	/**
 	 * Optional surface-specific UI descriptor (bundle id, mount point, …),
 	 * interpreted by the surface's app host. Opaque to the contract.

package/src/manifest.ts

@@ -239,6 +239,41 @@ export const HookEventContributionSchema = z.object({
 
 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) ─────────────────────────────────────────────
 
 /** Default widget MIME dialect. Mirrors Core `default_widget_mime`. */
@@ -335,6 +370,14 @@ export const ContributesSchema = z.object({
 	 *  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
@@ -350,6 +393,15 @@ export const ContributesSchema = z.object({
 	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>;

package/src/runnable/app.ts

@@ -228,6 +228,10 @@ export function defineApp(options: DefineAppOptions): PluginManifest {
 		// takes no `contributes` passthrough. An app that wants to declare language
 		// servers writes them in a hand-authored `manifest.json`.
 		lsp_servers: {},
+		// Same reason again: a danger-zone category and a Pi extension are both
+		// hand-authored declarations, not something derivable from runnables.
+		data_categories: [],
+		pi_extensions: [],
 		widgets,
 	};
 

package/src/runnable/turn-hook.ts

@@ -176,13 +176,16 @@ export function definePlugin(options: DefinePluginOptions): PluginManifest {
 		settings_tabs: options.settingsTabs ?? [],
 		slash_commands: options.slashCommands ?? [],
 		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.
+		// A turn-hook plugin contributes no app widgets, sidebar entries, dock
+		// panels, danger-zone categories or Pi extensions; the fields are required
+		// on the resolved `Contributes` type (zod defaults applied), so set them
+		// explicitly.
 		widgets: [],
 		sidebar_sections: [],
 		sidebar_buttons: [],
 		dock_panels: [],
+		data_categories: [],
+		pi_extensions: [],
 	};
 	// Ship each inline tool as a `kind:"tool"` runnable (Core's `inline_deno`
 	// backend). Shipping tools requires the `tool:execute` grant; add it once.