@axiom-lattice/core 2.1.51 → 2.1.53

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -14,16 +14,16 @@ export { AgentConfig, AgentType, GraphBuildOptions, MemoryType } from '@axiom-la
14
14
  import * as langchain from 'langchain';
15
15
  import { ReactAgent, AgentMiddleware } from 'langchain';
16
16
  import z, { z as z$1 } from 'zod';
17
+ import { BaseStore, BaseCheckpointSaver } from '@langchain/langgraph-checkpoint';
17
18
  import * as _langchain_core_tools from '@langchain/core/tools';
18
19
  import { StructuredTool } from '@langchain/core/tools';
19
20
  import * as _langchain_langgraph from '@langchain/langgraph';
20
21
  import { CompiledStateGraph, CommandParams } from '@langchain/langgraph';
21
- import { BaseCheckpointSaver, BaseStore } from '@langchain/langgraph-checkpoint';
22
22
  import { ReplaySubject } from 'rxjs';
23
23
  import { Embeddings } from '@langchain/core/embeddings';
24
24
  import { VectorStore } from '@langchain/core/vectorstores';
25
25
  import { Connection, MultiServerMCPClient } from '@langchain/mcp-adapters';
26
- import { Sandbox } from 'microsandbox';
26
+ import { FsEntry, Sandbox } from 'microsandbox';
27
27
  import { SandboxClient } from '@agent-infra/sandbox';
28
28
  import { Sandbox as Sandbox$1 } from 'e2b';
29
29
  import { Sandbox as Sandbox$2 } from '@daytonaio/sdk';
@@ -1265,6 +1265,213 @@ declare const createExecuteSqlQueryTool: ({ serverKeys, serverDescriptions, getT
1265
1265
  datasourceId?: string | undefined;
1266
1266
  }, string, "execute_sql_query">;
1267
1267
 
1268
+ /**
1269
+ * Protocol definition for pluggable memory backends.
1270
+ *
1271
+ * This module defines the BackendProtocol that all backend implementations
1272
+ * must follow. Backends can store files in different locations (state, filesystem,
1273
+ * database, etc.) and provide a uniform interface for file operations.
1274
+ */
1275
+
1276
+ type MaybePromise<T> = T | Promise<T>;
1277
+ /**
1278
+ * Structured file listing info.
1279
+ *
1280
+ * Minimal contract used across backends. Only "path" is required.
1281
+ * Other fields are best-effort and may be absent depending on backend.
1282
+ */
1283
+ interface FileInfo {
1284
+ /** File path */
1285
+ path: string;
1286
+ /** Whether this is a directory */
1287
+ is_dir?: boolean;
1288
+ /** File size in bytes (approximate) */
1289
+ size?: number;
1290
+ /** ISO 8601 timestamp of last modification */
1291
+ modified_at?: string;
1292
+ }
1293
+ /**
1294
+ * Structured grep match entry.
1295
+ */
1296
+ interface GrepMatch {
1297
+ /** File path where match was found */
1298
+ path: string;
1299
+ /** Line number (1-indexed) */
1300
+ line: number;
1301
+ /** The matching line text */
1302
+ text: string;
1303
+ }
1304
+ /**
1305
+ * File data structure used by backends.
1306
+ *
1307
+ * All file data is represented as objects with this structure:
1308
+ */
1309
+ interface FileData {
1310
+ /** Lines of text content */
1311
+ content: string[];
1312
+ /** ISO format timestamp of creation */
1313
+ created_at: string;
1314
+ /** ISO format timestamp of last modification */
1315
+ modified_at: string;
1316
+ }
1317
+ /**
1318
+ * Result from backend write operations.
1319
+ *
1320
+ * Checkpoint backends populate filesUpdate with {file_path: file_data} for LangGraph state.
1321
+ * External backends set filesUpdate to null (already persisted to disk/S3/database/etc).
1322
+ */
1323
+ interface WriteResult {
1324
+ /** Error message on failure, undefined on success */
1325
+ error?: string;
1326
+ /** File path of written file, undefined on failure */
1327
+ path?: string;
1328
+ /**
1329
+ * State update dict for checkpoint backends, null for external storage.
1330
+ * Checkpoint backends populate this with {file_path: file_data} for LangGraph state.
1331
+ * External backends set null (already persisted to disk/S3/database/etc).
1332
+ */
1333
+ filesUpdate?: Record<string, FileData> | null;
1334
+ /** Metadata for the write operation, attached to the ToolMessage */
1335
+ metadata?: Record<string, unknown>;
1336
+ }
1337
+ /**
1338
+ * Result from backend edit operations.
1339
+ *
1340
+ * Checkpoint backends populate filesUpdate with {file_path: file_data} for LangGraph state.
1341
+ * External backends set filesUpdate to null (already persisted to disk/S3/database/etc).
1342
+ */
1343
+ interface EditResult {
1344
+ /** Error message on failure, undefined on success */
1345
+ error?: string;
1346
+ /** File path of edited file, undefined on failure */
1347
+ path?: string;
1348
+ /**
1349
+ * State update dict for checkpoint backends, null for external storage.
1350
+ * Checkpoint backends populate this with {file_path: file_data} for LangGraph state.
1351
+ * External backends set null (already persisted to disk/S3/database/etc).
1352
+ */
1353
+ filesUpdate?: Record<string, FileData> | null;
1354
+ /** Number of replacements made, undefined on failure */
1355
+ occurrences?: number;
1356
+ /** Metadata for the edit operation, attached to the ToolMessage */
1357
+ metadata?: Record<string, unknown>;
1358
+ }
1359
+ /**
1360
+ * Protocol for pluggable memory backends (single, unified).
1361
+ *
1362
+ * Backends can store files in different locations (state, filesystem, database, etc.)
1363
+ * and provide a uniform interface for file operations.
1364
+ *
1365
+ * All file data is represented as objects with the FileData structure.
1366
+ *
1367
+ * Methods can return either direct values or Promises, allowing both
1368
+ * synchronous and asynchronous implementations.
1369
+ */
1370
+ interface BackendProtocol {
1371
+ /**
1372
+ * Structured listing with file metadata.
1373
+ *
1374
+ * Lists files and directories in the specified directory (non-recursive).
1375
+ * Directories have a trailing / in their path and is_dir=true.
1376
+ *
1377
+ * @param path - Absolute path to directory
1378
+ * @returns List of FileInfo objects for files and directories directly in the directory
1379
+ */
1380
+ lsInfo(path: string): MaybePromise<FileInfo[]>;
1381
+ /**
1382
+ * Read file content with line numbers or an error string.
1383
+ *
1384
+ * @param filePath - Absolute file path
1385
+ * @param offset - Line offset to start reading from (0-indexed), default 0
1386
+ * @param limit - Maximum number of lines to read, default 2000
1387
+ * @returns Formatted file content with line numbers, or error message
1388
+ */
1389
+ read(filePath: string, offset?: number, limit?: number): MaybePromise<string>;
1390
+ /**
1391
+ * Read file content as raw FileData.
1392
+ *
1393
+ * @param filePath - Absolute file path
1394
+ * @returns Raw file content as FileData
1395
+ */
1396
+ readRaw(filePath: string): MaybePromise<FileData>;
1397
+ /**
1398
+ * Structured search results or error string for invalid input.
1399
+ *
1400
+ * Searches file contents for a regex pattern.
1401
+ *
1402
+ * @param pattern - Regex pattern to search for
1403
+ * @param path - Base path to search from (default: null)
1404
+ * @param glob - Optional glob pattern to filter files (e.g., "*.py")
1405
+ * @returns List of GrepMatch objects or error string for invalid regex
1406
+ */
1407
+ grepRaw(pattern: string, path?: string | null, glob?: string | null): MaybePromise<GrepMatch[] | string>;
1408
+ /**
1409
+ * Structured glob matching returning FileInfo objects.
1410
+ *
1411
+ * @param pattern - Glob pattern (e.g., `*.py`, `**\/*.ts`)
1412
+ * @param path - Base path to search from (default: "/")
1413
+ * @returns List of FileInfo objects matching the pattern
1414
+ */
1415
+ globInfo(pattern: string, path?: string): MaybePromise<FileInfo[]>;
1416
+ /**
1417
+ * Create a new file.
1418
+ *
1419
+ * @param filePath - Absolute file path
1420
+ * @param content - File content as string
1421
+ * @returns WriteResult with error populated on failure
1422
+ */
1423
+ write(filePath: string, content: string): MaybePromise<WriteResult>;
1424
+ /**
1425
+ * Edit a file by replacing string occurrences.
1426
+ *
1427
+ * @param filePath - Absolute file path
1428
+ * @param oldString - String to find and replace
1429
+ * @param newString - Replacement string
1430
+ * @param replaceAll - If true, replace all occurrences (default: false)
1431
+ * @returns EditResult with error, path, filesUpdate, and occurrences
1432
+ */
1433
+ edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): MaybePromise<EditResult>;
1434
+ }
1435
+ /**
1436
+ * State and store container for backend initialization.
1437
+ *
1438
+ * This provides a clean interface for what backends need to access:
1439
+ * - state: Current agent state (with files, messages, etc.)
1440
+ * - store: Optional persistent store for cross-conversation data
1441
+ *
1442
+ * Different contexts build this differently:
1443
+ * - Tools: Extract state via getCurrentTaskInput(config)
1444
+ * - Middleware: Use request.state directly
1445
+ */
1446
+ interface StateAndStore {
1447
+ /** Current agent state with files, messages, etc. */
1448
+ state: unknown;
1449
+ /** Optional BaseStore for persistent cross-conversation storage */
1450
+ store?: BaseStore;
1451
+ /** Optional assistant ID for per-assistant isolation in store */
1452
+ assistantId?: string;
1453
+ assistant_id?: string;
1454
+ threadId?: string;
1455
+ tenantId?: string;
1456
+ workspaceId?: string;
1457
+ projectId?: string;
1458
+ }
1459
+ /**
1460
+ * Factory function type for creating backend instances.
1461
+ *
1462
+ * Backends receive StateAndStore which contains the current state
1463
+ * and optional store, extracted from the execution context.
1464
+ *
1465
+ * @example
1466
+ * ```typescript
1467
+ * // Using in middleware
1468
+ * const middleware = createFilesystemMiddleware({
1469
+ * backend: (stateAndStore) => new StateBackend(stateAndStore)
1470
+ * });
1471
+ * ```
1472
+ */
1473
+ type BackendFactory = (stateAndStore: StateAndStore) => Promise<BackendProtocol>;
1474
+
1268
1475
  interface SandboxFileInfo {
1269
1476
  path: string;
1270
1477
  is_dir: boolean;
@@ -1356,6 +1563,7 @@ interface SandboxManagerProtocol {
1356
1563
  stopSandbox(name: string): Promise<void>;
1357
1564
  deleteSandbox(name: string): Promise<void>;
1358
1565
  listSandboxes(): Promise<SandboxInstance[]>;
1566
+ getVolumeBackend(config: RunSandboxConfig): Promise<BackendProtocol | null>;
1359
1567
  }
1360
1568
 
1361
1569
  type ToolDefinition = ToolConfig;
@@ -3514,12 +3722,21 @@ declare class McpLatticeManager extends BaseLatticeManager<McpLatticeInterface>
3514
3722
  }
3515
3723
  declare const mcpManager: McpLatticeManager;
3516
3724
 
3725
+ interface VolumeFsClient {
3726
+ read(path: string): Promise<string>;
3727
+ write(path: string, content: string): Promise<void>;
3728
+ list(path: string): Promise<FsEntry[]>;
3729
+ readRaw(path: string): Promise<Buffer>;
3730
+ writeRaw(path: string, data: Buffer): Promise<void>;
3731
+ }
3732
+
3517
3733
  interface SandboxProvider {
3518
3734
  createSandbox(name: string, config?: RunSandboxConfig): Promise<SandboxInstance>;
3519
3735
  getSandbox(name: string): Promise<SandboxInstance>;
3520
3736
  stopSandbox(name: string): Promise<void>;
3521
3737
  deleteSandbox(name: string): Promise<void>;
3522
3738
  listSandboxes(): Promise<SandboxInstance[]>;
3739
+ createVolumeFsClient?(volumeName: string): VolumeFsClient;
3523
3740
  }
3524
3741
 
3525
3742
  interface MicrosandboxProviderConfig {
@@ -3534,7 +3751,7 @@ declare class MicrosandboxProvider implements SandboxProvider {
3534
3751
  private instances;
3535
3752
  private creating;
3536
3753
  constructor(config?: MicrosandboxProviderConfig);
3537
- createSandbox(name: string): Promise<SandboxInstance>;
3754
+ createSandbox(name: string, config?: RunSandboxConfig): Promise<SandboxInstance>;
3538
3755
  getSandbox(name: string): Promise<SandboxInstance>;
3539
3756
  stopSandbox(name: string): Promise<void>;
3540
3757
  deleteSandbox(name: string): Promise<void>;
@@ -3580,6 +3797,15 @@ type ExecCommandResponse = {
3580
3797
  stderr: string;
3581
3798
  exitCode: number;
3582
3799
  };
3800
+ type VolumeFsListResponse = {
3801
+ entries: Array<{
3802
+ path: string;
3803
+ kind: string;
3804
+ size: number;
3805
+ mode: number;
3806
+ modified: string | null;
3807
+ }>;
3808
+ };
3583
3809
  interface EnsureMicrosandboxInput {
3584
3810
  image?: string;
3585
3811
  cpus?: number;
@@ -3620,10 +3846,15 @@ declare class MicrosandboxServiceClient {
3620
3846
  uploadFile(sandboxName: string, path: string, content: Buffer): Promise<WriteFileResponse>;
3621
3847
  downloadFile(sandboxName: string, path: string): Promise<DownloadFileResponse>;
3622
3848
  execCommand(input: MicrosandboxShellExecInput): Promise<ExecCommandResponse>;
3849
+ volumeFsRead(volumeName: string, path: string): Promise<string>;
3850
+ volumeFsWrite(volumeName: string, path: string, content: string): Promise<void>;
3851
+ volumeFsList(volumeName: string, path: string): Promise<VolumeFsListResponse["entries"]>;
3852
+ volumeFsDownload(volumeName: string, path: string): Promise<Buffer>;
3853
+ volumeFsUpload(volumeName: string, path: string, data: Buffer): Promise<void>;
3623
3854
  private request;
3624
3855
  }
3625
3856
 
3626
- type MicrosandboxRemoteProviderClient = Pick<MicrosandboxServiceClient, "ensureSandbox" | "startSandbox" | "stopSandbox" | "killSandbox" | "deleteSandbox" | "getStatus" | "readFile" | "writeFile" | "listPath" | "findFiles" | "searchInFile" | "replaceInFile" | "uploadFile" | "downloadFile" | "execCommand">;
3857
+ type MicrosandboxRemoteProviderClient = Pick<MicrosandboxServiceClient, "ensureSandbox" | "startSandbox" | "stopSandbox" | "killSandbox" | "deleteSandbox" | "getStatus" | "readFile" | "writeFile" | "listPath" | "findFiles" | "searchInFile" | "replaceInFile" | "uploadFile" | "downloadFile" | "execCommand" | "volumeFsRead" | "volumeFsWrite" | "volumeFsList" | "volumeFsDownload" | "volumeFsUpload">;
3627
3858
  interface MicrosandboxRemoteProviderConfig extends MicrosandboxServiceClientConfig {
3628
3859
  client?: MicrosandboxRemoteProviderClient;
3629
3860
  image?: string;
@@ -3641,6 +3872,7 @@ declare class MicrosandboxRemoteProvider implements SandboxProvider {
3641
3872
  getSandbox(name: string): Promise<SandboxInstance>;
3642
3873
  stopSandbox(name: string): Promise<void>;
3643
3874
  deleteSandbox(name: string): Promise<void>;
3875
+ createVolumeFsClient(volumeName: string): VolumeFsClient;
3644
3876
  listSandboxes(): Promise<SandboxInstance[]>;
3645
3877
  private buildEnsureInput;
3646
3878
  private buildDefaultVolumes;
@@ -3862,6 +4094,7 @@ declare class SandboxLatticeManager extends BaseLatticeManager<SandboxProvider>
3862
4094
  vmIsolation: SandboxIsolationLevel;
3863
4095
  };
3864
4096
  getSandboxFromConfig(config: RunSandboxConfig): Promise<SandboxInstance>;
4097
+ getVolumeBackend(config: RunSandboxConfig): Promise<BackendProtocol | null>;
3865
4098
  createSandbox(name: string, config?: RunSandboxConfig): Promise<SandboxInstance>;
3866
4099
  getSandbox(name: string): Promise<SandboxInstance>;
3867
4100
  stopSandbox(name: string): Promise<void>;
@@ -3873,24 +4106,16 @@ declare const sandboxLatticeManager: SandboxLatticeManager;
3873
4106
  declare const getSandBoxManager: (key?: string) => SandboxManagerProtocol;
3874
4107
 
3875
4108
  /**
3876
- * Sandbox name normalization utility
3877
- *
3878
- * Normalizes sandbox names to comply with RFC 1123 subdomain naming requirements:
3879
- * - Only lowercase alphanumeric characters, '-' or '.'
3880
- * - Must start and end with an alphanumeric character
3881
- * - No underscores or other special characters
3882
- */
3883
- /**
3884
- * Normalize a sandbox name to be RFC 1123 compliant
4109
+ * Generate a sandbox name from meaningful identifiers.
3885
4110
  *
3886
- * @param name - The sandbox name to normalize
3887
- * @returns Normalized sandbox name that complies with RFC 1123 subdomain rules
4111
+ * All sandbox names are hashed (like buildNamedVolumeName) producing a
4112
+ * fixed 17-char "n<hash>" format. This avoids Unix domain socket path
4113
+ * length limits (SUN_LEN = 104 on macOS, 108 on Linux) regardless of
4114
+ * how long the input identifiers are.
3888
4115
  *
3889
- * @example
3890
- * normalizeSandboxName("sandbox_agent") // returns "sandbox-agent"
3891
- * normalizeSandboxName("My-Sandbox") // returns "my-sandbox"
3892
- * normalizeSandboxName("test.sandbox") // returns "test.sandbox"
3893
- * normalizeSandboxName("_invalid_") // returns "invalid"
4116
+ * Original identity metadata (tenant, assistant, project, etc.) should
4117
+ * be passed via sandbox env so operational tooling can still map names
4118
+ * back to their source.
3894
4119
  */
3895
4120
  declare function normalizeSandboxName(name: string): string;
3896
4121
  /**
@@ -3900,6 +4125,14 @@ declare function normalizeSandboxName(name: string): string;
3900
4125
  * @returns true if the name is valid, false otherwise
3901
4126
  */
3902
4127
  declare function isValidSandboxName(name: string): boolean;
4128
+ /**
4129
+ * Build env vars mapping a hashed sandbox name back to its source metadata.
4130
+ * Injected into every sandbox so operational tooling can correlate
4131
+ * opaque "n<hash>" names to the original tenant/assistant/project/workspace.
4132
+ */
4133
+ declare function buildSandboxMetadataEnv(config?: RunSandboxConfig): Record<string, string>;
4134
+
4135
+ declare function buildNamedVolumeName(prefix: "s" | "a" | "p", ...parts: Array<string | undefined>): string;
3903
4136
 
3904
4137
  /**
3905
4138
  * Agent Team - Store Protocols
@@ -4469,213 +4702,6 @@ declare class TeamAgentGraphBuilder implements AgentGraphBuilder {
4469
4702
  */
4470
4703
  declare function createAgentTeam(config: TeamConfig): ReactAgent<any, any, any, any>;
4471
4704
 
4472
- /**
4473
- * Protocol definition for pluggable memory backends.
4474
- *
4475
- * This module defines the BackendProtocol that all backend implementations
4476
- * must follow. Backends can store files in different locations (state, filesystem,
4477
- * database, etc.) and provide a uniform interface for file operations.
4478
- */
4479
-
4480
- type MaybePromise<T> = T | Promise<T>;
4481
- /**
4482
- * Structured file listing info.
4483
- *
4484
- * Minimal contract used across backends. Only "path" is required.
4485
- * Other fields are best-effort and may be absent depending on backend.
4486
- */
4487
- interface FileInfo {
4488
- /** File path */
4489
- path: string;
4490
- /** Whether this is a directory */
4491
- is_dir?: boolean;
4492
- /** File size in bytes (approximate) */
4493
- size?: number;
4494
- /** ISO 8601 timestamp of last modification */
4495
- modified_at?: string;
4496
- }
4497
- /**
4498
- * Structured grep match entry.
4499
- */
4500
- interface GrepMatch {
4501
- /** File path where match was found */
4502
- path: string;
4503
- /** Line number (1-indexed) */
4504
- line: number;
4505
- /** The matching line text */
4506
- text: string;
4507
- }
4508
- /**
4509
- * File data structure used by backends.
4510
- *
4511
- * All file data is represented as objects with this structure:
4512
- */
4513
- interface FileData {
4514
- /** Lines of text content */
4515
- content: string[];
4516
- /** ISO format timestamp of creation */
4517
- created_at: string;
4518
- /** ISO format timestamp of last modification */
4519
- modified_at: string;
4520
- }
4521
- /**
4522
- * Result from backend write operations.
4523
- *
4524
- * Checkpoint backends populate filesUpdate with {file_path: file_data} for LangGraph state.
4525
- * External backends set filesUpdate to null (already persisted to disk/S3/database/etc).
4526
- */
4527
- interface WriteResult {
4528
- /** Error message on failure, undefined on success */
4529
- error?: string;
4530
- /** File path of written file, undefined on failure */
4531
- path?: string;
4532
- /**
4533
- * State update dict for checkpoint backends, null for external storage.
4534
- * Checkpoint backends populate this with {file_path: file_data} for LangGraph state.
4535
- * External backends set null (already persisted to disk/S3/database/etc).
4536
- */
4537
- filesUpdate?: Record<string, FileData> | null;
4538
- /** Metadata for the write operation, attached to the ToolMessage */
4539
- metadata?: Record<string, unknown>;
4540
- }
4541
- /**
4542
- * Result from backend edit operations.
4543
- *
4544
- * Checkpoint backends populate filesUpdate with {file_path: file_data} for LangGraph state.
4545
- * External backends set filesUpdate to null (already persisted to disk/S3/database/etc).
4546
- */
4547
- interface EditResult {
4548
- /** Error message on failure, undefined on success */
4549
- error?: string;
4550
- /** File path of edited file, undefined on failure */
4551
- path?: string;
4552
- /**
4553
- * State update dict for checkpoint backends, null for external storage.
4554
- * Checkpoint backends populate this with {file_path: file_data} for LangGraph state.
4555
- * External backends set null (already persisted to disk/S3/database/etc).
4556
- */
4557
- filesUpdate?: Record<string, FileData> | null;
4558
- /** Number of replacements made, undefined on failure */
4559
- occurrences?: number;
4560
- /** Metadata for the edit operation, attached to the ToolMessage */
4561
- metadata?: Record<string, unknown>;
4562
- }
4563
- /**
4564
- * Protocol for pluggable memory backends (single, unified).
4565
- *
4566
- * Backends can store files in different locations (state, filesystem, database, etc.)
4567
- * and provide a uniform interface for file operations.
4568
- *
4569
- * All file data is represented as objects with the FileData structure.
4570
- *
4571
- * Methods can return either direct values or Promises, allowing both
4572
- * synchronous and asynchronous implementations.
4573
- */
4574
- interface BackendProtocol {
4575
- /**
4576
- * Structured listing with file metadata.
4577
- *
4578
- * Lists files and directories in the specified directory (non-recursive).
4579
- * Directories have a trailing / in their path and is_dir=true.
4580
- *
4581
- * @param path - Absolute path to directory
4582
- * @returns List of FileInfo objects for files and directories directly in the directory
4583
- */
4584
- lsInfo(path: string): MaybePromise<FileInfo[]>;
4585
- /**
4586
- * Read file content with line numbers or an error string.
4587
- *
4588
- * @param filePath - Absolute file path
4589
- * @param offset - Line offset to start reading from (0-indexed), default 0
4590
- * @param limit - Maximum number of lines to read, default 2000
4591
- * @returns Formatted file content with line numbers, or error message
4592
- */
4593
- read(filePath: string, offset?: number, limit?: number): MaybePromise<string>;
4594
- /**
4595
- * Read file content as raw FileData.
4596
- *
4597
- * @param filePath - Absolute file path
4598
- * @returns Raw file content as FileData
4599
- */
4600
- readRaw(filePath: string): MaybePromise<FileData>;
4601
- /**
4602
- * Structured search results or error string for invalid input.
4603
- *
4604
- * Searches file contents for a regex pattern.
4605
- *
4606
- * @param pattern - Regex pattern to search for
4607
- * @param path - Base path to search from (default: null)
4608
- * @param glob - Optional glob pattern to filter files (e.g., "*.py")
4609
- * @returns List of GrepMatch objects or error string for invalid regex
4610
- */
4611
- grepRaw(pattern: string, path?: string | null, glob?: string | null): MaybePromise<GrepMatch[] | string>;
4612
- /**
4613
- * Structured glob matching returning FileInfo objects.
4614
- *
4615
- * @param pattern - Glob pattern (e.g., `*.py`, `**\/*.ts`)
4616
- * @param path - Base path to search from (default: "/")
4617
- * @returns List of FileInfo objects matching the pattern
4618
- */
4619
- globInfo(pattern: string, path?: string): MaybePromise<FileInfo[]>;
4620
- /**
4621
- * Create a new file.
4622
- *
4623
- * @param filePath - Absolute file path
4624
- * @param content - File content as string
4625
- * @returns WriteResult with error populated on failure
4626
- */
4627
- write(filePath: string, content: string): MaybePromise<WriteResult>;
4628
- /**
4629
- * Edit a file by replacing string occurrences.
4630
- *
4631
- * @param filePath - Absolute file path
4632
- * @param oldString - String to find and replace
4633
- * @param newString - Replacement string
4634
- * @param replaceAll - If true, replace all occurrences (default: false)
4635
- * @returns EditResult with error, path, filesUpdate, and occurrences
4636
- */
4637
- edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): MaybePromise<EditResult>;
4638
- }
4639
- /**
4640
- * State and store container for backend initialization.
4641
- *
4642
- * This provides a clean interface for what backends need to access:
4643
- * - state: Current agent state (with files, messages, etc.)
4644
- * - store: Optional persistent store for cross-conversation data
4645
- *
4646
- * Different contexts build this differently:
4647
- * - Tools: Extract state via getCurrentTaskInput(config)
4648
- * - Middleware: Use request.state directly
4649
- */
4650
- interface StateAndStore {
4651
- /** Current agent state with files, messages, etc. */
4652
- state: unknown;
4653
- /** Optional BaseStore for persistent cross-conversation storage */
4654
- store?: BaseStore;
4655
- /** Optional assistant ID for per-assistant isolation in store */
4656
- assistantId?: string;
4657
- assistant_id?: string;
4658
- threadId?: string;
4659
- tenantId?: string;
4660
- workspaceId?: string;
4661
- projectId?: string;
4662
- }
4663
- /**
4664
- * Factory function type for creating backend instances.
4665
- *
4666
- * Backends receive StateAndStore which contains the current state
4667
- * and optional store, extracted from the execution context.
4668
- *
4669
- * @example
4670
- * ```typescript
4671
- * // Using in middleware
4672
- * const middleware = createFilesystemMiddleware({
4673
- * backend: (stateAndStore) => new StateBackend(stateAndStore)
4674
- * });
4675
- * ```
4676
- */
4677
- type BackendFactory = (stateAndStore: StateAndStore) => Promise<BackendProtocol>;
4678
-
4679
4705
  /**
4680
4706
  * StateBackend: Store files in LangGraph agent state (ephemeral).
4681
4707
  */
@@ -5056,6 +5082,18 @@ declare class SandboxFilesystem implements BackendProtocol {
5056
5082
  globInfo(pattern: string, searchPath?: string): Promise<FileInfo[]>;
5057
5083
  }
5058
5084
 
5085
+ declare class VolumeFilesystem implements BackendProtocol {
5086
+ private readonly client;
5087
+ constructor(client: VolumeFsClient);
5088
+ lsInfo(path: string): Promise<FileInfo[]>;
5089
+ read(filePath: string, offset?: number, limit?: number): Promise<string>;
5090
+ readRaw(filePath: string): Promise<FileData>;
5091
+ grepRaw(_pattern: string, _path?: string | null, _glob?: string | null): string | GrepMatch[];
5092
+ globInfo(_pattern: string, _path?: string): FileInfo[];
5093
+ write(filePath: string, content: string): Promise<WriteResult>;
5094
+ edit(_filePath: string, _oldString: string, _newString: string, _replaceAll?: boolean): EditResult;
5095
+ }
5096
+
5059
5097
  /**
5060
5098
  * Shared utility functions for memory backend implementations.
5061
5099
  *
@@ -5655,4 +5693,4 @@ interface SchedulerMiddlewareOptions {
5655
5693
  }
5656
5694
  declare function createSchedulerMiddleware(options?: SchedulerMiddlewareOptions): AgentMiddleware;
5657
5695
 
5658
- export { AGENT_TASK_EVENT, type AddMessageParams, Agent, type AgentClient, type AgentExecutor, AgentInstanceManager, type AgentLattice, AgentLatticeManager, type AgentLifecycleEventName, AgentManager, type AgentStreamExecutor, type AgentThreadInterface, type BackendFactory, type BackendProtocol, type BufferStats, type Chunk, ChunkBuffer, ChunkBufferLatticeManager, type ColumnInfo, CompositeBackend, ConsoleLoggerClient, type CreateSandboxProviderConfig, type CronFields, CustomMetricsClient, type DatabaseConfig, type DatabaseType, DaytonaInstance, DaytonaProvider, type DaytonaProviderConfig, DefaultScheduleClient, E2BInstance, E2BProvider, type E2BProviderConfig, EMPTY_CONTENT_WARNING, type EditResult, type EmbeddingsLatticeInterface, EmbeddingsLatticeManager, type EnsureMicrosandboxInput, type FileData, type FileInfo, FileSystemSkillStore, type FileSystemSkillStoreOptions, FilesystemBackend, type GrepMatch, type IMessageQueueStore, type IMetricsServerClient, type ISqlDatabase, InMemoryAssistantStore, InMemoryChunkBuffer, InMemoryDatabaseConfigStore, InMemoryMailboxStore, InMemoryTaskListStore, InMemoryTenantStore, InMemoryThreadMessageQueueStore, InMemoryThreadStore, InMemoryUserStore, InMemoryUserTenantLinkStore, LINE_NUMBER_WIDTH, type LangGraphStateChecker, type LoggerLattice, LoggerLatticeManager, MAX_LINE_LENGTH, type MailboxMessage, type MailboxStore, type McpLatticeInterface, McpLatticeManager, type McpServerInfo, MemoryBackend, MemoryLatticeManager, MemoryQueueClient, MemoryScheduleStorage, type MessageCompletedEvent, type MessageFailedEvent, type MessageStartedEvent, MessageType, MetricsServerManager, MicrosandboxInstance, MicrosandboxProvider, type MicrosandboxProviderConfig, MicrosandboxRemoteInstance, MicrosandboxRemoteProvider, type MicrosandboxRemoteProviderClient, type MicrosandboxRemoteProviderConfig, MicrosandboxServiceClient, type MicrosandboxServiceClientConfig, type MicrosandboxShellExecInput, type ModelConfig, type ModelLatticeInterface, ModelLatticeManager, type PendingMessage, PinoLoggerClient, PostgresDatabase, PrometheusClient, type QueryResult, type QueueLattice, QueueLatticeManager, QueueMode, type QueuePendingEvent, RemoteSandboxInstance, RemoteSandboxProvider, type RemoteSandboxProviderConfig, type RunSandboxConfig, type RuntimeModelConfig, type SandboxFileInfo, type SandboxFileService, SandboxFilesystem, type SandboxInstance, type SandboxIsolationLevel, SandboxLatticeManager, type SandboxManagerProtocol, type SandboxProvider, type SandboxShellService, SandboxSkillStore, type SandboxSkillStoreOptions, type SandboxVolumeDefinition, type ScheduleLattice, ScheduleLatticeManager, type SchedulerMiddlewareOptions, SemanticMetricsClient, type SkillLattice, SkillLatticeManager, type SkillMeta, type SkillResource, SqlDatabaseManager, type StateAndStore, StateBackend, StoreBackend, type StoreLattice, StoreLatticeManager, type StoreType, type StoreTypeMap, TOOL_RESULT_TOKEN_LIMIT, TRUNCATION_GUIDANCE, type TableInfo, type TableSchema, type TaskEvent, type TaskListStore, type TaskSpec, TaskStatus, type TaskUpdatable, TeamAgentGraphBuilder, type TeamConfig, type TeamMiddlewareOptions, type TeamTask, type TeammateSpec, type TeammateToolsOptions, type ThreadBuffer, type ThreadBufferConfig, type ThreadBusyEvent, type ThreadIdleEvent, type ThreadInfo, type ThreadQueueConfig, type ThreadState, ThreadStatus, type ThreadStatusChangedEvent, type ToolDefinition, type ToolLattice, ToolLatticeManager, type UnknownToolHandlerConfig, type VectorStoreLatticeInterface, VectorStoreLatticeManager, type WriteResult, agentInstanceManager, agentLatticeManager, buildGrepResultsDict, buildSkillFile, checkEmptyContent, clearEncryptionKeyCache, computeSandboxName, createAgentTeam, createExecuteSqlQueryTool, createFileData, createInfoSqlTool, createListMetricsDataSourcesTool, createListMetricsServersTool, createListTablesSqlTool, createModelSelectorMiddleware, createQueryCheckerSqlTool, createQueryMetricDefinitionTool, createQueryMetricsListTool, createQuerySemanticMetricDataTool, createQuerySqlTool, createQueryTableDefinitionTool, createQueryTablesListTool, createSandboxProvider, createSchedulerMiddleware, createTeamMiddleware, createTeammateTools, createUnknownToolHandlerMiddleware, createWidgetMiddleware, decrypt, defaultMicrosandboxConfig, describeCronExpression, embeddingsLatticeManager, encrypt, eventBus, eventBus as eventBusDefault, fileDataToString, formatContentWithLineNumbers, formatGrepMatches, formatGrepResults, formatReadResponse, getAgentClient, getAgentConfig, getAllAgentConfigs, getAllToolDefinitions, getCheckpointSaver, getChunkBuffer, getEmbeddingsClient, getEmbeddingsLattice, getEncryptionKey, getLoggerLattice, getModelLattice, getNextCronTime, getQueueLattice, getSandBoxManager, getScheduleLattice, getStoreLattice, getToolClient, getToolDefinition, getToolLattice, getVectorStoreClient, getVectorStoreLattice, globSearchFiles, grepMatchesFromFiles, grepSearchFiles, hasChunkBuffer, isUsingDefaultKey, isValidCronExpression, isValidSandboxName, isValidSkillName, loggerLatticeManager, mcpManager, metricsServerManager, modelLatticeManager, normalizeSandboxName, parseCronExpression, parseSkillFrontmatter, performStringReplacement, queueLatticeManager, registerAgentLattice, registerAgentLatticeWithTenant, registerAgentLattices, registerCheckpointSaver, registerChunkBuffer, registerEmbeddingsLattice, registerExistingTool, registerLoggerLattice, registerModelLattice, registerQueueLattice, registerScheduleLattice, registerStoreLattice, registerTeammateAgent, registerToolLattice, registerVectorStoreLattice, sandboxLatticeManager, sanitizeToolCallId, scheduleLatticeManager, skillLatticeManager, sqlDatabaseManager, storeLatticeManager, toolLatticeManager, truncateIfTooLong, unregisterTeammateAgent, updateFileData, validateAgentInput, validateEncryptionKey, validatePath, validateSkillName, validateToolInput, vectorStoreLatticeManager };
5696
+ export { AGENT_TASK_EVENT, type AddMessageParams, Agent, type AgentClient, type AgentExecutor, AgentInstanceManager, type AgentLattice, AgentLatticeManager, type AgentLifecycleEventName, AgentManager, type AgentStreamExecutor, type AgentThreadInterface, type BackendFactory, type BackendProtocol, type BufferStats, type Chunk, ChunkBuffer, ChunkBufferLatticeManager, type ColumnInfo, CompositeBackend, ConsoleLoggerClient, type CreateSandboxProviderConfig, type CronFields, CustomMetricsClient, type DatabaseConfig, type DatabaseType, DaytonaInstance, DaytonaProvider, type DaytonaProviderConfig, DefaultScheduleClient, E2BInstance, E2BProvider, type E2BProviderConfig, EMPTY_CONTENT_WARNING, type EditResult, type EmbeddingsLatticeInterface, EmbeddingsLatticeManager, type EnsureMicrosandboxInput, type FileData, type FileInfo, FileSystemSkillStore, type FileSystemSkillStoreOptions, FilesystemBackend, type GrepMatch, type IMessageQueueStore, type IMetricsServerClient, type ISqlDatabase, InMemoryAssistantStore, InMemoryChunkBuffer, InMemoryDatabaseConfigStore, InMemoryMailboxStore, InMemoryTaskListStore, InMemoryTenantStore, InMemoryThreadMessageQueueStore, InMemoryThreadStore, InMemoryUserStore, InMemoryUserTenantLinkStore, LINE_NUMBER_WIDTH, type LangGraphStateChecker, type LoggerLattice, LoggerLatticeManager, MAX_LINE_LENGTH, type MailboxMessage, type MailboxStore, type McpLatticeInterface, McpLatticeManager, type McpServerInfo, MemoryBackend, MemoryLatticeManager, MemoryQueueClient, MemoryScheduleStorage, type MessageCompletedEvent, type MessageFailedEvent, type MessageStartedEvent, MessageType, MetricsServerManager, MicrosandboxInstance, MicrosandboxProvider, type MicrosandboxProviderConfig, MicrosandboxRemoteInstance, MicrosandboxRemoteProvider, type MicrosandboxRemoteProviderClient, type MicrosandboxRemoteProviderConfig, MicrosandboxServiceClient, type MicrosandboxServiceClientConfig, type MicrosandboxShellExecInput, type ModelConfig, type ModelLatticeInterface, ModelLatticeManager, type PendingMessage, PinoLoggerClient, PostgresDatabase, PrometheusClient, type QueryResult, type QueueLattice, QueueLatticeManager, QueueMode, type QueuePendingEvent, RemoteSandboxInstance, RemoteSandboxProvider, type RemoteSandboxProviderConfig, type RunSandboxConfig, type RuntimeModelConfig, type SandboxFileInfo, type SandboxFileService, SandboxFilesystem, type SandboxInstance, type SandboxIsolationLevel, SandboxLatticeManager, type SandboxManagerProtocol, type SandboxProvider, type SandboxShellService, SandboxSkillStore, type SandboxSkillStoreOptions, type SandboxVolumeDefinition, type ScheduleLattice, ScheduleLatticeManager, type SchedulerMiddlewareOptions, SemanticMetricsClient, type SkillLattice, SkillLatticeManager, type SkillMeta, type SkillResource, SqlDatabaseManager, type StateAndStore, StateBackend, StoreBackend, type StoreLattice, StoreLatticeManager, type StoreType, type StoreTypeMap, TOOL_RESULT_TOKEN_LIMIT, TRUNCATION_GUIDANCE, type TableInfo, type TableSchema, type TaskEvent, type TaskListStore, type TaskSpec, TaskStatus, type TaskUpdatable, TeamAgentGraphBuilder, type TeamConfig, type TeamMiddlewareOptions, type TeamTask, type TeammateSpec, type TeammateToolsOptions, type ThreadBuffer, type ThreadBufferConfig, type ThreadBusyEvent, type ThreadIdleEvent, type ThreadInfo, type ThreadQueueConfig, type ThreadState, ThreadStatus, type ThreadStatusChangedEvent, type ToolDefinition, type ToolLattice, ToolLatticeManager, type UnknownToolHandlerConfig, type VectorStoreLatticeInterface, VectorStoreLatticeManager, VolumeFilesystem, type VolumeFsClient, type WriteResult, agentInstanceManager, agentLatticeManager, buildGrepResultsDict, buildNamedVolumeName, buildSandboxMetadataEnv, buildSkillFile, checkEmptyContent, clearEncryptionKeyCache, computeSandboxName, createAgentTeam, createExecuteSqlQueryTool, createFileData, createInfoSqlTool, createListMetricsDataSourcesTool, createListMetricsServersTool, createListTablesSqlTool, createModelSelectorMiddleware, createQueryCheckerSqlTool, createQueryMetricDefinitionTool, createQueryMetricsListTool, createQuerySemanticMetricDataTool, createQuerySqlTool, createQueryTableDefinitionTool, createQueryTablesListTool, createSandboxProvider, createSchedulerMiddleware, createTeamMiddleware, createTeammateTools, createUnknownToolHandlerMiddleware, createWidgetMiddleware, decrypt, defaultMicrosandboxConfig, describeCronExpression, embeddingsLatticeManager, encrypt, eventBus, eventBus as eventBusDefault, fileDataToString, formatContentWithLineNumbers, formatGrepMatches, formatGrepResults, formatReadResponse, getAgentClient, getAgentConfig, getAllAgentConfigs, getAllToolDefinitions, getCheckpointSaver, getChunkBuffer, getEmbeddingsClient, getEmbeddingsLattice, getEncryptionKey, getLoggerLattice, getModelLattice, getNextCronTime, getQueueLattice, getSandBoxManager, getScheduleLattice, getStoreLattice, getToolClient, getToolDefinition, getToolLattice, getVectorStoreClient, getVectorStoreLattice, globSearchFiles, grepMatchesFromFiles, grepSearchFiles, hasChunkBuffer, isUsingDefaultKey, isValidCronExpression, isValidSandboxName, isValidSkillName, loggerLatticeManager, mcpManager, metricsServerManager, modelLatticeManager, normalizeSandboxName, parseCronExpression, parseSkillFrontmatter, performStringReplacement, queueLatticeManager, registerAgentLattice, registerAgentLatticeWithTenant, registerAgentLattices, registerCheckpointSaver, registerChunkBuffer, registerEmbeddingsLattice, registerExistingTool, registerLoggerLattice, registerModelLattice, registerQueueLattice, registerScheduleLattice, registerStoreLattice, registerTeammateAgent, registerToolLattice, registerVectorStoreLattice, sandboxLatticeManager, sanitizeToolCallId, scheduleLatticeManager, skillLatticeManager, sqlDatabaseManager, storeLatticeManager, toolLatticeManager, truncateIfTooLong, unregisterTeammateAgent, updateFileData, validateAgentInput, validateEncryptionKey, validatePath, validateSkillName, validateToolInput, vectorStoreLatticeManager };