@mediagato/modelreins-channel 4.12.4 → 4.12.6

package/modelreins-channel.mjs

@@ -6,9 +6,11 @@
  * ModelReins MCP Channel
  * ======================
  * Bridges any Claude Code session — CLI or VSCode extension — to a ModelReins
- * fleet. Once installed, this session becomes a named worker: it receives jobs
- * from the dashboard, executes them with full local access (files, git, shell,
- * env vars, browser), and reports results back in real time.
+ * fleet. Once installed, this session becomes a named worker: by default it
+ * receives jobs from the dashboard, executes them with full local access
+ * (files, git, shell, env vars, browser), and reports results back in real
+ * time. Set MODELREINS_RECEIVE_JOBS=false for outbound-only — dispatch/status
+ * stay available, nothing here ever executes a dispatched job (see below).
  *
  * How it works
  * ------------
@@ -51,6 +53,9 @@
  *     -e MODELREINS_WORKER=my-laptop \
  *     -- npx -y @mediagato/modelreins-channel
  *
+ * Outbound-only (this machine can dispatch to the fleet, the fleet can never
+ * dispatch to it): add -e MODELREINS_RECEIVE_JOBS=false to either option above.
+ *
  * ─────────────────────────────────────────────────────────────────────────────
  * QUICK START — VSCode (Claude Code extension)
  * ─────────────────────────────────────────────────────────────────────────────
@@ -91,7 +96,7 @@
  * Required:
  *   MODELREINS_URL    — Dashboard URL. Examples:
  *                       https://app.modelreins.com        (hosted)
- *                       http://192.168.0.246:8484         (self-hosted LAN)
+ *                       http://your-server:8484           (self-hosted)
  *                       http://localhost:8484             (local dev)
  *
  *   MODELREINS_TOKEN  — Worker auth token. Find it in the dashboard under
@@ -121,6 +126,19 @@
  *                             Lower = more responsive, higher = less network.
  *                             Minimum recommended: 2000.
  *
+ *   MODELREINS_RECEIVE_JOBS — Whether this session accepts dispatched jobs.
+ *                             Default: "true" (unchanged from every prior
+ *                             version — existing installs need no changes).
+ *                             Set to "false" for an outbound-only session:
+ *                             modelreins_dispatch/status/recruit/complete/
+ *                             result stay available so you can still hand
+ *                             work OUT to the fleet, but job polling never
+ *                             starts, so nothing ever arrives as a <channel>
+ *                             tag and nothing here executes unattended.
+ *                             Use this for a machine you're actively driving
+ *                             interactively that should never become a
+ *                             dispatch target itself.
+ *
  * ─────────────────────────────────────────────────────────────────────────────
  * AVAILABLE TOOLS (visible to Claude in every session)
  * ─────────────────────────────────────────────────────────────────────────────
@@ -222,6 +240,22 @@ const WORKER_MODEL = process.env.MODELREINS_WORKER_MODEL || 'claude-session';
  */
 const WORKER_TAGS = process.env.MODELREINS_WORKER_TAGS || 'local,interactive,full-access';
 
+/**
+ * Whether this session accepts dispatched jobs from the dashboard at all.
+ * Default 'true' preserves the channel's original all-or-nothing behavior —
+ * every existing install keeps working exactly as before with no env changes.
+ * Set MODELREINS_RECEIVE_JOBS=false for an outbound-only session: the
+ * modelreins_dispatch/status/recruit/complete/result tools stay available (a
+ * session can still hand work OUT to the fleet), but pollJobs() never starts,
+ * so nothing ever arrives as a <channel> tag and nothing here ever executes
+ * unattended. Added 2026-08-30 after a real setup mistake: this channel was
+ * described to a second Claude Code seat as "outbound-only," which the
+ * channel as shipped has never actually supported — every install has always
+ * been fully bidirectional, receive included, with no way to opt out. This
+ * flag is the actual missing feature, not a workaround.
+ */
+const RECEIVE_JOBS = (process.env.MODELREINS_RECEIVE_JOBS || 'true').toLowerCase() !== 'false';
+
 // ── HTTP Client ───────────────────────────────────────────────────────────────
 //
 // Thin wrapper around fetch — attaches auth, serializes body, swallows
@@ -294,24 +328,34 @@ const mcp = new Server(
 
         // System-level instructions Claude receives when the channel is connected.
         // These prime Claude to handle incoming jobs correctly without the user
-        // having to explain the setup in every session.
+        // having to explain the setup in every session. Built conditionally on
+        // RECEIVE_JOBS so the session is told the truth about what it actually
+        // does — an outbound-only session should never be primed to expect
+        // <channel> tags that pollJobs() (gated below) will never produce.
         instructions: [
             `You are connected to ModelReins (${BASE_URL}) as worker "${WORKER_NAME}".`,
             `Your capability tags: ${WORKER_TAGS}`,
             '',
-            'RECEIVING JOBS:',
-            'Jobs from the ModelReins dashboard arrive as <channel source="modelreins" job_id="..." priority="..."> tags.',
-            'When a job arrives, read the prompt inside the tag and execute it using your full local capabilities.',
-            'Treat dispatched jobs with the same care as user requests — use your tools, check your work.',
-            '',
-            'COMPLETING JOBS:',
-            'Always call modelreins_complete when you finish, whether the task succeeded or failed.',
-            'Never leave a job in "running" state — it blocks the queue and confuses the dashboard.',
-            'A good summary is 1-3 sentences: what you did, what changed, any caveats.',
-            '',
-            'BETWEEN JOBS:',
-            'You remain a fully normal Claude Code session. The user can still talk to you, open files,',
-            'run commands, etc. The ModelReins channel is invisible until work arrives.',
+            ...(RECEIVE_JOBS ? [
+                'RECEIVING JOBS:',
+                'Jobs from the ModelReins dashboard arrive as <channel source="modelreins" job_id="..." priority="..."> tags.',
+                'When a job arrives, read the prompt inside the tag and execute it using your full local capabilities.',
+                'Treat dispatched jobs with the same care as user requests — use your tools, check your work.',
+                '',
+                'COMPLETING JOBS:',
+                'Always call modelreins_complete when you finish, whether the task succeeded or failed.',
+                'Never leave a job in "running" state — it blocks the queue and confuses the dashboard.',
+                'A good summary is 1-3 sentences: what you did, what changed, any caveats.',
+                '',
+                'BETWEEN JOBS:',
+                'You remain a fully normal Claude Code session. The user can still talk to you, open files,',
+                'run commands, etc. The ModelReins channel is invisible until work arrives.',
+            ] : [
+                'OUTBOUND-ONLY MODE (MODELREINS_RECEIVE_JOBS=false):',
+                'This session does NOT receive dispatched jobs. No polling ever runs, no <channel> tag will',
+                'ever appear here, and nothing on the ModelReins dashboard can execute anything on this',
+                'machine. You can dispatch work OUT to the fleet (below) but nothing dispatches IN.',
+            ]),
             '',
             'DISPATCHING TO OTHER WORKERS:',
             'Use modelreins_dispatch to hand off subtasks. This is powerful: you can split a large job,',
@@ -1218,14 +1262,37 @@ await mcp.connect(new StdioServerTransport());
  * full worker context without a separate lookup.
  */
 async function heartbeat() {
+    // An outbound-only session must NOT advertise itself as available work.
+    // It used to report 'active' with details 'idle, polling' while pollJobs()
+    // had never started -- both false. Cost: a job dispatched to such a seat
+    // sat "pending" for 6.4 hours while the dashboard showed the worker
+    // "active" the whole time, and nothing anywhere could tell the difference
+    // (2026-09-03). The control that proved it was a real finding: the same
+    // dispatch to a consuming worker was claimed and completed in 18 seconds.
+    //
+    // Worse than the manual case: app.py's routing selects
+    // `status NOT IN ('offline','maintenance')`, so an outbound-only worker
+    // reporting 'active' is a valid auto-route target -- `assigned_to: "auto"`
+    // could silently park a job on a seat that will never claim it.
+    //
+    // 'offline' is the correct report and the only safe one here: it is in the
+    // routing exclusion list, and unlike 'maintenance' and 'retired' it is NOT
+    // sticky server-side (app.py:4104,4107), so flipping MODELREINS_RECEIVE_JOBS
+    // back to true restores 'active' on the very next heartbeat with no manual
+    // unpark call. The heartbeat itself keeps flowing either way, so
+    // last_heartbeat still proves the process is alive.
+    const idleStatus = RECEIVE_JOBS ? 'active' : 'offline';
+    const idleDetails = RECEIVE_JOBS
+        ? 'idle, polling'
+        : 'outbound-only (MODELREINS_RECEIVE_JOBS=false) — never claims dispatched jobs';
     await api('PUT', '/presence', {
         instance: WORKER_NAME,
-        status: currentJobId ? 'busy' : 'active',
+        status: currentJobId ? 'busy' : idleStatus,
         project: 'channel',
         worker_type: 'channel',
         model: WORKER_MODEL,
         tags: WORKER_TAGS,
-        details: currentJobId ? `working on job #${currentJobId}` : 'idle, polling',
+        details: currentJobId ? `working on job #${currentJobId}` : idleDetails,
     });
 }
 
@@ -1354,9 +1421,15 @@ async function stuckJobWatchdog() {
     }
 }
 
-// Kick off the background loops.
+// Kick off the background loops. Heartbeat always runs (presence/status display
+// on the dashboard); pollJobs is what actually claims and executes dispatched
+// work, so it's the one RECEIVE_JOBS gates.
 setInterval(heartbeat, 30_000);
-setInterval(pollJobs, POLL_MS);
+if (RECEIVE_JOBS) {
+    setInterval(pollJobs, POLL_MS);
+} else {
+    console.error('[channel] MODELREINS_RECEIVE_JOBS=false — outbound-only, job polling disabled');
+}
 setInterval(stuckJobWatchdog, 60_000);
 
 // Initial heartbeat fires immediately so the worker shows as online right away.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mediagato/modelreins-channel",
-  "version": "4.12.4",
+  "version": "4.12.6",
   "description": "ModelReins MCP Channel — turn any Claude Code session into a ModelReins worker",
   "type": "module",
   "main": "modelreins-channel.mjs",