@evref-bl/pharo-agent 0.15.0 → 0.17.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pharo-agent",
   "displayName": "Pharo Agent",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Terminal-first Pharo image setup for coding agents.",
   "author": {
     "name": "Evref-BL",

package/README.md

@@ -3,8 +3,8 @@
 `pharo-agent` gives a coding agent a Pharo Launcher of its own. It can see the
 templates the launcher offers, create images from them, start and stop them,
 and work inside the ones it started: classes, methods, senders, tests,
-refactorings, critiques, and the rest of what a Pharo IDE does. On macOS it
-can also read and edit an image's source as files.
+refactorings, critiques, and the rest of what a Pharo IDE does. On macOS and
+Linux it can also read and edit an image's source as files.
 
 It works with Claude Code, Codex and OpenCode.
 
@@ -32,10 +32,10 @@ tested together, and gives the agent one command surface over the lot.
 - Node 22.12 or later.
 - [Pharo Launcher](https://pharo-project.github.io/pharo-launcher/), which is
   where images and templates come from.
-- For editing source as files: macOS with [fuse-t](https://www.fuse-t.org/),
-  installed with `brew install --cask fuse-t`. Its daemon is downloaded for
-  you. Everywhere else images start with their Pharo tools and no projection,
-  rather than failing.
+- For editing source as files: macOS, which needs nothing more, or Linux with
+  FUSE 3 (the `fuse3` package, installed by default on most distributions).
+  Its daemon is downloaded for you. Where a projection cannot mount, the image
+  starts with its Pharo tools and a warning saying why, rather than failing.
 
 The image tools cover Pharo 12 to 15. An image outside that range still
 starts, and says what it will not have.
@@ -76,10 +76,11 @@ its schemas stay out of the agent's context. The tools belong to the image, so
 what exists depends on what that image has loaded. [Tools](docs/tools.md)
 covers both, and serving a different MCP from an image.
 
-**Source as files, on macOS.** Starting an image mounts its source below
+**Source as files, on macOS and Linux.** Starting an image mounts its source below
 `.pharo-agent/mounts`. A file edited there is compiled into the live image:
 the files and the tools are two views of one image, not of an export and an
-image.
+image. Setting `PHARO_AGENT_PROJECTION=off` in the environment starts images
+without mounting anything.
 
 **Guidance for the agent.** Setting a project up writes a Pharo guide into it,
 and a conditional line in the host's own guide pointing at that guide for

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evref-bl/pharo-agent",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "private": false,
   "description": "Terminal-first Pharo integration for coding agents.",
   "license": "Apache-2.0",
@@ -32,8 +32,8 @@
     "test": "node --test"
   },
   "dependencies": {
-    "@evref-bl/pharo-mcp": "3.4.1",
-    "@evref-bl/plexus": "0.14.1",
+    "@evref-bl/pharo-mcp": "3.6.0",
+    "@evref-bl/plexus": "0.15.1",
     "@modelcontextprotocol/sdk": "1.32.2"
   },
   "devDependencies": {

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "pharo-agent",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Terminal-first Pharo image setup for coding agents.",
   "author": {
     "name": "Evref-BL",

package/skills/pharo-feedback/SKILL.md

@@ -63,7 +63,7 @@ instead of a new issue.
 One issue per problem; findings that share a cause make one issue. Title it
 with what goes wrong, in the tool's own terms. Keep the body short:
 
-- **Tool:** its name; `pharo-agent 0.15.0`; the image's Pharo version, which
+- **Tool:** its name; `pharo-agent 0.17.0`; the image's Pharo version, which
   `image_list` gives; the host you run in.
 - **What happened:** what you asked for and what came back, the error quoted
   and trimmed.

package/skills/pharo-setup/SKILL.md

@@ -5,21 +5,20 @@ description: Enable or refresh Pharo image tooling in the current Pharo project.
 
 Run this only when the user asks to enable or refresh Pharo tooling in this project.
 
-From the project root, run the released CLI that matches this plugin:
+From the project root, run the released CLI that matches this plugin, naming
+the host this chat runs in: `--host claude` in Claude Code, `--host codex` in
+Codex, `--host opencode` in OpenCode.
 
 ```sh
-npx --yes @evref-bl/pharo-agent@0.15.0 init --host claude
+npx --yes @evref-bl/pharo-agent@0.17.0 init --host claude
 ```
 
-Name the host this chat runs in: `--host claude` in Claude Code,
-`--host codex` in Codex, `--host opencode` in OpenCode.
-The command writes no host configuration. It adds a conditional instruction
-block and this project's own files, so Pharo guidance stays out of unrelated
-work.
+It writes the project's Pharo guide, skills and references, and a block in the
+host's guide that points to them; no host configuration. Re-running it after
+an upgrade replaces those files and keeps image declarations and image code.
 
-To get the image's tools as MCP tools in Claude Code, enable this plugin for
-this project rather than configuring a server by hand. Commit
-`.claude/settings.json`:
+In Claude Code, enable the plugin for this project in `.claude/settings.json`;
+the next session gets the tools:
 
 ```json
 {
@@ -35,26 +34,11 @@ this project rather than configuring a server by hand. Commit
 }
 ```
 
-A host reads that file when a session starts, so the tools appear in the next
-one. Enabling it per project keeps every other project untouched.
-
-After upgrading the plugin/CLI, re-run the setup command from the project root
-with the same host to refresh the generated guide and copied skills/references.
-Those files are overwritten; keep project-specific guidance outside the host's
-managed block and outside generated/copied paths. Omit `--mount-root` to retain
-existing settings. Image declarations, runtime state, and live image code are
-preserved. This refresh does not install a newer package or upgrade image tools.
-
-Setup initializes the current directory, creating `plexus.json` with
-no image when it is absent. Register one before the first
-`pharo-agent image start`:
+Then declare the project's first image, its default:
 
 ```sh
 pharo-agent image templates
 pharo-agent image add dev --template '<launcher template name>'
 ```
 
-`image templates` names what the launcher offers, with the category of each.
-
-After setup, read `pharo.AGENTS.md` in this chat before doing Pharo work. A
-new chat picks up the conditional project guidance automatically.
+Read `pharo.AGENTS.md` before doing Pharo work.

package/src/cli.js

@@ -2,11 +2,18 @@ import { hostChoices, hostList } from "./hosts.js";
 import { usage } from "./help.js";
 import { initialize } from "./init.js";
 import { addImage, listImages, removeImage, useImage } from "./images.js";
-import { callImageTool, listImageTools } from "./gateway.js";
+import { callImageTool, listAdvertisedTools, toolContract } from "./gateway.js";
 import { serveImagesMcp } from "./mcpServer.js";
 import { listImageTemplates, startAgentImage, stopAgentImage } from "./live.js";
 import { findProjectRoot } from "./project.js";
 import { readRunningImage } from "./runtime.js";
+import {
+  isToolName,
+  resultText,
+  toolArguments,
+  toolListing,
+  toolUsage,
+} from "./toolCommand.js";
 
 function parseInit(args) {
   let host;
@@ -97,20 +104,6 @@ function requireNoArguments(command, args) {
   }
 }
 
-function parseToolArguments(value) {
-  if (value === undefined) return {};
-  let parsed;
-  try {
-    parsed = JSON.parse(value);
-  } catch {
-    throw new Error("Tool arguments must be a JSON object.");
-  }
-  if (!parsed || Array.isArray(parsed) || typeof parsed !== "object") {
-    throw new Error("Tool arguments must be a JSON object.");
-  }
-  return parsed;
-}
-
 // A tool the image answered with an error is still an answer: the MCP result
 // carries the Pharo exception, and a caller wants to read it. Print it as
 // always, and report the failure in the exit status too, so `set -e` and
@@ -119,8 +112,61 @@ export function exitCodeForToolResult(result) {
   return result?.isError === true ? 1 : 0;
 }
 
+function takeFlag(args, flag) {
+  return { present: args.includes(flag), rest: args.filter((value) => value !== flag) };
+}
+
+// `pharo-agent <tool> ...`: the answer's text for a reader, or the MCP result
+// with --json. Its schema is fetched only when the words need reading.
+// The MCP server's own tools manage images; from the shell they are the
+// image commands, which an agent that knows the server may not have read.
+const lifecycleTools = new Set(["image_templates", "image_add", "image_start", "image_list", "image_stop"]);
+
+async function runTool([toolName, ...words]) {
+  if (lifecycleTools.has(toolName)) {
+    throw new Error(`${toolName} is pharo-agent image ${toolName.slice("image_".length)} here.`);
+  }
+  const { image, rest: withoutImage } = takeImageOption(words);
+  const json = takeFlag(withoutImage, "--json");
+  const help = takeFlag(json.rest, "--help");
+  if (help.present) {
+    // Help answers before a project or image exists; only the tool's own
+    // arguments need its image.
+    try {
+      const projectRoot = findProjectRoot();
+      console.log(toolUsage(await toolContract(projectRoot, readRunningImage(projectRoot, image), toolName)));
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      console.log(`${usage(["<tool>"])}\n\n${toolName}'s own arguments come from a running image: ${reason}`);
+    }
+    return 0;
+  }
+  const projectRoot = findProjectRoot();
+  const running = readRunningImage(projectRoot, image);
+  const argumentsValue = help.rest.length === 0 ? {}
+    : toolArguments(toolName, help.rest, (await toolContract(projectRoot, running, toolName)).inputSchema);
+  const result = await callImageTool(projectRoot, running, toolName, argumentsValue);
+  console.log(json.present ? JSON.stringify(result, null, 2) : resultText(result));
+  return exitCodeForToolResult(result);
+}
+
+async function listTools(words) {
+  const { image, rest: withoutImage } = takeImageOption(words);
+  const json = takeFlag(withoutImage, "--json");
+  requireNoArguments("list", json.rest);
+  const projectRoot = findProjectRoot();
+  const tools = await listAdvertisedTools(projectRoot, readRunningImage(projectRoot, image));
+  console.log(json.present ? JSON.stringify(tools, null, 2) : toolListing(tools));
+}
+
 export async function main(args) {
   const [command, ...rest] = args;
+  // A snake_case word is an image tool; its own --help reads the tool's
+  // schema, and the word help is a value it may take, not a request for
+  // the CLI's usage.
+  if (command && isToolName(command)) {
+    return runTool(args);
+  }
   // A caller reaching for help is asking the same question wherever the word
   // lands, and `image add --help` answering that it needs an image id is no
   // answer at all.
@@ -143,6 +189,10 @@ export async function main(args) {
     await serveImagesMcp(findProjectRoot, mcpImage);
     return;
   }
+  if (command === "list") {
+    await listTools(rest);
+    return;
+  }
   const projectRoot = findProjectRoot();
   if (command === "image") {
     const [subcommand, ...imageArgs] = rest;
@@ -193,29 +243,5 @@ export async function main(args) {
     }
     throw new Error(`Unsupported image command: ${subcommand ?? ""}\n${usage()}`);
   }
-  const { image, rest: commandArgs } = takeImageOption(rest);
-  if (command === "pharo") {
-    const [toolName, argumentsJson, ...extra] = commandArgs;
-    if (toolName === "list") {
-      if (argumentsJson || extra.length > 0) throw new Error("pharo list does not accept arguments");
-      console.log(JSON.stringify(
-        await listImageTools(projectRoot, readRunningImage(projectRoot, image)),
-        null,
-        2,
-      ));
-      return;
-    }
-    if (!toolName || extra.length > 0) {
-      throw new Error("pharo requires one tool name and an optional JSON object");
-    }
-    const result = await callImageTool(
-      projectRoot,
-      readRunningImage(projectRoot, image),
-      toolName,
-      parseToolArguments(argumentsJson),
-    );
-    console.log(JSON.stringify(result, null, 2));
-    return exitCodeForToolResult(result);
-  }
   throw new Error(`Unsupported command: ${command}\n${usage()}`);
 }

package/src/gateway.js

@@ -1,6 +1,7 @@
 import { createRequire } from "node:module";
 import { PlexusGateway } from "@evref-bl/plexus/gateway";
 import { loadProjectState } from "@evref-bl/plexus";
+import { toolContractFrom } from "./mcpYaml.js";
 import {
   selectRunningImage,
   unappliedPharoMcpPin,
@@ -65,6 +66,38 @@ export async function listImageTools(projectRoot, running) {
   return gateway.refreshPharoTools();
 }
 
+// PLexus adds its routing handle to every schema it lists; a caller never
+// passes it, so the CLI neither offers nor describes it.
+function withoutRouting(tool) {
+  const { required: listed = [], ...schema } = tool.inputSchema ?? {};
+  const properties = { ...(schema.properties ?? {}) };
+  delete properties.mcpServerId;
+  const required = listed.filter((name) => name !== "mcpServerId");
+  return { ...tool, inputSchema: { ...schema, properties, ...(required.length ? { required } : {}) } };
+}
+
+export async function listAdvertisedTools(projectRoot, running) {
+  return (await listImageTools(projectRoot, running)).map(withoutRouting);
+}
+
+/**
+ * A tool's contract: from the advertised list when it is there, otherwise
+ * from tool_get, which reaches the rest of the catalogue.
+ */
+export async function toolContract(projectRoot, running, toolName) {
+  const advertised = (await listAdvertisedTools(projectRoot, running)).find((tool) => tool.name === toolName);
+  if (advertised) return advertised;
+  const answer = /** @type {{ isError?: boolean, content?: { text?: string }[] }} */ (
+    await callImageTool(projectRoot, running, "tool_get", { name: toolName })
+  );
+  const contract = answer?.isError ? undefined
+    : toolContractFrom((answer?.content ?? []).map((part) => part.text ?? "").join("\n"));
+  if (!contract) {
+    throw new Error(`Image ${running.imageId} has no tool ${toolName}. pharo-agent tool_search <words> finds one.`);
+  }
+  return withoutRouting(contract);
+}
+
 export function withImageSelector(tool, defaultImage) {
   const inputSchema = tool.inputSchema ?? {};
   const properties = { ...(inputSchema.properties ?? {}) };

package/src/help.js

@@ -3,81 +3,67 @@ import { hostChoices, hostIds } from "./hosts.js";
 const commands = {
   init: {
     usage: `init --host <${hostChoices()}> [--mount-root <path>]`,
-    description: "Initialize the current project for the required agent host. Write its managed instruction block,\n"
-      + "pharo.AGENTS.md, and workflow skills/references. Re-run to refresh those generated files.\n"
-      + "The mount root defaults to .pharo-agent/mounts; omit --mount-root to keep an existing setting.",
+    description: "Write this project's Pharo guide, skills and references for the host. Re-run to refresh\n"
+      + "them. --mount-root sets where sources mount, .pharo-agent/mounts by default.",
     example: `init --host ${hostIds[0]}`,
   },
   "image list": {
     usage: "image list",
-    description: "List the project's declared images and the default one, with the mount and\n"
-      + "projection port of each image this project has running. An image this project\n"
-      + "started that has since exited is listed as exited.",
+    description: "List the declared images, the default, and the mount and port of each running one.",
     example: "image list",
   },
   "image templates": {
     usage: "image templates",
-    description: "List available launcher templates and their categories. A name in several categories\n"
-      + "needs --category when passed to image add.",
+    description: "List the templates images can be made from, with their categories.",
     example: "image templates",
   },
   "image add": {
     usage: "image add <id> --template <name> [--category <name>] [--profile <id>]",
-    description: "Declare an image with a required id and template name; image start creates it later.\n"
-      + "Use --category for an ambiguous template name and --profile to choose a launcher profile.\n"
-      + "The first declared image becomes the default.",
-    example: "image add dev --template '<template name>'",
+    description: "Declare an image; image start creates it. Name it after what it is for, like a branch.\n"
+      + "The first declared image is the default. --category is for a name two categories offer.",
+    example: "image add pretty-print-formatter --template '<template name>'",
   },
   "image use": {
     usage: "image use <id>",
-    description: "Make the required declared image the project's default. It may already be running.",
+    description: "Make an image the default.",
     example: "image use dev",
   },
   "image remove": {
     usage: "image remove <id>",
-    description: "Remove the required image declaration. Stop the image first. Its image files are kept.\n"
-      + "Removing the default image clears the default selection.",
+    description: "Drop an image's declaration. Stop it first; its files are kept.",
     example: "image remove dev",
   },
   "image start": {
     usage: "image start [<id>]",
-    description: "Create if needed and start an image with its Pharo tools. Omit the id to use the\n"
-      + "project's default image. Images already running stay running. A source projection is\n"
-      + "mounted on macOS with fuse-t; elsewhere the image starts without one and says so.\n"
-      + "Pharo versions outside the MCP support range start without tools or a projection.",
+    description: "Create if needed and start an image, the default one without an id. Others keep running.\n"
+      + "On macOS and Linux its source mounts as files, unless PHARO_AGENT_PROJECTION=off.",
     example: "image start dev",
   },
   "image stop": {
     usage: "image stop [<id>] [--all]",
-    description: "Stop the named image and any source projection it has, or the project's default\n"
-      + "image when no id is given. Use --all to stop every image this project started.",
+    description: "Stop an image and its source mount, the default one without an id, or --all of them.",
     example: "image stop dev",
   },
+  list: {
+    usage: "list [--image <id>] [--json]",
+    description: "List a running image's advertised tools, one line each. tool_search finds the rest.",
+    example: "list",
+  },
+  "<tool>": {
+    usage: "<tool> [<value>] [--<argument> <value>]... [--image <id>] [--json]",
+    description: "Call an image tool. Its arguments are flags, - reads a value from stdin, and\n"
+      + "<tool> --help lists them. Prints the answer's text, or the MCP result with --json.",
+    example: "class_get Point",
+  },
   mcp: {
     usage: "mcp [--image <id>]",
-    description: "Serve this project's images as a command-scoped stdio MCP server. Omit\n"
-      + "--image to use the project's default image. It starts whether or not an image\n"
-      + "is running: image_start starts one and the image's own tools join the list. The\n"
-      + "server exits with this command, and the plugin's .mcp.json starts it for a host.",
+    description: "Serve this project's images as a stdio MCP server, as the plugin does for a host.",
     example: "mcp --image dev",
   },
-  "pharo list": {
-    usage: "pharo list [--image <id>]",
-    description: "List a running image's advertised tools. Omit --image to use the project's default image.\n"
-      + "Use tool_search and tool_get to discover and inspect the rest of its catalogue.",
-    example: "pharo list",
-  },
-  pharo: {
-    usage: "pharo <tool> [arguments-json] [--image <id>]",
-    description: "Call a tool in a running image. Arguments must be a JSON object and default to {}.\n"
-      + "Omit --image to use the project's default image. Inspect the tool's schema with tool_get\n"
-      + "before calling it; a failed tool result makes the command exit unsuccessfully.",
-    example: 'pharo tool_get \'{"name":"class_search"}\'',
-  },
 };
 
 export function usage(args = []) {
-  const key = ["image", "pharo"].includes(args[0]) && args[1]
+  const key = args[0] === "image" && args[1]
     ? `${args[0]} ${args[1]}`
     : args[0];
   const command = Object.hasOwn(commands, key) ? commands[key]

package/src/hosts.js

@@ -4,7 +4,9 @@
 export const supportedHosts = [
   { id: "claude", name: "Claude Code", guide: "CLAUDE.md", plugin: true },
   { id: "codex", name: "Codex", guide: "AGENTS.md", plugin: true },
-  { id: "opencode", name: "OpenCode", guide: "AGENTS.md", plugin: false },
+  // No plugin manifest to declare the MCP server in: init writes it into the
+  // project's own configuration, which OpenCode reads for that project only.
+  { id: "opencode", name: "OpenCode", guide: "AGENTS.md", plugin: false, serverConfig: "opencode.json" },
 ];
 
 export const hostIds = supportedHosts.map((host) => host.id);

package/src/images.js

@@ -2,6 +2,7 @@ import { declareProjectImage, removeProjectImage } from "@evref-bl/plexus";
 import { configuredImages } from "./project.js";
 import {
   defaultImageId,
+  notConfigured,
   readConfig,
   readRunningImages,
   recordedImageIsRunning,
@@ -93,7 +94,7 @@ export function addImage(projectRoot, request) {
 
 export function useImage(projectRoot, id) {
   if (!configuredImages(projectRoot).some((image) => image.id === id)) {
-    throw new Error(`Image ${id} is not configured.`);
+    throw notConfigured(projectRoot, id);
   }
   writeConfig(projectRoot, { ...readConfig(projectRoot), defaultImage: id });
   return { defaultImage: id };
@@ -101,7 +102,7 @@ export function useImage(projectRoot, id) {
 
 export function removeImage(projectRoot, id) {
   if (!configuredImages(projectRoot).some((image) => image.id === id)) {
-    throw new Error(`Image ${id} is not configured.`);
+    throw notConfigured(projectRoot, id);
   }
   assertNotRunning(projectRoot, id, "removing it");
   removeProjectImage(projectRoot, id);