@ryuhq/sdk 0.1.14 → 0.2.2

package/dist/{chunk-AO2KJRDD.js → chunk-NZKVOSC2.js}

@@ -146,8 +146,38 @@ var WidgetContributionSchema = z.object({
   /** Default display mode (`inline` | `fullscreen` | `pip`). */
   default_display_mode: z.string().default(DEFAULT_WIDGET_DISPLAY_MODE)
 });
+var ChatWidgetTemplateSchema = z.object({
+  id: z.string().regex(/^[a-z0-9][a-z0-9._:-]*$/),
+  title: z.string().min(1),
+  description: z.string().optional(),
+  triggers: z.array(z.string()).default([]),
+  examples: z.array(z.string()).default([]),
+  backing: z.object({
+    tool_id: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:/-]*$/).optional(),
+    view_id: z.string().regex(/^[a-z0-9][a-z0-9._:-]*$/).optional()
+  }),
+  display_mode: z.string().min(1),
+  safe_action_ids: z.array(z.string().regex(/^[a-z0-9][a-z0-9._-]*$/)).default([]),
+  availability: 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 = 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: 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
@@ -166,6 +196,33 @@ var ToolAppConfigSchema = z.object({
   /** Optional status label shown when the render tool finishes. */
   invoked: z.string().optional()
 });
+var SlashCommandOptionSchema = z.object({
+  description: z.string().optional(),
+  label: z.string().min(1),
+  value: z.string().min(1)
+}).passthrough();
+var SlashCommandCustomOptionSchema = z.union([
+  z.literal(true),
+  z.object({
+    description: z.string().optional(),
+    label: z.string().min(1).optional()
+  }).passthrough()
+]);
+var SlashCommandArgumentSchema = z.object({
+  allow_custom: z.boolean().optional(),
+  custom: SlashCommandCustomOptionSchema.optional(),
+  description: z.string().optional(),
+  name: z.string().min(1),
+  options: z.array(SlashCommandOptionSchema).optional()
+}).passthrough();
+var SlashCommandContributionSchema = z.object({
+  args: z.array(SlashCommandArgumentSchema).optional(),
+  body: z.string().optional(),
+  command: z.string().min(1),
+  description: z.string().optional(),
+  id: z.string().optional(),
+  parameters: z.array(SlashCommandArgumentSchema).optional()
+}).passthrough();
 var ContributesSchema = z.object({
   turn_hooks: z.array(TurnHookContributionSchema).default([]),
   /** App events this plugin EMITS — the provider half of the hook system, whose
@@ -174,13 +231,20 @@ var ContributesSchema = z.object({
    *  signing, leaving an app that emits events nothing is allowed to subscribe to. */
   hook_events: z.array(HookEventContributionSchema).default([]),
   composer_controls: z.array(z.record(z.string(), 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: z.array(z.record(z.string(), z.unknown())).default([]),
   settings_tabs: z.array(z.record(z.string(), z.unknown())).default([]),
-  slash_commands: z.array(z.record(z.string(), z.unknown())).default([]),
+  slash_commands: 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: z.array(WidgetContributionSchema).default([]),
+  /** Metadata-only chat widget templates. */
+  chat_widget_templates: 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
@@ -193,6 +257,13 @@ var ContributesSchema = z.object({
    *  Rust-side `Contributes.dock_panels`; without it the CLI's zod parse would
    *  strip the dock panel an app declares here. */
   dock_panels: z.array(z.record(z.string(), z.unknown())).default([]),
+  /** 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: z.array(z.record(z.string(), z.unknown())).default([]),
   /** Deletable data categories the app owns — one "Delete all X" row in Settings
    *  → Danger Zone. Mirrors the Rust-side `Contributes.data_categories`; without
    *  it the CLI's zod parse would strip the declaration before signing, and the
@@ -230,7 +301,13 @@ var ContributesSchema = 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: z.array(OutputStyleContributionSchema).default([])
+  output_styles: 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: z.array(z.record(z.string(), 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: z.array(z.record(z.string(), z.unknown())).default([])
 });
 var SetupStepSchema = z.object({
   /** Card heading (e.g. the companion app name). */
@@ -311,6 +388,61 @@ var EnginesReqSchema = z.object({
   /** Floor for the Next.js web app. */
   web: z.string().optional()
 });
+var McpServerAuthSchema = z.object({
+  client_id: z.string().min(1).optional(),
+  type: z.literal("oauth")
+}).strict();
+var McpServerDeclSchema = z.object({
+  args: z.array(z.string()).default([]),
+  auth: McpServerAuthSchema.optional(),
+  command: z.string().optional(),
+  command_env: z.string().optional(),
+  description: z.string().optional(),
+  enabled: z.boolean().default(true),
+  env: z.record(z.string(), z.string()).default({}),
+  headers: z.record(z.string(), z.string()).default({}),
+  type: z.enum(["stdio", "http", "streamable-http", "streamable_http", "sse"]).optional(),
+  url: 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 = z.object({
   /** Reverse-domain unique identifier (e.g. `"com.example.my-plugin"`). */
   id: z.string().min(1, "id is required"),
@@ -325,6 +457,9 @@ var PluginManifestSchema = 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: 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
@@ -342,6 +477,26 @@ var PluginManifestSchema = z.object({
    * Declarations only — grant enforcement is the Gateway's responsibility.
    */
   permission_grants: z.array(z.string()).default([]),
+  /** Deny-by-default sandbox permissions. Core remains authoritative; this
+   *  schema mirrors the fields so `ryu pack` cannot strip them. */
+  permissions: z.object({
+    fs: z.object({
+      read: z.array(z.string()).default([]),
+      write: z.array(z.string()).default([])
+    }).optional(),
+    child_process: z.boolean().optional(),
+    run: z.array(z.string()).default([]),
+    network: z.union([z.boolean(), z.array(z.string())]).optional(),
+    tool: z.array(z.string()).default([])
+  }).optional(),
+  /** Core-owned permission presentation levels. Preserved verbatim here and
+   *  validated by Core's authoritative manifest contract. */
+  permission_levels: z.unknown().optional(),
+  /** Remote or stdio MCP servers registered by this plugin. */
+  mcp_servers: z.record(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: z.unknown().optional(),
   /**
    * Optional Companion surface (an in-desktop overlay or sidebar panel).
    * Absent when the plugin has no Companion surface.
@@ -377,6 +532,9 @@ var PluginManifestSchema = z.object({
    * an unsupported-target plugin stays installable and inspectable.
    */
   targets: z.array(SurfaceSchema).default([]),
+  /** Rich per-surface declarations (`support`, UI, contributed commands, …).
+   *  Core owns and validates the nested vocabulary. */
+  surfaces: z.unknown().optional(),
   /**
    * Host version floors — the semver requirement each surface must satisfy for
    * this plugin to install. Mirrors Core's `EnginesReq`
@@ -435,10 +593,16 @@ var PluginManifestSchema = z.object({
       url: z.string().optional()
     })
   ]).optional(),
+  /** Public source repository URL (Claude/Codex `repository`). */
+  repository: z.string().url().optional(),
+  /** True when the provider operates outside the local Ryu runtime. */
+  external: z.boolean().optional(),
   /** Project/marketing homepage — maps to the listing `website` (Claude field). */
   homepage: z.string().optional(),
   /** Free-text search keywords (Claude field). */
   keywords: z.array(z.string()).optional(),
+  /** Stable Marketplace filter labels (Ryu extension). */
+  tags: z.array(z.string()).optional(),
   /** Taxonomy category beyond the runnable kinds (Claude field). */
   category: z.string().optional(),
   /** SPDX-ish license identifier (Claude field). */
@@ -452,6 +616,8 @@ var PluginManifestSchema = z.object({
    * from `iconUrl` (a raster logo). Falls back to `iconUrl` when omitted.
    */
   icon: z.string().optional(),
+  /** Optional detail-page hero banner metadata forwarded to the marketplace. */
+  banner: z.record(z.string(), 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
@@ -483,6 +649,22 @@ var PluginManifestSchema = z.object({
    * array of steps guiding the user through post-install configuration.
    */
   setup: z.union([SetupStepSchema, 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);
@@ -504,7 +686,12 @@ export {
   PiExtensionContributionSchema,
   OutputStyleContributionSchema,
   WidgetContributionSchema,
+  ChatWidgetTemplateSchema,
   ToolAppConfigSchema,
+  SlashCommandOptionSchema,
+  SlashCommandCustomOptionSchema,
+  SlashCommandArgumentSchema,
+  SlashCommandContributionSchema,
   ContributesSchema,
   SetupStepSchema,
   AppDependencySchema,
@@ -512,6 +699,8 @@ export {
   RequiresSchema,
   SurfaceSchema,
   EnginesReqSchema,
+  McpServerAuthSchema,
+  McpServerDeclSchema,
   PluginManifestSchema,
   validatePluginId,
   validateManifestStrict,

package/dist/chunk-QYFUNJOH.js

@@ -0,0 +1,83 @@
+// 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 }
+    }
+  };
+}
+
+export {
+  defineTool,
+  inlineToolRunnable
+};

package/dist/chunk-SN2QBJUF.js

@@ -0,0 +1,148 @@
+import {
+  inlineToolRunnable
+} from "./chunk-QYFUNJOH.js";
+import {
+  PluginManifestSchema
+} from "./chunk-NZKVOSC2.js";
+
+// 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;
+}
+
+export {
+  appToolId,
+  defineApp
+};

package/dist/chunk-TLDPEGC7.js

@@ -0,0 +1,21 @@
+// src/plugin/ryu-plugin.ts
+function toDisposable(teardown) {
+  let done = false;
+  return {
+    dispose() {
+      if (done) {
+        return;
+      }
+      done = true;
+      teardown();
+    }
+  };
+}
+function definePlugin(plugin) {
+  return plugin;
+}
+
+export {
+  toDisposable,
+  definePlugin
+};