zeitlich 0.2.22 → 0.2.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeitlich",
-  "version": "0.2.22",
+  "version": "0.2.24",
   "description": "[EXPERIMENTAL] An opinionated AI agent implementation for Temporal",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -126,6 +126,26 @@
         "types": "./dist/adapters/sandbox/daytona/workflow.d.ts",
         "default": "./dist/adapters/sandbox/daytona/workflow.js"
       }
+    },
+    "./adapters/sandbox/bedrock": {
+      "import": {
+        "types": "./dist/adapters/sandbox/bedrock/index.d.ts",
+        "default": "./dist/adapters/sandbox/bedrock/index.js"
+      },
+      "require": {
+        "types": "./dist/adapters/sandbox/bedrock/index.d.ts",
+        "default": "./dist/adapters/sandbox/bedrock/index.js"
+      }
+    },
+    "./adapters/sandbox/bedrock/workflow": {
+      "import": {
+        "types": "./dist/adapters/sandbox/bedrock/workflow.d.ts",
+        "default": "./dist/adapters/sandbox/bedrock/workflow.js"
+      },
+      "require": {
+        "types": "./dist/adapters/sandbox/bedrock/workflow.d.ts",
+        "default": "./dist/adapters/sandbox/bedrock/workflow.js"
+      }
     }
   },
   "files": [
@@ -170,6 +190,7 @@
     "node": ">=18"
   },
   "devDependencies": {
+    "@aws-sdk/client-bedrock-agentcore": "^3.900.0",
     "@daytonaio/sdk": "^0.149.0",
     "@e2b/code-interpreter": "^2.3.3",
     "@eslint/js": "^10.0.1",
@@ -189,7 +210,8 @@
     "vitest": "^4.0.18"
   },
   "peerDependencies": {
-    "@daytonaio/sdk": ">=0.100.0",
+    "@aws-sdk/client-bedrock-agentcore": "^3.900.0",
+    "@daytonaio/sdk": ">=0.153.0",
     "@e2b/code-interpreter": "^2.3.3",
     "@google/genai": "^1.43.0",
     "@langchain/core": ">=1.0.0",
@@ -197,6 +219,9 @@
     "just-bash": ">=2.0.0"
   },
   "peerDependenciesMeta": {
+    "@aws-sdk/client-bedrock-agentcore": {
+      "optional": true
+    },
     "@daytonaio/sdk": {
       "optional": true
     },

package/src/adapters/sandbox/bedrock/filesystem.ts

@@ -0,0 +1,313 @@
+import type {
+  BedrockAgentCoreClient,
+  CodeInterpreterStreamOutput,
+  CodeInterpreterResult,
+  ToolName as ToolNameType,
+  ToolArguments,
+} from "@aws-sdk/client-bedrock-agentcore";
+import { InvokeCodeInterpreterCommand } from "@aws-sdk/client-bedrock-agentcore";
+import type {
+  SandboxFileSystem,
+  DirentEntry,
+  FileStat,
+} from "../../../lib/sandbox/types";
+import { SandboxNotSupportedError } from "../../../lib/sandbox/types";
+import { posix } from "node:path";
+
+async function consumeStream(
+  stream: AsyncIterable<CodeInterpreterStreamOutput>
+): Promise<CodeInterpreterResult> {
+  for await (const event of stream) {
+    if ("result" in event && event.result) return event.result;
+    if ("accessDeniedException" in event && event.accessDeniedException)
+      throw new Error(event.accessDeniedException.message ?? "Access denied");
+    if ("resourceNotFoundException" in event && event.resourceNotFoundException)
+      throw new Error(
+        event.resourceNotFoundException.message ?? "Resource not found"
+      );
+    if ("validationException" in event && event.validationException)
+      throw new Error(
+        event.validationException.message ?? "Validation error"
+      );
+    if ("internalServerException" in event && event.internalServerException)
+      throw new Error(
+        event.internalServerException.message ?? "Internal server error"
+      );
+    if ("throttlingException" in event && event.throttlingException)
+      throw new Error(event.throttlingException.message ?? "Throttled");
+    if (
+      "serviceQuotaExceededException" in event &&
+      event.serviceQuotaExceededException
+    )
+      throw new Error(
+        event.serviceQuotaExceededException.message ?? "Quota exceeded"
+      );
+    if ("conflictException" in event && event.conflictException)
+      throw new Error(event.conflictException.message ?? "Conflict");
+  }
+  throw new Error("No result received from code interpreter stream");
+}
+
+/**
+ * {@link SandboxFileSystem} backed by AWS Bedrock AgentCore Code Interpreter.
+ *
+ * Maps zeitlich's filesystem interface to Code Interpreter's
+ * `readFiles` / `writeFiles` / `listFiles` / `removeFiles` / `executeCommand`
+ * tool invocations.
+ */
+export class BedrockSandboxFileSystem implements SandboxFileSystem {
+  readonly workspaceBase: string;
+
+  constructor(
+    private client: BedrockAgentCoreClient,
+    private codeInterpreterIdentifier: string,
+    private sessionId: string,
+    workspaceBase = "/home/user"
+  ) {
+    this.workspaceBase = posix.resolve("/", workspaceBase);
+  }
+
+  private normalisePath(path: string): string {
+    return posix.resolve(this.workspaceBase, path);
+  }
+
+  private async invoke(
+    name: ToolNameType,
+    args: ToolArguments
+  ): Promise<CodeInterpreterResult> {
+    const resp = await this.client.send(
+      new InvokeCodeInterpreterCommand({
+        codeInterpreterIdentifier: this.codeInterpreterIdentifier,
+        sessionId: this.sessionId,
+        name,
+        arguments: args,
+      })
+    );
+    if (!resp.stream) throw new Error("No stream in code interpreter response");
+    return consumeStream(resp.stream);
+  }
+
+  private async execShell(command: string): Promise<{
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+  }> {
+    const result = await this.invoke("executeCommand" as ToolNameType, {
+      command,
+    });
+    return {
+      stdout: result.structuredContent?.stdout ?? "",
+      stderr: result.structuredContent?.stderr ?? "",
+      exitCode: result.structuredContent?.exitCode ?? 0,
+    };
+  }
+
+  async readFile(path: string): Promise<string> {
+    const norm = this.normalisePath(path);
+    const result = await this.invoke("readFiles" as ToolNameType, {
+      paths: [norm],
+    });
+
+    for (const block of result.content ?? []) {
+      if (block.resource?.text != null) return block.resource.text;
+      if (block.text != null) return block.text;
+    }
+    return "";
+  }
+
+  async readFileBuffer(path: string): Promise<Uint8Array> {
+    const norm = this.normalisePath(path);
+    const result = await this.invoke("readFiles" as ToolNameType, {
+      paths: [norm],
+    });
+
+    for (const block of result.content ?? []) {
+      if (block.resource?.blob) return block.resource.blob;
+      if (block.data) return block.data;
+      if (block.resource?.text != null)
+        return new TextEncoder().encode(block.resource.text);
+      if (block.text != null) return new TextEncoder().encode(block.text);
+    }
+    return new Uint8Array(0);
+  }
+
+  async writeFile(path: string, content: string | Uint8Array): Promise<void> {
+    const norm = this.normalisePath(path);
+    const isText = typeof content === "string";
+    const result = await this.invoke("writeFiles" as ToolNameType, {
+      content: [
+        {
+          path: norm,
+          ...(isText
+            ? { text: content as string }
+            : { blob: content as Uint8Array }),
+        },
+      ],
+    });
+    if (result.isError) {
+      const msg =
+        result.content?.map((b) => b.text).join("") ?? "writeFile failed";
+      throw new Error(msg);
+    }
+  }
+
+  async appendFile(path: string, content: string | Uint8Array): Promise<void> {
+    const norm = this.normalisePath(path);
+    const addition =
+      typeof content === "string"
+        ? content
+        : new TextDecoder().decode(content);
+    const escaped = addition.replace(/'/g, "'\\''");
+    const { exitCode, stderr } = await this.execShell(
+      `printf '%s' '${escaped}' >> "${norm}"`
+    );
+    if (exitCode !== 0) throw new Error(`appendFile failed: ${stderr}`);
+  }
+
+  async exists(path: string): Promise<boolean> {
+    const norm = this.normalisePath(path);
+    const { exitCode } = await this.execShell(`test -e "${norm}"`);
+    return exitCode === 0;
+  }
+
+  async stat(path: string): Promise<FileStat> {
+    const norm = this.normalisePath(path);
+    const { stdout, exitCode, stderr } = await this.execShell(
+      `stat -c '%F %s %Y' "${norm}" 2>&1`
+    );
+    if (exitCode !== 0) throw new Error(`stat failed: ${stderr || stdout}`);
+
+    const parts = stdout.trim().split(" ");
+    const fileType = parts.slice(0, -2).join(" ");
+    const sizeStr = parts[parts.length - 2] ?? "0";
+    const mtimeStr = parts[parts.length - 1] ?? "0";
+    const size = parseInt(sizeStr, 10);
+    const mtimeEpoch = parseInt(mtimeStr, 10);
+
+    return {
+      isFile: fileType === "regular file" || fileType === "regular empty file",
+      isDirectory: fileType === "directory",
+      isSymbolicLink: fileType === "symbolic link",
+      size: isNaN(size) ? 0 : size,
+      mtime: new Date(isNaN(mtimeEpoch) ? 0 : mtimeEpoch * 1000),
+    };
+  }
+
+  async mkdir(path: string, options?: { recursive?: boolean }): Promise<void> {
+    const norm = this.normalisePath(path);
+    const flag = options?.recursive ? "-p " : "";
+    const { exitCode, stderr } = await this.execShell(
+      `mkdir ${flag}"${norm}"`
+    );
+    if (exitCode !== 0) throw new Error(`mkdir failed: ${stderr}`);
+  }
+
+  async readdir(path: string): Promise<string[]> {
+    const norm = this.normalisePath(path);
+    const result = await this.invoke("listFiles" as ToolNameType, {
+      directoryPath: norm,
+    });
+
+    const names: string[] = [];
+    for (const block of result.content ?? []) {
+      if (block.name) names.push(block.name);
+    }
+
+    if (names.length > 0) return names;
+
+    const { stdout, exitCode, stderr } = await this.execShell(
+      `ls -1A "${norm}"`
+    );
+    if (exitCode !== 0) throw new Error(`readdir failed: ${stderr}`);
+    return stdout
+      .trim()
+      .split("\n")
+      .filter((l) => l.length > 0);
+  }
+
+  async readdirWithFileTypes(path: string): Promise<DirentEntry[]> {
+    const norm = this.normalisePath(path);
+    const { stdout, exitCode, stderr } = await this.execShell(
+      `find "${norm}" -maxdepth 1 -mindepth 1 -printf '%y %f\\n'`
+    );
+    if (exitCode !== 0)
+      throw new Error(`readdirWithFileTypes failed: ${stderr}`);
+
+    return stdout
+      .trim()
+      .split("\n")
+      .filter((l) => l.length > 0)
+      .map((line) => {
+        const type = line.charAt(0);
+        const name = line.slice(2);
+        return {
+          name,
+          isFile: type === "f",
+          isDirectory: type === "d",
+          isSymbolicLink: type === "l",
+        };
+      });
+  }
+
+  async rm(
+    path: string,
+    options?: { recursive?: boolean; force?: boolean }
+  ): Promise<void> {
+    const norm = this.normalisePath(path);
+    if (options?.recursive || options?.force) {
+      const flags = `${options?.recursive ? "-r" : ""} ${options?.force ? "-f" : ""}`.trim();
+      const { exitCode, stderr } = await this.execShell(
+        `rm ${flags} "${norm}"`
+      );
+      if (exitCode !== 0 && !options?.force)
+        throw new Error(`rm failed: ${stderr}`);
+      return;
+    }
+
+    const result = await this.invoke("removeFiles" as ToolNameType, {
+      paths: [norm],
+    });
+    if (result.isError) {
+      const msg =
+        result.content?.map((b) => b.text).join("") ?? "rm failed";
+      throw new Error(msg);
+    }
+  }
+
+  async cp(
+    src: string,
+    dest: string,
+    options?: { recursive?: boolean }
+  ): Promise<void> {
+    const normSrc = this.normalisePath(src);
+    const normDest = this.normalisePath(dest);
+    const flag = options?.recursive ? "-r " : "";
+    const { exitCode, stderr } = await this.execShell(
+      `cp ${flag}"${normSrc}" "${normDest}"`
+    );
+    if (exitCode !== 0) throw new Error(`cp failed: ${stderr}`);
+  }
+
+  async mv(src: string, dest: string): Promise<void> {
+    const normSrc = this.normalisePath(src);
+    const normDest = this.normalisePath(dest);
+    const { exitCode, stderr } = await this.execShell(
+      `mv "${normSrc}" "${normDest}"`
+    );
+    if (exitCode !== 0) throw new Error(`mv failed: ${stderr}`);
+  }
+
+  async readlink(path: string): Promise<string> {
+    const norm = this.normalisePath(path);
+    const { stdout, exitCode, stderr } = await this.execShell(
+      `readlink "${norm}"`
+    );
+    if (exitCode !== 0)
+      throw new SandboxNotSupportedError(`readlink: ${stderr}`);
+    return stdout.trim();
+  }
+
+  resolvePath(base: string, path: string): string {
+    return posix.resolve(this.normalisePath(base), path);
+  }
+}

package/src/adapters/sandbox/bedrock/index.ts

@@ -0,0 +1,259 @@
+import {
+  BedrockAgentCoreClient,
+  StartCodeInterpreterSessionCommand,
+  GetCodeInterpreterSessionCommand,
+  StopCodeInterpreterSessionCommand,
+  InvokeCodeInterpreterCommand,
+} from "@aws-sdk/client-bedrock-agentcore";
+import type { CodeInterpreterStreamOutput } from "@aws-sdk/client-bedrock-agentcore";
+import type {
+  Sandbox,
+  SandboxCapabilities,
+  SandboxCreateResult,
+  SandboxProvider,
+  SandboxSnapshot,
+  ExecOptions,
+  ExecResult,
+} from "../../../lib/sandbox/types";
+import {
+  SandboxNotFoundError,
+  SandboxNotSupportedError,
+} from "../../../lib/sandbox/types";
+import { BedrockSandboxFileSystem } from "./filesystem";
+import type {
+  BedrockSandbox,
+  BedrockSandboxConfig,
+  BedrockSandboxCreateOptions,
+} from "./types";
+
+// ============================================================================
+// Stream helpers
+// ============================================================================
+
+async function consumeExecStream(
+  stream: AsyncIterable<CodeInterpreterStreamOutput>
+): Promise<ExecResult> {
+  for await (const event of stream) {
+    if ("result" in event && event.result) {
+      const sc = event.result.structuredContent;
+      return {
+        exitCode: sc?.exitCode ?? 0,
+        stdout: sc?.stdout ?? "",
+        stderr: sc?.stderr ?? "",
+      };
+    }
+    if ("accessDeniedException" in event && event.accessDeniedException)
+      throw new Error(event.accessDeniedException.message ?? "Access denied");
+    if ("resourceNotFoundException" in event && event.resourceNotFoundException)
+      throw new Error(
+        event.resourceNotFoundException.message ?? "Resource not found"
+      );
+    if ("validationException" in event && event.validationException)
+      throw new Error(
+        event.validationException.message ?? "Validation error"
+      );
+    if ("internalServerException" in event && event.internalServerException)
+      throw new Error(
+        event.internalServerException.message ?? "Internal server error"
+      );
+    if ("throttlingException" in event && event.throttlingException)
+      throw new Error(event.throttlingException.message ?? "Throttled");
+    if (
+      "serviceQuotaExceededException" in event &&
+      event.serviceQuotaExceededException
+    )
+      throw new Error(
+        event.serviceQuotaExceededException.message ?? "Quota exceeded"
+      );
+    if ("conflictException" in event && event.conflictException)
+      throw new Error(event.conflictException.message ?? "Conflict");
+  }
+  return { exitCode: 0, stdout: "", stderr: "" };
+}
+
+// ============================================================================
+// BedrockSandboxImpl
+// ============================================================================
+
+class BedrockSandboxImpl implements Sandbox {
+  readonly capabilities: SandboxCapabilities = {
+    filesystem: true,
+    execution: true,
+    persistence: false,
+  };
+
+  readonly fs: BedrockSandboxFileSystem;
+
+  constructor(
+    readonly id: string,
+    private client: BedrockAgentCoreClient,
+    private codeInterpreterIdentifier: string,
+    private sessionId: string,
+    workspaceBase = "/home/user"
+  ) {
+    this.fs = new BedrockSandboxFileSystem(
+      client,
+      codeInterpreterIdentifier,
+      sessionId,
+      workspaceBase
+    );
+  }
+
+  async exec(command: string, options?: ExecOptions): Promise<ExecResult> {
+    let cmd = command;
+    if (options?.cwd) cmd = `cd "${options.cwd}" && ${cmd}`;
+    if (options?.env) {
+      const exports = Object.entries(options.env)
+        .map(([k, v]) => `export ${k}="${v.replace(/"/g, '\\"')}"`)
+        .join(" && ");
+      cmd = `${exports} && ${cmd}`;
+    }
+
+    const resp = await this.client.send(
+      new InvokeCodeInterpreterCommand({
+        codeInterpreterIdentifier: this.codeInterpreterIdentifier,
+        sessionId: this.sessionId,
+        name: "executeCommand",
+        arguments: { command: cmd },
+      })
+    );
+
+    if (!resp.stream)
+      throw new Error("No stream in code interpreter response");
+    return consumeExecStream(resp.stream);
+  }
+
+  async destroy(): Promise<void> {
+    await this.client.send(
+      new StopCodeInterpreterSessionCommand({
+        codeInterpreterIdentifier: this.codeInterpreterIdentifier,
+        sessionId: this.sessionId,
+      })
+    );
+  }
+}
+
+// ============================================================================
+// BedrockSandboxProvider
+// ============================================================================
+
+export class BedrockSandboxProvider
+  implements SandboxProvider<BedrockSandboxCreateOptions, BedrockSandbox>
+{
+  readonly id = "bedrock";
+  readonly capabilities: SandboxCapabilities = {
+    filesystem: true,
+    execution: true,
+    persistence: false,
+  };
+
+  private client: BedrockAgentCoreClient;
+  private readonly codeInterpreterIdentifier: string;
+  private readonly defaultWorkspaceBase: string;
+
+  constructor(config: BedrockSandboxConfig) {
+    this.client = new BedrockAgentCoreClient(config.clientConfig ?? {});
+    this.codeInterpreterIdentifier = config.codeInterpreterIdentifier;
+    this.defaultWorkspaceBase = config.workspaceBase ?? "/home/user";
+  }
+
+  async create(
+    options?: BedrockSandboxCreateOptions
+  ): Promise<SandboxCreateResult> {
+    const resp = await this.client.send(
+      new StartCodeInterpreterSessionCommand({
+        codeInterpreterIdentifier: this.codeInterpreterIdentifier,
+        name: options?.name,
+        sessionTimeoutSeconds: options?.sessionTimeoutSeconds,
+      })
+    );
+
+    const sessionId = resp.sessionId ?? "";
+    if (!sessionId) throw new Error("No sessionId returned from Bedrock");
+    const sandbox = new BedrockSandboxImpl(
+      sessionId,
+      this.client,
+      this.codeInterpreterIdentifier,
+      sessionId,
+      this.defaultWorkspaceBase
+    );
+
+    if (options?.initialFiles) {
+      for (const [path, content] of Object.entries(options.initialFiles)) {
+        await sandbox.fs.writeFile(path, content);
+      }
+    }
+
+    if (options?.env) {
+      const exports = Object.entries(options.env)
+        .map(([k, v]) => `${k}="${v.replace(/"/g, '\\"')}"`)
+        .join(" ");
+      await sandbox.exec(`echo '${exports}' >> ~/.bashrc`);
+    }
+
+    return { sandbox };
+  }
+
+  async get(sandboxId: string): Promise<BedrockSandbox> {
+    try {
+      const resp = await this.client.send(
+        new GetCodeInterpreterSessionCommand({
+          codeInterpreterIdentifier: this.codeInterpreterIdentifier,
+          sessionId: sandboxId,
+        })
+      );
+
+      if (resp.status === "TERMINATED") {
+        throw new SandboxNotFoundError(sandboxId);
+      }
+
+      return new BedrockSandboxImpl(
+        sandboxId,
+        this.client,
+        this.codeInterpreterIdentifier,
+        sandboxId,
+        this.defaultWorkspaceBase
+      );
+    } catch (err) {
+      if (err instanceof SandboxNotFoundError) throw err;
+      throw new SandboxNotFoundError(sandboxId);
+    }
+  }
+
+  async destroy(sandboxId: string): Promise<void> {
+    try {
+      await this.client.send(
+        new StopCodeInterpreterSessionCommand({
+          codeInterpreterIdentifier: this.codeInterpreterIdentifier,
+          sessionId: sandboxId,
+        })
+      );
+    } catch {
+      // Already stopped or not found
+    }
+  }
+
+  async pause(_sandboxId: string, _ttlSeconds?: number): Promise<void> {
+    throw new SandboxNotSupportedError("pause");
+  }
+
+  async snapshot(_sandboxId: string): Promise<SandboxSnapshot> {
+    throw new SandboxNotSupportedError("snapshot");
+  }
+
+  async restore(_snapshot: SandboxSnapshot): Promise<never> {
+    throw new SandboxNotSupportedError("restore");
+  }
+
+  async fork(_sandboxId: string): Promise<Sandbox> {
+    throw new SandboxNotSupportedError("fork");
+  }
+}
+
+// Re-exports
+export { BedrockSandboxFileSystem } from "./filesystem";
+export type {
+  BedrockSandbox,
+  BedrockSandboxConfig,
+  BedrockSandboxCreateOptions,
+} from "./types";

package/src/adapters/sandbox/bedrock/proxy.ts

@@ -0,0 +1,56 @@
+/**
+ * Workflow-safe proxy for Bedrock sandbox operations.
+ *
+ * Uses longer timeouts than in-memory providers since Bedrock
+ * sandboxes are remote and creation involves provisioning.
+ *
+ * Import this from `zeitlich/adapters/sandbox/bedrock/workflow`
+ * in your Temporal workflow files.
+ *
+ * By default the scope is derived from `workflowInfo().workflowType`,
+ * so activities are automatically namespaced per workflow.
+ *
+ * @example
+ * ```typescript
+ * import { proxyBedrockSandboxOps } from 'zeitlich/adapters/sandbox/bedrock/workflow';
+ *
+ * const sandbox = proxyBedrockSandboxOps();
+ * ```
+ */
+import { proxyActivities, workflowInfo } from "@temporalio/workflow";
+import type { SandboxOps } from "../../../lib/sandbox/types";
+import type { BedrockSandboxCreateOptions } from "./types";
+
+const ADAPTER_PREFIX = "bedrock";
+
+export function proxyBedrockSandboxOps(
+  scope?: string,
+  options?: Parameters<typeof proxyActivities>[0]
+): SandboxOps<BedrockSandboxCreateOptions> {
+  const resolvedScope = scope ?? workflowInfo().workflowType;
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const acts = proxyActivities<Record<string, (...args: any[]) => any>>(
+    options ?? {
+      startToCloseTimeout: "120s",
+      retry: {
+        maximumAttempts: 3,
+        initialInterval: "5s",
+        maximumInterval: "60s",
+        backoffCoefficient: 3,
+      },
+    }
+  );
+
+  const prefix = `${ADAPTER_PREFIX}${resolvedScope.charAt(0).toUpperCase()}${resolvedScope.slice(1)}`;
+  const p = (key: string): string =>
+    `${prefix}${key.charAt(0).toUpperCase()}${key.slice(1)}`;
+
+  return {
+    createSandbox: acts[p("createSandbox")],
+    destroySandbox: acts[p("destroySandbox")],
+    pauseSandbox: acts[p("pauseSandbox")],
+    snapshotSandbox: acts[p("snapshotSandbox")],
+    forkSandbox: acts[p("forkSandbox")],
+  } as SandboxOps<BedrockSandboxCreateOptions>;
+}