Contracts

Value objects that cross a boundary: they hold only HarnessWeaver types (RULES R7), and each has a JSON Schema in contracts/schemas/ (Contracts).

Messages

Message

Bases: _Contract

One message in a model conversation.

Role

Bases: StrEnum

Who wrote a message.

ModelRequest

Bases: _Contract

A request to a model, by alias or concrete model name.

ModelResponse

Bases: _Contract

A model's answer.

ToolCall

Bases: _Contract

A tool call proposed by a model.

ToolSpec

Bases: _Contract

A tool as offered to a model.

StreamChunk

Bases: _Contract

One piece of a streamed model response.

Usage

Bases: _Contract

Token usage of one or more model calls.

The envelope

Envelope

Bases: BaseModel

The immutable context every hook event carries.

clock property

clock: Clock

The clock decisions should use. Not part of the serialized envelope.

new classmethod

new(
    *,
    tenant: str,
    principal: Principal | str,
    task: str | None = None,
    task_version: str | None = None,
    budget: Budget | None = None,
    clock: Clock | None = None,
    run_id: str | None = None,
    parent_run_id: str | None = None,
    idempotency_key: str | None = None,
    trace_id: str | None = None,
    attributes: dict[str, str] | None = None,
) -> Self

Build the envelope for a new run. The deadline comes from budget.deadline.

with_labels

with_labels(labels: Labels) -> Self

Return a copy with new labels (the clock is kept).

with_clock

with_clock(clock: Clock) -> Self

Return a copy that uses clock.

remaining

remaining() -> timedelta | None

Time left before the deadline (never negative), or None without a deadline.

Principal

Bases: BaseModel

Who a run acts for.

has_role

has_role(role: str) -> bool

Return whether the principal holds role.

Labels

Bases: BaseModel

What kind of data a run has touched. Drives the lethal-trifecta check (RULES S3).

mark_untrusted

mark_untrusted(source: str | None = None) -> Self

Return labels recording that untrusted content entered the run.

mark_private

mark_private(source: str | None = None) -> Self

Return labels recording that the run holds private data.

Budget

Bases: BaseModel

Limits for one run. None means no limit at this layer.

intersect

intersect(other: Budget) -> Budget

Return the tightest combination of two budgets (each limit's minimum).

Clock

Bases: ABC

The source of time for everything that makes decisions (RULES C4).

now abstractmethod

now() -> datetime

Return the current time as a timezone-aware UTC datetime.

is_weekend

is_weekend() -> bool

Return whether it is Saturday or Sunday (UTC).

SystemClock

Bases: Clock

The real clock. All instances are the same clock, so they compare equal.

FakeClock

FakeClock(start: datetime | None = None)

Bases: Clock

A clock that only moves when told to. For tests (RULES T8).

It starts on Monday 2026-01-05 09:00 UTC unless given a start time.

advance

advance(delta: timedelta | str | float) -> None

Move the clock forward by a duration such as "5m".

set

set(moment: datetime) -> None

Jump to a specific, timezone-aware moment.

RunContext

RunContext(
    *,
    envelope: Envelope,
    bus: HookBus,
    trace: RunTrace,
    meter: BudgetMeter,
    models: ModelAccess | None = None,
    tools: ToolBackend | None = None,
    task: TaskInfo | None = None,
    prompts: PromptSource | None = None,
    grants: Iterable[Grant] = (),
    on_chunk: Callable[[StreamChunk], None] | None = None,
    harness: object = None,
    can_suspend: bool = True,
    telemetry: Telemetry | None = None,
    governor: ToolGovernor | None = None,
    policy: PolicyEngine | None = None,
    context: ContextGovernor | None = None,
    memory: Memory | None = None,
    memory_ttl: timedelta | None = None,
    context_ids: Iterable[str] = (),
    recorder: Callable[[RecordedCall], Awaitable[None]]
    | None = None,
    recorded: int = 0,
    replaying: bool = False,
    grant_scope: Literal["call", "run"] = "call",
)

Bases: StepChecks, ModelCalls, ToolCalls

The state of one run and its governed operations.

Parameters:

Name	Type	Description	Default
envelope	Envelope	The run's envelope; its clock is the run's clock.	required
bus	HookBus	The harness's hook bus.	required
trace	RunTrace	Where every outcome is recorded (R13).	required
meter	BudgetMeter	The run's budget meter.	required
models	ModelAccess | None	Model access.	None
tools	ToolBackend | None	Tool backend.	None
task	TaskInfo | None	The task being run, if any.	None
prompts	PromptSource | None	Where prompts come from.	None
grants	Iterable[Grant]	Approvals already given (when resuming).	()
on_chunk	Callable[[StreamChunk], None] | None	Called with each streamed chunk after stream.chunk.	None
harness	object	The owning harness, for runners that build sessions.	None
telemetry	Telemetry | None	Where spans and metrics go; None records none.	None
can_suspend	bool	Whether Suspend may pause this run. Standalone sessions can't be resumed, so there it escalates instead (DESIGNS No. 15).	True

activate

activate() -> Generator[RunContext]

Make this the current run for the enclosed code (see current_run).

current_run

current_run() -> RunContext | None

The run active in this task, for adapters and built-in middleware.

Decisions and guards

Decision

Bases: BaseModel

A router's answer, with the stage and reason that produced it (R13).

DecisionKind

Bases: StrEnum

How a decision was reached.

DecisionRequest

Bases: BaseModel

A question for a router: pick one of options for text and state.

GuardResult

Bases: BaseModel

A guardrail's verdict on one piece of content.

GuardAction

Bases: StrEnum

What a guardrail wants done with the content it checked.

The guardrails module maps actions onto hook outcomes (DESIGNS No. 9).

Finding

Bases: BaseModel

Something a guardrail found. Never holds the raw matched text (R9).

Policy

PolicyEffect

Bases: StrEnum

The outcome of a policy check, from most to least permissive.

PolicyRequest

Bases: BaseModel

The question a PolicyEngine answers: may this run, or this call, go ahead?

variables

variables() -> dict[str, JsonValue]

The names a rule's when sees, as plain JSON values.

PolicyDecision

Bases: BaseModel

A PolicyEngine's answer, with the rule that decided it.

tighten

tighten(
    current: PolicyEffect, proposed: PolicyEffect
) -> PolicyEffect

Combine a policy effect with a check that may only make it stricter (R3).

A judge or classifier can turn allow into require_approval or deny, but never the other way round.

Tools

ToolInfo

Bases: BaseModel

The parts of a tool manifest that policies and middleware decide on.

ToolResult

Bases: BaseModel

What a tool returned. Output is untrusted unless the manifest says otherwise (S3).

ToolVerdict

Bases: BaseModel

What the governor decided about one call, and at which of its steps (DESIGNS No. 17).

ToolManifest

Bases: _Strict

A kind: Tool document.

info

info() -> ToolInfo

The facts policies and middleware decide on.

tool_spec

tool_spec() -> ToolSpec

The tool as offered to a model.

computed_digest

computed_digest() -> str

The digest of the definition as written; compare with definition_digest.

definition_digest

definition_digest(
    name: str,
    description: str,
    input_schema: dict[str, JsonValue],
) -> str

The digest that pins what a model is told about a tool (S2, rug-pull defense).

Risk

Bases: StrEnum

How much harm a misused call could do.

SideEffect

Bases: StrEnum

What a tool changes when it runs.

Context

ContextItem

Bases: BaseModel

One retrieved document or memory entry.

Acl

Bases: BaseModel

Who may see a retrieved item. An empty list means "no restriction" for that part.

allows

allows(tenant: str, principal: Principal) -> bool

Return whether principal in tenant may see the item.

The tenant must match when tenants are listed. When principals or roles are listed, the principal must be named or hold one of the roles.

Approvals

ApprovalRequest

Bases: BaseModel

A suspended step waiting for a human.

ApprovalDecision

Bases: BaseModel

A human's answer to an ApprovalRequest.