Skip to content

Data contracts

Eight typed contracts own facts that used to travel as dict[str, Any], each with one writer set, a known reader set, and byte-level pins guarding its frozen surface. This page is generated by docs/gen_contracts.py from those modules' docstrings and the source tree; edit the docstrings, not this file (regenerate with uv run python docs/gen_contracts.py).

Conversation

agent6.workflows._conversation · mutable container + 5 frozen turn types

The loop-owned conversation: typed turns over the provider wire.

Conversation — Mutable container of frozen turns plus the rolling cache-mark pair.

  • Written by: workflows/{loop}
  • Read by: workflows/{_compaction, _critic}
  • Guarded by: golden_loop_wire.json (13 test files exercise it)

SessionManifest

agent6.sessions.manifest · pydantic model + 6 nested models

Read a session's manifest.json into the typed SessionManifest. The single reader + the on-disk shape; the writer is app.manifest.

SessionManifest — The typed manifest.json a session starts with (and later stamps).

field type default
version int MANIFEST_VERSION
agent6_version str ''
session_id str ''
mode str ''
start_ts str ''
user_task str ''
base_sha str ''
base_branch str ''
run_branch str | None None
models ModelsBrief ModelsBrief()
workflow WorkflowStamp WorkflowStamp()
policy PolicyStamp PolicyStamp()
parked_task str ''
parent_session_id str | None None
forked_from_turn int | None None
forked_from_sha str | None None
merged MergeStamp | None None
parallel_id str | None None
lane int | None None
compare CompareStamp | None None
  • Written by: app/{manifest}
  • Read by: app/{compare, finalize, fork, merge, parallel, resume, run}, tools/{sessions}, ui/{mcp_server}, ui/cli/{_ask, _steer_menu, plan_watch, sessions_cmds}, ui/tui/{app}, ui/web/{model}, viewmodel/{format, listing, policy, state}
  • Guarded by: test_runs_manifest.py (9 test files exercise it)

SessionSnapshot

agent6.workflows._session_state · pydantic model

How a session ends and how it resumes: the SessionResult the workflow returns, the ResumeError it raises, and the provider-agnostic resume snapshot written before each LLM call (load here; the loop owns saving it).

SessionSnapshot — The persisted state of an in-flight session: what resume re-enters and what fork clones.

field type default
version int SNAPSHOT_VERSION
system str required
messages list[dict[str, Any]] required
tool_calls int required
next_iteration int required
root_task_id str | None required
original_task str required
verify_command tuple[str, ...] required
review_rejections_total int 0
verify_ever_passed bool False
gateless_ever_committed bool False
metric_best_score float | None None
metric_at_ceiling bool False
last_verify_ok bool | None None
edited_since_verify bool False
baseline_ok bool | None None
standing_tools_mark int -1
parallel_groups_dispatched int 0
pins tuple[str, ...] ()
head_sha str ''
graph_version int 0
  • Written by: workflows/{loop}
  • Read by: app/{fork, resume, run}
  • Guarded by: golden_loop_wire.json (12 test files exercise it)

ToolResult family

agent6.tools.results · abstract base + 26 frozen result types

Typed tool-handler results: every handler returns one of these frozen values instead of a bare dict, each owning its two representations -- the exact model-facing to_wire() dict and the one-line human summary().

ToolResult — One tool handler's typed result: it owns the model-facing to_wire() dict and its one-line summary().

Members: DocsIndexResult, DocsContentResult, ReadFileResult, ListDirResult, OutlineResult, DefinitionsResult, ReferencesResult, EditResult, PatchResult, PreviewResult, FetchResult, ExecResult, MetricResult, FinishSessionResult, FinishPlanningResult, AnswersResult, AddTaskResult, UpdateTaskResult, ListTasksResult, NotesResult, AddMemoryResult, InvalidateMemoryResult, SkillResult, RawResult, BackgroundResult, SessionsResult

Event union

agent6.viewmodel.events · tagged union of 27 frozen families

Typed read model for the ~22 logs.jsonl event families the SessionState fold consumes.

Members: SessionStart, ResumeStart, GraphUpdate, DiffUpdated, RoleCall, RoleResult, RoleTextDelta, RoleThinkingDelta, ToolCall, ToolResult, VerifyStart, VerifyEnd, BudgetUpdate, ApprovalPrompt, ApprovalAnswer, QuestionPrompt, QuestionAnswer, PinAdded, PinsRestored, CompactRestored, CompactDropped, CompactGists, CompactSummarised, SteerRequested, SessionEnd, SessionUndone, RawEvent

  • Written by: viewmodel/{events}
  • Read by: ui/cli/{_console_view}, ui/tui/{machines}, viewmodel/{init, listing, state, transcript}
  • Guarded by: golden_session_logs.jsonl (4 test files exercise it)

MachineSpec

agent6.machine.model · pydantic model + 13 nested models

Parse and validate a .asm.toml machine file into a MachineSpec.

MachineSpec — A validated .asm.toml machine definition: budget, typed schemas, the named states graph, and an optional agent6 [config] overlay whose operator-only security policy is refused (see PROTECTED_OVERLAY_*) so an untrusted machine file cannot weaken the sandbox.

field type default
machine str required
version Literal[1] required
initial str required
budget BudgetSpec required
vars VarsSection factory
schemas dict[str, dict[str, _FieldSpecT]] factory
states dict[str, StateSpec] required
config dict[str, Any] factory
  • Written by: machine/{_semantics}
  • Read by: machine/{init, dryrun, engine, graph, journal}, viewmodel/{machine_state}
  • Guarded by: test_machine_model.py (4 test files exercise it)

JournalEvent

agent6.machine.journal · tagged union of 4 frozen families

Append-only journal, blackboard snapshots, and the single-writer lock for one machine instance. The journal is the source of truth: the pure reducer validates each impure observation, the validated fact is appended as a JournalEvent, and only then does the returned blackboard replace the current one, so replaying the events reproduces the exact path from the pure reducer.

Members: MachineBegin, StepEvent, MachineNotify, MachineEnd

  • Written by: machine/{engine, journal}
  • Read by: machine/{init, dryrun}, viewmodel/{machine_state}
  • Guarded by: golden_journal.jsonl (7 test files exercise it)

TaskNode

agent6.graph.models · pydantic model + 7 nested models

The persistent task-graph models: nodes plus the LLM-emitted curator intents that mutate them, a doubly-linked tree keyed by time-sortable ULID ids.

TaskNode — A persisted task-graph node: a time-sortable 26-char ULID id, a parent_id/children pair the curator keeps mutually consistent, and a status drawn from the fixed NodeStatus vocabulary.

field type default
id str required
parent_id str | None required
title str required
rationale str ''
acceptance str ''
relevant_paths tuple[str, ...] ()
depends_on tuple[str, ...] ()
children tuple[str, ...] ()
status NodeStatus 'pending'
created_at datetime required
updated_at datetime required
created_by NodeActor required
commit_sha str ''
notes str ''
standing bool False
  • Written by: graph/{curator, storage}
  • Read by: graph/{order, replay}, tools/{_dag_tools, schema}, ui/cli/{_task_tree}, workflows/{_dag_focus, _parallel_dispatch, loop}
  • Guarded by: test_graph_storage.py (11 test files exercise it)

Run/machine wire snapshot

agent6.viewmodel.state · mutable container + 11 frozen turn types

Pure event-fold: list[event_dict] -> SessionState.

session_state_as_dict — The JSON-able wire form of a SessionState, stable field names: what agent6 attach --json and a web client serialize.

  • Written by: viewmodel/{machine_state, state}
  • Read by: ui/cli/{_steer_menu, plan_watch}, ui/tui/{app, conversation, logview, modals}, viewmodel/{init}
  • Guarded by: golden_session_state.json, test_viewmodel_state.py (6 test files exercise it)