zeitlich 0.2.13 → 0.2.15

package/dist/adapters/sandbox/inmemory/index.js

@@ -0,0 +1,172 @@
+import { InMemoryFs, Bash } from 'just-bash';
+import { ApplicationFailure } from '@temporalio/common';
+import { uuid4 } from '@temporalio/workflow';
+
+// src/adapters/sandbox/inmemory/index.ts
+var SandboxNotFoundError = class extends ApplicationFailure {
+  constructor(sandboxId) {
+    super(`Sandbox not found: ${sandboxId}`, "SandboxNotFoundError", true);
+  }
+};
+var BASE62 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+function getShortId(length = 12) {
+  const hex = uuid4().replace(/-/g, "");
+  let result = "";
+  for (let i = 0; i < length; i++) {
+    const byte = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    result += BASE62[byte % BASE62.length];
+  }
+  return result;
+}
+
+// src/adapters/sandbox/inmemory/index.ts
+function toSandboxFs(fs) {
+  return {
+    readFile: (path) => fs.readFile(path),
+    readFileBuffer: (path) => fs.readFileBuffer(path),
+    writeFile: (path, content) => fs.writeFile(path, content),
+    appendFile: (path, content) => fs.appendFile(path, content),
+    exists: (path) => fs.exists(path),
+    stat: async (path) => {
+      const s = await fs.stat(path);
+      return {
+        isFile: s.isFile,
+        isDirectory: s.isDirectory,
+        isSymbolicLink: s.isSymbolicLink,
+        size: s.size,
+        mtime: s.mtime
+      };
+    },
+    mkdir: (path, opts) => fs.mkdir(path, opts),
+    readdir: (path) => fs.readdir(path),
+    readdirWithFileTypes: async (path) => {
+      if (!fs.readdirWithFileTypes) {
+        const names = await fs.readdir(path);
+        return Promise.all(
+          names.map(async (name) => {
+            const s = await fs.stat(`${path}/${name}`);
+            return {
+              name,
+              isFile: s.isFile,
+              isDirectory: s.isDirectory,
+              isSymbolicLink: s.isSymbolicLink
+            };
+          })
+        );
+      }
+      return fs.readdirWithFileTypes(path);
+    },
+    rm: (path, opts) => fs.rm(path, opts),
+    cp: (src, dest, opts) => fs.cp(src, dest, opts),
+    mv: (src, dest) => fs.mv(src, dest),
+    readlink: (path) => fs.readlink(path),
+    resolvePath: (base, p) => fs.resolvePath(base, p)
+  };
+}
+var InMemorySandboxImpl = class {
+  constructor(id, justBashFs, options) {
+    this.id = id;
+    this.justBashFs = justBashFs;
+    this.fs = toSandboxFs(justBashFs);
+    this.bashOptions = {
+      executionLimits: { maxStringLength: 52428800 },
+      ...options?.bashOptions
+    };
+  }
+  capabilities = {
+    filesystem: true,
+    execution: true,
+    persistence: true
+  };
+  fs;
+  bashOptions;
+  async exec(command, _options) {
+    const bash = new Bash({ ...this.bashOptions, fs: this.justBashFs });
+    const { exitCode, stderr, stdout } = await bash.exec(command);
+    return { exitCode, stdout, stderr };
+  }
+  async destroy() {
+  }
+  /** Expose the underlying IFileSystem for snapshot serialisation */
+  _getJustBashFs() {
+    return this.justBashFs;
+  }
+};
+var InMemorySandboxProvider = class {
+  constructor(defaultOptions) {
+    this.defaultOptions = defaultOptions;
+  }
+  id = "inmemory";
+  capabilities = {
+    filesystem: true,
+    execution: true,
+    persistence: true
+  };
+  sandboxes = /* @__PURE__ */ new Map();
+  async get(id) {
+    const sandbox = this.sandboxes.get(id);
+    if (!sandbox) throw new SandboxNotFoundError(id);
+    return sandbox;
+  }
+  async destroy(id) {
+    const sandbox = this.sandboxes.get(id);
+    if (sandbox) {
+      await sandbox.destroy();
+      this.sandboxes.delete(id);
+    }
+  }
+  async create(options) {
+    const id = options?.id ?? getShortId();
+    const initialFiles = {};
+    if (options?.initialFiles) {
+      for (const [path, content] of Object.entries(options.initialFiles)) {
+        initialFiles[path] = content;
+      }
+    }
+    const fs = new InMemoryFs(initialFiles);
+    const sandbox = new InMemorySandboxImpl(id, fs, this.defaultOptions);
+    this.sandboxes.set(id, sandbox);
+    return { sandbox };
+  }
+  async snapshot(sandboxId) {
+    const sandbox = this.sandboxes.get(sandboxId);
+    if (!sandbox) throw new SandboxNotFoundError(sandboxId);
+    const fs = sandbox._getJustBashFs();
+    const paths = fs.getAllPaths();
+    const files = {};
+    for (const p of paths) {
+      try {
+        const stat = await fs.stat(p);
+        if (stat.isFile) {
+          files[p] = await fs.readFile(p);
+        }
+      } catch {
+      }
+    }
+    return {
+      sandboxId,
+      providerId: this.id,
+      data: { files },
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  async restore(snapshot) {
+    const { files } = snapshot.data;
+    const initialFiles = {};
+    for (const [path, content] of Object.entries(files)) {
+      initialFiles[path] = content;
+    }
+    const fs = new InMemoryFs(initialFiles);
+    const sandbox = new InMemorySandboxImpl(
+      snapshot.sandboxId,
+      fs,
+      this.defaultOptions
+    );
+    this.sandboxes.set(sandbox.id, sandbox);
+    return sandbox;
+  }
+};
+
+export { InMemorySandboxProvider };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/adapters/sandbox/inmemory/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/lib/sandbox/types.ts","../../../../src/lib/thread/id.ts","../../../../src/adapters/sandbox/inmemory/index.ts"],"names":[],"mappings":";;;;;AA+JO,IAAM,oBAAA,GAAN,cAAmC,kBAAA,CAAmB;AAAA,EAC3D,YAAY,SAAA,EAAmB;AAC7B,IAAA,KAAA,CAAM,CAAA,mBAAA,EAAsB,SAAS,CAAA,CAAA,EAAI,sBAAA,EAAwB,IAAI,CAAA;AAAA,EACvE;AACF,CAAA;ACjKA,IAAM,MAAA,GACJ,gEAAA;AAaK,SAAS,UAAA,CAAW,SAAS,EAAA,EAAY;AAC9C,EAAA,MAAM,GAAA,GAAM,KAAA,EAAM,CAAE,OAAA,CAAQ,MAAM,EAAE,CAAA;AACpC,EAAA,IAAI,MAAA,GAAS,EAAA;AACb,EAAA,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,MAAA,EAAQ,CAAA,EAAA,EAAK;AAC/B,IAAA,MAAM,IAAA,GAAO,QAAA,CAAS,GAAA,CAAI,KAAA,CAAM,CAAA,GAAI,GAAG,CAAA,GAAI,CAAA,GAAI,CAAC,CAAA,EAAG,EAAE,CAAA;AACrD,IAAA,MAAA,IAAU,MAAA,CAAO,IAAA,GAAO,MAAA,CAAO,MAAM,CAAA;AAAA,EACvC;AACA,EAAA,OAAO,MAAA;AACT;;;ACGA,SAAS,YAAY,EAAA,EAAoC;AACvD,EAAA,OAAO;AAAA,IACL,QAAA,EAAU,CAAC,IAAA,KAAS,EAAA,CAAG,SAAS,IAAI,CAAA;AAAA,IACpC,cAAA,EAAgB,CAAC,IAAA,KAAS,EAAA,CAAG,eAAe,IAAI,CAAA;AAAA,IAChD,WAAW,CAAC,IAAA,EAAM,YAAY,EAAA,CAAG,SAAA,CAAU,MAAM,OAAO,CAAA;AAAA,IACxD,YAAY,CAAC,IAAA,EAAM,YAAY,EAAA,CAAG,UAAA,CAAW,MAAM,OAAO,CAAA;AAAA,IAC1D,MAAA,EAAQ,CAAC,IAAA,KAAS,EAAA,CAAG,OAAO,IAAI,CAAA;AAAA,IAChC,IAAA,EAAM,OAAO,IAAA,KAA4B;AACvC,MAAA,MAAM,CAAA,GAAI,MAAM,EAAA,CAAG,IAAA,CAAK,IAAI,CAAA;AAC5B,MAAA,OAAO;AAAA,QACL,QAAQ,CAAA,CAAE,MAAA;AAAA,QACV,aAAa,CAAA,CAAE,WAAA;AAAA,QACf,gBAAgB,CAAA,CAAE,cAAA;AAAA,QAClB,MAAM,CAAA,CAAE,IAAA;AAAA,QACR,OAAO,CAAA,CAAE;AAAA,OACX;AAAA,IACF,CAAA;AAAA,IACA,OAAO,CAAC,IAAA,EAAM,SAAS,EAAA,CAAG,KAAA,CAAM,MAAM,IAAI,CAAA;AAAA,IAC1C,OAAA,EAAS,CAAC,IAAA,KAAS,EAAA,CAAG,QAAQ,IAAI,CAAA;AAAA,IAClC,oBAAA,EAAsB,OAAO,IAAA,KAAiC;AAC5D,MAAA,IAAI,CAAC,GAAG,oBAAA,EAAsB;AAC5B,QAAA,MAAM,KAAA,GAAQ,MAAM,EAAA,CAAG,OAAA,CAAQ,IAAI,CAAA;AACnC,QAAA,OAAO,OAAA,CAAQ,GAAA;AAAA,UACb,KAAA,CAAM,GAAA,CAAI,OAAO,IAAA,KAAS;AACxB,YAAA,MAAM,CAAA,GAAI,MAAM,EAAA,CAAG,IAAA,CAAK,GAAG,IAAI,CAAA,CAAA,EAAI,IAAI,CAAA,CAAE,CAAA;AACzC,YAAA,OAAO;AAAA,cACL,IAAA;AAAA,cACA,QAAQ,CAAA,CAAE,MAAA;AAAA,cACV,aAAa,CAAA,CAAE,WAAA;AAAA,cACf,gBAAgB,CAAA,CAAE;AAAA,aACpB;AAAA,UACF,CAAC;AAAA,SACH;AAAA,MACF;AACA,MAAA,OAAO,EAAA,CAAG,qBAAqB,IAAI,CAAA;AAAA,IACrC,CAAA;AAAA,IACA,IAAI,CAAC,IAAA,EAAM,SAAS,EAAA,CAAG,EAAA,CAAG,MAAM,IAAI,CAAA;AAAA,IACpC,EAAA,EAAI,CAAC,GAAA,EAAK,IAAA,EAAM,SAAS,EAAA,CAAG,EAAA,CAAG,GAAA,EAAK,IAAA,EAAM,IAAI,CAAA;AAAA,IAC9C,IAAI,CAAC,GAAA,EAAK,SAAS,EAAA,CAAG,EAAA,CAAG,KAAK,IAAI,CAAA;AAAA,IAClC,QAAA,EAAU,CAAC,IAAA,KAAS,EAAA,CAAG,SAAS,IAAI,CAAA;AAAA,IACpC,aAAa,CAAC,IAAA,EAAM,MAAM,EAAA,CAAG,WAAA,CAAY,MAAM,CAAC;AAAA,GAClD;AACF;AAgBA,IAAM,sBAAN,MAA6C;AAAA,EAU3C,WAAA,CACW,EAAA,EACD,UAAA,EACR,OAAA,EACA;AAHS,IAAA,IAAA,CAAA,EAAA,GAAA,EAAA;AACD,IAAA,IAAA,CAAA,UAAA,GAAA,UAAA;AAGR,IAAA,IAAA,CAAK,EAAA,GAAK,YAAY,UAAU,CAAA;AAChC,IAAA,IAAA,CAAK,WAAA,GAAc;AAAA,MACjB,eAAA,EAAiB,EAAE,eAAA,EAAiB,QAAA,EAAW;AAAA,MAC/C,GAAG,OAAA,EAAS;AAAA,KACd;AAAA,EACF;AAAA,EAnBS,YAAA,GAAoC;AAAA,IAC3C,UAAA,EAAY,IAAA;AAAA,IACZ,SAAA,EAAW,IAAA;AAAA,IACX,WAAA,EAAa;AAAA,GACf;AAAA,EAES,EAAA;AAAA,EACD,WAAA;AAAA,EAcR,MAAM,IAAA,CAAK,OAAA,EAAiB,QAAA,EAA6C;AACvE,IAAA,MAAM,IAAA,GAAO,IAAI,IAAA,CAAK,EAAE,GAAG,KAAK,WAAA,EAAa,EAAA,EAAI,IAAA,CAAK,UAAA,EAAY,CAAA;AAClE,IAAA,MAAM,EAAE,UAAU,MAAA,EAAQ,MAAA,KAAW,MAAM,IAAA,CAAK,KAAK,OAAO,CAAA;AAC5D,IAAA,OAAO,EAAE,QAAA,EAAU,MAAA,EAAQ,MAAA,EAAO;AAAA,EACpC;AAAA,EAEA,MAAM,OAAA,GAAyB;AAAA,EAE/B;AAAA;AAAA,EAGA,cAAA,GAA8B;AAC5B,IAAA,OAAO,IAAA,CAAK,UAAA;AAAA,EACd;AACF,CAAA;AAMO,IAAM,0BAAN,MAAyD;AAAA,EAU9D,YAAoB,cAAA,EAAyC;AAAzC,IAAA,IAAA,CAAA,cAAA,GAAA,cAAA;AAAA,EAA0C;AAAA,EATrD,EAAA,GAAK,UAAA;AAAA,EACL,YAAA,GAAoC;AAAA,IAC3C,UAAA,EAAY,IAAA;AAAA,IACZ,SAAA,EAAW,IAAA;AAAA,IACX,WAAA,EAAa;AAAA,GACf;AAAA,EAEQ,SAAA,uBAAgB,GAAA,EAAiC;AAAA,EAIzD,MAAM,IAAI,EAAA,EAA8B;AACtC,IAAA,MAAM,OAAA,GAAU,IAAA,CAAK,SAAA,CAAU,GAAA,CAAI,EAAE,CAAA;AACrC,IAAA,IAAI,CAAC,OAAA,EAAS,MAAM,IAAI,qBAAqB,EAAE,CAAA;AAC/C,IAAA,OAAO,OAAA;AAAA,EACT;AAAA,EAEA,MAAM,QAAQ,EAAA,EAA2B;AACvC,IAAA,MAAM,OAAA,GAAU,IAAA,CAAK,SAAA,CAAU,GAAA,CAAI,EAAE,CAAA;AACrC,IAAA,IAAI,OAAA,EAAS;AACX,MAAA,MAAM,QAAQ,OAAA,EAAQ;AACtB,MAAA,IAAA,CAAK,SAAA,CAAU,OAAO,EAAE,CAAA;AAAA,IAC1B;AAAA,EACF;AAAA,EAEA,MAAM,OAAO,OAAA,EAA8D;AACzE,IAAA,MAAM,EAAA,GAAK,OAAA,EAAS,EAAA,IAAM,UAAA,EAAW;AACrC,IAAA,MAAM,eAA6B,EAAC;AAEpC,IAAA,IAAI,SAAS,YAAA,EAAc;AACzB,MAAA,KAAA,MAAW,CAAC,MAAM,OAAO,CAAA,IAAK,OAAO,OAAA,CAAQ,OAAA,CAAQ,YAAY,CAAA,EAAG;AAClE,QAAA,YAAA,CAAa,IAAI,CAAA,GAAI,OAAA;AAAA,MACvB;AAAA,IACF;AAEA,IAAA,MAAM,EAAA,GAAK,IAAI,UAAA,CAAW,YAAY,CAAA;AACtC,IAAA,MAAM,UAAU,IAAI,mBAAA,CAAoB,EAAA,EAAI,EAAA,EAAI,KAAK,cAAc,CAAA;AACnE,IAAA,IAAA,CAAK,SAAA,CAAU,GAAA,CAAI,EAAA,EAAI,OAAO,CAAA;AAC9B,IAAA,OAAO,EAAE,OAAA,EAAQ;AAAA,EACnB;AAAA,EAEA,MAAM,SAAS,SAAA,EAA6C;AAC1D,IAAA,MAAM,OAAA,GAAU,IAAA,CAAK,SAAA,CAAU,GAAA,CAAI,SAAS,CAAA;AAC5C,IAAA,IAAI,CAAC,OAAA,EAAS,MAAM,IAAI,qBAAqB,SAAS,CAAA;AAEtD,IAAA,MAAM,EAAA,GAAK,QAAQ,cAAA,EAAe;AAClC,IAAA,MAAM,KAAA,GAAQ,GAAG,WAAA,EAAY;AAC7B,IAAA,MAAM,QAAgC,EAAC;AAEvC,IAAA,KAAA,MAAW,KAAK,KAAA,EAAO;AACrB,MAAA,IAAI;AACF,QAAA,MAAM,IAAA,GAAO,MAAM,EAAA,CAAG,IAAA,CAAK,CAAC,CAAA;AAC5B,QAAA,IAAI,KAAK,MAAA,EAAQ;AACf,UAAA,KAAA,CAAM,CAAC,CAAA,GAAI,MAAM,EAAA,CAAG,SAAS,CAAC,CAAA;AAAA,QAChC;AAAA,MACF,CAAA,CAAA,MAAQ;AAAA,MAER;AAAA,IACF;AAEA,IAAA,OAAO;AAAA,MACL,SAAA;AAAA,MACA,YAAY,IAAA,CAAK,EAAA;AAAA,MACjB,IAAA,EAAM,EAAE,KAAA,EAAM;AAAA,MACd,SAAA,EAAA,iBAAW,IAAI,IAAA,EAAK,EAAE,WAAA;AAAY,KACpC;AAAA,EACF;AAAA,EAEA,MAAM,QAAQ,QAAA,EAA6C;AACzD,IAAA,MAAM,EAAE,KAAA,EAAM,GAAI,QAAA,CAAS,IAAA;AAC3B,IAAA,MAAM,eAA6B,EAAC;AACpC,IAAA,KAAA,MAAW,CAAC,IAAA,EAAM,OAAO,KAAK,MAAA,CAAO,OAAA,CAAQ,KAAK,CAAA,EAAG;AACnD,MAAA,YAAA,CAAa,IAAI,CAAA,GAAI,OAAA;AAAA,IACvB;AAEA,IAAA,MAAM,EAAA,GAAK,IAAI,UAAA,CAAW,YAAY,CAAA;AACtC,IAAA,MAAM,UAAU,IAAI,mBAAA;AAAA,MAClB,QAAA,CAAS,SAAA;AAAA,MACT,EAAA;AAAA,MACA,IAAA,CAAK;AAAA,KACP;AACA,IAAA,IAAA,CAAK,SAAA,CAAU,GAAA,CAAI,OAAA,CAAQ,EAAA,EAAI,OAAO,CAAA;AACtC,IAAA,OAAO,OAAA;AAAA,EACT;AACF","file":"index.js","sourcesContent":["// ============================================================================\n// Sandbox Filesystem\n// ============================================================================\n\nexport interface DirentEntry {\n  name: string;\n  isFile: boolean;\n  isDirectory: boolean;\n  isSymbolicLink: boolean;\n}\n\nexport interface FileStat {\n  isFile: boolean;\n  isDirectory: boolean;\n  isSymbolicLink: boolean;\n  size: number;\n  mtime: Date;\n}\n\n/**\n * Provider-agnostic filesystem interface.\n *\n * Implementations that don't support a method should throw\n * {@link SandboxNotSupportedError}.\n */\nexport interface SandboxFileSystem {\n  readFile(path: string): Promise<string>;\n  readFileBuffer(path: string): Promise<Uint8Array>;\n  writeFile(path: string, content: string | Uint8Array): Promise<void>;\n  appendFile(path: string, content: string | Uint8Array): Promise<void>;\n  exists(path: string): Promise<boolean>;\n  stat(path: string): Promise<FileStat>;\n  mkdir(path: string, options?: { recursive?: boolean }): Promise<void>;\n  readdir(path: string): Promise<string[]>;\n  readdirWithFileTypes(path: string): Promise<DirentEntry[]>;\n  rm(path: string, options?: { recursive?: boolean; force?: boolean }): Promise<void>;\n  cp(src: string, dest: string, options?: { recursive?: boolean }): Promise<void>;\n  mv(src: string, dest: string): Promise<void>;\n  readlink(path: string): Promise<string>;\n  resolvePath(base: string, path: string): string;\n}\n\n// ============================================================================\n// Execution\n// ============================================================================\n\nexport interface ExecOptions {\n  timeout?: number;\n  cwd?: string;\n  env?: Record<string, string>;\n}\n\nexport interface ExecResult {\n  exitCode: number;\n  stdout: string;\n  stderr: string;\n}\n\n// ============================================================================\n// Capabilities\n// ============================================================================\n\nexport interface SandboxCapabilities {\n  /** Sandbox supports filesystem operations */\n  filesystem: boolean;\n  /** Sandbox supports shell/command execution */\n  execution: boolean;\n  /** Sandbox state can be persisted and restored */\n  persistence: boolean;\n}\n\n// ============================================================================\n// Sandbox\n// ============================================================================\n\nexport interface Sandbox {\n  readonly id: string;\n  readonly capabilities: SandboxCapabilities;\n  readonly fs: SandboxFileSystem;\n\n  exec(command: string, options?: ExecOptions): Promise<ExecResult>;\n  destroy(): Promise<void>;\n}\n\n// ============================================================================\n// Snapshots\n// ============================================================================\n\nexport interface SandboxSnapshot {\n  sandboxId: string;\n  providerId: string;\n  /** Provider-specific serialised state */\n  data: unknown;\n  createdAt: string;\n}\n\n// ============================================================================\n// Provider\n// ============================================================================\n\nexport interface SandboxCreateOptions {\n  /** Preferred sandbox ID (provider may ignore) */\n  id?: string;\n  /** Seed the filesystem with these files */\n  initialFiles?: Record<string, string | Uint8Array>;\n  /** Environment variables available inside the sandbox */\n  env?: Record<string, string>;\n}\n\nexport interface SandboxCreateResult {\n  sandbox: Sandbox;\n  /** Optional state to merge into the workflow's `AgentState` via the session. */\n  stateUpdate?: Record<string, unknown>;\n}\n\nexport interface SandboxProvider<\n  TOptions extends SandboxCreateOptions = SandboxCreateOptions,\n  TSandbox extends Sandbox = Sandbox,\n> {\n  readonly id: string;\n  readonly capabilities: SandboxCapabilities;\n\n  create(options?: TOptions): Promise<SandboxCreateResult>;\n  get(sandboxId: string): Promise<TSandbox>;\n  destroy(sandboxId: string): Promise<void>;\n  snapshot(sandboxId: string): Promise<SandboxSnapshot>;\n  restore(snapshot: SandboxSnapshot): Promise<Sandbox>;\n}\n\n// ============================================================================\n// SandboxOps — workflow-side activity interface (like ThreadOps)\n// ============================================================================\n\nexport interface SandboxOps<\n  TOptions extends SandboxCreateOptions = SandboxCreateOptions,\n> {\n  createSandbox(\n    options?: TOptions,\n  ): Promise<{ sandboxId: string; stateUpdate?: Record<string, unknown> }>;\n  destroySandbox(sandboxId: string): Promise<void>;\n  snapshotSandbox(sandboxId: string): Promise<SandboxSnapshot>;\n}\n\n// ============================================================================\n// Errors\n// ============================================================================\n\nimport { ApplicationFailure } from \"@temporalio/common\";\n\nexport class SandboxNotSupportedError extends ApplicationFailure {\n  constructor(operation: string) {\n    super(\n      `Sandbox does not support: ${operation}`,\n      \"SandboxNotSupportedError\",\n      true,\n    );\n  }\n}\n\nexport class SandboxNotFoundError extends ApplicationFailure {\n  constructor(sandboxId: string) {\n    super(`Sandbox not found: ${sandboxId}`, \"SandboxNotFoundError\", true);\n  }\n}\n","import { uuid4 } from \"@temporalio/workflow\";\n\nconst BASE62 =\n  \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\";\n\n/**\n * Generate a compact, workflow-deterministic identifier.\n *\n * Uses Temporal's `uuid4()` internally (seeded by the workflow's RNG),\n * then re-encodes the hex bytes into a base-62 alphabet for a shorter,\n * more token-efficient identifier (~3 tokens vs ~10 for a full UUID).\n *\n * Suitable for thread IDs, child workflow IDs, or any workflow-scoped identifier.\n *\n * @param length - Number of base-62 characters (default 12, ~71 bits of entropy)\n */\nexport function getShortId(length = 12): string {\n  const hex = uuid4().replace(/-/g, \"\");\n  let result = \"\";\n  for (let i = 0; i < length; i++) {\n    const byte = parseInt(hex.slice(i * 2, i * 2 + 2), 16);\n    result += BASE62[byte % BASE62.length];\n  }\n  return result;\n}\n","import {\n  Bash,\n  InMemoryFs,\n  type BashOptions,\n  type IFileSystem,\n  type InitialFiles,\n} from \"just-bash\";\nimport type {\n  Sandbox,\n  SandboxCapabilities,\n  SandboxCreateOptions,\n  SandboxCreateResult,\n  SandboxFileSystem,\n  SandboxProvider,\n  SandboxSnapshot,\n  ExecOptions,\n  ExecResult,\n  DirentEntry,\n  FileStat,\n} from \"../../../lib/sandbox/types\";\nimport { SandboxNotFoundError } from \"../../../lib/sandbox/types\";\nimport { getShortId } from \"../../../lib/thread/id\";\n\n// ============================================================================\n// Adapter: IFileSystem → SandboxFileSystem\n// ============================================================================\n\nfunction toSandboxFs(fs: IFileSystem): SandboxFileSystem {\n  return {\n    readFile: (path) => fs.readFile(path),\n    readFileBuffer: (path) => fs.readFileBuffer(path),\n    writeFile: (path, content) => fs.writeFile(path, content),\n    appendFile: (path, content) => fs.appendFile(path, content),\n    exists: (path) => fs.exists(path),\n    stat: async (path): Promise<FileStat> => {\n      const s = await fs.stat(path);\n      return {\n        isFile: s.isFile,\n        isDirectory: s.isDirectory,\n        isSymbolicLink: s.isSymbolicLink,\n        size: s.size,\n        mtime: s.mtime,\n      };\n    },\n    mkdir: (path, opts) => fs.mkdir(path, opts),\n    readdir: (path) => fs.readdir(path),\n    readdirWithFileTypes: async (path): Promise<DirentEntry[]> => {\n      if (!fs.readdirWithFileTypes) {\n        const names = await fs.readdir(path);\n        return Promise.all(\n          names.map(async (name) => {\n            const s = await fs.stat(`${path}/${name}`);\n            return {\n              name,\n              isFile: s.isFile,\n              isDirectory: s.isDirectory,\n              isSymbolicLink: s.isSymbolicLink,\n            };\n          })\n        );\n      }\n      return fs.readdirWithFileTypes(path);\n    },\n    rm: (path, opts) => fs.rm(path, opts),\n    cp: (src, dest, opts) => fs.cp(src, dest, opts),\n    mv: (src, dest) => fs.mv(src, dest),\n    readlink: (path) => fs.readlink(path),\n    resolvePath: (base, p) => fs.resolvePath(base, p),\n  };\n}\n\n// ============================================================================\n// InMemorySandbox\n// ============================================================================\n\nexport interface InMemorySandboxOptions {\n  /** Options forwarded to `just-bash` `Bash` (minus `fs` which is managed) */\n  bashOptions?: Omit<BashOptions, \"fs\">;\n}\n\n/**\n * An in-memory {@link Sandbox} backed by `just-bash`.\n */\nexport type InMemorySandbox = Sandbox & { fs: SandboxFileSystem };\n\nclass InMemorySandboxImpl implements Sandbox {\n  readonly capabilities: SandboxCapabilities = {\n    filesystem: true,\n    execution: true,\n    persistence: true,\n  };\n\n  readonly fs: SandboxFileSystem;\n  private bashOptions: Omit<BashOptions, \"fs\">;\n\n  constructor(\n    readonly id: string,\n    private justBashFs: IFileSystem,\n    options?: InMemorySandboxOptions\n  ) {\n    this.fs = toSandboxFs(justBashFs);\n    this.bashOptions = {\n      executionLimits: { maxStringLength: 52_428_800 },\n      ...options?.bashOptions,\n    };\n  }\n\n  async exec(command: string, _options?: ExecOptions): Promise<ExecResult> {\n    const bash = new Bash({ ...this.bashOptions, fs: this.justBashFs });\n    const { exitCode, stderr, stdout } = await bash.exec(command);\n    return { exitCode, stdout, stderr };\n  }\n\n  async destroy(): Promise<void> {\n    // In-memory: nothing to clean up\n  }\n\n  /** Expose the underlying IFileSystem for snapshot serialisation */\n  _getJustBashFs(): IFileSystem {\n    return this.justBashFs;\n  }\n}\n\n// ============================================================================\n// InMemorySandboxProvider\n// ============================================================================\n\nexport class InMemorySandboxProvider implements SandboxProvider {\n  readonly id = \"inmemory\";\n  readonly capabilities: SandboxCapabilities = {\n    filesystem: true,\n    execution: true,\n    persistence: true,\n  };\n\n  private sandboxes = new Map<string, InMemorySandboxImpl>();\n\n  constructor(private defaultOptions?: InMemorySandboxOptions) {}\n\n  async get(id: string): Promise<Sandbox> {\n    const sandbox = this.sandboxes.get(id);\n    if (!sandbox) throw new SandboxNotFoundError(id);\n    return sandbox;\n  }\n\n  async destroy(id: string): Promise<void> {\n    const sandbox = this.sandboxes.get(id);\n    if (sandbox) {\n      await sandbox.destroy();\n      this.sandboxes.delete(id);\n    }\n  }\n\n  async create(options?: SandboxCreateOptions): Promise<SandboxCreateResult> {\n    const id = options?.id ?? getShortId();\n    const initialFiles: InitialFiles = {};\n\n    if (options?.initialFiles) {\n      for (const [path, content] of Object.entries(options.initialFiles)) {\n        initialFiles[path] = content;\n      }\n    }\n\n    const fs = new InMemoryFs(initialFiles);\n    const sandbox = new InMemorySandboxImpl(id, fs, this.defaultOptions);\n    this.sandboxes.set(id, sandbox);\n    return { sandbox };\n  }\n\n  async snapshot(sandboxId: string): Promise<SandboxSnapshot> {\n    const sandbox = this.sandboxes.get(sandboxId);\n    if (!sandbox) throw new SandboxNotFoundError(sandboxId);\n\n    const fs = sandbox._getJustBashFs();\n    const paths = fs.getAllPaths();\n    const files: Record<string, string> = {};\n\n    for (const p of paths) {\n      try {\n        const stat = await fs.stat(p);\n        if (stat.isFile) {\n          files[p] = await fs.readFile(p);\n        }\n      } catch {\n        // skip entries that can't be read (e.g. broken symlinks)\n      }\n    }\n\n    return {\n      sandboxId,\n      providerId: this.id,\n      data: { files },\n      createdAt: new Date().toISOString(),\n    };\n  }\n\n  async restore(snapshot: SandboxSnapshot): Promise<Sandbox> {\n    const { files } = snapshot.data as { files: Record<string, string> };\n    const initialFiles: InitialFiles = {};\n    for (const [path, content] of Object.entries(files)) {\n      initialFiles[path] = content;\n    }\n\n    const fs = new InMemoryFs(initialFiles);\n    const sandbox = new InMemorySandboxImpl(\n      snapshot.sandboxId,\n      fs,\n      this.defaultOptions\n    );\n    this.sandboxes.set(sandbox.id, sandbox);\n    return sandbox;\n  }\n}\n"]}

package/dist/adapters/sandbox/virtual/index.cjs

@@ -0,0 +1,405 @@
+'use strict';
+
+var common = require('@temporalio/common');
+var workflow = require('@temporalio/workflow');
+var activity = require('@temporalio/activity');
+
+// src/lib/sandbox/types.ts
+var SandboxNotSupportedError = class extends common.ApplicationFailure {
+  constructor(operation) {
+    super(
+      `Sandbox does not support: ${operation}`,
+      "SandboxNotSupportedError",
+      true
+    );
+  }
+};
+
+// src/adapters/sandbox/virtual/filesystem.ts
+function normalisePath(p) {
+  if (!p.startsWith("/")) p = "/" + p;
+  p = p.replace(/\/+/g, "/");
+  if (p.length > 1 && p.endsWith("/")) p = p.slice(0, -1);
+  return p;
+}
+function parentDir(p) {
+  const idx = p.lastIndexOf("/");
+  return idx <= 0 ? "/" : p.slice(0, idx);
+}
+function inferDirectories(entries) {
+  const dirs = /* @__PURE__ */ new Set();
+  dirs.add("/");
+  for (const entry of entries) {
+    let dir = parentDir(normalisePath(entry.path));
+    while (dir !== "/" && !dirs.has(dir)) {
+      dirs.add(dir);
+      dir = parentDir(dir);
+    }
+    dirs.add("/");
+  }
+  return dirs;
+}
+var VirtualSandboxFileSystem = class {
+  constructor(tree, resolver, ctx) {
+    this.resolver = resolver;
+    this.ctx = ctx;
+    this.entries = new Map(
+      tree.map((e) => [normalisePath(e.path), e])
+    );
+    this.directories = inferDirectories(tree);
+  }
+  entries;
+  directories;
+  mutations = [];
+  /** Return all mutations accumulated during this invocation. */
+  getMutations() {
+    return this.mutations;
+  }
+  /** Look up a file entry by virtual path. */
+  getEntry(path) {
+    return this.entries.get(normalisePath(path));
+  }
+  // --------------------------------------------------------------------------
+  // Read operations — delegate to resolver lazily
+  // --------------------------------------------------------------------------
+  async readFile(path) {
+    const entry = this.entries.get(normalisePath(path));
+    if (!entry) throw new Error(`ENOENT: no such file: ${path}`);
+    return this.resolver.readFile(entry.id, this.ctx);
+  }
+  async readFileBuffer(path) {
+    const entry = this.entries.get(normalisePath(path));
+    if (!entry) throw new Error(`ENOENT: no such file: ${path}`);
+    return this.resolver.readFileBuffer(entry.id, this.ctx);
+  }
+  // --------------------------------------------------------------------------
+  // Metadata operations — pure, resolved from the tree
+  // --------------------------------------------------------------------------
+  async exists(path) {
+    const norm = normalisePath(path);
+    return this.entries.has(norm) || this.directories.has(norm);
+  }
+  async stat(path) {
+    const norm = normalisePath(path);
+    const entry = this.entries.get(norm);
+    if (entry) {
+      return {
+        isFile: true,
+        isDirectory: false,
+        isSymbolicLink: false,
+        size: entry.size,
+        mtime: new Date(entry.mtime)
+      };
+    }
+    if (this.directories.has(norm)) {
+      return {
+        isFile: false,
+        isDirectory: true,
+        isSymbolicLink: false,
+        size: 0,
+        mtime: /* @__PURE__ */ new Date()
+      };
+    }
+    throw new Error(`ENOENT: no such file or directory: ${path}`);
+  }
+  async readdir(path) {
+    const norm = normalisePath(path);
+    if (!this.directories.has(norm)) {
+      throw new Error(`ENOENT: no such directory: ${path}`);
+    }
+    const prefix = norm === "/" ? "/" : norm + "/";
+    const names = /* @__PURE__ */ new Set();
+    for (const p of this.entries.keys()) {
+      if (p.startsWith(prefix)) {
+        const rest = p.slice(prefix.length);
+        const seg = rest.split("/")[0];
+        if (seg) names.add(seg);
+      }
+    }
+    for (const d of this.directories) {
+      if (d.startsWith(prefix) && d !== norm) {
+        const rest = d.slice(prefix.length);
+        const seg = rest.split("/")[0];
+        if (seg) names.add(seg);
+      }
+    }
+    return [...names].sort();
+  }
+  async readdirWithFileTypes(path) {
+    const names = await this.readdir(path);
+    const norm = normalisePath(path);
+    const prefix = norm === "/" ? "/" : norm + "/";
+    return names.map((name) => {
+      const full = prefix + name;
+      const isFile = this.entries.has(full);
+      const isDirectory = this.directories.has(full);
+      return { name, isFile, isDirectory, isSymbolicLink: false };
+    });
+  }
+  // --------------------------------------------------------------------------
+  // Write operations — delegate to resolver, record mutations
+  // --------------------------------------------------------------------------
+  async writeFile(path, content) {
+    const norm = normalisePath(path);
+    const existing = this.entries.get(norm);
+    if (existing) {
+      await this.resolver.writeFile(existing.id, content, this.ctx);
+      const size = typeof content === "string" ? new TextEncoder().encode(content).byteLength : content.byteLength;
+      const updated = {
+        ...existing,
+        size,
+        mtime: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      this.entries.set(norm, updated);
+      this.mutations.push({ type: "update", path: norm, entry: updated });
+    } else {
+      const entry = await this.resolver.createFile(norm, content, this.ctx);
+      const normalised = { ...entry, path: norm };
+      this.entries.set(norm, normalised);
+      this.addParentDirectories(norm);
+      this.mutations.push({ type: "add", entry: normalised });
+    }
+  }
+  async appendFile(path, content) {
+    const norm = normalisePath(path);
+    const existing = this.entries.get(norm);
+    if (!existing) {
+      return this.writeFile(path, content);
+    }
+    const current = await this.resolver.readFile(existing.id, this.ctx);
+    const appended = typeof content === "string" ? current + content : current + new TextDecoder().decode(content);
+    await this.resolver.writeFile(existing.id, appended, this.ctx);
+    const size = new TextEncoder().encode(appended).byteLength;
+    const updated = {
+      ...existing,
+      size,
+      mtime: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.entries.set(norm, updated);
+    this.mutations.push({ type: "update", path: norm, entry: updated });
+  }
+  async mkdir(_path, _options) {
+    const norm = normalisePath(_path);
+    if (this.directories.has(norm)) return;
+    if (_options?.recursive) {
+      this.addParentDirectories(norm + "/placeholder");
+      this.directories.add(norm);
+    } else {
+      const parent = parentDir(norm);
+      if (!this.directories.has(parent)) {
+        throw new Error(`ENOENT: no such directory: ${parent}`);
+      }
+      this.directories.add(norm);
+    }
+  }
+  async rm(path, options) {
+    const norm = normalisePath(path);
+    const entry = this.entries.get(norm);
+    if (entry) {
+      await this.resolver.deleteFile(entry.id, this.ctx);
+      this.entries.delete(norm);
+      this.mutations.push({ type: "remove", path: norm });
+      return;
+    }
+    if (this.directories.has(norm)) {
+      if (!options?.recursive) {
+        throw new Error(`EISDIR: is a directory (use recursive): ${path}`);
+      }
+      const prefix = norm === "/" ? "/" : norm + "/";
+      for (const [p, e] of this.entries) {
+        if (p.startsWith(prefix)) {
+          await this.resolver.deleteFile(e.id, this.ctx);
+          this.entries.delete(p);
+          this.mutations.push({ type: "remove", path: p });
+        }
+      }
+      for (const d of this.directories) {
+        if (d.startsWith(prefix)) this.directories.delete(d);
+      }
+      this.directories.delete(norm);
+      return;
+    }
+    if (!options?.force) {
+      throw new Error(`ENOENT: no such file or directory: ${path}`);
+    }
+  }
+  async cp(src, dest, _options) {
+    const normSrc = normalisePath(src);
+    const normDest = normalisePath(dest);
+    const entry = this.entries.get(normSrc);
+    if (entry) {
+      const content = await this.resolver.readFile(entry.id, this.ctx);
+      await this.writeFile(normDest, content);
+      return;
+    }
+    if (!this.directories.has(normSrc)) {
+      throw new Error(`ENOENT: no such file or directory: ${src}`);
+    }
+    if (!_options?.recursive) {
+      throw new Error(`EISDIR: is a directory (use recursive): ${src}`);
+    }
+    const prefix = normSrc === "/" ? "/" : normSrc + "/";
+    for (const [p, e] of this.entries) {
+      if (p.startsWith(prefix)) {
+        const relative = p.slice(normSrc.length);
+        const content = await this.resolver.readFile(e.id, this.ctx);
+        await this.writeFile(normDest + relative, content);
+      }
+    }
+  }
+  async mv(src, dest) {
+    await this.cp(src, dest, { recursive: true });
+    await this.rm(src, { recursive: true });
+  }
+  // --------------------------------------------------------------------------
+  // Unsupported
+  // --------------------------------------------------------------------------
+  async readlink(_path) {
+    throw new SandboxNotSupportedError("readlink");
+  }
+  resolvePath(base, path) {
+    if (path.startsWith("/")) return normalisePath(path);
+    const combined = base.endsWith("/") ? base + path : base + "/" + path;
+    return normalisePath(combined);
+  }
+  // --------------------------------------------------------------------------
+  // Helpers
+  // --------------------------------------------------------------------------
+  addParentDirectories(filePath) {
+    let dir = parentDir(normalisePath(filePath));
+    while (!this.directories.has(dir)) {
+      this.directories.add(dir);
+      dir = parentDir(dir);
+    }
+  }
+};
+var BASE62 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+function getShortId(length = 12) {
+  const hex = workflow.uuid4().replace(/-/g, "");
+  let result = "";
+  for (let i = 0; i < length; i++) {
+    const byte = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    result += BASE62[byte % BASE62.length];
+  }
+  return result;
+}
+
+// src/adapters/sandbox/virtual/provider.ts
+var VirtualSandboxProvider = class {
+  id = "virtual";
+  capabilities = {
+    filesystem: true,
+    execution: false,
+    persistence: true
+  };
+  resolver;
+  constructor(resolver) {
+    this.resolver = resolver;
+  }
+  async create(options) {
+    if (!options || !("resolverContext" in options)) {
+      throw new Error("VirtualSandboxProvider.create requires resolverContext");
+    }
+    const sandboxId = options.id ?? getShortId();
+    const fileTree = await this.resolver.resolveEntries(
+      options.resolverContext
+    );
+    const sandbox = createVirtualSandbox(
+      sandboxId,
+      fileTree,
+      this.resolver,
+      options.resolverContext
+    );
+    return {
+      sandbox,
+      stateUpdate: {
+        sandboxId,
+        fileTree,
+        resolverContext: options.resolverContext
+      }
+    };
+  }
+  async get() {
+    throw new SandboxNotSupportedError(
+      "get (virtual sandbox state lives in workflow AgentState)"
+    );
+  }
+  async destroy() {
+  }
+  async snapshot() {
+    throw new SandboxNotSupportedError(
+      "snapshot (virtual sandbox state lives in workflow AgentState)"
+    );
+  }
+  async restore() {
+    throw new SandboxNotSupportedError(
+      "restore (virtual sandbox state lives in workflow AgentState)"
+    );
+  }
+};
+async function queryParentWorkflowState(client) {
+  const { workflowExecution } = activity.Context.current().info;
+  const handle = client.getHandle(
+    workflowExecution.workflowId,
+    workflowExecution.runId
+  );
+  return handle.query("getAgentState");
+}
+
+// src/adapters/sandbox/virtual/with-virtual-sandbox.ts
+function withVirtualSandbox(client, provider, handler) {
+  return async (args, context) => {
+    const state = await queryParentWorkflowState(client);
+    const { sandboxId, fileTree, resolverContext } = state;
+    if (!fileTree || !sandboxId) {
+      return {
+        toolResponse: `Error: No fileTree/sandboxId in agent state. The ${context.toolName} tool requires a virtual sandbox.`,
+        data: null
+      };
+    }
+    const sandbox = createVirtualSandbox(
+      sandboxId,
+      fileTree,
+      provider.resolver,
+      resolverContext
+    );
+    const response = await handler(args, { ...context, sandbox });
+    const mutations = sandbox.fs.getMutations();
+    return {
+      toolResponse: response.toolResponse,
+      data: {
+        ...response.data ?? {},
+        treeMutations: mutations
+      }
+    };
+  };
+}
+
+// src/adapters/sandbox/virtual/index.ts
+var VirtualSandboxImpl = class {
+  constructor(id, tree, resolver, ctx) {
+    this.id = id;
+    this.fs = new VirtualSandboxFileSystem(tree, resolver, ctx);
+  }
+  capabilities = {
+    filesystem: true,
+    execution: false,
+    persistence: true
+  };
+  fs;
+  async exec(_command, _options) {
+    throw new SandboxNotSupportedError("exec");
+  }
+  async destroy() {
+  }
+};
+function createVirtualSandbox(id, tree, resolver, ctx) {
+  return new VirtualSandboxImpl(id, tree, resolver, ctx);
+}
+
+exports.VirtualSandboxFileSystem = VirtualSandboxFileSystem;
+exports.VirtualSandboxProvider = VirtualSandboxProvider;
+exports.createVirtualSandbox = createVirtualSandbox;
+exports.withVirtualSandbox = withVirtualSandbox;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map