create-ryu-app 0.0.5 → 0.0.17

package/README.md

@@ -5,9 +5,17 @@
 [![License](https://shieldcn.dev/badge/License-Apache--2.0-73DC8C.svg?logo=apache&logoColor=white)](./LICENSE)
 [![Stack](https://shieldcn.dev/badge/TypeScript-CLI-3178C6.svg?logo=typescript&logoColor=white)](../../README.md)
 
-`create-ryu-app` is the project scaffolder for the Ryu SDK. Running it generates a starter project with a Runnable, a gateway-pointed model config, and a `plugin.json` (legacy `ryu.json`) manifest validated against the PluginManifest schema, so a new plugin compiles and packs out of the box. It depends on `@ryuhq/sdk` by semver.
+`create-ryu-app` is the project scaffolder for Ryu extensions. Running it generates a starter project with a `manifest.json` validated against the PluginManifest schema, so it installs out of the box.
 
-Pick a starter with `--template` (default `agent`):
+Ryu extensions come in two shapes, and `--template` picks which one you get.
+
+**Apps** are self-contained `apps-store/<app>` satellites: a manifest plus an out-of-process `sidecar/`, driven through the generic ext-proxy (`/api/ext/<plugin_id>/*`). Shipping one never requires a change to Ryu Core or the Gateway.
+
+| Template | Emits | Runtime |
+|---|---|---|
+| `app` | A manifest declaring a lazy local sidecar + a grant-gated capability, and the loopback HTTP sidecar that serves it | Bun/Node, dependency-free |
+
+**Plugins** are manifest contributions Ryu renders in-process — runnables, turn hooks, widgets, composer controls, a companion panel. No sidecar, no port. They are authored against `@ryuhq/sdk` and shipped with `ryu pack`.
 
 | Template | Emits | Factory |
 |---|---|---|
@@ -27,6 +35,9 @@ bunx create-ryu-app <name>
 # scaffold a specific template
 bunx create-ryu-app <name> --template ryu-app
 
+# scaffold an apps-store satellite (manifest + sidecar)
+bunx create-ryu-app <name> --template app
+
 # build from source
 bun run build   # tsup → dist/
 bun test
@@ -35,8 +46,9 @@ bun test
 ## What it provides
 
 - A one-command scaffolder (`create-ryu-app <name> [--template <t>]`) bundled with a `template/<name>/` tree per starter.
-- A generated starter Runnable plus a gateway-pointed model config.
-- A `plugin.json` / `ryu.json` manifest validated against the PluginManifest schema, ready for `ryu pack`.
+- For plugins: a starter Runnable plus a gateway-pointed model config, and a manifest ready for `ryu pack`.
+- For apps: a satellite tree — `manifest.json` (sidecar + capability + grant) and a fail-closed, bearer-gated loopback sidecar that owns no dependency on this repo.
+- A `manifest.json` validated against the PluginManifest schema at scaffold time.
 
 ## License
 

package/dist/index.js

@@ -16,17 +16,38 @@ var RE_WORD_SEPARATOR = /[-_\s]+/;
 var RE_VALID_NAME = /^[a-z0-9][a-z0-9-_]*$/i;
 var RE_LABEL_IMPERSONATES = /ryu|system/i;
 var SAFE_COMPANION_LABEL = "App Panel";
-var SDK_DEPENDENCY_RANGE = "^0.0.5";
+var SDK_DEPENDENCY_RANGE = "^0.0.17";
 var TEMPLATES = {
-  agent: { devEntry: "src/agent.ts" },
-  "hook-plugin": { devEntry: "src/plugin.ts" },
+  agent: {
+    kind: "plugin",
+    summary: "a loop-owning Runnable agent (Agent + ryuTool)",
+    devEntry: "src/agent.ts"
+  },
+  "hook-plugin": {
+    kind: "plugin",
+    summary: "a post-assistant-turn hook (definePlugin + defineTurnHook)",
+    devEntry: "src/plugin.ts"
+  },
   "ryu-app": {
+    kind: "plugin",
+    summary: "an interactive in-chat widget (defineApp + a sandboxed widget)",
     devEntry: "src/app.ts",
     extraDependencies: { react: "^19.2.0", "react-dom": "^19.2.0" }
   },
   "companion-plugin": {
+    kind: "plugin",
+    summary: "a widget that calls a companion tool, plus a panel surface",
     devEntry: "src/app.ts",
     extraDependencies: { react: "^19.2.0", "react-dom": "^19.2.0" }
+  },
+  app: {
+    kind: "app",
+    summary: "an apps-store satellite: manifest + a loopback HTTP sidecar, driven through the ext-proxy",
+    devEntry: "sidecar/src/main/index.ts",
+    extraScripts: {
+      build: "bun run --cwd sidecar build",
+      "check-types": "bun run --cwd sidecar check-types"
+    }
   }
 };
 var DEFAULT_TEMPLATE = "agent";
@@ -36,11 +57,16 @@ function exitError(message) {
 `);
   process.exit(1);
 }
+function templateLines(kind) {
+  const width = Math.max(...Object.keys(TEMPLATES).map((n) => n.length));
+  return Object.entries(TEMPLATES).filter(([, spec]) => spec.kind === kind).map(
+    ([name, spec]) => `    ${name.padEnd(width)}  ${spec.summary}${name === DEFAULT_TEMPLATE ? " (default)" : ""}`
+  );
+}
 function printUsage() {
-  const templates = Object.keys(TEMPLATES).join(" | ");
   process.stderr.write(
     [
-      "create-ryu-app \u2014 scaffold a starter Ryu SDK project",
+      "create-ryu-app \u2014 scaffold a starter Ryu app or plugin",
       "",
       "Usage:",
       "  bunx create-ryu-app <name> [--template <template>]",
@@ -49,7 +75,17 @@ function printUsage() {
       "  <name>       Project directory name (also used as the app id slug)",
       "",
       "Options:",
-      `  --template   One of: ${templates} (default: ${DEFAULT_TEMPLATE})`,
+      "  --template   Which starter to emit. Two shapes:",
+      "",
+      "  APP \u2014 a self-contained satellite: manifest.json + an out-of-process",
+      "  sidecar/, reached through the generic ext-proxy (/api/ext/<id>/*).",
+      "  Ships without any change to Ryu Core or the Gateway.",
+      ...templateLines("app"),
+      "",
+      "  PLUGIN \u2014 manifest contributions Ryu renders in-process: runnables,",
+      "  turn hooks, widgets, composer controls, a companion panel. No sidecar,",
+      "  no port.",
+      ...templateLines("plugin"),
       ""
     ].join("\n")
   );
@@ -60,6 +96,9 @@ function toDisplayName(slug) {
 function toCompanionLabel(displayName) {
   return RE_LABEL_IMPERSONATES.test(displayName) ? SAFE_COMPANION_LABEL : displayName;
 }
+function toEnvPrefix(slug) {
+  return `RYU_${slug.toUpperCase().replaceAll("-", "_")}`;
+}
 function stampTemplate(filePath, replacements) {
   let content = readFileSync(filePath, "utf8");
   for (const [placeholder, value] of Object.entries(replacements)) {
@@ -115,33 +154,41 @@ function scaffold(name, outDir, template = DEFAULT_TEMPLATE) {
   }
   const templateDir = resolveTemplateDir(template);
   const displayName = toDisplayName(slug);
+  const envPrefix = toEnvPrefix(slug);
   mkdirSync(projectDir, { recursive: true });
   cpSync(templateDir, projectDir, { recursive: true });
   stampTree(projectDir, {
     __APP_NAME__: slug,
     __APP_DISPLAY_NAME__: displayName,
-    __COMPANION_LABEL__: toCompanionLabel(displayName)
+    __COMPANION_LABEL__: toCompanionLabel(displayName),
+    __APP_BIN_ENV__: `${envPrefix}_BIN`,
+    __APP_PORT_ENV__: `${envPrefix}_PORT`,
+    __APP_TOKEN_ENV__: `${envPrefix}_TOKEN`
   });
-  const manifestPath = join(projectDir, "plugin.json");
+  const manifestPath = join(projectDir, "manifest.json");
   const parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
   const validation = PluginManifestSchema.safeParse(parsed);
   if (!validation.success) {
     const first = validation.error.issues[0];
     const field = first?.path.join(".") ?? "unknown";
     const msg = first?.message ?? "validation failed";
-    exitError(`generated plugin.json is invalid at '${field}': ${msg}`);
+    exitError(`generated manifest.json is invalid at '${field}': ${msg}`);
   }
+  const isApp = spec.kind === "app";
   const pkgJson = {
     name: slug,
     version: "0.1.0",
     type: "module",
     scripts: {
       dev: `bun run ${spec.devEntry}`,
-      pack: "bunx ryu pack ."
+      ...isApp ? {} : { pack: "bunx ryu pack ." },
+      ...spec.extraScripts
     },
-    dependencies: {
-      "@ryuhq/sdk": SDK_DEPENDENCY_RANGE,
-      ...spec.extraDependencies
+    ...isApp ? {} : {
+      dependencies: {
+        "@ryuhq/sdk": SDK_DEPENDENCY_RANGE,
+        ...spec.extraDependencies
+      }
     }
   };
   writeFileSync(
@@ -191,6 +238,7 @@ if (import.meta.main) {
     exitError("name argument is required");
   }
   const created = scaffold(parsed.name, process.cwd(), parsed.template);
+  const isApp = TEMPLATES[parsed.template]?.kind === "app";
   process.stdout.write(
     [
       "",
@@ -199,8 +247,8 @@ if (import.meta.main) {
       "  next steps:",
       `    cd ${parsed.name}`,
       "    bun install",
-      "    bun dev        # runs the template entry",
-      "    bun run pack   # validate and bundle plugin.json",
+      "    bun dev         # runs the template entry",
+      isApp ? "    bun run build   # compile the sidecar binary the manifest names" : "    bun run pack    # validate and bundle manifest.json",
       ""
     ].join("\n")
   );

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "create-ryu-app",
-  "version": "0.0.5",
+  "version": "0.0.17",
   "type": "module",
-  "description": "Scaffold a starter Ryu SDK project with a Runnable, gateway-pointed model config, and plugin.json manifest",
+  "description": "Scaffold a starter Ryu SDK project with a Runnable, gateway-pointed model config, and manifest.json manifest",
   "bin": {
     "create-ryu-app": "./dist/index.js"
   },
@@ -20,7 +20,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@ryuhq/sdk": "^0.0.5"
+    "@ryuhq/sdk": "^0.0.17"
   },
   "devDependencies": {
     "@types/bun": "^1.3.4",

package/template/app/README.md

@@ -0,0 +1,58 @@
+# __APP_DISPLAY_NAME__
+
+A Ryu **app**: a self-contained satellite that ships a manifest and an
+out-of-process sidecar. It is not a plugin — there is no widget, no turn hook and
+no bundled UI code. Everything a Ryu node needs to run it is in this directory.
+
+```
+manifest.json          the whole integration surface (sidecar + capability + grant)
+sidecar/               the backend process, dependency-free (node:http only)
+  src/main/control.ts  the loopback HTTP control server (pure router + auth)
+  src/main/index.ts    entrypoint
+```
+
+## The contract
+
+An app owns **only** its `manifest.json` and its `sidecar/`. It must never require
+a change to Ryu Core or the Gateway — no route module, no reserved MCP server, no
+hardcoded id or port anywhere but this manifest. Control flows through the generic
+ext-proxy:
+
+```
+client → GET /api/ext/com.example.__APP_NAME__/items → Core → 127.0.0.1:<port>/items
+```
+
+Core forwards **only** the sub-paths declared in `sidecars[].http.routes[]` and
+404s everything else, so that list is a security boundary, not documentation. Keep
+it in sync with the router in `sidecar/src/main/control.ts`.
+
+`provides[]` publishes the sidecar as the `__APP_NAME__.control` capability behind
+the `__APP_NAME__:control` grant, so another app can depend on the *capability*
+rather than on this app's id.
+
+## Run it
+
+```bash
+bun install --cwd sidecar
+__APP_TOKEN_ENV__=dev-token bun run dev
+curl -s localhost:7899/health
+curl -s -H 'Authorization: Bearer dev-token' localhost:7899/items
+```
+
+Every route except `GET /health` is bearer-gated and **fails closed**: with no
+`RYU_EXT_TOKEN` (injected by Core at spawn) and no `__APP_TOKEN_ENV__` override,
+every protected route 401s. Do not relax that — loopback is not a trust boundary.
+
+## Before you ship
+
+- **Pick a free port.** There is no port registry. `7899` is the scaffold default;
+  avoid Core (`7980`), the Gateway (`7981`), the built-in sidecar band
+  (`7990`–`8003`) and the local engines (`8080`–`8087`). Core injects the
+  profile-shifted port through `__APP_PORT_ENV__`, so read it — never hardcode.
+- **Build the binary.** `sidecars[].process.command` names `ryu-__APP_NAME__` on
+  `PATH`; `bun run --cwd sidecar build` compiles it. `__APP_BIN_ENV__` points a
+  node at a local build instead.
+- **Rename the demo domain.** `/items` is a placeholder for whatever this app
+  actually does. Change it in `control.ts` *and* in the manifest's `routes[]`.
+- **Keep `sidecar/` self-contained.** No workspace imports, no Ryu SDK — this tree
+  is published on its own.

package/template/app/manifest.json

@@ -0,0 +1,45 @@
+{
+  "id": "com.example.__APP_NAME__",
+  "name": "__APP_DISPLAY_NAME__",
+  "version": "0.1.0",
+  "description": "A self-contained Ryu app: a loopback HTTP sidecar Ryu spawns lazily and exposes as the grant-gated `__APP_NAME__.control` capability. Clients reach it through the generic ext-proxy at /api/ext/com.example.__APP_NAME__/*; no Core or Gateway code knows this app exists.",
+  "tagline": "A sidecar-backed Ryu app",
+  "category": "Automation",
+  "engines": {
+    "ryu": ">=0.0.1"
+  },
+  "runnables": [],
+  "sidecars": [
+    {
+      "name": "__APP_NAME__",
+      "process": {
+        "kind": "local",
+        "command": "ryu-__APP_NAME__",
+        "command_env": "__APP_BIN_ENV__",
+        "port_env": "__APP_PORT_ENV__"
+      },
+      "port": 7899,
+      "health_path": "/health",
+      "lazy": true,
+      "idle_stop_secs": 300,
+      "http": {
+        "routes": [
+          { "path": "/" },
+          { "path": "/health" },
+          { "path": "/items" },
+          { "path": "/items/:id" }
+        ]
+      }
+    }
+  ],
+  "provides": [
+    {
+      "capability": "__APP_NAME__.control",
+      "version": "1.0.0",
+      "sidecar": "__APP_NAME__",
+      "route": "/",
+      "grant": "__APP_NAME__:control"
+    }
+  ],
+  "permission_grants": ["__APP_NAME__:control"]
+}

package/template/app/sidecar/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@example/__APP_NAME__-sidecar",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "ryu-__APP_NAME__": "./src/main/index.ts"
+  },
+  "main": "src/main/index.ts",
+  "scripts": {
+    "start": "bun run src/main/index.ts",
+    "build": "bun build src/main/index.ts --compile --outfile dist/ryu-__APP_NAME__",
+    "check-types": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "@types/node": "^22",
+    "typescript": "^5"
+  }
+}

package/template/app/sidecar/src/main/control.ts

@@ -0,0 +1,291 @@
+// Loopback control server for the __APP_DISPLAY_NAME__ sidecar.
+//
+// Ryu spawns this as a `local` manifest sidecar (see `../../../../manifest.json`,
+// `SidecarProcess::Local`). It exposes a small HTTP control surface bound to
+// loopback so Core — and, through Core's generic ext-proxy
+// (`/api/ext/com.example.__APP_NAME__/*`), every Ryu client — can drive the app.
+// Nothing in Core or the Gateway knows this app exists: the manifest's
+// `sidecars[]` + `provides[]` are the entire integration.
+//
+// SECURITY
+// --------
+// * Bound to 127.0.0.1 only. Never bind 0.0.0.0 — the ext-proxy is the only
+//   intended caller and it dials loopback.
+// * Every route except `GET /health` requires `Authorization: Bearer <token>` —
+//   the per-plugin secret Core mints and injects at spawn (`RYU_EXT_TOKEN`);
+//   `__APP_TOKEN_ENV__` overrides it for standalone/dev runs. Neither set ⇒
+//   FAIL-CLOSED (every protected route 401s). A sidecar that skips this check is
+//   an unauthenticated RCE surface for anything else running on the machine —
+//   loopback is not a trust boundary on a multi-user or agent-laden host.
+//
+// The router (`handleRequest`) is a pure function over an injected `ItemStore`,
+// so it unit-tests with a fake — no sockets, no process.
+
+import { randomUUID, timingSafeEqual } from "node:crypto";
+import { createServer, type Server } from "node:http";
+
+/** Default loopback port. There is NO port registry: picking a free one is the
+ *  app author's job. Stay clear of Core (:7980), the Gateway (:7981), the
+ *  built-in sidecar band (:7990–:8003), and the local engines (:8080–:8087). */
+const CONTROL_BASE_PORT = 7899;
+
+/** A Core running under `RYU_PROFILE=dev` shifts every port by this much so a dev
+ *  node and a release node coexist. Core injects the shifted value through
+ *  `__APP_PORT_ENV__`; this fallback only matters when the sidecar is run by hand. */
+const DEV_PORT_OFFSET = 1000;
+
+const PACKAGE_VERSION = "0.1.0";
+
+/** The capability this sidecar serves — must equal `provides[].capability` in the
+ *  manifest, which is what a consuming app names in its `requires.capabilities`. */
+export const CAPABILITY = "__APP_NAME__.control";
+
+/** One `/items` row. Replace this with whatever your app actually owns. */
+export interface Item {
+	createdAt: string;
+	id: string;
+	text: string;
+}
+
+/** The domain the router drives. Injected so the router can be tested against a
+ *  fake without touching the real backing store. */
+export interface ItemStore {
+	create(text: string): Item;
+	get(id: string): Item | null;
+	list(): Item[];
+	remove(id: string): boolean;
+}
+
+/** The default store — in-memory, so the scaffold runs with zero setup. Swap it
+ *  for a real one (SQLite, a file, a vendor SDK) without touching the router. */
+export class MemoryItemStore implements ItemStore {
+	private readonly items = new Map<string, Item>();
+
+	list(): Item[] {
+		return [...this.items.values()];
+	}
+
+	get(id: string): Item | null {
+		return this.items.get(id) ?? null;
+	}
+
+	create(text: string): Item {
+		const item: Item = {
+			id: randomUUID(),
+			text,
+			createdAt: new Date().toISOString(),
+		};
+		this.items.set(item.id, item);
+		return item;
+	}
+
+	remove(id: string): boolean {
+		return this.items.delete(id);
+	}
+}
+
+/** The bind port: whatever Core injected, else the profile-aware default. */
+export function resolveControlPort(
+	env: NodeJS.ProcessEnv = process.env
+): number {
+	const explicit = Number.parseInt(env.__APP_PORT_ENV__ ?? "", 10);
+	if (Number.isInteger(explicit) && explicit > 0) {
+		return explicit;
+	}
+	const isDev = (env.RYU_PROFILE ?? "").trim().toLowerCase() === "dev";
+	return isDev ? CONTROL_BASE_PORT + DEV_PORT_OFFSET : CONTROL_BASE_PORT;
+}
+
+/** The expected bearer, or `null` when unset — which fails every protected route
+ *  closed rather than serving the surface unauthenticated. */
+export function resolveControlToken(
+	env: NodeJS.ProcessEnv = process.env
+): string | null {
+	const raw = env.RYU_EXT_TOKEN ?? env.__APP_TOKEN_ENV__ ?? "";
+	const trimmed = raw.trim();
+	return trimmed.length > 0 ? trimmed : null;
+}
+
+/** Constant-time bearer check. `null`/empty `expected` ⇒ fail-closed (reject all).
+ *  Compared with `timingSafeEqual`, not `===`: a byte-at-a-time comparison leaks
+ *  the token one character per request to a caller that can time the loopback. */
+export function bearerOk(
+	authHeader: string | undefined,
+	expected: string | null
+): boolean {
+	if (!expected) {
+		return false;
+	}
+	const presented = authHeader?.startsWith("Bearer ")
+		? authHeader.slice("Bearer ".length)
+		: null;
+	if (!presented) {
+		return false;
+	}
+	const a = Buffer.from(presented, "utf8");
+	const b = Buffer.from(expected, "utf8");
+	if (a.length !== b.length) {
+		return false;
+	}
+	return timingSafeEqual(a, b);
+}
+
+export interface ControlResponse {
+	json?: unknown;
+	status: number;
+}
+
+export interface RequestDeps {
+	store: ItemStore;
+	token: string | null;
+}
+
+/** `/items/<id>` — a top-level literal (lint/performance/useTopLevelRegex). */
+const RE_ITEM_ID = /^\/items\/([^/]+)$/;
+
+function notFound(): ControlResponse {
+	return { status: 404, json: { ok: false, error: "not found" } };
+}
+
+function badRequest(error: string): ControlResponse {
+	return { status: 400, json: { ok: false, error } };
+}
+
+/** Parse a JSON body. `""` (no body) is an empty object; malformed is `null`. */
+function parseJsonBody(raw: string): Record<string, unknown> | null {
+	if (!raw) {
+		return {};
+	}
+	try {
+		const parsed: unknown = JSON.parse(raw);
+		return typeof parsed === "object" && parsed !== null
+			? (parsed as Record<string, unknown>)
+			: null;
+	} catch {
+		return null;
+	}
+}
+
+function handleItemsCollection(
+	method: string,
+	body: string,
+	store: ItemStore
+): ControlResponse {
+	if (method === "GET") {
+		return { status: 200, json: { ok: true, items: store.list() } };
+	}
+	if (method !== "POST") {
+		return notFound();
+	}
+	const payload = parseJsonBody(body);
+	if (!payload) {
+		return badRequest("body must be a JSON object");
+	}
+	const text = typeof payload.text === "string" ? payload.text.trim() : "";
+	if (!text) {
+		return badRequest("missing text");
+	}
+	return { status: 201, json: { ok: true, item: store.create(text) } };
+}
+
+function handleItem(
+	method: string,
+	id: string,
+	store: ItemStore
+): ControlResponse {
+	if (method === "GET") {
+		const item = store.get(id);
+		return item
+			? { status: 200, json: { ok: true, item } }
+			: { status: 404, json: { ok: false, error: "unknown item" } };
+	}
+	if (method === "DELETE") {
+		return store.remove(id)
+			? { status: 200, json: { ok: true } }
+			: { status: 404, json: { ok: false, error: "unknown item" } };
+	}
+	return notFound();
+}
+
+/**
+ * Pure request router. `path` carries no query string; `body` is the raw request
+ * body. Every route except `GET /health` is bearer-gated.
+ *
+ * The paths handled here MUST stay in sync with `sidecars[].http.routes[]` in the
+ * manifest: Core 404s any sub-path the manifest does not declare (undeclared paths
+ * are never forwarded), so a route added here but not there is simply unreachable
+ * through the ext-proxy — and one declared there but missing here 404s from the
+ * sidecar instead.
+ */
+export function handleRequest(
+	method: string,
+	path: string,
+	authHeader: string | undefined,
+	body: string,
+	deps: RequestDeps
+): ControlResponse {
+	// Unauthenticated on purpose: Core's health monitor probes this before the
+	// plugin's token is in play, and it reveals nothing but liveness.
+	if (path === "/health") {
+		return { status: 200, json: { ok: true, version: PACKAGE_VERSION } };
+	}
+
+	if (!bearerOk(authHeader, deps.token)) {
+		return { status: 401, json: { ok: false, error: "unauthorized" } };
+	}
+
+	// The capability root — `provides[].route` points here, so the broker hits it
+	// to describe the capability.
+	if (path === "/" && method === "GET") {
+		return {
+			status: 200,
+			json: {
+				ok: true,
+				capability: CAPABILITY,
+				version: PACKAGE_VERSION,
+				routes: ["/health", "/items", "/items/:id"],
+			},
+		};
+	}
+
+	if (path === "/items") {
+		return handleItemsCollection(method, body, deps.store);
+	}
+
+	const match = RE_ITEM_ID.exec(path);
+	if (match?.[1]) {
+		return handleItem(method, decodeURIComponent(match[1]), deps.store);
+	}
+
+	return notFound();
+}
+
+/** Start the loopback control server. A bind failure logs and leaves the process
+ *  up so Core's health probe reports it unhealthy instead of racing a respawn. */
+export function startControlServer(deps: RequestDeps, port: number): Server {
+	const server = createServer((req, res) => {
+		const chunks: Buffer[] = [];
+		req.on("data", (c) => chunks.push(c as Buffer));
+		req.on("end", () => {
+			const body = Buffer.concat(chunks).toString("utf8");
+			const path = (req.url ?? "/").split("?")[0] ?? "/";
+			const resp = handleRequest(
+				req.method ?? "GET",
+				path,
+				req.headers.authorization,
+				body,
+				deps
+			);
+			res.writeHead(resp.status, { "Content-Type": "application/json" });
+			res.end(JSON.stringify(resp.json ?? {}));
+		});
+	});
+	server.on("error", (err) => {
+		// biome-ignore lint/suspicious/noConsole: main-process diagnostic, no renderer.
+		console.warn(
+			`[ryu-__APP_NAME__] control server unavailable: ${err.message}`
+		);
+	});
+	server.listen(port, "127.0.0.1");
+	return server;
+}

package/template/app/sidecar/src/main/index.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env bun
+// __APP_DISPLAY_NAME__ sidecar — entrypoint.
+//
+// A dependency-free Node/Bun process Core spawns as a `local` manifest sidecar.
+// It owns ONE loopback HTTP control server (`control.ts`) and nothing else: no
+// import from `apps/core`, no Ryu SDK, no shared workspace package. That is the
+// satellite contract — this directory must build and ship from its own tree.
+//
+//   bun run src/main/index.ts        # standalone (set __APP_TOKEN_ENV__ first)
+//   bun run build                    # → dist/ryu-__APP_NAME__, the `command` the
+//                                    #   manifest's sidecars[].process names
+
+import {
+	MemoryItemStore,
+	resolveControlPort,
+	resolveControlToken,
+	startControlServer,
+} from "./control.ts";
+
+function main(): void {
+	const port = resolveControlPort();
+	const token = resolveControlToken();
+	if (!token) {
+		// Fail-closed is enforced per-request; warn once so a misconfigured spawn is
+		// diagnosable rather than silently 401ing every call.
+		// biome-ignore lint/suspicious/noConsole: main-process diagnostic, no renderer.
+		console.warn(
+			"[ryu-__APP_NAME__] no RYU_EXT_TOKEN/__APP_TOKEN_ENV__ set — all control routes will 401"
+		);
+	}
+	startControlServer({ store: new MemoryItemStore(), token }, port);
+	// biome-ignore lint/suspicious/noConsole: main-process diagnostic, no renderer.
+	console.log(`[ryu-__APP_NAME__] control server on 127.0.0.1:${port}`);
+}
+
+main();

package/template/app/sidecar/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "baseUrl": ".",
+    "types": ["node", "bun"]
+  },
+  "include": ["src"]
+}

package/template/companion-plugin/{plugin.json → manifest.json}

@@ -37,7 +37,7 @@
       }
     }
   ],
-  "permission_grants": [],
+  "permission_grants": ["widget:render"],
   "activation_events": ["*"],
   "contributes": {
     "turn_hooks": [],

package/template/companion-plugin/src/app.ts

@@ -13,7 +13,7 @@
  * can never impersonate first-party Ryu/system chrome.
  *
  *   bun run src/app.ts     # prints the assembled manifest
- *   bunx ryu pack .        # bundles src/widget.tsx into ui_code + writes plugin.json
+ *   bunx ryu pack .        # bundles src/widget.tsx into ui_code + writes manifest.json
  *
  * v1 boundary: DECLARATIVE PASS-THROUGH only — there is no `run` handler for the
  * tools. The render widget draws from `window.openai.toolInput` / `toolOutput`;

package/template/hook-plugin/src/plugin.ts

@@ -15,7 +15,7 @@
  * variables — reference only `ctx`, `host`, and language built-ins.
  *
  *   bun run src/plugin.ts   # prints the assembled manifest
- *   bunx ryu pack .         # serializes the hook + writes plugin.json
+ *   bunx ryu pack .         # serializes the hook + writes manifest.json
  */
 
 import { definePlugin, defineTurnHook } from "@ryuhq/sdk";

package/template/ryu-app/{plugin.json → manifest.json}

@@ -34,7 +34,7 @@
       }
     }
   ],
-  "permission_grants": [],
+  "permission_grants": ["widget:render"],
   "activation_events": ["*"],
   "contributes": {
     "turn_hooks": [],

package/template/ryu-app/src/app.ts

@@ -3,10 +3,10 @@
  *
  * A Ryu App bundles a "render" tool whose result mounts a self-contained widget
  * inline in the chat reply. This module is the AUTHORING source of truth: it uses
- * `defineApp` to assemble the `plugin.json` manifest that ships alongside it.
+ * `defineApp` to assemble the `manifest.json` manifest that ships alongside it.
  *
  *   bun run src/app.ts     # prints the assembled manifest
- *   bunx ryu pack .        # bundles src/widget.tsx into ui_code + writes plugin.json
+ *   bunx ryu pack .        # bundles src/widget.tsx into ui_code + writes manifest.json
  *
  * v1 boundary: this is DECLARATIVE PASS-THROUGH only. There is no `run` handler —
  * the widget renders from `window.openai.toolInput` / `toolOutput` (the arguments