@evref-bl/pharo-agent 0.10.2 → 0.12.0

package/src/init.js

@@ -120,7 +120,7 @@ outside generated/copied files and outside the host guide's managed block.
 Refreshing project files does not install a newer package or upgrade image tools.
 
 \`plexus.json\` declares this project's images. A freshly initialized
-project declares none; register one before the first \`pharo-agent open\`:
+project declares none; register one before the first \`pharo-agent image start\`:
 
 \`\`\`sh
 pharo-agent image templates
@@ -131,16 +131,22 @@ pharo-agent image add dev --template '<launcher template name>'
 \`image templates\` names the templates the launcher offers, with the category
 of each; a name two categories offer also needs \`--category <name>\`. Any
 version the launcher offers can be registered, and one outside the MCP range
-opens without MCP tools or a source projection, saying so.
+starts without MCP tools or a source projection, saying so.
 
 \`image add\` makes the first registered image the default. \`pharo-agent image
 use <id>\` changes the default, and \`pharo-agent image remove <id>\` drops a
-declaration. Close an image before removing its declaration.
+declaration. Stop an image before removing its declaration.
 
-Use \`pharo-agent open\` before live-image work and edit projected source under
-\`.pharo-agent/mounts\`. Call a tool with
-\`pharo-agent pharo <tool> [arguments-json]\`, and \`pharo-agent mcp\` exposes the
-image as a command-scoped stdio MCP server.
+Use \`pharo-agent image start\` before live-image work. On macOS with fuse-t
+installed the image's source is also projected under \`.pharo-agent/mounts\`
+and can be edited as files; everywhere else the Pharo tools are the way in,
+and \`image start\` says so.
+
+With the pharo-agent plugin enabled for this project, the image's tools are MCP
+tools: start an image with \`image_start\` and call the rest by name. Without it,
+call a tool with \`pharo-agent pharo <tool> [arguments-json]\`, and
+\`pharo-agent mcp\` serves the same surface as a command-scoped stdio MCP
+server.
 
 \`pharo-agent pharo list\` names the tools the image advertises, which are the
 common ones rather than all of it. Find the rest through the catalogue rather
@@ -152,11 +158,11 @@ pharo-agent pharo tool_get '{"name":"repository_commit"}'
 pharo-agent pharo repository_commit '{"name":"MCP","message":"..."}'
 \`\`\`
 
-Several images can be open at once. Every image-facing command takes
-\`--image <id>\`; without it the default image answers. \`pharo-agent open
---image <id>\` opens another image without closing the first,
-\`pharo-agent status\` lists what is open, and \`pharo-agent close\` closes
-everything this project opened.
+Several images can run at once. \`pharo-agent image start <id>\` and
+\`pharo-agent image stop <id>\` name their image, \`pharo\` and \`mcp\` take
+\`--image <id>\`, and without either the default image answers.
+\`pharo-agent image list\` says which are running, and
+\`pharo-agent image stop --all\` stops every one this project started.
 
 Image, Tonel, Iceberg, disk Git, and host processes are separate states.
 

package/src/live.js

@@ -9,22 +9,63 @@ import {
   stopProjectImage,
 } from "@evref-bl/plexus";
 import { callImageTool } from "./gateway.js";
-import { readProjectConfig, writeProjectConfig } from "./project.js";
+import { readProjectConfig } from "./project.js";
 import {
-  defaultImageId,
-  openedImageIsAlive,
   readConfig,
-  readOpenImages,
+  readRunningImages,
+  recordedImageIsRunning,
   resolveImageId,
   resolveMountPath,
   selectRunningImage,
   smalltalkString,
   unappliedPharoMcpPin,
-  writeOpenImages,
+  writeRunningImages,
 } from "./runtime.js";
 
 export const pifsRelease = "v0.9.2";
 
+// fuse-t ships as a macOS installer package, so it lands in /usr/local
+// whatever Homebrew's prefix is. The unversioned symlink is what the daemon
+// links against.
+export const fuseLibraryPath = "/usr/local/lib/libfuse-t.dylib";
+
+/**
+ * Whether a source projection can be mounted here.
+ *
+ * PIFS needs macOS and fuse-t, which is a kernel-adjacent install the user
+ * has to approve. PLexus and the Pharo MCP run anywhere, so until this was
+ * checked, `image start` mounted unconditionally and then stopped the image
+ * when the mount failed -- every image on Linux and Windows, and on any Mac
+ * without fuse-t. The image and its tools were never the part that could not
+ * work.
+ *
+ * @param {{ platform?: string, exists?: (path: string) => boolean }} [host]
+ */
+export function projectionAvailability(host = {}) {
+  const platform = host.platform ?? process.platform;
+  const exists = host.exists ?? fs.existsSync;
+  if (platform !== "darwin") {
+    return {
+      available: false,
+      reason: "A source projection needs macOS and fuse-t, which this platform"
+        + ` (${platform}) cannot provide.`,
+    };
+  }
+  if (!exists(fuseLibraryPath)) {
+    return {
+      available: false,
+      reason: "A source projection needs fuse-t, which is not installed."
+        + " Install it with `brew install --cask fuse-t`.",
+    };
+  }
+  return { available: true };
+}
+
+export function projectionUnavailableWarning(imageId, reason) {
+  return `${reason} Image ${imageId} is running with its Pharo tools and no`
+    + " source projection; read and edit its code through the tools.";
+}
+
 // The class-side PIFSServer messages this plugin sends into the image. The
 // release automation checks that a published PIFS still implements them: a pin
 // bump that leaves a removed selector in place passes every test here, because
@@ -85,62 +126,28 @@ export function resultPrintString(result) {
   return namedPrintString(result) ?? textPartText(result);
 }
 
+/**
+ * The status is spelled out rather than taken as a string: this read branched
+ * for a long time on "declared" and "failed", which PLexus does not report,
+ * so a declared image was never created and the launch that followed failed
+ * on an image that was not there. Naming the four it does report makes the
+ * typecheck reject a fifth.
+ *
+ * @param {{ images: { imageId: string,
+ *   status: "absent" | "stopped" | "starting" | "running" }[] }} listed
+ * @param {string} imageId
+ */
 export function imageCreationPlan(listed, imageId) {
   const summary = listed.images.find((image) => image.imageId === imageId);
   if (!summary) {
     throw new Error(`PLexus does not know image ${imageId}.`);
   }
-  // PLexus reports an image it has no runtime state for as declared.
-  if (summary.status === "declared") return "create";
-  // A creation that failed leaves runtime state that blocks both a retry and a
-  // fresh declaration of the same id, so the id would be spent for good. Clear
-  // it and create again.
-  if (summary.status === "failed") return "reset";
+  // "absent" is PLexus's word for no image file on disk, which is what a
+  // declared image looks like until something creates it.
+  if (summary.status === "absent") return "create";
   return "none";
 }
 
-// The launcher resolves a template name against its default group only, so an
-// image naming a template from any other group cannot be created until the
-// project config says which group that is. Find it once, on first creation.
-export async function resolveTemplateCategory(projectRoot, launcher, imageId) {
-  const config = readProjectConfig(projectRoot);
-  const images = Array.isArray(config.images) ? config.images : [];
-  const configured = images.find((image) => image.id === imageId);
-  const create = configured?.create;
-  if (!create?.templateName || create.templateCategory) {
-    return create?.templateCategory;
-  }
-
-  const listed = await launcher.listTemplates();
-  const templates = Array.isArray(listed?.templates) ? listed.templates : [];
-  const categories = [
-    ...new Set(
-      templates
-        .filter((template) => template?.name === create.templateName)
-        .map((template) => template?.templateCategory)
-        .filter(Boolean),
-    ),
-  ];
-  if (categories.length === 0) {
-    throw new Error(`No template named ${create.templateName} in any category.`);
-  }
-  if (categories.length > 1) {
-    throw new Error(
-      `Template ${create.templateName} exists in several categories: ${categories.join(", ")}.`
-      + ` Set create.templateCategory for image ${imageId} to choose one.`,
-    );
-  }
-
-  const [templateCategory] = categories;
-  writeProjectConfig(projectRoot, {
-    ...config,
-    images: images.map((image) => (image.id === imageId
-      ? { ...image, create: { ...image.create, templateCategory } }
-      : image)),
-  });
-  return templateCategory;
-}
-
 export function describeLifecycleFailure(failure) {
   const stderr = failure.launcherResult?.raw?.stderr?.trim();
   return [
@@ -185,71 +192,89 @@ export function fetchPifsRelease(cloneDirectory, release = pifsRelease) {
   return git("fetch", "--tags", "--quiet", "origin");
 }
 
-export async function openAgentImage(projectRoot, imageId) {
+export async function startAgentImage(projectRoot, imageId) {
   const resolved = resolveImageId(projectRoot, imageId);
-  let openImages = readOpenImages(projectRoot);
+  let runningImages = readRunningImages(projectRoot);
   let restarted = false;
-  if (openImages[resolved]) {
-    if (openedImageIsAlive(openImages[resolved])) {
-      return { alreadyOpen: true, ...openImages[resolved] };
+  if (runningImages[resolved]) {
+    if (recordedImageIsRunning(runningImages[resolved])) {
+      return { alreadyRunning: true, ...runningImages[resolved] };
     }
-    // The image this record names has exited. Forget it and open again,
-    // rather than hand back an endpoint nothing answers and say it is open.
-    const { [resolved]: exited, ...remaining } = openImages;
-    openImages = remaining;
-    writeOpenImages(projectRoot, openImages);
+    // The image this record names has exited. Forget it and start again,
+    // rather than hand back an endpoint nothing answers and call it running.
+    const { [resolved]: exited, ...remaining } = runningImages;
+    runningImages = remaining;
+    writeRunningImages(projectRoot, runningImages);
     restarted = true;
   }
-  fetchPifsRelease(pifsCloneDirectory(projectRoot));
+  if (projectionAvailability().available) {
+    fetchPifsRelease(pifsCloneDirectory(projectRoot));
+  }
   const launcher = new ScopedPharoLauncher({ projectRoot });
-  const plan = imageCreationPlan(launcher.listImages(), resolved);
+  const plan = imageCreationPlan(await launcher.listImages(), resolved);
   const created = plan !== "none";
   if (created) {
-    if (plan === "reset") await launcher.resetImage(resolved);
-    await resolveTemplateCategory(projectRoot, launcher, resolved);
+    // PLexus resolves which category the template lives in.
     await launcher.createImage(resolved);
   }
-  const opened = await runLifecycle(
+  const started = await runLifecycle(
     () => startProjectImage({ projectRoot, imageId: resolved }),
-    `PLexus could not open image ${resolved}.`,
+    `PLexus could not start image ${resolved}.`,
   );
   let image;
   let mcpServerId;
   try {
-    ({ image, mcpServerId } = selectRunningImage(opened.state, resolved));
+    ({ image, mcpServerId } = selectRunningImage(started.state, resolved));
   } catch (error) {
     // An image whose Pharo version is outside the MCP contract still runs, and
     // is still worth having: the caller asked for that version, and the tools
     // it cannot offer are the only thing missing. Keep it, and say what is gone.
-    const withoutMcp = unsupportedRunningImage(opened.state, resolved);
+    const withoutMcp = unsupportedRunningImage(started.state, resolved);
     if (!withoutMcp) {
       // The image is running but unusable to us, so do not leave it behind.
       await stopProjectImage({ projectRoot, imageId: resolved }).catch(() => {});
       throw error;
     }
-    const open = { statePath: opened.statePath, imageId: resolved, mcp: false };
-    writeOpenImages(projectRoot, { ...openImages, [resolved]: open });
-    return { ...open, created, warning: pharoMcpWarning(withoutMcp) };
+    const record = { statePath: started.statePath, imageId: resolved, mcp: false };
+    writeRunningImages(projectRoot, { ...runningImages, [resolved]: record });
+    return { ...record, created, warning: pharoMcpWarning(withoutMcp) };
+  }
+  const unappliedPin = unappliedPharoMcpPin(image);
+  const projection = projectionAvailability();
+  if (!projection.available) {
+    // The image and its tools are the point; the projection is the extra this
+    // package bundles where the platform allows it.
+    const record = { statePath: started.statePath, imageId: image.id, mcpServerId };
+    writeRunningImages(projectRoot, { ...runningImages, [resolved]: record });
+    return {
+      imageId: image.id,
+      created,
+      ...(restarted ? { restarted } : {}),
+      warning: [
+        projectionUnavailableWarning(image.id, projection.reason),
+        unappliedPin,
+      ].filter(Boolean).join("\n"),
+    };
   }
+
   const mountPath = resolveMountPath(projectRoot, readConfig(projectRoot), image.id);
   fs.mkdirSync(path.dirname(mountPath), { recursive: true });
-  const open = {
-    statePath: opened.statePath,
+  const record = {
+    statePath: started.statePath,
     imageId: image.id,
     mcpServerId,
     mountPath,
   };
   let projectionPort;
   try {
-    projectionPort = await startProjection(projectRoot, open, image.imageName);
+    projectionPort = await startProjection(projectRoot, record, image.imageName);
   } catch (error) {
     // The projection is half-started at best and nothing records it yet, so
-    // close the image rather than leave an image and a mount nothing owns.
+    // stop the image rather than leave an image and a mount nothing owns.
     await stopProjectImage({ projectRoot, imageId: resolved }).catch(() => {});
     throw error;
   }
-  writeOpenImages(projectRoot, { ...openImages, [resolved]: { ...open, projectionPort } });
-  const unappliedPin = unappliedPharoMcpPin(image);
+  writeRunningImages(projectRoot, { ...runningImages, [resolved]: { ...record, projectionPort } });
   return {
     imageId: image.id,
     created,
@@ -270,13 +295,13 @@ function unsupportedRunningImage(state, imageId) {
 export function pharoMcpWarning(image) {
   const reason = image.pharoMcpContract?.reason
     ?? "This image Pharo version is outside the supported Pharo MCP range.";
-  return `${reason} Image ${image.id} is open without MCP tools or a source projection;`
+  return `${reason} Image ${image.id} is running without MCP tools or a source projection;`
     + " drive it with the Pharo command line instead.";
 }
 
-async function startProjection(projectRoot, open, imageName) {
-  const result = await callImageTool(projectRoot, open, "image_evaluate", {
-    code: pifsStartCode(open.mountPath, imageName),
+async function startProjection(projectRoot, record, imageName) {
+  const result = await callImageTool(projectRoot, record, "image_evaluate", {
+    code: pifsStartCode(record.mountPath, imageName),
   });
   const projectionPort = Number(resultPrintString(result));
   if (!Number.isInteger(projectionPort) || projectionPort < 1) {
@@ -287,76 +312,73 @@ async function startProjection(projectRoot, open, imageName) {
   return projectionPort;
 }
 
-async function closeOneImage(projectRoot, openImages, imageId) {
-  const open = openImages[imageId];
+async function stopOneImage(projectRoot, runningImages, imageId) {
+  const record = runningImages[imageId];
   let projectionError;
-  // An image opened without MCP has no projection to stop, and no route to
+  // An image started without MCP has no projection to stop, and no route to
   // ask over either.
-  if (open.projectionPort !== undefined) {
+  if (record.projectionPort !== undefined) {
     try {
-      await callImageTool(projectRoot, open, "image_evaluate", {
-        code: pifsStopCode(open.projectionPort),
+      await callImageTool(projectRoot, record, "image_evaluate", {
+        code: pifsStopCode(record.projectionPort),
       });
     } catch (error) {
       projectionError = error;
     }
   }
-  const closed = await runLifecycle(
+  const stopped = await runLifecycle(
     () => stopProjectImage({ projectRoot, imageId }),
-    `PLexus could not close image ${imageId}.`,
+    `PLexus could not stop image ${imageId}.`,
   );
-  return { stoppedImages: closed.stoppedImages.map((image) => image.id), projectionError };
+  return { stoppedImage: stopped.stoppedImage?.id, projectionError };
 }
 
-export async function closeAgentImage(projectRoot, imageId) {
-  const openImages = readOpenImages(projectRoot);
-  const identifiers = imageId === undefined
-    ? Object.keys(openImages)
+/**
+ * Stop one image, or with `all`, every image this project started. Naming no
+ * image stops the default one, as every other command addresses it; `all` is
+ * the cleanup, and says so where the caller can see it.
+ *
+ * @param {string} projectRoot
+ * @param {string} [imageId]
+ * @param {{ all?: boolean }} [options]
+ */
+export async function stopAgentImage(projectRoot, imageId, options = {}) {
+  const runningImages = readRunningImages(projectRoot);
+  if (options.all && imageId !== undefined) {
+    throw new Error("Stopping every image takes no image id.");
+  }
+  const identifiers = options.all
+    ? Object.keys(runningImages)
     : [resolveImageId(projectRoot, imageId)];
   if (identifiers.length === 0) {
-    throw new Error("No open pharo-agent image.");
+    throw new Error("No pharo-agent image is running.");
   }
   for (const identifier of identifiers) {
-    if (!openImages[identifier]) {
-      throw new Error(`Image ${identifier} is not open.`);
+    if (!runningImages[identifier]) {
+      throw new Error(`Image ${identifier} is not running.`);
     }
   }
 
   const stoppedImages = [];
   const projectionErrors = [];
-  const remaining = { ...openImages };
+  const remaining = { ...runningImages };
   for (const identifier of identifiers) {
-    const closed = await closeOneImage(projectRoot, openImages, identifier);
+    const stopped = await stopOneImage(projectRoot, runningImages, identifier);
     delete remaining[identifier];
-    writeOpenImages(projectRoot, remaining);
-    stoppedImages.push(...closed.stoppedImages);
-    if (closed.projectionError) {
-      projectionErrors.push(`${identifier}: ${closed.projectionError.message}`);
+    writeRunningImages(projectRoot, remaining);
+    if (stopped.stoppedImage) {
+      stoppedImages.push(stopped.stoppedImage);
+    }
+    if (stopped.projectionError) {
+      projectionErrors.push(`${identifier}: ${stopped.projectionError.message}`);
     }
   }
   if (projectionErrors.length > 0) {
-    throw new Error(`Images closed, but PIFS cleanup failed: ${projectionErrors.join("; ")}`);
+    throw new Error(`Images stopped, but PIFS cleanup failed: ${projectionErrors.join("; ")}`);
   }
   return { stoppedImages };
 }
 
-export function agentImageStatus(projectRoot) {
-  const openImages = readOpenImages(projectRoot);
-  let defaultImage;
-  try {
-    defaultImage = defaultImageId(projectRoot);
-  } catch {
-    defaultImage = undefined;
-  }
-  return {
-    ...(defaultImage ? { defaultImage } : {}),
-    images: Object.values(openImages).map((open) => ({
-      ...open,
-      isDefault: open.imageId === defaultImage,
-    })),
-  };
-}
-
 export async function listImageTemplates(projectRoot) {
   // `image add --template` takes a name the launcher must already know, and a
   // name that lands in two categories needs the category as well, so answer

package/src/mcpServer.js

@@ -0,0 +1,154 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import {
+  callImageTool,
+  listImageTools,
+  toolResult,
+  version,
+  withImageSelector,
+} from "./gateway.js";
+import { listImages } from "./images.js";
+import { startAgentImage, stopAgentImage } from "./live.js";
+import { readRunningImage } from "./runtime.js";
+
+// The host loads only tool names and these instructions at session start and
+// defers the rest, so this is what decides whether Pharo tools are searched
+// for at all. It is the conditional guidance the generated guide gives,
+// written where the host can act on it.
+export const serverInstructions = `Live Pharo images for this project: reading and writing Smalltalk code in the
+image, running tests, finding senders and implementors, applying critiques,
+and projecting image source as files on disk.
+
+Search these tools whenever the task involves Pharo, Smalltalk, a Tonel
+package, or a .st file. Start an image with image_start before calling the
+image's own tools, which are listed once an image answers; image_list says
+what is already running.
+
+The image advertises the common tools rather than all of it. Use tool_search
+and tool_get to find the rest, then call one by name like any other.`;
+
+// Listed whether or not an image is running, so the list is never empty. A
+// host that caches tools and ignores tools/list_changed would otherwise hold
+// an empty list for the whole session and never learn that one had started.
+const lifecycleTools = [
+  {
+    name: "image_start",
+    description:
+      "Start one of this project's Pharo images, creating it from its template "
+      + "when it does not exist yet. The image's own tools are listed once it "
+      + "answers. On macOS with fuse-t its source also mounts as files; "
+      + "elsewhere the image starts without that and says so.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        image: {
+          type: "string",
+          description: "Image id to start. Defaults to the project's default image.",
+        },
+      },
+    },
+  },
+  {
+    name: "image_list",
+    description:
+      "List this project's declared images, which are running, and the route "
+      + "and mount of each running one.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "image_stop",
+    description:
+      "Stop a running image, and any source projection this project started for it.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        image: {
+          type: "string",
+          description: "Image id to stop. Defaults to the project's default image.",
+        },
+        all: {
+          type: "boolean",
+          description: "Stop every image this project started, instead of one.",
+        },
+      },
+    },
+  },
+];
+
+// Resolved per request rather than once at startup. A host starts this server
+// when its session starts, which is before anyone has started an image, so
+// resolving then meant the server died on its first line.
+async function runningImageTools(projectRoot, defaultImage) {
+  let running;
+  try {
+    running = readRunningImage(projectRoot, defaultImage);
+  } catch {
+    // No image running, none configured, or one running without MCP. The image
+    // contributes no tools yet and the lifecycle tools say how to change that.
+    return [];
+  }
+  return (await listImageTools(projectRoot, running))
+    .map((tool) => withImageSelector(tool, running.imageId));
+}
+
+export async function serveImagesMcp(resolveProjectRoot, defaultImage) {
+  const server = new Server(
+    { name: "pharo-agent", version },
+    { capabilities: { tools: { listChanged: true } }, instructions: serverInstructions },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    let projectRoot;
+    try {
+      projectRoot = resolveProjectRoot();
+    } catch {
+      // No project here. The lifecycle tools are still listed rather than
+      // nothing, so the host has a server that works and a call can say why.
+      return { tools: lifecycleTools };
+    }
+    return {
+      tools: [...lifecycleTools, ...(await runningImageTools(projectRoot, defaultImage))],
+    };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { image, all, ...argumentsValue } = request.params.arguments ?? {};
+    const selected = image ?? defaultImage;
+    // Throws when there is no project, which is the answer the caller needs.
+    const projectRoot = resolveProjectRoot();
+
+    // Matched before the image's catalogue: these three names belong to this
+    // server, and an image that happened to hold one must not decide what
+    // starting an image means.
+    if (request.params.name === "image_start") {
+      const started = await startAgentImage(projectRoot, selected);
+      await server.sendToolListChanged();
+      return toolResult({ ok: true, ...started });
+    }
+    if (request.params.name === "image_list") {
+      return toolResult({ ok: true, ...listImages(projectRoot) });
+    }
+    if (request.params.name === "image_stop") {
+      const stopped = all
+        ? await stopAgentImage(projectRoot, undefined, { all: true })
+        : await stopAgentImage(projectRoot, selected);
+      await server.sendToolListChanged();
+      return toolResult({ ok: true, ...stopped });
+    }
+
+    // Listed tools are the common ones, not the whole catalogue, and the image
+    // answers for any tool it holds. Refusing a name this list does not carry
+    // would hide tools that tool_search just found, and the image's own error
+    // is the better answer for a name nothing holds.
+    const running = readRunningImage(projectRoot, selected);
+    return toolResult(
+      await callImageTool(projectRoot, running, request.params.name, argumentsValue),
+    );
+  });
+
+  await server.connect(new StdioServerTransport());
+}