Run manifests and latency¶

PromptLatencyCollector¶

class PromptLatencyCollector(session: AgentSession)

tau_agent_core.latency.PromptLatencyCollector

Times prompt() calls on one session and partitions the results.

Usage — the prompt boundary is explicit because it is not recoverable from the event stream (a followUp re-entry produces a second full loop bracket inside the same prompt(), so "one bracket per prompt" is false)::

collector = PromptLatencyCollector(session)
with collector.prompt():
    await session.prompt("...")
...
artifact = collector.to_latency_json()

The collector subscribes for its lifetime; call :meth:close (or use it as a context manager) to unsubscribe.

Constructor parameters

session: AgentSession — (no description)

enter¶

__enter__() -> PromptLatencyCollector

tau_agent_core.latency.PromptLatencyCollector.__enter__

No description. This object is marked but undocumented.

exit¶

__exit__(*exc: object) -> None

tau_agent_core.latency.PromptLatencyCollector.__exit__

No description. This object is marked but undocumented.

Parameters

*exc: object — (no description)

anomalies¶

tau_agent_core.latency.PromptLatencyCollector.anomalies: list[str]

Structural violations of the bracket marker seen on this stream.

bare_brackets_outside_prompt¶

tau_agent_core.latency.PromptLatencyCollector.bare_brackets_outside_prompt

No description. This object is marked but undocumented.

close¶

close() -> None

tau_agent_core.latency.PromptLatencyCollector.close

Unsubscribe from the session bus. Idempotent.

prompt¶

prompt() -> Iterator[None]

tau_agent_core.latency.PromptLatencyCollector.prompt

Bracket one prompt() call. Records a sample even if it raises.

A prompt that raised still consumed time and may still have carried a compaction (_maybe_auto_compact emits its agent_end from a finally and then propagates), so dropping the sample would delete exactly the observations the exclusion exists to catch.

samples¶

tau_agent_core.latency.PromptLatencyCollector.samples: list[PromptLatencySample]

Every sample, in order. The raw output §9 rule 2 says to look at first.

to_latency_json¶

to_latency_json() -> dict[str, Any]

tau_agent_core.latency.PromptLatencyCollector.to_latency_json

The latency.json fragment for §5.2's headline number.

Two named populations and no union. There is deliberately no "all" key and no method that computes one: a pooled assembled-turn-latency figure over compacting and non-compacting prompts is the §9 rule 1 failure this module exists to make unavailable.

Raises

RuntimeError — the bracket marker did not hold on this stream. The partition would then be computed from a marker known to be wrong, which is worse than having no artifact.

PromptLatencySample¶

class PromptLatencySample(index: int, started_ms: int, ended_ms: int, total_ms: int, bare_bracket_ms: int, bare_brackets: int, compactions_committed: int, event_types: tuple[str, ...])

tau_agent_core.latency.PromptLatencySample

One prompt() call, timed and classified.

Durations come from AgentEvent.timestamp (milliseconds, stamped by the emitting site) rather than from a clock read in this module, so the sample is measured on the same time base as every other agent-tier stage §9 asks for.

Constructor parameters

index: int — (no description)
started_ms: int — (no description)
ended_ms: int — (no description)
total_ms: int — (no description)
bare_bracket_ms: int — (no description)
bare_brackets: int — (no description)
compactions_committed: int — (no description)
event_types: tuple[str, ...] — (no description)

compaction_bearing¶

tau_agent_core.latency.PromptLatencySample.compaction_bearing: bool

Whether this prompt is excluded from the pooled population.

build_run_manifest¶

build_run_manifest(*, harness: str = HARNESS, compaction_policy: CompactionPolicy, extensions: Sequence[Any] | None = None, **extra: Any) -> dict[str, Any]

tau_agent_core.run_manifest.build_run_manifest

Build the manifest fragment this harness is responsible for.

compaction_policy is keyword-only and has no default, so a manifest cannot be built without making the §16.8 decision. That is the whole mechanism: the option "leave the default" is removed by there not being one.

Parameters

harness: str = HARNESS — the harness identity §5.2 partitions latency by. Defaults to :data:HARNESS; a pi-era run records "pi" and the two are different populations that must never be pooled.
compaction_policy: CompactionPolicy — the run's declared policy.
extensions: Sequence[Any] | None = None — the run's loaded extensions, as returned by sdk.summarize_extensions() (H7, §16.6). None omits the extensions key entirely rather than writing an empty list, so a manifest built by a caller that hasn't threaded this through yet is visibly missing the key rather than silently claiming zero extensions loaded.
**extra: Any — (no description)

Raises

ValueError — extra contains compaction or extensions.

extension_manifest_entries¶

extension_manifest_entries(infos: Sequence[Any]) -> list[dict[str, Any]]

tau_agent_core.run_manifest.extension_manifest_entries

The extensions manifest fragment (H7, SIM_SPEC_v2 §16.6).

infos is whatever :func:~tau_agent_core.sdk.summarize_extensions returned — accepted structurally (name/path/content_hash/ subjects/tools/commands/shortcuts/hooks attributes) rather than by importing :class:~tau_agent_core.sdk.ExtensionInfo, so this module does not have to import sdk (which imports agent_session, which this package's __init__ already loads before run_manifest).

Two runs against the same extension path at different file contents produce different content_hash entries here — that is the entire point (§16.6: "two runs ... at different contents are two experimental conditions carrying one label").

Provisional shape: §16.6 asks this be built to the same diff format as tectum's T4 (tectum-005), which had not landed as of this writing. Coordinated through the format when it exists, not guessed at here.

Parameters

infos: Sequence[Any] — (no description)

require_compaction_policy¶

require_compaction_policy(manifest: dict[str, Any]) -> dict[str, Any]

tau_agent_core.run_manifest.require_compaction_policy

Return the manifest's compaction block, or raise.

The read side of the mandatory-partition-key rule. A consumer that reaches for the policy and finds nothing must stop, not assume: a run whose policy was not recorded cannot be compared to any other run, and "probably the default" is the guess §16.8 exists to prevent.

Parameters

manifest: dict[str, Any] — (no description)

Raises

KeyError — compaction is absent, or harness is absent — the two are reported together because a compaction policy without a harness identity is only half a partition key.
ValueError — the block is present but not a mode-bearing mapping.

summarize¶

summarize(values: list[int]) -> dict[str, Any]

tau_agent_core.latency.summarize

§9's shape: median/p90/p99/max, never a single number.

An empty population reports {"n": 0} and nothing else. A fabricated zero median for a population with no members is a value that reads as a measurement.

Parameters

values: list[int] — (no description)

write_run_manifest¶

write_run_manifest(path: str | Path, manifest: dict[str, Any]) -> Path

tau_agent_core.run_manifest.write_run_manifest

Write manifest as JSON, refusing one that is not partitionable.

The check runs on the way out rather than being left to the reader, so an unlabelled manifest never reaches disk to be trusted later.

Parameters

path: str | Path — (no description)
manifest: dict[str, Any] — (no description)