@evref-bl/pharo-agent 0.12.1 → 0.13.0

package/.claude-plugin/plugin.json

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

package/.mcp.json

@@ -1,12 +1,8 @@
 {
   "mcpServers": {
-    "image": {
-      "command": "npx",
-      "args": [
-        "--yes",
-        "@evref-bl/pharo-agent@0.12.1",
-        "mcp"
-      ]
+    "pharo": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/bin/pharo-agent.js", "mcp"]
     }
   }
 }

package/README.md

@@ -1,8 +1,44 @@
 # pharo-agent
 
-`pharo-agent` gives a coding agent a live Pharo image: semantic tools over MCP,
-and the image's source projected as files it can read and edit. It works with
-Claude Code, Codex and OpenCode.
+`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.
+
+It works with Claude Code, Codex and OpenCode.
+
+## What it is made of
+
+This plugin is the glue. Three projects do the work, and each is useful on its
+own:
+
+- [PLexus](https://github.com/Evref-BL/PLexus) drives Pharo Launcher. It
+  creates, starts and stops a project's images, keeps their state outside the
+  images, and forwards MCP calls to the server running in each one.
+- [MCP for Pharo](https://github.com/Evref-BL/MCP) is that server. It works
+  through Pharo's own compiler, refactorings, SUnit, Iceberg and Epicea rather
+  than patching exported text, and it maintains the Pharo guidance a project
+  gets.
+- [pharo-image-fs](https://github.com/Evref-BL/pharo-image-fs) projects a live
+  image's source as a filesystem, so ordinary file tools edit the image
+  itself.
+
+The plugin pins one released version of each, so a project gets a set that was
+tested together, and gives the agent one command surface over the lot.
+
+## Requirements
+
+- 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.
+
+The image tools cover Pharo 12 to 15. An image outside that range still
+starts, and says what it will not have.
 
 ## Setup
 
@@ -14,57 +50,64 @@ In Claude Code, install it as a plugin:
 ```
 
 Then ask the agent to enable Pharo tooling in a project. The plugin carries a
-setup skill that runs the command below for you, and declares the `image` MCP
-server, so the running image's tools reach the chat without a server
-configured by hand. [Hosts](docs/hosts.md) covers enabling it per project
-rather than everywhere.
+setup skill that does it, and declares the `pharo` MCP server, so a running
+image's tools reach the chat with nothing configured by hand.
+[Hosts](docs/hosts.md) covers enabling it per project rather than everywhere.
 
-Any host can run the CLI instead, which is the whole of the setup either way.
-In the project directory:
+Any host can run the CLI instead. In the project directory, once:
 
 ```sh
 npx --yes @evref-bl/pharo-agent init --host <claude|codex|opencode>
 ```
 
-That is all of it. `init` writes the project's Pharo guidance and copies the
-workflow skills that guidance refers to. From there the agent registers the
-image the project needs, starts it and uses its tools by following what was
-written; ask it for Pharo work as you would for anything else.
-
-## Refreshing an existing project
-
-After upgrading the plugin/CLI through your usual installation method, re-run
-`pharo-agent init --host <claude|codex|opencode>` from the project root with
-the same host. This refreshes the generated guidance, skills, and references
-using that CLI version's pinned templates. Image declarations, existing plugin
-settings, and guidance outside the host's managed block are preserved when
-you omit `--mount-root`.
-
-Generated/copied files are overwritten, so keep project-specific instructions
-outside them. Refreshing project files does not upgrade the installed package
-or update, restart, or save existing images. See [Hosts](docs/hosts.md) for
-the file ownership rules and [Images](docs/images.md) for image-side MCP updates.
-
-## Requirements
-
-Node 22.12 or later.
-
-Images and their Pharo tools run anywhere Node does. The source projection is
-the exception: it needs macOS with [fuse-t](https://www.fuse-t.org/), whose
-daemon is downloaded for you. Everywhere else an image starts with its tools
-and says that the projection is not available, rather than failing.
-
 ## What the agent gets
 
-Use `pharo-agent --help` for the command overview, or append `--help` to a
-command for its options, defaults, and an example: `pharo-agent init --help`
-or `pharo-agent image add --help`. Help works before project setup.
-
-Reference, for reading rather than typing: these are the commands the guidance
-hands to the agent.
-
-- [Hosts](docs/hosts.md) — what `init` writes, and installing as a plugin.
+**The launcher.** `image templates` names every template the installation
+offers. `image add <id> --template <name>` declares an image, and
+`image start <id>` creates it from that template the first time and starts it.
+A project can declare as many images as it likes — one per Pharo version, one
+to throw away — and run them at once; `image list` says what is declared and
+what is running. [Images](docs/images.md) has the rest.
+
+**The tools of each running image.** Classes, methods, senders, tests and
+evaluation are advertised; the fuller catalogue, such as packages,
+repositories, change history and debuggers, is searched rather than listed, so
+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
+`.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.
+
+**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
+Pharo work only, so Pharo instructions stay out of unrelated chats. The guide
+and what it refers to are maintained by the MCP project and copied from the
+release this plugin pins. [Hosts](docs/hosts.md) lists the paths it owns.
+
+## Refreshing after an upgrade
+
+Upgrade the plugin the way you installed it, then run the setup command again
+in the project, naming the same host. That rewrites the generated guide and
+the files copied with it, from the templates the new version pins.
+
+Image declarations, runtime state and settings are kept, as long as you omit
+`--mount-root`, and so is anything outside the block the plugin marks as its
+own. Generated and copied files are overwritten, so keep project-specific
+instructions out of them. Refreshing a project upgrades neither the installed
+plugin nor the code inside a running image; [Images](docs/images.md) covers
+the image side.
+
+## Reading further
+
+`pharo-agent --help` gives the command overview, and `--help` on a command
+gives its options, defaults and an example. Help works before a project is set
+up.
+
+- [Hosts](docs/hosts.md) — what setup writes, and installing as a plugin.
 - [Images](docs/images.md) — templates and categories, several images at once,
   Pharo versions outside the MCP range.
-- [Tools](docs/tools.md) — the advertised surface, finding the rest, and the
-  stdio bundle.
+- [Tools](docs/tools.md) — the advertised surface, finding the rest, the stdio
+  bundle, and serving a different MCP.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evref-bl/pharo-agent",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "private": false,
   "description": "Terminal-first Pharo integration for coding agents.",
   "license": "Apache-2.0",

package/plugin.json

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

package/skills/pharo-setup/SKILL.md

@@ -8,7 +8,7 @@ Run this only when the user asks to enable or refresh Pharo tooling in this proj
 From the project root, run the released CLI that matches this plugin:
 
 ```sh
-npx --yes @evref-bl/pharo-agent@0.12.1 init --host claude
+npx --yes @evref-bl/pharo-agent@0.13.0 init --host claude
 ```
 
 Name the host this chat runs in: `--host claude` in Claude Code,

package/src/init.js

@@ -120,7 +120,9 @@ 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 image start\`:
+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:
 
 \`\`\`sh
 pharo-agent image templates
@@ -142,8 +144,9 @@ 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,
+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.

package/src/mcpServer.js

@@ -11,8 +11,8 @@ import {
   version,
   withImageSelector,
 } from "./gateway.js";
-import { listImages } from "./images.js";
-import { startAgentImage, stopAgentImage } from "./live.js";
+import { addImage, listImages } from "./images.js";
+import { listImageTemplates, startAgentImage, stopAgentImage } from "./live.js";
 import { readRunningImage } from "./runtime.js";
 
 // The host loads only tool names and these instructions at session start and
@@ -26,15 +26,57 @@ 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.
+what is already running. A project that declares no image yet needs
+image_templates and image_add first.
 
 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 = [
+// 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
+// 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 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.",
+    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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description: "Short id this project calls the image by, such as dev.",
+        },
+        template: {
+          type: "string",
+          description: "Template name, exactly as image_templates gives it.",
+        },
+        category: {
+          type: "string",
+          description:
+            "Template category. Needed only for a name two categories offer.",
+        },
+        profile: {
+          type: "string",
+          description: "Pharo Launcher profile to create the image under.",
+        },
+      },
+      required: ["id", "template"],
+    },
+  },
   {
     name: "image_start",
     description:
@@ -95,6 +137,20 @@ async function runningImageTools(projectRoot, defaultImage) {
     .map((tool) => withImageSelector(tool, running.imageId));
 }
 
+// A schema is a description, not a guard: nothing between the model and here
+// enforces it, and a declaration missing its template would otherwise fail
+// somewhere further in, naming a field the caller never saw.
+function declarationFrom(argumentsValue) {
+  const { id, template, category, profile } = argumentsValue;
+  if (typeof id !== "string" || id === "") {
+    throw new Error("image_add needs the id this project will call the image by.");
+  }
+  if (typeof template !== "string" || template === "") {
+    throw new Error("image_add needs a template name, as image_templates gives it.");
+  }
+  return { id, template, category, profile };
+}
+
 export async function serveImagesMcp(resolveProjectRoot, defaultImage) {
   const server = new Server(
     { name: "pharo-agent", version },
@@ -108,10 +164,10 @@ export async function serveImagesMcp(resolveProjectRoot, defaultImage) {
     } 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: projectTools };
     }
     return {
-      tools: [...lifecycleTools, ...(await runningImageTools(projectRoot, defaultImage))],
+      tools: [...projectTools, ...(await runningImageTools(projectRoot, defaultImage))],
     };
   });
 
@@ -121,9 +177,15 @@ export async function serveImagesMcp(resolveProjectRoot, 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
+    // Matched before the image's catalogue: these 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_templates") {
+      return toolResult({ ok: true, ...(await listImageTemplates(projectRoot)) });
+    }
+    if (request.params.name === "image_add") {
+      return toolResult({ ok: true, ...addImage(projectRoot, declarationFrom(argumentsValue)) });
+    }
     if (request.params.name === "image_start") {
       const started = await startAgentImage(projectRoot, selected);
       await server.sendToolListChanged();

package/src/runtime.js

@@ -23,11 +23,18 @@ export function configPath(projectRoot) {
   return path.join(pluginDirectory(projectRoot), "config.json");
 }
 
+// A project can hold a plexus.json this plugin never initialized, and now that
+// an image can be declared from a chat it is reached before `.pharo-agent`
+// exists. An absent settings file is a project with no settings, not an error
+// about a path the caller never named.
 export function readConfig(projectRoot) {
-  return readJson(configPath(projectRoot));
+  const filePath = configPath(projectRoot);
+  if (!fs.existsSync(filePath)) return {};
+  return readJson(filePath);
 }
 
 export function writeConfig(projectRoot, config) {
+  fs.mkdirSync(pluginDirectory(projectRoot), { recursive: true });
   fs.writeFileSync(configPath(projectRoot), `${JSON.stringify(config, null, 2)}\n`);
 }