Skip to content

Data contracts

Each of the 15 typed contracts owns a set of facts, with one writer set, a known reader set, and byte-level pins over the frozen surface.

Support levels

These levels describe serialized formats, not Python imports.

Formats are not stable until 1.0. From 1.0, changes will be backwards compatible, and deprecations will carry a warning for a period before removal.

CLI listing rows

agent6.viewmodel.listing · mutable container + 2 frozen turn types

Scan session dirs into the listing rows every front-end's hub shows.

summary_row — Return one listing row as JSON, the shape sessions list --json and /api/hub share.

row_json — Return a listing row and its nested children as JSON.

Public fields: Formats.

  • Written by: ui/cli/sessions_cmds, ui/web/model
  • Read by: app/{btw, child_wait, children, compare, finalize, fork, fork_worktrees, merge_plan, preflight, resume, run, stop}, app/review/recap, harness/review/session, ui/{mcp_server, spawn}, ui/acp/session, ui/cli/{answer_cmd, ask, common, completers, entry, fork, net_cmds, plan_watch, ps_cmd, sessions_compare, sessions_show, steer_cmd, stop_cmd}, ui/telemetry/export, ui/tui/{app, home, new_work}, ui/web/{actions, git_model, review_routes, sse}, viewmodel/{init, children, wire}, viewmodel/session/view
  • Guarded by: test_cli_sessions_list.py (27 test files exercise it)

CLI session status

agent6.ui.cli.sessions_show · mutable container + 1 frozen turn types

agent6 sessions show: one-shot liveness and progress of a session from its dir.

_cmd_status — Print a one-shot liveness and progress summary for a run.

Public fields: Formats.

Live process rows

agent6.ui.cli.ps_cmd · frozen dataclass

agent6 ps: live agent6 sessions across every repository on this machine.

_Row — One live session or machine instance.

Public fields: Formats.

  • Written by: ui/cli/ps_cmd
  • Read by: ui/cli/entry
  • Guarded by: test_ps.py (2 test files exercise it)

Web payloads

agent6.ui.web.model

Build the web UI's JSON payloads.

hub_payload — Return the hub: sessions, machines, drafts, machine files, presets.

conversation_payload — Return a run's conversation and the operator's past inputs, from one read of the log.

config_payload — Return the effective config per leaf, keyed by dotted key.

Public fields: Formats.

  • Written by: ui/web/server
  • Read by: ui/cli/web_cmds, ui/web/{actions, sse}
  • Guarded by: test_web_server.py (11 test files exercise it)

Review read model

agent6.viewmodel.review · frozen dataclass

Fold review evidence and operator history for every session reader.

FindingView — Keep a finding's observations and operator history independently of panel verdicts.

ReviewView — Fold durable review evidence in journal append order.

MergeReviewGuard — Report open grounded blocks and unreadable evidence without enforcing a merge.

Public fields: Formats.

  • Written by: viewmodel/session/{log, state}
  • Read by: app/review/actions, ui/acp/review, ui/cli/sessions_findings, ui/tui/review, ui/web/review_routes, viewmodel/{listing, log_line, receipt, telemetry, transcript, transcript_text}, viewmodel/session/{records, view}
  • Guarded by: test_viewmodel_review.py (5 test files exercise it)

Review records

agent6.review_records · frozen dataclass

Define immutable review evidence and validate review boundary payloads.

ReviewTarget — Identify the immutable trees and path coverage of a review.

ReviewLocation — Name a repository-relative path on one side, with an optional inclusive line range.

Finding — Hold one review finding at a structured location.

ReviewerReply — Validate the verdict and findings returned by a reviewer.

ReviewVerdict — Hold one indexed reviewer's verdict, including an explicit abstention on failure.

LineOrigin — Record byte-level evidence without dating a defect or changing its severity.

FindingObservation — Associate a finding with its panel and the reviewers that reported it.

ReviewPanel — Validate a completed panel's durable evidence, including its worker feedback.

FindingResolution — Record the operator's conclusion without inferring verification success.

FindingAction — Validate an operator request against a known review-state version.

Public fields: Formats.

Conversation

agent6.harness.loop_conversation · mutable container + 5 frozen turn types

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

Conversation — The history as frozen messages plus the rolling cache-mark pair.

  • Written by: harness/loop
  • Read by: harness/{loop_resume, loop_snapshot, loop_state, loop_steer, operator_bridge, parallel_dispatch, provider_call, quiet_turns, standing_goal}, harness/compaction/{driver, rules, window}, harness/verify/gate
  • Guarded by: golden_loop_wire.json (36 test files exercise it)

SessionManifest

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

The manifest.json shape and its one reader; app.stamps is the writer.

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

Public fields: Formats.

  • Written by: app/stamps
  • Read by: app/{child_launch, children, compare, execution, finalize, fork, fork_worktrees, merge, merge_message, merge_plan, parallel_results, preflight, resume, resume_chain, run, undo, worktree_setup, worktrees}, app/review/actions, app/session/{prepare, setup}, models/choices, sessions/{layout, lineage}, tools/sessions, ui/mcp_server, ui/cli/{ask, entry, net_cmds, sessions_cmds, sessions_compare, sessions_prune, sessions_show, steer_menu, stop_cmd}, ui/tui/{app, dashboard_header, diff_pane, home}, ui/web/model, viewmodel/{children, comparison, format, listing, policy, receipt, wire}, viewmodel/session/{status, view}
  • Guarded by: test_sessions_manifest.py (49 test files exercise it)

SessionSnapshot

agent6.harness.loop_snapshot · pydantic model + 1 nested models

Hold a session's end and the snapshot a resume re-enters.

SessionSnapshot — Hold the persisted state of an in-flight session, what a resume re-enters and a fork clones.

field type default
version int SNAPSHOT_VERSION
system str required
messages list[dict[str, Any]] required
tool_calls int required
next_turn 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
verify_ever_failed bool False
gateless_ever_edited bool False
metric_best_score float | None None
metric_at_ceiling bool False
final_verify_id str | None None
verify_tree str | None None
last_verify_ok bool | None None
edited_since_verify bool False
baseline_ok bool | None None
verify_scoped bool False
verify_withheld bool False
memory_written bool False
memory_flip_nudged bool False
ok_tool_calls int 0
standing_tools_mark int -1
standing_fruitless int 0
parallel_groups_dispatched int 0
pins tuple[str, ...] ()
delivered_questions tuple[str, ...] ()
head_sha str ''
graph_version int 0
operator_task str ''
base_sha str ''
  • Written by: harness/loop
  • Read by: app/{execution, finalize, fork, frontend, resume, undo}, harness/{advice, finish_gates, guards, loop_resume, loop_state, loop_steer, metric_rules, quiet_turns}, ui/acp/frontend, ui/cli/ask
  • Guarded by: golden_loop_wire.json (35 test files exercise it)

ToolResult family

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

Typed tool-handler results.

ToolResult — One tool handler's typed result.

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

  • Written by: tools/{command_tools, control_tools, dag_tools, dispatch, edit_diag, fs_tools, nav_tools, skill_tools}
  • Read by: app/review/actions, harness/{guards, loop, memory_touch, metric_sampler, tool_effects}, harness/verify/gate, tools/result_format
  • Guarded by: test_tool_result_wire.py, test_tool_result_summaries.py (38 test files exercise it)

Event union

agent6.viewmodel.events · mutable container + 2 frozen turn types

Read logs.jsonl rows into the journal's records, with the coercions old session dirs need.

Public fields: Formats.

  • Written by: viewmodel/events
  • Read by: app/children, harness/review/session, ui/cli/{ask, console_render, machine_cmds, plan_watch, repl}, ui/tui/machines, viewmodel/{init, listing, log_line, review, telemetry, transcript, transcript_items, transcript_text}, viewmodel/session/{core, log, state}
  • Guarded by: golden_session_logs.jsonl (8 test files exercise it)

MachineSpec

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

The parse boundary of a .asm.toml machine file.

MachineSpec — A parsed .asm.toml machine.

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: app/machine/{bundle, create, host_preflight, run, state_configs}, machine/{init, contracts, dryrun, engine, execution, graph, journal}, ui/cli/{completers, config_cmds, machine_check, machine_cmds, watch}, ui/tui/machines, ui/web/{actions, server, sse}, viewmodel/machine/state
  • Guarded by: test_machine_model.py (16 test files exercise it)

JournalEvent

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

The append-only journal, the snapshots and the single-writer lock of one machine instance.

Members: MachineBegin, StepEvent, MachineNotify, MachineEnd, AttemptSpend

  • Written by: machine/{engine, journal}
  • Read by: app/machine/{crash_spend, run}, machine/{init, contracts, dryrun, execution, live_world}, ui/cli/{machine_cmds, watch}, ui/tui/machines, ui/web/actions, viewmodel/wire, viewmodel/machine/{logs, state}
  • Guarded by: golden_journal.jsonl (13 test files exercise it)

TaskNode

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

The task-graph nodes and the intents that mutate them.

TaskNode — A persisted task-graph node.

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.datetime required
updated_at datetime.datetime required
created_by NodeActor required
commit_sha str ''
notes str ''
standing bool False
graph_version int 0
  • Written by: graph/{curator, storage}
  • Read by: app/merge, graph/{order, replay}, harness/{advice, dag_focus, guards, loop, operator_tasks, parallel_join}, harness/compaction/driver, tools/{dag_tools, schema}, viewmodel/session/state
  • Guarded by: test_graph_storage.py (22 test files exercise it)

Run/machine wire snapshot

agent6.viewmodel.session.view

Render session status, context usage, and the wire snapshot.

session_state_as_dict — Return the wire form of a SessionState, what attach --json and the web serialize.

Public fields: Formats.

  • Written by: viewmodel/machine/state, viewmodel/session/view
  • Read by: ui/acp/updates, ui/cli/{sessions_show, steer_menu}, ui/tui/app, ui/web/{model, sse}, viewmodel/{init, wire}
  • Guarded by: golden_session_state.json, test_viewmodel_state.py (14 test files exercise it)