@ryuhq/sdk 0.1.13 → 0.2.0

package/README.md

@@ -1,18 +1,18 @@
-# <img src="https://raw.githubusercontent.com/amajorai/ryu/main/.github/logo.png" width="50" align="middle" alt="" />&nbsp; @ryu/sdk
+# <img src="https://raw.githubusercontent.com/amajorai/ryu/main/.github/logo.png" width="50" align="middle" alt="" />&nbsp; @ryuhq/sdk
 
 > Ryu's own developer SDK for authoring agents, workflows, tools, and skills. Part of [Ryu](../../README.md).
 
 [![License](https://shieldcn.dev/badge/License-Apache--2.0-73DC8C.svg?logo=apache&logoColor=white)](./LICENSE)
 [![Stack](https://shieldcn.dev/badge/TypeScript-SDK-3178C6.svg?logo=typescript&logoColor=white)](../../README.md)
 
-`@ryu/sdk` provides typed Runnable factories (`agent`, `workflow`, `tool`, `skill` plus their builders), a gateway-mandatory model client so every model call routes through the Ryu Gateway, an MCP server/client, and a `ryu` CLI for packing and publishing plugin bundles. It is Runnable-native: reference the AI SDK / Mastra / ACP patterns, but depend on none of them. The native logic ships through a prebuilt addon, `@ryu/sdk-native` (the `crates/ryu-sdk-napi` binding).
+`@ryuhq/sdk` provides typed Runnable factories (`agent`, `workflow`, `tool`, `skill` plus their builders), a gateway-mandatory model client so every model call routes through the Ryu Gateway, an MCP server/client, and a `ryu` CLI for packing and publishing plugin bundles. It is Runnable-native: reference the AI SDK / Mastra / ACP patterns, but depend on none of them. The native logic ships through a prebuilt addon, `@ryuhq/sdk-native` (the `crates/sdk/napi` binding).
 
 **Tier:** OSS (Apache-2.0)
 
 ## Install / Build
 
 ```bash
-bun add @ryu/sdk
+bun add @ryuhq/sdk
 # build from source
 bun run build   # tsup → dist/
 bun test
@@ -21,11 +21,24 @@ bun test
 ## What it provides
 
 - **Runnable factories:** `agent`, `workflow`, `tool`, `skill` (and `AgentBuilder` / `WorkflowBuilder` / `ToolBuilder` / `SkillBuilder` / `PluginBuilder`) for the one Runnable contract (input to run to output).
-- **Manifest model:** `PluginManifest` types + `PluginManifestSchema` / `validateManifestStrict` / `validatePluginId` (also exported from `@ryu/sdk/manifest`).
-- **Gateway-mandatory model client:** chat types and a client where every model call routes through the Ryu Gateway.
-- **MCP server/client:** author and consume MCP tool surfaces.
+- **Manifest model:** `PluginManifest` types + `PluginManifestSchema` / `validateManifestStrict` / `validatePluginId` (also exported from `@ryuhq/sdk/manifest`).
+- **Gateway-mandatory model client:** chat types and a client where every model call routes through the Ryu Gateway (also from `@ryuhq/sdk/model`).
+- **MCP server/client:** author (`McpServer`) and consume (`listTools` / `callTool`) MCP tool surfaces, via `@ryuhq/sdk/mcp`, `@ryuhq/sdk/mcp/server`, or `@ryuhq/sdk/mcp/client`.
+- **Plugin host surface:** `RyuPlugin` / `PluginContext` / `definePlugin` types for the desktop companion host, via `@ryuhq/sdk/plugin`.
+- **Runnables + builders as entries:** `@ryuhq/sdk/runnable` (the four kinds and their factories) and `@ryuhq/sdk/builder`.
 - **CLI:** `bunx ryu pack <dir>` (and `ryu publish`) via the package `bin` entry.
 
+## Managing a running node
+
+`@ryuhq/sdk` is the *authoring* SDK — it builds, packs, and publishes plugin
+bundles and runs Runnables in-process. If you want to **drive a running Ryu
+node programmatically** (install/enable/disable plugins, manage agents, models,
+skills, MCP servers, spaces, workflows, gateway config, chat against Core),
+that surface lives in [`@ryuhq/core-client`](../../packages/core-client) — the
+same client the desktop app, TUI, and CLI run on — plus `@ryuhq/client` for
+embedded agent chat. Nothing here duplicates it; `@ryuhq/sdk` deliberately
+stays the authoring layer.
+
 ## License
 
 Apache-2.0. See [LICENSE](./LICENSE). © 2026 A Major Pte. Ltd.

package/dist/agent-plugin.cjs

@@ -106,6 +106,21 @@ function toSpecEnv(value) {
   }
   return Object.keys(env).length > 0 ? env : void 0;
 }
+function validateRemoteUrl(name, raw) {
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    return `mcp server '${name}' remote url ${JSON.stringify(raw)} is invalid and was omitted`;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return `mcp server '${name}' remote url must use http or https and was omitted`;
+  }
+  if (parsed.username || parsed.password || parsed.hash) {
+    return `mcp server '${name}' remote url must not contain credentials or a fragment and was omitted`;
+  }
+  return void 0;
+}
 function toSpecServer(name, decl) {
   const extras = {};
   const commandEnv = asString(decl.command_env);
@@ -123,6 +138,37 @@ function toSpecServer(name, decl) {
       note: `mcp server '${name}' is disabled in the native manifest and was omitted from ${AGENT_PLUGIN_MCP_FILE}`
     };
   }
+  const declaredType = asString(decl.type);
+  const remoteUrl = asString(decl.url);
+  const remoteType = declaredType === "sse" ? "sse" : declaredType === "streamable-http" || declaredType === "streamable_http" || declaredType === "http" || !declaredType && remoteUrl ? "streamable-http" : void 0;
+  if (remoteType) {
+    if (!remoteUrl) {
+      return {
+        extras,
+        note: `mcp server '${name}' has remote type '${remoteType}' but no url and was omitted`
+      };
+    }
+    const urlNote = validateRemoteUrl(name, remoteUrl);
+    if (urlNote) {
+      return { extras, note: urlNote };
+    }
+    const server2 = {
+      type: remoteType,
+      url: remoteUrl
+    };
+    const headers = toSpecEnv(decl.headers);
+    if (headers) {
+      server2.headers = headers;
+    }
+    const note = decl.auth ? `mcp server '${name}' uses Ryu OAuth metadata that is not portable; static headers were exported` : void 0;
+    return { server: server2, extras, note };
+  }
+  if (declaredType && declaredType !== "stdio") {
+    return {
+      extras,
+      note: `mcp server '${name}' has unsupported transport '${declaredType}' and was omitted`
+    };
+  }
   const command = asString(decl.command);
   if (!command) {
     return {

package/dist/agent-plugin.d.cts

@@ -4,7 +4,9 @@
  * The Agent Plugins Specification (https://agent-plugins.org/, TSC: Amazon,
  * Cursor, Microsoft, OpenAI, Vercel) defines a small portable floor: a plugin is
  * a directory with `plugin.json`, Agent Skills under `skills/<slug>/SKILL.md`,
- * and MCP servers in `mcp.json`. Nothing else is portable.
+ * and MCP servers in `mcp.json`. Native stdio, Streamable HTTP, and legacy SSE
+ * servers all have a direct portable representation; richer Ryu-only fields stay
+ * in the extension namespace or are reported as notes.
  *
  * ## Why this is a SECOND file, not a migration
  *
@@ -69,22 +71,22 @@ declare const AGENT_PLUGIN_MCP_FILE = "mcp.json";
  */
 declare function isAgentPluginManifest(value: unknown): boolean;
 /** Author object — the only three fields the spec permits (§5.4). */
-type AgentPluginAuthor = {
-    name?: string;
+interface AgentPluginAuthor {
     email?: string;
+    name?: string;
     url?: string;
-};
+}
 /** Ryu data carried under {@link AGENT_PLUGIN_EXTENSION_NS}. */
-type RyuExtensionData = {
-    /** The real scoped plugin id (`@ryu/advisor`) — unrecoverable from spec `name`. */
-    id: string;
+interface RyuExtensionData {
     /** Human display name; spec `name` is a slug, not a display string. */
     displayName: string;
+    /** The real scoped plugin id (`@ryu/advisor`) — unrecoverable from spec `name`. */
+    id: string;
     /** Per-MCP-server fields the spec's closed server variants do not allow. */
     mcp?: Record<string, RyuMcpServerExtras>;
-};
+}
 /** Native MCP fields stripped out of the exported `mcp.json`. */
-type RyuMcpServerExtras = {
+interface RyuMcpServerExtras {
     /** Env var that overrides `command` with an absolute path at spawn. */
     command_env?: string;
     /** Human description for our MCP listing endpoint. */
@@ -96,37 +98,43 @@ type RyuMcpServerExtras = {
      * deliberately do not.
      */
     enabled?: false;
-};
+}
 /** A conformant `plugin.json` (§5.2). */
-type AgentPluginJson = {
+interface AgentPluginJson {
     $schema: string;
-    name: string;
-    version?: string;
-    description?: string;
     author?: AgentPluginAuthor;
+    description?: string;
+    extensions: Record<string, unknown>;
     homepage?: string;
-    repository?: string;
-    license?: string;
     keywords?: string[];
-    extensions: Record<string, unknown>;
-};
-/** A stdio server entry (§7.2.1) — the only variant we export. */
-type AgentPluginStdioServer = {
-    type: "stdio";
-    command: string;
+    license?: string;
+    name: string;
+    repository?: string;
+    version?: string;
+}
+/** A stdio server entry (§7.2.1). */
+interface AgentPluginStdioServer {
     args?: string[];
-    env?: Record<string, string>;
+    command: string;
     cwd?: string;
-};
+    env?: Record<string, string>;
+    type: "stdio";
+}
+/** A remote server entry (§7.2.1). */
+interface AgentPluginRemoteServer {
+    headers?: Record<string, string>;
+    type: "streamable-http" | "sse";
+    url: string;
+}
+/** Any server variant a conformant Agent Plugins client can consume. */
+type AgentPluginServer = AgentPluginStdioServer | AgentPluginRemoteServer;
 /** A conformant `mcp.json` (§7.2.1). */
-type AgentPluginMcpJson = {
+interface AgentPluginMcpJson {
     $schema: string;
-    mcpServers: Record<string, AgentPluginStdioServer>;
-};
+    mcpServers: Record<string, AgentPluginServer>;
+}
 /** What {@link toAgentPlugin} produces, plus what it had to leave behind. */
-type AgentPluginExport = {
-    /** The `plugin.json` contents. */
-    plugin: AgentPluginJson;
+interface AgentPluginExport {
     /** The `mcp.json` contents, or null when the plugin exports no server. */
     mcp: AgentPluginMcpJson | null;
     /**
@@ -134,7 +142,9 @@ type AgentPluginExport = {
      * is visible at the call site instead of silent.
      */
     notes: string[];
-};
+    /** The `plugin.json` contents. */
+    plugin: AgentPluginJson;
+}
 /**
  * Project a Ryu plugin id onto a spec-legal `name` (§5.5): 1–64 chars of
  * `a-z 0-9 - .`, alphanumeric at both ends, no `--` and no `..`.
@@ -156,4 +166,4 @@ declare function toSpecName(id: string): string;
  */
 declare function toAgentPlugin(manifest: Record<string, unknown>): AgentPluginExport;
 
-export { AGENT_PLUGINS_SPEC_VERSION, AGENT_PLUGIN_EXTENSION_NS, AGENT_PLUGIN_MANIFEST_FILE, AGENT_PLUGIN_MCP_FILE, AGENT_PLUGIN_MCP_SCHEMA_URL, AGENT_PLUGIN_SCHEMA_URL, type AgentPluginAuthor, type AgentPluginExport, type AgentPluginJson, type AgentPluginMcpJson, type AgentPluginStdioServer, type RyuExtensionData, type RyuMcpServerExtras, isAgentPluginManifest, toAgentPlugin, toSpecName };
+export { AGENT_PLUGINS_SPEC_VERSION, AGENT_PLUGIN_EXTENSION_NS, AGENT_PLUGIN_MANIFEST_FILE, AGENT_PLUGIN_MCP_FILE, AGENT_PLUGIN_MCP_SCHEMA_URL, AGENT_PLUGIN_SCHEMA_URL, type AgentPluginAuthor, type AgentPluginExport, type AgentPluginJson, type AgentPluginMcpJson, type AgentPluginRemoteServer, type AgentPluginServer, type AgentPluginStdioServer, type RyuExtensionData, type RyuMcpServerExtras, isAgentPluginManifest, toAgentPlugin, toSpecName };

package/dist/agent-plugin.d.ts

@@ -4,7 +4,9 @@
  * The Agent Plugins Specification (https://agent-plugins.org/, TSC: Amazon,
  * Cursor, Microsoft, OpenAI, Vercel) defines a small portable floor: a plugin is
  * a directory with `plugin.json`, Agent Skills under `skills/<slug>/SKILL.md`,
- * and MCP servers in `mcp.json`. Nothing else is portable.
+ * and MCP servers in `mcp.json`. Native stdio, Streamable HTTP, and legacy SSE
+ * servers all have a direct portable representation; richer Ryu-only fields stay
+ * in the extension namespace or are reported as notes.
  *
  * ## Why this is a SECOND file, not a migration
  *
@@ -69,22 +71,22 @@ declare const AGENT_PLUGIN_MCP_FILE = "mcp.json";
  */
 declare function isAgentPluginManifest(value: unknown): boolean;
 /** Author object — the only three fields the spec permits (§5.4). */
-type AgentPluginAuthor = {
-    name?: string;
+interface AgentPluginAuthor {
     email?: string;
+    name?: string;
     url?: string;
-};
+}
 /** Ryu data carried under {@link AGENT_PLUGIN_EXTENSION_NS}. */
-type RyuExtensionData = {
-    /** The real scoped plugin id (`@ryu/advisor`) — unrecoverable from spec `name`. */
-    id: string;
+interface RyuExtensionData {
     /** Human display name; spec `name` is a slug, not a display string. */
     displayName: string;
+    /** The real scoped plugin id (`@ryu/advisor`) — unrecoverable from spec `name`. */
+    id: string;
     /** Per-MCP-server fields the spec's closed server variants do not allow. */
     mcp?: Record<string, RyuMcpServerExtras>;
-};
+}
 /** Native MCP fields stripped out of the exported `mcp.json`. */
-type RyuMcpServerExtras = {
+interface RyuMcpServerExtras {
     /** Env var that overrides `command` with an absolute path at spawn. */
     command_env?: string;
     /** Human description for our MCP listing endpoint. */
@@ -96,37 +98,43 @@ type RyuMcpServerExtras = {
      * deliberately do not.
      */
     enabled?: false;
-};
+}
 /** A conformant `plugin.json` (§5.2). */
-type AgentPluginJson = {
+interface AgentPluginJson {
     $schema: string;
-    name: string;
-    version?: string;
-    description?: string;
     author?: AgentPluginAuthor;
+    description?: string;
+    extensions: Record<string, unknown>;
     homepage?: string;
-    repository?: string;
-    license?: string;
     keywords?: string[];
-    extensions: Record<string, unknown>;
-};
-/** A stdio server entry (§7.2.1) — the only variant we export. */
-type AgentPluginStdioServer = {
-    type: "stdio";
-    command: string;
+    license?: string;
+    name: string;
+    repository?: string;
+    version?: string;
+}
+/** A stdio server entry (§7.2.1). */
+interface AgentPluginStdioServer {
     args?: string[];
-    env?: Record<string, string>;
+    command: string;
     cwd?: string;
-};
+    env?: Record<string, string>;
+    type: "stdio";
+}
+/** A remote server entry (§7.2.1). */
+interface AgentPluginRemoteServer {
+    headers?: Record<string, string>;
+    type: "streamable-http" | "sse";
+    url: string;
+}
+/** Any server variant a conformant Agent Plugins client can consume. */
+type AgentPluginServer = AgentPluginStdioServer | AgentPluginRemoteServer;
 /** A conformant `mcp.json` (§7.2.1). */
-type AgentPluginMcpJson = {
+interface AgentPluginMcpJson {
     $schema: string;
-    mcpServers: Record<string, AgentPluginStdioServer>;
-};
+    mcpServers: Record<string, AgentPluginServer>;
+}
 /** What {@link toAgentPlugin} produces, plus what it had to leave behind. */
-type AgentPluginExport = {
-    /** The `plugin.json` contents. */
-    plugin: AgentPluginJson;
+interface AgentPluginExport {
     /** The `mcp.json` contents, or null when the plugin exports no server. */
     mcp: AgentPluginMcpJson | null;
     /**
@@ -134,7 +142,9 @@ type AgentPluginExport = {
      * is visible at the call site instead of silent.
      */
     notes: string[];
-};
+    /** The `plugin.json` contents. */
+    plugin: AgentPluginJson;
+}
 /**
  * Project a Ryu plugin id onto a spec-legal `name` (§5.5): 1–64 chars of
  * `a-z 0-9 - .`, alphanumeric at both ends, no `--` and no `..`.
@@ -156,4 +166,4 @@ declare function toSpecName(id: string): string;
  */
 declare function toAgentPlugin(manifest: Record<string, unknown>): AgentPluginExport;
 
-export { AGENT_PLUGINS_SPEC_VERSION, AGENT_PLUGIN_EXTENSION_NS, AGENT_PLUGIN_MANIFEST_FILE, AGENT_PLUGIN_MCP_FILE, AGENT_PLUGIN_MCP_SCHEMA_URL, AGENT_PLUGIN_SCHEMA_URL, type AgentPluginAuthor, type AgentPluginExport, type AgentPluginJson, type AgentPluginMcpJson, type AgentPluginStdioServer, type RyuExtensionData, type RyuMcpServerExtras, isAgentPluginManifest, toAgentPlugin, toSpecName };
+export { AGENT_PLUGINS_SPEC_VERSION, AGENT_PLUGIN_EXTENSION_NS, AGENT_PLUGIN_MANIFEST_FILE, AGENT_PLUGIN_MCP_FILE, AGENT_PLUGIN_MCP_SCHEMA_URL, AGENT_PLUGIN_SCHEMA_URL, type AgentPluginAuthor, type AgentPluginExport, type AgentPluginJson, type AgentPluginMcpJson, type AgentPluginRemoteServer, type AgentPluginServer, type AgentPluginStdioServer, type RyuExtensionData, type RyuMcpServerExtras, isAgentPluginManifest, toAgentPlugin, toSpecName };

package/dist/agent-plugin.js

@@ -8,7 +8,7 @@ import {
   isAgentPluginManifest,
   toAgentPlugin,
   toSpecName
-} from "./chunk-G6FLVEC4.js";
+} from "./chunk-JX6DDRXV.js";
 export {
   AGENT_PLUGINS_SPEC_VERSION,
   AGENT_PLUGIN_EXTENSION_NS,

package/dist/agent.cjs

@@ -273,6 +273,15 @@ function brokerCall(transport, cap, op, input) {
 }
 function createPrimitives(transport) {
   return {
+    background: {
+      list: (input) => transport.bridge("background.list", {
+        producer: input?.producer,
+        running_only: input?.runningOnly
+      }),
+      stop: (input) => transport.bridge("background.stop", {
+        process_id: input.processId
+      })
+    },
     rag: {
       retrieve: (input) => brokerCall(transport, "rag", "retrieve", input),
       embed: (input) => brokerCall(transport, "rag", "embed", input),