@ryuhq/sdk 0.1.13 → 0.2.0

package/dist/agent.d.cts

@@ -1,3 +1,379 @@
-export { A as Agent, b as AgentConfig, c as AgentEvent, U as AgentEventAuthRequired, V as AgentEventError, W as AgentEventResult, X as AgentEventText, Y as AgentEventToolCall, Z as AgentEventToolResult, d as AgentTool, _ as AssistantMessage, $ as Elicitation, E as Endpoint, h as GenerateResult, a0 as LoopConfig, a1 as LoopMessage, a2 as ModelCallOptions, a3 as ModelCallResult, a4 as ModelUsage, Q as QueryInput, n as QueryOptions, t as RemoteToolRef, a5 as RyuToolOptions, a6 as ToolCall, a7 as ToolExecContext, a8 as ToolExecResult, a9 as ToolFunctionDef, aa as callModelWithTools, y as createAgent, ab as detectElicitation, ac as executeTool, N as query, ad as resolveToolDefs, ae as runAgentLoop, O as ryuTool } from './index-BvAB5eMk.cjs';
+import { T as ToolRunnable, j as RunnableContext } from './tool-u-VR0fLF.cjs';
 import './manifest.cjs';
 import 'zod';
+import './client-D5U6ssPc.cjs';
+
+/**
+ * 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).
+ */
+/** An OpenAI function tool definition passed to the model. */
+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. */
+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. */
+interface AssistantMessage {
+    content: string | null;
+    role: "assistant";
+    tool_calls?: ToolCall[];
+}
+/** A message in the loop's running transcript. */
+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). */
+interface ModelUsage {
+    completionTokens: number;
+    promptTokens: number;
+    totalTokens: number;
+}
+/** Options for a single native tool-calling completion. */
+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. */
+interface ModelCallResult {
+    finishReason: string | null;
+    message: AssistantMessage;
+    usage?: ModelUsage;
+}
+/**
+ * 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.
+ */
+declare function callModelWithTools(options: ModelCallOptions): Promise<ModelCallResult>;
+
+/**
+ * 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.
+ */
+
+/** A reference to an existing Ryu tool, resolved + executed via Core. */
+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`. */
+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"] },
+ * });
+ * ```
+ */
+declare function ryuTool(id: string, opts?: RyuToolOptions): RemoteToolRef;
+/** A tool an `Agent` can expose to the model: local runnable or remote ref. */
+type AgentTool = RemoteToolRef | ToolRunnable;
+/** Everything the tool layer needs to resolve schemas + execute calls. */
+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;
+}
+/**
+ * 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.
+ */
+declare function resolveToolDefs(tools: Record<string, AgentTool>, ctx: ToolExecContext): Promise<ToolFunctionDef[]>;
+/** Result of executing one tool call. */
+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`.
+ */
+declare function executeTool(name: string, argsJson: string, tools: Record<string, AgentTool>, ctx: ToolExecContext): Promise<ToolExecResult>;
+/** The connect-required envelope Core returns when an account isn't linked. */
+interface Elicitation {
+    kind?: string;
+    message?: string;
+    url?: string;
+}
+/**
+ * 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 } }`.
+ */
+declare function detectElicitation(output: unknown): Elicitation | null;
+
+/**
+ * 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.
+ */
+
+/** A streamed text fragment from the assistant. */
+interface AgentEventText {
+    content: string;
+    type: "text";
+}
+/** The model initiated a tool call. */
+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). */
+interface AgentEventToolResult {
+    id: string;
+    name: string;
+    output: unknown;
+    type: "tool_result";
+}
+/** A remote tool needs an account connection — the loop paused. */
+interface AgentEventAuthRequired {
+    message?: string;
+    tool: string;
+    type: "auth_required";
+    url?: string;
+}
+/** A fatal loop error — the stream ends after this. */
+interface AgentEventError {
+    message: string;
+    type: "error";
+}
+/** Terminal event carrying the final text, step count, and aggregate usage. */
+interface AgentEventResult {
+    steps: number;
+    text: string;
+    type: "result";
+    usage?: ModelUsage;
+}
+/** Union of everything the loop yields. */
+type AgentEvent = AgentEventAuthRequired | AgentEventError | AgentEventResult | AgentEventText | AgentEventToolCall | AgentEventToolResult;
+/** Inputs for a single loop run. */
+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>;
+}
+/**
+ * Run the autonomous loop, yielding events as they occur. The generator returns
+ * after a terminal `result`, `auth_required`, or `error` event.
+ */
+declare function runAgentLoop(config: LoopConfig): AsyncGenerator<AgentEvent>;
+
+/**
+ * `Agent` — the declarative agent runtime for `@ryu/sdk`.
+ *
+ * Unlike `defineAgent` (a declaration wrapper whose `run()` you write by hand),
+ * `Agent` OWNS the loop: give it instructions, a model, a target node, and a
+ * set of tools, then call `generate()` / `stream()`. Inference is pointed at the
+ * node's gateway; tool calls resolve to local `defineTool` runnables or existing
+ * Ryu tools (`ryuTool`) executed through Core.
+ *
+ * Mirrors Mastra's config-object + `.generate()`/`.stream()` shape; `query()`
+ * (see query.ts) wraps the same runtime in a Claude-Agent-SDK-style streaming
+ * call.
+ */
+
+/** A target node for inference / tool execution: a base URL + optional token. */
+interface Endpoint {
+    baseUrl?: string;
+    token?: string;
+}
+/** Declarative configuration for an `Agent`. */
+interface AgentConfig {
+    /** Core agent id — REQUIRED when using `ryuTool` remote tools (governance). */
+    agentId?: string;
+    /** Core endpoint for tool discovery/execution. Defaults to env/localhost. */
+    core?: Endpoint;
+    /** System prompt / persona. */
+    instructions?: string;
+    /** Hard ceiling on model→tool rounds (default 10). */
+    maxSteps?: number;
+    /** Model id routed by the node's gateway. */
+    model: string;
+    /** Display name. */
+    name: string;
+    /** Target node for inference. Defaults to the local gateway. */
+    node?: Endpoint;
+    /**
+     * Reverse-domain plugin id. When set, the composable primitive surface
+     * (`ctx.rag`, `ctx.memory`, `ctx.engines`, …) is mounted on the run context,
+     * routed through this node via the governed host bridge / capability broker.
+     * Omitted = no primitives mounted (the bridge families authenticate a plugin
+     * id, so a half-wired transport is never attached).
+     */
+    pluginId?: string;
+    /** Tools keyed by the model-facing name. */
+    tools?: Record<string, AgentTool>;
+    /** Composio connected-account entity selector. */
+    userId?: string;
+}
+/** Result of a non-streaming `generate()`. */
+interface GenerateResult {
+    /** Present when the run paused for an account connection. */
+    authRequired?: AgentEventAuthRequired;
+    /** Number of model→tool rounds taken. */
+    steps: number;
+    /** Final assistant text. */
+    text: string;
+    /** Aggregate token usage across all rounds (when reported). */
+    usage?: ModelUsage;
+}
+/** A declarative, loop-owning agent. */
+declare class Agent {
+    readonly config: AgentConfig;
+    constructor(config: AgentConfig);
+    /** Assemble the loop config for a given prompt. */
+    private buildLoopConfig;
+    /** Stream loop events (text / tool_call / tool_result / auth_required / …). */
+    stream(prompt: string, signal?: AbortSignal): AsyncGenerator<AgentEvent>;
+    /** Run to completion and return the final text, step count, and usage. */
+    generate(prompt: string, signal?: AbortSignal): Promise<GenerateResult>;
+}
+/** Factory alias for `new Agent(config)`. */
+declare function createAgent(config: AgentConfig): Agent;
+
+/**
+ * `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.
+ */
+
+/** Options accepted by `query` — an `AgentConfig` with an optional `name`. */
+type QueryOptions = Omit<AgentConfig, "name"> & {
+    name?: string;
+};
+/** Input to `query`: a prompt plus agent options. */
+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);
+ * }
+ * ```
+ */
+declare function query(input: QueryInput): AsyncGenerator<AgentEvent>;
+
+export { Agent, type AgentConfig, type AgentEvent, type AgentEventAuthRequired, type AgentEventError, type AgentEventResult, type AgentEventText, type AgentEventToolCall, type AgentEventToolResult, type AgentTool, type AssistantMessage, type Elicitation, type Endpoint, type GenerateResult, type LoopConfig, type LoopMessage, type ModelCallOptions, type ModelCallResult, type ModelUsage, type QueryInput, type QueryOptions, type RemoteToolRef, type RyuToolOptions, type ToolCall, type ToolExecContext, type ToolExecResult, type ToolFunctionDef, callModelWithTools, createAgent, detectElicitation, executeTool, query, resolveToolDefs, runAgentLoop, ryuTool };