create-ryu-app 0.0.5

package/LICENSE

@@ -0,0 +1,179 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other transformations
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as "Not a
+      Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any patent
+      claims embodied in the Work constitute direct or contributory patent
+      infringement, then any patent licenses granted to You under this License
+      for that Work shall terminate as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or in addition to the
+          NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of Your modifications,
+      and to permit persons to whom the Work is furnished to do so,
+      subject to the following conditions:
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any conditions of title,
+      merchantability, or fitness for a particular purpose and
+      noninfringement. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may offer only
+      conditions consistent with this License.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 A Major Pte. Ltd.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,43 @@
+# <img src="https://raw.githubusercontent.com/amajorai/ryu/main/.github/logo.png" width="50" align="middle" alt="" />&nbsp; create-ryu-app
+
+> Scaffold a starter Ryu SDK project in one command. Part of [Ryu](../../README.md).
+
+[![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.
+
+Pick a starter with `--template` (default `agent`):
+
+| Template | Emits | Factory |
+|---|---|---|
+| `agent` | A loop-owning Runnable agent | `Agent` / `ryuTool` |
+| `hook-plugin` | A post-assistant-turn plugin | `definePlugin` + `defineTurnHook` |
+| `ryu-app` | An interactive in-chat widget | `defineApp` + a self-contained widget |
+| `companion-plugin` | A Ryu App whose widget calls a companion tool, plus a panel surface | `defineApp` |
+
+**Tier:** OSS, Apache-2.0
+
+## Install / Build
+
+```bash
+# scaffold a new project (default: agent template)
+bunx create-ryu-app <name>
+
+# scaffold a specific template
+bunx create-ryu-app <name> --template ryu-app
+
+# build from source
+bun run build   # tsup → dist/
+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`.
+
+## License
+
+Apache-2.0. See [LICENSE](./LICENSE). © 2026 A Major Pte. Ltd.

package/dist/index.js

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+
+// index.ts
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync
+} from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+import { PluginManifestSchema } from "@ryuhq/sdk/manifest";
+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 TEMPLATES = {
+  agent: { devEntry: "src/agent.ts" },
+  "hook-plugin": { devEntry: "src/plugin.ts" },
+  "ryu-app": {
+    devEntry: "src/app.ts",
+    extraDependencies: { react: "^19.2.0", "react-dom": "^19.2.0" }
+  },
+  "companion-plugin": {
+    devEntry: "src/app.ts",
+    extraDependencies: { react: "^19.2.0", "react-dom": "^19.2.0" }
+  }
+};
+var DEFAULT_TEMPLATE = "agent";
+var STAMPABLE_EXTENSIONS = [".json", ".ts", ".tsx", ".html", ".md"];
+function exitError(message) {
+  process.stderr.write(`error: ${message}
+`);
+  process.exit(1);
+}
+function printUsage() {
+  const templates = Object.keys(TEMPLATES).join(" | ");
+  process.stderr.write(
+    [
+      "create-ryu-app \u2014 scaffold a starter Ryu SDK project",
+      "",
+      "Usage:",
+      "  bunx create-ryu-app <name> [--template <template>]",
+      "",
+      "Arguments:",
+      "  <name>       Project directory name (also used as the app id slug)",
+      "",
+      "Options:",
+      `  --template   One of: ${templates} (default: ${DEFAULT_TEMPLATE})`,
+      ""
+    ].join("\n")
+  );
+}
+function toDisplayName(slug) {
+  return slug.split(RE_WORD_SEPARATOR).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+function toCompanionLabel(displayName) {
+  return RE_LABEL_IMPERSONATES.test(displayName) ? SAFE_COMPANION_LABEL : displayName;
+}
+function stampTemplate(filePath, replacements) {
+  let content = readFileSync(filePath, "utf8");
+  for (const [placeholder, value] of Object.entries(replacements)) {
+    content = content.replaceAll(placeholder, value);
+  }
+  writeFileSync(filePath, content, "utf8");
+}
+function stampTree(dir, replacements) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      stampTree(full, replacements);
+      continue;
+    }
+    if (STAMPABLE_EXTENSIONS.some((ext) => entry.name.endsWith(ext))) {
+      stampTemplate(full, replacements);
+    }
+  }
+}
+function resolveTemplateDir(template) {
+  const moduleDir = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    join(moduleDir, "template", template),
+    join(moduleDir, "..", "template", template)
+  ];
+  const found = candidates.find((dir) => existsSync(dir));
+  if (!found) {
+    exitError(
+      `template directory not found for '${template}' (looked in: ${candidates.join(", ")})`
+    );
+  }
+  return found;
+}
+function scaffold(name, outDir, template = DEFAULT_TEMPLATE) {
+  const slug = name.trim();
+  if (!slug) {
+    exitError("name must not be empty");
+  }
+  if (!RE_VALID_NAME.test(slug)) {
+    exitError(
+      "name must start with a letter or digit and contain only letters, digits, hyphens, and underscores"
+    );
+  }
+  const spec = TEMPLATES[template];
+  if (!spec) {
+    exitError(
+      `unknown template '${template}' \u2014 expected one of: ${Object.keys(TEMPLATES).join(", ")}`
+    );
+  }
+  const projectDir = resolve(join(outDir, slug));
+  if (existsSync(projectDir)) {
+    exitError(`directory already exists: ${projectDir}`);
+  }
+  const templateDir = resolveTemplateDir(template);
+  const displayName = toDisplayName(slug);
+  mkdirSync(projectDir, { recursive: true });
+  cpSync(templateDir, projectDir, { recursive: true });
+  stampTree(projectDir, {
+    __APP_NAME__: slug,
+    __APP_DISPLAY_NAME__: displayName,
+    __COMPANION_LABEL__: toCompanionLabel(displayName)
+  });
+  const manifestPath = join(projectDir, "plugin.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}`);
+  }
+  const pkgJson = {
+    name: slug,
+    version: "0.1.0",
+    type: "module",
+    scripts: {
+      dev: `bun run ${spec.devEntry}`,
+      pack: "bunx ryu pack ."
+    },
+    dependencies: {
+      "@ryuhq/sdk": SDK_DEPENDENCY_RANGE,
+      ...spec.extraDependencies
+    }
+  };
+  writeFileSync(
+    join(projectDir, "package.json"),
+    JSON.stringify(pkgJson, null, 2),
+    "utf8"
+  );
+  return projectDir;
+}
+function parseArgs(argv) {
+  let name;
+  let template = DEFAULT_TEMPLATE;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--template") {
+      const next = argv[i + 1];
+      if (!next) {
+        return { error: "--template requires a value" };
+      }
+      template = next;
+      i += 1;
+      continue;
+    }
+    if (arg?.startsWith("--template=")) {
+      template = arg.slice("--template=".length);
+      continue;
+    }
+    if (arg?.startsWith("-")) {
+      return { error: `unknown option: ${arg}` };
+    }
+    if (name === void 0) {
+      name = arg;
+      continue;
+    }
+    return { error: "too many arguments \u2014 expected exactly one <name>" };
+  }
+  return { name, template };
+}
+if (import.meta.main) {
+  const parsed = parseArgs(process.argv.slice(2));
+  if ("error" in parsed) {
+    printUsage();
+    exitError(parsed.error);
+  }
+  if (!parsed.name) {
+    printUsage();
+    exitError("name argument is required");
+  }
+  const created = scaffold(parsed.name, process.cwd(), parsed.template);
+  process.stdout.write(
+    [
+      "",
+      `  created ${parsed.name}/ (${parsed.template})`,
+      "",
+      "  next steps:",
+      `    cd ${parsed.name}`,
+      "    bun install",
+      "    bun dev        # runs the template entry",
+      "    bun run pack   # validate and bundle plugin.json",
+      ""
+    ].join("\n")
+  );
+  process.stdout.write(`  project: ${created}
+
+`);
+}
+export {
+  parseArgs,
+  scaffold
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "create-ryu-app",
+  "version": "0.0.5",
+  "type": "module",
+  "description": "Scaffold a starter Ryu SDK project with a Runnable, gateway-pointed model config, and plugin.json manifest",
+  "bin": {
+    "create-ryu-app": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "template",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "bun test",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@ryuhq/sdk": "^0.0.5"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.4",
+    "tsup": "^8.5.1",
+    "typescript": "^5"
+  }
+}

package/template/agent/plugin.json

@@ -0,0 +1,18 @@
+{
+  "id": "com.example.__APP_NAME__",
+  "name": "__APP_DISPLAY_NAME__",
+  "version": "0.1.0",
+  "runnables": [
+    {
+      "id": "agent-main",
+      "name": "Main Agent",
+      "kind": "agent"
+    }
+  ],
+  "permission_grants": [],
+  "companion": {
+    "label": "__COMPANION_LABEL__",
+    "icon": "sparkles",
+    "shortcut": "ctrl+shift+r"
+  }
+}

package/template/agent/src/agent.ts

@@ -0,0 +1,79 @@
+#!/usr/bin/env bun
+/**
+ * Starter Agent — a declarative, loop-owning Ryu agent.
+ *
+ * Run with:
+ *   bun run src/agent.ts
+ *
+ * This is an expense-tracker skeleton: it reads the user's Gmail through an
+ * existing Ryu tool (Composio) and summarizes the expenses it finds. The agent
+ * OWNS its tool-calling loop — you don't write the loop, you declare the agent.
+ *
+ * Every model call goes through the Ryu gateway of the node you target. Set
+ * RYU_GATEWAY_URL (default http://127.0.0.1:7981) and RYU_GATEWAY_TOKEN for
+ * inference; set RYU_CORE_URL (default http://127.0.0.1:7980) and RYU_TOKEN for
+ * tool execution. No provider key belongs in this file — credentials live in the
+ * gateway/Core config.
+ *
+ * Before this works end to end you need, once:
+ *   1. A Composio API key set on the node (Settings → Integrations).
+ *   2. A Core agent (here "agent-expense") whose allowlist includes the Gmail
+ *      actions below. `agentId` binds this SDK agent to it for governance.
+ *   3. On first run the agent emits an `auth_required` event with a Gmail OAuth
+ *      link — open it, connect Gmail, then run again.
+ */
+
+import { Agent, ryuTool } from "@ryuhq/sdk/agent";
+
+const MODEL_ID = process.env.RYU_MODEL ?? "gpt-4o-mini";
+
+const agent = new Agent({
+	name: "expense-tracker",
+	model: MODEL_ID,
+	agentId: "agent-expense",
+	instructions:
+		"You are an expense tracker. Search the user's Gmail for receipts and " +
+		"expense emails, read the relevant ones, and return a concise list of " +
+		"expenses with amount, merchant, date, and a category.",
+	tools: {
+		gmailSearch: ryuTool("composio__GMAIL_SEARCH_EMAILS", {
+			description: "Search the user's Gmail messages",
+			parameters: {
+				type: "object",
+				properties: {
+					query: {
+						type: "string",
+						description:
+							'Gmail search query, e.g. "receipt OR invoice newer_than:30d"',
+					},
+				},
+				required: ["query"],
+			},
+		}),
+		gmailGet: ryuTool("composio__GMAIL_GET_EMAIL", {
+			description: "Fetch a single Gmail message by id",
+		}),
+	},
+});
+
+const result = await agent.generate(
+	"Find my expenses from the last 30 days and summarize them."
+);
+
+if (result.authRequired) {
+	process.stdout.write(
+		`\nConnect your account to continue: ${result.authRequired.url ?? "(see message)"}\n`
+	);
+} else {
+	process.stdout.write(`\n${result.text}\n`);
+	process.stdout.write(`\n(${result.steps} step(s))\n`);
+}
+
+// ── Prefer the raw model client instead? ──────────────────────────────────────
+// For a single text turn with no tools, skip the agent loop entirely:
+//
+//   import { defineModel } from "@ryuhq/sdk";
+//   const model = defineModel(MODEL_ID);
+//   for await (const delta of model.stream([{ role: "user", content: "hi" }])) {
+//     if (delta.content) process.stdout.write(delta.content);
+//   }

package/template/companion-plugin/plugin.json

@@ -0,0 +1,62 @@
+{
+  "id": "com.example.__APP_NAME__",
+  "name": "__APP_DISPLAY_NAME__",
+  "version": "0.1.0",
+  "runnables": [
+    {
+      "id": "__APP_NAME____render",
+      "name": "render",
+      "kind": "tool",
+      "config": {
+        "slug": "__APP_NAME____render",
+        "description": "Render the interactive panel inline in the chat reply.",
+        "widget": true,
+        "widget_accessible": true,
+        "invoking": "Rendering…",
+        "invoked": "Ready"
+      }
+    },
+    {
+      "id": "__APP_NAME____save",
+      "name": "save",
+      "kind": "tool",
+      "config": {
+        "slug": "__APP_NAME____save",
+        "description": "Persist the panel's current state. Callable by the mounted widget via callTool.",
+        "widget": false,
+        "widget_accessible": true,
+        "input_schema": {
+          "type": "object",
+          "properties": {
+            "state": {
+              "type": "object"
+            }
+          },
+          "required": ["state"]
+        }
+      }
+    }
+  ],
+  "permission_grants": [],
+  "activation_events": ["*"],
+  "contributes": {
+    "turn_hooks": [],
+    "composer_controls": [],
+    "settings_tabs": [],
+    "slash_commands": [],
+    "widgets": [
+      {
+        "tool_id": "__APP_NAME____render",
+        "uri": "ui://widget/__APP_NAME__.html",
+        "ui_entry": "src/widget.tsx",
+        "mime": "text/html+skybridge",
+        "default_display_mode": "inline"
+      }
+    ]
+  },
+  "companion": {
+    "label": "App Panel",
+    "icon": "sidebar",
+    "shortcut": "ctrl+shift+p"
+  }
+}

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

@@ -0,0 +1,65 @@
+/**
+ * __APP_DISPLAY_NAME__ — a companion Ryu App (widget + a callable companion tool).
+ *
+ * This template goes one step past the plain Ryu App: besides the "render" tool
+ * that mounts the widget, it declares a `save` tool marked `accessible: true` — a
+ * COMPANION the mounted widget may invoke over the capability-gated bridge:
+ *
+ *     await window.openai.callTool("__APP_NAME____save", { state })
+ *
+ * The host routes that call through the Gateway (allowlist + audit) before it
+ * reaches Core; the frame never holds a token. It also declares a full-page
+ * `companion` surface (an in-desktop panel) whose label is a fixed literal so it
+ * 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
+ *
+ * v1 boundary: DECLARATIVE PASS-THROUGH only — there is no `run` handler for the
+ * tools. The render widget draws from `window.openai.toolInput` / `toolOutput`;
+ * the `save` companion is a call target (its handler is the serialized apps/core
+ * tool-exec slice, not shipped here). Keep the widget self-contained: no network.
+ */
+
+import { defineApp, type PluginManifest } from "@ryuhq/sdk";
+
+const app = defineApp({
+	id: "com.example.__APP_NAME__",
+	title: "__APP_DISPLAY_NAME__",
+	version: "0.1.0",
+	slug: "__APP_NAME__",
+	uiEntry: "src/widget.tsx",
+	tools: [
+		{
+			name: "render",
+			description: "Render the interactive panel inline in the chat reply.",
+			invoking: "Rendering…",
+			invoked: "Ready",
+		},
+		{
+			name: "save",
+			description:
+				"Persist the panel's current state. Callable by the mounted widget via callTool.",
+			accessible: true,
+			inputSchema: {
+				type: "object",
+				properties: { state: { type: "object" } },
+				required: ["state"],
+			},
+		},
+	],
+});
+
+// `defineApp` models the render/companion tool split but not the full-page
+// companion SURFACE, so add it here. The label is a fixed literal that passes the
+// anti-impersonation refine (must not contain "ryu" or "system").
+const manifest: PluginManifest = {
+	...app,
+	companion: { label: "App Panel", icon: "sidebar", shortcut: "ctrl+shift+p" },
+};
+
+export default manifest;
+
+if (import.meta.main) {
+	process.stdout.write(`${JSON.stringify(manifest, null, 2)}\n`);
+}

package/template/companion-plugin/src/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8">
+		<meta name="viewport" content="width=device-width, initial-scale=1">
+		<title>__APP_DISPLAY_NAME__</title>
+	</head>
+	<body>
+		<div id="root"></div>
+		<script type="module" src="./widget.tsx"></script>
+	</body>
+</html>

package/template/companion-plugin/src/widget.tsx

@@ -0,0 +1,81 @@
+/**
+ * __APP_DISPLAY_NAME__ widget — a companion widget that calls BACK to the host.
+ *
+ * `ryu pack` bundles this into a single self-contained HTML document. It runs in
+ * a null-origin `sandbox="allow-scripts"` iframe under a hard-pinned CSP
+ * (`connect-src 'none'`, no eval). NEVER `fetch` or reference a remote URL — the
+ * frame is offline; the ONLY channel to the node is `window.openai`.
+ *
+ * The Save button demonstrates the companion callTool bridge: the host validates
+ * the capability, routes the call through the Gateway, and executes it in Core.
+ */
+
+import { StrictMode, useState } from "react";
+import { createRoot } from "react-dom/client";
+
+/** The minimal Apps bridge this widget uses (installed synchronously by the host
+ *  before this module runs). `callTool` is gated by the app's `tool:call` grant. */
+interface RyuWidgetBridge {
+	callTool?(name: string, args: unknown): Promise<unknown>;
+	toolInput?: { title?: string };
+	toolOutput?: { title?: string };
+}
+
+declare global {
+	interface Window {
+		openai?: RyuWidgetBridge;
+	}
+}
+
+const SAVE_TOOL_ID = "__APP_NAME____save";
+
+function Widget() {
+	const bridge = window.openai ?? {};
+	const title =
+		bridge.toolOutput?.title ??
+		bridge.toolInput?.title ??
+		"__APP_DISPLAY_NAME__";
+	const [note, setNote] = useState("");
+	const [status, setStatus] = useState<"idle" | "saving" | "saved" | "error">(
+		"idle"
+	);
+
+	async function save() {
+		if (!bridge.callTool) {
+			setStatus("error");
+			return;
+		}
+		setStatus("saving");
+		try {
+			await bridge.callTool(SAVE_TOOL_ID, { state: { note } });
+			setStatus("saved");
+		} catch {
+			setStatus("error");
+		}
+	}
+
+	return (
+		<main className="ryu-app">
+			<h1>{title}</h1>
+			<textarea
+				aria-label="Note"
+				onChange={(event) => setNote(event.target.value)}
+				placeholder="Type a note to persist…"
+				value={note}
+			/>
+			<button onClick={save} type="button">
+				Save
+			</button>
+			<p className="status">{status}</p>
+		</main>
+	);
+}
+
+const rootEl = document.getElementById("root");
+if (rootEl) {
+	createRoot(rootEl).render(
+		<StrictMode>
+			<Widget />
+		</StrictMode>
+	);
+}

package/template/hook-plugin/plugin.json

@@ -0,0 +1,27 @@
+{
+  "id": "com.example.__APP_NAME__",
+  "name": "__APP_DISPLAY_NAME__",
+  "version": "0.1.0",
+  "runnables": [],
+  "permission_grants": [],
+  "activation_events": ["*"],
+  "contributes": {
+    "turn_hooks": [
+      {
+        "id": "flag-terse",
+        "on": "post_assistant_turn",
+        "code": "return await ((ctx, host) => {\n  const last = ctx.transcript.at(-1);\n  if (last && last.role === \"assistant\" && last.content.trim().length < 40) {\n    host.log(\"terse reply flagged\");\n    return { kind: \"note\", text: \"That reply looked brief \\u2014 want more detail?\" };\n  }\n  return { kind: \"none\" };\n})(ctx, host);"
+      }
+    ],
+    "composer_controls": [
+      {
+        "id": "hook.toggle",
+        "type": "toggle",
+        "flag": "com.example.__APP_NAME__"
+      }
+    ],
+    "settings_tabs": [],
+    "slash_commands": [],
+    "widgets": []
+  }
+}

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

@@ -0,0 +1,57 @@
+/**
+ * __APP_DISPLAY_NAME__ — a turn-hook plugin.
+ *
+ * A turn hook is server-side logic Core runs after each assistant turn, inside its
+ * capability-gated plugin sandbox (`apps/core/src/plugin_host/`). The hook sees a
+ * `ctx` (agent, conversation, transcript, flags) and a `host` bridge (logging,
+ * `sideModel`, namespaced `storage`), and returns a directive:
+ *   - `{ kind: "none" }`            — do nothing
+ *   - `{ kind: "note", text }`      — attach an out-of-band note to the turn
+ *   - `{ kind: "continue", text }`  — feed text back for another assistant turn
+ *
+ * This is the SAME shape the built-in double-check / goal / advisor plugins use.
+ * The `run` body must be SELF-CONTAINED: it executes in a fresh sandbox with only
+ * `ctx` and `host` in scope, so it cannot capture imports, closures, or module
+ * 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
+ */
+
+import { definePlugin, defineTurnHook } from "@ryuhq/sdk";
+
+const manifest = definePlugin({
+	id: "com.example.__APP_NAME__",
+	name: "__APP_DISPLAY_NAME__",
+	version: "0.1.0",
+	grants: [],
+	composerControls: [
+		{ id: "hook.toggle", type: "toggle", flag: "com.example.__APP_NAME__" },
+	],
+	turnHooks: [
+		defineTurnHook({
+			id: "flag-terse",
+			run: (ctx, host) => {
+				const last = ctx.transcript.at(-1);
+				if (
+					last &&
+					last.role === "assistant" &&
+					last.content.trim().length < 40
+				) {
+					host.log("terse reply flagged");
+					return {
+						kind: "note",
+						text: "That reply looked brief — want more detail?",
+					};
+				}
+				return { kind: "none" };
+			},
+		}),
+	],
+});
+
+export default manifest;
+
+if (import.meta.main) {
+	process.stdout.write(`${JSON.stringify(manifest, null, 2)}\n`);
+}

package/template/ryu-app/plugin.json

@@ -0,0 +1,54 @@
+{
+  "id": "com.example.__APP_NAME__",
+  "name": "__APP_DISPLAY_NAME__",
+  "version": "0.1.0",
+  "runnables": [
+    {
+      "id": "__APP_NAME____render",
+      "name": "render",
+      "kind": "tool",
+      "config": {
+        "slug": "__APP_NAME____render",
+        "description": "Render the __APP_DISPLAY_NAME__ widget inline in the chat reply.",
+        "widget": true,
+        "widget_accessible": false,
+        "input_schema": {
+          "type": "object",
+          "properties": {
+            "title": {
+              "type": "string",
+              "description": "Heading shown in the widget"
+            },
+            "items": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Rows to render"
+            }
+          },
+          "required": ["title"]
+        },
+        "invoking": "Rendering…",
+        "invoked": "Ready"
+      }
+    }
+  ],
+  "permission_grants": [],
+  "activation_events": ["*"],
+  "contributes": {
+    "turn_hooks": [],
+    "composer_controls": [],
+    "settings_tabs": [],
+    "slash_commands": [],
+    "widgets": [
+      {
+        "tool_id": "__APP_NAME____render",
+        "uri": "ui://widget/__APP_NAME__.html",
+        "ui_entry": "src/widget.tsx",
+        "mime": "text/html+skybridge",
+        "default_display_mode": "inline"
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,53 @@
+/**
+ * __APP_DISPLAY_NAME__ — a Ryu App (interactive in-chat widget).
+ *
+ * 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.
+ *
+ *   bun run src/app.ts     # prints the assembled manifest
+ *   bunx ryu pack .        # bundles src/widget.tsx into ui_code + writes plugin.json
+ *
+ * v1 boundary: this is DECLARATIVE PASS-THROUGH only. There is no `run` handler —
+ * the widget renders from `window.openai.toolInput` / `toolOutput` (the arguments
+ * the model passed and the structured content Core echoes back). Third-party tool
+ * CODE execution needs the plugin runtime, which is a later tier. Keep the widget
+ * self-contained: no network fetches (the CSP blocks egress), assets inline.
+ */
+
+import { defineApp } from "@ryuhq/sdk";
+
+const manifest = defineApp({
+	id: "com.example.__APP_NAME__",
+	title: "__APP_DISPLAY_NAME__",
+	version: "0.1.0",
+	slug: "__APP_NAME__",
+	uiEntry: "src/widget.tsx",
+	tools: [
+		{
+			name: "render",
+			description:
+				"Render the __APP_DISPLAY_NAME__ widget inline in the chat reply.",
+			invoking: "Rendering…",
+			invoked: "Ready",
+			inputSchema: {
+				type: "object",
+				properties: {
+					title: { type: "string", description: "Heading shown in the widget" },
+					items: {
+						type: "array",
+						items: { type: "string" },
+						description: "Rows to render",
+					},
+				},
+				required: ["title"],
+			},
+		},
+	],
+});
+
+export default manifest;
+
+if (import.meta.main) {
+	process.stdout.write(`${JSON.stringify(manifest, null, 2)}\n`);
+}

package/template/ryu-app/src/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8">
+		<meta name="viewport" content="width=device-width, initial-scale=1">
+		<title>__APP_DISPLAY_NAME__</title>
+	</head>
+	<body>
+		<div id="root"></div>
+		<script type="module" src="./widget.tsx"></script>
+	</body>
+</html>

package/template/ryu-app/src/widget.tsx

@@ -0,0 +1,59 @@
+/**
+ * __APP_DISPLAY_NAME__ widget — the in-chat surface `ryu pack` bundles into a
+ * single, self-contained HTML document (inline CSS + one inline module script).
+ *
+ * IMPORTANT — sandbox contract:
+ *   - Mounts inside a null-origin `sandbox="allow-scripts"` iframe under a
+ *     hard-pinned CSP: `connect-src 'none'`, `img-src data:`, no eval. So NEVER
+ *     `fetch`, load a CDN script, or reference a remote URL — the frame is offline
+ *     by construction. All host access goes through `window.openai`.
+ *   - Read your inputs from `window.openai.toolInput` (the model's arguments) and
+ *     `window.openai.toolOutput` (the structured content Core echoed back).
+ */
+
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+
+/** The minimal slice of the Apps bridge this widget reads (installed
+ *  synchronously by the host before this module runs). */
+interface RyuWidgetBridge {
+	toolInput?: { title?: string; items?: string[] };
+	toolOutput?: { title?: string; items?: string[] };
+}
+
+declare global {
+	interface Window {
+		openai?: RyuWidgetBridge;
+	}
+}
+
+function Widget() {
+	const bridge = window.openai ?? {};
+	const data = bridge.toolOutput ?? bridge.toolInput ?? {};
+	const title = data.title ?? "__APP_DISPLAY_NAME__";
+	const items = data.items ?? [];
+
+	return (
+		<main className="ryu-app">
+			<h1>{title}</h1>
+			{items.length === 0 ? (
+				<p className="empty">No rows yet.</p>
+			) : (
+				<ul>
+					{items.map((item, index) => (
+						<li key={`${index}-${item}`}>{item}</li>
+					))}
+				</ul>
+			)}
+		</main>
+	);
+}
+
+const rootEl = document.getElementById("root");
+if (rootEl) {
+	createRoot(rootEl).render(
+		<StrictMode>
+			<Widget />
+		</StrictMode>
+	);
+}