@ryuhq/sdk 0.1.13 → 0.2.0

package/src/agent-plugin.test.ts

@@ -183,6 +183,64 @@ describe("toAgentPlugin", () => {
 		});
 	});
 
+	test("exports Streamable HTTP, legacy SSE, and inferred remote servers", () => {
+		const { mcp, notes } = toAgentPlugin({
+			id: "@ryu/remote",
+			name: "Remote",
+			mcp_servers: {
+				hosted: {
+					type: "streamable-http",
+					url: "https://mcp.example.com/mcp",
+					headers: { Authorization: "Bearer static" },
+				},
+				legacy: {
+					type: "sse",
+					url: "https://legacy.example.com/sse",
+				},
+				inferred: { url: "https://inferred.example.com/mcp" },
+			},
+		});
+		expect(mcp?.mcpServers.hosted).toEqual({
+			type: "streamable-http",
+			url: "https://mcp.example.com/mcp",
+			headers: { Authorization: "Bearer static" },
+		});
+		expect(mcp?.mcpServers.legacy).toEqual({
+			type: "sse",
+			url: "https://legacy.example.com/sse",
+		});
+		expect(mcp?.mcpServers.inferred).toEqual({
+			type: "streamable-http",
+			url: "https://inferred.example.com/mcp",
+		});
+		expect(notes).toEqual([]);
+	});
+
+	test("omits malformed remote URLs while preserving valid HTTP endpoints", () => {
+		const { mcp, notes } = toAgentPlugin({
+			id: "@ryu/remote",
+			name: "Remote",
+			mcp_servers: {
+				insecure: {
+					type: "streamable-http",
+					url: "http://remote.example.com/mcp",
+				},
+				bad: { type: "streamable-http", url: "file:///tmp/mcp" },
+				local: { type: "sse", url: "http://127.0.0.1:8787/sse" },
+			},
+		});
+		expect(mcp?.mcpServers.insecure).toEqual({
+			type: "streamable-http",
+			url: "http://remote.example.com/mcp",
+		});
+		expect(mcp?.mcpServers.local).toEqual({
+			type: "sse",
+			url: "http://127.0.0.1:8787/sse",
+		});
+		expect(notes).toHaveLength(1);
+		expect(notes[0]).toContain("http or https");
+	});
+
 	test("omits a disabled server but records it", () => {
 		const { plugin, mcp, notes } = toAgentPlugin({
 			id: "@ryu/a",

package/src/agent-plugin.ts

@@ -4,7 +4,9 @@
  * The Agent Plugins Specification (https://agent-plugins.org/, TSC: Amazon,
  * Cursor, Microsoft, OpenAI, Vercel) defines a small portable floor: a plugin is
  * a directory with `plugin.json`, Agent Skills under `skills/<slug>/SKILL.md`,
- * and MCP servers in `mcp.json`. Nothing else is portable.
+ * and MCP servers in `mcp.json`. Native stdio, Streamable HTTP, and legacy SSE
+ * servers all have a direct portable representation; richer Ryu-only fields stay
+ * in the extension namespace or are reported as notes.
  *
  * ## Why this is a SECOND file, not a migration
  *
@@ -88,24 +90,24 @@ export function isAgentPluginManifest(value: unknown): boolean {
 }
 
 /** Author object — the only three fields the spec permits (§5.4). */
-export type AgentPluginAuthor = {
-	name?: string;
+export interface AgentPluginAuthor {
 	email?: string;
+	name?: string;
 	url?: string;
-};
+}
 
 /** Ryu data carried under {@link AGENT_PLUGIN_EXTENSION_NS}. */
-export type RyuExtensionData = {
-	/** The real scoped plugin id (`@ryu/advisor`) — unrecoverable from spec `name`. */
-	id: string;
+export interface RyuExtensionData {
 	/** Human display name; spec `name` is a slug, not a display string. */
 	displayName: string;
+	/** The real scoped plugin id (`@ryu/advisor`) — unrecoverable from spec `name`. */
+	id: string;
 	/** Per-MCP-server fields the spec's closed server variants do not allow. */
 	mcp?: Record<string, RyuMcpServerExtras>;
-};
+}
 
 /** Native MCP fields stripped out of the exported `mcp.json`. */
-export type RyuMcpServerExtras = {
+export interface RyuMcpServerExtras {
 	/** Env var that overrides `command` with an absolute path at spawn. */
 	command_env?: string;
 	/** Human description for our MCP listing endpoint. */
@@ -117,41 +119,51 @@ export type RyuMcpServerExtras = {
 	 * deliberately do not.
 	 */
 	enabled?: false;
-};
+}
 
 /** A conformant `plugin.json` (§5.2). */
-export type AgentPluginJson = {
+export interface AgentPluginJson {
 	$schema: string;
-	name: string;
-	version?: string;
-	description?: string;
 	author?: AgentPluginAuthor;
+	description?: string;
+	extensions: Record<string, unknown>;
 	homepage?: string;
-	repository?: string;
-	license?: string;
 	keywords?: string[];
-	extensions: Record<string, unknown>;
-};
+	license?: string;
+	name: string;
+	repository?: string;
+	version?: string;
+}
 
-/** A stdio server entry (§7.2.1) — the only variant we export. */
-export type AgentPluginStdioServer = {
-	type: "stdio";
-	command: string;
+/** A stdio server entry (§7.2.1). */
+export interface AgentPluginStdioServer {
 	args?: string[];
-	env?: Record<string, string>;
+	command: string;
 	cwd?: string;
-};
+	env?: Record<string, string>;
+	type: "stdio";
+}
+
+/** A remote server entry (§7.2.1). */
+export interface AgentPluginRemoteServer {
+	headers?: Record<string, string>;
+	type: "streamable-http" | "sse";
+	url: string;
+}
+
+/** Any server variant a conformant Agent Plugins client can consume. */
+export type AgentPluginServer =
+	| AgentPluginStdioServer
+	| AgentPluginRemoteServer;
 
 /** A conformant `mcp.json` (§7.2.1). */
-export type AgentPluginMcpJson = {
+export interface AgentPluginMcpJson {
 	$schema: string;
-	mcpServers: Record<string, AgentPluginStdioServer>;
-};
+	mcpServers: Record<string, AgentPluginServer>;
+}
 
 /** What {@link toAgentPlugin} produces, plus what it had to leave behind. */
-export type AgentPluginExport = {
-	/** The `plugin.json` contents. */
-	plugin: AgentPluginJson;
+export interface AgentPluginExport {
 	/** The `mcp.json` contents, or null when the plugin exports no server. */
 	mcp: AgentPluginMcpJson | null;
 	/**
@@ -159,7 +171,9 @@ export type AgentPluginExport = {
 	 * is visible at the call site instead of silent.
 	 */
 	notes: string[];
-};
+	/** The `plugin.json` contents. */
+	plugin: AgentPluginJson;
+}
 
 const SPEC_NAME_MAX = 64;
 const ILLEGAL_NAME_CHARS = /[^a-z0-9.-]+/g;
@@ -258,8 +272,24 @@ function toSpecEnv(value: unknown): Record<string, string> | undefined {
 	return Object.keys(env).length > 0 ? env : undefined;
 }
 
+function validateRemoteUrl(name: string, raw: string): string | undefined {
+	let parsed: URL;
+	try {
+		parsed = new URL(raw);
+	} catch {
+		return `mcp server '${name}' remote url ${JSON.stringify(raw)} is invalid and was omitted`;
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+		return `mcp server '${name}' remote url must use http or https and was omitted`;
+	}
+	if (parsed.username || parsed.password || parsed.hash) {
+		return `mcp server '${name}' remote url must not contain credentials or a fragment and was omitted`;
+	}
+	return undefined;
+}
+
 /**
- * Convert one native MCP server declaration to a spec stdio entry, or return the
+ * Convert one native MCP server declaration to a spec entry, or return the
  * reason it cannot be exported.
  *
  * Strictness is not optional here and differs from the manifest: an unknown field
@@ -270,7 +300,7 @@ function toSpecEnv(value: unknown): Record<string, string> | undefined {
 function toSpecServer(
 	name: string,
 	decl: Record<string, unknown>
-): { server?: AgentPluginStdioServer; extras: RyuMcpServerExtras; note?: string } {
+): { server?: AgentPluginServer; extras: RyuMcpServerExtras; note?: string } {
 	const extras: RyuMcpServerExtras = {};
 	const commandEnv = asString(decl.command_env);
 	const description = asString(decl.description);
@@ -289,6 +319,48 @@ function toSpecServer(
 		};
 	}
 
+	const declaredType = asString(decl.type);
+	const remoteUrl = asString(decl.url);
+	const remoteType =
+		declaredType === "sse"
+			? "sse"
+			: declaredType === "streamable-http" ||
+					declaredType === "streamable_http" ||
+					declaredType === "http" ||
+					(!declaredType && remoteUrl)
+				? "streamable-http"
+				: undefined;
+	if (remoteType) {
+		if (!remoteUrl) {
+			return {
+				extras,
+				note: `mcp server '${name}' has remote type '${remoteType}' but no url and was omitted`,
+			};
+		}
+		const urlNote = validateRemoteUrl(name, remoteUrl);
+		if (urlNote) {
+			return { extras, note: urlNote };
+		}
+		const server: AgentPluginRemoteServer = {
+			type: remoteType,
+			url: remoteUrl,
+		};
+		const headers = toSpecEnv(decl.headers);
+		if (headers) {
+			server.headers = headers;
+		}
+		const note = decl.auth
+			? `mcp server '${name}' uses Ryu OAuth metadata that is not portable; static headers were exported`
+			: undefined;
+		return { server, extras, note };
+	}
+	if (declaredType && declaredType !== "stdio") {
+		return {
+			extras,
+			note: `mcp server '${name}' has unsupported transport '${declaredType}' and was omitted`,
+		};
+	}
+
 	const command = asString(decl.command);
 	if (!command) {
 		return {
@@ -359,7 +431,8 @@ export function toAgentPlugin(
 	}
 	// `tagline` is our one-line pitch; it is the better `description` when no long
 	// description exists, and the spec has no second summary field to put it in.
-	const description = asString(manifest.description) ?? asString(manifest.tagline);
+	const description =
+		asString(manifest.description) ?? asString(manifest.tagline);
 	if (description) {
 		plugin.description = description;
 	}
@@ -385,7 +458,7 @@ export function toAgentPlugin(
 	}
 
 	const declared = manifest.mcp_servers;
-	const servers: Record<string, AgentPluginStdioServer> = {};
+	const servers: Record<string, AgentPluginServer> = {};
 	const mcpExtras: Record<string, RyuMcpServerExtras> = {};
 	if (declared && typeof declared === "object" && !Array.isArray(declared)) {
 		for (const [name, raw] of Object.entries(

package/src/cli/dev.test.ts

@@ -3,57 +3,27 @@
  * sample Runnable, asserting that text, tool-call, and tool-result events
  * stream to stdout correctly.
  *
- * The mock gateway is an in-process HTTP server (Bun.serve) that returns a
- * pre-canned SSE response so the test never needs a real gateway running.
+ * The mock gateway is an in-process request handler so the test never needs a
+ * real gateway or a listening socket.
  */
 
-import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { describe, expect, it } from "bun:test";
 import { unlinkSync, writeFileSync } from "node:fs";
-import { serve } from "bun";
-import type { ChatMessage } from "../model/client.ts";
-import { ModelClient } from "../model/client.ts";
-import type { DevEvent, Runnable } from "./dev.ts";
+import type { ChatMessage, ModelClient } from "../model/client.ts";
+import type { DevEvent, GatewayFetch, Runnable } from "./dev.ts";
 import { loadRunnable, probeGateway, runTurn } from "./dev.ts";
 
 // ── Mock gateway ──────────────────────────────────────────────────────────────
 
-/** Pre-canned SSE body the mock gateway returns for any chat completions POST. */
-const MOCK_SSE_BODY = [
-	'data: {"choices":[{"delta":{"content":"Hello"},"finish_reason":null}]}',
-	'data: {"choices":[{"delta":{"content":", world"},"finish_reason":null}]}',
-	'data: {"choices":[{"delta":{"content":"!"},"finish_reason":"stop"}]}',
-	"data: [DONE]",
-].join("\n");
-
-let mockServer: ReturnType<typeof serve>;
-let mockBaseUrl: string;
-
-beforeAll(() => {
-	mockServer = serve({
-		port: 0, // OS-assigned port
-		fetch(req) {
-			const url = new URL(req.url);
-
-			if (url.pathname === "/health") {
-				return new Response("ok", { status: 200 });
-			}
-
-			if (url.pathname === "/v1/chat/completions") {
-				return new Response(MOCK_SSE_BODY, {
-					status: 200,
-					headers: { "Content-Type": "text/event-stream" },
-				});
-			}
-
-			return new Response("not found", { status: 404 });
-		},
-	});
-	mockBaseUrl = `http://127.0.0.1:${mockServer.port}`;
-});
-
-afterAll(() => {
-	mockServer.stop();
-});
+/** Stable gateway URL used by the injected health request handler. */
+const MOCK_GATEWAY_URL = "http://mock-gateway.test";
+const mockFetch: GatewayFetch = async (input) => {
+	const url = new URL(String(input));
+	if (url.pathname === "/health") {
+		return new Response("ok", { status: 200 });
+	}
+	return new Response("not found", { status: 404 });
+};
 
 // ── Sample Runnable ───────────────────────────────────────────────────────────
 
@@ -98,7 +68,7 @@ const sampleRunnable: Runnable = {
 
 describe("probeGateway", () => {
 	it("returns true when the gateway /health responds", async () => {
-		const reachable = await probeGateway(mockBaseUrl);
+		const reachable = await probeGateway(MOCK_GATEWAY_URL, mockFetch);
 		expect(reachable).toBe(true);
 	});
 
@@ -130,7 +100,16 @@ describe("loadRunnable", () => {
 
 describe("runTurn — full turn streams to stdout", () => {
 	it("collects text + tool events from a full turn", async () => {
-		const model = new ModelClient("test-model", { baseUrl: mockBaseUrl });
+		const model = {
+			async *stream(): AsyncGenerator<{
+				content: string;
+				finishReason: string | null;
+			}> {
+				for (const content of ["Hello", ", world", "!"]) {
+					yield { content, finishReason: null };
+				}
+			},
+		} as unknown as ModelClient;
 
 		const events: DevEvent[] = [];
 
@@ -158,7 +137,7 @@ describe("runTurn — full turn streams to stdout", () => {
 		const toolCallEvents = events.filter((e) => e.type === "tool_call");
 		const toolResultEvents = events.filter((e) => e.type === "tool_result");
 
-		// Three text chunks from the mock SSE body.
+		// Three text chunks from the mock model stream.
 		expect(textEvents).toHaveLength(3);
 		const fullText = textEvents
 			.map((e) => (e as { content: string }).content)

package/src/cli/dev.ts

@@ -93,15 +93,23 @@ export interface Runnable {
 
 // ── Gateway reachability check ────────────────────────────────────────────────
 
+export type GatewayFetch = (
+	input: string | URL | Request,
+	init?: RequestInit
+) => Promise<Response>;
+
 /**
  * Probe the gateway at `baseUrl` with a HEAD request.
  *
  * Returns `true` when any HTTP response is received (even 4xx — the gateway
  * is reachable), `false` when the request fails with a network error.
  */
-export async function probeGateway(baseUrl: string): Promise<boolean> {
+export async function probeGateway(
+	baseUrl: string,
+	fetchImpl: GatewayFetch = fetch
+): Promise<boolean> {
 	try {
-		await fetch(`${baseUrl}/health`, {
+		await fetchImpl(`${baseUrl}/health`, {
 			method: "HEAD",
 			signal: AbortSignal.timeout(3000),
 		});

package/src/cli.ts

@@ -4,7 +4,8 @@
  *
  * Usage:
  *   bunx ryu pack <dir>
- *   bunx ryu publish <dir>
+ *   bunx ryu github-publish <repository-or-package-url>
+ *   bunx ryu publish <dir>  (legacy migration escape hatch)
  *   bunx ryu agent-plugin <dir>
  *
  * Commands:
@@ -12,9 +13,10 @@
  *                   Plugin bundle at <dir>/dist/plugin.bundle.json, plus the
  *                   Agent Plugins interop pair in <dir> itself.
  *                   Exits 0 on success; exits 1 with the failing field on error.
- *   publish <dir>   Validate the manifest.json and POST it to the Ryu Marketplace
- *                   publish endpoint with the author's auth token. The item is
- *                   stored as `pending` until a moderator approves it.
+ *   github-publish <url>
+ *                   Submit a seller-owned GitHub repository/package URL to the
+ *                   GitHub-backed marketplace bridge.
+ *   publish <dir>   Deprecated server-artifact publishing; disabled by default.
  *   agent-plugin <dir>
  *                   Emit only the Agent Plugins v1 interop pair (plugin.json and,
  *                   when servers exist, mcp.json) derived from the manifest.json.
@@ -56,7 +58,9 @@ function printUsage(): void {
 			"",
 			"Usage:",
 			"  bunx ryu pack <dir>      Validate and bundle a manifest.json Plugin",
-			"  bunx ryu publish <dir>   Validate and publish a manifest.json Plugin to the Ryu Marketplace",
+			"  bunx ryu github-publish <url>",
+			"                           Submit a GitHub repository/package URL to the Marketplace",
+			"  bunx ryu publish <dir>   Deprecated server-artifact publishing (migration only)",
 			"  bunx ryu dev <entry>     Run a Runnable locally with an interactive chat loop",
 			"  bunx ryu agent-plugin <dir>",
 			"                           Emit the Agent Plugins v1 interop pair (plugin.json + mcp.json)",
@@ -91,17 +95,21 @@ const MANIFEST_FILE_NAMES = [
 // `manifest.json` — and then fail validation for missing `id`. The `$schema`
 // discriminator separates them (see `isAgentPluginManifest`).
 function resolveNativeManifestPath(dir: string): string | undefined {
-	return MANIFEST_FILE_NAMES.map((name) => join(dir, name)).find((candidate) => {
-		if (!existsSync(candidate)) {
-			return false;
-		}
-		try {
-			return !isAgentPluginManifest(JSON.parse(readFileSync(candidate, "utf8")));
-		} catch {
-			// Unparseable: let the caller surface the JSON error against this path.
-			return true;
+	return MANIFEST_FILE_NAMES.map((name) => join(dir, name)).find(
+		(candidate) => {
+			if (!existsSync(candidate)) {
+				return false;
+			}
+			try {
+				return !isAgentPluginManifest(
+					JSON.parse(readFileSync(candidate, "utf8"))
+				);
+			} catch {
+				// Unparseable: let the caller surface the JSON error against this path.
+				return true;
+			}
 		}
-	});
+	);
 }
 
 // Read + parse + validate the manifest in `dir`. Exits with the failing
@@ -572,8 +580,16 @@ async function commandPublish(rawDir: string): Promise<void> {
 		...(manifest.description ? { description: manifest.description } : {}),
 		...(manifest.tagline ? { tagline: manifest.tagline } : {}),
 		...(developer ? { developer } : {}),
+		...(manifest.author ? { author: manifest.author } : {}),
+		...(manifest.repository ? { repository: manifest.repository } : {}),
+		...(manifest.external ? { external: true } : {}),
 		...(manifest.category ? { category: manifest.category } : {}),
+		...(manifest.license ? { license: manifest.license } : {}),
+		...(manifest.keywords?.length ? { keywords: manifest.keywords } : {}),
 		...(manifest.iconUrl ? { iconUrl: manifest.iconUrl } : {}),
+		...(manifest.icon ? { icon: manifest.icon } : {}),
+		...(manifest.iconDither ? { iconDither: manifest.iconDither } : {}),
+		...(manifest.banner ? { banner: manifest.banner } : {}),
 		...(manifest.screenshots?.length
 			? { screenshots: manifest.screenshots }
 			: {}),
@@ -648,6 +664,58 @@ async function commandPublish(rawDir: string): Promise<void> {
 	);
 }
 
+async function commandGithubPublish(repositoryUrl: string): Promise<void> {
+	const input = repositoryUrl.trim();
+	if (!input) {
+		exitError(
+			"github-publish requires a GitHub repository or package URL, for example https://github.com/acme/my-app"
+		);
+	}
+	const token = authToken();
+	const url = `${publishBaseUrl()}/api/marketplace/github/publish`;
+	const proof = process.env.RYU_GITHUB_INSTALLATION_PROOF?.trim();
+	const body = {
+		url: input,
+		...(proof ? { installationProof: proof } : {}),
+	};
+	let response: Response;
+	try {
+		response = await fetch(url, {
+			method: "POST",
+			headers: {
+				authorization: `Bearer ${token}`,
+				"content-type": "application/json",
+			},
+			body: JSON.stringify(body),
+		});
+	} catch (error) {
+		exitError(`could not reach ${url}: ${String(error)}`);
+	}
+	const text = await response.text();
+	if (!response.ok) {
+		try {
+			const error = JSON.parse(text) as {
+				code?: string;
+				installationUrl?: string;
+				error?: string;
+			};
+			if (error.installationUrl) {
+				exitError(
+					`${error.error ?? "GitHub App installation required"}. Open ${error.installationUrl}, then set RYU_GITHUB_INSTALLATION_PROOF to the callback proof and retry.`
+				);
+			}
+			exitError(
+				`github-publish failed (${response.status}): ${error.error ?? text}`
+			);
+		} catch {
+			exitError(`github-publish failed (${response.status}): ${text}`);
+		}
+	}
+	process.stdout.write(
+		`GitHub-backed listing submitted for moderation:\n${text}\n`
+	);
+}
+
 // ── main ──────────────────────────────────────────────────────────────────────
 
 const [, , command, ...args] = process.argv;
@@ -670,9 +738,24 @@ if (command === "pack") {
 	if (!dir) {
 		exitError("publish requires a directory argument: bunx ryu publish <dir>");
 	}
+	if (process.env.RYU_ENABLE_LEGACY_MARKETPLACE_WRITES !== "true") {
+		exitError(
+			"ryu publish is deprecated because marketplace package contents now live in GitHub Releases; use bunx ryu github-publish <repository-or-package-url>"
+		);
+	}
 	commandPublish(dir).catch((err: unknown) => {
 		exitError(String(err));
 	});
+} else if (command === "github-publish") {
+	const repositoryUrl = args[0];
+	if (!repositoryUrl) {
+		exitError(
+			"github-publish requires a GitHub repository or package URL, for example https://github.com/acme/my-app"
+		);
+	}
+	commandGithubPublish(repositoryUrl).catch((err: unknown) => {
+		exitError(String(err));
+	});
 } else if (command === "agent-plugin") {
 	const dir = args[0];
 	if (!dir) {

package/src/exports-lockstep.test.ts

@@ -0,0 +1,92 @@
+/**
+ * Package exports ↔ tsup entries lockstep guard.
+ *
+ * The SDK's public surface is split across `package.json` `exports` subpaths
+ * (`@ryuhq/sdk/model`, `@ryuhq/sdk/mcp/server`, …) and `tsup.config.ts`
+ * entrypoints that compile each one. They must stay a bijection: a subpath
+ * with no entry never builds, and an entry with no subpath is unreachable.
+ * This is the cheap structural guard that keeps the two from drifting again
+ * (a past drift left docs importing `@ryuhq/sdk/model` / `@ryuhq/sdk/mcp/server`
+ * that resolved to nothing).
+ *
+ * Deterministic, filesystem-only, no network.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import tsupConfig from "../tsup.config.ts";
+
+const PKG_PATH = join(import.meta.dir, "../package.json");
+const pkg = JSON.parse(readFileSync(PKG_PATH, "utf8")) as {
+	exports: Record<
+		string,
+		{ types?: string; import?: string; require?: string }
+	>;
+};
+
+// tsup's `defineConfig` type is the `Options | Options[] | fn` union, which the
+// spread doesn't narrow; the entry map is the one shape this package uses.
+const entryKeys = Object.keys(
+	(tsupConfig as { entry?: Record<string, string> }).entry ?? {}
+);
+const exportKeys = Object.keys(pkg.exports);
+
+describe("package exports ↔ tsup entries lockstep", () => {
+	test("every tsup entry has a matching exports subpath", () => {
+		// `.` in the exports map corresponds to the `index` entry.
+		const expected = entryKeys.map((key) =>
+			key === "index" ? "." : `./${key}`
+		);
+		for (const key of expected) {
+			expect(exportKeys).toContain(key);
+		}
+	});
+
+	test("every exports subpath has a matching tsup entry", () => {
+		const subpaths = exportKeys
+			.filter((key) => key !== ".")
+			.map((key) => key.replace(/^\.\//, ""));
+		for (const key of subpaths) {
+			expect(entryKeys).toContain(key);
+		}
+		expect(entryKeys).toContain("index");
+	});
+
+	test("every subpath the docs/examples import resolves in the exports map", () => {
+		// Each of these is referenced by real consumers (fumadocs cookbooks,
+		// examples/, the desktop host, create-ryu-app) and must never 404.
+		const documented = [
+			"manifest",
+			"agent",
+			"model",
+			"mcp",
+			"mcp/server",
+			"mcp/client",
+			"plugin",
+			"runnable",
+			"builder",
+		];
+		for (const sub of documented) {
+			expect(
+				pkg.exports[`./${sub}`],
+				`@ryuhq/sdk/${sub} must be exported`
+			).toBeTruthy();
+		}
+	});
+
+	test("each subpath points at its own dist files (no collisions)", () => {
+		const distFiles = new Set<string>();
+		for (const entry of Object.values(pkg.exports)) {
+			for (const kind of ["types", "import", "require"] as const) {
+				const path = entry?.[kind];
+				if (path) {
+					expect(distFiles.has(path), `dist file collision: ${path}`).toBe(
+						false
+					);
+					distFiles.add(path);
+				}
+			}
+		}
+	});
+});