leglas-mcp 0.3.0 → 0.4.0

package/README.md

@@ -14,6 +14,12 @@
   <a href="LICENSE"><img src="https://img.shields.io/npm/l/leglas" alt="license"></a>
 </p>
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/pr-assets/rail-single.jpg" width="900" alt="The Leglas interface: a rail of three design directions on the left, and the selected one running as the real app filling the rest of the window" />
+</p>
+
+<p align="center"><i>Every direction in the rail, the selected one running as your actual app. Arrow keys flip between them.</i></p>
+
 Code is becoming the source of truth. Features go from prompt to
 working code in minutes, and mockups/design files eventually lag behind the product and drift out of sync. The
 fastest teams already design in the medium they ship. Leglas is built
@@ -39,6 +45,12 @@ and sessions that clean up after themselves.
 
 ## What you can do with Leglas
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/pr-assets/compare-artboards.jpg" width="900" alt="The Leglas interface: a rail of three design directions on the left, and two of them running side by side as the real app, each labelled with its name." />
+</p>
+
+<p align="center"><i>Two directions for the same page, running side by side as the actual app.</i></p>
+
 - Pick any two variations for side-by-side comparison when it gets hard to choose.
 - Name each direction, drag to reorder and organise your variants, set aside the ones that
   don't feel right. Your actions on every idea survive a long exploration.
@@ -51,12 +63,23 @@ and sessions that clean up after themselves.
   the spread, your agent supplies the taste.
 - Ask for changes without leaving the comparison: describe what you
   want on the direction you're looking at, and Leglas turns it into a
-  precise request for your agent, file path included. Leave
-  `npx leglas watch --run "claude -p {prompt}"` running in another terminal
-  and your agent picks each request up as you send it. In Claude Code,
-  the Leglas MCP server can also push each request straight into your
-  open session as a channel event (channels are a research preview:
-  start Claude Code with `--dangerously-load-development-channels
+  precise request for your agent, file path included. The composer
+  carries its own agent picker, the way every chat you already use
+  carries a model picker: the CLIs found on your machine (Claude Code,
+  Codex, Cursor) are one click away next to the send button, each asked
+  for its login status so a signed-out CLI says so before a run instead
+  of failing one. Not on that list? Type the command that runs your
+  agent once, in the same menu, and Leglas hands it each request; or
+  connect an agent Leglas can't spawn (an IDE panel, an MCP host) with
+  the copy-paste MCP wiring behind "Connect another agent". Each run
+  reports in a card above the field: who is working, what file they
+  are touching, how long it has been, a stop button while it runs and
+  retry when it fails. Your agent, your subscription, no keys.
+  Prefer a terminal? `npx leglas watch` is the same loop with the
+  agent's own output scrolling by. In Claude Code, the Leglas MCP
+  server can also push each request straight into your open session as
+  a channel event (channels are a research preview: start Claude Code
+  with `--dangerously-load-development-channels
   server:<your leglas server name>`).
 - Keep the winner with one command. Leglas moves it into your source
   tree and clears the exploration away.
@@ -154,6 +177,23 @@ directly above the field. Your agent drains the queue with `npx leglas requests
 it with `--clear`. Leglas runs no model of its own; your agent already
 knows your conventions and your taste.
 
+The line under the field is the whole status: whether anything is
+listening, what you have queued, and when it has been picked up.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/pr-assets/field-idle.png" width="290" alt="The change field reading: Enter queues it for npx leglas requests" />
+  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/pr-assets/field-queued.png" width="290" alt="The change field reading: one change queued for your agent" />
+  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/pr-assets/field-pickedup.png" width="290" alt="The change field reading: Your agent is on it" />
+</p>
+
+<p align="center"><i>Nothing waiting, then a request queued, then an agent that has taken it.</i></p>
+
+Pick an agent once and the same line shows it working: which file it is
+editing, a cancel if you change your mind, a retry when a run goes
+wrong. `npx leglas watch` in another terminal is the same loop with the
+agent's own output in view, and it needs no flag once an agent has been
+picked in the interface.
+
 ### MCP server
 
 For agent hosts that cannot run shell commands, `leglas-mcp` exposes the
@@ -255,6 +295,15 @@ what you want for the last two directions in contention: press `C`, or
 hover a direction and press its compare button, and it becomes the right
 pane while the active direction holds the left.
 
+A split does not hand each side half the room. An app given half the room
+crosses its own breakpoints and draws a different design, so you would be
+choosing between two narrow renderings of directions meant for the wide
+one. Instead each side is drawn at the width it had on its own and scaled
+to fit, keeping the same proportions, so nothing reflows and flipping and
+splitting agree about what the design is. Each pane says the width it is
+drawn at and the scale it is shown at. If you want the narrow rendering,
+that is what the tools popover's "Scale each side to fit" switch is for.
+
 Arrows move between directions, `1` to `9` jump straight to one, `R` asks
 for a change to the one you are on, `Cmd K` (`Ctrl K` elsewhere) searches
 and `B` collapses the rail. Press `?` for the whole keymap.

package/dist/engagement.d.ts

@@ -0,0 +1,19 @@
+export type EngagementDeps = {
+    post?: (watching: boolean) => Promise<void>;
+    setInterval?: (callback: () => void, milliseconds: number) => unknown;
+    clearInterval?: (handle: unknown) => void;
+    now?: () => number;
+};
+export type Engagement = {
+    /**
+     * Note queue activity: starts the beat, or extends it. The returned
+     * promise settles once the server has had its chance to register the
+     * engagement; the caller awaits it before reading the queue, because the
+     * embedded runner backs off only after that registration lands. Watch
+     * closes the same handoff race the same way with its first heartbeat.
+     */
+    touch(): Promise<void>;
+    /** End the engagement and say so, as far as one best-effort post goes. */
+    stop(): Promise<void>;
+};
+export declare function createEngagement(deps?: EngagementDeps): Engagement;

package/dist/engagement.js

@@ -0,0 +1,68 @@
+import { DEFAULT_PORT, LEGLAS_PREFIX } from "leglas";
+/**
+ * Tell the Leglas server an agent is working the queue over MCP.
+ *
+ * The embedded runner yields to an attached watcher, and an MCP host driving
+ * the requests tool deserves the same right of way: without this, the runner
+ * could grab a request that arrives while the host's agent is mid-change in
+ * the same tree. Attachment is engagement, not connection: an MCP server sits
+ * connected to its host for hours doing nothing, so merely being alive proves
+ * nothing. Touch marks real queue activity, the beat keeps the server's
+ * window fresh, and a quiet spell lets it lapse.
+ */
+/** How often the server hears from an engaged session; matches watch. */
+const BEAT_MS = 2000;
+/** Queue work older than this no longer counts as engagement. */
+const ENGAGEMENT_MS = 120_000;
+/** A beat is worth a moment, never a stall. */
+const POST_TIMEOUT_MS = 1000;
+function defaultPost(watching) {
+    // Best effort at the default port: the queue is a file and every tool works
+    // without the server, so a beat that lands nowhere costs nothing. LEGLAS_PORT
+    // covers the server that had to bind elsewhere.
+    const port = Number(process.env.LEGLAS_PORT ?? "") || DEFAULT_PORT;
+    return fetch(`http://localhost:${port}${LEGLAS_PREFIX}/api/watch`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ watching }),
+        signal: AbortSignal.timeout(POST_TIMEOUT_MS),
+    }).then(() => { }, () => { });
+}
+export function createEngagement(deps = {}) {
+    const post = deps.post ?? defaultPost;
+    const setEvery = deps.setInterval ?? ((callback, milliseconds) => setInterval(callback, milliseconds));
+    const clearEvery = deps.clearInterval ?? ((handle) => clearInterval(handle));
+    const now = deps.now ?? (() => Date.now());
+    let timer = null;
+    let lastTouch = 0;
+    const quiet = () => {
+        if (timer === null)
+            return;
+        clearEvery(timer);
+        timer = null;
+    };
+    const beat = () => {
+        if (now() - lastTouch > ENGAGEMENT_MS) {
+            quiet();
+            void post(false);
+            return;
+        }
+        void post(true);
+    };
+    return {
+        touch() {
+            lastTouch = now();
+            // Mid-cycle the server already knows: nothing to wait for.
+            if (timer !== null)
+                return Promise.resolve();
+            timer = setEvery(beat, BEAT_MS);
+            return post(true).catch(() => { });
+        },
+        async stop() {
+            const wasBeating = timer !== null;
+            quiet();
+            if (wasBeating)
+                await post(false);
+        },
+    };
+}

package/dist/tools.d.ts

@@ -1,4 +1,5 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type Engagement } from "./engagement.js";
 import type { Project } from "./project.js";
 export type LeglasTools = {
     /** Stop anything the tools started. Wired to the transport's close. */
@@ -6,4 +7,5 @@ export type LeglasTools = {
 };
 export declare function registerLeglasTools(server: McpServer, options: {
     project: Project;
+    engagement?: Engagement;
 }): LeglasTools;

package/dist/tools.js

@@ -1,5 +1,6 @@
 import { run, runAdd, runClassify, runExplore, runInit, runKeep, runList, runNew, runRequests, runShow, } from "leglas";
 import { z } from "zod";
+import { createEngagement } from "./engagement.js";
 async function capture(invoke) {
     const lines = [];
     const deps = {
@@ -44,6 +45,9 @@ export function registerLeglasTools(server, options) {
     // One viewer per MCP process. The handle is held so a host that dies or
     // disconnects never leaves a dev server running on a port nobody remembers.
     let viewer = null;
+    // Working the queue over MCP counts as attachment, exactly like watch: the
+    // embedded runner must not race a host's agent for the same tree.
+    const engagement = options.engagement ?? createEngagement();
     server.registerTool("start", {
         title: "Start the Leglas viewer",
         description: "Boot the Leglas server for this project and return the interface URL. " +
@@ -166,7 +170,14 @@ export function registerLeglasTools(server, options) {
         inputSchema: {
             clear: z.boolean().optional(),
         },
-    }, async ({ clear }) => inProject(project, (cwd, deps) => runRequests({ json: true, clear: clear ?? false, cwd }, deps)));
+    }, async ({ clear }) => {
+        // Touched on every call, empty queue included: an agent that just asked
+        // is an agent about to act, and the beat lapses on its own once the
+        // asking stops. Awaited before the queue is read so the runner has
+        // backed off by the time this session could collect anything.
+        await engagement.touch();
+        return inProject(project, (cwd, deps) => runRequests({ json: true, clear: clear ?? false, cwd }, deps));
+    });
     server.registerTool("init", {
         title: "Prepare a project",
         description: "Write the AGENTS.md section, a starter config, and the gitignore entry into this project.",
@@ -178,6 +189,7 @@ export function registerLeglasTools(server, options) {
         shutdown: async () => {
             const running = viewer;
             viewer = null;
+            await engagement.stop().catch(() => { });
             await running?.stop().catch(() => { });
         },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "leglas-mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Stdio MCP server exposing Leglas to agent hosts that cannot run a shell.",
   "type": "module",
   "bin": {
@@ -15,7 +15,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^3.25.76",
-    "leglas": "^0.3.0"
+    "leglas": "^0.4.0"
   },
   "license": "MIT",
   "repository": {