@evref-bl/pharo-agent 0.0.0-stage → 0.1.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,14 @@
+{
+  "name": "pharo-agent",
+  "displayName": "Pharo Agent",
+  "version": "0.1.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,46 @@
-# 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.
+
+The project must already contain a `plexus.project.json` that declares one
+agent-facing image. Initialize it 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.
+
+`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.1.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.2.1",
+    "@evref-bl/plexus-gateway": "0.2.1",
+    "@modelcontextprotocol/sdk": "1.32.1"
+  }
+}

package/plugin.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "pharo-agent",
+  "version": "0.1.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,19 @@
+---
+name: pharo-setup
+description: Enable Pharo image tooling in the current PLexus 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.1.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.
+
+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,112 @@
+import { initialize } from "./init.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 usage() {
+  return [
+    "Usage:",
+    "  pharo-agent init --host <codex|claude|opencode> [--mount-root <path>]",
+    "  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 === "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/init.js

@@ -0,0 +1,138 @@
+import fs from "node:fs";
+import path from "node:path";
+import { templateDirectory as mcpTemplateDirectory } from "@evref-bl/pharo-mcp";
+import { findProjectRoot, pluginDirectory } 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
+
+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.
+`;
+}
+
+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 = findProjectRoot(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));
+  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 };
+}

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,39 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function findProjectRoot(start = process.cwd()) {
+  let directory = path.resolve(start);
+
+  while (true) {
+    if (fs.existsSync(path.join(directory, "plexus.project.json"))) {
+      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 pluginDirectory(projectRoot) {
+  return path.join(projectRoot, ".pharo-agent");
+}
+
+export function configuredActiveImageId(projectRoot) {
+  const configPath = path.join(projectRoot, "plexus.project.json");
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+  } catch (error) {
+    throw new Error(`Cannot read ${configPath}: ${error.message}`);
+  }
+  const images = Array.isArray(config.images) ? config.images.filter((image) => image?.active) : [];
+  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("'", "''")}'`;
+}