@ryuhq/sdk 0.0.5

package/dist/index.js

@@ -0,0 +1,771 @@
+import {
+  AppDependencySchema,
+  CapabilityReqSchema,
+  CompanionSurfaceSchema,
+  PluginManifestSchema,
+  RequiresSchema,
+  RunnableKindSchema,
+  RunnableMetaSchema,
+  SurfaceSchema,
+  ToolAppConfigSchema,
+  WidgetContributionSchema,
+  coreManifestJsonSchema,
+  validateManifestStrict,
+  validatePluginId
+} from "./chunk-GXHL5CO7.js";
+import {
+  Agent,
+  PRIMITIVE_BINDINGS,
+  createAgent,
+  createPrimitives,
+  httpPrimitiveTransport,
+  query,
+  ryuTool
+} from "./chunk-KPKMMGVC.js";
+import {
+  DEFAULT_GATEWAY_URL,
+  ModelClient,
+  assertAllowedEgressUrl,
+  defineModel,
+  resolveGatewayToken,
+  resolveGatewayUrl
+} from "./chunk-ODFEUVPW.js";
+
+// src/runnable/app.ts
+var DEFAULT_APP_WIDGET_MIME = "text/html+skybridge";
+var DEFAULT_APP_DISPLAY_MODE = "inline";
+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 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: [],
+    composer_controls: [],
+    settings_tabs: [],
+    slash_commands: [],
+    widgets
+  };
+  const raw = {
+    id: options.id,
+    name: options.title,
+    version: options.version,
+    runnables,
+    permission_grants: options.grants ?? [],
+    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(`plugin.json validation failed at '${field}': ${message}`);
+  }
+  return result.data;
+}
+
+// src/builder.ts
+var RunnableBuilder = class {
+  _id = "";
+  _name = "";
+  id(value) {
+    this._id = value;
+    return this;
+  }
+  name(value) {
+    this._name = value;
+    return this;
+  }
+};
+var AgentBuilder = class extends RunnableBuilder {
+  build() {
+    const result = RunnableMetaSchema.safeParse({
+      id: this._id,
+      name: this._name,
+      kind: "agent"
+    });
+    if (!result.success) {
+      throw new Error(
+        `Invalid agent runnable: ${result.error.issues.map((i) => i.message).join("; ")}`
+      );
+    }
+    return result.data;
+  }
+};
+var WorkflowBuilder = class extends RunnableBuilder {
+  build() {
+    const result = RunnableMetaSchema.safeParse({
+      id: this._id,
+      name: this._name,
+      kind: "workflow"
+    });
+    if (!result.success) {
+      throw new Error(
+        `Invalid workflow runnable: ${result.error.issues.map((i) => i.message).join("; ")}`
+      );
+    }
+    return result.data;
+  }
+};
+var ToolBuilder = class extends RunnableBuilder {
+  build() {
+    const result = RunnableMetaSchema.safeParse({
+      id: this._id,
+      name: this._name,
+      kind: "tool"
+    });
+    if (!result.success) {
+      throw new Error(
+        `Invalid tool runnable: ${result.error.issues.map((i) => i.message).join("; ")}`
+      );
+    }
+    return result.data;
+  }
+};
+var SkillBuilder = class extends RunnableBuilder {
+  build() {
+    const result = RunnableMetaSchema.safeParse({
+      id: this._id,
+      name: this._name,
+      kind: "skill"
+    });
+    if (!result.success) {
+      throw new Error(
+        `Invalid skill runnable: ${result.error.issues.map((i) => i.message).join("; ")}`
+      );
+    }
+    return result.data;
+  }
+};
+var agent = () => new AgentBuilder();
+var workflow = () => new WorkflowBuilder();
+var tool = () => new ToolBuilder();
+var skill = () => new SkillBuilder();
+var PluginBuilder = class {
+  _id = "";
+  _name = "";
+  _version = "";
+  _runnables = [];
+  _grants = [];
+  _companion = void 0;
+  _dependencies = [];
+  _requiredCapabilities = [];
+  _requiredGrants = [];
+  _targets = [];
+  /** Set the reverse-domain app id (e.g. `"com.example.my-app"`). */
+  id(value) {
+    this._id = value;
+    return this;
+  }
+  /** Set the human-readable display name. */
+  name(value) {
+    this._name = value;
+    return this;
+  }
+  /** Set the semver version string (e.g. `"1.0.0"`). */
+  version(value) {
+    this._version = value;
+    return this;
+  }
+  /** Append a pre-built `RunnableMeta` (from any per-kind builder). */
+  runnable(meta) {
+    this._runnables.push(meta);
+    return this;
+  }
+  /** Declare a permission grant (e.g. `"mcp:web_search"`). */
+  grant(permission) {
+    this._grants.push(permission);
+    return this;
+  }
+  /** Set an optional Companion surface descriptor. */
+  companion(surface) {
+    this._companion = surface;
+    return 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, minVersion) {
+    this._dependencies.push(
+      minVersion ? { id, min_version: minVersion } : { id }
+    );
+    return 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) {
+    this._requiredGrants.push(permission);
+    return 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, minVersion) {
+    this._requiredCapabilities.push(
+      minVersion ? { capability, min_version: minVersion } : { capability }
+    );
+    return this;
+  }
+  /**
+   * Restrict this plugin to a host surface (`"desktop"`, `"island"`, …).
+   * Declaring NO target is the default and means **every** surface.
+   */
+  target(surface) {
+    this._targets.push(surface);
+    return this;
+  }
+  /**
+   * Validate and return the assembled `PluginManifest`. Throws an `Error` with
+   * the failing field name and message when validation fails.
+   */
+  build() {
+    const hasRequires = this._dependencies.length > 0 || this._requiredCapabilities.length > 0 || this._requiredGrants.length > 0;
+    const raw = {
+      id: this._id,
+      name: this._name,
+      version: this._version,
+      runnables: this._runnables,
+      permission_grants: this._grants,
+      companion: this._companion,
+      targets: this._targets,
+      ...hasRequires ? {
+        requires: {
+          apps: this._dependencies,
+          capabilities: this._requiredCapabilities,
+          grants: this._requiredGrants
+        }
+      } : {}
+    };
+    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(
+        `plugin.json validation failed at '${field}': ${message}`
+      );
+    }
+    return result.data;
+  }
+};
+var AppBuilder = class {
+  _id = "";
+  _title = "";
+  _version = "";
+  _slug = "";
+  _server = void 0;
+  _displayMode = void 0;
+  _mime = void 0;
+  _uiEntry = "";
+  _grants = [];
+  _activationEvents = [];
+  _tools = [];
+  _dependencies = [];
+  _requiredCapabilities = [];
+  _requiredGrants = [];
+  _targets = [];
+  /** Set the reverse-domain app id (e.g. `"com.example.checklist"`). */
+  id(value) {
+    this._id = value;
+    return this;
+  }
+  /** Set the human-readable display name. */
+  title(value) {
+    this._title = value;
+    return this;
+  }
+  /** Set the semver version string (e.g. `"1.0.0"`). */
+  version(value) {
+    this._version = value;
+    return this;
+  }
+  /** Set the app slug (drives `ui://widget/<slug>.html` and the server default). */
+  slug(value) {
+    this._slug = value;
+    return this;
+  }
+  /** Override the MCP server namespace for tool ids (defaults to the slug). */
+  server(value) {
+    this._server = value;
+    return this;
+  }
+  /** Set the default widget display mode (`inline` | `fullscreen` | `pip`). */
+  displayMode(value) {
+    this._displayMode = value;
+    return this;
+  }
+  /** Override the widget MIME dialect (defaults to `text/html+skybridge`). */
+  mime(value) {
+    this._mime = value;
+    return this;
+  }
+  /** Set the widget UI source entry `ryu pack` bundles into `ui_code`. */
+  uiEntry(value) {
+    this._uiEntry = value;
+    return this;
+  }
+  /** Declare a permission grant (e.g. `"mcp:web_search"`). */
+  grant(permission) {
+    this._grants.push(permission);
+    return this;
+  }
+  /** Add a VS-Code-style activation event (empty = eager `["*"]`). */
+  activationEvent(event) {
+    this._activationEvents.push(event);
+    return this;
+  }
+  /** Append a tool spec (render tool unless `accessible:true`). */
+  tool(spec) {
+    this._tools.push(spec);
+    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"`).
+   */
+  dependsOn(id, minVersion) {
+    this._dependencies.push(
+      minVersion ? { id, min_version: minVersion } : { id }
+    );
+    return this;
+  }
+  /** Declare a grant implied by this app's dependencies (`requires.grants`). */
+  requiredGrant(permission) {
+    this._requiredGrants.push(permission);
+    return 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, minVersion) {
+    this._requiredCapabilities.push(
+      minVersion ? { capability, min_version: minVersion } : { capability }
+    );
+    return this;
+  }
+  /** Restrict this app to a host surface. No target = every surface. */
+  target(surface) {
+    this._targets.push(surface);
+    return this;
+  }
+  /**
+   * Validate and return the assembled `PluginManifest`. Throws an `Error` naming
+   * the failing field when validation fails.
+   */
+  build() {
+    const hasRequires = this._dependencies.length > 0 || this._requiredCapabilities.length > 0 || this._requiredGrants.length > 0;
+    const options = {
+      id: this._id,
+      title: this._title,
+      version: this._version,
+      slug: this._slug,
+      uiEntry: this._uiEntry,
+      tools: this._tools,
+      grants: this._grants,
+      ...this._server ? { server: this._server } : {},
+      ...this._displayMode ? { displayMode: this._displayMode } : {},
+      ...this._mime ? { mime: this._mime } : {},
+      ...this._activationEvents.length > 0 ? { activationEvents: this._activationEvents } : {},
+      ...hasRequires ? {
+        requires: {
+          apps: this._dependencies,
+          capabilities: this._requiredCapabilities,
+          grants: this._requiredGrants
+        }
+      } : {},
+      ...this._targets.length > 0 ? { targets: this._targets } : {}
+    };
+    return defineApp(options);
+  }
+};
+var app = () => new AppBuilder();
+
+// src/runnable/agent.ts
+var CAPABILITY_SLOTS = ["rag", "memory", "tts", "stt"];
+function lowerChatSlot(chat) {
+  if (chat === void 0) {
+    return {};
+  }
+  if (typeof chat === "string") {
+    return { model: chat };
+  }
+  return {
+    model: chat.model,
+    engine: chat.engine,
+    persona: chat.persona,
+    modelPrefKey: chat.modelPrefKey
+  };
+}
+function lowerCapabilitySlot(capability, slot, card) {
+  if (slot === void 0 || slot === false) {
+    return;
+  }
+  if (slot === true) {
+    card.capabilities.push({ capability });
+    return;
+  }
+  if (typeof slot === "string") {
+    card.capabilities.push({ capability });
+    card.providers[capability] = slot;
+    return;
+  }
+  card.capabilities.push(
+    slot.minVersion ? { capability, min_version: slot.minVersion } : { capability }
+  );
+  if (slot.provider) {
+    card.providers[capability] = slot.provider;
+  }
+}
+function lowerSlots(options) {
+  const card = {
+    ...lowerChatSlot(options.chat),
+    capabilities: [],
+    providers: {},
+    tools: []
+  };
+  for (const capability of CAPABILITY_SLOTS) {
+    lowerCapabilitySlot(capability, options[capability], card);
+  }
+  for (const t of options.tools ?? []) {
+    card.tools.push(typeof t === "string" ? t : t.id);
+  }
+  return card;
+}
+function defaultRun(card) {
+  return async (input, ctx) => {
+    const content = typeof input === "string" ? input : JSON.stringify(input ?? "");
+    const messages = card.persona ? [
+      { role: "system", content: card.persona },
+      { role: "user", content }
+    ] : [{ role: "user", content }];
+    const result = await ctx.gateway.chat(messages);
+    return result.content;
+  };
+}
+function cardConfig(card) {
+  const config = {};
+  if (card.model) {
+    config.model = card.model;
+  }
+  if (card.engine) {
+    config.engine = card.engine;
+  }
+  if (card.persona) {
+    config.persona = card.persona;
+  }
+  if (card.modelPrefKey) {
+    config.model_pref_key = card.modelPrefKey;
+  }
+  if (Object.keys(card.providers).length > 0) {
+    config.capability_providers = card.providers;
+  }
+  if (card.tools.length > 0) {
+    config.tools = card.tools;
+  }
+  return config;
+}
+function agentToManifest(agent2, options) {
+  const config = cardConfig(agent2.card);
+  const meta = {
+    id: agent2.id,
+    name: agent2.name,
+    kind: "agent",
+    ...Object.keys(config).length > 0 ? { config } : {}
+  };
+  const hasRequires = agent2.card.capabilities.length > 0 || (options.grants?.length ?? 0) > 0;
+  const raw = {
+    id: options.id,
+    name: options.name ?? agent2.name,
+    version: options.version,
+    runnables: [meta],
+    ...hasRequires ? {
+      requires: {
+        apps: [],
+        capabilities: agent2.card.capabilities,
+        grants: options.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(
+      `agent manifest validation failed at '${field}': ${message}`
+    );
+  }
+  return result.data;
+}
+function defineAgent(options) {
+  const { id, name } = options;
+  const card = lowerSlots(options);
+  const run = options.run ?? defaultRun(card);
+  return {
+    id,
+    name,
+    kind: "agent",
+    run,
+    card,
+    toManifest(manifestOptions) {
+      return agentToManifest(this, manifestOptions);
+    }
+  };
+}
+
+// src/runnable/skill.ts
+function defineSkill(options) {
+  const { id, name, run } = options;
+  return {
+    id,
+    name,
+    kind: "skill",
+    run
+  };
+}
+
+// src/runnable/tool.ts
+function validateInput(input, schema, toolId) {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    throw new Error(
+      `[ryu-sdk] Tool "${toolId}" input must be an object, got ${JSON.stringify(input)}`
+    );
+  }
+  const record = input;
+  for (const requiredKey of schema.required ?? []) {
+    if (!(requiredKey in record)) {
+      throw new Error(
+        `[ryu-sdk] Tool "${toolId}" input missing required field "${requiredKey}"`
+      );
+    }
+  }
+  for (const [key, prop] of Object.entries(schema.properties)) {
+    if (!(key in record)) {
+      continue;
+    }
+    const value = record[key];
+    if (!checkType(value, prop.type)) {
+      throw new Error(
+        `[ryu-sdk] Tool "${toolId}" input field "${key}" expected type "${prop.type}", got ${JSON.stringify(value)}`
+      );
+    }
+  }
+}
+function checkType(value, type) {
+  switch (type) {
+    case "string":
+      return typeof value === "string";
+    case "number":
+    case "integer":
+      return typeof value === "number";
+    case "boolean":
+      return typeof value === "boolean";
+    case "array":
+      return Array.isArray(value);
+    case "object":
+      return typeof value === "object" && value !== null && !Array.isArray(value);
+    default:
+      return false;
+  }
+}
+function defineTool(options) {
+  const { id, name, schema, run } = options;
+  const code = `return await (${run.toString()})(input, host);`;
+  return {
+    id,
+    name,
+    kind: "tool",
+    schema,
+    code,
+    run(input, ctx) {
+      validateInput(input, schema, id);
+      return run(input, ctx);
+    }
+  };
+}
+function inlineToolRunnable(tool2, options) {
+  return {
+    id: tool2.id,
+    name: tool2.name,
+    kind: "tool",
+    config: {
+      slug: tool2.id,
+      backend: "inline_deno",
+      code: tool2.code,
+      input_schema: tool2.schema,
+      ...options?.description ? { description: options.description } : {}
+    }
+  };
+}
+
+// src/runnable/turn-hook.ts
+function defineTurnHook(options) {
+  const source = options.run.toString();
+  const code = `return await (${source})(ctx, host);`;
+  return {
+    id: options.id,
+    on: options.on ?? "post_assistant_turn",
+    code
+  };
+}
+function definePlugin(options) {
+  const contributes = {
+    turn_hooks: options.turnHooks ?? [],
+    composer_controls: options.composerControls ?? [],
+    settings_tabs: options.settingsTabs ?? [],
+    slash_commands: options.slashCommands ?? [],
+    // A turn-hook plugin contributes no app widgets; the field is required on the
+    // resolved `Contributes` type (zod default applied), so set it explicitly.
+    widgets: []
+  };
+  const tools = options.tools ?? [];
+  const runnables = tools.map((t) => inlineToolRunnable(t));
+  const grants = new Set(options.grants ?? []);
+  if (tools.length > 0) {
+    grants.add("tool:execute");
+  }
+  return {
+    id: options.id,
+    name: options.name,
+    version: options.version,
+    runnables,
+    permission_grants: [...grants],
+    activation_events: options.activationEvents ?? ["*"],
+    contributes,
+    // Empty = EVERY surface (Core's backward-compatible default), never "hidden".
+    targets: options.targets ?? [],
+    // Absent (not `{apps:[],grants:[]}`) when undeclared, 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 ?? []
+      }
+    } : {}
+  };
+}
+
+// src/runnable/workflow.ts
+function defineWorkflow(options) {
+  const { id, name, run } = options;
+  return {
+    id,
+    name,
+    kind: "workflow",
+    run
+  };
+}
+export {
+  Agent,
+  AgentBuilder,
+  AppBuilder,
+  AppDependencySchema,
+  CapabilityReqSchema,
+  CompanionSurfaceSchema,
+  DEFAULT_GATEWAY_URL,
+  ModelClient,
+  PRIMITIVE_BINDINGS,
+  PluginBuilder,
+  PluginManifestSchema,
+  RequiresSchema,
+  RunnableKindSchema,
+  RunnableMetaSchema,
+  SkillBuilder,
+  SurfaceSchema,
+  ToolAppConfigSchema,
+  ToolBuilder,
+  WidgetContributionSchema,
+  WorkflowBuilder,
+  agent,
+  app,
+  appToolId,
+  assertAllowedEgressUrl,
+  coreManifestJsonSchema,
+  createAgent,
+  createPrimitives,
+  defineAgent,
+  defineApp,
+  defineModel,
+  definePlugin,
+  defineSkill,
+  defineTool,
+  defineTurnHook,
+  defineWorkflow,
+  httpPrimitiveTransport,
+  inlineToolRunnable,
+  query,
+  resolveGatewayToken,
+  resolveGatewayUrl,
+  ryuTool,
+  skill,
+  tool,
+  validateManifestStrict,
+  validatePluginId,
+  workflow
+};