@better-openclaw/core 1.0.26 → 1.0.31

package/src/frameworks/frameworks.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, it } from "vitest";
+import { parse } from "yaml";
+import { generate } from "../generate.js";
+import { getAllFrameworks, getFrameworkById } from "./registry.js";
+
+/**
+ * Smoke tests for all registered framework definitions.
+ *
+ * Each framework's buildGatewayService, generateConfig, and getBaseEnvVars
+ * should produce valid output when invoked through the generate() pipeline.
+ */
+
+describe("framework smoke tests via generate()", () => {
+	const primaryFrameworks = getAllFrameworks().filter((fw) => fw.canBePrimary);
+
+	for (const fw of primaryFrameworks) {
+		describe(`${fw.name} (${fw.id})`, () => {
+			it("generates a valid stack with this framework as primary", () => {
+				const result = generate({
+					projectName: `${fw.id}-test`,
+					services: ["redis"],
+					skillPacks: [],
+					proxy: "none",
+					gpu: false,
+					platform: "linux/amd64",
+					deployment: "local",
+					generateSecrets: true,
+					openclawVersion: "latest",
+					primaryFramework: fw.id,
+				});
+
+				expect(result.files).toHaveProperty("docker-compose.yml");
+				const composed = parse(result.files["docker-compose.yml"]!);
+				expect(composed.services).toBeDefined();
+
+				// Gateway service should exist with the framework's naming pattern
+				const gatewayKey = `${fw.id}-gateway`;
+				expect(composed.services).toHaveProperty(gatewayKey);
+			});
+
+			it("produces a docker-compose with the framework's network", () => {
+				const result = generate({
+					projectName: `${fw.id}-net-test`,
+					services: ["redis"],
+					skillPacks: [],
+					proxy: "none",
+					gpu: false,
+					platform: "linux/amd64",
+					deployment: "local",
+					generateSecrets: true,
+					openclawVersion: "latest",
+					primaryFramework: fw.id,
+				});
+
+				const composed = parse(result.files["docker-compose.yml"]!);
+				if (fw.networkName) {
+					expect(composed.networks).toHaveProperty(fw.networkName);
+				}
+			});
+
+			it("getBaseEnvVars returns an array", () => {
+				const envVars = fw.getBaseEnvVars({
+					generateSecrets: true,
+					domain: "example.com",
+				});
+				expect(envVars).toBeInstanceOf(Array);
+			});
+
+			it("getMandatoryServices returns an array", () => {
+				const mandatory = fw.getMandatoryServices();
+				expect(mandatory).toBeInstanceOf(Array);
+			});
+
+			it("getRecommendedServices returns an array", () => {
+				const recommended = fw.getRecommendedServices();
+				expect(recommended).toBeInstanceOf(Array);
+			});
+
+			it("getEnvSectionName returns a non-empty string", () => {
+				const section = fw.getEnvSectionName();
+				expect(typeof section).toBe("string");
+				expect(section.length).toBeGreaterThan(0);
+			});
+
+			it("getProviderEnvKeys returns an array", () => {
+				const keys = fw.getProviderEnvKeys();
+				expect(keys).toBeInstanceOf(Array);
+			});
+		});
+	}
+});
+
+describe("companion frameworks via generate()", () => {
+	const companionFrameworks = getAllFrameworks().filter((fw) => fw.canBeCompanion);
+
+	for (const fw of companionFrameworks) {
+		it(`${fw.name} can be added as companion`, () => {
+			const result = generate({
+				projectName: `companion-${fw.id}-test`,
+				services: ["redis"],
+				skillPacks: [],
+				proxy: "none",
+				gpu: false,
+				platform: "linux/amd64",
+				deployment: "local",
+				generateSecrets: true,
+				openclawVersion: "latest",
+				companionFrameworks: [fw.id],
+			});
+
+			const composed = parse(result.files["docker-compose.yml"]!);
+			expect(composed.services).toBeDefined();
+
+			// Companion should appear in compose
+			const companionKey = `${fw.id}-companion`;
+			expect(composed.services).toHaveProperty(companionKey);
+		});
+	}
+});

package/src/frameworks/index.ts

@@ -0,0 +1,46 @@
+export { claudeCodeFramework } from "./claude-code-fw.js";
+export { codexFramework } from "./codex-fw.js";
+export { copawFramework } from "./copaw.js";
+export { memuFramework } from "./memu.js";
+export { nanobotFramework } from "./nanobot.js";
+export { nanoclawFramework } from "./nanoclaw.js";
+export { openclawFramework } from "./openclaw.js";
+export {
+	getAllFrameworks,
+	getCompanionFrameworks,
+	getFrameworkById,
+	getPrimaryFrameworks,
+	registerFramework,
+} from "./registry.js";
+export type {
+	AgentFrameworkDefinition,
+	AgentFrameworkId,
+	EnvLine,
+	FrameworkComposeOptions,
+	FrameworkConfigOptions,
+	FrameworkConfigResult,
+	FrameworkEnvOptions,
+	GatewayBuildResult,
+} from "./types.js";
+export { zeroclawFramework } from "./zeroclaw.js";
+
+// ── Auto-register built-in frameworks ───────────────────────────────────────
+
+import { claudeCodeFramework } from "./claude-code-fw.js";
+import { codexFramework } from "./codex-fw.js";
+import { copawFramework } from "./copaw.js";
+import { memuFramework } from "./memu.js";
+import { nanobotFramework } from "./nanobot.js";
+import { nanoclawFramework } from "./nanoclaw.js";
+import { openclawFramework } from "./openclaw.js";
+import { registerFramework } from "./registry.js";
+import { zeroclawFramework } from "./zeroclaw.js";
+
+registerFramework(openclawFramework);
+registerFramework(copawFramework);
+registerFramework(nanoclawFramework);
+registerFramework(nanobotFramework);
+registerFramework(zeroclawFramework);
+registerFramework(memuFramework);
+registerFramework(claudeCodeFramework);
+registerFramework(codexFramework);

package/src/frameworks/memu.ts

@@ -0,0 +1,149 @@
+import type { ResolverOutput } from "../types.js";
+import type {
+	AgentFrameworkDefinition,
+	EnvLine,
+	FrameworkComposeOptions,
+	FrameworkConfigOptions,
+	FrameworkConfigResult,
+	FrameworkEnvOptions,
+	GatewayBuildResult,
+} from "./types.js";
+
+const IMAGE_VARIANTS: Record<string, string> = {
+	official: "nevamindai/memu-server",
+};
+
+function getMemuImage(_variant: string, version: string): string {
+	const base = IMAGE_VARIANTS.official;
+	const tag = version !== "latest" ? version : "latest";
+	return `${base}:${tag}`;
+}
+
+const PROVIDER_ENV_KEYS = ["OPENAI_API_KEY", "OPENROUTER_API_KEY"];
+
+export const memuFramework: AgentFrameworkDefinition = {
+	id: "memu",
+	name: "MemU",
+	icon: "🧠",
+	description: "Persistent knowledge graph memory agent backed by pgvector",
+	runtime: "python",
+	canBePrimary: true,
+	canBeCompanion: true,
+	networkName: "memu-network",
+	imageVariants: IMAGE_VARIANTS,
+	defaultImageVariant: "official",
+
+	buildGatewayService(
+		resolved: ResolverOutput,
+		options: FrameworkComposeOptions,
+		dependsOn?: Record<string, { condition: string }>,
+	): GatewayBuildResult {
+		const allVolumes = new Set<string>();
+		const defaultImage = getMemuImage(
+			options.frameworkImageVariant ?? "official",
+			options.frameworkVersion,
+		);
+
+		const gatewayEnv: Record<string, string> = {
+			OPENAI_API_KEY: "${OPENAI_API_KEY}",
+			OPENROUTER_API_KEY: "${OPENROUTER_API_KEY:-}",
+			DATABASE_URL:
+				"postgresql://${MEMU_DB_USER:-memu}:${MEMU_DB_PASSWORD}@postgresql:5432/${MEMU_DB_NAME:-memu}",
+		};
+
+		// Collect env vars from companion services
+		for (const { definition: def } of resolved.services) {
+			for (const env of def.openclawEnvVars) {
+				gatewayEnv[env.key] = env.secret ? `\${${env.key}}` : env.defaultValue;
+			}
+		}
+
+		// Ensure postgresql dependency
+		const deps = { ...dependsOn };
+		deps.postgresql = { condition: "service_healthy" };
+
+		const gateway: Record<string, unknown> = {
+			image: `\${MEMU_IMAGE:-${defaultImage}}`,
+			environment: gatewayEnv,
+			volumes: ["${MEMU_DATA_DIR:-./memu/data}:/app/data"],
+			ports: ["${MEMU_PORT:-8020}:8000"],
+			networks: [this.networkName],
+			restart: "unless-stopped",
+			depends_on: deps,
+			healthcheck: {
+				test: ["CMD", "curl", "-sf", "http://localhost:8000/health", "||", "exit", "1"],
+				interval: "30s",
+				timeout: "5s",
+				retries: 5,
+				start_period: "30s",
+			},
+		};
+
+		return { gatewayService: gateway, cliService: null, allVolumes };
+	},
+
+	generateConfig(
+		_resolved: ResolverOutput,
+		_options: FrameworkConfigOptions,
+	): FrameworkConfigResult | null {
+		// MemU uses environment-based config
+		return null;
+	},
+
+	getBaseEnvVars(_options: FrameworkEnvOptions): EnvLine[] {
+		return [
+			{
+				comment: "MemU Docker image override",
+				key: "MEMU_IMAGE",
+				exampleValue: "",
+				actualValue: "",
+			},
+			{
+				comment: "MemU REST API port",
+				key: "MEMU_PORT",
+				exampleValue: "8020",
+				actualValue: "8020",
+			},
+			{
+				comment: "MemU PostgreSQL database name",
+				key: "MEMU_DB_NAME",
+				exampleValue: "memu",
+				actualValue: "memu",
+			},
+			{
+				comment: "MemU PostgreSQL user",
+				key: "MEMU_DB_USER",
+				exampleValue: "memu",
+				actualValue: "memu",
+			},
+			{
+				comment: "MemU PostgreSQL password",
+				key: "MEMU_DB_PASSWORD",
+				exampleValue: "changeme",
+				actualValue: "",
+			},
+			{
+				comment: "Host path to MemU data directory",
+				key: "MEMU_DATA_DIR",
+				exampleValue: "./memu/data",
+				actualValue: "./memu/data",
+			},
+		];
+	},
+
+	getMandatoryServices(): string[] {
+		return ["postgresql"];
+	},
+
+	getRecommendedServices(): string[] {
+		return [];
+	},
+
+	getProviderEnvKeys(): string[] {
+		return [...PROVIDER_ENV_KEYS];
+	},
+
+	getEnvSectionName(): string {
+		return "MemU Core";
+	},
+};

package/src/frameworks/nanobot.ts

@@ -0,0 +1,156 @@
+import type { ResolverOutput } from "../types.js";
+import type {
+	AgentFrameworkDefinition,
+	EnvLine,
+	FrameworkComposeOptions,
+	FrameworkConfigOptions,
+	FrameworkConfigResult,
+	FrameworkEnvOptions,
+	GatewayBuildResult,
+} from "./types.js";
+
+const IMAGE_VARIANTS: Record<string, string> = {
+	official: "smanx/nanobot",
+	birdxs: "birdxs/nanobot",
+};
+
+function getNanobotImage(variant: string, version: string): string {
+	const base = IMAGE_VARIANTS[variant] ?? IMAGE_VARIANTS.official;
+	const tag = version !== "latest" ? version : "latest";
+	return `${base}:${tag}`;
+}
+
+const PROVIDER_ENV_KEYS = [
+	"OPENAI_API_KEY",
+	"ANTHROPIC_API_KEY",
+	"OPENROUTER_API_KEY",
+	"DEEPSEEK_API_KEY",
+	"MISTRAL_API_KEY",
+];
+
+export const nanobotFramework: AgentFrameworkDefinition = {
+	id: "nanobot",
+	name: "NanoBot",
+	icon: "🤏",
+	description: "Ultra-lightweight ~4K-line Python agent with 11 providers and 11 channels",
+	runtime: "python",
+	canBePrimary: true,
+	canBeCompanion: true,
+	networkName: "nanobot-network",
+	imageVariants: IMAGE_VARIANTS,
+	defaultImageVariant: "official",
+
+	buildGatewayService(
+		resolved: ResolverOutput,
+		options: FrameworkComposeOptions,
+		dependsOn?: Record<string, { condition: string }>,
+	): GatewayBuildResult {
+		const allVolumes = new Set<string>();
+		const defaultImage = getNanobotImage(
+			options.frameworkImageVariant ?? "official",
+			options.frameworkVersion,
+		);
+
+		const gatewayEnv: Record<string, string> = {};
+		for (const key of PROVIDER_ENV_KEYS) {
+			gatewayEnv[key] = `\${${key}}`;
+		}
+
+		// Collect env vars from companion services
+		for (const { definition: def } of resolved.services) {
+			for (const env of def.openclawEnvVars) {
+				gatewayEnv[env.key] = env.secret ? `\${${env.key}}` : env.defaultValue;
+			}
+		}
+
+		const gateway: Record<string, unknown> = {
+			image: `\${NANOBOT_IMAGE:-${defaultImage}}`,
+			environment: gatewayEnv,
+			volumes: ["${NANOBOT_CONFIG_DIR:-./nanobot/config}:/root/.nanobot"],
+			ports: ["${NANOBOT_GATEWAY_PORT:-18790}:18790"],
+			networks: [this.networkName],
+			restart: "unless-stopped",
+			deploy: {
+				resources: {
+					limits: { cpus: "1", memory: "1G" },
+					reservations: { cpus: "0.25", memory: "256M" },
+				},
+			},
+			healthcheck: {
+				test: ["CMD", "curl", "-sf", "http://localhost:18790/health", "||", "exit", "1"],
+				interval: "30s",
+				timeout: "5s",
+				retries: 3,
+				start_period: "15s",
+			},
+		};
+
+		if (dependsOn && Object.keys(dependsOn).length > 0) {
+			gateway.depends_on = dependsOn;
+		}
+
+		// CLI service for one-off commands
+		const cliService: Record<string, unknown> = {
+			image: `\${NANOBOT_IMAGE:-${defaultImage}}`,
+			environment: gatewayEnv,
+			volumes: ["${NANOBOT_CONFIG_DIR:-./nanobot/config}:/root/.nanobot"],
+			networks: [this.networkName],
+			profiles: ["cli"],
+			command: ["agent", "-m", "Hello!"],
+		};
+
+		return { gatewayService: gateway, cliService, allVolumes };
+	},
+
+	generateConfig(
+		_resolved: ResolverOutput,
+		_options: FrameworkConfigOptions,
+	): FrameworkConfigResult | null {
+		// NanoBot uses ~/.nanobot/config.json, generated via `nanobot init`
+		return null;
+	},
+
+	getBaseEnvVars(options: FrameworkEnvOptions): EnvLine[] {
+		const defaultImage = getNanobotImage(
+			options.frameworkImageVariant ?? "official",
+			options.frameworkVersion,
+		);
+
+		return [
+			{
+				comment: "NanoBot Docker image override",
+				key: "NANOBOT_IMAGE",
+				exampleValue: defaultImage,
+				actualValue: "",
+			},
+			{
+				comment: "NanoBot gateway port",
+				key: "NANOBOT_GATEWAY_PORT",
+				exampleValue: "18790",
+				actualValue: "18790",
+			},
+			{
+				comment: "Host path to NanoBot configuration directory",
+				key: "NANOBOT_CONFIG_DIR",
+				exampleValue: "./nanobot/config",
+				actualValue: "./nanobot/config",
+			},
+		];
+	},
+
+	getMandatoryServices(): string[] {
+		return [];
+	},
+
+	getRecommendedServices(): string[] {
+		return [];
+	},
+
+	getProviderEnvKeys(): string[] {
+		return [...PROVIDER_ENV_KEYS];
+	},
+
+	getEnvSectionName(): string {
+		return "NanoBot Core";
+	},
+};

package/src/frameworks/nanoclaw.ts

@@ -0,0 +1,126 @@
+import type { ResolverOutput } from "../types.js";
+import type {
+	AgentFrameworkDefinition,
+	EnvLine,
+	FrameworkComposeOptions,
+	FrameworkConfigOptions,
+	FrameworkConfigResult,
+	FrameworkEnvOptions,
+	GatewayBuildResult,
+} from "./types.js";
+
+const IMAGE_VARIANTS: Record<string, string> = {
+	official: "node",
+};
+
+const PROVIDER_ENV_KEYS = ["ANTHROPIC_API_KEY"];
+
+export const nanoclawFramework: AgentFrameworkDefinition = {
+	id: "nanoclaw",
+	name: "NanoClaw",
+	icon: "🔒",
+	description: "Security-first containerized agent with per-task isolation",
+	runtime: "node",
+	canBePrimary: true,
+	canBeCompanion: true,
+	networkName: "nanoclaw-network",
+	imageVariants: IMAGE_VARIANTS,
+	defaultImageVariant: "official",
+
+	buildGatewayService(
+		_resolved: ResolverOutput,
+		_options: FrameworkComposeOptions,
+		dependsOn?: Record<string, { condition: string }>,
+	): GatewayBuildResult {
+		const allVolumes = new Set<string>();
+
+		const gatewayEnv: Record<string, string> = {
+			ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY}",
+			ASSISTANT_NAME: "${NANOCLAW_ASSISTANT_NAME:-Andy}",
+			CONTAINER_IMAGE: "${NANOCLAW_CONTAINER_IMAGE:-nanoclaw-agent:latest}",
+			MAX_CONCURRENT_CONTAINERS: "${NANOCLAW_MAX_CONTAINERS:-5}",
+		};
+
+		const gateway: Record<string, unknown> = {
+			build: {
+				context: ".",
+				dockerfile: "Dockerfile",
+			},
+			image: "nanoclaw:latest",
+			environment: gatewayEnv,
+			volumes: [
+				"${NANOCLAW_STORE_DIR:-./nanoclaw/store}:/app/store",
+				"${NANOCLAW_GROUPS_DIR:-./nanoclaw/groups}:/app/groups",
+				"/var/run/docker.sock:/var/run/docker.sock",
+			],
+			networks: [this.networkName],
+			restart: "unless-stopped",
+			command: ["node", "dist/index.js"],
+		};
+
+		if (dependsOn && Object.keys(dependsOn).length > 0) {
+			gateway.depends_on = dependsOn;
+		}
+
+		return { gatewayService: gateway, cliService: null, allVolumes };
+	},
+
+	generateConfig(
+		_resolved: ResolverOutput,
+		_options: FrameworkConfigOptions,
+	): FrameworkConfigResult | null {
+		// NanoClaw uses .env file only, no config files
+		return null;
+	},
+
+	getBaseEnvVars(_options: FrameworkEnvOptions): EnvLine[] {
+		return [
+			{
+				comment: "NanoClaw bot display name",
+				key: "NANOCLAW_ASSISTANT_NAME",
+				exampleValue: "Andy",
+				actualValue: "Andy",
+			},
+			{
+				comment: "Agent container image for ephemeral task containers",
+				key: "NANOCLAW_CONTAINER_IMAGE",
+				exampleValue: "nanoclaw-agent:latest",
+				actualValue: "nanoclaw-agent:latest",
+			},
+			{
+				comment: "Maximum parallel agent containers",
+				key: "NANOCLAW_MAX_CONTAINERS",
+				exampleValue: "5",
+				actualValue: "5",
+			},
+			{
+				comment: "Host path to NanoClaw SQLite store",
+				key: "NANOCLAW_STORE_DIR",
+				exampleValue: "./nanoclaw/store",
+				actualValue: "./nanoclaw/store",
+			},
+			{
+				comment: "Host path to NanoClaw group workspaces",
+				key: "NANOCLAW_GROUPS_DIR",
+				exampleValue: "./nanoclaw/groups",
+				actualValue: "./nanoclaw/groups",
+			},
+		];
+	},
+
+	getMandatoryServices(): string[] {
+		return [];
+	},
+
+	getRecommendedServices(): string[] {
+		return [];
+	},
+
+	getProviderEnvKeys(): string[] {
+		return [...PROVIDER_ENV_KEYS];
+	},
+
+	getEnvSectionName(): string {
+		return "NanoClaw Core";
+	},
+};