@evref-bl/pharo-agent 0.2.1 → 0.3.1

package/.claude-plugin/plugin.json

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

package/README.md

@@ -15,7 +15,7 @@ on-demand Pharo workflow skills and references from the pinned MCP template
 package. It does not install an agent-host MCP server.
 
 `init` acts on the current directory and never searches above it. If that
-directory has no `plexus.project.json`, it creates one that declares the
+directory has no `plexus.json`, it creates one that declares the
 project and no image; an existing one is left untouched. It refuses to run
 inside an enclosing PLexus project rather than initializing that project root.
 
@@ -25,16 +25,23 @@ Register the image the project needs before the first `open`:
 pharo-agent image add dev --template 'Pharo 13.0 - 64bit (stable)'
 ```
 
-`image add` registers a template-created image with the pinned MCP load policy
-and makes it active when no other image is. `image list`, `image use <id>`,
-and `image remove <id>` cover the rest; an open image must be closed before
-its declaration changes.
-
-`open` starts the project image through PLexus, loads PIFS, and mounts its
-projection below `.pharo-agent/mounts`. `close` unmounts the projection and
-closes the PLexus image. `pharo` calls any exposed MCP tool through the same
-project route, while `mcp` exposes that tool surface as a command-scoped stdio
-MCP server.
+`image add` registers a template-created image with the pinned MCP load policy,
+and the first one registered becomes the default. `image list`,
+`image use <id>` (change the default) and `image remove <id>` cover the rest;
+an open image must be closed before its declaration is removed.
+
+`open` starts an image through PLexus, loads PIFS, and mounts its projection
+below `.pharo-agent/mounts`. `close` unmounts the projection and closes the
+PLexus image. `pharo` calls any exposed MCP tool through the same project
+route, while `mcp` exposes that tool surface as a command-scoped stdio MCP
+server.
+
+Several images can be open at once. `open`, `close`, `status`, `pharo` and
+`mcp` all accept `--image <id>`; without it the default image answers, so a
+project with one image never mentions an image at all. `open --image <id>`
+adds an image without closing the others, and `close` without `--image` closes
+every image this project opened. Over `mcp`, each Pharo tool takes the same
+optional `image` argument.
 
 Pass `--mount-root <path>` to `init` to use a different projection root.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evref-bl/pharo-agent",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "private": false,
   "description": "Terminal-first Pharo integration for coding agents.",
   "license": "Apache-2.0",
@@ -31,9 +31,9 @@
     "test": "node --test"
   },
   "dependencies": {
-    "@evref-bl/pharo-mcp": "1.4.1",
-    "@evref-bl/plexus": "0.3.0",
-    "@evref-bl/plexus-gateway": "0.3.0",
+    "@evref-bl/pharo-mcp": "1.5.0",
+    "@evref-bl/plexus": "0.4.1",
+    "@evref-bl/plexus-gateway": "0.4.1",
     "@modelcontextprotocol/sdk": "1.32.1"
   }
 }

package/plugin.json

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

package/skills/pharo-setup/SKILL.md

@@ -8,14 +8,14 @@ Run this only when the user asks to enable Pharo tooling in this project.
 From the project root, run the released CLI that matches this plugin:
 
 ```sh
-npx --yes @evref-bl/pharo-agent@0.2.1 init --host codex
+npx --yes @evref-bl/pharo-agent@0.3.1 init --host codex
 ```
 
 Use `--host claude` in Claude Code and `--host opencode` in OpenCode.
 Do not configure an MCP server in the agent host. The command adds only a
 conditional instruction block, so Pharo guidance stays out of unrelated work.
 
-Setup initializes the current directory, creating `plexus.project.json` with
+Setup initializes the current directory, creating `plexus.json` with
 no image when it is absent. Register one before the first `pharo-agent open`:
 
 ```sh

package/src/cli.js

@@ -1,9 +1,9 @@
 import { initialize } from "./init.js";
 import { addImage, listImages, removeImage, useImage } from "./images.js";
-import { callActiveTool, listActiveTools, serveActiveMcp } from "./gateway.js";
-import { closeAgentImage, openAgentImage } from "./live.js";
+import { callImageTool, listImageTools, serveImagesMcp } from "./gateway.js";
+import { agentImageStatus, closeAgentImage, openAgentImage } from "./live.js";
 import { findProjectRoot } from "./project.js";
-import { readActive } from "./runtime.js";
+import { readOpenImage } from "./runtime.js";
 
 function parseInit(args) {
   let host;
@@ -52,6 +52,16 @@ function parseImageAdd(args) {
   return parsed;
 }
 
+function takeImageOption(args) {
+  const index = args.indexOf("--image");
+  if (index === -1) return { image: undefined, rest: args };
+  const image = args[index + 1];
+  if (!image) {
+    throw new Error("--image requires a value");
+  }
+  return { image, rest: [...args.slice(0, index), ...args.slice(index + 2)] };
+}
+
 function usage() {
   return [
     "Usage:",
@@ -60,12 +70,12 @@ function usage() {
     "  pharo-agent image add <id> --template <name> [--category <name>] [--profile <id>]",
     "  pharo-agent image use <id>",
     "  pharo-agent image remove <id>",
-    "  pharo-agent open",
+    "  pharo-agent open [--image <id>]",
     "  pharo-agent status",
-    "  pharo-agent close",
-    "  pharo-agent mcp",
-    "  pharo-agent pharo list",
-    "  pharo-agent pharo <tool> [arguments-json]",
+    "  pharo-agent close [--image <id>]",
+    "  pharo-agent mcp [--image <id>]",
+    "  pharo-agent pharo list [--image <id>]",
+    "  pharo-agent pharo <tool> [arguments-json] [--image <id>]",
   ].join("\n");
 }
 
@@ -123,39 +133,44 @@ export async function main(args) {
     }
     throw new Error(`Unsupported image command: ${subcommand ?? ""}\n${usage()}`);
   }
+  const { image, rest: commandArgs } = takeImageOption(rest);
   if (command === "open") {
-    requireNoArguments(command, rest);
-    console.log(JSON.stringify({ ok: true, ...(await openAgentImage(projectRoot)) }, null, 2));
+    requireNoArguments(command, commandArgs);
+    console.log(JSON.stringify({ ok: true, ...(await openAgentImage(projectRoot, image)) }, null, 2));
     return;
   }
   if (command === "close") {
-    requireNoArguments(command, rest);
-    console.log(JSON.stringify({ ok: true, ...(await closeAgentImage(projectRoot)) }, null, 2));
+    requireNoArguments(command, commandArgs);
+    console.log(JSON.stringify({ ok: true, ...(await closeAgentImage(projectRoot, image)) }, null, 2));
     return;
   }
   if (command === "status") {
-    requireNoArguments(command, rest);
-    console.log(JSON.stringify({ ok: true, ...readActive(projectRoot) }, null, 2));
+    requireNoArguments(command, commandArgs);
+    console.log(JSON.stringify({ ok: true, ...agentImageStatus(projectRoot) }, null, 2));
     return;
   }
   if (command === "mcp") {
-    requireNoArguments(command, rest);
-    await serveActiveMcp(projectRoot, readActive(projectRoot));
+    requireNoArguments(command, commandArgs);
+    await serveImagesMcp(projectRoot, image);
     return;
   }
   if (command === "pharo") {
-    const [toolName, argumentsJson, ...extra] = rest;
+    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 listActiveTools(projectRoot, readActive(projectRoot)), null, 2));
+      console.log(JSON.stringify(
+        await listImageTools(projectRoot, readOpenImage(projectRoot, image)),
+        null,
+        2,
+      ));
       return;
     }
     if (!toolName || extra.length > 0) {
       throw new Error("pharo requires one tool name and an optional JSON object");
     }
-    console.log(JSON.stringify(await callActiveTool(
+    console.log(JSON.stringify(await callImageTool(
       projectRoot,
-      readActive(projectRoot),
+      readOpenImage(projectRoot, image),
       toolName,
       parseToolArguments(argumentsJson),
     ), null, 2));

package/src/gateway.js

@@ -1,13 +1,17 @@
 import { PlexusGateway } from "@evref-bl/plexus-gateway";
-import { createGatewayServerWithOptions } from "@evref-bl/plexus-gateway";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { readJson, selectRunningImage } from "./runtime.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { readJson, readOpenImage, selectRunningImage } from "./runtime.js";
 
-export async function activeGateway(projectRoot, active) {
-  const state = readJson(active.statePath);
-  const { image, mcpServerId } = selectRunningImage(state, active.imageId);
-  if (image.id !== active.imageId || mcpServerId !== active.mcpServerId) {
-    throw new Error("The active PLexus image changed; run pharo-agent open again.");
+export async function imageGateway(projectRoot, open) {
+  const state = readJson(open.statePath);
+  const { image, mcpServerId } = selectRunningImage(state, open.imageId);
+  if (image.id !== open.imageId || mcpServerId !== open.mcpServerId) {
+    throw new Error(`The PLexus image ${open.imageId} changed; run pharo-agent open again.`);
   }
   const gateway = new PlexusGateway({
     pharoScope: {
@@ -19,7 +23,7 @@ export async function activeGateway(projectRoot, active) {
   });
   const registered = await gateway.registerProjectRoute({
     projectRoot,
-    statePath: active.statePath,
+    statePath: open.statePath,
     state,
   });
   if (!registered.ok) {
@@ -28,8 +32,8 @@ export async function activeGateway(projectRoot, active) {
   return { gateway, mcpServerId };
 }
 
-export async function callActiveTool(projectRoot, active, toolName, argumentsValue) {
-  const { gateway, mcpServerId } = await activeGateway(projectRoot, active);
+export async function callImageTool(projectRoot, open, toolName, argumentsValue) {
+  const { gateway, mcpServerId } = await imageGateway(projectRoot, open);
   const result = await gateway.routeToImage({
     mcpServerId,
     toolName,
@@ -41,13 +45,53 @@ export async function callActiveTool(projectRoot, active, toolName, argumentsVal
   return result.data;
 }
 
-export async function listActiveTools(projectRoot, active) {
-  const { gateway } = await activeGateway(projectRoot, active);
+export async function listImageTools(projectRoot, open) {
+  const { gateway } = await imageGateway(projectRoot, open);
   return gateway.refreshPharoTools();
 }
 
-export async function serveActiveMcp(projectRoot, active) {
-  const { gateway, mcpServerId } = await activeGateway(projectRoot, active);
-  const server = createGatewayServerWithOptions(gateway, { fixedMcpServerId: mcpServerId });
+export function withImageSelector(tool, defaultImage) {
+  const inputSchema = tool.inputSchema ?? {};
+  const properties = { ...(inputSchema.properties ?? {}) };
+  delete properties.mcpServerId;
+  properties.image = {
+    type: "string",
+    description: `Project image to call. Defaults to ${defaultImage}.`,
+  };
+  const required = Array.isArray(inputSchema.required)
+    ? inputSchema.required.filter((value) => value !== "mcpServerId")
+    : [];
+  return { ...tool, inputSchema: { ...inputSchema, properties, required } };
+}
+
+export function toolResult(data) {
+  if (data && typeof data === "object" && Array.isArray(data.content)) {
+    return data;
+  }
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+
+export async function serveImagesMcp(projectRoot, defaultImage) {
+  const defaultOpen = readOpenImage(projectRoot, defaultImage);
+  const tools = (await listImageTools(projectRoot, defaultOpen))
+    .map((tool) => withImageSelector(tool, defaultImage));
+  const toolNames = new Set(tools.map((tool) => tool.name));
+
+  const server = new Server(
+    { name: "pharo-agent", version: "0.0.0" },
+    { capabilities: { tools: {} } },
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (!toolNames.has(request.params.name)) {
+      throw new Error(`Unknown Pharo tool: ${request.params.name}`);
+    }
+    const { image, ...argumentsValue } = request.params.arguments ?? {};
+    const open = readOpenImage(projectRoot, image);
+    return toolResult(
+      await callImageTool(projectRoot, open, request.params.name, argumentsValue),
+    );
+  });
+
   await server.connect(new StdioServerTransport());
 }

package/src/images.js

@@ -1,18 +1,15 @@
-import fs from "node:fs";
 import {
   configuredImages,
   projectIdentity,
   readProjectConfig,
   writeProjectConfig,
 } from "./project.js";
-import { activePath, readActive } from "./runtime.js";
+import { readConfig, readOpenImages, writeConfig } from "./runtime.js";
 
 export const defaultLoadScript = "pharo/load-mcp.st";
 
 function assertNoOpenImage(projectRoot, imageId, action) {
-  if (!fs.existsSync(activePath(projectRoot))) return;
-  const active = readActive(projectRoot);
-  if (active.imageId === imageId) {
+  if (readOpenImages(projectRoot)[imageId]) {
     throw new Error(`Image ${imageId} is open. Run pharo-agent close before ${action}.`);
   }
 }
@@ -23,11 +20,17 @@ function derivedImageName(projectRoot, imageId) {
 }
 
 export function listImages(projectRoot) {
+  const configured = configuredImages(projectRoot);
+  const open = readOpenImages(projectRoot);
+  const defaultImage = readConfig(projectRoot).defaultImage
+    ?? (configured.length === 1 ? configured[0].id : undefined);
   return {
-    images: configuredImages(projectRoot).map((image) => ({
+    ...(defaultImage ? { defaultImage } : {}),
+    images: configured.map((image) => ({
       id: image.id,
       imageName: image.imageName,
-      active: image.active === true,
+      isDefault: image.id === defaultImage,
+      open: Boolean(open[image.id]),
       templateName: image.create?.templateName,
       templateCategory: image.create?.templateCategory,
     })),
@@ -48,7 +51,7 @@ export function addImage(projectRoot, { id, template, category, profile }) {
   const image = {
     id,
     imageName,
-    active: !images.some((other) => other.active === true),
+    active: true,
     mcp: { loadScript: defaultLoadScript, loadPolicy: "ifMissing" },
     create: {
       kind: "template",
@@ -59,25 +62,20 @@ export function addImage(projectRoot, { id, template, category, profile }) {
     },
   };
   writeProjectConfig(projectRoot, { ...config, images: [...images, image] });
-  return { id, imageName, active: image.active, templateName: template };
+  const pluginConfig = readConfig(projectRoot);
+  const isDefault = pluginConfig.defaultImage === undefined && images.length === 0;
+  if (isDefault) {
+    writeConfig(projectRoot, { ...pluginConfig, defaultImage: id });
+  }
+  return { id, imageName, isDefault, templateName: template };
 }
 
 export function useImage(projectRoot, id) {
-  const config = readProjectConfig(projectRoot);
-  const images = Array.isArray(config.images) ? config.images : [];
-  if (!images.some((image) => image.id === id)) {
+  if (!configuredImages(projectRoot).some((image) => image.id === id)) {
     throw new Error(`Image ${id} is not configured.`);
   }
-  for (const image of images) {
-    if (image.active === true && image.id !== id) {
-      assertNoOpenImage(projectRoot, image.id, "switching the active image");
-    }
-  }
-  writeProjectConfig(projectRoot, {
-    ...config,
-    images: images.map((image) => ({ ...image, active: image.id === id })),
-  });
-  return { activeImageId: id };
+  writeConfig(projectRoot, { ...readConfig(projectRoot), defaultImage: id });
+  return { defaultImage: id };
 }
 
 export function removeImage(projectRoot, id) {
@@ -91,5 +89,10 @@ export function removeImage(projectRoot, id) {
     ...config,
     images: images.filter((image) => image.id !== id),
   });
+  const pluginConfig = readConfig(projectRoot);
+  if (pluginConfig.defaultImage === id) {
+    const { defaultImage: _removed, ...rest } = pluginConfig;
+    writeConfig(projectRoot, rest);
+  }
   return { removedImageId: id };
 }

package/src/init.js

@@ -77,7 +77,7 @@ function guidance() {
 function pharoGuide() {
   return `# Pharo project guide
 
-\`plexus.project.json\` declares this project's images. A freshly initialized
+\`plexus.json\` declares this project's images. A freshly initialized
 project declares none; register one before the first \`pharo-agent open\`:
 
 \`\`\`sh
@@ -85,9 +85,9 @@ pharo-agent image list
 pharo-agent image add dev --template '<launcher template name>'
 \`\`\`
 
-\`image add\` makes the first registered image active. \`pharo-agent image use
-<id>\` switches the active image, and \`pharo-agent image remove <id>\` drops a
-declaration. Close an image before changing its declaration.
+\`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. Close an image before removing its declaration.
 
 Use \`pharo-agent open\` before live-image work and edit projected source under
 \`.pharo-agent/mounts\`. Use \`pharo-agent pharo list\` to inspect the complete
@@ -95,6 +95,12 @@ live MCP tool surface and \`pharo-agent pharo <tool> [arguments-json]\` to call
 a tool. \`pharo-agent mcp\` exposes the image as a command-scoped stdio MCP
 server.
 
+Several images can be open at once. Every image-facing command takes
+\`--image <id>\`; without it the default image answers. \`pharo-agent open
+--image <id>\` opens another image without closing the first,
+\`pharo-agent status\` lists what is open, and \`pharo-agent close\` closes
+everything this project opened.
+
 Image, Tonel, Iceberg, disk Git, and host processes are separate states.
 
 ## Read first

package/src/live.js

@@ -1,17 +1,16 @@
 import fs from "node:fs";
 import path from "node:path";
 import { closeProject, openProject } from "@evref-bl/plexus";
-import { callActiveTool } from "./gateway.js";
-import { configuredActiveImageId } from "./project.js";
+import { callImageTool } from "./gateway.js";
 import {
-  activePath,
-  clearActive,
-  readActive,
+  defaultImageId,
   readConfig,
+  readOpenImages,
+  resolveImageId,
   resolveMountPath,
   selectRunningImage,
   smalltalkString,
-  writeActive,
+  writeOpenImages,
 } from "./runtime.js";
 
 export const pifsRelease = "v0.4.0";
@@ -37,52 +36,98 @@ export function resultPrintString(result) {
   return undefined;
 }
 
-export async function openAgentImage(projectRoot) {
-  if (fs.existsSync(activePath(projectRoot))) {
-    return { alreadyOpen: true, ...readActive(projectRoot) };
+export async function openAgentImage(projectRoot, imageId) {
+  const resolved = resolveImageId(projectRoot, imageId);
+  const openImages = readOpenImages(projectRoot);
+  if (openImages[resolved]) {
+    return { alreadyOpen: true, ...openImages[resolved] };
   }
-  const configuredImageId = configuredActiveImageId(projectRoot);
-  const opened = await openProject({ projectRoot, imageIds: [configuredImageId] });
+  const opened = await openProject({ projectRoot, imageIds: [resolved] });
   if (!opened.ok || opened.failures.length > 0) {
     throw new Error(opened.failures.map((failure) => failure.message).join("\n") || "PLexus could not open the project image.");
   }
-  const { image, mcpServerId } = selectRunningImage(opened.state, configuredImageId);
+  const { image, mcpServerId } = selectRunningImage(opened.state, resolved);
   const mountPath = resolveMountPath(projectRoot, readConfig(projectRoot), image.id);
   fs.mkdirSync(path.dirname(mountPath), { recursive: true });
-  const active = {
+  const open = {
     statePath: opened.statePath,
     imageId: image.id,
     mcpServerId,
     mountPath,
   };
-  const result = await callActiveTool(projectRoot, active, "image_evaluate", {
+  const result = await callImageTool(projectRoot, open, "image_evaluate", {
     code: pifsStartCode(mountPath, image.imageName),
   });
-  const port = Number(resultPrintString(result));
-  if (!Number.isInteger(port) || port < 1) {
+  const projectionPort = Number(resultPrintString(result));
+  if (!Number.isInteger(projectionPort) || projectionPort < 1) {
     throw new Error("PIFS started but did not report its projection port.");
   }
-  writeActive(projectRoot, { ...active, projectionPort: port });
-  return { imageId: image.id, mountPath, projectionPort: port };
+  writeOpenImages(projectRoot, { ...openImages, [resolved]: { ...open, projectionPort } });
+  return { imageId: image.id, mountPath, projectionPort };
 }
 
-export async function closeAgentImage(projectRoot) {
-  const active = readActive(projectRoot);
+async function closeOneImage(projectRoot, openImages, imageId) {
+  const open = openImages[imageId];
   let projectionError;
   try {
-    await callActiveTool(projectRoot, active, "image_evaluate", {
-      code: `PIFSServer stopOn: ${active.projectionPort}`,
+    await callImageTool(projectRoot, open, "image_evaluate", {
+      code: `PIFSServer stopOn: ${open.projectionPort}`,
     });
   } catch (error) {
     projectionError = error;
   }
-  const closed = await closeProject({ projectRoot, imageIds: [active.imageId] });
+  const closed = await closeProject({ projectRoot, imageIds: [imageId] });
   if (!closed.ok || closed.failures.length > 0) {
     throw new Error(closed.failures.map((failure) => failure.message).join("\n") || "PLexus could not close the project image.");
   }
-  clearActive(projectRoot);
-  if (projectionError) {
-    throw new Error(`Image closed, but PIFS cleanup failed: ${projectionError.message}`);
+  return { stoppedImages: closed.stoppedImages.map((image) => image.id), projectionError };
+}
+
+export async function closeAgentImage(projectRoot, imageId) {
+  const openImages = readOpenImages(projectRoot);
+  const identifiers = imageId === undefined
+    ? Object.keys(openImages)
+    : [resolveImageId(projectRoot, imageId)];
+  if (identifiers.length === 0) {
+    throw new Error("No open pharo-agent image.");
+  }
+  for (const identifier of identifiers) {
+    if (!openImages[identifier]) {
+      throw new Error(`Image ${identifier} is not open.`);
+    }
+  }
+
+  const stoppedImages = [];
+  const projectionErrors = [];
+  const remaining = { ...openImages };
+  for (const identifier of identifiers) {
+    const closed = await closeOneImage(projectRoot, openImages, identifier);
+    delete remaining[identifier];
+    writeOpenImages(projectRoot, remaining);
+    stoppedImages.push(...closed.stoppedImages);
+    if (closed.projectionError) {
+      projectionErrors.push(`${identifier}: ${closed.projectionError.message}`);
+    }
+  }
+  if (projectionErrors.length > 0) {
+    throw new Error(`Images closed, but PIFS cleanup failed: ${projectionErrors.join("; ")}`);
   }
-  return { stoppedImages: closed.stoppedImages.map((image) => image.id) };
+  return { stoppedImages };
+}
+
+export function agentImageStatus(projectRoot) {
+  const openImages = readOpenImages(projectRoot);
+  let defaultImage;
+  try {
+    defaultImage = defaultImageId(projectRoot);
+  } catch {
+    defaultImage = undefined;
+  }
+  return {
+    ...(defaultImage ? { defaultImage } : {}),
+    images: Object.values(openImages).map((open) => ({
+      ...open,
+      isDefault: open.imageId === defaultImage,
+    })),
+  };
 }

package/src/project.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 
-export const projectConfigFileName = "plexus.project.json";
+export const projectConfigFileName = "plexus.json";
 
 export function findProjectRoot(start = process.cwd()) {
   let directory = path.resolve(start);
@@ -13,7 +13,7 @@ export function findProjectRoot(start = process.cwd()) {
 
     const parent = path.dirname(directory);
     if (parent === directory) {
-      throw new Error("No plexus.project.json found above the current directory");
+      throw new Error("No plexus.json found above the current directory");
     }
     directory = parent;
   }
@@ -71,18 +71,3 @@ export function configuredImages(projectRoot) {
   const config = readProjectConfig(projectRoot);
   return Array.isArray(config.images) ? config.images : [];
 }
-
-export function configuredActiveImageId(projectRoot) {
-  const images = configuredImages(projectRoot).filter((image) => image?.active);
-  if (images.length === 0) {
-    throw new Error(
-      "No active image in plexus.project.json. Register one with pharo-agent image add <id> --template <name>.",
-    );
-  }
-  if (images.length !== 1 || typeof images[0].id !== "string") {
-    throw new Error(
-      `pharo-agent needs exactly one active image in plexus.project.json; found ${images.length}.`,
-    );
-  }
-  return images[0].id;
-}

package/src/runtime.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { pluginDirectory } from "./project.js";
+import { configuredImages, pluginDirectory } from "./project.js";
 
 export function runtimeDirectory(projectRoot) {
   return path.join(pluginDirectory(projectRoot), "runtime");
@@ -18,25 +18,79 @@ export function readJson(filePath) {
   }
 }
 
+export function configPath(projectRoot) {
+  return path.join(pluginDirectory(projectRoot), "config.json");
+}
+
 export function readConfig(projectRoot) {
-  return readJson(path.join(pluginDirectory(projectRoot), "config.json"));
+  return readJson(configPath(projectRoot));
 }
 
-export function readActive(projectRoot) {
+export function writeConfig(projectRoot, config) {
+  fs.writeFileSync(configPath(projectRoot), `${JSON.stringify(config, null, 2)}\n`);
+}
+
+export function readOpenImages(projectRoot) {
   const filePath = activePath(projectRoot);
-  if (!fs.existsSync(filePath)) {
-    throw new Error("No active pharo-agent image. Run pharo-agent open first.");
+  if (!fs.existsSync(filePath)) return {};
+  const recorded = readJson(filePath);
+  if (recorded && typeof recorded.images === "object" && recorded.images !== null) {
+    return recorded.images;
   }
-  return readJson(filePath);
+  return typeof recorded?.imageId === "string" ? { [recorded.imageId]: recorded } : {};
 }
 
-export function writeActive(projectRoot, value) {
+export function writeOpenImages(projectRoot, images) {
+  if (Object.keys(images).length === 0) {
+    fs.rmSync(activePath(projectRoot), { force: true });
+    return;
+  }
   fs.mkdirSync(runtimeDirectory(projectRoot), { recursive: true });
-  fs.writeFileSync(activePath(projectRoot), `${JSON.stringify(value, null, 2)}\n`);
+  fs.writeFileSync(activePath(projectRoot), `${JSON.stringify({ images }, null, 2)}\n`);
+}
+
+export function defaultImageId(projectRoot) {
+  const configured = readConfig(projectRoot).defaultImage;
+  const images = configuredImages(projectRoot);
+  if (typeof configured === "string") {
+    if (!images.some((image) => image.id === configured)) {
+      throw new Error(
+        `The default image ${configured} is not configured. Run pharo-agent image use <id>.`,
+      );
+    }
+    return configured;
+  }
+  if (images.length === 1 && typeof images[0].id === "string") {
+    return images[0].id;
+  }
+  if (images.length === 0) {
+    throw new Error(
+      "No image is configured. Register one with pharo-agent image add <id> --template <name>.",
+    );
+  }
+  throw new Error(
+    `Several images are configured (${images.map((image) => image.id).join(", ")}); `
+      + "choose one with pharo-agent image use <id>, or pass --image <id>.",
+  );
+}
+
+export function resolveImageId(projectRoot, imageId) {
+  if (imageId === undefined) return defaultImageId(projectRoot);
+  if (!configuredImages(projectRoot).some((image) => image.id === imageId)) {
+    throw new Error(`Image ${imageId} is not configured.`);
+  }
+  return imageId;
 }
 
-export function clearActive(projectRoot) {
-  fs.rmSync(activePath(projectRoot), { force: true });
+export function readOpenImage(projectRoot, imageId) {
+  const resolved = resolveImageId(projectRoot, imageId);
+  const open = readOpenImages(projectRoot)[resolved];
+  if (!open) {
+    throw new Error(
+      `Image ${resolved} is not open. Run pharo-agent open${imageId ? ` --image ${resolved}` : ""} first.`,
+    );
+  }
+  return open;
 }
 
 export function resolveMountPath(projectRoot, config, imageId) {
@@ -45,12 +99,15 @@ export function resolveMountPath(projectRoot, config, imageId) {
 }
 
 export function selectRunningImage(state, imageId) {
-  const images = (state.images ?? []).filter(
-    (image) => image.status === "running" && (imageId === undefined || image.id === imageId),
-  );
+  const running = (state.images ?? []).filter((image) => image.status === "running");
+  const images = imageId === undefined
+    ? running
+    : running.filter((image) => image.id === imageId);
   if (images.length !== 1) {
     throw new Error(
-      `pharo-agent needs exactly one running image; PLexus reported ${images.length}.`,
+      imageId === undefined
+        ? `pharo-agent needs exactly one running image; PLexus reported ${images.length}.`
+        : `PLexus reports ${images.length} running images with id ${imageId}.`,
     );
   }
   const image = images[0];