let5see/clawdbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add exec host routing + node daemon

Browse Source
This commit is contained in:
Peter Steinberger
2026-01-18 07:44:28 +00:00
parent 49bd2d96fa
commit ae0b4c4990
38 changed files with 2370 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
src/agents/bash-tools.exec.ts
View File

@@ -17,6 +17,7 @@ import {
resolveExecApprovals,
} from "../infra/exec-approvals.js";
import { requestHeartbeatNow } from "../infra/heartbeat-wake.js";
import { buildNodeShellCommand } from "../infra/node-shell.js";
import { enqueueSystemEvent } from "../infra/system-events.js";
import { logInfo } from "../logger.js";
import {
@@ -392,7 +393,7 @@ export function createExecTool(
const nodes = await listNodes({});
if (nodes.length === 0) {
throw new Error(
"exec host=node requires a paired node (none available). This requires the macOS companion app.",
"exec host=node requires a paired node (none available). This requires a companion app or node host.",
);
}
let nodeId: string;
@@ -411,14 +412,17 @@ export function createExecTool(
? nodeInfo?.commands?.includes("system.run")
: false;
if (!supportsSystemRun) {
throw new Error("exec host=node requires a node that supports system.run.");
throw new Error(
"exec host=node requires a node that supports system.run (companion app or node host).",
);
}
const argv = ["/bin/sh", "-lc", params.command];
const argv = buildNodeShellCommand(params.command, nodeInfo?.platform);
const invokeParams: Record<string, unknown> = {
nodeId,
command: "system.run",
params: {
command: argv,
rawCommand: params.command,
cwd: workdir,
env: params.env,
timeoutMs: typeof params.timeout === "number" ? params.timeout * 1000 : undefined,
@@ -471,6 +475,7 @@ export function createExecTool(
hostAsk === "always" ||
(hostAsk === "on-miss" && hostSecurity === "allowlist" && !allowlistMatch);
let approvedByAsk = false;
if (requiresAsk) {
const decision =
(await requestExecApprovalViaSocket({
@@ -491,31 +496,43 @@ export function createExecTool(
throw new Error("exec denied: user denied");
}
if (!decision) {
if (askFallback === "deny") {
throw new Error(
"exec denied: approval required (companion app approval UI not available)",
);
}
if (askFallback === "allowlist") {
if (askFallback === "full") {
approvedByAsk = true;
} else if (askFallback === "allowlist") {
if (!allowlistMatch) {
throw new Error(
"exec denied: approval required (companion app approval UI not available)",
);
}
approvedByAsk = true;
} else {
throw new Error(
"exec denied: approval required (companion app approval UI not available)",
);
}
}
if (decision === "allow-always" && hostSecurity === "allowlist") {
const pattern =
resolution?.resolvedPath ??
resolution?.rawExecutable ??
params.command.split(/\s+/).shift() ??
"";
if (pattern) {
addAllowlistEntry(approvals.file, defaults?.agentId, pattern);
if (decision === "allow-once") {
approvedByAsk = true;
}
if (decision === "allow-always") {
approvedByAsk = true;
if (hostSecurity === "allowlist") {
const pattern =
resolution?.resolvedPath ??
resolution?.rawExecutable ??
params.command.split(/\s+/).shift() ??
"";
if (pattern) {
addAllowlistEntry(approvals.file, defaults?.agentId, pattern);
}
}
}
}
if (hostSecurity === "allowlist" && !allowlistMatch && !approvedByAsk) {
throw new Error("exec denied: allowlist miss");
}
if (allowlistMatch) {
recordAllowlistUse(
approvals.file,

4
src/agents/tools/nodes-tool.ts
View File

@@ -388,7 +388,7 @@ export function createNodesTool(options?: {
const nodes = await listNodes(gatewayOpts);
if (nodes.length === 0) {
throw new Error(
"system.run requires a paired macOS companion app (no nodes available).",
"system.run requires a paired companion app or node host (no nodes available).",
);
}
const nodeId = resolveNodeIdFromList(nodes, node);
@@ -398,7 +398,7 @@ export function createNodesTool(options?: {
: false;
if (!supportsSystemRun) {
throw new Error(
"system.run requires the macOS companion app; the selected node does not support system.run.",
"system.run requires a companion app or node host; the selected node does not support system.run.",
);
}
const commandRaw = params.command;

2
src/cli/node-cli.ts Normal file
View File

@@ -0,0 +1,2 @@
export { registerNodeCli } from "./node-cli/register.js";

577
src/cli/node-cli/daemon.ts Normal file
View File

@@ -0,0 +1,577 @@
import { buildNodeInstallPlan } from "../../commands/node-daemon-install-helpers.js";
import {
DEFAULT_NODE_DAEMON_RUNTIME,
isNodeDaemonRuntime,
} from "../../commands/node-daemon-runtime.js";
import {
resolveNodeLaunchAgentLabel,
resolveNodeSystemdServiceName,
resolveNodeWindowsTaskName,
} from "../../daemon/constants.js";
import { resolveGatewayLogPaths } from "../../daemon/launchd.js";
import { resolveNodeService } from "../../daemon/node-service.js";
import { isSystemdUserServiceAvailable } from "../../daemon/systemd.js";
import { renderSystemdUnavailableHints } from "../../daemon/systemd-hints.js";
import { resolveIsNixMode } from "../../config/paths.js";
import { isWSL } from "../../infra/wsl.js";
import { loadNodeHostConfig } from "../../node-host/config.js";
import { defaultRuntime } from "../../runtime.js";
import { colorize, isRich, theme } from "../../terminal/theme.js";
import {
buildDaemonServiceSnapshot,
createNullWriter,
emitDaemonActionJson,
} from "../daemon-cli/response.js";
import { formatRuntimeStatus, parsePort } from "../daemon-cli/shared.js";
type NodeDaemonInstallOptions = {
host?: string;
port?: string | number;
tls?: boolean;
tlsFingerprint?: string;
nodeId?: string;
displayName?: string;
runtime?: string;
force?: boolean;
json?: boolean;
};
type NodeDaemonLifecycleOptions = {
json?: boolean;
};
type NodeDaemonStatusOptions = {
json?: boolean;
};
function renderNodeServiceStartHints(): string[] {
const base = ["clawdbot node daemon install", "clawdbot node start"];
switch (process.platform) {
case "darwin":
return [
...base,
`launchctl bootstrap gui/$UID ~/Library/LaunchAgents/${resolveNodeLaunchAgentLabel()}.plist`,
];
case "linux":
return [...base, `systemctl --user start ${resolveNodeSystemdServiceName()}.service`];
case "win32":
return [...base, `schtasks /Run /TN "${resolveNodeWindowsTaskName()}"`];
default:
return base;
}
}
function buildNodeRuntimeHints(env: NodeJS.ProcessEnv = process.env): string[] {
if (process.platform === "darwin") {
const logs = resolveGatewayLogPaths(env);
return [
`Launchd stdout (if installed): ${logs.stdoutPath}`,
`Launchd stderr (if installed): ${logs.stderrPath}`,
];
}
if (process.platform === "linux") {
const unit = resolveNodeSystemdServiceName();
return [`Logs: journalctl --user -u ${unit}.service -n 200 --no-pager`];
}
if (process.platform === "win32") {
const task = resolveNodeWindowsTaskName();
return [`Logs: schtasks /Query /TN "${task}" /V /FO LIST`];
}
return [];
}
function resolveNodeDefaults(opts: NodeDaemonInstallOptions, config: Awaited<ReturnType<typeof loadNodeHostConfig>>) {
const host = opts.host?.trim() || config?.gateway?.host || "127.0.0.1";
const portOverride = parsePort(opts.port);
if (opts.port !== undefined && portOverride === null) {
return { host, port: null };
}
const port = portOverride ?? config?.gateway?.port ?? 18790;
return { host, port };
}
export async function runNodeDaemonInstall(opts: NodeDaemonInstallOptions) {
const json = Boolean(opts.json);
const warnings: string[] = [];
const stdout = json ? createNullWriter() : process.stdout;
const emit = (payload: {
ok: boolean;
result?: string;
message?: string;
error?: string;
service?: {
label: string;
loaded: boolean;
loadedText: string;
notLoadedText: string;
};
hints?: string[];
warnings?: string[];
}) => {
if (!json) return;
emitDaemonActionJson({ action: "install", ...payload });
};
const fail = (message: string, hints?: string[]) => {
if (json) {
emit({
ok: false,
error: message,
hints,
warnings: warnings.length ? warnings : undefined,
});
} else {
defaultRuntime.error(message);
if (hints?.length) {
for (const hint of hints) defaultRuntime.log(`Tip: ${hint}`);
}
}
defaultRuntime.exit(1);
};
if (resolveIsNixMode(process.env)) {
fail("Nix mode detected; daemon install is disabled.");
return;
}
const config = await loadNodeHostConfig();
const { host, port } = resolveNodeDefaults(opts, config);
if (!Number.isFinite(port ?? NaN) || (port ?? 0) <= 0) {
fail("Invalid port");
return;
}
const runtimeRaw = opts.runtime ? String(opts.runtime) : DEFAULT_NODE_DAEMON_RUNTIME;
if (!isNodeDaemonRuntime(runtimeRaw)) {
fail('Invalid --runtime (use "node" or "bun")');
return;
}
const service = resolveNodeService();
let loaded = false;
try {
loaded = await service.isLoaded({ env: process.env });
} catch (err) {
fail(`Node service check failed: ${String(err)}`);
return;
}
if (loaded && !opts.force) {
emit({
ok: true,
result: "already-installed",
message: `Node service already ${service.loadedText}.`,
service: buildDaemonServiceSnapshot(service, loaded),
warnings: warnings.length ? warnings : undefined,
});
if (!json) {
defaultRuntime.log(`Node service already ${service.loadedText}.`);
defaultRuntime.log("Reinstall with: clawdbot node daemon install --force");
}
return;
}
const tlsFingerprint = opts.tlsFingerprint?.trim() || config?.gateway?.tlsFingerprint;
const tls =
Boolean(opts.tls) ||
Boolean(tlsFingerprint) ||
Boolean(config?.gateway?.tls);
const { programArguments, workingDirectory, environment, description } =
await buildNodeInstallPlan({
env: process.env,
host,
port: port ?? 18790,
tls,
tlsFingerprint: tlsFingerprint || undefined,
nodeId: opts.nodeId,
displayName: opts.displayName,
runtime: runtimeRaw,
warn: (message) => {
if (json) warnings.push(message);
else defaultRuntime.log(message);
},
});
try {
await service.install({
env: process.env,
stdout,
programArguments,
workingDirectory,
environment,
description,
});
} catch (err) {
fail(`Node install failed: ${String(err)}`);
return;
}
let installed = true;
try {
installed = await service.isLoaded({ env: process.env });
} catch {
installed = true;
}
emit({
ok: true,
result: "installed",
service: buildDaemonServiceSnapshot(service, installed),
warnings: warnings.length ? warnings : undefined,
});
}
export async function runNodeDaemonUninstall(opts: NodeDaemonLifecycleOptions = {}) {
const json = Boolean(opts.json);
const stdout = json ? createNullWriter() : process.stdout;
const emit = (payload: {
ok: boolean;
result?: string;
message?: string;
error?: string;
service?: {
label: string;
loaded: boolean;
loadedText: string;
notLoadedText: string;
};
}) => {
if (!json) return;
emitDaemonActionJson({ action: "uninstall", ...payload });
};
const fail = (message: string) => {
if (json) emit({ ok: false, error: message });
else defaultRuntime.error(message);
defaultRuntime.exit(1);
};
if (resolveIsNixMode(process.env)) {
fail("Nix mode detected; daemon uninstall is disabled.");
return;
}
const service = resolveNodeService();
try {
await service.uninstall({ env: process.env, stdout });
} catch (err) {
fail(`Node uninstall failed: ${String(err)}`);
return;
}
let loaded = false;
try {
loaded = await service.isLoaded({ env: process.env });
} catch {
loaded = false;
}
emit({
ok: true,
result: "uninstalled",
service: buildDaemonServiceSnapshot(service, loaded),
});
}
export async function runNodeDaemonStart(opts: NodeDaemonLifecycleOptions = {}) {
const json = Boolean(opts.json);
const stdout = json ? createNullWriter() : process.stdout;
const emit = (payload: {
ok: boolean;
result?: string;
message?: string;
error?: string;
hints?: string[];
service?: {
label: string;
loaded: boolean;
loadedText: string;
notLoadedText: string;
};
}) => {
if (!json) return;
emitDaemonActionJson({ action: "start", ...payload });
};
const fail = (message: string, hints?: string[]) => {
if (json) emit({ ok: false, error: message, hints });
else defaultRuntime.error(message);
defaultRuntime.exit(1);
};
const service = resolveNodeService();
let loaded = false;
try {
loaded = await service.isLoaded({ env: process.env });
} catch (err) {
fail(`Node service check failed: ${String(err)}`);
return;
}
if (!loaded) {
let hints = renderNodeServiceStartHints();
if (process.platform === "linux") {
const systemdAvailable = await isSystemdUserServiceAvailable().catch(() => false);
if (!systemdAvailable) {
hints = [...hints, ...renderSystemdUnavailableHints({ wsl: await isWSL() })];
}
}
emit({
ok: true,
result: "not-loaded",
message: `Node service ${service.notLoadedText}.`,
hints,
service: buildDaemonServiceSnapshot(service, loaded),
});
if (!json) {
defaultRuntime.log(`Node service ${service.notLoadedText}.`);
for (const hint of hints) {
defaultRuntime.log(`Start with: ${hint}`);
}
}
return;
}
try {
await service.restart({ env: process.env, stdout });
} catch (err) {
const hints = renderNodeServiceStartHints();
fail(`Node start failed: ${String(err)}`, hints);
return;
}
let started = true;
try {
started = await service.isLoaded({ env: process.env });
} catch {
started = true;
}
emit({
ok: true,
result: "started",
service: buildDaemonServiceSnapshot(service, started),
});
}
export async function runNodeDaemonRestart(opts: NodeDaemonLifecycleOptions = {}) {
const json = Boolean(opts.json);
const stdout = json ? createNullWriter() : process.stdout;
const emit = (payload: {
ok: boolean;
result?: string;
message?: string;
error?: string;
hints?: string[];
service?: {
label: string;
loaded: boolean;
loadedText: string;
notLoadedText: string;
};
}) => {
if (!json) return;
emitDaemonActionJson({ action: "restart", ...payload });
};
const fail = (message: string, hints?: string[]) => {
if (json) emit({ ok: false, error: message, hints });
else defaultRuntime.error(message);
defaultRuntime.exit(1);
};
const service = resolveNodeService();
let loaded = false;
try {
loaded = await service.isLoaded({ env: process.env });
} catch (err) {
fail(`Node service check failed: ${String(err)}`);
return;
}
if (!loaded) {
let hints = renderNodeServiceStartHints();
if (process.platform === "linux") {
const systemdAvailable = await isSystemdUserServiceAvailable().catch(() => false);
if (!systemdAvailable) {
hints = [...hints, ...renderSystemdUnavailableHints({ wsl: await isWSL() })];
}
}
emit({
ok: true,
result: "not-loaded",
message: `Node service ${service.notLoadedText}.`,
hints,
service: buildDaemonServiceSnapshot(service, loaded),
});
if (!json) {
defaultRuntime.log(`Node service ${service.notLoadedText}.`);
for (const hint of hints) {
defaultRuntime.log(`Start with: ${hint}`);
}
}
return;
}
try {
await service.restart({ env: process.env, stdout });
} catch (err) {
const hints = renderNodeServiceStartHints();
fail(`Node restart failed: ${String(err)}`, hints);
return;
}
let restarted = true;
try {
restarted = await service.isLoaded({ env: process.env });
} catch {
restarted = true;
}
emit({
ok: true,
result: "restarted",
service: buildDaemonServiceSnapshot(service, restarted),
});
}
export async function runNodeDaemonStop(opts: NodeDaemonLifecycleOptions = {}) {
const json = Boolean(opts.json);
const stdout = json ? createNullWriter() : process.stdout;
const emit = (payload: {
ok: boolean;
result?: string;
message?: string;
error?: string;
service?: {
label: string;
loaded: boolean;
loadedText: string;
notLoadedText: string;
};
}) => {
if (!json) return;
emitDaemonActionJson({ action: "stop", ...payload });
};
const fail = (message: string) => {
if (json) emit({ ok: false, error: message });
else defaultRuntime.error(message);
defaultRuntime.exit(1);
};
const service = resolveNodeService();
let loaded = false;
try {
loaded = await service.isLoaded({ env: process.env });
} catch (err) {
fail(`Node service check failed: ${String(err)}`);
return;
}
if (!loaded) {
emit({
ok: true,
result: "not-loaded",
message: `Node service ${service.notLoadedText}.`,
service: buildDaemonServiceSnapshot(service, loaded),
});
if (!json) {
defaultRuntime.log(`Node service ${service.notLoadedText}.`);
}
return;
}
try {
await service.stop({ env: process.env, stdout });
} catch (err) {
fail(`Node stop failed: ${String(err)}`);
return;
}
let stopped = false;
try {
stopped = await service.isLoaded({ env: process.env });
} catch {
stopped = false;
}
emit({
ok: true,
result: "stopped",
service: buildDaemonServiceSnapshot(service, stopped),
});
}
export async function runNodeDaemonStatus(opts: NodeDaemonStatusOptions = {}) {
const json = Boolean(opts.json);
const service = resolveNodeService();
const [loaded, command, runtime] = await Promise.all([
service.isLoaded({ env: process.env }).catch(() => false),
service.readCommand(process.env).catch(() => null),
service.readRuntime(process.env).catch((err) => ({ status: "unknown", detail: String(err) })),
]);
const payload = {
service: {
...buildDaemonServiceSnapshot(service, loaded),
command,
runtime,
},
};
if (json) {
defaultRuntime.log(JSON.stringify(payload, null, 2));
return;
}
const rich = isRich();
const label = (value: string) => colorize(rich, theme.muted, value);
const accent = (value: string) => colorize(rich, theme.accent, value);
const infoText = (value: string) => colorize(rich, theme.info, value);
const okText = (value: string) => colorize(rich, theme.success, value);
const warnText = (value: string) => colorize(rich, theme.warn, value);
const errorText = (value: string) => colorize(rich, theme.error, value);
const serviceStatus = loaded ? okText(service.loadedText) : warnText(service.notLoadedText);
defaultRuntime.log(`${label("Service:")} ${accent(service.label)} (${serviceStatus})`);
if (command?.programArguments?.length) {
defaultRuntime.log(`${label("Command:")} ${infoText(command.programArguments.join(" "))}`);
}
if (command?.sourcePath) {
defaultRuntime.log(`${label("Service file:")} ${infoText(command.sourcePath)}`);
}
if (command?.workingDirectory) {
defaultRuntime.log(`${label("Working dir:")} ${infoText(command.workingDirectory)}`);
}
const runtimeLine = formatRuntimeStatus(runtime);
if (runtimeLine) {
const runtimeStatus = runtime?.status ?? "unknown";
const runtimeColor =
runtimeStatus === "running"
? theme.success
: runtimeStatus === "stopped"
? theme.error
: runtimeStatus === "unknown"
? theme.muted
: theme.warn;
defaultRuntime.log(`${label("Runtime:")} ${colorize(rich, runtimeColor, runtimeLine)}`);
}
if (!loaded) {
defaultRuntime.log("");
for (const hint of renderNodeServiceStartHints()) {
defaultRuntime.log(`${warnText("Start with:")} ${infoText(hint)}`);
}
return;
}
const baseEnv = {
...(process.env as Record<string, string | undefined>),
...(command?.environment ?? undefined),
};
const hintEnv = {
...baseEnv,
CLAWDBOT_LOG_PREFIX: baseEnv.CLAWDBOT_LOG_PREFIX ?? "node",
} as NodeJS.ProcessEnv;
if (runtime?.missingUnit) {
defaultRuntime.error(errorText("Service unit not found."));
for (const hint of buildNodeRuntimeHints(hintEnv)) {
defaultRuntime.error(errorText(hint));
}
return;
}
if (runtime?.status === "stopped") {
defaultRuntime.error(errorText("Service is loaded but not running."));
for (const hint of buildNodeRuntimeHints(hintEnv)) {
defaultRuntime.error(errorText(hint));
}
}
}

116
src/cli/node-cli/register.ts Normal file
View File

@@ -0,0 +1,116 @@
import type { Command } from "commander";
import { formatDocsLink } from "../../terminal/links.js";
import { theme } from "../../terminal/theme.js";
import { loadNodeHostConfig } from "../../node-host/config.js";
import { runNodeHost } from "../../node-host/runner.js";
import {
runNodeDaemonInstall,
runNodeDaemonRestart,
runNodeDaemonStart,
runNodeDaemonStatus,
runNodeDaemonStop,
runNodeDaemonUninstall,
} from "./daemon.js";
import { parsePort } from "../daemon-cli/shared.js";
function parsePortWithFallback(value: unknown, fallback: number): number {
const parsed = parsePort(value);
return parsed ?? fallback;
}
export function registerNodeCli(program: Command) {
const node = program
.command("node")
.description("Run a headless node host (system.run/system.which)")
.addHelpText(
"after",
() =>
`\n${theme.muted("Docs:")} ${formatDocsLink("/cli/node", "docs.clawd.bot/cli/node")}\n`,
);
node
.command("start")
.description("Start the headless node host (foreground)")
.option("--host <host>", "Gateway bridge host")
.option("--port <port>", "Gateway bridge port")
.option("--tls", "Use TLS for the bridge connection", false)
.option("--tls-fingerprint <sha256>", "Expected TLS certificate fingerprint (sha256)")
.option("--node-id <id>", "Override node id (clears pairing token)")
.option("--display-name <name>", "Override node display name")
.action(async (opts) => {
const existing = await loadNodeHostConfig();
const host =
(opts.host as string | undefined)?.trim() ||
existing?.gateway?.host ||
"127.0.0.1";
const port = parsePortWithFallback(opts.port, existing?.gateway?.port ?? 18790);
await runNodeHost({
gatewayHost: host,
gatewayPort: port,
gatewayTls: Boolean(opts.tls) || Boolean(opts.tlsFingerprint),
gatewayTlsFingerprint: opts.tlsFingerprint,
nodeId: opts.nodeId,
displayName: opts.displayName,
});
});
const daemon = node
.command("daemon")
.description("Manage the headless node daemon service (launchd/systemd/schtasks)");
daemon
.command("status")
.description("Show node daemon status")
.option("--json", "Output JSON", false)
.action(async (opts) => {
await runNodeDaemonStatus(opts);
});
daemon
.command("install")
.description("Install the node daemon service (launchd/systemd/schtasks)")
.option("--host <host>", "Gateway bridge host")
.option("--port <port>", "Gateway bridge port")
.option("--tls", "Use TLS for the bridge connection", false)
.option("--tls-fingerprint <sha256>", "Expected TLS certificate fingerprint (sha256)")
.option("--node-id <id>", "Override node id (clears pairing token)")
.option("--display-name <name>", "Override node display name")
.option("--runtime <runtime>", "Daemon runtime (node|bun). Default: node")
.option("--force", "Reinstall/overwrite if already installed", false)
.option("--json", "Output JSON", false)
.action(async (opts) => {
await runNodeDaemonInstall(opts);
});
daemon
.command("uninstall")
.description("Uninstall the node daemon service (launchd/systemd/schtasks)")
.option("--json", "Output JSON", false)
.action(async (opts) => {
await runNodeDaemonUninstall(opts);
});
daemon
.command("start")
.description("Start the node daemon service (launchd/systemd/schtasks)")
.option("--json", "Output JSON", false)
.action(async (opts) => {
await runNodeDaemonStart(opts);
});
daemon
.command("stop")
.description("Stop the node daemon service (launchd/systemd/schtasks)")
.option("--json", "Output JSON", false)
.action(async (opts) => {
await runNodeDaemonStop(opts);
});
daemon
.command("restart")
.description("Restart the node daemon service (launchd/systemd/schtasks)")
.option("--json", "Output JSON", false)
.action(async (opts) => {
await runNodeDaemonRestart(opts);
});
}

2
src/cli/program/register.subclis.ts
View File

@@ -13,6 +13,7 @@ import { registerWebhooksCli } from "../webhooks-cli.js";
import { registerLogsCli } from "../logs-cli.js";
import { registerModelsCli } from "../models-cli.js";
import { registerNodesCli } from "../nodes-cli.js";
import { registerNodeCli } from "../node-cli.js";
import { registerPairingCli } from "../pairing-cli.js";
import { registerPluginsCli } from "../plugins-cli.js";
import { registerSandboxCli } from "../sandbox-cli.js";
@@ -27,6 +28,7 @@ export function registerSubCliCommands(program: Command) {
registerLogsCli(program);
registerModelsCli(program);
registerNodesCli(program);
registerNodeCli(program);
registerSandboxCli(program);
registerTuiCli(program);
registerCronCli(program);

65
src/commands/node-daemon-install-helpers.ts Normal file
View File

@@ -0,0 +1,65 @@
import { formatNodeServiceDescription } from "../daemon/constants.js";
import { resolveNodeProgramArguments } from "../daemon/program-args.js";
import {
renderSystemNodeWarning,
resolvePreferredNodePath,
resolveSystemNodeInfo,
} from "../daemon/runtime-paths.js";
import { buildNodeServiceEnvironment } from "../daemon/service-env.js";
import { resolveGatewayDevMode } from "./daemon-install-helpers.js";
import type { NodeDaemonRuntime } from "./node-daemon-runtime.js";
type WarnFn = (message: string, title?: string) => void;
export type NodeInstallPlan = {
programArguments: string[];
workingDirectory?: string;
environment: Record<string, string | undefined>;
description?: string;
};
export async function buildNodeInstallPlan(params: {
env: Record<string, string | undefined>;
host: string;
port: number;
tls?: boolean;
tlsFingerprint?: string;
nodeId?: string;
displayName?: string;
runtime: NodeDaemonRuntime;
devMode?: boolean;
nodePath?: string;
warn?: WarnFn;
}): Promise<NodeInstallPlan> {
const devMode = params.devMode ?? resolveGatewayDevMode();
const nodePath =
params.nodePath ??
(await resolvePreferredNodePath({
env: params.env,
runtime: params.runtime,
}));
const { programArguments, workingDirectory } = await resolveNodeProgramArguments({
host: params.host,
port: params.port,
tls: params.tls,
tlsFingerprint: params.tlsFingerprint,
nodeId: params.nodeId,
displayName: params.displayName,
dev: devMode,
runtime: params.runtime,
nodePath,
});
if (params.runtime === "node") {
const systemNode = await resolveSystemNodeInfo({ env: params.env });
const warning = renderSystemNodeWarning(systemNode, programArguments[0]);
if (warning) params.warn?.(warning, "Node daemon runtime");
}
const environment = buildNodeServiceEnvironment({ env: params.env });
const description = formatNodeServiceDescription({
version: environment.CLAWDBOT_SERVICE_VERSION,
});
return { programArguments, workingDirectory, environment, description };
}

16
src/commands/node-daemon-runtime.ts Normal file
View File

@@ -0,0 +1,16 @@
import {
DEFAULT_GATEWAY_DAEMON_RUNTIME,
GATEWAY_DAEMON_RUNTIME_OPTIONS,
isGatewayDaemonRuntime,
type GatewayDaemonRuntime,
} from "./daemon-runtime.js";
export type NodeDaemonRuntime = GatewayDaemonRuntime;
export const DEFAULT_NODE_DAEMON_RUNTIME = DEFAULT_GATEWAY_DAEMON_RUNTIME;
export const NODE_DAEMON_RUNTIME_OPTIONS = GATEWAY_DAEMON_RUNTIME_OPTIONS;
export function isNodeDaemonRuntime(value: string | undefined): value is NodeDaemonRuntime {
return isGatewayDaemonRuntime(value);
}

24
src/daemon/constants.ts
View File

@@ -4,6 +4,12 @@ export const GATEWAY_SYSTEMD_SERVICE_NAME = "clawdbot-gateway";
export const GATEWAY_WINDOWS_TASK_NAME = "Clawdbot Gateway";
export const GATEWAY_SERVICE_MARKER = "clawdbot";
export const GATEWAY_SERVICE_KIND = "gateway";
export const NODE_LAUNCH_AGENT_LABEL = "com.clawdbot.node";
export const NODE_SYSTEMD_SERVICE_NAME = "clawdbot-node";
export const NODE_WINDOWS_TASK_NAME = "Clawdbot Node";
export const NODE_SERVICE_MARKER = "clawdbot";
export const NODE_SERVICE_KIND = "node";
export const NODE_WINDOWS_TASK_SCRIPT_NAME = "node.cmd";
export const LEGACY_GATEWAY_LAUNCH_AGENT_LABELS = ["com.steipete.clawdbot.gateway"];
export const LEGACY_GATEWAY_SYSTEMD_SERVICE_NAMES: string[] = [];
export const LEGACY_GATEWAY_WINDOWS_TASK_NAMES: string[] = [];
@@ -51,3 +57,21 @@ export function formatGatewayServiceDescription(params?: {
if (parts.length === 0) return "Clawdbot Gateway";
return `Clawdbot Gateway (${parts.join(", ")})`;
}
export function resolveNodeLaunchAgentLabel(): string {
return NODE_LAUNCH_AGENT_LABEL;
}
export function resolveNodeSystemdServiceName(): string {
return NODE_SYSTEMD_SERVICE_NAME;
}
export function resolveNodeWindowsTaskName(): string {
return NODE_WINDOWS_TASK_NAME;
}
export function formatNodeServiceDescription(params?: { version?: string }): string {
const version = params?.version?.trim();
if (!version) return "Clawdbot Node Host";
return `Clawdbot Node Host (v${version})`;
}

19
src/daemon/launchd.ts
View File

@@ -52,10 +52,11 @@ export function resolveGatewayLogPaths(env: Record<string, string | undefined>):
} {
const stateDir = resolveGatewayStateDir(env);
const logDir = path.join(stateDir, "logs");
const prefix = env.CLAWDBOT_LOG_PREFIX?.trim() || "gateway";
return {
logDir,
stdoutPath: path.join(logDir, "gateway.log"),
stderrPath: path.join(logDir, "gateway.err.log"),
stdoutPath: path.join(logDir, `${prefix}.log`),
stderrPath: path.join(logDir, `${prefix}.err.log`),
};
}
@@ -340,12 +341,14 @@ export async function installLaunchAgent({
programArguments,
workingDirectory,
environment,
description,
}: {
env: Record<string, string | undefined>;
stdout: NodeJS.WritableStream;
programArguments: string[];
workingDirectory?: string;
environment?: Record<string, string | undefined>;
description?: string;
}): Promise<{ plistPath: string }> {
const { logDir, stdoutPath, stderrPath } = resolveGatewayLogPaths(env);
await fs.mkdir(logDir, { recursive: true });
@@ -366,13 +369,15 @@ export async function installLaunchAgent({
const plistPath = resolveLaunchAgentPlistPathForLabel(env, label);
await fs.mkdir(path.dirname(plistPath), { recursive: true });
const description = formatGatewayServiceDescription({
profile: env.CLAWDBOT_PROFILE,
version: environment?.CLAWDBOT_SERVICE_VERSION ?? env.CLAWDBOT_SERVICE_VERSION,
});
const serviceDescription =
description ??
formatGatewayServiceDescription({
profile: env.CLAWDBOT_PROFILE,
version: environment?.CLAWDBOT_SERVICE_VERSION ?? env.CLAWDBOT_SERVICE_VERSION,
});
const plist = buildLaunchAgentPlist({
label,
comment: description,
comment: serviceDescription,
programArguments,
workingDirectory,
stdoutPath,

66
src/daemon/node-service.ts Normal file
View File

@@ -0,0 +1,66 @@
import type { GatewayService, GatewayServiceInstallArgs } from "./service.js";
import { resolveGatewayService } from "./service.js";
import {
NODE_SERVICE_KIND,
NODE_SERVICE_MARKER,
NODE_WINDOWS_TASK_SCRIPT_NAME,
resolveNodeLaunchAgentLabel,
resolveNodeSystemdServiceName,
resolveNodeWindowsTaskName,
} from "./constants.js";
function withNodeServiceEnv(
env: Record<string, string | undefined>,
): Record<string, string | undefined> {
return {
...env,
CLAWDBOT_LAUNCHD_LABEL: resolveNodeLaunchAgentLabel(),
CLAWDBOT_SYSTEMD_UNIT: resolveNodeSystemdServiceName(),
CLAWDBOT_WINDOWS_TASK_NAME: resolveNodeWindowsTaskName(),
CLAWDBOT_TASK_SCRIPT_NAME: NODE_WINDOWS_TASK_SCRIPT_NAME,
CLAWDBOT_LOG_PREFIX: "node",
CLAWDBOT_SERVICE_MARKER: NODE_SERVICE_MARKER,
CLAWDBOT_SERVICE_KIND: NODE_SERVICE_KIND,
};
}
function withNodeInstallEnv(args: GatewayServiceInstallArgs): GatewayServiceInstallArgs {
return {
...args,
env: withNodeServiceEnv(args.env),
environment: {
...args.environment,
CLAWDBOT_LAUNCHD_LABEL: resolveNodeLaunchAgentLabel(),
CLAWDBOT_SYSTEMD_UNIT: resolveNodeSystemdServiceName(),
CLAWDBOT_WINDOWS_TASK_NAME: resolveNodeWindowsTaskName(),
CLAWDBOT_TASK_SCRIPT_NAME: NODE_WINDOWS_TASK_SCRIPT_NAME,
CLAWDBOT_LOG_PREFIX: "node",
CLAWDBOT_SERVICE_MARKER: NODE_SERVICE_MARKER,
CLAWDBOT_SERVICE_KIND: NODE_SERVICE_KIND,
},
};
}
export function resolveNodeService(): GatewayService {
const base = resolveGatewayService();
return {
...base,
install: async (args) => {
return base.install(withNodeInstallEnv(args));
},
uninstall: async (args) => {
return base.uninstall({ ...args, env: withNodeServiceEnv(args.env) });
},
stop: async (args) => {
return base.stop({ ...args, env: withNodeServiceEnv(args.env ?? {}) });
},
restart: async (args) => {
return base.restart({ ...args, env: withNodeServiceEnv(args.env ?? {}) });
},
isLoaded: async (args) => {
return base.isLoaded({ env: withNodeServiceEnv(args.env ?? {}) });
},
readCommand: (env) => base.readCommand(withNodeServiceEnv(env)),
readRuntime: (env) => base.readRuntime(withNodeServiceEnv(env)),
};
}

58
src/daemon/program-args.ts
View File

@@ -138,13 +138,12 @@ async function resolveBinaryPath(binary: string): Promise<string> {
}
}
export async function resolveGatewayProgramArguments(params: {
port: number;
async function resolveCliProgramArguments(params: {
args: string[];
dev?: boolean;
runtime?: GatewayRuntimePreference;
nodePath?: string;
}): Promise<GatewayProgramArgs> {
const gatewayArgs = ["gateway", "--port", String(params.port)];
const execPath = process.execPath;
const runtime = params.runtime ?? "auto";
@@ -153,7 +152,7 @@ export async function resolveGatewayProgramArguments(params: {
params.nodePath ?? (isNodeRuntime(execPath) ? execPath : await resolveNodePath());
const cliEntrypointPath = await resolveCliEntrypointPathForService();
return {
programArguments: [nodePath, cliEntrypointPath, ...gatewayArgs],
programArguments: [nodePath, cliEntrypointPath, ...params.args],
};
}
@@ -164,7 +163,7 @@ export async function resolveGatewayProgramArguments(params: {
await fs.access(devCliPath);
const bunPath = isBunRuntime(execPath) ? execPath : await resolveBunPath();
return {
programArguments: [bunPath, devCliPath, ...gatewayArgs],
programArguments: [bunPath, devCliPath, ...params.args],
workingDirectory: repoRoot,
};
}
@@ -172,7 +171,7 @@ export async function resolveGatewayProgramArguments(params: {
const bunPath = isBunRuntime(execPath) ? execPath : await resolveBunPath();
const cliEntrypointPath = await resolveCliEntrypointPathForService();
return {
programArguments: [bunPath, cliEntrypointPath, ...gatewayArgs],
programArguments: [bunPath, cliEntrypointPath, ...params.args],
};
}
@@ -180,12 +179,12 @@ export async function resolveGatewayProgramArguments(params: {
try {
const cliEntrypointPath = await resolveCliEntrypointPathForService();
return {
programArguments: [execPath, cliEntrypointPath, ...gatewayArgs],
programArguments: [execPath, cliEntrypointPath, ...params.args],
};
} catch (error) {
// If running under bun or another runtime that can execute TS directly
if (!isNodeRuntime(execPath)) {
return { programArguments: [execPath, ...gatewayArgs] };
return { programArguments: [execPath, ...params.args] };
}
throw error;
}
@@ -199,7 +198,7 @@ export async function resolveGatewayProgramArguments(params: {
// If already running under bun, use current execPath
if (isBunRuntime(execPath)) {
return {
programArguments: [execPath, devCliPath, ...gatewayArgs],
programArguments: [execPath, devCliPath, ...params.args],
workingDirectory: repoRoot,
};
}
@@ -207,7 +206,46 @@ export async function resolveGatewayProgramArguments(params: {
// Otherwise resolve bun from PATH
const bunPath = await resolveBunPath();
return {
programArguments: [bunPath, devCliPath, ...gatewayArgs],
programArguments: [bunPath, devCliPath, ...params.args],
workingDirectory: repoRoot,
};
}
export async function resolveGatewayProgramArguments(params: {
port: number;
dev?: boolean;
runtime?: GatewayRuntimePreference;
nodePath?: string;
}): Promise<GatewayProgramArgs> {
const gatewayArgs = ["gateway", "--port", String(params.port)];
return resolveCliProgramArguments({
args: gatewayArgs,
dev: params.dev,
runtime: params.runtime,
nodePath: params.nodePath,
});
}
export async function resolveNodeProgramArguments(params: {
host: string;
port: number;
tls?: boolean;
tlsFingerprint?: string;
nodeId?: string;
displayName?: string;
dev?: boolean;
runtime?: GatewayRuntimePreference;
nodePath?: string;
}): Promise<GatewayProgramArgs> {
const args = ["node", "start", "--host", params.host, "--port", String(params.port)];
if (params.tls || params.tlsFingerprint) args.push("--tls");
if (params.tlsFingerprint) args.push("--tls-fingerprint", params.tlsFingerprint);
if (params.nodeId) args.push("--node-id", params.nodeId);
if (params.displayName) args.push("--display-name", params.displayName);
return resolveCliProgramArguments({
args,
dev: params.dev,
runtime: params.runtime,
nodePath: params.nodePath,
});
}

37
src/daemon/schtasks.ts
View File

@@ -16,9 +16,18 @@ const formatLine = (label: string, value: string) => {
return `${colorize(rich, theme.muted, `${label}:`)} ${colorize(rich, theme.command, value)}`;
};
function resolveTaskName(env: Record<string, string | undefined>): string {
const override = env.CLAWDBOT_WINDOWS_TASK_NAME?.trim();
if (override) return override;
return resolveGatewayWindowsTaskName(env.CLAWDBOT_PROFILE);
}
export function resolveTaskScriptPath(env: Record<string, string | undefined>): string {
const override = env.CLAWDBOT_TASK_SCRIPT?.trim();
if (override) return override;
const scriptName = env.CLAWDBOT_TASK_SCRIPT_NAME?.trim() || "gateway.cmd";
const stateDir = resolveGatewayStateDir(env);
return path.join(stateDir, "gateway.cmd");
return path.join(stateDir, scriptName);
}
function quoteCmdArg(value: string): string {
@@ -201,29 +210,33 @@ export async function installScheduledTask({
programArguments,
workingDirectory,
environment,
description,
}: {
env: Record<string, string | undefined>;
stdout: NodeJS.WritableStream;
programArguments: string[];
workingDirectory?: string;
environment?: Record<string, string | undefined>;
description?: string;
}): Promise<{ scriptPath: string }> {
await assertSchtasksAvailable();
const scriptPath = resolveTaskScriptPath(env);
await fs.mkdir(path.dirname(scriptPath), { recursive: true });
const description = formatGatewayServiceDescription({
profile: env.CLAWDBOT_PROFILE,
version: environment?.CLAWDBOT_SERVICE_VERSION ?? env.CLAWDBOT_SERVICE_VERSION,
});
const taskDescription =
description ??
formatGatewayServiceDescription({
profile: env.CLAWDBOT_PROFILE,
version: environment?.CLAWDBOT_SERVICE_VERSION ?? env.CLAWDBOT_SERVICE_VERSION,
});
const script = buildTaskScript({
description,
description: taskDescription,
programArguments,
workingDirectory,
environment,
});
await fs.writeFile(scriptPath, script, "utf8");
const taskName = resolveGatewayWindowsTaskName(env.CLAWDBOT_PROFILE);
const taskName = resolveTaskName(env);
const quotedScript = quoteCmdArg(scriptPath);
const baseArgs = [
"/Create",
@@ -268,7 +281,7 @@ export async function uninstallScheduledTask({
stdout: NodeJS.WritableStream;
}): Promise<void> {
await assertSchtasksAvailable();
const taskName = resolveGatewayWindowsTaskName(env.CLAWDBOT_PROFILE);
const taskName = resolveTaskName(env);
await execSchtasks(["/Delete", "/F", "/TN", taskName]);
const scriptPath = resolveTaskScriptPath(env);
@@ -293,7 +306,7 @@ export async function stopScheduledTask({
env?: Record<string, string | undefined>;
}): Promise<void> {
await assertSchtasksAvailable();
const taskName = resolveGatewayWindowsTaskName(env?.CLAWDBOT_PROFILE);
const taskName = resolveTaskName(env ?? (process.env as Record<string, string | undefined>));
const res = await execSchtasks(["/End", "/TN", taskName]);
if (res.code !== 0 && !isTaskNotRunning(res)) {
throw new Error(`schtasks end failed: ${res.stderr || res.stdout}`.trim());
@@ -309,7 +322,7 @@ export async function restartScheduledTask({
env?: Record<string, string | undefined>;
}): Promise<void> {
await assertSchtasksAvailable();
const taskName = resolveGatewayWindowsTaskName(env?.CLAWDBOT_PROFILE);
const taskName = resolveTaskName(env ?? (process.env as Record<string, string | undefined>));
await execSchtasks(["/End", "/TN", taskName]);
const res = await execSchtasks(["/Run", "/TN", taskName]);
if (res.code !== 0) {
@@ -322,7 +335,7 @@ export async function isScheduledTaskInstalled(args: {
env?: Record<string, string | undefined>;
}): Promise<boolean> {
await assertSchtasksAvailable();
const taskName = resolveGatewayWindowsTaskName(args.env?.CLAWDBOT_PROFILE);
const taskName = resolveTaskName(args.env ?? (process.env as Record<string, string | undefined>));
const res = await execSchtasks(["/Query", "/TN", taskName]);
return res.code === 0;
}
@@ -338,7 +351,7 @@ export async function readScheduledTaskRuntime(
detail: String(err),
};
}
const taskName = resolveGatewayWindowsTaskName(env.CLAWDBOT_PROFILE);
const taskName = resolveTaskName(env);
const res = await execSchtasks(["/Query", "/TN", taskName, "/V", "/FO", "LIST"]);
if (res.code !== 0) {
const detail = (res.stderr || res.stdout).trim();

25
src/daemon/service-env.ts
View File

@@ -6,6 +6,12 @@ import {
GATEWAY_SERVICE_MARKER,
resolveGatewayLaunchAgentLabel,
resolveGatewaySystemdServiceName,
NODE_SERVICE_KIND,
NODE_SERVICE_MARKER,
NODE_WINDOWS_TASK_SCRIPT_NAME,
resolveNodeLaunchAgentLabel,
resolveNodeSystemdServiceName,
resolveNodeWindowsTaskName,
} from "./constants.js";
export type MinimalServicePathOptions = {
@@ -82,3 +88,22 @@ export function buildServiceEnvironment(params: {
CLAWDBOT_SERVICE_VERSION: VERSION,
};
}
export function buildNodeServiceEnvironment(params: {
env: Record<string, string | undefined>;
}): Record<string, string | undefined> {
const { env } = params;
return {
PATH: buildMinimalServicePath({ env }),
CLAWDBOT_STATE_DIR: env.CLAWDBOT_STATE_DIR,
CLAWDBOT_CONFIG_PATH: env.CLAWDBOT_CONFIG_PATH,
CLAWDBOT_LAUNCHD_LABEL: resolveNodeLaunchAgentLabel(),
CLAWDBOT_SYSTEMD_UNIT: resolveNodeSystemdServiceName(),
CLAWDBOT_WINDOWS_TASK_NAME: resolveNodeWindowsTaskName(),
CLAWDBOT_TASK_SCRIPT_NAME: NODE_WINDOWS_TASK_SCRIPT_NAME,
CLAWDBOT_LOG_PREFIX: "node",
CLAWDBOT_SERVICE_MARKER: NODE_SERVICE_MARKER,
CLAWDBOT_SERVICE_KIND: NODE_SERVICE_KIND,
CLAWDBOT_SERVICE_VERSION: VERSION,
};
}

1
src/daemon/service.ts
View File

@@ -33,6 +33,7 @@ export type GatewayServiceInstallArgs = {
programArguments: string[];
workingDirectory?: string;
environment?: Record<string, string | undefined>;
description?: string;
};
export type GatewayService = {

14
src/daemon/systemd.ts
View File

@@ -186,23 +186,27 @@ export async function installSystemdService({
programArguments,
workingDirectory,
environment,
description,
}: {
env: Record<string, string | undefined>;
stdout: NodeJS.WritableStream;
programArguments: string[];
workingDirectory?: string;
environment?: Record<string, string | undefined>;
description?: string;
}): Promise<{ unitPath: string }> {
await assertSystemdAvailable();
const unitPath = resolveSystemdUnitPath(env);
await fs.mkdir(path.dirname(unitPath), { recursive: true });
const description = formatGatewayServiceDescription({
profile: env.CLAWDBOT_PROFILE,
version: environment?.CLAWDBOT_SERVICE_VERSION ?? env.CLAWDBOT_SERVICE_VERSION,
});
const serviceDescription =
description ??
formatGatewayServiceDescription({
profile: env.CLAWDBOT_PROFILE,
version: environment?.CLAWDBOT_SERVICE_VERSION ?? env.CLAWDBOT_SERVICE_VERSION,
});
const unit = buildSystemdUnit({
description,
description: serviceDescription,
programArguments,
workingDirectory,
environment,

18
src/gateway/server-bridge-methods-system.ts
View File

@@ -1,3 +1,7 @@
import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agents/agent-scope.js";
import { buildWorkspaceSkillStatus } from "../agents/skills-status.js";
import { loadConfig } from "../config/config.js";
import { getRemoteSkillEligibility } from "../infra/skills-remote.js";
import { loadVoiceWakeConfig, setVoiceWakeTriggers } from "../infra/voicewake.js";
import {
ErrorCodes,
@@ -72,6 +76,20 @@ export const handleSystemBridgeMethods: BridgeMethodHandler = async (
const models = await ctx.loadGatewayModelCatalog();
return { ok: true, payloadJSON: JSON.stringify({ models }) };
}
case "skills.bins": {
const cfg = loadConfig();
const workspaceDir = resolveAgentWorkspaceDir(cfg, resolveDefaultAgentId(cfg));
const report = buildWorkspaceSkillStatus(workspaceDir, {
config: cfg,
eligibility: { remote: getRemoteSkillEligibility() },
});
const bins = Array.from(
new Set(
report.skills.flatMap((skill) => skill.requirements?.bins ?? []).filter(Boolean),
),
);
return { ok: true, payloadJSON: JSON.stringify({ bins }) };
}
default:
return null;
}

9
src/infra/exec-approvals.ts
View File

@@ -106,7 +106,7 @@ export function loadExecApprovals(): ExecApprovalsFile {
const raw = fs.readFileSync(filePath, "utf8");
const parsed = JSON.parse(raw) as ExecApprovalsFile;
if (parsed?.version !== 1) {
return normalizeExecApprovals({ version: 1, agents: parsed?.agents ?? {} });
return normalizeExecApprovals({ version: 1, agents: {} });
}
return normalizeExecApprovals(parsed);
} catch {
@@ -117,7 +117,12 @@ export function loadExecApprovals(): ExecApprovalsFile {
export function saveExecApprovals(file: ExecApprovalsFile) {
const filePath = resolveExecApprovalsPath();
ensureDir(filePath);
fs.writeFileSync(filePath, JSON.stringify(file, null, 2));
fs.writeFileSync(filePath, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
try {
fs.chmodSync(filePath, 0o600);
} catch {
// best-effort on platforms without chmod
}
}
export function ensureExecApprovals(): ExecApprovalsFile {

10
src/infra/node-shell.ts Normal file
View File

@@ -0,0 +1,10 @@
export function buildNodeShellCommand(command: string, platform?: string | null) {
const normalized = String(platform ?? "")
.trim()
.toLowerCase();
if (normalized.includes("win")) {
return ["cmd.exe", "/d", "/s", "/c", command];
}
return ["/bin/sh", "-lc", command];
}

306
src/node-host/bridge-client.ts Normal file
View File

@@ -0,0 +1,306 @@
import crypto from "node:crypto";
import net from "node:net";
import tls from "node:tls";
import type {
BridgeErrorFrame,
BridgeEventFrame,
BridgeHelloFrame,
BridgeHelloOkFrame,
BridgeInvokeRequestFrame,
BridgeInvokeResponseFrame,
BridgePairOkFrame,
BridgePairRequestFrame,
BridgePingFrame,
BridgePongFrame,
BridgeRPCRequestFrame,
BridgeRPCResponseFrame,
} from "../infra/bridge/server/types.js";
export type BridgeClientOptions = {
host: string;
port: number;
tls?: boolean;
tlsFingerprint?: string;
nodeId: string;
token?: string;
displayName?: string;
platform?: string;
version?: string;
deviceFamily?: string;
modelIdentifier?: string;
caps?: string[];
commands?: string[];
permissions?: Record<string, boolean>;
onInvoke?: (frame: BridgeInvokeRequestFrame) => void | Promise<void>;
onEvent?: (frame: BridgeEventFrame) => void | Promise<void>;
onPairToken?: (token: string) => void | Promise<void>;
onAuthReset?: () => void | Promise<void>;
onConnected?: (hello: BridgeHelloOkFrame) => void | Promise<void>;
onDisconnected?: (err?: Error) => void | Promise<void>;
log?: { info?: (msg: string) => void; warn?: (msg: string) => void };
};
type PendingRpc = {
resolve: (frame: BridgeRPCResponseFrame) => void;
reject: (err: Error) => void;
timer?: NodeJS.Timeout;
};
function normalizeFingerprint(input: string): string {
return input.replace(/[^a-fA-F0-9]/g, "").toLowerCase();
}
function extractFingerprint(raw: tls.PeerCertificate | tls.DetailedPeerCertificate): string | null {
const value = "fingerprint256" in raw ? raw.fingerprint256 : undefined;
if (!value) return null;
return normalizeFingerprint(value);
}
export class BridgeClient {
private opts: BridgeClientOptions;
private socket: net.Socket | tls.TLSSocket | null = null;
private buffer = "";
private pendingRpc = new Map<string, PendingRpc>();
private connected = false;
private helloReady: Promise<void> | null = null;
private helloResolve: (() => void) | null = null;
private helloReject: ((err: Error) => void) | null = null;
constructor(opts: BridgeClientOptions) {
this.opts = opts;
}
async connect(): Promise<void> {
if (this.connected) return;
this.helloReady = new Promise<void>((resolve, reject) => {
this.helloResolve = resolve;
this.helloReject = reject;
});
const socket = this.opts.tls
? tls.connect({
host: this.opts.host,
port: this.opts.port,
rejectUnauthorized: false,
})
: net.connect({ host: this.opts.host, port: this.opts.port });
this.socket = socket;
socket.setNoDelay(true);
socket.on("connect", () => {
this.sendHello();
});
socket.on("error", (err) => {
this.handleDisconnect(err);
});
socket.on("close", () => {
this.handleDisconnect();
});
socket.on("data", (chunk) => {
this.buffer += chunk.toString("utf8");
this.flush();
});
if (this.opts.tls && socket instanceof tls.TLSSocket && this.opts.tlsFingerprint) {
socket.once("secureConnect", () => {
const cert = socket.getPeerCertificate(true);
const fingerprint = cert ? extractFingerprint(cert) : null;
if (!fingerprint || fingerprint !== normalizeFingerprint(this.opts.tlsFingerprint ?? "")) {
const err = new Error("bridge tls fingerprint mismatch");
this.handleDisconnect(err);
socket.destroy(err);
}
});
}
await this.helloReady;
}
async close(): Promise<void> {
if (this.socket) {
this.socket.destroy();
this.socket = null;
}
this.connected = false;
this.pendingRpc.forEach((pending) => {
pending.timer && clearTimeout(pending.timer);
pending.reject(new Error("bridge client closed"));
});
this.pendingRpc.clear();
}
async request(method: string, params: Record<string, unknown> | null = null, timeoutMs = 5000) {
const id = crypto.randomUUID();
const frame: BridgeRPCRequestFrame = {
type: "req",
id,
method,
paramsJSON: params ? JSON.stringify(params) : null,
};
const res = await new Promise<BridgeRPCResponseFrame>((resolve, reject) => {
const timer = setTimeout(() => {
this.pendingRpc.delete(id);
reject(new Error(`bridge request timeout (${method})`));
}, timeoutMs);
this.pendingRpc.set(id, { resolve, reject, timer });
this.send(frame);
});
if (!res.ok) {
throw new Error(res.error?.message ?? "bridge request failed");
}
return res.payloadJSON ? JSON.parse(res.payloadJSON) : null;
}
sendEvent(event: string, payload?: unknown) {
const frame: BridgeEventFrame = {
type: "event",
event,
payloadJSON: payload ? JSON.stringify(payload) : null,
};
this.send(frame);
}
sendInvokeResponse(frame: BridgeInvokeResponseFrame) {
this.send(frame);
}
private sendHello() {
const hello: BridgeHelloFrame = {
type: "hello",
nodeId: this.opts.nodeId,
token: this.opts.token,
displayName: this.opts.displayName,
platform: this.opts.platform,
version: this.opts.version,
deviceFamily: this.opts.deviceFamily,
modelIdentifier: this.opts.modelIdentifier,
caps: this.opts.caps,
commands: this.opts.commands,
permissions: this.opts.permissions,
};
this.send(hello);
}
private sendPairRequest() {
const req: BridgePairRequestFrame = {
type: "pair-request",
nodeId: this.opts.nodeId,
displayName: this.opts.displayName,
platform: this.opts.platform,
version: this.opts.version,
deviceFamily: this.opts.deviceFamily,
modelIdentifier: this.opts.modelIdentifier,
caps: this.opts.caps,
commands: this.opts.commands,
permissions: this.opts.permissions,
};
this.send(req);
}
private send(frame: object) {
if (!this.socket) return;
this.socket.write(`${JSON.stringify(frame)}\n`);
}
private handleDisconnect(err?: Error) {
if (!this.connected && this.helloReject) {
this.helloReject(err ?? new Error("bridge connection failed"));
this.helloResolve = null;
this.helloReject = null;
}
if (!this.connected && !this.socket) return;
this.connected = false;
this.socket = null;
this.pendingRpc.forEach((pending) => {
pending.timer && clearTimeout(pending.timer);
pending.reject(err ?? new Error("bridge connection closed"));
});
this.pendingRpc.clear();
void this.opts.onDisconnected?.(err);
}
private flush() {
while (true) {
const idx = this.buffer.indexOf("\n");
if (idx === -1) break;
const line = this.buffer.slice(0, idx).trim();
this.buffer = this.buffer.slice(idx + 1);
if (!line) continue;
let frame: { type?: string; [key: string]: unknown };
try {
frame = JSON.parse(line) as { type?: string };
} catch {
continue;
}
this.handleFrame(frame as BridgeErrorFrame);
}
}
private handleFrame(frame: {
type?: string;
[key: string]: unknown;
}) {
const type = String(frame.type ?? "");
switch (type) {
case "hello-ok": {
this.connected = true;
this.helloResolve?.();
this.helloResolve = null;
this.helloReject = null;
void this.opts.onConnected?.(frame as BridgeHelloOkFrame);
return;
}
case "pair-ok": {
const token = String((frame as BridgePairOkFrame).token ?? "").trim();
if (token) {
this.opts.token = token;
void this.opts.onPairToken?.(token);
}
return;
}
case "error": {
const code = String((frame as BridgeErrorFrame).code ?? "");
if (code === "NOT_PAIRED" || code === "UNAUTHORIZED") {
this.opts.token = undefined;
void this.opts.onAuthReset?.();
this.sendPairRequest();
return;
}
this.handleDisconnect(new Error((frame as BridgeErrorFrame).message ?? "bridge error"));
return;
}
case "pong":
return;
case "ping": {
const ping = frame as BridgePingFrame;
const pong: BridgePongFrame = { type: "pong", id: String(ping.id ?? "") };
this.send(pong);
return;
}
case "event": {
void this.opts.onEvent?.(frame as BridgeEventFrame);
return;
}
case "res": {
const res = frame as BridgeRPCResponseFrame;
const pending = this.pendingRpc.get(res.id);
if (pending) {
pending.timer && clearTimeout(pending.timer);
this.pendingRpc.delete(res.id);
pending.resolve(res);
}
return;
}
case "invoke": {
void this.opts.onInvoke?.(frame as BridgeInvokeRequestFrame);
return;
}
case "invoke-res": {
return;
}
default:
return;
}
}
}

74
src/node-host/config.ts Normal file
View File

@@ -0,0 +1,74 @@
import crypto from "node:crypto";
import fs from "node:fs/promises";
import path from "node:path";
import { resolveStateDir } from "../config/paths.js";
export type NodeHostGatewayConfig = {
host?: string;
port?: number;
tls?: boolean;
tlsFingerprint?: string;
};
export type NodeHostConfig = {
version: 1;
nodeId: string;
token?: string;
displayName?: string;
gateway?: NodeHostGatewayConfig;
};
const NODE_HOST_FILE = "node.json";
export function resolveNodeHostConfigPath(): string {
return path.join(resolveStateDir(), NODE_HOST_FILE);
}
function normalizeConfig(config: Partial<NodeHostConfig> | null): NodeHostConfig {
const base: NodeHostConfig = {
version: 1,
nodeId: "",
token: config?.token,
displayName: config?.displayName,
gateway: config?.gateway,
};
if (config?.version === 1 && typeof config.nodeId === "string") {
base.nodeId = config.nodeId.trim();
}
if (!base.nodeId) {
base.nodeId = crypto.randomUUID();
}
return base;
}
export async function loadNodeHostConfig(): Promise<NodeHostConfig | null> {
const filePath = resolveNodeHostConfigPath();
try {
const raw = await fs.readFile(filePath, "utf8");
const parsed = JSON.parse(raw) as Partial<NodeHostConfig>;
return normalizeConfig(parsed);
} catch {
return null;
}
}
export async function saveNodeHostConfig(config: NodeHostConfig): Promise<void> {
const filePath = resolveNodeHostConfigPath();
await fs.mkdir(path.dirname(filePath), { recursive: true });
const payload = JSON.stringify(config, null, 2);
await fs.writeFile(filePath, `${payload}\n`, { mode: 0o600 });
try {
await fs.chmod(filePath, 0o600);
} catch {
// best-effort on platforms without chmod
}
}
export async function ensureNodeHostConfig(): Promise<NodeHostConfig> {
const existing = await loadNodeHostConfig();
const normalized = normalizeConfig(existing);
await saveNodeHostConfig(normalized);
return normalized;
}

654
src/node-host/runner.ts Normal file
View File

@@ -0,0 +1,654 @@
import crypto from "node:crypto";
import { spawn } from "node:child_process";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import type { BridgeInvokeRequestFrame } from "../infra/bridge/server/types.js";
import {
addAllowlistEntry,
matchAllowlist,
recordAllowlistUse,
requestExecApprovalViaSocket,
resolveCommandResolution,
resolveExecApprovals,
} from "../infra/exec-approvals.js";
import { getMachineDisplayName } from "../infra/machine-name.js";
import { VERSION } from "../version.js";
import { BridgeClient } from "./bridge-client.js";
import {
ensureNodeHostConfig,
saveNodeHostConfig,
type NodeHostGatewayConfig,
} from "./config.js";
type NodeHostRunOptions = {
gatewayHost: string;
gatewayPort: number;
gatewayTls?: boolean;
gatewayTlsFingerprint?: string;
nodeId?: string;
displayName?: string;
};
type SystemRunParams = {
command: string[];
rawCommand?: string | null;
cwd?: string | null;
env?: Record<string, string>;
timeoutMs?: number | null;
needsScreenRecording?: boolean | null;
agentId?: string | null;
sessionKey?: string | null;
};
type SystemWhichParams = {
bins: string[];
};
type RunResult = {
exitCode?: number;
timedOut: boolean;
success: boolean;
stdout: string;
stderr: string;
error?: string | null;
truncated: boolean;
};
type ExecEventPayload = {
sessionKey: string;
runId: string;
host: string;
command?: string;
exitCode?: number;
timedOut?: boolean;
success?: boolean;
output?: string;
reason?: string;
};
const OUTPUT_CAP = 200_000;
const OUTPUT_EVENT_TAIL = 20_000;
const blockedEnvKeys = new Set([
"PATH",
"NODE_OPTIONS",
"PYTHONHOME",
"PYTHONPATH",
"PERL5LIB",
"PERL5OPT",
"RUBYOPT",
]);
const blockedEnvPrefixes = ["DYLD_", "LD_"];
class SkillBinsCache {
private bins = new Set<string>();
private lastRefresh = 0;
private readonly ttlMs = 90_000;
private readonly fetch: () => Promise<string[]>;
constructor(fetch: () => Promise<string[]>) {
this.fetch = fetch;
}
async current(force = false): Promise<Set<string>> {
if (force || Date.now() - this.lastRefresh > this.ttlMs) {
await this.refresh();
}
return this.bins;
}
private async refresh() {
try {
const bins = await this.fetch();
this.bins = new Set(bins);
this.lastRefresh = Date.now();
} catch {
if (!this.lastRefresh) {
this.bins = new Set();
}
}
}
}
function sanitizeEnv(overrides?: Record<string, string> | null): Record<string, string> | undefined {
if (!overrides) return undefined;
const merged = { ...process.env } as Record<string, string>;
for (const [rawKey, value] of Object.entries(overrides)) {
const key = rawKey.trim();
if (!key) continue;
const upper = key.toUpperCase();
if (blockedEnvKeys.has(upper)) continue;
if (blockedEnvPrefixes.some((prefix) => upper.startsWith(prefix))) continue;
merged[key] = value;
}
return merged;
}
function formatCommand(argv: string[]): string {
return argv
.map((arg) => {
const trimmed = arg.trim();
if (!trimmed) return "\"\"";
const needsQuotes = /\s|"/.test(trimmed);
if (!needsQuotes) return trimmed;
return `"${trimmed.replace(/"/g, '\\"')}"`;
})
.join(" ");
}
function truncateOutput(raw: string, maxChars: number): { text: string; truncated: boolean } {
if (raw.length <= maxChars) return { text: raw, truncated: false };
return { text: `... (truncated) ${raw.slice(raw.length - maxChars)}`, truncated: true };
}
async function runCommand(
argv: string[],
cwd: string | undefined,
env: Record<string, string> | undefined,
timeoutMs: number | undefined,
): Promise<RunResult> {
return await new Promise((resolve) => {
let stdout = "";
let stderr = "";
let outputLen = 0;
let truncated = false;
let timedOut = false;
let settled = false;
const child = spawn(argv[0], argv.slice(1), {
cwd,
env,
stdio: ["ignore", "pipe", "pipe"],
windowsHide: true,
});
const onChunk = (chunk: Buffer, target: "stdout" | "stderr") => {
if (outputLen >= OUTPUT_CAP) {
truncated = true;
return;
}
const remaining = OUTPUT_CAP - outputLen;
const slice = chunk.length > remaining ? chunk.subarray(0, remaining) : chunk;
const str = slice.toString("utf8");
outputLen += slice.length;
if (target === "stdout") stdout += str;
else stderr += str;
if (chunk.length > remaining) truncated = true;
};
child.stdout?.on("data", (chunk) => onChunk(chunk as Buffer, "stdout"));
child.stderr?.on("data", (chunk) => onChunk(chunk as Buffer, "stderr"));
let timer: NodeJS.Timeout | undefined;
if (timeoutMs && timeoutMs > 0) {
timer = setTimeout(() => {
timedOut = true;
try {
child.kill("SIGKILL");
} catch {
// ignore
}
}, timeoutMs);
}
const finalize = (exitCode?: number, error?: string | null) => {
if (settled) return;
settled = true;
if (timer) clearTimeout(timer);
resolve({
exitCode,
timedOut,
success: exitCode === 0 && !timedOut && !error,
stdout,
stderr,
error: error ?? null,
truncated,
});
};
child.on("error", (err) => {
finalize(undefined, err.message);
});
child.on("exit", (code) => {
finalize(code === null ? undefined : code, null);
});
});
}
function resolveEnvPath(env?: Record<string, string>): string[] {
const raw =
env?.PATH ??
(env as Record<string, string>)?.Path ??
process.env.PATH ??
process.env.Path ??
"";
return raw.split(path.delimiter).filter(Boolean);
}
function resolveExecutable(bin: string, env?: Record<string, string>) {
if (bin.includes("/") || bin.includes("\\")) return null;
const extensions =
process.platform === "win32"
? (process.env.PATHEXT ?? process.env.PathExt ?? ".EXE;.CMD;.BAT;.COM")
.split(";")
.map((ext) => ext.toLowerCase())
: [""];
for (const dir of resolveEnvPath(env)) {
for (const ext of extensions) {
const candidate = path.join(dir, bin + ext);
if (fs.existsSync(candidate)) return candidate;
}
}
return null;
}
async function handleSystemWhich(params: SystemWhichParams, env?: Record<string, string>) {
const bins = params.bins
.map((bin) => bin.trim())
.filter(Boolean);
const found: Record<string, string> = {};
for (const bin of bins) {
const path = resolveExecutable(bin, env);
if (path) found[bin] = path;
}
return { bins: found };
}
function buildExecEventPayload(payload: ExecEventPayload): ExecEventPayload {
if (!payload.output) return payload;
const trimmed = payload.output.trim();
if (!trimmed) return payload;
const { text } = truncateOutput(trimmed, OUTPUT_EVENT_TAIL);
return { ...payload, output: text };
}
export async function runNodeHost(opts: NodeHostRunOptions): Promise<void> {
const config = await ensureNodeHostConfig();
const nodeId = opts.nodeId?.trim() || config.nodeId;
if (nodeId !== config.nodeId) {
config.nodeId = nodeId;
config.token = undefined;
}
const displayName =
opts.displayName?.trim() || config.displayName || (await getMachineDisplayName());
config.displayName = displayName;
const gateway: NodeHostGatewayConfig = {
host: opts.gatewayHost,
port: opts.gatewayPort,
tls: opts.gatewayTls === true,
tlsFingerprint: opts.gatewayTlsFingerprint,
};
config.gateway = gateway;
await saveNodeHostConfig(config);
let disconnectResolve: (() => void) | null = null;
let disconnectSignal = false;
const waitForDisconnect = () =>
new Promise<void>((resolve) => {
if (disconnectSignal) {
disconnectSignal = false;
resolve();
return;
}
disconnectResolve = resolve;
});
const client = new BridgeClient({
host: gateway.host ?? "127.0.0.1",
port: gateway.port ?? 18790,
tls: gateway.tls,
tlsFingerprint: gateway.tlsFingerprint,
nodeId,
token: config.token,
displayName,
platform: process.platform,
version: VERSION,
deviceFamily: os.platform(),
modelIdentifier: os.hostname(),
caps: ["system"],
commands: ["system.run", "system.which"],
onPairToken: async (token) => {
config.token = token;
await saveNodeHostConfig(config);
},
onAuthReset: async () => {
if (!config.token) return;
config.token = undefined;
await saveNodeHostConfig(config);
},
onInvoke: async (frame) => {
await handleInvoke(frame, client, skillBins);
},
onDisconnected: () => {
if (disconnectResolve) {
disconnectResolve();
disconnectResolve = null;
} else {
disconnectSignal = true;
}
},
});
const skillBins = new SkillBinsCache(async () => {
const res = await client.request("skills.bins", {});
const bins = Array.isArray(res?.bins) ? res.bins.map((b) => String(b)) : [];
return bins;
});
while (true) {
try {
await client.connect();
await waitForDisconnect();
} catch {
// ignore connect errors; retry
}
await new Promise((resolve) => setTimeout(resolve, 1500));
}
}
async function handleInvoke(
frame: BridgeInvokeRequestFrame,
client: BridgeClient,
skillBins: SkillBinsCache,
) {
const command = String(frame.command ?? "");
if (command === "system.which") {
try {
const params = decodeParams<SystemWhichParams>(frame.paramsJSON);
if (!Array.isArray(params.bins)) {
throw new Error("INVALID_REQUEST: bins required");
}
const env = sanitizeEnv(undefined);
const payload = await handleSystemWhich(params, env);
client.sendInvokeResponse({
type: "invoke-res",
id: frame.id,
ok: true,
payloadJSON: JSON.stringify(payload),
});
} catch (err) {
client.sendInvokeResponse({
type: "invoke-res",
id: frame.id,
ok: false,
error: { code: "INVALID_REQUEST", message: String(err) },
});
}
return;
}
if (command !== "system.run") {
client.sendInvokeResponse({
type: "invoke-res",
id: frame.id,
ok: false,
error: { code: "UNAVAILABLE", message: "command not supported" },
});
return;
}
let params: SystemRunParams;
try {
params = decodeParams<SystemRunParams>(frame.paramsJSON);
} catch (err) {
client.sendInvokeResponse({
type: "invoke-res",
id: frame.id,
ok: false,
error: { code: "INVALID_REQUEST", message: String(err) },
});
return;
}
if (!Array.isArray(params.command) || params.command.length === 0) {
client.sendInvokeResponse({
type: "invoke-res",
id: frame.id,
ok: false,
error: { code: "INVALID_REQUEST", message: "command required" },
});
return;
}
const argv = params.command.map((item) => String(item));
const rawCommand = typeof params.rawCommand === "string" ? params.rawCommand.trim() : "";
const cmdText = rawCommand || formatCommand(argv);
const agentId = params.agentId?.trim() || undefined;
const approvals = resolveExecApprovals(agentId);
const security = approvals.agent.security;
const ask = approvals.agent.ask;
const askFallback = approvals.agent.askFallback;
const autoAllowSkills = approvals.agent.autoAllowSkills;
const sessionKey = params.sessionKey?.trim() || "node";
const runId = crypto.randomUUID();
const env = sanitizeEnv(params.env ?? undefined);
const resolution = resolveCommandResolution(cmdText, params.cwd ?? undefined, env);
const allowlistMatch =
security === "allowlist" ? matchAllowlist(approvals.allowlist, resolution) : null;
const bins = autoAllowSkills ? await skillBins.current() : new Set<string>();
const skillAllow =
autoAllowSkills && resolution?.executableName ? bins.has(resolution.executableName) : false;
if (security === "deny") {
client.sendEvent(
"exec.denied",
buildExecEventPayload({
sessionKey,
runId,
host: "node",
command: cmdText,
reason: "security=deny",
}),
);
client.sendInvokeResponse({
type: "invoke-res",
id: frame.id,
ok: false,
error: { code: "UNAVAILABLE", message: "SYSTEM_RUN_DISABLED: security=deny" },
});
return;
}
const requiresAsk =
ask === "always" ||
(ask === "on-miss" && security === "allowlist" && !allowlistMatch && !skillAllow);
let approvedByAsk = false;
if (requiresAsk) {
const decision = await requestExecApprovalViaSocket({
socketPath: approvals.socketPath,
token: approvals.token,
request: {
command: cmdText,
cwd: params.cwd ?? undefined,
host: "node",
security,
ask,
agentId,
resolvedPath: resolution?.resolvedPath ?? null,
},
});
if (decision === "deny") {
client.sendEvent(
"exec.denied",
buildExecEventPayload({
sessionKey,
runId,
host: "node",
command: cmdText,
reason: "user-denied",
}),
);
client.sendInvokeResponse({
type: "invoke-res",
id: frame.id,
ok: false,
error: { code: "UNAVAILABLE", message: "SYSTEM_RUN_DENIED: user denied" },
});
return;
}
if (!decision) {
if (askFallback === "full") {
approvedByAsk = true;
} else if (askFallback === "allowlist") {
if (allowlistMatch || skillAllow) {
approvedByAsk = true;
} else {
client.sendEvent(
"exec.denied",
buildExecEventPayload({
sessionKey,
runId,
host: "node",
command: cmdText,
reason: "approval-required",
}),
);
client.sendInvokeResponse({
type: "invoke-res",
id: frame.id,
ok: false,
error: { code: "UNAVAILABLE", message: "SYSTEM_RUN_DENIED: approval required" },
});
return;
}
} else {
client.sendEvent(
"exec.denied",
buildExecEventPayload({
sessionKey,
runId,
host: "node",
command: cmdText,
reason: "approval-required",
}),
);
client.sendInvokeResponse({
type: "invoke-res",
id: frame.id,
ok: false,
error: { code: "UNAVAILABLE", message: "SYSTEM_RUN_DENIED: approval required" },
});
return;
}
}
if (decision === "allow-once") {
approvedByAsk = true;
}
if (decision === "allow-always") {
approvedByAsk = true;
if (security === "allowlist") {
const pattern = resolution?.resolvedPath ?? resolution?.rawExecutable ?? argv[0] ?? "";
if (pattern) addAllowlistEntry(approvals.file, agentId, pattern);
}
}
}
if (security === "allowlist" && !allowlistMatch && !skillAllow && !approvedByAsk) {
client.sendEvent(
"exec.denied",
buildExecEventPayload({
sessionKey,
runId,
host: "node",
command: cmdText,
reason: "allowlist-miss",
}),
);
client.sendInvokeResponse({
type: "invoke-res",
id: frame.id,
ok: false,
error: { code: "UNAVAILABLE", message: "SYSTEM_RUN_DENIED: allowlist miss" },
});
return;
}
if (allowlistMatch) {
recordAllowlistUse(approvals.file, agentId, allowlistMatch, cmdText, resolution?.resolvedPath);
}
if (params.needsScreenRecording === true) {
client.sendEvent(
"exec.denied",
buildExecEventPayload({
sessionKey,
runId,
host: "node",
command: cmdText,
reason: "permission:screenRecording",
}),
);
client.sendInvokeResponse({
type: "invoke-res",
id: frame.id,
ok: false,
error: { code: "UNAVAILABLE", message: "PERMISSION_MISSING: screenRecording" },
});
return;
}
client.sendEvent(
"exec.started",
buildExecEventPayload({
sessionKey,
runId,
host: "node",
command: cmdText,
}),
);
const result = await runCommand(
argv,
params.cwd?.trim() || undefined,
env,
params.timeoutMs ?? undefined,
);
if (result.truncated) {
const suffix = "... (truncated)";
if (result.stderr.trim().length > 0) {
result.stderr = `${result.stderr}\n${suffix}`;
} else {
result.stdout = `${result.stdout}\n${suffix}`;
}
}
const combined = [result.stdout, result.stderr, result.error].filter(Boolean).join("\n");
client.sendEvent(
"exec.finished",
buildExecEventPayload({
sessionKey,
runId,
host: "node",
command: cmdText,
exitCode: result.exitCode,
timedOut: result.timedOut,
success: result.success,
output: combined,
}),
);
client.sendInvokeResponse({
type: "invoke-res",
id: frame.id,
ok: true,
payloadJSON: JSON.stringify({
exitCode: result.exitCode,
timedOut: result.timedOut,
success: result.success,
stdout: result.stdout,
stderr: result.stderr,
error: result.error ?? null,
}),
});
}
function decodeParams<T>(raw?: string | null): T {
if (!raw) {
throw new Error("INVALID_REQUEST: paramsJSON required");
}
return JSON.parse(raw) as T;
}