zeitlich 0.2.29 → 0.2.30

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.
Files changed (98) hide show
  1. package/dist/{activities-1xrWRrGJ.d.cts → activities-BeveyY9b.d.cts} +2 -2
  2. package/dist/{activities-DOViDCTE.d.ts → activities-NT3rcw66.d.ts} +2 -2
  3. package/dist/adapters/sandbox/bedrock/index.cjs.map +1 -1
  4. package/dist/adapters/sandbox/bedrock/index.d.cts +3 -3
  5. package/dist/adapters/sandbox/bedrock/index.d.ts +3 -3
  6. package/dist/adapters/sandbox/bedrock/index.js.map +1 -1
  7. package/dist/adapters/sandbox/bedrock/workflow.d.cts +2 -2
  8. package/dist/adapters/sandbox/bedrock/workflow.d.ts +2 -2
  9. package/dist/adapters/sandbox/daytona/index.cjs.map +1 -1
  10. package/dist/adapters/sandbox/daytona/index.d.cts +1 -1
  11. package/dist/adapters/sandbox/daytona/index.d.ts +1 -1
  12. package/dist/adapters/sandbox/daytona/index.js.map +1 -1
  13. package/dist/adapters/sandbox/daytona/workflow.d.cts +1 -1
  14. package/dist/adapters/sandbox/daytona/workflow.d.ts +1 -1
  15. package/dist/adapters/sandbox/e2b/index.cjs.map +1 -1
  16. package/dist/adapters/sandbox/e2b/index.d.cts +1 -1
  17. package/dist/adapters/sandbox/e2b/index.d.ts +1 -1
  18. package/dist/adapters/sandbox/e2b/index.js.map +1 -1
  19. package/dist/adapters/sandbox/e2b/workflow.d.cts +1 -1
  20. package/dist/adapters/sandbox/e2b/workflow.d.ts +1 -1
  21. package/dist/adapters/sandbox/inmemory/index.cjs.map +1 -1
  22. package/dist/adapters/sandbox/inmemory/index.d.cts +1 -1
  23. package/dist/adapters/sandbox/inmemory/index.d.ts +1 -1
  24. package/dist/adapters/sandbox/inmemory/index.js.map +1 -1
  25. package/dist/adapters/sandbox/inmemory/workflow.d.cts +1 -1
  26. package/dist/adapters/sandbox/inmemory/workflow.d.ts +1 -1
  27. package/dist/adapters/thread/anthropic/index.cjs +0 -1
  28. package/dist/adapters/thread/anthropic/index.cjs.map +1 -1
  29. package/dist/adapters/thread/anthropic/index.d.cts +5 -5
  30. package/dist/adapters/thread/anthropic/index.d.ts +5 -5
  31. package/dist/adapters/thread/anthropic/index.js +0 -1
  32. package/dist/adapters/thread/anthropic/index.js.map +1 -1
  33. package/dist/adapters/thread/anthropic/workflow.d.cts +5 -5
  34. package/dist/adapters/thread/anthropic/workflow.d.ts +5 -5
  35. package/dist/adapters/thread/google-genai/index.cjs +0 -1
  36. package/dist/adapters/thread/google-genai/index.cjs.map +1 -1
  37. package/dist/adapters/thread/google-genai/index.d.cts +5 -5
  38. package/dist/adapters/thread/google-genai/index.d.ts +5 -5
  39. package/dist/adapters/thread/google-genai/index.js +0 -1
  40. package/dist/adapters/thread/google-genai/index.js.map +1 -1
  41. package/dist/adapters/thread/google-genai/workflow.d.cts +5 -5
  42. package/dist/adapters/thread/google-genai/workflow.d.ts +5 -5
  43. package/dist/adapters/thread/langchain/index.cjs +0 -1
  44. package/dist/adapters/thread/langchain/index.cjs.map +1 -1
  45. package/dist/adapters/thread/langchain/index.d.cts +5 -5
  46. package/dist/adapters/thread/langchain/index.d.ts +5 -5
  47. package/dist/adapters/thread/langchain/index.js +0 -1
  48. package/dist/adapters/thread/langchain/index.js.map +1 -1
  49. package/dist/adapters/thread/langchain/workflow.d.cts +5 -5
  50. package/dist/adapters/thread/langchain/workflow.d.ts +5 -5
  51. package/dist/index.cjs +69 -52
  52. package/dist/index.cjs.map +1 -1
  53. package/dist/index.d.cts +78 -15
  54. package/dist/index.d.ts +78 -15
  55. package/dist/index.js +69 -52
  56. package/dist/index.js.map +1 -1
  57. package/dist/{proxy-78nc985d.d.ts → proxy-BgswT47M.d.ts} +1 -1
  58. package/dist/{proxy-Bm2UTiO_.d.cts → proxy-OJihshQF.d.cts} +1 -1
  59. package/dist/{thread-manager-07BaYu_z.d.ts → thread-manager-BS477gj8.d.ts} +1 -1
  60. package/dist/{thread-manager-BRE5KkHB.d.cts → thread-manager-DH0zv05W.d.cts} +1 -1
  61. package/dist/{thread-manager-CxbWo7q_.d.ts → thread-manager-iUplxEZt.d.ts} +1 -1
  62. package/dist/{thread-manager-CatBkarc.d.cts → thread-manager-lfN0V-gH.d.cts} +1 -1
  63. package/dist/{types-ChAMwU3q.d.ts → types-AujBIMMn.d.cts} +5 -8
  64. package/dist/{types-ChAMwU3q.d.cts → types-AujBIMMn.d.ts} +5 -8
  65. package/dist/{types-DAv_SLN8.d.ts → types-CCIc7Eam.d.ts} +1 -1
  66. package/dist/{types-BkVoEyiH.d.ts → types-D90Q5aOh.d.ts} +140 -139
  67. package/dist/{types-BdCdR41N.d.ts → types-DBk-C8zM.d.ts} +1 -1
  68. package/dist/{types-ZHs2v9Ap.d.cts → types-DUvEZSDe.d.cts} +1 -1
  69. package/dist/{types-seDYom4M.d.cts → types-DVdT5ybA.d.cts} +140 -139
  70. package/dist/{types-Dpz2gXLk.d.cts → types-DgIVPOa1.d.cts} +1 -1
  71. package/dist/{workflow-B4T3la0p.d.cts → workflow-Cj4DxGdM.d.cts} +2 -2
  72. package/dist/{workflow-DCmaXLZ_.d.ts → workflow-CzrBdCcJ.d.ts} +2 -2
  73. package/dist/workflow.cjs +31 -43
  74. package/dist/workflow.cjs.map +1 -1
  75. package/dist/workflow.d.cts +3 -3
  76. package/dist/workflow.d.ts +3 -3
  77. package/dist/workflow.js +31 -43
  78. package/dist/workflow.js.map +1 -1
  79. package/package.json +1 -1
  80. package/src/adapters/thread/anthropic/thread-manager.ts +6 -6
  81. package/src/adapters/thread/google-genai/thread-manager.ts +6 -6
  82. package/src/adapters/thread/langchain/thread-manager.ts +6 -6
  83. package/src/index.ts +1 -0
  84. package/src/lib/lifecycle.ts +8 -3
  85. package/src/lib/sandbox/index.ts +2 -4
  86. package/src/lib/sandbox/manager.ts +128 -13
  87. package/src/lib/sandbox/sandbox.test.ts +136 -16
  88. package/src/lib/sandbox/types.ts +6 -5
  89. package/src/lib/session/session.integration.test.ts +7 -40
  90. package/src/lib/session/session.ts +63 -49
  91. package/src/lib/session/types.ts +22 -13
  92. package/src/lib/state/types.ts +9 -6
  93. package/src/lib/subagent/handler.ts +18 -12
  94. package/src/lib/subagent/register.ts +11 -12
  95. package/src/lib/types.ts +2 -0
  96. package/src/lib/virtual-fs/types.ts +8 -14
  97. package/src/lib/virtual-fs/with-virtual-fs.ts +4 -4
  98. package/src/tools/bash/bash.test.ts +2 -1
@@ -1,5 +1,5 @@
1
1
  import { proxyActivities, ActivityInterfaceFor } from '@temporalio/workflow';
2
- import { T as ThreadOps } from './types-BkVoEyiH.js';
2
+ import { T as ThreadOps } from './types-D90Q5aOh.js';
3
3
 
4
4
  /**
5
5
  * Shared proxy helper for thread operations.
@@ -1,5 +1,5 @@
1
1
  import { proxyActivities, ActivityInterfaceFor } from '@temporalio/workflow';
2
- import { T as ThreadOps } from './types-seDYom4M.cjs';
2
+ import { T as ThreadOps } from './types-DVdT5ybA.cjs';
3
3
 
4
4
  /**
5
5
  * Shared proxy helper for thread operations.
@@ -1,6 +1,6 @@
1
1
  import Redis from 'ioredis';
2
2
  import Anthropic from '@anthropic-ai/sdk';
3
- import { T as ThreadManagerHooks, P as ProviderThreadManager } from './types-DAv_SLN8.js';
3
+ import { T as ThreadManagerHooks, P as ProviderThreadManager } from './types-CCIc7Eam.js';
4
4
 
5
5
  /** SDK-native content type for Anthropic human messages */
6
6
  type AnthropicContent = string | Anthropic.Messages.ContentBlockParam[];
@@ -1,6 +1,6 @@
1
1
  import Redis from 'ioredis';
2
2
  import { MessageContent, StoredMessage, BaseMessage } from '@langchain/core/messages';
3
- import { T as ThreadManagerHooks, P as ProviderThreadManager } from './types-Dpz2gXLk.cjs';
3
+ import { T as ThreadManagerHooks, P as ProviderThreadManager } from './types-DgIVPOa1.cjs';
4
4
 
5
5
  /** SDK-native content type for LangChain human messages */
6
6
  type LangChainContent = string | MessageContent;
@@ -1,6 +1,6 @@
1
1
  import Redis from 'ioredis';
2
2
  import { MessageContent, StoredMessage, BaseMessage } from '@langchain/core/messages';
3
- import { T as ThreadManagerHooks, P as ProviderThreadManager } from './types-DAv_SLN8.js';
3
+ import { T as ThreadManagerHooks, P as ProviderThreadManager } from './types-CCIc7Eam.js';
4
4
 
5
5
  /** SDK-native content type for LangChain human messages */
6
6
  type LangChainContent = string | MessageContent;
@@ -1,6 +1,6 @@
1
1
  import Redis from 'ioredis';
2
2
  import Anthropic from '@anthropic-ai/sdk';
3
- import { T as ThreadManagerHooks, P as ProviderThreadManager } from './types-Dpz2gXLk.cjs';
3
+ import { T as ThreadManagerHooks, P as ProviderThreadManager } from './types-DgIVPOa1.cjs';
4
4
 
5
5
  /** SDK-native content type for Anthropic human messages */
6
6
  type AnthropicContent = string | Anthropic.Messages.ContentBlockParam[];
@@ -86,8 +86,6 @@ interface SandboxCreateOptions {
86
86
  }
87
87
  interface SandboxCreateResult {
88
88
  sandbox: Sandbox;
89
- /** Optional state to merge into the workflow's `AgentState` via the session. */
90
- stateUpdate?: Record<string, unknown>;
91
89
  }
92
90
  interface SandboxProvider<TOptions extends SandboxCreateOptions = SandboxCreateOptions, TSandbox extends Sandbox = Sandbox> {
93
91
  readonly id: string;
@@ -100,11 +98,10 @@ interface SandboxProvider<TOptions extends SandboxCreateOptions = SandboxCreateO
100
98
  restore(snapshot: SandboxSnapshot): Promise<Sandbox>;
101
99
  fork(sandboxId: string): Promise<Sandbox>;
102
100
  }
103
- interface SandboxOps<TOptions extends SandboxCreateOptions = SandboxCreateOptions> {
104
- createSandbox(options?: TOptions): Promise<{
101
+ interface SandboxOps<TOptions extends SandboxCreateOptions = SandboxCreateOptions, TCtx = unknown> {
102
+ createSandbox(options?: TOptions, ctx?: TCtx): Promise<{
105
103
  sandboxId: string;
106
- stateUpdate?: Record<string, unknown>;
107
- }>;
104
+ } | null>;
108
105
  destroySandbox(sandboxId: string): Promise<void>;
109
106
  pauseSandbox(sandboxId: string): Promise<void>;
110
107
  snapshotSandbox(sandboxId: string): Promise<SandboxSnapshot>;
@@ -119,8 +116,8 @@ interface SandboxOps<TOptions extends SandboxCreateOptions = SandboxCreateOption
119
116
  * // → { inMemoryCreateSandbox, inMemoryDestroySandbox, inMemorySnapshotSandbox }
120
117
  * ```
121
118
  */
122
- type PrefixedSandboxOps<TPrefix extends string, TOptions extends SandboxCreateOptions = SandboxCreateOptions> = {
123
- [K in keyof SandboxOps<TOptions> as `${TPrefix}${Capitalize<K & string>}`]: SandboxOps<TOptions>[K];
119
+ type PrefixedSandboxOps<TPrefix extends string, TOptions extends SandboxCreateOptions = SandboxCreateOptions, TCtx = unknown> = {
120
+ [K in keyof SandboxOps<TOptions, TCtx> as `${TPrefix}${Capitalize<K & string>}`]: SandboxOps<TOptions, TCtx>[K];
124
121
  };
125
122
 
126
123
  declare class SandboxNotSupportedError extends ApplicationFailure {
@@ -86,8 +86,6 @@ interface SandboxCreateOptions {
86
86
  }
87
87
  interface SandboxCreateResult {
88
88
  sandbox: Sandbox;
89
- /** Optional state to merge into the workflow's `AgentState` via the session. */
90
- stateUpdate?: Record<string, unknown>;
91
89
  }
92
90
  interface SandboxProvider<TOptions extends SandboxCreateOptions = SandboxCreateOptions, TSandbox extends Sandbox = Sandbox> {
93
91
  readonly id: string;
@@ -100,11 +98,10 @@ interface SandboxProvider<TOptions extends SandboxCreateOptions = SandboxCreateO
100
98
  restore(snapshot: SandboxSnapshot): Promise<Sandbox>;
101
99
  fork(sandboxId: string): Promise<Sandbox>;
102
100
  }
103
- interface SandboxOps<TOptions extends SandboxCreateOptions = SandboxCreateOptions> {
104
- createSandbox(options?: TOptions): Promise<{
101
+ interface SandboxOps<TOptions extends SandboxCreateOptions = SandboxCreateOptions, TCtx = unknown> {
102
+ createSandbox(options?: TOptions, ctx?: TCtx): Promise<{
105
103
  sandboxId: string;
106
- stateUpdate?: Record<string, unknown>;
107
- }>;
104
+ } | null>;
108
105
  destroySandbox(sandboxId: string): Promise<void>;
109
106
  pauseSandbox(sandboxId: string): Promise<void>;
110
107
  snapshotSandbox(sandboxId: string): Promise<SandboxSnapshot>;
@@ -119,8 +116,8 @@ interface SandboxOps<TOptions extends SandboxCreateOptions = SandboxCreateOption
119
116
  * // → { inMemoryCreateSandbox, inMemoryDestroySandbox, inMemorySnapshotSandbox }
120
117
  * ```
121
118
  */
122
- type PrefixedSandboxOps<TPrefix extends string, TOptions extends SandboxCreateOptions = SandboxCreateOptions> = {
123
- [K in keyof SandboxOps<TOptions> as `${TPrefix}${Capitalize<K & string>}`]: SandboxOps<TOptions>[K];
119
+ type PrefixedSandboxOps<TPrefix extends string, TOptions extends SandboxCreateOptions = SandboxCreateOptions, TCtx = unknown> = {
120
+ [K in keyof SandboxOps<TOptions, TCtx> as `${TPrefix}${Capitalize<K & string>}`]: SandboxOps<TOptions, TCtx>[K];
124
121
  };
125
122
 
126
123
  declare class SandboxNotSupportedError extends ApplicationFailure {
@@ -1,5 +1,5 @@
1
1
  import Redis from 'ioredis';
2
- import { J as JsonValue } from './types-BkVoEyiH.js';
2
+ import { J as JsonValue } from './types-D90Q5aOh.js';
3
3
 
4
4
  interface ThreadManagerConfig<T> {
5
5
  redis: Redis;
@@ -2,7 +2,7 @@ import { Duration } from '@temporalio/common';
2
2
  import { ActivityFunctionWithOptions, QueryDefinition, ActivityInterfaceFor } from '@temporalio/workflow';
3
3
  import { UpdateDefinition } from '@temporalio/common/lib/interfaces';
4
4
  import { z } from 'zod';
5
- import { a as SandboxFileSystem, F as FileStat, D as DirentEntry, g as SandboxOps } from './types-ChAMwU3q.js';
5
+ import { a as SandboxFileSystem, F as FileStat, D as DirentEntry, g as SandboxOps } from './types-AujBIMMn.js';
6
6
 
7
7
  /**
8
8
  * A tool definition with a name, description, and Zod schema for arguments.
@@ -431,8 +431,8 @@ interface AgentStateManager<TCustom extends JsonSerializable<TCustom>> {
431
431
  get<K extends keyof TCustom>(key: K): TCustom[K];
432
432
  /** Set a custom state value by key */
433
433
  set<K extends keyof TCustom>(key: K, value: TCustom[K]): void;
434
- /** Bulk-merge a partial update into custom state (e.g. from sandbox stateUpdate) */
435
- mergeUpdate(update: Partial<TCustom>): void;
434
+ /** Bulk-merge a partial update into custom state */
435
+ mergeUpdate(update: Partial<AgentState<TCustom>>): void;
436
436
  /** Get full state for query handler */
437
437
  getCurrentState(): AgentState<TCustom>;
438
438
  /** Check if should return from waitForStateChange */
@@ -460,6 +460,135 @@ interface AgentStateManager<TCustom extends JsonSerializable<TCustom>> {
460
460
  };
461
461
  }
462
462
 
463
+ /**
464
+ * Ephemeral virtual filesystem backed by a {@link FileResolver}.
465
+ *
466
+ * Created fresh for each tool invocation from the current workflow file tree.
467
+ * Directory structure is inferred from file paths. All mutations are tracked
468
+ * and can be retrieved via {@link getMutations} after the handler completes.
469
+ */
470
+ declare class VirtualFileSystem<TCtx = unknown, TMeta = FileEntryMetadata> implements SandboxFileSystem {
471
+ private resolver;
472
+ private ctx;
473
+ readonly workspaceBase: string;
474
+ private entries;
475
+ private directories;
476
+ private mutations;
477
+ constructor(tree: FileEntry<TMeta>[], resolver: FileResolver<TCtx, TMeta>, ctx: TCtx, workspaceBase?: string);
478
+ /** Return all mutations accumulated during this invocation. */
479
+ getMutations(): TreeMutation<TMeta>[];
480
+ /** Look up a file entry by virtual path. */
481
+ getEntry(path: string): FileEntry<TMeta> | undefined;
482
+ readFile(path: string): Promise<string>;
483
+ readFileBuffer(path: string): Promise<Uint8Array>;
484
+ exists(path: string): Promise<boolean>;
485
+ stat(path: string): Promise<FileStat>;
486
+ readdir(path: string): Promise<string[]>;
487
+ readdirWithFileTypes(path: string): Promise<DirentEntry[]>;
488
+ writeFile(path: string, content: string | Uint8Array): Promise<void>;
489
+ appendFile(path: string, content: string | Uint8Array): Promise<void>;
490
+ mkdir(_path: string, _options?: {
491
+ recursive?: boolean;
492
+ }): Promise<void>;
493
+ rm(path: string, options?: {
494
+ recursive?: boolean;
495
+ force?: boolean;
496
+ }): Promise<void>;
497
+ cp(src: string, dest: string, _options?: {
498
+ recursive?: boolean;
499
+ }): Promise<void>;
500
+ mv(src: string, dest: string): Promise<void>;
501
+ readlink(_path: string): Promise<string>;
502
+ resolvePath(base: string, path: string): string;
503
+ private addParentDirectories;
504
+ }
505
+
506
+ /** Allowed value types for file-entry metadata. */
507
+ type FileEntryMetadata = Record<string, string | number | boolean | null>;
508
+ /** JSON-serializable metadata for a single file in the virtual tree. */
509
+ interface FileEntry<TMeta = FileEntryMetadata> {
510
+ id: string;
511
+ /** Virtual path, e.g. "/src/index.ts" */
512
+ path: string;
513
+ size: number;
514
+ /** ISO-8601 date string (JSON-safe) */
515
+ mtime: string;
516
+ metadata: TMeta;
517
+ }
518
+ /**
519
+ * Flat list of file entries.
520
+ * Directories are inferred from file paths at runtime.
521
+ */
522
+ type VirtualFileTree<TMeta = FileEntryMetadata> = FileEntry<TMeta>[];
523
+ type TreeMutation<TMeta = FileEntryMetadata> = {
524
+ type: "add";
525
+ entry: FileEntry<TMeta>;
526
+ } | {
527
+ type: "remove";
528
+ path: string;
529
+ } | {
530
+ type: "update";
531
+ path: string;
532
+ entry: Partial<FileEntry<TMeta>>;
533
+ };
534
+ /**
535
+ * Consumer-provided bridge to the existing DB / S3 / CRUD layer.
536
+ *
537
+ * Generic over `TCtx` so every call receives workflow-level context
538
+ * (e.g. `{ projectId: string }`) without the resolver holding state.
539
+ *
540
+ * Generic over `TMeta` so resolved entries carry typed metadata.
541
+ */
542
+ interface FileResolver<TCtx = unknown, TMeta = FileEntryMetadata> {
543
+ resolveEntries(ctx: TCtx): Promise<FileEntry<TMeta>[]>;
544
+ readFile(id: string, ctx: TCtx, metadata: TMeta): Promise<string>;
545
+ readFileBuffer(id: string, ctx: TCtx, metadata: TMeta): Promise<Uint8Array>;
546
+ writeFile(id: string, content: string | Uint8Array, ctx: TCtx, metadata: TMeta): Promise<void>;
547
+ createFile(path: string, content: string | Uint8Array, ctx: TCtx): Promise<FileEntry<TMeta>>;
548
+ deleteFile(id: string, ctx: TCtx, metadata: TMeta): Promise<void>;
549
+ }
550
+ /**
551
+ * Workflow-side operations for the virtual filesystem.
552
+ *
553
+ * Unlike {@link SandboxOps}, this only exposes what is actually needed:
554
+ * resolving the initial file tree from the consumer's data layer.
555
+ */
556
+ interface VirtualFsOps<TCtx = unknown, TMeta = FileEntryMetadata> {
557
+ resolveFileTree(ctx: TCtx): Promise<{
558
+ fileTree: FileEntry<TMeta>[];
559
+ }>;
560
+ }
561
+ /**
562
+ * Maps generic {@link VirtualFsOps} method names to scope-prefixed names.
563
+ *
564
+ * @example
565
+ * ```typescript
566
+ * type Ops = PrefixedVirtualFsOps<"codingAgent">;
567
+ * // → { codingAgentResolveFileTree: ... }
568
+ * ```
569
+ */
570
+ type PrefixedVirtualFsOps<TPrefix extends string, TCtx = unknown, TMeta = FileEntryMetadata> = {
571
+ [K in keyof VirtualFsOps<TCtx, TMeta> as `${TPrefix}${Capitalize<K & string>}`]: VirtualFsOps<TCtx, TMeta>[K];
572
+ };
573
+ /**
574
+ * The portion of workflow `AgentState` that the virtual filesystem reads via
575
+ * {@link queryParentWorkflowState}. Populated automatically by the session
576
+ * when `virtualFs` config is provided.
577
+ */
578
+ interface VirtualFsState<TCtx = unknown, TMeta = FileEntryMetadata> {
579
+ fileTree: FileEntry<TMeta>[];
580
+ ctx: TCtx;
581
+ workspaceBase?: string;
582
+ }
583
+ /**
584
+ * Extended router context injected by {@link withVirtualFs}.
585
+ * Guarantees a live (ephemeral) virtual filesystem built from the workflow
586
+ * file tree.
587
+ */
588
+ interface VirtualFsContext<TCtx = unknown, TMeta = FileEntryMetadata> extends RouterContext {
589
+ virtualFs: VirtualFileSystem<TCtx, TMeta>;
590
+ }
591
+
463
592
  /**
464
593
  * Agent execution status
465
594
  */
@@ -473,6 +602,7 @@ interface BaseAgentState {
473
602
  version: number;
474
603
  turns: number;
475
604
  tasks: Map<string, WorkflowTask>;
605
+ fileTree: FileEntry[];
476
606
  systemPrompt?: string;
477
607
  totalInputTokens: number;
478
608
  totalOutputTokens: number;
@@ -665,7 +795,9 @@ type ThreadInit = {
665
795
  /**
666
796
  * Sandbox initialization strategy.
667
797
  *
668
- * - `"new"` — create a fresh sandbox.
798
+ * - `"new"` — create a fresh sandbox. Optionally pass `ctx` to
799
+ * have the {@link SandboxManager}'s resolver produce creation options
800
+ * (e.g. initial files) from workflow arguments.
669
801
  * - `"continue"` — resume a previously-paused sandbox (this session takes
670
802
  * ownership and the shutdown policy applies on exit).
671
803
  * - `"fork"` — fork from an existing (or paused) sandbox; a new sandbox is
@@ -675,6 +807,7 @@ type ThreadInit = {
675
807
  */
676
808
  type SandboxInit = {
677
809
  mode: "new";
810
+ ctx?: unknown;
678
811
  } | {
679
812
  mode: "continue";
680
813
  sandboxId: string;
@@ -684,7 +817,6 @@ type SandboxInit = {
684
817
  } | {
685
818
  mode: "inherit";
686
819
  sandboxId: string;
687
- stateUpdate?: Record<string, unknown>;
688
820
  };
689
821
  /**
690
822
  * What to do with the sandbox when the session exits.
@@ -891,136 +1023,6 @@ interface SkillProvider {
891
1023
  loadAll(): Promise<Skill[]>;
892
1024
  }
893
1025
 
894
- /**
895
- * Ephemeral virtual filesystem backed by a {@link FileResolver}.
896
- *
897
- * Created fresh for each tool invocation from the current workflow file tree.
898
- * Directory structure is inferred from file paths. All mutations are tracked
899
- * and can be retrieved via {@link getMutations} after the handler completes.
900
- */
901
- declare class VirtualFileSystem<TCtx = unknown, TMeta = FileEntryMetadata> implements SandboxFileSystem {
902
- private resolver;
903
- private ctx;
904
- readonly workspaceBase: string;
905
- private entries;
906
- private directories;
907
- private mutations;
908
- constructor(tree: FileEntry<TMeta>[], resolver: FileResolver<TCtx, TMeta>, ctx: TCtx, workspaceBase?: string);
909
- /** Return all mutations accumulated during this invocation. */
910
- getMutations(): TreeMutation<TMeta>[];
911
- /** Look up a file entry by virtual path. */
912
- getEntry(path: string): FileEntry<TMeta> | undefined;
913
- readFile(path: string): Promise<string>;
914
- readFileBuffer(path: string): Promise<Uint8Array>;
915
- exists(path: string): Promise<boolean>;
916
- stat(path: string): Promise<FileStat>;
917
- readdir(path: string): Promise<string[]>;
918
- readdirWithFileTypes(path: string): Promise<DirentEntry[]>;
919
- writeFile(path: string, content: string | Uint8Array): Promise<void>;
920
- appendFile(path: string, content: string | Uint8Array): Promise<void>;
921
- mkdir(_path: string, _options?: {
922
- recursive?: boolean;
923
- }): Promise<void>;
924
- rm(path: string, options?: {
925
- recursive?: boolean;
926
- force?: boolean;
927
- }): Promise<void>;
928
- cp(src: string, dest: string, _options?: {
929
- recursive?: boolean;
930
- }): Promise<void>;
931
- mv(src: string, dest: string): Promise<void>;
932
- readlink(_path: string): Promise<string>;
933
- resolvePath(base: string, path: string): string;
934
- private addParentDirectories;
935
- }
936
-
937
- /** Allowed value types for file-entry metadata. */
938
- type FileEntryMetadata = Record<string, string | number | boolean | null>;
939
- /** JSON-serializable metadata for a single file in the virtual tree. */
940
- interface FileEntry<TMeta = FileEntryMetadata> {
941
- id: string;
942
- /** Virtual path, e.g. "/src/index.ts" */
943
- path: string;
944
- size: number;
945
- /** ISO-8601 date string (JSON-safe) */
946
- mtime: string;
947
- metadata: TMeta;
948
- }
949
- /**
950
- * Flat list of file entries.
951
- * Directories are inferred from file paths at runtime.
952
- */
953
- type VirtualFileTree<TMeta = FileEntryMetadata> = FileEntry<TMeta>[];
954
- type TreeMutation<TMeta = FileEntryMetadata> = {
955
- type: "add";
956
- entry: FileEntry<TMeta>;
957
- } | {
958
- type: "remove";
959
- path: string;
960
- } | {
961
- type: "update";
962
- path: string;
963
- entry: Partial<FileEntry<TMeta>>;
964
- };
965
- /**
966
- * Consumer-provided bridge to the existing DB / S3 / CRUD layer.
967
- *
968
- * Generic over `TCtx` so every call receives workflow-level context
969
- * (e.g. `{ projectId: string }`) without the resolver holding state.
970
- *
971
- * Generic over `TMeta` so resolved entries carry typed metadata.
972
- */
973
- interface FileResolver<TCtx = unknown, TMeta = FileEntryMetadata> {
974
- resolveEntries(ctx: TCtx): Promise<FileEntry<TMeta>[]>;
975
- readFile(id: string, ctx: TCtx, metadata: TMeta): Promise<string>;
976
- readFileBuffer(id: string, ctx: TCtx, metadata: TMeta): Promise<Uint8Array>;
977
- writeFile(id: string, content: string | Uint8Array, ctx: TCtx, metadata: TMeta): Promise<void>;
978
- createFile(path: string, content: string | Uint8Array, ctx: TCtx): Promise<FileEntry<TMeta>>;
979
- deleteFile(id: string, ctx: TCtx, metadata: TMeta): Promise<void>;
980
- }
981
- /**
982
- * Workflow-side operations for the virtual filesystem.
983
- *
984
- * Unlike {@link SandboxOps}, this only exposes what is actually needed:
985
- * resolving the initial file tree from the consumer's data layer.
986
- */
987
- interface VirtualFsOps<TCtx = unknown, TMeta = FileEntryMetadata> {
988
- resolveFileTree(ctx: TCtx): Promise<{
989
- fileTree: FileEntry<TMeta>[];
990
- stateUpdate?: Record<string, unknown>;
991
- }>;
992
- }
993
- /**
994
- * Maps generic {@link VirtualFsOps} method names to scope-prefixed names.
995
- *
996
- * @example
997
- * ```typescript
998
- * type Ops = PrefixedVirtualFsOps<"codingAgent">;
999
- * // → { codingAgentResolveFileTree: ... }
1000
- * ```
1001
- */
1002
- type PrefixedVirtualFsOps<TPrefix extends string, TCtx = unknown, TMeta = FileEntryMetadata> = {
1003
- [K in keyof VirtualFsOps<TCtx, TMeta> as `${TPrefix}${Capitalize<K & string>}`]: VirtualFsOps<TCtx, TMeta>[K];
1004
- };
1005
- /**
1006
- * The portion of workflow `AgentState` that the virtual filesystem reads via
1007
- * {@link queryParentWorkflowState}. Populated automatically by the session
1008
- * when `virtualFs` config is provided.
1009
- */
1010
- interface VirtualFsState<TCtx = unknown, TMeta = FileEntryMetadata> {
1011
- fileTree: FileEntry<TMeta>[];
1012
- resolverContext: TCtx;
1013
- workspaceBase?: string;
1014
- }
1015
- /**
1016
- * Extended router context injected by {@link withVirtualFs}.
1017
- * Guarantees a live (ephemeral) virtual filesystem built from the workflow
1018
- * file tree.
1019
- */
1020
- interface VirtualFsContext<TCtx = unknown, TMeta = FileEntryMetadata> extends RouterContext {
1021
- virtualFs: VirtualFileSystem<TCtx, TMeta>;
1022
- }
1023
-
1024
1026
  /**
1025
1027
  * Agent response from LLM invocation
1026
1028
  */
@@ -1176,20 +1178,19 @@ interface SessionConfig<T extends ToolMap, M = unknown, TContent = string> {
1176
1178
  * Has no effect when the sandbox is inherited (`sandbox.mode === "inherit"`).
1177
1179
  */
1178
1180
  sandboxShutdown?: SubagentSandboxShutdown;
1181
+ virtualFsOps?: VirtualFsOps;
1179
1182
  /**
1180
1183
  * Virtual filesystem configuration (optional — independent of sandbox).
1181
1184
  *
1182
1185
  * When provided, the session resolves the file tree on start and merges
1183
- * `fileTree`, `resolverContext`, and `workspaceBase` into `AgentState`.
1186
+ * `fileTree`, `ctx`, and `workspaceBase` into `AgentState`.
1184
1187
  * Tool handlers wrapped with `withVirtualFs` can then read this state.
1185
1188
  *
1186
1189
  * Can be used alongside `sandboxOps` for agents that need both a real
1187
1190
  * sandbox (e.g. for execution) and a virtual filesystem.
1188
1191
  */
1189
1192
  virtualFs?: {
1190
- ops: VirtualFsOps;
1191
- resolverContext: unknown;
1192
- workspaceBase?: string;
1193
+ ctx: unknown;
1193
1194
  };
1194
1195
  }
1195
1196
  type SessionResult<M, TState extends JsonSerializable<TState>, HasSandbox extends boolean = boolean> = {
@@ -1,4 +1,4 @@
1
- import { a as SandboxFileSystem, F as FileStat, D as DirentEntry, S as Sandbox, d as SandboxCreateOptions } from './types-ChAMwU3q.js';
1
+ import { a as SandboxFileSystem, F as FileStat, D as DirentEntry, S as Sandbox, d as SandboxCreateOptions } from './types-AujBIMMn.js';
2
2
  import { BedrockAgentCoreClient, BedrockAgentCoreClientConfig } from '@aws-sdk/client-bedrock-agentcore';
3
3
 
4
4
  /**
@@ -1,4 +1,4 @@
1
- import { a as SandboxFileSystem, F as FileStat, D as DirentEntry, S as Sandbox, d as SandboxCreateOptions } from './types-ChAMwU3q.cjs';
1
+ import { a as SandboxFileSystem, F as FileStat, D as DirentEntry, S as Sandbox, d as SandboxCreateOptions } from './types-AujBIMMn.cjs';
2
2
  import { BedrockAgentCoreClient, BedrockAgentCoreClientConfig } from '@aws-sdk/client-bedrock-agentcore';
3
3
 
4
4
  /**