@evref-bl/pharo-agent 0.12.2 → 0.13.0

package/.claude-plugin/plugin.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evref-bl/pharo-agent",
-  "version": "0.12.2",
+  "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.2",
+  "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.2 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`);
 }