@tbrandenburg/node-red-agents 0.3.6 → 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") {
@@ -250,6 +253,14 @@ module.exports = function (RED) {
               timedOut: result.timedOut,
               durationMs: result.durationMs,
               sessionID: result.sessionID,
+              // Raw error object from the adapter (e.g. opencode's full
+              // {"type":"error"} payload, or pi's failing assistant
+              // message) when the run failed -- the `done(err)` string
+              // below only carries a single summarized message/name, so
+              // anything needing the fuller detail (extra fields the
+              // adapter didn't fold into errorMessage) should wire a
+              // Debug node to output 1 and inspect this field.
+              errorDetail: result.errorDetail,
             },
           });
           send([resultMsg, null]);

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;
@@ -119,11 +122,41 @@ class OpenCodeAdapter extends AgentAdapter {
       .trim();
 
     if (errorEvent) {
+      const errDetail = errorEvent.error || {};
       const message =
-        (errorEvent.error &&
-          ((errorEvent.error.data && errorEvent.error.data.message) || errorEvent.error.name)) ||
+        (errDetail.data && errDetail.data.message) ||
+        errDetail.name ||
         "opencode reported an error";
-      return { payload, sessionID, status: "failed", errorMessage: message };
+      // The JSON error event only carries opencode's own top-level
+      // 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 {
+        payload,
+        sessionID,
+        status: "failed",
+        errorMessage,
+        errorDetail: errDetail,
+      };
     }
     if (signal) {
       return {

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

@@ -186,9 +186,10 @@ class PiAdapter extends AgentAdapter {
 
     let payload = "";
     let errorMessage;
+    let lastAssistant;
 
     if (agentEnd && Array.isArray(agentEnd.messages)) {
-      const lastAssistant = [...agentEnd.messages].reverse().find((m) => m.role === "assistant");
+      lastAssistant = [...agentEnd.messages].reverse().find((m) => m.role === "assistant");
       if (lastAssistant) {
         if (lastAssistant.stopReason === "error") {
           // pi does NOT set a non-zero exit code for a model/API
@@ -207,7 +208,17 @@ class PiAdapter extends AgentAdapter {
     }
 
     if (errorMessage) {
-      return { payload, sessionID, status: "failed", errorMessage };
+      // Same rationale as the opencode adapter: stderr is otherwise
+      // silently dropped for this branch (it's only appended in the
+      // exitCode!==0 branch below).
+      const extra = stderr && String(stderr).trim() ? ` (${String(stderr).trim()})` : "";
+      return {
+        payload,
+        sessionID,
+        status: "failed",
+        errorMessage: `${errorMessage}${extra}`,
+        errorDetail: lastAssistant,
+      };
     }
     if (signal) {
       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/README.md

@@ -49,7 +49,23 @@ configuration for that message.
 
 A non-zero exit code, a timeout, or a missing `gh` executable all go through
 `done(error)` (catchable with a Catch node) instead of producing an output
-message.
+message. Every such error carries an `err.errorType` string so flows can
+branch on it without regex-matching gh's (locale/version dependent) human
+-readable stderr text themselves:
+
+| `errorType`        | When                                                                          |
+| ------------------- | ------------------------------------------------------------------------------ |
+| `auth`              | Not logged in / bad credentials (stderr mentions `gh auth login`, etc.)       |
+| `rate-limit`        | GitHub API (primary or secondary) rate limit exceeded                        |
+| `feature-disabled`  | Repo has issues/PRs/projects disabled (e.g. this ticket's original report)    |
+| `not-found`         | Repository/resource doesn't exist or can't be resolved                       |
+| `permission`        | 403 / insufficient permissions                                               |
+| `network`           | Network failure or timeout talking to GitHub                                 |
+| `not-installed`     | `gh` executable not found on `PATH` (spawn `ENOENT`)                          |
+| `spawn-failed`      | The child process could not be started for another reason                    |
+| `timeout`           | The command exceeded the configured Timeout and was killed                   |
+| `killed`            | The command was killed by a signal other than the node's own timeout         |
+| `unknown`           | Non-zero exit whose stderr didn't match any known pattern                    |
 
 ## Example
 

package/nodes/gh/gh.js

@@ -38,6 +38,30 @@ function validateCommand(command) {
   return null;
 }
 
+// Classifies a gh stderr message into a stable, machine-checkable category so
+// downstream flows can branch on `err.errorType` instead of regex-matching
+// 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",
+  ],
+  [/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"],
+  [/403|resource not accessible|must have admin rights|permission/i, "permission"],
+  [/network|timed out|econnreset|enotfound/i, "network"],
+];
+
+function classifyGhError(stderr) {
+  if (!stderr) return "unknown";
+  for (const [pattern, type] of ERROR_TYPE_PATTERNS) {
+    if (pattern.test(stderr)) return type;
+  }
+  return "unknown";
+}
+
 // Resolves an "args" value (from config or msg.gh.args) into a string[].
 // Strings are tokenized (quote-aware, no shell evaluation); arrays are used
 // as-is (each element coerced to a string); anything else is rejected.
@@ -172,6 +196,7 @@ module.exports = function (RED) {
         const wrapped = new Error("gh: " + message);
         wrapped.command = command;
         wrapped.args = args;
+        wrapped.errorType = err && err.code === "ENOENT" ? "not-installed" : "spawn-failed";
         done(wrapped);
       });
 
@@ -188,19 +213,23 @@ module.exports = function (RED) {
           err.args = args;
           err.signal = signal;
           err.timedOut = timedOut;
+          err.errorType = timedOut ? "timeout" : "killed";
           done(err);
           return;
         }
 
         if (code !== 0) {
-          node.status({ fill: "red", shape: "dot", text: "exit " + code });
+          const trimmedStderr = stderr.trim();
+          const errorType = classifyGhError(trimmedStderr);
+          node.status({ fill: "red", shape: "dot", text: errorType + " (exit " + code + ")" });
           const err = new Error(
-            "gh: command failed (exit " + code + ")" + (stderr.trim() ? ": " + stderr.trim() : ""),
+            "gh: command failed (exit " + code + ")" + (trimmedStderr ? ": " + trimmedStderr : ""),
           );
           err.command = command;
           err.args = args;
           err.exitCode = code;
-          err.stderr = stderr.trim();
+          err.stderr = trimmedStderr;
+          err.errorType = errorType;
           done(err);
           return;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tbrandenburg/node-red-agents",
-  "version": "0.3.6",
+  "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 };