@ryuhq/sdk 0.0.5

package/dist/index.d.ts

@@ -0,0 +1,759 @@
+import { R as Runnable, a as RunnableContext, T as ToolRunnable } from './index-DAxq7Y0R.js';
+export { A as Agent, b as AgentConfig, c as AgentEvent, d as AgentTool, C as ChatDelta, e as ChatMessage, f as ChatResult, D as DurableClient, E as Endpoint, g as EnginesClient, G as GatewayClient, h as GenerateResult, H as HttpPrimitiveTransportOptions, I as ImageClient, J as JsonSchemaProperty, M as MemoryClient, i as MemoryItem, j as ModelClient, k as ModelClientOptions, P as PRIMITIVE_BINDINGS, l as PrimitiveBinding, m as PrimitiveTransport, Q as QueryInput, n as QueryOptions, o as RagChunk, p as RagClient, q as RagRerankResult, r as RealtimeClient, s as RealtimeSubscription, t as RemoteToolRef, u as RyuPrimitives, S as SttClient, v as ToolOptions, w as ToolSchema, x as TtsClient, y as createAgent, z as createPrimitives, B as defineModel, F as defineTool, K as httpPrimitiveTransport, L as inlineToolRunnable, N as query, O as ryuTool } from './index-DAxq7Y0R.js';
+import { Requires, Surface, PluginManifest, RunnableMeta, CompanionSurface, CapabilityReq, TurnHookContribution } from './manifest.js';
+export { AppDependency, AppDependencySchema, CapabilityReqSchema, CompanionSurfaceSchema, Contributes, PluginManifestSchema, RequiresSchema, RunnableKind, RunnableKindSchema, RunnableMetaSchema, SurfaceSchema, ToolAppConfig, ToolAppConfigSchema, WidgetContribution, WidgetContributionSchema, coreManifestJsonSchema, validateManifestStrict, validatePluginId } from './manifest.js';
+import 'zod';
+
+/**
+ * Ryu App authoring factory — `defineApp`.
+ *
+ * A "Ryu App" bundles one or more tools whose results render an interactive
+ * widget inline in chat (the ChatGPT-Apps-style surface). `defineApp` assembles a
+ * complete `plugin.json` `PluginManifest` from a declarative description, deriving
+ * the render-vs-companion split exactly the way Core's in-process provider does
+ * (`apps/core/src/sidecar/mcp/apps/mod.rs` `tools()`):
+ *
+ *   - A **render** tool (`accessible` unset/false) produces the widget: it gets a
+ *     `contributes.widgets[]` entry binding its id to the app's
+ *     `ui://widget/<slug>.html` template, and its runnable config carries
+ *     `widget:true` plus `invoking`/`invoked` status labels.
+ *   - A **companion** tool (`accessible:true`) is a call target a mounted widget
+ *     may invoke: it carries `widget_accessible:true` and gets no widget template.
+ *
+ * v1 boundary: this is **declarative pass-through only** — there is no `run`
+ * handler. Third-party tool code execution needs the plugin runtime (out of
+ * scope); the widget renders from `window.openai.toolInput`/`toolOutput` and Core
+ * echoes the validated arguments as `structuredContent`. `ryu pack` bundles the
+ * `uiEntry` source into the manifest's `ui_code`.
+ */
+
+/** One tool a Ryu App declares. */
+interface AppToolSpec {
+    /**
+     * True when this is a **companion** tool — a call target a mounted widget may
+     * `callTool`. False/unset makes it a **render** tool that produces the widget.
+     */
+    accessible?: boolean;
+    /** Human-readable description the model reads when choosing the tool. */
+    description: string;
+    /** JSON Schema object describing the tool's arguments. Optional. */
+    inputSchema?: Record<string, unknown>;
+    /** Status label shown when a render tool finishes (e.g. `"Chart ready"`). */
+    invoked?: string;
+    /** Status label shown while a render tool runs (e.g. `"Plotting chart…"`). */
+    invoking?: string;
+    /** Tool name (unqualified). The wire id is `<server>__<name>`. */
+    name: string;
+}
+/**
+ * The `requires` block as an AUTHOR writes it: both members optional. Distinct
+ * from the parsed {@link Requires} (where zod has applied its `[]` defaults, so
+ * both are present).
+ */
+interface DefineAppRequires {
+    /** Plugins that must be installed + enabled before this app enables. */
+    apps?: Requires["apps"];
+    /**
+     * Abstract capability edges the broker binds to a provider at enable time
+     * (`[{ capability: "rag" }]`). This is what composable agent slots lower to.
+     */
+    capabilities?: Requires["capabilities"];
+    /** Grants implied by those dependencies (declaration only). */
+    grants?: string[];
+}
+/** Options for {@link defineApp}. */
+interface DefineAppOptions {
+    /** VS-Code-style activation events. Empty = eager (default `["*"]`). */
+    activationEvents?: string[];
+    /** Default widget display mode (`inline` | `fullscreen` | `pip`). */
+    displayMode?: string;
+    /** Permission grants the app declares it needs (e.g. `["mcp:web_search"]`). */
+    grants?: string[];
+    /** Reverse-domain plugin id (e.g. `"com.example.checklist"`). */
+    id: string;
+    /** Widget MIME dialect. Defaults to `text/html+skybridge`. */
+    mime?: string;
+    /**
+     * Plugin-to-plugin dependencies. Core auto-enables them (in dependency order)
+     * before this app, and refuses to disable one while this app still needs it.
+     * Omit for the common case (no dependencies) — the key is then absent from the
+     * emitted manifest entirely.
+     */
+    requires?: DefineAppRequires;
+    /** MCP server namespace for the tool ids. Defaults to `slug`. */
+    server?: string;
+    /**
+     * App slug — used to build the widget uri (`ui://widget/<slug>.html`) and, when
+     * `server` is omitted, the MCP server namespace that qualifies each tool id.
+     */
+    slug: string;
+    /**
+     * Host surfaces this app runs on. **Omitted/empty = every surface** (the
+     * backward-compatible default); it never means "hidden".
+     */
+    targets?: Surface[];
+    /** Human-readable display name shown in the app store / launcher. */
+    title: string;
+    /** The tools this app exposes (at least one render tool is expected). */
+    tools: AppToolSpec[];
+    /**
+     * Source entry (relative to the manifest dir) for the widget UI. `ryu pack`
+     * bundles it into the manifest's `ui_code` so Core can serve the widget HTML.
+     */
+    uiEntry: string;
+    /** Semver version string (e.g. `"1.0.0"`). */
+    version: string;
+}
+/** Build a fully-qualified tool id from a server namespace and tool name. */
+declare function appToolId(server: string, name: string): string;
+/**
+ * Assemble a `plugin.json` manifest for a Ryu App. The result matches Core's
+ * `PluginManifest` serde shape (validated through `PluginManifestSchema`) and can
+ * be written to disk, packed with `ryu pack`, or published with `ryu publish`.
+ *
+ * @example
+ * ```ts
+ * import { defineApp } from "@ryuhq/sdk"
+ *
+ * const manifest = defineApp({
+ *   id: "com.example.checklist",
+ *   title: "Checklist",
+ *   version: "1.0.0",
+ *   slug: "checklist",
+ *   uiEntry: "src/checklist.tsx",
+ *   tools: [
+ *     { name: "render", description: "Render a checklist", invoking: "Building…", invoked: "Ready" },
+ *     { name: "toggle", description: "Toggle an item", accessible: true },
+ *   ],
+ * })
+ * ```
+ */
+declare function defineApp(options: DefineAppOptions): PluginManifest;
+
+/**
+ * Ryu SDK typed builders — one builder per RunnableKind plus a PluginBuilder that
+ * assembles a complete, validated `plugin.json` manifest.
+ *
+ * Each builder follows a fluent interface: construct, chain setter calls, then
+ * call `.build()` to get a validated result. Invalid manifests throw a
+ * descriptive `Error` — never a silent fallback.
+ *
+ * Engine/model fields are typed as `string` throughout.  No provider union is
+ * used so adding a new provider never requires an SDK change.
+ */
+
+/** Base builder shared by all Runnable kinds. */
+declare class RunnableBuilder {
+    protected _id: string;
+    protected _name: string;
+    id(value: string): this;
+    name(value: string): this;
+}
+/** Builds an Agent `RunnableMeta` entry. */
+declare class AgentBuilder extends RunnableBuilder {
+    build(): RunnableMeta;
+}
+/** Builds a Workflow `RunnableMeta` entry. */
+declare class WorkflowBuilder extends RunnableBuilder {
+    build(): RunnableMeta;
+}
+/** Builds a Tool `RunnableMeta` entry. */
+declare class ToolBuilder extends RunnableBuilder {
+    build(): RunnableMeta;
+}
+/** Builds a Skill `RunnableMeta` entry. */
+declare class SkillBuilder extends RunnableBuilder {
+    build(): RunnableMeta;
+}
+/** Create an AgentBuilder. */
+declare const agent: () => AgentBuilder;
+/** Create a WorkflowBuilder. */
+declare const workflow: () => WorkflowBuilder;
+/** Create a ToolBuilder. */
+declare const tool: () => ToolBuilder;
+/** Create a SkillBuilder. */
+declare const skill: () => SkillBuilder;
+/**
+ * Fluent builder for a complete `plugin.json` Plugin manifest. Produces a
+ * validated `PluginManifest` on `.build()` or throws a descriptive `Error`
+ * naming the first invalid field.
+ *
+ * @example
+ * ```ts
+ * import { PluginBuilder, agent, tool } from "@ryuhq/sdk/builder"
+ *
+ * const manifest = new PluginBuilder()
+ *   .id("com.example.my-plugin")
+ *   .name("My Plugin")
+ *   .version("1.0.0")
+ *   .runnable(agent().id("agent-main").name("Main Agent").build())
+ *   .runnable(tool().id("tool-search").name("Web Search").build())
+ *   .grant("mcp:web_search")
+ *   .companion({ label: "My Plugin", icon: "sparkles", shortcut: "ctrl+shift+m" })
+ *   .build()
+ * ```
+ */
+declare class PluginBuilder {
+    private _id;
+    private _name;
+    private _version;
+    private readonly _runnables;
+    private readonly _grants;
+    private _companion;
+    private readonly _dependencies;
+    private readonly _requiredCapabilities;
+    private readonly _requiredGrants;
+    private readonly _targets;
+    /** Set the reverse-domain app id (e.g. `"com.example.my-app"`). */
+    id(value: string): this;
+    /** Set the human-readable display name. */
+    name(value: string): this;
+    /** Set the semver version string (e.g. `"1.0.0"`). */
+    version(value: string): this;
+    /** Append a pre-built `RunnableMeta` (from any per-kind builder). */
+    runnable(meta: RunnableMeta): this;
+    /** Declare a permission grant (e.g. `"mcp:web_search"`). */
+    grant(permission: string): this;
+    /** Set an optional Companion surface descriptor. */
+    companion(surface: CompanionSurface): this;
+    /**
+     * Declare a **plugin-to-plugin dependency**: `id` must be installed and is
+     * auto-enabled (in dependency order) before this plugin enables.
+     *
+     * `minVersion` is a MINIMUM — a bare `"1.2.0"` means `">=1.2.0"`, so an
+     * installed `2.0.0` satisfies it (comparator syntax like `">=1.2, <2"` is
+     * honoured verbatim).
+     */
+    dependsOn(id: string, minVersion?: string): this;
+    /**
+     * Declare a permission grant implied by this plugin's dependencies
+     * (`requires.grants`). Declaration only — the Gateway remains the sole
+     * authority on what a grant allows. Use {@link PluginBuilder.grant} for the
+     * grants this plugin needs in its own right.
+     */
+    requiredGrant(permission: string): this;
+    /**
+     * Declare an abstract **capability** edge (`requires.capabilities`) the broker
+     * resolves to a bound provider at enable time — e.g. `requiresCapability("rag")`.
+     * Distinct from a specific-plugin dependency: a capability edge lets the
+     * binding registry choose the provider. `minVersion` is a MINIMUM (`"1.2.0"`
+     * = `">=1.2.0"`).
+     */
+    requiresCapability(capability: string, minVersion?: string): this;
+    /**
+     * Restrict this plugin to a host surface (`"desktop"`, `"island"`, …).
+     * Declaring NO target is the default and means **every** surface.
+     */
+    target(surface: Surface): this;
+    /**
+     * Validate and return the assembled `PluginManifest`. Throws an `Error` with
+     * the failing field name and message when validation fails.
+     */
+    build(): PluginManifest;
+}
+/**
+ * Fluent builder for a Ryu App — a `plugin.json` whose tools render interactive
+ * widgets inline in chat. Delegates to {@link defineApp} on `.build()`, so it
+ * derives the render-vs-companion split and validates through
+ * `PluginManifestSchema` (throwing a descriptive `Error` on bad input) exactly
+ * like the factory.
+ *
+ * @example
+ * ```ts
+ * import { app } from "@ryuhq/sdk/builder"
+ *
+ * const manifest = app()
+ *   .id("com.example.checklist")
+ *   .title("Checklist")
+ *   .version("1.0.0")
+ *   .slug("checklist")
+ *   .uiEntry("src/checklist.tsx")
+ *   .tool({ name: "render", description: "Render a checklist", invoking: "Building…" })
+ *   .tool({ name: "toggle", description: "Toggle an item", accessible: true })
+ *   .build()
+ * ```
+ */
+declare class AppBuilder {
+    private _id;
+    private _title;
+    private _version;
+    private _slug;
+    private _server;
+    private _displayMode;
+    private _mime;
+    private _uiEntry;
+    private readonly _grants;
+    private readonly _activationEvents;
+    private readonly _tools;
+    private readonly _dependencies;
+    private readonly _requiredCapabilities;
+    private readonly _requiredGrants;
+    private readonly _targets;
+    /** Set the reverse-domain app id (e.g. `"com.example.checklist"`). */
+    id(value: string): this;
+    /** Set the human-readable display name. */
+    title(value: string): this;
+    /** Set the semver version string (e.g. `"1.0.0"`). */
+    version(value: string): this;
+    /** Set the app slug (drives `ui://widget/<slug>.html` and the server default). */
+    slug(value: string): this;
+    /** Override the MCP server namespace for tool ids (defaults to the slug). */
+    server(value: string): this;
+    /** Set the default widget display mode (`inline` | `fullscreen` | `pip`). */
+    displayMode(value: string): this;
+    /** Override the widget MIME dialect (defaults to `text/html+skybridge`). */
+    mime(value: string): this;
+    /** Set the widget UI source entry `ryu pack` bundles into `ui_code`. */
+    uiEntry(value: string): this;
+    /** Declare a permission grant (e.g. `"mcp:web_search"`). */
+    grant(permission: string): this;
+    /** Add a VS-Code-style activation event (empty = eager `["*"]`). */
+    activationEvent(event: string): this;
+    /** Append a tool spec (render tool unless `accessible:true`). */
+    tool(spec: AppToolSpec): this;
+    /**
+     * Declare a **plugin-to-plugin dependency** (auto-enabled, in dependency order,
+     * before this app). `minVersion` is a MINIMUM (`"1.2.0"` = `">=1.2.0"`).
+     */
+    dependsOn(id: string, minVersion?: string): this;
+    /** Declare a grant implied by this app's dependencies (`requires.grants`). */
+    requiredGrant(permission: string): this;
+    /**
+     * Declare an abstract **capability** edge (`requires.capabilities`) the broker
+     * resolves to a bound provider at enable time — e.g. `requiresCapability("rag")`.
+     * Distinct from a specific-plugin dependency: a capability edge lets the
+     * binding registry choose the provider. `minVersion` is a MINIMUM (`"1.2.0"`
+     * = `">=1.2.0"`).
+     */
+    requiresCapability(capability: string, minVersion?: string): this;
+    /** Restrict this app to a host surface. No target = every surface. */
+    target(surface: Surface): this;
+    /**
+     * Validate and return the assembled `PluginManifest`. Throws an `Error` naming
+     * the failing field when validation fails.
+     */
+    build(): PluginManifest;
+}
+/** Create an AppBuilder. */
+declare const app: () => AppBuilder;
+
+/**
+ * Gateway configuration + egress enforcement for the Ryu SDK model client.
+ *
+ * Rust-cored: every function here delegates to the `@ryuhq/sdk-native` addon, so
+ * the gateway URL/token resolution and the direct-provider egress blocklist are
+ * the exact same implementation (`crates/ryu-sdk/src/gateway.rs`) used by the
+ * Go/Python bindings and Core itself — one source of truth, no drift.
+ */
+/** Default base URL for the local Ryu gateway — matches Core's DEFAULT_GATEWAY_URL. */
+declare const DEFAULT_GATEWAY_URL = "http://127.0.0.1:7981";
+/**
+ * Resolve the effective gateway base URL.
+ *
+ * Resolution order (in the Rust core):
+ *   1. `RYU_GATEWAY_URL` env var (when non-empty).
+ *   2. `DEFAULT_GATEWAY_URL`.
+ */
+declare function resolveGatewayUrl(): string;
+/**
+ * Resolve the optional gateway bearer token (`RYU_GATEWAY_TOKEN`), or
+ * `undefined` when unset/empty.
+ */
+declare function resolveGatewayToken(): string | undefined;
+/**
+ * Validate that `baseUrl` is an allowed egress target. Throws a descriptive
+ * `Error` (from the Rust core) when the URL matches a known direct-provider
+ * pattern, enforcing the BYOK-at-the-gateway rule.
+ */
+declare function assertAllowedEgressUrl(baseUrl: string): void;
+
+/**
+ * defineAgent — factory for Runnable agents.
+ *
+ * An agent is a Runnable that drives a multi-turn model loop. It may reference a
+ * workflow as a named tool by including a Runnable with kind="workflow" in its
+ * `tools` list; the agent's run() implementation calls it like any other tool.
+ *
+ * All model calls must go through `ctx.gateway` — no direct provider imports.
+ *
+ * ## Composable primitive slots (the "Pokémon card" model, program §6b)
+ *
+ * `defineAgent` additionally accepts swappable-provider SLOTS —
+ * `defineAgent({ chat, rag, memory, tools, tts, stt })` — where each slot picks
+ * a provider for one attribute of the card. They **lower** to the manifest:
+ *   - `chat`  → the agent `RunnableMeta.config` (model / engine / persona);
+ *   - `rag` / `memory` / `tts` / `stt` → `requires.capabilities` edges the
+ *     capability broker binds to a provider (with an optional explicit override);
+ *   - `tools` → the tool ids the agent exposes.
+ *
+ * The slots are ADDITIVE: the classic `defineAgent({ id, name, run })` signature
+ * is unchanged. When `run` is omitted, a thin default run drives the `chat` slot
+ * through `ctx.gateway` (never a direct provider).
+ */
+
+/**
+ * A capability-backed slot (rag / memory / tts / stt). Written as:
+ *   - `true` — require the capability; the broker/registry picks the provider;
+ *   - `"com.acme.graphrag"` — bind this explicit provider app id;
+ *   - `{ provider?, minVersion? }` — provider override and/or a version floor.
+ */
+type CapabilitySlot = boolean | string | {
+    provider?: string;
+    minVersion?: string;
+};
+/**
+ * The chat/model slot — the agent's own, swappable model config. Written as a
+ * model-id string shorthand or the full object. Every field is a `string`; no
+ * provider union, so a new provider never needs an SDK change.
+ */
+type ChatSlot = string | {
+    /** Model id (swappable). */
+    model?: string;
+    /** Engine id (e.g. `"llamacpp"`, `"openai-compat"`). */
+    engine?: string;
+    /** System persona / instructions. */
+    persona?: string;
+    /** Preference key Core resolves to a model id (swappable, not hardcoded). */
+    modelPrefKey?: string;
+};
+/** The composable slots an agent card declares. All optional. */
+interface AgentSlots {
+    /** The chat/model slot (model + engine + persona). */
+    chat?: ChatSlot;
+    /** Memory provider slot → `requires.capabilities: [{ capability: "memory" }]`. */
+    memory?: CapabilitySlot;
+    /** RAG provider slot → `requires.capabilities: [{ capability: "rag" }]`. */
+    rag?: CapabilitySlot;
+    /** STT provider slot → `requires.capabilities: [{ capability: "stt" }]`. */
+    stt?: CapabilitySlot;
+    /** Tools the agent exposes — Runnables (workflows/tools) or bare tool ids. */
+    tools?: readonly (Runnable | string)[];
+    /** TTS provider slot → `requires.capabilities: [{ capability: "tts" }]`. */
+    tts?: CapabilitySlot;
+}
+/** Options accepted by `defineAgent`. */
+interface AgentOptions<TInput, TOutput> extends AgentSlots {
+    /** Stable unique identifier (e.g. "agent-researcher"). */
+    id: string;
+    /** Human-readable display name. */
+    name: string;
+    /**
+     * The agent's run implementation. OPTIONAL when slots are declared — a
+     * `chat`-slot default is synthesized (drives `ctx.gateway`). All model calls
+     * MUST go through `ctx.gateway`.
+     */
+    run?(input: TInput, ctx: RunnableContext): Promise<TOutput>;
+}
+/**
+ * The lowered "card": the swappable slots resolved to manifest-ready pieces —
+ * the persona/model config plus the `requires.capabilities` edges. This is what
+ * makes the Pokémon-card model literal in code.
+ */
+interface AgentCard {
+    /** Lowered capability edges for `requires.capabilities`. */
+    capabilities: CapabilityReq[];
+    /** Engine id from the `chat` slot. */
+    engine?: string;
+    /** Model id from the `chat` slot. */
+    model?: string;
+    /** Preference key from the `chat` slot. */
+    modelPrefKey?: string;
+    /** Persona/instructions from the `chat` slot. */
+    persona?: string;
+    /** Explicit provider bindings by capability (a slot that named a provider). */
+    providers: Record<string, string>;
+    /** Tool ids the agent exposes. */
+    tools: string[];
+}
+/** A defined agent: a Runnable plus its lowered card + a manifest lowering. */
+interface AgentRunnable<TInput = unknown, TOutput = unknown> extends Runnable<TInput, TOutput> {
+    /** The lowered slot card (empty edges when no slots were declared). */
+    readonly card: AgentCard;
+    /**
+     * Lower this agent (card + run identity) to a single-agent `plugin.json`
+     * `PluginManifest`: the agent `RunnableMeta` carries the persona/model
+     * config; `requires.capabilities` carries the slot edges. Throws if the
+     * assembled manifest is invalid.
+     */
+    toManifest(options: AgentManifestOptions): PluginManifest;
+}
+/** Options for {@link AgentRunnable.toManifest}. */
+interface AgentManifestOptions {
+    /** Extra permission grants beyond those implied by slots. */
+    grants?: string[];
+    /** Reverse-domain plugin id (e.g. `"com.acme.researcher"`). */
+    id: string;
+    /** Display name (defaults to the agent's name). */
+    name?: string;
+    /** Semver version (e.g. `"1.0.0"`). */
+    version: string;
+}
+/**
+ * Create a Runnable agent.
+ *
+ * The returned value satisfies `Runnable<TInput, TOutput>` with `kind = "agent"`
+ * and additionally exposes the lowered {@link AgentCard} + a `toManifest()`
+ * lowering, so a slot-composed agent round-trips to a valid `plugin.json`.
+ *
+ * @example Classic (unchanged, back-compat):
+ * ```ts
+ * const a = defineAgent({
+ *   id: "agent-researcher",
+ *   name: "Researcher",
+ *   async run({ query }, ctx) {
+ *     const r = await ctx.gateway.chat([{ role: "user", content: query }]);
+ *     return { answer: r.content };
+ *   },
+ * });
+ * ```
+ *
+ * @example Composable slots (the Pokémon card):
+ * ```ts
+ * const cmo = defineAgent({
+ *   id: "agent-cmo",
+ *   name: "CMO",
+ *   chat: { model: "gpt-4o", persona: "You are a CMO." },
+ *   rag: true,                    // requires.capabilities: [{ capability: "rag" }]
+ *   memory: { minVersion: "1.2" },
+ *   tts: "com.acme.elevenlabs",   // explicit provider override
+ * });
+ * const manifest = cmo.toManifest({ id: "com.acme.cmo", version: "1.0.0" });
+ * ```
+ */
+declare function defineAgent<TInput = unknown, TOutput = unknown>(options: AgentOptions<TInput, TOutput>): AgentRunnable<TInput, TOutput>;
+
+/**
+ * defineSkill — factory for Runnable skills.
+ *
+ * A skill is a prompt-template / capability block that is reusable across
+ * agents and workflows.  Like a tool it is stateless, but its primary purpose
+ * is to encapsulate a reusable prompt pattern rather than a side-effectful
+ * function.
+ *
+ * All model calls must go through `ctx.gateway` — no direct provider imports.
+ */
+
+/** Options accepted by `defineSkill`. */
+interface SkillOptions<TInput, TOutput> {
+    /** Stable unique identifier (e.g. "skill-summarise"). */
+    id: string;
+    /** Human-readable display name. */
+    name: string;
+    /**
+     * The skill's run implementation.
+     *
+     * Skills typically build a prompt from `input` and call `ctx.gateway.chat()`
+     * to get a model response, then return structured output.  All model calls
+     * MUST go through `ctx.gateway`.
+     */
+    run(input: TInput, ctx: RunnableContext): Promise<TOutput>;
+}
+/**
+ * Create a Runnable skill.
+ *
+ * The returned value satisfies the `Runnable<TInput, TOutput>` interface with
+ * `kind = "skill"`.
+ *
+ * @example
+ * ```ts
+ * const summariseSkill = defineSkill({
+ *   id: "skill-summarise",
+ *   name: "Summarise",
+ *   async run({ text }, ctx) {
+ *     const result = await ctx.gateway.chat([
+ *       { role: "user", content: `Summarise the following:\n\n${text}` },
+ *     ]);
+ *     return { summary: result.content };
+ *   },
+ * });
+ * ```
+ */
+declare function defineSkill<TInput = unknown, TOutput = unknown>(options: SkillOptions<TInput, TOutput>): Runnable<TInput, TOutput>;
+
+/**
+ * Turn-hook + plugin authoring factories.
+ *
+ * A turn hook is plugin-authored logic that runs after each assistant turn in
+ * Ryu's Core plugin sandbox (`apps/core/src/plugin_host/`). The hook reaches Core
+ * only through capability-gated `host` functions and returns a directive. This is
+ * what makes features like double-check and goal real, installable plugins.
+ *
+ * `defineTurnHook` serializes your typed `run(ctx, host)` function to the `code`
+ * string the sandbox executes. IMPORTANT: the function must be **self-contained**
+ * — it runs in a fresh sandbox with only `ctx` and `host` in scope, so it cannot
+ * capture outer variables, imports, or closures (same constraint as a Web Worker
+ * body). Reference only `ctx`, `host`, and language built-ins.
+ */
+
+/** The context a `post_assistant_turn` hook receives. */
+interface HookContext {
+    /** The agent that produced the turn. */
+    agent_id?: string;
+    /** The conversation id (also the natural per-conversation storage key). */
+    conversation_id?: string;
+    /** Per-request plugin flags (e.g. a composer toggle): `{ "<pluginId>": true }`. */
+    flags: Record<string, boolean>;
+    /** Recent transcript (oldest → newest). */
+    transcript: Array<{
+        role: string;
+        content: string;
+    }>;
+}
+/** Arguments to a `host.sideModel` call. */
+interface SideModelArgs {
+    /** Reasoning effort, forwarded when non-empty. */
+    effort?: string;
+    /** Explicit model id (wins over `model_pref_key`). */
+    model?: string;
+    /** A preference key Core resolves to a model id (swappable, not hardcoded). */
+    model_pref_key?: string;
+    /** The user prompt for the side model. Required. */
+    prompt: string;
+    /** Optional system prompt. */
+    system?: string;
+}
+/** The capability bridge available to a hook (gated by manifest grants). */
+interface HostApi {
+    /** Captured logging. */
+    log(...args: unknown[]): void;
+    /** One non-streaming gateway completion. Grant: `hook:side-model`. */
+    sideModel(args: SideModelArgs): Promise<string>;
+    /** The plugin's own namespaced KV store. Grant: `storage:kv`. */
+    storage: {
+        get(key: string): Promise<string | null>;
+        set(key: string, value: unknown): Promise<boolean>;
+        delete(key: string): Promise<boolean>;
+        keys(): Promise<string[]>;
+    };
+}
+/** What a hook asks the chat path to do after the assistant turn. */
+type HookDirective = {
+    kind: "none";
+} | {
+    kind: "note";
+    text: string;
+} | {
+    kind: "continue";
+    text: string;
+};
+/** A typed hook implementation: `(ctx, host) => directive`. */
+type HookRun = (ctx: HookContext, host: HostApi) => HookDirective | Promise<HookDirective>;
+interface DefineTurnHookOptions {
+    /** Stable id for this hook, unique within the plugin. */
+    id: string;
+    /** Turn boundary (default `"post_assistant_turn"`). */
+    on?: string;
+    /** The hook body. Must be self-contained (no captured variables). */
+    run: HookRun;
+}
+/**
+ * Build a turn-hook contribution from a typed `run` function. The function source
+ * is serialized into the sandbox `code` string and invoked with `ctx`/`host` at
+ * run time.
+ */
+declare function defineTurnHook(options: DefineTurnHookOptions): TurnHookContribution;
+interface DefinePluginOptions {
+    /** Activation events (default `["*"]` — driven by the enabled flag). */
+    activationEvents?: string[];
+    /** Declarative composer widgets (toggle/chip), passed verbatim to the desktop. */
+    composerControls?: Record<string, unknown>[];
+    /** Capability grants the hooks need (e.g. `["hook:side-model", "storage:kv"]`). */
+    grants?: string[];
+    /** Reverse-domain id (e.g. `"com.example.my-plugin"`). */
+    id: string;
+    /** Display name. */
+    name: string;
+    /**
+     * Plugin-to-plugin dependencies. Core auto-enables them (in dependency order)
+     * before this plugin, and refuses to disable one while this plugin needs it.
+     * Omit for the common case — the key is then absent from the emitted manifest.
+     */
+    requires?: DefineAppRequires;
+    /** Declarative settings tabs (model pickers, fields), passed verbatim. */
+    settingsTabs?: Record<string, unknown>[];
+    /** Declarative slash commands, passed verbatim. */
+    slashCommands?: Record<string, unknown>[];
+    /**
+     * Host surfaces this plugin runs on. **Omitted/empty = every surface** (the
+     * backward-compatible default); it never means "hidden".
+     */
+    targets?: Surface[];
+    /**
+     * Inline tools the plugin ships — each a {@link ToolRunnable} from `defineTool`
+     * whose `run` body is bundled as Core's `inline_deno` backend (registered as
+     * `app__<tool.id>`). Shipping any tool auto-adds the `tool:execute` grant.
+     */
+    tools?: ToolRunnable[];
+    /** Turn hooks the plugin contributes. */
+    turnHooks?: TurnHookContribution[];
+    /** Semver version (e.g. `"1.0.0"`). */
+    version: string;
+}
+/**
+ * Assemble a `plugin.json` manifest for a turn-hook plugin. The result matches
+ * Core's `PluginManifest` serde shape and can be written to disk or validated via
+ * `validateManifestStrict`.
+ */
+declare function definePlugin(options: DefinePluginOptions): PluginManifest;
+
+/**
+ * defineWorkflow — factory for Runnable workflows.
+ *
+ * A workflow orchestrates agents (and other Runnables) as sequential steps.
+ * It exposes the peer relationship described in packages/sdk/README.md §2:
+ * a workflow may list an agent as a step and call it via its run() method.
+ *
+ * All model calls must go through `ctx.gateway` — no direct provider imports.
+ */
+
+/**
+ * A single step inside a workflow definition.
+ *
+ * A step is any `Runnable` — most commonly an agent, but may also be a tool
+ * or a nested workflow (allowing composition without a strict hierarchy).
+ */
+type WorkflowStep<TStepInput = unknown, TStepOutput = unknown> = Runnable<TStepInput, TStepOutput>;
+/** Options accepted by `defineWorkflow`. */
+interface WorkflowOptions<TInput, TOutput> {
+    /** Stable unique identifier (e.g. "workflow-report"). */
+    id: string;
+    /** Human-readable display name. */
+    name: string;
+    /**
+     * The workflow's run implementation.
+     *
+     * May call any step via `step.run(input, ctx)`.  All model calls that
+     * steps make MUST go through `ctx.gateway`.
+     */
+    run(input: TInput, ctx: RunnableContext): Promise<TOutput>;
+    /**
+     * Optional list of Runnables this workflow orchestrates as steps.
+     *
+     * An agent may be listed here so the workflow can invoke it by calling
+     * `step.run(input, ctx)` — this is the peer relationship described in
+     * packages/sdk/README.md §2.
+     */
+    steps?: readonly Runnable[];
+}
+/**
+ * Create a Runnable workflow.
+ *
+ * The returned value satisfies the `Runnable<TInput, TOutput>` interface with
+ * `kind = "workflow"`.
+ *
+ * @example
+ * ```ts
+ * const myWorkflow = defineWorkflow({
+ *   id: "workflow-report",
+ *   name: "Report Workflow",
+ *   steps: [researchAgent],
+ *   async run({ topic }, ctx) {
+ *     const { answer } = await researchAgent.run({ query: topic }, ctx);
+ *     return { report: answer };
+ *   },
+ * });
+ * ```
+ */
+declare function defineWorkflow<TInput = unknown, TOutput = unknown>(options: WorkflowOptions<TInput, TOutput>): Runnable<TInput, TOutput>;
+
+export { AgentBuilder, type AgentCard, type AgentManifestOptions, type AgentOptions, type AgentRunnable, type AgentSlots, AppBuilder, type AppToolSpec, CapabilityReq, type CapabilitySlot, type ChatSlot, CompanionSurface, DEFAULT_GATEWAY_URL, type DefineAppOptions, type DefineAppRequires, type DefinePluginOptions, type DefineTurnHookOptions, type HookContext, type HookDirective, type HookRun, type HostApi, PluginBuilder, PluginManifest, Requires, Runnable, RunnableContext, RunnableMeta, type SideModelArgs, SkillBuilder, type SkillOptions, Surface, ToolBuilder, ToolRunnable, TurnHookContribution, WorkflowBuilder, type WorkflowOptions, type WorkflowStep, agent, app, appToolId, assertAllowedEgressUrl, defineAgent, defineApp, definePlugin, defineSkill, defineTurnHook, defineWorkflow, resolveGatewayToken, resolveGatewayUrl, skill, tool, workflow };