@evref-bl/pharo-agent 0.15.0 → 0.17.0

package/src/init.js

@@ -1,7 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { templateDirectory as mcpTemplateDirectory } from "@evref-bl/pharo-mcp";
-import { guideForHost, hostList } from "./hosts.js";
+import { version } from "./gateway.js";
+import { hostList, hostNamed } from "./hosts.js";
 import {
   createProjectConfig,
   enclosingProjectRoot,
@@ -67,6 +68,47 @@ function assertGeneratedGuideCanBeUpdated(filePath) {
   }
 }
 
+// Pinned to the release that wrote the guide, as the setup skill pins its
+// npx command: a host that has no plugin has no pharo-agent on its PATH
+// either. Code mode off, because OpenCode would otherwise hide the tools
+// inside its own execute tool.
+function serverEntry() {
+  return {
+    type: "local",
+    command: ["npx", "--yes", `@evref-bl/pharo-agent@${version}`, "mcp"],
+    enabled: true,
+    codemode: false,
+  };
+}
+
+// Only mcp.pharo is ours. A configuration that may hold comments is not
+// rewritten, since parsing and writing it back would drop them.
+function readServerConfig(projectRoot, fileName) {
+  const filePath = path.join(projectRoot, fileName);
+  const byHand = `add this under "mcp" by hand:\n"pharo": ${JSON.stringify(serverEntry(), null, 2)}`;
+  if (!fs.existsSync(filePath)) {
+    if (fs.existsSync(`${filePath}c`)) {
+      throw new Error(`${filePath}c may hold comments that rewriting it would drop; ${byHand}`);
+    }
+    return { filePath, config: { $schema: "https://opencode.ai/config.json" } };
+  }
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    throw new Error(`${filePath} is not plain JSON, so rewriting it would lose what it holds; ${byHand}`);
+  }
+  if (config === null || typeof config !== "object" || Array.isArray(config)) {
+    throw new Error(`${filePath} is not a JSON object; ${byHand}`);
+  }
+  return { filePath, config };
+}
+
+function writeServerConfig({ filePath, config }) {
+  const mcp = config.mcp !== null && typeof config.mcp === "object" ? config.mcp : {};
+  fs.writeFileSync(filePath, `${JSON.stringify({ ...config, mcp: { ...mcp, pharo: serverEntry() } }, null, 2)}\n`);
+}
+
 function guidance() {
   return `# Pharo work\n\nWhen the task uses Pharo, read \`pharo.AGENTS.md\` before acting.\n`;
 }
@@ -110,64 +152,34 @@ function assertRoutingResolves(routing, templates) {
 function pharoGuide() {
   return `# Pharo project guide
 
-${generatedBy}. Edits here are replaced the next time it runs.
+${generatedBy}. Edits here are replaced the next time it
+runs: re-run it after upgrading the plugin, and keep your own instructions
+elsewhere.
 
-After upgrading the plugin/CLI, re-run \`pharo-agent init --host <host>\` from
-the project root with the same host to refresh this guide and the copied skills
-and references. Omit \`--mount-root\` to keep existing settings. Image declarations,
-runtime state, and live code are preserved. Keep project-specific instructions
-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.
+## Images
 
-\`plexus.json\` declares this project's images. A freshly initialized
-project declares none; register one before the first image start. With the
-pharo-agent plugin enabled, that is \`image_templates\` and then \`image_add\`,
-with no shell. Otherwise:
+\`plexus.json\` declares this workspace's images. With the \`pharo\` MCP server,
+use the \`image_*\` tools; otherwise:
 
 \`\`\`sh
 pharo-agent image templates
-pharo-agent image list
-pharo-agent image add dev --template '<launcher template name>'
+pharo-agent image add <id> --template '<template name>'
+pharo-agent image start <id>
 \`\`\`
 
-\`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
-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. Stop an image before removing its declaration.
-
-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, this is all MCP tools:
-declare an image with \`image_add\`, start it with \`image_start\`, and call the
-image's own tools 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
-than guessing at a name, then call one the same way as any other:
-
-\`\`\`sh
-pharo-agent pharo tool_search '{"query":"repository commit"}'
-pharo-agent pharo tool_get '{"name":"repository_commit"}'
-pharo-agent pharo repository_commit '{"name":"MCP","message":"..."}'
-\`\`\`
+The first image declared is the default, the main line. An image takes one
+writer, and making one takes seconds: add a new one for each new subject or
+parallel agent rather than share one, named like a branch
+(\`pretty-print-formatter\`, not \`p15\`). A running image may be another
+session's. Stop an image and remove its declaration when its subject is done.
 
-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.
+## Tools
 
-Image, Tonel, Iceberg, disk Git, and host processes are separate states.
+With the \`pharo\` MCP server, an image's tools are MCP tools. Otherwise run
+one as \`pharo-agent <tool> --<argument> <value>\`: \`<tool> --help\` lists its
+arguments, and a value of \`-\` is read from stdin. \`pharo-agent list\` names
+the common tools; \`tool_search\` finds the rest. On macOS and Linux,
+\`image start\` also mounts the source under \`.pharo-agent/mounts\`.
 
 ${pharoRouting()}
 `;
@@ -192,10 +204,11 @@ function resolveInitProjectRoot(cwd) {
 
 /** @param {{ host: string, mountRoot?: string, cwd?: string }} options */
 export function initialize({ host, mountRoot, cwd = process.cwd() }) {
-  const guideName = guideForHost(host);
-  if (!guideName) {
+  const hostEntry = hostNamed(host);
+  if (!hostEntry) {
     throw new Error(`--host must be ${hostList()}`);
   }
+  const guideName = hostEntry.guide;
 
   const { projectRoot, createdProjectConfig } = resolveInitProjectRoot(cwd);
   const directory = pluginDirectory(projectRoot);
@@ -203,6 +216,7 @@ export function initialize({ host, mountRoot, cwd = process.cwd() }) {
   const pharoGuidePath = path.join(projectRoot, "pharo.AGENTS.md");
   assertGeneratedGuideCanBeUpdated(pharoGuidePath);
   assertManagedBlockCanBeUpdated(path.join(projectRoot, guideName));
+  const serverConfig = hostEntry.serverConfig && readServerConfig(projectRoot, hostEntry.serverConfig);
   if (createdProjectConfig) {
     createProjectConfig(projectRoot);
   }
@@ -219,6 +233,7 @@ export function initialize({ host, mountRoot, cwd = process.cwd() }) {
   copyDirectory(path.join(templates, "pharo-references"), path.join(directory, "references"));
   copyDirectory(path.join(templates, "pharo-skills"), path.join(directory, "skills"));
   updateManagedBlock(path.join(projectRoot, guideName), guidance());
+  if (serverConfig) writeServerConfig(serverConfig);
 
-  return { projectRoot, guideName, createdProjectConfig };
+  return { projectRoot, guideName, createdProjectConfig, ...(serverConfig && { serverConfig: hostEntry.serverConfig }) };
 }

package/src/live.js

@@ -22,47 +22,65 @@ import {
   writeRunningImages,
 } from "./runtime.js";
 
-export const pifsRelease = "v0.10.2";
+export const pifsRelease = "v0.11.0";
 
-// 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";
+// Set to `off`, no image mounts a source projection, wherever it runs.
+const projectionVariable = "PHARO_AGENT_PROJECTION";
+
+// The systems PIFS releases a daemon for.
+const projectedPlatforms = ["darwin", "linux"];
 
 /**
- * Whether a source projection can be mounted here.
+ * Whether to ask the image for a source projection.
+ *
+ * Whether this machine can mount is the PIFS daemon's to say: macOS needs
+ * nothing, Linux needs fuse3, and the daemon names what is missing. A
+ * projection that fails leaves the image running with that reason as its
+ * warning, so this answers no only where asking is wasted, on a system PIFS
+ * has no daemon for, or forbidden.
  *
- * 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.
+ * A machine that could mount may still be one that must not, so the
+ * environment can turn projections off before anything is asked.
  *
- * @param {{ platform?: string, exists?: (path: string) => boolean }} [host]
+ * @param {{
+ *   env?: Record<string, string | undefined>,
+ *   platform?: string,
+ * }} [host]
  */
 export function projectionAvailability(host = {}) {
+  const setting = (host.env ?? process.env)[projectionVariable];
   const platform = host.platform ?? process.platform;
-  const exists = host.exists ?? fs.existsSync;
-  if (platform !== "darwin") {
+  if (setting === "off") {
+    return {
+      available: false,
+      reason: `Source projections are turned off by ${projectionVariable}=off.`,
+    };
+  }
+  if (setting) {
+    // Any other value fails safe: an opt-out that ignored a typo, or a 0,
+    // would mount on the very machine that asked not to be mounted on.
     return {
       available: false,
-      reason: "A source projection needs macOS and fuse-t, which this platform"
-        + ` (${platform}) cannot provide.`,
+      reason: `Source projections are off: ${projectionVariable} takes only off,`
+        + ` and is ${JSON.stringify(setting)}. Unset it to mount them where the platform allows.`,
     };
   }
-  if (!exists(fuseLibraryPath)) {
+  if (!projectedPlatforms.includes(platform)) {
     return {
       available: false,
-      reason: "A source projection needs fuse-t, which is not installed."
-        + " Install it with `brew install --cask fuse-t`.",
+      reason: `PIFS mounts source projections on macOS and Linux, not on this platform (${platform}).`,
     };
   }
   return { available: true };
 }
 
+// The daemon's own reasons end without a period.
+function sentence(text) {
+  return /[.!?]$/.test(text) ? text : `${text}.`;
+}
+
 export function projectionUnavailableWarning(imageId, reason) {
-  return `${reason} Image ${imageId} is running with its Pharo tools and no`
+  return `${sentence(reason)} Image ${imageId} is running with its Pharo tools and no`
     + " source projection; read and edit its code through the tools.";
 }
 
@@ -73,71 +91,67 @@ export function projectionUnavailableWarning(imageId, reason) {
 export const pifsSelectors = ["startMountedAt:named:", "stopOn:"];
 
 export function pifsStartCode(mountPath, imageName) {
-  return `Metacello new
-	baseline: 'PharoImageFS';
-	repository: 'github://Evref-BL/pharo-image-fs:${pifsRelease}/src';
-	load: 'Core'.
-((Smalltalk globals at: #PIFSServer)
-	startMountedAt: ${smalltalkString(mountPath)} asFileReference
-	named: ${smalltalkString(imageName)}) port`;
-}
-
-export function pifsStopCode(projectionPort) {
-  return `(Smalltalk globals at: #PIFSServer) stopOn: ${projectionPort}`;
+  // A projection that cannot mount answers why, as a string, rather than
+  // failing the evaluation: the reason is the daemon's, and becomes the
+  // warning of an image that keeps running.
+  return `[ Metacello new
+		baseline: 'PharoImageFS';
+		repository: 'github://Evref-BL/pharo-image-fs:${pifsRelease}/src';
+		load: 'Core'.
+	((Smalltalk globals at: #PIFSServer)
+		startMountedAt: ${smalltalkString(mountPath)} asFileReference
+		named: ${smalltalkString(imageName)}) port ]
+	on: Error
+	do: [ :error | error messageText asString ]`;
 }
 
-// `mount` prints one "<source> on <path> (<options>)" line per mount, with the
-// path resolved, so a project under a symlink is looked for by its real path.
-export function isMountedAt(mountPath, mountTable) {
-  let realPath = mountPath;
-  try {
-    realPath = path.join(fs.realpathSync(path.dirname(mountPath)), path.basename(mountPath));
-  } catch {
-    // No parent directory, so nothing can be mounted there either.
-  }
-  return mountTable
-    .split("\n")
-    .some((line) => line.includes(` on ${mountPath} (`) || line.includes(` on ${realPath} (`));
-}
-
-function currentMountTable() {
-  return spawnSync("mount", [], { encoding: "utf8" }).stdout ?? "";
-}
-
-function unmount(mountPath) {
-  // What PIFSServer>>stopDaemon runs when it stops a projection itself.
-  if (spawnSync("umount", [mountPath], { stdio: "ignore" }).status !== 0) {
-    spawnSync("diskutil", ["unmount", mountPath], { stdio: "ignore" });
-  }
+/**
+ * What a projection start answered: the port serving it, why PIFS could not
+ * mount, or nothing readable.
+ *
+ * @param {string | undefined} printString
+ * @returns {{ port: number } | { reason: string } | undefined}
+ */
+export function projectionStartOutcome(printString) {
+  // The value comes first; MCP appends warnings, the Transcript and a
+  // truncation mark on the lines after it.
+  const text = printString ?? "";
+  const digits = /^(\d+)(?:\n|$)/.exec(text);
+  if (digits && Number(digits[1]) > 0) return { port: Number(digits[1]) };
+  // A string prints quoted, its quotes doubled, and a long one is cut short
+  // of its closing quote, before the truncation mark.
+  const quoted = /^'((?:[^']|'')*)(?:'|$)/.exec(text);
+  if (!quoted) return undefined;
+  const literal = quoted[1].split("\n[truncated")[0].replaceAll("''", "'").trim();
+  return {
+    reason: `${sentence(literal)} Set ${projectionVariable}=off to start images without trying to mount.`,
+  };
 }
 
 /**
- * Unmount a projection whose image is gone.
+ * Unmount the projection of an image that is gone, when nothing else will.
  *
- * The mount is served by a PIFS daemon, a process of its own that reads the
- * source over HTTP from the image. PIFS unmounts it from inside the image when
- * it stops, which an image that crashed or was closed never does: the mount
- * stays, every read in it fails with an I/O error, and it holds the path
- * against the next projection. Unmounting is enough; the daemon exits with its
- * mount.
+ * Records written before this one name no PIFS release: fuse-t's daemon
+ * served their projection, and it outlives its image. A later daemon
+ * unmounts on its own once its image is gone. A path with nothing mounted
+ * just fails to unmount.
  *
- * @param {string | undefined} mountPath
- * @param {{ mountTable?: () => string, unmount?: (path: string) => void }} [host]
- * @returns {boolean} whether something was unmounted
+ * @param {{ mountPath?: string, pifsRelease?: string, [key: string]: unknown } | undefined} record
+ * @param {(mountPath: string) => void} [unmount]
+ * @returns {boolean} whether it tried
  */
-export function releaseProjectionMount(mountPath, host = {}) {
-  const mountTable = host.mountTable ?? currentMountTable;
-  if (mountPath === undefined || !isMountedAt(mountPath, mountTable())) return false;
-  (host.unmount ?? unmount)(mountPath);
-  if (isMountedAt(mountPath, mountTable())) {
-    throw new Error(
-      `The source projection of an image that is gone is still mounted at ${mountPath},`
-        + ` and could not be unmounted. Run umount ${JSON.stringify(mountPath)}, then try again.`,
-    );
-  }
+export function releaseFuseTMount(record, unmount = (mountPath) => {
+  spawnSync("umount", [mountPath], { stdio: "ignore" });
+}) {
+  if (record?.mountPath === undefined || record.pifsRelease !== undefined) return false;
+  unmount(record.mountPath);
   return true;
 }
 
+export function pifsStopCode(projectionPort) {
+  return `(Smalltalk globals at: #PIFSServer) stopOn: ${projectionPort}`;
+}
+
 function namedPrintString(value) {
   // Structured results name the print string, somewhere under the envelope,
   // and reach us either as an object or as JSON inside a text part.
@@ -255,16 +269,12 @@ export async function startAgentImage(projectRoot, imageId) {
     // 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;
+    releaseFuseTMount(exited);
     runningImages = remaining;
     writeRunningImages(projectRoot, runningImages);
     restarted = true;
   }
   if (projectionAvailability().available) {
-    // This project has no live image at this mount path now: none was
-    // recorded, or the one recorded has exited. Whatever is still mounted
-    // there was left by an image that is gone, and would hold the path
-    // against the projection about to be mounted.
-    releaseProjectionMount(resolveMountPath(projectRoot, readConfig(projectRoot), resolved));
     fetchPifsRelease(pifsCloneDirectory(projectRoot));
   }
   const launcher = new ScopedPharoLauncher({ projectRoot });
@@ -297,11 +307,24 @@ export async function startAgentImage(projectRoot, imageId) {
     return { ...record, created, warning: pharoMcpWarning(withoutMcp) };
   }
   const unappliedPin = unappliedPharoMcpPin(image);
-  const projection = projectionAvailability();
-  if (!projection.available) {
+  const record = { statePath: started.statePath, imageId: image.id, mcpServerId };
+  const mountPath = resolveMountPath(projectRoot, readConfig(projectRoot), image.id);
+  const availability = projectionAvailability();
+  /** @type {{ port?: number, reason?: string }} */
+  let projection = availability;
+  if (availability.available) {
+    try {
+      projection = await startProjection(projectRoot, record, mountPath, image.imageName);
+    } catch (error) {
+      // Nothing says whether PIFS mounted, so stop the image rather than keep
+      // a mount nothing records: its daemon unmounts once the image is gone.
+      await stopProjectImage({ projectRoot, imageId: resolved }).catch(() => {});
+      throw error;
+    }
+  }
+  if (projection.reason !== undefined) {
     // 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 };
+    // package bundles where the machine allows it.
     writeRunningImages(projectRoot, { ...runningImages, [resolved]: record });
     return {
       imageId: image.id,
@@ -313,25 +336,11 @@ export async function startAgentImage(projectRoot, imageId) {
       ].filter(Boolean).join("\n"),
     };
   }
-
-  const mountPath = resolveMountPath(projectRoot, readConfig(projectRoot), image.id);
-  fs.mkdirSync(path.dirname(mountPath), { recursive: true });
-  const record = {
-    statePath: started.statePath,
-    imageId: image.id,
-    mcpServerId,
-    mountPath,
-  };
-  let projectionPort;
-  try {
-    projectionPort = await startProjection(projectRoot, record, image.imageName);
-  } catch (error) {
-    // The projection is half-started at best and nothing records it yet, so
-    // stop the image rather than leave an image and a mount nothing owns.
-    await stopProjectImage({ projectRoot, imageId: resolved }).catch(() => {});
-    throw error;
-  }
-  writeRunningImages(projectRoot, { ...runningImages, [resolved]: { ...record, projectionPort } });
+  const projectionPort = projection.port;
+  writeRunningImages(projectRoot, {
+    ...runningImages,
+    [resolved]: { ...record, mountPath, projectionPort, pifsRelease },
+  });
   return {
     imageId: image.id,
     created,
@@ -356,17 +365,16 @@ export function pharoMcpWarning(image) {
     + " drive it with the Pharo command line instead.";
 }
 
-async function startProjection(projectRoot, record, imageName) {
+async function startProjection(projectRoot, record, mountPath, imageName) {
   const result = await callImageTool(projectRoot, record, "image_evaluate", {
-    code: pifsStartCode(record.mountPath, imageName),
+    code: pifsStartCode(mountPath, imageName),
   });
-  const projectionPort = Number(resultPrintString(result));
-  if (!Number.isInteger(projectionPort) || projectionPort < 1) {
-    throw new Error(
-      `PIFS did not report a projection port: ${JSON.stringify(result).slice(0, 500)}`,
-    );
+  // A refusal is PIFS's own: it stopped what it had started.
+  const outcome = projectionStartOutcome(resultPrintString(result));
+  if (!outcome) {
+    throw new Error(`PIFS did not report a projection port: ${JSON.stringify(result).slice(0, 500)}`);
   }
-  return projectionPort;
+  return outcome;
 }
 
 async function stopOneImage(projectRoot, runningImages, imageId) {
@@ -374,19 +382,18 @@ async function stopOneImage(projectRoot, runningImages, imageId) {
   let projectionError;
   // An image started without MCP has no projection to stop, and no route to
   // ask over either.
-  if (record.projectionPort !== undefined) {
+  if (record.projectionPort !== undefined && recordedImageIsRunning(record)) {
     try {
-      if (recordedImageIsRunning(record)) {
-        await callImageTool(projectRoot, record, "image_evaluate", {
-          code: pifsStopCode(record.projectionPort),
-        });
-      } else {
-        // PIFS stops a projection from inside its image, and this one is gone.
-        releaseProjectionMount(record.mountPath);
-      }
+      await callImageTool(projectRoot, record, "image_evaluate", {
+        code: pifsStopCode(record.projectionPort),
+      });
     } catch (error) {
       projectionError = error;
     }
+  } else {
+    // A gone image has no one to ask, and its projection's daemon unmounts
+    // on its own, unless fuse-t's served it.
+    releaseFuseTMount(record);
   }
   const stopped = await runLifecycle(
     () => stopProjectImage({ projectRoot, imageId }),

package/src/mcpServer.js

@@ -19,18 +19,18 @@ import { readRunningImage } from "./runtime.js";
 // 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.
+export const serverInstructions = `Live Pharo images for this project: reading and changing code, running tests,
+searching and critiquing it.
 
-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. A project that declares no image yet needs
-image_templates and image_add first.
+Search these tools for any Pharo, Smalltalk, Tonel or .st work. Start an
+image with image_start before calling its tools; a project with no image needs
+image_templates and image_add first. An image lists its common tools;
+tool_search and tool_get find the rest.
 
-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.`;
+An image takes one writer, and making one takes seconds: image_add a new one
+for each new subject or parallel agent rather than share one, named like a
+branch (pretty-print-formatter, not p15). The default image is the main line.
+A running image may be another session's.`;
 
 // This server's own tools, in the order a project meets them: declare an
 // image, start it, and the image's tools join the list. Listed whether or not
@@ -40,34 +40,28 @@ and tool_get to find the rest, then call one by name like any other.`;
 const projectTools = [
   {
     name: "image_templates",
-    description:
-      "List the images Pharo Launcher can create, with the category of each. "
-      + "A template name that two categories offer is flagged, and needs its "
-      + "category when it is declared.",
+    description: "List the templates images can be made from, with their categories.",
     inputSchema: { type: "object", properties: {} },
   },
   {
     name: "image_add",
     description:
-      "Declare an image in this project, from a template image_templates "
-      + "names. Declaring does not create the image: the first image_start "
-      + "does, from this template. The first image declared becomes the "
-      + "project's default.",
+      "Declare an image made from a template; image_start creates it. The "
+      + "first image declared is the default.",
     inputSchema: {
       type: "object",
       properties: {
         id: {
           type: "string",
-          description: "Short id this project calls the image by, such as dev.",
+          description: "What the image is for, named like a branch.",
         },
         template: {
           type: "string",
-          description: "Template name, exactly as image_templates gives it.",
+          description: "Template name, as image_templates gives it.",
         },
         category: {
           type: "string",
-          description:
-            "Template category. Needed only for a name two categories offer.",
+          description: "Template category, for a name two categories offer.",
         },
         profile: {
           type: "string",
@@ -80,42 +74,36 @@ const projectTools = [
   {
     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.",
+      "Start an image, creating it the first time. Its tools are listed once "
+      + "it answers. On macOS and Linux its source also mounts as files.",
     inputSchema: {
       type: "object",
       properties: {
         image: {
           type: "string",
-          description: "Image id to start. Defaults to the project's default image.",
+          description: "Image id. Defaults to the default image.",
         },
       },
     },
   },
   {
     name: "image_list",
-    description:
-      "List this project's declared images, which are running, and the route "
-      + "and mount of each running one. An image that was started and has "
-      + "exited since is listed as exited; image_start starts it again.",
+    description: "List the declared images, which are running, and the route and mount of each.",
     inputSchema: { type: "object", properties: {} },
   },
   {
     name: "image_stop",
-    description:
-      "Stop a running image, and any source projection this project started for it.",
+    description: "Stop an image and its source mount.",
     inputSchema: {
       type: "object",
       properties: {
         image: {
           type: "string",
-          description: "Image id to stop. Defaults to the project's default image.",
+          description: "Image id. Defaults to the default image.",
         },
         all: {
           type: "boolean",
-          description: "Stop every image this project started, instead of one.",
+          description: "Stop every image this project started.",
         },
       },
     },