npm - conductor-remote - Versions diffs - 1.80.0 → 1.82.0 - Mend

conductor-remote 1.80.0 → 1.82.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

package/README.md +22 -9
package/dist/assets/index-CJakNa4V.css +1 -0
package/dist/assets/index-CZWaZeNN.js +47 -0
package/dist/index.html +2 -2
package/dist/sw.js +1 -1
package/dist-node/src/dev-server.js +184 -62
package/dist-node/src/mcp-tools.js +21 -1
package/dist-node/src/plan-usage.js +430 -0
package/dist-node/src/preview-urls.js +283 -0
package/dist-node/src/reads.js +19 -12
package/dist-node/src/routes.js +2 -0
package/dist-node/src/server.js +22 -6
package/package.json +1 -1
package/dist/assets/index-DaafT1eA.css +0 -1
package/dist/assets/index-ILQ9q-V7.js +0 -47

package/dist/index.html CHANGED Viewed

@@ -13,8 +13,8 @@
 		<title>Conductor Remote</title>
 		<!-- Runs before the module bundle so it can catch a stale shell that fails to boot. -->
 		<script src="/self-heal.js"></script>
-		<script type="module" crossorigin src="/assets/index-ILQ9q-V7.js"></script>
-		<link rel="stylesheet" crossorigin href="/assets/index-DaafT1eA.css">
+		<script type="module" crossorigin src="/assets/index-CZWaZeNN.js"></script>
+		<link rel="stylesheet" crossorigin href="/assets/index-CJakNa4V.css">
 	<link rel="manifest" href="/manifest.webmanifest"></head>
 	<body>
 		<div id="root"></div>

package/dist/sw.js CHANGED Viewed

	@@ -1 +1 @@
1	- if(!self.define){let e,s={};const i=(i,n)=>(i=new URL(i+".js",n).href,s[i]\|\|new Promise(s=>{if("document"in self){const e=document.createElement("script");e.src=i,e.onload=s,document.head.appendChild(e)}else e=i,importScripts(i),s()}).then(()=>{let e=s[i];if(!e)throw new Error(`Module ${i} didn’t register its module`);return e}));self.define=(n,r)=>{const o=e\|\|("document"in self?document.currentScript.src:"")\|\|location.href;if(s[o])return;let l={};const c=e=>i(e,o),t={module:{uri:o},exports:l,require:c};s[o]=Promise.all(n.map(e=>t[e]\|\|c(e))).then(e=>(r(...e),l))}}define(["./workbox-9c191d2f"],function(e){"use strict";importScripts("/push-sw.js"),self.addEventListener("message",e=>{e.data&&"SKIP_WAITING"===e.data.type&&self.skipWaiting()}),e.clientsClaim(),e.precacheAndRoute([{url:"self-heal.js",revision:"49bd63adb25a09341f8d2610e8bd3c76"},{url:"push-sw.js",revision:"e7ef44deca46c0539e6ff7bba5eb815e"},{url:"index.html",revision:"~~4fa6b9e7cf25227330786aa264ae4ce6~~"},{url:"assets/workbox-window.prod.es5-BBnX5xw4.js",revision:null},{url:"assets/index-~~ILQ9q-V7~~.js",revision:null},{url:"assets/index-~~DaafT1eA~~.css",revision:null},{url:"apple-touch-icon.png",revision:"1127bb396b4648add53dce3f22c92aee"},{url:"icon-192.png",revision:"c5e01ac58768627e18ee7b8b6a9239ef"},{url:"icon-512.png",revision:"a40638c55e310312457a621c9a0002c8"},{url:"icon-maskable-512.png",revision:"a9b0d962686287452216492cd2247499"},{url:"icon.svg",revision:"c1aee186821798733dd477e69a0ef243"},{url:"manifest.webmanifest",revision:"cf88fbc5755108a7fe0616fa160a8a15"}],{}),e.cleanupOutdatedCaches(),e.registerRoute(new e.NavigationRoute(e.createHandlerBoundToURL("/index.html"),{denylist:[/^\/api\//]}))});
1	+ if(!self.define){let e,s={};const i=(i,n)=>(i=new URL(i+".js",n).href,s[i]\|\|new Promise(s=>{if("document"in self){const e=document.createElement("script");e.src=i,e.onload=s,document.head.appendChild(e)}else e=i,importScripts(i),s()}).then(()=>{let e=s[i];if(!e)throw new Error(`Module ${i} didn’t register its module`);return e}));self.define=(n,r)=>{const o=e\|\|("document"in self?document.currentScript.src:"")\|\|location.href;if(s[o])return;let l={};const t=e=>i(e,o),c={module:{uri:o},exports:l,require:t};s[o]=Promise.all(n.map(e=>c[e]\|\|t(e))).then(e=>(r(...e),l))}}define(["./workbox-9c191d2f"],function(e){"use strict";importScripts("/push-sw.js"),self.addEventListener("message",e=>{e.data&&"SKIP_WAITING"===e.data.type&&self.skipWaiting()}),e.clientsClaim(),e.precacheAndRoute([{url:"self-heal.js",revision:"49bd63adb25a09341f8d2610e8bd3c76"},{url:"push-sw.js",revision:"e7ef44deca46c0539e6ff7bba5eb815e"},{url:"index.html",revision:"92fe37786069a3859a13db5d5d63f6e3"},{url:"assets/workbox-window.prod.es5-BBnX5xw4.js",revision:null},{url:"assets/index-CZWaZeNN.js",revision:null},{url:"assets/index-CJakNa4V.css",revision:null},{url:"apple-touch-icon.png",revision:"1127bb396b4648add53dce3f22c92aee"},{url:"icon-192.png",revision:"c5e01ac58768627e18ee7b8b6a9239ef"},{url:"icon-512.png",revision:"a40638c55e310312457a621c9a0002c8"},{url:"icon-maskable-512.png",revision:"a9b0d962686287452216492cd2247499"},{url:"icon.svg",revision:"c1aee186821798733dd477e69a0ef243"},{url:"manifest.webmanifest",revision:"cf88fbc5755108a7fe0616fa160a8a15"}],{}),e.cleanupOutdatedCaches(),e.registerRoute(new e.NavigationRoute(e.createHandlerBoundToURL("/index.html"),{denylist:[/^\/api\//]}))});

package/dist-node/src/dev-server.js CHANGED Viewed

@@ -5,8 +5,10 @@
  * The relay never spawns a repository command itself. Starting and stopping go
  * through Conductor's real Run button (`writes.ts`), which preserves its task
  * selection, environment, run-mode rules and process-group cleanup. This module
- * discovers that workspace's allocated `CONDUCTOR_PORT`, waits for it, and gives
- * it a root-mounted HTTPS origin on the Mac's MagicDNS name.
+ * discovers that workspace's allocated `CONDUCTOR_PORT`, expands Conductor's
+ * configured `preview_urls`, and gives each local preview a tailnet HTTPS origin
+ * on the Mac's MagicDNS name. Conductor's detected Open-button ports remain the
+ * fallback for repositories that do not declare previews.
  *
  * Tailscale's reverse proxy preserves the public Host header. Dev servers such
  * as Vite reject that by default, so a tiny loopback bridge rewrites Host/Origin
@@ -22,12 +24,18 @@ import net from 'node:net';
 import path from 'node:path';
 import { promisify } from 'node:util';
 import { stateDir } from "./config.js";
+import { previewUrlSettings, resolvePreviewTargets } from "./preview-urls.js";
 import { magicDnsName, tailscaleBin } from "./tailscale.js";
 import { setRunTask } from "./writes.js";
 const exec = promisify(execFile);
+// Keep the receipt additive and version-1-readable: an installed relay and a
+// source `yarn dev` relay can briefly share this file during an update.
 const STORE_VERSION = 1;
 const PORT_WAIT_MS = 15_000;
 const PORT_SNAPSHOT_TTL_MS = 5000;
+function recordKey(workspaceId, targetPort) {
+    return `${workspaceId}:${targetPort}`;
+}
 function validPort(value) {
     return Number.isInteger(value) && value > 0 && value <= 65535;
 }
@@ -287,21 +295,21 @@ function servePorts(status) {
         .map(Number)
         .filter(validPort));
 }
-function chooseServePort(status, targetPort) {
+function chooseServePort(status, targetPort, reserved = new Set()) {
     const used = servePorts(status);
     for (let offset = 0; offset < 10; offset++) {
         const candidate = targetPort + offset;
-        if (validPort(candidate) && !used.has(candidate))
+        if (validPort(candidate) && !used.has(candidate) && !reserved.has(candidate))
             return candidate;
     }
     for (let candidate = 49152; candidate <= 65535; candidate++) {
-        if (!used.has(candidate))
+        if (!used.has(candidate) && !reserved.has(candidate))
             return candidate;
     }
     return null;
 }
-function forwardUrl(record) {
-    return `https://${record.host}${record.servePort === 443 ? '' : `:${record.servePort}`}/`;
+function forwardUrl(record, previewPath = record.path || '/') {
+    return `https://${record.host}${record.servePort === 443 ? '' : `:${record.servePort}`}${previewPath}`;
 }
 export class DevServerController {
     storeFile;
@@ -329,12 +337,15 @@ export class DevServerController {
                 return;
             for (const record of parsed.forwards) {
                 if (record.workspaceId &&
+                    (record.basePort === undefined || record.basePort === null || validPort(record.basePort)) &&
                     validPort(record.targetPort) &&
                     validPort(record.servePort) &&
                     validPort(record.bridgePort) &&
                     typeof record.host === 'string' &&
                     record.host.length > 0) {
-                    this.records.set(record.workspaceId, record);
+                    if (record.basePort === undefined)
+                        record.basePort = record.targetPort;
+                    this.records.set(recordKey(record.workspaceId, record.targetPort), record);
                 }
             }
         }
@@ -360,7 +371,31 @@ export class DevServerController {
         const discovered = await workspacePort(workspaceId, PORT_SNAPSHOT_TTL_MS);
         if (discovered)
             this.ports.set(workspaceId, discovered);
-        return discovered;
+        if (discovered)
+            return discovered;
+        for (const record of this.records.values()) {
+            if (record.workspaceId === workspaceId && record.basePort)
+                return record.basePort;
+        }
+        return null;
+    }
+    targetsFor(workspace, basePort, detectedPorts = []) {
+        const configured = resolvePreviewTargets(previewUrlSettings(workspace), basePort);
+        if (configured.length)
+            return configured;
+        const ports = [...new Set(detectedPorts.filter(validPort))];
+        if (!ports.length && basePort)
+            ports.push(basePort);
+        if (!ports.length) {
+            for (const record of this.records.values()) {
+                if (record.workspaceId === workspace.id)
+                    ports.push(record.targetPort);
+            }
+        }
+        return ports.slice(0, 10).map(port => {
+            const record = this.records.get(recordKey(workspace.id, port));
+            return { name: record?.name || `Port ${port}`, port, path: record?.path || '/' };
+        });
     }
     async serveStatus() {
         if (!this.bin)
@@ -399,9 +434,9 @@ export class DevServerController {
             throw new Error(`could not remove the Tailscale Serve mapping on :${record.servePort}`);
         }
     }
-    async release(workspaceId) {
-        const record = this.records.get(workspaceId);
-        const proxy = this.proxies.get(workspaceId);
+    async releaseRecord(key) {
+        const record = this.records.get(key);
+        const proxy = this.proxies.get(key);
         let cleanupError;
         if (record) {
             try {
@@ -415,30 +450,51 @@ export class DevServerController {
         // its stale HTTPS mapping cannot reach a later process that reuses the port.
         if (proxy)
             await proxy.close();
-        this.proxies.delete(workspaceId);
+        this.proxies.delete(key);
         if (!cleanupError)
-            this.records.delete(workspaceId);
+            this.records.delete(key);
         this.save();
         if (cleanupError)
             throw cleanupError;
     }
-    async forward(workspaceId, targetPort) {
-        const existing = this.records.get(workspaceId);
-        if (existing?.targetPort === targetPort) {
+    async release(workspaceId) {
+        let firstError;
+        for (const [key, record] of [...this.records]) {
+            if (record.workspaceId !== workspaceId)
+                continue;
+            try {
+                await this.releaseRecord(key);
+            }
+            catch (err) {
+                firstError ??= err;
+            }
+        }
+        if (firstError)
+            throw firstError;
+    }
+    async forward(workspaceId, basePort, target, reservedPorts) {
+        const key = recordKey(workspaceId, target.port);
+        const existing = this.records.get(key);
+        if (existing) {
             const status = await this.serveStatus();
             const expected = `http://127.0.0.1:${existing.bridgePort}`;
-            if (serveProxyAt(status, existing.servePort) === expected && (await bridgeMatches(existing)))
+            if (serveProxyAt(status, existing.servePort) === expected && (await bridgeMatches(existing))) {
+                existing.basePort = basePort ?? existing.basePort;
+                existing.name = target.name;
+                existing.path = target.path;
+                this.save();
                 return existing;
+            }
         }
         if (existing)
-            await this.release(workspaceId);
+            await this.releaseRecord(key);
         if (!this.bin || !this.host)
             throw new Error('Tailscale is not connected on this Mac');
         const status = await this.serveStatus();
-        const servePort = chooseServePort(status, targetPort);
+        const servePort = chooseServePort(status, target.port, reservedPorts);
         if (!servePort)
             throw new Error('no free Tailscale Serve port is available');
-        const proxy = await createDevProxy(targetPort);
+        const proxy = await createDevProxy(target.port);
         try {
             await this.setServe(servePort, proxy.port);
         }
@@ -463,18 +519,37 @@ export class DevServerController {
         }
         const record = {
             workspaceId,
-            targetPort,
+            basePort,
+            targetPort: target.port,
             servePort,
             bridgePort: proxy.port,
             host: this.host,
+            name: target.name,
+            path: target.path,
             ownerPid: process.pid,
             bridgeToken: proxy.token
         };
-        this.proxies.set(workspaceId, proxy);
-        this.records.set(workspaceId, record);
+        this.proxies.set(key, proxy);
+        this.records.set(key, record);
         this.save();
         return record;
     }
+    async forwardAll(workspaceId, basePort, targets) {
+        const byPort = new Map();
+        for (const target of targets)
+            if (!byPort.has(target.port))
+                byPort.set(target.port, target);
+        const wanted = new Set([...byPort].map(([port]) => recordKey(workspaceId, port)));
+        for (const [key, record] of [...this.records]) {
+            if (record.workspaceId === workspaceId && !wanted.has(key))
+                await this.releaseRecord(key);
+        }
+        const naturalPorts = new Set(byPort.keys());
+        for (const target of byPort.values()) {
+            const reserved = new Set([...naturalPorts].filter(port => port !== target.port));
+            await this.forward(workspaceId, basePort, target, reserved);
+        }
+    }
     /** Rebuild loopback bridges after launchd or the self-updater restarts the relay. */
     async restore() {
         this.refreshTailscale();
@@ -482,9 +557,10 @@ export class DevServerController {
         // that case; a later tap can safely replace or remove their exact mappings.
         if (!this.bin || !this.host)
             return;
-        for (const record of [...this.records.values()]) {
+        for (const [key, record] of [...this.records]) {
             try {
-                this.ports.set(record.workspaceId, record.targetPort);
+                if (record.basePort)
+                    this.ports.set(record.workspaceId, record.basePort);
                 // `yarn dev` runs another relay beside the installed LaunchAgent. A
                 // node --watch restart must not steal the installed relay's live bridge
                 // merely because both instances share the same state directory.
@@ -493,11 +569,11 @@ export class DevServerController {
                 const status = await this.serveStatus();
                 const owned = serveProxyAt(status, record.servePort) === `http://127.0.0.1:${record.bridgePort}`;
                 if (!owned) {
-                    this.records.delete(record.workspaceId);
+                    this.records.delete(key);
                     continue;
                 }
                 if (!(await tcpOpen(record.targetPort))) {
-                    await this.release(record.workspaceId);
+                    await this.releaseRecord(key);
                     continue;
                 }
                 const proxy = await createDevProxy(record.targetPort);
@@ -505,8 +581,8 @@ export class DevServerController {
                 record.bridgePort = proxy.port;
                 record.ownerPid = process.pid;
                 record.bridgeToken = proxy.token;
-                this.proxies.set(record.workspaceId, proxy);
-                this.records.set(record.workspaceId, record);
+                this.proxies.set(key, proxy);
+                this.records.set(key, record);
             }
             catch (err) {
                 console.warn(`⚠ could not restore dev-server forward for ${record.workspaceId} (${err instanceof Error ? err.message : err})`);
@@ -516,32 +592,67 @@ export class DevServerController {
     }
     async state(workspace) {
         this.refreshTailscale();
-        const record = this.records.get(workspace.id);
-        const port = (await this.portFor(workspace.id)) ?? record?.targetPort ?? null;
-        if (port)
-            this.ports.set(workspace.id, port);
-        const running = port ? await tcpOpen(port) : false;
-        let forwarded = false;
-        if (running && record) {
-            try {
-                const status = await this.serveStatus();
-                forwarded =
-                    serveProxyAt(status, record.servePort) === `http://127.0.0.1:${record.bridgePort}` &&
-                        (await bridgeMatches(record));
+        const basePort = await this.portFor(workspace.id);
+        if (basePort)
+            this.ports.set(workspace.id, basePort);
+        const targets = this.targetsFor(workspace, basePort);
+        const targetPorts = new Set(targets.map(target => target.port));
+        // Keep a configured URL list authoritative, but don't hide a still-owned
+        // forward after the file changes; it must remain visible until Start
+        // reconciles it or Stop removes it.
+        for (const record of this.records.values()) {
+            if (record.workspaceId !== workspace.id || targetPorts.has(record.targetPort))
+                continue;
+            targets.push({
+                name: record.name || `Port ${record.targetPort}`,
+                port: record.targetPort,
+                path: record.path || '/'
+            });
+            targetPorts.add(record.targetPort);
+        }
+        let status = null;
+        try {
+            if (targets.some(target => this.records.has(recordKey(workspace.id, target.port))))
+                status = await this.serveStatus();
+        }
+        catch {
+            // A disconnected CLI makes every URL unverified, never optimistically live.
+        }
+        const openByPort = new Map();
+        const ownedByPort = new Map();
+        const forwards = await Promise.all(targets.map(async (target) => {
+            let open = openByPort.get(target.port);
+            if (!open) {
+                open = tcpOpen(target.port);
+                openByPort.set(target.port, open);
             }
-            catch {
-                // A disconnected CLI makes the URL unverified, never optimistically live.
+            const record = this.records.get(recordKey(workspace.id, target.port));
+            let owned = ownedByPort.get(target.port);
+            if (!owned) {
+                owned = Promise.resolve(Boolean(status && record && serveProxyAt(status, record.servePort) === `http://127.0.0.1:${record.bridgePort}`)).then(matches => (matches && record ? bridgeMatches(record) : false));
+                ownedByPort.set(target.port, owned);
             }
-        }
+            const [targetRunning, targetForwarded] = await Promise.all([open, owned]);
+            return {
+                name: target.name,
+                port: target.port,
+                running: targetRunning,
+                forwarded: targetForwarded,
+                url: targetForwarded && record ? forwardUrl(record, target.path) : null
+            };
+        }));
+        const primary = forwards[0];
+        const firstForwarded = forwards.find(forward => forward.forwarded && forward.url);
         let error;
         if (!this.bin || !this.host)
             error = 'Tailscale is not connected on this Mac';
         return {
             available: !!this.bin && !!this.host,
-            running,
-            forwarded,
-            port,
-            url: forwarded && record ? forwardUrl(record) : null,
+            running: primary?.running ?? false,
+            forwarded: Boolean(firstForwarded),
+            port: primary?.port ?? basePort,
+            url: firstForwarded?.url ?? null,
+            forwards,
             error
         };
     }
@@ -577,15 +688,17 @@ export class DevServerController {
                     error: 'Tailscale Serve is not available on this Mac'
                 };
             }
-            let port = await this.portFor(workspace.id);
+            let basePort = await this.portFor(workspace.id);
+            let targets = this.targetsFor(workspace, basePort);
+            let primaryPort = targets[0]?.port ?? null;
             // A task already listening needs no button. Forwarding it touches only
             // Tailscale and this relay, so it costs about a second, steals no focus
             // from the Mac, and stays inside the tap activation a phone can open a
             // tab with. Pressing Run here would also assert a pane for a press it
             // then decides not to make.
-            if (port && (await tcpOpen(port))) {
+            if (primaryPort && (await tcpOpen(primaryPort))) {
                 try {
-                    await this.forward(workspace.id, port);
+                    await this.forwardAll(workspace.id, basePort, targets);
                     return { ok: true, ...(await this.state(workspace)), changed: false };
                 }
                 catch (err) {
@@ -600,12 +713,14 @@ export class DevServerController {
             const run = await setRunTask(workspace, true);
             if (!run.ok)
                 return { ok: false, ...(await this.state(workspace)), error: run.error };
-            port ??= run.ports?.[0] ?? null;
-            if (!port)
-                port = await workspacePort(workspace.id);
-            if (port)
-                this.ports.set(workspace.id, port);
-            if (!port) {
+            basePort ??= await workspacePort(workspace.id);
+            if (basePort)
+                this.ports.set(workspace.id, basePort);
+            // Configured previews win. Conductor's expanded Open buttons are the
+            // compatibility path for repositories that have not declared them yet.
+            targets = this.targetsFor(workspace, basePort, run.ports);
+            primaryPort = targets[0]?.port ?? null;
+            if (!primaryPort) {
                 const rollback = run.changed ? await setRunTask(workspace, false) : null;
                 const suffix = rollback
                     ? rollback.ok
@@ -617,10 +732,10 @@ export class DevServerController {
                     ...(await this.state(workspace)),
                     task: run.task,
                     changed: run.changed,
-                    error: `Conductor started the task, but its CONDUCTOR_PORT wasn’t visible${suffix}`
+                    error: `Conductor started the task, but no configured or detected preview port was visible${suffix}`
                 };
             }
-            if (!(await waitForPort(port, true, PORT_WAIT_MS))) {
+            if (!(await waitForPort(primaryPort, true, PORT_WAIT_MS))) {
                 const rollback = run.changed ? await setRunTask(workspace, false) : null;
                 const suffix = rollback
                     ? rollback.ok
@@ -632,14 +747,21 @@ export class DevServerController {
                     ...(await this.state(workspace)),
                     task: run.task,
                     changed: run.changed,
-                    error: `${run.task ?? 'Run task'} started, but nothing listened on :${port}${suffix}`
+                    error: `${run.task ?? 'Run task'} started, but nothing listened on :${primaryPort}${suffix}`
                 };
             }
             try {
-                await this.forward(workspace.id, port);
+                await this.forwardAll(workspace.id, basePort, targets);
                 return { ok: true, ...(await this.state(workspace)), task: run.task, changed: run.changed };
             }
             catch (err) {
+                try {
+                    await this.release(workspace.id);
+                }
+                catch {
+                    // The original forwarding failure remains the actionable error. Any
+                    // receipt cleanup failure stays persisted for the next relay start.
+                }
                 const rollback = run.changed ? await setRunTask(workspace, false) : null;
                 const suffix = rollback
                     ? rollback.ok

package/dist-node/src/mcp-tools.js CHANGED Viewed

@@ -31,7 +31,7 @@ import { HIT_CLOSE, HIT_OPEN, isToolResult, timestampMs, workspaceTitle } from "
 /** Versions we know how to speak. The client's choice wins when we know it. */
 export const PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'];
 export const SERVER_INFO = { name: 'conductor-remote', version: '1' };
-export const INSTRUCTIONS = 'Drives local Conductor agents through the conductor-remote relay. search_chats and read_chat reach archived workspaces, which is where most finished work lives. create_workspace opens its workspace link without direct UI control; requested agent settings and the first prompt are applied later through Conductor’s UI. dismiss_prompt, keep_awake and relay_logs touch no UI. send_prompt, split_chat, stop_turn, set_agent_options, set_default_model, a live list_models call, set_workspace_status and archive_workspace drive the real Mac UI and steal focus for a few seconds — confirm with the user before using them on a chat they did not name. archive_workspace also deletes the worktree and stops whatever is running there.';
+export const INSTRUCTIONS = 'Drives local Conductor agents through the conductor-remote relay. search_chats and read_chat reach archived workspaces, which is where most finished work lives. create_workspace opens its workspace link without direct UI control; requested agent settings and the first prompt are applied later through Conductor’s UI. plan_usage, dismiss_prompt, keep_awake and relay_logs touch no UI. send_prompt, split_chat, stop_turn, set_agent_options, set_default_model, a live list_models call, set_workspace_status and archive_workspace drive the real Mac UI and steal focus for a few seconds — confirm with the user before using them on a chat they did not name. archive_workspace also deletes the worktree and stops whatever is running there.';
 /** Reads are quick; a UI write is measured in tens of seconds (writes.ts ▸ SEND_ATTEMPT_MS). */
 export const READ_TIMEOUT_MS = 10_000;
 export const WRITE_TIMEOUT_MS = 75_000;
@@ -359,6 +359,26 @@ export function createTools(call) {
                 return data.repos.map(r => `${r.name}  (${r.default_branch ?? '?'})  ${r.root_path ?? ''}`).join('\n');
             }
         },
+        {
+            name: 'plan_usage',
+            description: 'Read rolling Claude Code and Codex subscription allowances from their local CLIs: percentage used and reset time. Sends no model prompt and touches no Conductor UI. Cursor Agent and OpenCode explain why no comparable plan quota is available.',
+            inputSchema: { type: 'object', properties: {} },
+            run: async () => {
+                const data = await call(routes.planUsage.path(), { timeoutMs: 15_000 });
+                const sections = data.providers.map(provider => {
+                    const head = `## ${provider.label}${provider.plan ? ` · ${provider.plan}` : ''}`;
+                    if (provider.status !== 'available')
+                        return `${head}\n${provider.message ?? 'unavailable'}`;
+                    const lines = provider.buckets.flatMap(bucket => bucket.windows.map(window => {
+                        const bucketName = provider.buckets.length > 1 ? `${bucket.label} — ` : '';
+                        const reset = window.resetsAt === null ? 'reset unavailable' : `resets ${new Date(window.resetsAt).toISOString()}`;
+                        return `- ${bucketName}${window.label}: ${Math.round(window.usedPercent)}% used · ${reset}`;
+                    }));
+                    return `${head}\n${lines.join('\n')}`;
+                });
+                return `${sections.join('\n\n')}\n\nupdated ${new Date(data.fetchedAt).toISOString()}`;
+            }
+        },
         {
             name: 'create_workspace',
             description: 'Start a new Conductor workspace in a repo, optionally with a first prompt and agent settings. The workspace starts from a Conductor deep link, so creation itself needs no Accessibility. The relay applies requested model, effort, plan, and fast settings through Conductor’s UI after it creates the first chat and before it delivers the prompt. Returns as soon as the workspace row exists (~2s), before the worktree is built.',