@tbrandenburg/node-red-agents 0.3.7 → 0.4.0

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 {
@@ -72,6 +75,15 @@ class OpenCodeAdapter extends AgentAdapter {
     if (resolved.model) args.push("--model", resolved.model);
     if (resolved.auto) args.push("--auto");
 
+    // --variant <effort> -- verified working against a real `opencode run`
+    // invocation (see CAPABILITIES.effortControl below). systemPrompt has
+    // no verified CLI flag for this adapter (CAPABILITIES.systemPromptControl
+    // is false), so it's never forwarded here -- agent.js already warns and
+    // drops it before this is even called.
+    if (OpenCodeAdapter.CAPABILITIES.effortControl && resolved.effort) {
+      args.push("--variant", resolved.effort);
+    }
+
     // 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
@@ -84,8 +96,36 @@ class OpenCodeAdapter extends AgentAdapter {
     }
 
     const env = {};
+    const opencodeConfig = {};
     if (Array.isArray(resolved.mcpServers) && resolved.mcpServers.length > 0) {
-      env.OPENCODE_CONFIG_CONTENT = JSON.stringify({ mcp: toOpenCodeMcp(resolved.mcpServers) });
+      opencodeConfig.mcp = toOpenCodeMcp(resolved.mcpServers);
+    }
+
+    // allowed_tools/denied_tools (issue #25): opencode has no direct
+    // `--tools` flag (unlike pi.js), but its config schema supports a
+    // per-agent `tools: { <name>: true|false }` map (verified against
+    // opencode's own agent docs). Rather than inventing a new delivery
+    // mechanism, this reuses the exact same OPENCODE_CONFIG_CONTENT env
+    // var already used for mcpServers above -- an ephemeral, per-process
+    // config the child process reads and that vanishes with it, with
+    // nothing left on disk to clean up (unlike the srt inline-settings
+    // temp file, which outlives the process and does need explicit
+    // unlinking). A fixed, unique-per-node agent name is defined as
+    // "primary" (required for `opencode run --agent <name>` to accept it)
+    // and selected via --agent.
+    const hasAllow = Array.isArray(resolved.allowedTools) && resolved.allowedTools.length > 0;
+    const hasDeny = Array.isArray(resolved.deniedTools) && resolved.deniedTools.length > 0;
+    if (OpenCodeAdapter.CAPABILITIES.toolRestrictions && (hasAllow || hasDeny)) {
+      const tools = {};
+      for (const name of resolved.deniedTools || []) tools[name] = false;
+      for (const name of resolved.allowedTools || []) tools[name] = true;
+      const agentName = "node-red-agent-tools";
+      opencodeConfig.agent = { [agentName]: { mode: "primary", tools } };
+      args.push("--agent", agentName);
+    }
+
+    if (Object.keys(opencodeConfig).length > 0) {
+      env.OPENCODE_CONFIG_CONTENT = JSON.stringify(opencodeConfig);
     }
 
     return { command: "opencode", args, env };
@@ -107,7 +147,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;
@@ -118,45 +158,137 @@ class OpenCodeAdapter extends AgentAdapter {
       .join("\n")
       .trim();
 
+    // Sums cost/tokens across every step_finish event seen during this run
+    // -- verified against a real `opencode run --format json` invocation,
+    // whose step_finish `part` carries { tokens: {input,output,reasoning,
+    // cache:{read,write},total}, cost }. `costUsd`/`tokens` stay undefined
+    // (rather than 0) when no step_finish event was observed at all, so
+    // agent.js can omit the fields entirely instead of reporting a false 0.
+    const usage = summarizeUsage(raw);
+
     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 {
-        payload,
-        sessionID,
-        status: "failed",
-        errorMessage,
-        errorDetail: errDetail,
-      };
+      return Object.assign(
+        {
+          payload,
+          sessionID,
+          status: "failed",
+          errorMessage,
+          errorDetail: errDetail,
+        },
+        usage,
+      );
     }
     if (signal) {
-      return {
-        payload,
-        sessionID,
-        status: "failed",
-        errorMessage: `process killed by signal ${signal}`,
-      };
+      return Object.assign(
+        {
+          payload,
+          sessionID,
+          status: "failed",
+          errorMessage: `process killed by signal ${signal}`,
+        },
+        usage,
+      );
     }
     if (exitCode !== 0) {
-      return {
-        payload,
-        sessionID,
-        status: "failed",
-        errorMessage: `exited with code ${exitCode}${stderr ? ": " + String(stderr).trim() : ""}`,
+      return Object.assign(
+        {
+          payload,
+          sessionID,
+          status: "failed",
+          errorMessage: `exited with code ${exitCode}${stderr ? ": " + String(stderr).trim() : ""}`,
+        },
+        usage,
+      );
+    }
+    if (!payload) {
+      return Object.assign(
+        {
+          payload,
+          sessionID,
+          status: "failed",
+          errorMessage:
+            "opencode produced no assistant output (silent rejection or empty response)",
+        },
+        usage,
+      );
+    }
+    return Object.assign({ payload, sessionID, status: "completed" }, usage);
+  }
+}
+
+// Sums cost (USD) and token counts across every step_finish event in a run.
+// Returns {} (no keys at all) when no step_finish event carried usable
+// data, so Object.assign(...) callers above never introduce costUsd/tokens
+// keys with `undefined` values -- agent.js relies on the key's mere
+// presence (not just its value) to decide whether to surface it.
+function summarizeUsage(raw) {
+  let costUsd;
+  let tokens;
+  for (const e of raw) {
+    if (e.type !== "step_finish" || !e.part || typeof e.part !== "object") continue;
+    const part = e.part;
+    if (typeof part.cost === "number") {
+      costUsd = (costUsd || 0) + part.cost;
+    }
+    if (part.tokens && typeof part.tokens === "object") {
+      tokens = tokens || {
+        total: 0,
+        input: 0,
+        output: 0,
+        reasoning: 0,
+        cache: { read: 0, write: 0 },
       };
+      tokens.total += Number(part.tokens.total) || 0;
+      tokens.input += Number(part.tokens.input) || 0;
+      tokens.output += Number(part.tokens.output) || 0;
+      tokens.reasoning += Number(part.tokens.reasoning) || 0;
+      if (part.tokens.cache) {
+        tokens.cache.read += Number(part.tokens.cache.read) || 0;
+        tokens.cache.write += Number(part.tokens.cache.write) || 0;
+      }
     }
-    return { payload, sessionID, status: "completed" };
   }
+  const usage = {};
+  if (costUsd !== undefined) usage.costUsd = costUsd;
+  if (tokens !== undefined) usage.tokens = tokens;
+  return usage;
 }
 
+OpenCodeAdapter.CAPABILITIES = {
+  sessionResume: true, // opencode.js -s/--session verified working
+  structuredOutput: "best-effort", // no --schema/--json-schema CLI flag
+  toolRestrictions: true, // via materialized temp agent config + --agent
+  effortControl: true, // --variant, verified working
+  systemPromptControl: false, // no CLI flag found
+  costReporting: true, // step_finish tokens/cost already in --format json stream
+};
+
 module.exports = { OpenCodeAdapter };

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

@@ -118,7 +118,21 @@ class PiAdapter extends AgentAdapter {
     // tools are even available: "not auto" -> read-only tool set,
     // "auto" -> everything. This is an approximation, not a true
     // permission bypass -- documented in the node's help text.
-    if (!resolved.auto) {
+    //
+    // allowed_tools (issue #25): a configured allow-list always wins over
+    // the auto-derived default above, for both auto and non-auto runs --
+    // an explicit list is a stronger signal than the auto/read-only
+    // heuristic. denied_tools has no equivalent here: pi's --tools flag is
+    // allow-list-only (verified against `pi --help`), so there's no
+    // mechanism to subtract individual tools from an otherwise-unbounded
+    // set; only allowedTools is wired up for this adapter.
+    const hasAllow =
+      PiAdapter.CAPABILITIES.toolRestrictions &&
+      Array.isArray(resolved.allowedTools) &&
+      resolved.allowedTools.length > 0;
+    if (hasAllow) {
+      args.push("--tools", resolved.allowedTools.join(","));
+    } else if (!resolved.auto) {
       args.push("--tools", "read,grep,find,ls");
     }
 
@@ -244,8 +258,25 @@ class PiAdapter extends AgentAdapter {
         errorMessage: "pi produced no agent_end event",
       };
     }
+    if (!payload) {
+      return {
+        payload,
+        sessionID,
+        status: "failed",
+        errorMessage: "pi produced no assistant output (silent rejection or empty response)",
+      };
+    }
     return { payload, sessionID, status: "completed" };
   }
 }
 
+PiAdapter.CAPABILITIES = {
+  sessionResume: false, // every run uses --no-session
+  structuredOutput: "best-effort", // no schema CLI flag; prompt+parse only
+  toolRestrictions: true, // --tools flag
+  effortControl: false, // no verified CLI flag yet (pi not installed here)
+  systemPromptControl: false, // no verified CLI flag yet
+  costReporting: false, // pi CLI not installed/verified
+};
+
 module.exports = { PiAdapter, resolveResourcePath };

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

@@ -0,0 +1,22 @@
+"use strict";
+
+// Pure string-templating helper for issue #20's $INPUTS.<name> substitution.
+// Deliberately dumb: no BindingDirective/DAG concept (see issue text) --
+// just a name -> value map applied to a single free-text string before it
+// becomes the invocation's resolved.args, adapter-agnostic. Unmatched
+// tokens are left as literal text rather than throwing, so a typo in a
+// flow's arguments string degrades to visible-but-harmless output instead
+// of a hard failure.
+const TOKEN_RE = /\$INPUTS\.([A-Za-z0-9_]+)/g;
+
+function substituteInputs(text, inputsMap) {
+  if (typeof text !== "string" || !text) return text;
+  const map = inputsMap || {};
+  return text.replace(TOKEN_RE, (match, name) => {
+    if (!Object.prototype.hasOwnProperty.call(map, name)) return match;
+    const value = map[name];
+    return value === undefined || value === null ? match : String(value);
+  });
+}
+
+module.exports = { substituteInputs };

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/lib/execution/retry.js

@@ -0,0 +1,61 @@
+"use strict";
+
+// Node-level retry classification (issue #24). Deliberately tiny and
+// framework-agnostic (no Node-RED dependency) so it can be unit-tested in
+// isolation -- see test/execution/retry.spec.js. Consumed by agent.js's
+// startExecution retry loop, which owns the actual delay/re-invoke wiring
+// (this module only ever classifies/decides, never sleeps or retries
+// anything itself).
+
+// FATAL patterns are checked first and win over TRANSIENT when both match
+// (e.g. a 401 body that also happens to mention a network-ish word) --
+// per the issue spec, an auth/permission failure should never be retried
+// just because its text also contains a transient-looking substring.
+const FATAL_PATTERNS = [
+  "unauthorized",
+  "forbidden",
+  "invalid token",
+  "authentication failed",
+  "permission denied",
+  "401",
+  "403",
+  "credit exhaustion",
+  "credit balance",
+];
+
+const TRANSIENT_PATTERNS = [
+  "timeout",
+  "econnrefused",
+  "econnreset",
+  "etimedout",
+  "503",
+  "502",
+  "429",
+  "rate limit",
+  "too many requests",
+  "overloaded",
+  "network error",
+  "socket hang up",
+  "exited with code",
+];
+
+function classifyError(message) {
+  const text = String(message || "").toLowerCase();
+  if (FATAL_PATTERNS.some((p) => text.includes(p))) return "FATAL";
+  if (TRANSIENT_PATTERNS.some((p) => text.includes(p))) return "TRANSIENT";
+  return "UNKNOWN";
+}
+
+// `result.retryable === false` is an explicit escape hatch (e.g. issue
+// #23's structured-output validation failure, once wired) that always
+// wins regardless of `onError` -- checked before any error-text
+// classification.
+function shouldRetry(result, onError) {
+  if (result && result.retryable === false) return false;
+  const classification = classifyError(result && result.errorMessage);
+  if (classification === "FATAL") return false;
+  if (onError === "all") return true;
+  return classification === "TRANSIENT";
+}
+
+module.exports = { classifyError, shouldRetry };

package/nodes/agent/lib/execution/structured-output.js

@@ -0,0 +1,111 @@
+"use strict";
+
+const Ajv = require("ajv");
+
+// Best-effort reask budget (issue #23): neither the opencode nor pi CLI has
+// a --schema/--json-schema flag (verified against both CLIs' --help), so
+// output_format is enforced entirely via prompt augmentation + post-hoc
+// parsing/validation + a bounded number of "please retry" reask turns. This
+// is a fixed constant, not per-node configurable, to keep the failure mode
+// predictable (a run either produces valid structured output within this
+// budget, or fails outright -- never silently degrades to raw text).
+const STRUCTURED_OUTPUT_MAX_REASKS = 3;
+
+// Compiles a JSON Schema (already-parsed object) into an AJV validate
+// function. Never throws -- returns { error: <message> } instead, so a
+// caller (agent.js, at deploy time) can surface a clean red node status
+// ("invalid output_format schema: <msg>") rather than crashing Node-RED.
+function compileOutputFormat(schema) {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+    return { error: "output_format must be a JSON object (a JSON Schema)" };
+  }
+  try {
+    const ajv = new Ajv({ strict: false });
+    const validate = ajv.compile(schema);
+    return { validate };
+  } catch (err) {
+    return { error: err.message };
+  }
+}
+
+// Strips a single ```json ... ``` (or plain ``` ... ```) fence if present,
+// otherwise returns the text unchanged -- models asked for "only JSON"
+// still commonly wrap it in a markdown code fence.
+function stripCodeFence(text) {
+  const match = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  return match ? match[1] : text;
+}
+
+// Parses `text` to a plain object only (arrays/primitives at the top level
+// are rejected -- output_format is an object-only contract). Returns
+// undefined instead of throwing on any failure.
+function parseObjectOnly(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    return undefined;
+  }
+  return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+    ? parsed
+    : undefined;
+}
+
+// Tiered best-effort parse of an agent's raw text response into a JSON
+// object matching output_format, per issue #23:
+//   1. Strip a ```json fence if present.
+//   2. Try a clean JSON.parse of the (fence-stripped) whole text.
+//   3. If that fails, scan for the FIRST '{' (not the last -- avoids
+//      grabbing a trailing example instead of the real payload) through
+//      the last '}' and retry JSON.parse on that slice.
+//   4. If that also fails, return undefined (no jsonrepair dependency --
+//      shipped without it per the issue's own v1 allowance).
+function tryParseStructuredOutput(text) {
+  if (typeof text !== "string" || !text.trim()) return undefined;
+
+  const candidate = stripCodeFence(text).trim();
+
+  const clean = parseObjectOnly(candidate);
+  if (clean !== undefined) return clean;
+
+  const firstBrace = candidate.indexOf("{");
+  const lastBrace = candidate.lastIndexOf("}");
+  if (firstBrace === -1 || lastBrace === -1 || lastBrace <= firstBrace) return undefined;
+
+  return parseObjectOnly(candidate.slice(firstBrace, lastBrace + 1));
+}
+
+// Appends a fixed instruction block asking the model for ONLY a JSON
+// object matching `schema` (pretty-printed). Same functional intent as
+// Archon's structured-output prompting, written independently.
+function augmentPromptForSchema(prompt, schema) {
+  return (
+    `${prompt}\n\n` +
+    "Respond with ONLY a single JSON object (no surrounding prose, no " +
+    "markdown code fences) that validates against this JSON Schema:\n" +
+    `${JSON.stringify(schema, null, 2)}`
+  );
+}
+
+// Builds a reask prompt: the original prompt, the AJV validation errors
+// from the previous (invalid) attempt, and the schema again.
+function buildReaskPrompt(originalPrompt, schema, errors) {
+  const errorLines = (errors || [])
+    .map((e) => `- ${e.instancePath || "(root)"} ${e.message}`)
+    .join("\n");
+  return (
+    `${originalPrompt}\n\n` +
+    "Your previous response did not validate against the required JSON " +
+    `Schema. Validation errors:\n${errorLines || "(response was not valid JSON)"}\n\n` +
+    "Respond again with ONLY a single JSON object (no prose, no markdown " +
+    `code fences) that validates against this schema:\n${JSON.stringify(schema, null, 2)}`
+  );
+}
+
+module.exports = {
+  STRUCTURED_OUTPUT_MAX_REASKS,
+  compileOutputFormat,
+  tryParseStructuredOutput,
+  augmentPromptForSchema,
+  buildReaskPrompt,
+};

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.4.0",
   "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'"
@@ -56,5 +56,8 @@
   },
   "devDependencies": {
     "node-red-node-test-helper": "^0.3.6"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0"
   }
 }

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 };