@ryuhq/sdk 0.0.5

package/src/runnable/tool.ts

@@ -0,0 +1,260 @@
+/**
+ * defineTool — factory for Runnable tools.
+ *
+ * A tool is a stateless function invoked by an agent or workflow step.
+ * It accepts a typed schema (Zod-style field definitions) that is converted
+ * to a JSON Schema object compatible with Core's `ToolInfo.schema` shape
+ * (apps/core/src/sidecar/adapters/mod.rs:66-71).
+ *
+ * Input is validated against the schema at run() time; invalid input throws
+ * a descriptive Error before the tool body executes.
+ *
+ * Tools do NOT require model calls and therefore do not need `ctx.gateway`
+ * to be present, but the context is still injected so tools can optionally
+ * call gateway.chat() when they need model assistance.
+ */
+
+import type { RunnableMeta } from "../manifest.ts";
+import type { Runnable, RunnableContext } from "./runnable-types.ts";
+
+// ── JSON Schema types ─────────────────────────────────────────────────────────
+
+/**
+ * A single JSON Schema property descriptor — the subset required by Core's
+ * `ToolInfo.schema` field and the OpenAI function-calling format.
+ */
+export interface JsonSchemaProperty {
+	/** Human-readable description surfaced to the model. */
+	description?: string;
+	/** Allowed enum values. */
+	enum?: unknown[];
+	/** Array item schema (required when type is "array"). */
+	items?: JsonSchemaProperty;
+	/** Nested object properties (used when type is "object"). */
+	properties?: Record<string, JsonSchemaProperty>;
+	/** Required keys list (used when type is "object"). */
+	required?: string[];
+	/** JSON Schema type string. */
+	type: "string" | "number" | "integer" | "boolean" | "array" | "object";
+}
+
+/**
+ * Zod-style schema descriptor for a tool's input.
+ *
+ * Keys are field names; values describe their JSON Schema shape.  Required
+ * fields are listed separately under `required`.
+ *
+ * This intentionally mirrors the shape that `ToolInfo.schema` expects in
+ * `apps/core/src/sidecar/adapters/mod.rs` so a `defineTool` output can be
+ * forwarded to Core without transformation.
+ */
+export interface ToolSchema {
+	/** Field definitions. */
+	properties: Record<string, JsonSchemaProperty>;
+	/** Names of fields that must be present in the input. */
+	required?: string[];
+	/** Type is always "object" for a tool's top-level input schema. */
+	type: "object";
+}
+
+// ── Options ───────────────────────────────────────────────────────────────────
+
+/** Options accepted by `defineTool`. */
+export interface ToolOptions<TInput extends Record<string, unknown>, TOutput> {
+	/** Stable unique identifier (e.g. "tool-web-search"). */
+	id: string;
+	/** Human-readable display name. */
+	name: string;
+	/**
+	 * The tool's run implementation.
+	 *
+	 * Called only after input validation passes.  Model calls are optional but
+	 * must go through `ctx.gateway` if used.
+	 */
+	run(input: TInput, ctx: RunnableContext): Promise<TOutput>;
+	/** JSON Schema describing the tool's input — used for input validation and Core ToolInfo. */
+	schema: ToolSchema;
+}
+
+// ── Internal: input validation ────────────────────────────────────────────────
+
+/**
+ * Validate `input` against `schema`.
+ *
+ * Throws a descriptive `Error` naming the first failing field.  This mirrors
+ * the validation behaviour of `PluginManifestSchema.safeParse` used elsewhere in
+ * the SDK — consistent error handling, no silent fallback.
+ */
+function validateInput(
+	input: unknown,
+	schema: ToolSchema,
+	toolId: string
+): void {
+	if (typeof input !== "object" || input === null || Array.isArray(input)) {
+		throw new Error(
+			`[ryu-sdk] Tool "${toolId}" input must be an object, got ${JSON.stringify(input)}`
+		);
+	}
+
+	const record = input as Record<string, unknown>;
+
+	for (const requiredKey of schema.required ?? []) {
+		if (!(requiredKey in record)) {
+			throw new Error(
+				`[ryu-sdk] Tool "${toolId}" input missing required field "${requiredKey}"`
+			);
+		}
+	}
+
+	for (const [key, prop] of Object.entries(schema.properties)) {
+		if (!(key in record)) {
+			continue; // optional field — skip
+		}
+		const value = record[key];
+		if (!checkType(value, prop.type)) {
+			throw new Error(
+				`[ryu-sdk] Tool "${toolId}" input field "${key}" expected type "${prop.type}", ` +
+					`got ${JSON.stringify(value)}`
+			);
+		}
+	}
+}
+
+/** Check that `value` matches the expected JSON Schema primitive type. */
+function checkType(value: unknown, type: JsonSchemaProperty["type"]): boolean {
+	switch (type) {
+		case "string":
+			return typeof value === "string";
+		case "number":
+		case "integer":
+			return typeof value === "number";
+		case "boolean":
+			return typeof value === "boolean";
+		case "array":
+			return Array.isArray(value);
+		case "object":
+			return (
+				typeof value === "object" && value !== null && !Array.isArray(value)
+			);
+		default:
+			return false;
+	}
+}
+
+// ── ToolRunnable ──────────────────────────────────────────────────────────────
+
+/**
+ * A `Runnable` with an extra `schema` field exposing the tool's JSON Schema.
+ *
+ * The `schema` is compatible with Core's `ToolInfo.schema` shape so it can
+ * be forwarded verbatim to Core's MCP/ACP layer.
+ */
+export interface ToolRunnable<
+	TInput extends Record<string, unknown> = Record<string, unknown>,
+	TOutput = unknown,
+> extends Runnable<TInput, TOutput> {
+	readonly kind: "tool";
+	/** JSON Schema for this tool's input — compatible with Core's ToolInfo.schema. */
+	readonly schema: ToolSchema;
+	/**
+	 * The `run` body serialized for Core's `inline_deno` tool backend — the exact
+	 * same technique `defineTurnHook` uses for its `code`. This is what makes a
+	 * `defineTool` **shippable**: bundled into a plugin manifest (see
+	 * {@link inlineToolRunnable} / `definePlugin({ tools })`), Core runs it in the
+	 * Deno sandbox, so the tool ships NEW behavior instead of only aliasing an
+	 * existing tool.
+	 *
+	 * IMPORTANT: like a hook body, the serialized function is **self-contained** —
+	 * it runs in a fresh sandbox with only `input` (the call arguments) and `host`
+	 * (the capability bridge: `host.sideModel` / `host.storage` / `host.log`, each
+	 * gated by the plugin's grants) in scope. It cannot capture outer variables,
+	 * imports, or closures, and `ctx.gateway` is **not** available in the sandbox
+	 * — a shipped tool reaches models through `host.sideModel`. When run in-process
+	 * via {@link ToolRunnable.run} the normal `(input, ctx)` contract still holds;
+	 * the sandbox form is the second parameter aliased to `host`.
+	 */
+	readonly code: string;
+}
+
+// ── Factory ───────────────────────────────────────────────────────────────────
+
+/**
+ * Create a Runnable tool with input validation.
+ *
+ * The returned value satisfies `ToolRunnable<TInput, TOutput>` (which extends
+ * `Runnable`) with `kind = "tool"`.  The `schema` property is the JSON Schema
+ * descriptor passed in options — forwarding it to Core's `ToolInfo.schema`
+ * requires no transformation.
+ *
+ * Input is validated at `run()` time: missing required fields or type
+ * mismatches throw before the tool body executes.
+ *
+ * @example
+ * ```ts
+ * const searchTool = defineTool({
+ *   id: "tool-web-search",
+ *   name: "Web Search",
+ *   schema: {
+ *     type: "object",
+ *     properties: { query: { type: "string", description: "Search query" } },
+ *     required: ["query"],
+ *   },
+ *   async run({ query }, _ctx) {
+ *     return { results: [`Result for: ${query}`] };
+ *   },
+ * });
+ * // schema is Core-compatible:
+ * console.log(searchTool.schema); // { type: "object", properties: { query: ... }, required: [...] }
+ * ```
+ */
+export function defineTool<
+	TInput extends Record<string, unknown> = Record<string, unknown>,
+	TOutput = unknown,
+>(options: ToolOptions<TInput, TOutput>): ToolRunnable<TInput, TOutput> {
+	const { id, name, schema, run } = options;
+
+	// Serialize the run body for Core's `inline_deno` backend — the same approach
+	// `defineTurnHook` uses: the sandbox wraps this in an async IIFE where `input`
+	// and `host` are in scope and a bare `return` reports the tool result.
+	const code = `return await (${run.toString()})(input, host);`;
+
+	return {
+		id,
+		name,
+		kind: "tool",
+		schema,
+		code,
+		run(input: TInput, ctx: RunnableContext): Promise<TOutput> {
+			validateInput(input, schema, id);
+			return run(input, ctx);
+		},
+	} satisfies ToolRunnable<TInput, TOutput>;
+}
+
+/**
+ * Convert a {@link ToolRunnable} into a `plugin.json` `kind:"tool"` runnable that
+ * ships its `run` body as Core's `inline_deno` backend. The emitted config
+ * mirrors Core's `ToolConfig` (`apps/core/src/plugin_manifest/schema.rs`):
+ * `{ slug, backend:"inline_deno", code, description?, input_schema }`. Core
+ * registers it as `app__<slug>` — discoverable via `/api/tools/search` and
+ * executed in the grant-gated sandbox.
+ *
+ * The plugin must declare the `tool:execute` grant (see `definePlugin`).
+ */
+export function inlineToolRunnable(
+	tool: ToolRunnable,
+	options?: { description?: string }
+): RunnableMeta {
+	return {
+		id: tool.id,
+		name: tool.name,
+		kind: "tool",
+		config: {
+			slug: tool.id,
+			backend: "inline_deno",
+			code: tool.code,
+			input_schema: tool.schema,
+			...(options?.description ? { description: options.description } : {}),
+		},
+	};
+}

package/src/runnable/turn-hook.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "bun:test";
+import { PluginManifestSchema } from "../manifest.ts";
+import {
+	definePlugin,
+	defineTurnHook,
+	type HookDirective,
+} from "./turn-hook.ts";
+
+describe("defineTurnHook", () => {
+	it("serializes the run function into sandbox code and defaults `on`", () => {
+		const hook = defineTurnHook({
+			id: "x.review",
+			run: (ctx) =>
+				({ kind: "note", text: `t:${ctx.transcript.length}` }) as HookDirective,
+		});
+		expect(hook.id).toBe("x.review");
+		expect(hook.on).toBe("post_assistant_turn");
+		// The code calls the serialized function with the sandbox globals.
+		expect(hook.code).toContain("(ctx, host)");
+		expect(hook.code.startsWith("return await (")).toBe(true);
+		expect(hook.code).toContain("kind");
+	});
+
+	it("honors an explicit `on`", () => {
+		const hook = defineTurnHook({
+			id: "x.pre",
+			on: "pre_user_turn",
+			run: () => ({ kind: "none" }),
+		});
+		expect(hook.on).toBe("pre_user_turn");
+	});
+});
+
+describe("definePlugin", () => {
+	it("produces a manifest that matches the Core PluginManifest shape", () => {
+		const manifest = definePlugin({
+			id: "com.example.double-check",
+			name: "Example Double Check",
+			version: "1.0.0",
+			grants: ["hook:side-model"],
+			turnHooks: [
+				defineTurnHook({
+					id: "dc.review",
+					run: async (ctx, host) => {
+						const last = ctx.transcript.at(-1);
+						const review = await host.sideModel({
+							prompt: last ? last.content : "",
+							model_pref_key: "double-check-model",
+						});
+						return { kind: "note", text: review };
+					},
+				}),
+			],
+			composerControls: [
+				{ id: "dc.toggle", type: "toggle", flag: "com.example.double-check" },
+			],
+		});
+
+		// Validates against the SDK's zod schema (which mirrors Core's serde shape).
+		const parsed = PluginManifestSchema.parse(manifest);
+		expect(parsed.id).toBe("com.example.double-check");
+		expect(parsed.runnables).toEqual([]);
+		expect(parsed.activation_events).toEqual(["*"]);
+		expect(parsed.contributes?.turn_hooks).toHaveLength(1);
+		expect(parsed.contributes?.turn_hooks[0]?.id).toBe("dc.review");
+		expect(parsed.contributes?.composer_controls).toHaveLength(1);
+		expect(parsed.permission_grants).toContain("hook:side-model");
+	});
+
+	it("defaults empty contribution arrays and grants", () => {
+		const manifest = definePlugin({
+			id: "com.example.empty",
+			name: "Empty",
+			version: "0.1.0",
+		});
+		const parsed = PluginManifestSchema.parse(manifest);
+		expect(parsed.permission_grants).toEqual([]);
+		expect(parsed.contributes?.turn_hooks).toEqual([]);
+		expect(parsed.contributes?.slash_commands).toEqual([]);
+	});
+});

package/src/runnable/turn-hook.ts

@@ -0,0 +1,191 @@
+/**
+ * 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.
+ */
+
+import type {
+	Contributes,
+	PluginManifest,
+	RunnableMeta,
+	Surface,
+	TurnHookContribution,
+} from "../manifest.ts";
+import type { DefineAppRequires } from "./app.ts";
+import { inlineToolRunnable, type ToolRunnable } from "./tool.ts";
+
+/** The context a `post_assistant_turn` hook receives. */
+export 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. */
+export 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). */
+export 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. */
+export type HookDirective =
+	| { kind: "none" }
+	| { kind: "note"; text: string }
+	| { kind: "continue"; text: string };
+
+/** A typed hook implementation: `(ctx, host) => directive`. */
+export type HookRun = (
+	ctx: HookContext,
+	host: HostApi
+) => HookDirective | Promise<HookDirective>;
+
+export 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.
+ */
+export function defineTurnHook(
+	options: DefineTurnHookOptions
+): TurnHookContribution {
+	const source = options.run.toString();
+	// The sandbox wraps `code` in an async IIFE where `ctx`/`host` are in scope
+	// and a bare `return` reports the directive — so call the serialized function
+	// with them and return its result.
+	const code = `return await (${source})(ctx, host);`;
+	return {
+		id: options.id,
+		on: options.on ?? "post_assistant_turn",
+		code,
+	};
+}
+
+export 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`.
+ */
+export function definePlugin(options: DefinePluginOptions): PluginManifest {
+	const contributes: Contributes = {
+		turn_hooks: options.turnHooks ?? [],
+		composer_controls: options.composerControls ?? [],
+		settings_tabs: options.settingsTabs ?? [],
+		slash_commands: options.slashCommands ?? [],
+		// A turn-hook plugin contributes no app widgets; the field is required on the
+		// resolved `Contributes` type (zod default applied), so set it explicitly.
+		widgets: [],
+	};
+	// Ship each inline tool as a `kind:"tool"` runnable (Core's `inline_deno`
+	// backend). Shipping tools requires the `tool:execute` grant; add it once.
+	const tools = options.tools ?? [];
+	const runnables: RunnableMeta[] = tools.map((t) => inlineToolRunnable(t));
+	const grants = new Set(options.grants ?? []);
+	if (tools.length > 0) {
+		grants.add("tool:execute");
+	}
+	return {
+		id: options.id,
+		name: options.name,
+		version: options.version,
+		runnables,
+		permission_grants: [...grants],
+		activation_events: options.activationEvents ?? ["*"],
+		contributes,
+		// Empty = EVERY surface (Core's backward-compatible default), never "hidden".
+		targets: options.targets ?? [],
+		// Absent (not `{apps:[],grants:[]}`) when undeclared, matching Core's
+		// `Option<Requires>` + `skip_serializing_if = "Option::is_none"`.
+		...(options.requires
+			? {
+					requires: {
+						apps: options.requires.apps ?? [],
+						capabilities: options.requires.capabilities ?? [],
+						grants: options.requires.grants ?? [],
+					},
+				}
+			: {}),
+	};
+}

package/src/runnable/workflow.ts

@@ -0,0 +1,76 @@
+/**
+ * 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.
+ */
+
+import type { Runnable, RunnableContext } from "./runnable-types.ts";
+
+/**
+ * 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).
+ */
+export type WorkflowStep<
+	TStepInput = unknown,
+	TStepOutput = unknown,
+> = Runnable<TStepInput, TStepOutput>;
+
+/** Options accepted by `defineWorkflow`. */
+export 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 };
+ *   },
+ * });
+ * ```
+ */
+export function defineWorkflow<TInput = unknown, TOutput = unknown>(
+	options: WorkflowOptions<TInput, TOutput>
+): Runnable<TInput, TOutput> {
+	const { id, name, run } = options;
+	return {
+		id,
+		name,
+		kind: "workflow",
+		run,
+	} satisfies Runnable<TInput, TOutput>;
+}