@tbrandenburg/node-red-agents 0.1.5 → 0.3.0

package/nodes/agent/agent.html

@@ -84,6 +84,9 @@
                 runtime: { value: 'direct' },
                 invocation: { value: 'prompt' },
 
+                agentName: { value: '' },
+                agentNameType: { value: 'str' },
+
                 model: { value: '' },
                 modelType: { value: 'str' },
 
@@ -140,6 +143,11 @@
                     MODEL_SUGGESTIONS.forEach((m) => datalist.append('<option value="' + m + '">'));
                 }
 
+                $('#node-input-agentName').typedInput({
+                    typeField: '#node-input-agentNameType',
+                    types: ['str', 'msg', 'flow', 'global', 'env']
+                });
+
                 $('#node-input-prompt').typedInput({
                     typeField: '#node-input-promptType',
                     types: ['msg', 'str', 'flow', 'global', 'env']
@@ -317,6 +325,15 @@
         <input type="text" id="node-input-name" placeholder="Agent">
     </div>
 
+    <div class="form-row">
+        <label for="node-input-agentName"><i class="fa fa-id-badge"></i> Agent name
+            <i class="fa fa-info-circle" style="color:#888; cursor:help; margin-left:4px;"
+               title="Reported as msg.agentName on the result/event outputs. Leave blank (str) to use the Name field above; set to msg/flow/global to make it dynamic per message."></i>
+        </label>
+        <input type="text" id="node-input-agentName" placeholder="leave blank to use the Name field above" style="width:60%">
+        <input type="hidden" id="node-input-agentNameType">
+    </div>
+
     <div class="form-row">
         <label for="node-input-agent"><i class="fa fa-cube"></i> Agent</label>
         <select id="node-input-agent" style="width:70%">
@@ -475,6 +492,12 @@
             the id of the execution to kill, as returned by an earlier run in
             <code>msg.agentExecution.id</code> or an Events message's
             <code>executionId</code>.</dd>
+        <dt class="optional">concurrency <span class="property-type">number</span></dt>
+        <dd>Overrides the Concurrency field at runtime, applied before this
+            message is submitted -- no redeploy needed. Raising it starts any
+            already-queued messages immediately; lowering it only affects
+            future scheduling (already-running executions are never
+            cancelled). Non-numeric/non-positive values are ignored.</dd>
     </dl>
     <h3>Outputs</h3>
     <ol class="node-ports">
@@ -488,6 +511,16 @@
                     conversation on the next message.</dd>
                 <dt>agentExecution <span class="property-type">object</span></dt>
                 <dd>id, status, exitCode, signal, timedOut, durationMs, sessionID.</dd>
+                <dt>agentId <span class="property-type">string</span></dt>
+                <dd>This node instance's own Node-RED id, so a flow with
+                    several agent nodes can tell which one produced a
+                    given message.</dd>
+                <dt>agentName <span class="property-type">string</span></dt>
+                <dd>The resolved Agent name field, falling back to this node
+                    instance's configured Name if the Agent name field is
+                    blank/unresolved for this message (e.g. via
+                    <code>msg.agentName</code> when configured as a msg
+                    property).</dd>
             </dl>
         </li>
         <li>Events
@@ -498,6 +531,10 @@
                 <dt>executionId <span class="property-type">string</span></dt>
                 <dd>Correlates events (and the eventual result) belonging to
                     the same execution when several run concurrently.</dd>
+                <dt>agentId <span class="property-type">string</span></dt>
+                <dd>This node instance's own Node-RED id (see Result output).</dd>
+                <dt>agentName <span class="property-type">string</span></dt>
+                <dd>The resolved Agent name for this execution (see Result output).</dd>
             </dl>
         </li>
     </ol>
@@ -509,7 +546,9 @@
        complete in a different order than the messages arrived; ordering is
        not guaranteed above concurrency 1. On redeploy/removal, queued
        messages are cancelled (a <code>cancelled</code> event plus a Node-RED
-       error) and any still-running agent processes are terminated.</p>
+       error) and any still-running agent processes are terminated. Send
+       <code>msg.concurrency</code> to change the bound at runtime without a
+       redeploy -- see Inputs below.</p>
     <p><b>Terminating a specific execution on demand</b>: send a message with
        <code>msg.operation = "terminate"</code> and <code>msg.executionId</code>
        set to the id to kill (from a prior run's <code>msg.agentExecution.id</code>

package/nodes/agent/agent.js

@@ -45,6 +45,14 @@ module.exports = function (RED) {
     node.runtime = config.runtime || "direct";
     node.invocation = config.invocation || "prompt";
 
+    // Typed-input override of the agentName reported on outgoing/event
+    // messages (see lifecycleEnvelope below). Same typed-input pattern as
+    // every other overridable field: blank/unresolved falls back to
+    // node.name, so existing flows relying on the (previously static)
+    // node.name value keep working unchanged.
+    node.agentName = config.agentName !== undefined ? config.agentName : "";
+    node.agentNameType = config.agentNameType || "str";
+
     node.model = config.model || "";
     node.modelType = config.modelType || "str";
 
@@ -150,19 +158,30 @@ module.exports = function (RED) {
       }
     }
 
+    // Per-message resolution of the reported agentName: the typed-input
+    // agentName/agentNameType field (e.g. msg.agentName) if configured and
+    // present, else node.name -- same fallback behavior a blank/unset
+    // typed-input field has always had for every other field.
+    function resolveAgentName(msg) {
+      const v = resolveTyped(node.agentName, node.agentNameType, msg, node.name);
+      return v === undefined || v === null || v === "" ? node.name : String(v).trim();
+    }
+
     // Common envelope for every message on output 2 (the lifecycle/event
     // stream): correlation (topic, executionId), live scheduler counts
     // (so a widget bound to this stream always has the current
     // active/queued numbers, no separate polling needed) and a
     // timestamp (so external aggregation/history doesn't have to rely
     // on message-arrival time).
-    function lifecycleEnvelope(msg, executionId, payload) {
+    function lifecycleEnvelope(msg, executionId, payload, agentName) {
       return {
         _msgid: msg._msgid,
         topic: msg.topic,
         payload,
         agent: node.agent,
         runtime: node.runtime,
+        agentId: node.id,
+        agentName,
         executionId,
         active: node.scheduler.activeCount,
         queued: node.scheduler.queuedCount,
@@ -170,8 +189,8 @@ module.exports = function (RED) {
       };
     }
 
-    function emitEvent(send, msg, executionId, type) {
-      send([null, lifecycleEnvelope(msg, executionId, { type })]);
+    function emitEvent(send, msg, executionId, type, agentName) {
+      send([null, lifecycleEnvelope(msg, executionId, { type }, agentName)]);
     }
 
     // The actual work for one execution. Only ever invoked by the
@@ -188,11 +207,11 @@ module.exports = function (RED) {
         resolved,
         executionId,
         onEvent: (event) => {
-          send([null, lifecycleEnvelope(msg, executionId, event)]);
+          send([null, lifecycleEnvelope(msg, executionId, event, resolved.agentName)]);
         },
         onStatus: (status) => {
           if (status === "running") {
-            emitEvent(send, msg, executionId, "running");
+            emitEvent(send, msg, executionId, "running", resolved.agentName);
           } else {
             // Terminal (completed/failed/timeout): stash rather
             // than emit immediately -- the scheduler hasn't
@@ -214,6 +233,8 @@ module.exports = function (RED) {
             payload: result.payload,
             agent: node.agent,
             runtime: node.runtime,
+            agentId: node.id,
+            agentName: resolved.agentName,
             // Top-level, in addition to agentExecution.sessionID
             // below: matches the agent-server node's convention
             // so this output can be fed straight back into the
@@ -261,13 +282,22 @@ module.exports = function (RED) {
     node.scheduler = new ExecutionScheduler({
       concurrency: node.concurrency,
       onStart: startExecution,
-      onQueued: (item) => emitEvent(item.send, item.msg, item.executionId, "queued"),
+      onQueued: (item) =>
+        emitEvent(item.send, item.msg, item.executionId, "queued", item.resolved.agentName),
       // Runs after this item is removed from `active` and any newly-
       // eligible queued item has already been started, so the terminal
       // event's active/queued counts are accurate (see the onStatus
       // comment in startExecution for why it's deferred to here).
       onSettled: (item) => {
-        if (item.finalStatus) emitEvent(item.send, item.msg, item.executionId, item.finalStatus);
+        if (item.finalStatus) {
+          emitEvent(
+            item.send,
+            item.msg,
+            item.executionId,
+            item.finalStatus,
+            item.resolved.agentName,
+          );
+        }
         updateStatus();
       },
     });
@@ -287,6 +317,7 @@ module.exports = function (RED) {
         return;
       }
 
+      const agentName = resolveAgentName(msg);
       const result = node.scheduler.cancel(executionId);
       if (!result) {
         done(new Error(`agent: unknown or already-finished executionId "${executionId}"`));
@@ -295,7 +326,13 @@ module.exports = function (RED) {
 
       if (result.status === "queued") {
         const queuedItem = result.item;
-        emitEvent(queuedItem.send, queuedItem.msg, executionId, "cancelled");
+        emitEvent(
+          queuedItem.send,
+          queuedItem.msg,
+          executionId,
+          "cancelled",
+          queuedItem.resolved ? queuedItem.resolved.agentName : agentName,
+        );
         queuedItem.done(
           new Error("agent: execution cancelled before it started (terminate requested)"),
         );
@@ -303,6 +340,8 @@ module.exports = function (RED) {
         send([
           Object.assign({}, msg, {
             payload: { executionId, terminated: true, status: "cancelled" },
+            agentId: node.id,
+            agentName,
           }),
           null,
         ]);
@@ -320,6 +359,8 @@ module.exports = function (RED) {
           send([
             Object.assign({}, msg, {
               payload: { executionId, terminated: true, status: "terminating" },
+              agentId: node.id,
+              agentName,
             }),
             null,
           ]);
@@ -342,9 +383,19 @@ module.exports = function (RED) {
         return;
       }
 
+      // Optional per-message override of the deploy-time Concurrency
+      // field, applied before this message is submitted so a raised
+      // bound can immediately start any items already queued from
+      // earlier messages. Invalid values (non-numeric/non-positive)
+      // are ignored -- see ExecutionScheduler.setConcurrency.
+      if (msg.concurrency !== undefined) {
+        node.scheduler.setConcurrency(Number(msg.concurrency));
+      }
+
       let resolved;
       try {
         resolved = {
+          agentName: resolveAgentName(msg),
           invocation: node.invocation,
           prompt:
             node.invocation === "prompt"

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

@@ -27,6 +27,20 @@ class ExecutionScheduler {
     return this.active.size;
   }
 
+  // Runtime override of the concurrency bound (e.g. from a per-message
+  // msg.concurrency), as opposed to the fixed value passed into the
+  // constructor. Invalid input (non-finite/non-positive) is ignored
+  // rather than falling back to 1 -- an in-flight bound should never be
+  // silently reset by a bad message. Raising the bound immediately
+  // drains eligible queued items via _advance(); lowering it only
+  // affects future scheduling -- already-active items are never
+  // cancelled by this call.
+  setConcurrency(concurrency) {
+    if (!Number.isFinite(concurrency) || concurrency <= 0) return;
+    this.concurrency = Math.floor(concurrency);
+    this._advance();
+  }
+
   get queuedCount() {
     return this.queue.length;
   }

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

@@ -18,6 +18,9 @@
             defaults: {
                 name: { value: '' },
 
+                serverName: { value: '' },
+                serverNameType: { value: 'str' },
+
                 operation: { value: 'message' },
 
                 hostname: { value: '127.0.0.1' },
@@ -71,6 +74,10 @@
                     typeField: '#node-input-modelType',
                     types: ['str', 'msg', 'flow', 'global', 'env']
                 });
+                $('#node-input-serverName').typedInput({
+                    typeField: '#node-input-serverNameType',
+                    types: ['str', 'msg', 'flow', 'global', 'env']
+                });
 
                 function updateOperationRows() {
                     const op = $('#node-input-operation').val();
@@ -141,6 +148,15 @@
         <input type="text" id="node-input-name" placeholder="Agent Server">
     </div>
 
+    <div class="form-row">
+        <label for="node-input-serverName"><i class="fa fa-id-badge"></i> Server name
+            <i class="fa fa-info-circle" style="color:#888; cursor:help; margin-left:4px;"
+               title="Reported as msg.serverName on the result/event outputs. Leave blank (str) to use the Name field above; set to msg/flow/global to make it dynamic per message."></i>
+        </label>
+        <input type="text" id="node-input-serverName" placeholder="leave blank to use the Name field above" style="width:60%">
+        <input type="hidden" id="node-input-serverNameType">
+    </div>
+
     <div class="form-row">
         <label for="node-input-operation"><i class="fa fa-play"></i> Operation</label>
         <select id="node-input-operation" style="width:70%">
@@ -194,7 +210,7 @@
         <label for="node-input-maxInstances"><i class="fa fa-tasks"></i> Max instances</label>
         <input type="text" id="node-input-maxInstances" placeholder="5" style="width:80px">
         <i class="fa fa-info-circle" style="color:#888; cursor:help; margin-left:4px;"
-           title="Maximum number of daemons this node may have spawned at once. A new no-session-id trigger errors immediately once reached (no queueing). 0 = unlimited."></i>
+           title="Maximum number of daemons this node may have spawned at once. A new no-session-id trigger errors immediately once reached (no queueing). 0 = unlimited. Overridable at runtime via msg.maxInstances."></i>
     </div>
     <div class="form-row agent-server-row-spawn">
         <label for="node-input-startupTimeoutMs"><i class="fa fa-clock-o"></i> Startup timeout</label>
@@ -340,6 +356,12 @@
        configured Operation for a single trigger -- e.g. to ask a message-sending node
        instance for its own current status, without needing a second node pointed at
        nothing.</p>
+    <p>Set <code>msg.maxInstances</code> to override the Max instances field at
+       runtime, without a redeploy -- 0 keeps meaning "unlimited", and
+       negative/non-numeric values are ignored. Lowering it below the current
+       number of tracked daemons never kills any of them; it only blocks
+       <em>future</em> spawns until the count naturally drops back under the
+       new cap.</p>
     <h3>Outputs</h3>
     <ol class="node-ports">
         <li>Result
@@ -348,6 +370,16 @@
                 <dd>Operation-dependent: assistant reply text (message), a status object, etc.</dd>
                 <dt>sessionID <span class="property-type">string</span></dt>
                 <dd>Echoed back so a later trigger can reuse the same daemon/session.</dd>
+                <dt>serverId <span class="property-type">string</span></dt>
+                <dd>This node instance's own Node-RED id, so a flow with
+                    several agent-server nodes can tell which one produced a
+                    given message.</dd>
+                <dt>serverName <span class="property-type">string</span></dt>
+                <dd>The resolved Server name field, falling back to this node
+                    instance's configured Name if the Server name field is
+                    blank/unresolved for this message (e.g. via
+                    <code>msg.serverName</code> when configured as a msg
+                    property).</dd>
             </dl>
         </li>
         <li>Lifecycle events
@@ -357,6 +389,10 @@
                     <code>failed</code> / <code>closed</code>, each with <code>sessionID</code>,
                     <code>timestamp</code>, and this node instance's live <code>active</code>
                     (busy) / <code>tracked</code> (total) daemon counts.</dd>
+                <dt>serverId <span class="property-type">string</span></dt>
+                <dd>This node instance's own Node-RED id (see Result output).</dd>
+                <dt>serverName <span class="property-type">string</span></dt>
+                <dd>The resolved Server name for this event (see Result output).</dd>
             </dl>
         </li>
     </ol>

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

@@ -21,6 +21,12 @@ module.exports = function (RED) {
 
     node.operation = config.operation || "message";
 
+    // Typed-input override of the serverName reported on outgoing/event
+    // messages (see emitEvent below). Same typed-input pattern as every
+    // other overridable field: blank/unresolved falls back to node.name.
+    node.serverName = config.serverName !== undefined ? config.serverName : "";
+    node.serverNameType = config.serverNameType || "str";
+
     node.sessionIdProp = config.sessionIdProp !== undefined ? config.sessionIdProp : "sessionID";
     node.sessionIdPropType = config.sessionIdPropType || "msg";
 
@@ -105,6 +111,8 @@ module.exports = function (RED) {
           topic: msg && msg.topic,
           payload: { type },
           sessionID,
+          serverId: node.id,
+          serverName: resolveServerName(msg),
           active: summary.busy,
           tracked: summary.total,
           timestamp: Date.now(),
@@ -122,6 +130,16 @@ module.exports = function (RED) {
       }
     }
 
+    // Per-message resolution of the reported serverName: the typed-input
+    // serverName/serverNameType field (e.g. msg.serverName) if configured
+    // and present, else node.name -- same fallback every other typed-input
+    // field has when blank/unresolved. Tolerates a missing msg (emitEvent
+    // is sometimes called without one, e.g. from spawnNewInstance's own
+    // internal bookkeeping) by resolving against an empty object.
+    function resolveServerName(msg) {
+      return resolveTyped(node.serverName, node.serverNameType, msg || {}, node.name);
+    }
+
     function authOptions() {
       return node.authUsername || node.authPassword
         ? { username: node.authUsername, password: node.authPassword }
@@ -236,6 +254,8 @@ module.exports = function (RED) {
         const resultMsg = Object.assign({}, msg, {
           payload: extractText(response),
           sessionID,
+          serverId: node.id,
+          serverName: resolveServerName(msg),
           agentServer: {
             sessionID,
             host: record && record.host,
@@ -330,7 +350,14 @@ module.exports = function (RED) {
       if (!sessionID) {
         // Aggregate across every daemon this node instance is
         // tracking -- purely local, no network calls.
-        send([Object.assign({}, msg, { payload: node.registry.summary() }), null]);
+        send([
+          Object.assign({}, msg, {
+            payload: node.registry.summary(),
+            serverId: node.id,
+            serverName: resolveServerName(msg),
+          }),
+          null,
+        ]);
         done();
         return;
       }
@@ -355,6 +382,8 @@ module.exports = function (RED) {
             startedAt: record.startedAt,
             lastUsed: record.lastUsed,
           },
+          serverId: node.id,
+          serverName: resolveServerName(msg),
         }),
         null,
       ]);
@@ -387,7 +416,15 @@ module.exports = function (RED) {
         .then(() => {
           node.registry.setBusy(sessionID, false);
           updateStatus();
-          send([Object.assign({}, msg, { payload: true, sessionID }), null]);
+          send([
+            Object.assign({}, msg, {
+              payload: true,
+              sessionID,
+              serverId: node.id,
+              serverName: resolveServerName(msg),
+            }),
+            null,
+          ]);
           done();
         })
         .catch((err) => done(new Error(`agent-server: abort failed: ${err.message}`)));
@@ -416,7 +453,15 @@ module.exports = function (RED) {
         ...authOptions(),
       })
         .then((history) => {
-          send([Object.assign({}, msg, { payload: history, sessionID }), null]);
+          send([
+            Object.assign({}, msg, {
+              payload: history,
+              sessionID,
+              serverId: node.id,
+              serverName: resolveServerName(msg),
+            }),
+            null,
+          ]);
           done();
         })
         .catch((err) => done(new Error(`agent-server: history fetch failed: ${err.message}`)));
@@ -450,7 +495,15 @@ module.exports = function (RED) {
         .then(() => {
           emitEvent(sessionID, "terminated", msg);
           updateStatus();
-          send([Object.assign({}, msg, { payload: true, sessionID }), null]);
+          send([
+            Object.assign({}, msg, {
+              payload: true,
+              sessionID,
+              serverId: node.id,
+              serverName: resolveServerName(msg),
+            }),
+            null,
+          ]);
           done();
         })
         .catch((err) => done(new Error(`agent-server: terminate failed: ${err.message}`)));
@@ -464,6 +517,18 @@ module.exports = function (RED) {
         return;
       }
 
+      // Optional per-message override of the deploy-time Max instances
+      // field, applied before spawnNewInstance()'s guard clause reads it
+      // -- no redeploy needed. 0 stays "unlimited" (same as the
+      // constructor's semantics above); negative/non-numeric values are
+      // ignored. Lowering the limit below the current registry size
+      // never evicts already-spawned daemons -- it only blocks *future*
+      // spawns until the count naturally drops back under the new cap.
+      if (msg.maxInstances !== undefined) {
+        const n = Number(msg.maxInstances);
+        if (Number.isFinite(n) && n >= 0) node.maxInstances = Math.floor(n);
+      }
+
       // msg.operation can override the configured default for this one
       // trigger. This matters because each node instance's registry is
       // private (per-node-instance scoping, same as the `agent` node's

package/package.json

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