@ryuhq/sdk 0.2.0 → 0.2.2

package/dist/chunk-4TPUZDTI.js

@@ -0,0 +1,94 @@
+import {
+  defineTool,
+  inlineToolRunnable
+} from "./chunk-QYFUNJOH.js";
+import {
+  PluginManifestSchema
+} from "./chunk-NZKVOSC2.js";
+
+// src/runnable/action.ts
+function deriveAnnotations(effect, annotations) {
+  const resolved = {
+    ...annotations,
+    readOnlyHint: annotations?.readOnlyHint ?? effect === "read",
+    destructiveHint: annotations?.destructiveHint ?? effect === "mutate"
+  };
+  if (effect === "read" && resolved.destructiveHint) {
+    throw new Error(
+      "[ryu-sdk] read actions cannot set annotations.destructiveHint=true"
+    );
+  }
+  if (effect === "mutate" && resolved.readOnlyHint) {
+    throw new Error(
+      "[ryu-sdk] mutate actions cannot set annotations.readOnlyHint=true"
+    );
+  }
+  return resolved;
+}
+function actionManifestEntry(action) {
+  const options = {
+    action: true,
+    annotations: action.annotations,
+    description: action.description,
+    needsApproval: action.needsApproval,
+    ...action.outputSchema ? { outputSchema: action.outputSchema } : {}
+  };
+  return inlineToolRunnable(action, options);
+}
+function actionToManifest(action, options) {
+  const grants = [.../* @__PURE__ */ new Set([...options.grants ?? [], "tool:execute"])];
+  const raw = {
+    id: options.id,
+    name: options.name ?? action.name,
+    version: options.version,
+    runnables: [actionManifestEntry(action)],
+    permission_grants: grants,
+    activation_events: [...options.activationEvents ?? ["*"]],
+    targets: [...options.targets ?? []]
+  };
+  const result = PluginManifestSchema.safeParse(raw);
+  if (!result.success) {
+    const first = result.error.issues[0];
+    const field = first?.path.join(".") ?? "unknown";
+    const message = first?.message ?? "validation failed";
+    throw new Error(
+      `[ryu-sdk] action manifest validation failed at '${field}': ${message}`
+    );
+  }
+  return result.data;
+}
+function defineAction(options) {
+  const annotations = deriveAnnotations(options.effect, options.annotations);
+  const tool = defineTool({
+    description: options.description,
+    id: options.id,
+    name: options.name,
+    run: options.run,
+    schema: options.schema
+  });
+  const action = {
+    ...tool,
+    action: true,
+    annotations,
+    description: options.description,
+    effect: options.effect,
+    needsApproval: options.needsApproval ?? false,
+    ...options.outputSchema ? { outputSchema: options.outputSchema } : {},
+    toManifest(manifestOptions) {
+      return actionToManifest(action, manifestOptions);
+    },
+    toMcpTool(context) {
+      return {
+        name: action.id,
+        description: action.description,
+        inputSchema: action.schema,
+        run: (input) => action.run(input, context)
+      };
+    }
+  };
+  return action;
+}
+
+export {
+  defineAction
+};

package/dist/{chunk-T5676WL2.js → chunk-BC3A7HMO.js}

@@ -1,6 +1,6 @@
 import {
   PluginManifestSchema
-} from "./chunk-IEUQ3CDG.js";
+} from "./chunk-NZKVOSC2.js";
 
 // src/runnable/agent.ts
 var CAPABILITY_SLOTS = ["rag", "memory", "tts", "stt"];
@@ -146,80 +146,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(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 ? { description: options.description } : {}
-    }
-  };
-}
-
 // src/runnable/workflow.ts
 function defineWorkflow(options) {
   const { id, name, run } = options;
@@ -234,7 +160,5 @@ function defineWorkflow(options) {
 export {
   defineAgent,
   defineSkill,
-  defineTool,
-  inlineToolRunnable,
   defineWorkflow
 };

package/dist/{chunk-IOLP5FFE.js → chunk-HLKJZAFK.js}

@@ -1,10 +1,10 @@
 import {
   defineApp
-} from "./chunk-W3KPP4WN.js";
+} from "./chunk-SN2QBJUF.js";
 import {
   PluginManifestSchema,
   RunnableMetaSchema
-} from "./chunk-IEUQ3CDG.js";
+} from "./chunk-NZKVOSC2.js";
 
 // src/builder.ts
 var RunnableBuilder = class {
@@ -218,6 +218,7 @@ var AppBuilder = class {
   _dependencies = [];
   _requiredCapabilities = [];
   _requiredGrants = [];
+  _slashCommands = [];
   _targets = [];
   /** Set the reverse-domain app id (e.g. `"com.example.checklist"`). */
   id(value) {
@@ -274,6 +275,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"`).
@@ -321,6 +327,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 } : {},

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

@@ -162,10 +162,18 @@ var ChatWidgetTemplateSchema = z.object({
 }).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" });
+    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" });
+    ctx.addIssue({
+      code: "custom",
+      path: ["backing"],
+      message: "backing must declare at most one of tool_id or view_id"
+    });
   }
 });
 var ToolAppConfigSchema = z.object({
@@ -188,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
@@ -202,7 +237,7 @@ var ContributesSchema = z.object({
    * 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
@@ -269,7 +304,10 @@ var ContributesSchema = z.object({
   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([])
+  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). */
@@ -419,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
@@ -436,8 +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.
@@ -473,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`
@@ -587,7 +649,7 @@ var PluginManifestSchema = z.object({
    * array of steps guiding the user through post-install configuration.
    */
   setup: z.union([SetupStepSchema, z.array(SetupStepSchema)]).optional()
-}).superRefine((manifest, context) => {
+}).passthrough().superRefine((manifest, context) => {
   const hasOAuthServer = Object.values(manifest.mcp_servers ?? {}).some(
     (server) => server.auth?.type === "oauth"
   );
@@ -626,6 +688,10 @@ export {
   WidgetContributionSchema,
   ChatWidgetTemplateSchema,
   ToolAppConfigSchema,
+  SlashCommandOptionSchema,
+  SlashCommandCustomOptionSchema,
+  SlashCommandArgumentSchema,
+  SlashCommandContributionSchema,
   ContributesSchema,
   SetupStepSchema,
   AppDependencySchema,

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-W3KPP4WN.js → chunk-SN2QBJUF.js}

@@ -1,6 +1,9 @@
+import {
+  inlineToolRunnable
+} from "./chunk-QYFUNJOH.js";
 import {
   PluginManifestSchema
-} from "./chunk-IEUQ3CDG.js";
+} from "./chunk-NZKVOSC2.js";
 
 // src/runnable/app.ts
 var DEFAULT_APP_WIDGET_MIME = "text/html+skybridge";
@@ -13,6 +16,13 @@ function withWidgetRenderGrant(grants, widgets) {
   }
   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}`;
 }
@@ -27,7 +37,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,
@@ -61,7 +73,7 @@ function defineApp(options) {
     hook_events: [],
     composer_controls: [],
     settings_tabs: [],
-    slash_commands: [],
+    slash_commands: options.slashCommands ?? [],
     sidebar_sections: [],
     sidebar_buttons: [],
     dock_panels: [],
@@ -79,6 +91,7 @@ function defineApp(options) {
     pi_extensions: [],
     output_styles: [],
     message_actions: [],
+    selection_actions: [],
     widgets
   };
   const raw = {
@@ -92,15 +105,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

package/dist/{chunk-ULSVL7EC.js → chunk-Z57QDDJR.js}

@@ -1,7 +1,7 @@
 import {
   createPrimitives,
   httpPrimitiveTransport
-} from "./chunk-A3RGEPDG.js";
+} from "./chunk-ZTJWBRUL.js";
 import {
   defineModel
 } from "./chunk-HACAGK65.js";

package/dist/{chunk-A3RGEPDG.js → chunk-ZTJWBRUL.js}

@@ -154,6 +154,31 @@ var PRIMITIVE_BINDINGS = {
     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",
@@ -196,6 +221,13 @@ function createPrimitives(transport) {
         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),