@ryuhq/sdk 0.0.5

package/src/agent/index.ts

@@ -0,0 +1,51 @@
+/**
+ * `@ryu/sdk/agent` — the declarative agent runtime.
+ *
+ * Public entry for building apps on top of the SDK: a loop-owning `Agent`
+ * (Mastra-style) and a `query()` streaming call (Claude-Agent-SDK-style), plus
+ * `ryuTool` to reference existing Ryu tools and the event/type surface.
+ */
+
+export type {
+	AgentConfig,
+	Endpoint,
+	GenerateResult,
+} from "./agent.ts";
+export { Agent, createAgent } from "./agent.ts";
+export type {
+	AgentEvent,
+	AgentEventAuthRequired,
+	AgentEventError,
+	AgentEventResult,
+	AgentEventText,
+	AgentEventToolCall,
+	AgentEventToolResult,
+	LoopConfig,
+} from "./loop.ts";
+export { runAgentLoop } from "./loop.ts";
+export type {
+	AssistantMessage,
+	LoopMessage,
+	ModelCallOptions,
+	ModelCallResult,
+	ModelUsage,
+	ToolCall,
+	ToolFunctionDef,
+} from "./model-call.ts";
+export { callModelWithTools } from "./model-call.ts";
+export type { QueryInput, QueryOptions } from "./query.ts";
+export { query } from "./query.ts";
+export type {
+	AgentTool,
+	Elicitation,
+	RemoteToolRef,
+	RyuToolOptions,
+	ToolExecContext,
+	ToolExecResult,
+} from "./tools.ts";
+export {
+	detectElicitation,
+	executeTool,
+	resolveToolDefs,
+	ryuTool,
+} from "./tools.ts";

package/src/agent/loop.test.ts

@@ -0,0 +1,261 @@
+/**
+ * Unit tests for the autonomous agent loop.
+ *
+ * The loop talks to the gateway and Core over `fetch` (the model client's native
+ * reqwest transport is bypassed here), so we stub `globalThis.fetch` and route
+ * by URL: gateway completions, Core tool calls, and Core describe. Egress
+ * enforcement is real (loopback passes), matching model/client.test.ts.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { defineTool } from "../runnable/tool.ts";
+import { Agent } from "./agent.ts";
+import type { AgentEvent } from "./loop.ts";
+import type { ToolCall } from "./model-call.ts";
+import { executeTool, ryuTool } from "./tools.ts";
+
+const NODE = "http://127.0.0.1:7981";
+const RE_AGENT_ID = /agentId/;
+
+// ── Fetch stub ────────────────────────────────────────────────────────────────
+
+let modelQueue: unknown[] = [];
+let toolHandler: (body: Record<string, unknown>) => unknown = () => ({
+	ok: true,
+	output: {},
+});
+let originalFetch: typeof globalThis.fetch;
+
+function modelResponse(opts: {
+	content?: string | null;
+	finish?: string;
+	toolCalls?: ToolCall[];
+}) {
+	const toolCalls = opts.toolCalls ?? [];
+	return {
+		choices: [
+			{
+				finish_reason:
+					opts.finish ?? (toolCalls.length > 0 ? "tool_calls" : "stop"),
+				message: {
+					content: opts.content ?? null,
+					tool_calls: toolCalls.length > 0 ? toolCalls : undefined,
+				},
+			},
+		],
+		usage: { prompt_tokens: 3, completion_tokens: 5, total_tokens: 8 },
+	};
+}
+
+function toolCall(id: string, name: string, args: unknown): ToolCall {
+	return {
+		id,
+		type: "function",
+		function: { name, arguments: JSON.stringify(args) },
+	};
+}
+
+beforeEach(() => {
+	originalFetch = globalThis.fetch;
+	modelQueue = [];
+	toolHandler = () => ({ ok: true, output: {} });
+	globalThis.fetch = ((input: string | URL | Request, init?: RequestInit) => {
+		const url = String(input);
+		if (url.includes("/v1/chat/completions")) {
+			const next = modelQueue.shift() ?? modelResponse({ content: "done" });
+			return Promise.resolve(
+				new Response(JSON.stringify(next), { status: 200 })
+			);
+		}
+		if (url.includes("/api/mcp/tools/call")) {
+			const body = JSON.parse(String(init?.body ?? "{}")) as Record<
+				string,
+				unknown
+			>;
+			return Promise.resolve(
+				new Response(JSON.stringify(toolHandler(body)), { status: 200 })
+			);
+		}
+		if (url.includes("/api/tools/describe")) {
+			return Promise.resolve(
+				new Response(JSON.stringify({ description: "desc" }), { status: 200 })
+			);
+		}
+		return Promise.resolve(new Response("not found", { status: 404 }));
+	}) as typeof globalThis.fetch;
+});
+
+afterEach(() => {
+	globalThis.fetch = originalFetch;
+});
+
+async function collect(gen: AsyncGenerator<AgentEvent>): Promise<AgentEvent[]> {
+	const events: AgentEvent[] = [];
+	for await (const event of gen) {
+		events.push(event);
+	}
+	return events;
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe("runAgentLoop", () => {
+	it("executes a local tool, feeds the result back, and terminates", async () => {
+		let ran = false;
+		const echo = defineTool({
+			id: "echo",
+			name: "Echo the input",
+			schema: {
+				type: "object",
+				properties: { text: { type: "string" } },
+				required: ["text"],
+			},
+			run: (input) => {
+				ran = true;
+				return Promise.resolve({ echoed: input.text });
+			},
+		});
+
+		modelQueue = [
+			modelResponse({ toolCalls: [toolCall("c1", "echo", { text: "hi" })] }),
+			modelResponse({ content: "All done.", finish: "stop" }),
+		];
+
+		const agent = new Agent({
+			name: "t",
+			model: "gpt-4o",
+			node: { baseUrl: NODE },
+			tools: { echo },
+		});
+
+		const events = await collect(agent.stream("go"));
+		const types = events.map((e) => e.type);
+
+		expect(ran).toBe(true);
+		expect(types).toContain("tool_call");
+		expect(types).toContain("tool_result");
+		const result = events.find((e) => e.type === "result");
+		expect(result).toBeDefined();
+		expect(result?.type === "result" && result.text).toBe("All done.");
+		// Usage aggregates across both model rounds (8 + 8).
+		expect(result?.type === "result" && result.usage?.totalTokens).toBe(16);
+	});
+
+	it("executes a remote tool via Core /api/mcp/tools/call", async () => {
+		const captured: {
+			body: { agent_id?: unknown; tool?: unknown; user_id?: unknown } | null;
+		} = { body: null };
+		toolHandler = (body) => {
+			captured.body = body;
+			return { ok: true, output: { messages: ["expense receipt"] } };
+		};
+		modelQueue = [
+			modelResponse({
+				toolCalls: [toolCall("c1", "gmailSearch", { query: "receipt" })],
+			}),
+			modelResponse({ content: "Found 1 expense.", finish: "stop" }),
+		];
+
+		const agent = new Agent({
+			name: "expense",
+			model: "gpt-4o",
+			node: { baseUrl: NODE },
+			agentId: "agent-expense",
+			userId: "user-1",
+			tools: {
+				gmailSearch: ryuTool("composio__GMAIL_SEARCH_EMAILS", {
+					description: "Search Gmail",
+					parameters: {
+						type: "object",
+						properties: { query: { type: "string" } },
+						required: ["query"],
+					},
+				}),
+			},
+		});
+
+		const events = await collect(agent.stream("find expenses"));
+		expect(captured.body).not.toBeNull();
+		expect(captured.body?.tool).toBe("composio__GMAIL_SEARCH_EMAILS");
+		expect(captured.body?.agent_id).toBe("agent-expense");
+		expect(captured.body?.user_id).toBe("user-1");
+		const result = events.find((e) => e.type === "result");
+		expect(result?.type === "result" && result.text).toBe("Found 1 expense.");
+	});
+
+	it("pauses with auth_required when a remote tool returns an elicitation", async () => {
+		toolHandler = () => ({
+			ok: true,
+			output: {
+				__ryu_elicitation__: {
+					kind: "url",
+					url: "https://connect.example/gmail",
+					message: "Connect your Gmail",
+				},
+			},
+		});
+		modelQueue = [
+			modelResponse({
+				toolCalls: [toolCall("c1", "gmailSearch", { query: "x" })],
+			}),
+			// This second response must NOT be consumed — the loop stops on auth.
+			modelResponse({ content: "should not reach", finish: "stop" }),
+		];
+
+		const agent = new Agent({
+			name: "expense",
+			model: "gpt-4o",
+			node: { baseUrl: NODE },
+			agentId: "agent-expense",
+			tools: {
+				gmailSearch: ryuTool("composio__GMAIL_SEARCH_EMAILS", {
+					parameters: { type: "object", properties: {} },
+				}),
+			},
+		});
+
+		const events = await collect(agent.stream("find expenses"));
+		const auth = events.find((e) => e.type === "auth_required");
+		expect(auth?.type === "auth_required" && auth.url).toBe(
+			"https://connect.example/gmail"
+		);
+		// Loop stopped: no result event, second model response left unconsumed.
+		expect(events.some((e) => e.type === "result")).toBe(false);
+		expect(modelQueue.length).toBe(1);
+	});
+
+	it("query() yields the same terminal result as Agent.generate()", async () => {
+		const { query } = await import("./query.ts");
+		modelQueue = [modelResponse({ content: "Hello there.", finish: "stop" })];
+
+		const events = await collect(
+			query({
+				prompt: "hi",
+				options: { model: "gpt-4o", node: { baseUrl: NODE } },
+			})
+		);
+		const result = events.find((e) => e.type === "result");
+		expect(result?.type === "result" && result.text).toBe("Hello there.");
+	});
+});
+
+describe("executeTool", () => {
+	it("throws when a remote tool is used without an agentId", async () => {
+		const tools = {
+			gmailSearch: ryuTool("composio__GMAIL_SEARCH_EMAILS"),
+		};
+		await expect(
+			executeTool("gmailSearch", "{}", tools, {
+				coreBaseUrl: "http://127.0.0.1:7980",
+				runnableContext: {
+					gateway: {
+						chat: () => Promise.reject(new Error("unused")),
+						async *stream() {
+							// no-op
+						},
+					},
+				},
+			})
+		).rejects.toThrow(RE_AGENT_ID);
+	});
+});

package/src/agent/loop.ts

@@ -0,0 +1,259 @@
+/**
+ * The autonomous agent loop for the Ryu SDK runtime.
+ *
+ * This is what `defineAgent` never had: a real multi-turn tool-calling loop that
+ * runs in TypeScript. Each round calls the node's gateway with the resolved
+ * tool definitions; if the model emits `tool_calls`, each is executed (local
+ * runnable or Core `/api/mcp/tools/call`), results are fed back, and the loop
+ * repeats until the model stops calling tools or `maxSteps` is reached.
+ *
+ * Emitted events mirror Core's `AcpEvent` categories (see cli/dev.ts) plus an
+ * `auth_required` pause — when a remote tool returns Ryu's connection-required
+ * envelope (first-run Gmail OAuth), the loop surfaces the connect URL and stops
+ * instead of feeding the envelope back as a normal tool result.
+ */
+
+import {
+	type AssistantMessage,
+	callModelWithTools,
+	type LoopMessage,
+	type ModelUsage,
+	type ToolCall,
+} from "./model-call.ts";
+import {
+	type AgentTool,
+	detectElicitation,
+	executeTool,
+	resolveToolDefs,
+	type ToolExecContext,
+} from "./tools.ts";
+
+// ── Events ────────────────────────────────────────────────────────────────────
+
+/** A streamed text fragment from the assistant. */
+export interface AgentEventText {
+	content: string;
+	type: "text";
+}
+
+/** The model initiated a tool call. */
+export interface AgentEventToolCall {
+	id: string;
+	input: unknown;
+	name: string;
+	type: "tool_call";
+}
+
+/** A tool finished (or failed with an error output the model can recover from). */
+export interface AgentEventToolResult {
+	id: string;
+	name: string;
+	output: unknown;
+	type: "tool_result";
+}
+
+/** A remote tool needs an account connection — the loop paused. */
+export interface AgentEventAuthRequired {
+	message?: string;
+	tool: string;
+	type: "auth_required";
+	url?: string;
+}
+
+/** A fatal loop error — the stream ends after this. */
+export interface AgentEventError {
+	message: string;
+	type: "error";
+}
+
+/** Terminal event carrying the final text, step count, and aggregate usage. */
+export interface AgentEventResult {
+	steps: number;
+	text: string;
+	type: "result";
+	usage?: ModelUsage;
+}
+
+/** Union of everything the loop yields. */
+export type AgentEvent =
+	| AgentEventAuthRequired
+	| AgentEventError
+	| AgentEventResult
+	| AgentEventText
+	| AgentEventToolCall
+	| AgentEventToolResult;
+
+// ── Config ────────────────────────────────────────────────────────────────────
+
+/** Inputs for a single loop run. */
+export interface LoopConfig {
+	/** Gateway base URL for inference (the target node). */
+	gatewayBaseUrl: string;
+	/** Gateway bearer token. */
+	gatewayToken?: string;
+	/** Hard ceiling on model→tool rounds. */
+	maxSteps: number;
+	/** Seed transcript (system + user messages already assembled). */
+	messages: LoopMessage[];
+	/** Model id routed by the gateway. */
+	model: string;
+	/** Abort signal. */
+	signal?: AbortSignal;
+	/** Context for resolving + executing tools. */
+	toolCtx: ToolExecContext;
+	/** Tools keyed by model-facing name. */
+	tools: Record<string, AgentTool>;
+}
+
+function safeParse(json: string): unknown {
+	try {
+		return JSON.parse(json);
+	} catch {
+		return json;
+	}
+}
+
+function addUsage(a: ModelUsage | undefined, b: ModelUsage | undefined) {
+	if (!(a || b)) {
+		return undefined;
+	}
+	return {
+		promptTokens: (a?.promptTokens ?? 0) + (b?.promptTokens ?? 0),
+		completionTokens: (a?.completionTokens ?? 0) + (b?.completionTokens ?? 0),
+		totalTokens: (a?.totalTokens ?? 0) + (b?.totalTokens ?? 0),
+	};
+}
+
+/** Look at a tool output (object or JSON string) for the elicitation envelope. */
+function findElicitation(output: unknown) {
+	const direct = detectElicitation(output);
+	if (direct) {
+		return direct;
+	}
+	if (typeof output === "string") {
+		return detectElicitation(safeParse(output));
+	}
+	return null;
+}
+
+/**
+ * Run the autonomous loop, yielding events as they occur. The generator returns
+ * after a terminal `result`, `auth_required`, or `error` event.
+ */
+export async function* runAgentLoop(
+	config: LoopConfig
+): AsyncGenerator<AgentEvent> {
+	const messages = [...config.messages];
+	let toolDefs: Awaited<ReturnType<typeof resolveToolDefs>>;
+	try {
+		toolDefs = await resolveToolDefs(config.tools, config.toolCtx);
+	} catch (err) {
+		yield { type: "error", message: describeError(err) };
+		return;
+	}
+
+	let usage: ModelUsage | undefined;
+	let lastText = "";
+
+	for (let step = 1; step <= config.maxSteps; step++) {
+		let result: Awaited<ReturnType<typeof callModelWithTools>>;
+		try {
+			result = await callModelWithTools({
+				baseUrl: config.gatewayBaseUrl,
+				token: config.gatewayToken,
+				model: config.model,
+				messages,
+				tools: toolDefs.length > 0 ? toolDefs : undefined,
+				toolChoice: toolDefs.length > 0 ? "auto" : undefined,
+				signal: config.signal,
+			});
+		} catch (err) {
+			yield { type: "error", message: describeError(err) };
+			return;
+		}
+
+		usage = addUsage(usage, result.usage);
+		const assistant: AssistantMessage = 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;
+		}
+	}
+
+	// Ran out of steps — surface what we have rather than hang.
+	yield { type: "result", text: lastText, steps: config.maxSteps, usage };
+}
+
+/**
+ * Execute the model's tool calls, appending results to `messages`. Yields
+ * tool_call/tool_result/auth_required events. Returns `true` when the loop must
+ * stop (an elicitation pause was surfaced).
+ */
+async function* runToolCalls(
+	toolCalls: ToolCall[],
+	messages: LoopMessage[],
+	config: LoopConfig
+): AsyncGenerator<AgentEvent, boolean> {
+	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: unknown;
+		try {
+			const res = await executeTool(
+				name,
+				call.function.arguments,
+				config.tools,
+				config.toolCtx
+			);
+			output = res.output;
+		} catch (err) {
+			// Recoverable: feed the error back so the model can adjust.
+			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: unknown): string {
+	return err instanceof Error ? err.message : String(err);
+}