@ryuhq/sdk 0.1.14 → 0.2.2

package/dist/runnable.cjs

@@ -0,0 +1,1438 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/runnable/index.ts
+var runnable_exports = {};
+__export(runnable_exports, {
+  PRIMITIVE_BINDINGS: () => PRIMITIVE_BINDINGS,
+  appToolId: () => appToolId,
+  createPrimitives: () => createPrimitives,
+  defineAction: () => defineAction,
+  defineAgent: () => defineAgent,
+  defineApp: () => defineApp,
+  defineSkill: () => defineSkill,
+  defineTool: () => defineTool,
+  defineWorkflow: () => defineWorkflow,
+  httpPrimitiveTransport: () => httpPrimitiveTransport
+});
+module.exports = __toCommonJS(runnable_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;
+}
+
+// src/runnable/agent.ts
+var CAPABILITY_SLOTS = ["rag", "memory", "tts", "stt"];
+function lowerChatSlot(chat) {
+  if (chat === void 0) {
+    return {};
+  }
+  if (typeof chat === "string") {
+    return { model: chat };
+  }
+  return {
+    model: chat.model,
+    engine: chat.engine,
+    persona: chat.persona,
+    modelPrefKey: chat.modelPrefKey
+  };
+}
+function lowerCapabilitySlot(capability, slot, card) {
+  if (slot === void 0 || slot === false) {
+    return;
+  }
+  if (slot === true) {
+    card.capabilities.push({ capability });
+    return;
+  }
+  if (typeof slot === "string") {
+    card.capabilities.push({ capability });
+    card.providers[capability] = slot;
+    return;
+  }
+  card.capabilities.push(
+    slot.minVersion ? { capability, min_version: slot.minVersion } : { capability }
+  );
+  if (slot.provider) {
+    card.providers[capability] = slot.provider;
+  }
+}
+function lowerSlots(options) {
+  const card = {
+    ...lowerChatSlot(options.chat),
+    capabilities: [],
+    providers: {},
+    tools: []
+  };
+  for (const capability of CAPABILITY_SLOTS) {
+    lowerCapabilitySlot(capability, options[capability], card);
+  }
+  for (const t of options.tools ?? []) {
+    card.tools.push(typeof t === "string" ? t : t.id);
+  }
+  return card;
+}
+function defaultRun(card) {
+  return async (input, ctx) => {
+    const content = typeof input === "string" ? input : JSON.stringify(input ?? "");
+    const messages = card.persona ? [
+      { role: "system", content: card.persona },
+      { role: "user", content }
+    ] : [{ role: "user", content }];
+    const result = await ctx.gateway.chat(messages);
+    return result.content;
+  };
+}
+function cardConfig(card) {
+  const config = {};
+  if (card.model) {
+    config.model = card.model;
+  }
+  if (card.engine) {
+    config.engine = card.engine;
+  }
+  if (card.persona) {
+    config.persona = card.persona;
+  }
+  if (card.modelPrefKey) {
+    config.model_pref_key = card.modelPrefKey;
+  }
+  if (Object.keys(card.providers).length > 0) {
+    config.capability_providers = card.providers;
+  }
+  if (card.tools.length > 0) {
+    config.tools = card.tools;
+  }
+  return config;
+}
+function agentToManifest(agent, options) {
+  const config = cardConfig(agent.card);
+  const meta = {
+    id: agent.id,
+    name: agent.name,
+    kind: "agent",
+    ...Object.keys(config).length > 0 ? { config } : {}
+  };
+  const hasRequires = agent.card.capabilities.length > 0 || (options.grants?.length ?? 0) > 0;
+  const raw = {
+    id: options.id,
+    name: options.name ?? agent.name,
+    version: options.version,
+    runnables: [meta],
+    ...hasRequires ? {
+      requires: {
+        apps: [],
+        capabilities: agent.card.capabilities,
+        grants: options.grants ?? []
+      }
+    } : {}
+  };
+  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(
+      `agent manifest validation failed at '${field}': ${message}`
+    );
+  }
+  return result.data;
+}
+function defineAgent(options) {
+  const { id, name } = options;
+  const card = lowerSlots(options);
+  const run = options.run ?? defaultRun(card);
+  return {
+    id,
+    name,
+    kind: "agent",
+    run,
+    card,
+    toManifest(manifestOptions) {
+      return agentToManifest(this, manifestOptions);
+    }
+  };
+}
+
+// src/runnable/app.ts
+var DEFAULT_APP_WIDGET_MIME = "text/html+skybridge";
+var DEFAULT_APP_DISPLAY_MODE = "inline";
+var WIDGET_RENDER_GRANT = "widget:render";
+function withWidgetRenderGrant(grants, widgets) {
+  const out = [...grants];
+  if (widgets.length > 0 && !out.includes(WIDGET_RENDER_GRANT)) {
+    out.push(WIDGET_RENDER_GRANT);
+  }
+  return out;
+}
+function withToolExecuteGrant(grants, tools) {
+  const out = [...grants];
+  if (tools.some((tool) => tool.runnable !== void 0) && !out.includes("tool:execute")) {
+    out.push("tool:execute");
+  }
+  return out;
+}
+function appToolId(server, name) {
+  return `${server}.${name}`;
+}
+function defineApp(options) {
+  const server = options.server ?? options.slug;
+  const uri = `ui://widget/${options.slug}.html`;
+  const mime = options.mime ?? DEFAULT_APP_WIDGET_MIME;
+  const displayMode = options.displayMode ?? DEFAULT_APP_DISPLAY_MODE;
+  const hasCompanions = options.tools.some((t) => t.accessible === true);
+  const runnables = [];
+  const widgets = [];
+  for (const spec of options.tools) {
+    const isRender = spec.accessible !== true;
+    const id = appToolId(server, spec.name);
+    const executable = spec.runnable ? inlineToolRunnable(spec.runnable) : void 0;
+    const config = {
+      ...executable?.config ?? {},
+      slug: id,
+      description: spec.description,
+      widget: isRender,
+      widget_accessible: isRender ? hasCompanions : true,
+      ...spec.inputSchema ? { input_schema: spec.inputSchema } : {},
+      ...spec.invoking ? { invoking: spec.invoking } : {},
+      ...spec.invoked ? { invoked: spec.invoked } : {}
+    };
+    runnables.push({
+      id,
+      name: spec.name,
+      kind: "tool",
+      config
+    });
+    if (isRender) {
+      widgets.push({
+        tool_id: id,
+        uri,
+        ui_entry: options.uiEntry,
+        mime,
+        default_display_mode: displayMode
+      });
+    }
+  }
+  const contributes = {
+    turn_hooks: [],
+    chat_features: [],
+    // This builder synthesises an app from its runnables; an app that emits
+    // events declares them in a hand-authored `manifest.json`, same as
+    // `lsp_servers` below.
+    hook_events: [],
+    composer_controls: [],
+    settings_tabs: [],
+    slash_commands: options.slashCommands ?? [],
+    sidebar_sections: [],
+    sidebar_buttons: [],
+    dock_panels: [],
+    live_activities: [],
+    // Empty for the same reason as every sibling family above: this builder
+    // synthesises `widgets` from the app's own runnables and nothing else, and
+    // takes no `contributes` passthrough. An app that wants to declare language
+    // servers writes them in a hand-authored `manifest.json`.
+    lsp_servers: {},
+    // Same reason again: a danger-zone category, a Pi extension and an output
+    // style are all hand-authored declarations, not something derivable from
+    // runnables. An output style in particular points at a Markdown file next
+    // to the manifest, which this builder never writes.
+    data_categories: [],
+    pi_extensions: [],
+    output_styles: [],
+    message_actions: [],
+    selection_actions: [],
+    widgets
+  };
+  const raw = {
+    id: options.id,
+    name: options.title,
+    version: options.version,
+    runnables,
+    // An app that synthesises widgets MUST hold `widget:render`, so this
+    // builder declares it rather than leaving the author to discover it.
+    //
+    // Core gates widget promotion on declared-AND-enabled-AND-granted, and a
+    // missing grant fails as `DeniedNoGrant` — which is an `info!` log and
+    // nothing else. The widget silently renders as plain text, with no error
+    // in the UI and nothing pointing at the manifest.
+    //
+    // Added only when there is a widget to render, and unioned rather than
+    // overwritten so an author's own `grants` list survives and re-declaring
+    // it is not an error.
+    permission_grants: withToolExecuteGrant(
+      withWidgetRenderGrant(options.grants ?? [], widgets),
+      options.tools
+    ),
+    activation_events: options.activationEvents ?? ["*"],
+    contributes,
+    // `targets: []` means EVERY surface, so an app that declares none is
+    // unrestricted — the backward-compatible default.
+    targets: options.targets ?? [],
+    // `requires` stays ABSENT (not `{apps:[],grants:[]}`) when undeclared, so the
+    // emitted manifest carries no key at all — matching Core's
+    // `Option<Requires>` + `skip_serializing_if = "Option::is_none"`.
+    ...options.requires ? {
+      requires: {
+        apps: options.requires.apps ?? [],
+        capabilities: options.requires.capabilities ?? [],
+        grants: options.requires.grants ?? []
+      }
+    } : {}
+  };
+  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(
+      `manifest.json validation failed at '${field}': ${message}`
+    );
+  }
+  return result.data;
+}
+
+// src/model/gateway.ts
+var native = __toESM(require("@ryuhq/sdk-native"), 1);
+function assertAllowedEgressUrl(baseUrl) {
+  native.assertAllowedEgress(baseUrl);
+}
+
+// src/runnable/primitives.ts
+function dataUrlToBytes(dataUrl) {
+  const match = /^data:([^;,]*)(;base64)?,([\s\S]*)$/.exec(dataUrl);
+  if (!match) {
+    throw new Error(
+      "stt.transcribe expects an `audio` value that is a data: URL (data:<mime>;base64,<data>)"
+    );
+  }
+  const mediaType = match[1] || "application/octet-stream";
+  const isBase64 = Boolean(match[2]);
+  const payload = match[3] ?? "";
+  if (isBase64) {
+    const binary = atob(payload);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return { bytes, mediaType };
+  }
+  return {
+    bytes: new TextEncoder().encode(decodeURIComponent(payload)),
+    mediaType
+  };
+}
+function bytesToDataUrl(bytes, mediaType) {
+  let binary = "";
+  const chunk = 32768;
+  for (let i = 0; i < bytes.length; i += chunk) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+  }
+  return `data:${mediaType};base64,${btoa(binary)}`;
+}
+function httpPrimitiveTransport(options) {
+  const base = options.nodeUrl.replace(/\/+$/, "");
+  assertAllowedEgressUrl(base);
+  const doFetch = options.fetchImpl ?? fetch;
+  const authHeader = () => options.token ? { authorization: `Bearer ${options.token}` } : {};
+  const failDetail = async (path, res) => {
+    const detail = await res.text().catch(() => "");
+    return new Error(
+      `Ryu primitive call ${path} failed: ${res.status} ${res.statusText}${detail ? ` \u2014 ${detail}` : ""}`
+    );
+  };
+  const post = async (path, body) => {
+    const res = await doFetch(`${base}${path}`, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...authHeader() },
+      body: JSON.stringify(body ?? {})
+    });
+    if (!res.ok) {
+      throw await failDetail(path, res);
+    }
+    const text = await res.text();
+    return text ? JSON.parse(text) : void 0;
+  };
+  const transcribeDirect = async (body) => {
+    const input = body ?? {};
+    if (!input.audio) {
+      throw new Error(
+        "stt.transcribe requires an `audio` data: URL (the recorded audio)"
+      );
+    }
+    const { bytes, mediaType } = dataUrlToBytes(input.audio);
+    const form = new FormData();
+    form.append(
+      "file",
+      new Blob([bytes], { type: mediaType || "audio/wav" }),
+      input.filename ?? "recording.wav"
+    );
+    const res = await doFetch(`${base}/api/voice/transcribe`, {
+      method: "POST",
+      headers: authHeader(),
+      body: form
+    });
+    if (!res.ok) {
+      throw await failDetail("/api/voice/transcribe", res);
+    }
+    const parsed = await res.json();
+    return (parsed.text ?? "").trim();
+  };
+  const speakDirect = async (body) => {
+    const res = await doFetch(`${base}/api/voice/speak`, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...authHeader() },
+      body: JSON.stringify(body ?? {})
+    });
+    if (!res.ok) {
+      throw await failDetail("/api/voice/speak", res);
+    }
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    const mediaType = res.headers.get("content-type") || "audio/wav";
+    return bytesToDataUrl(bytes, mediaType);
+  };
+  const generateImageDirect = async (body) => {
+    const res = await doFetch(`${base}/api/images/generate`, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...authHeader() },
+      body: JSON.stringify(body ?? {})
+    });
+    if (!res.ok) {
+      throw await failDetail("/api/images/generate", res);
+    }
+    const parsed = await res.json();
+    return (parsed.data ?? []).map(
+      (item) => item.url ? item.url : `data:image/png;base64,${item.b64_json ?? ""}`
+    );
+  };
+  return {
+    bridge(method, args) {
+      if (!options.pluginId) {
+        return Promise.reject(
+          new Error(
+            `bridge primitive "${method}" requires a pluginId (the /api/plugins/:id/host caller identity)`
+          )
+        );
+      }
+      return post(`/api/plugins/${options.pluginId}/host`, { method, args });
+    },
+    direct(path, body) {
+      if (path === "/api/voice/transcribe") {
+        return transcribeDirect(body);
+      }
+      if (path === "/api/voice/speak") {
+        return speakDirect(body);
+      }
+      if (path === "/api/images/generate") {
+        return generateImageDirect(body);
+      }
+      return post(path, body);
+    },
+    capability(cap, body) {
+      return post(`/api/host/capability/${cap}`, body);
+    }
+  };
+}
+var PRIMITIVE_BINDINGS = {
+  // Bridge families (existing `PluginHookBridge`).
+  "engines.complete": {
+    transport: "bridge",
+    method: "model.complete",
+    grant: "hook:side-model"
+  },
+  "background.list": {
+    transport: "bridge",
+    method: "background.list",
+    grant: "background:control"
+  },
+  "background.stop": {
+    transport: "bridge",
+    method: "background.stop",
+    grant: "background:control"
+  },
+  "storage.get": {
+    transport: "bridge",
+    method: "storage.get",
+    grant: "storage:kv"
+  },
+  "storage.set": {
+    transport: "bridge",
+    method: "storage.set",
+    grant: "storage:kv"
+  },
+  "storage.delete": {
+    transport: "bridge",
+    method: "storage.delete",
+    grant: "storage:kv"
+  },
+  "storage.keys": {
+    transport: "bridge",
+    method: "storage.keys",
+    grant: "storage:kv"
+  },
+  "storage.compareAndSet": {
+    transport: "bridge",
+    method: "storage.compareAndSet",
+    grant: "storage:kv"
+  },
+  // Host-direct media data-path (the host holds the node token; returns data: URLs).
+  "image.generate": {
+    transport: "direct",
+    path: "/api/images/generate",
+    grant: "media:generate"
+  },
+  "tts.speak": {
+    transport: "direct",
+    path: "/api/voice/speak",
+    grant: "media:generate"
+  },
+  "stt.transcribe": {
+    transport: "direct",
+    path: "/api/voice/transcribe",
+    grant: "media:transcribe"
+  },
+  // Broker capabilities — no rpc family yet (@requires-grant).
+  "rag.retrieve": { transport: "broker", capability: "rag" },
+  "rag.embed": { transport: "broker", capability: "rag" },
+  "rag.rerank": { transport: "broker", capability: "rag" },
+  "memory.recall": { transport: "broker", capability: "memory" },
+  "memory.store": { transport: "broker", capability: "memory" },
+  "realtime.broadcast": { transport: "broker", capability: "realtime" },
+  "realtime.subscribe": { transport: "broker", capability: "realtime" },
+  "durable.checkpoint": { transport: "broker", capability: "durable" },
+  "durable.resume": { transport: "broker", capability: "durable" },
+  "engines.embed": { transport: "broker", capability: "engines" }
+};
+function brokerCall(transport, cap, op, input) {
+  return transport.capability(cap, { op, input });
+}
+function createPrimitives(transport) {
+  return {
+    background: {
+      list: (input) => transport.bridge("background.list", {
+        producer: input?.producer,
+        running_only: input?.runningOnly
+      }),
+      stop: (input) => transport.bridge("background.stop", {
+        process_id: input.processId
+      })
+    },
+    storage: {
+      get: (input) => transport.bridge("storage.get", input),
+      set: (input) => transport.bridge("storage.set", input).then(() => void 0),
+      delete: (input) => transport.bridge("storage.delete", input).then(() => void 0),
+      keys: (input) => transport.bridge("storage.keys", input ?? {}).then((value) => Array.isArray(value) ? value : []),
+      compareAndSet: (input) => transport.bridge("storage.compareAndSet", input)
+    },
+    rag: {
+      retrieve: (input) => brokerCall(transport, "rag", "retrieve", input),
+      embed: (input) => brokerCall(transport, "rag", "embed", input),
+      rerank: (input) => brokerCall(transport, "rag", "rerank", input)
+    },
+    memory: {
+      recall: (input) => brokerCall(transport, "memory", "recall", input),
+      store: (input) => brokerCall(transport, "memory", "store", input)
+    },
+    realtime: {
+      broadcast: (input) => brokerCall(transport, "realtime", "broadcast", input).then(
+        () => void 0
+      ),
+      subscribe: (input) => brokerCall(
+        transport,
+        "realtime",
+        "subscribe",
+        input
+      )
+    },
+    durable: {
+      checkpoint: (input) => brokerCall(transport, "durable", "checkpoint", input),
+      resume: (input) => brokerCall(transport, "durable", "resume", input)
+    },
+    engines: {
+      // Bridge family: model.complete → host.sideModel (wire keys are snake_case).
+      complete: (input) => transport.bridge("model.complete", {
+        prompt: input.prompt,
+        system: input.system,
+        model: input.model,
+        model_pref_key: input.modelPrefKey,
+        effort: input.effort
+      }),
+      embed: (input) => brokerCall(transport, "engines", "embed", input)
+    },
+    tts: {
+      speak: (input) => transport.direct("/api/voice/speak", input)
+    },
+    stt: {
+      transcribe: (input) => transport.direct("/api/voice/transcribe", input)
+    },
+    image: {
+      generate: (input) => transport.direct("/api/images/generate", input)
+    }
+  };
+}
+
+// src/runnable/skill.ts
+function defineSkill(options) {
+  const { id, name, run } = options;
+  return {
+    id,
+    name,
+    kind: "skill",
+    run
+  };
+}
+
+// src/runnable/workflow.ts
+function defineWorkflow(options) {
+  const { id, name, run } = options;
+  return {
+    id,
+    name,
+    kind: "workflow",
+    run
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PRIMITIVE_BINDINGS,
+  appToolId,
+  createPrimitives,
+  defineAction,
+  defineAgent,
+  defineApp,
+  defineSkill,
+  defineTool,
+  defineWorkflow,
+  httpPrimitiveTransport
+});