Add a shared filesystem for Daytona and Modal

AGENTS.md

@@ -33,8 +33,8 @@ public client owns cleanup through `Close`.
   fields, and plain allowlists. The client materializes wire messages privately
   for Protovalidate. Application code depends on `@sandbox-kit/sandbox` (and a
   provider); `@sandbox-kit/contracts` is an internal SDK dependency.
-- Creation returns a sandbox handle. Implement lifecycle methods on that handle
-  separately from creation configuration.
+- Creation returns a sandbox handle. Implement lifecycle and filesystem methods
+  on that handle separately from creation configuration.
 - Preserve field presence, units, source kinds, and provider defaults.
 - Reject unsupported intent before provider calls. Account quotas, permissions,
   and capacity remain provider-enforced.
@@ -72,9 +72,10 @@ classification are handwritten per language.
 ## Examples and documentation
 
 For every public feature, update its language's runnable example and guide.
-Use small, independent provider-specific projects under `examples/<language>/`.
-Each example demonstrates one operation with its own configuration and no provider
-selector or CLI flags.
+Use small, independent provider-specific projects under
+`examples/<language>/<provider>/` in `filesystem/`, `configuration/`,
+`lifecycle/`, or `errors/`. Each example demonstrates one operation with its
+own configuration and no provider selector or CLI flags.
 
 Keep examples aligned with the implemented API. Label test doubles and local
 verification limits clearly. Verify changed examples before handoff and update

README.md

@@ -115,7 +115,7 @@ TypeScript (Daytona):
 
 ```sh
 git clone https://github.com/sandbox-kit/kit.git
-cd kit/examples/typescript/daytona/create-daytona-sandbox
+cd kit/examples/typescript/daytona/configuration/create-daytona-sandbox
 cp .env.example .env   # set DAYTONA_API_KEY
 npm install && npm run build && npm start
 ```
@@ -124,19 +124,20 @@ Go (Daytona), from a fresh clone:
 
 ```sh
 git clone https://github.com/sandbox-kit/kit.git
-cd kit/examples/go/daytona/create-daytona-sandbox
+cd kit/examples/go/daytona/configuration/create-daytona-sandbox
 cp .env.example .env   # set DAYTONA_API_KEY
 go run .
 ```
 
 Modal needs a token pair and an existing app:
-[TypeScript](examples/typescript/modal/create-modal-sandbox/README.md) ·
-[Go](examples/go/modal/create-modal-sandbox/README.md).
+[TypeScript](examples/typescript/modal/configuration/create-modal-sandbox/README.md) ·
+[Go](examples/go/modal/configuration/create-modal-sandbox/README.md).
 
-Creation examples provision real sandboxes. Lifecycle examples use the ID in
-`.env` (stop / terminate / archive / delete can destroy that resource).
-Error-handling examples fail locally and create nothing. Skip copying
-`.env.example` if you already have a configured `.env`.
+Creation examples provision real sandboxes. Filesystem and lifecycle examples
+use the ID in `.env` (stop / terminate / archive / delete can destroy that
+resource; filesystem examples use the path you set). Error-handling examples
+fail locally and create nothing. Skip copying `.env.example` if you already
+have a configured `.env`.
 
 Full catalog: [examples/README.md](examples/README.md) ·
 [TypeScript](examples/typescript/README.md) · [Go](examples/go/README.md).
@@ -238,7 +239,8 @@ More detail: [responses and errors](docs/responses-and-errors.md).
 
 Guides: [configuration](docs/configuration.md) ·
 [creation](docs/sandbox-creation.md) ·
-[lifecycle](docs/sandbox-lifecycle.md).
+[lifecycle](docs/sandbox-lifecycle.md) ·
+[filesystem](docs/filesystem.md).
 
 ## Documentation
 
@@ -259,6 +261,7 @@ These pages are the behavior reference for the same API:
 | [Client configuration](docs/configuration.md)                                                                  | Auth, scope, defaults, deadlines  |
 | [Sandbox creation](docs/sandbox-creation.md)                                                                   | Fields, units, policies           |
 | [Sandbox lifecycle](docs/sandbox-lifecycle.md)                                                                 | Get, attach, capabilities         |
+| [Filesystem](docs/filesystem.md)                                                                               | Read, write, copy, list, stat, mkdir, remove |
 | [Providers](docs/providers.md)                                                                                 | Daytona and Modal                 |
 | [Responses and errors](docs/responses-and-errors.md)                                                           | Error details and provider causes |
 | [TS Daytona](sdks/typescript/providers/daytona/README.md) / [Modal](sdks/typescript/providers/modal/README.md) | TypeScript provider notes         |

docs/agent-skills.md

@@ -81,14 +81,15 @@ rules instead of invocable skills (`/skill-name`).
 
 - **Source:** `wshobson/agents`
 - **Why selected:** Covers package boundaries, public exports, `pyproject.toml`,
-  source layouts, and dependency organization for a Python SDK under
-  `sdks/python/`.
+  source layouts, and dependency organization for a Python language binding that
+  would follow the same provider-neutral module layout as Go and TypeScript.
 
 ### `python-testing-patterns`
 
 - **Source:** `wshobson/agents`
 - **Why selected:** Adds focused pytest fixtures, parametrization, mocking,
-  integration tests, and asynchronous test patterns for a Python SDK.
+  integration tests, and asynchronous test patterns for a Python language
+  binding.
 
 ### `python-error-handling`
 
@@ -100,8 +101,8 @@ rules instead of invocable skills (`/skill-name`).
 
 - **Source:** `wshobson/agents`
 - **Why selected:** Covers structured concurrency, cancellation, timeouts,
-  resource cleanup, and async context managers for a Python SDK that wraps
-  networked sandbox providers.
+  resource cleanup, and async context managers when wrapping networked sandbox
+  providers from Python.
 
 ### `docs-current-state`
 

docs/api-declarations.md

@@ -19,14 +19,15 @@ provider classification are handwritten per language.
 
 ## Handwritten runtime
 
-- `Client` / `Sandbox` facades and lifecycle dispatch
+- `Client` / `Sandbox` facades, lifecycle dispatch, and `Filesystem`
 - TypeScript public create/config input types and materialization to wire
 - Provider selection, native SDK initialization, and cleanup
 - Error wrappers, cause chaining, and provider-native error classification
 - Metadata clone helpers
 - Protovalidate evaluation for shared create/config rules (`secure_endpoint` is
   handwritten)
 - Provider checks, field mappings, and config assembly
+- Path validation and provider filesystem bindings
 - Provider orchestration that the mapping inventory cannot express
 
 See [Protobuf SDK boundary](protobuf-sdk-boundary.md) and

docs/code-generation.md

@@ -59,7 +59,7 @@ the SDK.
 
 | Input                             | Defines                                                                            |
 | --------------------------------- | ---------------------------------------------------------------------------------- |
-| `proto/kit/sandbox/v1/`           | Public portable types (config, create, lifecycle options, metadata, errors)        |
+| `proto/kit/sandbox/v1/`           | Public portable types (config, create, lifecycle options, filesystem options, metadata, errors) |
 | `specs/validation.yaml`           | Portable create-validation inventory (mirrors Protovalidate options in proto)      |
 | `specs/client.yaml`               | Config validation inventory (mirrors Protovalidate; `secure_endpoint` handwritten) |
 | `specs/contracts.yaml`            | Metadata/error contract limits                                                     |
@@ -85,8 +85,9 @@ plus per-provider classification mappers. Go provider helpers
 `sdks/go/internal/sdk`. `RejectUnmapped` sets `Provider` to the provider name
 and `Field` to the parent path plus the leftover protobuf name.
 
-Handwritten `CreateField*`, `ConfigField*`, `InfoField*`, and `ResultField*`
-constants are the field paths used by validation, mappings, and errors.
+Handwritten `CreateField*`, `ConfigField*`, `InfoField*`, `ResultField*`, and
+`FileField*` constants are the field paths used by validation, mappings, and
+errors.
 
 `specs/contracts.yaml` names the shared metadata and error messages.
 Portable messages come from standard protobuf generation into contract packages.
@@ -249,18 +250,19 @@ Backend state capture and metadata cloning are handwritten in the SDK runtime
 5. Run the CLI verification command.
 
 SDK orchestration that the inventory cannot express stays in handwritten
-provider integration files (Go `sandbox.go`, `creation.go`, and, where the
-provider observes native state, `lifecycle.go` and `metadata.go`; TypeScript
-provider-named `.ts` plus `mappings.ts` files): lookup sequences, source
-selection, readiness, and remaining provider semantics. Handwritten
-`provider_mappings` / `provider_config` own field conversions and native client
-configuration; handwritten `provider_checks` enforces create checks; handwritten
-`errors` classifies native provider errors.
-
-Lifecycle option and result types come from protobuf contracts. Handle methods,
-typed provider dispatch, capability discovery, and close coordination remain
-handwritten runtime code on `Client`, `Sandbox`, and provider `Backend`
-adapters.
+provider integration files (Go `sandbox.go`, `creation.go`, `filesystem.go`,
+and, where the provider observes native state, `lifecycle.go` and
+`metadata.go`; TypeScript provider-named `.ts` plus `mappings.ts` files):
+lookup sequences, source selection, readiness, filesystem bindings, and
+remaining provider semantics. Handwritten `provider_mappings` /
+`provider_config` own field conversions and native client configuration;
+handwritten `provider_checks` enforces create checks; handwritten `errors`
+classifies native provider errors.
+
+Lifecycle and filesystem option and result types come from protobuf contracts.
+Handle methods, typed provider dispatch, lifecycle capability discovery,
+filesystem backend methods, and close coordination remain handwritten runtime
+code on `Client`, `Sandbox` / `Filesystem`, and provider `Backend` adapters.
 
 See [tooling](../tooling/README.md), [naming](naming.md), and
 [reference verification](provider-verification.md).