@ryuhq/sdk 0.0.5

package/src/plugin/ryu-plugin.ts

@@ -0,0 +1,191 @@
+// The `RyuPlugin` host API — the contract a Ryu plugin's `activate()` receives.
+//
+// This is the SINGLE canonical home for the host API surface. The desktop
+// extension host (proprietary, closed source) IMPLEMENTS this contract; the
+// types ship here in the OSS `@ryuhq/sdk` so plugins stay buildable against a
+// stable, open contract (the open-core invariant: the host is closed, the
+// contract is open). See `docs/desktop-extension-host-spec.md`.
+//
+// Design notes:
+// - Every `register*()` returns a `Disposable` (the VS Code pattern). A plugin
+//   collects them in `context.subscriptions`; `deactivate()` disposes all, so
+//   disable/uninstall is leak-free — no dangling routes/commands/panels.
+// - This file is TYPES + factory shape ONLY. It imports NOTHING (not even React)
+//   and has no runtime side effects, so it is safe in the OSS SDK, when installed
+//   standalone (`@ryuhq/sdk` is published), and in any bundler. The desktop host
+//   provides the concrete `RyuPlugin` instance.
+// - UI contributions are declared DECLARATIVELY here (a route path/title + a
+//   sandboxed-webview `entry`). The OSS contract stays framework-agnostic: it does
+//   NOT carry a React component type. Trusted, in-process React components are a
+//   desktop-HOST concern (the host's own registry owns the `(tab) => ReactNode`
+//   render-fn, see `apps/desktop/src/contributions/registry.ts`), not the public
+//   contract. WHERE plugin UI renders (trusted host registry vs sandboxed child
+//   webview) is the host's decision per the three-tier UI model in the spec.
+
+/** A handle that undoes a registration. Idempotent: calling `dispose()` twice is
+ *  a no-op. */
+export interface Disposable {
+	dispose(): void;
+}
+
+/** Build a {@link Disposable} from a teardown function. */
+export function toDisposable(teardown: () => void): Disposable {
+	let done = false;
+	return {
+		dispose() {
+			if (done) {
+				return;
+			}
+			done = true;
+			teardown();
+		},
+	};
+}
+
+// ── Contribution descriptors ──────────────────────────────────────────────────
+
+/** A tab/route a plugin adds. `path` is matched against `tab.path` (exact match
+ *  unless `pattern` is set). The host loads `webview.entry` in a sandboxed
+ *  surface as the tab body.
+ *
+ *  Note: the OSS contract is declarative + sandboxed-webview only. A trusted,
+ *  in-process React component is a desktop-host capability (the host's registry
+ *  accepts a `(tab) => ReactNode` render-fn for BUILT-INS and first-party bundled
+ *  plugins); it is intentionally absent from this framework-agnostic contract. */
+export interface RouteContribution {
+	/** Exact path (e.g. "/my-plugin") or, with `pattern: true`, a RegExp source
+	 *  string matched against the full path (e.g. "^/my-plugin/[^/]+$"). */
+	path: string;
+	/** Treat `path` as a RegExp source string rather than an exact match. */
+	pattern?: boolean;
+	/** Human title (tab label, command-palette entry). */
+	title: string;
+	/** Load plugin UI in a SANDBOXED webview with NO Tauri IPC; the plugin reaches
+	 *  capabilities only over the host RPC bridge. */
+	webview: { entry: string };
+}
+
+/** A named mount region a panel can target. Generalizes the desktop's existing
+ *  per-section slots (sidebar sections, settings tabs, the chat side-panel, the
+ *  companion overlay) into declared contribution points. */
+export type PanelRegion =
+	| "sidebar-section"
+	| "settings-tab"
+	| "chat-side-panel"
+	| "companion-overlay";
+
+export interface PanelContribution {
+	/** Stable id within the region (also the host's key). */
+	id: string;
+	region: PanelRegion;
+	title: string;
+	webview: { entry: string };
+}
+
+/** A command-palette entry. Shaped to map 1:1 onto the desktop's
+ *  `CommandAction` (from `@ryu/command/types`) so a contributed command lands in
+ *  the same palette as built-ins with no shim. */
+export interface CommandContribution {
+	/** Group heading in the palette. Defaults to the plugin's display name. */
+	group?: string;
+	id: string;
+	/** Extra fuzzy-search terms. */
+	keywords?: string;
+	/** The side effect. Runs in the host; for sandboxed plugins it is an RPC. */
+	run(): void | Promise<void>;
+	/** Right-aligned keyboard hint (e.g. "⌘⇧P"). */
+	shortcut?: string;
+	title: string;
+}
+
+export interface SettingsSectionContribution {
+	id: string;
+	title: string;
+	webview: { entry: string };
+}
+
+/** A section in the unified Store/marketplace surface. */
+export interface StoreSectionContribution {
+	id: string;
+	title: string;
+	webview: { entry: string };
+}
+
+/** A theme a plugin contributes (CSS custom-property overrides keyed by token). */
+export interface ThemeContribution {
+	id: string;
+	name: string;
+	tokens: Record<string, string>;
+}
+
+// ── Host services (proxied to Core over the host RPC) ─────────────────────────
+
+/** The host-service surface a plugin calls back into. Each method is mediated by
+ *  the host and grant-gated by the manifest (#443). For a sandboxed plugin these
+ *  are RPCs over the postMessage bridge; the plugin never holds a Core token or
+ *  Tauri IPC handle directly. */
+export interface RyuHostServices {
+	/** Run a registered command by id (built-in or contributed). */
+	commands: { execute(id: string, ...args: unknown[]): Promise<unknown> };
+	/** Gateway-governed model access (chat/embed). Mirrors `@ryuhq/sdk` model
+	 *  client semantics; every call still routes through the Gateway. */
+	gateway: {
+		chat(
+			model: string,
+			messages: { role: string; content: string }[]
+		): Promise<string>;
+	};
+	/** List the agents on the active node, PROJECTED to `{id,name}` only. The host
+	 *  holds the Core token and performs the fetch; the plugin never sees a token
+	 *  or any other agent field (invariant: no capability returns a secret). Gated
+	 *  by the `core:list_agents` grant. */
+	listAgents(): Promise<{ id: string; name: string }[]>;
+	/** Open a tab at a path (built-in or a route this plugin contributed). */
+	openTab(path: string): void;
+	/** Read/write the plugin's own Spaces docs (scoped by grant). */
+	spaces: {
+		ingestDocument(
+			spaceId: string,
+			title: string,
+			markdown: string
+		): Promise<{ docId: string }>;
+	};
+}
+
+// ── The host API a plugin's activate() receives ───────────────────────────────
+
+/** Everything a plugin can contribute. Each `register*` returns a
+ *  {@link Disposable}; collect them in {@link PluginContext.subscriptions}. */
+export interface RyuPlugin {
+	/** Host services the plugin calls back into (grant-gated). */
+	readonly host: RyuHostServices;
+	registerCommand(contribution: CommandContribution): Disposable;
+	registerPanel(contribution: PanelContribution): Disposable;
+	registerRoute(contribution: RouteContribution): Disposable;
+	registerSettingsSection(
+		contribution: SettingsSectionContribution
+	): Disposable;
+	registerStoreSection(contribution: StoreSectionContribution): Disposable;
+	registerTheme(contribution: ThemeContribution): Disposable;
+}
+
+/** Passed to `activate(context)`. The plugin pushes its disposables onto
+ *  `subscriptions`; the host disposes them all on `deactivate`. */
+export interface PluginContext {
+	readonly plugin: RyuPlugin;
+	/** The plugin's own id (from `plugin.json`). */
+	readonly pluginId: string;
+	/** Disposables auto-cleaned on deactivate. */
+	readonly subscriptions: Disposable[];
+}
+
+/** The shape the host expects a plugin's entry module to export. */
+export interface RyuPluginModule {
+	activate(context: PluginContext): void | Promise<void>;
+	deactivate?(): void | Promise<void>;
+}
+
+/** Identity helper for authoring a typed plugin module (no runtime behavior). */
+export function definePlugin(plugin: RyuPluginModule): RyuPluginModule {
+	return plugin;
+}

package/src/runnable/agent.ts

@@ -0,0 +1,338 @@
+/**
+ * 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).
+ */
+
+import type {
+	CapabilityReq,
+	PluginManifest,
+	RunnableMeta,
+} from "../manifest.ts";
+import { PluginManifestSchema } from "../manifest.ts";
+import type { Runnable, RunnableContext } from "./runnable-types.ts";
+
+/**
+ * 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.
+ */
+export 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.
+ */
+export 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. */
+export 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`. */
+export 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.
+ */
+export 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. */
+export 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}. */
+export 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;
+}
+
+const CAPABILITY_SLOTS = ["rag", "memory", "tts", "stt"] as const;
+
+/** Normalize a chat slot to the card's model fields. */
+function lowerChatSlot(
+	chat: ChatSlot | undefined
+): Pick<AgentCard, "model" | "engine" | "persona" | "modelPrefKey"> {
+	if (chat === undefined) {
+		return {};
+	}
+	if (typeof chat === "string") {
+		return { model: chat };
+	}
+	return {
+		model: chat.model,
+		engine: chat.engine,
+		persona: chat.persona,
+		modelPrefKey: chat.modelPrefKey,
+	};
+}
+
+/** Lower one capability slot to an edge + optional provider override. */
+function lowerCapabilitySlot(
+	capability: string,
+	slot: CapabilitySlot | undefined,
+	card: AgentCard
+): void {
+	if (slot === undefined || slot === false) {
+		return;
+	}
+	if (slot === true) {
+		card.capabilities.push({ capability });
+		return;
+	}
+	if (typeof slot === "string") {
+		card.capabilities.push({ capability });
+		card.providers[capability] = slot;
+		return;
+	}
+	card.capabilities.push(
+		slot.minVersion
+			? { capability, min_version: slot.minVersion }
+			: { capability }
+	);
+	if (slot.provider) {
+		card.providers[capability] = slot.provider;
+	}
+}
+
+/** Build the lowered {@link AgentCard} from an agent's slots. */
+function lowerSlots(options: AgentSlots): AgentCard {
+	const card: AgentCard = {
+		...lowerChatSlot(options.chat),
+		capabilities: [],
+		providers: {},
+		tools: [],
+	};
+	for (const capability of CAPABILITY_SLOTS) {
+		lowerCapabilitySlot(capability, options[capability], card);
+	}
+	for (const t of options.tools ?? []) {
+		card.tools.push(typeof t === "string" ? t : t.id);
+	}
+	return card;
+}
+
+/** Synthesize a default run that drives the `chat` slot through `ctx.gateway`. */
+function defaultRun(card: AgentCard) {
+	return async (input: unknown, ctx: RunnableContext): Promise<string> => {
+		const content =
+			typeof input === "string" ? input : JSON.stringify(input ?? "");
+		const messages = card.persona
+			? [
+					{ role: "system" as const, content: card.persona },
+					{ role: "user" as const, content },
+				]
+			: [{ role: "user" as const, content }];
+		const result = await ctx.gateway.chat(messages);
+		return result.content;
+	};
+}
+
+/** The manifest `config` block a card lowers to (kept opaque by Core). */
+function cardConfig(card: AgentCard): Record<string, unknown> {
+	const config: Record<string, unknown> = {};
+	if (card.model) {
+		config.model = card.model;
+	}
+	if (card.engine) {
+		config.engine = card.engine;
+	}
+	if (card.persona) {
+		config.persona = card.persona;
+	}
+	if (card.modelPrefKey) {
+		config.model_pref_key = card.modelPrefKey;
+	}
+	if (Object.keys(card.providers).length > 0) {
+		config.capability_providers = card.providers;
+	}
+	if (card.tools.length > 0) {
+		config.tools = card.tools;
+	}
+	return config;
+}
+
+/** Lower an agent to a single-agent `plugin.json` `PluginManifest`. */
+function agentToManifest(
+	agent: Runnable & { card: AgentCard },
+	options: AgentManifestOptions
+): PluginManifest {
+	const config = cardConfig(agent.card);
+	const meta: RunnableMeta = {
+		id: agent.id,
+		name: agent.name,
+		kind: "agent",
+		...(Object.keys(config).length > 0 ? { config } : {}),
+	};
+	const hasRequires =
+		agent.card.capabilities.length > 0 || (options.grants?.length ?? 0) > 0;
+	const raw = {
+		id: options.id,
+		name: options.name ?? agent.name,
+		version: options.version,
+		runnables: [meta],
+		...(hasRequires
+			? {
+					requires: {
+						apps: [],
+						capabilities: agent.card.capabilities,
+						grants: options.grants ?? [],
+					},
+				}
+			: {}),
+	};
+	const result = PluginManifestSchema.safeParse(raw);
+	if (!result.success) {
+		const first = result.error.issues[0];
+		const field = first?.path.join(".") ?? "unknown";
+		const message = first?.message ?? "validation failed";
+		throw new Error(
+			`agent manifest validation failed at '${field}': ${message}`
+		);
+	}
+	return result.data;
+}
+
+/**
+ * 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" });
+ * ```
+ */
+export function defineAgent<TInput = unknown, TOutput = unknown>(
+	options: AgentOptions<TInput, TOutput>
+): AgentRunnable<TInput, TOutput> {
+	const { id, name } = options;
+	const card = lowerSlots(options);
+	const run = (options.run ?? defaultRun(card)) as Runnable<
+		TInput,
+		TOutput
+	>["run"];
+
+	return {
+		id,
+		name,
+		kind: "agent",
+		run,
+		card,
+		toManifest(manifestOptions: AgentManifestOptions): PluginManifest {
+			return agentToManifest(this, manifestOptions);
+		},
+	};
+}