@themoltnet/node-red-contrib-core 0.12.19 → 0.13.0

package/README.md

@@ -4,6 +4,41 @@ Node-RED nodes for the MoltNet API — drive the MoltNet SDK from Node-RED as a
 visual authoring + cockpit layer. See tracking issue
 [getlarge/themoltnet#1422](https://github.com/getlarge/themoltnet/issues/1422).
 
+## Install
+
+This package targets Node-RED 5 and is validated with Node.js 22. From the
+Node-RED user directory (normally `~/.node-red`), install the public package and
+restart Node-RED:
+
+```bash
+cd ~/.node-red
+npm install @themoltnet/node-red-contrib-core
+```
+
+The nodes then appear in the **moltnet** palette category. Once the package is
+listed in the Node-RED Flow Library, the same package can also be installed from
+**Manage palette → Install**.
+
+## First flow
+
+1. [Install and initialize a MoltNet agent](https://docs.themolt.net/start/install-and-initialize),
+   then keep an eligible agent daemon running so it can claim the task.
+2. Create a scoped key in [Agent Keys](https://console.themolt.net/runtime/agent-keys).
+   The minimal flow below needs `task:manage` and `task:read`.
+3. In Node-RED, wire **inject → task: build → tasks: create → task: wait →
+   task: read → debug**.
+4. On **task: build**, create a `moltnet-agent` configuration, choose **Agent
+   Key (recommended)**, paste the key once, and set the team and diary defaults.
+   Select the same configuration on the other MoltNet nodes.
+5. Give **task: build** a freeform brief, deploy the flow, and trigger the
+   inject node. **task: wait** emits progress on its first output and the
+   terminal snapshot on its second; **task: read** turns that snapshot into the
+   accepted result.
+
+See [Run agents](https://docs.themolt.net/operate/running-agents) for daemon,
+key rotation, and team-binding details. Packaged flows are available under
+**Menu → Import → Examples**.
+
 ## What it provides
 
 Empirically validated against **Node-RED 5.0.0** (Node 22):
@@ -30,12 +65,47 @@ For editor styling, install the separate companion package
 runtime nodes so it can be used independently by Node-RED instances that only
 want the MoltNet editor skin.
 
+## Authentication and scopes
+
+Open [Agent Keys](https://console.themolt.net/runtime/agent-keys), select the
+team and agent, then create a key containing only the scopes used by the flow.
+A team-bound key is the narrowest choice for a Node-RED instance pinned to one
+team. Use an identity-scoped key only when the same config node must select
+multiple teams where the agent is already a member.
+
+| Nodes or capability                                         | Required scope |
+| ----------------------------------------------------------- | -------------- |
+| `tasks: create`, `task: cancel`, `task artifact: stage`     | `task:manage`  |
+| Task list/get/wait, workflow status, artifact list/download | `task:read`    |
+| Task artifact upload and runtime-session operations         | `task:execute` |
+| Runtime-profile lookup                                      | `runtime:read` |
+| Entries search                                              | `diary:read`   |
+| Task builder and task reader                                | None (offline) |
+
+A key that may use every runtime node in this package therefore needs:
+
+```text
+diary:read runtime:read task:execute task:manage task:read
+```
+
+In the `moltnet-agent` config node, choose **Agent Key (recommended)** and paste
+the one-time key secret. Node-RED encrypts it with its credential secret and
+does not include it in exported flows. The SDK refuses to send an agent key
+over plaintext HTTP except to a loopback address used for local development.
+
+To keep using OAuth2, choose **OAuth2 Client Credentials** and enter the agent's
+client ID and secret. Config nodes exported before the authentication selector
+was added continue to infer OAuth2 from their existing client ID.
+
+For binding, rotation, and revocation, see
+[Team-bound and identity-scoped API keys](https://github.com/getlarge/themoltnet/blob/main/docs/operate/running-agents.md#team-bound-and-identity-scoped-api-keys).
+
 ## Nodes
 
-- **`moltnet-agent`** (config) — holds one MoltNet agent identity (OAuth2 client
-  credentials, Plane B). Client secret stored as an encrypted Node-RED
-  credential. Exposes `getAgent()` returning a connected, token-managed SDK
-  agent.
+- **`moltnet-agent`** (config) — holds one MoltNet agent identity (Plane B).
+  Scoped agent-key authentication is recommended; OAuth2 client credentials
+  remain supported. The agent key or client secret is stored as an encrypted
+  Node-RED credential. Exposes `getAgent()` returning a connected SDK agent.
 - **`moltnet-runtime-profile`** (config) — names one runtime profile by
   `profileId`; referenced by `tasks: create` to set `allowedProfiles`. References
   a `moltnet-agent` and offers a **dynamic dropdown** of the team's profiles
@@ -441,9 +511,10 @@ Three layers, increasing fidelity:
    > pnpm's symlinked store** (`Cannot find module @node-red/registry/lib/util`).
    > Hence the lightweight harness for unit tests.
 
-2. **Manual / local** — see the smoke test below. Configure `moltnet-agent` with a
-   real `clientId`/`clientSecret` (a throwaway local agent, or point `apiUrl` at a
-   local `docker-compose.e2e.yaml` rest-api) and drive a flow against live data.
+2. **Manual / local** — see the smoke test below. Configure `moltnet-agent` with
+   a scoped agent key or OAuth2 credentials for a throwaway local agent, point
+   `apiUrl` at the local `docker-compose.e2e.yaml` REST API, and drive a flow
+   against live data.
 
 3. **E2E** (future) — run the MoltNet e2e Docker stack + a real Node-RED 5 with
    this package installed, deploy a flow via Node-RED's admin HTTP API, inject,
@@ -481,7 +552,7 @@ Open the editor, drag in `agent` + the task nodes, or import
 [`examples/deep-review-freeform.flow.json`](./examples/deep-review-freeform.flow.json)
 or
 [`examples/axiom-alert-triage.flow.json`](./examples/axiom-alert-triage.flow.json),
-then fill the agent's `clientId`/`clientSecret`.
+then fill the agent's scoped key or OAuth2 credentials.
 
 If Node-RED crashes in `@node-red/editor-api/lib/auth/tokens.js` with
 `Cannot read properties of undefined (reading 'getSessions')`, the browser is

package/dist/nodes/agent.html

@@ -5,16 +5,39 @@
     defaults: {
       name: { value: '' },
       apiUrl: { value: 'https://api.themolt.net' },
-      clientId: { value: '', required: true },
+      authType: { value: 'agentKey', required: true },
+      clientId: { value: '' },
       teamId: { value: '' },
       diaryId: { value: '' },
     },
     credentials: {
+      agentKey: { type: 'password' },
       clientSecret: { type: 'password' },
     },
     label: function () {
       return this.name || this.clientId || 'moltnet-agent';
     },
+    oneditprepare: function () {
+      // Node-RED applies defaults before opening an older config node, so a
+      // flow saved before authType existed appears to use the new agentKey
+      // default. Detect its retained OAuth2 fields/credential marker and put
+      // the editor back in OAuth2 mode before a deploy can persist the default.
+      const legacyOAuth2 =
+        typeof this.clientId === 'string' &&
+        this.clientId.trim().length > 0 &&
+        this.credentials?.has_clientSecret === true &&
+        this.credentials?.has_agentKey !== true;
+      if (legacyOAuth2 && this.authType !== 'oauth2') {
+        $('#node-config-input-authType').val('oauth2');
+      }
+      const updateAuthRows = function () {
+        const agentKey = $('#node-config-input-authType').val() === 'agentKey';
+        $('.moltnet-auth-agent-key').toggle(agentKey);
+        $('.moltnet-auth-oauth2').toggle(!agentKey);
+      };
+      $('#node-config-input-authType').on('change', updateAuthRows);
+      updateAuthRows();
+    },
   });
 </script>
 
@@ -38,12 +61,27 @@
     />
   </div>
   <div class="form-row">
+    <label for="node-config-input-authType"
+      ><i class="fa fa-shield"></i> Authentication</label
+    >
+    <select id="node-config-input-authType">
+      <option value="agentKey">Agent Key (recommended)</option>
+      <option value="oauth2">OAuth2 Client Credentials</option>
+    </select>
+  </div>
+  <div class="form-row moltnet-auth-agent-key">
+    <label for="node-config-input-agentKey"
+      ><i class="fa fa-key"></i> Agent Key</label
+    >
+    <input type="password" id="node-config-input-agentKey" />
+  </div>
+  <div class="form-row moltnet-auth-oauth2">
     <label for="node-config-input-clientId"
       ><i class="fa fa-user"></i> Client ID</label
     >
     <input type="text" id="node-config-input-clientId" />
   </div>
-  <div class="form-row">
+  <div class="form-row moltnet-auth-oauth2">
     <label for="node-config-input-clientSecret"
       ><i class="fa fa-key"></i> Client Secret</label
     >
@@ -69,9 +107,15 @@
 
 <script type="text/html" data-help-name="moltnet-agent">
   <p>
-    Holds a single MoltNet agent identity (OAuth2 client credentials). Other
-    MoltNet nodes reference this config to act as that agent. The client secret
-    is stored as an encrypted Node-RED credential.
+    Holds one MoltNet agent identity. Agent key authentication is recommended;
+    OAuth2 client credentials remain supported. Secrets are stored as encrypted
+    Node-RED credentials and are not exported with flows.
+  </p>
+  <p>
+    A key used by every node in this package needs
+    <code>diary:read</code>, <code>runtime:read</code>,
+    <code>task:execute</code>, <code>task:manage</code>, and
+    <code>task:read</code>. Grant only the subset used by your flow.
   </p>
   <p>
     <b>Team ID</b> and <b>Diary ID</b> set the default team/diary context for

package/dist/nodes/agent.js

@@ -5,6 +5,7 @@ var init = (RED) => {
 		RED.nodes.createNode(this, def);
 		this.apiUrl = def.apiUrl?.trim() || "https://api.themolt.net";
 		this.clientId = def.clientId?.trim();
+		this.authType = def.authType === "agentKey" || def.authType === "oauth2" ? def.authType : this.clientId ? "oauth2" : "agentKey";
 		this.teamId = def.teamId?.trim() || void 0;
 		this.diaryId = def.diaryId?.trim() || void 0;
 		let agentPromise = null;
@@ -12,20 +13,36 @@ var init = (RED) => {
 			agentPromise = null;
 		};
 		this.getAgent = function getAgent() {
+			const authType = this.authType;
+			const agentKey = this.credentials?.agentKey?.trim();
+			const clientId = this.clientId;
 			const clientSecret = this.credentials?.clientSecret;
-			if (!this.clientId || !clientSecret) return Promise.reject(/* @__PURE__ */ new Error("moltnet-agent: clientId and clientSecret are required"));
-			if (!agentPromise) agentPromise = connect({
-				clientId: this.clientId,
-				clientSecret,
-				apiUrl: this.apiUrl
-			}).catch((err) => {
+			let createConnection;
+			if (authType === "agentKey") {
+				if (!agentKey) return Promise.reject(/* @__PURE__ */ new Error("moltnet-agent: agentKey is required"));
+				createConnection = () => connect({
+					agentKey,
+					apiUrl: this.apiUrl
+				});
+			} else {
+				if (!clientId || !clientSecret) return Promise.reject(/* @__PURE__ */ new Error("moltnet-agent: clientId and clientSecret are required for OAuth2"));
+				createConnection = () => connect({
+					clientId,
+					clientSecret,
+					apiUrl: this.apiUrl
+				});
+			}
+			if (!agentPromise) agentPromise = createConnection().catch((err) => {
 				agentPromise = null;
 				throw err;
 			});
 			return agentPromise;
 		};
 	}
-	RED.nodes.registerType("moltnet-agent", MoltnetAgentNode, { credentials: { clientSecret: { type: "password" } } });
+	RED.nodes.registerType("moltnet-agent", MoltnetAgentNode, { credentials: {
+		agentKey: { type: "password" },
+		clientSecret: { type: "password" }
+	} });
 };
 //#endregion
 export { init as default };

package/dist/nodes/task-get.js

@@ -1,5 +1,5 @@
 import { t as withAgent } from "./agent-call.js";
-import { t as buildTaskSnapshot } from "./task-snapshot.js";
+import { buildTaskSnapshot } from "@themoltnet/sdk";
 //#region src/nodes/task-get.ts
 var init = (RED) => {
 	function TaskGetNode(def) {

package/dist/nodes/task-wait.js

@@ -1,5 +1,5 @@
 import { t as withAgent } from "./agent-call.js";
-import { n as isTerminalTaskStatus, t as buildTaskSnapshot } from "./task-snapshot.js";
+import { buildTaskSnapshot, isTerminalTaskStatus } from "@themoltnet/sdk";
 //#region src/nodes/task-wait.ts
 var DEFAULT_POLL_SEC = 5;
 var DEFAULT_TIMEOUT_SEC = 1800;

package/examples/ab-eval-with-judge.flow.json

@@ -255,7 +255,7 @@
   },
   {
     "apiUrl": "https://api.themolt.net",
-    "clientId": "b46d59c1-0b14-453c-a57b-8be1ced93141",
+    "authType": "agentKey",
     "diaryId": "6e4d9948-8ec5-4f59-b82a-3acbc4bbc396",
     "id": "eval_agent_cfg",
     "name": "eval-agent",

package/examples/axiom-alert-triage.flow.json

@@ -8,7 +8,7 @@
   },
   {
     "apiUrl": "https://api.themolt.net",
-    "clientId": "",
+    "authType": "agentKey",
     "diaryId": "",
     "id": "moltnet_agent_cfg",
     "name": "triage-agent",

package/examples/cockpit.flow.json

@@ -8,7 +8,7 @@
   },
   {
     "apiUrl": "https://api.themolt.net",
-    "clientId": "",
+    "authType": "agentKey",
     "id": "moltnet_agent_cfg",
     "name": "my-agent",
     "type": "moltnet-agent"

package/examples/deep-review-freeform.flow.json

@@ -8,7 +8,7 @@
   },
   {
     "apiUrl": "",
-    "clientId": "b46d59c1-0b14-453c-a57b-8be1ced93141",
+    "authType": "agentKey",
     "diaryId": "6e4d9948-8ec5-4f59-b82a-3acbc4bbc396",
     "id": "deep_review_agent_cfg",
     "name": "deep-review-agent",

package/examples/issue-lifecycle.flow.json

@@ -2,13 +2,13 @@
   {
     "disabled": false,
     "id": "moltnet_lifecycle_tab",
-    "info": "Reproduces the apps/issue-lifecycle orchestration shape in Node-RED.\n\nEach step is: tasks:create → task:wait → switch(phase/decision) → next step.\nDurability is coarse (re-run from top with idempotent steps), inherited from\nthe MoltNet tasks tier — Node-RED is the authoring/cockpit surface, not the\ndurable engine (see issue #1422).\n\ntask:wait has two outputs: output 1 (tail) streams live task messages to a\ndebug node; output 2 (result) carries the terminal snapshot the switch nodes\nbranch on. A failed task is routed to the 'interpret failure' debug, the hook\nwhere an agent/human decides retry vs. escalate — exactly what the\nissue-lifecycle supervisor does.\n\nReplace the moltnet-agent clientId/secret and the inject's issue payload, then\nwire real task bodies into each tasks:create (this example uses minimal bodies).",
+    "info": "Reproduces the apps/issue-lifecycle orchestration shape in Node-RED.\n\nEach step is: tasks:create → task:wait → switch(phase/decision) → next step.\nDurability is coarse (re-run from top with idempotent steps), inherited from\nthe MoltNet tasks tier — Node-RED is the authoring/cockpit surface, not the\ndurable engine (see issue #1422).\n\ntask:wait has two outputs: output 1 (tail) streams live task messages to a\ndebug node; output 2 (result) carries the terminal snapshot the switch nodes\nbranch on. A failed task is routed to the 'interpret failure' debug, the hook\nwhere an agent/human decides retry vs. escalate — exactly what the\nissue-lifecycle supervisor does.\n\nAdd a scoped agent key to the moltnet-agent config and update the inject's issue\npayload, then wire real task bodies into each tasks:create (this example uses\nminimal bodies).",
     "label": "MoltNet Issue Lifecycle (example)",
     "type": "tab"
   },
   {
     "apiUrl": "https://api.themolt.net",
-    "clientId": "",
+    "authType": "agentKey",
     "diaryId": "",
     "id": "moltnet_agent_cfg",
     "name": "my-agent",

package/examples/weather-advisor.flow.json

@@ -2,13 +2,13 @@
   {
     "disabled": false,
     "id": "weather_tab",
-    "info": "Free-text request → INTENT agent (classify + extract slots) → Open-Meteo forecast → ADVISOR agent (reason → recommend) → JUDGE agent (evaluate vs rubric) → decision.\n\nDemonstrates: external API → agent, passing context via the `task: build` node's context rows, agent output→input chaining via the `task: read` node's pre-computed `outputRef`, and judgment/eval via a freeform task with a rubric.\n\nThe `task: build` nodes compose the create body from the SDK builder; `task: read` parses each completed snapshot into typed output (`msg.payload`) + a flat `msg.result` (summary, outputRef, artifactBody).\n\nFill the moltnet-agent config (clientId/secret + teamId/diaryId) and run a daemon. See the comment node for model-specialization notes.",
+    "info": "Free-text request → INTENT agent (classify + extract slots) → Open-Meteo forecast → ADVISOR agent (reason → recommend) → JUDGE agent (evaluate vs rubric) → decision.\n\nDemonstrates: external API → agent, passing context via the `task: build` node's context rows, agent output→input chaining via the `task: read` node's pre-computed `outputRef`, and judgment/eval via a freeform task with a rubric.\n\nThe `task: build` nodes compose the create body from the SDK builder; `task: read` parses each completed snapshot into typed output (`msg.payload`) + a flat `msg.result` (summary, outputRef, artifactBody).\n\nFill the moltnet-agent config (scoped agent key + teamId/diaryId) and run a daemon. See the comment node for model-specialization notes.",
     "label": "MoltNet Weather Advisor (multi-agent)",
     "type": "tab"
   },
   {
     "apiUrl": "https://api.themolt.net",
-    "clientId": "",
+    "authType": "agentKey",
     "diaryId": "",
     "id": "weather_agent_cfg",
     "name": "weather-agent",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@themoltnet/node-red-contrib-core",
-  "version": "0.12.19",
+  "version": "0.13.0",
   "type": "module",
   "description": "Node-RED nodes for the MoltNet API",
   "keywords": [
@@ -46,7 +46,7 @@
   },
   "main": "dist/nodes/agent.js",
   "dependencies": {
-    "@themoltnet/sdk": "0.138.0"
+    "@themoltnet/sdk": "0.139.0"
   },
   "devDependencies": {
     "@types/node": "^22.19.0",

package/dist/nodes/task-snapshot.js

@@ -1,32 +0,0 @@
-//#region src/nodes/task-snapshot.ts
-/** Task statuses that mean the run will not progress further. */
-var TERMINAL_TASK_STATUSES = new Set([
-	"completed",
-	"failed",
-	"cancelled",
-	"expired"
-]);
-function isTerminalTaskStatus(status) {
-	return TERMINAL_TASK_STATUSES.has(status);
-}
-function buildTaskSnapshot(task, attempts) {
-	const acceptedAttemptN = task.acceptedAttemptN;
-	const acceptedAttempt = acceptedAttemptN !== null ? attempts.find((a) => a.attemptN === acceptedAttemptN) ?? null : null;
-	const latestAttempt = attempts.length > 0 ? attempts.reduce((max, a) => a.attemptN > max.attemptN ? a : max) : null;
-	const attempt = acceptedAttempt ?? latestAttempt;
-	const accepted = acceptedAttempt !== null;
-	return {
-		taskId: task.id,
-		status: task.status,
-		terminal: isTerminalTaskStatus(task.status),
-		accepted,
-		acceptedAttemptN,
-		state: accepted ? acceptedAttempt?.output ?? null : null,
-		attempt,
-		attempts,
-		error: latestAttempt?.error ?? null,
-		task
-	};
-}
-//#endregion
-export { isTerminalTaskStatus as n, buildTaskSnapshot as t };