generated from coulomb/repo-seed
Implement SAND-WP-0002 meta-framework foundation (T01–T09)
Add meta-framework spec, pydantic schemas, profile/extension YAML, extension registry, ext.compose-ssh backend, SandboxManager with State Hub events, CLI commands, integration docs, capability registry entry, and compose-e2e runbook. Nine unit tests pass. T10 remote smoke test remains for operator.
This commit is contained in:
187
docs/meta-framework.md
Normal file
187
docs/meta-framework.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# sand-boxer meta-framework specification
|
||||
|
||||
Version 0.1 — derived from `research/03-meta-framework-synthesis.md` and `INTENT.md`.
|
||||
|
||||
sand-boxer is the **sandbox establishment service**: one API for consumers, many
|
||||
extension backends. It provisions *where and how* code runs; sibling projects own
|
||||
agent harnessing, validation, and code generation.
|
||||
|
||||
---
|
||||
|
||||
## Resource model
|
||||
|
||||
| Resource | Description |
|
||||
|----------|-------------|
|
||||
| **Profile** | Named, versioned sandbox recipe: extension binding, isolation, network, TTL, placement |
|
||||
| **Extension** | Backend adapter implementing provision / wait_ready / teardown |
|
||||
| **Host** | Registered placement target for self-hosted extensions |
|
||||
| **Sandbox** | Running instance of a profile |
|
||||
| **Snapshot** | Point-in-time workspace checkpoint (deferred — SAND-WP-0003) |
|
||||
| **Route** | Extension selection policy when multiple backends qualify |
|
||||
| **Meter** | Usage record for payments layer (SaaS extensions — SAND-WP-0006) |
|
||||
|
||||
---
|
||||
|
||||
## Lifecycle states
|
||||
|
||||
```
|
||||
requested → provisioning → ready → active → { expired | failed } → destroying → destroyed
|
||||
```
|
||||
|
||||
| State | Meaning |
|
||||
|-------|---------|
|
||||
| `requested` | Create accepted; not yet handed to extension |
|
||||
| `provisioning` | Extension running provision + wait_ready |
|
||||
| `ready` | Reachability confirmed; consumer may attach |
|
||||
| `active` | Consumer has marked sandbox in use (optional transition) |
|
||||
| `expired` | TTL elapsed before explicit destroy |
|
||||
| `failed` | Provision or readiness failed |
|
||||
| `destroying` | Teardown in progress |
|
||||
| `destroyed` | Resources released; record retained for audit |
|
||||
|
||||
### State Hub event mapping
|
||||
|
||||
Each transition emits a State Hub progress event (or dedicated registration API
|
||||
when available):
|
||||
|
||||
| Transition | `event_type` | Required fields |
|
||||
|------------|--------------|-----------------|
|
||||
| → `requested` | `note` | `sandbox_id`, `profile_id`, `consumer` |
|
||||
| → `provisioning` | `note` | `extension_id`, `host` |
|
||||
| → `ready` | `milestone` | `reachability` descriptor |
|
||||
| → `active` | `note` | `actor_type`, timestamps |
|
||||
| → `failed` | `note` | `error` summary |
|
||||
| → `destroying` | `note` | — |
|
||||
| → `destroyed` | `milestone` | `duration_s`, cleanup report |
|
||||
|
||||
Event `detail` payload (JSON):
|
||||
|
||||
```json
|
||||
{
|
||||
"sandbox_id": "abc12345",
|
||||
"profile_id": "profile.compose-e2e",
|
||||
"extension_id": "ext.compose-ssh",
|
||||
"host": "coulombcore",
|
||||
"consumer": {"actor": "atm", "project": "wise-validator", "run_id": "..."},
|
||||
"actor_type": "atm",
|
||||
"state": "ready",
|
||||
"reachability": {"ssh": "root@coulombcore", "remote_dir": "/tmp/sandboxer/abc12345"},
|
||||
"timestamps": {"created_at": "...", "ready_at": "..."}
|
||||
}
|
||||
```
|
||||
|
||||
Extends the `build-agent` self-register pattern: generic sandbox identities carry
|
||||
`profile_id` + `extension_id` instead of build-machine metadata.
|
||||
|
||||
---
|
||||
|
||||
## Core API operations (v0)
|
||||
|
||||
| Operation | Description | v0 scope |
|
||||
|-----------|-------------|----------|
|
||||
| `create` | Provision from profile + inputs | **Yes** |
|
||||
| `get` | Inspect sandbox status | **Yes** |
|
||||
| `list` | List sandboxes (filter by consumer optional) | **Yes** |
|
||||
| `extend_ttl` | Extend time-to-live | Stub |
|
||||
| `recreate` | Destroy and reprovision from stored seed | **Yes** |
|
||||
| `destroy` | Idempotent teardown | **Yes** |
|
||||
| `snapshot` / `restore` | Checkpoint workspace | Deferred (SAND-WP-0003) |
|
||||
| `exec` | Run command in sandbox | Harness-owned via SSH (glas-harness) |
|
||||
|
||||
HTTP surface (optional v0; CLI calls core library directly):
|
||||
|
||||
- `POST /v1/sandboxes` — create
|
||||
- `GET /v1/sandboxes/{id}` — get
|
||||
- `GET /v1/sandboxes` — list
|
||||
- `DELETE /v1/sandboxes/{id}` — destroy
|
||||
|
||||
---
|
||||
|
||||
## Consumer attribution
|
||||
|
||||
Every create request carries a **consumer** block:
|
||||
|
||||
```yaml
|
||||
consumer:
|
||||
actor: adm | agt | atm
|
||||
project: <calling-repo-or-service> # e.g. wise-validator, glas-harness
|
||||
session_id: <optional>
|
||||
run_id: <optional>
|
||||
```
|
||||
|
||||
| Actor | Typical caller |
|
||||
|-------|----------------|
|
||||
| `adm` | Human operator via CLI |
|
||||
| `agt` | LLM agent session |
|
||||
| `atm` | Deterministic automation (CI, activity-core, wise-validator) |
|
||||
|
||||
sand-boxer records attribution on every lifecycle event. It does not interpret
|
||||
agent intent or authorize the caller — flex-auth owns authorization when enforced.
|
||||
|
||||
---
|
||||
|
||||
## Extension interface
|
||||
|
||||
Each extension implements:
|
||||
|
||||
```text
|
||||
provision(profile, inputs, placement) → SandboxHandle
|
||||
wait_ready(handle) → Reachability
|
||||
teardown(handle) → CleanupReport
|
||||
estimate_cost?(profile, duration) → MeterQuote # optional; SaaS only
|
||||
```
|
||||
|
||||
Registration requirements (validated at load time):
|
||||
|
||||
- `id` — unique extension identifier (`ext.<name>`)
|
||||
- `capabilities` — isolation levels, regions, persistence, pricing model
|
||||
- `handler` — Python entry point or built-in registry binding
|
||||
|
||||
Extensions are discovered from `extensions/*.yaml` at repo root and loaded via
|
||||
`sandboxer.extensions.registry`.
|
||||
|
||||
---
|
||||
|
||||
## Routing policy vocabulary
|
||||
|
||||
When multiple extensions satisfy a profile capability:
|
||||
|
||||
| Strategy | Behavior |
|
||||
|----------|----------|
|
||||
| `prefer-self-hosted` | Self-hosted extensions first; SaaS fallback (default Coulomb posture) |
|
||||
| `lowest-cost` | Cheapest `estimate_cost` quote wins |
|
||||
| `lowest-latency` | Closest region / host wins |
|
||||
| `explicit` | Profile names a single `extension`; no auto-routing |
|
||||
|
||||
v0 resolves `profile.extension` directly — routing engine deferred to SAND-WP-0006.
|
||||
|
||||
---
|
||||
|
||||
## Security limits
|
||||
|
||||
sand-boxer commits to:
|
||||
|
||||
1. **Default-deny network** unless profile explicitly allows egress
|
||||
2. **Secrets at provision boundary** — `secret_refs` resolved via ops-warden /
|
||||
OpenBao; never returned to agent context
|
||||
3. **Blast-radius isolation** — dedicated hosts (sandboxer01, CoulombCore) away
|
||||
from Railiance01 production
|
||||
4. **Observable lifecycle** — every transition attributed to `adm` / `agt` / `atm`
|
||||
5. **Honest limits** — allowed tool paths can be abused by compromised agents
|
||||
|
||||
sand-boxer does **not** provide intent-aware egress filtering in v1.
|
||||
|
||||
---
|
||||
|
||||
## Out of scope (sibling ownership)
|
||||
|
||||
| Concern | Owner |
|
||||
|---------|-------|
|
||||
| Agent gateway, tools, memory | glas-harness |
|
||||
| e2e.yml semantics, health checks, test pass/fail | wise-validator |
|
||||
| Code generation, setup instructions content | snuggle-inventor |
|
||||
| SSH tunnels | ops-bridge |
|
||||
| SSH certificates | ops-warden |
|
||||
| Workstream / task state | state-hub |
|
||||
|
||||
See `docs/integrations/` for per-sibling contracts.
|
||||
Reference in New Issue
Block a user