@tbrandenburg/node-red-agents 0.3.7 → 0.3.8

package/README.md

@@ -19,7 +19,9 @@ and example flows (`nodes/gh/examples/`).
 
 ## Requirements
 
-- Node-RED >= 4.0.0, Node.js >= 22
+- Node-RED >= 4.0.0, Node.js >= 20
+  (Node.js 20 compatibility is verified for these nodes; the monorepo's own
+  dev/CI tooling still targets Node.js 22, see the repo root `.nvmrc`)
 - The [`opencode`](https://opencode.ai) CLI on `PATH` (for `agent`/`agent-server`)
 - [`srt`](https://github.com/anthropics/sandbox-runtime) on `PATH`, only if using the SRT runtime option
 - The [`gh`](https://cli.github.com) CLI on `PATH`, authenticated (for `gh`)

package/nodes/agent/agent.html

@@ -120,7 +120,18 @@
                 srtAllowedDomains: { value: [] },
                 srtAllowedWriteDirs: { value: ['.', '/tmp', '~/.local/share/opencode'] },
                 srtStrictAllowlist: { value: true },
-                srtAdvancedJson: { value: '' }
+                srtAdvancedJson: {
+                    value: '',
+                    validate: function (v) {
+                        if (!v || !v.trim()) return true;
+                        try {
+                            JSON.parse(v);
+                            return true;
+                        } catch (err) {
+                            return false;
+                        }
+                    }
+                }
             },
             inputs: 1,
             outputs: 2,
@@ -312,8 +323,49 @@
                     });
                     return values;
                 }
-                this.srtAllowedDomains = collectStrings($('#node-input-srtAllowedDomains-list'));
-                this.srtAllowedWriteDirs = collectStrings($('#node-input-srtAllowedWriteDirs-list'));
+
+                // Only persist the SRT inline-settings lists/fields while
+                // they're actually the active runtime+mode -- otherwise
+                // reset them to their defaults. Without this, switching
+                // Runtime back to Direct (or SRT settings back to File
+                // path) silently keeps whatever domains/directories/JSON
+                // were entered earlier, still saved into the flow even
+                // though the now-hidden fields are irrelevant to the
+                // deployed config -- confusing at best, and a footgun if
+                // the runtime is ever switched back to SRT without
+                // re-checking these stale values.
+                //
+                // Note: Node-RED's own core copies each defaults-bound
+                // plain input's *current DOM value* into `this[key]`
+                // right after oneditsave returns, so setting e.g.
+                // `this.srtSettingsMode` here alone is not enough -- a
+                // hidden <select>/<input>/<textarea> still holds its old
+                // value and would silently overwrite it straight back.
+                // The reset has to touch the DOM element itself for any
+                // field with a plain `#node-input-<name>` binding;
+                // srtAllowedDomains/srtAllowedWriteDirs are the exception
+                // (no such element exists -- only the "-list" editableList
+                // container), so those are fine set directly on `this`.
+                const runtime = $('#node-input-runtime').val();
+                const srtSettingsMode = $('#node-input-srtSettingsMode').val();
+
+                if (runtime !== 'srt') {
+                    $('#node-input-srtSettingsMode').val('file');
+                    $('#node-input-srtSettingsPath').val('');
+                    $('#node-input-srtBinary').val('');
+                    $('#node-input-srtStrictAllowlist').prop('checked', true);
+                    $('#node-input-srtAdvancedJson').val('');
+                    this.srtAllowedDomains = [];
+                    this.srtAllowedWriteDirs = ['.', '/tmp', '~/.local/share/opencode'];
+                } else if (srtSettingsMode !== 'inline') {
+                    $('#node-input-srtStrictAllowlist').prop('checked', true);
+                    $('#node-input-srtAdvancedJson').val('');
+                    this.srtAllowedDomains = [];
+                    this.srtAllowedWriteDirs = ['.', '/tmp', '~/.local/share/opencode'];
+                } else {
+                    this.srtAllowedDomains = collectStrings($('#node-input-srtAllowedDomains-list'));
+                    this.srtAllowedWriteDirs = collectStrings($('#node-input-srtAllowedWriteDirs-list'));
+                }
             }
         });
     }());

package/nodes/agent/agent.js

@@ -208,7 +208,10 @@ module.exports = function (RED) {
         resolved,
         executionId,
         onEvent: (event) => {
-          send([null, lifecycleEnvelope(msg, executionId, event, resolved.agentName, resolved.cwd)]);
+          send([
+            null,
+            lifecycleEnvelope(msg, executionId, event, resolved.agentName, resolved.cwd),
+          ]);
         },
         onStatus: (status) => {
           if (status === "running") {

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

@@ -3,6 +3,7 @@
 const fs = require("fs");
 const { AgentAdapter } = require("./base");
 const { toOpenCodeMcp } = require("../mcp/normalize");
+const { assertModelFormat } = require("../../../../shared/model-format");
 
 // 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
@@ -18,6 +19,8 @@ const TYPE_MAP = {
 
 class OpenCodeAdapter extends AgentAdapter {
   validate(resolved) {
+    assertModelFormat(resolved.model);
+
     if (resolved.cwd) {
       let stat;
       try {
@@ -107,7 +110,7 @@ class OpenCodeAdapter extends AgentAdapter {
     return { type, sessionID: raw.sessionID, data: raw };
   }
 
-  parseResult(events, exitCode, signal, stderr) {
+  parseResult(events, exitCode, signal, stderr, resolved) {
     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;
@@ -121,14 +124,30 @@ class OpenCodeAdapter extends AgentAdapter {
     if (errorEvent) {
       const errDetail = errorEvent.error || {};
       const message =
-        (errDetail.data && errDetail.data.message) || errDetail.name || "opencode reported an error";
+        (errDetail.data && errDetail.data.message) ||
+        errDetail.name ||
+        "opencode reported an error";
       // The JSON error event only carries opencode's own top-level
-      // message/name -- append name (if distinct) and any stderr output
-      // opencode wrote alongside it, since both would otherwise be
-      // silently dropped here (unlike the exitCode!==0 branch below,
-      // which already surfaces stderr).
+      // message/name -- append name (if distinct), its diagnostic ref (if
+      // any -- note this does NOT reliably show up in opencode's own log
+      // file, verified empirically, so it's a weak clue at best), and any
+      // stderr output opencode wrote alongside it, since all three would
+      // otherwise be silently dropped here (unlike the exitCode!==0
+      // branch below, which already surfaces stderr).
       const extras = [];
       if (errDetail.name && errDetail.name !== message) extras.push(errDetail.name);
+      if (errDetail.data && errDetail.data.ref) extras.push(`ref=${errDetail.data.ref}`);
+      // "UnknownError" is opencode's catch-all for a request the provider/
+      // server rejected before generating any content -- in practice the
+      // single most common trigger we've seen is a `--model` value that
+      // doesn't exist (wrong provider, typo, or a model that isn't
+      // actually available to this account). It's not the only possible
+      // cause, so this is phrased as a hint, not a diagnosis.
+      if (errDetail.name === "UnknownError" && resolved && resolved.model) {
+        extras.push(
+          `possible cause: model "${resolved.model}" may not exist or isn't available -- run "opencode models" to check`,
+        );
+      }
       if (stderr && String(stderr).trim()) extras.push(String(stderr).trim());
       const errorMessage = extras.length ? `${message} (${extras.join("; ")})` : message;
       return {

package/nodes/agent/lib/execution/lifecycle.js

@@ -51,7 +51,13 @@ async function runAgent({ adapter, runtime, resolved, executionId, onEvent, onSt
   });
 
   const durationMs = Date.now() - startedAt;
-  const result = adapter.parseResult(events, outcome.exitCode, outcome.signal, outcome.stderr);
+  const result = adapter.parseResult(
+    events,
+    outcome.exitCode,
+    outcome.signal,
+    outcome.stderr,
+    resolved,
+  );
   const status = outcome.timedOut ? "timeout" : result.status;
 
   if (onStatus) onStatus(status);

package/nodes/agent-server/agent-server.html

@@ -49,7 +49,18 @@
                 srtAllowedDomains: { value: [] },
                 srtAllowedWriteDirs: { value: ['.', '/tmp', '~/.local/share/opencode'] },
                 srtStrictAllowlist: { value: true },
-                srtAdvancedJson: { value: '' }
+                srtAdvancedJson: {
+                    value: '',
+                    validate: function (v) {
+                        if (!v || !v.trim()) return true;
+                        try {
+                            JSON.parse(v);
+                            return true;
+                        } catch (err) {
+                            return false;
+                        }
+                    }
+                }
             },
             inputs: 1,
             outputs: 2,
@@ -135,8 +146,46 @@
                     });
                     return values;
                 }
-                this.srtAllowedDomains = collectStrings($('#node-input-srtAllowedDomains-list'));
-                this.srtAllowedWriteDirs = collectStrings($('#node-input-srtAllowedWriteDirs-list'));
+
+                // Same rationale as the agent node's oneditsave: only
+                // persist the SRT inline-settings lists/fields while
+                // they're actually the active runtime+mode, otherwise
+                // reset them to their defaults so switching back to
+                // Direct (or File path mode) doesn't silently leave a
+                // stale SRT config sitting in the deployed flow.
+                //
+                // Note: Node-RED's own core copies each defaults-bound
+                // plain input's *current DOM value* into `this[key]`
+                // right after oneditsave returns, so the reset has to
+                // touch the DOM element itself for any field with a
+                // plain `#node-input-<name>` binding (srtSettingsMode,
+                // srtSettingsPath, srtBinary, srtStrictAllowlist,
+                // srtAdvancedJson) -- setting `this.<name>` alone would
+                // get silently overwritten straight back by that hidden
+                // element's stale value. srtAllowedDomains/
+                // srtAllowedWriteDirs are the exception (no such element
+                // exists -- only the "-list" editableList container), so
+                // those are fine set directly on `this`.
+                const runtime = $('#node-input-runtime').val();
+                const srtSettingsMode = $('#node-input-srtSettingsMode').val();
+
+                if (runtime !== 'srt') {
+                    $('#node-input-srtSettingsMode').val('file');
+                    $('#node-input-srtSettingsPath').val('');
+                    $('#node-input-srtBinary').val('');
+                    $('#node-input-srtStrictAllowlist').prop('checked', true);
+                    $('#node-input-srtAdvancedJson').val('');
+                    this.srtAllowedDomains = [];
+                    this.srtAllowedWriteDirs = ['.', '/tmp', '~/.local/share/opencode'];
+                } else if (srtSettingsMode !== 'inline') {
+                    $('#node-input-srtStrictAllowlist').prop('checked', true);
+                    $('#node-input-srtAdvancedJson').val('');
+                    this.srtAllowedDomains = [];
+                    this.srtAllowedWriteDirs = ['.', '/tmp', '~/.local/share/opencode'];
+                } else {
+                    this.srtAllowedDomains = collectStrings($('#node-input-srtAllowedDomains-list'));
+                    this.srtAllowedWriteDirs = collectStrings($('#node-input-srtAllowedWriteDirs-list'));
+                }
             }
         });
     }());

package/nodes/agent-server/lib/model.js

@@ -1,5 +1,7 @@
 "use strict";
 
+const { assertModelFormat } = require("../../../shared/model-format");
+
 // The `agent` node's --model flag accepts a plain "provider/model" string
 // (opencode's CLI parses that itself). The HTTP API has no such shorthand --
 // POST /session/:id/message's `model` field must be a
@@ -10,12 +12,8 @@
 function parseModel(value) {
   if (value === undefined || value === null || value === "") return undefined;
   const str = String(value);
+  assertModelFormat(str); // throws with a shared, consistent message (see shared/model-format.js)
   const slash = str.indexOf("/");
-  if (slash <= 0 || slash === str.length - 1) {
-    throw new Error(
-      `invalid model "${str}" -- expected "provider/model" (e.g. "github-copilot/claude-sonnet-4.6")`,
-    );
-  }
   return { providerID: str.slice(0, slash), modelID: str.slice(slash + 1) };
 }
 

package/nodes/gh/gh.js

@@ -43,7 +43,10 @@ function validateCommand(command) {
 // the (locale/version dependent) human-readable message themselves. Order
 // matters: more specific patterns are checked before generic ones.
 const ERROR_TYPE_PATTERNS = [
-  [/not logged into|to authenticate|gh auth login|authentication required|bad credentials/i, "auth"],
+  [
+    /not logged into|to authenticate|gh auth login|authentication required|bad credentials/i,
+    "auth",
+  ],
   [/api rate limit exceeded|secondary rate limit/i, "rate-limit"],
   [/has disabled issues|has disabled pull requests|has disabled projects/i, "feature-disabled"],
   [/could not resolve to a repository|repository not found|404/i, "not-found"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tbrandenburg/node-red-agents",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "Node-RED nodes for running coding agents (opencode, pi) and GitHub CLI operations from flows.",
   "keywords": [
     "node-red",
@@ -41,7 +41,7 @@
     "!**/fixtures/**"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=20"
   },
   "scripts": {
     "test": "node --test --experimental-test-coverage=false 'nodes/**/test/**/*.spec.js' 'shared/**/test/**/*.spec.js'"

package/shared/model-format.js

@@ -0,0 +1,34 @@
+"use strict";
+
+// opencode's model identifiers are always "provider/model" (e.g.
+// "github-copilot/claude-sonnet-5"). Both the `agent` node (which passes
+// the string straight through to `opencode run --model`) and the
+// `agent-server` node (which splits it into { providerID, modelID } for the
+// HTTP API, see agent-server/lib/model.js) need the same shape check.
+//
+// This exists because a malformed or non-existent model string currently
+// only surfaces as opencode's own generic, unhelpful failure -- e.g.
+// `opencode run --model bogus "hi"` prints
+//   {"type":"error","error":{"name":"UnknownError","data":{"message":
+//   "Unexpected server error. Check server logs for details.","ref":"err_..."}}}
+// with exit code 0, and that "err_..." ref does *not* actually appear in
+// opencode's own log file (verified empirically) -- so "check server logs"
+// is a dead end. Catching an obviously-malformed string (no slash, or an
+// empty provider/model half) before ever spawning opencode turns that into
+// an immediate, actionable Node-RED error instead. It cannot catch a
+// syntactically valid but non-existent "provider/model" pair -- that still
+// requires either `opencode models` (see opencode's own --help) or opencode
+// fixing its own error reporting.
+function assertModelFormat(value) {
+  if (value === undefined || value === null || value === "") return;
+  const str = String(value);
+  const slash = str.indexOf("/");
+  if (slash <= 0 || slash === str.length - 1) {
+    throw new Error(
+      `invalid model "${str}" -- expected "provider/model" (e.g. "github-copilot/claude-sonnet-5"); ` +
+        `run "opencode models" to list valid values`,
+    );
+  }
+}
+
+module.exports = { assertModelFormat };