@ryuhq/sdk 0.1.4 → 0.1.6

package/src/agent-plugin.test.ts

@@ -0,0 +1,222 @@
+// Tests for the Agent Plugins v1.0.0 export projection. The spec is unusually
+// strict about two things and both are asserted here because getting either wrong
+// produces a file that a conformant client REJECTS rather than degrades on:
+//
+//  1. `plugin.json`'s schema is closed (§5.2) — exporting a stray top-level field
+//     is at best reported-and-ignored, and the field set is fixed.
+//  2. An unknown field inside an `mcp.json` server entry invalidates THAT ENTRY
+//     (§7.2.2 rule 3), so the server export must be an allowlist, not a passthrough.
+
+import { describe, expect, test } from "bun:test";
+import {
+	AGENT_PLUGIN_EXTENSION_NS,
+	AGENT_PLUGIN_MCP_SCHEMA_URL,
+	AGENT_PLUGIN_SCHEMA_URL,
+	toAgentPlugin,
+	toSpecName,
+} from "./agent-plugin.ts";
+
+/** The exact top-level field set §5.2 permits. */
+const PERMITTED_TOP_LEVEL = new Set([
+	"$schema",
+	"name",
+	"version",
+	"description",
+	"author",
+	"homepage",
+	"repository",
+	"license",
+	"keywords",
+	"extensions",
+]);
+
+/** Fields §7.2.1 permits on a stdio server entry. */
+const PERMITTED_STDIO = new Set(["type", "command", "args", "env", "cwd"]);
+
+/** §5.5 name constraints, expressed as one predicate. */
+function isSpecLegalName(name: string): boolean {
+	return (
+		name.length >= 1 &&
+		name.length <= 64 &&
+		/^[a-z0-9][a-z0-9.-]*$/.test(name) &&
+		/[a-z0-9]$/.test(name) &&
+		!name.includes("--") &&
+		!name.includes("..")
+	);
+}
+
+describe("toSpecName", () => {
+	test("projects a scoped id onto a legal dotted name", () => {
+		expect(toSpecName("@ryu/advisor")).toBe("ryu.advisor");
+		expect(toSpecName("@example/research-assistant")).toBe(
+			"example.research-assistant"
+		);
+	});
+
+	test("output is spec-legal for every shape our ids take", () => {
+		const ids = [
+			"@ryu/advisor",
+			"@ryu/hook-session-context",
+			"@ryu/sample-widget",
+			"com.ryu.browser",
+			"@Scope/UPPER_Case",
+			"@ryu/weird--id..here",
+			"@ryu/-leading-and-trailing-",
+			`@ryu/${"x".repeat(120)}`,
+		];
+		for (const id of ids) {
+			expect(isSpecLegalName(toSpecName(id))).toBe(true);
+		}
+	});
+
+	test("clamping to 64 chars cannot leave a trailing separator", () => {
+		// 63 chars then a hyphen at position 64: the naive slice would end on '-'.
+		const id = `@ryu/${"a".repeat(58)}-tail`;
+		const name = toSpecName(id);
+		expect(name.length).toBeLessThanOrEqual(64);
+		expect(isSpecLegalName(name)).toBe(true);
+	});
+
+	test("throws when nothing legal survives", () => {
+		expect(() => toSpecName("@/")).toThrow();
+	});
+});
+
+describe("toAgentPlugin", () => {
+	test("emits only permitted top-level fields", () => {
+		const { plugin } = toAgentPlugin({
+			id: "@ryu/advisor",
+			name: "Advisor",
+			version: "1.0.0",
+			description: "Consult a stronger reviewer model.",
+			category: "Research",
+			icon: "bulb",
+			iconDither: { from: 261, to: 295 },
+			surfaces: { core: { support: "full" } },
+			engines: { ryu: ">=0.1.0" },
+			runnables: [{ id: "t", name: "T", kind: "tool" }],
+			permission_grants: ["hook:side-model"],
+			contributes: { slash_commands: [] },
+		});
+		for (const key of Object.keys(plugin)) {
+			expect(PERMITTED_TOP_LEVEL.has(key)).toBe(true);
+		}
+		expect(plugin.$schema).toBe(AGENT_PLUGIN_SCHEMA_URL);
+		expect(plugin.name).toBe("ryu.advisor");
+	});
+
+	test("carries the real id and display name in the extension namespace", () => {
+		const { plugin } = toAgentPlugin({
+			id: "@ryu/advisor",
+			name: "Advisor",
+			version: "1.0.0",
+		});
+		expect(plugin.extensions[AGENT_PLUGIN_EXTENSION_NS]).toMatchObject({
+			id: "@ryu/advisor",
+			displayName: "Advisor",
+		});
+	});
+
+	test("falls back to the tagline when there is no description", () => {
+		const { plugin } = toAgentPlugin({
+			id: "@ryu/advisor",
+			name: "Advisor",
+			tagline: "A stronger second model reviews your answers",
+		});
+		expect(plugin.description).toBe(
+			"A stronger second model reviews your answers"
+		);
+	});
+
+	test("normalizes a bare-string author into the spec object form", () => {
+		const { plugin } = toAgentPlugin({
+			id: "@ryu/a",
+			name: "A",
+			author: "Ryu",
+		});
+		expect(plugin.author).toEqual({ name: "Ryu" });
+	});
+
+	test("drops author fields the spec does not permit", () => {
+		// An extra member on `author` makes the WHOLE manifest invalid (§5.4), so
+		// this must be a drop, not a passthrough.
+		const { plugin } = toAgentPlugin({
+			id: "@ryu/a",
+			name: "A",
+			author: { name: "Ryu", url: "https://example.com", twitter: "@ryu" },
+		});
+		expect(plugin.author).toEqual({ name: "Ryu", url: "https://example.com" });
+	});
+
+	test("no mcp.json when the manifest declares no servers", () => {
+		const { mcp } = toAgentPlugin({ id: "@ryu/a", name: "A" });
+		expect(mcp).toBeNull();
+	});
+
+	test("exports a stdio server with only the permitted fields", () => {
+		const { plugin, mcp } = toAgentPlugin({
+			id: "@ryu/ghost",
+			name: "Ghost",
+			mcp_servers: {
+				ghost: {
+					command: "ghost",
+					command_env: "RYU_GHOST_BIN",
+					args: ["mcp"],
+					description: "Ghost — desktop automation.",
+				},
+			},
+		});
+		expect(mcp?.$schema).toBe(AGENT_PLUGIN_MCP_SCHEMA_URL);
+		const server = mcp?.mcpServers.ghost;
+		expect(server).toEqual({ type: "stdio", command: "ghost", args: ["mcp"] });
+		for (const key of Object.keys(server ?? {})) {
+			expect(PERMITTED_STDIO.has(key)).toBe(true);
+		}
+		// The stripped native fields survive in the extension namespace.
+		expect(plugin.extensions[AGENT_PLUGIN_EXTENSION_NS]).toMatchObject({
+			mcp: {
+				ghost: {
+					command_env: "RYU_GHOST_BIN",
+					description: "Ghost — desktop automation.",
+				},
+			},
+		});
+	});
+
+	test("omits a disabled server but records it", () => {
+		const { plugin, mcp, notes } = toAgentPlugin({
+			id: "@ryu/a",
+			name: "A",
+			mcp_servers: {
+				off: { command: "x", enabled: false },
+				on: { command: "y" },
+			},
+		});
+		expect(mcp?.mcpServers.off).toBeUndefined();
+		expect(mcp?.mcpServers.on).toBeDefined();
+		expect(plugin.extensions[AGENT_PLUGIN_EXTENSION_NS]).toMatchObject({
+			mcp: { off: { enabled: false } },
+		});
+		expect(notes.some((n) => n.includes("off"))).toBe(true);
+	});
+
+	test("omits a command the spec cannot express, with a note", () => {
+		const { mcp, notes } = toAgentPlugin({
+			id: "@ryu/a",
+			name: "A",
+			mcp_servers: {
+				shellish: { command: "node server.mjs" },
+				absolute: { command: "/usr/local/bin/thing" },
+				fine: { command: "npx", args: ["-y", "pkg"] },
+			},
+		});
+		expect(mcp?.mcpServers.shellish).toBeUndefined();
+		expect(mcp?.mcpServers.absolute).toBeUndefined();
+		expect(mcp?.mcpServers.fine).toBeDefined();
+		expect(notes).toHaveLength(2);
+	});
+
+	test("throws on a manifest with no id", () => {
+		expect(() => toAgentPlugin({ name: "No id" })).toThrow("no id");
+	});
+});

package/src/agent-plugin.ts

@@ -0,0 +1,424 @@
+/**
+ * Agent Plugins v1.0.0 export — the interop face of a Ryu `manifest.json`.
+ *
+ * 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.
+ *
+ * ## Why this is a SECOND file, not a migration
+ *
+ * The spec manifest schema is **closed** (§5.2): the only permitted top-level
+ * fields are `$schema`, `name`, `version`, `description`, `author`, `homepage`,
+ * `repository`, `license`, `keywords`, and `extensions`. Every field that makes a
+ * Ryu manifest a Ryu manifest — `id`, `runnables`, `contributes`, `surfaces`,
+ * `engines`, `permission_grants`, `mcp_servers`, `companion`, `ui_code_sha256` —
+ * is an unknown field there. So `manifest.json` can never *be* a conformant
+ * `plugin.json`; it can only be projected into one.
+ *
+ * `manifest.json` therefore stays the single source of truth and this module
+ * DERIVES the interop pair (`plugin.json` + `mcp.json`) from it. Nothing is
+ * hand-maintained, so the pair cannot desync — the same reason the packaged
+ * manifests are compiled in from their package home instead of copied (AGENTS.md).
+ *
+ * For the same reason `extensions` carries only what cannot be re-derived by a
+ * reader of the spec files: the real scoped id, the display name, and the
+ * per-server MCP fields the spec's closed server variants forced us to strip. It
+ * is deliberately NOT a copy of the whole native manifest — that would be a second
+ * source of truth with a stale-copy failure mode.
+ *
+ * Both `plugins-store/*` and `apps-store/*` use this one `PluginManifest` shape, so
+ * one converter covers both stores.
+ */
+
+/** Agent Plugins spec version this module targets. */
+export const AGENT_PLUGINS_SPEC_VERSION = "1.0.0";
+
+/**
+ * Canonical manifest schema identifier (§5.2). MUST be this exact string — a
+ * client selects its validation rules from the value and MUST NOT fetch it.
+ */
+export const AGENT_PLUGIN_SCHEMA_URL =
+	"https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
+
+/** Canonical `mcp.json` schema identifier (§7.2.1). */
+export const AGENT_PLUGIN_MCP_SCHEMA_URL =
+	"https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
+
+/**
+ * Our reverse-domain client extension namespace (§8) — the key in `extensions`
+ * AND, when a plugin ships Ryu-only files, the top-level directory name.
+ *
+ * The spec asks for a domain the client controls, kept stable indefinitely, so
+ * this is a one-way door: changing it later orphans every published plugin's Ryu
+ * data. Derived from the `@ryuhq` npm scope / `ryuhq.com`.
+ */
+export const AGENT_PLUGIN_EXTENSION_NS = "com.ryuhq.ryu";
+
+/** Spec file name for the manifest (§5.1). */
+export const AGENT_PLUGIN_MANIFEST_FILE = "plugin.json";
+
+/** Spec file name for the MCP configuration (§7.2.1). */
+export const AGENT_PLUGIN_MCP_FILE = "mcp.json";
+
+/**
+ * Whether a parsed JSON value is an Agent Plugins spec manifest rather than a
+ * native Ryu one.
+ *
+ * This predicate is load-bearing, not cosmetic. `plugin.json` is BOTH the spec's
+ * manifest name and a legacy alias for our own `manifest.json` (Core's
+ * `MANIFEST_FILE_NAMES` and the CLI's copy of it both still accept it). Once a
+ * plugin directory carries an exported spec `plugin.json`, any resolver that
+ * blindly takes the first matching name can pick the wrong file and reject the
+ * plugin for having no `id`/`runnables`.
+ *
+ * The discriminator is unambiguous: a spec manifest MUST carry `$schema` with the
+ * canonical agent-plugins.org identifier (§5.2), and no native manifest has ever
+ * had that field.
+ */
+export function isAgentPluginManifest(value: unknown): boolean {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		return false;
+	}
+	const schema = (value as Record<string, unknown>).$schema;
+	return (
+		typeof schema === "string" &&
+		schema.startsWith("https://agent-plugins.org/schemas/")
+	);
+}
+
+/** Author object — the only three fields the spec permits (§5.4). */
+export type AgentPluginAuthor = {
+	name?: string;
+	email?: 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;
+	/** Human display name; spec `name` is a slug, not a display string. */
+	displayName: 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 = {
+	/** Env var that overrides `command` with an absolute path at spawn. */
+	command_env?: string;
+	/** Human description for our MCP listing endpoint. */
+	description?: string;
+	/**
+	 * Present and `false` when the native manifest disables the server. Such a
+	 * server is OMITTED from `mcp.json` entirely — the spec has no `enabled` flag,
+	 * so emitting the entry would make a foreign client spawn something we
+	 * deliberately do not.
+	 */
+	enabled?: false;
+};
+
+/** A conformant `plugin.json` (§5.2). */
+export type AgentPluginJson = {
+	$schema: string;
+	name: string;
+	version?: string;
+	description?: string;
+	author?: AgentPluginAuthor;
+	homepage?: string;
+	repository?: string;
+	license?: string;
+	keywords?: string[];
+	extensions: Record<string, unknown>;
+};
+
+/** A stdio server entry (§7.2.1) — the only variant we export. */
+export type AgentPluginStdioServer = {
+	type: "stdio";
+	command: string;
+	args?: string[];
+	env?: Record<string, string>;
+	cwd?: string;
+};
+
+/** A conformant `mcp.json` (§7.2.1). */
+export type AgentPluginMcpJson = {
+	$schema: string;
+	mcpServers: Record<string, AgentPluginStdioServer>;
+};
+
+/** What {@link toAgentPlugin} produces, plus what it had to leave behind. */
+export type AgentPluginExport = {
+	/** The `plugin.json` contents. */
+	plugin: AgentPluginJson;
+	/** The `mcp.json` contents, or null when the plugin exports no server. */
+	mcp: AgentPluginMcpJson | null;
+	/**
+	 * Human-readable notes about anything dropped or rewritten, so a lossy export
+	 * is visible at the call site instead of silent.
+	 */
+	notes: string[];
+};
+
+const SPEC_NAME_MAX = 64;
+const ILLEGAL_NAME_CHARS = /[^a-z0-9.-]+/g;
+const REPEATED_HYPHENS = /-{2,}/g;
+const REPEATED_DOTS = /\.{2,}/g;
+const LEADING_NON_ALNUM = /^[^a-z0-9]+/;
+const TRAILING_NON_ALNUM = /[^a-z0-9]+$/;
+/** A spec `command` must be ONE executable token (§7.2.1), so no whitespace. */
+const WHITESPACE = /\s/;
+
+/**
+ * Project a Ryu plugin id onto a spec-legal `name` (§5.5): 1–64 chars of
+ * `a-z 0-9 - .`, alphanumeric at both ends, no `--` and no `..`.
+ *
+ * Our ids are all `@scope/name`, which is illegal there (`@` and `/`), so
+ * `@ryu/advisor` becomes `ryu.advisor`. Periods ARE legal, which is what makes the
+ * mapping readable rather than a hash. The mapping is lossy by construction (two
+ * ids could collide after normalization), so the true id always rides in
+ * `extensions` and this value is never treated as an identity on our side.
+ */
+export function toSpecName(id: string): string {
+	const normalized = id
+		.trim()
+		.toLowerCase()
+		.replace(/^@/, "")
+		.replace(/[/_]/g, ".")
+		.replace(ILLEGAL_NAME_CHARS, "-")
+		.replace(REPEATED_HYPHENS, "-")
+		.replace(REPEATED_DOTS, ".")
+		.replace(LEADING_NON_ALNUM, "")
+		.replace(TRAILING_NON_ALNUM, "")
+		.slice(0, SPEC_NAME_MAX)
+		// A slice can re-expose a trailing separator; trim again after clamping.
+		.replace(TRAILING_NON_ALNUM, "");
+	if (!normalized) {
+		throw new Error(
+			`plugin id ${JSON.stringify(id)} has no spec-legal name projection`
+		);
+	}
+	return normalized;
+}
+
+function asString(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+function asStringArray(value: unknown): string[] | undefined {
+	if (!Array.isArray(value)) {
+		return;
+	}
+	const strings = value.filter((v): v is string => typeof v === "string");
+	return strings.length > 0 ? strings : undefined;
+}
+
+/**
+ * Normalize our `author` (a bare string OR a Claude-style object) into the spec's
+ * object form. The spec permits ONLY `name`, `email`, and `url` — any other member
+ * makes the whole manifest invalid, so extra keys are dropped rather than passed
+ * through.
+ */
+function toSpecAuthor(value: unknown): AgentPluginAuthor | undefined {
+	const bare = asString(value);
+	if (bare) {
+		return { name: bare };
+	}
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		return;
+	}
+	const source = value as Record<string, unknown>;
+	const author: AgentPluginAuthor = {};
+	const name = asString(source.name);
+	const email = asString(source.email);
+	const url = asString(source.url);
+	if (name) {
+		author.name = name;
+	}
+	if (email) {
+		author.email = email;
+	}
+	if (url) {
+		author.url = url;
+	}
+	return Object.keys(author).length > 0 ? author : undefined;
+}
+
+function toSpecEnv(value: unknown): Record<string, string> | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		return;
+	}
+	const env: Record<string, string> = {};
+	for (const [key, raw] of Object.entries(value as Record<string, unknown>)) {
+		if (typeof raw === "string") {
+			env[key] = raw;
+		}
+	}
+	return Object.keys(env).length > 0 ? env : undefined;
+}
+
+/**
+ * Convert one native MCP server declaration to a spec stdio entry, or return the
+ * reason it cannot be exported.
+ *
+ * Strictness is not optional here and differs from the manifest: an unknown field
+ * in a server entry makes THAT ENTRY invalid (§7.2.2 rule 3), where an unknown
+ * top-level manifest field is merely reported and ignored. So the export is an
+ * allowlist — `command`, `args`, `env` — and everything else moves to `extensions`.
+ */
+function toSpecServer(
+	name: string,
+	decl: Record<string, unknown>
+): { server?: AgentPluginStdioServer; extras: RyuMcpServerExtras; note?: string } {
+	const extras: RyuMcpServerExtras = {};
+	const commandEnv = asString(decl.command_env);
+	const description = asString(decl.description);
+	if (commandEnv) {
+		extras.command_env = commandEnv;
+	}
+	if (description) {
+		extras.description = description;
+	}
+
+	if (decl.enabled === false) {
+		extras.enabled = false;
+		return {
+			extras,
+			note: `mcp server '${name}' is disabled in the native manifest and was omitted from ${AGENT_PLUGIN_MCP_FILE}`,
+		};
+	}
+
+	const command = asString(decl.command);
+	if (!command) {
+		return {
+			extras,
+			note: `mcp server '${name}' has no command and was omitted`,
+		};
+	}
+	// §7.2.1: `command` is a bare executable name or a `./`-relative path — never a
+	// shell string and never absolute. Ours are all bare names today; a violation is
+	// reported rather than exported as an entry a conformant client would reject.
+	if (WHITESPACE.test(command)) {
+		return {
+			extras,
+			note: `mcp server '${name}' command ${JSON.stringify(command)} is not a single executable token and was omitted`,
+		};
+	}
+	if (command.startsWith("/") || command.startsWith("~")) {
+		return {
+			extras,
+			note: `mcp server '${name}' command ${JSON.stringify(command)} is an absolute path (spec allows a bare name or './' relative path) and was omitted`,
+		};
+	}
+
+	const server: AgentPluginStdioServer = { type: "stdio", command };
+	const args = asStringArray(decl.args);
+	if (args) {
+		server.args = args;
+	}
+	const env = toSpecEnv(decl.env);
+	if (env) {
+		server.env = env;
+	}
+	return { server, extras };
+}
+
+/**
+ * Project a Ryu `manifest.json` onto the Agent Plugins interop pair.
+ *
+ * Takes the RAW parsed manifest (not the SDK's narrower zod type) because the
+ * fields that matter for export — notably `mcp_servers` — live in Core's richer
+ * model. Throws only when the id cannot be projected onto a spec-legal name;
+ * every other lossy step is reported through {@link AgentPluginExport.notes}.
+ */
+export function toAgentPlugin(
+	manifest: Record<string, unknown>
+): AgentPluginExport {
+	const id = asString(manifest.id);
+	if (!id) {
+		throw new Error("manifest has no id");
+	}
+	const notes: string[] = [];
+
+	const ryu: RyuExtensionData = {
+		id,
+		displayName: asString(manifest.name) ?? id,
+	};
+
+	// Built in the spec's own field order (§5.2) so the emitted file reads like the
+	// spec's examples; `extensions` is attached last for the same reason.
+	const plugin = {
+		$schema: AGENT_PLUGIN_SCHEMA_URL,
+		name: toSpecName(id),
+	} as AgentPluginJson;
+
+	const version = asString(manifest.version);
+	if (version) {
+		plugin.version = version;
+	}
+	// `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);
+	if (description) {
+		plugin.description = description;
+	}
+	const author = toSpecAuthor(manifest.author);
+	if (author) {
+		plugin.author = author;
+	}
+	const homepage = asString(manifest.homepage);
+	if (homepage) {
+		plugin.homepage = homepage;
+	}
+	const repository = asString(manifest.repository);
+	if (repository) {
+		plugin.repository = repository;
+	}
+	const license = asString(manifest.license);
+	if (license) {
+		plugin.license = license;
+	}
+	const keywords = asStringArray(manifest.keywords);
+	if (keywords) {
+		plugin.keywords = keywords;
+	}
+
+	const declared = manifest.mcp_servers;
+	const servers: Record<string, AgentPluginStdioServer> = {};
+	const mcpExtras: Record<string, RyuMcpServerExtras> = {};
+	if (declared && typeof declared === "object" && !Array.isArray(declared)) {
+		for (const [name, raw] of Object.entries(
+			declared as Record<string, unknown>
+		)) {
+			if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+				notes.push(`mcp server '${name}' is not an object and was omitted`);
+				continue;
+			}
+			const { server, extras, note } = toSpecServer(
+				name,
+				raw as Record<string, unknown>
+			);
+			if (Object.keys(extras).length > 0) {
+				mcpExtras[name] = extras;
+			}
+			if (note) {
+				notes.push(note);
+			}
+			if (server) {
+				servers[name] = server;
+			}
+		}
+	}
+	if (Object.keys(mcpExtras).length > 0) {
+		ryu.mcp = mcpExtras;
+	}
+	plugin.extensions = { [AGENT_PLUGIN_EXTENSION_NS]: ryu };
+
+	const mcp =
+		Object.keys(servers).length > 0
+			? { $schema: AGENT_PLUGIN_MCP_SCHEMA_URL, mcpServers: servers }
+			: null;
+
+	return { plugin, mcp, notes };
+}