@ryuhq/sdk 0.0.5

package/dist/index-DAxq7Y0R.d.ts

@@ -0,0 +1,988 @@
+import { RunnableMeta } from './manifest.js';
+
+/**
+ * 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>;
+
+/**
+ * Gateway-mandatory model client for the Ryu SDK.
+ *
+ * Rust-cored: this is a thin TypeScript wrapper over the `@ryuhq/sdk-native`
+ * addon's `ModelClient`, which is the `crates/ryu-sdk` Rust core. Every model
+ * call is routed by the Rust core to the Ryu gateway's OpenAI-compatible
+ * `/v1/chat/completions` endpoint; direct-provider base URLs are rejected at
+ * construction. No provider SDK or base URL is ever imported here.
+ *
+ * Usage:
+ *
+ *   const model = defineModel("gpt-4o");
+ *   const reply = await model.chat([{ role: "user", content: "hello" }]);
+ *   for await (const delta of model.stream([{ role: "user", content: "hi" }])) {
+ *     process.stdout.write(delta.content);
+ *   }
+ */
+/** A single message in a chat conversation. */
+interface ChatMessage {
+    /** The message text. */
+    content: string;
+    /** The speaker: "system", "user", or "assistant". */
+    role: "system" | "user" | "assistant";
+}
+/** A streaming chat completion delta. */
+interface ChatDelta {
+    /** Incremental text fragment from the model. */
+    content: string | null;
+    /** Non-null on the final chunk when `finish_reason` is set. */
+    finishReason: string | null;
+}
+/** Non-streaming chat completion result. */
+interface ChatResult {
+    /** The full assistant reply text. */
+    content: string;
+    /** The gateway/model-reported finish reason. */
+    finishReason: string | null;
+    /** Usage stats as reported by the gateway (optional — gateway may omit). */
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+/** Options accepted by `defineModel`. */
+interface ModelClientOptions {
+    /**
+     * Gateway base URL (no trailing `/v1`). Defaults to `RYU_GATEWAY_URL` then
+     * the Rust core's default. Direct provider URLs are rejected at construction.
+     */
+    baseUrl?: string;
+    /**
+     * Bearer token forwarded to the gateway. Defaults to `RYU_GATEWAY_TOKEN`.
+     * This is the gateway token, never a provider API key.
+     */
+    token?: string;
+}
+/**
+ * A gateway-mandatory model client backed by the Rust core.
+ *
+ * All calls go through the native `ModelClient`; if the configured base URL is a
+ * direct provider, construction throws.
+ */
+declare class ModelClient {
+    readonly model: string;
+    readonly baseUrl: string;
+    private readonly native;
+    constructor(model: string, options?: ModelClientOptions);
+    /** Send a non-streaming chat completion request to the gateway. */
+    chat(messages: ChatMessage[]): Promise<ChatResult>;
+    /** Send a streaming chat completion request, yielding deltas as they arrive. */
+    stream(messages: ChatMessage[]): AsyncGenerator<ChatDelta>;
+}
+/**
+ * Create a gateway-mandatory model client for `modelId`.
+ *
+ *   const model = defineModel("gpt-4o");
+ *   const model = defineModel("claude-3-5-sonnet", { baseUrl: "http://my-gateway:7981" });
+ *
+ * A direct provider URL throws immediately (egress enforcement in the Rust core).
+ */
+declare function defineModel(modelId: string, options?: ModelClientOptions): ModelClient;
+
+/**
+ * Composable primitive-client surface for the Ryu SDK runtime context.
+ *
+ * Now that each capability is its own crate with a clean trait
+ * (`crates/ryu-rag`, `crates/ryu-memory`, `crates/ryu-realtime`,
+ * `crates/ryu-durable`, `crates/ryu-engines`, `crates/ryu-tts`,
+ * `crates/ryu-stt`, `crates/ryu-image`), the SDK exposes each as a typed,
+ * **gateway-mandatory** client on `RunnableContext`: `ctx.rag.retrieve()`,
+ * `ctx.memory.recall()`, `ctx.engines.complete()`, and so on. An agent composes
+ * the same building blocks a developer does — the DX payoff of decomposition
+ * (program §6b).
+ *
+ * These clients are **thin typed wrappers** over the EXISTING host transport
+ * families — they invent NO new backend endpoints. The method names and grants
+ * mirror the canonical vocabulary in
+ * `packages/app-host/src/rpc.ts` (`METHOD_CAPABILITY` / `GRANT_CAPABILITY`); the
+ * arg/result shapes mirror the `RpcServices` signatures there. We MIRROR that
+ * vocabulary rather than importing it: `@ryuhq/sdk` is a published package and
+ * `@ryu/app-host` is a desktop-host package in a disjoint lane.
+ *
+ * Three real transport shapes exist in `rpc.ts`, so the transport exposes three
+ * ops (all reach a Core node the host holds the token for):
+ *   - `bridge`  → the `PluginHookBridge` families (`POST /api/plugins/:id/host`,
+ *                 `{ method, args }`) — e.g. `model.complete` → `host.sideModel`.
+ *   - `direct`  → host-direct Core data-path calls the host makes on the frame's
+ *                 behalf (`POST /api/images/generate`, `/api/voice/speak`,
+ *                 `/api/voice/transcribe`).
+ *   - `capability` → the capability broker (`POST /api/host/capability/:cap`) for
+ *                 caps that have no rpc family yet (rag/memory/realtime/durable/
+ *                 engines.embed). These are marked `@requires-grant`: the caller
+ *                 must DECLARE the edge in `requires.capabilities` and hold the
+ *                 bound provider's grant, else Core fails closed (404/403).
+ */
+/**
+ * Low-level dispatcher a primitive client uses to reach a Core node. Injected
+ * so the SDK stays transport-agnostic (the same seam as `ctx.gateway`); a
+ * default HTTP implementation is {@link httpPrimitiveTransport}.
+ */
+interface PrimitiveTransport {
+    /**
+     * Invoke a `PluginHookBridge` family method (`POST /api/plugins/:id/host`).
+     * `method` is the exact `rpc.ts` `METHOD_CAPABILITY` key (e.g.
+     * `"model.complete"`); the host maps it to the closed `host.*` bridge path.
+     */
+    bridge(method: string, args: unknown): Promise<unknown>;
+    /**
+     * Invoke an abstract capability through the broker
+     * (`POST /api/host/capability/:cap`). `@requires-grant`: the caller must have
+     * declared `requires.capabilities: [{ capability: cap }]` and hold the bound
+     * provider's grant, or Core fails closed.
+     */
+    capability(cap: string, body: unknown): Promise<unknown>;
+    /**
+     * Invoke a host-direct Core data-path endpoint (`POST {path}`). Used for the
+     * media families the host reaches directly (`/api/images/generate`,
+     * `/api/voice/speak`, `/api/voice/transcribe`) rather than via the bridge.
+     *
+     * The two voice endpoints do NOT speak plain JSON-in/JSON-out — a real Core
+     * node requires a multipart `file` upload for transcription and streams raw
+     * `audio/wav` bytes back from synthesis. The default {@link httpPrimitiveTransport}
+     * therefore reshapes those two calls (mirroring the desktop host's `rpc.ts`):
+     *   - `/api/voice/transcribe` — `{ audio: data-URL, filename? }` → multipart
+     *     `file` upload; resolves to the transcript `string`.
+     *   - `/api/voice/speak` — JSON in; resolves to a renderable `data:` audio URL
+     *     built from the returned `audio/wav` bytes.
+     * Every other path is a straight JSON round-trip.
+     */
+    direct(path: string, body: unknown): Promise<unknown>;
+}
+/** Options for {@link httpPrimitiveTransport}. */
+interface HttpPrimitiveTransportOptions {
+    /** Injectable `fetch` (defaults to the global). */
+    fetchImpl?: typeof fetch;
+    /**
+     * Core **node** base URL (no trailing slash) — NEVER a direct provider. The
+     * URL is validated against the direct-provider egress blocklist so every
+     * primitive call stays governed (the gateway-mandatory rule).
+     */
+    nodeUrl: string;
+    /**
+     * The calling plugin's reverse-domain id. REQUIRED for the `bridge` op —
+     * `/api/plugins/:id/host` authenticates this id and gates on its
+     * Gateway-approved grants. Omit only if the caller never uses bridge-backed
+     * primitives (`ctx.engines.complete`).
+     */
+    pluginId?: string;
+    /** Node bearer token forwarded on every call. */
+    token?: string;
+}
+/**
+ * A default HTTP {@link PrimitiveTransport} targeting a Core node. Validates
+ * `nodeUrl` against the direct-provider egress blocklist at construction, so a
+ * mis-pointed transport can never route a primitive call at a raw provider.
+ */
+declare function httpPrimitiveTransport(options: HttpPrimitiveTransportOptions): PrimitiveTransport;
+/**
+ * How one primitive method reaches Core. This is the SDK's single mirror of the
+ * `rpc.ts` `METHOD_CAPABILITY` / `GRANT_CAPABILITY` maps — keep it in lockstep
+ * with that canonical source. `bridge`/`direct` families exist today;
+ * `broker` families are `@requires-grant` (declared capability edge).
+ */
+type PrimitiveBinding = {
+    readonly transport: "bridge";
+    /** Exact `rpc.ts` method key (e.g. `"model.complete"`). */
+    readonly method: string;
+    /** Gateway grant that unlocks it (`GRANT_CAPABILITY` inverse). */
+    readonly grant: string;
+} | {
+    readonly transport: "direct";
+    /** Core data-path endpoint the host calls directly. */
+    readonly path: string;
+    /** Gateway grant that unlocks it. */
+    readonly grant: string;
+} | {
+    readonly transport: "broker";
+    /** Abstract capability name (the broker `:cap` segment + the
+     *  `requires.capabilities` edge the caller must declare). */
+    readonly capability: string;
+};
+/**
+ * The binding for every primitive method, keyed `"<namespace>.<method>"`.
+ * Mirrors `rpc.ts`; the ONLY place primitive→endpoint knowledge lives.
+ */
+declare const PRIMITIVE_BINDINGS: Record<string, PrimitiveBinding>;
+/** One retrieved chunk (`crates/ryu-rag` `RagChunk`). */
+interface RagChunk {
+    id: string;
+    metadata?: Record<string, unknown>;
+    score: number;
+    source?: string;
+    text: string;
+}
+/** One rerank result (`crates/ryu-rag` reranker trait). */
+interface RagRerankResult {
+    document: string;
+    index: number;
+    score: number;
+}
+/** RAG primitive — retrieval, embedding, reranking (`crates/ryu-rag`). */
+interface RagClient {
+    /** Embed text into vectors. `@requires-grant rag`. */
+    embed(input: {
+        input: string | string[];
+        model?: string;
+    }): Promise<number[][]>;
+    /** Rerank `documents` against `query`. `@requires-grant rag`. */
+    rerank(input: {
+        query: string;
+        documents: string[];
+        topK?: number;
+        model?: string;
+    }): Promise<RagRerankResult[]>;
+    /** Vector/GraphRAG retrieval for `query`. `@requires-grant rag`. */
+    retrieve(input: {
+        query: string;
+        topK?: number;
+        spaceId?: string;
+        filter?: Record<string, unknown>;
+    }): Promise<RagChunk[]>;
+}
+/** One recalled memory (`crates/ryu-memory` `MemoryItem`). */
+interface MemoryItem {
+    category?: string;
+    content: string;
+    id: string;
+    importance?: number;
+    level?: string;
+    score?: number;
+    tags?: string[];
+}
+/** Memory primitive — recall + store (`crates/ryu-memory`). */
+interface MemoryClient {
+    /** Semantic recall across the readable scope levels. `@requires-grant memory`. */
+    recall(input: {
+        query: string;
+        levels?: string[];
+        limit?: number;
+    }): Promise<MemoryItem[]>;
+    /** Persist a memory. `@requires-grant memory`. */
+    store(input: {
+        content: string;
+        level?: string;
+        category?: string;
+        importance?: number;
+        tags?: string[];
+    }): Promise<{
+        id: string;
+    }>;
+}
+/**
+ * A realtime subscription handle. The broker is a unary POST, so `subscribe`
+ * cannot stream today — it returns a handle (the crate's typed event contract
+ * grows a live channel later). Honest shape over a promised-but-unbacked stream.
+ */
+interface RealtimeSubscription {
+    room: string;
+    subscriptionId: string;
+}
+/** Realtime primitive — typed room events (`crates/ryu-realtime`). */
+interface RealtimeClient {
+    /** Broadcast a typed event to a room. `@requires-grant realtime`. */
+    broadcast(input: {
+        room: string;
+        event: string;
+        payload?: unknown;
+    }): Promise<void>;
+    /** Open a subscription handle for a room. `@requires-grant realtime`. */
+    subscribe(input: {
+        room: string;
+    }): Promise<RealtimeSubscription>;
+}
+/** Durable primitive — checkpoint + resume (`crates/ryu-durable`). */
+interface DurableClient {
+    /** Persist a checkpoint; returns a resume token. `@requires-grant durable`. */
+    checkpoint(input: {
+        key: string;
+        state: unknown;
+    }): Promise<{
+        token: string;
+    }>;
+    /** Resume from a checkpoint token (`null` when unknown). `@requires-grant durable`. */
+    resume(input: {
+        token: string;
+    }): Promise<{
+        state: unknown;
+    } | null>;
+}
+/** Engines primitive — completion + embedding (`crates/ryu-engines`). */
+interface EnginesClient {
+    /**
+     * Tool-less one-shot completion (bridge `model.complete` → `host.sideModel`,
+     * Gateway-routed). Grant `hook:side-model`.
+     */
+    complete(input: {
+        prompt: string;
+        system?: string;
+        model?: string;
+        modelPrefKey?: string;
+        effort?: string;
+    }): Promise<string>;
+    /** Embed text into vectors. `@requires-grant engines`. */
+    embed(input: {
+        input: string | string[];
+        model?: string;
+    }): Promise<number[][]>;
+}
+/** TTS primitive — speech synthesis (`crates/ryu-tts`). */
+interface TtsClient {
+    /**
+     * Synthesize speech (host-direct `/api/voice/speak`, Gateway-governed).
+     * Returns a renderable `data:` audio URL. Grant `media:generate`.
+     */
+    speak(input: {
+        text: string;
+        engine?: string;
+        voice?: string;
+        speed?: number;
+        language?: string;
+    }): Promise<string>;
+}
+/** STT primitive — transcription (`crates/ryu-stt`). */
+interface SttClient {
+    /**
+     * Transcribe an audio `data:` URL (host-direct `/api/voice/transcribe`).
+     * Returns the text. Grant `media:transcribe`.
+     */
+    transcribe(input: {
+        audio: string;
+        filename?: string;
+    }): Promise<string>;
+}
+/** Image primitive — generation (`crates/ryu-image`). */
+interface ImageClient {
+    /**
+     * Generate image(s) from a prompt (host-direct `/api/images/generate`,
+     * Gateway-governed). Returns renderable `data:` URLs. Grant `media:generate`.
+     */
+    generate(input: {
+        prompt: string;
+        count?: number;
+        size?: string;
+        provider?: string;
+        model?: string;
+    }): Promise<string[]>;
+}
+/**
+ * The composable primitive bundle mounted on {@link RunnableContext}. Every
+ * client routes through the Gateway (bridge/direct/broker all reach a governed
+ * Core node) — the same "what runs vs what is allowed" split as `ctx.gateway`.
+ */
+interface RyuPrimitives {
+    durable: DurableClient;
+    engines: EnginesClient;
+    image: ImageClient;
+    memory: MemoryClient;
+    rag: RagClient;
+    realtime: RealtimeClient;
+    stt: SttClient;
+    tts: TtsClient;
+}
+/**
+ * Build the typed {@link RyuPrimitives} bundle over a {@link PrimitiveTransport}.
+ * Each method is a thin wrapper: bridge/direct families forward to the existing
+ * endpoints; broker families POST to `/api/host/capability/:cap` (`@requires-grant`).
+ */
+declare function createPrimitives(transport: PrimitiveTransport): RyuPrimitives;
+
+/**
+ * Shared Runnable interface and context types.
+ *
+ * Every factory (defineAgent, defineWorkflow, defineTool, defineSkill) returns
+ * a value that satisfies the `Runnable` interface.  This keeps the contract
+ * in one place and avoids circular imports between the four factory modules.
+ */
+
+/**
+ * Thin client over the Ryu gateway `POST /v1/chat/completions` endpoint.
+ *
+ * This is the ONLY way a Runnable may invoke a model.  Injected via
+ * `RunnableContext.gateway` so every call is gateway-mandatory — matching the
+ * Core-vs-Gateway rule (the SDK decides what runs; the gateway decides what is
+ * allowed/measured/paid).
+ *
+ * Mirrors the interface specified in packages/sdk/README.md §2 and the
+ * `ModelClient` shape in `packages/sdk/src/model/client.ts`.
+ */
+interface GatewayClient {
+    /** POST /v1/chat/completions (non-streaming). */
+    chat(messages: ChatMessage[]): Promise<ChatResult>;
+    /** POST /v1/chat/completions (streaming SSE). */
+    stream(messages: ChatMessage[]): AsyncGenerator<ChatDelta>;
+}
+/**
+ * Context injected into every `Runnable.run()` call.
+ *
+ * The gateway client is always present (fail-closed): a missing gateway throws
+ * at construction time via `defineModel`, never at run time.
+ */
+interface RunnableContext {
+    /** Durable primitive: checkpoint · resume (`crates/ryu-durable`). */
+    durable?: DurableClient;
+    /** Engines primitive: complete · embed (`crates/ryu-engines`). */
+    engines?: EnginesClient;
+    /**
+     * Gateway client — the single allowed path for model calls.
+     * Never null; a Runnable that needs a model must use this.
+     */
+    gateway: GatewayClient;
+    /** Image primitive: generate (`crates/ryu-image`). */
+    image?: ImageClient;
+    /** Memory primitive: recall · store (`crates/ryu-memory`). */
+    memory?: MemoryClient;
+    /** RAG primitive: retrieve · embed · rerank (`crates/ryu-rag`). */
+    rag?: RagClient;
+    /** Realtime primitive: broadcast · subscribe (`crates/ryu-realtime`). */
+    realtime?: RealtimeClient;
+    /** Optional session id for stateful runs (Core session). */
+    sessionId?: string;
+    /** Signal to abort a long-running run. */
+    signal?: AbortSignal;
+    /** STT primitive: transcribe (`crates/ryu-stt`). */
+    stt?: SttClient;
+    /** TTS primitive: speak (`crates/ryu-tts`). */
+    tts?: TtsClient;
+}
+/**
+ * The single contract for everything that can run in Ryu:
+ * Agent | Workflow | Tool | Skill.
+ *
+ * Typed over `TInput` (what the caller passes) and `TOutput` (what run()
+ * returns).  The `kind` field narrows the discriminated union.
+ */
+interface Runnable<TInput = unknown, TOutput = unknown> {
+    /** Stable unique identifier (e.g. "agent-researcher"). */
+    readonly id: string;
+    /** Kind tag — narrows the discriminated union. */
+    readonly kind: "agent" | "workflow" | "tool" | "skill";
+    /** Human-readable name. */
+    readonly name: string;
+    /**
+     * Execute this Runnable.
+     *
+     * Every model call MUST go through `ctx.gateway`.  Direct provider imports
+     * are forbidden by the SDK's egress enforcement (assertAllowedEgressUrl).
+     */
+    run(input: TInput, ctx: RunnableContext): Promise<TOutput>;
+}
+
+/**
+ * defineTool — factory for Runnable tools.
+ *
+ * A tool is a stateless function invoked by an agent or workflow step.
+ * It accepts a typed schema (Zod-style field definitions) that is converted
+ * to a JSON Schema object compatible with Core's `ToolInfo.schema` shape
+ * (apps/core/src/sidecar/adapters/mod.rs:66-71).
+ *
+ * Input is validated against the schema at run() time; invalid input throws
+ * a descriptive Error before the tool body executes.
+ *
+ * Tools do NOT require model calls and therefore do not need `ctx.gateway`
+ * to be present, but the context is still injected so tools can optionally
+ * call gateway.chat() when they need model assistance.
+ */
+
+/**
+ * A single JSON Schema property descriptor — the subset required by Core's
+ * `ToolInfo.schema` field and the OpenAI function-calling format.
+ */
+interface JsonSchemaProperty {
+    /** Human-readable description surfaced to the model. */
+    description?: string;
+    /** Allowed enum values. */
+    enum?: unknown[];
+    /** Array item schema (required when type is "array"). */
+    items?: JsonSchemaProperty;
+    /** Nested object properties (used when type is "object"). */
+    properties?: Record<string, JsonSchemaProperty>;
+    /** Required keys list (used when type is "object"). */
+    required?: string[];
+    /** JSON Schema type string. */
+    type: "string" | "number" | "integer" | "boolean" | "array" | "object";
+}
+/**
+ * Zod-style schema descriptor for a tool's input.
+ *
+ * Keys are field names; values describe their JSON Schema shape.  Required
+ * fields are listed separately under `required`.
+ *
+ * This intentionally mirrors the shape that `ToolInfo.schema` expects in
+ * `apps/core/src/sidecar/adapters/mod.rs` so a `defineTool` output can be
+ * forwarded to Core without transformation.
+ */
+interface ToolSchema {
+    /** Field definitions. */
+    properties: Record<string, JsonSchemaProperty>;
+    /** Names of fields that must be present in the input. */
+    required?: string[];
+    /** Type is always "object" for a tool's top-level input schema. */
+    type: "object";
+}
+/** Options accepted by `defineTool`. */
+interface ToolOptions<TInput extends Record<string, unknown>, TOutput> {
+    /** Stable unique identifier (e.g. "tool-web-search"). */
+    id: string;
+    /** Human-readable display name. */
+    name: string;
+    /**
+     * The tool's run implementation.
+     *
+     * Called only after input validation passes.  Model calls are optional but
+     * must go through `ctx.gateway` if used.
+     */
+    run(input: TInput, ctx: RunnableContext): Promise<TOutput>;
+    /** JSON Schema describing the tool's input — used for input validation and Core ToolInfo. */
+    schema: ToolSchema;
+}
+/**
+ * A `Runnable` with an extra `schema` field exposing the tool's JSON Schema.
+ *
+ * The `schema` is compatible with Core's `ToolInfo.schema` shape so it can
+ * be forwarded verbatim to Core's MCP/ACP layer.
+ */
+interface ToolRunnable<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput = unknown> extends Runnable<TInput, TOutput> {
+    readonly kind: "tool";
+    /** JSON Schema for this tool's input — compatible with Core's ToolInfo.schema. */
+    readonly schema: ToolSchema;
+    /**
+     * The `run` body serialized for Core's `inline_deno` tool backend — the exact
+     * same technique `defineTurnHook` uses for its `code`. This is what makes a
+     * `defineTool` **shippable**: bundled into a plugin manifest (see
+     * {@link inlineToolRunnable} / `definePlugin({ tools })`), Core runs it in the
+     * Deno sandbox, so the tool ships NEW behavior instead of only aliasing an
+     * existing tool.
+     *
+     * IMPORTANT: like a hook body, the serialized function is **self-contained** —
+     * it runs in a fresh sandbox with only `input` (the call arguments) and `host`
+     * (the capability bridge: `host.sideModel` / `host.storage` / `host.log`, each
+     * gated by the plugin's grants) in scope. It cannot capture outer variables,
+     * imports, or closures, and `ctx.gateway` is **not** available in the sandbox
+     * — a shipped tool reaches models through `host.sideModel`. When run in-process
+     * via {@link ToolRunnable.run} the normal `(input, ctx)` contract still holds;
+     * the sandbox form is the second parameter aliased to `host`.
+     */
+    readonly code: string;
+}
+/**
+ * Create a Runnable tool with input validation.
+ *
+ * The returned value satisfies `ToolRunnable<TInput, TOutput>` (which extends
+ * `Runnable`) with `kind = "tool"`.  The `schema` property is the JSON Schema
+ * descriptor passed in options — forwarding it to Core's `ToolInfo.schema`
+ * requires no transformation.
+ *
+ * Input is validated at `run()` time: missing required fields or type
+ * mismatches throw before the tool body executes.
+ *
+ * @example
+ * ```ts
+ * const searchTool = defineTool({
+ *   id: "tool-web-search",
+ *   name: "Web Search",
+ *   schema: {
+ *     type: "object",
+ *     properties: { query: { type: "string", description: "Search query" } },
+ *     required: ["query"],
+ *   },
+ *   async run({ query }, _ctx) {
+ *     return { results: [`Result for: ${query}`] };
+ *   },
+ * });
+ * // schema is Core-compatible:
+ * console.log(searchTool.schema); // { type: "object", properties: { query: ... }, required: [...] }
+ * ```
+ */
+declare function defineTool<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput = unknown>(options: ToolOptions<TInput, TOutput>): ToolRunnable<TInput, TOutput>;
+/**
+ * Convert a {@link ToolRunnable} into a `plugin.json` `kind:"tool"` runnable that
+ * ships its `run` body as Core's `inline_deno` backend. The emitted config
+ * mirrors Core's `ToolConfig` (`apps/core/src/plugin_manifest/schema.rs`):
+ * `{ slug, backend:"inline_deno", code, description?, input_schema }`. Core
+ * registers it as `app__<slug>` — discoverable via `/api/tools/search` and
+ * executed in the grant-gated sandbox.
+ *
+ * The plugin must declare the `tool:execute` grant (see `definePlugin`).
+ */
+declare function inlineToolRunnable(tool: ToolRunnable, options?: {
+    description?: string;
+}): RunnableMeta;
+
+/**
+ * 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 { type Elicitation as $, Agent as A, defineModel as B, type ChatDelta as C, type DurableClient as D, type Endpoint as E, defineTool as F, type GatewayClient as G, type HttpPrimitiveTransportOptions as H, type ImageClient as I, type JsonSchemaProperty as J, httpPrimitiveTransport as K, inlineToolRunnable as L, type MemoryClient as M, query as N, ryuTool as O, PRIMITIVE_BINDINGS as P, type QueryInput as Q, type Runnable as R, type SttClient as S, type ToolRunnable as T, type AgentEventAuthRequired as U, type AgentEventError as V, type AgentEventResult as W, type AgentEventText as X, type AgentEventToolCall as Y, type AgentEventToolResult as Z, type AssistantMessage as _, type RunnableContext as a, type LoopConfig as a0, type LoopMessage as a1, type ModelCallOptions as a2, type ModelCallResult as a3, type ModelUsage as a4, type RyuToolOptions as a5, type ToolCall as a6, type ToolExecContext as a7, type ToolExecResult as a8, type ToolFunctionDef as a9, callModelWithTools as aa, detectElicitation as ab, executeTool as ac, resolveToolDefs as ad, runAgentLoop as ae, type AgentConfig as b, type AgentEvent as c, type AgentTool as d, type ChatMessage as e, type ChatResult as f, type EnginesClient as g, type GenerateResult as h, type MemoryItem as i, ModelClient as j, type ModelClientOptions as k, type PrimitiveBinding as l, type PrimitiveTransport as m, type QueryOptions as n, type RagChunk as o, type RagClient as p, type RagRerankResult as q, type RealtimeClient as r, type RealtimeSubscription as s, type RemoteToolRef as t, type RyuPrimitives as u, type ToolOptions as v, type ToolSchema as w, type TtsClient as x, createAgent as y, createPrimitives as z };