@ryuhq/sdk 0.2.0 → 0.2.2

package/dist/action.cjs

@@ -0,0 +1,839 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/runnable/action.ts
+var action_exports = {};
+__export(action_exports, {
+  defineAction: () => defineAction
+});
+module.exports = __toCommonJS(action_exports);
+
+// src/manifest.ts
+var import_node_module = require("module");
+var import_zod = require("zod");
+var RunnableKindSchema = import_zod.z.enum([
+  "agent",
+  "workflow",
+  "tool",
+  "skill",
+  // A companion surface (in-desktop panel). Added so a packable plugin can
+  // declare a companion runnable that flows through Core's existing Companion
+  // handler → app_contrib → `GET /api/plugins/contributions` → the desktop
+  // `/plugin/<id>` route. Its `config.ui_entry` (see `CompanionRunnableConfigSchema`)
+  // is what `ryu pack` bundles into `ui_code`.
+  "companion"
+]);
+var RunnableMetaSchema = import_zod.z.object({
+  /** Stable unique identifier (e.g. `"agent-researcher"`). */
+  id: import_zod.z.string().min(1),
+  /** Human-readable display name. */
+  name: import_zod.z.string().min(1),
+  /** Which kind of runnable this entry describes. */
+  kind: RunnableKindSchema,
+  /**
+   * Optional per-kind config blob. Mirrors Core's `RunnableEntry.config`
+   * (`Option<serde_json::Value>`) so a manifest authored here round-trips
+   * through Core-strict validation. Left opaque (a record) at this authoring
+   * layer; the per-kind shape is enforced by Core's `validate_runnable`.
+   *
+   * For a `companion` runnable, `config.ui_entry` names the plugin's UI entry
+   * module (relative to the manifest dir). `ryu pack` bundles that entry into
+   * the emitted `ui_code`; Core's `CompanionConfig.ui_entry` is the lockstep
+   * field so a packed companion validates.
+   */
+  config: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional()
+});
+function labelImpersonatesSystemChrome(label) {
+  const lower = label.toLowerCase();
+  return lower.includes("ryu") || lower.includes("system");
+}
+var CompanionSurfaceSchema = import_zod.z.object({
+  /** Display label for the companion panel tab or tooltip. Anti-impersonation:
+   *  may not pose as first-party Ryu/system chrome (see
+   *  {@link labelImpersonatesSystemChrome}). */
+  label: import_zod.z.string().min(1).refine((value) => !labelImpersonatesSystemChrome(value), {
+    message: "companion label must not impersonate system chrome (must not contain 'ryu' or 'system')"
+  }),
+  /** Icon identifier resolved by the desktop shell. */
+  icon: import_zod.z.string().optional(),
+  /** Keyboard shortcut string (e.g. `"ctrl+shift+r"`). */
+  shortcut: import_zod.z.string().optional()
+});
+var TurnHookContributionSchema = import_zod.z.object({
+  /** Stable id for this hook (unique within the plugin). */
+  id: import_zod.z.string().min(1),
+  /** 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).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 OutputStyleContributionSchema = import_zod.z.object({
+  /** Stable id for this style within the plugin (`[a-z0-9][a-z0-9._-]*`). It is
+   *  also the persisted selection key, so it must survive a settings key and a URL
+   *  path. */
+  id: import_zod.z.string().min(1),
+  /** SOURCE form: path to the Markdown file, relative to the plugin root —
+   *  exactly `output-styles/<name>.md`. `ryu pack` replaces this with `source`. */
+  file: import_zod.z.string().min(1).optional(),
+  /** WIRE form: the file's contents verbatim, frontmatter INCLUDED. The whole file
+   *  rather than a pre-split body plus mirrored `name`/`description` keys, so a
+   *  plugin style and a user's own `output-styles/*.md` go through one parser and
+   *  the frontmatter stays the single source of truth for a style's metadata. */
+  source: import_zod.z.string().optional()
+});
+var DEFAULT_WIDGET_MIME = "text/html+skybridge";
+var DEFAULT_WIDGET_DISPLAY_MODE = "inline";
+var WidgetContributionSchema = import_zod.z.object({
+  /** The fully-qualified tool id whose result renders this widget. */
+  tool_id: import_zod.z.string().min(1),
+  /** `ui://widget/<slug>.html` — the widget resource uri. */
+  uri: import_zod.z.string().min(1),
+  /** Source entry (e.g. `src/apps/checklist/index.tsx`) for `ryu pack`. */
+  ui_entry: import_zod.z.string().optional(),
+  /** Widget MIME dialect (default `text/html+skybridge`). */
+  mime: import_zod.z.string().default(DEFAULT_WIDGET_MIME),
+  /** Default display mode (`inline` | `fullscreen` | `pip`). */
+  default_display_mode: import_zod.z.string().default(DEFAULT_WIDGET_DISPLAY_MODE)
+});
+var ChatWidgetTemplateSchema = import_zod.z.object({
+  id: import_zod.z.string().regex(/^[a-z0-9][a-z0-9._:-]*$/),
+  title: import_zod.z.string().min(1),
+  description: import_zod.z.string().optional(),
+  triggers: import_zod.z.array(import_zod.z.string()).default([]),
+  examples: import_zod.z.array(import_zod.z.string()).default([]),
+  backing: import_zod.z.object({
+    tool_id: import_zod.z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:/-]*$/).optional(),
+    view_id: import_zod.z.string().regex(/^[a-z0-9][a-z0-9._:-]*$/).optional()
+  }),
+  display_mode: import_zod.z.string().min(1),
+  safe_action_ids: import_zod.z.array(import_zod.z.string().regex(/^[a-z0-9][a-z0-9._-]*$/)).default([]),
+  availability: import_zod.z.string().default("available")
+}).superRefine((value, ctx) => {
+  const count = Number(Boolean(value.backing.tool_id)) + Number(Boolean(value.backing.view_id));
+  if (count !== 1 && value.availability === "available") {
+    ctx.addIssue({
+      code: "custom",
+      path: ["backing"],
+      message: "available templates need exactly one backing tool_id or view_id"
+    });
+  }
+  if (count > 1) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["backing"],
+      message: "backing must declare at most one of tool_id or view_id"
+    });
+  }
+});
+var ToolAppConfigSchema = import_zod.z.object({
+  /** MCP tool slug this runnable wraps — the fully-qualified `<server>.<name>` id. */
+  slug: import_zod.z.string().min(1),
+  /** The tool description the model reads when choosing it. Carried here because a
+   *  packed app's manifest is the only channel (there is no `generated.rs`); Core's
+   *  app-tool synthesis reads it back onto the `RegistryTool`. */
+  description: import_zod.z.string(),
+  /** JSON Schema for the tool's arguments (used for validation + the LLM tool
+   *  surface). Snake_case to match `widget_accessible`. Absent = no arguments. */
+  input_schema: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional(),
+  /** True when calling this tool renders the app's widget (carries the template). */
+  widget: import_zod.z.boolean().default(false),
+  /** True when a mounted widget may `callTool` this tool (a companion), or when a
+   *  render tool's widget may call any companion the app declares. */
+  widget_accessible: import_zod.z.boolean().default(false),
+  /** Optional status label shown while the render tool runs. */
+  invoking: import_zod.z.string().optional(),
+  /** Optional status label shown when the render tool finishes. */
+  invoked: import_zod.z.string().optional()
+});
+var SlashCommandOptionSchema = import_zod.z.object({
+  description: import_zod.z.string().optional(),
+  label: import_zod.z.string().min(1),
+  value: import_zod.z.string().min(1)
+}).passthrough();
+var SlashCommandCustomOptionSchema = import_zod.z.union([
+  import_zod.z.literal(true),
+  import_zod.z.object({
+    description: import_zod.z.string().optional(),
+    label: import_zod.z.string().min(1).optional()
+  }).passthrough()
+]);
+var SlashCommandArgumentSchema = import_zod.z.object({
+  allow_custom: import_zod.z.boolean().optional(),
+  custom: SlashCommandCustomOptionSchema.optional(),
+  description: import_zod.z.string().optional(),
+  name: import_zod.z.string().min(1),
+  options: import_zod.z.array(SlashCommandOptionSchema).optional()
+}).passthrough();
+var SlashCommandContributionSchema = import_zod.z.object({
+  args: import_zod.z.array(SlashCommandArgumentSchema).optional(),
+  body: import_zod.z.string().optional(),
+  command: import_zod.z.string().min(1),
+  description: import_zod.z.string().optional(),
+  id: import_zod.z.string().optional(),
+  parameters: import_zod.z.array(SlashCommandArgumentSchema).optional()
+}).passthrough();
+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([]),
+  /** Chat feature descriptors whose behavior is implemented by the host shell.
+   * Mirrors the Rust-side `Contributes.chat_features`; keeping this field in the
+   * authoring schema prevents `ryu pack` from silently deleting a plugin's chat
+   * feature declaration before signing. */
+  chat_features: 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(SlashCommandContributionSchema).default([]),
+  /** App widgets (Ryu Apps). Each binds a render tool id to its
+   *  `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([]),
+  /** Metadata-only chat widget templates. */
+  chat_widget_templates: import_zod.z.array(ChatWidgetTemplateSchema).optional(),
+  /** 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([]),
+  /** App-registered live activities (the desktop "Dynamic Island" cards). Loosely
+   *  typed for the same reason as the surfaces above — the shell owns the
+   *  `spec` vocabulary. Mirrors the Rust-side `Contributes.live_activities`;
+   *  without it the CLI's zod parse would strip every live activity an app
+   *  declares here, so a packed bundle would ship a dock that silently stays
+   *  empty. */
+  live_activities: 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([]),
+  /** Output styles the plugin ships — Markdown files that rewrite the system
+   *  prompt's voice. Mirrors the Rust-side `Contributes.output_styles`; without it
+   *  the CLI's zod parse would strip the declaration, and `ryu pack` would sign a
+   *  bundle whose styles simply do not exist. Worse than the usual case of that
+   *  bug: the styles' `.md` files are not carried by the bundle either, so there
+   *  would be no residue to notice — the plugin would install clean and contribute
+   *  nothing. */
+  output_styles: import_zod.z.array(OutputStyleContributionSchema).default([]),
+  /** Per-message actions contributed by an enabled plugin. Kept as loose records
+   *  so renderer-specific `kind`/`args` payloads survive `ryu pack` unchanged. */
+  message_actions: import_zod.z.array(import_zod.z.record(import_zod.z.string(), import_zod.z.unknown())).default([]),
+  /** Buttons contributed to the floating text-selection toolbar. Kept as loose
+   *  records so host-owned dispatch args survive `ryu pack` unchanged. */
+  selection_actions: import_zod.z.array(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). */
+  title: import_zod.z.string().optional(),
+  /** Instruction body shown under the title. */
+  description: import_zod.z.string().optional(),
+  /** Label for the optional action button. */
+  actionLabel: import_zod.z.string().optional(),
+  /** URL the action button opens (validated server-side on publish). */
+  actionUrl: import_zod.z.string().optional()
+});
+var AppDependencySchema = import_zod.z.object({
+  /** The `id` of the plugin this one depends on. */
+  id: import_zod.z.string().min(1, "dependency id is required"),
+  /** Optional MINIMUM version the dependency must satisfy (`"1.2.0"` = `">=1.2.0"`). */
+  min_version: import_zod.z.string().min(1).optional()
+});
+var CapabilityReqSchema = import_zod.z.object({
+  /** Capability name (e.g. `"rag"`, `"memory"`, `"tts"`). Matched against a
+   *  provider's `provides[].capability`. */
+  capability: import_zod.z.string().min(1, "capability name is required"),
+  /** Optional MINIMUM capability version the bound provider must satisfy
+   *  (`"1.2.0"` = `">=1.2.0"`). Absent = any version. */
+  min_version: import_zod.z.string().min(1).optional()
+});
+var RequiresSchema = import_zod.z.object({
+  /** Other plugins that must be installed + enabled before this one enables. */
+  apps: import_zod.z.array(AppDependencySchema).default([]),
+  /**
+   * Abstract capability edges the broker resolves to a bound provider at
+   * enable time. Mirrors `Requires::capabilities` in
+   * `crates/ryu-kernel-contracts` — an `apps` edge names a specific plugin; a
+   * `capabilities` edge names a capability and lets the binding registry choose
+   * the provider. Each is lowered to an app-id graph edge once bound, so the
+   * enable/disable/cycle machinery is shared. Empty for the common case.
+   */
+  capabilities: import_zod.z.array(CapabilityReqSchema).default([]),
+  /**
+   * Permission grants implied by the dependencies. Declaration only — the
+   * Gateway remains the sole authority on what a grant *allows*, and Core's
+   * dependency graph resolves `apps` only.
+   */
+  grants: import_zod.z.array(import_zod.z.string()).default([])
+});
+var SurfaceSchema = import_zod.z.enum([
+  /** The Ryu Gateway. */
+  "gateway",
+  /** A headless Core node (no UI). */
+  "core",
+  /** The Tauri desktop app. */
+  "desktop",
+  /** The Electron dynamic-island companion. */
+  "island",
+  /** The Expo/React-Native mobile app. */
+  "mobile",
+  /** The browser extension. */
+  "extension",
+  /** The Next.js web app. */
+  "web",
+  /** The terminal client. */
+  "cli"
+]);
+var EnginesReqSchema = import_zod.z.object({
+  /** Floor for the terminal (`cli`) surface. */
+  cli: import_zod.z.string().optional(),
+  /** Floor for the Tauri desktop app. */
+  desktop: import_zod.z.string().optional(),
+  /** Floor for the browser extension. */
+  extension: import_zod.z.string().optional(),
+  /** Floor for the Ryu Gateway. */
+  gateway: import_zod.z.string().optional(),
+  /** Floor for the dynamic-island companion. */
+  island: import_zod.z.string().optional(),
+  /** Floor for the mobile app. */
+  mobile: import_zod.z.string().optional(),
+  /** Floor for the running **Core** (e.g. `">=0.3.0"`). Required. */
+  ryu: import_zod.z.string().min(1, "engines.ryu is required when engines is present"),
+  /** Floor for the Next.js web app. */
+  web: import_zod.z.string().optional()
+});
+var McpServerAuthSchema = import_zod.z.object({
+  client_id: import_zod.z.string().min(1).optional(),
+  type: import_zod.z.literal("oauth")
+}).strict();
+var McpServerDeclSchema = import_zod.z.object({
+  args: import_zod.z.array(import_zod.z.string()).default([]),
+  auth: McpServerAuthSchema.optional(),
+  command: import_zod.z.string().optional(),
+  command_env: import_zod.z.string().optional(),
+  description: import_zod.z.string().optional(),
+  enabled: import_zod.z.boolean().default(true),
+  env: import_zod.z.record(import_zod.z.string(), import_zod.z.string()).default({}),
+  headers: import_zod.z.record(import_zod.z.string(), import_zod.z.string()).default({}),
+  type: import_zod.z.enum(["stdio", "http", "streamable-http", "streamable_http", "sse"]).optional(),
+  url: import_zod.z.url().optional()
+}).superRefine((server, context) => {
+  if (!(server.command || server.url)) {
+    context.addIssue({
+      code: "custom",
+      message: "an MCP server requires command or url"
+    });
+  }
+  if (!server.auth) {
+    return;
+  }
+  if (server.command || server.type === "stdio" || !server.url) {
+    context.addIssue({
+      code: "custom",
+      message: "OAuth is supported only for remote HTTP MCP servers"
+    });
+    return;
+  }
+  if (Object.keys(server.headers).some(
+    (name) => name.toLowerCase() === "authorization"
+  )) {
+    context.addIssue({
+      code: "custom",
+      message: "OAuth cannot be combined with a static Authorization header"
+    });
+  }
+  const url = new URL(server.url);
+  const loopback = url.hostname === "localhost" || url.hostname.startsWith("127.") || url.hostname === "[::1]" || url.hostname === "::1";
+  if (url.username || url.password || url.hash) {
+    context.addIssue({
+      code: "custom",
+      message: "OAuth MCP URLs cannot contain credentials or fragments"
+    });
+  }
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
+    context.addIssue({
+      code: "custom",
+      message: "OAuth MCP URLs must use HTTPS except on loopback"
+    });
+  }
+});
+var PluginManifestSchema = import_zod.z.object({
+  /** Reverse-domain unique identifier (e.g. `"com.example.my-plugin"`). */
+  id: import_zod.z.string().min(1, "id is required"),
+  /** Human-readable display name shown in the plugin store / launcher. */
+  name: import_zod.z.string().min(1, "name is required"),
+  /**
+   * Semver version string (e.g. `"1.0.0"`). Core's loader rejects any manifest
+   * whose version is not valid semver; the regex here enforces the same rule at
+   * SDK-build time.
+   */
+  version: import_zod.z.string().regex(
+    /^\d+\.\d+\.\d+(?:-[\w.]+)?(?:\+[\w.]+)?$/,
+    "version must be a valid semver string (e.g. 1.0.0)"
+  ),
+  /** Core-owned release maturity metadata. The Rust contract validates the
+   *  richer shape; the SDK authoring parser must preserve it for pack/publish. */
+  stability: import_zod.z.unknown().optional(),
+  /**
+   * Lower-case hex `sha256(utf8_bytes(ui_code))` binding the plugin's bundled
+   * sandboxed-UI code to this manifest. `ryu pack` / `ryu publish` compute it and
+   * write it here BEFORE the manifest is signed, so the hash rides INSIDE the
+   * Gateway-signed surface while the `ui_code` blob rides OUTSIDE it as payload;
+   * Core's install path recomputes the hash over the fetched code and rejects a
+   * mismatch fail-closed. Absent for a manifest-only plugin (no bundled UI).
+   * Mirrors Core's `PluginManifest.ui_code_sha256`.
+   */
+  ui_code_sha256: import_zod.z.string().nullish(),
+  /** The Runnables this plugin bundles. */
+  runnables: import_zod.z.array(RunnableMetaSchema).default([]),
+  /**
+   * Permission grants this plugin declares it needs (e.g. `"mcp:web_search"`).
+   * Declarations only — grant enforcement is the Gateway's responsibility.
+   */
+  permission_grants: import_zod.z.array(import_zod.z.string()).default([]),
+  /** Deny-by-default sandbox permissions. Core remains authoritative; this
+   *  schema mirrors the fields so `ryu pack` cannot strip them. */
+  permissions: import_zod.z.object({
+    fs: import_zod.z.object({
+      read: import_zod.z.array(import_zod.z.string()).default([]),
+      write: import_zod.z.array(import_zod.z.string()).default([])
+    }).optional(),
+    child_process: import_zod.z.boolean().optional(),
+    run: import_zod.z.array(import_zod.z.string()).default([]),
+    network: import_zod.z.union([import_zod.z.boolean(), import_zod.z.array(import_zod.z.string())]).optional(),
+    tool: import_zod.z.array(import_zod.z.string()).default([])
+  }).optional(),
+  /** Core-owned permission presentation levels. Preserved verbatim here and
+   *  validated by Core's authoritative manifest contract. */
+  permission_levels: import_zod.z.unknown().optional(),
+  /** Remote or stdio MCP servers registered by this plugin. */
+  mcp_servers: import_zod.z.record(import_zod.z.string(), McpServerDeclSchema).optional(),
+  /** Core-owned sidecar declarations. Their full process/HTTP schema stays in
+   *  the Rust contract; this authoring layer must never strip them. */
+  sidecars: import_zod.z.unknown().optional(),
+  /**
+   * Optional Companion surface (an in-desktop overlay or sidebar panel).
+   * Absent when the plugin has no Companion surface.
+   */
+  companion: CompanionSurfaceSchema.optional(),
+  /**
+   * VS-Code-style activation events (`"*"`, `"onStartup"`, `"onChat"`,
+   * `"onCommand:<id>"`). Empty = eager. Turn-hook plugins are driven by their
+   * enabled flag, so `["*"]` is the usual value.
+   */
+  activation_events: import_zod.z.array(import_zod.z.string()).default([]),
+  /**
+   * Contribution points: server-side turn hooks + declarative UI widgets.
+   * Absent for a plugin that contributes nothing here.
+   */
+  contributes: ContributesSchema.optional(),
+  /**
+   * **Plugin-to-plugin dependencies** — the other plugins this one needs. Core
+   * resolves them into a topological enable order (dependencies enable first;
+   * disabling one is refused while an enabled dependent needs it).
+   *
+   * Absent = **no dependencies**, the backward-compatible default. Kept
+   * `.optional()` (never defaulted) so a manifest that declares none serialises
+   * with no `requires` key at all, exactly like Core's
+   * `#[serde(skip_serializing_if = "Option::is_none")]`.
+   */
+  requires: RequiresSchema.optional(),
+  /**
+   * Host surfaces this plugin runs on. **Empty or absent = runs on EVERY
+   * surface** — the backward-compatible default, which must never be read as
+   * "runs nowhere". Core filters only when the list is explicitly non-empty, and
+   * only at the read boundary (`GET /api/plugins`, keyed on `x-ryu-surface`), so
+   * an unsupported-target plugin stays installable and inspectable.
+   */
+  targets: import_zod.z.array(SurfaceSchema).default([]),
+  /** Rich per-surface declarations (`support`, UI, contributed commands, …).
+   *  Core owns and validates the nested vocabulary. */
+  surfaces: import_zod.z.unknown().optional(),
+  /**
+   * Host version floors — the semver requirement each surface must satisfy for
+   * this plugin to install. Mirrors Core's `EnginesReq`
+   * (`crates/core/kernel-contracts/src/manifest.rs`).
+   *
+   * `ryu` is the **Core** floor and the only required key (it is the legacy
+   * spelling; every manifest in the wild carries just that one). The rest are
+   * optional per-surface floors.
+   *
+   * REGRESSION THIS FIXES: `engines` was absent from this schema entirely, and
+   * zod strips unlisted keys — so `ryu pack` silently dropped the whole block
+   * from every bundle it produced. A plugin could declare a Core floor, publish,
+   * and ship a bundle that declared none. Any new host floor MUST be added here
+   * as well as in the Rust contract, or it does not survive packing.
+   */
+  engines: EnginesReqSchema.optional(),
+  /**
+   * Optional per-item AFFILIATE terms: the commission paid to a referrer when a
+   * referred user buys this (paid) item. `value` is basis points for `percent`
+   * (2000 = 20%) or minor units (cents) for `flat`. Absent (or `enabled:false`)
+   * falls back to the seller org owner's default affiliate terms. This is the
+   * authoring surface for the marketplace publish body's `affiliate` field (the
+   * server re-validates it); it only takes effect on a paid item.
+   */
+  affiliate: import_zod.z.object({
+    enabled: import_zod.z.boolean().default(false),
+    rule: import_zod.z.object({
+      type: import_zod.z.enum(["percent", "flat"]),
+      value: import_zod.z.number().nonnegative(),
+      recurring: import_zod.z.boolean().default(false),
+      durationMonths: import_zod.z.number().int().positive().nullish(),
+      fundedBy: import_zod.z.enum(["platform", "seller"]).default("platform")
+    }).optional()
+  }).optional(),
+  // ── Rich listing metadata (Phase 1.5) ──────────────────────────────────────
+  // Optional store-listing fields a plugin author declares so the marketplace
+  // detail dialog renders a richer App-Store-style preview. Field names align
+  // with the Claude `.claude-plugin/marketplace.json` plugin-entry standard where
+  // one exists (`author`, `homepage`, `keywords`, `category`, `license`); the
+  // rest are Ryu extensions. `ryu publish` forwards these FLAT into the publish
+  // body (not inside the signed manifest blob) so the control plane stores them.
+  // All optional + additive: a manifest omitting them still validates.
+  /** Longer plain/markdown description shown in the detail dialog. */
+  description: import_zod.z.string().optional(),
+  /** Short one-line pitch shown under the name (Ryu extension). */
+  tagline: import_zod.z.string().optional(),
+  /**
+   * Publisher identity. A bare string OR a Claude-style object; `ryu publish`
+   * resolves it to the display `developer` (`author.name` when an object).
+   */
+  author: import_zod.z.union([
+    import_zod.z.string(),
+    import_zod.z.object({
+      name: import_zod.z.string(),
+      email: import_zod.z.string().optional(),
+      url: import_zod.z.string().optional()
+    })
+  ]).optional(),
+  /** Public source repository URL (Claude/Codex `repository`). */
+  repository: import_zod.z.string().url().optional(),
+  /** True when the provider operates outside the local Ryu runtime. */
+  external: import_zod.z.boolean().optional(),
+  /** Project/marketing homepage — maps to the listing `website` (Claude field). */
+  homepage: import_zod.z.string().optional(),
+  /** Free-text search keywords (Claude field). */
+  keywords: import_zod.z.array(import_zod.z.string()).optional(),
+  /** Stable Marketplace filter labels (Ryu extension). */
+  tags: import_zod.z.array(import_zod.z.string()).optional(),
+  /** Taxonomy category beyond the runnable kinds (Claude field). */
+  category: import_zod.z.string().optional(),
+  /** SPDX-ish license identifier (Claude field). */
+  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(),
+  /** Optional detail-page hero banner metadata forwarded to the marketplace. */
+  banner: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).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). */
+  privacyPolicyUrl: import_zod.z.string().optional(),
+  /** Terms-of-service URL surfaced on detail (Ryu extension). */
+  termsOfServiceUrl: import_zod.z.string().optional(),
+  /**
+   * Human-readable capability strings (Ryu extension). When omitted the control
+   * plane derives a default from `permission_grants`, so declaring this is only
+   * needed to override the derived labels.
+   */
+  capabilities: import_zod.z.array(import_zod.z.string()).optional(),
+  /** Example prompt chips shown on detail (Ryu extension). */
+  examplePrompts: import_zod.z.array(import_zod.z.string()).optional(),
+  /**
+   * Optional companion/config card (Ryu extension): a single setup step or an
+   * array of steps guiding the user through post-install configuration.
+   */
+  setup: import_zod.z.union([SetupStepSchema, import_zod.z.array(SetupStepSchema)]).optional()
+}).passthrough().superRefine((manifest, context) => {
+  const hasOAuthServer = Object.values(manifest.mcp_servers ?? {}).some(
+    (server) => server.auth?.type === "oauth"
+  );
+  if (!hasOAuthServer) {
+    return;
+  }
+  for (const grant of ["mcp:server", "identity.read"]) {
+    if (!manifest.permission_grants.includes(grant)) {
+      context.addIssue({
+        code: "custom",
+        message: `OAuth MCP servers require the ${grant} permission grant`,
+        path: ["permission_grants"]
+      });
+    }
+  }
+});
+
+// src/runnable/tool.ts
+function validateInput(input, schema, toolId) {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    throw new Error(
+      `[ryu-sdk] Tool "${toolId}" input must be an object, got ${JSON.stringify(input)}`
+    );
+  }
+  const record = input;
+  for (const requiredKey of schema.required ?? []) {
+    if (!(requiredKey in record)) {
+      throw new Error(
+        `[ryu-sdk] Tool "${toolId}" input missing required field "${requiredKey}"`
+      );
+    }
+  }
+  for (const [key, prop] of Object.entries(schema.properties)) {
+    if (!(key in record)) {
+      continue;
+    }
+    const value = record[key];
+    if (!checkType(value, prop.type)) {
+      throw new Error(
+        `[ryu-sdk] Tool "${toolId}" input field "${key}" expected type "${prop.type}", got ${JSON.stringify(value)}`
+      );
+    }
+  }
+}
+function checkType(value, type) {
+  switch (type) {
+    case "string":
+      return typeof value === "string";
+    case "number":
+    case "integer":
+      return typeof value === "number";
+    case "boolean":
+      return typeof value === "boolean";
+    case "array":
+      return Array.isArray(value);
+    case "object":
+      return typeof value === "object" && value !== null && !Array.isArray(value);
+    default:
+      return false;
+  }
+}
+function defineTool(options) {
+  const { description, id, name, schema, run } = options;
+  const code = `return await (${run.toString()})(input, host);`;
+  return {
+    id,
+    name,
+    kind: "tool",
+    schema,
+    ...description === void 0 ? {} : { description },
+    code,
+    run(input, ctx) {
+      validateInput(input, schema, id);
+      return run(input, ctx);
+    }
+  };
+}
+function inlineToolRunnable(tool, options) {
+  return {
+    id: tool.id,
+    name: tool.name,
+    kind: "tool",
+    config: {
+      slug: tool.id,
+      backend: "inline_deno",
+      code: tool.code,
+      input_schema: tool.schema,
+      ...options?.description === void 0 ? tool.description === void 0 ? {} : { description: tool.description } : { description: options.description },
+      ...options?.outputSchema ? { output_schema: options.outputSchema } : {},
+      ...options?.annotations ? { annotations: options.annotations } : {},
+      ...options?.action === void 0 ? {} : { action: options.action },
+      ...options?.needsApproval === void 0 ? {} : { needs_approval: options.needsApproval }
+    }
+  };
+}
+
+// src/runnable/action.ts
+function deriveAnnotations(effect, annotations) {
+  const resolved = {
+    ...annotations,
+    readOnlyHint: annotations?.readOnlyHint ?? effect === "read",
+    destructiveHint: annotations?.destructiveHint ?? effect === "mutate"
+  };
+  if (effect === "read" && resolved.destructiveHint) {
+    throw new Error(
+      "[ryu-sdk] read actions cannot set annotations.destructiveHint=true"
+    );
+  }
+  if (effect === "mutate" && resolved.readOnlyHint) {
+    throw new Error(
+      "[ryu-sdk] mutate actions cannot set annotations.readOnlyHint=true"
+    );
+  }
+  return resolved;
+}
+function actionManifestEntry(action) {
+  const options = {
+    action: true,
+    annotations: action.annotations,
+    description: action.description,
+    needsApproval: action.needsApproval,
+    ...action.outputSchema ? { outputSchema: action.outputSchema } : {}
+  };
+  return inlineToolRunnable(action, options);
+}
+function actionToManifest(action, options) {
+  const grants = [.../* @__PURE__ */ new Set([...options.grants ?? [], "tool:execute"])];
+  const raw = {
+    id: options.id,
+    name: options.name ?? action.name,
+    version: options.version,
+    runnables: [actionManifestEntry(action)],
+    permission_grants: grants,
+    activation_events: [...options.activationEvents ?? ["*"]],
+    targets: [...options.targets ?? []]
+  };
+  const result = PluginManifestSchema.safeParse(raw);
+  if (!result.success) {
+    const first = result.error.issues[0];
+    const field = first?.path.join(".") ?? "unknown";
+    const message = first?.message ?? "validation failed";
+    throw new Error(
+      `[ryu-sdk] action manifest validation failed at '${field}': ${message}`
+    );
+  }
+  return result.data;
+}
+function defineAction(options) {
+  const annotations = deriveAnnotations(options.effect, options.annotations);
+  const tool = defineTool({
+    description: options.description,
+    id: options.id,
+    name: options.name,
+    run: options.run,
+    schema: options.schema
+  });
+  const action = {
+    ...tool,
+    action: true,
+    annotations,
+    description: options.description,
+    effect: options.effect,
+    needsApproval: options.needsApproval ?? false,
+    ...options.outputSchema ? { outputSchema: options.outputSchema } : {},
+    toManifest(manifestOptions) {
+      return actionToManifest(action, manifestOptions);
+    },
+    toMcpTool(context) {
+      return {
+        name: action.id,
+        description: action.description,
+        inputSchema: action.schema,
+        run: (input) => action.run(input, context)
+      };
+    }
+  };
+  return action;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  defineAction
+});