@tbrandenburg/node-red-agents 0.1.1

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

@@ -0,0 +1,60 @@
+'use strict';
+
+// Thin fetch wrapper for talking to an opencode `serve` daemon: adds an
+// AbortController-based timeout (fetch has no built-in one) and optional
+// HTTP basic auth. Deliberately not a generic HTTP client -- just enough to
+// call the handful of endpoints this node needs.
+function basicAuthHeader(username, password) {
+    return 'Basic ' + Buffer.from(`${username}:${password}`).toString('base64');
+}
+
+// opts: { method, body, timeoutMs, username, password }
+// Returns the parsed JSON body, or undefined for a 204/empty response.
+// Throws an Error (with .status set, if the server responded at all) on
+// network failure, timeout, or a non-2xx response.
+async function request(url, opts = {}) {
+    const controller = new AbortController();
+    const timeoutMs = opts.timeoutMs || 30000;
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+    const headers = { 'Content-Type': 'application/json' };
+    if (opts.username || opts.password) {
+        headers.Authorization = basicAuthHeader(opts.username || '', opts.password || '');
+    }
+
+    let res;
+    try {
+        res = await fetch(url, {
+            method: opts.method || 'GET',
+            headers,
+            body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+            signal: controller.signal
+        });
+    } catch (err) {
+        if (err.name === 'AbortError') {
+            throw new Error(`request to ${url} timed out after ${timeoutMs}ms`);
+        }
+        throw new Error(`request to ${url} failed: ${err.message}`);
+    } finally {
+        clearTimeout(timer);
+    }
+
+    const text = await res.text();
+    let body;
+    try {
+        body = text ? JSON.parse(text) : undefined;
+    } catch (err) {
+        body = text;
+    }
+
+    if (!res.ok) {
+        const err = new Error(`${opts.method || 'GET'} ${url} -> ${res.status}${text ? ': ' + text : ''}`);
+        err.status = res.status;
+        err.body = body;
+        throw err;
+    }
+
+    return body;
+}
+
+module.exports = { request, basicAuthHeader };

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

@@ -0,0 +1,20 @@
+'use strict';
+
+// 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
+// `{ providerID, modelID }` object (verified empirically: passing a plain
+// string 400s with "Expected object | null, got \"...\""). This is the
+// translation between the two, kept pure/testable and separate from
+// agent-server.js.
+function parseModel(value) {
+    if (value === undefined || value === null || value === '') return undefined;
+    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-4.6")`);
+    }
+    return { providerID: str.slice(0, slash), modelID: str.slice(slash + 1) };
+}
+
+module.exports = { parseModel };

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

@@ -0,0 +1,31 @@
+'use strict';
+
+const net = require('net');
+
+// Self-allocates a free TCP port instead of spawning `opencode serve --port
+// 0` and scraping its stdout for the OS-assigned port: bind a throwaway
+// server to port 0, read back whatever the OS gave it, close it immediately,
+// then hand that concrete number to `--port`. Deterministic, doesn't depend
+// on a log line's exact wording, and is trivially unit-testable without
+// spawning any real agent binary.
+//
+// Unavoidable TOCTOU: the port could theoretically be grabbed by something
+// else between close() here and the daemon binding it moments later. Left
+// as a known, accepted race (same as almost every "find a free port" helper)
+// -- the daemon's own health-poll failing/timing out is the backstop.
+function findFreePort(hostname = '127.0.0.1') {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.unref();
+        server.on('error', reject);
+        server.listen(0, hostname, () => {
+            const { port } = server.address();
+            server.close((err) => {
+                if (err) reject(err);
+                else resolve(port);
+            });
+        });
+    });
+}
+
+module.exports = { findFreePort };

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

@@ -0,0 +1,77 @@
+'use strict';
+
+// Framework-agnostic, in-memory tracking of every daemon (opencode serve
+// process) this node instance has spawned, keyed by sessionID. Deliberately
+// has no Node-RED dependency (same reasoning as the `agent` package's
+// lib/execution/scheduler.js) so it's unit-testable in isolation.
+//
+// This is also the entire answer to "how many/which agents are running
+// right now": everything summary() reports comes from local state already
+// being maintained for routing purposes anyway -- no extra network calls,
+// no separate bookkeeping subsystem.
+class InstanceRegistry {
+    constructor() {
+        this.map = new Map();
+    }
+
+    // record: { child, host, port, baseUrl } -- busy/startedAt/lastUsed are
+    // owned by the registry itself, not the caller.
+    register(sessionID, record) {
+        this.map.set(
+            sessionID,
+            Object.assign({ busy: false, startedAt: Date.now(), lastUsed: Date.now() }, record)
+        );
+    }
+
+    get(sessionID) {
+        return this.map.get(sessionID);
+    }
+
+    has(sessionID) {
+        return this.map.has(sessionID);
+    }
+
+    delete(sessionID) {
+        return this.map.delete(sessionID);
+    }
+
+    list() {
+        return Array.from(this.map.keys());
+    }
+
+    size() {
+        return this.map.size;
+    }
+
+    // Marks a tracked session busy/idle and bumps lastUsed. No-op if the
+    // sessionID isn't tracked (e.g. already torn down) -- callers don't need
+    // to guard this themselves.
+    setBusy(sessionID, busy) {
+        const record = this.map.get(sessionID);
+        if (!record) return;
+        record.busy = busy;
+        record.lastUsed = Date.now();
+    }
+
+    // Pure, local (no network) snapshot -- this is what backs the 'status'
+    // operation when called without a sessionID, and the lifecycle-event
+    // envelope's live counts.
+    summary() {
+        const sessions = [];
+        let busy = 0;
+        for (const [sessionID, record] of this.map) {
+            if (record.busy) busy += 1;
+            sessions.push({
+                sessionID,
+                host: record.host,
+                port: record.port,
+                busy: !!record.busy,
+                startedAt: record.startedAt,
+                lastUsed: record.lastUsed
+            });
+        }
+        return { total: sessions.length, busy, idle: sessions.length - busy, sessions };
+    }
+}
+
+module.exports = { InstanceRegistry };

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

@@ -0,0 +1,15 @@
+'use strict';
+
+// Pure function computing the node.status() shape from the registry's local
+// summary (see lib/registry.js). Kept separate from agent-server.js so it's
+// unit-testable without a Node-RED runtime -- same reasoning as the `agent`
+// package's lib/execution/status.js.
+function computeNodeStatus({ total, busy, idle }) {
+    if (total === 0) return {}; // no daemons tracked -- idle, nothing to show
+
+    let text = `${total} daemon${total === 1 ? '' : 's'}`;
+    text += busy > 0 ? ` \u00b7 ${busy} busy` : ' \u00b7 idle';
+    return { fill: busy > 0 ? 'blue' : 'green', shape: 'dot', text };
+}
+
+module.exports = { computeNodeStatus };

package/nodes/gh/README.md

@@ -0,0 +1,75 @@
+# node-red-contrib-gh
+
+Runs the installed [GitHub CLI](https://cli.github.com/) (`gh`) from a
+Node-RED flow. One `gh` invocation per incoming message, no shell involved.
+
+## Prerequisites
+
+`gh` must already be installed and authenticated on the Node-RED host:
+
+```bash
+gh --version
+gh auth login          # or GH_TOKEN / GH_ENTERPRISE_TOKEN in the environment
+```
+
+This package does not bundle `gh` or implement its own login flow.
+
+## Node: `gh`
+
+**Inputs:** 1   **Outputs:** 1
+
+| Field | Type | Notes |
+|---|---|---|
+| Command | str/msg/flow/global | The `gh` subcommand, e.g. `pr`, `issue`, `workflow`, `api`. Not the full command line -- `gh` itself is always the executable and can never be overridden. |
+| Arguments | str/msg/flow/global | Everything after the command, e.g. `list --state open --json number,title,url`. A string value is tokenized (quote-aware, no shell evaluation); an array value (e.g. from `msg.`) is used as-is. |
+| Repository | str/msg/flow/global | Optional `owner/repo`. Sets `GH_REPO` for the invocation. |
+| Host (Advanced) | str | Optional GitHub Enterprise hostname, e.g. `github.example.com`. Sets `GH_HOST`. |
+| Timeout (Advanced) | number (ms) | Default 60000. The child process is killed (`SIGTERM`) if it runs longer than this. |
+
+### `msg.gh` overrides
+
+```js
+msg.gh = {
+  command: 'issue',
+  args: ['list', '--state', 'open'],   // array preferred; skips parsing entirely
+  repo: 'owner/repo',
+  host: 'github.example.com'
+};
+```
+
+Any property present on `msg.gh` takes precedence over the node's own
+configuration for that message.
+
+### Output
+
+- `msg.payload`: parsed JSON if stdout was valid JSON, otherwise the raw
+  stdout string.
+- `msg.gh`: `{ command, args, repo, host, exitCode, stderr }` execution
+  metadata. Never contains credentials.
+
+A non-zero exit code, a timeout, or a missing `gh` executable all go through
+`done(error)` (catchable with a Catch node) instead of producing an output
+message.
+
+## Example
+
+See `examples/list-pull-requests.json` and `examples/run-workflow.json` for
+importable flow snippets.
+
+## Tests
+
+```bash
+npm test
+```
+
+Uses Node's built-in test runner (`node --test`) against a fake `gh`
+executable in `test/fixtures/` -- no real GitHub CLI or network access
+required.
+
+## Security
+
+- The executable is always the literal string `gh`; nothing in `msg` or
+  config can change it.
+- No shell is used (`shell: false`); arguments are passed as an array.
+- Credentials are never logged, included in `msg`, or included in errors.
+- The full process environment is never dumped anywhere.

package/nodes/gh/examples/list-pull-requests.json

@@ -0,0 +1,48 @@
+[
+    {
+        "id": "gh-example-inject",
+        "type": "inject",
+        "name": "",
+        "props": [{ "p": "payload" }],
+        "repeat": "",
+        "crontab": "",
+        "once": false,
+        "onceDelay": 0.1,
+        "topic": "",
+        "payload": "",
+        "payloadType": "date",
+        "x": 150,
+        "y": 120,
+        "wires": [["gh-example-node"]]
+    },
+    {
+        "id": "gh-example-node",
+        "type": "gh",
+        "name": "Open PRs",
+        "command": "pr",
+        "commandType": "str",
+        "args": "list --state open --json number,title,author,url",
+        "argsType": "str",
+        "repo": "owner/repository",
+        "repoType": "str",
+        "host": "",
+        "timeoutMs": 60000,
+        "x": 350,
+        "y": 120,
+        "wires": [["gh-example-debug"]]
+    },
+    {
+        "id": "gh-example-debug",
+        "type": "debug",
+        "name": "PRs",
+        "active": true,
+        "tosidebar": true,
+        "console": false,
+        "tostatus": false,
+        "complete": "payload",
+        "targetType": "msg",
+        "x": 550,
+        "y": 120,
+        "wires": []
+    }
+]

package/nodes/gh/examples/run-workflow.json

@@ -0,0 +1,42 @@
+[
+    {
+        "id": "gh-wf-example-function",
+        "type": "function",
+        "name": "Build gh args",
+        "func": "msg.gh = {\n    command: 'workflow',\n    args: ['run', 'deploy.yml', '--ref', 'main', '-f', 'environment=staging'],\n    repo: 'owner/repository'\n};\nreturn msg;",
+        "outputs": 1,
+        "x": 200,
+        "y": 220,
+        "wires": [["gh-wf-example-node"]]
+    },
+    {
+        "id": "gh-wf-example-node",
+        "type": "gh",
+        "name": "Trigger workflow",
+        "command": "",
+        "commandType": "str",
+        "args": "",
+        "argsType": "str",
+        "repo": "",
+        "repoType": "str",
+        "host": "",
+        "timeoutMs": 60000,
+        "x": 420,
+        "y": 220,
+        "wires": [["gh-wf-example-debug"]]
+    },
+    {
+        "id": "gh-wf-example-debug",
+        "type": "debug",
+        "name": "Result",
+        "active": true,
+        "tosidebar": true,
+        "console": false,
+        "tostatus": false,
+        "complete": "true",
+        "targetType": "full",
+        "x": 620,
+        "y": 220,
+        "wires": []
+    }
+]

package/nodes/gh/gh.html

@@ -0,0 +1,146 @@
+<script type="text/javascript">
+    (function () {
+        'use strict';
+        RED.nodes.registerType('gh', {
+            category: 'Collaboration',
+            color: '#6e5494',
+            defaults: {
+                name: { value: "" },
+                command: { value: "", required: true },
+                commandType: { value: "str" },
+                args: { value: "" },
+                argsType: { value: "str" },
+                repo: { value: "" },
+                repoType: { value: "str" },
+                host: { value: "" },
+                timeoutMs: { value: 60000, validate: RED.validators.number() }
+            },
+            inputs: 1,
+            outputs: 1,
+            icon: "gh.svg",
+            label: function () {
+                return this.name || (this.command ? "gh " + this.command : "gh");
+            },
+            oneditprepare: function () {
+                $('#node-input-command').typedInput({
+                    typeField: '#node-input-commandType',
+                    types: ['str', 'msg', 'flow', 'global']
+                });
+                $('#node-input-args').typedInput({
+                    typeField: '#node-input-argsType',
+                    types: ['str', 'msg', 'flow', 'global']
+                });
+                $('#node-input-repo').typedInput({
+                    typeField: '#node-input-repoType',
+                    types: ['str', 'msg', 'flow', 'global']
+                });
+            },
+            oneditsave: function () {
+                const cmd = ($('#node-input-command').val() || '').trim();
+                if (this.commandType === 'str' || !this.commandType) {
+                    if (cmd === 'gh' || /\s/.test(cmd)) {
+                        // Editor-side warning only; the runtime re-validates
+                        // regardless (flow JSON can be edited outside the UI).
+                        RED.notify(
+                            'Command should be a single gh subcommand (e.g. "pr"), not "gh" itself or a full command line.',
+                            'warning'
+                        );
+                    }
+                }
+            }
+        });
+    }());
+</script>
+
+<script type="text/html" data-template-name="gh">
+    <div class="form-row">
+        <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="Name">
+    </div>
+    <div class="form-row">
+        <label for="node-input-command"><i class="fa fa-terminal"></i> Command</label>
+        <input type="text" id="node-input-command" placeholder="pr">
+        <input type="hidden" id="node-input-commandType">
+    </div>
+    <div class="form-row">
+        <label for="node-input-args"><i class="fa fa-list"></i> Arguments</label>
+        <input type="text" id="node-input-args" placeholder="list --state open --json number,title,url">
+        <input type="hidden" id="node-input-argsType">
+    </div>
+    <div class="form-row">
+        <label for="node-input-repo"><i class="fa fa-book"></i> Repository</label>
+        <input type="text" id="node-input-repo" placeholder="owner/repo (optional)">
+        <input type="hidden" id="node-input-repoType">
+    </div>
+
+    <div class="form-row">
+        <a href="#" class="editor-tray-help-tray-hide" id="gh-advanced-toggle" style="font-weight:bold;">
+            <i class="fa fa-angle-right" id="gh-advanced-icon"></i> Advanced
+        </a>
+    </div>
+    <div id="gh-advanced-fields" style="display:none;">
+        <div class="form-row">
+            <label for="node-input-host"><i class="fa fa-globe"></i> Host</label>
+            <input type="text" id="node-input-host" placeholder="github.com (leave blank for gh's own default)">
+        </div>
+        <div class="form-row">
+            <label for="node-input-timeoutMs"><i class="fa fa-clock-o"></i> Timeout (ms)</label>
+            <input type="text" id="node-input-timeoutMs" style="width:100px">
+        </div>
+    </div>
+    <script type="text/javascript">
+        (function () {
+            $('#gh-advanced-toggle').on('click', function (e) {
+                e.preventDefault();
+                $('#gh-advanced-fields').slideToggle();
+                $('#gh-advanced-icon').toggleClass('fa-angle-right fa-angle-down');
+            });
+        }());
+    </script>
+</script>
+
+<script type="text/html" data-help-name="gh">
+    <p>Runs one GitHub CLI (<code>gh</code>) invocation per incoming message
+       and returns its result. Requires <code>gh</code> to already be
+       installed and authenticated (<code>gh auth login</code>) on the
+       Node-RED host -- this node does not implement its own login flow.</p>
+
+    <h3>Editor fields</h3>
+    <dl class="message-properties">
+        <dt>Command</dt>
+        <dd>The gh top-level subcommand, e.g. <code>pr</code>, <code>issue</code>,
+            <code>workflow</code>, <code>api</code>. Not the full command
+            line -- <code>gh</code> itself is always the executable.</dd>
+        <dt>Arguments</dt>
+        <dd>Everything after the command, e.g.
+            <code>list --state open --json number,title,url</code>. Quoted
+            spans stay together as one argument; nothing is passed through
+            a shell.</dd>
+        <dt>Repository</dt>
+        <dd>Optional <code>owner/repo</code>. Sets <code>GH_REPO</code> for
+            the invocation so it works without a checked-out git repo.</dd>
+    </dl>
+
+    <h3>Inputs</h3>
+    <dl class="message-properties">
+        <dt class="optional">gh <span class="property-type">object</span></dt>
+        <dd>Overrides the node's configuration for this message:
+            <code>msg.gh.command</code>, <code>msg.gh.args</code> (string or
+            array -- array is preferred, it skips argument parsing entirely),
+            <code>msg.gh.repo</code>, <code>msg.gh.host</code>.</dd>
+    </dl>
+
+    <h3>Outputs</h3>
+    <dl class="message-properties">
+        <dt>payload</dt>
+        <dd>Parsed JSON if stdout was valid JSON, otherwise the raw stdout
+            string.</dd>
+        <dt>gh <span class="property-type">object</span></dt>
+        <dd>Execution metadata: <code>{ command, args, repo, host, exitCode,
+            stderr }</code>. Never contains credentials.</dd>
+    </dl>
+
+    <p>A non-zero exit code, a timeout, or a missing <code>gh</code>
+       executable all trigger the node's error path (catchable with a Catch
+       node) instead of sending an output message.</p>
+</script>