create-agents24-app 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agents24
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+# create-agents24-app
+
+Last Updated: 2026-07-19
+
+Create a canonical Agents24 React/Vite application:
+
+```bash
+npm create agents24-app@latest
+```
+
+Choose a direct client deployment or a server-backed BFF, then choose the Essential, Workbench, or Flow visual recipe. The generated app contains only the selected integration and recipe.

package/dist/chunk-OCIF3LSI.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+
+// src/generator.ts
+import { spawnSync } from "child_process";
+import { randomBytes } from "crypto";
+import {
+  chmodSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync
+} from "fs";
+import { basename, dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+var packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+var templateRoot = join(packageRoot, "templates");
+var versions = JSON.parse(readFileSync(join(packageRoot, "versions.json"), "utf8"));
+function packageName(directory) {
+  const value = basename(resolve(directory)).toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[._-]+|[._-]+$/g, "");
+  if (!value || !/^[a-z0-9]/.test(value)) throw new Error("The destination does not produce a valid npm package name.");
+  return value;
+}
+function assertDestination(destination) {
+  if (!existsSync(destination)) return;
+  if (!statSync(destination).isDirectory()) throw new Error("The destination already exists and is not a directory.");
+  if (readdirSync(destination).length > 0) throw new Error("The destination directory must be empty.");
+}
+function walk(directory) {
+  return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(directory, entry.name);
+    return entry.isDirectory() ? walk(path) : [path];
+  });
+}
+function replaceTemplateValues(directory, replacements) {
+  for (const file of walk(directory)) {
+    if (file.endsWith(".png") || file.endsWith(".ico")) continue;
+    let content = readFileSync(file, "utf8");
+    for (const [token, value] of Object.entries(replacements)) content = content.split(token).join(value);
+    writeFileSync(file, content);
+  }
+}
+function copyLayer(name, destination) {
+  cpSync(join(templateRoot, name), destination, { recursive: true, force: true });
+}
+function generatedManifest(options, name) {
+  const dependencies = {
+    "@agents24/client": versions.agents24["@agents24/client"],
+    "@agents24/react": versions.agents24["@agents24/react"],
+    "@agents24/chat-react": versions.agents24["@agents24/chat-react"],
+    react: versions.runtime.react,
+    "react-dom": versions.runtime["react-dom"]
+  };
+  const devDependencies = {
+    "@types/react": versions.development["@types/react"],
+    "@types/react-dom": versions.development["@types/react-dom"],
+    "@vitejs/plugin-react": versions.development["@vitejs/plugin-react"],
+    typescript: versions.development.typescript,
+    vite: versions.development.vite
+  };
+  const scripts = {
+    dev: "vite",
+    build: "tsc --noEmit && vite build",
+    preview: "vite preview"
+  };
+  if (options.integration === "bff") {
+    dependencies["@agents24/node"] = versions.agents24["@agents24/node"];
+    dependencies.hono = versions.runtime.hono;
+    dependencies["@hono/node-server"] = versions.runtime["@hono/node-server"];
+    devDependencies["@types/node"] = versions.development["@types/node"];
+    devDependencies.concurrently = versions.development.concurrently;
+    devDependencies.tsx = versions.development.tsx;
+    devDependencies.tsup = "^8.5.1";
+    scripts.dev = 'concurrently -k -n web,bff "vite" "tsx watch server/index.ts"';
+    scripts.build = "tsc --noEmit && vite build && tsup server/index.ts --format esm --platform node --out-dir server-dist --external @agents24/node --external hono --external @hono/node-server";
+    scripts.start = "node server-dist/index.js --production";
+  }
+  return { name, private: true, version: "0.0.0", type: "module", engines: { node: "^22.0.0 || ^24.0.0" }, scripts, dependencies, devDependencies };
+}
+function envFiles(options) {
+  const value = (input) => JSON.stringify(String(input || ""));
+  if (options.integration === "client-deployment") {
+    return {
+      example: "VITE_AGENTS24_BASE_URL=https://api.agents24.dev\nVITE_AGENTS24_DEPLOYMENT_ID=acd_your_public_deployment_id\n",
+      local: `VITE_AGENTS24_BASE_URL=${value(options.baseUrl)}
+VITE_AGENTS24_DEPLOYMENT_ID=${value(options.deploymentId)}
+`
+    };
+  }
+  return {
+    example: [
+      "AGENTS24_BASE_URL=https://api.agents24.dev",
+      "AGENTS24_API_KEY=your_server_only_api_key",
+      "AGENTS24_ORGANIZATION_ID=your_organization_uuid",
+      "AGENTS24_PROJECT_ID=your_project_uuid",
+      "AGENTS24_AGENT_ID=your_agent_uuid",
+      "AGENTS24_AGENT_VERSION_ID=",
+      "SESSION_COOKIE_SECRET=generate_at_least_32_random_bytes",
+      "PORT=3001",
+      ""
+    ].join("\n"),
+    local: [
+      `AGENTS24_BASE_URL=${value(options.baseUrl)}`,
+      `AGENTS24_API_KEY=${value(options.apiKey)}`,
+      `AGENTS24_ORGANIZATION_ID=${value(options.organizationId)}`,
+      `AGENTS24_PROJECT_ID=${value(options.projectId)}`,
+      `AGENTS24_AGENT_ID=${value(options.agentId)}`,
+      `AGENTS24_AGENT_VERSION_ID=${value(options.agentVersionId)}`,
+      `SESSION_COOKIE_SECRET=${value(randomBytes(32).toString("base64url"))}`,
+      "PORT=3001",
+      ""
+    ].join("\n")
+  };
+}
+function installCommand(packageManager) {
+  if (packageManager === "npm") return ["npm", ["install"]];
+  if (packageManager === "yarn") return ["yarn", []];
+  if (packageManager === "bun") return ["bun", ["install"]];
+  return ["pnpm", ["install"]];
+}
+function runScriptCommand(packageManager, script) {
+  if (packageManager === "npm") return `npm run ${script}`;
+  if (packageManager === "bun") return `bun run ${script}`;
+  return `${packageManager} ${script}`;
+}
+function installDependencies(directory, packageManager) {
+  const [command, args] = installCommand(packageManager);
+  const { AGENTS24_API_KEY: _apiKey, ...installerEnvironment } = process.env;
+  const result = spawnSync(command, args, { cwd: directory, stdio: "inherit", env: installerEnvironment });
+  if (result.error) throw new Error(`Could not start ${command}: ${result.error.message}`);
+  if (result.status !== 0) throw new Error(`${command} ${args.join(" ")} failed with exit ${result.status}.`);
+}
+function createApp(options) {
+  const destination = resolve(options.directory);
+  assertDestination(destination);
+  const name = packageName(destination);
+  const parent = dirname(destination);
+  mkdirSync(parent, { recursive: true });
+  const staging = join(parent, `.${name}.agents24-${randomBytes(6).toString("hex")}`);
+  try {
+    mkdirSync(staging, { mode: 448 });
+    copyLayer("common", staging);
+    copyLayer(`integrations/${options.integration}`, staging);
+    copyLayer(`themes/${options.theme}`, staging);
+    const apiOrigin = new URL(options.baseUrl).origin;
+    replaceTemplateValues(staging, {
+      "__APP_NAME__": name,
+      "__THEME__": options.theme,
+      "__INTEGRATION__": options.integration,
+      "__CONNECT_SOURCE__": options.integration === "client-deployment" ? apiOrigin : "",
+      "__PM_DEV__": runScriptCommand(options.packageManager, "dev"),
+      "__PM_BUILD__": runScriptCommand(options.packageManager, "build"),
+      "__PM_PRODUCTION__": runScriptCommand(options.packageManager, options.integration === "bff" ? "start" : "preview")
+    });
+    const gitignore = join(staging, "_gitignore");
+    if (existsSync(gitignore)) renameSync(gitignore, join(staging, ".gitignore"));
+    writeFileSync(join(staging, "package.json"), `${JSON.stringify(generatedManifest(options, name), null, 2)}
+`);
+    const env = envFiles(options);
+    writeFileSync(join(staging, ".env.example"), env.example);
+    if (options.install) installDependencies(staging, options.packageManager);
+    writeFileSync(join(staging, ".env.local"), env.local, { mode: 384 });
+    chmodSync(join(staging, ".env.local"), 384);
+    if (existsSync(destination)) rmSync(destination, { recursive: true });
+    renameSync(staging, destination);
+    return { directory: destination, packageName: name };
+  } catch (error) {
+    rmSync(staging, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+export {
+  installDependencies,
+  createApp
+};
+//# sourceMappingURL=chunk-OCIF3LSI.js.map

package/dist/chunk-OCIF3LSI.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/generator.ts"],"sourcesContent":["import { spawnSync } from \"node:child_process\";\nimport { randomBytes } from \"node:crypto\";\nimport {\n  chmodSync,\n  cpSync,\n  existsSync,\n  mkdirSync,\n  readdirSync,\n  readFileSync,\n  renameSync,\n  rmSync,\n  statSync,\n  writeFileSync,\n} from \"node:fs\";\nimport { basename, dirname, join, resolve } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\nimport type { CreateAppOptions, GeneratedApp, PackageManager } from \"./types.js\";\n\ntype Versions = {\n  agents24: Record<string, string>;\n  runtime: Record<string, string>;\n  development: Record<string, string>;\n};\n\nconst packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), \"..\");\nconst templateRoot = join(packageRoot, \"templates\");\nconst versions = JSON.parse(readFileSync(join(packageRoot, \"versions.json\"), \"utf8\")) as Versions;\n\nfunction packageName(directory: string): string {\n  const value = basename(resolve(directory))\n    .toLowerCase()\n    .replace(/[^a-z0-9._-]+/g, \"-\")\n    .replace(/^[._-]+|[._-]+$/g, \"\");\n  if (!value || !/^[a-z0-9]/.test(value)) throw new Error(\"The destination does not produce a valid npm package name.\");\n  return value;\n}\n\nfunction assertDestination(destination: string): void {\n  if (!existsSync(destination)) return;\n  if (!statSync(destination).isDirectory()) throw new Error(\"The destination already exists and is not a directory.\");\n  if (readdirSync(destination).length > 0) throw new Error(\"The destination directory must be empty.\");\n}\n\nfunction walk(directory: string): string[] {\n  return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {\n    const path = join(directory, entry.name);\n    return entry.isDirectory() ? walk(path) : [path];\n  });\n}\n\nfunction replaceTemplateValues(directory: string, replacements: Record<string, string>): void {\n  for (const file of walk(directory)) {\n    if (file.endsWith(\".png\") || file.endsWith(\".ico\")) continue;\n    let content = readFileSync(file, \"utf8\");\n    for (const [token, value] of Object.entries(replacements)) content = content.split(token).join(value);\n    writeFileSync(file, content);\n  }\n}\n\nfunction copyLayer(name: string, destination: string): void {\n  cpSync(join(templateRoot, name), destination, { recursive: true, force: true });\n}\n\nfunction generatedManifest(options: CreateAppOptions, name: string): Record<string, unknown> {\n  const dependencies: Record<string, string> = {\n    \"@agents24/client\": versions.agents24[\"@agents24/client\"]!,\n    \"@agents24/react\": versions.agents24[\"@agents24/react\"]!,\n    \"@agents24/chat-react\": versions.agents24[\"@agents24/chat-react\"]!,\n    react: versions.runtime.react!,\n    \"react-dom\": versions.runtime[\"react-dom\"]!,\n  };\n  const devDependencies: Record<string, string> = {\n    \"@types/react\": versions.development[\"@types/react\"]!,\n    \"@types/react-dom\": versions.development[\"@types/react-dom\"]!,\n    \"@vitejs/plugin-react\": versions.development[\"@vitejs/plugin-react\"]!,\n    typescript: versions.development.typescript!,\n    vite: versions.development.vite!,\n  };\n  const scripts: Record<string, string> = {\n    dev: \"vite\",\n    build: \"tsc --noEmit && vite build\",\n    preview: \"vite preview\",\n  };\n  if (options.integration === \"bff\") {\n    dependencies[\"@agents24/node\"] = versions.agents24[\"@agents24/node\"]!;\n    dependencies.hono = versions.runtime.hono!;\n    dependencies[\"@hono/node-server\"] = versions.runtime[\"@hono/node-server\"]!;\n    devDependencies[\"@types/node\"] = versions.development[\"@types/node\"]!;\n    devDependencies.concurrently = versions.development.concurrently!;\n    devDependencies.tsx = versions.development.tsx!;\n    devDependencies.tsup = \"^8.5.1\";\n    scripts.dev = \"concurrently -k -n web,bff \\\"vite\\\" \\\"tsx watch server/index.ts\\\"\";\n    scripts.build = \"tsc --noEmit && vite build && tsup server/index.ts --format esm --platform node --out-dir server-dist --external @agents24/node --external hono --external @hono/node-server\";\n    scripts.start = \"node server-dist/index.js --production\";\n  }\n  return { name, private: true, version: \"0.0.0\", type: \"module\", engines: { node: \"^22.0.0 || ^24.0.0\" }, scripts, dependencies, devDependencies };\n}\n\nfunction envFiles(options: CreateAppOptions): { example: string; local: string } {\n  const value = (input: string | undefined) => JSON.stringify(String(input || \"\"));\n  if (options.integration === \"client-deployment\") {\n    return {\n      example: \"VITE_AGENTS24_BASE_URL=https://api.agents24.dev\\nVITE_AGENTS24_DEPLOYMENT_ID=acd_your_public_deployment_id\\n\",\n      local: `VITE_AGENTS24_BASE_URL=${value(options.baseUrl)}\\nVITE_AGENTS24_DEPLOYMENT_ID=${value(options.deploymentId)}\\n`,\n    };\n  }\n  return {\n    example: [\n      \"AGENTS24_BASE_URL=https://api.agents24.dev\",\n      \"AGENTS24_API_KEY=your_server_only_api_key\",\n      \"AGENTS24_ORGANIZATION_ID=your_organization_uuid\",\n      \"AGENTS24_PROJECT_ID=your_project_uuid\",\n      \"AGENTS24_AGENT_ID=your_agent_uuid\",\n      \"AGENTS24_AGENT_VERSION_ID=\",\n      \"SESSION_COOKIE_SECRET=generate_at_least_32_random_bytes\",\n      \"PORT=3001\",\n      \"\",\n    ].join(\"\\n\"),\n    local: [\n      `AGENTS24_BASE_URL=${value(options.baseUrl)}`,\n      `AGENTS24_API_KEY=${value(options.apiKey)}`,\n      `AGENTS24_ORGANIZATION_ID=${value(options.organizationId)}`,\n      `AGENTS24_PROJECT_ID=${value(options.projectId)}`,\n      `AGENTS24_AGENT_ID=${value(options.agentId)}`,\n      `AGENTS24_AGENT_VERSION_ID=${value(options.agentVersionId)}`,\n      `SESSION_COOKIE_SECRET=${value(randomBytes(32).toString(\"base64url\"))}`,\n      \"PORT=3001\",\n      \"\",\n    ].join(\"\\n\"),\n  };\n}\n\nfunction installCommand(packageManager: PackageManager): [string, string[]] {\n  if (packageManager === \"npm\") return [\"npm\", [\"install\"]];\n  if (packageManager === \"yarn\") return [\"yarn\", []];\n  if (packageManager === \"bun\") return [\"bun\", [\"install\"]];\n  return [\"pnpm\", [\"install\"]];\n}\n\nfunction runScriptCommand(packageManager: PackageManager, script: string): string {\n  if (packageManager === \"npm\") return `npm run ${script}`;\n  if (packageManager === \"bun\") return `bun run ${script}`;\n  return `${packageManager} ${script}`;\n}\n\nexport function installDependencies(directory: string, packageManager: PackageManager): void {\n  const [command, args] = installCommand(packageManager);\n  const { AGENTS24_API_KEY: _apiKey, ...installerEnvironment } = process.env;\n  const result = spawnSync(command, args, { cwd: directory, stdio: \"inherit\", env: installerEnvironment });\n  if (result.error) throw new Error(`Could not start ${command}: ${result.error.message}`);\n  if (result.status !== 0) throw new Error(`${command} ${args.join(\" \")} failed with exit ${result.status}.`);\n}\n\nexport function createApp(options: CreateAppOptions): GeneratedApp {\n  const destination = resolve(options.directory);\n  assertDestination(destination);\n  const name = packageName(destination);\n  const parent = dirname(destination);\n  mkdirSync(parent, { recursive: true });\n  const staging = join(parent, `.${name}.agents24-${randomBytes(6).toString(\"hex\")}`);\n  try {\n    mkdirSync(staging, { mode: 0o700 });\n    copyLayer(\"common\", staging);\n    copyLayer(`integrations/${options.integration}`, staging);\n    copyLayer(`themes/${options.theme}`, staging);\n    const apiOrigin = new URL(options.baseUrl).origin;\n    replaceTemplateValues(staging, {\n      \"__APP_NAME__\": name,\n      \"__THEME__\": options.theme,\n      \"__INTEGRATION__\": options.integration,\n      \"__CONNECT_SOURCE__\": options.integration === \"client-deployment\" ? apiOrigin : \"\",\n      \"__PM_DEV__\": runScriptCommand(options.packageManager, \"dev\"),\n      \"__PM_BUILD__\": runScriptCommand(options.packageManager, \"build\"),\n      \"__PM_PRODUCTION__\": runScriptCommand(options.packageManager, options.integration === \"bff\" ? \"start\" : \"preview\"),\n    });\n    const gitignore = join(staging, \"_gitignore\");\n    if (existsSync(gitignore)) renameSync(gitignore, join(staging, \".gitignore\"));\n    writeFileSync(join(staging, \"package.json\"), `${JSON.stringify(generatedManifest(options, name), null, 2)}\\n`);\n    const env = envFiles(options);\n    writeFileSync(join(staging, \".env.example\"), env.example);\n    if (options.install) installDependencies(staging, options.packageManager);\n    writeFileSync(join(staging, \".env.local\"), env.local, { mode: 0o600 });\n    chmodSync(join(staging, \".env.local\"), 0o600);\n    if (existsSync(destination)) rmSync(destination, { recursive: true });\n    renameSync(staging, destination);\n    return { directory: destination, packageName: name };\n  } catch (error) {\n    rmSync(staging, { recursive: true, force: true });\n    throw error;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/cli.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+import {
+  createApp
+} from "./chunk-OCIF3LSI.js";
+
+// src/cli.ts
+import process3 from "process";
+import { intro, outro } from "@clack/prompts";
+
+// src/arguments.ts
+import process from "process";
+var VALUE_FLAGS = /* @__PURE__ */ new Set([
+  "integration",
+  "theme",
+  "package-manager",
+  "base-url",
+  "deployment-id",
+  "agent-id",
+  "agent-version-id",
+  "organization-id",
+  "project-id"
+]);
+var BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["yes", "no-install", "help"]);
+function parseArguments(argv = process.argv.slice(2)) {
+  const flags = {};
+  let directory;
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index] || "";
+    if (!argument.startsWith("--")) {
+      if (directory) throw new Error("Only one destination directory may be provided.");
+      directory = argument;
+      continue;
+    }
+    const [rawName, inlineValue] = argument.slice(2).split("=", 2);
+    if (BOOLEAN_FLAGS.has(rawName)) {
+      if (inlineValue !== void 0) throw new Error(`--${rawName} does not accept a value.`);
+      flags[rawName] = true;
+      continue;
+    }
+    if (!VALUE_FLAGS.has(rawName)) throw new Error(`Unknown option: --${rawName}`);
+    const value = inlineValue ?? argv[index + 1];
+    if (!value || value.startsWith("--")) throw new Error(`--${rawName} requires a value.`);
+    flags[rawName] = value;
+    if (inlineValue === void 0) index += 1;
+  }
+  return { ...directory ? { directory } : {}, flags };
+}
+var HELP = `Create an Agents24 React application.
+
+Usage:
+  npm create agents24-app@latest [directory] [options]
+
+Options:
+  --integration <client-deployment|bff>
+  --theme <essential|workbench|flow>
+  --package-manager <pnpm|npm|yarn|bun>
+  --base-url <url>
+  --deployment-id <acd_...>        Client deployment mode
+  --agent-id <uuid>                BFF mode
+  --agent-version-id <uuid>        Optional pinned BFF version
+  --organization-id <uuid>         BFF mode
+  --project-id <uuid>              BFF mode
+  --no-install
+  --yes                            Disable prompts; required values must be supplied
+  --help
+
+For security, API keys are accepted only through the masked prompt or the
+AGENTS24_API_KEY environment variable.`;
+
+// src/prompts.ts
+import process2 from "process";
+import { confirm, isCancel, password, select, text } from "@clack/prompts";
+
+// src/types.ts
+var INTEGRATIONS = ["client-deployment", "bff"];
+var THEMES = ["essential", "workbench", "flow"];
+var PACKAGE_MANAGERS = ["pnpm", "npm", "yarn", "bun"];
+
+// src/prompts.ts
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var DEPLOYMENT_ID = /^acd_[A-Za-z0-9_-]{10,}$/;
+function cancelled(value) {
+  if (isCancel(value)) throw new Error("App creation cancelled.");
+}
+function flag(args, name) {
+  const value = args.flags[name];
+  return typeof value === "string" ? value.trim() : void 0;
+}
+function oneOf(value, choices, field) {
+  if (value === void 0) return void 0;
+  if (!choices.includes(value)) throw new Error(`${field} must be one of: ${choices.join(", ")}.`);
+  return value;
+}
+function detectedPackageManager() {
+  const name = String(process2.env.npm_config_user_agent || "").split("/")[0];
+  return PACKAGE_MANAGERS.includes(name) ? name : "pnpm";
+}
+function validateUrl(value) {
+  try {
+    const parsed = new URL(value);
+    if (/[\r\n\0]/.test(value) || parsed.username || parsed.password || parsed.search || parsed.hash) {
+      return "Use a base URL without credentials, query parameters, or fragments.";
+    }
+    return parsed.protocol === "https:" || parsed.protocol === "http:" && ["localhost", "127.0.0.1", "::1"].includes(parsed.hostname) ? void 0 : "Use HTTPS, or HTTP for a local development server.";
+  } catch {
+    return "Enter a valid URL.";
+  }
+}
+async function requiredText(message, initialValue, validate) {
+  const result = await text({
+    message,
+    ...initialValue ? { initialValue } : {},
+    validate(value) {
+      const normalized = String(value || "").trim();
+      return normalized ? validate?.(normalized) : "This value is required.";
+    }
+  });
+  cancelled(result);
+  return String(result).trim();
+}
+async function resolveOptions(args) {
+  const nonInteractive = args.flags.yes === true;
+  let directory = args.directory;
+  let integration = oneOf(flag(args, "integration"), INTEGRATIONS, "integration");
+  let theme = oneOf(flag(args, "theme"), THEMES, "theme");
+  let packageManager = oneOf(flag(args, "package-manager"), PACKAGE_MANAGERS, "package-manager");
+  let baseUrl = flag(args, "base-url");
+  let install = args.flags["no-install"] !== true;
+  if (!nonInteractive) {
+    directory ||= await requiredText("Where should the app be created?", "my-agents24-app");
+    if (!integration) {
+      const result = await select({ message: "How should the app connect?", options: [
+        { value: "client-deployment", label: "Client deployment", hint: "Direct anonymous browser connection" },
+        { value: "bff", label: "Server BFF", hint: "API key remains on your Node server" }
+      ] });
+      cancelled(result);
+      integration = result;
+    }
+    if (!theme) {
+      const result = await select({ message: "Choose a visual recipe", initialValue: "essential", options: [
+        { value: "essential", label: "Essential", hint: "Canonical shared-page UI" },
+        { value: "workbench", label: "Workbench", hint: "Dense and structured" },
+        { value: "flow", label: "Flow", hint: "Soft and conversational" }
+      ] });
+      cancelled(result);
+      theme = result;
+    }
+    if (!packageManager) {
+      const detected = detectedPackageManager();
+      const result = await select({ message: "Package manager", initialValue: detected, options: PACKAGE_MANAGERS.map((value) => ({ value, label: value })) });
+      cancelled(result);
+      packageManager = result;
+    }
+    baseUrl ||= await requiredText("Agents24 API URL", "https://api.agents24.dev", validateUrl);
+    if (args.flags["no-install"] !== true) {
+      const result = await confirm({ message: "Install dependencies?", initialValue: true });
+      cancelled(result);
+      install = result;
+    }
+  }
+  directory = String(directory || "").trim();
+  integration ||= "client-deployment";
+  theme ||= "essential";
+  packageManager ||= detectedPackageManager();
+  baseUrl ||= "https://api.agents24.dev";
+  const urlError = validateUrl(baseUrl);
+  if (!directory) throw new Error("A destination directory is required.");
+  if (urlError) throw new Error(urlError);
+  if (integration === "client-deployment") {
+    let deploymentId = flag(args, "deployment-id");
+    if (!deploymentId && !nonInteractive) deploymentId = await requiredText("Public deployment ID", void 0, (value) => DEPLOYMENT_ID.test(value) ? void 0 : "Use a public acd_\u2026 deployment ID.");
+    if (!deploymentId || !DEPLOYMENT_ID.test(deploymentId)) throw new Error("A valid --deployment-id (acd_\u2026) is required.");
+    return { directory, integration, theme, packageManager, install, baseUrl, deploymentId };
+  }
+  const fields = {
+    agentId: flag(args, "agent-id"),
+    agentVersionId: flag(args, "agent-version-id"),
+    organizationId: flag(args, "organization-id"),
+    projectId: flag(args, "project-id")
+  };
+  if (!nonInteractive) {
+    fields.agentId ||= await requiredText("Agent ID", void 0, (value) => UUID.test(value) ? void 0 : "Enter an Agent UUID.");
+    fields.organizationId ||= await requiredText("Organization ID", void 0, (value) => UUID.test(value) ? void 0 : "Enter an organization UUID.");
+    fields.projectId ||= await requiredText("Project ID", void 0, (value) => UUID.test(value) ? void 0 : "Enter a project UUID.");
+    if (!fields.agentVersionId) {
+      const result = await text({
+        message: "Agent version ID (optional)",
+        placeholder: "Leave blank to use latest published",
+        validate: (value) => String(value || "").trim() && !UUID.test(String(value).trim()) ? "Enter an Agent version UUID or leave blank." : void 0
+      });
+      cancelled(result);
+      fields.agentVersionId = String(result || "").trim() || void 0;
+    }
+  }
+  for (const [name, value] of Object.entries(fields)) {
+    if (name === "agentVersionId" && !value) continue;
+    if (!value || !UUID.test(value)) throw new Error(`A valid --${name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)} UUID is required.`);
+  }
+  let apiKey = String(process2.env.AGENTS24_API_KEY || "").trim();
+  if (!apiKey && !nonInteractive) {
+    const result = await password({ message: "Agents24 API key", validate: (value) => String(value || "").trim() ? void 0 : "The API key is required." });
+    cancelled(result);
+    apiKey = String(result).trim();
+  }
+  if (!apiKey) throw new Error("AGENTS24_API_KEY is required for noninteractive BFF creation.");
+  if (/[\r\n\0]/.test(apiKey)) throw new Error("AGENTS24_API_KEY contains invalid control characters.");
+  return { directory, integration, theme, packageManager, install, baseUrl, apiKey, ...fields };
+}
+
+// src/cli.ts
+function scriptCommand(packageManager, script) {
+  if (packageManager === "npm") return `npm run ${script}`;
+  if (packageManager === "bun") return `bun run ${script}`;
+  return `${packageManager} ${script}`;
+}
+async function main() {
+  const args = parseArguments();
+  if (args.flags.help) {
+    process3.stdout.write(`${HELP}
+`);
+    return;
+  }
+  intro("Create Agents24 App");
+  const options = await resolveOptions(args);
+  const generated = createApp(options);
+  const relative = generated.directory.startsWith(`${process3.cwd()}/`) ? generated.directory.slice(process3.cwd().length + 1) : generated.directory;
+  const install = `${options.packageManager} install`;
+  const productionScript = options.integration === "bff" ? "start" : "preview";
+  outro([
+    `Created ${generated.packageName}`,
+    "",
+    `  cd ${relative}`,
+    `  ${install}${options.install ? "  # already completed" : ""}`,
+    `  ${scriptCommand(options.packageManager, "dev")}`,
+    `  ${scriptCommand(options.packageManager, "build")}`,
+    `  ${scriptCommand(options.packageManager, productionScript)}`
+  ].join("\n"));
+}
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : "App creation failed.";
+  process3.stderr.write(`create-agents24-app: ${message}
+`);
+  process3.exitCode = 1;
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts","../src/arguments.ts","../src/prompts.ts","../src/types.ts"],"sourcesContent":["import process from \"node:process\";\nimport { intro, outro } from \"@clack/prompts\";\n\nimport { HELP, parseArguments } from \"./arguments.js\";\nimport { createApp } from \"./generator.js\";\nimport { resolveOptions } from \"./prompts.js\";\n\nfunction scriptCommand(packageManager: string, script: string): string {\n  if (packageManager === \"npm\") return `npm run ${script}`;\n  if (packageManager === \"bun\") return `bun run ${script}`;\n  return `${packageManager} ${script}`;\n}\n\nasync function main(): Promise<void> {\n  const args = parseArguments();\n  if (args.flags.help) {\n    process.stdout.write(`${HELP}\\n`);\n    return;\n  }\n  intro(\"Create Agents24 App\");\n  const options = await resolveOptions(args);\n  const generated = createApp(options);\n  const relative = generated.directory.startsWith(`${process.cwd()}/`)\n    ? generated.directory.slice(process.cwd().length + 1)\n    : generated.directory;\n  const install = `${options.packageManager} install`;\n  const productionScript = options.integration === \"bff\" ? \"start\" : \"preview\";\n  outro([\n    `Created ${generated.packageName}`,\n    \"\",\n    `  cd ${relative}`,\n    `  ${install}${options.install ? \"  # already completed\" : \"\"}`,\n    `  ${scriptCommand(options.packageManager, \"dev\")}`,\n    `  ${scriptCommand(options.packageManager, \"build\")}`,\n    `  ${scriptCommand(options.packageManager, productionScript)}`,\n  ].join(\"\\n\"));\n}\n\nmain().catch((error: unknown) => {\n  const message = error instanceof Error ? error.message : \"App creation failed.\";\n  process.stderr.write(`create-agents24-app: ${message}\\n`);\n  process.exitCode = 1;\n});\n","import process from \"node:process\";\n\nexport type ParsedArguments = {\n  directory?: string;\n  flags: Record<string, string | boolean>;\n};\n\nconst VALUE_FLAGS = new Set([\n  \"integration\",\n  \"theme\",\n  \"package-manager\",\n  \"base-url\",\n  \"deployment-id\",\n  \"agent-id\",\n  \"agent-version-id\",\n  \"organization-id\",\n  \"project-id\",\n]);\nconst BOOLEAN_FLAGS = new Set([\"yes\", \"no-install\", \"help\"]);\n\nexport function parseArguments(argv = process.argv.slice(2)): ParsedArguments {\n  const flags: Record<string, string | boolean> = {};\n  let directory: string | undefined;\n  for (let index = 0; index < argv.length; index += 1) {\n    const argument = argv[index] || \"\";\n    if (!argument.startsWith(\"--\")) {\n      if (directory) throw new Error(\"Only one destination directory may be provided.\");\n      directory = argument;\n      continue;\n    }\n    const [rawName, inlineValue] = argument.slice(2).split(\"=\", 2);\n    if (BOOLEAN_FLAGS.has(rawName)) {\n      if (inlineValue !== undefined) throw new Error(`--${rawName} does not accept a value.`);\n      flags[rawName] = true;\n      continue;\n    }\n    if (!VALUE_FLAGS.has(rawName)) throw new Error(`Unknown option: --${rawName}`);\n    const value = inlineValue ?? argv[index + 1];\n    if (!value || value.startsWith(\"--\")) throw new Error(`--${rawName} requires a value.`);\n    flags[rawName] = value;\n    if (inlineValue === undefined) index += 1;\n  }\n  return { ...(directory ? { directory } : {}), flags };\n}\n\nexport const HELP = `Create an Agents24 React application.\n\nUsage:\n  npm create agents24-app@latest [directory] [options]\n\nOptions:\n  --integration <client-deployment|bff>\n  --theme <essential|workbench|flow>\n  --package-manager <pnpm|npm|yarn|bun>\n  --base-url <url>\n  --deployment-id <acd_...>        Client deployment mode\n  --agent-id <uuid>                BFF mode\n  --agent-version-id <uuid>        Optional pinned BFF version\n  --organization-id <uuid>         BFF mode\n  --project-id <uuid>              BFF mode\n  --no-install\n  --yes                            Disable prompts; required values must be supplied\n  --help\n\nFor security, API keys are accepted only through the masked prompt or the\nAGENTS24_API_KEY environment variable.`;\n","import process from \"node:process\";\nimport { confirm, isCancel, password, select, text } from \"@clack/prompts\";\n\nimport type { ParsedArguments } from \"./arguments.js\";\nimport {\n  INTEGRATIONS,\n  PACKAGE_MANAGERS,\n  THEMES,\n  type CreateAppOptions,\n  type Integration,\n  type PackageManager,\n  type Theme,\n} from \"./types.js\";\n\nconst UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;\nconst DEPLOYMENT_ID = /^acd_[A-Za-z0-9_-]{10,}$/;\n\nfunction cancelled(value: unknown): asserts value is Exclude<typeof value, symbol> {\n  if (isCancel(value)) throw new Error(\"App creation cancelled.\");\n}\n\nfunction flag(args: ParsedArguments, name: string): string | undefined {\n  const value = args.flags[name];\n  return typeof value === \"string\" ? value.trim() : undefined;\n}\n\nfunction oneOf<T extends string>(value: string | undefined, choices: readonly T[], field: string): T | undefined {\n  if (value === undefined) return undefined;\n  if (!choices.includes(value as T)) throw new Error(`${field} must be one of: ${choices.join(\", \")}.`);\n  return value as T;\n}\n\nfunction detectedPackageManager(): PackageManager {\n  const name = String(process.env.npm_config_user_agent || \"\").split(\"/\")[0];\n  return PACKAGE_MANAGERS.includes(name as PackageManager) ? name as PackageManager : \"pnpm\";\n}\n\nfunction validateUrl(value: string): string | undefined {\n  try {\n    const parsed = new URL(value);\n    if (/[\\r\\n\\0]/.test(value) || parsed.username || parsed.password || parsed.search || parsed.hash) {\n      return \"Use a base URL without credentials, query parameters, or fragments.\";\n    }\n    return parsed.protocol === \"https:\" || (parsed.protocol === \"http:\" && [\"localhost\", \"127.0.0.1\", \"::1\"].includes(parsed.hostname))\n      ? undefined\n      : \"Use HTTPS, or HTTP for a local development server.\";\n  } catch { return \"Enter a valid URL.\"; }\n}\n\nasync function requiredText(message: string, initialValue: string | undefined, validate?: (value: string) => string | undefined): Promise<string> {\n  const result = await text({\n    message,\n    ...(initialValue ? { initialValue } : {}),\n    validate(value) {\n      const normalized = String(value || \"\").trim();\n      return normalized ? validate?.(normalized) : \"This value is required.\";\n    },\n  });\n  cancelled(result);\n  return String(result).trim();\n}\n\nexport async function resolveOptions(args: ParsedArguments): Promise<CreateAppOptions> {\n  const nonInteractive = args.flags.yes === true;\n  let directory = args.directory;\n  let integration = oneOf(flag(args, \"integration\"), INTEGRATIONS, \"integration\");\n  let theme = oneOf(flag(args, \"theme\"), THEMES, \"theme\");\n  let packageManager = oneOf(flag(args, \"package-manager\"), PACKAGE_MANAGERS, \"package-manager\");\n  let baseUrl = flag(args, \"base-url\");\n  let install = args.flags[\"no-install\"] !== true;\n\n  if (!nonInteractive) {\n    directory ||= await requiredText(\"Where should the app be created?\", \"my-agents24-app\");\n    if (!integration) {\n      const result = await select<Integration>({ message: \"How should the app connect?\", options: [\n        { value: \"client-deployment\", label: \"Client deployment\", hint: \"Direct anonymous browser connection\" },\n        { value: \"bff\", label: \"Server BFF\", hint: \"API key remains on your Node server\" },\n      ] });\n      cancelled(result); integration = result;\n    }\n    if (!theme) {\n      const result = await select<Theme>({ message: \"Choose a visual recipe\", initialValue: \"essential\", options: [\n        { value: \"essential\", label: \"Essential\", hint: \"Canonical shared-page UI\" },\n        { value: \"workbench\", label: \"Workbench\", hint: \"Dense and structured\" },\n        { value: \"flow\", label: \"Flow\", hint: \"Soft and conversational\" },\n      ] });\n      cancelled(result); theme = result;\n    }\n    if (!packageManager) {\n      const detected = detectedPackageManager();\n      const result = await select<PackageManager>({ message: \"Package manager\", initialValue: detected, options: PACKAGE_MANAGERS.map((value) => ({ value, label: value })) });\n      cancelled(result); packageManager = result;\n    }\n    baseUrl ||= await requiredText(\"Agents24 API URL\", \"https://api.agents24.dev\", validateUrl);\n    if (args.flags[\"no-install\"] !== true) {\n      const result = await confirm({ message: \"Install dependencies?\", initialValue: true });\n      cancelled(result); install = result;\n    }\n  }\n\n  directory = String(directory || \"\").trim();\n  integration ||= \"client-deployment\";\n  theme ||= \"essential\";\n  packageManager ||= detectedPackageManager();\n  baseUrl ||= \"https://api.agents24.dev\";\n  const urlError = validateUrl(baseUrl);\n  if (!directory) throw new Error(\"A destination directory is required.\");\n  if (urlError) throw new Error(urlError);\n\n  if (integration === \"client-deployment\") {\n    let deploymentId = flag(args, \"deployment-id\");\n    if (!deploymentId && !nonInteractive) deploymentId = await requiredText(\"Public deployment ID\", undefined, (value) => DEPLOYMENT_ID.test(value) ? undefined : \"Use a public acd_… deployment ID.\");\n    if (!deploymentId || !DEPLOYMENT_ID.test(deploymentId)) throw new Error(\"A valid --deployment-id (acd_…) is required.\");\n    return { directory, integration, theme, packageManager, install, baseUrl, deploymentId };\n  }\n\n  const fields = {\n    agentId: flag(args, \"agent-id\"),\n    agentVersionId: flag(args, \"agent-version-id\"),\n    organizationId: flag(args, \"organization-id\"),\n    projectId: flag(args, \"project-id\"),\n  };\n  if (!nonInteractive) {\n    fields.agentId ||= await requiredText(\"Agent ID\", undefined, (value) => UUID.test(value) ? undefined : \"Enter an Agent UUID.\");\n    fields.organizationId ||= await requiredText(\"Organization ID\", undefined, (value) => UUID.test(value) ? undefined : \"Enter an organization UUID.\");\n    fields.projectId ||= await requiredText(\"Project ID\", undefined, (value) => UUID.test(value) ? undefined : \"Enter a project UUID.\");\n    if (!fields.agentVersionId) {\n      const result = await text({\n        message: \"Agent version ID (optional)\",\n        placeholder: \"Leave blank to use latest published\",\n        validate: (value) => String(value || \"\").trim() && !UUID.test(String(value).trim()) ? \"Enter an Agent version UUID or leave blank.\" : undefined,\n      });\n      cancelled(result);\n      fields.agentVersionId = String(result || \"\").trim() || undefined;\n    }\n  }\n  for (const [name, value] of Object.entries(fields)) {\n    if (name === \"agentVersionId\" && !value) continue;\n    if (!value || !UUID.test(value)) throw new Error(`A valid --${name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)} UUID is required.`);\n  }\n  let apiKey = String(process.env.AGENTS24_API_KEY || \"\").trim();\n  if (!apiKey && !nonInteractive) {\n    const result = await password({ message: \"Agents24 API key\", validate: (value) => String(value || \"\").trim() ? undefined : \"The API key is required.\" });\n    cancelled(result); apiKey = String(result).trim();\n  }\n  if (!apiKey) throw new Error(\"AGENTS24_API_KEY is required for noninteractive BFF creation.\");\n  if (/[\\r\\n\\0]/.test(apiKey)) throw new Error(\"AGENTS24_API_KEY contains invalid control characters.\");\n  return { directory, integration, theme, packageManager, install, baseUrl, apiKey, ...fields } as CreateAppOptions;\n}\n","export const INTEGRATIONS = [\"client-deployment\", \"bff\"] as const;\nexport const THEMES = [\"essential\", \"workbench\", \"flow\"] as const;\nexport const PACKAGE_MANAGERS = [\"pnpm\", \"npm\", \"yarn\", \"bun\"] as const;\n\nexport type Integration = (typeof INTEGRATIONS)[number];\nexport type Theme = (typeof THEMES)[number];\nexport type PackageManager = (typeof PACKAGE_MANAGERS)[number];\n\nexport type CreateAppOptions = {\n  directory: string;\n  integration: Integration;\n  theme: Theme;\n  packageManager: PackageManager;\n  install: boolean;\n  baseUrl: string;\n  deploymentId?: string;\n  agentId?: string;\n  agentVersionId?: string;\n  organizationId?: string;\n  projectId?: string;\n  apiKey?: string;\n};\n\nexport type GeneratedApp = {\n  directory: string;\n  packageName: string;\n};\n"],"mappings":"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","names":["process","process","process","process"]}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+declare const INTEGRATIONS: readonly ["client-deployment", "bff"];
+declare const THEMES: readonly ["essential", "workbench", "flow"];
+declare const PACKAGE_MANAGERS: readonly ["pnpm", "npm", "yarn", "bun"];
+type Integration = (typeof INTEGRATIONS)[number];
+type Theme = (typeof THEMES)[number];
+type PackageManager = (typeof PACKAGE_MANAGERS)[number];
+type CreateAppOptions = {
+    directory: string;
+    integration: Integration;
+    theme: Theme;
+    packageManager: PackageManager;
+    install: boolean;
+    baseUrl: string;
+    deploymentId?: string;
+    agentId?: string;
+    agentVersionId?: string;
+    organizationId?: string;
+    projectId?: string;
+    apiKey?: string;
+};
+type GeneratedApp = {
+    directory: string;
+    packageName: string;
+};
+
+declare function installDependencies(directory: string, packageManager: PackageManager): void;
+declare function createApp(options: CreateAppOptions): GeneratedApp;
+
+export { type CreateAppOptions, type GeneratedApp, type Integration, type PackageManager, type Theme, createApp, installDependencies };

package/dist/index.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import {
+  createApp,
+  installDependencies
+} from "./chunk-OCIF3LSI.js";
+export {
+  createApp,
+  installDependencies
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "create-agents24-app",
+  "version": "0.1.0",
+  "description": "Create a production-ready Agents24 React application.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/daniel5426/talmudpedia.git",
+    "directory": "packages/create-agents24-app"
+  },
+  "type": "module",
+  "bin": {
+    "create-agents24-app": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "templates",
+    "versions.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": "^22.0.0 || ^24.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "dependencies": {
+    "@clack/prompts": "1.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.7.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "pnpm run build && node --test tests/*.test.mjs",
+    "prepack": "pnpm run build && pnpm run test"
+  }
+}

package/templates/common/README.md

@@ -0,0 +1,24 @@
+# __APP_NAME__
+
+Last Updated: 2026-07-19
+
+This app was generated by `create-agents24-app` with the `__INTEGRATION__` integration and `__THEME__` visual recipe.
+
+The app includes a strict document CSP. If you deploy the static client-deployment build without the generated BFF, configure your host to send `Content-Security-Policy: frame-ancestors 'none'`; browsers do not honor that directive in an HTML meta tag.
+
+## Development
+
+```bash
+__PM_DEV__
+```
+
+Configuration lives in `.env.local`. Commit `.env.example`, never `.env.local`.
+
+## Production
+
+```bash
+__PM_BUILD__
+__PM_PRODUCTION__
+```
+
+The chat layout comes directly from `@agents24/chat-react`; keep product-specific additions in the provided slots instead of copying the layout.

package/templates/common/_gitignore

@@ -0,0 +1,7 @@
+node_modules
+dist
+server-dist
+.env.local
+*.log
+*.tsbuildinfo
+.DS_Store

package/templates/common/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en" data-agents24-color-mode="system">
+  <head>
+    <meta charset="UTF-8" />
+    <meta content="width=device-width, initial-scale=1.0" name="viewport" />
+    <meta content="default-src 'self'; base-uri 'none'; object-src 'none'; script-src 'self'; style-src 'self'; img-src 'self' data: blob:; connect-src 'self' __CONNECT_SOURCE__ ws://127.0.0.1:* ws://localhost:*; form-action 'self'" http-equiv="Content-Security-Policy" />
+    <link href="/src/styles.css" rel="stylesheet" />
+    <title>__APP_NAME__</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script src="/src/main.tsx" type="module"></script>
+  </body>
+</html>

package/templates/common/src/styles.css

@@ -0,0 +1,7 @@
+@import "@agents24/chat-react/styles.css";
+@import "./theme.css";
+
+* { box-sizing: border-box; }
+html, body, #root { height: 100%; margin: 0; }
+body { background: var(--a24-background); color: var(--a24-text); overflow: hidden; }
+.app-shell { height: 100%; min-height: 32rem; width: 100%; }

package/templates/common/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/templates/common/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "types": ["vite/client"]
+  },
+  "include": ["src", "server", "vite.config.ts"]
+}

package/templates/integrations/bff/server/env.ts

@@ -0,0 +1,30 @@
+import process from "node:process";
+
+try { process.loadEnvFile?.(".env.local"); }
+catch (error) {
+  if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+}
+
+const REQUIRED = [
+  "AGENTS24_BASE_URL",
+  "AGENTS24_API_KEY",
+  "AGENTS24_ORGANIZATION_ID",
+  "AGENTS24_PROJECT_ID",
+  "AGENTS24_AGENT_ID",
+  "SESSION_COOKIE_SECRET",
+] as const;
+
+function required(name: (typeof REQUIRED)[number]): string {
+  const value = String(process.env[name] || "").trim();
+  if (!value) throw new Error(`${name} is required.`);
+  return value;
+}
+
+export const env = {
+  ...Object.fromEntries(REQUIRED.map((name) => [name, required(name)])) as Record<(typeof REQUIRED)[number], string>,
+  AGENTS24_AGENT_VERSION_ID: String(process.env.AGENTS24_AGENT_VERSION_ID || "").trim() || undefined,
+  PORT: Number(process.env.PORT || 3001),
+};
+
+if (!Number.isInteger(env.PORT) || env.PORT < 1 || env.PORT > 65535) throw new Error("PORT must be a valid port.");
+if (env.SESSION_COOKIE_SECRET.length < 32) throw new Error("SESSION_COOKIE_SECRET must contain at least 32 characters.");

package/templates/integrations/bff/server/index.ts

@@ -0,0 +1,44 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { serve } from "@hono/node-server";
+import { serveStatic } from "@hono/node-server/serve-static";
+import { Agents24 } from "@agents24/node";
+import { createAgents24BffHandler } from "@agents24/node/bff";
+import { Hono } from "hono";
+
+import { env } from "./env.js";
+import { resolveAgents24Principal, revokeAgents24Principal } from "./principal.js";
+
+const client = new Agents24({
+  baseUrl: env.AGENTS24_BASE_URL,
+  apiKey: env.AGENTS24_API_KEY,
+  organizationId: env.AGENTS24_ORGANIZATION_ID,
+  projectId: env.AGENTS24_PROJECT_ID,
+});
+const agents24 = createAgents24BffHandler({
+  client,
+  agentId: env.AGENTS24_AGENT_ID,
+  agentVersionId: env.AGENTS24_AGENT_VERSION_ID,
+  resolvePrincipal: resolveAgents24Principal,
+  revokePrincipal: (request) => revokeAgents24Principal(request),
+});
+const app = new Hono();
+
+app.use("*", async (context, next) => {
+  await next();
+  context.header("Referrer-Policy", "no-referrer");
+  context.header("Content-Security-Policy", "frame-ancestors 'none'");
+  context.header("X-Content-Type-Options", "nosniff");
+  context.header("X-Frame-Options", "DENY");
+});
+app.all("/api/agents24", (context) => agents24(context.req.raw));
+app.all("/api/agents24/*", (context) => agents24(context.req.raw));
+
+if (process.argv.includes("--production") || process.env.NODE_ENV === "production") {
+  app.use("*", serveStatic({ root: "./dist" }));
+  app.get("*", async (context) => context.html(await readFile(resolve("dist/index.html"), "utf8")));
+}
+
+serve({ fetch: app.fetch, hostname: "127.0.0.1", port: env.PORT }, (info) => {
+  process.stdout.write(`Agents24 app listening on http://127.0.0.1:${info.port}\n`);
+});

package/templates/integrations/bff/server/principal.ts

@@ -0,0 +1,51 @@
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import type { AgentBffPrincipalResolution } from "@agents24/node/bff";
+
+import { env } from "./env.js";
+
+const COOKIE = "agents24_app_session";
+const MAX_AGE = 60 * 60 * 24 * 30;
+
+function signature(value: string): string {
+  return createHmac("sha256", env.SESSION_COOKIE_SECRET).update(value).digest("base64url");
+}
+
+function parseCookies(request: Request): Record<string, string> {
+  return Object.fromEntries(String(request.headers.get("cookie") || "").split(";").flatMap((part) => {
+    const pivot = part.indexOf("=");
+    if (pivot < 1) return [];
+    return [[part.slice(0, pivot).trim(), decodeURIComponent(part.slice(pivot + 1).trim())]];
+  }));
+}
+
+function verifiedId(value: string | undefined): string | null {
+  const pivot = String(value || "").lastIndexOf(".");
+  if (pivot < 1) return null;
+  const id = String(value).slice(0, pivot);
+  const supplied = Buffer.from(String(value).slice(pivot + 1));
+  const expected = Buffer.from(signature(id));
+  return supplied.length === expected.length && timingSafeEqual(supplied, expected) ? id : null;
+}
+
+function secure(request: Request): boolean {
+  return request.headers.get("x-forwarded-proto")?.split(",")[0]?.trim() === "https" || new URL(request.url).protocol === "https:";
+}
+
+function cookie(value: string, request: Request, maxAge = MAX_AGE): string {
+  return `${COOKIE}=${encodeURIComponent(value)}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${maxAge}${secure(request) ? "; Secure" : ""}`;
+}
+
+// Replace this function with your application session lookup. Never accept a
+// user ID supplied by browser request data.
+export function resolveAgents24Principal(request: Request): AgentBffPrincipalResolution {
+  const existing = verifiedId(parseCookies(request)[COOKIE]);
+  const externalUserId = existing || randomUUID();
+  return {
+    principal: { externalUserId, externalSessionId: externalUserId },
+    ...(existing ? {} : { responseHeaders: { "Set-Cookie": cookie(`${externalUserId}.${signature(externalUserId)}`, request) } }),
+  };
+}
+
+export function revokeAgents24Principal(request: Request): HeadersInit {
+  return { "Set-Cookie": cookie("", request, 0) };
+}

package/templates/integrations/bff/src/main.tsx

@@ -0,0 +1,26 @@
+import { AgentChatAppearanceControl, AgentChatApp } from "@agents24/chat-react/templates";
+import { createBffAgentClient } from "@agents24/client/bff";
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+
+const client = createBffAgentClient({ basePath: "/api/agents24" });
+
+function App() {
+  return (
+    <div className="app-shell" data-agents24-theme="__THEME__">
+      <AgentChatApp
+        allowAttachments
+        client={client}
+        completeMcpAuthorization={async ({ completion, serverId }) => {
+          if (completion.serverId !== serverId || !completion.connectionId) {
+            throw new Error("MCP authorization did not return the expected connection.");
+          }
+        }}
+        mcpRedirectUri={window.location.href}
+        slots={{ headerActions: <AgentChatAppearanceControl /> }}
+      />
+    </div>
+  );
+}
+
+createRoot(document.getElementById("root")!).render(<StrictMode><App /></StrictMode>);

package/templates/integrations/bff/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "types": ["vite/client", "node"]
+  },
+  "include": ["src", "server", "vite.config.ts"]
+}

package/templates/integrations/bff/vite.config.ts

@@ -0,0 +1,10 @@
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    host: "127.0.0.1",
+    proxy: { "/api/agents24": "http://127.0.0.1:3001" },
+  },
+});

package/templates/integrations/client-deployment/src/main.tsx

@@ -0,0 +1,31 @@
+import { AgentChatAppearanceControl, AgentChatApp } from "@agents24/chat-react/templates";
+import { createAnonymousSessionProvider } from "@agents24/client";
+import { createBrowserAgentClient } from "@agents24/client/browser";
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+
+const baseUrl = String(import.meta.env.VITE_AGENTS24_BASE_URL || "").trim();
+const deploymentId = String(import.meta.env.VITE_AGENTS24_DEPLOYMENT_ID || "").trim();
+
+if (!baseUrl) throw new Error("VITE_AGENTS24_BASE_URL is required.");
+if (!/^acd_[A-Za-z0-9_-]{10,}$/.test(deploymentId)) {
+  throw new Error("VITE_AGENTS24_DEPLOYMENT_ID must be a public acd_… deployment ID.");
+}
+
+const sessionProvider = createAnonymousSessionProvider({ baseUrl, deploymentId });
+const client = createBrowserAgentClient({ baseUrl, deploymentId, sessionProvider });
+
+function App() {
+  return (
+    <div className="app-shell" data-agents24-theme="__THEME__">
+      <AgentChatApp
+        allowAttachments
+        client={client}
+        mcpRedirectUri={window.location.href}
+        slots={{ headerActions: <AgentChatAppearanceControl /> }}
+      />
+    </div>
+  );
+}
+
+createRoot(document.getElementById("root")!).render(<StrictMode><App /></StrictMode>);

package/templates/integrations/client-deployment/vite.config.ts

@@ -0,0 +1,7 @@
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [react()],
+  server: { host: "127.0.0.1" },
+});

package/templates/themes/essential/src/theme.css

@@ -0,0 +1,2 @@
+/* Essential is the exact canonical Agents24 shared-page presentation. */
+[data-agents24-theme="essential"] { isolation: isolate; }

package/templates/themes/flow/src/theme.css

@@ -0,0 +1,60 @@
+[data-agents24-theme="flow"] {
+  --a24-background: #fbfaf7;
+  --a24-surface: #f0eee8;
+  --a24-surface-hover: #e8e4dc;
+  --a24-text: #252a27;
+  --a24-muted: #60675f;
+  --a24-border: rgba(55, 63, 58, .13);
+  --a24-accent: #315648;
+  --a24-accent-text: #f8fbf8;
+  --a24-focus: #668276;
+  --a24-font-family: Charter, "Bitstream Charter", "Iowan Old Style", Georgia, serif;
+  isolation: isolate;
+}
+
+:root[data-agents24-color-mode="dark"] [data-agents24-theme="flow"] {
+  --a24-background: #151916;
+  --a24-surface: #1d231f;
+  --a24-surface-hover: #283029;
+  --a24-text: #edf1ec;
+  --a24-muted: #a2aba3;
+  --a24-border: rgba(237, 241, 236, .13);
+  --a24-accent: #b9d5c6;
+  --a24-accent-text: #17231d;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-agents24-color-mode="light"]) [data-agents24-theme="flow"] {
+    --a24-background: #151916;
+    --a24-surface: #1d231f;
+    --a24-surface-hover: #283029;
+    --a24-text: #edf1ec;
+    --a24-muted: #a2aba3;
+    --a24-border: rgba(237, 241, 236, .13);
+    --a24-accent: #b9d5c6;
+    --a24-accent-text: #17231d;
+  }
+}
+
+[data-agents24-theme="flow"] .a24-chat { grid-template-columns: 17.5rem minmax(0, 1fr); }
+[data-agents24-theme="flow"] .a24-header { min-height: 4.5rem; }
+[data-agents24-theme="flow"] .a24-shell__content { gap: 2.4rem; max-width: 50rem; }
+[data-agents24-theme="flow"] .a24-shell__composer-inner,
+[data-agents24-theme="flow"] .a24-shell__empty-composer { max-width: 50rem; }
+[data-agents24-theme="flow"] .a24-thread,
+[data-agents24-theme="flow"] .a24-button,
+[data-agents24-theme="flow"] .a24-icon-button,
+[data-agents24-theme="flow"] .a24-search { border-radius: .8rem; }
+[data-agents24-theme="flow"] .a24-composer__surface { border-radius: 1.35rem; box-shadow: 0 14px 42px rgba(42, 53, 47, .1), 0 2px 7px rgba(42, 53, 47, .07); }
+[data-agents24-theme="flow"] .a24-composer__surface[data-expanded] { border-radius: 1.15rem; }
+[data-agents24-theme="flow"] .a24-chat .is-user > :is([data-slot="message-content"], [data-slot="bubble-content"]) { border-radius: 1rem 1rem .3rem 1rem; }
+[data-agents24-theme="flow"] .a24-scroller__item { animation: a24-flow-enter 260ms ease-out both; }
+
+@keyframes a24-flow-enter {
+  from { opacity: 0; transform: translateY(.35rem); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-agents24-theme="flow"] .a24-scroller__item { animation: none; }
+}

package/templates/themes/workbench/src/theme.css

@@ -0,0 +1,51 @@
+[data-agents24-theme="workbench"] {
+  --a24-background: #fcfcfb;
+  --a24-surface: #f0f1ef;
+  --a24-surface-hover: #e5e7e4;
+  --a24-text: #171a18;
+  --a24-muted: #626963;
+  --a24-border: rgba(23, 26, 24, .16);
+  --a24-accent: #1f3d32;
+  --a24-accent-text: #ffffff;
+  --a24-focus: #53665d;
+  --a24-font-family: "Avenir Next", Avenir, "Segoe UI", sans-serif;
+  isolation: isolate;
+}
+
+:root[data-agents24-color-mode="dark"] [data-agents24-theme="workbench"] {
+  --a24-background: #111412;
+  --a24-surface: #191d1a;
+  --a24-surface-hover: #232925;
+  --a24-text: #eef1ee;
+  --a24-muted: #9ca69f;
+  --a24-border: rgba(238, 241, 238, .14);
+  --a24-accent: #d7e7dd;
+  --a24-accent-text: #152019;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-agents24-color-mode="light"]) [data-agents24-theme="workbench"] {
+    --a24-background: #111412;
+    --a24-surface: #191d1a;
+    --a24-surface-hover: #232925;
+    --a24-text: #eef1ee;
+    --a24-muted: #9ca69f;
+    --a24-border: rgba(238, 241, 238, .14);
+    --a24-accent: #d7e7dd;
+    --a24-accent-text: #152019;
+  }
+}
+
+[data-agents24-theme="workbench"] .a24-chat { grid-template-columns: 18rem minmax(0, 1fr); }
+[data-agents24-theme="workbench"] .a24-sidebar__inner { padding: .625rem; }
+[data-agents24-theme="workbench"] .a24-header { min-height: 3.5rem; padding-block: .4rem; }
+[data-agents24-theme="workbench"] .a24-thread,
+[data-agents24-theme="workbench"] .a24-button,
+[data-agents24-theme="workbench"] .a24-icon-button,
+[data-agents24-theme="workbench"] .a24-search { border-radius: .35rem; }
+[data-agents24-theme="workbench"] .a24-shell__content { gap: 1.5rem; max-width: 54rem; padding-top: 2rem; }
+[data-agents24-theme="workbench"] .a24-shell__composer-inner,
+[data-agents24-theme="workbench"] .a24-shell__empty-composer { max-width: 54rem; }
+[data-agents24-theme="workbench"] .a24-composer__surface,
+[data-agents24-theme="workbench"] .a24-composer__surface[data-expanded] { border-radius: .65rem; box-shadow: 0 2px 8px rgba(0,0,0,.06); }
+[data-agents24-theme="workbench"] .a24-chat .is-user > :is([data-slot="message-content"], [data-slot="bubble-content"]) { border-radius: .35rem; }

package/versions.json

@@ -0,0 +1,24 @@
+{
+  "agents24": {
+    "@agents24/client": "^0.2.0",
+    "@agents24/react": "^0.2.0",
+    "@agents24/chat-react": "^0.5.0",
+    "@agents24/node": "^0.2.0"
+  },
+  "runtime": {
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "hono": "^4.12.31",
+    "@hono/node-server": "^2.0.10"
+  },
+  "development": {
+    "@types/node": "^24.7.2",
+    "@types/react": "^19.2.3",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.3",
+    "concurrently": "^10.0.3",
+    "tsx": "^4.23.1",
+    "typescript": "^5.9.3",
+    "vite": "^8.1.5"
+  }
+}