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

package/dist/slack-relay-server.js

@@ -0,0 +1,197 @@
+import { WebSocket, WebSocketServer } from 'ws';
+import { config } from './config.js';
+import { toErrorMessage } from './utils/response.js';
+/**
+ * Daemon-hosted local Slack relay WS **server** (transport variant B).
+ *
+ * The openclaw runtime in this same pod runs `channels.slack.mode:'relay'` and
+ * dials us at `ws://127.0.0.1:8788/slack-relay?gateway_id=<AGENT_ID>` with an
+ * `Authorization: Bearer <token>` header (see the client in openclaw
+ * `extensions/slack/src/monitor/relay-source.ts`). We speak the server half of
+ * that wire protocol: send a `hello` on connect and push `slack_event` frames.
+ *
+ * We resolve each push as soon as the frame is written to the connected client
+ * socket (the `ws.send` callback fires with no error) — NOT when openclaw later
+ * returns its dispatch `ack`. openclaw only acks after it has dispatched the
+ * message to a possibly-busy agent, so waiting on that ack blocked the backend's
+ * serial (prefetch(1)) messages-broker for up to a full agent turn and produced
+ * false ack-timeouts. openclaw still sends the ack; we simply ignore it. The
+ * residual loss window (openclaw crashes after receiving the frame but before
+ * dispatch) is covered by openclaw's own channel+ts dedup on redelivery.
+ *
+ * The backend delivers events over Centrifugo as `slack_event` system commands;
+ * `handlers/slack-event.ts` calls `pushSlackEvent()` here. We bind loopback only
+ * — the auth token is defense-in-depth on top of that.
+ */
+/** Default port; overridable via `SLACK_RELAY_PORT` (see `config.slackRelayPort`). */
+export const SLACK_RELAY_PORT = 8788;
+const SLACK_RELAY_PATH = '/slack-relay';
+/** Matches the client's `SLACK_RELAY_MAX_PAYLOAD_BYTES` (1 MiB). */
+const SLACK_RELAY_MAX_PAYLOAD_BYTES = 1024 * 1024;
+/**
+ * Safety net only — a healthy loopback `ws.send` calls back in ~ms. This bounds
+ * the ONE remaining wait (the send callback) so a stalled/half-open client can't
+ * hang the backend's serial broker. It is NOT a wait for openclaw's dispatch-ack
+ * (that ack is ignored); the previous 15s ACK_TIMEOUT_MS was that wait and is
+ * gone. A successful send never approaches this budget.
+ */
+const SEND_TIMEOUT_MS = 2_000;
+// Module-level singleton so the slack_event handler can reach pushSlackEvent()
+// without threading the server through buildHandlers() — mirrors how handlers
+// reach the shared `logCollector`. Set on start, cleared on close.
+let state = null;
+export function startSlackRelayServer() {
+    const port = config.slackRelayPort ?? SLACK_RELAY_PORT;
+    const wss = new WebSocketServer({
+        host: '127.0.0.1',
+        port,
+        path: SLACK_RELAY_PATH,
+        maxPayload: SLACK_RELAY_MAX_PAYLOAD_BYTES,
+        perMessageDeflate: false,
+        verifyClient: verifyRelayClient,
+    });
+    const serverState = { wss, socket: null };
+    state = serverState;
+    wss.on('connection', (ws) => handleConnection(serverState, ws));
+    wss.on('listening', () => {
+        console.log(`[slack-relay] Slack relay server listening on ws://127.0.0.1:${port}${SLACK_RELAY_PATH}`);
+    });
+    // Bind errors (e.g. EADDRINUSE) arrive here asynchronously; log and stay up —
+    // Slack relay is optional, the rest of the controller must not crash for it.
+    wss.on('error', (err) => {
+        console.error('[slack-relay] server error:', toErrorMessage(err));
+    });
+    return {
+        close: () => {
+            // No pending-ack map to drain — pushSlackEvent resolves on frame-send, so
+            // nothing is in flight here.
+            serverState.socket?.close();
+            serverState.socket = null;
+            wss.close();
+            if (state === serverState)
+                state = null;
+        },
+    };
+}
+/**
+ * Send a `slack_event` frame to the connected openclaw client and resolve as
+ * soon as the frame is written to that socket (the `ws.send` callback fires with
+ * no error). We do NOT wait for openclaw's dispatch `ack` — see the module
+ * header for why. `delivered:true` on the backend therefore means "openclaw's
+ * relay client received the frame", not "openclaw dispatched it to the agent".
+ *
+ * Rejects on: no connected client, a send error, or the send stalling past
+ * `SEND_TIMEOUT_MS`. The backend redelivers on rejection (at-least-once), keyed
+ * by the same `delivery_id`; the no-client rejection is the durability contract
+ * that makes the backend retry rather than drop when nothing is connected.
+ */
+export function pushSlackEvent(payload) {
+    const serverState = state;
+    if (!serverState) {
+        return Promise.reject(new Error('Slack relay server not started'));
+    }
+    const ws = serverState.socket;
+    if (!ws || ws.readyState !== WebSocket.OPEN) {
+        return Promise.reject(new Error('No Slack relay client connected'));
+    }
+    const { event, deliveryId, route } = payload;
+    const frame = JSON.stringify({
+        type: 'slack_event',
+        delivery_id: deliveryId,
+        route,
+        payload: { event },
+    });
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        // Bounds the send itself, not openclaw's dispatch. Fires only if the socket
+        // stalls (half-open client, full send buffer) so a broken client can't hang
+        // the backend's serial broker.
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            reject(new Error(`Slack relay send stalled after ${SEND_TIMEOUT_MS}ms (delivery ${deliveryId})`));
+        }, SEND_TIMEOUT_MS);
+        // A hanging send must never hold the process open during shutdown.
+        timer.unref?.();
+        ws.send(frame, (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (err)
+                reject(err);
+            else
+                resolve(); // frame handed to the client socket — ack no longer awaited
+        });
+    });
+}
+function verifyRelayClient(info, cb) {
+    const { req } = info;
+    const url = new URL(req.url ?? '', 'http://127.0.0.1');
+    const gatewayId = url.searchParams.get('gateway_id');
+    // Fail closed: reject unless gateway_id names THIS agent.
+    if (!gatewayId || gatewayId !== config.agentId) {
+        console.warn(`[slack-relay] rejecting connection: gateway_id mismatch (got ${gatewayId ?? 'none'})`);
+        cb(false, 403, 'Forbidden');
+        return;
+    }
+    const expectedToken = config.slackRelayAuthToken;
+    // Token is defense-in-depth on a loopback-only bind: enforced only when set.
+    if (expectedToken && bearerToken(req.headers.authorization) !== expectedToken) {
+        console.warn('[slack-relay] rejecting connection: bad or missing bearer token');
+        cb(false, 401, 'Unauthorized');
+        return;
+    }
+    cb(true);
+}
+function bearerToken(header) {
+    const match = header ? /^Bearer\s+(.+)$/i.exec(header.trim()) : null;
+    return match?.[1]?.trim() || undefined;
+}
+function handleConnection(serverState, ws) {
+    // openclaw reconnects with backoff — always keep the newest socket and drop
+    // any stale one so pushSlackEvent talks to the live connection.
+    if (serverState.socket && serverState.socket !== ws) {
+        serverState.socket.close();
+    }
+    serverState.socket = ws;
+    console.log('[slack-relay] openclaw relay client connected');
+    // hello first — the client reads an optional slack_identity from it; we omit it.
+    ws.send(JSON.stringify({ type: 'hello' }));
+    ws.on('message', (data) => handleClientFrame(data));
+    ws.on('error', (err) => {
+        console.error('[slack-relay] client socket error:', toErrorMessage(err));
+    });
+    ws.on('close', () => {
+        console.log('[slack-relay] openclaw relay client disconnected');
+        if (serverState.socket === ws) {
+            serverState.socket = null;
+        }
+        // Nothing to fail on close — pushSlackEvent already resolved on frame-send,
+        // so there are no in-flight deliveries tied to this socket.
+    });
+}
+function handleClientFrame(data) {
+    // openclaw still sends `{ type:'ack', delivery_id }` after it dispatches each
+    // event to the agent. We resolved the push on frame-send and keep no pending
+    // map, so every ack — for any delivery_id, already-resolved or unknown — is a
+    // harmless no-op. Parse only to surface a malformed frame; the result is
+    // deliberately discarded.
+    try {
+        JSON.parse(rawDataToString(data));
+    }
+    catch {
+        console.warn('[slack-relay] dropping malformed JSON frame from client');
+    }
+}
+function rawDataToString(data) {
+    if (typeof data === 'string')
+        return data;
+    if (Buffer.isBuffer(data))
+        return data.toString('utf8');
+    if (Array.isArray(data))
+        return Buffer.concat(data).toString('utf8');
+    return Buffer.from(data).toString('utf8');
+}
+//# sourceMappingURL=slack-relay-server.js.map

package/dist/slack-relay-server.js.map

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

package/dist/types.d.ts

@@ -4,7 +4,7 @@
  *   chat:<agentId>      — chat commands (list sessions, history, send)
  *   heartbeat:<agentId> — heartbeat publications from agent
  */
-export type CommandType = 'diagnostics' | 'restart' | 'deploy' | 'pair' | 'stop' | 'backup' | 'chat_list_sessions' | 'chat_history' | 'chat_send' | 'chat_delete_session' | 'package_install' | 'file_write' | 'file_delete' | 'onboarding_complete' | 'knowledge_sync' | 'self_update' | 'plugin_update' | 'agent_update' | 'telegram_webhook' | 'update_skills' | 'update_config' | 'memory_create_entities' | 'memory_create_relations' | 'memory_add_observations' | 'memory_delete_entities' | 'memory_delete_observations' | 'memory_delete_relations' | 'memory_read_graph' | 'memory_search_nodes' | 'memory_open_nodes';
+export type CommandType = 'diagnostics' | 'restart' | 'deploy' | 'pair' | 'stop' | 'backup' | 'chat_list_sessions' | 'chat_history' | 'chat_send' | 'chat_delete_session' | 'package_install' | 'file_write' | 'file_delete' | 'onboarding_complete' | 'knowledge_sync' | 'self_update' | 'plugin_update' | 'agent_update' | 'telegram_webhook' | 'slack_event' | 'update_skills' | 'update_config' | 'memory_create_entities' | 'memory_create_relations' | 'memory_add_observations' | 'memory_delete_entities' | 'memory_delete_observations' | 'memory_delete_relations' | 'memory_read_graph' | 'memory_search_nodes' | 'memory_open_nodes';
 export interface AgentCommand {
     id: string;
     type: CommandType;
@@ -22,9 +22,23 @@ export interface GatewayStatus {
     rpcOk: boolean;
     pid?: number;
 }
+/**
+ * Live snapshot of the Centrifugo WS connection state, so backend can tell
+ * whether this agent is actually able to receive commands (heartbeat 200 alone
+ * does not prove the WS is up — the controller can be alive while the Centrifugo
+ * subscription is in error / reconnecting).
+ */
+export interface CentrifugoStatus {
+    connected: boolean;
+    state: 'connected' | 'connecting' | 'disconnected';
+    commandSubState: 'subscribed' | 'subscribing' | 'unsubscribed';
+    chatSubState: 'subscribed' | 'subscribing' | 'unsubscribed';
+    lastEventAt?: string | null;
+}
 export interface InstalledVersions {
     agentController: string;
     agentRuntime?: string;
+    nodeVersion?: string;
     plugins?: Array<{
         id: string;
         version: string;
@@ -42,5 +56,6 @@ export interface HeartbeatPayload {
         uptime: number;
     };
     gatewayStatus?: GatewayStatus;
+    centrifugoStatus?: CentrifugoStatus;
     lastMessageAt?: string | null;
 }

package/dist/utils/anthropic-auth.d.ts

@@ -23,3 +23,17 @@ export declare function classifyAnthropicAuth(input: {
     anthropicAuthToken?: string;
     anthropicApiKey?: string;
 }): AnthropicAuth;
+/** The permissions block both Claude settings writers emit, verbatim. */
+export declare const CLAUDE_PERMISSIONS: {
+    allow: string[];
+};
+/**
+ * The settings.json base shared by both writers: the permissions block plus the
+ * `env` entry the auth classification implies.
+ *
+ * `providers/claude-code/settings-writer.ts` uses this as its complete output;
+ * `utils/claude-env.ts` uses it for the OAuth branch and composes its own
+ * apiKeyHelper variant for the API-key branch (that flow reads the key out of
+ * the VM `.env` at runtime instead of embedding it).
+ */
+export declare function buildClaudeSettings(auth: AnthropicAuth): Record<string, unknown>;

package/dist/utils/anthropic-auth.js

@@ -10,4 +10,28 @@ export function classifyAnthropicAuth(input) {
         return { kind: 'auth_token', value: apiKey };
     return { kind: 'api_key', value: apiKey };
 }
+/** The permissions block both Claude settings writers emit, verbatim. */
+export const CLAUDE_PERMISSIONS = {
+    allow: ['Bash(*)', 'Read(*)', 'Write(*)', 'Edit(*)', 'mcp__*'],
+};
+/**
+ * The settings.json base shared by both writers: the permissions block plus the
+ * `env` entry the auth classification implies.
+ *
+ * `providers/claude-code/settings-writer.ts` uses this as its complete output;
+ * `utils/claude-env.ts` uses it for the OAuth branch and composes its own
+ * apiKeyHelper variant for the API-key branch (that flow reads the key out of
+ * the VM `.env` at runtime instead of embedding it).
+ */
+export function buildClaudeSettings(auth) {
+    switch (auth.kind) {
+        case 'auth_token':
+            return { permissions: CLAUDE_PERMISSIONS, env: { ANTHROPIC_AUTH_TOKEN: auth.value } };
+        case 'api_key':
+            return { permissions: CLAUDE_PERMISSIONS, env: { ANTHROPIC_API_KEY: auth.value } };
+        case 'none':
+            // No static credentials: rely on ~/.claude/.credentials.json (subscription login).
+            return { permissions: CLAUDE_PERMISSIONS };
+    }
+}
 //# sourceMappingURL=anthropic-auth.js.map

package/dist/utils/anthropic-auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"anthropic-auth.js","sourceRoot":"","sources":["../../src/utils/anthropic-auth.ts"],"names":[],"mappings":"AAiBA,MAAM,UAAU,qBAAqB,CAAC,KAGrC;IACC,MAAM,SAAS,GAAG,KAAK,CAAC,kBAAkB,EAAE,IAAI,EAAE,CAAC;IACnD,IAAI,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAE/D,MAAM,MAAM,GAAG,KAAK,CAAC,eAAe,EAAE,IAAI,EAAE,CAAC;IAC7C,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAErC,yEAAyE;IACzE,IAAI,MAAM,CAAC,UAAU,CAAC,YAAY,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAElF,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AAC5C,CAAC"}
+{"version":3,"file":"anthropic-auth.js","sourceRoot":"","sources":["../../src/utils/anthropic-auth.ts"],"names":[],"mappings":"AAiBA,MAAM,UAAU,qBAAqB,CAAC,KAGrC;IACC,MAAM,SAAS,GAAG,KAAK,CAAC,kBAAkB,EAAE,IAAI,EAAE,CAAC;IACnD,IAAI,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAE/D,MAAM,MAAM,GAAG,KAAK,CAAC,eAAe,EAAE,IAAI,EAAE,CAAC;IAC7C,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAErC,yEAAyE;IACzE,IAAI,MAAM,CAAC,UAAU,CAAC,YAAY,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAElF,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AAC5C,CAAC;AAED,yEAAyE;AACzE,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,KAAK,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,CAAC;CAC/D,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAmB;IACrD,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,YAAY;YACf,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,GAAG,EAAE,EAAE,oBAAoB,EAAE,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC;QACxF,KAAK,SAAS;YACZ,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,GAAG,EAAE,EAAE,iBAAiB,EAAE,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC;QACrF,KAAK,MAAM;YACT,mFAAmF;YACnF,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;IAC/C,CAAC;AACH,CAAC"}

package/dist/utils/apply-config.d.ts

@@ -1,14 +1,29 @@
-import type { BootstrapResult } from '../api.js';
+import type { AgentApi, BootstrapResult } from '../api.js';
+/** Canonical openclaw.json location — `<stateDir>/openclaw.json`. */
+export declare function getOpenclawJsonPath(): string;
 /**
- * Apply config from bootstrap API response:
+ * The ONE writer for openclaw.json — atomic (tmp + rename) and mode 0600.
+ *
+ * Both properties are load-bearing and used to be split across three
+ * independent write sites: the full apply wrote 0600 but non-atomically (a
+ * reader could see a truncated file), the scoped merge wrote atomically but
+ * with no mode (tmp + rename RESETS a pre-existing 0600 file to 0644, leaking
+ * `models.providers[*].apiKey`), and the startup memory-MCP injection did
+ * neither. Everything goes through here now.
+ */
+export declare function writeOpenclawJson(data: Record<string, unknown>): Promise<void>;
+/**
+ * FULL apply — only ever legal on a managed install (see `isManagedDeploy`).
+ * Rewrites files wholesale:
  * 1. Write openclaw.json
- * 2. Write auth-profiles.json + settings.json (from envVars)
- * 3. Write .env (for VM agents)
- * 4. Restart gateway
+ * 2. Write workspace files + skills
+ * 3. Write auth-profiles.json + settings.json (from envVars)
+ * 4. MERGE .env (for VM agents) — never a wholesale replace, see step 4 below
+ * 5. Restart gateway
  */
 export declare function applyBootstrapConfig(data: BootstrapResult): Promise<void>;
-type MergeOutcome = 'added' | 'equal' | 'conflict' | 'merged';
-interface MergeResult {
+type MergeOutcome = 'added' | 'equal' | 'conflict' | 'merged' | 'overwritten';
+export interface MergeResult {
     changed: boolean;
     outcomes: Array<{
         path: string;
@@ -26,12 +41,50 @@ interface MergeResult {
  *  - Missing local value → remote is written.
  *  - Equal values → no-op.
  *  - Differing values → conflict, local wins, warn+skip logged.
- *  - For `mcp.servers` (and other object paths): conflict detection is
- *    per-key inside the dict.
- *  - Does NOT restart the gateway (standalone owns their own lifecycle).
- *  - Settings.json (~/.claude/settings.json) gets the same treatment for
- *    `mcp.servers` and `env` only — apiKeyHelper/permissions/etc untouched.
+ *  - For object paths: conflict detection is per-key inside the dict.
+ *  - **Exception — `mcp.servers` in openclaw.json is REMOTE-wins per key.**
+ *    That section is backend-managed: the URL, transport and bearer token of a
+ *    backend-generated server (e.g. `openclaw-cloud`) change over time, and
+ *    under local-wins an updated entry could never reach a standalone agent —
+ *    a rotated token was skipped forever (observed live 2026-08-02). Every
+ *    server NAME present in the payload is overwritten; names that exist only
+ *    locally are left untouched.
+ *    LIMITATION — no deletions. A server removed in the backend stays in the
+ *    local openclaw.json: the payload cannot distinguish "removed upstream"
+ *    from "never managed here", and dropping local-only entries would delete
+ *    the user's own servers. Removal on standalone is a manual edit.
+ *  - Restarts the gateway **iff** the `mcp.servers` subtree actually changed.
+ *    This is a FALLBACK, not the primary delivery mechanism: openclaw 2026.7.1
+ *    does self-reload this section (verified live 2026-08-03 — the gateway
+ *    logged `[reload] config hot reload applied (mcp.servers.<name>.url,
+ *    mcp.servers.<name>.headers)` on an overwrite, with no restart). The
+ *    restart covers builds/paths where that self-reload does not fire, and
+ *    mirrors what applyBootstrapConfig does on managed installs. It is
+ *    best-effort: a failure is logged and does not fail the apply — on a
+ *    launchd box where `openclaw` is not on the service PATH it never runs at
+ *    all, and the merge still lands.
+ *  - Settings.json (~/.claude/settings.json) keeps LOCAL-wins for
+ *    `mcp.servers` ONLY — apiKeyHelper/permissions/env/etc untouched. `env` is
+ *    never written here: it would redirect the user's own Claude Code sessions
+ *    to the platform proxy (see MERGEABLE_SETTINGS_PATHS).
  *  - auth-profiles.json and .env are NOT touched on standalone.
  */
 export declare function applyMergeableConfig(data: BootstrapResult): Promise<MergeResult>;
+export interface ApplyConfigOutcome {
+    /** True when the full apply ran (managed install), false for scoped merge. */
+    managed: boolean;
+    /** Present only on the scoped-merge path. */
+    mergeResult?: MergeResult;
+}
+/**
+ * The one owner of "fetch bootstrap and apply it". Every caller — the
+ * `update_config` WS handler, the `bootstrap` CLI, the opt-in startup refresh —
+ * goes through here so the deploy-type decision cannot drift between them.
+ *
+ * Managed installs ('vm'/'k8s') are provisioned end to end by the platform and
+ * get the full apply. Anything else — 'standalone', 'external', or a payload
+ * from an older backend that omits `deploymentType` — is a third-party machine
+ * and gets the scoped, additive merge only. Never rewrite files we don't own.
+ */
+export declare function fetchAndApplyConfig(api: AgentApi, agentId: string): Promise<ApplyConfigOutcome>;
 export {};