@axiom-lattice/core 2.1.72 → 2.1.74

package/dist/index.js

@@ -79,6 +79,7 @@ __export(index_exports, {
   MicrosandboxRemoteProvider: () => MicrosandboxRemoteProvider,
   MicrosandboxServiceClient: () => MicrosandboxServiceClient,
   ModelLatticeManager: () => ModelLatticeManager,
+  MysqlDatabase: () => MysqlDatabase,
   PinoLoggerClient: () => PinoLoggerClient,
   PostgresDatabase: () => PostgresDatabase,
   PrometheusClient: () => PrometheusClient,
@@ -143,6 +144,7 @@ __export(index_exports, {
   ensureBuiltinAgentsForTenant: () => ensureBuiltinAgentsForTenant,
   eventBus: () => eventBus,
   eventBusDefault: () => event_bus_default,
+  extractFetcherError: () => extractFetcherError,
   fileDataToString: () => fileDataToString,
   formatContentWithLineNumbers: () => formatContentWithLineNumbers,
   formatGrepMatches: () => formatGrepMatches,
@@ -3284,6 +3286,168 @@ var PostgresDatabase = class {
     }
   }
 };
+var MysqlDatabase = class {
+  constructor(config) {
+    // mysql2.Pool
+    this.connected = false;
+    this.config = config;
+  }
+  async connect() {
+    if (this.connected && this.pool) return;
+    try {
+      const mysql = await import("mysql2/promise");
+      const poolConfig = this.config.connectionString ? { uri: this.config.connectionString } : {
+        host: this.config.host || "localhost",
+        port: this.config.port || 3306,
+        database: this.config.database,
+        user: this.config.user,
+        password: this.config.password,
+        ssl: this.config.ssl ? { rejectUnauthorized: false } : void 0
+      };
+      this.pool = mysql.createPool({
+        ...poolConfig,
+        waitForConnections: true,
+        connectionLimit: 10,
+        maxIdle: 10,
+        idleTimeout: 6e4,
+        queueLimit: 0,
+        enableKeepAlive: true,
+        keepAliveInitialDelay: 0
+      });
+      const connection = await this.pool.getConnection();
+      try {
+        await connection.query("SELECT 1");
+      } finally {
+        connection.release();
+      }
+      this.connected = true;
+    } catch (error) {
+      this.connected = false;
+      throw new Error(`Failed to connect to MySQL: ${error}`);
+    }
+  }
+  async disconnect() {
+    if (this.pool) {
+      try {
+        await this.pool.end();
+      } catch (error) {
+        console.warn("Warning: Error closing MySQL pool:", error);
+      } finally {
+        this.pool = null;
+        this.connected = false;
+      }
+    }
+  }
+  async listTables() {
+    await this.ensureConnected();
+    const query = `
+      SELECT TABLE_NAME, TABLE_SCHEMA
+      FROM information_schema.TABLES
+      WHERE TABLE_SCHEMA NOT IN ('mysql', 'information_schema', 'performance_schema', 'sys')
+        AND TABLE_SCHEMA = DATABASE()
+        AND TABLE_TYPE = 'BASE TABLE'
+      ORDER BY TABLE_SCHEMA, TABLE_NAME
+    `;
+    const [rows] = await this.pool.query(query);
+    return rows.map((row) => ({
+      name: row.TABLE_NAME,
+      schema: row.TABLE_SCHEMA
+    }));
+  }
+  async getTableInfo(tables) {
+    await this.ensureConnected();
+    const schemas = [];
+    for (const tableName of tables) {
+      const rawName = tableName.includes(".") ? tableName.split(".").pop() : tableName;
+      const columnQuery = `
+        SELECT
+          c.COLUMN_NAME,
+          c.DATA_TYPE,
+          c.IS_NULLABLE,
+          c.COLUMN_DEFAULT
+        FROM information_schema.COLUMNS c
+        WHERE c.TABLE_NAME = ?
+          AND c.TABLE_SCHEMA = DATABASE()
+        ORDER BY c.ORDINAL_POSITION
+      `;
+      const pkQuery = `
+        SELECT k.COLUMN_NAME
+        FROM information_schema.TABLE_CONSTRAINTS t
+        JOIN information_schema.KEY_COLUMN_USAGE k
+          ON t.CONSTRAINT_NAME = k.CONSTRAINT_NAME
+          AND t.TABLE_SCHEMA = k.TABLE_SCHEMA
+          AND t.TABLE_NAME = k.TABLE_NAME
+        WHERE t.CONSTRAINT_TYPE = 'PRIMARY KEY'
+          AND t.TABLE_NAME = ?
+          AND t.TABLE_SCHEMA = DATABASE()
+      `;
+      const fkQuery = `
+        SELECT
+          k.COLUMN_NAME,
+          k.REFERENCED_TABLE_NAME,
+          k.REFERENCED_COLUMN_NAME
+        FROM information_schema.KEY_COLUMN_USAGE k
+        WHERE k.TABLE_NAME = ?
+          AND k.TABLE_SCHEMA = DATABASE()
+          AND k.REFERENCED_TABLE_NAME IS NOT NULL
+      `;
+      const [columnRows] = await this.pool.query(columnQuery, [rawName]);
+      const [pkRows] = await this.pool.query(pkQuery, [rawName]);
+      const [fkRows] = await this.pool.query(fkQuery, [rawName]);
+      const pkColumns = new Set(pkRows.map((r) => r.COLUMN_NAME));
+      const fkMap = /* @__PURE__ */ new Map();
+      for (const row of fkRows) {
+        fkMap.set(row.COLUMN_NAME, {
+          foreignTable: row.REFERENCED_TABLE_NAME,
+          foreignColumn: row.REFERENCED_COLUMN_NAME
+        });
+      }
+      const columns = columnRows.map((row) => {
+        const fkRef = fkMap.get(row.COLUMN_NAME);
+        return {
+          name: row.COLUMN_NAME,
+          type: row.DATA_TYPE,
+          nullable: row.IS_NULLABLE === "YES",
+          default: row.COLUMN_DEFAULT,
+          isPrimaryKey: pkColumns.has(row.COLUMN_NAME),
+          isForeignKey: fkRef !== void 0,
+          foreignKeyRef: fkRef ? `${fkRef.foreignTable}.${fkRef.foreignColumn}` : void 0
+        };
+      });
+      let sampleRows = [];
+      try {
+        const sampleQuery = `SELECT * FROM \`${rawName}\` LIMIT 3`;
+        const [sampleResult] = await this.pool.query(sampleQuery);
+        sampleRows = sampleResult;
+      } catch {
+      }
+      schemas.push({
+        tableName,
+        columns,
+        sampleRows
+      });
+    }
+    return schemas;
+  }
+  async executeQuery(query) {
+    await this.ensureConnected();
+    const [rows, fields] = await this.pool.query(query);
+    const isSelectResult = Array.isArray(rows);
+    return {
+      rows: isSelectResult ? rows : [],
+      rowCount: isSelectResult ? rows.length : rows.affectedRows || 0,
+      fields: fields?.map((f) => f.name)
+    };
+  }
+  getDatabaseType() {
+    return "mysql";
+  }
+  async ensureConnected() {
+    if (!this.connected) {
+      await this.connect();
+    }
+  }
+};
 var SqlDatabaseManager = class _SqlDatabaseManager {
   constructor() {
     this.databases = /* @__PURE__ */ new Map();
@@ -3323,7 +3487,8 @@ var SqlDatabaseManager = class _SqlDatabaseManager {
         database = new PostgresDatabase(config);
         break;
       case "mysql":
-        throw new Error("MySQL support not yet implemented");
+        database = new MysqlDatabase(config);
+        break;
       case "sqlite":
         throw new Error("SQLite support not yet implemented");
       default:
@@ -5858,7 +6023,7 @@ var SandboxLatticeManager = class _SandboxLatticeManager extends BaseLatticeMana
     const tenantId = config.tenantId ?? "default";
     const mapping = this._resolveVolumeForPath(config, tenantId, filePath);
     if (!mapping) return null;
-    const client = provider.createVolumeFsClient(mapping.volumeName);
+    const client = provider.createVolumeFsClient(mapping.volumeName, mapping.pathPrefix);
     return new VolumeFilesystem(stripPrefixClient(client, mapping.pathPrefix), mapping.pathPrefix);
   }
   _resolveVolumeForPath(config, tenantId, filePath) {
@@ -19070,10 +19235,105 @@ Use this when the task follows a standard BPO (Business Process Orchestration) p
 
 **Business rule \u2014 Draft-then-confirm pattern:** When a workflow creates business objects that require human approval (e.g., draft orders in SAP B1, purchase requisitions, expense reports), the design MUST include a confirmation step AFTER the creation step. The create step must complete successfully before the confirm step runs. The flow is always: **Create draft \u2192 User confirms \u2192 Finalize**. Reason: systems like SAP B1 only expose drafts to users after they are created \u2014 the user cannot see or approve something that doesn't exist yet. The confirm step MUST use the \`ask_user_to_clarify\` middleware.
 
+**Business pattern \u2014 SAP B1 Draft SO Creation:** When designing a sub-agent responsible for creating draft Sales Orders in SAP B1, embed the following standards into its system prompt. These ensure consistent data construction, API usage, and user presentation:
+
+**Step 1: Construct SO Data Structure**
+Build the JSON payload. For each DocumentLines item:
+- Include \`WarehouseCode\` ONLY if sku.json provides a value; if missing or empty, OMIT the field entirely
+- Generate \`Comments\` dynamically based on context (customer name, PO reference, special instructions)
+
+\`\`\`json
+{
+  "DocObjectCode": "17",
+  "DocType": "dDocument_Items",
+  "CardCode": "C001",
+  "DocDate": "current date",
+  "DocDueDate": "delivery date",
+  "TaxDate": "current date",
+  "U_YWLX": "Modern Trade",
+  "Comments": "SO for Kaimay Retail - PO ref: PO-2024-001234",
+  "DocumentLines": [
+    {
+      "ItemCode": "SKU001",
+      "Quantity": 240,
+      "UnitPrice": 15.84
+    }
+  ]
+}
+\`\`\`
+
+Field mapping rules:
+| SAP Field | Data Source |
+|-----------|-------------|
+| CardCode | customer.json \u2192 CardCode |
+| DocDate | Current date (yyyy-MM-dd) |
+| DocDueDate | extracted.json \u2192 delivery_date |
+| TaxDate | Current date (yyyy-MM-dd) |
+| U_YWLX | customer.json \u2192 SalesType |
+| ItemCode | sku.json \u2192 ItemCode |
+| Quantity | extracted.json \u2192 Quantity |
+| WarehouseCode | sku.json \u2192 WarehouseCode (OMIT if missing/empty) |
+| UnitPrice | price.json \u2192 UnitPrice |
+| Comments | AI-generated based on customer name, PO reference, and context |
+
+**Step 2: Call SAP API to Create Draft (MUST EXECUTE)**
+Use the \`sap_api_call\` tool with EXACTLY these parameters:
+- **Method**: POST
+- **Endpoint**: \`Drafts\` (ONLY allowed endpoint; do NOT call SalesOrders or any other endpoint)
+- **Body**: The JSON constructed in Step 1
+
+CRITICAL: You MUST call sap_api_call BEFORE proceeding to Step 3. This step is NOT optional.
+
+If the API call fails:
+- Log the error details
+- STOP the process
+- Report the failure to the user with the error message
+- Do NOT proceed to Step 3
+
+**Step 3: Present Draft for User Review (MUST EXECUTE AFTER Step 2)**
+ONLY after the SAP API call in Step 2 succeeds, use the \`ask_user_to_clarify\` tool to present the complete SO summary.
+
+Message format (STRICT \u2014 no emoji, no summary, field names match Service Layer):
+
+=== Sales Order Draft ===
+
+DocEntry: {DocEntry}
+DocNum: {DocNum}
+DocDate: {DocDate}
+DocDueDate: {DocDueDate}
+CardCode: {CardCode}
+CardName: {CardName}
+U_YWLX: {SalesType}
+Comments: {Comments}
+
+DocumentLines:
+LineNum | ItemCode | Quantity | WarehouseCode | UnitPrice | LineTotal
+0       | {ItemCode} | {Quantity} | {WarehouseCode} | {UnitPrice} | {LineTotal}
+1       | {ItemCode} | {Quantity} | {WarehouseCode} | {UnitPrice} | {LineTotal}
+...
+
+DocTotal: {DocTotal}
+
+Warnings:
+- {warning1}
+- {warning2}
+
+Options:
+[Confirm generating draft]
+[Cancel, do not generate]
+
+**Data sharing pattern \u2014 File-based handoff:** Every sub-agent in the pipeline MUST persist its work results as files under a shared project directory, never rely on in-memory data passing between steps. Deep agents have built-in file capabilities, so no middleware is needed.
+
+Rules:
+1. The **orchestrator** generates a unique project ID at the start (e.g., timestamp-based) and passes it to each sub-agent in the task context
+2. Each sub-agent reads input from \`/project/{project-id}/\` and writes output files into the same directory
+3. Establish clear file naming conventions so downstream steps know exactly which files to read (e.g., \`extracted.json\`, \`sku.json\`, \`customer.json\`, \`so_draft.json\`)
+4. The orchestrator's system prompt MUST specify for each edge: which files the target sub-agent should read and which files it should produce
+
 **Step 2: Topology design.** Design the agent topology and use \`show_widget\` to render an interactive diagram showing the flow: Orchestrator \u2192 Stage 1 \u2192 Stage 2 \u2192 ... \u2192 Output. Each edge should be labeled with its business purpose.
 
 **Step 3: Design each sub-agent** as a **deep_agent** type (one at a time). For each:
-- Responsibility, system prompt, middleware, input/output contract
+- Responsibility, system prompt, middleware, file input/output contract (which files from \`/project/{project-id}/\` it reads, which files it writes)
 - Deep agents have built-in file capabilities (ls, read, write, edit, glob, grep), so do NOT add filesystem middleware.
 - **Ask for confirmation before moving to the next sub-agent.**
 
@@ -19092,15 +19352,15 @@ Use this when the task follows a standard BPO (Business Process Orchestration) p
  | Section | Content |
  |---------|---------|
  | **Overview** | One-sentence summary of the workflow's purpose and business value |
- | **Steps** | Numbered list of each stage in the pipeline. For each step: which sub-agent handles it, what it does, what tools it uses, and what it produces (output) |
- | **Data Flow** | How data moves between steps. What does each step receive as input? What does it produce and pass to the next step? |
+ | **Steps** | Numbered list of each stage in the pipeline. For each step: which sub-agent handles it, what it does, what tools it uses, what files it reads from \`/project/{project-id}/\`, and what files it writes. |
+ | **Data Flow** | How data moves between steps via files under \`/project/{project-id}/\`. For each step: which files it reads as input and which files it writes as output. |
  | **Logic & Conditions** | Any conditional branching, decision points, retry logic, or exception handling. When does the workflow take path A vs path B? What happens on failure? |
  | **Tools Used** | Summary table or list of all tools used across sub-agents, grouped by sub-agent |
  | **Expected Input** | What input does the workflow expect from the user? (format, examples) |
  | **Expected Output** | What does the workflow produce at the end? (format, examples) |
 
  **Formatting rules:**
- - Write in **Chinese** if the user communicates in Chinese; otherwise English
+  - Write in **English**
  - Use **Markdown** for formatting (headings, lists, tables, code blocks)
  - Be detailed but concise \u2014 each section should be 1-5 lines
  - Avoid placeholder text like "TODO" or "TBD"
@@ -19112,13 +19372,14 @@ Use this when the task follows a standard BPO (Business Process Orchestration) p
  \u672C\u5DE5\u4F5C\u6D41\u81EA\u52A8\u4ECE\u591A\u4E2A\u6570\u636E\u6E90\u91C7\u96C6\u7ADE\u54C1\u4EF7\u683C\uFF0C\u751F\u6210\u5BF9\u6BD4\u5206\u6790\u62A5\u544A\u5E76\u63A8\u9001\u901A\u77E5\u3002
 
  ## Steps
- 1. **\u6570\u636E\u91C7\u96C6 (data-collector)** \u2014 \u4F7F\u7528 browser \u5DE5\u5177\u722C\u53D6\u6307\u5B9AURL\u7684\u7ADE\u54C1\u4EF7\u683C\u6570\u636E\uFF0C\u8C03\u7528 metrics API \u62C9\u53D6\u5386\u53F2\u4EF7\u683C\u3002\u8F93\u51FA\u539F\u59CB\u4EF7\u683C\u6570\u636E\u96C6 JSON\u3002
- 2. **\u6570\u636E\u6E05\u6D17 (data-cleaner)** \u2014 \u4F7F\u7528 code_eval \u6267\u884C Python \u811A\u672C\u6E05\u6D17\u5F02\u5E38\u503C\u548C\u7F3A\u5931\u503C\uFF0C\u7EDF\u4E00\u8D27\u5E01\u5355\u4F4D\u3002\u8F93\u51FA\u6807\u51C6\u5316\u6570\u636E\u96C6\u3002
-  3. **\u62A5\u544A\u751F\u6210 (report-generator)** \u2014 \u8BFB\u53D6\u6A21\u677F\u6587\u4EF6\uFF0Ccode_eval \u8BA1\u7B97\u6DA8\u8DCC\u5E45\u548C\u8D8B\u52BF\uFF0C\u751F\u6210 Markdown \u5BF9\u6BD4\u62A5\u544A\u3002\u8F93\u51FA\u62A5\u544A\u6587\u4EF6\u8DEF\u5F84\u3002
- 4. **\u901A\u77E5\u63A8\u9001 (notifier)** \u2014 \u8C03\u7528 scheduler \u5B89\u6392\u5B9A\u65F6\u53D1\u9001\uFF0C\u4F7F\u7528 ask_user_to_clarify \u8BF7\u6C42\u53D1\u9001\u786E\u8BA4\u3002\u8F93\u51FA\u53D1\u9001\u7ED3\u679C\u3002
+  1. **\u6570\u636E\u91C7\u96C6 (data-collector)** \u2014 \u4F7F\u7528 browser \u5DE5\u5177\u722C\u53D6\u6307\u5B9AURL\u7684\u7ADE\u54C1\u4EF7\u683C\u6570\u636E\uFF0C\u8C03\u7528 metrics API \u62C9\u53D6\u5386\u53F2\u4EF7\u683C\u3002\u8F93\u51FA \u2192 \`raw_prices.json\`
+  2. **\u6570\u636E\u6E05\u6D17 (data-cleaner)** \u2014 \u8BFB\u53D6 \`raw_prices.json\`\uFF0C\u4F7F\u7528 code_eval \u6267\u884C Python \u811A\u672C\u6E05\u6D17\u5F02\u5E38\u503C\u548C\u7F3A\u5931\u503C\uFF0C\u7EDF\u4E00\u8D27\u5E01\u5355\u4F4D\u3002\u8F93\u51FA \u2192 \`cleaned_prices.json\`
+   3. **\u62A5\u544A\u751F\u6210 (report-generator)** \u2014 \u8BFB\u53D6 \`cleaned_prices.json\` \u548C\u6A21\u677F\u6587\u4EF6\uFF0Ccode_eval \u8BA1\u7B97\u6DA8\u8DCC\u5E45\u548C\u8D8B\u52BF\uFF0C\u751F\u6210 Markdown \u5BF9\u6BD4\u62A5\u544A\u3002\u8F93\u51FA \u2192 \`report.md\`
+  4. **\u901A\u77E5\u63A8\u9001 (notifier)** \u2014 \u8BFB\u53D6 \`report.md\`\uFF0C\u8C03\u7528 scheduler \u5B89\u6392\u5B9A\u65F6\u53D1\u9001\uFF0C\u4F7F\u7528 ask_user_to_clarify \u8BF7\u6C42\u53D1\u9001\u786E\u8BA4\u3002\u8F93\u51FA\u53D1\u9001\u7ED3\u679C\u3002
 
  ## Data Flow
- \`\u7528\u6237\u8F93\u5165(URL\u5217\u8868 + \u65E5\u671F\u8303\u56F4)\` \u2192 data-collector \u722C\u53D6+\u67E5\u8BE2 \u2192 \u539F\u59CBJSON \u2192 data-cleaner \u6E05\u6D17\u8F6C\u6362 \u2192 \u6807\u51C6\u5316JSON \u2192 report-generator \u5206\u6790\u751F\u6210 \u2192 \u62A5\u544AMarkdown \u2192 notifier \u63A8\u9001
+ All data is shared via files under \`/project/{project-id}/\`:
+ \`\u7528\u6237\u8F93\u5165\` \u2192 data-collector writes \`raw_prices.json\` \u2192 data-cleaner reads \`raw_prices.json\`, writes \`cleaned_prices.json\` \u2192 report-generator reads \`cleaned_prices.json\`, writes \`report.md\` \u2192 notifier reads \`report.md\`, pushes
 
  ## Logic & Conditions
  - data-collector \u722C\u53D6\u5931\u8D25\u65F6\u91CD\u8BD5\u6700\u591A3\u6B21\uFF0C\u95F4\u969430\u79D2
@@ -19279,7 +19540,7 @@ Creates a PROCESSING agent with a business-defined workflow topology. Sub-agents
 \`\`\`typescript
 {
   name: string,              // Required. Display name for the orchestrator
-  description?: string,      // Required for good UX. Comprehensive workflow spec in Markdown (Chinese if user speaks Chinese). Must cover: Overview, Steps (with tools per step), Data Flow, Logic & Conditions, Tools Used, Expected Input, Expected Output. This is the single source of truth displayed in the automation view info popover.
+  description?: string,      // Required for good UX. Comprehensive workflow spec in Markdown (English). Must cover: Overview, Steps (with tools per step), Data Flow, Logic & Conditions, Tools Used, Expected Input, Expected Output. This is the single source of truth displayed in the automation view info popover.
   prompt: string,            // Required. System prompt \u2014 how to route through the topology
   edges: [{                  // Required. At least 1 edge defining the serial workflow chain
     from: string,            // Source agent ID. First edge: use orchestrator name as placeholder (tool auto-replaces). Subsequent edges: previous sub-agent ID
@@ -21375,7 +21636,7 @@ var MicrosandboxRemoteProvider = class {
     this.instances.delete(name);
     await this.client.deleteSandbox(name);
   }
-  createVolumeFsClient(volumeName) {
+  createVolumeFsClient(volumeName, _pathPrefix) {
     return {
       read: (path3) => this.client.volumeFsRead(volumeName, path3),
       write: (path3, content) => this.client.volumeFsWrite(volumeName, path3, content),
@@ -21432,50 +21693,84 @@ var MicrosandboxRemoteProvider = class {
 var import_sandbox23 = require("@agent-infra/sandbox");
 
 // src/sandbox_lattice/RemoteSandboxInstance.ts
+function extractFetcherError(error) {
+  if (typeof error === "string") {
+    return error;
+  }
+  if (error && typeof error === "object") {
+    const e = error;
+    if (typeof e.reason === "string") {
+      switch (e.reason) {
+        case "status-code":
+          return `HTTP ${e.statusCode}: ${JSON.stringify(e.body)}`;
+        case "non-json":
+          return `HTTP ${e.statusCode}: ${e.rawBody}`;
+        case "timeout":
+          return "Request timed out";
+        case "unknown":
+          return typeof e.errorMessage === "string" ? e.errorMessage : "Unknown error";
+      }
+    }
+    if (typeof e.message === "string") {
+      return e.message;
+    }
+    if (typeof e.error === "string") {
+      return e.error;
+    }
+    return JSON.stringify(error);
+  }
+  return String(error);
+}
 var RemoteSandboxInstance = class {
-  constructor(name, client) {
+  constructor(name, client, workspace) {
     this.client = client;
+    this.workspace = workspace;
     this.file = {
       readFile: async (file) => {
-        const result = await this.client.file.readFile({ file });
+        const resolved = this.resolvePath(file);
+        const result = await this.client.file.readFile({ file: resolved });
         if (!result.ok) {
-          throw new Error(String(result.error));
+          throw new Error(`readFile failed: ${extractFetcherError(result.error)}`);
         }
         return { content: result.body.data?.content ?? "" };
       },
       writeFile: async (file, content) => {
-        const result = await this.client.file.writeFile({ file, content });
+        const resolved = this.resolvePath(file);
+        const result = await this.client.file.writeFile({ file: resolved, content });
         if (!result.ok) {
-          throw new Error(String(result.error));
+          throw new Error(`writeFile failed: ${extractFetcherError(result.error)}`);
         }
       },
       listPath: async (path3, options) => {
+        const resolved = this.resolvePath(path3);
         const result = await this.client.file.listPath({
-          path: path3,
+          path: resolved,
           recursive: options?.recursive ?? false
         });
         if (!result.ok) {
-          throw new Error(String(result.error));
+          throw new Error(`listPath failed: ${extractFetcherError(result.error)}`);
         }
         const files = (result.body.data?.files || []).map((f) => ({
           path: f.path,
-          is_dir: f.is_dir ?? false,
-          size: f.size,
+          is_dir: f.is_dir === true || f.size === null,
+          size: f.size ?? void 0,
           modified_at: f.modified_at
         }));
         return { files };
       },
       findFiles: async (path3, glob) => {
-        const result = await this.client.file.findFiles({ path: path3, glob });
+        const resolved = this.resolvePath(path3);
+        const result = await this.client.file.findFiles({ path: resolved, glob });
         if (!result.ok) {
-          throw new Error(String(result.error));
+          throw new Error(`findFiles failed: ${extractFetcherError(result.error)}`);
         }
         return { files: result.body.data?.files || [] };
       },
       searchInFile: async (file, regex) => {
-        const result = await this.client.file.searchInFile({ file, regex });
+        const resolved = this.resolvePath(file);
+        const result = await this.client.file.searchInFile({ file: resolved, regex });
         if (!result.ok) {
-          throw new Error(String(result.error));
+          throw new Error(`searchInFile failed: ${extractFetcherError(result.error)}`);
         }
         return {
           matches: result.body.data?.matches || [],
@@ -21483,30 +21778,33 @@ var RemoteSandboxInstance = class {
         };
       },
       strReplaceEditor: async (params) => {
+        const resolved = this.resolvePath(params.path);
         const result = await this.client.file.strReplaceEditor({
           command: params.command,
-          path: params.path,
+          path: resolved,
           old_str: params.old_str,
           new_str: params.new_str,
           replace_mode: params.replace_mode
         });
         if (!result.ok) {
-          throw new Error(String(result.error));
+          throw new Error(`strReplaceEditor failed: ${extractFetcherError(result.error)}`);
         }
       },
       uploadFile: async (params) => {
+        const resolved = this.resolvePath(params.file);
         const result = await this.client.file.uploadFile({
           file: params.data,
-          path: params.file
+          path: resolved
         });
         if (!result.ok) {
-          throw new Error(String(result.error));
+          throw new Error(`uploadFile failed: ${extractFetcherError(result.error)}`);
         }
       },
       downloadFile: async (params) => {
-        const result = await this.client.file.downloadFile({ path: params.file });
+        const resolved = this.resolvePath(params.file);
+        const result = await this.client.file.downloadFile({ path: resolved });
         if (!result.ok) {
-          throw new Error(String(result.error));
+          throw new Error(`downloadFile failed: ${extractFetcherError(result.error)}`);
         }
         const buffer2 = await result.body.arrayBuffer();
         return Buffer.from(buffer2);
@@ -21516,11 +21814,11 @@ var RemoteSandboxInstance = class {
       execCommand: async (params) => {
         const result = await this.client.shell.execCommand({
           command: params.command,
-          exec_dir: params.exec_dir,
+          exec_dir: params.exec_dir ? this.resolvePath(params.exec_dir) : void 0,
           timeout: params.timeout
         });
         if (!result.ok) {
-          throw new Error(String(result.error));
+          throw new Error(`execCommand failed: ${extractFetcherError(result.error)}`);
         }
         return {
           output: result.body.data?.output ?? "",
@@ -21530,6 +21828,15 @@ var RemoteSandboxInstance = class {
     };
     this.name = name;
   }
+  resolvePath(file) {
+    if (file.startsWith(this.workspace)) {
+      return file;
+    }
+    if (!file.startsWith("/")) {
+      return `${this.workspace}/${file}`;
+    }
+    return `${this.workspace}${file}`;
+  }
   async start() {
   }
   async stop() {
@@ -21550,23 +21857,58 @@ var RemoteSandboxInstance = class {
 };
 
 // src/sandbox_lattice/providers/RemoteSandboxProvider.ts
+var DEFAULT_WORKSPACE = "/home/gem";
 var RemoteSandboxProvider = class {
   constructor(config) {
     this.config = config;
     this.instances = /* @__PURE__ */ new Map();
+    this.creating = /* @__PURE__ */ new Map();
+    this.workspace = DEFAULT_WORKSPACE;
+    this.workspaceResolved = false;
     this.client = new import_sandbox23.SandboxClient({
       baseUrl: config.baseURL,
       environment: ""
     });
   }
+  async resolveWorkspace() {
+    if (this.workspaceResolved) {
+      return this.workspace;
+    }
+    try {
+      const result = await this.client.sandbox.getContext();
+      if (result.ok && result.body.home_dir) {
+        this.workspace = result.body.home_dir;
+      }
+    } catch {
+    }
+    this.workspaceResolved = true;
+    return this.workspace;
+  }
   async createSandbox(name, _config) {
     const existing = this.instances.get(name);
     if (existing) {
       return existing;
     }
-    const instance = new RemoteSandboxInstance(name, this.client);
-    this.instances.set(name, instance);
-    return instance;
+    const inFlight = this.creating.get(name);
+    if (inFlight) {
+      return inFlight;
+    }
+    const creation = (async () => {
+      const workspace = await this.resolveWorkspace();
+      const instance = new RemoteSandboxInstance(name, this.client, workspace);
+      this.instances.set(name, instance);
+      return instance;
+    })();
+    this.creating.set(name, creation);
+    creation.then(
+      () => {
+        this.creating.delete(name);
+      },
+      () => {
+        this.creating.delete(name);
+      }
+    );
+    return creation;
   }
   async getSandbox(name) {
     const instance = this.instances.get(name);
@@ -21576,9 +21918,7 @@ var RemoteSandboxProvider = class {
     return instance;
   }
   async stopSandbox(name) {
-    const instance = this.instances.get(name);
-    if (instance) {
-    }
+    this.instances.delete(name);
   }
   async deleteSandbox(name) {
     this.instances.delete(name);
@@ -21586,6 +21926,82 @@ var RemoteSandboxProvider = class {
   async listSandboxes() {
     return Array.from(this.instances.values());
   }
+  createVolumeFsClient(_volumeName, pathPrefix) {
+    const workspace = this.workspace;
+    const resolve3 = (p) => {
+      if (!p || p === "/") {
+        if (pathPrefix) {
+          return `${workspace}${pathPrefix}`;
+        }
+        return workspace;
+      }
+      if (p.startsWith(workspace)) {
+        return p;
+      }
+      if (p.startsWith("/")) {
+        return `${workspace}${p}`;
+      }
+      if (pathPrefix) {
+        const mountDir = pathPrefix.replace(/^\//, "");
+        return `${workspace}/${mountDir}/${p}`;
+      }
+      return `${workspace}/${p}`;
+    };
+    return {
+      read: async (path3) => {
+        const resolved = resolve3(path3);
+        const result = await this.client.file.readFile({ file: resolved });
+        if (!result.ok) {
+          throw new Error(`Volume read failed: ${extractFetcherError(result.error)}`);
+        }
+        return result.body.data?.content ?? "";
+      },
+      write: async (path3, content) => {
+        const resolved = resolve3(path3);
+        const result = await this.client.file.writeFile({ file: resolved, content });
+        if (!result.ok) {
+          throw new Error(`Volume write failed: ${extractFetcherError(result.error)}`);
+        }
+      },
+      list: async (path3) => {
+        const resolved = resolve3(path3);
+        const result = await this.client.file.listPath({
+          path: resolved,
+          recursive: false
+        });
+        if (!result.ok) {
+          throw new Error(`Volume list failed: ${extractFetcherError(result.error)}`);
+        }
+        const entries = (result.body.data?.files || []).map((f) => ({
+          path: f.path.startsWith(workspace) ? f.path.slice(workspace.length) : f.path,
+          kind: f.is_dir === true || f.size === null ? "directory" : "file",
+          size: f.size ?? 0,
+          mode: 0,
+          modified: f.modified_at ?? null
+        }));
+        return entries;
+      },
+      readRaw: async (path3) => {
+        const resolved = resolve3(path3);
+        const result = await this.client.file.downloadFile({ path: resolved });
+        if (!result.ok) {
+          throw new Error(`Volume download failed: ${extractFetcherError(result.error)}`);
+        }
+        const buffer2 = await result.body.arrayBuffer();
+        return Buffer.from(buffer2);
+      },
+      writeRaw: async (path3, data) => {
+        const resolved = resolve3(path3);
+        const result = await this.client.file.uploadFile({
+          file: data,
+          path: resolved
+        });
+        if (!result.ok) {
+          throw new Error(`Volume upload failed: ${extractFetcherError(result.error)}`);
+        }
+      }
+    };
+  }
 };
 
 // src/sandbox_lattice/providers/E2BProvider.ts
@@ -22227,6 +22643,7 @@ function clearEncryptionKeyCache() {
   MicrosandboxRemoteProvider,
   MicrosandboxServiceClient,
   ModelLatticeManager,
+  MysqlDatabase,
   PinoLoggerClient,
   PostgresDatabase,
   PrometheusClient,
@@ -22291,6 +22708,7 @@ function clearEncryptionKeyCache() {
   ensureBuiltinAgentsForTenant,
   eventBus,
   eventBusDefault,
+  extractFetcherError,
   fileDataToString,
   formatContentWithLineNumbers,
   formatGrepMatches,