@ryuhq/sdk 0.0.5

package/dist/index.cjs

@@ -0,0 +1,1900 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  Agent: () => Agent,
+  AgentBuilder: () => AgentBuilder,
+  AppBuilder: () => AppBuilder,
+  AppDependencySchema: () => AppDependencySchema,
+  CapabilityReqSchema: () => CapabilityReqSchema,
+  CompanionSurfaceSchema: () => CompanionSurfaceSchema,
+  DEFAULT_GATEWAY_URL: () => DEFAULT_GATEWAY_URL,
+  ModelClient: () => ModelClient2,
+  PRIMITIVE_BINDINGS: () => PRIMITIVE_BINDINGS,
+  PluginBuilder: () => PluginBuilder,
+  PluginManifestSchema: () => PluginManifestSchema,
+  RequiresSchema: () => RequiresSchema,
+  RunnableKindSchema: () => RunnableKindSchema,
+  RunnableMetaSchema: () => RunnableMetaSchema,
+  SkillBuilder: () => SkillBuilder,
+  SurfaceSchema: () => SurfaceSchema,
+  ToolAppConfigSchema: () => ToolAppConfigSchema,
+  ToolBuilder: () => ToolBuilder,
+  WidgetContributionSchema: () => WidgetContributionSchema,
+  WorkflowBuilder: () => WorkflowBuilder,
+  agent: () => agent,
+  app: () => app,
+  appToolId: () => appToolId,
+  assertAllowedEgressUrl: () => assertAllowedEgressUrl,
+  coreManifestJsonSchema: () => coreManifestJsonSchema,
+  createAgent: () => createAgent,
+  createPrimitives: () => createPrimitives,
+  defineAgent: () => defineAgent,
+  defineApp: () => defineApp,
+  defineModel: () => defineModel,
+  definePlugin: () => definePlugin,
+  defineSkill: () => defineSkill,
+  defineTool: () => defineTool,
+  defineTurnHook: () => defineTurnHook,
+  defineWorkflow: () => defineWorkflow,
+  httpPrimitiveTransport: () => httpPrimitiveTransport,
+  inlineToolRunnable: () => inlineToolRunnable,
+  query: () => query,
+  resolveGatewayToken: () => resolveGatewayToken2,
+  resolveGatewayUrl: () => resolveGatewayUrl3,
+  ryuTool: () => ryuTool,
+  skill: () => skill,
+  tool: () => tool,
+  validateManifestStrict: () => validateManifestStrict,
+  validatePluginId: () => validatePluginId,
+  workflow: () => workflow
+});
+module.exports = __toCommonJS(src_exports);
+
+// ../../node_modules/.bun/tsup@8.5.1+7a7b737fa55947b7/node_modules/tsup/assets/cjs_shims.js
+var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
+var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
+
+// src/model/client.ts
+var native = __toESM(require("@ryuhq/sdk-native"), 1);
+var ModelClient2 = class {
+  model;
+  baseUrl;
+  native;
+  constructor(model, options = {}) {
+    this.native = new native.ModelClient(
+      model,
+      options.baseUrl ?? null,
+      options.token ?? null
+    );
+    this.model = model;
+    this.baseUrl = options.baseUrl ?? native.resolveGatewayUrl();
+  }
+  /** Send a non-streaming chat completion request to the gateway. */
+  async chat(messages) {
+    const res = await this.native.chat(messages);
+    const usage = res.promptTokens === void 0 && res.completionTokens === void 0 && res.totalTokens === void 0 ? void 0 : {
+      promptTokens: res.promptTokens ?? 0,
+      completionTokens: res.completionTokens ?? 0,
+      totalTokens: res.totalTokens ?? 0
+    };
+    return {
+      content: res.content,
+      finishReason: res.finishReason ?? null,
+      usage
+    };
+  }
+  /** Send a streaming chat completion request, yielding deltas as they arrive. */
+  async *stream(messages) {
+    const queue = [];
+    let done = false;
+    let failure = null;
+    let wake = null;
+    const notify = () => {
+      if (wake) {
+        const w = wake;
+        wake = null;
+        w();
+      }
+    };
+    this.native.stream(messages, (err, delta) => {
+      if (err) {
+        failure = err;
+        done = true;
+      } else if (delta === null || delta === void 0) {
+        done = true;
+      } else {
+        queue.push({
+          content: delta.content ?? null,
+          finishReason: delta.finishReason ?? null
+        });
+      }
+      notify();
+    });
+    while (true) {
+      while (queue.length > 0) {
+        const next = queue.shift();
+        if (next) {
+          yield next;
+        }
+      }
+      if (failure) {
+        throw failure;
+      }
+      if (done) {
+        return;
+      }
+      await new Promise((resolve) => {
+        wake = resolve;
+      });
+    }
+  }
+};
+function defineModel(modelId, options = {}) {
+  return new ModelClient2(modelId, options);
+}
+
+// src/model/gateway.ts
+var native2 = __toESM(require("@ryuhq/sdk-native"), 1);
+var DEFAULT_GATEWAY_URL = "http://127.0.0.1:7981";
+function resolveGatewayUrl3() {
+  return native2.resolveGatewayUrl();
+}
+function resolveGatewayToken2() {
+  return native2.resolveGatewayToken() ?? void 0;
+}
+function assertAllowedEgressUrl(baseUrl) {
+  native2.assertAllowedEgress(baseUrl);
+}
+
+// src/runnable/primitives.ts
+function dataUrlToBytes(dataUrl) {
+  const match = /^data:([^;,]*)(;base64)?,([\s\S]*)$/.exec(dataUrl);
+  if (!match) {
+    throw new Error(
+      "stt.transcribe expects an `audio` value that is a data: URL (data:<mime>;base64,<data>)"
+    );
+  }
+  const mediaType = match[1] || "application/octet-stream";
+  const isBase64 = Boolean(match[2]);
+  const payload = match[3] ?? "";
+  if (isBase64) {
+    const binary = atob(payload);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return { bytes, mediaType };
+  }
+  return { bytes: new TextEncoder().encode(decodeURIComponent(payload)), mediaType };
+}
+function bytesToDataUrl(bytes, mediaType) {
+  let binary = "";
+  const chunk = 32768;
+  for (let i = 0; i < bytes.length; i += chunk) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+  }
+  return `data:${mediaType};base64,${btoa(binary)}`;
+}
+function httpPrimitiveTransport(options) {
+  const base = options.nodeUrl.replace(/\/+$/, "");
+  assertAllowedEgressUrl(base);
+  const doFetch = options.fetchImpl ?? fetch;
+  const authHeader = () => options.token ? { authorization: `Bearer ${options.token}` } : {};
+  const failDetail = async (path, res) => {
+    const detail = await res.text().catch(() => "");
+    return new Error(
+      `Ryu primitive call ${path} failed: ${res.status} ${res.statusText}${detail ? ` \u2014 ${detail}` : ""}`
+    );
+  };
+  const post = async (path, body) => {
+    const res = await doFetch(`${base}${path}`, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...authHeader() },
+      body: JSON.stringify(body ?? {})
+    });
+    if (!res.ok) {
+      throw await failDetail(path, res);
+    }
+    const text = await res.text();
+    return text ? JSON.parse(text) : void 0;
+  };
+  const transcribeDirect = async (body) => {
+    const input = body ?? {};
+    if (!input.audio) {
+      throw new Error(
+        "stt.transcribe requires an `audio` data: URL (the recorded audio)"
+      );
+    }
+    const { bytes, mediaType } = dataUrlToBytes(input.audio);
+    const form = new FormData();
+    form.append(
+      "file",
+      new Blob([bytes], { type: mediaType || "audio/wav" }),
+      input.filename ?? "recording.wav"
+    );
+    const res = await doFetch(`${base}/api/voice/transcribe`, {
+      method: "POST",
+      headers: authHeader(),
+      body: form
+    });
+    if (!res.ok) {
+      throw await failDetail("/api/voice/transcribe", res);
+    }
+    const parsed = await res.json();
+    return (parsed.text ?? "").trim();
+  };
+  const speakDirect = async (body) => {
+    const res = await doFetch(`${base}/api/voice/speak`, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...authHeader() },
+      body: JSON.stringify(body ?? {})
+    });
+    if (!res.ok) {
+      throw await failDetail("/api/voice/speak", res);
+    }
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    const mediaType = res.headers.get("content-type") || "audio/wav";
+    return bytesToDataUrl(bytes, mediaType);
+  };
+  const generateImageDirect = async (body) => {
+    const res = await doFetch(`${base}/api/images/generate`, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...authHeader() },
+      body: JSON.stringify(body ?? {})
+    });
+    if (!res.ok) {
+      throw await failDetail("/api/images/generate", res);
+    }
+    const parsed = await res.json();
+    return (parsed.data ?? []).map(
+      (item) => item.url ? item.url : `data:image/png;base64,${item.b64_json ?? ""}`
+    );
+  };
+  return {
+    bridge(method, args) {
+      if (!options.pluginId) {
+        return Promise.reject(
+          new Error(
+            `bridge primitive "${method}" requires a pluginId (the /api/plugins/:id/host caller identity)`
+          )
+        );
+      }
+      return post(`/api/plugins/${options.pluginId}/host`, { method, args });
+    },
+    direct(path, body) {
+      if (path === "/api/voice/transcribe") {
+        return transcribeDirect(body);
+      }
+      if (path === "/api/voice/speak") {
+        return speakDirect(body);
+      }
+      if (path === "/api/images/generate") {
+        return generateImageDirect(body);
+      }
+      return post(path, body);
+    },
+    capability(cap, body) {
+      return post(`/api/host/capability/${cap}`, body);
+    }
+  };
+}
+var PRIMITIVE_BINDINGS = {
+  // Bridge families (existing `PluginHookBridge`).
+  "engines.complete": {
+    transport: "bridge",
+    method: "model.complete",
+    grant: "hook:side-model"
+  },
+  // Host-direct media data-path (the host holds the node token; returns data: URLs).
+  "image.generate": {
+    transport: "direct",
+    path: "/api/images/generate",
+    grant: "media:generate"
+  },
+  "tts.speak": {
+    transport: "direct",
+    path: "/api/voice/speak",
+    grant: "media:generate"
+  },
+  "stt.transcribe": {
+    transport: "direct",
+    path: "/api/voice/transcribe",
+    grant: "media:transcribe"
+  },
+  // Broker capabilities — no rpc family yet (@requires-grant).
+  "rag.retrieve": { transport: "broker", capability: "rag" },
+  "rag.embed": { transport: "broker", capability: "rag" },
+  "rag.rerank": { transport: "broker", capability: "rag" },
+  "memory.recall": { transport: "broker", capability: "memory" },
+  "memory.store": { transport: "broker", capability: "memory" },
+  "realtime.broadcast": { transport: "broker", capability: "realtime" },
+  "realtime.subscribe": { transport: "broker", capability: "realtime" },
+  "durable.checkpoint": { transport: "broker", capability: "durable" },
+  "durable.resume": { transport: "broker", capability: "durable" },
+  "engines.embed": { transport: "broker", capability: "engines" }
+};
+function brokerCall(transport, cap, op, input) {
+  return transport.capability(cap, { op, input });
+}
+function createPrimitives(transport) {
+  return {
+    rag: {
+      retrieve: (input) => brokerCall(transport, "rag", "retrieve", input),
+      embed: (input) => brokerCall(transport, "rag", "embed", input),
+      rerank: (input) => brokerCall(transport, "rag", "rerank", input)
+    },
+    memory: {
+      recall: (input) => brokerCall(transport, "memory", "recall", input),
+      store: (input) => brokerCall(transport, "memory", "store", input)
+    },
+    realtime: {
+      broadcast: (input) => brokerCall(transport, "realtime", "broadcast", input).then(
+        () => void 0
+      ),
+      subscribe: (input) => brokerCall(
+        transport,
+        "realtime",
+        "subscribe",
+        input
+      )
+    },
+    durable: {
+      checkpoint: (input) => brokerCall(transport, "durable", "checkpoint", input),
+      resume: (input) => brokerCall(transport, "durable", "resume", input)
+    },
+    engines: {
+      // Bridge family: model.complete → host.sideModel (wire keys are snake_case).
+      complete: (input) => transport.bridge("model.complete", {
+        prompt: input.prompt,
+        system: input.system,
+        model: input.model,
+        model_pref_key: input.modelPrefKey,
+        effort: input.effort
+      }),
+      embed: (input) => brokerCall(transport, "engines", "embed", input)
+    },
+    tts: {
+      speak: (input) => transport.direct("/api/voice/speak", input)
+    },
+    stt: {
+      transcribe: (input) => transport.direct("/api/voice/transcribe", input)
+    },
+    image: {
+      generate: (input) => transport.direct("/api/images/generate", input)
+    }
+  };
+}
+
+// src/agent/model-call.ts
+var CHAT_COMPLETIONS_PATH = "/v1/chat/completions";
+function normalizeBaseUrl(baseUrl) {
+  return baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+}
+async function callModelWithTools(options) {
+  const base = normalizeBaseUrl(options.baseUrl);
+  assertAllowedEgressUrl(base);
+  const body = {
+    model: options.model,
+    messages: options.messages
+  };
+  if (options.tools && options.tools.length > 0) {
+    body.tools = options.tools;
+    if (options.toolChoice) {
+      body.tool_choice = options.toolChoice;
+    }
+  }
+  const headers = {
+    "content-type": "application/json",
+    // Force the gateway's plain-completion branch so our own tool_calls are
+    // returned verbatim on Composio-on managed nodes.
+    "x-ryu-raw-tools": "on"
+  };
+  if (options.token) {
+    headers.authorization = `Bearer ${options.token}`;
+  }
+  const res = await fetch(`${base}${CHAT_COMPLETIONS_PATH}`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+    signal: options.signal
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(
+      `[ryu-sdk] gateway ${res.status} ${res.statusText} at ${base}${CHAT_COMPLETIONS_PATH}${text ? `: ${text}` : ""}`
+    );
+  }
+  const json = await res.json();
+  const choice = json.choices?.[0];
+  const rawMessage = choice?.message;
+  const message = {
+    role: "assistant",
+    content: rawMessage?.content ?? null,
+    ...rawMessage?.tool_calls && rawMessage.tool_calls.length > 0 ? { tool_calls: rawMessage.tool_calls } : {}
+  };
+  const usage = json.usage ? {
+    promptTokens: json.usage.prompt_tokens ?? 0,
+    completionTokens: json.usage.completion_tokens ?? 0,
+    totalTokens: json.usage.total_tokens ?? 0
+  } : void 0;
+  return {
+    message,
+    finishReason: choice?.finish_reason ?? null,
+    usage
+  };
+}
+
+// src/agent/tools.ts
+function ryuTool(id, opts = {}) {
+  return {
+    kind: "remote",
+    id,
+    description: opts.description,
+    parameters: opts.parameters
+  };
+}
+function isLocalTool(tool2) {
+  return tool2.kind === "tool";
+}
+var PERMISSIVE_OBJECT_SCHEMA = {
+  type: "object",
+  additionalProperties: true
+};
+function normalize(baseUrl) {
+  return baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+}
+function authHeaders(token) {
+  const headers = {
+    "content-type": "application/json"
+  };
+  if (token) {
+    headers.authorization = `Bearer ${token}`;
+  }
+  return headers;
+}
+async function resolveToolDefs(tools, ctx) {
+  const defs = [];
+  for (const [name, tool2] of Object.entries(tools)) {
+    if (isLocalTool(tool2)) {
+      defs.push({
+        type: "function",
+        function: {
+          name,
+          description: tool2.name,
+          parameters: tool2.schema
+        }
+      });
+      continue;
+    }
+    let description = tool2.description;
+    if (!description) {
+      description = await describeRemoteTool(tool2.id, ctx);
+    }
+    defs.push({
+      type: "function",
+      function: {
+        name,
+        description: description ?? tool2.id,
+        parameters: tool2.parameters ?? PERMISSIVE_OBJECT_SCHEMA
+      }
+    });
+  }
+  return defs;
+}
+async function describeRemoteTool(id, ctx) {
+  const url = `${normalize(ctx.coreBaseUrl)}/api/tools/describe?id=${encodeURIComponent(id)}`;
+  try {
+    const res = await fetch(url, {
+      headers: authHeaders(ctx.coreToken),
+      signal: ctx.signal
+    });
+    if (!res.ok) {
+      return void 0;
+    }
+    const json = await res.json();
+    return json.description || json.name || void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function executeTool(name, argsJson, tools, ctx) {
+  const tool2 = tools[name];
+  if (!tool2) {
+    throw new Error(`[ryu-sdk] model called unknown tool "${name}"`);
+  }
+  const args = parseArgs(argsJson, name);
+  if (isLocalTool(tool2)) {
+    const output = await tool2.run(
+      args,
+      ctx.runnableContext
+    );
+    return { output };
+  }
+  if (!ctx.agentId) {
+    throw new Error(
+      `[ryu-sdk] remote tool "${name}" (${tool2.id}) requires an agentId \u2014 set it on the Agent config so Core can govern the call`
+    );
+  }
+  const url = `${normalize(ctx.coreBaseUrl)}/api/mcp/tools/call`;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: authHeaders(ctx.coreToken),
+    signal: ctx.signal,
+    body: JSON.stringify({
+      tool: tool2.id,
+      arguments: args,
+      agent_id: ctx.agentId,
+      ...ctx.userId ? { user_id: ctx.userId } : {}
+    })
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(
+      `[ryu-sdk] Core tools/call ${res.status} for "${tool2.id}"${text ? `: ${text}` : ""}`
+    );
+  }
+  const json = await res.json();
+  if (json.ok === false) {
+    throw new Error(
+      `[ryu-sdk] tool "${tool2.id}" failed: ${json.error ?? "unknown error"}`
+    );
+  }
+  return { output: json.output };
+}
+function parseArgs(argsJson, name) {
+  const trimmed = (argsJson ?? "").trim();
+  if (trimmed === "") {
+    return {};
+  }
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    throw new Error(
+      `[ryu-sdk] tool "${name}" arguments were not valid JSON: ${argsJson}`
+    );
+  }
+}
+var ELICITATION_KEY = "__ryu_elicitation__";
+function detectElicitation(output) {
+  if (typeof output !== "object" || output === null) {
+    return null;
+  }
+  const envelope = output[ELICITATION_KEY];
+  if (typeof envelope !== "object" || envelope === null) {
+    return null;
+  }
+  return envelope;
+}
+
+// src/agent/loop.ts
+function safeParse(json) {
+  try {
+    return JSON.parse(json);
+  } catch {
+    return json;
+  }
+}
+function addUsage(a, b) {
+  if (!(a || b)) {
+    return void 0;
+  }
+  return {
+    promptTokens: (a?.promptTokens ?? 0) + (b?.promptTokens ?? 0),
+    completionTokens: (a?.completionTokens ?? 0) + (b?.completionTokens ?? 0),
+    totalTokens: (a?.totalTokens ?? 0) + (b?.totalTokens ?? 0)
+  };
+}
+function findElicitation(output) {
+  const direct = detectElicitation(output);
+  if (direct) {
+    return direct;
+  }
+  if (typeof output === "string") {
+    return detectElicitation(safeParse(output));
+  }
+  return null;
+}
+async function* runAgentLoop(config) {
+  const messages = [...config.messages];
+  let toolDefs;
+  try {
+    toolDefs = await resolveToolDefs(config.tools, config.toolCtx);
+  } catch (err) {
+    yield { type: "error", message: describeError(err) };
+    return;
+  }
+  let usage;
+  let lastText = "";
+  for (let step = 1; step <= config.maxSteps; step++) {
+    let result;
+    try {
+      result = await callModelWithTools({
+        baseUrl: config.gatewayBaseUrl,
+        token: config.gatewayToken,
+        model: config.model,
+        messages,
+        tools: toolDefs.length > 0 ? toolDefs : void 0,
+        toolChoice: toolDefs.length > 0 ? "auto" : void 0,
+        signal: config.signal
+      });
+    } catch (err) {
+      yield { type: "error", message: describeError(err) };
+      return;
+    }
+    usage = addUsage(usage, result.usage);
+    const assistant = result.message;
+    messages.push(assistant);
+    if (assistant.content) {
+      lastText = assistant.content;
+      yield { type: "text", content: assistant.content };
+    }
+    const toolCalls = assistant.tool_calls ?? [];
+    if (toolCalls.length === 0) {
+      yield { type: "result", text: lastText, steps: step, usage };
+      return;
+    }
+    const paused = yield* runToolCalls(toolCalls, messages, config);
+    if (paused) {
+      return;
+    }
+  }
+  yield { type: "result", text: lastText, steps: config.maxSteps, usage };
+}
+async function* runToolCalls(toolCalls, messages, config) {
+  for (const call of toolCalls) {
+    const name = call.function.name;
+    const input = safeParse(call.function.arguments);
+    yield { type: "tool_call", id: call.id, name, input };
+    let output;
+    try {
+      const res = await executeTool(
+        name,
+        call.function.arguments,
+        config.tools,
+        config.toolCtx
+      );
+      output = res.output;
+    } catch (err) {
+      const errPayload = { error: describeError(err) };
+      messages.push({
+        role: "tool",
+        tool_call_id: call.id,
+        content: JSON.stringify(errPayload)
+      });
+      yield { type: "tool_result", id: call.id, name, output: errPayload };
+      continue;
+    }
+    const elicitation = findElicitation(output);
+    if (elicitation) {
+      yield {
+        type: "auth_required",
+        tool: name,
+        url: elicitation.url,
+        message: elicitation.message
+      };
+      return true;
+    }
+    messages.push({
+      role: "tool",
+      tool_call_id: call.id,
+      content: typeof output === "string" ? output : JSON.stringify(output)
+    });
+    yield { type: "tool_result", id: call.id, name, output };
+  }
+  return false;
+}
+function describeError(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/agent/agent.ts
+var DEFAULT_MAX_STEPS = 10;
+var DEFAULT_CORE_URL = "http://127.0.0.1:7980";
+function env(key) {
+  const value = globalThis.process?.env?.[key];
+  return value && value !== "" ? value : void 0;
+}
+function lazyGatewayClient(model, baseUrl, token) {
+  let client = null;
+  const get = () => {
+    client ??= defineModel(model, { baseUrl, token });
+    return client;
+  };
+  return {
+    chat: (messages) => get().chat(messages),
+    stream: (messages) => get().stream(messages)
+  };
+}
+var Agent = class {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  /** Assemble the loop config for a given prompt. */
+  buildLoopConfig(prompt, signal) {
+    const gatewayBaseUrl = this.config.node?.baseUrl ?? resolveGatewayUrl3();
+    const gatewayToken = this.config.node?.token ?? resolveGatewayToken2();
+    const coreBaseUrl = this.config.core?.baseUrl ?? env("RYU_CORE_URL") ?? DEFAULT_CORE_URL;
+    const coreToken = this.config.core?.token ?? env("RYU_TOKEN");
+    const messages = [];
+    if (this.config.instructions) {
+      messages.push({ role: "system", content: this.config.instructions });
+    }
+    messages.push({ role: "user", content: prompt });
+    const toolCtx = {
+      agentId: this.config.agentId,
+      coreBaseUrl,
+      coreToken,
+      userId: this.config.userId,
+      signal,
+      runnableContext: {
+        gateway: lazyGatewayClient(
+          this.config.model,
+          gatewayBaseUrl,
+          gatewayToken
+        ),
+        signal,
+        // Mount the composable primitive surface only when a plugin id is
+        // present — the bridge families authenticate it, so we never attach a
+        // half-wired transport (advisor guidance / §6b).
+        ...this.config.pluginId ? createPrimitives(
+          httpPrimitiveTransport({
+            nodeUrl: coreBaseUrl,
+            token: coreToken,
+            pluginId: this.config.pluginId
+          })
+        ) : {}
+      }
+    };
+    return {
+      model: this.config.model,
+      gatewayBaseUrl,
+      gatewayToken,
+      messages,
+      tools: this.config.tools ?? {},
+      toolCtx,
+      maxSteps: this.config.maxSteps ?? DEFAULT_MAX_STEPS,
+      signal
+    };
+  }
+  /** Stream loop events (text / tool_call / tool_result / auth_required / …). */
+  stream(prompt, signal) {
+    return runAgentLoop(this.buildLoopConfig(prompt, signal));
+  }
+  /** Run to completion and return the final text, step count, and usage. */
+  async generate(prompt, signal) {
+    let text = "";
+    let steps = 0;
+    let usage;
+    let authRequired;
+    for await (const event of this.stream(prompt, signal)) {
+      if (event.type === "result") {
+        text = event.text;
+        steps = event.steps;
+        usage = event.usage;
+      } else if (event.type === "auth_required") {
+        authRequired = event;
+      } else if (event.type === "error") {
+        throw new Error(
+          `[ryu-sdk] agent "${this.config.name}": ${event.message}`
+        );
+      }
+    }
+    return { text, steps, usage, authRequired };
+  }
+};
+function createAgent(config) {
+  return new Agent(config);
+}
+
+// src/agent/query.ts
+function query(input) {
+  const agent2 = new Agent({
+    name: input.options.name ?? "agent",
+    ...input.options
+  });
+  return agent2.stream(input.prompt);
+}
+
+// src/manifest.ts
+var import_node_module = require("module");
+var import_zod = require("zod");
+var cachedNative = null;
+var nativeLoadError = null;
+function loadNative() {
+  if (cachedNative) {
+    return cachedNative;
+  }
+  if (nativeLoadError) {
+    throw nativeLoadError;
+  }
+  try {
+    const req = (0, import_node_module.createRequire)(importMetaUrl);
+    cachedNative = req("@ryuhq/sdk-native");
+    return cachedNative;
+  } catch (cause) {
+    nativeLoadError = new Error(
+      "@ryuhq/sdk-native (the Rust-cored napi addon) is not available; Core-strict manifest validation requires it. Build/install the addon, or use PluginManifestSchema (pure-JS zod) for authoring-time validation.",
+      { cause }
+    );
+    throw nativeLoadError;
+  }
+}
+var RunnableKindSchema = import_zod.z.enum([
+  "agent",
+  "workflow",
+  "tool",
+  "skill",
+  // A companion surface (in-desktop panel). Added so a packable plugin can
+  // declare a companion runnable that flows through Core's existing Companion
+  // handler → app_contrib → `GET /api/plugins/contributions` → the desktop
+  // `/plugin/<id>` route. Its `config.ui_entry` (see `CompanionRunnableConfigSchema`)
+  // is what `ryu pack` bundles into `ui_code`.
+  "companion"
+]);
+var RunnableMetaSchema = import_zod.z.object({
+  /** Stable unique identifier (e.g. `"agent-researcher"`). */
+  id: import_zod.z.string().min(1),
+  /** Human-readable display name. */
+  name: import_zod.z.string().min(1),
+  /** Which kind of runnable this entry describes. */
+  kind: RunnableKindSchema,
+  /**
+   * Optional per-kind config blob. Mirrors Core's `RunnableEntry.config`
+   * (`Option<serde_json::Value>`) so a manifest authored here round-trips
+   * through Core-strict validation. Left opaque (a record) at this authoring
+   * layer; the per-kind shape is enforced by Core's `validate_runnable`.
+   *
+   * For a `companion` runnable, `config.ui_entry` names the plugin's UI entry
+   * module (relative to the manifest dir). `ryu pack` bundles that entry into
+   * the emitted `ui_code`; Core's `CompanionConfig.ui_entry` is the lockstep
+   * field so a packed companion validates.
+   */
+  config: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional()
+});
+function labelImpersonatesSystemChrome(label) {
+  const lower = label.toLowerCase();
+  return lower.includes("ryu") || lower.includes("system");
+}
+var CompanionSurfaceSchema = import_zod.z.object({
+  /** Display label for the companion panel tab or tooltip. Anti-impersonation:
+   *  may not pose as first-party Ryu/system chrome (see
+   *  {@link labelImpersonatesSystemChrome}). */
+  label: import_zod.z.string().min(1).refine((value) => !labelImpersonatesSystemChrome(value), {
+    message: "companion label must not impersonate system chrome (must not contain 'ryu' or 'system')"
+  }),
+  /** Icon identifier resolved by the desktop shell. */
+  icon: import_zod.z.string().optional(),
+  /** Keyboard shortcut string (e.g. `"ctrl+shift+r"`). */
+  shortcut: import_zod.z.string().optional()
+});
+var TurnHookContributionSchema = import_zod.z.object({
+  /** Stable id for this hook (unique within the plugin). */
+  id: import_zod.z.string().min(1),
+  /** Turn boundary this fires on. Today only `"post_assistant_turn"`. */
+  on: import_zod.z.string().min(1).default("post_assistant_turn"),
+  /** The JS hook body executed in the sandbox (returns a directive). */
+  code: import_zod.z.string().min(1)
+});
+var DEFAULT_WIDGET_MIME = "text/html+skybridge";
+var DEFAULT_WIDGET_DISPLAY_MODE = "inline";
+var WidgetContributionSchema = import_zod.z.object({
+  /** The fully-qualified tool id whose result renders this widget. */
+  tool_id: import_zod.z.string().min(1),
+  /** `ui://widget/<slug>.html` — the widget resource uri. */
+  uri: import_zod.z.string().min(1),
+  /** Source entry (e.g. `src/apps/checklist/index.tsx`) for `ryu pack`. */
+  ui_entry: import_zod.z.string().optional(),
+  /** Widget MIME dialect (default `text/html+skybridge`). */
+  mime: import_zod.z.string().default(DEFAULT_WIDGET_MIME),
+  /** Default display mode (`inline` | `fullscreen` | `pip`). */
+  default_display_mode: import_zod.z.string().default(DEFAULT_WIDGET_DISPLAY_MODE)
+});
+var ToolAppConfigSchema = import_zod.z.object({
+  /** MCP tool slug this runnable wraps — the fully-qualified `<server>__<name>` id. */
+  slug: import_zod.z.string().min(1),
+  /** The tool description the model reads when choosing it. Carried here because a
+   *  packed app's manifest is the only channel (there is no `generated.rs`); Core's
+   *  app-tool synthesis reads it back onto the `RegistryTool`. */
+  description: import_zod.z.string(),
+  /** JSON Schema for the tool's arguments (used for validation + the LLM tool
+   *  surface). Snake_case to match `widget_accessible`. Absent = no arguments. */
+  input_schema: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional(),
+  /** True when calling this tool renders the app's widget (carries the template). */
+  widget: import_zod.z.boolean().default(false),
+  /** True when a mounted widget may `callTool` this tool (a companion), or when a
+   *  render tool's widget may call any companion the app declares. */
+  widget_accessible: import_zod.z.boolean().default(false),
+  /** Optional status label shown while the render tool runs. */
+  invoking: import_zod.z.string().optional(),
+  /** Optional status label shown when the render tool finishes. */
+  invoked: import_zod.z.string().optional()
+});
+var ContributesSchema = import_zod.z.object({
+  turn_hooks: import_zod.z.array(TurnHookContributionSchema).default([]),
+  composer_controls: 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([]),
+  /** 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
+   *  every widget an app authored here declares. */
+  widgets: import_zod.z.array(WidgetContributionSchema).default([])
+});
+var SetupStepSchema = import_zod.z.object({
+  /** Card heading (e.g. the companion app name). */
+  title: import_zod.z.string().optional(),
+  /** Instruction body shown under the title. */
+  description: import_zod.z.string().optional(),
+  /** Label for the optional action button. */
+  actionLabel: import_zod.z.string().optional(),
+  /** URL the action button opens (validated server-side on publish). */
+  actionUrl: import_zod.z.string().optional()
+});
+var AppDependencySchema = import_zod.z.object({
+  /** The `id` of the plugin this one depends on. */
+  id: import_zod.z.string().min(1, "dependency id is required"),
+  /** Optional MINIMUM version the dependency must satisfy (`"1.2.0"` = `">=1.2.0"`). */
+  min_version: import_zod.z.string().min(1).optional()
+});
+var CapabilityReqSchema = import_zod.z.object({
+  /** Capability name (e.g. `"rag"`, `"memory"`, `"tts"`). Matched against a
+   *  provider's `provides[].capability`. */
+  capability: import_zod.z.string().min(1, "capability name is required"),
+  /** Optional MINIMUM capability version the bound provider must satisfy
+   *  (`"1.2.0"` = `">=1.2.0"`). Absent = any version. */
+  min_version: import_zod.z.string().min(1).optional()
+});
+var RequiresSchema = import_zod.z.object({
+  /** Other plugins that must be installed + enabled before this one enables. */
+  apps: import_zod.z.array(AppDependencySchema).default([]),
+  /**
+   * Abstract capability edges the broker resolves to a bound provider at
+   * enable time. Mirrors `Requires::capabilities` in
+   * `crates/ryu-kernel-contracts` — an `apps` edge names a specific plugin; a
+   * `capabilities` edge names a capability and lets the binding registry choose
+   * the provider. Each is lowered to an app-id graph edge once bound, so the
+   * enable/disable/cycle machinery is shared. Empty for the common case.
+   */
+  capabilities: import_zod.z.array(CapabilityReqSchema).default([]),
+  /**
+   * Permission grants implied by the dependencies. Declaration only — the
+   * Gateway remains the sole authority on what a grant *allows*, and Core's
+   * dependency graph resolves `apps` only.
+   */
+  grants: import_zod.z.array(import_zod.z.string()).default([])
+});
+var SurfaceSchema = import_zod.z.enum([
+  /** The Ryu Gateway. */
+  "gateway",
+  /** A headless Core node (no UI). */
+  "core",
+  /** The Tauri desktop app. */
+  "desktop",
+  /** The Electron dynamic-island companion. */
+  "island",
+  /** The Expo/React-Native mobile app. */
+  "mobile",
+  /** The browser extension. */
+  "extension",
+  /** The Next.js web app. */
+  "web",
+  /** The terminal client. */
+  "cli"
+]);
+var PluginManifestSchema = import_zod.z.object({
+  /** Reverse-domain unique identifier (e.g. `"com.example.my-plugin"`). */
+  id: import_zod.z.string().min(1, "id is required"),
+  /** Human-readable display name shown in the plugin store / launcher. */
+  name: import_zod.z.string().min(1, "name is required"),
+  /**
+   * Semver version string (e.g. `"1.0.0"`). Core's loader rejects any manifest
+   * whose version is not valid semver; the regex here enforces the same rule at
+   * SDK-build time.
+   */
+  version: import_zod.z.string().regex(
+    /^\d+\.\d+\.\d+(?:-[\w.]+)?(?:\+[\w.]+)?$/,
+    "version must be a valid semver string (e.g. 1.0.0)"
+  ),
+  /**
+   * 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
+   * write it here BEFORE the manifest is signed, so the hash rides INSIDE the
+   * Gateway-signed surface while the `ui_code` blob rides OUTSIDE it as payload;
+   * Core's install path recomputes the hash over the fetched code and rejects a
+   * mismatch fail-closed. Absent for a manifest-only plugin (no bundled UI).
+   * Mirrors Core's `PluginManifest.ui_code_sha256`.
+   */
+  ui_code_sha256: import_zod.z.string().nullish(),
+  /** The Runnables this plugin bundles. */
+  runnables: import_zod.z.array(RunnableMetaSchema).default([]),
+  /**
+   * Permission grants this plugin declares it needs (e.g. `"mcp:web_search"`).
+   * Declarations only — grant enforcement is the Gateway's responsibility.
+   */
+  permission_grants: import_zod.z.array(import_zod.z.string()).default([]),
+  /**
+   * Optional Companion surface (an in-desktop overlay or sidebar panel).
+   * Absent when the plugin has no Companion surface.
+   */
+  companion: CompanionSurfaceSchema.optional(),
+  /**
+   * VS-Code-style activation events (`"*"`, `"onStartup"`, `"onChat"`,
+   * `"onCommand:<id>"`). Empty = eager. Turn-hook plugins are driven by their
+   * enabled flag, so `["*"]` is the usual value.
+   */
+  activation_events: import_zod.z.array(import_zod.z.string()).default([]),
+  /**
+   * Contribution points: server-side turn hooks + declarative UI widgets.
+   * Absent for a plugin that contributes nothing here.
+   */
+  contributes: ContributesSchema.optional(),
+  /**
+   * **Plugin-to-plugin dependencies** — the other plugins this one needs. Core
+   * resolves them into a topological enable order (dependencies enable first;
+   * disabling one is refused while an enabled dependent needs it).
+   *
+   * Absent = **no dependencies**, the backward-compatible default. Kept
+   * `.optional()` (never defaulted) so a manifest that declares none serialises
+   * with no `requires` key at all, exactly like Core's
+   * `#[serde(skip_serializing_if = "Option::is_none")]`.
+   */
+  requires: RequiresSchema.optional(),
+  /**
+   * Host surfaces this plugin runs on. **Empty or absent = runs on EVERY
+   * surface** — the backward-compatible default, which must never be read as
+   * "runs nowhere". Core filters only when the list is explicitly non-empty, and
+   * only at the read boundary (`GET /api/plugins`, keyed on `x-ryu-surface`), so
+   * an unsupported-target plugin stays installable and inspectable.
+   */
+  targets: import_zod.z.array(SurfaceSchema).default([]),
+  /**
+   * Optional per-item AFFILIATE terms: the commission paid to a referrer when a
+   * referred user buys this (paid) item. `value` is basis points for `percent`
+   * (2000 = 20%) or minor units (cents) for `flat`. Absent (or `enabled:false`)
+   * falls back to the seller org owner's default affiliate terms. This is the
+   * authoring surface for the marketplace publish body's `affiliate` field (the
+   * server re-validates it); it only takes effect on a paid item.
+   */
+  affiliate: import_zod.z.object({
+    enabled: import_zod.z.boolean().default(false),
+    rule: import_zod.z.object({
+      type: import_zod.z.enum(["percent", "flat"]),
+      value: import_zod.z.number().nonnegative(),
+      recurring: import_zod.z.boolean().default(false),
+      durationMonths: import_zod.z.number().int().positive().nullish(),
+      fundedBy: import_zod.z.enum(["platform", "seller"]).default("platform")
+    }).optional()
+  }).optional(),
+  // ── Rich listing metadata (Phase 1.5) ──────────────────────────────────────
+  // Optional store-listing fields a plugin author declares so the marketplace
+  // detail dialog renders a richer App-Store-style preview. Field names align
+  // with the Claude `.claude-plugin/marketplace.json` plugin-entry standard where
+  // one exists (`author`, `homepage`, `keywords`, `category`, `license`); the
+  // rest are Ryu extensions. `ryu publish` forwards these FLAT into the publish
+  // body (not inside the signed manifest blob) so the control plane stores them.
+  // All optional + additive: a manifest omitting them still validates.
+  /** Longer plain/markdown description shown in the detail dialog. */
+  description: import_zod.z.string().optional(),
+  /** Short one-line pitch shown under the name (Ryu extension). */
+  tagline: import_zod.z.string().optional(),
+  /**
+   * Publisher identity. A bare string OR a Claude-style object; `ryu publish`
+   * resolves it to the display `developer` (`author.name` when an object).
+   */
+  author: import_zod.z.union([
+    import_zod.z.string(),
+    import_zod.z.object({
+      name: import_zod.z.string(),
+      email: import_zod.z.string().optional(),
+      url: import_zod.z.string().optional()
+    })
+  ]).optional(),
+  /** Project/marketing homepage — maps to the listing `website` (Claude field). */
+  homepage: import_zod.z.string().optional(),
+  /** Free-text search keywords (Claude field). */
+  keywords: import_zod.z.array(import_zod.z.string()).optional(),
+  /** Taxonomy category beyond the runnable kinds (Claude field). */
+  category: import_zod.z.string().optional(),
+  /** SPDX-ish license identifier (Claude field). */
+  license: import_zod.z.string().optional(),
+  /** Square logo/icon URL for the listing card + detail header. */
+  iconUrl: import_zod.z.string().optional(),
+  /** Ordered App-Store-style screenshot gallery URLs (Ryu extension). */
+  screenshots: import_zod.z.array(import_zod.z.string()).optional(),
+  /** Privacy policy URL surfaced on detail (Ryu extension). */
+  privacyPolicyUrl: import_zod.z.string().optional(),
+  /** Terms-of-service URL surfaced on detail (Ryu extension). */
+  termsOfServiceUrl: import_zod.z.string().optional(),
+  /**
+   * Human-readable capability strings (Ryu extension). When omitted the control
+   * plane derives a default from `permission_grants`, so declaring this is only
+   * needed to override the derived labels.
+   */
+  capabilities: import_zod.z.array(import_zod.z.string()).optional(),
+  /** Example prompt chips shown on detail (Ryu extension). */
+  examplePrompts: import_zod.z.array(import_zod.z.string()).optional(),
+  /**
+   * Optional companion/config card (Ryu extension): a single setup step or an
+   * array of steps guiding the user through post-install configuration.
+   */
+  setup: import_zod.z.union([SetupStepSchema, import_zod.z.array(SetupStepSchema)]).optional()
+});
+function validatePluginId(id) {
+  loadNative().validatePluginId(id);
+}
+function validateManifestStrict(manifestJson) {
+  return loadNative().parseAndValidateManifest(manifestJson);
+}
+function coreManifestJsonSchema() {
+  return JSON.parse(loadNative().pluginManifestJsonSchema());
+}
+
+// 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
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  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
+});