@ryuhq/sdk 0.0.5

package/dist/manifest.d.ts

@@ -0,0 +1,355 @@
+import { z } from 'zod';
+
+/**
+ * Ryu SDK manifest types — TypeScript mirror of the Core `plugin_manifest` and
+ * `runnable` schemas (`apps/core/src/plugin_manifest/mod.rs` and
+ * `apps/core/src/runnable/mod.rs`).
+ *
+ * These types must stay in sync with the Rust serde shapes so that a manifest
+ * authored here deserialises cleanly by `PluginManifestLoader::load()` in Core.
+ *
+ * Design note on engine/model fields: every field that holds an engine name,
+ * model id, or provider reference is typed as `string` — never a union of
+ * known provider literals.  A new provider must never require an SDK change.
+ */
+
+/**
+ * The kind of a Runnable. Mirrors `RunnableKind` in
+ * `apps/core/src/runnable/mod.rs`.
+ */
+declare const RunnableKindSchema: z.ZodEnum<{
+    agent: "agent";
+    workflow: "workflow";
+    tool: "tool";
+    skill: "skill";
+    companion: "companion";
+}>;
+type RunnableKind = z.infer<typeof RunnableKindSchema>;
+/**
+ * Kind-agnostic identity snapshot of a Runnable. Mirrors `RunnableMeta` in
+ * `apps/core/src/runnable/mod.rs`.
+ */
+declare const RunnableMetaSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    kind: z.ZodEnum<{
+        agent: "agent";
+        workflow: "workflow";
+        tool: "tool";
+        skill: "skill";
+        companion: "companion";
+    }>;
+    config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+type RunnableMeta = z.infer<typeof RunnableMetaSchema>;
+/**
+ * True when a companion `label` impersonates first-party Ryu/system chrome.
+ *
+ * Mirrors Core's `label_impersonates_system_chrome`
+ * (`apps/core/src/plugin_manifest/schema.rs`) and the desktop `validatePluginRoute`
+ * title gate (`apps/desktop/src/contributions/host/rpc.ts`): a plugin's visible
+ * label may not contain `"ryu"` or `"system"` (case-insensitive), so a third-party
+ * companion can never pose as built-in UI. The desktop host's mandatory,
+ * non-removable `"Plugin ·"` attribution prefix is the primary guarantee; this is
+ * defense in depth enforced at the authoring seam so a hostile label is rejected
+ * before `ryu pack`/publish rather than at load.
+ */
+declare function labelImpersonatesSystemChrome(label: string): boolean;
+/**
+ * Optional in-desktop overlay / sidebar panel descriptor. Mirrors
+ * `CompanionSurface` in `apps/core/src/plugin_manifest/mod.rs`.
+ */
+declare const CompanionSurfaceSchema: z.ZodObject<{
+    label: z.ZodString;
+    icon: z.ZodOptional<z.ZodString>;
+    shortcut: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type CompanionSurface = z.infer<typeof CompanionSurfaceSchema>;
+/**
+ * A server-side chat turn hook. Mirrors `TurnHookContribution` in
+ * `apps/core/src/plugin_manifest/mod.rs`. `code` is a JS body run in the plugin
+ * sandbox with `ctx` + `host` in scope; it returns a directive. Authors usually
+ * build this via `defineTurnHook` rather than writing the string by hand.
+ */
+declare const TurnHookContributionSchema: z.ZodObject<{
+    id: z.ZodString;
+    on: z.ZodDefault<z.ZodString>;
+    code: z.ZodString;
+}, z.core.$strip>;
+type TurnHookContribution = z.infer<typeof TurnHookContributionSchema>;
+/**
+ * One app-widget contribution (Ryu Apps). Binds the render tool that produces the
+ * widget to its `ui://widget/<slug>.html` template. Shape-identical to Core's
+ * `WidgetContribution` (`apps/core/src/plugin_manifest/mod.rs`): built-in apps
+ * serve the HTML from the in-process provider and leave `ui_entry` unset, while a
+ * third-party app authored here sets `ui_entry` so `ryu pack` bundles the source
+ * into the manifest's `ui_code`.
+ */
+declare const WidgetContributionSchema: z.ZodObject<{
+    tool_id: z.ZodString;
+    uri: z.ZodString;
+    ui_entry: z.ZodOptional<z.ZodString>;
+    mime: z.ZodDefault<z.ZodString>;
+    default_display_mode: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+type WidgetContribution = z.infer<typeof WidgetContributionSchema>;
+/**
+ * The `config` blob carried by a Ryu App's `kind:"tool"` runnable. Core's strict
+ * `ToolConfig` (`apps/core/src/plugin_manifest/schema.rs`) requires `slug` and
+ * ignores unknown fields on the current shape; the widget flags below are read by
+ * Core's `register_app_tool_with_widget` synthesis path (a separate Core unit) to
+ * rebuild the `_meta` binding, mirroring how the in-process `apps::tools()`
+ * derives `outputTemplate` / `toolInvocation` / `widgetAccessible`.
+ */
+declare const ToolAppConfigSchema: z.ZodObject<{
+    slug: z.ZodString;
+    description: z.ZodString;
+    input_schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    widget: z.ZodDefault<z.ZodBoolean>;
+    widget_accessible: z.ZodDefault<z.ZodBoolean>;
+    invoking: z.ZodOptional<z.ZodString>;
+    invoked: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ToolAppConfig = z.infer<typeof ToolAppConfigSchema>;
+/**
+ * The `contributes` block. Mirrors `Contributes` in
+ * `apps/core/src/plugin_manifest/mod.rs`. The declarative UI surfaces
+ * (`composer_controls` / `settings_tabs` / `slash_commands`) are passed verbatim
+ * to the desktop renderer, so they are typed loosely here (records).
+ */
+declare const ContributesSchema: z.ZodObject<{
+    turn_hooks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        on: z.ZodDefault<z.ZodString>;
+        code: z.ZodString;
+    }, z.core.$strip>>>;
+    composer_controls: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    settings_tabs: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    slash_commands: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    widgets: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        tool_id: z.ZodString;
+        uri: z.ZodString;
+        ui_entry: z.ZodOptional<z.ZodString>;
+        mime: z.ZodDefault<z.ZodString>;
+        default_display_mode: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+type Contributes = z.infer<typeof ContributesSchema>;
+/**
+ * One optional post-install setup/companion card step surfaced on the
+ * marketplace detail dialog (Phase 1.5 Ryu extension). All fields optional so a
+ * card can be a bare call-to-action or a labelled instruction. `ryu publish`
+ * forwards this into the publish body's `setup` field.
+ */
+declare const SetupStepSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    actionLabel: z.ZodOptional<z.ZodString>;
+    actionUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type SetupStep = z.infer<typeof SetupStepSchema>;
+/**
+ * A single plugin-to-plugin dependency edge. Mirrors `AppDependency` in
+ * `apps/core/src/plugin_manifest/mod.rs`.
+ *
+ * `min_version` is snake_case on the wire (Core declares no serde rename) and is
+ * a **minimum**, not a caret range: a bare `"1.2.0"` means `">=1.2.0"`, so an
+ * installed `2.0.0` satisfies it. Explicit comparator syntax (`">=1.2, <2"`,
+ * `"^1.2"`, `"~1.2"`) is honoured verbatim by Core's `parse_min_version`.
+ */
+declare const AppDependencySchema: z.ZodObject<{
+    id: z.ZodString;
+    min_version: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type AppDependency = z.infer<typeof AppDependencySchema>;
+/**
+ * A single **capability** edge — the layered, provider-agnostic dependency
+ * (`requires: [{ capability: "rag" }]`) the capability broker resolves to a
+ * concrete provider app at bind time. Mirrors `CapabilityReq` in
+ * `crates/ryu-kernel-contracts/src/manifest.rs` (the canonical contract):
+ * `{ capability, min_version? }`. Distinct from an `apps` edge (which names a
+ * specific plugin id); a `capabilities` edge names an abstract capability and
+ * lets the binding registry pick — or the user override — which enabled provider
+ * serves it. This is the field the composable `defineAgent` slots lower to.
+ */
+declare const CapabilityReqSchema: z.ZodObject<{
+    capability: z.ZodString;
+    min_version: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type CapabilityReq = z.infer<typeof CapabilityReqSchema>;
+/**
+ * The `requires` block — this plugin's dependencies. Mirrors `Requires` in
+ * `apps/core/src/plugin_manifest/mod.rs`.
+ *
+ * Core resolves `apps` into a topological enable order (`plugins::graph`):
+ * enabling this plugin auto-enables its dependencies first, and disabling a
+ * dependency is REFUSED (409) while an enabled dependent still needs it.
+ *
+ * **Absent = no dependencies** — the backward-compatible default every manifest
+ * predating this field carries.
+ */
+declare const RequiresSchema: z.ZodObject<{
+    apps: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        min_version: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    capabilities: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        capability: z.ZodString;
+        min_version: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    grants: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type Requires = z.infer<typeof RequiresSchema>;
+/**
+ * A host surface a plugin can declare support for via `targets`. Mirrors Core's
+ * `Surface` enum (`#[serde(rename_all = "kebab-case")]`), so these eight tokens
+ * are the exact wire values — also the vocabulary of the `x-ryu-surface` request
+ * header Core filters listings on.
+ */
+declare const SurfaceSchema: z.ZodEnum<{
+    gateway: "gateway";
+    core: "core";
+    desktop: "desktop";
+    island: "island";
+    mobile: "mobile";
+    extension: "extension";
+    web: "web";
+    cli: "cli";
+}>;
+type Surface = z.infer<typeof SurfaceSchema>;
+/**
+ * Full schema for a `plugin.json` Plugin manifest. Mirrors `PluginManifest` in
+ * `apps/core/src/plugin_manifest/mod.rs`.
+ *
+ * Validation rules (matching Core's `PluginManifestLoader`):
+ * - `id` must be non-empty
+ * - `version` must be a valid semver string (MAJOR.MINOR.PATCH)
+ * - `runnables` may be empty for a "surface-only" plugin, but each entry must be
+ *   a valid `RunnableMeta`
+ */
+declare const PluginManifestSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    version: z.ZodString;
+    ui_code_sha256: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    runnables: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            agent: "agent";
+            workflow: "workflow";
+            tool: "tool";
+            skill: "skill";
+            companion: "companion";
+        }>;
+        config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
+    permission_grants: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    companion: z.ZodOptional<z.ZodObject<{
+        label: z.ZodString;
+        icon: z.ZodOptional<z.ZodString>;
+        shortcut: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    activation_events: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    contributes: z.ZodOptional<z.ZodObject<{
+        turn_hooks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            on: z.ZodDefault<z.ZodString>;
+            code: z.ZodString;
+        }, z.core.$strip>>>;
+        composer_controls: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        settings_tabs: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        slash_commands: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        widgets: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            tool_id: z.ZodString;
+            uri: z.ZodString;
+            ui_entry: z.ZodOptional<z.ZodString>;
+            mime: z.ZodDefault<z.ZodString>;
+            default_display_mode: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    requires: z.ZodOptional<z.ZodObject<{
+        apps: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            min_version: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        capabilities: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            capability: z.ZodString;
+            min_version: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        grants: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    targets: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        gateway: "gateway";
+        core: "core";
+        desktop: "desktop";
+        island: "island";
+        mobile: "mobile";
+        extension: "extension";
+        web: "web";
+        cli: "cli";
+    }>>>;
+    affiliate: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        rule: z.ZodOptional<z.ZodObject<{
+            type: z.ZodEnum<{
+                flat: "flat";
+                percent: "percent";
+            }>;
+            value: z.ZodNumber;
+            recurring: z.ZodDefault<z.ZodBoolean>;
+            durationMonths: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            fundedBy: z.ZodDefault<z.ZodEnum<{
+                platform: "platform";
+                seller: "seller";
+            }>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    description: z.ZodOptional<z.ZodString>;
+    tagline: z.ZodOptional<z.ZodString>;
+    author: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        name: z.ZodString;
+        email: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>>;
+    homepage: z.ZodOptional<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    category: z.ZodOptional<z.ZodString>;
+    license: z.ZodOptional<z.ZodString>;
+    iconUrl: z.ZodOptional<z.ZodString>;
+    screenshots: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    privacyPolicyUrl: z.ZodOptional<z.ZodString>;
+    termsOfServiceUrl: z.ZodOptional<z.ZodString>;
+    capabilities: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    examplePrompts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    setup: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        actionLabel: z.ZodOptional<z.ZodString>;
+        actionUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodArray<z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        actionLabel: z.ZodOptional<z.ZodString>;
+        actionUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>]>>;
+}, z.core.$strip>;
+type PluginManifest = z.infer<typeof PluginManifestSchema>;
+/**
+ * Validate a plugin id with Core's strict reverse-domain, path-traversal-safe
+ * rules. Throws a descriptive `Error` when invalid.
+ */
+declare function validatePluginId(id: string): void;
+/**
+ * Validate a full `plugin.json` string against Core's authoritative rules
+ * (id, semver, per-kind runnable config contracts). Returns the normalized
+ * manifest JSON string, or throws.
+ */
+declare function validateManifestStrict(manifestJson: string): string;
+/**
+ * The Core-derived JSON Schema for a `plugin.json`, as a parsed object. Stays in
+ * lockstep with the Rust types because it is emitted from them.
+ */
+declare function coreManifestJsonSchema(): unknown;
+
+export { type AppDependency, AppDependencySchema, type CapabilityReq, CapabilityReqSchema, type CompanionSurface, CompanionSurfaceSchema, type Contributes, ContributesSchema, type PluginManifest, PluginManifestSchema, type Requires, RequiresSchema, type RunnableKind, RunnableKindSchema, type RunnableMeta, RunnableMetaSchema, type SetupStep, SetupStepSchema, type Surface, SurfaceSchema, type ToolAppConfig, ToolAppConfigSchema, type TurnHookContribution, TurnHookContributionSchema, type WidgetContribution, WidgetContributionSchema, coreManifestJsonSchema, labelImpersonatesSystemChrome, validateManifestStrict, validatePluginId };

package/dist/manifest.js

@@ -0,0 +1,38 @@
+import {
+  AppDependencySchema,
+  CapabilityReqSchema,
+  CompanionSurfaceSchema,
+  ContributesSchema,
+  PluginManifestSchema,
+  RequiresSchema,
+  RunnableKindSchema,
+  RunnableMetaSchema,
+  SetupStepSchema,
+  SurfaceSchema,
+  ToolAppConfigSchema,
+  TurnHookContributionSchema,
+  WidgetContributionSchema,
+  coreManifestJsonSchema,
+  labelImpersonatesSystemChrome,
+  validateManifestStrict,
+  validatePluginId
+} from "./chunk-GXHL5CO7.js";
+export {
+  AppDependencySchema,
+  CapabilityReqSchema,
+  CompanionSurfaceSchema,
+  ContributesSchema,
+  PluginManifestSchema,
+  RequiresSchema,
+  RunnableKindSchema,
+  RunnableMetaSchema,
+  SetupStepSchema,
+  SurfaceSchema,
+  ToolAppConfigSchema,
+  TurnHookContributionSchema,
+  WidgetContributionSchema,
+  coreManifestJsonSchema,
+  labelImpersonatesSystemChrome,
+  validateManifestStrict,
+  validatePluginId
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@ryuhq/sdk",
+  "version": "0.0.5",
+  "type": "module",
+  "description": "Ryu developer SDK: typed builders and CLI for authoring plugin.json Plugin bundles",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./manifest": {
+      "types": "./dist/manifest.d.ts",
+      "import": "./dist/manifest.js",
+      "require": "./dist/manifest.cjs"
+    },
+    "./agent": {
+      "types": "./dist/agent.d.ts",
+      "import": "./dist/agent.js",
+      "require": "./dist/agent.cjs"
+    },
+    "./cli": {
+      "import": "./dist/cli.js"
+    }
+  },
+  "bin": {
+    "ryu": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "check-types": "tsc --noEmit",
+    "generate:contracts": "bun run scripts/generate-contracts.ts",
+    "test": "bun test",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@ryuhq/sdk-native": "0.1.0",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.4",
+    "json-schema-to-typescript": "^15.0.4",
+    "tsup": "^8.5.1",
+    "typescript": "^5"
+  }
+}

package/src/agent/agent.ts

@@ -0,0 +1,208 @@
+/**
+ * `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.
+ */
+
+import { defineModel } from "../model/client.ts";
+import { resolveGatewayToken, resolveGatewayUrl } from "../model/gateway.ts";
+import {
+	createPrimitives,
+	httpPrimitiveTransport,
+} from "../runnable/primitives.ts";
+import type { GatewayClient } from "../runnable/runnable-types.ts";
+import {
+	type AgentEvent,
+	type AgentEventAuthRequired,
+	type LoopConfig,
+	runAgentLoop,
+} from "./loop.ts";
+import type { LoopMessage, ModelUsage } from "./model-call.ts";
+import type { AgentTool, ToolExecContext } from "./tools.ts";
+
+const DEFAULT_MAX_STEPS = 10;
+const DEFAULT_CORE_URL = "http://127.0.0.1:7980";
+
+/** A target node for inference / tool execution: a base URL + optional token. */
+export interface Endpoint {
+	baseUrl?: string;
+	token?: string;
+}
+
+/** Declarative configuration for an `Agent`. */
+export 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()`. */
+export 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;
+}
+
+/** Read `process.env` defensively (SDK may run outside Node typings). */
+function env(key: string): string | undefined {
+	const value = (globalThis as { process?: { env?: Record<string, string> } })
+		.process?.env?.[key];
+	return value && value !== "" ? value : undefined;
+}
+
+/**
+ * Build a `GatewayClient` for local tools that lazily constructs the native
+ * `ModelClient` only on first use — so an agent with no gateway-calling local
+ * tools never touches the native addon.
+ */
+function lazyGatewayClient(
+	model: string,
+	baseUrl: string,
+	token?: string
+): GatewayClient {
+	let client: ReturnType<typeof defineModel> | null = null;
+	const get = () => {
+		client ??= defineModel(model, { baseUrl, token });
+		return client;
+	};
+	return {
+		chat: (messages) => get().chat(messages),
+		stream: (messages) => get().stream(messages),
+	};
+}
+
+/** A declarative, loop-owning agent. */
+export class Agent {
+	readonly config: AgentConfig;
+
+	constructor(config: AgentConfig) {
+		this.config = config;
+	}
+
+	/** Assemble the loop config for a given prompt. */
+	private buildLoopConfig(prompt: string, signal?: AbortSignal): LoopConfig {
+		const gatewayBaseUrl = this.config.node?.baseUrl ?? resolveGatewayUrl();
+		const gatewayToken = this.config.node?.token ?? resolveGatewayToken();
+		const coreBaseUrl =
+			this.config.core?.baseUrl ?? env("RYU_CORE_URL") ?? DEFAULT_CORE_URL;
+		const coreToken = this.config.core?.token ?? env("RYU_TOKEN");
+
+		const messages: LoopMessage[] = [];
+		if (this.config.instructions) {
+			messages.push({ role: "system", content: this.config.instructions });
+		}
+		messages.push({ role: "user", content: prompt });
+
+		const toolCtx: ToolExecContext = {
+			agentId: this.config.agentId,
+			coreBaseUrl,
+			coreToken,
+			userId: this.config.userId,
+			signal,
+			runnableContext: {
+				gateway: lazyGatewayClient(
+					this.config.model,
+					gatewayBaseUrl,
+					gatewayToken
+				),
+				signal,
+				// Mount the composable primitive surface only when a plugin id is
+				// present — the bridge families authenticate it, so we never attach a
+				// half-wired transport (advisor guidance / §6b).
+				...(this.config.pluginId
+					? createPrimitives(
+							httpPrimitiveTransport({
+								nodeUrl: coreBaseUrl,
+								token: coreToken,
+								pluginId: this.config.pluginId,
+							})
+						)
+					: {}),
+			},
+		};
+
+		return {
+			model: this.config.model,
+			gatewayBaseUrl,
+			gatewayToken,
+			messages,
+			tools: this.config.tools ?? {},
+			toolCtx,
+			maxSteps: this.config.maxSteps ?? DEFAULT_MAX_STEPS,
+			signal,
+		};
+	}
+
+	/** Stream loop events (text / tool_call / tool_result / auth_required / …). */
+	stream(prompt: string, signal?: AbortSignal): AsyncGenerator<AgentEvent> {
+		return runAgentLoop(this.buildLoopConfig(prompt, signal));
+	}
+
+	/** Run to completion and return the final text, step count, and usage. */
+	async generate(
+		prompt: string,
+		signal?: AbortSignal
+	): Promise<GenerateResult> {
+		let text = "";
+		let steps = 0;
+		let usage: ModelUsage | undefined;
+		let authRequired: AgentEventAuthRequired | undefined;
+
+		for await (const event of this.stream(prompt, signal)) {
+			if (event.type === "result") {
+				text = event.text;
+				steps = event.steps;
+				usage = event.usage;
+			} else if (event.type === "auth_required") {
+				authRequired = event;
+			} else if (event.type === "error") {
+				throw new Error(
+					`[ryu-sdk] agent "${this.config.name}": ${event.message}`
+				);
+			}
+		}
+
+		return { text, steps, usage, authRequired };
+	}
+}
+
+/** Factory alias for `new Agent(config)`. */
+export function createAgent(config: AgentConfig): Agent {
+	return new Agent(config);
+}