@ryuhq/sdk 0.0.5

package/src/agent/model-call.ts

@@ -0,0 +1,190 @@
+/**
+ * Native tool-calling model call for the Ryu agent runtime.
+ *
+ * The gateway-mandatory `ModelClient` (packages/sdk/src/model/client.ts) only
+ * exposes text `chat`/`stream` — it cannot pass a `tools` array or receive
+ * `tool_calls`. The autonomous agent loop needs both, so this module makes a
+ * direct request to the node's gateway `POST /v1/chat/completions` endpoint
+ * with the caller's own `tools` and reads back `message.tool_calls`.
+ *
+ * The no-direct-provider guarantee is preserved: `assertAllowedEgressUrl` (the
+ * same Rust-cored blocklist the ModelClient uses) is called before every fetch,
+ * so a direct provider base URL throws exactly as it would elsewhere in the SDK.
+ *
+ * `x-ryu-raw-tools: on` is always sent. On a plain gateway it is a harmless
+ * no-op; on a Composio-on managed node it forces the plain completion branch so
+ * the caller's `tool_calls` are returned verbatim instead of being intercepted
+ * and executed by Core's own tool loop (see apps/gateway/src/pipeline/mod.rs).
+ */
+
+import { assertAllowedEgressUrl } from "../model/gateway.ts";
+
+// ── OpenAI-compatible wire types (function-calling subset) ────────────────────
+
+/** An OpenAI function tool definition passed to the model. */
+export interface ToolFunctionDef {
+	function: {
+		description?: string;
+		name: string;
+		/** JSON Schema for the function's arguments. */
+		parameters: Record<string, unknown>;
+	};
+	type: "function";
+}
+
+/** A single tool call emitted by the model. */
+export interface ToolCall {
+	function: {
+		/** JSON-encoded arguments string (per the OpenAI wire format). */
+		arguments: string;
+		name: string;
+	};
+	id: string;
+	type: "function";
+}
+
+/** An assistant turn — may carry text, tool calls, or both. */
+export interface AssistantMessage {
+	content: string | null;
+	role: "assistant";
+	tool_calls?: ToolCall[];
+}
+
+/** A message in the loop's running transcript. */
+export type LoopMessage =
+	| { content: string; role: "system" | "user" }
+	| AssistantMessage
+	| { content: string; role: "tool"; tool_call_id: string };
+
+/** Token usage as reported by the gateway (optional — gateway may omit). */
+export interface ModelUsage {
+	completionTokens: number;
+	promptTokens: number;
+	totalTokens: number;
+}
+
+/** Options for a single native tool-calling completion. */
+export interface ModelCallOptions {
+	/** Gateway base URL (no trailing `/v1`). */
+	baseUrl: string;
+	/** Running transcript. */
+	messages: LoopMessage[];
+	/** Model id routed by the gateway (provider is derived from the id). */
+	model: string;
+	/** Abort signal for cancellation. */
+	signal?: AbortSignal;
+	/** Bearer token forwarded to the gateway (never a provider key). */
+	token?: string;
+	/** How the model should choose tools; defaults to gateway/provider default. */
+	toolChoice?: "auto" | "none" | "required";
+	/** Function tool definitions the model may call. */
+	tools?: ToolFunctionDef[];
+}
+
+/** Result of a single completion. */
+export interface ModelCallResult {
+	finishReason: string | null;
+	message: AssistantMessage;
+	usage?: ModelUsage;
+}
+
+// ── Internal response shape (minimal subset we read) ──────────────────────────
+
+interface ChatCompletionResponse {
+	choices?: Array<{
+		finish_reason?: string | null;
+		message?: {
+			content?: string | null;
+			tool_calls?: ToolCall[];
+		};
+	}>;
+	usage?: {
+		completion_tokens?: number;
+		prompt_tokens?: number;
+		total_tokens?: number;
+	};
+}
+
+const CHAT_COMPLETIONS_PATH = "/v1/chat/completions";
+
+/** Strip a trailing slash so `baseUrl + path` never doubles up. */
+function normalizeBaseUrl(baseUrl: string): string {
+	return baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+}
+
+/**
+ * Call the node's gateway with the caller's own tools and return the first
+ * choice, including any `tool_calls`.
+ *
+ * Throws when the base URL is a direct provider (egress enforcement) or when
+ * the gateway returns a non-2xx status.
+ */
+export async function callModelWithTools(
+	options: ModelCallOptions
+): Promise<ModelCallResult> {
+	const base = normalizeBaseUrl(options.baseUrl);
+	// Preserve the BYOK-at-the-gateway rule — same blocklist as ModelClient.
+	assertAllowedEgressUrl(base);
+
+	const body: Record<string, unknown> = {
+		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: Record<string, string> = {
+		"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()) as ChatCompletionResponse;
+	const choice = json.choices?.[0];
+	const rawMessage = choice?.message;
+	const message: AssistantMessage = {
+		role: "assistant",
+		content: rawMessage?.content ?? null,
+		...(rawMessage?.tool_calls && rawMessage.tool_calls.length > 0
+			? { tool_calls: rawMessage.tool_calls }
+			: {}),
+	};
+
+	const usage: ModelUsage | undefined = json.usage
+		? {
+				promptTokens: json.usage.prompt_tokens ?? 0,
+				completionTokens: json.usage.completion_tokens ?? 0,
+				totalTokens: json.usage.total_tokens ?? 0,
+			}
+		: undefined;
+
+	return {
+		message,
+		finishReason: choice?.finish_reason ?? null,
+		usage,
+	};
+}

package/src/agent/query.ts

@@ -0,0 +1,40 @@
+/**
+ * `query()` — Claude-Agent-SDK-style streaming entry over the same `Agent`.
+ *
+ * Where `Agent` gives you Mastra's config-object + method shape, `query()` gives
+ * you the `for await (const msg of query({ prompt, options }))` ergonomics of
+ * the Claude Agent SDK. Both drive the identical loop; this is a thin wrapper.
+ */
+
+import { Agent, type AgentConfig } from "./agent.ts";
+import type { AgentEvent } from "./loop.ts";
+
+/** Options accepted by `query` — an `AgentConfig` with an optional `name`. */
+export type QueryOptions = Omit<AgentConfig, "name"> & { name?: string };
+
+/** Input to `query`: a prompt plus agent options. */
+export interface QueryInput {
+	options: QueryOptions;
+	prompt: string;
+}
+
+/**
+ * Run an agent for a single prompt and stream its events.
+ *
+ * @example
+ * ```ts
+ * for await (const msg of query({
+ *   prompt: "Find my expenses from last month.",
+ *   options: { model: "gpt-4o", agentId: "agent-expense", tools: { gmailSearch } },
+ * })) {
+ *   if (msg.type === "result") console.log(msg.text);
+ * }
+ * ```
+ */
+export function query(input: QueryInput): AsyncGenerator<AgentEvent> {
+	const agent = new Agent({
+		name: input.options.name ?? "agent",
+		...input.options,
+	});
+	return agent.stream(input.prompt);
+}

package/src/agent/tools.ts

@@ -0,0 +1,295 @@
+/**
+ * Tool resolution + execution for the Ryu agent runtime.
+ *
+ * Two kinds of tool feed the same model `tools[]` array:
+ *
+ *  - **Local** tools are `ToolRunnable`s from `defineTool` — they run in-process
+ *    via their `run(input, ctx)` implementation.
+ *  - **Remote** tools are references to existing Ryu tools (e.g.
+ *    `composio__GMAIL_SEARCH_EMAILS`) created with `ryuTool(id)`. Their schema is
+ *    lazily fetched from Core `GET /api/tools/describe` and they execute through
+ *    Core `POST /api/mcp/tools/call`, which enforces the agent's allowlist and
+ *    selects the Composio connected-account entity via `user_id`.
+ *
+ * The model-facing function name is the **config key** the developer chose (e.g.
+ * `gmailSearch`), not the raw Composio slug — internals stay hidden and names
+ * stay OpenAI-safe.
+ */
+
+import type { RunnableContext } from "../runnable/runnable-types.ts";
+import type { ToolRunnable } from "../runnable/tool.ts";
+import type { ToolFunctionDef } from "./model-call.ts";
+
+// ── Remote tool reference ─────────────────────────────────────────────────────
+
+/** A reference to an existing Ryu tool, resolved + executed via Core. */
+export interface RemoteToolRef {
+	/** One-line description shown to the model (overrides Core's describe). */
+	description?: string;
+	/** Fully-qualified Ryu tool id, e.g. `composio__GMAIL_SEARCH_EMAILS`. */
+	id: string;
+	readonly kind: "remote";
+	/**
+	 * JSON Schema for the tool's arguments. Optional: when omitted, a permissive
+	 * open-object schema is used (Composio `describe` is shallow), so supplying
+	 * this materially improves the model's tool-call accuracy.
+	 */
+	parameters?: Record<string, unknown>;
+}
+
+/** Options accepted by `ryuTool`. */
+export interface RyuToolOptions {
+	description?: string;
+	parameters?: Record<string, unknown>;
+}
+
+/**
+ * Reference an existing Ryu tool by id so an `Agent` can call it.
+ *
+ * @example
+ * ```ts
+ * ryuTool("composio__GMAIL_SEARCH_EMAILS", {
+ *   description: "Search the user's Gmail",
+ *   parameters: { type: "object", properties: { query: { type: "string" } }, required: ["query"] },
+ * });
+ * ```
+ */
+export function ryuTool(id: string, opts: RyuToolOptions = {}): RemoteToolRef {
+	return {
+		kind: "remote",
+		id,
+		description: opts.description,
+		parameters: opts.parameters,
+	};
+}
+
+/** A tool an `Agent` can expose to the model: local runnable or remote ref. */
+export type AgentTool = RemoteToolRef | ToolRunnable;
+
+/** Narrow to a local `defineTool` runnable. */
+function isLocalTool(tool: AgentTool): tool is ToolRunnable {
+	return tool.kind === "tool";
+}
+
+// ── Execution context ─────────────────────────────────────────────────────────
+
+/** Everything the tool layer needs to resolve schemas + execute calls. */
+export interface ToolExecContext {
+	/** Core agent id — REQUIRED for remote tools (governs execution). */
+	agentId?: string;
+	/** Core base URL (no trailing `/api`). */
+	coreBaseUrl: string;
+	/** Bearer token for Core (`RYU_TOKEN`); may be undefined on loopback dev. */
+	coreToken?: string;
+	/** RunnableContext handed to local tools so they may call the gateway. */
+	runnableContext: RunnableContext;
+	/** Abort signal. */
+	signal?: AbortSignal;
+	/** Composio connected-account entity selector. */
+	userId?: string;
+}
+
+const PERMISSIVE_OBJECT_SCHEMA: Record<string, unknown> = {
+	type: "object",
+	additionalProperties: true,
+};
+
+/** Core `/api/tools/describe` response subset we read. */
+interface DescribeResponse {
+	description?: string;
+	name?: string;
+}
+
+function normalize(baseUrl: string): string {
+	return baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+}
+
+function authHeaders(token?: string): Record<string, string> {
+	const headers: Record<string, string> = {
+		"content-type": "application/json",
+	};
+	if (token) {
+		headers.authorization = `Bearer ${token}`;
+	}
+	return headers;
+}
+
+/**
+ * Build the OpenAI `tools[]` array the model sees, keyed by the developer's
+ * config names. Remote tools without an explicit `parameters` schema are
+ * described from Core (`describe` is shallow) and given a permissive schema.
+ */
+export async function resolveToolDefs(
+	tools: Record<string, AgentTool>,
+	ctx: ToolExecContext
+): Promise<ToolFunctionDef[]> {
+	const defs: ToolFunctionDef[] = [];
+
+	for (const [name, tool] of Object.entries(tools)) {
+		if (isLocalTool(tool)) {
+			defs.push({
+				type: "function",
+				function: {
+					name,
+					description: tool.name,
+					parameters: tool.schema as unknown as Record<string, unknown>,
+				},
+			});
+			continue;
+		}
+
+		// Remote: prefer an explicit schema; else describe from Core.
+		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: string,
+	ctx: ToolExecContext
+): Promise<string | undefined> {
+	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 undefined;
+		}
+		const json = (await res.json()) as DescribeResponse;
+		return json.description || json.name || undefined;
+	} catch {
+		// Describe is best-effort — a missing description never blocks the loop.
+		return undefined;
+	}
+}
+
+// ── Execution ─────────────────────────────────────────────────────────────────
+
+/** Result of executing one tool call. */
+export interface ToolExecResult {
+	/** Raw tool output (already JSON-parsed when the tool returned JSON). */
+	output: unknown;
+}
+
+/**
+ * Execute a single model tool call by config `name`, dispatching to the local
+ * runnable or the Core `/api/mcp/tools/call` endpoint.
+ *
+ * `argsJson` is the raw JSON string from `tool_call.function.arguments`.
+ */
+export async function executeTool(
+	name: string,
+	argsJson: string,
+	tools: Record<string, AgentTool>,
+	ctx: ToolExecContext
+): Promise<ToolExecResult> {
+	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 as Record<string, unknown>,
+			ctx.runnableContext
+		);
+		return { output };
+	}
+
+	// Remote tool — requires a Core agent id for governance.
+	if (!ctx.agentId) {
+		throw new Error(
+			`[ryu-sdk] remote tool "${name}" (${tool.id}) requires an agentId — ` +
+				"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()) as {
+		error?: string;
+		ok?: boolean;
+		output?: unknown;
+	};
+	if (json.ok === false) {
+		throw new Error(
+			`[ryu-sdk] tool "${tool.id}" failed: ${json.error ?? "unknown error"}`
+		);
+	}
+	return { output: json.output };
+}
+
+function parseArgs(argsJson: string, name: string): unknown {
+	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}`
+		);
+	}
+}
+
+// ── Elicitation (connection-required) detection ───────────────────────────────
+
+/** The connect-required envelope Core returns when an account isn't linked. */
+export interface Elicitation {
+	kind?: string;
+	message?: string;
+	url?: string;
+}
+
+const ELICITATION_KEY = "__ryu_elicitation__";
+
+/**
+ * Detect Ryu's connection-required envelope in a tool output. Mirrors Core's
+ * `detect_elicitation` (apps/core/src/sidecar/mcp/composio.rs): the first Gmail
+ * call for an unconnected account returns `{ "__ryu_elicitation__": { url } }`.
+ */
+export function detectElicitation(output: unknown): Elicitation | null {
+	if (typeof output !== "object" || output === null) {
+		return null;
+	}
+	const envelope = (output as Record<string, unknown>)[ELICITATION_KEY];
+	if (typeof envelope !== "object" || envelope === null) {
+		return null;
+	}
+	return envelope as Elicitation;
+}