@ryuhq/sdk 0.1.13 → 0.2.0

package/src/plugin/ryu-plugin.ts

@@ -125,6 +125,27 @@ export interface ThemeContribution {
  *  are RPCs over the postMessage bridge; the plugin never holds a Core token or
  *  Tauri IPC handle directly. */
 export interface RyuHostServices {
+	/** Read and cooperatively stop Core-visible background processes. */
+	background: {
+		list(input?: { producer?: string; running_only?: boolean }): Promise<
+			{
+				process_id: string;
+				command: string;
+				cwd: string;
+				elapsed_ms: number;
+				running: boolean;
+				[key: string]: unknown;
+			}[]
+		>;
+		stop(input: { process_id: string }): Promise<{
+			ok: boolean;
+			requested: boolean;
+			process_id: string;
+		}>;
+	};
+	/** Read-only feature discovery. Older hosts may omit this method; treat that
+	 * as an empty capability set rather than assuming a native surface exists. */
+	capabilities?(): Promise<RyuHostCapabilities>;
 	/** 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
@@ -140,6 +161,21 @@ export interface RyuHostServices {
 	 *  or any other agent field (invariant: no capability returns a secret). Gated
 	 *  by the `core:list_agents` grant. */
 	listAgents(): Promise<{ id: string; name: string }[]>;
+	/** Mobile-native effects. These methods remain optional at the type boundary
+	 * because desktop, web, extension, and terminal hosts fail closed. */
+	native?: {
+		haptics(input: RyuNativeHapticsInput): Promise<RyuNativeHapticsResult>;
+		notifications: {
+			create(
+				input: RyuNativeNotificationInput
+			): Promise<RyuNativeNotificationResult>;
+		};
+		liveActivities: {
+			update(
+				input: RyuNativeLiveActivityInput
+			): Promise<RyuNativeLiveActivityResult>;
+		};
+	};
 	/** 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). */
@@ -152,6 +188,52 @@ export interface RyuHostServices {
 	};
 }
 
+/** The token-free, read-only native feature inventory returned by a host. */
+export interface RyuHostCapabilities {
+	androidOngoingNotifications: boolean;
+	browserNotifications: boolean;
+	dynamicIsland: boolean;
+	haptics: boolean;
+	hardwareBleRelay: boolean;
+	liveActivities: boolean;
+	localNotifications: boolean;
+	platform: "android" | "browser" | "ios" | "unknown";
+	pushRegistration: boolean;
+	quickActions: boolean;
+	sounds: boolean;
+}
+
+export type RyuNativeHapticStyle = "light" | "success" | "warning" | "error";
+
+export interface RyuNativeHapticsInput {
+	style: RyuNativeHapticStyle;
+}
+
+export interface RyuNativeNotificationInput {
+	body: string;
+	title: string;
+}
+
+export interface RyuNativeLiveActivityInput {
+	conversationId: string;
+	detail: string;
+	status: "running" | "waiting" | "review" | "done" | "error";
+	title: string;
+}
+
+export interface RyuNativeHapticsResult {
+	signaled: true;
+}
+
+export interface RyuNativeNotificationResult {
+	id: string;
+	scheduled: true;
+}
+
+export interface RyuNativeLiveActivityResult {
+	updated: true;
+}
+
 // ── The host API a plugin's activate() receives ───────────────────────────────
 
 /** Everything a plugin can contribute. Each `register*` returns a

package/src/runnable/app.test.ts

@@ -9,6 +9,7 @@ function checklistApp(grants?: string[]) {
 		slug: "checklist",
 		title: "Checklist",
 		version: "1.0.0",
+		uiEntry: "src/checklist.tsx",
 		...(grants ? { grants } : {}),
 		tools: [{ name: "render", description: "Render a checklist" }],
 	});
@@ -48,6 +49,7 @@ describe("defineApp widget grant", () => {
 			slug: "tools",
 			title: "Tools",
 			version: "1.0.0",
+			uiEntry: "src/tools.tsx",
 			tools: [{ name: "toggle", description: "Toggle", accessible: true }],
 		});
 		expect(manifest.contributes?.widgets ?? []).toHaveLength(0);

package/src/runnable/app.ts

@@ -74,7 +74,7 @@ export interface AppToolSpec {
 	invoked?: string;
 	/** Status label shown while a render tool runs (e.g. `"Plotting chart…"`). */
 	invoking?: string;
-	/** Tool name (unqualified). The wire id is `<server>__<name>`. */
+	/** Tool name (unqualified). The wire id is `<server>.<name>`. */
 	name: string;
 }
 
@@ -141,7 +141,7 @@ export interface DefineAppOptions {
 
 /** Build a fully-qualified tool id from a server namespace and tool name. */
 export function appToolId(server: string, name: string): string {
-	return `${server}__${name}`;
+	return `${server}.${name}`;
 }
 
 /**
@@ -213,6 +213,7 @@ export function defineApp(options: DefineAppOptions): PluginManifest {
 
 	const contributes: Contributes = {
 		turn_hooks: [],
+		chat_features: [],
 		// This builder synthesises an app from its runnables; an app that emits
 		// events declares them in a hand-authored `manifest.json`, same as
 		// `lsp_servers` below.
@@ -223,6 +224,7 @@ export function defineApp(options: DefineAppOptions): PluginManifest {
 		sidebar_sections: [],
 		sidebar_buttons: [],
 		dock_panels: [],
+		live_activities: [],
 		// Empty for the same reason as every sibling family above: this builder
 		// synthesises `widgets` from the app's own runnables and nothing else, and
 		// takes no `contributes` passthrough. An app that wants to declare language
@@ -235,6 +237,7 @@ export function defineApp(options: DefineAppOptions): PluginManifest {
 		data_categories: [],
 		pi_extensions: [],
 		output_styles: [],
+		message_actions: [],
 		widgets,
 	};
 

package/src/runnable/index.ts

@@ -26,6 +26,8 @@ export { defineAgent } from "./agent.ts";
 export type { AppToolSpec, DefineAppOptions } from "./app.ts";
 export { appToolId, defineApp } from "./app.ts";
 export type {
+	BackgroundClient,
+	BackgroundProcess,
 	DurableClient,
 	EnginesClient,
 	HttpPrimitiveTransportOptions,

package/src/runnable/primitives.ts

@@ -316,6 +316,16 @@ export const PRIMITIVE_BINDINGS: Record<string, PrimitiveBinding> = {
 		method: "model.complete",
 		grant: "hook:side-model",
 	},
+	"background.list": {
+		transport: "bridge",
+		method: "background.list",
+		grant: "background:control",
+	},
+	"background.stop": {
+		transport: "bridge",
+		method: "background.stop",
+		grant: "background:control",
+	},
 	// Host-direct media data-path (the host holds the node token; returns data: URLs).
 	"image.generate": {
 		transport: "direct",
@@ -468,6 +478,37 @@ export interface EnginesClient {
 	}): Promise<number[][]>;
 }
 
+/** One process visible through the shared Core background registry. */
+export interface BackgroundProcess {
+	command: string;
+	cwd: string;
+	description?: string | null;
+	elapsed_ms: number;
+	exit_code?: number | null;
+	exit_signal?: string | null;
+	kind: string;
+	label?: string | null;
+	pid?: number | null;
+	process_id: string;
+	producer: string;
+	running: boolean;
+	shell_id?: string | null;
+	started_at: number;
+}
+
+/** Background-process registry and cooperative stop requests. */
+export interface BackgroundClient {
+	list(input?: {
+		producer?: string;
+		runningOnly?: boolean;
+	}): Promise<BackgroundProcess[]>;
+	stop(input: { processId: string }): Promise<{
+		ok: boolean;
+		requested: boolean;
+		process_id: string;
+	}>;
+}
+
 /** TTS primitive — speech synthesis (`crates/ryu-tts`). */
 export interface TtsClient {
 	/**
@@ -513,6 +554,7 @@ export interface ImageClient {
  * Core node) — the same "what runs vs what is allowed" split as `ctx.gateway`.
  */
 export interface RyuPrimitives {
+	background: BackgroundClient;
 	durable: DurableClient;
 	engines: EnginesClient;
 	image: ImageClient;
@@ -542,6 +584,21 @@ function brokerCall(
  */
 export function createPrimitives(transport: PrimitiveTransport): RyuPrimitives {
 	return {
+		background: {
+			list: (input) =>
+				transport.bridge("background.list", {
+					producer: input?.producer,
+					running_only: input?.runningOnly,
+				}) as Promise<BackgroundProcess[]>,
+			stop: (input) =>
+				transport.bridge("background.stop", {
+					process_id: input.processId,
+				}) as Promise<{
+					ok: boolean;
+					requested: boolean;
+					process_id: string;
+				}>,
+		},
 		rag: {
 			retrieve: (input) =>
 				brokerCall(transport, "rag", "retrieve", input) as Promise<RagChunk[]>,

package/src/runnable/tool.ts

@@ -236,7 +236,7 @@ export function defineTool<
  * 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
+ * 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`).

package/src/runnable/turn-hook.ts

@@ -154,7 +154,7 @@ export interface DefinePluginOptions {
 	/**
 	 * 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.
+	 * `app.<tool.id>`). Shipping any tool auto-adds the `tool:execute` grant.
 	 */
 	tools?: ToolRunnable[];
 	/** Turn hooks the plugin contributes. */
@@ -173,6 +173,7 @@ export function definePlugin(options: DefinePluginOptions): PluginManifest {
 		turn_hooks: options.turnHooks ?? [],
 		hook_events: options.hookEvents ?? [],
 		composer_controls: options.composerControls ?? [],
+		chat_features: [],
 		settings_tabs: options.settingsTabs ?? [],
 		slash_commands: options.slashCommands ?? [],
 		lsp_servers: options.lspServers ?? {},
@@ -184,9 +185,11 @@ export function definePlugin(options: DefinePluginOptions): PluginManifest {
 		sidebar_sections: [],
 		sidebar_buttons: [],
 		dock_panels: [],
+		live_activities: [],
 		data_categories: [],
 		pi_extensions: [],
 		output_styles: [],
+		message_actions: [],
 	};
 	// Ship each inline tool as a `kind:"tool"` runnable (Core's `inline_deno`
 	// backend). Shipping tools requires the `tool:execute` grant; add it once.