@evref-bl/pharo-agent 0.14.1 → 0.16.0

package/.claude-plugin/plugin.json

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

package/README.md

@@ -87,6 +87,12 @@ 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.
 
+**A way to report what got in its way.** The plugin's feedback skill has the
+agent look back over the conversation for tool calls that failed, misled it or
+needed a workaround, and draft issues for the tools' maintainers. It offers
+itself at the end of Pharo work where that happened, searches for existing
+issues first, and files only the drafts you approve.
+
 ## Refreshing after an upgrade
 
 Upgrade the plugin the way you installed it, then run the setup command again

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evref-bl/pharo-agent",
-  "version": "0.14.1",
+  "version": "0.16.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.0",
-    "@evref-bl/plexus": "0.14.0",
+    "@evref-bl/pharo-mcp": "3.5.0",
+    "@evref-bl/plexus": "0.15.0",
     "@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.14.1",
+  "version": "0.16.0",
   "description": "Terminal-first Pharo image setup for coding agents.",
   "author": {
     "name": "Evref-BL",

package/skills/pharo-feedback/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: pharo-feedback
+description: Look back on how the Pharo tools served this conversation and propose GitHub issues for what failed, misled you or was missing. Use when the user asks for feedback on the Pharo tools or wants to report a problem with them. At the end of Pharo work in which a tool failed, misled you or needed a workaround, offer it once; never file anything unasked.
+---
+
+# Pharo tool feedback
+
+The Pharo tools improve from what their users run into, and you saw this
+conversation's tool calls more closely than anyone. Turn what got in your way
+into issues the maintainers can act on. Issues are public: file only what the
+user approves.
+
+## Look back
+
+Go over this conversation's calls to the Pharo tools, whether through this
+plugin's MCP tools or the `pharo-agent` command, and keep what the tools did
+wrong:
+
+- a call failed with an error you could not have avoided: an internal error, a
+  Smalltalk exception, a timeout;
+- a call failed on your input, and its description, schema or error message
+  led you there or did not say what was wrong;
+- a search missed a tool that existed, or found it only after several tries;
+- an answer was wrong, partial, too large to use, or said less than you needed;
+- a warning or the Pharo guidance sent you the wrong way;
+- you fell back to `image_evaluate`, a shell or the files because no tool did
+  what you needed;
+- one step took several attempts.
+
+Leave out your own slips that a clear error caught, bugs in the user's project,
+and passing trouble such as a network outage, unless the tool handled it badly.
+If the conversation was summarized, say what you can no longer see rather than
+reconstruct it.
+
+Then ask the user whether a tool got in their way in a way you did not notice.
+
+## Where each one goes
+
+- The image's own tools, from classes, methods and tests to repositories,
+  search and evaluation, and the Pharo guidance copied into the project
+  (`pharo.AGENTS.md`, the `pharo-*` skills and references): `Evref-BL/MCP`.
+- Everything else this plugin brings, such as the `image_*` tools, the source
+  projection, setup, the `pharo-agent` command and the passing of calls between
+  the host and an image: `Evref-BL/pharo-agent-plugin`. Its maintainers move an
+  issue to the component that owns it.
+
+When the project loads an MCP of its own into the image, that project answers
+for the image's tools.
+
+## Before proposing
+
+Look for the same problem among each repository's issues, open and closed:
+
+```sh
+gh issue list --repo Evref-BL/MCP --state all --search "<words>"
+```
+
+Where one exists, propose a comment adding what this conversation showed
+instead of a new issue.
+
+## Drafting
+
+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.16.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.
+- **Expected:** what would have served.
+- **Workaround:** what worked instead, or none.
+- **To reproduce:** the smallest call that shows it.
+
+End with: "Reported through the pharo-agent feedback skill."
+
+Issues are public. Leave out the project's code, class and package names,
+paths, URLs, and anything that identifies the user or their organization.
+Reproduce on Pharo's own classes, such as `Object` or `OrderedCollection`, or
+describe the shape of what you had. When a problem cannot be shown without the
+project's material, say so and let the user decide.
+
+## Propose, then file
+
+Show every draft in full, with its repository, and ask which to file. File only
+those the user names:
+
+```sh
+gh issue create --repo Evref-BL/MCP --title "<title>" --body-file <draft>
+```
+
+Without `gh` or its login, give each draft as a link that opens the form
+already filled, `https://github.com/<owner>/<repo>/issues/new?title=…&body=…`
+with both values URL-encoded, and let the user submit it. A comment on an
+existing issue goes the same way.
+
+Report what was filed, with its link.

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.14.1 init --host claude
+npx --yes @evref-bl/pharo-agent@0.16.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/help.js

@@ -3,75 +3,61 @@ 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 with fuse-t its source mounts as files.",
     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",
   },
   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.",
+    description: "List a running image's advertised tools. tool_search and tool_get find the rest.",
     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.",
+    description: "Call a tool in a running image with a JSON object of arguments, {} by default.\n"
+      + "Read its schema with tool_get first.",
     example: 'pharo tool_get \'{"name":"class_search"}\'',
   },
 };

package/src/init.js

@@ -110,64 +110,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 plugin, 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.
+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.
 
-\`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.
+## Tools
 
-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":"..."}'
-\`\`\`
-
-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.
+With the plugin, an image's tools are MCP tools. Otherwise call one with
+\`pharo-agent pharo <tool> [arguments-json] [--image <id>]\`, or serve them
+with \`pharo-agent mcp\`. An image lists its common tools; \`tool_search\` and
+\`tool_get\` find the rest. On macOS with fuse-t, \`image start\` also mounts
+the source under \`.pharo-agent/mounts\`.
 
 ${pharoRouting()}
 `;

package/src/live.js

@@ -22,7 +22,7 @@ import {
   writeRunningImages,
 } from "./runtime.js";
 
-export const pifsRelease = "v0.10.1";
+export const pifsRelease = "v0.10.3";
 
 // 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

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 with fuse-t 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.",
         },
       },
     },