@tbrandenburg/node-red-agents 0.1.1

package/nodes/agent/agent.js

@@ -0,0 +1,396 @@
+const fs = require('fs');
+const { OpenCodeAdapter } = require('./lib/agents/opencode');
+const { PiAdapter } = require('./lib/agents/pi');
+const { DirectRuntime } = require('./lib/runtimes/direct');
+const { SrtRuntime } = require('./lib/runtimes/srt');
+const { writeInlineSettingsFile } = require('../../shared/srt-settings');
+const { runAgent } = require('./lib/execution/lifecycle');
+const { ExecutionScheduler } = require('./lib/execution/scheduler');
+const { computeNodeStatus } = require('./lib/execution/status');
+
+// Registries. Adding a future adapter/runtime is just one more entry here --
+// nothing else in this file (or in lib/execution/lifecycle.js) needs to
+// change, per the spec's adapter-independence requirement. Concurrency
+// (lib/execution/scheduler.js) is likewise fully independent of both: it
+// only ever sees opaque { executionId, ... } items.
+const AGENTS = {
+    opencode: () => new OpenCodeAdapter(),
+    pi: () => new PiAdapter()
+};
+
+function buildRuntime(node) {
+    if (node.runtime === 'srt') {
+        return new SrtRuntime({
+            binary: node.srtBinary || undefined,
+            settingsPath: node.resolvedSrtSettingsPath || undefined
+        });
+    }
+    return new DirectRuntime();
+}
+
+let executionCounter = 0;
+function nextExecutionId() {
+    executionCounter += 1;
+    return `exec-${Date.now()}-${executionCounter}`;
+}
+
+module.exports = function (RED) {
+    'use strict';
+
+    function AgentNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+
+        node.agent = config.agent || 'opencode';
+        node.runtime = config.runtime || 'direct';
+        node.invocation = config.invocation || 'prompt';
+
+        node.model = config.model || '';
+        node.modelType = config.modelType || 'str';
+
+        node.prompt = config.prompt !== undefined ? config.prompt : 'payload';
+        node.promptType = config.promptType || 'msg';
+
+        // Same name/default/type as the agent-server node's sessionIdProp:
+        // absent/blank on a run -> a brand-new session is started (today's
+        // only behavior); present -> that session is resumed instead (only
+        // the OpenCode adapter supports this -- see lib/agents/opencode.js
+        // and lib/agents/pi.js).
+        node.sessionIdProp = config.sessionIdProp !== undefined ? config.sessionIdProp : 'sessionID';
+        node.sessionIdPropType = config.sessionIdPropType || 'msg';
+
+        node.invocationName = config.invocationName || '';
+        node.invocationNameType = config.invocationNameType || 'str';
+
+        node.arguments_ = config.arguments !== undefined ? config.arguments : 'payload';
+        node.argumentsType = config.argumentsType || 'msg';
+
+        node.cwd = config.cwd !== undefined ? config.cwd : 'cwd';
+        node.cwdType = config.cwdType || 'msg';
+
+        node.auto = config.auto === true;
+
+        node.timeout = config.timeout !== undefined ? config.timeout : '';
+        node.timeoutType = config.timeoutType || 'num';
+
+        node.mcpServers = Array.isArray(config.mcpServers) ? config.mcpServers : [];
+
+        node.srtBinary = config.srtBinary || '';
+        node.srtSettingsMode = config.srtSettingsMode || 'file';
+        node.srtSettingsPath = config.srtSettingsPath || '';
+        node.srtAllowedDomains = Array.isArray(config.srtAllowedDomains) ? config.srtAllowedDomains : [];
+        node.srtAllowedWriteDirs = Array.isArray(config.srtAllowedWriteDirs) ? config.srtAllowedWriteDirs : [];
+        node.srtStrictAllowlist = config.srtStrictAllowlist !== false;
+        node.srtAdvancedJson = config.srtAdvancedJson || '';
+
+        // Resolved once at construction time (not per-execution -- these
+        // settings don't change without a redeploy). For 'file' mode this
+        // is just srtSettingsPath itself; for 'inline' mode it's a
+        // generated temp settings file. node.resolvedSrtSettingsPath stays
+        // undefined (srt falls back to its own default) if unset/failed.
+        node.resolvedSrtSettingsPath = undefined;
+        node.srtTempSettingsFile = undefined;
+        node.srtSettingsError = undefined;
+
+        if (node.runtime === 'srt') {
+            if (node.srtSettingsMode === 'inline') {
+                try {
+                    node.resolvedSrtSettingsPath = writeInlineSettingsFile(node.id, {
+                        allowedDomains: node.srtAllowedDomains,
+                        allowedWriteDirs: node.srtAllowedWriteDirs,
+                        strictAllowlist: node.srtStrictAllowlist,
+                        advancedJson: node.srtAdvancedJson
+                    });
+                    node.srtTempSettingsFile = node.resolvedSrtSettingsPath;
+                } catch (err) {
+                    node.srtSettingsError = `invalid inline SRT settings JSON: ${err.message}`;
+                    node.error(`agent: ${node.srtSettingsError}`);
+                    node.status({ fill: 'red', shape: 'ring', text: 'bad srt settings' });
+                }
+            } else {
+                node.resolvedSrtSettingsPath = node.srtSettingsPath || undefined;
+            }
+        }
+
+        // Default 1 = sequential, matching today's single-node-single-run
+        // mental model unless a flow author explicitly opts into more.
+        const concurrencyNum = parseInt(config.concurrency, 10);
+        node.concurrency = Number.isFinite(concurrencyNum) && concurrencyNum > 0 ? concurrencyNum : 1;
+
+        // Last terminal outcome, shown once active+queued both drop to 0.
+        node.lastTerminal = undefined;
+        node.lastText = undefined;
+
+        function updateStatus() {
+            node.status(
+                computeNodeStatus({
+                    active: node.scheduler.activeCount,
+                    queued: node.scheduler.queuedCount,
+                    lastTerminal: node.lastTerminal,
+                    lastText: node.lastText
+                })
+            );
+        }
+
+        // Resolves a typed-input field the same way for every field: an
+        // empty property path is only meaningful for type 'str' (falls
+        // through to `fallback`); for 'msg'/'flow'/'global'/'env' an empty
+        // path is invalid, so it's never even evaluated.
+        function resolveTyped(prop, type, msg, fallback) {
+            if (prop === '') return fallback;
+            try {
+                const value = RED.util.evaluateNodeProperty(prop, type, node, msg);
+                return value === undefined || value === null ? fallback : value;
+            } catch (err) {
+                throw new Error(`invalid ${type} property "${prop}": ${err.message}`);
+            }
+        }
+
+        // Common envelope for every message on output 2 (the lifecycle/event
+        // stream): correlation (topic, executionId), live scheduler counts
+        // (so a widget bound to this stream always has the current
+        // active/queued numbers, no separate polling needed) and a
+        // timestamp (so external aggregation/history doesn't have to rely
+        // on message-arrival time).
+        function lifecycleEnvelope(msg, executionId, payload) {
+            return {
+                _msgid: msg._msgid,
+                topic: msg.topic,
+                payload,
+                agent: node.agent,
+                runtime: node.runtime,
+                executionId,
+                active: node.scheduler.activeCount,
+                queued: node.scheduler.queuedCount,
+                timestamp: Date.now()
+            };
+        }
+
+        function emitEvent(send, msg, executionId, type) {
+            send([null, lifecycleEnvelope(msg, executionId, { type })]);
+        }
+
+        // The actual work for one execution. Only ever invoked by the
+        // scheduler once a concurrency slot is free -- never called
+        // directly from the input handler.
+        function startExecution(item) {
+            const { executionId, msg, send, done, resolved } = item;
+            const adapter = AGENTS[node.agent]();
+            const runtime = buildRuntime(node);
+
+            return runAgent({
+                adapter,
+                runtime,
+                resolved,
+                executionId,
+                onEvent: (event) => {
+                    send([null, lifecycleEnvelope(msg, executionId, event)]);
+                },
+                onStatus: (status) => {
+                    if (status === 'running') {
+                        emitEvent(send, msg, executionId, 'running');
+                    } else {
+                        // Terminal (completed/failed/timeout): stash rather
+                        // than emit immediately -- the scheduler hasn't
+                        // removed this execution from `active` yet at this
+                        // point, so the active/queued counts on the
+                        // envelope would be stale by one. onSettled (below)
+                        // emits it once the scheduler's own bookkeeping,
+                        // including any newly-started queued item, is
+                        // fully settled.
+                        item.finalStatus = status;
+                    }
+                }
+            })
+                .then((result) => {
+                    node.lastTerminal = result.status;
+                    node.lastText = undefined;
+
+                    const resultMsg = Object.assign({}, msg, {
+                        payload: result.payload,
+                        agent: node.agent,
+                        runtime: node.runtime,
+                        // Top-level, in addition to agentExecution.sessionID
+                        // below: matches the agent-server node's convention
+                        // so this output can be fed straight back into the
+                        // (default) Session ID field -- msg.sessionID -- of
+                        // this or another agent node with no extra wiring.
+                        sessionID: result.sessionID,
+                        agentExecution: {
+                            id: executionId,
+                            status: result.status,
+                            exitCode: result.exitCode,
+                            signal: result.signal,
+                            timedOut: result.timedOut,
+                            durationMs: result.durationMs,
+                            sessionID: result.sessionID
+                        }
+                    });
+                    send([resultMsg, null]);
+
+                    if (result.status === 'failed' || result.status === 'timeout') {
+                        done(
+                            `agent (${node.agent}/${node.runtime}): ${result.status}` +
+                                (result.errorMessage ? ` -- ${result.errorMessage}` : '') +
+                                ` [executionId=${executionId} cwd=${resolved.cwd || '(default)'} exitCode=${result.exitCode}]`
+                        );
+                    } else {
+                        done();
+                    }
+                })
+                .catch((err) => {
+                    node.lastTerminal = 'failed';
+                    node.lastText = 'error';
+                    // Covers e.g. adapter.validate() throwing synchronously,
+                    // before onStatus('running') ever fires -- still needs a
+                    // terminal lifecycle event for anything tracking this
+                    // execution by executionId/topic.
+                    item.finalStatus = 'failed';
+                    done(new Error(`agent (${node.agent}/${node.runtime}) [executionId=${executionId}]: ${err.message}`));
+                });
+        }
+
+        node.scheduler = new ExecutionScheduler({
+            concurrency: node.concurrency,
+            onStart: startExecution,
+            onQueued: (item) => emitEvent(item.send, item.msg, item.executionId, 'queued'),
+            // Runs after this item is removed from `active` and any newly-
+            // eligible queued item has already been started, so the terminal
+            // event's active/queued counts are accurate (see the onStatus
+            // comment in startExecution for why it's deferred to here).
+            onSettled: (item) => {
+                if (item.finalStatus) emitEvent(item.send, item.msg, item.executionId, item.finalStatus);
+                updateStatus();
+            }
+        });
+
+        // On-demand termination of one in-flight (or still-queued) execution
+        // of *this* node instance, addressed by the executionId a previous
+        // trigger returned (msg.agentExecution.id / the events envelope's
+        // executionId). A separate msg from the one being terminated -- the
+        // terminated execution's own original done()/outputs still fire on
+        // their own once the process actually exits (status 'failed' with a
+        // SIGTERM/SIGKILL signal, same as any other non-zero exit), this
+        // handler's output/done is only the immediate "kill requested" ack.
+        function handleTerminateOperation(msg, send, done) {
+            const executionId = typeof msg.executionId === 'string' ? msg.executionId.trim() : '';
+            if (!executionId) {
+                done(new Error('agent: terminate requires msg.executionId'));
+                return;
+            }
+
+            const result = node.scheduler.cancel(executionId);
+            if (!result) {
+                done(new Error(`agent: unknown or already-finished executionId "${executionId}"`));
+                return;
+            }
+
+            if (result.status === 'queued') {
+                const queuedItem = result.item;
+                emitEvent(queuedItem.send, queuedItem.msg, executionId, 'cancelled');
+                queuedItem.done(new Error('agent: execution cancelled before it started (terminate requested)'));
+                updateStatus();
+                send([Object.assign({}, msg, { payload: { executionId, terminated: true, status: 'cancelled' } }), null]);
+                done();
+                return;
+            }
+
+            // Active: send SIGTERM (escalating to SIGKILL) to the whole
+            // process group. Works identically for both the direct and srt
+            // runtimes -- see process-exec.js's killProcessGroup -- so no
+            // per-runtime branching is needed here.
+            const runtime = buildRuntime(node);
+            Promise.resolve(runtime.terminate(executionId))
+                .then(() => {
+                    send([Object.assign({}, msg, { payload: { executionId, terminated: true, status: 'terminating' } }), null]);
+                    done();
+                })
+                .catch((err) => done(err));
+        }
+
+        node.on('input', function (msg, send, done) {
+            if (node.srtSettingsError) {
+                node.lastTerminal = 'failed';
+                node.lastText = 'bad srt settings';
+                updateStatus();
+                done(new Error(`agent: ${node.srtSettingsError}`));
+                return;
+            }
+
+            if (msg.operation === 'terminate') {
+                handleTerminateOperation(msg, send, done);
+                return;
+            }
+
+            let resolved;
+            try {
+                resolved = {
+                    invocation: node.invocation,
+                    prompt: node.invocation === 'prompt' ? resolveTyped(node.prompt, node.promptType, msg, msg.payload) : undefined,
+                    invocationName: node.invocation !== 'prompt' ? resolveTyped(node.invocationName, node.invocationNameType, msg, '') : undefined,
+                    args: node.invocation !== 'prompt' ? resolveTyped(node.arguments_, node.argumentsType, msg, msg.payload) : undefined,
+                    cwd: (() => {
+                        const v = resolveTyped(node.cwd, node.cwdType, msg, '');
+                        return v === undefined || v === null ? '' : String(v).trim();
+                    })(),
+                    sessionID: (() => {
+                        const v = resolveTyped(node.sessionIdProp, node.sessionIdPropType, msg, '');
+                        return v === undefined || v === null ? '' : String(v).trim();
+                    })(),
+                    model: (() => {
+                        const v = resolveTyped(node.model, node.modelType, msg, '');
+                        return v === undefined || v === null ? '' : String(v).trim();
+                    })(),
+                    auto: node.auto,
+                    timeoutMs: (() => {
+                        const v = resolveTyped(node.timeout, node.timeoutType, msg, undefined);
+                        const num = Number(v);
+                        return v === undefined || v === '' || !Number.isFinite(num) || num <= 0 ? undefined : num * 1000;
+                    })(),
+                    mcpServers: node.mcpServers
+                };
+            } catch (err) {
+                node.lastTerminal = 'failed';
+                node.lastText = 'bad config';
+                updateStatus();
+                done(err);
+                return;
+            }
+
+            if (!AGENTS[node.agent]) {
+                node.lastTerminal = 'failed';
+                node.lastText = 'unknown agent';
+                updateStatus();
+                done(new Error(`agent: unknown agent "${node.agent}"`));
+                return;
+            }
+
+            const executionId = nextExecutionId();
+            node.scheduler.submit({ executionId, msg, send, done, resolved });
+            updateStatus();
+        });
+
+        node.on('close', function (done) {
+            // Stop accepting further work first: drop anything still
+            // waiting in the queue with a clean done()/cancelled event,
+            // then terminate whatever's still actively running. No child
+            // process should be orphaned by a redeploy or node removal.
+            node.scheduler.drainQueue((item) => {
+                emitEvent(item.send, item.msg, item.executionId, 'cancelled');
+                item.done(new Error('agent: node closing, execution cancelled before it started'));
+            });
+
+            const runtime = buildRuntime(node);
+            const activeIds = node.scheduler.activeIds();
+            Promise.all(activeIds.map((id) => Promise.resolve(runtime.terminate(id)).catch(() => {}))).then(() => {
+                if (node.srtTempSettingsFile) {
+                    fs.unlink(node.srtTempSettingsFile, () => {});
+                }
+                node.status({});
+                done();
+            });
+        });
+    }
+
+    RED.nodes.registerType('agent', AgentNode);
+};

package/nodes/agent/icons/agent.svg

@@ -0,0 +1,27 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 40 60">
+  <!--
+    Node-RED custom node icon requirements (docs/creating-nodes/appearance.md):
+    white on transparent background, 2:3 aspect ratio, >= 40x60px.
+    This viewBox is exactly 40x60 (2:3). Eyes/mouth are cut as transparent
+    holes out of the solid white silhouette via a mask, so the shape reads
+    correctly against any node background color.
+  -->
+  <defs>
+    <mask id="agent-face-mask">
+      <rect x="0" y="0" width="40" height="60" fill="#ffffff"/>
+      <circle cx="14" cy="30" r="3.2" fill="#000000"/>
+      <circle cx="26" cy="30" r="3.2" fill="#000000"/>
+      <rect x="13" y="38" width="14" height="4" rx="2" fill="#000000"/>
+    </mask>
+  </defs>
+  <g fill="#ffffff" mask="url(#agent-face-mask)">
+    <!-- antenna -->
+    <circle cx="20" cy="6" r="3"/>
+    <rect x="18.5" y="9" width="3" height="6" rx="1.5"/>
+    <!-- head -->
+    <rect x="4" y="15" width="32" height="34" rx="8"/>
+    <!-- side ears -->
+    <rect x="0" y="26" width="4" height="10" rx="2"/>
+    <rect x="36" y="26" width="4" height="10" rx="2"/>
+  </g>
+</svg>

package/nodes/agent/lib/agents/base.js

@@ -0,0 +1,42 @@
+'use strict';
+
+// Generic interface every agent harness adapter (OpenCode, and later
+// Pi/Claude Code) must implement. The Agent node core only ever talks to
+// this interface -- it must never know about a specific agent's CLI flags.
+class AgentAdapter {
+    // Throws a descriptive Error if `resolved` (the already-typed-input
+    // -resolved config, see lib/execution/lifecycle.js) is not runnable.
+    // Must not have side effects beyond validation.
+    //
+    // `resolved.sessionID` (string, may be '' or undefined) is an optional
+    // continuation id: '' / undefined means "start a new session" (today's
+    // only behavior); a non-empty value asks the adapter to resume that
+    // session instead. An adapter that has no way to honor this (no
+    // underlying CLI/session concept, or one that's deliberately disabled
+    // -- see the Pi adapter) must throw here rather than silently ignoring
+    // it or starting a new session anyway.
+    validate(_resolved) {}
+
+    // Returns { command, args, env } -- a normalized, adapter-specific
+    // execution request. `args` must always be a plain array of strings;
+    // never a shell command string (see spec: spawn over exec).
+    buildExecution(_resolved) {
+        throw new Error('AgentAdapter.buildExecution() not implemented');
+    }
+
+    // Parses one line of stdout. Returns a normalized event object
+    // { type, sessionID, data } or null if the line should be ignored
+    // (blank, or malformed -- must never throw).
+    parseEvent(_line) {
+        return null;
+    }
+
+    // Given all accumulated parsed events plus the process exit info,
+    // returns { payload, sessionID, status, errorMessage? }.
+    // status is one of "completed" | "failed".
+    parseResult(_events, _exitCode, _signal, _stderr) {
+        return { payload: '', status: 'completed' };
+    }
+}
+
+module.exports = { AgentAdapter };

package/nodes/agent/lib/agents/opencode.js

@@ -0,0 +1,141 @@
+'use strict';
+
+const fs = require('fs');
+const { AgentAdapter } = require('./base');
+const { toOpenCodeMcp } = require('../mcp/normalize');
+
+// Maps opencode's real `--format json` event stream types (verified against
+// packages/opencode/src/cli/cmd/run.ts) onto the Agent node's generic event
+// vocabulary (spec section "Event output").
+const TYPE_MAP = {
+    step_start: 'started',
+    step_finish: 'progress',
+    tool_use: 'tool',
+    text: 'agent',
+    reasoning: 'agent',
+    error: 'failed'
+};
+
+class OpenCodeAdapter extends AgentAdapter {
+    validate(resolved) {
+        if (resolved.cwd) {
+            let stat;
+            try {
+                stat = fs.statSync(resolved.cwd);
+            } catch (err) {
+                throw new Error(`cwd does not exist: ${resolved.cwd}`);
+            }
+            if (!stat.isDirectory()) {
+                throw new Error(`cwd is not a directory: ${resolved.cwd}`);
+            }
+        }
+
+        if (resolved.invocation === 'prompt') {
+            if (!resolved.prompt || !String(resolved.prompt).trim()) {
+                throw new Error('prompt invocation requires a non-empty prompt (msg.payload or the Prompt field)');
+            }
+        } else if (resolved.invocation === 'skill' || resolved.invocation === 'command') {
+            if (!resolved.invocationName || !String(resolved.invocationName).trim()) {
+                throw new Error(`${resolved.invocation} invocation requires a non-empty name`);
+            }
+        } else {
+            throw new Error(`unknown invocation mode: ${resolved.invocation}`);
+        }
+
+        for (const server of resolved.mcpServers || []) {
+            if (!server || !server.name) {
+                throw new Error('mcpServers entries require a name');
+            }
+            if (server.type === 'remote' && !server.url) {
+                throw new Error(`mcp server "${server.name}" (remote) requires a url`);
+            }
+            if (server.type === 'local' && !server.command) {
+                throw new Error(`mcp server "${server.name}" (local) requires a command`);
+            }
+            if (server.type !== 'remote' && server.type !== 'local') {
+                throw new Error(`mcp server "${server.name}" has unknown type: ${server.type}`);
+            }
+        }
+    }
+
+    buildExecution(resolved) {
+        const args = ['run', '--format', 'json'];
+
+        // Resuming an existing session (opencode run -s <id> ...) rather
+        // than always starting a new one -- verified against `opencode run
+        // --help`: -s/--session takes the id to continue.
+        if (resolved.sessionID) args.push('--session', String(resolved.sessionID));
+
+        if (resolved.cwd) args.push('--dir', resolved.cwd);
+        if (resolved.model) args.push('--model', resolved.model);
+        if (resolved.auto) args.push('--auto');
+
+        // Skill and Command/Template invocation share the same underlying
+        // opencode mechanism: skills are registered internally as commands
+        // (source:"skill"), so `--command <name>` handles both -- verified
+        // against packages/opencode/src/command/index.ts.
+        if (resolved.invocation === 'skill' || resolved.invocation === 'command') {
+            args.push('--command', String(resolved.invocationName));
+            args.push(resolved.args !== undefined && resolved.args !== null ? String(resolved.args) : '');
+        } else {
+            args.push(String(resolved.prompt));
+        }
+
+        const env = {};
+        if (Array.isArray(resolved.mcpServers) && resolved.mcpServers.length > 0) {
+            env.OPENCODE_CONFIG_CONTENT = JSON.stringify({ mcp: toOpenCodeMcp(resolved.mcpServers) });
+        }
+
+        return { command: 'opencode', args, env };
+    }
+
+    parseEvent(line) {
+        const trimmed = line.trim();
+        if (!trimmed) return null;
+
+        let raw;
+        try {
+            raw = JSON.parse(trimmed);
+        } catch (err) {
+            // Malformed/non-JSON diagnostic output must never crash Node-RED.
+            return null;
+        }
+
+        const type = TYPE_MAP[raw.type] || raw.type || 'progress';
+        return { type, sessionID: raw.sessionID, data: raw };
+    }
+
+    parseResult(events, exitCode, signal, stderr) {
+        const raw = events.map((e) => e.data);
+        const errorEvent = raw.find((e) => e.type === 'error');
+        const sessionID = raw.length ? raw[raw.length - 1].sessionID : undefined;
+
+        const payload = raw
+            .filter((e) => e.type === 'text' && e.part && typeof e.part.text === 'string')
+            .map((e) => e.part.text)
+            .join('\n')
+            .trim();
+
+        if (errorEvent) {
+            const message =
+                (errorEvent.error &&
+                    ((errorEvent.error.data && errorEvent.error.data.message) || errorEvent.error.name)) ||
+                'opencode reported an error';
+            return { payload, sessionID, status: 'failed', errorMessage: message };
+        }
+        if (signal) {
+            return { payload, sessionID, status: 'failed', errorMessage: `process killed by signal ${signal}` };
+        }
+        if (exitCode !== 0) {
+            return {
+                payload,
+                sessionID,
+                status: 'failed',
+                errorMessage: `exited with code ${exitCode}${stderr ? ': ' + String(stderr).trim() : ''}`
+            };
+        }
+        return { payload, sessionID, status: 'completed' };
+    }
+}
+
+module.exports = { OpenCodeAdapter };