@openagents-org/agent-launcher 0.2.192 → 0.2.194

package/src/log-writer.js

@@ -0,0 +1,351 @@
+'use strict';
+
+/**
+ * The daemon's writer for daemon.log — one sink shared by the daemon and every
+ * adapter running inside it.
+ *
+ * The line format is unchanged (`<ISO time> <LEVEL> <scope>: <message>`, extra
+ * message lines following as continuation lines): Launchers already in the
+ * field parse this file, and they may run a newer core than they shipped with.
+ * What changes is how lines get there:
+ *
+ *  - Batched, asynchronous writes. The old writer did an appendFileSync — an
+ *    open/write/close on the event loop — plus a statSync for every line. Lines
+ *    now collect in memory and go out in one append per `flushMs`, or sooner
+ *    once `flushBytes` are waiting. The size check runs once per batch.
+ *
+ *  - Repeat suppression. A failure that repeats every few seconds used to fill
+ *    the file with identical entries and rotate out everything useful. Within
+ *    each `rateWindowMs`, lines with the same level, scope and message shape
+ *    (digits and ids masked) pass `rateBurst` times; the rest are counted and
+ *    reported in one line when the window ends. ERROR lines always pass.
+ *
+ *  - Copy-truncate rotation with gzip generations. The old rename-based
+ *    rotation moved the file out from under every process that inherited a
+ *    handle to it — the daemon's own stdout/stderr, and with them every
+ *    adapter line — so those kept writing into the renamed backup, which the
+ *    next rotation deleted while still open. Copying the file aside and then
+ *    truncating it keeps every holder writing to daemon.log (they all opened
+ *    it in append mode). The copy is gzipped into daemon.log.1.gz, and the
+ *    older generations shift up to `keep`.
+ *
+ * Writes are best-effort, as they always were: a log that cannot be written
+ * must never take the daemon down.
+ */
+
+const fs = require('fs');
+const zlib = require('zlib');
+const { pipeline } = require('stream');
+
+const LEVEL_TOKENS = { debug: 'DEBUG', info: 'INFO', warn: 'WARN', error: 'ERROR' };
+
+const DEFAULTS = {
+  flushMs: 250,
+  flushBytes: 64 * 1024,
+  // Backlog bound for a log that cannot keep up (a stalled disk). Past this the
+  // oldest waiting lines are dropped and the drop is reported in the log.
+  maxPendingBytes: 4 * 1024 * 1024,
+  maxBytes: 10 * 1024 * 1024,
+  keep: 5,
+  rateWindowMs: 60 * 1000,
+  rateBurst: 20,
+  // Distinct message shapes tracked per window. A shape seen after the table
+  // is full is let through rather than tracked.
+  maxRateKeys: 1024,
+};
+
+/** Every writer with lines that may still be in memory; flushed on exit. */
+const live = new Set();
+let exitHookInstalled = false;
+
+function installExitHook() {
+  if (exitHookInstalled) return;
+  exitHookInstalled = true;
+  process.once('exit', () => {
+    for (const w of live) w.flushSync();
+  });
+}
+
+function normalizeLevel(level) {
+  return Object.prototype.hasOwnProperty.call(LEVEL_TOKENS, level) ? level : 'info';
+}
+
+/**
+ * The shape of a message: its first line with ids and numbers masked, so
+ * `Poll #257 failed` and `Poll #258 failed` count as the same line.
+ */
+function messageShape(message) {
+  const first = String(message).split('\n', 1)[0];
+  return first
+    .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, '<id>')
+    .replace(/\d+/g, '#')
+    .slice(0, 200);
+}
+
+class LogWriter {
+  /**
+   * @param {string} file - daemon.log
+   * @param {object} [opts] - overrides for DEFAULTS
+   */
+  constructor(file, opts = {}) {
+    this.file = file;
+    this.opts = { ...DEFAULTS, ...opts };
+
+    this._pending = [];
+    this._pendingBytes = 0;
+    this._timer = null;
+    this._writing = false;
+    this._rotating = false;
+    this._waiters = [];
+
+    this._rate = new Map();
+    this._windowStart = Date.now();
+    this._windowTimer = null;
+
+    this.stats = { written: 0, suppressed: 0, dropped: 0, writeErrors: 0, rotations: 0 };
+    this._droppedSinceNote = 0;
+
+    live.add(this);
+    installExitHook();
+  }
+
+  /** Queue one entry. Returns false when it was suppressed as a repeat. */
+  write(level, scope, message) {
+    const lvl = normalizeLevel(level);
+    const now = Date.now();
+    if (!this._admit(lvl, scope, message, now)) return false;
+    this._enqueue(lvl, scope, message, now);
+    return true;
+  }
+
+  /** Resolves once everything queued so far is on disk (or failed to be). */
+  flush() {
+    return new Promise((resolve) => {
+      this._rollWindow(Date.now());
+      if (!this._writing && this._pending.length === 0) return resolve();
+      this._waiters.push(resolve);
+      if (this._timer) { clearTimeout(this._timer); this._timer = null; }
+      this._flush();
+    });
+  }
+
+  /**
+   * Write whatever is still queued, synchronously. For process exit, where an
+   * asynchronous write would never complete.
+   */
+  flushSync() {
+    this._rollWindow(Date.now());
+    if (this._timer) { clearTimeout(this._timer); this._timer = null; }
+    const data = this._takePending();
+    if (!data) return;
+    try {
+      fs.appendFileSync(this.file, data, 'utf-8');
+      this.stats.written += data.length;
+    } catch {
+      this.stats.writeErrors++;
+    }
+  }
+
+  /** Flush synchronously and stop tracking this writer. */
+  close() {
+    this.flushSync();
+    if (this._windowTimer) { clearTimeout(this._windowTimer); this._windowTimer = null; }
+    live.delete(this);
+  }
+
+  // ------------------------------------------------------------------
+  // Repeat suppression
+  // ------------------------------------------------------------------
+
+  _admit(level, scope, message, now) {
+    if (level === 'error') return true;
+    if (now - this._windowStart >= this.opts.rateWindowMs) this._rollWindow(now);
+
+    const key = `${level}\u0000${scope}\u0000${messageShape(message)}`;
+    let slot = this._rate.get(key);
+    if (!slot) {
+      if (this._rate.size >= this.opts.maxRateKeys) return true;
+      slot = { level, scope, sample: String(message).split('\n', 1)[0], seen: 0, suppressed: 0 };
+      this._rate.set(key, slot);
+    }
+    slot.seen++;
+    if (slot.seen <= this.opts.rateBurst) return true;
+
+    slot.suppressed++;
+    this.stats.suppressed++;
+    // Report at the end of this window even if nothing else is ever logged.
+    if (!this._windowTimer) {
+      const wait = Math.max(0, this._windowStart + this.opts.rateWindowMs - now);
+      this._windowTimer = setTimeout(() => {
+        this._windowTimer = null;
+        this._rollWindow(Date.now());
+      }, wait);
+      if (this._windowTimer.unref) this._windowTimer.unref();
+    }
+    return false;
+  }
+
+  /** Close the current window: one summary line per suppressed shape. */
+  _rollWindow(now) {
+    const secs = Math.max(1, Math.round((now - this._windowStart) / 1000));
+    for (const slot of this._rate.values()) {
+      if (slot.suppressed > 0) {
+        this._enqueue(
+          slot.level,
+          slot.scope,
+          `Suppressed ${slot.suppressed} more like this in the last ${secs}s: ${slot.sample}`,
+          now,
+        );
+      }
+    }
+    this._rate.clear();
+    this._windowStart = now;
+    if (this._windowTimer) { clearTimeout(this._windowTimer); this._windowTimer = null; }
+  }
+
+  // ------------------------------------------------------------------
+  // Batching
+  // ------------------------------------------------------------------
+
+  _format(level, scope, message, now) {
+    return `${new Date(now).toISOString()} ${LEVEL_TOKENS[level]} ${scope}: ${message}\n`;
+  }
+
+  _enqueue(level, scope, message, now) {
+    const line = this._format(level, scope, message, now);
+    this._pending.push(line);
+    this._pendingBytes += line.length;
+
+    while (this._pendingBytes > this.opts.maxPendingBytes && this._pending.length > 1) {
+      this._pendingBytes -= this._pending.shift().length;
+      this.stats.dropped++;
+      this._droppedSinceNote++;
+    }
+
+    this._schedule(this._pendingBytes >= this.opts.flushBytes ? 0 : this.opts.flushMs);
+  }
+
+  _schedule(delay) {
+    // A write in progress picks up the backlog when it completes.
+    if (this._writing) return;
+    if (this._timer) {
+      if (delay > 0) return;
+      clearTimeout(this._timer);
+    }
+    this._timer = setTimeout(() => {
+      this._timer = null;
+      this._flush();
+    }, delay);
+    if (this._timer.unref) this._timer.unref();
+  }
+
+  _takePending() {
+    if (this._droppedSinceNote > 0) {
+      this._pending.unshift(this._format(
+        'warn', 'daemon',
+        `Log writer fell behind — dropped ${this._droppedSinceNote} line(s)`,
+        Date.now(),
+      ));
+      this._droppedSinceNote = 0;
+    }
+    if (this._pending.length === 0) return '';
+    const data = this._pending.join('');
+    this._pending = [];
+    this._pendingBytes = 0;
+    return data;
+  }
+
+  _flush() {
+    if (this._writing) return;
+    const data = this._takePending();
+    if (!data) return this._settle();
+
+    this._writing = true;
+    fs.appendFile(this.file, data, 'utf-8', (err) => {
+      if (err) this.stats.writeErrors++;
+      else this.stats.written += data.length;
+      this._maybeRotate(() => {
+        this._writing = false;
+        if (this._pending.length > 0) this._flush();
+        else this._settle();
+      });
+    });
+  }
+
+  _settle() {
+    if (this._writing || this._pending.length > 0) return;
+    const waiters = this._waiters;
+    this._waiters = [];
+    for (const resolve of waiters) resolve();
+  }
+
+  // ------------------------------------------------------------------
+  // Rotation
+  // ------------------------------------------------------------------
+
+  _gen(n) {
+    return `${this.file}.${n}.gz`;
+  }
+
+  _maybeRotate(done) {
+    if (this._rotating) return done();
+    fs.stat(this.file, (err, st) => {
+      if (err || st.size < this.opts.maxBytes) return done();
+      this._rotate(done);
+    });
+  }
+
+  /**
+   * Copy the full log aside, truncate it in place, then compress the copy in
+   * the background. `done` runs as soon as the truncate lands, so writing
+   * continues into the emptied file while the copy is compressed.
+   *
+   * A line another process appends between the copy and the truncate is lost.
+   * That window is the duration of one file copy, once per `maxBytes` of log.
+   */
+  _rotate(done) {
+    this._rotating = true;
+    const copy = `${this.file}.rotating`;
+    try {
+      fs.copyFileSync(this.file, copy);
+      fs.truncateSync(this.file, 0);
+    } catch {
+      try { fs.unlinkSync(copy); } catch { /* not created */ }
+      this._rotating = false;
+      return done();
+    }
+    this.stats.rotations++;
+    done();
+
+    this._shiftGenerations();
+    const target = this._gen(1);
+    const partial = `${target}.tmp`;
+    pipeline(
+      fs.createReadStream(copy),
+      zlib.createGzip(),
+      fs.createWriteStream(partial),
+      (err) => {
+        try { fs.unlinkSync(copy); } catch { /* already gone */ }
+        if (err) {
+          try { fs.unlinkSync(partial); } catch { /* not created */ }
+        } else {
+          try { fs.renameSync(partial, target); } catch { /* best effort */ }
+        }
+        this._rotating = false;
+      },
+    );
+  }
+
+  _shiftGenerations() {
+    const { keep } = this.opts;
+    try { fs.unlinkSync(this._gen(keep)); } catch { /* none yet */ }
+    for (let n = keep - 1; n >= 1; n--) {
+      try { fs.renameSync(this._gen(n), this._gen(n + 1)); } catch { /* none yet */ }
+    }
+    // The uncompressed backup the previous writer kept. It was always deleted
+    // at the next rotation; this is that rotation.
+    try { fs.unlinkSync(`${this.file}.1`); } catch { /* none */ }
+  }
+}
+
+module.exports = { LogWriter, messageShape, DEFAULTS };

package/src/mcp-server.js

@@ -22,6 +22,8 @@ const _activeTunnels = {};
 
 // ── Tool definitions ────────────────────────────────────────────────────────
 
+const v11 = require('./tools-v11');
+
 function buildToolDefs(disabledModules) {
   const tools = [
     // -- Workspace core (always enabled) --
@@ -73,6 +75,21 @@ function buildToolDefs(disabledModules) {
           required: ['file_id'],
         },
       },
+      {
+        name: 'workspace_publish_project',
+        description: 'Publish a static web project as one previewable artifact. Include its HTML, images, CSS, JavaScript and data using relative paths. No servers or dependencies are installed. Exclude secrets and hidden files. Reuse project_id and expected_revision to update while keeping its link and pins.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            title: { type: 'string' }, entrypoint: { type: 'string', description: 'Relative HTML entry page, usually index.html' },
+            project_id: { type: 'string' }, expected_revision: { type: 'string', description: 'Revision returned by the last publish or preview' },
+            files: { type: 'array', maxItems: 500, items: { type: 'object', properties: {
+              path: { type: 'string' }, content: { type: 'string', description: 'UTF-8 text, or use content_base64 for binary files' },
+              content_base64: { type: 'string' },
+            }, required: ['path'] } },
+          }, required: ['title', 'files'],
+        },
+      },
       {
         name: 'workspace_write_file',
         description: 'Write/upload a file to shared workspace storage.',
@@ -442,6 +459,40 @@ function buildToolDefs(disabledModules) {
     );
   }
 
+  // -- Approvals (always on: a governance primitive, not a skill) --
+  tools.push(
+    {
+      name: 'workspace_request_approval',
+      description: 'Ask a human for permission BEFORE doing something consequential: deploying to production, spending money or calling paid APIs, sending email/messages to customers or external parties, deleting data, or any irreversible action you are unsure about. Workspace policy decides: the request may be auto-approved, auto-blocked, or paused until a person with the right role approves it in the thread. This call blocks (up to wait_seconds) until a decision arrives and returns it. If it returns "pending", stop and wait — the decision will arrive as a message in this thread.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          action: { type: 'string', description: 'Short label of what you want to do, e.g. "Deploy 2.4 hotfix to prod-eu" or "Email 38 affected customers"' },
+          kind: {
+            type: 'string',
+            enum: ['deploy', 'spend', 'external_send', 'repo_read', 'repo_write', 'data_delete', 'shell', 'other'],
+            description: 'Category the policy is keyed on. deploy=production deploys; spend=money/paid APIs; external_send=email/messages leaving the workspace; repo_read/repo_write=git; data_delete=destructive data ops; shell=commands with side effects; other=anything else',
+          },
+          details: { type: 'string', description: 'The exact command, diff summary, recipient list, URL or amount — what a reviewer needs to decide' },
+          risk: { type: 'string', enum: ['low', 'medium', 'high'], description: 'Your own risk estimate' },
+          wait_seconds: { type: 'integer', description: 'How long to wait for a decision before returning "pending" (default 300, max 900)' },
+        },
+        required: ['action', 'kind'],
+      },
+    },
+    {
+      name: 'workspace_check_approval',
+      description: 'Check the status of an approval request you made earlier (by id). Use after workspace_request_approval returned "pending".',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          approval_id: { type: 'string', description: 'The approval id returned by workspace_request_approval' },
+        },
+        required: ['approval_id'],
+      },
+    },
+  );
+
   // -- Knowledge Base --
   if (!disabledModules.has('knowledge')) {
     tools.push(
@@ -489,9 +540,37 @@ function buildToolDefs(disabledModules) {
     );
   }
 
+  // -- v1.1 milestone tools (always on) --
+  tools.push(...v11.toolDefs());
+
   return tools;
 }
 
+// ── Approvals ───────────────────────────────────────────────────────────────
+
+/**
+ * What the agent reads back from an approval. The verdict comes first so a
+ * model skimming the tool result cannot miss it.
+ */
+function formatApproval(a) {
+  const who = a.resolved_by === 'policy'
+    ? 'workspace policy'
+    : a.resolved_by ? `${a.resolved_by}${a.resolved_by_role ? ` (${a.resolved_by_role})` : ''}` : null;
+  const note = a.note ? `\nNote from approver: ${a.note}` : '';
+  switch (a.status) {
+    case 'approved':
+      return `APPROVED — "${a.action}" was approved by ${who}. You may proceed.${note}\n(approval id: ${a.id})`;
+    case 'rejected':
+      return `REJECTED — "${a.action}" was rejected by ${who}. Do NOT do it. Explain in the thread what you would have done and ask how to proceed.${note}\n(approval id: ${a.id})`;
+    case 'expired':
+      return `EXPIRED — nobody decided on "${a.action}" in time. Do not proceed; ask in the thread.\n(approval id: ${a.id})`;
+    default: {
+      const role = a.required_role === 'admin' ? 'an Admin' : a.required_role === 'owner' ? 'the Owner' : 'a workspace member';
+      return `PENDING — "${a.action}" is waiting for ${role} to approve. Do NOT proceed with this action. Stop here and end your turn; the decision will arrive as a new message in this thread (@mentioning you), or call workspace_check_approval with id ${a.id} later.`;
+    }
+  }
+}
+
 // ── MIME type detection ─────────────────────────────────────────────────────
 
 const MIME_MAP = {
@@ -521,12 +600,13 @@ function isTextMime(mime) {
 // ── MCP Server ──────────────────────────────────────────────────────────────
 
 class McpServer {
-  constructor({ wsClient, workspaceId, channelName, agentName, token, disabledModules }) {
+  constructor({ wsClient, workspaceId, channelName, agentName, token, disabledModules, requesterEmail = process.env.OPENAGENTS_REQUESTER_EMAIL || null }) {
     this.ws = wsClient;
     this.workspaceId = workspaceId;
     this.channelName = channelName;
     this.agentName = agentName;
     this.token = token;
+    this.requesterEmail = requesterEmail;
     this.disabledModules = disabledModules || new Set();
     this.tools = buildToolDefs(this.disabledModules);
   }
@@ -662,6 +742,20 @@ class McpServer {
         return text(str);
       }
 
+      case 'workspace_publish_project': {
+        const channel = this.channelName && !this.channelName.startsWith('dm:') ? this.channelName : undefined;
+        const files = args.files.map(file => {
+          if (typeof file.content_base64 !== 'string' && typeof file.content !== 'string') throw new Error('Each file needs content or content_base64');
+          return { path:file.path, content_base64:file.content_base64 ?? Buffer.from(file.content,'utf8').toString('base64') };
+        });
+        const result = await this.ws.publishWebProject(this.workspaceId, this.token, {
+          title:args.title, entrypoint:args.entrypoint || 'index.html', files,
+          channel_name:channel, visibility:channel ? 'inherit' : 'private',
+          source:`openagents:${this.agentName}`, expected_revision:args.expected_revision,
+        }, args.project_id);
+        return text(`Project published (id: ${result.id}, revision: ${result.revision}). Link it in your reply: [${args.title}](/v1/files/${encodeURIComponent(result.id)})`);
+      }
+
       case 'workspace_write_file': {
         const mime = args.content_type || detectMime(args.filename);
         let b64;
@@ -674,9 +768,10 @@ class McpServer {
           contentType: mime,
           source: `openagents:${this.agentName}`,
           channelName: this.channelName,
+          visibility: this.channelName ? 'inherit' : undefined,
         });
         const fileId = result.id || result.file_id || 'unknown';
-        return text(`File written: ${args.filename} (id: ${fileId})`);
+        return text(`File written: ${args.filename} (id: ${fileId}). Link it in your reply: [${args.filename}](/v1/files/${encodeURIComponent(fileId)})`);
       }
 
       case 'workspace_delete_file': {
@@ -745,6 +840,7 @@ class McpServer {
         const opts = {
           url: args.url || 'about:blank',
           source: `openagents:${this.agentName}`,
+          channel: this.channelName,
         };
         // Resolve context_name to context_id
         if (args.context_name) {
@@ -767,29 +863,29 @@ class McpServer {
       }
 
       case 'workspace_browser_navigate': {
-        const result = await this.ws.browserNavigate(this.workspaceId, this.token, args.tab_id, args.url);
+        const result = await this.ws.browserNavigate(this.workspaceId, this.token, args.tab_id, args.url, { source: `openagents:${this.agentName}`, channel: this.channelName });
         const title = result.title || '';
         return text(`Navigated to: ${args.url}${title ? ` (title: ${title})` : ''}`);
       }
 
       case 'workspace_browser_click': {
-        const result = await this.ws.browserClick(this.workspaceId, this.token, args.tab_id, args.selector);
+        const result = await this.ws.browserClick(this.workspaceId, this.token, args.tab_id, args.selector, { source: `openagents:${this.agentName}`, channel: this.channelName });
         return text(`Clicked: ${args.selector}${result.url ? ` (url now: ${result.url})` : ''}`);
       }
 
       case 'workspace_browser_type': {
-        await this.ws.browserType(this.workspaceId, this.token, args.tab_id, args.selector, args.text);
+        await this.ws.browserType(this.workspaceId, this.token, args.tab_id, args.selector, args.text, { source: `openagents:${this.agentName}`, channel: this.channelName });
         return text(`Typed into ${args.selector}: ${args.text.slice(0, 50)}${args.text.length > 50 ? '...' : ''}`);
       }
 
       case 'workspace_browser_screenshot': {
-        const buf = await this.ws.browserScreenshot(this.workspaceId, this.token, args.tab_id);
+        const buf = await this.ws.browserScreenshot(this.workspaceId, this.token, args.tab_id, { source: `openagents:${this.agentName}`, channel: this.channelName });
         const b64 = Buffer.isBuffer(buf) ? buf.toString('base64') : buf;
         return image(b64, 'image/png');
       }
 
       case 'workspace_browser_snapshot': {
-        const snapshot = await this.ws.browserSnapshot(this.workspaceId, this.token, args.tab_id);
+        const snapshot = await this.ws.browserSnapshot(this.workspaceId, this.token, args.tab_id, { source: `openagents:${this.agentName}`, channel: this.channelName });
         return text(typeof snapshot === 'string' ? snapshot : JSON.stringify(snapshot));
       }
 
@@ -1039,6 +1135,35 @@ class McpServer {
         return text(lines.join('\n'));
       }
 
+      // ── Approvals ──
+
+      case 'workspace_request_approval': {
+        const waitSec = Math.max(0, Math.min(900, Number(args.wait_seconds) || 300));
+        let approval = await this.ws.createApproval(this.workspaceId, this.token, {
+          channel: this.channelName,
+          kind: args.kind || 'other',
+          action: args.action,
+          details: args.details,
+          risk: args.risk,
+          source: `openagents:${this.agentName}`,
+        });
+        const deadline = Date.now() + waitSec * 1000;
+        while (approval.status === 'pending' && Date.now() < deadline) {
+          await new Promise((r) => setTimeout(r, 3000));
+          try {
+            approval = await this.ws.getApproval(this.workspaceId, this.token, approval.id);
+          } catch (e) {
+            this._log(`approval poll failed: ${e.message}`);
+          }
+        }
+        return text(formatApproval(approval));
+      }
+
+      case 'workspace_check_approval': {
+        const approval = await this.ws.getApproval(this.workspaceId, this.token, args.approval_id);
+        return text(formatApproval(approval));
+      }
+
       // ── Knowledge Base ──
 
       case 'workspace_list_knowledge': {
@@ -1087,8 +1212,11 @@ class McpServer {
         return text(`Knowledge entry deleted: ${args.entry_id}`);
       }
 
-      default:
+      default: {
+        const handled = await v11.dispatch(this, name, args, { text, image });
+        if (handled !== undefined) return handled;
         throw new Error(`Unknown tool: ${name}`);
+      }
     }
   }
 
@@ -1114,7 +1242,8 @@ function jsonRpcError(id, code, message) {
 // ── Entry point (called from cli.js) ────────────────────────────────────────
 
 function runMcpServer(opts) {
-  const wsClient = new WorkspaceClient(opts.endpoint);
+  // Every tool call (incl. tools-v11 via server.ws) is made for opts.agentName.
+  const wsClient = new WorkspaceClient(opts.endpoint, { agentName: opts.agentName });
   const server = new McpServer({
     wsClient,
     workspaceId: opts.workspaceId,

package/src/node-config.js

@@ -98,7 +98,7 @@ function recordPairing(nodeKey, pairing) {
   const stamped = { ...pairing, paired_at: new Date().toISOString() };
   const pairings = [
     stamped,
-    ...pairingsOf(readNode()).filter((p) => p.workspace_id !== pairing.workspace_id),
+    ...pairingsOf(readNode()).filter((p) => pairing.node_id && p.node_id ? p.node_id !== pairing.node_id : p.workspace_id !== pairing.workspace_id),
   ];
   saveNode({ node_key: nodeKey, ...stamped, pairings });
 }
@@ -116,17 +116,19 @@ function recordPairing(nodeKey, pairing) {
  * @param workspaceId which pairing to drop; defaults to the top-level one.
  * @returns the pairing that was dropped, or null if there was no such pairing.
  */
-function clearPairing(workspaceId) {
+function clearPairing(workspaceId, nodeId) {
   const record = readNode();
   if (!record) return null;
   const target = workspaceId || record.workspace_id;
   if (!target) return null;
 
   const pairings = pairingsOf(record);
-  const dropped = pairings.find((p) => p.workspace_id === target);
+  const candidates = pairings.filter((p) => p.workspace_id === target);
+  if (!nodeId && candidates.length > 1) throw new Error("Choose a specific device connection");
+  const dropped = candidates.find((p) => !nodeId || p.node_id === nodeId);
   if (!dropped) return null;
 
-  const remaining = pairings.filter((p) => p.workspace_id !== target);
+  const remaining = pairings.filter((p) => p !== dropped);
   saveNode({ node_key: record.node_key, ...remaining[0], pairings: remaining });
   return {
     node_id: dropped.node_id,