@ryuhq/sdk 0.1.14 → 0.2.2

package/dist/builder.d.cts

@@ -0,0 +1,217 @@
+import { RunnableMeta, SlashCommandContribution, Surface, PluginManifest, CompanionSurface } from './manifest.cjs';
+import { A as AppToolSpec } from './app-B0Z9Ew_R.cjs';
+import 'zod';
+import './tool-CgzW92O_.cjs';
+import './client-D5U6ssPc.cjs';
+
+/**
+ * Ryu SDK typed builders — one builder per RunnableKind plus a PluginBuilder that
+ * assembles a complete, validated `manifest.json` manifest.
+ *
+ * Each builder follows a fluent interface: construct, chain setter calls, then
+ * call `.build()` to get a validated result. Invalid manifests throw a
+ * descriptive `Error` — never a silent fallback.
+ *
+ * Engine/model fields are typed as `string` throughout.  No provider union is
+ * used so adding a new provider never requires an SDK change.
+ */
+
+/** Base builder shared by all Runnable kinds. */
+declare class RunnableBuilder {
+    protected _id: string;
+    protected _name: string;
+    id(value: string): this;
+    name(value: string): this;
+}
+/** Builds an Agent `RunnableMeta` entry. */
+declare class AgentBuilder extends RunnableBuilder {
+    build(): RunnableMeta;
+}
+/** Builds a Workflow `RunnableMeta` entry. */
+declare class WorkflowBuilder extends RunnableBuilder {
+    build(): RunnableMeta;
+}
+/** Builds a Tool `RunnableMeta` entry. */
+declare class ToolBuilder extends RunnableBuilder {
+    build(): RunnableMeta;
+}
+/** Builds a Skill `RunnableMeta` entry. */
+declare class SkillBuilder extends RunnableBuilder {
+    build(): RunnableMeta;
+}
+/** Create an AgentBuilder. */
+declare const agent: () => AgentBuilder;
+/** Create a WorkflowBuilder. */
+declare const workflow: () => WorkflowBuilder;
+/** Create a ToolBuilder. */
+declare const tool: () => ToolBuilder;
+/** Create a SkillBuilder. */
+declare const skill: () => SkillBuilder;
+/**
+ * Fluent builder for a complete `manifest.json` Plugin manifest. Produces a
+ * validated `PluginManifest` on `.build()` or throws a descriptive `Error`
+ * naming the first invalid field.
+ *
+ * @example
+ * ```ts
+ * import { PluginBuilder, agent, tool } from "@ryuhq/sdk/builder"
+ *
+ * const manifest = new PluginBuilder()
+ *   .id("com.example.my-plugin")
+ *   .name("My Plugin")
+ *   .version("1.0.0")
+ *   .runnable(agent().id("agent-main").name("Main Agent").build())
+ *   .runnable(tool().id("tool-search").name("Web Search").build())
+ *   .grant("mcp:web_search")
+ *   .companion({ label: "My Plugin", icon: "sparkles", shortcut: "ctrl+shift+m" })
+ *   .build()
+ * ```
+ */
+declare class PluginBuilder {
+    private _id;
+    private _name;
+    private _version;
+    private readonly _runnables;
+    private readonly _grants;
+    private _companion;
+    private readonly _dependencies;
+    private readonly _requiredCapabilities;
+    private readonly _requiredGrants;
+    private readonly _targets;
+    /** Set the reverse-domain app id (e.g. `"com.example.my-app"`). */
+    id(value: string): this;
+    /** Set the human-readable display name. */
+    name(value: string): this;
+    /** Set the semver version string (e.g. `"1.0.0"`). */
+    version(value: string): this;
+    /** Append a pre-built `RunnableMeta` (from any per-kind builder). */
+    runnable(meta: RunnableMeta): this;
+    /** Declare a permission grant (e.g. `"mcp:web_search"`). */
+    grant(permission: string): this;
+    /** Set an optional Companion surface descriptor. */
+    companion(surface: CompanionSurface): this;
+    /**
+     * Declare a **plugin-to-plugin dependency**: `id` must be installed and is
+     * auto-enabled (in dependency order) before this plugin enables.
+     *
+     * `minVersion` is a MINIMUM — a bare `"1.2.0"` means `">=1.2.0"`, so an
+     * installed `2.0.0` satisfies it (comparator syntax like `">=1.2, <2"` is
+     * honoured verbatim).
+     */
+    dependsOn(id: string, minVersion?: string): this;
+    /**
+     * Declare a permission grant implied by this plugin's dependencies
+     * (`requires.grants`). Declaration only — the Gateway remains the sole
+     * authority on what a grant allows. Use {@link PluginBuilder.grant} for the
+     * grants this plugin needs in its own right.
+     */
+    requiredGrant(permission: string): this;
+    /**
+     * Declare an abstract **capability** edge (`requires.capabilities`) the broker
+     * resolves to a bound provider at enable time — e.g. `requiresCapability("rag")`.
+     * Distinct from a specific-plugin dependency: a capability edge lets the
+     * binding registry choose the provider. `minVersion` is a MINIMUM (`"1.2.0"`
+     * = `">=1.2.0"`).
+     */
+    requiresCapability(capability: string, minVersion?: string): this;
+    /**
+     * Restrict this plugin to a host surface (`"desktop"`, `"island"`, …).
+     * Declaring NO target is the default and means **every** surface.
+     */
+    target(surface: Surface): this;
+    /**
+     * Validate and return the assembled `PluginManifest`. Throws an `Error` with
+     * the failing field name and message when validation fails.
+     */
+    build(): PluginManifest;
+}
+/**
+ * Fluent builder for a Ryu App — a `manifest.json` whose tools render interactive
+ * widgets inline in chat. Delegates to {@link defineApp} on `.build()`, so it
+ * derives the render-vs-companion split and validates through
+ * `PluginManifestSchema` (throwing a descriptive `Error` on bad input) exactly
+ * like the factory.
+ *
+ * @example
+ * ```ts
+ * import { app } from "@ryuhq/sdk/builder"
+ *
+ * const manifest = app()
+ *   .id("com.example.checklist")
+ *   .title("Checklist")
+ *   .version("1.0.0")
+ *   .slug("checklist")
+ *   .uiEntry("src/checklist.tsx")
+ *   .tool({ name: "render", description: "Render a checklist", invoking: "Building…" })
+ *   .tool({ name: "toggle", description: "Toggle an item", accessible: true })
+ *   .build()
+ * ```
+ */
+declare class AppBuilder {
+    private _id;
+    private _title;
+    private _version;
+    private _slug;
+    private _server;
+    private _displayMode;
+    private _mime;
+    private _uiEntry;
+    private readonly _grants;
+    private readonly _activationEvents;
+    private readonly _tools;
+    private readonly _dependencies;
+    private readonly _requiredCapabilities;
+    private readonly _requiredGrants;
+    private readonly _slashCommands;
+    private readonly _targets;
+    /** Set the reverse-domain app id (e.g. `"com.example.checklist"`). */
+    id(value: string): this;
+    /** Set the human-readable display name. */
+    title(value: string): this;
+    /** Set the semver version string (e.g. `"1.0.0"`). */
+    version(value: string): this;
+    /** Set the app slug (drives `ui://widget/<slug>.html` and the server default). */
+    slug(value: string): this;
+    /** Override the MCP server namespace for tool ids (defaults to the slug). */
+    server(value: string): this;
+    /** Set the default widget display mode (`inline` | `fullscreen` | `pip`). */
+    displayMode(value: string): this;
+    /** Override the widget MIME dialect (defaults to `text/html+skybridge`). */
+    mime(value: string): this;
+    /** Set the widget UI source entry `ryu pack` bundles into `ui_code`. */
+    uiEntry(value: string): this;
+    /** Declare a permission grant (e.g. `"mcp:web_search"`). */
+    grant(permission: string): this;
+    /** Add a VS-Code-style activation event (empty = eager `["*"]`). */
+    activationEvent(event: string): this;
+    /** Append a tool spec (render tool unless `accessible:true`). */
+    tool(spec: AppToolSpec): this;
+    /** Add a slash command and its optional sequential argument choices. */
+    slashCommand(command: SlashCommandContribution): this;
+    /**
+     * Declare a **plugin-to-plugin dependency** (auto-enabled, in dependency order,
+     * before this app). `minVersion` is a MINIMUM (`"1.2.0"` = `">=1.2.0"`).
+     */
+    dependsOn(id: string, minVersion?: string): this;
+    /** Declare a grant implied by this app's dependencies (`requires.grants`). */
+    requiredGrant(permission: string): this;
+    /**
+     * Declare an abstract **capability** edge (`requires.capabilities`) the broker
+     * resolves to a bound provider at enable time — e.g. `requiresCapability("rag")`.
+     * Distinct from a specific-plugin dependency: a capability edge lets the
+     * binding registry choose the provider. `minVersion` is a MINIMUM (`"1.2.0"`
+     * = `">=1.2.0"`).
+     */
+    requiresCapability(capability: string, minVersion?: string): this;
+    /** Restrict this app to a host surface. No target = every surface. */
+    target(surface: Surface): this;
+    /**
+     * Validate and return the assembled `PluginManifest`. Throws an `Error` naming
+     * the failing field when validation fails.
+     */
+    build(): PluginManifest;
+}
+/** Create an AppBuilder. */
+declare const app: () => AppBuilder;
+
+export { AgentBuilder, AppBuilder, PluginBuilder, SkillBuilder, ToolBuilder, WorkflowBuilder, agent, app, skill, tool, workflow };

package/dist/builder.d.ts

@@ -0,0 +1,217 @@
+import { RunnableMeta, SlashCommandContribution, Surface, PluginManifest, CompanionSurface } from './manifest.js';
+import { A as AppToolSpec } from './app-C-BDJwfG.js';
+import 'zod';
+import './tool-AjkdFvhE.js';
+import './client-D5U6ssPc.js';
+
+/**
+ * Ryu SDK typed builders — one builder per RunnableKind plus a PluginBuilder that
+ * assembles a complete, validated `manifest.json` manifest.
+ *
+ * Each builder follows a fluent interface: construct, chain setter calls, then
+ * call `.build()` to get a validated result. Invalid manifests throw a
+ * descriptive `Error` — never a silent fallback.
+ *
+ * Engine/model fields are typed as `string` throughout.  No provider union is
+ * used so adding a new provider never requires an SDK change.
+ */
+
+/** Base builder shared by all Runnable kinds. */
+declare class RunnableBuilder {
+    protected _id: string;
+    protected _name: string;
+    id(value: string): this;
+    name(value: string): this;
+}
+/** Builds an Agent `RunnableMeta` entry. */
+declare class AgentBuilder extends RunnableBuilder {
+    build(): RunnableMeta;
+}
+/** Builds a Workflow `RunnableMeta` entry. */
+declare class WorkflowBuilder extends RunnableBuilder {
+    build(): RunnableMeta;
+}
+/** Builds a Tool `RunnableMeta` entry. */
+declare class ToolBuilder extends RunnableBuilder {
+    build(): RunnableMeta;
+}
+/** Builds a Skill `RunnableMeta` entry. */
+declare class SkillBuilder extends RunnableBuilder {
+    build(): RunnableMeta;
+}
+/** Create an AgentBuilder. */
+declare const agent: () => AgentBuilder;
+/** Create a WorkflowBuilder. */
+declare const workflow: () => WorkflowBuilder;
+/** Create a ToolBuilder. */
+declare const tool: () => ToolBuilder;
+/** Create a SkillBuilder. */
+declare const skill: () => SkillBuilder;
+/**
+ * Fluent builder for a complete `manifest.json` Plugin manifest. Produces a
+ * validated `PluginManifest` on `.build()` or throws a descriptive `Error`
+ * naming the first invalid field.
+ *
+ * @example
+ * ```ts
+ * import { PluginBuilder, agent, tool } from "@ryuhq/sdk/builder"
+ *
+ * const manifest = new PluginBuilder()
+ *   .id("com.example.my-plugin")
+ *   .name("My Plugin")
+ *   .version("1.0.0")
+ *   .runnable(agent().id("agent-main").name("Main Agent").build())
+ *   .runnable(tool().id("tool-search").name("Web Search").build())
+ *   .grant("mcp:web_search")
+ *   .companion({ label: "My Plugin", icon: "sparkles", shortcut: "ctrl+shift+m" })
+ *   .build()
+ * ```
+ */
+declare class PluginBuilder {
+    private _id;
+    private _name;
+    private _version;
+    private readonly _runnables;
+    private readonly _grants;
+    private _companion;
+    private readonly _dependencies;
+    private readonly _requiredCapabilities;
+    private readonly _requiredGrants;
+    private readonly _targets;
+    /** Set the reverse-domain app id (e.g. `"com.example.my-app"`). */
+    id(value: string): this;
+    /** Set the human-readable display name. */
+    name(value: string): this;
+    /** Set the semver version string (e.g. `"1.0.0"`). */
+    version(value: string): this;
+    /** Append a pre-built `RunnableMeta` (from any per-kind builder). */
+    runnable(meta: RunnableMeta): this;
+    /** Declare a permission grant (e.g. `"mcp:web_search"`). */
+    grant(permission: string): this;
+    /** Set an optional Companion surface descriptor. */
+    companion(surface: CompanionSurface): this;
+    /**
+     * Declare a **plugin-to-plugin dependency**: `id` must be installed and is
+     * auto-enabled (in dependency order) before this plugin enables.
+     *
+     * `minVersion` is a MINIMUM — a bare `"1.2.0"` means `">=1.2.0"`, so an
+     * installed `2.0.0` satisfies it (comparator syntax like `">=1.2, <2"` is
+     * honoured verbatim).
+     */
+    dependsOn(id: string, minVersion?: string): this;
+    /**
+     * Declare a permission grant implied by this plugin's dependencies
+     * (`requires.grants`). Declaration only — the Gateway remains the sole
+     * authority on what a grant allows. Use {@link PluginBuilder.grant} for the
+     * grants this plugin needs in its own right.
+     */
+    requiredGrant(permission: string): this;
+    /**
+     * Declare an abstract **capability** edge (`requires.capabilities`) the broker
+     * resolves to a bound provider at enable time — e.g. `requiresCapability("rag")`.
+     * Distinct from a specific-plugin dependency: a capability edge lets the
+     * binding registry choose the provider. `minVersion` is a MINIMUM (`"1.2.0"`
+     * = `">=1.2.0"`).
+     */
+    requiresCapability(capability: string, minVersion?: string): this;
+    /**
+     * Restrict this plugin to a host surface (`"desktop"`, `"island"`, …).
+     * Declaring NO target is the default and means **every** surface.
+     */
+    target(surface: Surface): this;
+    /**
+     * Validate and return the assembled `PluginManifest`. Throws an `Error` with
+     * the failing field name and message when validation fails.
+     */
+    build(): PluginManifest;
+}
+/**
+ * Fluent builder for a Ryu App — a `manifest.json` whose tools render interactive
+ * widgets inline in chat. Delegates to {@link defineApp} on `.build()`, so it
+ * derives the render-vs-companion split and validates through
+ * `PluginManifestSchema` (throwing a descriptive `Error` on bad input) exactly
+ * like the factory.
+ *
+ * @example
+ * ```ts
+ * import { app } from "@ryuhq/sdk/builder"
+ *
+ * const manifest = app()
+ *   .id("com.example.checklist")
+ *   .title("Checklist")
+ *   .version("1.0.0")
+ *   .slug("checklist")
+ *   .uiEntry("src/checklist.tsx")
+ *   .tool({ name: "render", description: "Render a checklist", invoking: "Building…" })
+ *   .tool({ name: "toggle", description: "Toggle an item", accessible: true })
+ *   .build()
+ * ```
+ */
+declare class AppBuilder {
+    private _id;
+    private _title;
+    private _version;
+    private _slug;
+    private _server;
+    private _displayMode;
+    private _mime;
+    private _uiEntry;
+    private readonly _grants;
+    private readonly _activationEvents;
+    private readonly _tools;
+    private readonly _dependencies;
+    private readonly _requiredCapabilities;
+    private readonly _requiredGrants;
+    private readonly _slashCommands;
+    private readonly _targets;
+    /** Set the reverse-domain app id (e.g. `"com.example.checklist"`). */
+    id(value: string): this;
+    /** Set the human-readable display name. */
+    title(value: string): this;
+    /** Set the semver version string (e.g. `"1.0.0"`). */
+    version(value: string): this;
+    /** Set the app slug (drives `ui://widget/<slug>.html` and the server default). */
+    slug(value: string): this;
+    /** Override the MCP server namespace for tool ids (defaults to the slug). */
+    server(value: string): this;
+    /** Set the default widget display mode (`inline` | `fullscreen` | `pip`). */
+    displayMode(value: string): this;
+    /** Override the widget MIME dialect (defaults to `text/html+skybridge`). */
+    mime(value: string): this;
+    /** Set the widget UI source entry `ryu pack` bundles into `ui_code`. */
+    uiEntry(value: string): this;
+    /** Declare a permission grant (e.g. `"mcp:web_search"`). */
+    grant(permission: string): this;
+    /** Add a VS-Code-style activation event (empty = eager `["*"]`). */
+    activationEvent(event: string): this;
+    /** Append a tool spec (render tool unless `accessible:true`). */
+    tool(spec: AppToolSpec): this;
+    /** Add a slash command and its optional sequential argument choices. */
+    slashCommand(command: SlashCommandContribution): this;
+    /**
+     * Declare a **plugin-to-plugin dependency** (auto-enabled, in dependency order,
+     * before this app). `minVersion` is a MINIMUM (`"1.2.0"` = `">=1.2.0"`).
+     */
+    dependsOn(id: string, minVersion?: string): this;
+    /** Declare a grant implied by this app's dependencies (`requires.grants`). */
+    requiredGrant(permission: string): this;
+    /**
+     * Declare an abstract **capability** edge (`requires.capabilities`) the broker
+     * resolves to a bound provider at enable time — e.g. `requiresCapability("rag")`.
+     * Distinct from a specific-plugin dependency: a capability edge lets the
+     * binding registry choose the provider. `minVersion` is a MINIMUM (`"1.2.0"`
+     * = `">=1.2.0"`).
+     */
+    requiresCapability(capability: string, minVersion?: string): this;
+    /** Restrict this app to a host surface. No target = every surface. */
+    target(surface: Surface): this;
+    /**
+     * Validate and return the assembled `PluginManifest`. Throws an `Error` naming
+     * the failing field when validation fails.
+     */
+    build(): PluginManifest;
+}
+/** Create an AppBuilder. */
+declare const app: () => AppBuilder;
+
+export { AgentBuilder, AppBuilder, PluginBuilder, SkillBuilder, ToolBuilder, WorkflowBuilder, agent, app, skill, tool, workflow };

package/dist/builder.js

@@ -0,0 +1,29 @@
+import {
+  AgentBuilder,
+  AppBuilder,
+  PluginBuilder,
+  SkillBuilder,
+  ToolBuilder,
+  WorkflowBuilder,
+  agent,
+  app,
+  skill,
+  tool,
+  workflow
+} from "./chunk-HLKJZAFK.js";
+import "./chunk-SN2QBJUF.js";
+import "./chunk-QYFUNJOH.js";
+import "./chunk-NZKVOSC2.js";
+export {
+  AgentBuilder,
+  AppBuilder,
+  PluginBuilder,
+  SkillBuilder,
+  ToolBuilder,
+  WorkflowBuilder,
+  agent,
+  app,
+  skill,
+  tool,
+  workflow
+};

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
+};