@ryuhq/sdk 0.1.14 → 0.2.2

package/dist/index.cjs

@@ -37,6 +37,10 @@ __export(src_exports, {
   CapabilityReqSchema: () => CapabilityReqSchema,
   CompanionSurfaceSchema: () => CompanionSurfaceSchema,
   DEFAULT_GATEWAY_URL: () => DEFAULT_GATEWAY_URL,
+  MCP_PROTOCOL_VERSION: () => MCP_PROTOCOL_VERSION,
+  McpServer: () => McpServer,
+  McpServerAuthSchema: () => McpServerAuthSchema,
+  McpServerDeclSchema: () => McpServerDeclSchema,
   ModelClient: () => ModelClient2,
   PRIMITIVE_BINDINGS: () => PRIMITIVE_BINDINGS,
   PluginBuilder: () => PluginBuilder,
@@ -45,6 +49,10 @@ __export(src_exports, {
   RunnableKindSchema: () => RunnableKindSchema,
   RunnableMetaSchema: () => RunnableMetaSchema,
   SkillBuilder: () => SkillBuilder,
+  SlashCommandArgumentSchema: () => SlashCommandArgumentSchema,
+  SlashCommandContributionSchema: () => SlashCommandContributionSchema,
+  SlashCommandCustomOptionSchema: () => SlashCommandCustomOptionSchema,
+  SlashCommandOptionSchema: () => SlashCommandOptionSchema,
   SurfaceSchema: () => SurfaceSchema,
   ToolAppConfigSchema: () => ToolAppConfigSchema,
   ToolBuilder: () => ToolBuilder,
@@ -54,9 +62,11 @@ __export(src_exports, {
   app: () => app,
   appToolId: () => appToolId,
   assertAllowedEgressUrl: () => assertAllowedEgressUrl,
+  callTool: () => callTool,
   coreManifestJsonSchema: () => coreManifestJsonSchema,
   createAgent: () => createAgent,
   createPrimitives: () => createPrimitives,
+  defineAction: () => defineAction,
   defineAgent: () => defineAgent,
   defineApp: () => defineApp,
   defineModel: () => defineModel,
@@ -67,19 +77,22 @@ __export(src_exports, {
   defineWorkflow: () => defineWorkflow,
   httpPrimitiveTransport: () => httpPrimitiveTransport,
   inlineToolRunnable: () => inlineToolRunnable,
+  listTools: () => listTools,
   query: () => query,
   resolveGatewayToken: () => resolveGatewayToken2,
   resolveGatewayUrl: () => resolveGatewayUrl3,
   ryuTool: () => ryuTool,
   skill: () => skill,
+  toDisposable: () => toDisposable,
   tool: () => tool,
+  unwrapContent: () => unwrapContent,
   validateManifestStrict: () => validateManifestStrict,
   validatePluginId: () => validatePluginId,
   workflow: () => workflow
 });
 module.exports = __toCommonJS(src_exports);
 
-// ../../node_modules/.bun/tsup@8.5.1+7a7b737fa55947b7/node_modules/tsup/assets/cjs_shims.js
+// ../../node_modules/.bun/tsup@8.5.1+68ce2442ac00f52e/node_modules/tsup/assets/cjs_shims.js
 var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
 var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
 
@@ -317,6 +330,41 @@ var PRIMITIVE_BINDINGS = {
     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",
@@ -350,6 +398,22 @@ function brokerCall(transport, 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),
@@ -976,8 +1040,38 @@ var WidgetContributionSchema = import_zod.z.object({
   /** 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. */
+  /** 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
@@ -996,6 +1090,33 @@ var ToolAppConfigSchema = import_zod.z.object({
   /** 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
@@ -1004,13 +1125,20 @@ var ContributesSchema = import_zod.z.object({
    *  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([]),
+  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
@@ -1023,6 +1151,13 @@ var ContributesSchema = import_zod.z.object({
    *  Rust-side `Contributes.dock_panels`; without it the CLI's zod parse would
    *  strip the dock panel an app declares here. */
   dock_panels: import_zod.z.array(import_zod.z.record(import_zod.z.string(), import_zod.z.unknown())).default([]),
+  /** 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
@@ -1060,7 +1195,13 @@ var ContributesSchema = import_zod.z.object({
    *  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([])
+  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). */
@@ -1141,6 +1282,61 @@ var EnginesReqSchema = import_zod.z.object({
   /** 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"),
@@ -1155,6 +1351,9 @@ var PluginManifestSchema = import_zod.z.object({
     /^\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
@@ -1172,6 +1371,26 @@ var PluginManifestSchema = import_zod.z.object({
    * 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.
@@ -1207,6 +1426,9 @@ var PluginManifestSchema = import_zod.z.object({
    * 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`
@@ -1265,10 +1487,16 @@ var PluginManifestSchema = import_zod.z.object({
       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). */
@@ -1282,6 +1510,8 @@ var PluginManifestSchema = import_zod.z.object({
    * 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
@@ -1313,6 +1543,22 @@ var PluginManifestSchema = import_zod.z.object({
    * 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"]
+      });
+    }
+  }
 });
 function validatePluginId(id) {
   loadNative().validatePluginId(id);
@@ -1324,6 +1570,85 @@ function coreManifestJsonSchema() {
   return JSON.parse(loadNative().pluginManifestJsonSchema());
 }
 
+// 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(tool2, options) {
+  return {
+    id: tool2.id,
+    name: tool2.name,
+    kind: "tool",
+    config: {
+      slug: tool2.id,
+      backend: "inline_deno",
+      code: tool2.code,
+      input_schema: tool2.schema,
+      ...options?.description === void 0 ? tool2.description === void 0 ? {} : { description: tool2.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/app.ts
 var DEFAULT_APP_WIDGET_MIME = "text/html+skybridge";
 var DEFAULT_APP_DISPLAY_MODE = "inline";
@@ -1335,8 +1660,15 @@ function withWidgetRenderGrant(grants, widgets) {
   }
   return out;
 }
+function withToolExecuteGrant(grants, tools) {
+  const out = [...grants];
+  if (tools.some((tool2) => tool2.runnable !== void 0) && !out.includes("tool:execute")) {
+    out.push("tool:execute");
+  }
+  return out;
+}
 function appToolId(server, name) {
-  return `${server}__${name}`;
+  return `${server}.${name}`;
 }
 function defineApp(options) {
   const server = options.server ?? options.slug;
@@ -1349,7 +1681,9 @@ function defineApp(options) {
   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,
@@ -1376,16 +1710,18 @@ function defineApp(options) {
   }
   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: [],
+    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
@@ -1398,6 +1734,8 @@ function defineApp(options) {
     data_categories: [],
     pi_extensions: [],
     output_styles: [],
+    message_actions: [],
+    selection_actions: [],
     widgets
   };
   const raw = {
@@ -1411,15 +1749,15 @@ function defineApp(options) {
     // 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.
+    // 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: withWidgetRenderGrant(options.grants ?? [], widgets),
+    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
@@ -1660,6 +1998,7 @@ var AppBuilder = class {
   _dependencies = [];
   _requiredCapabilities = [];
   _requiredGrants = [];
+  _slashCommands = [];
   _targets = [];
   /** Set the reverse-domain app id (e.g. `"com.example.checklist"`). */
   id(value) {
@@ -1716,6 +2055,11 @@ var AppBuilder = class {
     this._tools.push(spec);
     return this;
   }
+  /** Add a slash command and its optional sequential argument choices. */
+  slashCommand(command) {
+    this._slashCommands.push(command);
+    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"`).
@@ -1763,6 +2107,7 @@ var AppBuilder = class {
       uiEntry: this._uiEntry,
       tools: this._tools,
       grants: this._grants,
+      slashCommands: this._slashCommands,
       ...this._server ? { server: this._server } : {},
       ...this._displayMode ? { displayMode: this._displayMode } : {},
       ...this._mime ? { mime: this._mime } : {},
@@ -1781,6 +2126,442 @@ var AppBuilder = class {
 };
 var app = () => new AppBuilder();
 
+// src/mcp/client.ts
+var import_node_child_process = require("child_process");
+var import_node_readline = require("readline");
+var MCP_PROTOCOL_VERSION = "2024-11-05";
+var RPC_TIMEOUT_MS = 6e4;
+var McpConnection = class _McpConnection {
+  proc;
+  nextId = 1;
+  closed = false;
+  waiters = [];
+  constructor(proc) {
+    this.proc = proc;
+  }
+  /** Spawn the server and complete the MCP `initialize` handshake. */
+  static async connect(cmd) {
+    const env2 = { ...process.env, ...cmd.env ?? {} };
+    const proc = (0, import_node_child_process.spawn)(cmd.command, cmd.args ?? [], {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: env2
+    });
+    if (!(proc.stdin && proc.stdout)) {
+      proc.kill();
+      throw new Error(`MCP server '${cmd.command}' stdin/stdout unavailable`);
+    }
+    if (proc.stderr) {
+      proc.stderr.on("data", (chunk) => {
+        process.stderr.write(`[mcp-server] ${chunk.toString()}`);
+      });
+    }
+    const conn = new _McpConnection(proc);
+    const rl = (0, import_node_readline.createInterface)({
+      input: proc.stdout,
+      crlfDelay: Number.POSITIVE_INFINITY
+    });
+    rl.on("line", (rawLine) => {
+      const trimmed = rawLine.trim();
+      if (!trimmed) {
+        return;
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(trimmed);
+      } catch {
+        return;
+      }
+      if (parsed.id === void 0 || parsed.id === null) {
+        return;
+      }
+      const idx = conn.waiters.findIndex((w) => w.id === parsed.id);
+      if (idx === -1) {
+        return;
+      }
+      const [waiter] = conn.waiters.splice(idx, 1);
+      if (!waiter) {
+        return;
+      }
+      clearTimeout(waiter.timer);
+      if (parsed.error) {
+        waiter.reject(new Error(`MCP error: ${JSON.stringify(parsed.error)}`));
+      } else {
+        waiter.resolve(parsed.result ?? null);
+      }
+    });
+    rl.on("close", () => {
+      for (const waiter of conn.waiters.splice(0)) {
+        clearTimeout(waiter.timer);
+        waiter.reject(new Error("MCP server closed the connection"));
+      }
+    });
+    await conn.request("initialize", {
+      protocolVersion: MCP_PROTOCOL_VERSION,
+      capabilities: {},
+      clientInfo: { name: "ryu-sdk", version: "0.0.1" }
+    });
+    conn.notify("notifications/initialized", {});
+    return conn;
+  }
+  /** Send a JSON-RPC request and return the `result` field. */
+  request(method, params) {
+    const id = this.nextId++;
+    const frame = JSON.stringify({
+      jsonrpc: "2.0",
+      id,
+      method,
+      params
+    });
+    this.write(frame);
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new Error(`MCP request '${method}' timed out`)),
+        RPC_TIMEOUT_MS
+      );
+      this.waiters.push({ id, resolve, reject, timer });
+    });
+  }
+  /** Send a JSON-RPC notification (no response expected). */
+  notify(method, params) {
+    const frame = JSON.stringify({ jsonrpc: "2.0", method, params });
+    this.write(frame);
+  }
+  write(frame) {
+    if (this.closed) {
+      return;
+    }
+    this.proc.stdin?.write(`${frame}
+`);
+  }
+  /** Graceful shutdown: close stdin, then kill. */
+  async shutdown() {
+    this.closed = true;
+    this.proc.stdin?.end();
+    await new Promise((resolve) => {
+      this.proc.once("exit", () => resolve());
+      this.proc.kill();
+      setTimeout(resolve, 500);
+    });
+  }
+};
+async function listTools(cmd) {
+  const conn = await McpConnection.connect(cmd);
+  let result;
+  try {
+    result = await conn.request("tools/list", {});
+  } finally {
+    await conn.shutdown();
+  }
+  const tools = result?.tools ?? [];
+  return tools.map((t) => {
+    const tool2 = t;
+    const name = tool2.name;
+    if (typeof name !== "string") {
+      return null;
+    }
+    return {
+      name,
+      description: typeof tool2.description === "string" ? tool2.description : void 0,
+      inputSchema: tool2.inputSchema
+    };
+  }).filter((t) => t !== null);
+}
+async function callTool(cmd, tool2, args) {
+  const conn = await McpConnection.connect(cmd);
+  try {
+    return await conn.request("tools/call", { name: tool2, arguments: args });
+  } finally {
+    await conn.shutdown();
+  }
+}
+
+// src/mcp/server.ts
+var import_node_readline2 = require("readline");
+function respond(id, result) {
+  return { jsonrpc: "2.0", id: id ?? null, result };
+}
+function respondError(id, code, message) {
+  return { jsonrpc: "2.0", id: id ?? null, error: { code, message } };
+}
+function wrapContent(value) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: typeof value === "string" ? value : JSON.stringify(value)
+      }
+    ]
+  };
+}
+function unwrapContent(raw) {
+  const r = raw;
+  const text = r?.content?.[0]?.text;
+  if (text === void 0) {
+    return raw;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+var McpServer = class {
+  runnables = /* @__PURE__ */ new Map();
+  passthroughs = [];
+  /**
+   * Register an SDK Runnable as an MCP tool.
+   * Returns `this` for chaining.
+   */
+  register(runnable) {
+    this.runnables.set(runnable.name, runnable);
+    return this;
+  }
+  /**
+   * Register a passthrough to an external MCP stdio server (e.g. Ghost or
+   * Shadow).  Tools from that server are fetched lazily and re-advertised.
+   * Returns `this` for chaining.
+   */
+  passthrough(registration) {
+    this.passthroughs.push(registration);
+    return this;
+  }
+  /** Fetch all tools: local Runnables + passthrough tools. */
+  async allTools() {
+    const local = [...this.runnables.values()].map((r) => ({
+      name: r.name,
+      description: r.description,
+      inputSchema: r.inputSchema
+    }));
+    const remote = [];
+    for (const pt of this.passthroughs) {
+      try {
+        const tools = await listTools(pt.command);
+        remote.push(...tools);
+      } catch (err) {
+        process.stderr.write(
+          `[mcp-server] passthrough '${pt.label}' list_tools failed: ${err}
+`
+        );
+      }
+    }
+    return [...local, ...remote];
+  }
+  /** Handle a `tools/call` request. */
+  async handleCallTool(name, args) {
+    const local = this.runnables.get(name);
+    if (local) {
+      const result = await local.run(args);
+      return wrapContent(result);
+    }
+    for (const pt of this.passthroughs) {
+      try {
+        const tools = await listTools(pt.command);
+        if (tools.some((t) => t.name === name)) {
+          return await callTool(pt.command, name, args);
+        }
+      } catch {
+      }
+    }
+    throw new Error(`Unknown tool: ${name}`);
+  }
+  /**
+   * Handle a single parsed JSON-RPC request line. Returns the response to write
+   * (or null for notifications that require no response).
+   */
+  async handleRequest(req, initialized, write) {
+    const { id, method, params } = req;
+    if (method === "initialize") {
+      initialized.value = true;
+      write(
+        respond(id, {
+          protocolVersion: MCP_PROTOCOL_VERSION,
+          capabilities: { tools: {} },
+          serverInfo: { name: "ryu-sdk-server", version: "0.0.1" }
+        })
+      );
+      return;
+    }
+    if (method === "notifications/initialized") {
+      return;
+    }
+    if (!initialized.value) {
+      write(respondError(id, -32002, "Server not initialized"));
+      return;
+    }
+    if (method === "tools/list") {
+      try {
+        const tools = await this.allTools();
+        write(respond(id, { tools }));
+      } catch (err) {
+        write(respondError(id, -32603, String(err)));
+      }
+      return;
+    }
+    if (method === "tools/call") {
+      await this.handleToolsCall(id, params, write);
+      return;
+    }
+    write(respondError(id, -32601, `Method not found: ${method}`));
+  }
+  /** Handle a `tools/call` JSON-RPC request. */
+  async handleToolsCall(id, params, write) {
+    const p = params;
+    const toolName = p?.name;
+    const toolArgs = p?.arguments ?? {};
+    if (typeof toolName !== "string") {
+      write(respondError(id, -32602, "tools/call requires 'name'"));
+      return;
+    }
+    try {
+      const result = await this.handleCallTool(toolName, toolArgs);
+      write(respond(id, result));
+    } catch (err) {
+      write(
+        respond(id, {
+          content: [{ type: "text", text: String(err) }],
+          isError: true
+        })
+      );
+    }
+  }
+  /**
+   * Start reading JSON-RPC requests from the given readable stream and writing
+   * responses to the given writable stream.
+   *
+   * Defaults to `process.stdin` / `process.stdout`.  Passing explicit streams
+   * lets tests inject a pair of in-process pipes.
+   *
+   * Resolves when the input stream ends (EOF).
+   */
+  serve(input = process.stdin, output = process.stdout) {
+    const write = (obj) => {
+      output.write(`${JSON.stringify(obj)}
+`);
+    };
+    const initialized = { value: false };
+    return new Promise((resolve) => {
+      const rl = (0, import_node_readline2.createInterface)({
+        input,
+        crlfDelay: Number.POSITIVE_INFINITY
+      });
+      rl.on("line", (rawLine) => {
+        const line = rawLine.trim();
+        if (!line) {
+          return;
+        }
+        let req;
+        try {
+          req = JSON.parse(line);
+        } catch {
+          write(respondError(null, -32700, "Parse error"));
+          return;
+        }
+        this.handleRequest(req, initialized, write).catch((err) => {
+          write(respondError(req.id, -32603, String(err)));
+        });
+      });
+      rl.on("close", resolve);
+    });
+  }
+};
+
+// src/plugin/ryu-plugin.ts
+function toDisposable(teardown) {
+  let done = false;
+  return {
+    dispose() {
+      if (done) {
+        return;
+      }
+      done = true;
+      teardown();
+    }
+  };
+}
+
+// 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 tool2 = defineTool({
+    description: options.description,
+    id: options.id,
+    name: options.name,
+    run: options.run,
+    schema: options.schema
+  });
+  const action = {
+    ...tool2,
+    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) {
@@ -1925,80 +2706,6 @@ function defineSkill(options) {
   };
 }
 
-// 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 { id, name, schema, run } = options;
-  const code = `return await (${run.toString()})(input, host);`;
-  return {
-    id,
-    name,
-    kind: "tool",
-    schema,
-    code,
-    run(input, ctx) {
-      validateInput(input, schema, id);
-      return run(input, ctx);
-    }
-  };
-}
-function inlineToolRunnable(tool2, options) {
-  return {
-    id: tool2.id,
-    name: tool2.name,
-    kind: "tool",
-    config: {
-      slug: tool2.id,
-      backend: "inline_deno",
-      code: tool2.code,
-      input_schema: tool2.schema,
-      ...options?.description ? { description: options.description } : {}
-    }
-  };
-}
-
 // src/runnable/turn-hook.ts
 function defineTurnHook(options) {
   const source = options.run.toString();
@@ -2014,6 +2721,7 @@ function definePlugin(options) {
     turn_hooks: options.turnHooks ?? [],
     hook_events: options.hookEvents ?? [],
     composer_controls: options.composerControls ?? [],
+    chat_features: [],
     settings_tabs: options.settingsTabs ?? [],
     slash_commands: options.slashCommands ?? [],
     lsp_servers: options.lspServers ?? {},
@@ -2025,9 +2733,12 @@ function definePlugin(options) {
     sidebar_sections: [],
     sidebar_buttons: [],
     dock_panels: [],
+    live_activities: [],
     data_categories: [],
     pi_extensions: [],
-    output_styles: []
+    output_styles: [],
+    message_actions: [],
+    selection_actions: []
   };
   const tools = options.tools ?? [];
   const runnables = tools.map((t) => inlineToolRunnable(t));
@@ -2076,6 +2787,10 @@ function defineWorkflow(options) {
   CapabilityReqSchema,
   CompanionSurfaceSchema,
   DEFAULT_GATEWAY_URL,
+  MCP_PROTOCOL_VERSION,
+  McpServer,
+  McpServerAuthSchema,
+  McpServerDeclSchema,
   ModelClient,
   PRIMITIVE_BINDINGS,
   PluginBuilder,
@@ -2084,6 +2799,10 @@ function defineWorkflow(options) {
   RunnableKindSchema,
   RunnableMetaSchema,
   SkillBuilder,
+  SlashCommandArgumentSchema,
+  SlashCommandContributionSchema,
+  SlashCommandCustomOptionSchema,
+  SlashCommandOptionSchema,
   SurfaceSchema,
   ToolAppConfigSchema,
   ToolBuilder,
@@ -2093,9 +2812,11 @@ function defineWorkflow(options) {
   app,
   appToolId,
   assertAllowedEgressUrl,
+  callTool,
   coreManifestJsonSchema,
   createAgent,
   createPrimitives,
+  defineAction,
   defineAgent,
   defineApp,
   defineModel,
@@ -2106,12 +2827,15 @@ function defineWorkflow(options) {
   defineWorkflow,
   httpPrimitiveTransport,
   inlineToolRunnable,
+  listTools,
   query,
   resolveGatewayToken,
   resolveGatewayUrl,
   ryuTool,
   skill,
+  toDisposable,
   tool,
+  unwrapContent,
   validateManifestStrict,
   validatePluginId,
   workflow