@evref-bl/pharo-agent 0.0.0-stage → 0.2.0

package/.agents/plugins/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "evref-bl",
+  "interface": {
+    "displayName": "Evref-BL"
+  },
+  "plugins": [
+    {
+      "name": "pharo-agent",
+      "source": "./",
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Developer Tools"
+    }
+  ]
+}

package/.claude-plugin/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "evref-bl",
+  "owner": {
+    "name": "Evref-BL"
+  },
+  "plugins": [
+    {
+      "name": "pharo-agent",
+      "source": "./"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "pharo-agent",
+  "displayName": "Pharo Agent",
+  "version": "0.2.0",
+  "description": "Terminal-first Pharo image setup for coding agents.",
+  "author": {
+    "name": "Evref-BL",
+    "url": "https://github.com/Evref-BL"
+  },
+  "homepage": "https://github.com/Evref-BL/pharo-agent-plugin",
+  "repository": "https://github.com/Evref-BL/pharo-agent-plugin",
+  "license": "Apache-2.0",
+  "keywords": [
+    "pharo",
+    "smalltalk",
+    "mcp"
+  ]
+}

package/LICENSE

@@ -0,0 +1,7 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+This project is licensed under the Apache License, Version 2.0.

package/README.md

@@ -1,3 +1,61 @@
-# Temporary Holding Version
+# pharo-agent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`pharo-agent` is a terminal-first Pharo integration for Codex, Claude Code, and
+OpenCode. It has one small setup skill; a project receives the full Pharo
+guidance only after setup.
+
+Initialize the current directory for one selected agent host:
+
+```sh
+npx --yes @evref-bl/pharo-agent init --host codex
+```
+
+It writes a small conditional instruction block, `pharo.AGENTS.md`, and copies
+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
+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.
+
+Register the image the project needs before the first `open`:
+
+```sh
+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.
+
+Pass `--mount-root <path>` to `init` to use a different projection root.
+
+## Requirements
+
+PIFS currently supports the macOS workflow and needs
+[fuse-t](https://www.fuse-t.org/). Its matching daemon is downloaded by PIFS;
+Go is not required at runtime.
+
+The CLI pins released MCP and PLexus dependencies. PLexus, in turn, pins the
+MCP release used to prepare the image; PIFS is loaded at its own exact release
+from the image.
+
+## Host setup
+
+Codex and Claude Code can install the repository as a plugin. Its only global
+skill initializes the current project; it does not add an MCP server or the
+Pharo workflow catalogue to every chat. OpenCode uses the same CLI command
+with `--host opencode`.
+
+After initialization, the selected host guide says to read
+`pharo.AGENTS.md` only for Pharo work. That guide points to local workflow
+skills and references on demand. In the chat that runs setup, read that file
+before beginning Pharo work; later chats load the conditional guidance normally.

package/bin/pharo-agent.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+
+main(process.argv.slice(2)).catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@evref-bl/pharo-agent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "private": false,
+  "description": "Terminal-first Pharo integration for coding agents.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Evref-BL/pharo-agent-plugin.git"
+  },
+  "type": "module",
+  "bin": {
+    "pharo-agent": "bin/pharo-agent.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "plugin.json",
+    ".agents",
+    ".claude-plugin",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "check": "node --check bin/pharo-agent.js && node --check src/*.js",
+    "package:check": "npm pack --dry-run",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@evref-bl/pharo-mcp": "1.4.1",
+    "@evref-bl/plexus": "0.3.0",
+    "@evref-bl/plexus-gateway": "0.3.0",
+    "@modelcontextprotocol/sdk": "1.32.1"
+  }
+}

package/plugin.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "pharo-agent",
+  "version": "0.2.0",
+  "description": "Terminal-first Pharo image setup for coding agents.",
+  "author": {
+    "name": "Evref-BL",
+    "url": "https://github.com/Evref-BL"
+  },
+  "homepage": "https://github.com/Evref-BL/pharo-agent-plugin",
+  "repository": "https://github.com/Evref-BL/pharo-agent-plugin",
+  "license": "Apache-2.0",
+  "keywords": [
+    "pharo",
+    "smalltalk",
+    "mcp"
+  ],
+  "extensions": {
+    "com.openai": {
+      "requires_local_executor": true,
+      "onboardingSkill": "./skills/pharo-setup/SKILL.md"
+    }
+  }
+}

package/skills/pharo-setup/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: pharo-setup
+description: Enable Pharo image tooling in the current Pharo project.
+---
+
+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.0 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
+no image when it is absent. Register one before the first `pharo-agent open`:
+
+```sh
+pharo-agent image list
+pharo-agent image add dev --template '<launcher template name>'
+```
+
+After setup, read `pharo.AGENTS.md` in this chat before doing Pharo work. A
+new chat picks up the conditional project guidance automatically.

package/src/cli.js

@@ -0,0 +1,165 @@
+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 { findProjectRoot } from "./project.js";
+import { readActive } from "./runtime.js";
+
+function parseInit(args) {
+  let host;
+  let mountRoot;
+  for (let index = 0; index < args.length; index += 1) {
+    const option = args[index];
+    if (option === "--host" || option === "--mount-root") {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error(`${option} requires a value`);
+      }
+      if (option === "--host") host = value;
+      else mountRoot = value;
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown init option: ${option}`);
+  }
+  if (!host) throw new Error("init requires --host <codex|claude|opencode>");
+  return { host, mountRoot };
+}
+
+function parseImageAdd(args) {
+  const [id, ...rest] = args;
+  if (!id || id.startsWith("--")) {
+    throw new Error("image add requires an image id");
+  }
+  const parsed = { id };
+  const options = { "--template": "template", "--category": "category", "--profile": "profile" };
+  for (let index = 0; index < rest.length; index += 1) {
+    const option = rest[index];
+    const key = options[option];
+    if (!key) {
+      throw new Error(`Unknown image add option: ${option}`);
+    }
+    const value = rest[index + 1];
+    if (!value) {
+      throw new Error(`${option} requires a value`);
+    }
+    parsed[key] = value;
+    index += 1;
+  }
+  if (!parsed.template) {
+    throw new Error("image add requires --template <name>");
+  }
+  return parsed;
+}
+
+function usage() {
+  return [
+    "Usage:",
+    "  pharo-agent init --host <codex|claude|opencode> [--mount-root <path>]",
+    "  pharo-agent image list",
+    "  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 status",
+    "  pharo-agent close",
+    "  pharo-agent mcp",
+    "  pharo-agent pharo list",
+    "  pharo-agent pharo <tool> [arguments-json]",
+  ].join("\n");
+}
+
+function requireNoArguments(command, args) {
+  if (args.length > 0) {
+    throw new Error(`${command} does not accept arguments`);
+  }
+}
+
+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;
+}
+
+export async function main(args) {
+  const [command, ...rest] = args;
+  if (command === "init") {
+    const result = initialize(parseInit(rest));
+    console.log(JSON.stringify({ ok: true, ...result }, null, 2));
+    return;
+  }
+  if (!command || command === "--help" || command === "help") {
+    console.log(usage());
+    return;
+  }
+  const projectRoot = findProjectRoot();
+  if (command === "image") {
+    const [subcommand, ...imageArgs] = rest;
+    if (subcommand === "list") {
+      requireNoArguments("image list", imageArgs);
+      console.log(JSON.stringify({ ok: true, ...listImages(projectRoot) }, null, 2));
+      return;
+    }
+    if (subcommand === "add") {
+      console.log(JSON.stringify({ ok: true, ...addImage(projectRoot, parseImageAdd(imageArgs)) }, null, 2));
+      return;
+    }
+    if (subcommand === "use" || subcommand === "remove") {
+      const [id, ...extra] = imageArgs;
+      if (!id || extra.length > 0) {
+        throw new Error(`image ${subcommand} requires one image id`);
+      }
+      const result = subcommand === "use" ? useImage(projectRoot, id) : removeImage(projectRoot, id);
+      console.log(JSON.stringify({ ok: true, ...result }, null, 2));
+      return;
+    }
+    throw new Error(`Unsupported image command: ${subcommand ?? ""}\n${usage()}`);
+  }
+  if (command === "open") {
+    requireNoArguments(command, rest);
+    console.log(JSON.stringify({ ok: true, ...(await openAgentImage(projectRoot)) }, null, 2));
+    return;
+  }
+  if (command === "close") {
+    requireNoArguments(command, rest);
+    console.log(JSON.stringify({ ok: true, ...(await closeAgentImage(projectRoot)) }, null, 2));
+    return;
+  }
+  if (command === "status") {
+    requireNoArguments(command, rest);
+    console.log(JSON.stringify({ ok: true, ...readActive(projectRoot) }, null, 2));
+    return;
+  }
+  if (command === "mcp") {
+    requireNoArguments(command, rest);
+    await serveActiveMcp(projectRoot, readActive(projectRoot));
+    return;
+  }
+  if (command === "pharo") {
+    const [toolName, argumentsJson, ...extra] = rest;
+    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));
+      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(
+      projectRoot,
+      readActive(projectRoot),
+      toolName,
+      parseToolArguments(argumentsJson),
+    ), null, 2));
+    return;
+  }
+  throw new Error(`Unsupported command: ${command}\n${usage()}`);
+}

package/src/gateway.js

@@ -0,0 +1,53 @@
+import { PlexusGateway } from "@evref-bl/plexus-gateway";
+import { createGatewayServerWithOptions } from "@evref-bl/plexus-gateway";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { readJson, 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.");
+  }
+  const gateway = new PlexusGateway({
+    pharoScope: {
+      projectId: state.projectId,
+      workspaceId: state.workspaceId,
+      targetId: state.targetId,
+    },
+    pharoToolSchemaMcpServerId: mcpServerId,
+  });
+  const registered = await gateway.registerProjectRoute({
+    projectRoot,
+    statePath: active.statePath,
+    state,
+  });
+  if (!registered.ok) {
+    throw new Error(registered.error ?? "Cannot register the PLexus route.");
+  }
+  return { gateway, mcpServerId };
+}
+
+export async function callActiveTool(projectRoot, active, toolName, argumentsValue) {
+  const { gateway, mcpServerId } = await activeGateway(projectRoot, active);
+  const result = await gateway.routeToImage({
+    mcpServerId,
+    toolName,
+    arguments: argumentsValue,
+  });
+  if (!result.ok) {
+    throw new Error(result.error ?? `Pharo tool ${toolName} failed.`);
+  }
+  return result.data;
+}
+
+export async function listActiveTools(projectRoot, active) {
+  const { gateway } = await activeGateway(projectRoot, active);
+  return gateway.refreshPharoTools();
+}
+
+export async function serveActiveMcp(projectRoot, active) {
+  const { gateway, mcpServerId } = await activeGateway(projectRoot, active);
+  const server = createGatewayServerWithOptions(gateway, { fixedMcpServerId: mcpServerId });
+  await server.connect(new StdioServerTransport());
+}

package/src/images.js

@@ -0,0 +1,95 @@
+import fs from "node:fs";
+import {
+  configuredImages,
+  projectIdentity,
+  readProjectConfig,
+  writeProjectConfig,
+} from "./project.js";
+import { activePath, readActive } 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) {
+    throw new Error(`Image ${imageId} is open. Run pharo-agent close before ${action}.`);
+  }
+}
+
+function derivedImageName(projectRoot, imageId) {
+  const { name } = projectIdentity(projectRoot);
+  return `${name}-{workspaceId}-${imageId}`;
+}
+
+export function listImages(projectRoot) {
+  return {
+    images: configuredImages(projectRoot).map((image) => ({
+      id: image.id,
+      imageName: image.imageName,
+      active: image.active === true,
+      templateName: image.create?.templateName,
+      templateCategory: image.create?.templateCategory,
+    })),
+  };
+}
+
+export function addImage(projectRoot, { id, template, category, profile }) {
+  const config = readProjectConfig(projectRoot);
+  const images = Array.isArray(config.images) ? config.images : [];
+  if (images.some((image) => image.id === id)) {
+    throw new Error(`Image ${id} is already configured.`);
+  }
+  const imageName = derivedImageName(projectRoot, id);
+  if (images.some((image) => image.imageName === imageName)) {
+    throw new Error(`Image name ${imageName} is already configured.`);
+  }
+
+  const image = {
+    id,
+    imageName,
+    active: !images.some((other) => other.active === true),
+    mcp: { loadScript: defaultLoadScript, loadPolicy: "ifMissing" },
+    create: {
+      kind: "template",
+      ...(profile ? { profileId: profile } : {}),
+      templateName: template,
+      ...(category ? { templateCategory: category } : {}),
+      cleanupPolicy: "workspace_cleanup_only",
+    },
+  };
+  writeProjectConfig(projectRoot, { ...config, images: [...images, image] });
+  return { id, imageName, active: image.active, 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)) {
+    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 };
+}
+
+export function removeImage(projectRoot, id) {
+  const config = readProjectConfig(projectRoot);
+  const images = Array.isArray(config.images) ? config.images : [];
+  if (!images.some((image) => image.id === id)) {
+    throw new Error(`Image ${id} is not configured.`);
+  }
+  assertNoOpenImage(projectRoot, id, "removing it");
+  writeProjectConfig(projectRoot, {
+    ...config,
+    images: images.filter((image) => image.id !== id),
+  });
+  return { removedImageId: id };
+}

package/src/init.js

@@ -0,0 +1,176 @@
+import fs from "node:fs";
+import path from "node:path";
+import { templateDirectory as mcpTemplateDirectory } from "@evref-bl/pharo-mcp";
+import {
+  createProjectConfig,
+  enclosingProjectRoot,
+  pluginDirectory,
+  projectConfigFileName,
+  projectConfigPath,
+} from "./project.js";
+
+const managedStart = "<!-- pharo-agent:begin -->";
+const managedEnd = "<!-- pharo-agent:end -->";
+
+const hostGuide = {
+  claude: "CLAUDE.md",
+  codex: "AGENTS.md",
+  opencode: "AGENTS.md",
+};
+
+function copyDirectory(source, target) {
+  fs.mkdirSync(target, { recursive: true });
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    const sourcePath = path.join(source, entry.name);
+    const targetPath = path.join(target, entry.name);
+    if (entry.isDirectory()) {
+      copyDirectory(sourcePath, targetPath);
+    } else {
+      fs.copyFileSync(sourcePath, targetPath);
+    }
+  }
+}
+
+function assertManagedBlockCanBeUpdated(filePath) {
+  const current = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : "";
+  const start = current.indexOf(managedStart);
+  const end = current.indexOf(managedEnd);
+  if ((start === -1) !== (end === -1) || (end !== -1 && end < start)) {
+    throw new Error(`Cannot update incomplete pharo-agent block in ${filePath}`);
+  }
+}
+
+function updateManagedBlock(filePath, content) {
+  assertManagedBlockCanBeUpdated(filePath);
+  const current = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : "";
+  const start = current.indexOf(managedStart);
+  const end = current.indexOf(managedEnd);
+
+  const block = `${managedStart}\n${content}\n${managedEnd}\n`;
+  const updated = start === -1
+    ? `${current}${current && !current.endsWith("\n") ? "\n" : ""}${block}`
+    : `${current.slice(0, start)}${block}${current.slice(end + managedEnd.length).replace(/^\n?/, "")}`;
+  fs.writeFileSync(filePath, updated);
+}
+
+function writeIfMissing(filePath, content) {
+  if (!fs.existsSync(filePath)) {
+    fs.writeFileSync(filePath, content);
+  }
+}
+
+function assertGeneratedGuideCanBeUpdated(filePath) {
+  if (!fs.existsSync(filePath)) return;
+  const content = fs.readFileSync(filePath, "utf8");
+  if (
+    content.trimEnd() !== pharoGuide().trimEnd()
+    && (!content.includes(managedStart) || !content.includes(managedEnd))
+  ) {
+    throw new Error(`Refusing to replace user-owned ${filePath}`);
+  }
+}
+
+function guidance() {
+  return `# Pharo work\n\nWhen the task uses Pharo, read \`pharo.AGENTS.md\` before acting.\n`;
+}
+
+function pharoGuide() {
+  return `# Pharo project guide
+
+\`plexus.project.json\` declares this project's images. A freshly initialized
+project declares none; register one before the first \`pharo-agent open\`:
+
+\`\`\`sh
+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.
+
+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
+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.
+
+Image, Tonel, Iceberg, disk Git, and host processes are separate states.
+
+## Read first
+
+- Before Pharo source changes, read the project guidance. If absent, read the
+  local [coding rules](.pharo-agent/references/pharo-coding-rules.md) and
+  [coding style](.pharo-agent/references/pharo-coding-style.md).
+- Before loading a project, read
+  [.pharo-agent/skills/pharo-project-load/SKILL.md](.pharo-agent/skills/pharo-project-load/SKILL.md).
+- Before cross-version work, read
+  [.pharo-agent/skills/pharo-version-compat/SKILL.md](.pharo-agent/skills/pharo-version-compat/SKILL.md).
+- Before exporting image changes or changing Git state, read
+  [.pharo-agent/skills/pharo-image-git-handoff/SKILL.md](.pharo-agent/skills/pharo-image-git-handoff/SKILL.md).
+- Before reproducing smalltalkCI or GitHub failures, read
+  [.pharo-agent/skills/pharo-ci-repro/SKILL.md](.pharo-agent/skills/pharo-ci-repro/SKILL.md).
+- Before recovering a stopped standalone image, read
+  [.pharo-agent/skills/pharo-mcp-recovery/SKILL.md](.pharo-agent/skills/pharo-mcp-recovery/SKILL.md).
+- Before debugger sessions or repairs, read the local
+  [debugging guide](.pharo-agent/references/debugging.md).
+
+## Workflow
+
+1. Inspect the tool schema before acting; do not rely on remembered names.
+2. Prefer the least-mutating dedicated tool; use \`image_evaluate\` only when
+   no dedicated tool fits.
+3. Verify identity before mutation, make the narrowest change, then run focused
+   tests.
+4. Use the image-to-Git handoff skill before export or commit.
+`;
+}
+
+function resolveInitProjectRoot(cwd) {
+  const projectRoot = path.resolve(cwd);
+  if (fs.existsSync(projectConfigPath(projectRoot))) {
+    return { projectRoot, createdProjectConfig: false };
+  }
+
+  const enclosing = enclosingProjectRoot(projectRoot);
+  if (enclosing) {
+    throw new Error(
+      `${projectRoot} is inside the PLexus project at ${enclosing}. `
+        + `Initialize that project root, or remove its ${projectConfigFileName}.`,
+    );
+  }
+
+  return { projectRoot, createdProjectConfig: true };
+}
+
+export function initialize({ host, mountRoot, cwd = process.cwd() }) {
+  const guideName = hostGuide[host];
+  if (!guideName) {
+    throw new Error("--host must be codex, claude, or opencode");
+  }
+
+  const { projectRoot, createdProjectConfig } = resolveInitProjectRoot(cwd);
+  const directory = pluginDirectory(projectRoot);
+  const configPath = path.join(directory, "config.json");
+  const pharoGuidePath = path.join(projectRoot, "pharo.AGENTS.md");
+  assertGeneratedGuideCanBeUpdated(pharoGuidePath);
+  assertManagedBlockCanBeUpdated(path.join(projectRoot, guideName));
+  if (createdProjectConfig) {
+    createProjectConfig(projectRoot);
+  }
+  fs.mkdirSync(directory, { recursive: true });
+  if (!fs.existsSync(configPath) || mountRoot !== undefined) {
+    fs.writeFileSync(
+      configPath,
+      `${JSON.stringify({ mountRoot: mountRoot ?? ".pharo-agent/mounts" }, null, 2)}\n`,
+    );
+  }
+  writeIfMissing(path.join(directory, ".gitignore"), "mounts/\nruntime/\n");
+  updateManagedBlock(pharoGuidePath, pharoGuide());
+  const templates = mcpTemplateDirectory();
+  copyDirectory(path.join(templates, "pharo-references"), path.join(directory, "references"));
+  copyDirectory(path.join(templates, "pharo-skills"), path.join(directory, "skills"));
+  updateManagedBlock(path.join(projectRoot, guideName), guidance());
+
+  return { projectRoot, guideName, createdProjectConfig };
+}

package/src/live.js

@@ -0,0 +1,88 @@
+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 {
+  activePath,
+  clearActive,
+  readActive,
+  readConfig,
+  resolveMountPath,
+  selectRunningImage,
+  smalltalkString,
+  writeActive,
+} from "./runtime.js";
+
+export const pifsRelease = "v0.4.0";
+
+export function pifsStartCode(mountPath, imageName) {
+  return `Metacello new
+	baseline: 'PharoImageFS';
+	repository: 'github://Evref-BL/pharo-image-fs:${pifsRelease}/src';
+	load: 'Core'.
+(PIFSServer
+	startOn: 0
+	mountAt: ${smalltalkString(mountPath)} asFileReference
+	named: ${smalltalkString(imageName)}) port`;
+}
+
+export function resultPrintString(result) {
+  if (!result || typeof result !== "object") return undefined;
+  if (typeof result.resultPrintString === "string") return result.resultPrintString;
+  for (const value of Object.values(result)) {
+    const found = resultPrintString(value);
+    if (found) return found;
+  }
+  return undefined;
+}
+
+export async function openAgentImage(projectRoot) {
+  if (fs.existsSync(activePath(projectRoot))) {
+    return { alreadyOpen: true, ...readActive(projectRoot) };
+  }
+  const configuredImageId = configuredActiveImageId(projectRoot);
+  const opened = await openProject({ projectRoot, imageIds: [configuredImageId] });
+  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 mountPath = resolveMountPath(projectRoot, readConfig(projectRoot), image.id);
+  fs.mkdirSync(path.dirname(mountPath), { recursive: true });
+  const active = {
+    statePath: opened.statePath,
+    imageId: image.id,
+    mcpServerId,
+    mountPath,
+  };
+  const result = await callActiveTool(projectRoot, active, "image_evaluate", {
+    code: pifsStartCode(mountPath, image.imageName),
+  });
+  const port = Number(resultPrintString(result));
+  if (!Number.isInteger(port) || port < 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 };
+}
+
+export async function closeAgentImage(projectRoot) {
+  const active = readActive(projectRoot);
+  let projectionError;
+  try {
+    await callActiveTool(projectRoot, active, "image_evaluate", {
+      code: `PIFSServer stopOn: ${active.projectionPort}`,
+    });
+  } catch (error) {
+    projectionError = error;
+  }
+  const closed = await closeProject({ projectRoot, imageIds: [active.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) };
+}

package/src/project.js

@@ -0,0 +1,88 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const projectConfigFileName = "plexus.project.json";
+
+export function findProjectRoot(start = process.cwd()) {
+  let directory = path.resolve(start);
+
+  while (true) {
+    if (fs.existsSync(path.join(directory, projectConfigFileName))) {
+      return directory;
+    }
+
+    const parent = path.dirname(directory);
+    if (parent === directory) {
+      throw new Error("No plexus.project.json found above the current directory");
+    }
+    directory = parent;
+  }
+}
+
+export function enclosingProjectRoot(start) {
+  const directory = path.resolve(start);
+  const parent = path.dirname(directory);
+  if (parent === directory) return undefined;
+  try {
+    return findProjectRoot(parent);
+  } catch {
+    return undefined;
+  }
+}
+
+export function projectConfigPath(projectRoot) {
+  return path.join(projectRoot, projectConfigFileName);
+}
+
+export function pluginDirectory(projectRoot) {
+  return path.join(projectRoot, ".pharo-agent");
+}
+
+export function projectIdentity(projectRoot) {
+  const name = path.basename(path.resolve(projectRoot));
+  const id = name
+    .replaceAll(/[^A-Za-z0-9._-]+/g, "-")
+    .replaceAll(/^-+|-+$/g, "")
+    .toLowerCase();
+  return { id: id || "pharo-project", name };
+}
+
+export function readProjectConfig(projectRoot) {
+  const configPath = projectConfigPath(projectRoot);
+  try {
+    return JSON.parse(fs.readFileSync(configPath, "utf8"));
+  } catch (error) {
+    throw new Error(`Cannot read ${configPath}: ${error.message}`);
+  }
+}
+
+export function writeProjectConfig(projectRoot, config) {
+  fs.writeFileSync(projectConfigPath(projectRoot), `${JSON.stringify(config, null, 2)}\n`);
+}
+
+export function createProjectConfig(projectRoot) {
+  const { id, name } = projectIdentity(projectRoot);
+  const config = { id, name, images: [] };
+  writeProjectConfig(projectRoot, config);
+  return config;
+}
+
+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

@@ -0,0 +1,67 @@
+import fs from "node:fs";
+import path from "node:path";
+import { pluginDirectory } from "./project.js";
+
+export function runtimeDirectory(projectRoot) {
+  return path.join(pluginDirectory(projectRoot), "runtime");
+}
+
+export function activePath(projectRoot) {
+  return path.join(runtimeDirectory(projectRoot), "active.json");
+}
+
+export function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch (error) {
+    throw new Error(`Cannot read ${filePath}: ${error.message}`);
+  }
+}
+
+export function readConfig(projectRoot) {
+  return readJson(path.join(pluginDirectory(projectRoot), "config.json"));
+}
+
+export function readActive(projectRoot) {
+  const filePath = activePath(projectRoot);
+  if (!fs.existsSync(filePath)) {
+    throw new Error("No active pharo-agent image. Run pharo-agent open first.");
+  }
+  return readJson(filePath);
+}
+
+export function writeActive(projectRoot, value) {
+  fs.mkdirSync(runtimeDirectory(projectRoot), { recursive: true });
+  fs.writeFileSync(activePath(projectRoot), `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function clearActive(projectRoot) {
+  fs.rmSync(activePath(projectRoot), { force: true });
+}
+
+export function resolveMountPath(projectRoot, config, imageId) {
+  const root = config.mountRoot ?? ".pharo-agent/mounts";
+  return path.resolve(projectRoot, root, imageId);
+}
+
+export function selectRunningImage(state, imageId) {
+  const images = (state.images ?? []).filter(
+    (image) => image.status === "running" && (imageId === undefined || image.id === imageId),
+  );
+  if (images.length !== 1) {
+    throw new Error(
+      `pharo-agent needs exactly one running image; PLexus reported ${images.length}.`,
+    );
+  }
+  const image = images[0];
+  if (!Array.isArray(image.mcpServers) || image.mcpServers.length !== 1) {
+    throw new Error(
+      `Image ${image.id} needs exactly one MCP endpoint; PLexus reported ${image.mcpServers?.length ?? 0}.`,
+    );
+  }
+  return { image, mcpServerId: image.mcpServers[0].id };
+}
+
+export function smalltalkString(value) {
+  return `'${String(value).replaceAll("'", "''")}'`;
+}