@tbrandenburg/node-red-agents 0.4.0 → 0.4.2

package/README.md

@@ -7,11 +7,21 @@ flow.
 
 - **agent** — runs a coding-agent CLI (OpenCode first, `pi` also
   supported) either directly or sandboxed via SRT (Anthropic's
-  sandbox-runtime), one execution per input message.
+  sandbox-runtime), one execution per input message. Also supports
+  session resume, `$INPUTS.<name>` templating, retry with session
+  reuse, a FIFO concurrency scheduler, on-demand termination, tool
+  allow/deny lists, MCP server configuration, structured (JSON-Schema)
+  output validation, and cost/token usage reporting where supported.
 - **agent-server** — manages a long-lived `opencode serve` daemon
-  (session-based, SRT-sandboxable), for flows that need repeated
-  low-latency calls instead of `agent`'s one-shot execution model.
-- **gh** — runs GitHub CLI (`gh`) commands and returns parsed output.
+  (session-based), for flows that need repeated low-latency calls
+  instead of `agent`'s one-shot execution model. Supports
+  `message`/`status`/`abort`/`history`/`terminate` operations, an
+  instance cap (`maxInstances`), and optional basic auth. SRT
+  sandboxing is **not functional** for this node (see its built-in
+  help) since it only sandboxes outbound egress, not the inbound calls
+  this node needs.
+- **gh** — runs GitHub CLI (`gh`) commands and returns parsed output,
+  with structured error classification and per-message overrides.
 
 See each node's built-in help (Node-RED editor info panel) for
 configuration details, or `nodes/gh/README.md` for `gh`-specific usage

package/nodes/agent/agent.html

@@ -15,6 +15,8 @@
       "github-copilot/gpt-5.4",
       "openai/gpt-5.4",
       "openai/gpt-4.1",
+      "claude-sonnet-5",
+      "gpt-5.4",
     ];
 
     function mcpServerRow(container, data) {
@@ -156,7 +158,7 @@
         arguments: { value: "payload" },
         argumentsType: { value: "msg" },
 
-        inputs: { value: [] },
+        promptArgs: { value: [] },
 
         cwd: { value: "cwd" },
         cwdType: { value: "msg" },
@@ -312,6 +314,10 @@
             skill: "code-review (looked up under .github/skills/)",
             command: "review (looked up under .github/prompts/)",
           },
+          copilot: {
+            skill: "code-review (looked up under .github/skills/)",
+            command: "review (looked up under .github/prompts/)",
+          },
         };
 
         function updateInvocationRows() {
@@ -342,6 +348,7 @@
         const AUTO_HINTS = {
           opencode: "Maps to --auto: skips permission prompts for actions not explicitly denied.",
           pi: "Pi has no permission prompts to bypass. Off = read-only tools (read/grep/find/ls). On = full tool access (bash/edit/write too).",
+          copilot: "Maps to --allow-all-tools: skips permission prompts for all tool calls.",
         };
 
         // Grey out (rather than hide) fields an agent doesn't
@@ -392,7 +399,7 @@
           removable: true,
           sortable: true,
         });
-        (node.inputs || []).forEach((entry) => inputsList.editableList("addItem", entry));
+        (node.promptArgs || []).forEach((entry) => inputsList.editableList("addItem", entry));
 
 
         const deniedToolsList = $("#node-input-deniedTools-list");
@@ -444,7 +451,7 @@
           const sessionSupported = agent !== "pi";
           setSectionSupported($(".agent-row-session"), sessionSupported);
           $(".agent-row-session-hint").toggle(!sessionSupported);
-          const effortSupported = agent === "opencode";
+          const effortSupported = agent === "opencode" || agent === "copilot";
           setSectionSupported($(".agent-row-effort"), effortSupported);
           $(".agent-row-effort-hint").toggle(!effortSupported);
           updateInvocationRows();
@@ -475,14 +482,14 @@
         this.allowedTools = collectStrings($("#node-input-allowedTools-list"));
         this.deniedTools = collectStrings($("#node-input-deniedTools-list"));
 
-        const inputsOut = [];
+        const promptArgsOut = [];
         $("#node-input-inputs-list")
           .editableList("items")
           .each(function () {
             const v = $(this).data("inputsGetValue")();
-            if (v && v.name) inputsOut.push(v);
+            if (v && v.name) promptArgsOut.push(v);
           });
-        this.inputs = inputsOut;
+        this.promptArgs = promptArgsOut;
 
 
         // Only persist the SRT inline-settings lists/fields while
@@ -561,6 +568,7 @@
     <select id="node-input-agent" style="width:70%">
       <option value="opencode">OpenCode</option>
       <option value="pi">Pi</option>
+      <option value="copilot">Copilot</option>
     </select>
   </div>
 
@@ -880,8 +888,8 @@
 
 <script type="text/html" data-help-name="agent">
   <p>
-    Runs a coding agent (<b>OpenCode</b> or <b>Pi</b>) non-interactively, either directly on this
-    host or sandboxed through <code>srt</code>.
+    Runs a coding agent (<b>OpenCode</b>, <b>Pi</b>, or <b>Copilot</b>) non-interactively, either
+    directly on this host or sandboxed through <code>srt</code>.
   </p>
   <h3>Inputs</h3>
   <dl class="message-properties">
@@ -898,7 +906,7 @@
     <dt class="optional">sessionID <span class="property-type">string</span></dt>
     <dd>
       Used to resume a previous session if the Session ID field is left at its default
-      (<code>msg.sessionID</code>). Empty/absent starts a new session. OpenCode only.
+      (<code>msg.sessionID</code>). Empty/absent starts a new session. OpenCode and Copilot only.
     </dd>
     <dt class="optional">operation <span class="property-type">string</span></dt>
     <dd>
@@ -994,21 +1002,27 @@
     still completes). Pi has no equivalent permission-prompt system to bypass in non-interactive
     mode -- for Pi this instead restricts the available tools to read-only
     (<code>read/grep/find/ls</code>) when off, and allows everything (including
-    <code>bash/edit/write</code>) when on.
+    <code>bash/edit/write</code>) when on. For Copilot it maps to <code>--allow-all-tools</code>: off
+    (default) leaves Copilot's own permission prompts in effect (which auto-reject in
+    non-interactive mode), on skips them entirely.
   </p>
   <p>
     <b>Skill</b>/<b>Command</b> invocation: for OpenCode this is the name of a discovered skill or a
     <code>.opencode/command(s)/&lt;name&gt;.md</code> file, dispatched deterministically via
-    <code>--command</code>. Pi has no equivalent dispatch mechanism -- the name is resolved to a
-    file under <code>.github/skills/</code> (skill) or <code>.github/prompts/</code> (command),
-    passed via <code>--skill</code>/<code>--prompt-template</code>, and the model is explicitly told
-    in the prompt to use it. Pi also does not support configuring MCP servers through this node.
+    <code>--command</code>. Pi and Copilot have no equivalent dispatch mechanism -- the name is
+    resolved to a file under <code>.github/skills/</code> (skill) or <code>.github/prompts/</code>
+    (command), passed via <code>--skill</code>/<code>--prompt-template</code> for Pi (Copilot has the
+    resolved file path spelled out in the synthesized prompt instruction instead, since it has no
+    equivalent CLI flag), and the model is explicitly told in the prompt to use it. Pi does not
+    support configuring MCP servers through this node; Copilot does.
   </p>
   <p>
     <b>Session ID</b>: leave blank to always start a fresh session (the default). Set it (typically
     from the previous result's <code>msg.sessionID</code>) to continue that conversation instead --
-    maps to OpenCode's <code>opencode run --session &lt;id&gt; ...</code>. Only the OpenCode agent
-    supports this; Pi rejects a non-empty Session ID (every Pi run uses <code>--no-session</code>).
+    maps to OpenCode's <code>opencode run --session &lt;id&gt; ...</code> or Copilot's
+    <code>copilot --resume &lt;id&gt; ...</code>. Pi rejects a non-empty Session ID (every Pi run
+    uses <code>--no-session</code>). Copilot only ever resumes via <code>--resume</code> -- it has
+    no equivalent of OpenCode's explicit "start a new session with this id" flag.
   </p>
   <p>
     <b>SRT</b> runtime shells out to the <code>srt</code> sandbox-runtime CLI already installed on
@@ -1019,13 +1033,24 @@
     <b>System prompt</b>, <b>Effort</b>, and <b>Allowed/Denied tools</b> are forwarded to the
     underlying CLI only where that adapter actually supports it -- a field set for an adapter that
     doesn't will be silently dropped with a Node-RED warning, never a hard error.
-    <b>System prompt</b> has no verified CLI flag for either adapter yet and is always dropped.
+    <b>System prompt</b> has no verified CLI flag for any adapter yet and is always dropped.
     <b>Effort</b> (reasoning depth, e.g. <code>low</code>/<code>medium</code>/<code>high</code>)
-    maps to OpenCode's <code>--variant</code>; Pi has no equivalent.
-    <b>Allowed/ Denied tools</b> are supported by both: for OpenCode they're materialized into a
-    temporary, per-run agent config (delivered the same way as MCP servers, via
+    maps to OpenCode's <code>--variant</code> or Copilot's own effort flag; Pi has no equivalent.
+    <b>Allowed/ Denied tools</b> are supported by all three: for OpenCode they're materialized into
+    a temporary, per-run agent config (delivered the same way as MCP servers, via
     <code>OPENCODE_CONFIG_CONTENT</code>) selected with <code>--agent</code>; for Pi, a non-empty
     Allowed tools list is passed as <code>--tools</code> (Pi has no deny-list mechanism, so Denied
-    tools has no effect for Pi).
+    tools has no effect for Pi); for Copilot both lists are passed as
+    <code>--allow-tool</code>/<code>--deny-tool</code> flags.
+  </p>
+  <p>
+    <b>Copilot</b> specifics: <b>Model</b> is a bare model id (e.g. <code>claude-sonnet-5</code>,
+    <code>gpt-5.4</code>) rather than OpenCode's <code>provider/model</code> form. <b>Session ID</b>
+    is always resumed with <code>--resume &lt;id&gt;</code> -- there is no equivalent of OpenCode's
+    "start a new session with this specific id" flag. MCP servers configured through this node are
+    passed via <code>--additional-mcp-config</code>, but the Copilot CLI always additionally loads
+    the user's global <code>~/.copilot/mcp-config.json</code> alongside them -- a known CLI
+    limitation, not a bug in this node, so servers defined there are always active too regardless of
+    what's configured here.
   </p>
 </script>

package/nodes/agent/agent.js

@@ -1,6 +1,8 @@
 const fs = require("fs");
-const { OpenCodeAdapter } = require("./lib/agents/opencode");
-const { PiAdapter } = require("./lib/agents/pi");
+require("./lib/agents/opencode"); // registers "opencode" as a side effect
+require("./lib/agents/pi"); // registers "pi" as a side effect
+require("./lib/agents/copilot"); // registers "copilot" as a side effect
+const { isRegisteredAgent, getAgentAdapter } = require("./lib/agents/registry");
 const { DirectRuntime } = require("./lib/runtimes/direct");
 const { SrtRuntime } = require("./lib/runtimes/srt");
 const { writeInlineSettingsFile } = require("../../shared/srt-settings");
@@ -10,6 +12,7 @@ const { computeNodeStatus } = require("./lib/execution/status");
 const { getCapabilities } = require("./lib/agents/capabilities");
 const { shouldRetry } = require("./lib/execution/retry");
 const { substituteInputs } = require("./lib/execution/inputs");
+const { resumeOutcome } = require("./lib/execution/resume-outcome");
 const {
   STRUCTURED_OUTPUT_MAX_REASKS,
   compileOutputFormat,
@@ -18,15 +21,12 @@ const {
   buildReaskPrompt,
 } = require("./lib/execution/structured-output");
 
-// Registries. Adding a future adapter/runtime is just one more entry here --
+// Registries. Adding a future adapter/runtime is just one more self-
+// registration in the adapter's own module (see lib/agents/registry.js) --
 // 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") {
@@ -89,7 +89,7 @@ module.exports = function (RED) {
     // resolved arguments string before it's handed to either adapter.
     // Pure text templating, zero adapter-specific code -- see
     // lib/execution/inputs.js. Default empty list = zero behavior change.
-    node.inputs = Array.isArray(config.inputs) ? config.inputs : [];
+    node.promptArgs = Array.isArray(config.promptArgs) ? config.promptArgs : [];
 
     node.cwd = config.cwd !== undefined ? config.cwd : "cwd";
     node.cwdType = config.cwdType || "msg";
@@ -158,8 +158,8 @@ module.exports = function (RED) {
           node.outputFormatSchema = schema;
         }
       }
-      if (!node.outputFormatError && AGENTS[node.agent]) {
-        const capabilities = getCapabilities(AGENTS[node.agent]());
+      if (!node.outputFormatError && isRegisteredAgent(node.agent)) {
+        const capabilities = getCapabilities(getAgentAdapter(node.agent));
         if (capabilities.structuredOutput === false) {
           node.outputFormatError = `output_format not supported by ${node.agent}`;
         }
@@ -241,7 +241,7 @@ module.exports = function (RED) {
         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}`);
+        throw new Error(`invalid ${type} property "${prop}": ${err.message}`, { cause: err });
       }
     }
 
@@ -293,7 +293,7 @@ module.exports = function (RED) {
     // directly from the input handler.
     function startExecution(item) {
       const { executionId, msg, send, done, resolved } = item;
-      const adapter = AGENTS[node.agent]();
+      const adapter = getAgentAdapter(node.agent);
       const runtime = buildRuntime(node);
       const capabilities = getCapabilities(adapter);
 
@@ -494,6 +494,19 @@ module.exports = function (RED) {
             // Debug node to output 1 and inspect this field.
             errorDetail: result.errorDetail,
           };
+          // Explicit resume-outcome signal (issue #41): compares the
+          // ORIGINALLY-requested sessionID (resolved.sessionID, before any
+          // internal reask/retry continuity mutation) against the FINAL
+          // result.sessionID once the whole execution has settled. Omitted
+          // entirely (never emitted as undefined) when no resume was ever
+          // requested or this adapter doesn't support it -- same
+          // omit-rather-than-emit convention as costUsd/tokens below.
+          const resumed = resumeOutcome(
+            resolved.sessionID,
+            result.sessionID,
+            capabilities.sessionResume,
+          );
+          if (resumed !== undefined) agentExecution.resumed = resumed;
           if (structuredEnabled && result.structuredOutput !== undefined) {
             agentExecution.structuredOutput = result.structuredOutput;
             agentExecution.declaredFields = Object.keys(
@@ -705,9 +718,9 @@ module.exports = function (RED) {
             node.invocation !== "prompt"
               ? (() => {
                   const raw = resolveTyped(node.arguments_, node.argumentsType, msg, msg.payload);
-                  if (typeof raw !== "string" || node.inputs.length === 0) return raw;
+                  if (typeof raw !== "string" || node.promptArgs.length === 0) return raw;
                   const inputsMap = {};
-                  node.inputs.forEach((entry) => {
+                  node.promptArgs.forEach((entry) => {
                     inputsMap[entry.name] = resolveTyped(
                       entry.value,
                       entry.valueType || "msg",
@@ -715,7 +728,21 @@ module.exports = function (RED) {
                       "",
                     );
                   });
-                  return substituteInputs(raw, inputsMap);
+                  // issue #29: warn once per distinct unmatched $INPUTS.<name>
+                  // token found in this run (de-duplicated so a typo'd token
+                  // repeated in `arguments` doesn't spam the log) -- purely
+                  // additive observability, the substituted text itself (and
+                  // thus the eventual invocation) is unchanged.
+                  const unmatchedNames = new Set();
+                  const substituted = substituteInputs(raw, inputsMap, (name) =>
+                    unmatchedNames.add(name),
+                  );
+                  unmatchedNames.forEach((name) => {
+                    node.warn(
+                      `$INPUTS.${name} has no matching 'inputs' entry and was left unsubstituted`,
+                    );
+                  });
+                  return substituted;
                 })()
               : undefined,
           cwd: (() => {
@@ -758,7 +785,7 @@ module.exports = function (RED) {
         return;
       }
 
-      if (!AGENTS[node.agent]) {
+      if (!isRegisteredAgent(node.agent)) {
         node.lastTerminal = "failed";
         node.lastText = "unknown agent";
         updateStatus();

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

@@ -0,0 +1,318 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { AgentAdapter } = require("./base");
+const { toCopilotMcp } = require("../mcp/normalize");
+
+// Maps the real Copilot CLI `--output-format json` event stream (verified
+// empirically against `copilot` v1.0.86) onto the Agent node's generic
+// event vocabulary. Deliberately coarser than the CLI's own granularity:
+// `assistant.message_delta` (streamed fragments) is skipped in favor of
+// the single completed `assistant.message` event, same rationale as
+// pi.js's *_delta skipping.
+const TYPE_MAP = {
+  "session.mcp_server_status_changed": "progress",
+  "session.mcp_servers_loaded": "progress",
+  "session.tools_updated": "progress",
+  "user.message": "progress",
+  "assistant.turn_start": "started",
+  "model.call_start": "progress",
+  "assistant.message_start": "progress",
+  "assistant.message_delta": "progress",
+  "tool.execution_start": "tool",
+  "tool.execution_complete": "tool",
+  "model.call_finished": "progress",
+  "assistant.message": "agent",
+  "assistant.turn_end": "progress",
+  "session.usage_checkpoint": "progress",
+  "assistant.idle": "progress",
+  // Not directly observed in a successful transcript (issue #46/Task 1
+  // did not surface a `session.error` event in the empirically verified
+  // failure paths -- bad model/resume instead exit non-zero with zero or
+  // partial JSON stdout, handled in parseResult()'s exitCode branch), but
+  // kept as a defensive mapping in case the CLI ever does emit one.
+  "session.error": "failed",
+};
+
+// Copilot has no `--skill`/`--command` CLI flag (verified against
+// `copilot --help`) -- mirrors pi.js's directory-convention resolution
+// for turning a bare invocationName into a real file path so it can be
+// spelled out in the synthesized prompt instruction. Re-implemented
+// locally (not imported from pi.js) per the plan's "duplication here is
+// acceptable, keep changes minimal" guidance.
+const RESOURCE_DIRS = {
+  skill: ".github/skills",
+  command: ".github/prompts",
+};
+
+function resolveResourcePath(name, kind, cwd) {
+  const base = cwd || process.cwd();
+  const candidates = [];
+
+  if (path.isAbsolute(name)) {
+    candidates.push(name);
+  } else if (name.includes("/") || name.endsWith(".md")) {
+    candidates.push(path.join(base, name));
+  }
+
+  const dir = RESOURCE_DIRS[kind];
+  candidates.push(path.join(base, dir, name, "SKILL.md"));
+  candidates.push(path.join(base, dir, `${name}.md`));
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  throw new Error(
+    `could not find a ${kind} named "${name}" (looked for: ${candidates.join(", ")})`,
+  );
+}
+
+class CopilotAdapter extends AgentAdapter {
+  validate(resolved) {
+    // Copilot model ids are bare (e.g. "claude-sonnet-5", "gpt-5.4"), not
+    // "provider/model" like OpenCode's -- deliberately does NOT call
+    // assertModelFormat() here (that check is OpenCode-specific).
+
+    if (resolved.cwd) {
+      let stat;
+      try {
+        stat = fs.statSync(resolved.cwd);
+      } catch (err) {
+        throw new Error(`cwd does not exist: ${resolved.cwd}`, { cause: err });
+      }
+      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`);
+      }
+      // Throws its own clear error if nothing matches -- fail before
+      // spawning anything, per the adapter contract.
+      resolveResourcePath(resolved.invocationName, resolved.invocation, resolved.cwd);
+    } 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 = ["--output-format", "json", "--allow-all-tools"];
+
+    // --resume <id> is resume-ONLY: verified to hard-fail (exit 1, zero
+    // JSON stdout) on an unresolvable id, unlike --session-id's dual
+    // create-or-resume semantics (which silently succeeds/creates a new
+    // session on an unknown id). Never use --session-id here -- that
+    // would make resumeOutcome() always report a false positive.
+    if (resolved.sessionID) args.push("--resume", String(resolved.sessionID));
+
+    if (resolved.cwd) args.push("--add-dir", resolved.cwd);
+    if (resolved.model) args.push("--model", resolved.model);
+
+    // --effort/--reasoning-effort verified working against a real
+    // `copilot` invocation (choices: none, minimal, low, medium, high,
+    // xhigh, max) -- passed straight through, no clamping.
+    if (CopilotAdapter.CAPABILITIES.effortControl && resolved.effort) {
+      args.push("--effort", resolved.effort);
+    }
+
+    // allowedTools/deniedTools (issue #25 parity): --allow-tool/--deny-tool
+    // verified present in `copilot --help`; the most direct mapping of
+    // resolved.allowedTools/deniedTools onto the CLI's own flags.
+    const hasAllow =
+      CopilotAdapter.CAPABILITIES.toolRestrictions &&
+      Array.isArray(resolved.allowedTools) &&
+      resolved.allowedTools.length > 0;
+    const hasDeny =
+      CopilotAdapter.CAPABILITIES.toolRestrictions &&
+      Array.isArray(resolved.deniedTools) &&
+      resolved.deniedTools.length > 0;
+    if (hasAllow) args.push(`--allow-tool=${resolved.allowedTools.join(",")}`);
+    if (hasDeny) args.push(`--deny-tool=${resolved.deniedTools.join(",")}`);
+
+    // --additional-mcp-config <json>: verified schema requires a
+    // top-level {"mcpServers": {...}} wrapper (see toCopilotMcp()).
+    // KNOWN LIMITATION (not fixed here, see normalize.js's comment): the
+    // global ~/.copilot/mcp-config.json always loads regardless of this
+    // flag.
+    if (Array.isArray(resolved.mcpServers) && resolved.mcpServers.length > 0) {
+      args.push("--additional-mcp-config", JSON.stringify(toCopilotMcp(resolved.mcpServers)));
+    }
+
+    // No --skill/--command CLI flag exists (verified) -- synthesize a
+    // natural-language instruction instead, exactly like pi.js's pattern.
+    let message;
+    if (resolved.invocation === "prompt") {
+      message = String(resolved.prompt);
+    } else {
+      const resourcePath = resolveResourcePath(
+        resolved.invocationName,
+        resolved.invocation,
+        resolved.cwd,
+      );
+      const kind = resolved.invocation === "skill" ? "skill" : "prompt template";
+      const argsText =
+        resolved.args !== undefined && resolved.args !== null ? String(resolved.args) : "";
+      message =
+        `Use the "${resolved.invocationName}" ${kind} at ${resourcePath}. ${argsText}`.trim();
+    }
+    args.push("-p", message);
+
+    // Auth is fully via env vars already inherited from process.env
+    // (lib/execution/lifecycle.js merges these already) -- zero
+    // adapter-side auth code needed.
+    return { command: "copilot", 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;
+    }
+
+    if (raw.type === "result") {
+      return { type: "completed", sessionID: raw.sessionId, data: raw };
+    }
+
+    const type = TYPE_MAP[raw.type] || "progress";
+    return { type, sessionID: raw.sessionId, data: raw };
+  }
+
+  parseResult(events, exitCode, signal, stderr, resolved) {
+    const raw = events.map((e) => e.data);
+    const errorEvent = raw.find((e) => e.type === "session.error");
+    const resultEvent = [...raw].reverse().find((e) => e.type === "result");
+    const finalMessage = [...raw].reverse().find((e) => e.type === "assistant.message");
+
+    const sessionID = resultEvent
+      ? resultEvent.sessionId
+      : finalMessage
+        ? finalMessage.sessionId
+        : raw.length
+          ? raw[raw.length - 1].sessionId
+          : undefined;
+
+    const payload =
+      finalMessage && finalMessage.data && typeof finalMessage.data.content === "string"
+        ? finalMessage.data.content.trim()
+        : "";
+
+    const usage = summarizeUsage(resultEvent);
+
+    if (errorEvent) {
+      const detail = errorEvent.data || {};
+      const message = detail.message || "copilot reported a session error";
+      const extras = [];
+      if (stderr && String(stderr).trim()) extras.push(String(stderr).trim());
+      const errorMessage = extras.length ? `${message} (${extras.join("; ")})` : message;
+      return Object.assign(
+        { payload, sessionID, status: "failed", errorMessage, errorDetail: detail },
+        usage,
+      );
+    }
+    if (signal) {
+      return Object.assign(
+        {
+          payload,
+          sessionID,
+          status: "failed",
+          errorMessage: `process killed by signal ${signal}`,
+        },
+        usage,
+      );
+    }
+    if (exitCode !== 0) {
+      // Bad --model and bad --resume both verified to exit 1 with a clear
+      // stderr message and zero (or partial) JSON stdout -- surface
+      // stderr directly, same as opencode.js's exitCode!==0 branch.
+      const stderrText = stderr ? String(stderr).trim() : "";
+      let hint = "";
+      if (resolved && resolved.model && /model/i.test(stderrText)) {
+        hint = ` (possible cause: model "${resolved.model}" may not exist or isn't available)`;
+      }
+      return Object.assign(
+        {
+          payload,
+          sessionID,
+          status: "failed",
+          errorMessage: `exited with code ${exitCode}${stderrText ? ": " + stderrText : ""}${hint}`,
+        },
+        usage,
+      );
+    }
+    if (!payload) {
+      return Object.assign(
+        {
+          payload,
+          sessionID,
+          status: "failed",
+          errorMessage: "copilot produced no assistant output (silent rejection or empty response)",
+        },
+        usage,
+      );
+    }
+    return Object.assign({ payload, sessionID, status: "completed" }, usage);
+  }
+}
+
+// Reads cost/token usage from the terminal {type:"result", usage:{...}}
+// event -- a different shape than opencode's per-step summing, needs its
+// own field mapping. Returns {} (no keys at all) when no result event
+// carried usable data, so Object.assign(...) callers never introduce
+// costUsd/tokens keys with `undefined` values.
+function summarizeUsage(resultEvent) {
+  const usage = {};
+  if (!resultEvent || !resultEvent.usage || typeof resultEvent.usage !== "object") return usage;
+  const u = resultEvent.usage;
+  if (typeof u.premiumRequests === "number") {
+    usage.tokens = {
+      premiumRequests: u.premiumRequests,
+      totalApiDurationMs: Number(u.totalApiDurationMs) || 0,
+      sessionDurationMs: Number(u.sessionDurationMs) || 0,
+    };
+  }
+  return usage;
+}
+
+CopilotAdapter.CAPABILITIES = {
+  sessionResume: true, // --resume=<id> verified: hard-fails (exit 1, zero stdout) on unknown id
+  structuredOutput: "best-effort", // no --schema/--json-schema flag found
+  toolRestrictions: true, // --allow-tool/--deny-tool verified present in --help
+  effortControl: true, // --effort/--reasoning-effort verified working
+  systemPromptControl: false, // no CLI flag found
+  costReporting: true, // terminal result.usage + session.usage_checkpoint events
+};
+
+const { registerAgent } = require("./registry");
+registerAgent({ id: "copilot", factory: () => new CopilotAdapter() });
+
+module.exports = { CopilotAdapter, resolveResourcePath };

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

@@ -26,7 +26,7 @@ class OpenCodeAdapter extends AgentAdapter {
       try {
         stat = fs.statSync(resolved.cwd);
       } catch (err) {
-        throw new Error(`cwd does not exist: ${resolved.cwd}`);
+        throw new Error(`cwd does not exist: ${resolved.cwd}`, { cause: err });
       }
       if (!stat.isDirectory()) {
         throw new Error(`cwd is not a directory: ${resolved.cwd}`);
@@ -283,7 +283,15 @@ function summarizeUsage(raw) {
 }
 
 OpenCodeAdapter.CAPABILITIES = {
-  sessionResume: true, // opencode.js -s/--session verified working
+  sessionResume: true, // opencode.js -s/--session verified working: an
+  // unresolvable/bogus sessionID hard-fails the CLI (exit 1, zero JSON
+  // events, "Session not found" on stderr) rather than silently
+  // falling back to a fresh session -- verified empirically with real
+  // CLI invocations. So `resumeOutcome()` (lib/execution/resume-
+  // outcome.js) reaching `false` for this adapter today always
+  // co-occurs with a failed execution; there is no known path where
+  // OpenCode reports status:"completed" after silently discarding a
+  // requested resume.
   structuredOutput: "best-effort", // no --schema/--json-schema CLI flag
   toolRestrictions: true, // via materialized temp agent config + --agent
   effortControl: true, // --variant, verified working
@@ -291,4 +299,7 @@ OpenCodeAdapter.CAPABILITIES = {
   costReporting: true, // step_finish tokens/cost already in --format json stream
 };
 
+const { registerAgent } = require("./registry");
+registerAgent({ id: "opencode", factory: () => new OpenCodeAdapter() });
+
 module.exports = { OpenCodeAdapter };

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

@@ -61,7 +61,7 @@ class PiAdapter extends AgentAdapter {
       try {
         stat = fs.statSync(resolved.cwd);
       } catch (err) {
-        throw new Error(`cwd does not exist: ${resolved.cwd}`);
+        throw new Error(`cwd does not exist: ${resolved.cwd}`, { cause: err });
       }
       if (!stat.isDirectory()) {
         throw new Error(`cwd is not a directory: ${resolved.cwd}`);
@@ -279,4 +279,7 @@ PiAdapter.CAPABILITIES = {
   costReporting: false, // pi CLI not installed/verified
 };
 
+const { registerAgent } = require("./registry");
+registerAgent({ id: "pi", factory: () => new PiAdapter() });
+
 module.exports = { PiAdapter, resolveResourcePath };

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

@@ -0,0 +1,47 @@
+"use strict";
+
+const registry = new Map();
+
+// entry: { id, factory }
+// factory: () => AgentAdapter instance
+function registerAgent(entry) {
+  if (registry.has(entry.id)) return; // idempotent, mirrors Archon
+  if (typeof entry.factory !== "function") {
+    throw new Error(`agent '${entry.id}': factory must be a function`);
+  }
+  registry.set(entry.id, entry);
+}
+
+function isRegisteredAgent(id) {
+  return registry.has(id);
+}
+
+// Throws a clear, listing error instead of returning undefined -- callers
+// (agent.js) must not have to null-check every lookup site.
+function getAgentAdapter(id) {
+  const entry = registry.get(id);
+  if (!entry) {
+    throw new Error(
+      `unknown agent '${id}'. Registered agents: ${[...registry.keys()].join(", ") || "(none)"}`,
+    );
+  }
+  return entry.factory();
+}
+
+function listAgentIds() {
+  return [...registry.keys()];
+}
+
+// Test-only: clears the registry so adapter-registration tests don't
+// leak state across test files.
+function resetRegistryForTests() {
+  registry.clear();
+}
+
+module.exports = {
+  registerAgent,
+  isRegisteredAgent,
+  getAgentAdapter,
+  listAgentIds,
+  resetRegistryForTests,
+};

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

@@ -7,15 +7,26 @@
 // 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) {
+function substituteInputs(text, inputsMap, onUnmatched) {
   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);
+    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);
   });
 }
 

package/nodes/agent/lib/execution/resume-outcome.js

@@ -0,0 +1,22 @@
+"use strict";
+
+// Computes the three-state "was a requested resume actually honored?"
+// signal, mirroring Archon's shared/resumed.ts:
+//   undefined -- no resume was requested this invocation (fresh by design,
+//                or this adapter doesn't support resume at all)
+//   true      -- resume was requested and the adapter/CLI honored it
+//   false     -- resume was requested but did not happen (may co-occur
+//                with a failed execution -- see opencode.js's CAPABILITIES
+//                comment for the verified OpenCode-specific behavior)
+//
+// `requestedSessionID` is the sessionID this execution was originally
+// invoked with (item.resolved.sessionID, before any internal retry/reask
+// continuity mutation); `actualSessionID` is the FINAL result.sessionID
+// reported by the adapter's parseResult() once the whole execution
+// (including any internal retries/reasks) has settled.
+function resumeOutcome(requestedSessionID, actualSessionID, sessionResumeCapable) {
+  if (!requestedSessionID || !sessionResumeCapable) return undefined;
+  return requestedSessionID === actualSessionID;
+}
+
+module.exports = { resumeOutcome };

package/nodes/agent/lib/mcp/normalize.js

@@ -28,4 +28,42 @@ function toOpenCodeMcp(mcpServers) {
   return out;
 }
 
-module.exports = { toOpenCodeMcp };
+// Generic mcpServers[] -> Copilot CLI's `--additional-mcp-config` JSON
+// schema, as verified against a real `copilot --additional-mcp-config
+// '{"mcpServers":{...}}' -p ... --output-format json` invocation:
+//   { "mcpServers": { "<name>": { "type":"local","command":"npx",
+//     "args":["-y","pkg"], "tools":["*"] } } }
+// The remote shape ({"type":"remote","url":"...","tools":["*"]}) mirrors
+// the local shape's structure but was not independently verified against
+// a real remote MCP server -- follows `copilot mcp add`'s own default of
+// `"tools":["*"]` (allow every tool from that server).
+//
+// KNOWN LIMITATION (do not attempt to fix here): the global
+// ~/.copilot/mcp-config.json ALWAYS loads regardless of
+// --additional-mcp-config -- confirmed `--disable-builtin-mcps` does NOT
+// prevent this (it only suppresses actual builtin MCPs like
+// github-mcp-server). Surfacing this to the user is the adapter's job
+// (see copilot.js's validate()), not this pure translation function's.
+function toCopilotMcp(mcpServers) {
+  const out = {};
+  if (!Array.isArray(mcpServers)) return { mcpServers: out };
+
+  for (const server of mcpServers) {
+    if (!server || typeof server.name !== "string" || !server.name.trim()) continue;
+
+    if (server.type === "remote") {
+      if (typeof server.url !== "string" || !server.url.trim()) continue;
+      out[server.name] = { type: "remote", url: server.url, tools: ["*"] };
+    } else if (server.type === "local") {
+      if (typeof server.command !== "string" || !server.command.trim()) continue;
+      const args = Array.isArray(server.args) ? server.args : [];
+      out[server.name] = { type: "local", command: server.command, args, tools: ["*"] };
+    }
+    // Unknown types are silently skipped -- validate() at the adapter
+    // level is responsible for surfacing a clear error before execution.
+  }
+
+  return { mcpServers: out };
+}
+
+module.exports = { toOpenCodeMcp, toCopilotMcp };

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

@@ -126,7 +126,7 @@ module.exports = function (RED) {
         const value = RED.util.evaluateNodeProperty(prop, type, node, msg);
         return value === undefined || value === null || value === "" ? fallback : value;
       } catch (err) {
-        throw new Error(`invalid ${type} property "${prop}": ${err.message}`);
+        throw new Error(`invalid ${type} property "${prop}": ${err.message}`, { cause: err });
       }
     }
 

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

@@ -32,9 +32,9 @@ async function request(url, opts = {}) {
     });
   } catch (err) {
     if (err.name === "AbortError") {
-      throw new Error(`request to ${url} timed out after ${timeoutMs}ms`);
+      throw new Error(`request to ${url} timed out after ${timeoutMs}ms`, { cause: err });
     }
-    throw new Error(`request to ${url} failed: ${err.message}`);
+    throw new Error(`request to ${url} failed: ${err.message}`, { cause: err });
   } finally {
     clearTimeout(timer);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tbrandenburg/node-red-agents",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Node-RED nodes for running coding agents (opencode, pi) and GitHub CLI operations from flows.",
   "keywords": [
     "node-red",