@tbrandenburg/node-red-agents 0.3.8 → 0.4.1

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

@@ -75,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
@@ -87,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 };
@@ -121,6 +158,14 @@ 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 =
@@ -150,32 +195,100 @@ class OpenCodeAdapter extends AgentAdapter {
       }
       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,33 @@
+"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.
+//
+// issue #29: this module has no access to the Node-RED `node` object (and
+// unit tests call it directly without a fake node), so it never warns
+// itself -- callers that do have a `node` may pass an optional
+// onUnmatched(name) callback, invoked for every token left as literal text
+// (missing from inputsMap, or present but mapped to null/undefined -- both
+// produce the same visible symptom of a literal token reaching the LLM).
+const TOKEN_RE = /\$INPUTS\.([A-Za-z0-9_]+)/g;
+
+function substituteInputs(text, inputsMap, onUnmatched) {
+  if (typeof text !== "string" || !text) return text;
+  const map = inputsMap || {};
+  return text.replace(TOKEN_RE, (match, name) => {
+    const hasName = Object.prototype.hasOwnProperty.call(map, name);
+    const value = hasName ? map[name] : undefined;
+    if (!hasName || value === undefined || value === null) {
+      if (typeof onUnmatched === "function") onUnmatched(name);
+      return match;
+    }
+    return String(value);
+  });
+}
+
+module.exports = { substituteInputs };

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tbrandenburg/node-red-agents",
-  "version": "0.3.8",
+  "version": "0.4.1",
   "description": "Node-RED nodes for running coding agents (opencode, pi) and GitHub CLI operations from flows.",
   "keywords": [
     "node-red",
@@ -56,5 +56,8 @@
   },
   "devDependencies": {
     "node-red-node-test-helper": "^0.3.6"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0"
   }
 }