@retrotech71/appleii-agent 1.0.8 → 1.0.9

package/README.md

@@ -36,11 +36,70 @@ npm install
 
 ## Configuration
 
-Add to your MCP client configuration. For Claude Code, edit `~/.claude/mcp.json`:
+### For Claude Desktop
 
-### Option 1: Using bunx (Recommended)
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):
 
-Runs the published package directly with Bun:
+**Using npx (Recommended):**
+
+```json
+{
+  "mcpServers": {
+    "appleii-agent": {
+      "command": "npx",
+      "args": ["-y", "@retrotech71/appleii-agent"]
+    }
+  }
+}
+```
+
+**Using bunx:**
+
+```json
+{
+  "mcpServers": {
+    "appleii-agent": {
+      "command": "bunx",
+      "args": ["-y", "@retrotech71/appleii-agent"]
+    }
+  }
+}
+```
+
+**From source:**
+
+```json
+{
+  "mcpServers": {
+    "appleii-agent": {
+      "command": "node",
+      "args": ["/absolute/path/to/appleii-agent/src/index.js"]
+    }
+  }
+}
+```
+
+**With custom sandbox config location:**
+
+```json
+{
+  "mcpServers": {
+    "appleii-agent": {
+      "command": "npx",
+      "args": ["-y", "@retrotech71/appleii-agent"],
+      "env": {
+        "APPLEII_AGENT_SANDBOX": "/path/to/custom/sandbox.config"
+      }
+    }
+  }
+}
+```
+
+### For Claude Code
+
+Edit `~/.claude/mcp.json`:
+
+**Using bunx (Recommended):**
 
 ```json
 {
@@ -54,7 +113,7 @@ Runs the published package directly with Bun:
 }
 ```
 
-### Option 2: Local development from source
+**From source:**
 
 ```json
 {
@@ -78,12 +137,19 @@ Runs the published package directly with Bun:
 
 ```
 Show the CPU debugger window
-Load ~/Documents/ProDOS_2_4_2.dsk into drive 1
+Load [disks]/ProDOS_2_4_2.dsk into drive 1
+Load [zork]/zork1.dsk into drive 2
 Write a BASIC program that draws a sine wave
 Install the SmartPort card in slot 7
-Load ~/Images/Total_Replay.hdv into SmartPort device 1
+Load [games]/Total_Replay.hdv into SmartPort device 1
 Turn on the emulator and boot from disk
-Save 256 bytes from memory address $0800 to ~/output.bin
+Save the BASIC program to [basic]/sinewave.bas
+```
+
+You can also use full paths:
+```
+Load ~/Documents/ProDOS.dsk into drive 1
+Save assembly code to ~/code/program.s
 ```
 
 ## Available Tools
@@ -117,6 +183,55 @@ Save 256 bytes from memory address $0800 to ~/output.bin
 | `shutdown_remote_server` | Shutdown another MCP server instance on the same port |
 | `disconnect_clients` | Gracefully disconnect all connected emulator clients |
 
+## Sandbox Paths
+
+Sandbox paths provide convenient shortcuts for frequently accessed directories. Instead of typing full paths, you can define sandboxes in a configuration file and use them across all file operations.
+
+### Configuration
+
+1. **Create a sandbox config file** anywhere you like (e.g., `~/sandbox.config`):
+
+```
+# Apple //e Agent - Sandbox Paths Configuration
+# Format: [key]@/path/to/directory
+
+[disks]@~/Documents/Apple2/Disks
+[games]@~/Documents/Apple2/Games
+[zork]@~/Games/Zork
+[basic]@~/Documents/Apple2/BASIC
+[files]@~/Documents/Apple2/Files
+```
+
+2. **Set the `APPLEII_AGENT_SANDBOX` environment variable** to point to your config file in your MCP client configuration (see Configuration section above for examples).
+
+### Usage
+
+All file loading/saving tools support both sandbox syntax and full paths:
+
+**With sandbox paths:**
+```
+Load [disks]/ProDOS.dsk into drive 1
+Load [zork]/zork1.dsk into drive 2
+Save BASIC program to [basic]/hello.bas
+Load [games]/total-replay.hdv into SmartPort device 1
+```
+
+**With full paths:**
+```
+Load ~/Documents/game.dsk into drive 1
+Save assembly to ~/code/program.s
+```
+
+### Supported Tools
+
+Sandbox paths work with:
+- `load_disk_image` - `[disks]/game.dsk`
+- `load_smartport_image` - `[games]/hd.hdv`
+- `load_file` - `[files]/data.bin`
+- `save_basic_file` - `[basic]/program.bas`
+- `save_asm_file` - `[asm]/code.s`
+- `save_disk_file` - `[files]/output.bin`
+
 ## Environment Variables
 
 | Variable | Default | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retrotech71/appleii-agent",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "MCP server for the Apple //e browser emulator — control the emulator and integrate with AI agents",
   "type": "module",
   "main": "src/index.js",

package/src/mcp-server.js

@@ -13,6 +13,7 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 import { tools } from "./tools/index.js";
 import { VERSION } from "./version.js";
+import { pathResolver } from "./path-resolver.js";
 
 /**
  * MCP Server for Apple //e emulator agent
@@ -60,6 +61,11 @@ export class McpServer {
         // Call the handler
         const result = await toolModule.handler(args, this.httpServer);
 
+        // If the handler returns _mcpContent, pass it through directly (e.g. image content)
+        if (result?._mcpContent) {
+          return { content: result._mcpContent };
+        }
+
         return {
           content: [
             {
@@ -88,5 +94,15 @@ export class McpServer {
   async start() {
     const transport = new StdioServerTransport();
     await this.server.connect(transport);
+
+    // Alert user if no sandbox config is configured
+    if (!pathResolver.configPath) {
+      await this.server.sendLoggingMessage({
+        level: "warning",
+        data: "⚠️  Apple //e Agent: No sandbox config set. File operations are disabled. " +
+              "Set the APPLEII_AGENT_SANDBOX environment variable to point to your sandbox.config file. " +
+              "See https://github.com/mikedaley/appleii-agent#sandbox-paths for setup instructions.",
+      });
+    }
   }
 }

package/src/path-resolver.js

@@ -0,0 +1,200 @@
+/*
+ * path-resolver.js - Sandbox path resolution for convenient file access
+ *
+ * Written by
+ *  Shawn Bullock <shawn@agenticexpert.ai>
+ */
+
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { fileURLToPath } from "url";
+import { logger } from "./logger.js";
+
+/**
+ * PathResolver - Manages sandbox paths for convenient file access
+ *
+ * Format: [key]@/path/to/directory
+ * Usage: [key]/relative/path/to/file.dsk or /full/path/to/file.dsk
+ */
+export class PathResolver {
+  constructor(configPath = null) {
+    // User must specify config location via constructor or APPLEII_AGENT_SANDBOX env var
+    const expandTilde = (p) => p.startsWith("~") ? p.replace("~", os.homedir()) : p;
+
+    if (configPath) {
+      this.configPath = expandTilde(configPath);
+    } else if (process.env.APPLEII_AGENT_SANDBOX) {
+      this.configPath = expandTilde(process.env.APPLEII_AGENT_SANDBOX);
+    } else {
+      // No config specified - sandbox paths will not be available
+      this.configPath = null;
+    }
+    this.sandboxes = new Map();
+    this.loadConfig();
+  }
+
+  /**
+   * Load sandbox paths from config file
+   */
+  loadConfig() {
+    // No config path specified - all file access will be blocked
+    if (!this.configPath) {
+      logger.log("[PathResolver] No sandbox config specified. All file operations are blocked. Set APPLEII_AGENT_SANDBOX to enable file access.");
+      return;
+    }
+
+    try {
+      // Check if config file exists
+      if (!fs.existsSync(this.configPath)) {
+        logger.log(`[PathResolver] Sandbox config not found: ${this.configPath}`);
+        logger.log(`[PathResolver] Create the file or update APPLEII_AGENT_SANDBOX to point to a valid config.`);
+        return;
+      }
+
+      // Read and parse config
+      const content = fs.readFileSync(this.configPath, "utf8");
+      const lines = content.split("\n");
+
+      this.sandboxes.clear();
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+
+        // Skip empty lines and comments
+        if (!trimmed || trimmed.startsWith("#")) {
+          continue;
+        }
+
+        // Parse [key]@path format
+        const match = trimmed.match(/^\[([a-zA-Z0-9_-]+)\]@(.+)$/);
+        if (match) {
+          const [, key, pathValue] = match;
+
+          // Expand ~ to home directory
+          let resolvedPath = pathValue;
+          if (resolvedPath.startsWith("~")) {
+            resolvedPath = resolvedPath.replace("~", os.homedir());
+          }
+
+          // Convert to absolute path
+          if (!path.isAbsolute(resolvedPath)) {
+            resolvedPath = path.resolve(resolvedPath);
+          }
+
+          this.sandboxes.set(key, resolvedPath);
+        }
+      }
+
+      if (this.sandboxes.size > 0) {
+        logger.log(`[PathResolver] Loaded ${this.sandboxes.size} sandbox paths from ${this.configPath}`);
+      } else {
+        logger.log(`[PathResolver] No sandbox paths found in ${this.configPath}`);
+      }
+    } catch (error) {
+      logger.log(`[PathResolver] Error loading config: ${error.message}`);
+    }
+  }
+
+  /**
+   * Resolve a path with sandbox syntax [key]/path or regular path.
+   * If sandboxes are configured, full paths must fall within a trusted directory.
+   *
+   * @param {string} pathString - Path to resolve (e.g., "[disks]/game.dsk" or "~/file.txt")
+   * @returns {string} Resolved absolute path
+   * @throws {Error} If sandbox is unknown, path traversal detected, or path outside trusted directories
+   */
+  resolve(pathString) {
+    if (!pathString) {
+      return pathString;
+    }
+
+    // Check if path uses sandbox syntax [key]/path
+    const sandboxMatch = pathString.match(/^\[([a-zA-Z0-9_-]+)\](.*)$/);
+
+    if (sandboxMatch) {
+      const [, key, relativePath] = sandboxMatch;
+
+      // Check if key exists
+      if (!this.sandboxes.has(key)) {
+        if (this.sandboxes.size === 0) {
+          throw new Error(
+            this.configPath
+              ? `No sandboxes loaded from ${this.configPath}. Check the file has valid [key]@/path entries.`
+              : `No sandbox config set. Set APPLEII_AGENT_SANDBOX environment variable and restart the MCP server.`
+          );
+        }
+        const available = [...this.sandboxes.keys()].map(k => `[${k}]`).join(", ");
+        throw new Error(`Unknown sandbox path: [${key}]. Available sandboxes: ${available}`);
+      }
+
+      const basePath = this.sandboxes.get(key);
+
+      // Remove leading slash from relative path if present
+      const cleanRelativePath = relativePath.startsWith("/")
+        ? relativePath.slice(1)
+        : relativePath;
+
+      // Resolve and normalize the full path
+      const resolved = path.normalize(path.join(basePath, cleanRelativePath));
+
+      // Prevent path traversal escaping the sandbox directory
+      if (!resolved.startsWith(path.normalize(basePath))) {
+        throw new Error(`Path traversal detected: [${key}]${relativePath} escapes its trusted directory.`);
+      }
+
+      return resolved;
+    }
+
+    // No sandbox syntax - treat as regular full path
+    let expandedPath = pathString;
+    if (pathString.startsWith("~")) {
+      expandedPath = pathString.replace("~", os.homedir());
+    }
+    const resolved = path.normalize(path.resolve(expandedPath));
+
+    // Full paths must always be within a trusted sandbox directory
+    if (!this._isWithinTrustedPath(resolved)) {
+      throw new Error(
+        `Access denied: "${resolved}" is outside all trusted directories. ` +
+        `Use a sandbox path like [key]/file or add a trusted path to ${this.configPath}`
+      );
+    }
+
+    return resolved;
+  }
+
+  /**
+   * Check if a resolved absolute path falls within any configured sandbox directory
+   */
+  _isWithinTrustedPath(absolutePath) {
+    for (const trustedPath of this.sandboxes.values()) {
+      const normalizedTrusted = path.normalize(trustedPath);
+      if (absolutePath === normalizedTrusted || absolutePath.startsWith(normalizedTrusted + path.sep)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Get list of available sandbox paths
+   */
+  getSandboxes() {
+    const result = {};
+    for (const [key, value] of this.sandboxes.entries()) {
+      result[key] = value;
+    }
+    return result;
+  }
+
+  /**
+   * Reload config from disk
+   */
+  reload() {
+    this.loadConfig();
+  }
+}
+
+// Singleton instance
+export const pathResolver = new PathResolver();

package/src/tools/get-screenshot.js

@@ -0,0 +1,59 @@
+/*
+ * get-screenshot.js - Capture and return emulator screenshot as an image
+ *
+ * Written by
+ *  Shawn Bullock <shawn@agenticexpert.ai>
+ */
+
+export const tool = {
+  name: "get_screenshot",
+  description: "Capture the current Apple //e screen and return it as a viewable image.",
+  inputSchema: {
+    type: "object",
+    properties: {},
+    required: []
+  }
+};
+
+export async function handler(args, httpServer) {
+  const toolCallId = `tc_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+
+  await httpServer.sendEvent({
+    type: "TOOL_CALL_START",
+    tool_call_id: toolCallId,
+    tool_call_name: "emma_command",
+  });
+
+  await httpServer.sendEvent({
+    type: "TOOL_CALL_ARGS",
+    tool_call_id: toolCallId,
+    delta: JSON.stringify({ command: "captureScreenshot", params: {} }),
+  });
+
+  await httpServer.sendEvent({
+    type: "TOOL_CALL_END",
+    tool_call_id: toolCallId,
+  });
+
+  const raw = await httpServer.waitForToolResult(toolCallId, 10000);
+  const captureResult = typeof raw === "string" ? JSON.parse(raw) : raw;
+
+  if (!captureResult?.success) {
+    return { success: false, error: captureResult?.error || "Screenshot capture failed" };
+  }
+
+  const { imageBase64 } = captureResult;
+  if (!imageBase64) {
+    return { success: false, error: "No image data returned from emulator" };
+  }
+
+  // Strip data URL prefix to get raw base64
+  const data = imageBase64.replace(/^data:[^;]+;base64,\s*/, '').trim();
+
+  // Return as MCP image content so the LLM can view it directly
+  return {
+    _mcpContent: [
+      { type: "image", data, mimeType: "image/png" }
+    ]
+  };
+}

package/src/tools/index.js

@@ -18,10 +18,10 @@ import * as hideWindow from "./hide-window.js";
 import * as focusWindow from "./focus-window.js";
 import * as loadDiskImage from "./load-disk-image.js";
 import * as loadFile from "./load-file.js";
-import * as saveBasicFile from "./save-basic-file.js";
-import * as saveAsmFile from "./save-asm-file.js";
-import * as saveDiskFile from "./save-disk-file.js";
 import * as loadSmartportImage from "./load-smartport-image.js";
+import * as reloadSandbox from "./reload-sandbox.js";
+import * as getScreenshot from "./get-screenshot.js";
+import * as saveTo from "./save-to.js";
 
 export const tools = [
   serverControl,
@@ -29,6 +29,7 @@ export const tools = [
   setDebug,
   getState,
   getVersion,
+  reloadSandbox,
   disconnectClients,
   shutdownRemoteServer,
   showWindow,
@@ -38,7 +39,6 @@ export const tools = [
   loadDiskImage,
   loadSmartportImage,
   loadFile,
-  saveBasicFile,
-  saveAsmFile,
-  saveDiskFile,
+  getScreenshot,
+  saveTo,
 ];

package/src/tools/load-disk-image.js

@@ -7,17 +7,17 @@
 
 import fs from 'fs';
 import path from 'path';
-import { homedir } from 'os';
+import { pathResolver } from '../path-resolver.js';
 
 export const tool = {
   name: "load_disk_image",
-  description: "Load a disk image file from the local filesystem and return as base64",
+  description: "Load a disk image file from the local filesystem and return as base64. Supports sandbox paths like [disks]/game.dsk or full paths like ~/Documents/game.dsk",
   inputSchema: {
     type: "object",
     properties: {
       path: {
         type: "string",
-        description: "Path to disk image file (supports ~ for home directory)",
+        description: "Path to disk image file. Use [sandbox]/path syntax or full path with ~ for home directory",
       },
     },
     required: ["path"],
@@ -35,16 +35,8 @@ export function handler(args) {
   }
 
   try {
-    // Expand ~ to home directory
-    let expandedPath = filePath;
-    if (filePath.startsWith('~/')) {
-      expandedPath = path.join(homedir(), filePath.slice(2));
-    } else if (filePath === '~') {
-      expandedPath = homedir();
-    }
-
-    // Resolve to absolute path
-    const absolutePath = path.resolve(expandedPath);
+    // Resolve path (handles sandbox paths and ~ expansion)
+    const absolutePath = pathResolver.resolve(filePath);
 
     // Check if file exists
     if (!fs.existsSync(absolutePath)) {

package/src/tools/load-file.js

@@ -1,16 +1,16 @@
 import fs from 'fs';
 import path from 'path';
-import os from 'os';
+import { pathResolver } from '../path-resolver.js';
 
 export const tool = {
   name: "load_file",
-  description: "Read a file from the local filesystem. Returns base64 for binary files or plain text for text files.",
+  description: "Read a file from the local filesystem. Returns base64 for binary files or plain text for text files. Supports sandbox paths like [files]/program.bas or full paths like ~/Documents/file.txt",
   inputSchema: {
     type: "object",
     properties: {
       path: {
         type: "string",
-        description: "Path to the file (supports ~ for home directory)"
+        description: "Path to the file. Use [sandbox]/path syntax or full path with ~ for home directory"
       },
       binary: {
         type: "boolean",
@@ -33,11 +33,8 @@ export function handler(args) {
   }
 
   try {
-    // Expand ~ to home directory
-    let expandedPath = filePath;
-    if (filePath.startsWith('~')) {
-      expandedPath = path.join(os.homedir(), filePath.slice(1));
-    }
+    // Resolve path (handles sandbox paths and ~ expansion)
+    const expandedPath = pathResolver.resolve(filePath);
 
     // Check if file exists
     if (!fs.existsSync(expandedPath)) {

package/src/tools/load-smartport-image.js

@@ -7,17 +7,17 @@
 
 import fs from 'fs';
 import path from 'path';
-import { homedir } from 'os';
+import { pathResolver } from '../path-resolver.js';
 
 export const tool = {
   name: "load_smartport_image",
-  description: "Load a SmartPort hard drive image file from the local filesystem and return as base64",
+  description: "Load a SmartPort hard drive image file from the local filesystem and return as base64. Supports sandbox paths like [games]/total-replay.hdv or full paths like ~/Documents/disk.hdv",
   inputSchema: {
     type: "object",
     properties: {
       path: {
         type: "string",
-        description: "Path to SmartPort image file (supports ~ for home directory)",
+        description: "Path to SmartPort image file. Use [sandbox]/path syntax or full path with ~ for home directory",
       },
     },
     required: ["path"],
@@ -35,16 +35,8 @@ export function handler(args) {
   }
 
   try {
-    // Expand ~ to home directory
-    let expandedPath = filePath;
-    if (filePath.startsWith('~/')) {
-      expandedPath = path.join(homedir(), filePath.slice(2));
-    } else if (filePath === '~') {
-      expandedPath = homedir();
-    }
-
-    // Resolve to absolute path
-    const absolutePath = path.resolve(expandedPath);
+    // Resolve path (handles sandbox paths and ~ expansion)
+    const absolutePath = pathResolver.resolve(filePath);
 
     // Check if file exists
     if (!fs.existsSync(absolutePath)) {

package/src/tools/reload-sandbox.js

@@ -0,0 +1,36 @@
+/*
+ * reload-sandbox.js - Reload sandbox paths config without restarting MCP server
+ *
+ * Written by
+ *  Shawn Bullock <shawn@agenticexpert.ai>
+ */
+
+import { pathResolver } from "../path-resolver.js";
+
+export const tool = {
+  name: "reload_sandbox",
+  description: "Reload the sandbox paths configuration from disk without restarting the MCP server. Use this after editing your sandbox.config file to pick up new paths.",
+  inputSchema: {
+    type: "object",
+    properties: {},
+    required: [],
+  },
+};
+
+export function handler() {
+  pathResolver.reload();
+  const sandboxes = pathResolver.getSandboxes();
+  const keys = Object.keys(sandboxes);
+
+  return {
+    success: true,
+    config: pathResolver.configPath,
+    loaded: keys.length,
+    sandboxes: keys.length > 0
+      ? sandboxes
+      : null,
+    message: keys.length > 0
+      ? `Loaded ${keys.length} sandbox path(s): ${keys.map(k => `[${k}]`).join(", ")}`
+      : "No sandbox paths found in config.",
+  };
+}

package/src/tools/save-asm-file.js

@@ -7,17 +7,17 @@
 
 import fs from 'fs';
 import path from 'path';
-import { homedir } from 'os';
+import { pathResolver } from '../path-resolver.js';
 
 export const tool = {
   name: "save_asm_file",
-  description: "Save assembly source code to a file on the local filesystem",
+  description: "Save assembly source code to a file on the local filesystem. Supports sandbox paths like [asm]/program.s or full paths like ~/Documents/program.asm",
   inputSchema: {
     type: "object",
     properties: {
       path: {
         type: "string",
-        description: "Path to save file (supports ~ for home directory, .s or .asm extension recommended)",
+        description: "Path to save file. Use [sandbox]/path syntax or full path with ~ for home directory (.s or .asm extension recommended)",
       },
       content: {
         type: "string",
@@ -51,19 +51,8 @@ export function handler(args) {
   }
 
   try {
-    // Expand ~ to home directory
-    let expandedPath = filePath;
-    if (filePath.startsWith('~/')) {
-      expandedPath = path.join(homedir(), filePath.slice(2));
-    } else if (filePath === '~') {
-      return {
-        success: false,
-        error: "Cannot save to home directory root, please specify a filename",
-      };
-    }
-
-    // Resolve to absolute path
-    const absolutePath = path.resolve(expandedPath);
+    // Resolve path (handles sandbox paths and ~ expansion)
+    const absolutePath = pathResolver.resolve(filePath);
 
     // Ensure parent directory exists
     const dir = path.dirname(absolutePath);

package/src/tools/save-basic-file.js

@@ -7,17 +7,17 @@
 
 import fs from 'fs';
 import path from 'path';
-import { homedir } from 'os';
+import { pathResolver } from '../path-resolver.js';
 
 export const tool = {
   name: "save_basic_file",
-  description: "Save BASIC program text to a file on the local filesystem",
+  description: "Save BASIC program text to a file on the local filesystem. Supports sandbox paths like [basic]/program.bas or full paths like ~/Documents/program.bas",
   inputSchema: {
     type: "object",
     properties: {
       path: {
         type: "string",
-        description: "Path to save file (supports ~ for home directory, .bas extension recommended)",
+        description: "Path to save file. Use [sandbox]/path syntax or full path with ~ for home directory (.bas extension recommended)",
       },
       content: {
         type: "string",
@@ -51,19 +51,8 @@ export function handler(args) {
   }
 
   try {
-    // Expand ~ to home directory
-    let expandedPath = filePath;
-    if (filePath.startsWith('~/')) {
-      expandedPath = path.join(homedir(), filePath.slice(2));
-    } else if (filePath === '~') {
-      return {
-        success: false,
-        error: "Cannot save to home directory root, please specify a filename",
-      };
-    }
-
-    // Resolve to absolute path
-    const absolutePath = path.resolve(expandedPath);
+    // Resolve path (handles sandbox paths and ~ expansion)
+    const absolutePath = pathResolver.resolve(filePath);
 
     // Ensure parent directory exists
     const dir = path.dirname(absolutePath);

package/src/tools/save-disk-file.js

@@ -1,16 +1,16 @@
 import fs from 'fs';
 import path from 'path';
-import os from 'os';
+import { pathResolver } from '../path-resolver.js';
 
 export const tool = {
   name: "save_disk_file",
-  description: "Save disk file content to the local filesystem. Content should be base64 encoded binary data.",
+  description: "Save disk file content to the local filesystem. Content should be base64 encoded binary data. Supports sandbox paths like [files]/data.bin or full paths like ~/Documents/file.bin",
   inputSchema: {
     type: "object",
     properties: {
       path: {
         type: "string",
-        description: "Path to save the file (supports ~ for home directory)"
+        description: "Path to save the file. Use [sandbox]/path syntax or full path with ~ for home directory"
       },
       contentBase64: {
         type: "string",
@@ -20,6 +20,11 @@ export const tool = {
         type: "boolean",
         description: "Allow overwriting existing files (default: false)",
         default: false
+      },
+      direct: {
+        type: "boolean",
+        description: "When true (default), decode and save the file, returning only metadata. When false, return the base64 content to the LLM without saving.",
+        default: true
       }
     },
     required: ["path", "contentBase64"]
@@ -27,7 +32,7 @@ export const tool = {
 };
 
 export function handler(args) {
-  const { path: filePath, contentBase64, overwrite = false } = args;
+  const { path: filePath, contentBase64, overwrite = false, direct = true } = args;
 
   if (!filePath) {
     return {
@@ -43,12 +48,20 @@ export function handler(args) {
     };
   }
 
+  // direct=false: return content to LLM without saving
+  if (!direct) {
+    const raw = contentBase64.replace(/^data:[^;]+;base64,\s*/, '').trim();
+    const buffer = Buffer.from(raw, 'base64');
+    return {
+      success: true,
+      contentBase64: raw,
+      size: buffer.length
+    };
+  }
+
   try {
-    // Expand ~ to home directory
-    let expandedPath = filePath;
-    if (filePath.startsWith('~')) {
-      expandedPath = path.join(os.homedir(), filePath.slice(1));
-    }
+    // Resolve path (handles sandbox paths and ~ expansion)
+    const expandedPath = pathResolver.resolve(filePath);
 
     // Check if file exists and overwrite is false
     if (!overwrite && fs.existsSync(expandedPath)) {
@@ -58,8 +71,12 @@ export function handler(args) {
       };
     }
 
+    // Strip data URL prefix if present (e.g. "data:image/png;base64, iVBOR...")
+    // The regex handles any media type and optional whitespace after the comma
+    const raw = contentBase64.replace(/^data:[^;]+;base64,\s*/, '').trim();
+
     // Decode base64 content
-    const buffer = Buffer.from(contentBase64, 'base64');
+    const buffer = Buffer.from(raw, 'base64');
 
     // Ensure directory exists
     const dir = path.dirname(expandedPath);

package/src/tools/save-screenshot.js

@@ -0,0 +1,112 @@
+/*
+ * save-screenshot.js - Capture and save emulator screenshot in one step
+ *
+ * Written by
+ *  Shawn Bullock <shawn@agenticexpert.ai>
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { pathResolver } from '../path-resolver.js';
+
+export const tool = {
+  name: "save_screenshot",
+  description: "Capture the current Apple //e screen and save it as a PNG file. Handles the full capture-decode-save pipeline without returning the image data to the LLM.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      path: {
+        type: "string",
+        description: "Sandbox path to save the PNG (e.g. \"[t]/cap.png\" or \"[files]/screen.png\")"
+      },
+      overwrite: {
+        type: "boolean",
+        description: "Allow overwriting an existing file (default: false)",
+        default: false
+      }
+    },
+    required: ["path"]
+  }
+};
+
+export async function handler(args, httpServer) {
+  const { path: filePath, overwrite = false } = args;
+
+  if (!filePath) {
+    return { success: false, error: "path parameter is required" };
+  }
+
+  // Resolve sandbox path
+  let expandedPath;
+  try {
+    expandedPath = pathResolver.resolve(filePath);
+  } catch (err) {
+    return { success: false, error: err.message };
+  }
+
+  // Check overwrite
+  if (!overwrite && fs.existsSync(expandedPath)) {
+    return {
+      success: false,
+      error: `File already exists: ${expandedPath}. Set overwrite: true to replace it.`
+    };
+  }
+
+  // Call the captureScreenshot app tool via AG-UI
+  const toolCallId = `tc_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+
+  await httpServer.sendEvent({
+    type: "TOOL_CALL_START",
+    tool_call_id: toolCallId,
+    tool_call_name: "emma_command",
+  });
+
+  await httpServer.sendEvent({
+    type: "TOOL_CALL_ARGS",
+    tool_call_id: toolCallId,
+    delta: JSON.stringify({ command: "captureScreenshot", params: {} }),
+  });
+
+  await httpServer.sendEvent({
+    type: "TOOL_CALL_END",
+    tool_call_id: toolCallId,
+  });
+
+  const toolResult = await httpServer.waitForToolResult(toolCallId, 10000);
+  const captureResult = typeof toolResult === "string" ? JSON.parse(toolResult) : toolResult;
+
+  if (!captureResult?.success) {
+    return { success: false, error: captureResult?.error || "Screenshot capture failed" };
+  }
+
+  const { imageBase64 } = captureResult;
+  if (!imageBase64) {
+    return { success: false, error: "No image data returned from emulator" };
+  }
+
+  // Strip data URL prefix (e.g. "data:image/png;base64, ") to get raw base64
+  const raw = imageBase64.replace(/^data:[^;]+;base64,\s*/, '').trim();
+
+  // Decode and save
+  try {
+    const buffer = Buffer.from(raw, 'base64');
+
+    const dir = path.dirname(expandedPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    fs.writeFileSync(expandedPath, buffer);
+
+    return {
+      success: true,
+      path: expandedPath,
+      size: buffer.length,
+      width: 560,
+      height: 384,
+      message: `Screenshot saved to ${expandedPath} (${buffer.length} bytes)`
+    };
+  } catch (err) {
+    return { success: false, error: err.message };
+  }
+}

package/src/tools/save-to.js

@@ -0,0 +1,263 @@
+/*
+ * save-to.js - Unified load-and-save tool for all emulator content sources
+ *
+ * Fetches content from an emulator source and saves it directly to a file
+ * without exposing the raw data to the LLM (when direct=true).
+ *
+ * Written by
+ *  Shawn Bullock <shawn@agenticexpert.ai>
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { pathResolver } from '../path-resolver.js';
+
+export const tool = {
+  name: "save_to",
+  description: "Load content from an emulator source and save it to a file in one step. When direct=true (default), saves silently and returns only metadata — the base64 is never sent to the LLM. When direct=false, returns the content to the LLM without saving.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      from: {
+        type: "string",
+        enum: ["basic-editor", "asm-editor", "basic-memory", "file-explorer", "memory-range", "screen", "raw"],
+        description: "Content source: basic-editor (BASIC editor text), asm-editor (ASM editor source), basic-memory (BASIC program from emulator memory), file-explorer (file from disk/SmartPort), memory-range (raw memory bytes), screen (screen capture), raw (LLM-provided content)"
+      },
+      whereTo: {
+        type: "string",
+        description: "Sandbox path to save the file (e.g. \"[files]/prog.bas\", \"[t]/dump.bin\")"
+      },
+      direct: {
+        type: "boolean",
+        description: "When true (default), save file and return only metadata. When false, return content to LLM without saving.",
+        default: true
+      },
+      overwrite: {
+        type: "boolean",
+        description: "Allow overwriting an existing file (default: false)",
+        default: false
+      },
+      // raw source
+      content: {
+        type: "object",
+        description: "For from=raw: content provided by the LLM",
+        properties: {
+          data: {
+            type: "string",
+            description: "The content to save — UTF-8 text or base64-encoded binary depending on type"
+          },
+          type: {
+            type: "string",
+            enum: ["text", "binary"],
+            description: "text: save data as UTF-8. binary: decode data from base64 and save as binary."
+          }
+        },
+        required: ["data", "type"]
+      },
+      // file-explorer source
+      filename: {
+        type: "string",
+        description: "For from=file-explorer: filename on disk to load"
+      },
+      drive: {
+        type: "number",
+        description: "For from=file-explorer: drive number 0 or 1 (default 0)",
+        default: 0
+      },
+      // memory-range source
+      address: {
+        type: "string",
+        description: "For from=memory-range: start address — $hex (e.g. \"$0300\") or decimal"
+      },
+      length: {
+        type: "string",
+        description: "For from=memory-range: byte count — $hex (e.g. \"$0800\") or decimal"
+      },
+      // screen source
+      screenMode: {
+        type: "string",
+        enum: ["auto", "text", "graphics"],
+        description: "For from=screen: 'graphics' captures as PNG, 'text' captures screen text, 'auto' defaults to graphics (default: auto)",
+        default: "auto"
+      }
+    },
+    required: ["from", "whereTo"]
+  }
+};
+
+/**
+ * Call a frontend app tool via AG-UI and return parsed result
+ */
+async function callAppTool(httpServer, command, params = {}) {
+  const toolCallId = `tc_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+
+  await httpServer.sendEvent({
+    type: "TOOL_CALL_START",
+    tool_call_id: toolCallId,
+    tool_call_name: "emma_command",
+  });
+
+  await httpServer.sendEvent({
+    type: "TOOL_CALL_ARGS",
+    tool_call_id: toolCallId,
+    delta: JSON.stringify({ command, params }),
+  });
+
+  await httpServer.sendEvent({
+    type: "TOOL_CALL_END",
+    tool_call_id: toolCallId,
+  });
+
+  const raw = await httpServer.waitForToolResult(toolCallId, 15000);
+  return typeof raw === "string" ? JSON.parse(raw) : raw;
+}
+
+/**
+ * Fetch content from the requested source.
+ * Returns { content, isBinary, isDataUrl }
+ *   content   — string: raw base64 (isBinary=true) or UTF-8 text (isBinary=false)
+ *   isBinary  — true if content is base64-encoded binary
+ *   isDataUrl — true if the base64 has a data URL prefix that must be stripped
+ */
+async function fetchContent(httpServer, args) {
+  const { from, content, filename, drive = 0, address, length, screenMode = "auto" } = args;
+
+  switch (from) {
+
+    case "raw": {
+      if (!content?.data) throw new Error("content.data is required for from=raw");
+      if (!content?.type) throw new Error("content.type is required for from=raw");
+      return {
+        content: content.data,
+        isBinary: content.type === "binary",
+      };
+    }
+
+    case "basic-editor": {
+      const result = await callAppTool(httpServer, "basicProgramGet");
+      if (!result?.success) throw new Error(result?.error || "Failed to get BASIC program from editor");
+      return { content: result.program, isBinary: false };
+    }
+
+    case "asm-editor": {
+      const result = await callAppTool(httpServer, "asmGet");
+      if (!result?.success) throw new Error(result?.error || "Failed to get ASM source from editor");
+      return { content: result.source, isBinary: false };
+    }
+
+    case "basic-memory": {
+      const result = await callAppTool(httpServer, "directReadBasic");
+      if (!result?.success) throw new Error(result?.error || "Failed to read BASIC from memory");
+      return { content: result.program, isBinary: false };
+    }
+
+    case "file-explorer": {
+      if (!filename) throw new Error("filename is required for from=file-explorer");
+      const result = await callAppTool(httpServer, "getDiskFileContent", { filename, drive });
+      if (!result?.success) throw new Error(result?.error || "Failed to read file from disk");
+      if (result.isBinary) {
+        return { content: result.contentBase64, isBinary: true };
+      }
+      return { content: result.content ?? result.text ?? result.contentBase64, isBinary: false };
+    }
+
+    case "memory-range": {
+      if (!address) throw new Error("address is required for from=memory-range");
+      if (!length) throw new Error("length is required for from=memory-range");
+      const result = await callAppTool(httpServer, "directSaveBinaryRangeTo", { address, length });
+      if (!result?.success) throw new Error(result?.error || "Failed to read memory range");
+      return { content: result.contentBase64, isBinary: true };
+    }
+
+    case "screen": {
+      if (screenMode === "text") {
+        const result = await callAppTool(httpServer, "captureScreenText");
+        if (!result?.success) throw new Error(result?.error || "Failed to capture screen text");
+        return { content: result.text, isBinary: false };
+      }
+      // "auto" and "graphics" → PNG
+      const result = await callAppTool(httpServer, "captureScreenshot");
+      if (!result?.success) throw new Error(result?.error || "Failed to capture screenshot");
+      return { content: result.imageBase64, isBinary: true, isDataUrl: true };
+    }
+
+    default:
+      throw new Error(`Unknown source: ${from}`);
+  }
+}
+
+export async function handler(args, httpServer) {
+  const { whereTo, direct = true, overwrite = false } = args;
+
+  if (!whereTo) {
+    return { success: false, error: "whereTo parameter is required" };
+  }
+
+  // Fetch content from the source
+  let fetched;
+  try {
+    fetched = await fetchContent(httpServer, args);
+  } catch (err) {
+    return { success: false, error: err.message };
+  }
+
+  const { isBinary, isDataUrl } = fetched;
+  let content = fetched.content;
+
+  // Strip data URL prefix if present (e.g. "data:image/png;base64, ")
+  if (isDataUrl && isBinary) {
+    content = content.replace(/^data:[^;]+;base64,\s*/, '').trim();
+  }
+
+  // direct=false: return content to LLM without saving
+  if (!direct) {
+    return {
+      success: true,
+      isBinary,
+      ...(isBinary ? { contentBase64: content } : { content }),
+      message: "Content loaded — not saved (direct=false)"
+    };
+  }
+
+  // direct=true: save to file, scrub content from response
+  let expandedPath;
+  try {
+    expandedPath = pathResolver.resolve(whereTo);
+  } catch (err) {
+    return { success: false, error: err.message };
+  }
+
+  if (!overwrite && fs.existsSync(expandedPath)) {
+    return {
+      success: false,
+      error: `File already exists: ${expandedPath}. Set overwrite: true to replace it.`
+    };
+  }
+
+  try {
+    const dir = path.dirname(expandedPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    let size;
+    if (isBinary) {
+      const buffer = Buffer.from(content, 'base64');
+      fs.writeFileSync(expandedPath, buffer);
+      size = buffer.length;
+    } else {
+      fs.writeFileSync(expandedPath, content, 'utf8');
+      size = Buffer.byteLength(content, 'utf8');
+    }
+
+    return {
+      success: true,
+      path: expandedPath,
+      size,
+      from: args.from,
+      message: `Saved ${size} bytes to ${expandedPath}`
+    };
+  } catch (err) {
+    return { success: false, error: err.message };
+  }
+}