@papercraneai/sandbox-agent 0.1.13 → 0.1.14-beta.1

package/dist/dashboard-fs/read.js

@@ -0,0 +1,190 @@
+import { open } from "fs/promises";
+import { extname } from "path";
+import { lookup } from "./file-index.js";
+const DEFAULT_LIMIT = 2000;
+const MAX_LINE_LENGTH = 2000;
+const MAX_LINE_SUFFIX = `... (line truncated to ${MAX_LINE_LENGTH} chars)`;
+const MAX_BYTES = 50 * 1024;
+const MAX_BYTES_LABEL = `${MAX_BYTES / 1024} KB`;
+const SAMPLE_BYTES = 4096;
+// Binary-file detection ported from opencode read.ts:104-149 (MIT).
+// Pure function: extension list + null-byte / non-printable density check.
+const BINARY_EXTENSIONS = new Set([
+    ".zip", ".tar", ".gz", ".exe", ".dll", ".so", ".class", ".jar", ".war",
+    ".7z", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx", ".odt", ".ods",
+    ".odp", ".bin", ".dat", ".obj", ".o", ".a", ".lib", ".wasm", ".pyc", ".pyo",
+    // Images and PDFs are also binary; we report them as binary for v1 since the
+    // shared-view chat surface doesn't have an image-attachment path. We can add
+    // base64 attachment support later if useful.
+    ".png", ".jpg", ".jpeg", ".gif", ".webp", ".pdf", ".ico", ".svg"
+]);
+function isBinaryFile(filepath, sample) {
+    if (BINARY_EXTENSIONS.has(extname(filepath).toLowerCase()))
+        return true;
+    if (sample.length === 0)
+        return false;
+    let nonPrintableCount = 0;
+    for (let i = 0; i < sample.length; i++) {
+        if (sample[i] === 0)
+            return true;
+        if (sample[i] < 9 || (sample[i] > 13 && sample[i] < 32)) {
+            nonPrintableCount++;
+        }
+    }
+    return nonPrintableCount / sample.length > 0.3;
+}
+async function readSample(filePath, fileSize) {
+    const handle = await open(filePath, "r");
+    try {
+        const sampleSize = Math.min(fileSize, SAMPLE_BYTES);
+        const buf = Buffer.alloc(sampleSize);
+        await handle.read(buf, 0, sampleSize, 0);
+        return buf;
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function readLines(filePath, offset, limit) {
+    const { createReadStream } = await import("fs");
+    const { createInterface } = await import("readline");
+    const stream = createReadStream(filePath, { encoding: "utf-8" });
+    const rl = createInterface({ input: stream, crlfDelay: Infinity });
+    const lines = [];
+    let totalLines = 0;
+    let bytes = 0;
+    let truncatedByBytes = false;
+    let hasMore = false;
+    try {
+        for await (const rawLine of rl) {
+            totalLines++;
+            if (totalLines < offset)
+                continue;
+            if (lines.length >= limit) {
+                hasMore = true;
+                // Continue counting totalLines so the caller can report the full count.
+                continue;
+            }
+            let line = rawLine;
+            if (line.length > MAX_LINE_LENGTH) {
+                line = line.slice(0, MAX_LINE_LENGTH) + MAX_LINE_SUFFIX;
+            }
+            const lineBytes = Buffer.byteLength(line, "utf-8") + 1;
+            if (bytes + lineBytes > MAX_BYTES) {
+                truncatedByBytes = true;
+                hasMore = true;
+                // Continue counting totalLines so the caller can report the full count.
+                continue;
+            }
+            bytes += lineBytes;
+            lines.push(line);
+        }
+    }
+    finally {
+        rl.close();
+        stream.destroy();
+    }
+    const startLine = offset;
+    const endLine = startLine + lines.length - 1;
+    return {
+        content: lines.map((l, i) => `${i + startLine}: ${l}`).join("\n"),
+        totalLines,
+        startLine,
+        endLine,
+        truncatedByBytes,
+        hasMore
+    };
+}
+/**
+ * Reads a file by handle. The agent never sees or constructs a path; the
+ * `fileId` is opaque and resolves to an absolute path only via the
+ * server-built index. Output format mirrors what models trained on the
+ * SDK Read tool already expect: `<line>: <content>` with truncation
+ * markers and a footer explaining offset/total.
+ */
+export async function executeReadFile(index, args) {
+    const entry = lookup(index, args.fileId);
+    if (!entry) {
+        return {
+            content: [{ type: "text", text: `Error: unknown fileId. Use ListFiles to discover available files.` }],
+            isError: true
+        };
+    }
+    const offsetRaw = args.offset;
+    const limitRaw = args.limit;
+    const offset = typeof offsetRaw === "number" && offsetRaw >= 1 ? Math.floor(offsetRaw) : 1;
+    const limit = typeof limitRaw === "number" && limitRaw >= 1 ? Math.floor(limitRaw) : DEFAULT_LIMIT;
+    if (offset < 1) {
+        return {
+            content: [{ type: "text", text: `Error: offset must be >= 1` }],
+            isError: true
+        };
+    }
+    let sample;
+    try {
+        sample = await readSample(entry.absolutePath, entry.size);
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Error reading file: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true
+        };
+    }
+    if (isBinaryFile(entry.absolutePath, sample)) {
+        return {
+            content: [{ type: "text", text: `Error: cannot read binary file ${entry.relativePath}` }],
+            isError: true
+        };
+    }
+    const result = await readLines(entry.absolutePath, offset, limit);
+    if (result.totalLines === 0 && offset === 1) {
+        return {
+            content: [{ type: "text", text: `<path>${entry.relativePath}</path>\n<content>\n(empty file)\n</content>` }]
+        };
+    }
+    if (result.totalLines < offset) {
+        return {
+            content: [{ type: "text", text: `Error: offset ${offset} is out of range for this file (${result.totalLines} lines)` }],
+            isError: true
+        };
+    }
+    let footer;
+    if (result.truncatedByBytes) {
+        footer = `(Output capped at ${MAX_BYTES_LABEL}. Showing lines ${result.startLine}-${result.endLine}. Use offset=${result.endLine + 1} to continue.)`;
+    }
+    else if (result.hasMore) {
+        footer = `(Showing lines ${result.startLine}-${result.endLine} of ${result.totalLines}. Use offset=${result.endLine + 1} to continue.)`;
+    }
+    else {
+        footer = `(End of file - total ${result.totalLines} lines)`;
+    }
+    const text = [
+        `<path>${entry.relativePath}</path>`,
+        `<content>`,
+        result.content,
+        ``,
+        footer,
+        `</content>`
+    ].join("\n");
+    return { content: [{ type: "text", text }] };
+}
+/**
+ * Returns the index as a list of `{ fileId, relativePath, size, writable }`.
+ * The agent uses this to discover what's readable before issuing ReadFile.
+ */
+export function executeListFiles(index) {
+    const items = [...index.entries()].map(([fileId, entry]) => ({
+        fileId,
+        relativePath: entry.relativePath,
+        size: entry.size,
+        writable: entry.writable
+    }));
+    // Sort by relativePath for stable, predictable output.
+    items.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({ files: items, total: items.length }, null, 2)
+            }]
+    };
+}

package/dist/dashboard-fs/write.d.ts

@@ -0,0 +1,36 @@
+import type { FileIndex } from "./file-index.js";
+interface WriteFileArgs {
+    fileId: unknown;
+    content: unknown;
+}
+interface ToolResult {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Writes a file by handle. The fileId must reference a writable entry in the index.
+ * Preserves the original file's line endings so diffs stay clean. Returns a unified
+ * diff of what changed.
+ *
+ * Not in shared-view's `allowedTools` for v1 — registered for use by future authoring
+ * surfaces with reduced privilege.
+ */
+export declare function executeWriteFile(index: FileIndex, args: WriteFileArgs): Promise<ToolResult>;
+interface CreateFileArgs {
+    relativePath: unknown;
+    content: unknown;
+}
+/**
+ * Creates a new file under the dashboard root. Validates the relativePath has
+ * no `..` segments and isn't absolute; the absolute path is resolved against the
+ * dashboard root (passed in via `dashboardRoot`). The new file is added to the
+ * index and a fresh fileId is returned for subsequent reads/writes.
+ *
+ * Not in shared-view's `allowedTools` for v1.
+ */
+export declare function executeCreateFile(index: FileIndex, dashboardRoot: string, args: CreateFileArgs): Promise<ToolResult>;
+export {};

package/dist/dashboard-fs/write.js

@@ -0,0 +1,179 @@
+import { readFile, writeFile, stat } from "fs/promises";
+import { createTwoFilesPatch } from "diff";
+import { lookup } from "./file-index.js";
+/**
+ * Detects whether the given text uses CRLF line endings. Ported from gemini-cli's
+ * write-file.ts approach (Apache 2.0). When the existing file uses CRLF, new content
+ * is normalized to CRLF too — avoids polluting diffs with line-ending churn.
+ */
+function detectCrlf(text) {
+    return text.includes("\r\n");
+}
+function applyLineEndings(text, useCrlf) {
+    // Normalize the input first to LF, then upgrade if needed.
+    const lf = text.replaceAll("\r\n", "\n");
+    return useCrlf ? lf.replaceAll("\n", "\r\n") : lf;
+}
+async function readExisting(entry) {
+    try {
+        const buf = await readFile(entry.absolutePath, "utf-8");
+        return { existed: true, content: buf };
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return { existed: false, content: "" };
+        }
+        throw err;
+    }
+}
+/**
+ * Writes a file by handle. The fileId must reference a writable entry in the index.
+ * Preserves the original file's line endings so diffs stay clean. Returns a unified
+ * diff of what changed.
+ *
+ * Not in shared-view's `allowedTools` for v1 — registered for use by future authoring
+ * surfaces with reduced privilege.
+ */
+export async function executeWriteFile(index, args) {
+    const entry = lookup(index, args.fileId);
+    if (!entry) {
+        return {
+            content: [{ type: "text", text: `Error: unknown fileId. Use ListFiles to discover available files.` }],
+            isError: true
+        };
+    }
+    if (!entry.writable) {
+        return {
+            content: [{ type: "text", text: `Error: file ${entry.relativePath} is not writable in this session.` }],
+            isError: true
+        };
+    }
+    if (typeof args.content !== "string") {
+        return {
+            content: [{ type: "text", text: `Error: content must be a string` }],
+            isError: true
+        };
+    }
+    let existing;
+    try {
+        existing = await readExisting(entry);
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Error reading existing file: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true
+        };
+    }
+    const useCrlf = existing.existed && detectCrlf(existing.content);
+    const newContent = applyLineEndings(args.content, useCrlf);
+    try {
+        await writeFile(entry.absolutePath, newContent, "utf-8");
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Error writing file: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true
+        };
+    }
+    // Refresh the index entry's size so subsequent ReadFile reflects the new state.
+    try {
+        const s = await stat(entry.absolutePath);
+        entry.size = s.size;
+    }
+    catch { /* non-fatal */ }
+    const diff = createTwoFilesPatch(entry.relativePath, entry.relativePath, existing.content, newContent, existing.existed ? "before" : "(new file)", "after");
+    // Strip the standard `Index:` header that diff emits — it's noise for the model.
+    const trimmedDiff = diff.replace(/^Index: .*\n=+\n/m, "");
+    const summary = existing.existed
+        ? `Wrote ${entry.relativePath} (${newContent.length} bytes)`
+        : `Created ${entry.relativePath} (${newContent.length} bytes)`;
+    return {
+        content: [{
+                type: "text",
+                text: `${summary}\n\n${trimmedDiff}`
+            }]
+    };
+}
+/**
+ * Creates a new file under the dashboard root. Validates the relativePath has
+ * no `..` segments and isn't absolute; the absolute path is resolved against the
+ * dashboard root (passed in via `dashboardRoot`). The new file is added to the
+ * index and a fresh fileId is returned for subsequent reads/writes.
+ *
+ * Not in shared-view's `allowedTools` for v1.
+ */
+export async function executeCreateFile(index, dashboardRoot, args) {
+    if (typeof args.relativePath !== "string" || args.relativePath.length === 0) {
+        return {
+            content: [{ type: "text", text: `Error: relativePath must be a non-empty string` }],
+            isError: true
+        };
+    }
+    if (typeof args.content !== "string") {
+        return {
+            content: [{ type: "text", text: `Error: content must be a string` }],
+            isError: true
+        };
+    }
+    const rel = args.relativePath;
+    if (rel.startsWith("/") || rel.includes("\0")) {
+        return {
+            content: [{ type: "text", text: `Error: relativePath must be relative and not contain null bytes` }],
+            isError: true
+        };
+    }
+    // Reject any path segment equal to ".." — can't escape the root.
+    const segments = rel.split(/[\\/]/);
+    if (segments.some((s) => s === ".." || s === ".")) {
+        return {
+            content: [{ type: "text", text: `Error: relativePath must not contain "." or ".." segments` }],
+            isError: true
+        };
+    }
+    const { join, isAbsolute } = await import("path");
+    const { randomBytes } = await import("crypto");
+    const absolutePath = join(dashboardRoot, rel);
+    // Belt and suspenders — the resolved absolute path must be under dashboardRoot.
+    if (!isAbsolute(absolutePath) || !absolutePath.startsWith(dashboardRoot)) {
+        return {
+            content: [{ type: "text", text: `Error: resolved path is outside dashboard root` }],
+            isError: true
+        };
+    }
+    // Don't overwrite an existing file silently — Write does that, Create doesn't.
+    try {
+        await stat(absolutePath);
+        return {
+            content: [{ type: "text", text: `Error: file already exists at ${rel}. Use WriteFile to overwrite.` }],
+            isError: true
+        };
+    }
+    catch { /* expected — file shouldn't exist */ }
+    // Write the file, then add to index.
+    const { mkdir } = await import("fs/promises");
+    const { dirname } = await import("path");
+    try {
+        await mkdir(dirname(absolutePath), { recursive: true });
+        await writeFile(absolutePath, args.content, "utf-8");
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Error creating file: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true
+        };
+    }
+    const fileId = `f_${randomBytes(8).toString("hex")}`;
+    const s = await stat(absolutePath);
+    index.set(fileId, {
+        absolutePath,
+        relativePath: rel,
+        writable: true,
+        size: s.size
+    });
+    return {
+        content: [{
+                type: "text",
+                text: `Created ${rel} (${s.size} bytes). fileId: ${fileId}`
+            }]
+    };
+}

package/dist/index.js

@@ -4,6 +4,8 @@ import { createServer } from "http";
 import { WebSocketServer, WebSocket } from "ws";
 import { Tail } from "tail";
 import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
+import { createDashboardFsServer } from "./dashboard-fs/index.js";
+import { createPapercraneDataServer } from "./papercrane-data/index.js";
 import { realpathSync } from "fs";
 import { readdir, stat, mkdir, readFile, writeFile, access, unlink, rm } from "fs/promises";
 import { join, dirname, resolve } from "path";
@@ -1136,7 +1138,21 @@ app.post("/chat", async (req, res) => {
     const requestId = Math.random().toString(36).substring(7);
     const { message, sessionId, systemPrompt, verbose = false, subdir, selectedDashboard, 
     // Configurable agent options
-    maxTurns = 40, allowedTools, disallowedTools, model, maxBudgetUsd } = req.body;
+    maxTurns = 40, allowedTools, disallowedTools, model, maxBudgetUsd, 
+    // Reasoning effort (low | medium | high | xhigh | max | <number>). The
+    // SDK defaults to "high" on Opus 4.6+; "medium" is Anthropic's recommended
+    // balance of speed/cost/performance for most agentic workflows. Callers can
+    // override per request when a heavier or lighter pass is warranted.
+    effort = "medium", 
+    // Shared-view chat fields (Phase 2a/2b). When mode === "shared-view" the agent
+    // gets a locked-down tool set (handle-based file tools + scoped integration
+    // calls only; no Bash/Web/SDK file tools) regardless of the caller's
+    // `allowedTools` value. The dashboard folder is identified via the existing
+    // `subdir` field (relative to PROJECT_DIR); Papercrane doesn't need to know
+    // the sandbox's absolute filesystem layout. `queryFiles` is an optional list
+    // of additional relative paths to include in the file index. The remaining
+    // fields configure the papercrane-data MCP server (Phase 2b).
+    mode, queryFiles, shareId, shareCode, visitorSessionId } = req.body;
     const ctx = { requestId, sessionId };
     log.info(ctx, "Agent received chat request");
     if (!message) {
@@ -1185,7 +1201,7 @@ app.post("/chat", async (req, res) => {
             parent_tool_use_id: null
         };
     }
-    // Default tools if not specified
+    // Default tools if not specified (authoring mode)
     const defaultTools = [
         "Read",
         "Write",
@@ -1199,18 +1215,111 @@ app.post("/chat", async (req, res) => {
         "mcp__client-tools__ShowPreview",
         "mcp__client-tools__GetContext"
     ];
+    // Locked-down tool set for shared-view chat. Server-enforced regardless of
+    // any `allowedTools` passed in the request body — defense-in-depth so a
+    // miswiring on the Papercrane side can't widen the agent's surface.
+    const sharedViewAllowedTools = [
+        "mcp__dashboard-fs__ListFiles",
+        "mcp__dashboard-fs__ReadFile",
+        "mcp__dashboard-fs__GrepFiles",
+        "mcp__papercrane-data__List",
+        "mcp__papercrane-data__Describe",
+        "mcp__papercrane-data__Call",
+        "mcp__client-tools__GetContext"
+    ];
+    const isSharedView = mode === "shared-view";
     // Store UI context for GetContext tool
     sessionContext[requestId] = { selectedDashboard: selectedDashboard || null };
     const clientTools = createClientToolsServer(requestId);
+    // Build the dashboard-fs MCP server for shared-view chat. The file index is
+    // walked once at session start from `cwd` (PROJECT_DIR + subdir); the agent
+    // addresses files only by handle.
+    let dashboardFs = null;
+    let papercraneData = null;
+    if (isSharedView) {
+        if (!subdir || typeof subdir !== "string") {
+            res.status(400).json({ error: "subdir (the dashboard folder name) is required when mode is 'shared-view'" });
+            return;
+        }
+        if (typeof shareId !== "number") {
+            res.status(400).json({ error: "shareId is required when mode is 'shared-view'" });
+            return;
+        }
+        if (!shareCode || typeof shareCode !== "string") {
+            res.status(400).json({ error: "shareCode is required when mode is 'shared-view'" });
+            return;
+        }
+        if (!visitorSessionId || typeof visitorSessionId !== "string") {
+            res.status(400).json({ error: "visitorSessionId is required when mode is 'shared-view'" });
+            return;
+        }
+        // Read Papercrane credentials from the same config file the CLI uses
+        // (~/.papercrane/config.json). Single source of truth.
+        let papercraneApiUrl;
+        let papercraneApiKey;
+        try {
+            const configPath = join(homedir(), ".papercrane", "config.json");
+            const raw = await readFile(configPath, "utf-8");
+            const cfg = JSON.parse(raw);
+            console.log(`[shared-view] full config:`, cfg);
+            if (!cfg.apiKey)
+                throw new Error("apiKey missing from ~/.papercrane/config.json");
+            if (!cfg.apiBaseUrl)
+                throw new Error("apiBaseUrl missing from ~/.papercrane/config.json");
+            papercraneApiKey = cfg.apiKey;
+            papercraneApiUrl = cfg.apiBaseUrl;
+        }
+        catch (err) {
+            log.error({ ...ctx, err: err instanceof Error ? err.message : String(err) }, "Failed to load Papercrane credentials");
+            res.status(500).json({ error: "Sandbox is missing Papercrane credentials. Run `papercrane login` to set up the API key." });
+            return;
+        }
+        try {
+            // Resolve queryFiles to absolute paths if relative (callers pass relative paths)
+            const resolvedQueryFiles = Array.isArray(queryFiles)
+                ? queryFiles.map((qf) => qf.startsWith("/") ? qf : join(PROJECT_DIR, qf))
+                : undefined;
+            dashboardFs = await createDashboardFsServer({
+                dashboardRoot: cwd,
+                queryFiles: resolvedQueryFiles
+            });
+        }
+        catch (err) {
+            log.error({ ...ctx, err: err instanceof Error ? err.message : String(err) }, "Failed to build dashboard-fs index");
+            res.status(400).json({ error: `Failed to build dashboard-fs index: ${err instanceof Error ? err.message : String(err)}` });
+            return;
+        }
+        papercraneData = createPapercraneDataServer({
+            apiBaseUrl: papercraneApiUrl,
+            apiKey: papercraneApiKey,
+            shareCode,
+            visitorSessionId
+        });
+        log.info({
+            ...ctx,
+            shareId,
+            shareCode,
+            visitorSessionId,
+            cwd,
+            papercraneApiUrl
+        }, "Shared-view chat session initialized");
+    }
+    const mcpServers = {
+        "client-tools": clientTools
+    };
+    if (dashboardFs) {
+        mcpServers["dashboard-fs"] = dashboardFs.server;
+    }
+    if (papercraneData) {
+        mcpServers["papercrane-data"] = papercraneData.server;
+    }
     const options = {
         maxTurns,
         cwd,
         permissionMode: "bypassPermissions",
         allowDangerouslySkipPermissions: true,
-        mcpServers: {
-            "client-tools": clientTools
-        },
-        allowedTools: allowedTools || defaultTools,
+        mcpServers,
+        allowedTools: isSharedView ? sharedViewAllowedTools : (allowedTools || defaultTools),
         settingSources: ["project"],
         hooks,
         abortController,
@@ -1234,6 +1343,9 @@ app.post("/chat", async (req, res) => {
     if (maxBudgetUsd) {
         options.maxBudgetUsd = maxBudgetUsd;
     }
+    if (effort !== undefined) {
+        options.effort = effort;
+    }
     try {
         let gotResult = false;
         log.debug({ ...ctx, elapsed: Date.now() - requestStartTime }, "Starting Claude SDK query");
@@ -1310,9 +1422,15 @@ app.post("/chat", async (req, res) => {
         }
     }
     finally {
-        // Clean up per-request context and close MCP server
+        // Clean up per-request context and close MCP servers
         delete sessionContext[requestId];
         await clientTools.instance?.close().catch(() => { });
+        if (dashboardFs) {
+            await dashboardFs.server.instance?.close().catch(() => { });
+        }
+        if (papercraneData) {
+            await papercraneData.server.instance?.close().catch(() => { });
+        }
     }
 });
 // =============================================================================

package/dist/papercrane-data/index.d.ts

@@ -0,0 +1,23 @@
+interface CreateOptions {
+    /** Base URL of the Papercrane API, e.g. "https://app.papercrane.ai". No trailing slash. */
+    apiBaseUrl: string;
+    /** Environment API key (Bearer token). Same key the rest of the agent uses. */
+    apiKey: string;
+    /** Share code from the chat session. Papercrane uses it to scope every call. */
+    shareCode: string;
+    /** Visitor session identifier (cookie-derived). Stamped on outbound calls for usage attribution. */
+    visitorSessionId: string;
+}
+/**
+ * Builds the papercrane-data MCP server for a shared-view chat session.
+ *
+ * Each tool is a thin HTTP wrapper around the share-scoped integrations
+ * endpoint at `/api/share/:shareCode/integrations/*`. Papercrane resolves the
+ * share's allowlist on every call (single source of truth, no staleness) and
+ * filters/gates the response server-side. The MCP server does no filtering of
+ * its own.
+ */
+export declare function createPapercraneDataServer(options: CreateOptions): {
+    server: import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;
+};
+export {};