@better-openclaw/core 1.0.26 → 1.0.31

package/dist/zeroclaw-B-0TuOfZ.d.mts

@@ -0,0 +1,7 @@
+import { t as AgentFrameworkDefinition } from "./types-DbXajvYq.mjs";
+
+//#region src/frameworks/zeroclaw.d.ts
+declare const zeroclawFramework: AgentFrameworkDefinition;
+//#endregion
+export { zeroclawFramework as t };
+//# sourceMappingURL=zeroclaw-B-0TuOfZ.d.mts.map

package/dist/zeroclaw-B-0TuOfZ.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zeroclaw-B-0TuOfZ.d.mts","names":[],"sources":["../src/frameworks/zeroclaw.ts"],"mappings":";;;cAuBa,iBAAA,EAAmB,wBAAA"}

package/dist/zeroclaw-BvKpDHKe.d.cts

@@ -0,0 +1,7 @@
+import { t as AgentFrameworkDefinition } from "./types-DIsPc-hb.cjs";
+
+//#region src/frameworks/zeroclaw.d.ts
+declare const zeroclawFramework: AgentFrameworkDefinition;
+//#endregion
+export { zeroclawFramework as t };
+//# sourceMappingURL=zeroclaw-BvKpDHKe.d.cts.map

package/dist/zeroclaw-BvKpDHKe.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zeroclaw-BvKpDHKe.d.cts","names":[],"sources":["../src/frameworks/zeroclaw.ts"],"mappings":";;;cAuBa,iBAAA,EAAmB,wBAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-openclaw/core",
-  "version": "1.0.26",
+  "version": "1.0.31",
   "private": false,
   "description": "Core logic for better-openclaw: schemas, service registry, resolver, composer, validators and generators",
   "author": "bidew.io <bachir@bidew.io>",
@@ -12,7 +12,11 @@
   },
   "homepage": "https://better-openclaw.dev",
   "packageManager": "pnpm@10.30.3",
-  "sideEffects": false,
+  "sideEffects": [
+    "./src/frameworks/index.ts",
+    "./dist/index.mjs",
+    "./dist/index.cjs"
+  ],
   "main": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "type": "module",

package/src/addon-stack.test.ts

@@ -1,5 +1,5 @@
-import { parse } from "yaml";
 import { describe, expect, it } from "vitest";
+import { parse } from "yaml";
 import { generateAddonStack, updateAddonStack } from "./addon-stack.js";
 import { AddonStackInputSchema } from "./schema.js";
 
@@ -83,7 +83,7 @@ describe("generateAddonStack", () => {
 		// Password should be non-empty (48 hex chars = 24 bytes)
 		const match = result.envFile.match(/N8N_DB_PASSWORD=([a-f0-9]+)/);
 		expect(match).not.toBeNull();
-		expect(match![1].length).toBe(48);
+		expect(match?.[1].length).toBe(48);
 	});
 
 	it("gracefully handles unknown service IDs without throwing", () => {
@@ -131,8 +131,8 @@ describe("generateAddonStack", () => {
 
 		const n8nRoute = result.proxyRoutes.find((r) => r.serviceId === "n8n");
 		expect(n8nRoute).toBeDefined();
-		expect(n8nRoute!.path).toBe("/n8n");
-		expect(n8nRoute!.port).toBe(5678);
+		expect(n8nRoute?.path).toBe("/n8n");
+		expect(n8nRoute?.port).toBe(5678);
 	});
 
 	it("generates skill files and openclaw config patch", () => {
@@ -155,11 +155,9 @@ describe("generateAddonStack", () => {
 
 		// Port should be reassigned
 		const portAssignments = result.metadata.portAssignments;
-		const n8nAssignment = Object.entries(portAssignments).find(([key]) =>
-			key.startsWith("n8n:"),
-		);
+		const n8nAssignment = Object.entries(portAssignments).find(([key]) => key.startsWith("n8n:"));
 		expect(n8nAssignment).toBeDefined();
-		expect(n8nAssignment![1]).not.toBe(5678);
+		expect(n8nAssignment?.[1]).not.toBe(5678);
 	});
 
 	it("sanitizes project name from instanceId", () => {
@@ -211,9 +209,9 @@ describe("generateAddonStack", () => {
 		// MEILI_MASTER_KEY should be a base64url string of at least 32 chars (24 bytes)
 		const match = result.envFile.match(/MEILI_MASTER_KEY=([^\n]+)/);
 		expect(match).not.toBeNull();
-		expect(match![1].length).toBeGreaterThanOrEqual(32);
+		expect(match?.[1].length).toBeGreaterThanOrEqual(32);
 		// Should not be empty
-		expect(match![1]).not.toBe("");
+		expect(match?.[1]).not.toBe("");
 	});
 
 	it("applies env quirks to envFile output (grafana GF_SECURITY_ADMIN_PASSWORD)", () => {
@@ -226,7 +224,7 @@ describe("generateAddonStack", () => {
 		const match = result.envFile.match(/GF_SECURITY_ADMIN_PASSWORD=([^\n]+)/);
 		expect(match).not.toBeNull();
 		// Should be at least 22 chars (16 bytes base64url)
-		expect(match![1].length).toBeGreaterThanOrEqual(22);
+		expect(match?.[1].length).toBeGreaterThanOrEqual(22);
 	});
 
 	it("syncs DB_POSTGRESDB_PASSWORD with N8N_DB_PASSWORD via must_sync quirk", () => {
@@ -241,7 +239,7 @@ describe("generateAddonStack", () => {
 		expect(n8nDbPw).not.toBeNull();
 		expect(dbPostgresPw).not.toBeNull();
 		// Both passwords must match due to must_sync quirk
-		expect(n8nDbPw![1]).toBe(dbPostgresPw![1]);
+		expect(n8nDbPw?.[1]).toBe(dbPostgresPw?.[1]);
 	});
 
 	it("syncs user-provided credential with DB password reference", () => {
@@ -270,11 +268,9 @@ describe("generateAddonStack", () => {
 
 		// n8n should still get its default port (no conflict with qdrant)
 		const portAssignments = result.metadata.portAssignments;
-		const n8nAssignment = Object.entries(portAssignments).find(([key]) =>
-			key.startsWith("n8n:"),
-		);
+		const n8nAssignment = Object.entries(portAssignments).find(([key]) => key.startsWith("n8n:"));
 		expect(n8nAssignment).toBeDefined();
-		expect(n8nAssignment![1]).toBe(5678);
+		expect(n8nAssignment?.[1]).toBe(5678);
 	});
 
 	it("does not dual-list GPU services in both skipped and resolved", () => {
@@ -341,7 +337,7 @@ describe("generateAddonStack", () => {
 		const match = result.envFile.match(/OPEN_SANDBOX_API_KEY=([^\n]+)/);
 		expect(match).not.toBeNull();
 		// 32 bytes base64url ≈ 43 chars
-		expect(match![1].length).toBeGreaterThanOrEqual(43);
+		expect(match?.[1].length).toBeGreaterThanOrEqual(43);
 	});
 
 	it("generates code-sandbox skill file and config patch", () => {
@@ -372,8 +368,8 @@ describe("generateAddonStack", () => {
 
 		const route = result.proxyRoutes.find((r) => r.serviceId === "opensandbox");
 		expect(route).toBeDefined();
-		expect(route!.path).toBe("/sandbox");
-		expect(route!.port).toBe(8080);
+		expect(route?.path).toBe("/sandbox");
+		expect(route?.port).toBe(8080);
 	});
 
 	it("generates sandbox.toml in additionalFiles", () => {
@@ -384,11 +380,11 @@ describe("generateAddonStack", () => {
 
 		expect(result.additionalFiles).toHaveProperty("sandbox.toml");
 		const toml = result.additionalFiles["sandbox.toml"];
-		expect(toml).toContain('[server]');
+		expect(toml).toContain("[server]");
 		expect(toml).toContain('api_key = "${OPEN_SANDBOX_API_KEY}"');
-		expect(toml).toContain('[runtime]');
-		expect(toml).toContain('[docker]');
-		expect(toml).toContain('[secure_runtime]');
+		expect(toml).toContain("[runtime]");
+		expect(toml).toContain("[docker]");
+		expect(toml).toContain("[secure_runtime]");
 		expect(toml).toContain('type = "gvisor"');
 	});
 

package/src/addon-stack.ts

@@ -1,7 +1,8 @@
 import { randomBytes } from "node:crypto";
-import { stringify } from "yaml";
-import { parse as parseYaml } from "yaml";
-import { buildCompanionService, buildPostgresSetup, quotedStr, YAML_OPTIONS } from "./composer.js";
+import { parse as parseYaml, stringify } from "yaml";
+import { buildCompanionService, quotedStr, YAML_OPTIONS } from "./composer.js";
+import { getFrameworkById } from "./frameworks/index.js";
+import type { AgentFrameworkDefinition } from "./frameworks/types.js";
 import { getDbRequirements } from "./generators/postgres-init.js";
 import { generateSkillFiles } from "./generators/skills.js";
 import { resolve } from "./resolver.js";
@@ -22,33 +23,30 @@ import type {
 
 // ── Constants ────────────────────────────────────────────────────────────────
 
-/** Services that Clawexa's cloud-init already provisions (or are mandatory platform services). */
-const INFRA_SERVICE_IDS = new Set([
-	"openclaw-gateway",
-	"openclaw-cli",
+/** Base infrastructure service IDs that Clawexa's cloud-init provisions. */
+const BASE_INFRA_SERVICE_IDS = [
 	"redis",
 	"postgresql",
 	"open-webui",
 	"caddy",
 	"traefik",
 	"postgres-setup",
-	// Mandatory platform services provisioned by Clawexa cloud-init
-	"convex",
-	"convex-dashboard",
-	"mission-control",
-]);
+];
+
+/** Build the full set of infra IDs for a given framework. */
+function getInfraServiceIds(framework: AgentFrameworkDefinition): Set<string> {
+	return new Set([
+		`${framework.id}-gateway`,
+		`${framework.id}-cli`,
+		...BASE_INFRA_SERVICE_IDS,
+		...framework.getMandatoryServices(),
+	]);
+}
 
 /** Env keys managed by Clawexa's cloud-init — never include in addon env output. */
 const CLAWEXA_MANAGED_ENV_KEYS = new Set([
 	"COMPOSE_FILE",
 	"COMPOSE_PROFILES",
-	"OPENCLAW_VERSION",
-	"OPENCLAW_GATEWAY_TOKEN",
-	"OPENCLAW_GATEWAY_PORT",
-	"OPENCLAW_BRIDGE_PORT",
-	"OPENCLAW_GATEWAY_BIND",
-	"OPENCLAW_CONFIG_DIR",
-	"OPENCLAW_WORKSPACE_DIR",
 	"REDIS_PASSWORD",
 	"REDIS_HOST",
 	"REDIS_PORT",
@@ -59,16 +57,31 @@ const CLAWEXA_MANAGED_ENV_KEYS = new Set([
 	"POSTGRES_PORT",
 ]);
 
+/** Build the full set of managed env keys for a given framework. */
+function getManagedEnvKeys(framework: AgentFrameworkDefinition): Set<string> {
+	const keys = new Set(CLAWEXA_MANAGED_ENV_KEYS);
+	for (const envLine of framework.getBaseEnvVars({
+		generateSecrets: false,
+		frameworkVersion: "latest",
+		frameworkImageVariant: "official",
+	})) {
+		keys.add(envLine.key);
+	}
+	return keys;
+}
+
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
 /** Sanitize instanceId into a valid Docker Compose project name. */
 function sanitizeProjectName(instanceId: string): string {
-	return instanceId
-		.toLowerCase()
-		.replace(/[^a-z0-9-]/g, "-")
-		.replace(/^-+|-+$/g, "")
-		.replace(/-{2,}/g, "-")
-		.slice(0, 64) || "addon";
+	return (
+		instanceId
+			.toLowerCase()
+			.replace(/[^a-z0-9-]/g, "-")
+			.replace(/^-+|-+$/g, "")
+			.replace(/-{2,}/g, "-")
+			.slice(0, 64) || "addon"
+	);
 }
 
 /** Generate a cryptographically secure hex secret of the given byte length. */
@@ -221,8 +234,8 @@ function resolvePortConflicts(
 			if (userOverride) {
 				usedPorts.add(userOverride);
 				assignments[`${def.id}:${port.container}`] = userOverride;
-				if (!overrides[def.id]) overrides[def.id] = {};
-				overrides[def.id][String(port.host)] = userOverride;
+				overrides[def.id] ??= {};
+				overrides[def.id]![String(port.host)] = userOverride;
 				continue;
 			}
 
@@ -233,8 +246,8 @@ function resolvePortConflicts(
 				while (usedPorts.has(assignedPort)) {
 					assignedPort++;
 				}
-				if (!overrides[def.id]) overrides[def.id] = {};
-				overrides[def.id][String(port.host)] = assignedPort;
+				overrides[def.id] ??= {};
+				overrides[def.id]![String(port.host)] = assignedPort;
 			}
 			usedPorts.add(assignedPort);
 			assignments[`${def.id}:${port.container}`] = assignedPort;
@@ -270,9 +283,14 @@ export function generateAddonStack(rawInput: AddonStackInput): AddonStackResult
 
 	const projectName = sanitizeProjectName(input.instanceId);
 
+	// Resolve framework for this addon stack (defaults to openclaw)
+	const framework = getFrameworkById("openclaw")!;
+	const infraIds = getInfraServiceIds(framework);
+	const managedKeys = getManagedEnvKeys(framework);
+
 	// 2. Filter out infrastructure service IDs from request
 	const addonServiceIds = input.services.filter((id) => {
-		if (INFRA_SERVICE_IDS.has(id)) {
+		if (infraIds.has(id)) {
 			warnings.push(`Service "${id}" is managed by Clawexa infrastructure and was excluded.`);
 			return false;
 		}
@@ -340,7 +358,7 @@ export function generateAddonStack(rawInput: AddonStackInput): AddonStackResult
 	// 5. Filter resolved services: keep only addon services (not infra)
 	const addonResolved: ResolvedService[] = [];
 	for (const svc of resolved.services) {
-		if (INFRA_SERVICE_IDS.has(svc.definition.id)) continue;
+		if (infraIds.has(svc.definition.id)) continue;
 		addonResolved.push(svc);
 	}
 
@@ -478,7 +496,7 @@ export function generateAddonStack(rawInput: AddonStackInput): AddonStackResult
 			if (entry.depends_on) {
 				const deps = entry.depends_on as Record<string, { condition: string }>;
 				for (const depId of Object.keys(deps)) {
-					if (INFRA_SERVICE_IDS.has(depId)) {
+					if (infraIds.has(depId)) {
 						delete deps[depId];
 					}
 				}
@@ -506,7 +524,7 @@ export function generateAddonStack(rawInput: AddonStackInput): AddonStackResult
 						envVar.defaultValue?.endsWith("}")
 					) {
 						const refKey = envVar.defaultValue.slice(2, -1);
-						envValues.set(refKey, userCreds[envVar.key]);
+						envValues.set(refKey, userCreds[envVar.key]!);
 					}
 				}
 			}
@@ -516,7 +534,9 @@ export function generateAddonStack(rawInput: AddonStackInput): AddonStackResult
 				reason: "resolution_error",
 				details: `Failed to build compose entry: ${err instanceof Error ? err.message : String(err)}`,
 			});
-			warnings.push(`Failed to process service "${def.name}": ${err instanceof Error ? err.message : String(err)}`);
+			warnings.push(
+				`Failed to process service "${def.name}": ${err instanceof Error ? err.message : String(err)}`,
+			);
 		}
 	}
 
@@ -561,7 +581,7 @@ export function generateAddonStack(rawInput: AddonStackInput): AddonStackResult
 			entrypoint: ["/bin/sh", "-c"],
 			command: [scriptLines.join("\n")],
 			restart: quotedStr("no"),
-			networks: ["openclaw-network"],
+			networks: [framework.networkName],
 		};
 
 		// Update addon services that need DB to depend on postgres-setup
@@ -592,14 +612,16 @@ export function generateAddonStack(rawInput: AddonStackInput): AddonStackResult
 			const secretValue = input.generateSecrets ? generateHexSecret(24) : "";
 			envValues.set(req.passwordEnvVar, secretValue);
 			if (secretValue) generatedSecretKeys.push(req.passwordEnvVar);
-			envLines.push(`# PostgreSQL password for ${req.serviceName} (db: ${req.dbName}, user: ${req.dbUser})`);
+			envLines.push(
+				`# PostgreSQL password for ${req.serviceName} (db: ${req.dbName}, user: ${req.dbUser})`,
+			);
 			envLines.push(`${req.passwordEnvVar}=${secretValue}`);
 			envLines.push("");
 		}
 	}
 
 	// Per-service env vars
-	const seenKeys = new Set<string>([...CLAWEXA_MANAGED_ENV_KEYS, ...dbReqs.map((r) => r.passwordEnvVar)]);
+	const seenKeys = new Set<string>([...managedKeys, ...dbReqs.map((r) => r.passwordEnvVar)]);
 	const envVarGroups: AddonStackResult["envVars"] = [];
 
 	for (const svc of deployableServices) {
@@ -688,7 +710,7 @@ export function generateAddonStack(rawInput: AddonStackInput): AddonStackResult
 	}
 	// Append any new keys introduced by quirks (e.g., must_sync creating a new key)
 	for (const [key, value] of envValues) {
-		if (!quirkedKeys.has(key) && !seenKeys.has(key) && !CLAWEXA_MANAGED_ENV_KEYS.has(key)) {
+		if (!quirkedKeys.has(key) && !seenKeys.has(key) && !managedKeys.has(key)) {
 			finalEnvLines.push(`# Synced by env quirk`);
 			finalEnvLines.push(`${key}=${value}`);
 			finalEnvLines.push("");
@@ -729,7 +751,7 @@ export function generateAddonStack(rawInput: AddonStackInput): AddonStackResult
 			'execd_image = "opensandbox/execd:v1.0.6"',
 			"",
 			"[docker]",
-			"network_mode = \"bridge\"",
+			'network_mode = "bridge"',
 			'drop_capabilities = ["NET_ADMIN", "SYS_ADMIN", "SYS_PTRACE", "MKNOD", "NET_RAW", "SYS_RAWIO"]',
 			"no_new_privileges = true",
 			"pids_limit = 512",
@@ -773,7 +795,7 @@ export function generateAddonStack(rawInput: AddonStackInput): AddonStackResult
 	}
 
 	composeDoc.networks = {
-		"openclaw-network": {
+		[framework.networkName]: {
 			external: true,
 		},
 	};
@@ -851,7 +873,6 @@ export function updateAddonStack(rawInput: AddonStackUpdateInput): AddonStackUpd
 	}
 
 	// 4. Compute desired service list
-	const addSet = new Set(input.addServices);
 	const removeSet = new Set(input.removeServices);
 	const desiredServiceIds = [
 		...currentServiceIds.filter((id) => !removeSet.has(id)),
@@ -865,10 +886,12 @@ export function updateAddonStack(rawInput: AddonStackUpdateInput): AddonStackUpd
 		skillPacks: [],
 		platform: input.platform,
 		openclawVersion: input.openclawVersion,
+		existingServices: input.existingServices,
 		reservedPorts: input.reservedPorts,
 		generateSecrets: input.generateSecrets,
 		credentials: input.credentials,
 		portOverrides: input.portOverrides,
+		gpu: input.gpu,
 		aiProviders: input.aiProviders,
 		prebuiltImages: input.prebuiltImages,
 	});
@@ -911,10 +934,10 @@ export function updateAddonStack(rawInput: AddonStackUpdateInput): AddonStackUpd
 		const def = getServiceById(id);
 		if (!def) continue;
 		for (const skill of def.skills) {
-			const skillPath = Object.keys(targetResult.skillFiles).find(
-				(path) => path.includes(skill.skillId),
+			const skillPath = Object.keys(targetResult.skillFiles).find((path) =>
+				path.includes(skill.skillId),
 			);
-			if (skillPath) {
+			if (skillPath && targetResult.skillFiles[skillPath]) {
 				newSkillFiles[skillPath] = targetResult.skillFiles[skillPath];
 			}
 		}

package/src/composer.test.ts

@@ -223,4 +223,63 @@ describe("compose", () => {
 		const serviceKeys = Object.keys(parsed.services);
 		expect(serviceKeys[0]).toBe("openclaw-gateway");
 	});
+
+	// ── Multi-framework tests ──────────────────────────────────────────────
+
+	it("generates zeroclaw-gateway when primaryFramework is zeroclaw", () => {
+		const resolved = resolve({ services: ["redis"], skillPacks: [], primaryFramework: "zeroclaw" });
+		const yaml = compose(resolved, {
+			...defaultOptions,
+			primaryFramework: "zeroclaw",
+		});
+		const parsed = parse(yaml);
+
+		// Should have zeroclaw-gateway, NOT openclaw-gateway
+		expect(parsed.services).toHaveProperty("zeroclaw-gateway");
+		expect(parsed.services).not.toHaveProperty("openclaw-gateway");
+		expect(parsed.services).not.toHaveProperty("openclaw-cli");
+
+		// Network should be zeroclaw-network
+		expect(parsed.networks).toHaveProperty("zeroclaw-network");
+		expect(parsed.services.redis.networks).toContain("zeroclaw-network");
+	});
+
+	it("generates claude-code-gateway when primaryFramework is claude-code", () => {
+		const resolved = resolve({ services: [], skillPacks: [], primaryFramework: "claude-code" });
+		const yaml = compose(resolved, {
+			...defaultOptions,
+			primaryFramework: "claude-code",
+		});
+		const parsed = parse(yaml);
+
+		expect(parsed.services).toHaveProperty("claude-code-gateway");
+		expect(parsed.networks).toHaveProperty("claude-code-network");
+	});
+
+	it("does NOT include convex/mission-control in non-openclaw framework stacks", () => {
+		const resolved = resolve({ services: ["redis"], skillPacks: [], primaryFramework: "copaw" });
+		const yaml = compose(resolved, {
+			...defaultOptions,
+			primaryFramework: "copaw",
+		});
+		const parsed = parse(yaml);
+
+		expect(parsed.services).not.toHaveProperty("convex");
+		expect(parsed.services).not.toHaveProperty("mission-control");
+		expect(parsed.services).not.toHaveProperty("tailscale");
+	});
+
+	it("adds companion framework containers", () => {
+		const resolved = resolve({ services: ["redis"], skillPacks: [] });
+		const yaml = compose(resolved, {
+			...defaultOptions,
+			companionFrameworks: ["claude-code"],
+		});
+		const parsed = parse(yaml);
+
+		// Primary should still be openclaw
+		expect(parsed.services).toHaveProperty("openclaw-gateway");
+		// Companion should exist
+		expect(parsed.services).toHaveProperty("claude-code-companion");
+	});
 });