@better-openclaw/core 1.0.26 → 1.0.31

package/src/deployers/coolify.ts

@@ -151,6 +151,11 @@ export class CoolifyDeployer implements PaasDeployer {
 	}
 
 	async deploy(input: DeployInput): Promise<DeployResult> {
+		input.logger?.info("deployment", `Starting deployment to Coolify`, {
+			projectName: input.projectName,
+			instanceUrl: input.target.instanceUrl,
+		});
+
 		const step1: DeployStep = { step: "Discover server", status: "pending" };
 		const step2: DeployStep = {
 			step: "Find or create project",
@@ -318,6 +323,29 @@ export class CoolifyDeployer implements PaasDeployer {
 
 			result.dashboardUrl = `${base}/project/${project.uuid}`;
 
+			input.logger?.log({
+				level: "info",
+				category: "deployment",
+				message: `Deployment to Coolify succeeded`,
+				outcome: "success",
+				context: {
+					projectId: project.uuid,
+					serviceId: service.uuid,
+					dashboardUrl: result.dashboardUrl,
+				},
+				steps: steps.map((s) => ({
+					name: s.step,
+					status:
+						s.status === "done"
+							? ("success" as const)
+							: s.status === "error"
+								? ("failure" as const)
+								: ("in_progress" as const),
+					detail: s.detail,
+					startedAt: new Date().toISOString(),
+				})),
+			});
+
 			return result;
 		} catch (err) {
 			const running = steps.find((s) => s.status === "running");
@@ -329,6 +357,16 @@ export class CoolifyDeployer implements PaasDeployer {
 
 			result.error = err instanceof Error ? err.message : String(err);
 
+			input.logger?.error(
+				"deployment",
+				`Deployment to Coolify failed`,
+				err instanceof Error ? err : null,
+				{
+					projectName: input.projectName,
+					failedStep: running?.step,
+				},
+			);
+
 			return result;
 		}
 	}

package/src/deployers/dokploy.test.ts

@@ -0,0 +1,120 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+describe("DokployDeployer", () => {
+	beforeEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("can be imported and instantiated", async () => {
+		const { DokployDeployer } = await import("./dokploy.js");
+		const deployer = new DokployDeployer();
+		expect(deployer.name).toBe("Dokploy");
+		expect(deployer.id).toBe("dokploy");
+	});
+
+	it("testConnection returns error on network failure", async () => {
+		vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("ECONNREFUSED")));
+		const { DokployDeployer } = await import("./dokploy.js");
+		const deployer = new DokployDeployer();
+		const result = await deployer.testConnection({
+			instanceUrl: "https://dokploy.example.com",
+			apiKey: "test-key",
+		});
+		expect(result.ok).toBe(false);
+		expect(result.error).toContain("ECONNREFUSED");
+		vi.unstubAllGlobals();
+	});
+
+	it("testConnection returns ok when project list succeeds", async () => {
+		vi.stubGlobal(
+			"fetch",
+			vi.fn().mockResolvedValue({
+				ok: true,
+				text: () => Promise.resolve("[]"),
+			}),
+		);
+		const { DokployDeployer } = await import("./dokploy.js");
+		const deployer = new DokployDeployer();
+		const result = await deployer.testConnection({
+			instanceUrl: "https://dokploy.example.com",
+			apiKey: "test-key",
+		});
+		expect(result.ok).toBe(true);
+		vi.unstubAllGlobals();
+	});
+
+	it("listServers returns empty array on API failure", async () => {
+		vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("Not found")));
+		const { DokployDeployer } = await import("./dokploy.js");
+		const deployer = new DokployDeployer();
+		const servers = await deployer.listServers({
+			instanceUrl: "https://dokploy.example.com",
+			apiKey: "test-key",
+		});
+		expect(servers).toEqual([]);
+		vi.unstubAllGlobals();
+	});
+
+	it("listServers maps server fields correctly", async () => {
+		vi.stubGlobal(
+			"fetch",
+			vi.fn().mockResolvedValue({
+				ok: true,
+				text: () =>
+					Promise.resolve(
+						JSON.stringify([
+							{ serverId: "s1", name: "Production", ipAddress: "1.2.3.4" },
+							{ serverId: "s2", name: "Staging", ipAddress: "5.6.7.8" },
+						]),
+					),
+			}),
+		);
+		const { DokployDeployer } = await import("./dokploy.js");
+		const deployer = new DokployDeployer();
+		const servers = await deployer.listServers({
+			instanceUrl: "https://dokploy.example.com",
+			apiKey: "test-key",
+		});
+		expect(servers).toHaveLength(2);
+		expect(servers[0]).toEqual({ id: "s1", name: "Production", ip: "1.2.3.4" });
+		expect(servers[1]).toEqual({ id: "s2", name: "Staging", ip: "5.6.7.8" });
+		vi.unstubAllGlobals();
+	});
+
+	it("deploy sets error on running step when an API call fails", async () => {
+		let callCount = 0;
+		vi.stubGlobal(
+			"fetch",
+			vi.fn().mockImplementation(() => {
+				callCount++;
+				if (callCount === 1) {
+					// project.all succeeds
+					return Promise.resolve({
+						ok: true,
+						text: () => Promise.resolve("[]"),
+					});
+				}
+				// project.create fails
+				return Promise.resolve({
+					ok: false,
+					status: 500,
+					text: () => Promise.resolve('{"message":"Internal error"}'),
+				});
+			}),
+		);
+		const { DokployDeployer } = await import("./dokploy.js");
+		const deployer = new DokployDeployer();
+		const result = await deployer.deploy({
+			target: { instanceUrl: "https://dokploy.example.com", apiKey: "key" },
+			projectName: "test",
+			composeYaml: "version: '3'",
+			envContent: "",
+		});
+		expect(result.success).toBe(false);
+		expect(result.error).toBeDefined();
+		// At least one step should be in error state
+		const errorStep = result.steps.find((s) => s.status === "error");
+		expect(errorStep).toBeDefined();
+		vi.unstubAllGlobals();
+	});
+});

package/src/deployers/dokploy.ts

@@ -139,6 +139,11 @@ export class DokployDeployer implements PaasDeployer {
 	}
 
 	async deploy(input: DeployInput): Promise<DeployResult> {
+		input.logger?.info("deployment", `Starting deployment to Dokploy`, {
+			projectName: input.projectName,
+			instanceUrl: input.target.instanceUrl,
+		});
+
 		const step1: DeployStep = {
 			step: "Find or create project",
 			status: "pending",
@@ -309,6 +314,29 @@ export class DokployDeployer implements PaasDeployer {
 
 			result.dashboardUrl = `${base}/dashboard/project/${project.projectId}/environment/${env.environmentId}/services/compose/${stack?.composeId}?tab=deployments`;
 
+			input.logger?.log({
+				level: "info",
+				category: "deployment",
+				message: `Deployment to Dokploy succeeded`,
+				outcome: "success",
+				context: {
+					projectId: project.projectId,
+					composeId: stack?.composeId,
+					dashboardUrl: result.dashboardUrl,
+				},
+				steps: steps.map((s) => ({
+					name: s.step,
+					status:
+						s.status === "done"
+							? ("success" as const)
+							: s.status === "error"
+								? ("failure" as const)
+								: ("in_progress" as const),
+					detail: s.detail,
+					startedAt: new Date().toISOString(),
+				})),
+			});
+
 			return result;
 		} catch (err) {
 			const running = steps.find((s) => s.status === "running");
@@ -321,6 +349,16 @@ export class DokployDeployer implements PaasDeployer {
 
 			result.error = err instanceof Error ? err.message : String(err);
 
+			input.logger?.error(
+				"deployment",
+				`Deployment to Dokploy failed`,
+				err instanceof Error ? err : null,
+				{
+					projectName: input.projectName,
+					failedStep: running?.step,
+				},
+			);
+
 			return result;
 		}
 	}

package/src/deployers/types.ts

@@ -35,6 +35,8 @@ export interface DeployInput {
 	description?: string;
 	/** Optional server ID to deploy to (for PaaS platforms managing multiple servers) */
 	serverId?: string;
+	/** Optional operations logger for persistent audit logging */
+	logger?: import("../logger/logger.js").OperationsLogger;
 }
 
 /** Step-level status for deploy progress. */

package/src/frameworks/claude-code-fw.ts

@@ -0,0 +1,118 @@
+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: "ghcr.io/zeeno-atl/claude-code",
+};
+
+function getClaudeCodeImage(_variant: string, version: string): string {
+	const base = IMAGE_VARIANTS.official;
+	const tag = version !== "latest" ? version : "1.0";
+	return `${base}:${tag}`;
+}
+
+const PROVIDER_ENV_KEYS = ["ANTHROPIC_API_KEY"];
+
+export const claudeCodeFramework: AgentFrameworkDefinition = {
+	id: "claude-code",
+	name: "Claude Code",
+	icon: "🟣",
+	description: "Anthropic's agentic coding assistant with full codebase understanding",
+	runtime: "node",
+	canBePrimary: true,
+	canBeCompanion: true,
+	networkName: "claude-code-network",
+	imageVariants: IMAGE_VARIANTS,
+	defaultImageVariant: "official",
+
+	buildGatewayService(
+		_resolved: ResolverOutput,
+		options: FrameworkComposeOptions,
+		dependsOn?: Record<string, { condition: string }>,
+	): GatewayBuildResult {
+		const allVolumes = new Set<string>();
+		const defaultImage = getClaudeCodeImage(
+			options.frameworkImageVariant ?? "official",
+			options.frameworkVersion,
+		);
+
+		const gatewayEnv: Record<string, string> = {
+			ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY}",
+		};
+
+		const gateway: Record<string, unknown> = {
+			image: `\${CLAUDE_CODE_IMAGE:-${defaultImage}}`,
+			environment: gatewayEnv,
+			volumes: [
+				"${CLAUDE_CODE_CONFIG_DIR:-./claude-code/config}:/home/coder/.claude",
+				"${CLAUDE_CODE_WORKSPACE_DIR:-./claude-code/workspace}:/workspace",
+			],
+			networks: [this.networkName],
+			restart: "unless-stopped",
+			stdin_open: true,
+			tty: true,
+			command: "tail -f /dev/null",
+		};
+
+		if (dependsOn && Object.keys(dependsOn).length > 0) {
+			gateway.depends_on = dependsOn;
+		}
+
+		return { gatewayService: gateway, cliService: null, allVolumes };
+	},
+
+	generateConfig(
+		_resolved: ResolverOutput,
+		_options: FrameworkConfigOptions,
+	): FrameworkConfigResult | null {
+		// Claude Code uses env-based config
+		return null;
+	},
+
+	getBaseEnvVars(_options: FrameworkEnvOptions): EnvLine[] {
+		return [
+			{
+				comment: "Claude Code Docker image override",
+				key: "CLAUDE_CODE_IMAGE",
+				exampleValue: "",
+				actualValue: "",
+			},
+			{
+				comment: "Host path to Claude Code config directory",
+				key: "CLAUDE_CODE_CONFIG_DIR",
+				exampleValue: "./claude-code/config",
+				actualValue: "./claude-code/config",
+			},
+			{
+				comment: "Host path to Claude Code workspace directory",
+				key: "CLAUDE_CODE_WORKSPACE_DIR",
+				exampleValue: "./claude-code/workspace",
+				actualValue: "./claude-code/workspace",
+			},
+		];
+	},
+
+	getMandatoryServices(): string[] {
+		return [];
+	},
+
+	getRecommendedServices(): string[] {
+		return [];
+	},
+
+	getProviderEnvKeys(): string[] {
+		return [...PROVIDER_ENV_KEYS];
+	},
+
+	getEnvSectionName(): string {
+		return "Claude Code Core";
+	},
+};

package/src/frameworks/codex-fw.ts

@@ -0,0 +1,102 @@
+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 = ["OPENAI_API_KEY"];
+
+export const codexFramework: AgentFrameworkDefinition = {
+	id: "codex",
+	name: "OpenAI Codex CLI",
+	icon: "🟢",
+	description: "OpenAI's lightweight coding agent with sandboxed execution",
+	runtime: "node",
+	canBePrimary: true,
+	canBeCompanion: true,
+	networkName: "codex-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> = {
+			OPENAI_API_KEY: "${OPENAI_API_KEY}",
+		};
+
+		const gateway: Record<string, unknown> = {
+			image: "node:24-alpine",
+			environment: gatewayEnv,
+			volumes: [
+				"${CODEX_CONFIG_DIR:-./codex/config}:/home/node/.codex",
+				"${CODEX_WORKSPACE_DIR:-./codex/workspace}:/workspace",
+			],
+			networks: [this.networkName],
+			restart: "unless-stopped",
+			stdin_open: true,
+			tty: true,
+			command: "npx @openai/codex@latest --headless",
+		};
+
+		if (dependsOn && Object.keys(dependsOn).length > 0) {
+			gateway.depends_on = dependsOn;
+		}
+
+		return { gatewayService: gateway, cliService: null, allVolumes };
+	},
+
+	generateConfig(
+		_resolved: ResolverOutput,
+		_options: FrameworkConfigOptions,
+	): FrameworkConfigResult | null {
+		// Codex uses env-based config
+		return null;
+	},
+
+	getBaseEnvVars(_options: FrameworkEnvOptions): EnvLine[] {
+		return [
+			{
+				comment: "Host path to Codex config directory",
+				key: "CODEX_CONFIG_DIR",
+				exampleValue: "./codex/config",
+				actualValue: "./codex/config",
+			},
+			{
+				comment: "Host path to Codex workspace directory",
+				key: "CODEX_WORKSPACE_DIR",
+				exampleValue: "./codex/workspace",
+				actualValue: "./codex/workspace",
+			},
+		];
+	},
+
+	getMandatoryServices(): string[] {
+		return [];
+	},
+
+	getRecommendedServices(): string[] {
+		return [];
+	},
+
+	getProviderEnvKeys(): string[] {
+		return [...PROVIDER_ENV_KEYS];
+	},
+
+	getEnvSectionName(): string {
+		return "Codex Core";
+	},
+};

package/src/frameworks/copaw.ts

@@ -0,0 +1,154 @@
+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: "agentscope/copaw",
+	pre: "agentscope/copaw",
+};
+
+function getCopawImage(variant: string, _version: string): string {
+	const base = IMAGE_VARIANTS[variant] ?? IMAGE_VARIANTS.official;
+	const tag = variant === "pre" ? "pre" : "latest";
+	return `${base}:${tag}`;
+}
+
+const PROVIDER_ENV_KEYS = [
+	"DASHSCOPE_API_KEY",
+	"OPENAI_API_KEY",
+	"ANTHROPIC_API_KEY",
+	"GOOGLE_API_KEY",
+	"DEEPSEEK_API_KEY",
+	"GROQ_API_KEY",
+	"OPENROUTER_API_KEY",
+	"MISTRAL_API_KEY",
+	"TAVILY_API_KEY",
+];
+
+export const copawFramework: AgentFrameworkDefinition = {
+	id: "copaw",
+	name: "CoPaw",
+	icon: "🐾",
+	description: "Alibaba's personal agent workstation with ReMe memory and cron autonomy",
+	runtime: "python",
+	canBePrimary: true,
+	canBeCompanion: true,
+	networkName: "copaw-network",
+	imageVariants: IMAGE_VARIANTS,
+	defaultImageVariant: "official",
+
+	buildGatewayService(
+		resolved: ResolverOutput,
+		options: FrameworkComposeOptions,
+		dependsOn?: Record<string, { condition: string }>,
+	): GatewayBuildResult {
+		const allVolumes = new Set<string>();
+		const defaultImage = getCopawImage(
+			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: `\${COPAW_IMAGE:-${defaultImage}}`,
+			environment: gatewayEnv,
+			volumes: [
+				"${COPAW_DATA_DIR:-./copaw/data}:/app/working",
+				"${COPAW_SECRETS_DIR:-./copaw/secrets}:/app/working.secret",
+			],
+			ports: ["${COPAW_PORT:-8088}:8088"],
+			networks: [this.networkName],
+			restart: "unless-stopped",
+			healthcheck: {
+				test: ["CMD", "curl", "-sf", "http://localhost:8088/", "||", "exit", "1"],
+				interval: "30s",
+				timeout: "5s",
+				retries: 5,
+				start_period: "30s",
+			},
+		};
+
+		if (dependsOn && Object.keys(dependsOn).length > 0) {
+			gateway.depends_on = dependsOn;
+		}
+
+		return { gatewayService: gateway, cliService: null, allVolumes };
+	},
+
+	generateConfig(
+		_resolved: ResolverOutput,
+		_options: FrameworkConfigOptions,
+	): FrameworkConfigResult | null {
+		// CoPaw uses config.json in the working directory, generated on first run
+		return null;
+	},
+
+	getBaseEnvVars(options: FrameworkEnvOptions): EnvLine[] {
+		const imageVariantMap: Record<string, string> = {
+			official: "",
+			pre: "agentscope/copaw:pre",
+		};
+		const imageValue = imageVariantMap[options.frameworkImageVariant ?? "official"] ?? "";
+
+		return [
+			{
+				comment: "CoPaw Docker image override",
+				key: "COPAW_IMAGE",
+				exampleValue: "",
+				actualValue: imageValue,
+			},
+			{
+				comment: "CoPaw web console port",
+				key: "COPAW_PORT",
+				exampleValue: "8088",
+				actualValue: "8088",
+			},
+			{
+				comment: "Host path to CoPaw data directory",
+				key: "COPAW_DATA_DIR",
+				exampleValue: "./copaw/data",
+				actualValue: "./copaw/data",
+			},
+			{
+				comment: "Host path to CoPaw secrets directory",
+				key: "COPAW_SECRETS_DIR",
+				exampleValue: "./copaw/secrets",
+				actualValue: "./copaw/secrets",
+			},
+		];
+	},
+
+	getMandatoryServices(): string[] {
+		return [];
+	},
+
+	getRecommendedServices(): string[] {
+		return ["clawrouter"];
+	},
+
+	getProviderEnvKeys(): string[] {
+		return [...PROVIDER_ENV_KEYS];
+	},
+
+	getEnvSectionName(): string {
+		return "CoPaw Core";
+	},
+};