@ryuhq/sdk 0.2.0 → 0.2.3

package/dist/runnable.cjs

@@ -33,6 +33,7 @@ __export(runnable_exports, {
   PRIMITIVE_BINDINGS: () => PRIMITIVE_BINDINGS,
   appToolId: () => appToolId,
   createPrimitives: () => createPrimitives,
+  defineAction: () => defineAction,
   defineAgent: () => defineAgent,
   defineApp: () => defineApp,
   defineSkill: () => defineSkill,
@@ -185,10 +186,18 @@ var ChatWidgetTemplateSchema = import_zod.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 = import_zod.z.object({
@@ -211,6 +220,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
@@ -225,7 +261,7 @@ var ContributesSchema = import_zod.z.object({
    * 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
@@ -292,7 +328,10 @@ var ContributesSchema = import_zod.z.object({
   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([])
+  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). */
@@ -442,6 +481,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
@@ -459,8 +501,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.
@@ -496,6 +556,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`
@@ -610,7 +673,7 @@ 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()
-}).superRefine((manifest, context) => {
+}).passthrough().superRefine((manifest, context) => {
   const hasOAuthServer = Object.values(manifest.mcp_servers ?? {}).some(
     (server) => server.auth?.type === "oauth"
   );
@@ -628,6 +691,168 @@ var PluginManifestSchema = import_zod.z.object({
   }
 });
 
+// src/runnable/tool.ts
+function validateInput(input, schema, toolId) {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    throw new Error(
+      `[ryu-sdk] Tool "${toolId}" input must be an object, got ${JSON.stringify(input)}`
+    );
+  }
+  const record = input;
+  for (const requiredKey of schema.required ?? []) {
+    if (!(requiredKey in record)) {
+      throw new Error(
+        `[ryu-sdk] Tool "${toolId}" input missing required field "${requiredKey}"`
+      );
+    }
+  }
+  for (const [key, prop] of Object.entries(schema.properties)) {
+    if (!(key in record)) {
+      continue;
+    }
+    const value = record[key];
+    if (!checkType(value, prop.type)) {
+      throw new Error(
+        `[ryu-sdk] Tool "${toolId}" input field "${key}" expected type "${prop.type}", got ${JSON.stringify(value)}`
+      );
+    }
+  }
+}
+function checkType(value, type) {
+  switch (type) {
+    case "string":
+      return typeof value === "string";
+    case "number":
+    case "integer":
+      return typeof value === "number";
+    case "boolean":
+      return typeof value === "boolean";
+    case "array":
+      return Array.isArray(value);
+    case "object":
+      return typeof value === "object" && value !== null && !Array.isArray(value);
+    default:
+      return false;
+  }
+}
+function defineTool(options) {
+  const { description, id, name, schema, run } = options;
+  const code = `return await (${run.toString()})(input, host);`;
+  return {
+    id,
+    name,
+    kind: "tool",
+    schema,
+    ...description === void 0 ? {} : { description },
+    code,
+    run(input, ctx) {
+      validateInput(input, schema, id);
+      return run(input, ctx);
+    }
+  };
+}
+function inlineToolRunnable(tool, options) {
+  return {
+    id: tool.id,
+    name: tool.name,
+    kind: "tool",
+    config: {
+      slug: tool.id,
+      backend: "inline_deno",
+      code: tool.code,
+      input_schema: tool.schema,
+      ...options?.description === void 0 ? tool.description === void 0 ? {} : { description: tool.description } : { description: options.description },
+      ...options?.outputSchema ? { output_schema: options.outputSchema } : {},
+      ...options?.annotations ? { annotations: options.annotations } : {},
+      ...options?.action === void 0 ? {} : { action: options.action },
+      ...options?.needsApproval === void 0 ? {} : { needs_approval: options.needsApproval }
+    }
+  };
+}
+
+// src/runnable/action.ts
+function deriveAnnotations(effect, annotations) {
+  const resolved = {
+    ...annotations,
+    readOnlyHint: annotations?.readOnlyHint ?? effect === "read",
+    destructiveHint: annotations?.destructiveHint ?? effect === "mutate"
+  };
+  if (effect === "read" && resolved.destructiveHint) {
+    throw new Error(
+      "[ryu-sdk] read actions cannot set annotations.destructiveHint=true"
+    );
+  }
+  if (effect === "mutate" && resolved.readOnlyHint) {
+    throw new Error(
+      "[ryu-sdk] mutate actions cannot set annotations.readOnlyHint=true"
+    );
+  }
+  return resolved;
+}
+function actionManifestEntry(action) {
+  const options = {
+    action: true,
+    annotations: action.annotations,
+    description: action.description,
+    needsApproval: action.needsApproval,
+    ...action.outputSchema ? { outputSchema: action.outputSchema } : {}
+  };
+  return inlineToolRunnable(action, options);
+}
+function actionToManifest(action, options) {
+  const grants = [.../* @__PURE__ */ new Set([...options.grants ?? [], "tool:execute"])];
+  const raw = {
+    id: options.id,
+    name: options.name ?? action.name,
+    version: options.version,
+    runnables: [actionManifestEntry(action)],
+    permission_grants: grants,
+    activation_events: [...options.activationEvents ?? ["*"]],
+    targets: [...options.targets ?? []]
+  };
+  const result = PluginManifestSchema.safeParse(raw);
+  if (!result.success) {
+    const first = result.error.issues[0];
+    const field = first?.path.join(".") ?? "unknown";
+    const message = first?.message ?? "validation failed";
+    throw new Error(
+      `[ryu-sdk] action manifest validation failed at '${field}': ${message}`
+    );
+  }
+  return result.data;
+}
+function defineAction(options) {
+  const annotations = deriveAnnotations(options.effect, options.annotations);
+  const tool = defineTool({
+    description: options.description,
+    id: options.id,
+    name: options.name,
+    run: options.run,
+    schema: options.schema
+  });
+  const action = {
+    ...tool,
+    action: true,
+    annotations,
+    description: options.description,
+    effect: options.effect,
+    needsApproval: options.needsApproval ?? false,
+    ...options.outputSchema ? { outputSchema: options.outputSchema } : {},
+    toManifest(manifestOptions) {
+      return actionToManifest(action, manifestOptions);
+    },
+    toMcpTool(context) {
+      return {
+        name: action.id,
+        description: action.description,
+        inputSchema: action.schema,
+        run: (input) => action.run(input, context)
+      };
+    }
+  };
+  return action;
+}
+
 // src/runnable/agent.ts
 var CAPABILITY_SLOTS = ["rag", "memory", "tts", "stt"];
 function lowerChatSlot(chat) {
@@ -772,6 +997,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}`;
 }
@@ -786,7 +1018,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,
@@ -820,7 +1054,7 @@ function defineApp(options) {
     hook_events: [],
     composer_controls: [],
     settings_tabs: [],
-    slash_commands: [],
+    slash_commands: options.slashCommands ?? [],
     sidebar_sections: [],
     sidebar_buttons: [],
     dock_panels: [],
@@ -838,6 +1072,7 @@ function defineApp(options) {
     pi_extensions: [],
     output_styles: [],
     message_actions: [],
+    selection_actions: [],
     widgets
   };
   const raw = {
@@ -851,15 +1086,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
@@ -1046,6 +1281,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",
@@ -1088,6 +1348,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),
@@ -1146,66 +1413,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);
-    }
-  };
-}
-
 // src/runnable/workflow.ts
 function defineWorkflow(options) {
   const { id, name, run } = options;
@@ -1221,6 +1428,7 @@ function defineWorkflow(options) {
   PRIMITIVE_BINDINGS,
   appToolId,
   createPrimitives,
+  defineAction,
   defineAgent,
   defineApp,
   defineSkill,

package/dist/runnable.d.cts

@@ -1,7 +1,10 @@
+export { ActionAnnotations, ActionEffect, ActionManifestOptions, ActionOptions, ActionRunnable, defineAction } from './action.cjs';
 import { CapabilityReq, PluginManifest } from './manifest.cjs';
-import { i as Runnable, j as RunnableContext } from './tool-u-VR0fLF.cjs';
-export { B as BackgroundClient, a as BackgroundProcess, D as DurableClient, E as EnginesClient, G as GatewayClient, H as HttpPrimitiveTransportOptions, I as ImageClient, J as JsonSchemaProperty, M as MemoryClient, b as MemoryItem, P as PRIMITIVE_BINDINGS, c as PrimitiveBinding, d as PrimitiveTransport, R as RagChunk, e as RagClient, f as RagRerankResult, g as RealtimeClient, h as RealtimeSubscription, k as RyuPrimitives, S as SttClient, l as ToolOptions, m as ToolSchema, n as TtsClient, o as createPrimitives, p as defineTool, q as httpPrimitiveTransport } from './tool-u-VR0fLF.cjs';
-export { A as AppToolSpec, a as DefineAppOptions, b as appToolId, d as defineApp } from './app-DNaGmLVf.cjs';
+import { j as Runnable, k as RunnableContext } from './tool-CgzW92O_.cjs';
+export { B as BackgroundClient, a as BackgroundProcess, D as DurableClient, E as EnginesClient, G as GatewayClient, H as HttpPrimitiveTransportOptions, I as ImageClient, b as InlineToolManifestOptions, J as JsonSchemaProperty, M as MemoryClient, c as MemoryItem, P as PRIMITIVE_BINDINGS, d as PrimitiveBinding, e as PrimitiveTransport, R as RagChunk, f as RagClient, g as RagRerankResult, h as RealtimeClient, i as RealtimeSubscription, l as RyuPrimitives, S as StorageClient, m as SttClient, n as ToolOptions, o as ToolSchema, p as TtsClient, q as createPrimitives, r as defineTool, s as httpPrimitiveTransport } from './tool-CgzW92O_.cjs';
+export { A as AppToolSpec, a as DefineAppOptions, b as appToolId, d as defineApp } from './app-B0Z9Ew_R.cjs';
+import './mcp/server.cjs';
+import './mcp/client.cjs';
 import 'zod';
 import './client-D5U6ssPc.cjs';
 

package/dist/runnable.d.ts

@@ -1,7 +1,10 @@
+export { ActionAnnotations, ActionEffect, ActionManifestOptions, ActionOptions, ActionRunnable, defineAction } from './action.js';
 import { CapabilityReq, PluginManifest } from './manifest.js';
-import { i as Runnable, j as RunnableContext } from './tool-DSx2bFx8.js';
-export { B as BackgroundClient, a as BackgroundProcess, D as DurableClient, E as EnginesClient, G as GatewayClient, H as HttpPrimitiveTransportOptions, I as ImageClient, J as JsonSchemaProperty, M as MemoryClient, b as MemoryItem, P as PRIMITIVE_BINDINGS, c as PrimitiveBinding, d as PrimitiveTransport, R as RagChunk, e as RagClient, f as RagRerankResult, g as RealtimeClient, h as RealtimeSubscription, k as RyuPrimitives, S as SttClient, l as ToolOptions, m as ToolSchema, n as TtsClient, o as createPrimitives, p as defineTool, q as httpPrimitiveTransport } from './tool-DSx2bFx8.js';
-export { A as AppToolSpec, a as DefineAppOptions, b as appToolId, d as defineApp } from './app-Bkw7LlCK.js';
+import { j as Runnable, k as RunnableContext } from './tool-AjkdFvhE.js';
+export { B as BackgroundClient, a as BackgroundProcess, D as DurableClient, E as EnginesClient, G as GatewayClient, H as HttpPrimitiveTransportOptions, I as ImageClient, b as InlineToolManifestOptions, J as JsonSchemaProperty, M as MemoryClient, c as MemoryItem, P as PRIMITIVE_BINDINGS, d as PrimitiveBinding, e as PrimitiveTransport, R as RagChunk, f as RagClient, g as RagRerankResult, h as RealtimeClient, i as RealtimeSubscription, l as RyuPrimitives, S as StorageClient, m as SttClient, n as ToolOptions, o as ToolSchema, p as TtsClient, q as createPrimitives, r as defineTool, s as httpPrimitiveTransport } from './tool-AjkdFvhE.js';
+export { A as AppToolSpec, a as DefineAppOptions, b as appToolId, d as defineApp } from './app-C-BDJwfG.js';
+import './mcp/server.js';
+import './mcp/client.js';
 import 'zod';
 import './client-D5U6ssPc.js';
 

package/dist/runnable.js

@@ -1,24 +1,30 @@
 import {
   defineAgent,
   defineSkill,
-  defineTool,
   defineWorkflow
-} from "./chunk-T5676WL2.js";
+} from "./chunk-BC3A7HMO.js";
 import {
   appToolId,
   defineApp
-} from "./chunk-W3KPP4WN.js";
-import "./chunk-IEUQ3CDG.js";
+} from "./chunk-SN2QBJUF.js";
 import {
   PRIMITIVE_BINDINGS,
   createPrimitives,
   httpPrimitiveTransport
-} from "./chunk-A3RGEPDG.js";
+} from "./chunk-ZTJWBRUL.js";
+import {
+  defineAction
+} from "./chunk-4TPUZDTI.js";
+import {
+  defineTool
+} from "./chunk-QYFUNJOH.js";
+import "./chunk-NZKVOSC2.js";
 import "./chunk-IKEDLLFY.js";
 export {
   PRIMITIVE_BINDINGS,
   appToolId,
   createPrimitives,
+  defineAction,
   defineAgent,
   defineApp,
   defineSkill,

package/dist/{tool-DSx2bFx8.d.ts → tool-AjkdFvhE.d.ts}

@@ -278,6 +278,36 @@ interface BackgroundClient {
         process_id: string;
     }>;
 }
+/** Durable app-owned key/value state (`storage:kv` via the host bridge). */
+interface StorageClient {
+    /** Atomically replace a value when it still equals `expected`. */
+    compareAndSet(input: {
+        expected: string | null;
+        key: string;
+        namespace?: string;
+        value: string | null;
+    }): Promise<boolean>;
+    /** Delete one value. */
+    delete(input: {
+        key: string;
+        namespace?: string;
+    }): Promise<void>;
+    /** Read one value; missing keys return `null`. */
+    get(input: {
+        key: string;
+        namespace?: string;
+    }): Promise<string | null>;
+    /** List keys in an app-owned namespace. */
+    keys(input?: {
+        namespace?: string;
+    }): Promise<string[]>;
+    /** Write one string value. JSON can be encoded by the app when needed. */
+    set(input: {
+        key: string;
+        namespace?: string;
+        value: string;
+    }): Promise<void>;
+}
 /** TTS primitive — speech synthesis (`crates/ryu-tts`). */
 interface TtsClient {
     /**
@@ -330,6 +360,7 @@ interface RyuPrimitives {
     memory: MemoryClient;
     rag: RagClient;
     realtime: RealtimeClient;
+    storage: StorageClient;
     stt: SttClient;
     tts: TtsClient;
 }
@@ -393,6 +424,8 @@ interface RunnableContext {
     sessionId?: string;
     /** Signal to abort a long-running run. */
     signal?: AbortSignal;
+    /** Durable app-owned KV state, gated by the manifest's `storage:kv` grant. */
+    storage?: StorageClient;
     /** STT primitive: transcribe (`crates/ryu-stt`). */
     stt?: SttClient;
     /** TTS primitive: speak (`crates/ryu-tts`). */
@@ -472,9 +505,13 @@ interface ToolSchema {
     required?: string[];
     /** Type is always "object" for a tool's top-level input schema. */
     type: "object";
+    /** Preserve additional JSON Schema keywords for Core/MCP consumers. */
+    [key: string]: unknown;
 }
 /** Options accepted by `defineTool`. */
 interface ToolOptions<TInput extends Record<string, unknown>, TOutput> {
+    /** Optional description surfaced to models and tool discovery. */
+    description?: string;
     /** Stable unique identifier (e.g. "tool-web-search"). */
     id: string;
     /** Human-readable display name. */
@@ -514,6 +551,8 @@ interface ToolRunnable<TInput extends Record<string, unknown> = Record<string, u
      * the sandbox form is the second parameter aliased to `host`.
      */
     readonly code: string;
+    /** Optional description surfaced to models and tool discovery. */
+    readonly description?: string;
     readonly kind: "tool";
     /** JSON Schema for this tool's input — compatible with Core's ToolInfo.schema. */
     readonly schema: ToolSchema;
@@ -548,6 +587,19 @@ interface ToolRunnable<TInput extends Record<string, unknown> = Record<string, u
  * ```
  */
 declare function defineTool<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput = unknown>(options: ToolOptions<TInput, TOutput>): ToolRunnable<TInput, TOutput>;
+/** Optional metadata lowered alongside a tool's executable backend. */
+interface InlineToolManifestOptions {
+    /** Marks the entry as a semantic Ryu Action. */
+    action?: boolean;
+    /** MCP-style effect annotations, for example `readOnlyHint`. */
+    annotations?: Record<string, boolean | undefined>;
+    /** Description shown in Core's unified tool catalog. */
+    description?: string;
+    /** Force the human approval gate before the tool runs. */
+    needsApproval?: boolean;
+    /** JSON Schema for the structured result. */
+    outputSchema?: Record<string, unknown>;
+}
 /**
  * Convert a {@link ToolRunnable} into a `manifest.json` `kind:"tool"` runnable that
  * ships its `run` body as Core's `inline_deno` backend. The emitted config
@@ -558,8 +610,6 @@ declare function defineTool<TInput extends Record<string, unknown> = Record<stri
  *
  * The plugin must declare the `tool:execute` grant (see `definePlugin`).
  */
-declare function inlineToolRunnable(tool: ToolRunnable, options?: {
-    description?: string;
-}): RunnableMeta;
+declare function inlineToolRunnable(tool: Pick<ToolRunnable, "code" | "description" | "id" | "name" | "schema">, options?: InlineToolManifestOptions): RunnableMeta;
 
-export { type BackgroundClient as B, type DurableClient as D, type EnginesClient as E, type GatewayClient as G, type HttpPrimitiveTransportOptions as H, type ImageClient as I, type JsonSchemaProperty as J, type MemoryClient as M, PRIMITIVE_BINDINGS as P, type RagChunk as R, type SttClient as S, type ToolRunnable as T, type BackgroundProcess as a, type MemoryItem as b, type PrimitiveBinding as c, type PrimitiveTransport as d, type RagClient as e, type RagRerankResult as f, type RealtimeClient as g, type RealtimeSubscription as h, type Runnable as i, type RunnableContext as j, type RyuPrimitives as k, type ToolOptions as l, type ToolSchema as m, type TtsClient as n, createPrimitives as o, defineTool as p, httpPrimitiveTransport as q, inlineToolRunnable as r };
+export { type BackgroundClient as B, type DurableClient as D, type EnginesClient as E, type GatewayClient as G, type HttpPrimitiveTransportOptions as H, type ImageClient as I, type JsonSchemaProperty as J, type MemoryClient as M, PRIMITIVE_BINDINGS as P, type RagChunk as R, type StorageClient as S, type ToolRunnable as T, type BackgroundProcess as a, type InlineToolManifestOptions as b, type MemoryItem as c, type PrimitiveBinding as d, type PrimitiveTransport as e, type RagClient as f, type RagRerankResult as g, type RealtimeClient as h, type RealtimeSubscription as i, type Runnable as j, type RunnableContext as k, type RyuPrimitives as l, type SttClient as m, type ToolOptions as n, type ToolSchema as o, type TtsClient as p, createPrimitives as q, defineTool as r, httpPrimitiveTransport as s, inlineToolRunnable as t };