@ryuhq/sdk 0.0.5

package/dist/chunk-KPKMMGVC.js

@@ -0,0 +1,671 @@
+import {
+  assertAllowedEgressUrl,
+  defineModel,
+  resolveGatewayToken,
+  resolveGatewayUrl
+} from "./chunk-ODFEUVPW.js";
+
+// 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(tool) {
+  return tool.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, tool] of Object.entries(tools)) {
+    if (isLocalTool(tool)) {
+      defs.push({
+        type: "function",
+        function: {
+          name,
+          description: tool.name,
+          parameters: tool.schema
+        }
+      });
+      continue;
+    }
+    let description = tool.description;
+    if (!description) {
+      description = await describeRemoteTool(tool.id, ctx);
+    }
+    defs.push({
+      type: "function",
+      function: {
+        name,
+        description: description ?? tool.id,
+        parameters: tool.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 tool = tools[name];
+  if (!tool) {
+    throw new Error(`[ryu-sdk] model called unknown tool "${name}"`);
+  }
+  const args = parseArgs(argsJson, name);
+  if (isLocalTool(tool)) {
+    const output = await tool.run(
+      args,
+      ctx.runnableContext
+    );
+    return { output };
+  }
+  if (!ctx.agentId) {
+    throw new Error(
+      `[ryu-sdk] remote tool "${name}" (${tool.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: tool.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 "${tool.id}"${text ? `: ${text}` : ""}`
+    );
+  }
+  const json = await res.json();
+  if (json.ok === false) {
+    throw new Error(
+      `[ryu-sdk] tool "${tool.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 ?? resolveGatewayUrl();
+    const gatewayToken = this.config.node?.token ?? resolveGatewayToken();
+    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 agent = new Agent({
+    name: input.options.name ?? "agent",
+    ...input.options
+  });
+  return agent.stream(input.prompt);
+}
+
+export {
+  httpPrimitiveTransport,
+  PRIMITIVE_BINDINGS,
+  createPrimitives,
+  callModelWithTools,
+  ryuTool,
+  resolveToolDefs,
+  executeTool,
+  detectElicitation,
+  runAgentLoop,
+  Agent,
+  createAgent,
+  query
+};