zeitlich 0.2.23 → 0.2.25

package/README.md

@@ -61,6 +61,7 @@ A sandbox adapter provides filesystem access for tools like `Bash`, `Read`, `Wri
 | Virtual | `zeitlich/adapters/sandbox/virtual` | Custom resolvers with path-only ops |
 | Daytona | `zeitlich/adapters/sandbox/daytona` | Remote Daytona workspaces |
 | E2B | `zeitlich/adapters/sandbox/e2b` | E2B cloud sandboxes |
+| Bedrock | `zeitlich/adapters/sandbox/bedrock` | AWS Bedrock AgentCore Code Interpreter |
 
 ### Example: LangChain Adapter
 
@@ -95,6 +96,7 @@ npm install zeitlich ioredis
 - `ioredis` >= 5.0.0
 - `@langchain/core` >= 1.0.0 (optional — only when using the LangChain adapter)
 - `@google/genai` >= 1.0.0 (optional — only when using the Google GenAI adapter)
+- `@aws-sdk/client-bedrock-agentcore` >= 3.900.0 (optional — only when using the Bedrock adapter)
 
 **Required infrastructure:**
 
@@ -483,14 +485,18 @@ Zeitlich has first-class support for the [agentskills.io](https://agentskills.io
 
 #### Defining a Skill
 
-Each skill lives in its own directory as a `SKILL.md` file with YAML frontmatter:
+Each skill lives in its own directory as a `SKILL.md` file with YAML frontmatter. A skill directory can also contain **resource files** — supporting documents, templates, or data that the agent can read from the sandbox filesystem:
 
 ```
 skills/
 ├── code-review/
-│   └── SKILL.md
+│   ├── SKILL.md
+│   └── resources/
+│       └── checklist.md
 ├── pdf-processing/
-│   └── SKILL.md
+│   ├── SKILL.md
+│   └── templates/
+│       └── extraction-prompt.txt
 ```
 
 ```markdown
@@ -506,14 +512,17 @@ license: MIT
 When reviewing code, follow these steps:
 1. Read the diff with `Bash`
 2. Search for related tests with `Grep`
-3. ...
+3. Read the checklist from `resources/checklist.md`
+4. ...
 ```
 
 Required fields: `name` and `description`. Optional: `license`, `compatibility`, `allowed-tools` (space-delimited), `metadata` (key-value map).
 
+Resource files are any non-`SKILL.md` files inside the skill directory (discovered recursively). When loaded via `FileSystemSkillProvider`, their contents are stored in `skill.resourceContents` — a `Record<string, string>` keyed by relative path (e.g. `"resources/checklist.md"`).
+
 #### Loading Skills
 
-Use `FileSystemSkillProvider` to load skills from a directory (works with any sandbox filesystem):
+Use `FileSystemSkillProvider` to load skills from a directory. It accepts any `SandboxFileSystem` implementation. `loadAll()` eagerly reads `SKILL.md` instructions **and** all resource file contents into each `Skill` object:
 
 ```typescript
 import { FileSystemSkillProvider } from "zeitlich";
@@ -524,6 +533,28 @@ const { sandbox } = await provider.create({});
 
 const skillProvider = new FileSystemSkillProvider(sandbox.fs, "/skills");
 const skills = await skillProvider.loadAll();
+// Each skill has: { name, description, instructions, resourceContents }
+// resourceContents: { "resources/checklist.md": "...", ... }
+```
+
+**Loading from the local filesystem (activity-side):** Use `NodeFsSandboxFileSystem` to read skills from the worker's disk. This is the simplest option when skill files are bundled alongside your application code:
+
+```typescript
+import { NodeFsSandboxFileSystem, FileSystemSkillProvider } from "zeitlich";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const fs = new NodeFsSandboxFileSystem(join(__dirname, "skills"));
+const skillProvider = new FileSystemSkillProvider(fs, "/");
+const skills = await skillProvider.loadAll();
+```
+
+For lightweight discovery without reading file contents, use `listSkills()`:
+
+```typescript
+const metadata = await skillProvider.listSkills();
+// SkillMetadata[] — name, description, location only
 ```
 
 Or parse a single file directly:
@@ -537,7 +568,10 @@ const { frontmatter, body } = parseSkillFile(rawMarkdown);
 
 #### Passing Skills to a Session
 
-Pass loaded skills to `createSession`. Zeitlich automatically registers a `ReadSkill` tool whose description lists all available skills — the agent discovers them through the tool definition and loads instructions on demand:
+Pass loaded skills to `createSession`. Zeitlich automatically:
+
+1. Registers a `ReadSkill` tool whose description lists all available skills — the agent discovers them through the tool definition and loads instructions on demand.
+2. Seeds `resourceContents` into the sandbox as `initialFiles` (when `sandboxOps` is configured), so the agent can read resource files with its `Read` tool without any extra setup.
 
 ```typescript
 import { createSession } from "zeitlich/workflow";
@@ -548,7 +582,7 @@ const session = await createSession({
 });
 ```
 
-The `ReadSkill` tool accepts a `skill_name` parameter (constrained to an enum of available names) and returns the full instruction body. The handler runs directly in the workflow — no activity needed.
+The `ReadSkill` tool accepts a `skill_name` parameter (constrained to an enum of available names) and returns the full instruction body plus a list of available resource file paths. The handler runs directly in the workflow — no activity needed. Resource file contents are not included in the `ReadSkill` response (progressive disclosure); the agent reads them from the sandbox filesystem on demand.
 
 #### Building Skills Manually
 
@@ -867,6 +901,7 @@ Framework-agnostic utilities for activities, worker setup, and Node.js code:
 | `createThreadManager`     | Generic Redis-backed thread manager factory                                                   |
 | `toTree`                  | Generate file tree string from an `IFileSystem` instance                                      |
 | `withSandbox`             | Wraps a handler to auto-resolve sandbox from context (pairs with `withAutoAppend`)            |
+| `NodeFsSandboxFileSystem`   | `node:fs` adapter for `SandboxFileSystem` — read skills from the worker's local disk              |
 | `FileSystemSkillProvider`   | Load skills from a directory following the agentskills.io layout                                  |
 | Tool handlers             | `bashHandler`, `editHandler`, `globHandler`, `readFileHandler`, `writeFileHandler`, `createAskUserQuestionHandler` |
 
@@ -926,6 +961,7 @@ Framework-agnostic utilities for activities, worker setup, and Node.js code:
 │  │  │ • Turns        │  │  • Tool routing & hooks       │   │  │
 │  │  │ • Custom state │  │  • Prompts (system, context)  │   │  │
 │  │  └────────────────┘  │  • Subagent coordination      │   │  │
+│  │                      │  • Skills (progressive load)   │   │  │
 │  │                      └───────────────────────────────┘   │  │
 │  └──────────────────────────────────────────────────────────┘  │
 │                              │                                  │
@@ -942,7 +978,7 @@ Framework-agnostic utilities for activities, worker setup, and Node.js code:
 │  └──────────────────────────────────────────────────────────┘  │
 │  ┌──────────────────────────────────────────────────────────┐  │
 │  │         Sandbox Adapter (zeitlich/adapters/sandbox/*)      │  │
-│  │  • In-memory, Virtual, Daytona, E2B, or custom            │  │
+│  │  • In-memory, Virtual, Daytona, E2B, Bedrock, or custom   │  │
 │  │  • Filesystem ops for agent tools                          │  │
 │  └──────────────────────────────────────────────────────────┘  │
 └─────────────────────────────────────────────────────────────────┘

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

@@ -0,0 +1,452 @@
+'use strict';
+
+var clientBedrockAgentcore = require('@aws-sdk/client-bedrock-agentcore');
+var common = require('@temporalio/common');
+var path = require('path');
+
+// src/adapters/sandbox/bedrock/index.ts
+var SandboxNotSupportedError = class extends common.ApplicationFailure {
+  constructor(operation) {
+    super(
+      `Sandbox does not support: ${operation}`,
+      "SandboxNotSupportedError",
+      true
+    );
+  }
+};
+var SandboxNotFoundError = class extends common.ApplicationFailure {
+  constructor(sandboxId) {
+    super(`Sandbox not found: ${sandboxId}`, "SandboxNotFoundError", true);
+  }
+};
+async function consumeStream(stream) {
+  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");
+}
+var BedrockSandboxFileSystem = class {
+  constructor(client, codeInterpreterIdentifier, sessionId, workspaceBase = "/home/user") {
+    this.client = client;
+    this.codeInterpreterIdentifier = codeInterpreterIdentifier;
+    this.sessionId = sessionId;
+    this.workspaceBase = path.posix.resolve("/", workspaceBase);
+  }
+  workspaceBase;
+  /**
+   * Resolve a caller-supplied path to an absolute path within the workspace.
+   * Used for shell commands that need full paths.
+   */
+  normalisePath(path$1) {
+    if (path.posix.isAbsolute(path$1) && !path$1.startsWith(this.workspaceBase + "/") && path$1 !== this.workspaceBase) {
+      path$1 = path$1.replace(/^\/+/, "");
+    }
+    const resolved = path.posix.resolve(this.workspaceBase, path$1);
+    if (!resolved.startsWith(this.workspaceBase + "/") && resolved !== this.workspaceBase) {
+      throw new Error(
+        `Invalid file path: "${resolved}" escapes workspace "${this.workspaceBase}"`
+      );
+    }
+    return resolved;
+  }
+  /**
+   * Return a workspace-relative path for Bedrock tool invocations
+   * (`writeFiles`, `readFiles`, `listFiles`, `removeFiles`), which
+   * reject absolute paths as "path traversal".
+   */
+  toToolPath(path) {
+    const abs = this.normalisePath(path);
+    const prefix = this.workspaceBase + "/";
+    return abs.startsWith(prefix) ? abs.slice(prefix.length) : abs;
+  }
+  async invoke(name, args) {
+    const resp = await this.client.send(
+      new clientBedrockAgentcore.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);
+  }
+  async execShell(command) {
+    const result = await this.invoke("executeCommand", {
+      command
+    });
+    return {
+      stdout: result.structuredContent?.stdout ?? "",
+      stderr: result.structuredContent?.stderr ?? "",
+      exitCode: result.structuredContent?.exitCode ?? 0
+    };
+  }
+  async readFile(path) {
+    const rel = this.toToolPath(path);
+    const result = await this.invoke("readFiles", {
+      paths: [rel]
+    });
+    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) {
+    const rel = this.toToolPath(path);
+    const result = await this.invoke("readFiles", {
+      paths: [rel]
+    });
+    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, content) {
+    const rel = this.toToolPath(path);
+    const isText = typeof content === "string";
+    const result = await this.invoke("writeFiles", {
+      content: [
+        {
+          path: rel,
+          ...isText ? { text: content } : { blob: content }
+        }
+      ]
+    });
+    if (result.isError) {
+      const msg = result.content?.map((b) => b.text).join("") ?? "writeFile failed";
+      throw new Error(msg);
+    }
+  }
+  async appendFile(path, content) {
+    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) {
+    const norm = this.normalisePath(path);
+    const { exitCode } = await this.execShell(`test -e "${norm}"`);
+    return exitCode === 0;
+  }
+  async stat(path) {
+    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 * 1e3)
+    };
+  }
+  async mkdir(path, options) {
+    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) {
+    const rel = this.toToolPath(path);
+    const result = await this.invoke("listFiles", {
+      directoryPath: rel
+    });
+    const names = [];
+    for (const block of result.content ?? []) {
+      if (block.name) names.push(block.name);
+    }
+    if (names.length > 0) return names;
+    const norm = this.normalisePath(path);
+    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) {
+    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, options) {
+    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 rel = this.toToolPath(path);
+    const result = await this.invoke("removeFiles", {
+      paths: [rel]
+    });
+    if (result.isError) {
+      const msg = result.content?.map((b) => b.text).join("") ?? "rm failed";
+      throw new Error(msg);
+    }
+  }
+  async cp(src, dest, options) {
+    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, dest) {
+    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) {
+    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, path$1) {
+    return path.posix.resolve(this.normalisePath(base), path$1);
+  }
+};
+
+// src/adapters/sandbox/bedrock/index.ts
+async function consumeExecStream(stream) {
+  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: "" };
+}
+var BedrockSandboxImpl = class {
+  constructor(id, client, codeInterpreterIdentifier, sessionId, workspaceBase = "/home/user") {
+    this.id = id;
+    this.client = client;
+    this.codeInterpreterIdentifier = codeInterpreterIdentifier;
+    this.sessionId = sessionId;
+    this.fs = new BedrockSandboxFileSystem(
+      client,
+      codeInterpreterIdentifier,
+      sessionId,
+      workspaceBase
+    );
+  }
+  capabilities = {
+    filesystem: true,
+    execution: true,
+    persistence: false
+  };
+  fs;
+  async exec(command, options) {
+    let cmd = command;
+    if (options?.cwd) cmd = `cd "${options.cwd}" && ${cmd}`;
+    if (options?.env) {
+      const exports$1 = Object.entries(options.env).map(([k, v]) => `export ${k}="${v.replace(/"/g, '\\"')}"`).join(" && ");
+      cmd = `${exports$1} && ${cmd}`;
+    }
+    const resp = await this.client.send(
+      new clientBedrockAgentcore.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() {
+    await this.client.send(
+      new clientBedrockAgentcore.StopCodeInterpreterSessionCommand({
+        codeInterpreterIdentifier: this.codeInterpreterIdentifier,
+        sessionId: this.sessionId
+      })
+    );
+  }
+};
+var BedrockSandboxProvider = class {
+  id = "bedrock";
+  capabilities = {
+    filesystem: true,
+    execution: true,
+    persistence: false
+  };
+  client;
+  codeInterpreterIdentifier;
+  defaultWorkspaceBase;
+  constructor(config) {
+    this.client = new clientBedrockAgentcore.BedrockAgentCoreClient(config.clientConfig ?? {});
+    this.codeInterpreterIdentifier = config.codeInterpreterIdentifier;
+    this.defaultWorkspaceBase = config.workspaceBase ?? "/home/user";
+  }
+  async create(options) {
+    const resp = await this.client.send(
+      new clientBedrockAgentcore.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$1 = Object.entries(options.env).map(([k, v]) => `${k}="${v.replace(/"/g, '\\"')}"`).join(" ");
+      await sandbox.exec(`echo '${exports$1}' >> ~/.bashrc`);
+    }
+    return { sandbox };
+  }
+  async get(sandboxId) {
+    try {
+      const resp = await this.client.send(
+        new clientBedrockAgentcore.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) {
+    try {
+      await this.client.send(
+        new clientBedrockAgentcore.StopCodeInterpreterSessionCommand({
+          codeInterpreterIdentifier: this.codeInterpreterIdentifier,
+          sessionId: sandboxId
+        })
+      );
+    } catch {
+    }
+  }
+  async pause(_sandboxId, _ttlSeconds) {
+    throw new SandboxNotSupportedError("pause");
+  }
+  async snapshot(_sandboxId) {
+    throw new SandboxNotSupportedError("snapshot");
+  }
+  async restore(_snapshot) {
+    throw new SandboxNotSupportedError("restore");
+  }
+  async fork(_sandboxId) {
+    throw new SandboxNotSupportedError("fork");
+  }
+};
+
+exports.BedrockSandboxFileSystem = BedrockSandboxFileSystem;
+exports.BedrockSandboxProvider = BedrockSandboxProvider;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map