runtime

Bases: FrozenModel

Cost and token accounting reported by a specialist harness run (ASTR §10.4).

Immutable and extra="forbid" (inherited from :class:FrozenModel). Every field defaults to a zero-ish value so an adapter can report a partial accounting (e.g. a Codex run that surfaces token counts but no dollar cost) without constructing an invalid object.

Attributes:

Bases: FrozenModel

The structured outcome of one specialist harness run (ASTR §10.4).

This is the ONLY thing that crosses the harness boundary back into the swarm's context. It carries a disposition, the artifacts the harness changed, typed findings, evidence refs, a residual-risk note, and resource usage — but never the raw transcript, private chain-of-thought, or full terminal command log (ASTR §10.4; plan §5 "Boundary discipline"). Immutable and extra="forbid" (inherited from :class:FrozenModel), so an out-of-range disposition or an unexpected extra field is rejected at construction rather than silently coerced (AC-2-7).

Attributes:

Bases: Protocol

Structural interface for an autonomous external coding harness (ASTR §10).

A SpecialistRuntime drives one bounded coding task in its own OS subprocess (a Claude Agent SDK query() subprocess, or codex exec) and reports back only a :class:SpecialistResult. This Protocol is defined in strands_teams core without importing any coding-agent SDK or subprocess — the concrete adapters live in strands_teams_runtimes and are injected into the coding tool by dependency injection, so core stays vendor-free (plan §3; research-coding-runtimes.yaml architecture).

Implementations are typically async because they await a subprocess; a runtime_checkable Protocol only checks method presence, not signatures, so both sync and async adapters satisfy it structurally.

The five methods model a submit/poll/collect lifecycle:

• submit(task, *, workspace, model_id, capabilities) — start a harness run rooted at workspace (its only writable root) and return an opaque run-handle/id.
• status(handle) — report the run's current lifecycle state.
• send_input(handle, text) — feed additional input to a running harness.
• cancel(handle) — cancel a running harness (e.g. on a wall-clock timeout).
• collect(handle) — return the :class:SpecialistResult. Returns the structured result only — never the harness raw transcript, private chain-of-thought, or full terminal command log (ASTR §10.4).

submit(task, *, workspace, model_id, capabilities=...)

145
146
147
148
149
150
151
152
153
154

def submit(
    self,
    task: str,
    *,
    workspace: object,
    model_id: str,
    capabilities: Mapping[str, object] | None = ...,
) -> object:
    """Start a harness run rooted at ``workspace``; return an opaque run handle."""
    ...

status(handle)

156
157
158

def status(self, handle: object) -> str:
    """Report the run's current lifecycle state (e.g. ``running`` / ``done``)."""
    ...

send_input(handle, text)

160
161
162

def send_input(self, handle: object, text: str) -> None:
    """Feed additional input to a running harness."""
    ...

cancel(handle)

164
165
166

def cancel(self, handle: object) -> None:
    """Cancel a running harness (e.g. on a wall-clock timeout)."""
    ...

collect(handle)

168
169
170

def collect(self, handle: object) -> SpecialistResult:
    """Return the structured :class:`SpecialistResult` — never the raw transcript (ASTR §10.4)."""
    ...