TAI42 — the OS for AI tools

Sandbox contract. Exposes the neutral session models, the resolved SandboxPolicy, the error family, and the Sandbox / SandboxSession / SandboxExecHandle ABCs. WHAT THE CONTRACT CARRIES: the shape of a session request/result, the security policy the kit enforces, the failure family, and the provider face — no logic. WHAT THE KIT OWNS: the shared session ledger, TTL/reap bookkeeping, and the session-create policy chokepoint (a Sandbox / SandboxSession base a provider extends). WHAT A PROVIDER IMPLEMENTS: only its runtime I/O — creating session resources and running exec / file transfers against them.

ExecResult

tai42_contract.sandbox.models.ExecResult

class ExecResult(BaseModel)

The outcome of a completed non-interactive exec. Attributes

Attribute	Type
`exit_code`	`int`
`stdout`	`str`
`stderr`	`str`

Sandbox

tai42_contract.sandbox.base.Sandbox

class Sandbox(ABC)

Abstract sandbox provider for a Tai app. A provider creates/destroys disposable SandboxSession instances and reaps expired ones. The app core depends only on this interface and stays sandbox-agnostic; concrete providers (a container runtime, a direct-host runner) implement it and register via @tai42_app.sandboxes.register_sandbox.

Members

create_session

tai42_contract.sandbox.base.Sandbox.create_session

async create_session(self, spec: SandboxSessionSpec) -> SandboxSession

Create a session from spec or REJECT it with SandboxSpecRejectedError. Parameters

Parameter	Type	Default	Description
`spec`	`SandboxSessionSpec`	—	—

get_session

tai42_contract.sandbox.base.Sandbox.get_session

async get_session(self, session_id: str) -> SandboxSession

Fetch a live session by id. Raise SandboxSessionNotFoundError if absent. Parameters

Parameter	Type	Default	Description
`session_id`	`str`	—	—

list_sessions

tai42_contract.sandbox.base.Sandbox.list_sessions

async list_sessions(self) -> list[SandboxSessionInfo]

The observable state of every live session.

destroy_session

tai42_contract.sandbox.base.Sandbox.destroy_session

async destroy_session(self, session_id: str) -> None

Tear a session down. Idempotent on an already-gone session. Parameters

Parameter	Type	Default	Description
`session_id`	`str`	—	—

reap

tai42_contract.sandbox.base.Sandbox.reap

async reap(self) -> list[str]

Destroy every session past its expires_at and return the destroyed ids.

exec_default_timeout_seconds

tai42_contract.sandbox.base.Sandbox.exec_default_timeout_seconds

exec_default_timeout_seconds: float

The provider’s configured default for one short exec; exec itself still requires timeout_seconds.

reap_interval_seconds

tai42_contract.sandbox.base.Sandbox.reap_interval_seconds

reap_interval_seconds: float

The provider’s configured reap sweep cadence.

SandboxDurability

tai42_contract.sandbox.models.SandboxDurability

SandboxDurability = Literal['ephemeral', 'persistent']

SandboxError

tai42_contract.sandbox.errors.SandboxError

class SandboxError(Exception)

Base for every sandbox failure.

SandboxExecHandle

tai42_contract.sandbox.base.SandboxExecHandle

class SandboxExecHandle(ABC)

A live interactive exec started by SandboxSession.exec_start. CONCURRENCY CONTRACT: write_stdin / close_stdin MUST be safe to call concurrently with active output iteration — a provider that serializes reads and writes on one attach stream does its OWN demux/buffering (a deadlocking handle is non-conformant). A single write_stdin call delivers its bytes intact and in order (the provider must not split or reorder them); a consumer multiplexing a line protocol holds its OWN single-writer lock so each message is one atomic call — the provider does no framing. LIFETIME CONTRACT: kill may be called at any time and more than once. Once the exec has exited it is idempotent and never raises, and the exit status output reports stays the exec’s own; write_stdin then raises a typed SandboxError (never an arbitrary exception). A handle may keep provider resources until kill has returned or its session is destroyed, and the exec’s own exit releases none of them: a consumer done with a handle calls kill.

Members

write_stdin

tai42_contract.sandbox.base.SandboxExecHandle.write_stdin

async write_stdin(self, data: bytes) -> None

Deliver data to the exec’s stdin intact and in order. Parameters

Parameter	Type	Default	Description
`data`	`bytes`	—	—

close_stdin

tai42_contract.sandbox.base.SandboxExecHandle.close_stdin

async close_stdin(self) -> None

Signal end-of-input to the exec.

output

tai42_contract.sandbox.base.SandboxExecHandle.output

output: AsyncIterator[SandboxStreamChunk | SandboxStreamExit]

The interleaved stdout/stderr stream, terminated by one SandboxStreamExit. On timeout_seconds expiry the provider kills the exec and the iterator raises SandboxExecTimeoutError. A provider that reports a failure of the exec itself, such as stdin input it accepted that the exec never got, ends the stream with a SandboxError instead of the exit item. Once kill has returned, the stream ends as that method states, after the output the provider received before the kill, which it still yields, in order.

kill

tai42_contract.sandbox.base.SandboxExecHandle.kill

async kill(self) -> None

Terminate the exec. Idempotent, never raising once the exec has exited, and callable at any time. Once this returns, output ends promptly and raises no timeout, even past the deadline. The output the provider received before the kill, read or not, is still yielded, in order: every whole unit of output (a chunk, a frame, a message) its own process had already taken in from the exec’s transport, its buffered and queued output included. Output not yet taken in at the kill, still on its way or held by the operating system or the exec’s runtime, and the part of a unit still arriving, may end with the exec. The stream then ends with exactly one SandboxStreamExit carrying the exec’s exit status, or with a SandboxError when the provider cannot read that status, which it never invents. A failure of the exec itself that the provider reported before the kill, as output describes, still ends the stream with that SandboxError: the kill never clears it. Whether a kill also stops processes the command started and left running, before or after the command’s own exit, is the provider’s behaviour, stated in its documentation; the contract promises the exec’s own end only.

SandboxExecTimeoutError

tai42_contract.sandbox.errors.SandboxExecTimeoutError

class SandboxExecTimeoutError(SandboxError)

An exec / exec_start exceeded its timeout_seconds. Carries the partial-output LENGTHS (never the content — output may hold secrets read from env) so a caller can log the shape of what was produced before the kill. When the exec’s output ended with the kill, they count every byte the exec produced; when a process the command started still held the output after the kill, they count the output received up to the stop, and a note on the error says so. Attributes

Attribute	Type
`timeout_seconds`	—
`stdout_len`	—
`stderr_len`	—

SandboxFileNotFoundError

tai42_contract.sandbox.errors.SandboxFileNotFoundError

class SandboxFileNotFoundError(SandboxError)

No file exists at the requested path in the session’s workspace. Raised by a provider’s get_file ONLY when path does not exist in the session’s workspace. Every OTHER read failure (an IO/permission/engine error, an unreadable non-file) stays the base SandboxError carrying the real message, so a caller can tell a genuine miss (report the file absent) from a real fault (surface the error), never masking one as the other. Attributes

Attribute	Type
`path`	—

SandboxIsolation

tai42_contract.sandbox.models.SandboxIsolation

SandboxIsolation = Literal['none', 'container', 'vm']

SandboxNetwork

tai42_contract.sandbox.models.SandboxNetwork

SandboxNetwork = Literal['none', 'internal', 'egress']

SandboxPolicy

tai42_contract.sandbox.policy.SandboxPolicy

class SandboxPolicy(BaseModel)

The resolved security policy the kit enforces at session create. egress is the network CEILING (a session’s network must be at-or-tighter); isolation is the strength FLOOR (a session runs at at-least this level); durable gates whether a persistent session is permitted at all; scrub_transcript is carried for the consumer to read — it is applied consumer-side, NOT a create-time gate. It is a pure platform-policy envelope — no consumer concept lives here. Attributes

Attribute	Type
`egress`	`SandboxNetwork`
`isolation`	`SandboxIsolation`
`scrub_transcript`	`bool`
`durable`	`bool`

SandboxSession

tai42_contract.sandbox.base.SandboxSession

class SandboxSession(ABC)

One live sandbox session — the unit a consumer runs code in.

Members

id

tai42_contract.sandbox.base.SandboxSession.id

id: str

This session’s provider-assigned id.

workspace_path

tai42_contract.sandbox.base.SandboxSession.workspace_path

workspace_path: str

The provider’s ABSOLUTE root path for THIS session’s workspace. Also carried on SandboxSessionInfo so a caller can read it off info() too. Anchors the workspace-relative resolution of cwd / path (see the module path contract).

info

tai42_contract.sandbox.base.SandboxSession.info

async info(self) -> SandboxSessionInfo

This session’s observable state.

exec

tai42_contract.sandbox.base.SandboxSession.exec

async exec(
    self,
    argv: Sequence[str],
    *,
    cwd: str | None = None,
    env: dict[str, SecretStr] | None = None,
    stdin: bytes | None = None,
    timeout_seconds: float,
) -> ExecResult

Run argv to completion and return its ExecResult. timeout_seconds is REQUIRED: on expiry the provider kills the exec and raises SandboxExecTimeoutError. env overlays the session’s base spec.env (per-exec keys override on collision). cwd is WORKSPACE-RELATIVE by default (resolved against workspace_path; unset defaults to workspace_path) per the module path contract. Parameters

Parameter	Type	Default	Description
`argv`	`Sequence[str]`	—	—
`cwd`	`str \| None`	`None`	—
`env`	`dict[str, SecretStr] \| None`	`None`	—
`stdin`	`bytes \| None`	`None`	—
`timeout_seconds`	`float`	—	—

exec_start

tai42_contract.sandbox.base.SandboxSession.exec_start

async exec_start(
    self,
    argv: Sequence[str],
    *,
    cwd: str | None = None,
    env: dict[str, SecretStr] | None = None,
    timeout_seconds: float,
) -> SandboxExecHandle

Start argv as an INTERACTIVE exec, returning a SandboxExecHandle. timeout_seconds is REQUIRED: on expiry the provider kills the exec and the handle’s output iterator raises SandboxExecTimeoutError. env and cwd follow the same rules as exec. Parameters

Parameter	Type	Default	Description
`argv`	`Sequence[str]`	—	—
`cwd`	`str \| None`	`None`	—
`env`	`dict[str, SecretStr] \| None`	`None`	—
`timeout_seconds`	`float`	—	—

put_file

tai42_contract.sandbox.base.SandboxSession.put_file

async put_file(self, path: str, data: bytes) -> None

Write data to path (WORKSPACE-RELATIVE by default) in the workspace. Parameters

Parameter	Type	Default	Description
`path`	`str`	—	—
`data`	`bytes`	—	—

get_file

tai42_contract.sandbox.base.SandboxSession.get_file

async get_file(self, path: str) -> bytes

Read path (WORKSPACE-RELATIVE by default) from the workspace. Raise SandboxFileNotFoundError when path does not exist; any other read failure raises the base SandboxError with the real message. Parameters

Parameter	Type	Default	Description
`path`	`str`	—	—

touch

tai42_contract.sandbox.base.SandboxSession.touch

async touch(self) -> None

Extend expires_at by the session’s ttl — a keep-alive turn.

destroy

tai42_contract.sandbox.base.SandboxSession.destroy

async destroy(self) -> None

Tear this session down.

SandboxSessionInfo

tai42_contract.sandbox.models.SandboxSessionInfo

class SandboxSessionInfo(BaseModel)

The observable state of a live session, returned by info() / list_sessions(). Attributes

Attribute	Type
`id`	`str`
`image`	`str`
`workspace_key`	`str`
`workspace_path`	`str`
`durability`	`SandboxDurability`
`created_at`	`datetime`
`expires_at`	`datetime`
`labels`	`dict[str, str]`

SandboxSessionNotFoundError

tai42_contract.sandbox.errors.SandboxSessionNotFoundError

class SandboxSessionNotFoundError(SandboxError)

No live session has the requested id. Attributes

Attribute	Type
`session_id`	—

SandboxSessionSpec

tai42_contract.sandbox.models.SandboxSessionSpec

class SandboxSessionSpec(BaseModel)

The requested shape of one sandbox session. The CONSUMER declares the session it needs; the provider maps each field onto its runtime or REJECTS with SandboxSpecRejectedError what it cannot honor — it never silently downgrades a request. Attributes

Attribute	Type
`image`	`str`
`workspace_key`	`str`
`durability`	`SandboxDurability`
`env`	`dict[str, SecretStr]`
`network`	`SandboxNetwork`
`isolation`	`SandboxIsolation \| None`
`cpu`	`float \| None`
`memory_mb`	`int \| None`
`ttl_seconds`	`int`
`labels`	`dict[str, str]`

SandboxSpecRejectedError

tai42_contract.sandbox.errors.SandboxSpecRejectedError

class SandboxSpecRejectedError(SandboxError)

A SandboxSessionSpec cannot be honored. ONE error for two causes the message distinguishes: EITHER the provider cannot enforce the spec (e.g. persistent on a provider without durable storage, an unenforceable cap) OR the spec violates the operator policy at the kit session-create chokepoint (a network looser than the egress ceiling, an isolation below the floor, persistent while durable is off). The message names which; the family never silently downgrades a rejected spec.

SandboxStreamChunk

tai42_contract.sandbox.models.SandboxStreamChunk

class SandboxStreamChunk(BaseModel)

One interleaved output frame from an interactive exec_start. Attributes

Attribute	Type
`stream`	`Literal['stdout', 'stderr']`
`data`	`bytes`

SandboxStreamExit

tai42_contract.sandbox.models.SandboxStreamExit

class SandboxStreamExit(BaseModel)

The interactive iterator’s final item, carrying the exec’s exit code. Attributes

Attribute	Type
`exit_code`	`int`

SandboxUnavailableError

tai42_contract.sandbox.errors.SandboxUnavailableError

class SandboxUnavailableError(SandboxError)

No sandbox provider is registered. Raised by the facet require_sandbox() acquisition chokepoint so every consumer catches this ONE type when no provider backs the seam.

isolation_strength

tai42_contract.sandbox.policy.isolation_strength

isolation_strength(isolation: SandboxIsolation) -> int

The strength rank of an isolation tier (none < container < vm). Parameters

Parameter	Type	Default	Description
`isolation`	`SandboxIsolation`	—	—

network_openness

tai42_contract.sandbox.policy.network_openness

network_openness(network: SandboxNetwork) -> int

The openness rank of a network tier (none < internal < egress). Parameters

Parameter	Type	Default	Description
`network`	`SandboxNetwork`	—	—

​ExecResult

​Sandbox

​Members

​create_session

​get_session

​list_sessions

​destroy_session

​reap

​exec_default_timeout_seconds

​reap_interval_seconds

​SandboxDurability

​SandboxError

​SandboxExecHandle

​Members

​write_stdin

​close_stdin

​output

​kill

​SandboxExecTimeoutError

​SandboxFileNotFoundError

​SandboxIsolation

​SandboxNetwork

​SandboxPolicy

​SandboxSession

​Members

​id

​workspace_path

​info

​exec

​exec_start

​put_file

​get_file

​touch

​destroy

​SandboxSessionInfo

​SandboxSessionNotFoundError

​SandboxSessionSpec

​SandboxSpecRejectedError

​SandboxStreamChunk

​SandboxStreamExit

​SandboxUnavailableError

​isolation_strength

​network_openness

ExecResult

Sandbox

Members

create_session

get_session

list_sessions

destroy_session

reap

exec_default_timeout_seconds

reap_interval_seconds

SandboxDurability

SandboxError

SandboxExecHandle

Members

write_stdin

close_stdin

output

kill

SandboxExecTimeoutError

SandboxFileNotFoundError

SandboxIsolation

SandboxNetwork

SandboxPolicy

SandboxSession

Members

id

workspace_path

info

exec

exec_start

put_file

get_file

touch

destroy

SandboxSessionInfo

SandboxSessionNotFoundError

SandboxSessionSpec

SandboxSpecRejectedError

SandboxStreamChunk

SandboxStreamExit

SandboxUnavailableError

isolation_strength

network_openness