@openclaw-cloud/agent-controller 3.0.0-beta.2 → 3.0.0-beta.21

package/dist/utils/plugin-reconcile.d.ts

@@ -0,0 +1,46 @@
+export type ReconcileSource = 'bootstrap' | 'startup';
+export interface ReconcileResult {
+    declared: string[];
+    missing: string[];
+    installed: string[];
+    failed: Array<{
+        id: string;
+        error: string;
+    }>;
+    /** Set when reconcile could not run — nothing was installed. */
+    skippedReason?: string;
+}
+/**
+ * The plugin ids openclaw.json says must be present.
+ *
+ * `plugins.allow` is the primary source: the backend's config generator writes
+ * exactly the external npm plugins it expects installed (today
+ * `['@openclaw-cloud/mcp-warmup']`).
+ *
+ * `plugins.entries` is also consulted, but ONLY for scoped ids (`@scope/name`).
+ * That block additionally holds openclaw's BUNDLED plugins — `telegram`,
+ * `discord`, `slack`, `whatsapp` — which ship inside the runtime and are not
+ * npm-installable; handing those to `openclaw plugins install` would fail on
+ * every boot. Bundled ids are bare words, external ones are scoped, so the
+ * `@scope/` shape is the discriminator. An entry explicitly `{enabled: false}`
+ * is skipped.
+ *
+ * Everything is finally filtered through `isSafePackageName` — these ids reach
+ * a shell via `openclaw plugins install <id>@<version>`.
+ */
+export declare function declaredPluginIds(openclawConfig: unknown): string[];
+/**
+ * Install every declared-but-absent plugin. NEVER throws — bootstrap and
+ * startup both call it on their happy path and a plugin problem must not take
+ * down the boot; the next controller start reconciles again.
+ *
+ * Cheap when nothing is missing: one `openclaw plugins list --json` (no npm
+ * traffic, no backend call). The backend/npm work only happens once something
+ * is actually absent.
+ *
+ * Installs go through `runOpenclawStackUpdate`, the one owner of
+ * "install then restart the gateway once if anything changed" — so a plugin
+ * installed while the gateway is already running is picked up immediately
+ * instead of waiting for the next restart.
+ */
+export declare function reconcilePlugins(source: ReconcileSource): Promise<ReconcileResult>;

package/dist/utils/plugin-reconcile.js

@@ -0,0 +1,201 @@
+/**
+ * Plugin reconciliation — agent-controller is the SINGLE OWNER of "the plugins
+ * openclaw.json declares are actually installed on disk".
+ *
+ * Background (incident 2026-08-03): the EC2 user-data used to install
+ * `@openclaw-cloud/mcp-warmup` itself with
+ *   su - ubuntu -c "openclaw plugins install ...@latest --force" || echo "…non-fatal"
+ * On a whole cohort of VMs that step died with `openclaw: command not found`
+ * (the login shell has no npm-global bin on PATH that early in first boot) and
+ * the `|| echo` swallowed it. The agents then ran for months with
+ * `plugins.allow=["@openclaw-cloud/mcp-warmup"]` in openclaw.json and no
+ * package on disk — openclaw logged "stale config entry ignored", no MCP warmup
+ * session ever started, and board tasks were undeliverable. Nothing noticed.
+ *
+ * So: the declared set lives in openclaw.json (written by the backend
+ * bootstrap), and this module makes the disk match it — at `agent-controller
+ * bootstrap` and again on every controller start, which is what turns a reboot
+ * into a self-heal instead of a permanent silent failure.
+ *
+ * SCOPE — missing-entirely only. A plugin that is installed at the "wrong"
+ * version is NOT touched here: version upgrades remain self-update's job
+ * (`runExplicitSelfUpdate` / the `agent_update` + `plugin_update` handlers,
+ * driven by backend targets). Reconcile answers one question — "is it there at
+ * all?" — so it can stay cheap enough to run on every boot.
+ */
+import fs from 'node:fs/promises';
+import { getOpenclawJsonPath } from './apply-config.js';
+import { listInstalledPlugins } from './openclaw-ops.js';
+import { runOpenclawStackUpdate } from './openclaw-stack-update.js';
+import { isSafePackageName } from './package-install.js';
+import { getReleaseChannel } from './release-channel.js';
+// The runtime-targets fetch has one implementation, in the self-update CLI —
+// reused rather than re-spelled so reconcile resolves plugin versions exactly
+// the way self-update does.
+import { fetchRuntimeTargets } from '../commands/self-update.js';
+import { logCollector } from '../connection.js';
+import { toErrorMessage } from './response.js';
+const LOG_PREFIX = '[plugin-reconcile]';
+/**
+ * The plugin ids openclaw.json says must be present.
+ *
+ * `plugins.allow` is the primary source: the backend's config generator writes
+ * exactly the external npm plugins it expects installed (today
+ * `['@openclaw-cloud/mcp-warmup']`).
+ *
+ * `plugins.entries` is also consulted, but ONLY for scoped ids (`@scope/name`).
+ * That block additionally holds openclaw's BUNDLED plugins — `telegram`,
+ * `discord`, `slack`, `whatsapp` — which ship inside the runtime and are not
+ * npm-installable; handing those to `openclaw plugins install` would fail on
+ * every boot. Bundled ids are bare words, external ones are scoped, so the
+ * `@scope/` shape is the discriminator. An entry explicitly `{enabled: false}`
+ * is skipped.
+ *
+ * Everything is finally filtered through `isSafePackageName` — these ids reach
+ * a shell via `openclaw plugins install <id>@<version>`.
+ */
+export function declaredPluginIds(openclawConfig) {
+    const plugins = openclawConfig?.plugins;
+    if (!plugins || typeof plugins !== 'object')
+        return [];
+    const ids = new Set();
+    const allow = plugins.allow;
+    if (Array.isArray(allow)) {
+        for (const id of allow) {
+            if (typeof id === 'string' && id.trim())
+                ids.add(id.trim());
+        }
+    }
+    const entries = plugins.entries;
+    if (entries && typeof entries === 'object' && !Array.isArray(entries)) {
+        for (const [rawId, entry] of Object.entries(entries)) {
+            const id = rawId.trim();
+            if (!id.startsWith('@') || !id.includes('/'))
+                continue; // bundled runtime plugin
+            const enabled = entry?.enabled;
+            if (enabled === false)
+                continue;
+            ids.add(id);
+        }
+    }
+    return [...ids].filter(isSafePackageName);
+}
+async function readDeclaredPlugins() {
+    const raw = await fs.readFile(getOpenclawJsonPath(), 'utf-8').catch(() => null);
+    if (raw === null)
+        return [];
+    try {
+        return declaredPluginIds(JSON.parse(raw));
+    }
+    catch (err) {
+        console.warn(`${LOG_PREFIX} openclaw.json is not valid JSON:`, toErrorMessage(err));
+        return [];
+    }
+}
+/**
+ * Version to install a missing plugin at — resolved exactly the way
+ * self-update does:
+ *   1. the backend's runtime targets for this agent
+ *      (`GET /api/agent/runtime-targets` → `openclaw.plugins[]`), which is what
+ *      `runSelfUpdateCli` prefers, then
+ *   2. the AC_RELEASE_CHANNEL dist-tag — `beta` on the beta channel, `latest`
+ *      on stable (the same mapping as `selfUpdate()`), which is also what the
+ *      old user-data line used.
+ */
+async function resolvePluginVersions(ids) {
+    const channel = getReleaseChannel();
+    const distTag = channel === 'stable' ? 'latest' : channel;
+    // Best-effort: fetchRuntimeTargets() already swallows every failure into null.
+    const targets = await fetchRuntimeTargets();
+    const fromBackend = new Map();
+    for (const p of targets?.openclaw?.plugins ?? []) {
+        if (p && typeof p.id === 'string' && typeof p.version === 'string' && p.version) {
+            fromBackend.set(p.id, p.version);
+        }
+    }
+    return new Map(ids.map((id) => [id, fromBackend.get(id) ?? distTag]));
+}
+/**
+ * Install every declared-but-absent plugin. NEVER throws — bootstrap and
+ * startup both call it on their happy path and a plugin problem must not take
+ * down the boot; the next controller start reconciles again.
+ *
+ * Cheap when nothing is missing: one `openclaw plugins list --json` (no npm
+ * traffic, no backend call). The backend/npm work only happens once something
+ * is actually absent.
+ *
+ * Installs go through `runOpenclawStackUpdate`, the one owner of
+ * "install then restart the gateway once if anything changed" — so a plugin
+ * installed while the gateway is already running is picked up immediately
+ * instead of waiting for the next restart.
+ */
+export async function reconcilePlugins(source) {
+    const empty = { declared: [], missing: [], installed: [], failed: [] };
+    try {
+        const declared = await readDeclaredPlugins();
+        if (declared.length === 0) {
+            console.log(`${LOG_PREFIX} no plugins declared in openclaw.json — nothing to reconcile`);
+            return empty;
+        }
+        // `openclaw plugins list --json` is the source of truth, NOT the
+        // `plugins.installs` block of openclaw.json: the incident was precisely a
+        // config entry with no package behind it, so a config-derived inventory
+        // would report the missing plugin as present.
+        let installedIds;
+        try {
+            installedIds = new Set((await listInstalledPlugins()).map((p) => p.id));
+        }
+        catch (err) {
+            const error = toErrorMessage(err);
+            // Loud: without an inventory we cannot tell present from absent, and
+            // blind-installing on every boot would hit npm forever.
+            console.error(`${LOG_PREFIX} cannot list installed plugins — skipping reconcile: ${error}`);
+            logCollector?.push('plugin_reconcile_probe_failed', 'error', `Plugin reconcile could not read the installed plugin list: ${error}`, { source, declared, error });
+            return { ...empty, declared, skippedReason: error };
+        }
+        const missing = declared.filter((id) => !installedIds.has(id));
+        if (missing.length === 0) {
+            console.log(`${LOG_PREFIX} all ${declared.length} declared plugin(s) present`);
+            return { ...empty, declared };
+        }
+        console.log(`${LOG_PREFIX} missing plugin(s): ${missing.join(', ')} — installing`);
+        logCollector?.push('plugin_reconcile_missing', 'warn', `Declared plugin(s) not installed: ${missing.join(', ')}`, { source, declared, missing });
+        const versions = await resolvePluginVersions(missing);
+        const plugins = missing.map((id) => ({ id, version: versions.get(id) ?? 'latest' }));
+        const stack = await runOpenclawStackUpdate({
+            plugins,
+            eventPrefix: 'plugin_reconcile',
+            meta: { source },
+        });
+        const summary = stack.pluginSummary ?? { installed: [], skipped: [], failed: [] };
+        if (summary.installed.length > 0) {
+            console.log(`${LOG_PREFIX} installed: ${summary.installed.join(', ')}`);
+            logCollector?.push('plugin_reconcile_installed', 'info', `Installed ${summary.installed.length} missing plugin(s): ${summary.installed.join(', ')}`, { source, installed: summary.installed, gatewayRestarted: stack.gatewayRestarted });
+        }
+        if (stack.restartError) {
+            console.error(`${LOG_PREFIX} gateway restart failed: ${stack.restartError}`);
+        }
+        if (summary.failed.length > 0) {
+            // LOUD. A swallowed plugin install is what caused the incident; this is
+            // the line an operator greps for, and the backend `agent_log` row an
+            // alert can fire on. (In the `bootstrap` CLI process `logCollector` is
+            // undefined — no WS connection — so there the console line is all we
+            // have; the startup reconcile re-reports it to the backend.)
+            const detail = summary.failed.map((f) => `${f.id}: ${f.error}`).join('; ');
+            console.error(`${LOG_PREFIX} install FAILED for ${summary.failed.length} plugin(s): ${detail}`);
+            logCollector?.push('plugin_reconcile_failed', 'error', `Plugin install failed during reconcile: ${detail}`, { source, failed: summary.failed });
+        }
+        return { declared, missing, installed: summary.installed, failed: summary.failed };
+    }
+    catch (err) {
+        // Anything unexpected (fs, backend client construction, …). Never fatal.
+        const error = toErrorMessage(err);
+        console.error(`${LOG_PREFIX} reconcile failed: ${error}`);
+        logCollector?.push('plugin_reconcile_failed', 'error', `Plugin reconcile failed: ${error}`, {
+            source,
+            error,
+        });
+        return { ...empty, skippedReason: error };
+    }
+}
+//# sourceMappingURL=plugin-reconcile.js.map

package/dist/utils/plugin-reconcile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-reconcile.js","sourceRoot":"","sources":["../../src/utils/plugin-reconcile.ts"],"names":[],"mappings":"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"}

package/dist/utils/response.js

@@ -1,4 +1,5 @@
 export function toErrorMessage(err) {
+    // eslint-disable-next-line no-restricted-syntax -- this IS the one implementation
     return err instanceof Error ? err.message : String(err);
 }
 export function toErrorResponse(command, err) {

package/dist/utils/response.js.map

@@ -1 +1 @@
-{"version":3,"file":"response.js","sourceRoot":"","sources":["../../src/utils/response.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,cAAc,CAAC,GAAY;IACzC,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,OAAqB,EAAE,GAAY;IACjE,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC;AAC5F,CAAC"}
+{"version":3,"file":"response.js","sourceRoot":"","sources":["../../src/utils/response.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,cAAc,CAAC,GAAY;IACzC,kFAAkF;IAClF,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,OAAqB,EAAE,GAAY;IACjE,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC;AAC5F,CAAC"}

package/dist/utils/write-home-files.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Write platform-managed files into the agent user's HOME directory.
+ *
+ * These live OUTSIDE the openclaw workspace on purpose: the workspace is
+ * indexed and pushed back to the backend by knowledge sync, and these files are
+ * credentials (first consumer: `.secrets/SECRETS.txt`). Keys are paths RELATIVE
+ * to `os.homedir()`; values are the full contents.
+ *
+ * `os.homedir()` is the right anchor because on a VM/pod agent-controller runs
+ * as the agent user itself — the same resolution `writeClaudeEnv()`
+ * (`~/.claude`) and `config.stateDir` (`~/.openclaw`) already rely on. On
+ * systemd that means the unit's `HOME` must be the agent user's home; it
+ * already must be, or the controller would not find `~/.openclaw` either
+ * (docs/DRAGONS.md#systemd-home).
+ *
+ * Semantics:
+ *  - Parent dirs created with mode 0700, files written 0600, always overwritten.
+ *  - Absolute keys and keys escaping HOME are logged and skipped — the same
+ *    segment-aware sandbox `writeWorkspaceFiles` uses, anchored at HOME.
+ *  - Nothing here throws: one bad entry must never fail the whole config apply.
+ *  - File CONTENTS are never logged — only the relative path and a byte count.
+ *
+ * ponytail: no deletion / directory GC. The platform overwrites the files it
+ * knows about; a key dropped from a later payload leaves the file on disk. Add
+ * a manifest + prune only if revocation-by-removal ever becomes a requirement.
+ */
+export declare function writeHomeFiles(files: Record<string, string> | undefined): Promise<number>;

package/dist/utils/write-home-files.js

@@ -0,0 +1,72 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { resolveInsideWorkspace } from '../workspace.js';
+import { getResolvedDeployType, isManagedDeploy } from './deploy-type.js';
+import { toErrorMessage } from './response.js';
+/**
+ * Write platform-managed files into the agent user's HOME directory.
+ *
+ * These live OUTSIDE the openclaw workspace on purpose: the workspace is
+ * indexed and pushed back to the backend by knowledge sync, and these files are
+ * credentials (first consumer: `.secrets/SECRETS.txt`). Keys are paths RELATIVE
+ * to `os.homedir()`; values are the full contents.
+ *
+ * `os.homedir()` is the right anchor because on a VM/pod agent-controller runs
+ * as the agent user itself — the same resolution `writeClaudeEnv()`
+ * (`~/.claude`) and `config.stateDir` (`~/.openclaw`) already rely on. On
+ * systemd that means the unit's `HOME` must be the agent user's home; it
+ * already must be, or the controller would not find `~/.openclaw` either
+ * (docs/DRAGONS.md#systemd-home).
+ *
+ * Semantics:
+ *  - Parent dirs created with mode 0700, files written 0600, always overwritten.
+ *  - Absolute keys and keys escaping HOME are logged and skipped — the same
+ *    segment-aware sandbox `writeWorkspaceFiles` uses, anchored at HOME.
+ *  - Nothing here throws: one bad entry must never fail the whole config apply.
+ *  - File CONTENTS are never logged — only the relative path and a byte count.
+ *
+ * ponytail: no deletion / directory GC. The platform overwrites the files it
+ * knows about; a key dropped from a later payload leaves the file on disk. Add
+ * a manifest + prune only if revocation-by-removal ever becomes a requirement.
+ */
+export async function writeHomeFiles(files) {
+    if (!files || Object.keys(files).length === 0)
+        return 0;
+    // Same guard as writeClaudeEnv(), for the same reason: this writes into a
+    // real user's HOME. `agent-controller bootstrap` on a developer laptop must
+    // never do that. Defense in depth — the only caller is already managed-only.
+    if (!isManagedDeploy()) {
+        console.log(`[home-files] skipped: not a managed install (deployType=${getResolvedDeployType() ?? 'unknown'})`);
+        return 0;
+    }
+    const homeDir = os.homedir();
+    let written = 0;
+    for (const [relPath, content] of Object.entries(files)) {
+        if (typeof content !== 'string') {
+            console.warn(`[home-files] ✗ ${relPath}: rejected (content is not a string)`);
+            continue;
+        }
+        const fullPath = resolveInsideWorkspace(homeDir, relPath);
+        if (!fullPath) {
+            console.warn(`[home-files] ✗ ${relPath}: rejected (path escapes home directory)`);
+            continue;
+        }
+        try {
+            // `mode` only applies to what these calls CREATE: a pre-existing dir
+            // keeps its permissions, and writeFile's mode is ignored when the file
+            // already exists — hence the explicit chmod on every write.
+            await fs.mkdir(path.dirname(fullPath), { recursive: true, mode: 0o700 });
+            await fs.writeFile(fullPath, content, { mode: 0o600 });
+            await fs.chmod(fullPath, 0o600);
+            written++;
+            // Credentials: path + size only, never the value.
+            console.log(`[home-files] ✓ ${relPath} (${Buffer.byteLength(content, 'utf8')} bytes)`);
+        }
+        catch (err) {
+            console.error(`[home-files] ✗ ${relPath}: ${toErrorMessage(err)}`);
+        }
+    }
+    return written;
+}
+//# sourceMappingURL=write-home-files.js.map

package/dist/utils/write-home-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-home-files.js","sourceRoot":"","sources":["../../src/utils/write-home-files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,KAAyC;IAC5E,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAExD,0EAA0E;IAC1E,4EAA4E;IAC5E,6EAA6E;IAC7E,IAAI,CAAC,eAAe,EAAE,EAAE,CAAC;QACvB,OAAO,CAAC,GAAG,CACT,2DAA2D,qBAAqB,EAAE,IAAI,SAAS,GAAG,CACnG,CAAC;QACF,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,OAAO,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC;IAC7B,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,KAAK,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACvD,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAChC,OAAO,CAAC,IAAI,CAAC,kBAAkB,OAAO,sCAAsC,CAAC,CAAC;YAC9E,SAAS;QACX,CAAC;QAED,MAAM,QAAQ,GAAG,sBAAsB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC1D,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,OAAO,CAAC,IAAI,CAAC,kBAAkB,OAAO,0CAA0C,CAAC,CAAC;YAClF,SAAS;QACX,CAAC;QAED,IAAI,CAAC;YACH,qEAAqE;YACrE,uEAAuE;YACvE,4DAA4D;YAC5D,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YACzE,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YACvD,MAAM,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;YAChC,OAAO,EAAE,CAAC;YACV,kDAAkD;YAClD,OAAO,CAAC,GAAG,CAAC,kBAAkB,OAAO,KAAK,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;QACzF,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,kBAAkB,OAAO,KAAK,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACrE,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/utils/write-workspace-files.d.ts

@@ -12,4 +12,4 @@
  * command path in `applyBootstrapConfig` (propagates shared-file updates from
  * the backend without requiring a restart).
  */
-export declare function writeWorkspaceFiles(files: Record<string, string>, workspaceDir: string): Promise<void>;
+export declare function writeWorkspaceFiles(files: Record<string, string>, workspaceDir: string): Promise<number>;

package/dist/utils/write-workspace-files.js

@@ -1,5 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { resolveInsideWorkspace } from '../workspace.js';
+import { toErrorMessage } from './response.js';
 /**
  * Write a map of workspace-relative paths → content into `workspaceDir`.
  *
@@ -17,32 +19,42 @@ import path from 'node:path';
 export async function writeWorkspaceFiles(files, workspaceDir) {
     const fileNames = Object.keys(files);
     if (fileNames.length === 0)
-        return;
+        return 0;
     await fs.mkdir(workspaceDir, { recursive: true });
+    const written = [];
     for (const [filePath, content] of Object.entries(files)) {
-        const fullPath = path.join(workspaceDir, filePath);
+        // Reject any key that escapes the workspace — a backend-supplied key like
+        // "../../etc/openclaw/agent.env" or an absolute path must not write outside
+        // it. Same sandbox helper as the file_write / file_delete handlers.
+        const fullPath = resolveInsideWorkspace(workspaceDir, filePath);
+        if (!fullPath) {
+            console.error(`  ✗ ${filePath}: rejected (path escapes workspace)`);
+            continue;
+        }
         await fs.mkdir(path.dirname(fullPath), { recursive: true });
         try {
             await fs.writeFile(fullPath, content);
+            written.push(filePath);
             console.log(`  ✓ ${filePath}`);
         }
         catch (err) {
-            console.error(`  ✗ ${filePath}: ${err instanceof Error ? err.message : err}`);
+            console.error(`  ✗ ${filePath}: ${toErrorMessage(err)}`);
         }
     }
-    // Make .sh files executable
-    for (const filePath of fileNames) {
+    // Make .sh files executable (only the ones we actually wrote)
+    for (const filePath of written) {
         if (filePath.endsWith('.sh')) {
             const fullPath = path.join(workspaceDir, filePath);
             await fs.chmod(fullPath, 0o755);
         }
     }
     // Summary for deployed skills (under .agents/skills/<name>/...)
-    const skillFiles = fileNames.filter((f) => f.startsWith('.agents/skills/'));
+    const skillFiles = written.filter((f) => f.startsWith('.agents/skills/'));
     if (skillFiles.length > 0) {
         const skills = [...new Set(skillFiles.map((f) => f.split('/')[2]))];
         console.log(`  ✓ skills deployed: ${skills.join(', ')}`);
     }
-    console.log(`  wrote ${fileNames.length} workspace files`);
+    console.log(`  wrote ${written.length} workspace files`);
+    return written.length;
 }
 //# sourceMappingURL=write-workspace-files.js.map

package/dist/utils/write-workspace-files.js.map

@@ -1 +1 @@
-{"version":3,"file":"write-workspace-files.js","sourceRoot":"","sources":["../../src/utils/write-workspace-files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,KAA6B,EAC7B,YAAoB;IAEpB,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAEnC,MAAM,EAAE,CAAC,KAAK,CAAC,YAAY,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAElD,KAAK,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;QACnD,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YACtC,OAAO,CAAC,GAAG,CAAC,OAAO,QAAQ,EAAE,CAAC,CAAC;QACjC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,OAAO,QAAQ,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;QAChF,CAAC;IACH,CAAC;IAED,4BAA4B;IAC5B,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,IAAI,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;YACnD,MAAM,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED,gEAAgE;IAChE,MAAM,UAAU,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC,CAAC;IAC5E,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACpE,OAAO,CAAC,GAAG,CAAC,wBAAwB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,WAAW,SAAS,CAAC,MAAM,kBAAkB,CAAC,CAAC;AAC7D,CAAC"}
+{"version":3,"file":"write-workspace-files.js","sourceRoot":"","sources":["../../src/utils/write-workspace-files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,KAA6B,EAC7B,YAAoB;IAEpB,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAErC,MAAM,EAAE,CAAC,KAAK,CAAC,YAAY,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAElD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxD,0EAA0E;QAC1E,4EAA4E;QAC5E,oEAAoE;QACpE,MAAM,QAAQ,GAAG,sBAAsB,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;QAChE,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,OAAO,CAAC,KAAK,CAAC,OAAO,QAAQ,qCAAqC,CAAC,CAAC;YACpE,SAAS;QACX,CAAC;QACD,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YACtC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACvB,OAAO,CAAC,GAAG,CAAC,OAAO,QAAQ,EAAE,CAAC,CAAC;QACjC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,OAAO,QAAQ,KAAK,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IAED,8DAA8D;IAC9D,KAAK,MAAM,QAAQ,IAAI,OAAO,EAAE,CAAC;QAC/B,IAAI,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;YACnD,MAAM,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED,gEAAgE;IAChE,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC,CAAC;IAC1E,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACpE,OAAO,CAAC,GAAG,CAAC,wBAAwB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,WAAW,OAAO,CAAC,MAAM,kBAAkB,CAAC,CAAC;IACzD,OAAO,OAAO,CAAC,MAAM,CAAC;AACxB,CAAC"}

package/dist/workspace.d.ts

@@ -10,3 +10,14 @@
  * (which used WORKSPACE_DIR) and backup/knowledge_sync (which used OPENCLAW_STATE_DIR).
  */
 export declare function getWorkspaceDir(): string;
+/**
+ * Resolve a backend-supplied relative path inside `workspaceDir`, or null if it
+ * escapes. The ONE sandbox for every backend-supplied path — `file_write`,
+ * `file_delete` and `writeWorkspaceFiles` all route through it.
+ *
+ * Containment is checked on path *segments* (via `path.relative`), not by
+ * substring. The old `p.includes('..') || p.startsWith('/')` copies in the two
+ * handlers rejected innocent names like `notes..v2.md` and missed Windows
+ * absolute forms such as `C:\x` and `\\server\share`.
+ */
+export declare function resolveInsideWorkspace(workspaceDir: string, relPath: string): string | null;

package/dist/workspace.js

@@ -16,4 +16,24 @@ export function getWorkspaceDir() {
         return config.workspaceDir;
     return path.join(config.stateDir, 'workspace');
 }
+/**
+ * Resolve a backend-supplied relative path inside `workspaceDir`, or null if it
+ * escapes. The ONE sandbox for every backend-supplied path — `file_write`,
+ * `file_delete` and `writeWorkspaceFiles` all route through it.
+ *
+ * Containment is checked on path *segments* (via `path.relative`), not by
+ * substring. The old `p.includes('..') || p.startsWith('/')` copies in the two
+ * handlers rejected innocent names like `notes..v2.md` and missed Windows
+ * absolute forms such as `C:\x` and `\\server\share`.
+ */
+export function resolveInsideWorkspace(workspaceDir, relPath) {
+    if (!relPath || path.isAbsolute(relPath) || path.win32.isAbsolute(relPath))
+        return null;
+    const fullPath = path.resolve(workspaceDir, relPath);
+    const rel = path.relative(workspaceDir, fullPath);
+    if (rel === '' || rel === '..' || rel.startsWith('..' + path.sep) || path.isAbsolute(rel)) {
+        return null;
+    }
+    return fullPath;
+}
 //# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe;IAC7B,IAAI,MAAM,CAAC,YAAY;QAAE,OAAO,MAAM,CAAC,YAAY,CAAC;IACpD,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;AACjD,CAAC"}
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe;IAC7B,IAAI,MAAM,CAAC,YAAY;QAAE,OAAO,MAAM,CAAC,YAAY,CAAC;IACpD,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CAAC,YAAoB,EAAE,OAAe;IAC1E,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IACxF,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IACrD,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;IAClD,IAAI,GAAG,KAAK,EAAE,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1F,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/package.json

@@ -1,17 +1,21 @@
 {
   "name": "@openclaw-cloud/agent-controller",
-  "version": "3.0.0-beta.2",
+  "version": "3.0.0-beta.21",
+  "packageManager": "pnpm@11.5.2",
   "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
   "main": "dist/index.js",
   "bin": {
     "agent-controller": "bin/agent-controller.js"
   },
   "scripts": {
     "build": "tsc",
-    "prepublishOnly": "npm run build",
-    "test": "node --experimental-vm-modules node_modules/.bin/jest --forceExit",
+    "prepublishOnly": "pnpm run build",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest --forceExit",
     "start": "node bin/agent-controller.js",
-    "prepare": "[ -d .git ] && husky || true",
+    "prepare": "[ -e .git ] && husky || true",
     "lint": "eslint --fix ./src"
   },
   "files": [
@@ -25,6 +29,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@jest/globals": "^30.0.0",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/npm": "^13.1.5",
     "@types/jest": "^30.0.0",