Skip to content

Filesystem

Three layers, A shipped now, B shipped now (CLI only), C deferred.

v0.4.0concept

Filesystem (v0.2)

Three layers, A shipped now, B shipped now (CLI only), C deferred.

Layer A: URL-based file transport (server-compatible)

Pipeline-level output already supports format: zip + files: [...] + delivery: signed_url. The runtime uploads the ZIP to R2 (or S3) and returns a signed URL with expires_in.

output:
  format: zip
  files: [refactored_code.ts, tests.test.ts, README.md]
  delivery: signed_url
  expires_in: 86400  # 24h

Server execution: ✅. No local FS required.

Layer B: working_dir (CLI only)

- id: read_project
  uses: code_analyzer@0.1.0
  working_dir: ./my-project         # v0.2 NEW
  input: { target: "src/" }

When the CLI encounters working_dir:, it:

  1. Resolves the path relative to the pipeline YAML’s directory (or, if absolute, uses as-is)
  2. Creates the directory if it doesn’t exist
  3. Exposes read_file(path), write_file(path, content), list_dir(path) helpers in the stage context — these are described in the LLM system prompt so the model can call them via structured output
  4. After the stage completes, the dir is left in place (CLI user can inspect). The directory is added to the provenance payload

Server execution: ❌. Server emits warning "working_dir_ignored_on_server": true and continues with the stage as if the field were omitted.

Security: working_dir is OPT-IN. CLI users must explicitly include it in their YAML. The CLI does not sandbox the working_dir — it’s the user’s responsibility to point it at a safe location. Future v0.3 will add an allowed_paths whitelist inside working_dir.

Layer C: Virtualized FS + fs_ops allowlist (Phase 3+)

- id: read_dataset
  uses: dataset_analyzer@0.1.0
  fs_ops:
    - op: read
      path: s3://alice-datasets/2026-q3.csv
      allowed_paths: ["/data/**"]
      max_size_mb: 50

Phase 3 will:

  • Back working_dir with R2 (or compatible) on the server
  • Enforce op allowlist (read/write/list)
  • Per-op billing (fs_read: 0.001 USDC, fs_write: 0.002 USDC)
  • Tool-call style invocation (model returns tool_use → executor runs op → result injected into next turn)

Deferred because it requires: server-side sandbox, per-op accounting, R2 quota, billing integration.