@papercraneai/sandbox-agent 0.1.0

package/dist/index.js

@@ -0,0 +1,1152 @@
+#!/usr/bin/env node
+import express from "express";
+import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
+import { readdir, stat, mkdir, readFile, writeFile, access } from "fs/promises";
+import { join, dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+import { spawn, execSync } from "child_process";
+import { homedir } from "os";
+import { z } from "zod";
+import multer from "multer";
+import * as log from "./logger.js";
+// Get the directory of this file (works for both source and compiled)
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Read package version at startup
+const pkg = JSON.parse(await readFile(join(__dirname, "..", "package.json"), "utf-8"));
+// Parse CLI arguments
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const result = {
+        register: false,
+        token: null,
+        papercraneUrl: process.env.PAPERCRANE_URL || "https://fly.papercrane.ai",
+        agentPort: parseInt(process.env.PORT || "3001"),
+        devPort: parseInt(process.env.DEV_PORT || "3000"),
+        workdir: join(homedir(), ".papercrane", "sandbox"),
+        agentOnly: false
+    };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--register") {
+            result.register = true;
+        }
+        else if (arg === "--token" && args[i + 1]) {
+            result.token = args[++i];
+        }
+        else if (arg === "--papercrane-url" && args[i + 1]) {
+            result.papercraneUrl = args[++i];
+        }
+        else if (arg === "--port" && args[i + 1]) {
+            result.agentPort = parseInt(args[++i]);
+        }
+        else if (arg === "--dev-port" && args[i + 1]) {
+            result.devPort = parseInt(args[++i]);
+        }
+        else if (arg === "--workdir" && args[i + 1]) {
+            result.workdir = args[++i];
+        }
+        else if (arg === "--agent-only") {
+            result.agentOnly = true;
+        }
+        else if (arg === "--help" || arg === "-h") {
+            console.log(`
+sandbox-agent - Claude Agent SDK server for environments
+
+Usage:
+  sandbox-agent [options]
+
+Modes:
+  Standalone (default):   Full setup - copies template, installs deps, starts dev server
+  Agent-only:             Just runs the agent API (use with --agent-only)
+
+Options:
+  --workdir <path>        Project directory (default: ~/.papercrane/sandbox)
+  --agent-only            Only run agent API (no template setup, no dev server)
+  --port <port>           Agent API port (default: 3001)
+  --dev-port <port>       Dev server port, standalone only (default: 3000)
+  --register              Register with Papercrane server (requires --token)
+  --token <token>         Connection token from Papercrane UI
+  --papercrane-url <url>  Papercrane server URL (default: https://fly.papercrane.ai)
+  --help, -h              Show this help message
+
+Environment Variables:
+  PORT                    Agent API port (same as --port)
+  DEV_PORT                Dev server port (same as --dev-port)
+  PAPERCRANE_URL          Papercrane server URL (same as --papercrane-url)
+
+Examples:
+  sandbox-agent                                    # Standalone: full setup
+  sandbox-agent --workdir ~/my-project            # Standalone: custom directory
+  sandbox-agent --agent-only --workdir /tmp/app   # Agent-only: just the API
+      `);
+            process.exit(0);
+        }
+    }
+    return result;
+}
+const cliArgs = parseArgs();
+// =============================================================================
+// Template Management
+// =============================================================================
+const TEMPLATE_REPO_URL = process.env.TEMPLATE_REPO_URL || "https://github.com/papercraneai/sandbox-template.git";
+// Get the working directory for the project (Next.js root)
+function getWorkingDirectory() {
+    return cliArgs.workdir;
+}
+// Get the PROJECT_DIR (src/app within the working directory)
+// In agent-only mode, workdir IS the project dir (e.g., /tmp/project/src/app)
+function getProjectDir() {
+    if (cliArgs.agentOnly) {
+        return cliArgs.workdir;
+    }
+    return join(cliArgs.workdir, "src", "app");
+}
+// Check if directory exists
+async function directoryExists(path) {
+    try {
+        const stats = await stat(path);
+        return stats.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+// Check if file exists
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Run a shell command and return stdout
+function runCommand(command, cwd) {
+    return execSync(command, { cwd, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+}
+// Run npm install in the working directory
+async function runNpmInstall(workdir) {
+    console.log("Installing dependencies (this may take a minute)...");
+    return new Promise((resolve, reject) => {
+        const npm = spawn("npm", ["install"], {
+            cwd: workdir,
+            stdio: "inherit",
+            shell: true
+        });
+        npm.on("close", (code) => {
+            if (code === 0) {
+                console.log("✓ Dependencies installed");
+                resolve();
+            }
+            else {
+                reject(new Error(`npm install exited with code ${code}`));
+            }
+        });
+        npm.on("error", reject);
+    });
+}
+// Clone template repo to working directory
+async function cloneTemplate(workdir) {
+    console.log(`Cloning template from ${TEMPLATE_REPO_URL} to ${workdir}...`);
+    // Create parent directory if needed
+    await mkdir(dirname(workdir), { recursive: true });
+    return new Promise((resolve, reject) => {
+        const git = spawn("git", ["clone", TEMPLATE_REPO_URL, workdir], {
+            stdio: "inherit",
+            shell: true
+        });
+        git.on("close", (code) => {
+            if (code === 0) {
+                console.log("✓ Template cloned");
+                resolve();
+            }
+            else {
+                reject(new Error(`git clone exited with code ${code}`));
+            }
+        });
+        git.on("error", reject);
+    });
+}
+// Create initial src/app/ scaffold files if they don't exist
+async function ensureAppScaffold(workdir) {
+    const appDir = join(workdir, "src", "app");
+    await mkdir(appDir, { recursive: true });
+    const layoutPath = join(appDir, "layout.tsx");
+    if (!(await fileExists(layoutPath))) {
+        await writeFile(layoutPath, `import type { Metadata } from "next"
+import "./globals.css"
+
+export const metadata: Metadata = {
+  title: "Papercrane App",
+  description: "Built with Papercrane",
+}
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode
+}>) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>{children}</body>
+    </html>
+  )
+}
+`);
+        console.log("✓ Created scaffold layout.tsx");
+    }
+    const pagePath = join(appDir, "page.tsx");
+    if (!(await fileExists(pagePath))) {
+        await writeFile(pagePath, `export default function Home() {
+  return (
+    <div className="flex min-h-screen items-center justify-center">
+      <h1 className="text-4xl font-bold">Welcome to Papercrane</h1>
+    </div>
+  )
+}
+`);
+        console.log("✓ Created scaffold page.tsx");
+    }
+    const globalsCssPath = join(appDir, "globals.css");
+    if (!(await fileExists(globalsCssPath))) {
+        await writeFile(globalsCssPath, `@import "tailwindcss";
+`);
+        console.log("✓ Created scaffold globals.css");
+    }
+}
+// Next.js dev server process
+let nextDevProcess = null;
+// Start Next.js dev server
+function startNextDevServer(workdir, port) {
+    return new Promise((resolve, reject) => {
+        console.log(`Starting Next.js dev server on port ${port}...`);
+        nextDevProcess = spawn("npm", ["run", "dev", "--", "-p", String(port)], {
+            cwd: workdir,
+            stdio: ["ignore", "pipe", "pipe"],
+            shell: true
+        });
+        let resolved = false;
+        // Listen for "Ready" message from Next.js
+        nextDevProcess.stdout?.on("data", (data) => {
+            const output = data.toString();
+            process.stdout.write(`[next] ${output}`);
+            if (!resolved && (output.includes("Ready") || output.includes("started server"))) {
+                resolved = true;
+                console.log("✓ Next.js dev server started");
+                resolve();
+            }
+        });
+        nextDevProcess.stderr?.on("data", (data) => {
+            process.stderr.write(`[next] ${data}`);
+        });
+        nextDevProcess.on("error", (err) => {
+            if (!resolved) {
+                reject(err);
+            }
+        });
+        nextDevProcess.on("close", (code) => {
+            if (!resolved) {
+                reject(new Error(`Next.js dev server exited with code ${code}`));
+            }
+            nextDevProcess = null;
+        });
+        // Timeout after 60 seconds
+        setTimeout(() => {
+            if (!resolved) {
+                resolved = true;
+                // Assume it started if we haven't seen an error
+                console.log("✓ Next.js dev server started (assumed)");
+                resolve();
+            }
+        }, 60000);
+    });
+}
+// Setup template and start Next.js (standalone mode only)
+async function setupTemplate() {
+    const workdir = getWorkingDirectory();
+    // Check if workdir already has a git repo (already cloned)
+    const isGitRepo = await directoryExists(join(workdir, ".git"));
+    if (!isGitRepo) {
+        // First run: clone the template repo
+        await cloneTemplate(workdir);
+        await ensureAppScaffold(workdir);
+        await runNpmInstall(workdir);
+    }
+    else {
+        console.log(`Using existing template at ${workdir}`);
+        // Ensure scaffold files exist (in case they were removed)
+        await ensureAppScaffold(workdir);
+        // Check if node_modules exists
+        if (!(await directoryExists(join(workdir, "node_modules")))) {
+            await runNpmInstall(workdir);
+        }
+    }
+    // Start Next.js dev server
+    await startNextDevServer(workdir, cliArgs.devPort);
+    return getProjectDir();
+}
+// =============================================================================
+// Express App Setup
+// =============================================================================
+const app = express();
+app.use(express.json());
+const PORT = cliArgs.agentPort;
+let PROJECT_DIR = getProjectDir(); // Will be updated after template setup
+// Registration state
+let environmentId = null;
+let connectionToken = null;
+let heartbeatInterval = null;
+// Client-side tool: ShowPreview
+const showPreviewTool = tool("ShowPreview", "Shows the preview iframe for a specific route. Call this after creating or modifying a visualization so the user can see the result immediately. The preview will appear in the user's browser.", {
+    path: z.string().describe("The route path to preview, e.g., '/insights' or '/dashboard'. Must start with '/'")
+}, async (args) => {
+    return {
+        content: [{
+                type: "text",
+                text: `Preview activated for ${args.path}. The user can now see the visualization.`
+            }]
+    };
+});
+// Create MCP server for client-side tools
+const clientToolsServer = createSdkMcpServer({
+    name: "client-tools",
+    tools: [showPreviewTool]
+});
+// Recursively build file tree
+async function buildFileTree(dirPath) {
+    const entries = await readdir(dirPath, { withFileTypes: true });
+    const nodes = [];
+    entries.sort((a, b) => {
+        if (a.isDirectory() && !b.isDirectory())
+            return -1;
+        if (!a.isDirectory() && b.isDirectory())
+            return 1;
+        return a.name.localeCompare(b.name);
+    });
+    for (const entry of entries) {
+        if (entry.name === "node_modules" || entry.name.startsWith(".")) {
+            continue;
+        }
+        if (entry.isDirectory()) {
+            const children = await buildFileTree(join(dirPath, entry.name));
+            nodes.push({
+                name: entry.name,
+                type: "folder",
+                children
+            });
+        }
+        else {
+            nodes.push({
+                name: entry.name,
+                type: "file"
+            });
+        }
+    }
+    return nodes;
+}
+// Health check
+app.get("/health", (_req, res) => {
+    res.json({ status: "healthy", projectDir: PROJECT_DIR, version: pkg.version });
+});
+// Pull template updates (git pull + conditional npm install)
+app.post("/pull-template", async (_req, res) => {
+    const workdir = getWorkingDirectory();
+    try {
+        // Check if workdir is a git repo
+        if (!(await directoryExists(join(workdir, ".git")))) {
+            res.status(400).json({ error: "Working directory is not a git repository" });
+            return;
+        }
+        // Run git pull
+        const pullOutput = runCommand("git pull", workdir);
+        console.log(`git pull output: ${pullOutput}`);
+        // Check if already up to date
+        if (pullOutput.includes("Already up to date")) {
+            res.json({ updated: false, files_changed: [], npm_installed: false });
+            return;
+        }
+        // Get list of changed files from the pull
+        // git diff HEAD@{1} --name-only shows what changed in the last pull
+        let filesChanged = [];
+        try {
+            const diffOutput = runCommand("git diff HEAD@{1} --name-only", workdir);
+            filesChanged = diffOutput.split("\n").filter(f => f.trim());
+        }
+        catch {
+            // If HEAD@{1} doesn't exist, just report the pull succeeded
+            filesChanged = ["(unable to determine changed files)"];
+        }
+        // Check if package.json changed — if so, run npm install
+        const packageJsonChanged = filesChanged.some(f => f === "package.json" || f === "package-lock.json");
+        let npmInstalled = false;
+        if (packageJsonChanged) {
+            console.log("package.json changed, running npm install...");
+            await runNpmInstall(workdir);
+            npmInstalled = true;
+        }
+        // Ensure scaffold files still exist after pull
+        await ensureAppScaffold(workdir);
+        res.json({ updated: true, files_changed: filesChanged, npm_installed: npmInstalled });
+    }
+    catch (error) {
+        log.error({ error: error instanceof Error ? error.message : String(error) }, "Pull template failed");
+        res.status(500).json({
+            error: error instanceof Error ? error.message : "Failed to pull template"
+        });
+    }
+});
+// File tree endpoint
+app.get("/files/tree", async (req, res) => {
+    const subPath = req.query.path || "";
+    const fullPath = subPath ? join(PROJECT_DIR, subPath) : PROJECT_DIR;
+    try {
+        const dirStat = await stat(fullPath);
+        if (!dirStat.isDirectory()) {
+            res.status(400).json({ error: "Path is not a directory" });
+            return;
+        }
+        const tree = await buildFileTree(fullPath);
+        res.json({
+            path: fullPath,
+            tree
+        });
+    }
+    catch (error) {
+        console.error("File tree error for path:", fullPath);
+        console.error("Error details:", error);
+        if (error.code === "ENOENT") {
+            res.status(404).json({ error: "Directory not found", path: fullPath });
+        }
+        else {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : "Unknown error",
+                path: fullPath
+            });
+        }
+    }
+});
+// File read endpoint - returns file contents with metadata
+app.get("/files/read", async (req, res) => {
+    const filePath = req.query.path;
+    if (!filePath) {
+        res.status(400).json({ error: "Path query parameter is required" });
+        return;
+    }
+    // Resolve path relative to PROJECT_DIR
+    const fullPath = filePath.startsWith("/") ? filePath : join(PROJECT_DIR, filePath);
+    // Security: ensure path is within PROJECT_DIR or a parent (for standalone mode)
+    const normalizedPath = join(fullPath);
+    if (!normalizedPath.startsWith(PROJECT_DIR) && !PROJECT_DIR.startsWith(normalizedPath.split("/").slice(0, -1).join("/"))) {
+        res.status(403).json({ error: "Access denied: path outside project directory" });
+        return;
+    }
+    try {
+        const stats = await stat(fullPath);
+        if (stats.isDirectory()) {
+            res.status(400).json({ error: "Path is a directory, not a file" });
+            return;
+        }
+        // Limit file size to 1MB for reading
+        const MAX_FILE_SIZE = 1 * 1024 * 1024;
+        if (stats.size > MAX_FILE_SIZE) {
+            res.status(413).json({
+                error: "File too large to read",
+                size: stats.size,
+                maxSize: MAX_FILE_SIZE
+            });
+            return;
+        }
+        const content = await readFile(fullPath, "utf-8");
+        const ext = fullPath.split(".").pop()?.toLowerCase() || "";
+        // Determine mime type
+        const mimeTypes = {
+            ts: "text/typescript",
+            tsx: "text/typescript",
+            js: "text/javascript",
+            jsx: "text/javascript",
+            json: "application/json",
+            css: "text/css",
+            html: "text/html",
+            md: "text/markdown",
+            txt: "text/plain",
+            svg: "image/svg+xml",
+            png: "image/png",
+            jpg: "image/jpeg",
+            jpeg: "image/jpeg",
+            gif: "image/gif",
+            webp: "image/webp"
+        };
+        res.json({
+            path: fullPath,
+            name: fullPath.split("/").pop(),
+            content,
+            size: stats.size,
+            mimeType: mimeTypes[ext] || "text/plain",
+            extension: ext
+        });
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            res.status(404).json({ error: "File not found", path: fullPath });
+        }
+        else {
+            log.error({ error: error instanceof Error ? error.message : String(error), path: fullPath }, "File read error");
+            res.status(500).json({ error: error instanceof Error ? error.message : "Unknown error" });
+        }
+    }
+});
+// File download endpoint - returns file as attachment
+app.get("/files/download", async (req, res) => {
+    const filePath = req.query.path;
+    if (!filePath) {
+        res.status(400).json({ error: "Path query parameter is required" });
+        return;
+    }
+    const fullPath = filePath.startsWith("/") ? filePath : join(PROJECT_DIR, filePath);
+    // Security check
+    const normalizedPath = join(fullPath);
+    if (!normalizedPath.startsWith(PROJECT_DIR) && !PROJECT_DIR.startsWith(normalizedPath.split("/").slice(0, -1).join("/"))) {
+        res.status(403).json({ error: "Access denied: path outside project directory" });
+        return;
+    }
+    try {
+        const stats = await stat(fullPath);
+        if (stats.isDirectory()) {
+            res.status(400).json({ error: "Cannot download a directory" });
+            return;
+        }
+        const fileName = fullPath.split("/").pop() || "file";
+        const content = await readFile(fullPath);
+        res.setHeader("Content-Disposition", `attachment; filename="${fileName}"`);
+        res.setHeader("Content-Type", "application/octet-stream");
+        res.setHeader("Content-Length", stats.size);
+        res.send(content);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            res.status(404).json({ error: "File not found", path: fullPath });
+        }
+        else {
+            log.error({ error: error instanceof Error ? error.message : String(error), path: fullPath }, "File download error");
+            res.status(500).json({ error: error instanceof Error ? error.message : "Unknown error" });
+        }
+    }
+});
+// File upload endpoint
+const upload = multer({
+    storage: multer.memoryStorage(),
+    limits: { fileSize: 10 * 1024 * 1024 } // 10MB limit per file
+});
+app.post("/files/upload", upload.array("files", 10), async (req, res) => {
+    try {
+        const files = req.files;
+        if (!files || files.length === 0) {
+            res.status(400).json({ error: "No files provided" });
+            return;
+        }
+        // Get target path from query param or form field (defaults to "uploads")
+        const targetPath = req.query.targetPath || req.body?.targetPath || "uploads";
+        // Sanitize target path - remove leading/trailing slashes and prevent traversal
+        const sanitizedTargetPath = targetPath
+            .replace(/^\/+|\/+$/g, "") // Remove leading/trailing slashes
+            .split("/")
+            .filter(part => part !== ".." && part !== ".") // Remove traversal attempts
+            .join("/");
+        // Build the full target directory path
+        const targetDir = join(PROJECT_DIR, sanitizedTargetPath);
+        // Ensure target is within PROJECT_DIR
+        const resolvedTarget = resolve(targetDir);
+        const resolvedProject = resolve(PROJECT_DIR);
+        if (!resolvedTarget.startsWith(resolvedProject)) {
+            res.status(403).json({ error: "Invalid target path" });
+            return;
+        }
+        // Create target directory if it doesn't exist
+        await mkdir(targetDir, { recursive: true });
+        const uploadedFiles = [];
+        for (const file of files) {
+            // Sanitize filename - remove path traversal attempts
+            const safeName = file.originalname.replace(/[\/\\]/g, "_");
+            const filePath = join(targetDir, safeName);
+            const relativePath = sanitizedTargetPath ? `${sanitizedTargetPath}/${safeName}` : safeName;
+            await writeFile(filePath, file.buffer);
+            uploadedFiles.push({
+                name: safeName,
+                path: relativePath,
+                size: file.size
+            });
+            log.info({ fileName: safeName, size: file.size, targetPath: sanitizedTargetPath }, "File uploaded");
+        }
+        res.json({ files: uploadedFiles });
+    }
+    catch (error) {
+        log.error({ error: error instanceof Error ? error.message : String(error) }, "File upload failed");
+        res.status(500).json({
+            error: error instanceof Error ? error.message : "Upload failed"
+        });
+    }
+});
+// Helper to encode path for Claude session storage (slashes and dots become dashes)
+function encodeSessionPath(path) {
+    return path.replace(/[\/\.]/g, "-");
+}
+// Get the directory where Claude stores sessions for this project
+function getSessionsDir() {
+    const claudeConfigDir = process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
+    const encodedPath = encodeSessionPath(PROJECT_DIR);
+    return join(claudeConfigDir, "projects", encodedPath);
+}
+// Parse a JSONL file to extract session metadata
+async function getSessionMetadata(sessionPath, sessionId) {
+    try {
+        const content = await readFile(sessionPath, "utf-8");
+        const lines = content.trim().split("\n").filter(line => line.trim());
+        let firstMessage = null;
+        let lastMessageAt = null;
+        let createdAt = null;
+        let messageCount = 0;
+        for (const line of lines) {
+            try {
+                const entry = JSON.parse(line);
+                // Track timestamps
+                if (entry.timestamp) {
+                    if (!createdAt)
+                        createdAt = entry.timestamp;
+                    lastMessageAt = entry.timestamp;
+                }
+                // Count user/assistant messages and get first user message
+                if (entry.type === "user" || entry.type === "assistant") {
+                    messageCount++;
+                    if (entry.type === "user" && !firstMessage && entry.message?.content) {
+                        // Handle both string content and array content
+                        const content = entry.message.content;
+                        if (typeof content === "string") {
+                            firstMessage = content.slice(0, 100);
+                        }
+                        else if (Array.isArray(content)) {
+                            const textBlock = content.find((b) => b.type === "text");
+                            if (textBlock?.text) {
+                                firstMessage = textBlock.text.slice(0, 100);
+                            }
+                        }
+                    }
+                }
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+        return { id: sessionId, firstMessage, lastMessageAt, createdAt, messageCount };
+    }
+    catch (error) {
+        return { id: sessionId, firstMessage: null, lastMessageAt: null, createdAt: null, messageCount: 0 };
+    }
+}
+// List all chat sessions
+app.get("/sessions", async (_req, res) => {
+    try {
+        const sessionsDir = getSessionsDir();
+        log.info({ sessionsDir, projectDir: PROJECT_DIR }, "Listing sessions");
+        // Check if sessions directory exists
+        if (!(await directoryExists(sessionsDir))) {
+            log.info({ sessionsDir }, "Sessions directory does not exist");
+            res.json({ sessions: [] });
+            return;
+        }
+        const files = await readdir(sessionsDir);
+        log.info({ sessionsDir, fileCount: files.length, files }, "Found files in sessions directory");
+        const jsonlFiles = files.filter(f => f.endsWith(".jsonl"));
+        log.info({ jsonlFileCount: jsonlFiles.length, jsonlFiles }, "Found JSONL session files");
+        // Get metadata for each session
+        const sessions = [];
+        for (const file of jsonlFiles) {
+            const sessionId = file.replace(".jsonl", "");
+            const sessionPath = join(sessionsDir, file);
+            const metadata = await getSessionMetadata(sessionPath, sessionId);
+            sessions.push(metadata);
+        }
+        // Sort by lastMessageAt descending (most recent first)
+        sessions.sort((a, b) => {
+            if (!a.lastMessageAt)
+                return 1;
+            if (!b.lastMessageAt)
+                return -1;
+            return new Date(b.lastMessageAt).getTime() - new Date(a.lastMessageAt).getTime();
+        });
+        log.info({ sessionCount: sessions.length }, "Returning sessions");
+        res.json({ sessions });
+    }
+    catch (error) {
+        log.error({ error: error instanceof Error ? error.message : String(error) }, "Failed to list sessions");
+        res.status(500).json({ error: "Failed to list sessions" });
+    }
+});
+// Get a single session's messages
+app.get("/sessions/:id", async (req, res) => {
+    try {
+        const { id } = req.params;
+        const sessionsDir = getSessionsDir();
+        const sessionPath = join(sessionsDir, `${id}.jsonl`);
+        // Check if session file exists
+        if (!(await fileExists(sessionPath))) {
+            res.status(404).json({ error: "Session not found" });
+            return;
+        }
+        const content = await readFile(sessionPath, "utf-8");
+        const lines = content.trim().split("\n").filter(line => line.trim());
+        // Parse messages, transforming to chat UI format
+        const messages = [];
+        for (const line of lines) {
+            try {
+                const entry = JSON.parse(line);
+                // Only include user and assistant messages
+                if (entry.type === "user" && entry.message) {
+                    const content = entry.message.content;
+                    let blocks;
+                    if (typeof content === "string") {
+                        blocks = [{ type: "text", text: content }];
+                    }
+                    else if (Array.isArray(content)) {
+                        blocks = content;
+                    }
+                    else {
+                        continue;
+                    }
+                    messages.push({
+                        role: "user",
+                        blocks,
+                        timestamp: entry.timestamp || new Date().toISOString()
+                    });
+                }
+                else if (entry.type === "assistant" && entry.message?.content) {
+                    messages.push({
+                        role: "assistant",
+                        blocks: entry.message.content,
+                        timestamp: entry.timestamp || new Date().toISOString()
+                    });
+                }
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+        res.json({ sessionId: id, messages });
+    }
+    catch (error) {
+        log.error({ error: error instanceof Error ? error.message : String(error) }, "Failed to get session");
+        res.status(500).json({ error: "Failed to get session" });
+    }
+});
+// Helper to build hooks for streaming
+const buildHooks = (res, verbose, requestId, requestStartTime) => {
+    const toolTimings = new Map();
+    const ctx = { requestId };
+    const hooks = {
+        PreToolUse: [
+            {
+                // Log timing for all tools
+                hooks: [async (input, toolUseID) => {
+                        const toolName = String(input.tool_name);
+                        if (toolUseID) {
+                            toolTimings.set(toolUseID, { startTime: Date.now(), toolName });
+                        }
+                        log.debug({ ...ctx, toolName, toolUseId: toolUseID, elapsed: Date.now() - requestStartTime }, "Tool START");
+                        return { continue: true };
+                    }]
+            },
+            {
+                matcher: /^mcp__client-tools__/,
+                hooks: [async (input, toolUseID) => {
+                        res.write(`data: ${JSON.stringify({
+                            type: "client_tool",
+                            tool_use_id: toolUseID,
+                            tool_name: String(input.tool_name).replace("mcp__client-tools__", ""),
+                            input: input.tool_input
+                        })}\n\n`);
+                        return {
+                            hookSpecificOutput: {
+                                hookEventName: "PreToolUse",
+                                permissionDecision: "allow"
+                            }
+                        };
+                    }]
+            }
+        ],
+        PostToolUse: [{
+                hooks: [async (input, toolUseID) => {
+                        const timing = toolUseID ? toolTimings.get(toolUseID) : undefined;
+                        const duration = timing ? Date.now() - timing.startTime : 0;
+                        log.debug({ ...ctx, toolName: String(input.tool_name), toolUseId: toolUseID, duration, elapsed: Date.now() - requestStartTime }, "Tool END");
+                        if (toolUseID)
+                            toolTimings.delete(toolUseID);
+                        if (verbose) {
+                            res.write(`data: ${JSON.stringify({
+                                type: "tool_result",
+                                tool_use_id: toolUseID,
+                                tool_name: input.tool_name,
+                                tool_response: input.tool_response
+                            })}\n\n`);
+                        }
+                        return {
+                            continue: true,
+                            hookSpecificOutput: { hookEventName: "PostToolUse" }
+                        };
+                    }]
+            }],
+        PostToolUseFailure: [{
+                hooks: [async (input, toolUseID) => {
+                        const timing = toolUseID ? toolTimings.get(toolUseID) : undefined;
+                        const duration = timing ? Date.now() - timing.startTime : 0;
+                        log.warn({ ...ctx, toolName: String(input.tool_name), toolUseId: toolUseID, duration, elapsed: Date.now() - requestStartTime, error: String(input.error) }, "Tool FAILED");
+                        if (toolUseID)
+                            toolTimings.delete(toolUseID);
+                        if (verbose) {
+                            res.write(`data: ${JSON.stringify({
+                                type: "tool_error",
+                                tool_use_id: toolUseID,
+                                tool_name: input.tool_name,
+                                error: input.error
+                            })}\n\n`);
+                        }
+                        return {
+                            continue: true,
+                            hookSpecificOutput: { hookEventName: "PostToolUseFailure" }
+                        };
+                    }]
+            }]
+    };
+    return hooks;
+};
+// Chat endpoint - streaming SSE
+app.post("/chat", async (req, res) => {
+    const requestStartTime = Date.now();
+    const requestId = Math.random().toString(36).substring(7);
+    const { message, sessionId, systemPrompt, verbose = false, subdir, 
+    // Configurable agent options
+    maxTurns = 40, allowedTools, disallowedTools, model, maxBudgetUsd } = req.body;
+    const ctx = { requestId, sessionId };
+    log.info(ctx, "Agent received chat request");
+    if (!message) {
+        res.status(400).json({ error: "Message is required" });
+        return;
+    }
+    // Require systemPrompt for new sessions
+    if (!sessionId && !systemPrompt) {
+        res.status(400).json({ error: "systemPrompt is required for new sessions" });
+        return;
+    }
+    // Log the full system prompt for new sessions
+    if (!sessionId && systemPrompt) {
+        log.info(ctx, "=== NEW SESSION SYSTEM PROMPT ===");
+        console.log("\n" + "=".repeat(60));
+        console.log("SYSTEM PROMPT FOR NEW SESSION:");
+        console.log("=".repeat(60));
+        console.log(systemPrompt);
+        console.log("=".repeat(60) + "\n");
+    }
+    // Determine working directory - optionally use subdirectory
+    const cwd = subdir ? join(PROJECT_DIR, subdir) : PROJECT_DIR;
+    log.debug({ ...ctx, cwd }, "Working directory");
+    res.setHeader("Content-Type", "text/event-stream");
+    res.setHeader("Cache-Control", "no-cache");
+    res.setHeader("Connection", "keep-alive");
+    res.setHeader("X-Accel-Buffering", "no");
+    res.socket?.setNoDelay(true);
+    res.flushHeaders();
+    const abortController = new AbortController();
+    let isAborted = false;
+    res.on("close", () => {
+        if (!res.writableEnded) {
+            isAborted = true;
+            abortController.abort();
+        }
+    });
+    const hooks = buildHooks(res, verbose, requestId, requestStartTime);
+    async function* createPrompt() {
+        yield {
+            type: "user",
+            message: {
+                role: "user",
+                content: message
+            },
+            parent_tool_use_id: null
+        };
+    }
+    // Default tools if not specified
+    const defaultTools = [
+        "Read",
+        "Write",
+        "Edit",
+        "Glob",
+        "Grep",
+        "Bash",
+        "mcp__client-tools__ShowPreview"
+    ];
+    const options = {
+        maxTurns,
+        cwd,
+        permissionMode: "bypassPermissions",
+        allowDangerouslySkipPermissions: true,
+        mcpServers: {
+            "client-tools": clientToolsServer
+        },
+        allowedTools: allowedTools || defaultTools,
+        hooks,
+        abortController,
+        includePartialMessages: true
+    };
+    // System prompt must be passed on EVERY request (it's not stored with the session)
+    // resume only loads conversation history, not the system prompt
+    if (systemPrompt) {
+        options.systemPrompt = systemPrompt;
+    }
+    if (sessionId) {
+        options.resume = sessionId;
+    }
+    // Add optional parameters if provided
+    if (disallowedTools) {
+        options.disallowedTools = disallowedTools;
+    }
+    if (model) {
+        options.model = model;
+    }
+    if (maxBudgetUsd) {
+        options.maxBudgetUsd = maxBudgetUsd;
+    }
+    try {
+        let gotResult = false;
+        log.debug({ ...ctx, elapsed: Date.now() - requestStartTime }, "Starting Claude SDK query");
+        // Determine which model is being used (either provided or SDK default)
+        const usedModel = model || options.model || "claude-sonnet-4-5-20250929";
+        for await (const msg of query({
+            prompt: createPrompt(),
+            options
+        })) {
+            if (isAborted)
+                break;
+            // Add model to result message so it can be logged for billing
+            if (msg.type === "result") {
+                const resultWithModel = { ...msg, model: usedModel };
+                res.write(`data: ${JSON.stringify(resultWithModel)}\n\n`);
+                gotResult = true;
+                log.info({ ...ctx, elapsed: Date.now() - requestStartTime }, "Query complete");
+                res.write("data: [DONE]\n\n");
+                res.end();
+                return;
+            }
+            res.write(`data: ${JSON.stringify(msg)}\n\n`);
+        }
+        if (!gotResult && !res.writableEnded) {
+            log.warn({ ...ctx, elapsed: Date.now() - requestStartTime, isAborted }, "Query ended without result");
+            if (isAborted) {
+                res.write(`data: ${JSON.stringify({ type: "aborted" })}\n\n`);
+            }
+            else {
+                res.write(`data: ${JSON.stringify({ type: "error", error: "Stream ended unexpectedly" })}\n\n`);
+            }
+            res.write("data: [DONE]\n\n");
+            res.end();
+        }
+    }
+    catch (error) {
+        const isAbortError = error instanceof Error &&
+            (error.name === "AbortError" || error.constructor.name === "AbortError");
+        if (isAbortError || isAborted) {
+            if (!res.writableEnded) {
+                res.write(`data: ${JSON.stringify({ type: "aborted" })}\n\n`);
+                res.write("data: [DONE]\n\n");
+                res.end();
+            }
+            return;
+        }
+        log.error({ ...ctx, error: error instanceof Error ? error.message : String(error) }, "Agent error");
+        if (!res.writableEnded) {
+            res.write(`data: ${JSON.stringify({
+                type: "error",
+                error: error instanceof Error ? error.message : "Unknown error"
+            })}\n\n`);
+            res.end();
+        }
+    }
+});
+// =============================================================================
+// Registration & Heartbeat
+// =============================================================================
+async function registerWithPapercrane() {
+    if (!cliArgs.token) {
+        console.error("Error: --token is required when using --register");
+        return false;
+    }
+    console.log(`Registering with Papercrane server at ${cliArgs.papercraneUrl}...`);
+    try {
+        const agentEndpoint = `http://localhost:${cliArgs.agentPort}`;
+        const previewEndpoint = `http://localhost:${cliArgs.devPort}`;
+        const res = await fetch(`${cliArgs.papercraneUrl}/api/environments/register`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                connectionToken: cliArgs.token,
+                agentEndpoint,
+                previewEndpoint
+            })
+        });
+        if (!res.ok) {
+            const data = await res.json().catch(() => ({ error: "Unknown error" }));
+            console.error(`Registration failed: ${data.error}`);
+            return false;
+        }
+        const data = await res.json();
+        environmentId = data.environmentId;
+        connectionToken = cliArgs.token;
+        console.log(`✓ Successfully registered as environment #${environmentId}`);
+        console.log(`  Agent endpoint: ${agentEndpoint}`);
+        console.log(`  Preview endpoint: ${previewEndpoint}`);
+        startHeartbeat();
+        return true;
+    }
+    catch (error) {
+        console.error("Registration error:", error instanceof Error ? error.message : error);
+        return false;
+    }
+}
+async function sendHeartbeat() {
+    if (!environmentId || !connectionToken)
+        return;
+    try {
+        const res = await fetch(`${cliArgs.papercraneUrl}/api/environments/${environmentId}/heartbeat`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Authorization": `Bearer ${connectionToken}`
+            }
+        });
+        if (!res.ok) {
+            const data = await res.json().catch(() => ({ error: "Unknown error" }));
+            console.error(`Heartbeat failed: ${data.error}`);
+        }
+    }
+    catch (error) {
+        console.error("Heartbeat error:", error instanceof Error ? error.message : error);
+    }
+}
+function startHeartbeat() {
+    if (heartbeatInterval) {
+        clearInterval(heartbeatInterval);
+    }
+    heartbeatInterval = setInterval(sendHeartbeat, 30000);
+    sendHeartbeat();
+}
+// =============================================================================
+// Shutdown Handling
+// =============================================================================
+let isShuttingDown = false;
+function killChildProcess() {
+    if (nextDevProcess) {
+        console.log("Stopping Next.js dev server...");
+        nextDevProcess.kill("SIGTERM");
+        nextDevProcess = null;
+    }
+}
+function handleShutdown(exitCode = 0) {
+    if (isShuttingDown)
+        return;
+    isShuttingDown = true;
+    console.log("\nShutting down...");
+    // Stop heartbeat
+    if (heartbeatInterval) {
+        clearInterval(heartbeatInterval);
+        heartbeatInterval = null;
+    }
+    // Kill Next.js dev server
+    killChildProcess();
+    // Notify Papercrane of disconnect
+    if (environmentId && connectionToken) {
+        console.log("Disconnecting from Papercrane...");
+        fetch(`${cliArgs.papercraneUrl}/api/environments/${environmentId}/disconnect`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Authorization": `Bearer ${connectionToken}`
+            }
+        }).catch(() => { });
+    }
+    process.exit(exitCode);
+}
+// Handle various exit scenarios
+process.on("SIGINT", () => handleShutdown(0));
+process.on("SIGTERM", () => handleShutdown(0));
+// Handle uncaught errors - ensure child process is killed
+process.on("uncaughtException", (err) => {
+    console.error("Uncaught exception:", err);
+    handleShutdown(1);
+});
+process.on("unhandledRejection", (reason) => {
+    console.error("Unhandled rejection:", reason);
+    handleShutdown(1);
+});
+// Handle normal exit - last-resort cleanup (only synchronous operations work here)
+process.on("exit", () => {
+    if (nextDevProcess) {
+        try {
+            nextDevProcess.kill("SIGTERM");
+        }
+        catch {
+            // Process may already be dead
+        }
+    }
+});
+// =============================================================================
+// Main Entry Point
+// =============================================================================
+async function start() {
+    try {
+        const mode = cliArgs.agentOnly ? "agent-only" : "standalone";
+        if (cliArgs.agentOnly) {
+            // Agent-only mode: just set PROJECT_DIR and start agent
+            PROJECT_DIR = cliArgs.workdir;
+            log.info({ mode, projectDir: PROJECT_DIR }, "Agent-only mode starting");
+        }
+        else {
+            // Standalone mode: full setup with template and dev server
+            log.info({ mode }, "Standalone mode: setting up template and dev server");
+            PROJECT_DIR = await setupTemplate();
+        }
+        // Register with Papercrane if requested
+        if (cliArgs.register) {
+            const success = await registerWithPapercrane();
+            if (!success) {
+                process.exit(1);
+            }
+        }
+        // Start the agent API server
+        app.listen(PORT, () => {
+            log.info({
+                port: PORT,
+                mode,
+                projectDir: PROJECT_DIR,
+                devPort: cliArgs.agentOnly ? undefined : cliArgs.devPort,
+                papercraneUrl: cliArgs.register ? cliArgs.papercraneUrl : undefined,
+                logLevel: log.getLogLevel()
+            }, "Sandbox agent ready");
+            // Also print human-readable startup message
+            console.log(`\n✓ Sandbox agent running on port ${PORT}`);
+            console.log(`  Mode: ${mode}`);
+            console.log(`  Log level: ${log.getLogLevel()}`);
+            console.log(`  Project directory: ${PROJECT_DIR}`);
+            if (!cliArgs.agentOnly) {
+                console.log(`  Dev server: http://localhost:${cliArgs.devPort}`);
+            }
+            if (cliArgs.register) {
+                console.log(`  Connected to Papercrane at ${cliArgs.papercraneUrl}`);
+            }
+            console.log(`\nReady to accept connections.`);
+        });
+    }
+    catch (error) {
+        log.error({ error: error instanceof Error ? error.message : String(error) }, "Failed to start");
+        process.exit(1);
+    }
+}
+start();