@ryuhq/sdk 0.1.13 → 0.2.0

package/dist/builder.cjs

@@ -0,0 +1,1095 @@
+"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/builder.ts
+var builder_exports = {};
+__export(builder_exports, {
+  AgentBuilder: () => AgentBuilder,
+  AppBuilder: () => AppBuilder,
+  PluginBuilder: () => PluginBuilder,
+  SkillBuilder: () => SkillBuilder,
+  ToolBuilder: () => ToolBuilder,
+  WorkflowBuilder: () => WorkflowBuilder,
+  agent: () => agent,
+  app: () => app,
+  skill: () => skill,
+  tool: () => tool,
+  workflow: () => workflow
+});
+module.exports = __toCommonJS(builder_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 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(import_zod.z.record(import_zod.z.string(), import_zod.z.unknown())).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([])
+});
+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)"
+  ),
+  /**
+   * 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([]),
+  /** Remote or stdio MCP servers registered by this plugin. */
+  mcp_servers: import_zod.z.record(import_zod.z.string(), McpServerDeclSchema).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([]),
+  /**
+   * 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()
+}).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/app.ts
+var DEFAULT_APP_WIDGET_MIME = "text/html+skybridge";
+var DEFAULT_APP_DISPLAY_MODE = "inline";
+var WIDGET_RENDER_GRANT = "widget:render";
+function withWidgetRenderGrant(grants, widgets) {
+  const out = [...grants];
+  if (widgets.length > 0 && !out.includes(WIDGET_RENDER_GRANT)) {
+    out.push(WIDGET_RENDER_GRANT);
+  }
+  return out;
+}
+function appToolId(server, name) {
+  return `${server}.${name}`;
+}
+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 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: [],
+    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: [],
+    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. Every app scaffolded
+    // through `defineApp` hit that, because the only fix was a grant string
+    // the templates never mention and the builder never added; the one
+    // working example on disk hand-writes it.
+    //
+    // Added only when there is a widget to render, and unioned rather than
+    // overwritten so an author's own `grants` list survives and re-declaring
+    // it is not an error.
+    permission_grants: withWidgetRenderGrant(options.grants ?? [], widgets),
+    activation_events: options.activationEvents ?? ["*"],
+    contributes,
+    // `targets: []` means EVERY surface, so an app that declares none is
+    // 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/builder.ts
+var RunnableBuilder = class {
+  _id = "";
+  _name = "";
+  id(value) {
+    this._id = value;
+    return this;
+  }
+  name(value) {
+    this._name = value;
+    return this;
+  }
+};
+var AgentBuilder = class extends RunnableBuilder {
+  build() {
+    const result = RunnableMetaSchema.safeParse({
+      id: this._id,
+      name: this._name,
+      kind: "agent"
+    });
+    if (!result.success) {
+      throw new Error(
+        `Invalid agent runnable: ${result.error.issues.map((i) => i.message).join("; ")}`
+      );
+    }
+    return result.data;
+  }
+};
+var WorkflowBuilder = class extends RunnableBuilder {
+  build() {
+    const result = RunnableMetaSchema.safeParse({
+      id: this._id,
+      name: this._name,
+      kind: "workflow"
+    });
+    if (!result.success) {
+      throw new Error(
+        `Invalid workflow runnable: ${result.error.issues.map((i) => i.message).join("; ")}`
+      );
+    }
+    return result.data;
+  }
+};
+var ToolBuilder = class extends RunnableBuilder {
+  build() {
+    const result = RunnableMetaSchema.safeParse({
+      id: this._id,
+      name: this._name,
+      kind: "tool"
+    });
+    if (!result.success) {
+      throw new Error(
+        `Invalid tool runnable: ${result.error.issues.map((i) => i.message).join("; ")}`
+      );
+    }
+    return result.data;
+  }
+};
+var SkillBuilder = class extends RunnableBuilder {
+  build() {
+    const result = RunnableMetaSchema.safeParse({
+      id: this._id,
+      name: this._name,
+      kind: "skill"
+    });
+    if (!result.success) {
+      throw new Error(
+        `Invalid skill runnable: ${result.error.issues.map((i) => i.message).join("; ")}`
+      );
+    }
+    return result.data;
+  }
+};
+var agent = () => new AgentBuilder();
+var workflow = () => new WorkflowBuilder();
+var tool = () => new ToolBuilder();
+var skill = () => new SkillBuilder();
+var PluginBuilder = class {
+  _id = "";
+  _name = "";
+  _version = "";
+  _runnables = [];
+  _grants = [];
+  _companion = void 0;
+  _dependencies = [];
+  _requiredCapabilities = [];
+  _requiredGrants = [];
+  _targets = [];
+  /** Set the reverse-domain app id (e.g. `"com.example.my-app"`). */
+  id(value) {
+    this._id = value;
+    return this;
+  }
+  /** Set the human-readable display name. */
+  name(value) {
+    this._name = value;
+    return this;
+  }
+  /** Set the semver version string (e.g. `"1.0.0"`). */
+  version(value) {
+    this._version = value;
+    return this;
+  }
+  /** Append a pre-built `RunnableMeta` (from any per-kind builder). */
+  runnable(meta) {
+    this._runnables.push(meta);
+    return this;
+  }
+  /** Declare a permission grant (e.g. `"mcp:web_search"`). */
+  grant(permission) {
+    this._grants.push(permission);
+    return this;
+  }
+  /** Set an optional Companion surface descriptor. */
+  companion(surface) {
+    this._companion = surface;
+    return this;
+  }
+  /**
+   * Declare a **plugin-to-plugin dependency**: `id` must be installed and is
+   * auto-enabled (in dependency order) before this plugin enables.
+   *
+   * `minVersion` is a MINIMUM — a bare `"1.2.0"` means `">=1.2.0"`, so an
+   * installed `2.0.0` satisfies it (comparator syntax like `">=1.2, <2"` is
+   * honoured verbatim).
+   */
+  dependsOn(id, minVersion) {
+    this._dependencies.push(
+      minVersion ? { id, min_version: minVersion } : { id }
+    );
+    return this;
+  }
+  /**
+   * Declare a permission grant implied by this plugin's dependencies
+   * (`requires.grants`). Declaration only — the Gateway remains the sole
+   * authority on what a grant allows. Use {@link PluginBuilder.grant} for the
+   * grants this plugin needs in its own right.
+   */
+  requiredGrant(permission) {
+    this._requiredGrants.push(permission);
+    return this;
+  }
+  /**
+   * Declare an abstract **capability** edge (`requires.capabilities`) the broker
+   * resolves to a bound provider at enable time — e.g. `requiresCapability("rag")`.
+   * Distinct from a specific-plugin dependency: a capability edge lets the
+   * binding registry choose the provider. `minVersion` is a MINIMUM (`"1.2.0"`
+   * = `">=1.2.0"`).
+   */
+  requiresCapability(capability, minVersion) {
+    this._requiredCapabilities.push(
+      minVersion ? { capability, min_version: minVersion } : { capability }
+    );
+    return this;
+  }
+  /**
+   * Restrict this plugin to a host surface (`"desktop"`, `"island"`, …).
+   * Declaring NO target is the default and means **every** surface.
+   */
+  target(surface) {
+    this._targets.push(surface);
+    return this;
+  }
+  /**
+   * Validate and return the assembled `PluginManifest`. Throws an `Error` with
+   * the failing field name and message when validation fails.
+   */
+  build() {
+    const hasRequires = this._dependencies.length > 0 || this._requiredCapabilities.length > 0 || this._requiredGrants.length > 0;
+    const raw = {
+      id: this._id,
+      name: this._name,
+      version: this._version,
+      runnables: this._runnables,
+      permission_grants: this._grants,
+      companion: this._companion,
+      targets: this._targets,
+      ...hasRequires ? {
+        requires: {
+          apps: this._dependencies,
+          capabilities: this._requiredCapabilities,
+          grants: this._requiredGrants
+        }
+      } : {}
+    };
+    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;
+  }
+};
+var AppBuilder = class {
+  _id = "";
+  _title = "";
+  _version = "";
+  _slug = "";
+  _server = void 0;
+  _displayMode = void 0;
+  _mime = void 0;
+  _uiEntry = "";
+  _grants = [];
+  _activationEvents = [];
+  _tools = [];
+  _dependencies = [];
+  _requiredCapabilities = [];
+  _requiredGrants = [];
+  _targets = [];
+  /** Set the reverse-domain app id (e.g. `"com.example.checklist"`). */
+  id(value) {
+    this._id = value;
+    return this;
+  }
+  /** Set the human-readable display name. */
+  title(value) {
+    this._title = value;
+    return this;
+  }
+  /** Set the semver version string (e.g. `"1.0.0"`). */
+  version(value) {
+    this._version = value;
+    return this;
+  }
+  /** Set the app slug (drives `ui://widget/<slug>.html` and the server default). */
+  slug(value) {
+    this._slug = value;
+    return this;
+  }
+  /** Override the MCP server namespace for tool ids (defaults to the slug). */
+  server(value) {
+    this._server = value;
+    return this;
+  }
+  /** Set the default widget display mode (`inline` | `fullscreen` | `pip`). */
+  displayMode(value) {
+    this._displayMode = value;
+    return this;
+  }
+  /** Override the widget MIME dialect (defaults to `text/html+skybridge`). */
+  mime(value) {
+    this._mime = value;
+    return this;
+  }
+  /** Set the widget UI source entry `ryu pack` bundles into `ui_code`. */
+  uiEntry(value) {
+    this._uiEntry = value;
+    return this;
+  }
+  /** Declare a permission grant (e.g. `"mcp:web_search"`). */
+  grant(permission) {
+    this._grants.push(permission);
+    return this;
+  }
+  /** Add a VS-Code-style activation event (empty = eager `["*"]`). */
+  activationEvent(event) {
+    this._activationEvents.push(event);
+    return this;
+  }
+  /** Append a tool spec (render tool unless `accessible:true`). */
+  tool(spec) {
+    this._tools.push(spec);
+    return this;
+  }
+  /**
+   * Declare a **plugin-to-plugin dependency** (auto-enabled, in dependency order,
+   * before this app). `minVersion` is a MINIMUM (`"1.2.0"` = `">=1.2.0"`).
+   */
+  dependsOn(id, minVersion) {
+    this._dependencies.push(
+      minVersion ? { id, min_version: minVersion } : { id }
+    );
+    return this;
+  }
+  /** Declare a grant implied by this app's dependencies (`requires.grants`). */
+  requiredGrant(permission) {
+    this._requiredGrants.push(permission);
+    return this;
+  }
+  /**
+   * Declare an abstract **capability** edge (`requires.capabilities`) the broker
+   * resolves to a bound provider at enable time — e.g. `requiresCapability("rag")`.
+   * Distinct from a specific-plugin dependency: a capability edge lets the
+   * binding registry choose the provider. `minVersion` is a MINIMUM (`"1.2.0"`
+   * = `">=1.2.0"`).
+   */
+  requiresCapability(capability, minVersion) {
+    this._requiredCapabilities.push(
+      minVersion ? { capability, min_version: minVersion } : { capability }
+    );
+    return this;
+  }
+  /** Restrict this app to a host surface. No target = every surface. */
+  target(surface) {
+    this._targets.push(surface);
+    return this;
+  }
+  /**
+   * Validate and return the assembled `PluginManifest`. Throws an `Error` naming
+   * the failing field when validation fails.
+   */
+  build() {
+    const hasRequires = this._dependencies.length > 0 || this._requiredCapabilities.length > 0 || this._requiredGrants.length > 0;
+    const options = {
+      id: this._id,
+      title: this._title,
+      version: this._version,
+      slug: this._slug,
+      uiEntry: this._uiEntry,
+      tools: this._tools,
+      grants: this._grants,
+      ...this._server ? { server: this._server } : {},
+      ...this._displayMode ? { displayMode: this._displayMode } : {},
+      ...this._mime ? { mime: this._mime } : {},
+      ...this._activationEvents.length > 0 ? { activationEvents: this._activationEvents } : {},
+      ...hasRequires ? {
+        requires: {
+          apps: this._dependencies,
+          capabilities: this._requiredCapabilities,
+          grants: this._requiredGrants
+        }
+      } : {},
+      ...this._targets.length > 0 ? { targets: this._targets } : {}
+    };
+    return defineApp(options);
+  }
+};
+var app = () => new AppBuilder();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AgentBuilder,
+  AppBuilder,
+  PluginBuilder,
+  SkillBuilder,
+  ToolBuilder,
+  WorkflowBuilder,
+  agent,
+  app,
+  skill,
+  tool,
+  workflow
+});