Data contracts

Each of the 9 typed contracts owns a set of facts, with one writer set, a known reader set, and byte-level pins over the frozen surface. Every card is generated from the module and class docstrings, so edit those rather than this page.

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, _compactor, _loop_state, _verify_gate}
• Guarded by: golden_loop_wire.json (22 test files exercise it)

SessionManifest

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

Read a session's manifest.json into the typed SessionManifest: the one reader and the on-disk shape, with app.manifest as the writer.

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

• Written by: app/manifest
• Read by: app/{compare, finalize, fork, fork_worktrees, merge, parallel, preflight, resume, run, stop, undo}, models/choices, sessions/layout, tools/sessions, ui/mcp_server, ui/cli/{init, _ask, _steer_menu, net_cmds, sessions_cmds, sessions_compare, sessions_merge, sessions_show}, ui/tui/{app, dashboard}, ui/web/{actions, model}, viewmodel/{format, listing, policy, snapshot, state}
• Guarded by: test_sessions_manifest.py (15 test files exercise it)

SessionSnapshot

agent6.workflows._session_state · pydantic model

Session end and resume: 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.

• Written by: workflows/loop
• Read by: app/{_leg, fork, resume, undo}, workflows/{_advice, _finish_gates, _guards, _loop_state, _metric, _verify_gate}
• Guarded by: golden_loop_wire.json (17 test files exercise it)

ToolResult family

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

Typed tool-handler results: every handler returns one of these frozen values instead of a bare dict. Each owns two representations, the 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, SkillResult, RawResult, BackgroundResult, SessionsResult

• Written by: tools/{_control_tools, _dag_tools, _edit_diag, _fs_tools, _nav_tools, _skill_tools, dispatch}
• Read by: workflows/{_guards, _review, _toolset, _verify_gate, loop}
• Guarded by: test_tool_result_wire.py, test_tool_result_summaries.py (25 test files exercise it)

Event union

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

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

Members: SessionStart, ResumeStart, GraphUpdate, DiffUpdated, AutoCommit, 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, machine_cmds, plan_watch}, ui/tui/{app, conversation, machines}, viewmodel/{init, listing, log_line, state, transcript}
• Guarded by: golden_session_logs.jsonl (5 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: app/machine/{_bundle, _frontend, _preflight, create, run}, machine/{init, dryrun, engine, graph, journal}, ui/cli/{completers, config_cmds, machine_check, machine_cmds, watch}, ui/tui/machines, ui/web/{_sse, actions, server}, viewmodel/machine_state
• Guarded by: test_machine_model.py (12 test files exercise it)

JournalEvent

agent6.machine.journal · tagged union of 5 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 the returned blackboard replaces the current one only then. Replaying the events reproduces the reducer's path exactly.

Members: MachineBegin, StepEvent, MachineNotify, MachineEnd, AttemptSpend

• Written by: machine/{engine, journal}
• Read by: app/machine/{_spend, run}, machine/{init, dryrun}, ui/cli/{machine_cmds, watch}, ui/tui/machines, ui/web/actions, viewmodel/{machine_state, snapshot}
• Guarded by: golden_journal.jsonl (12 test files exercise it)

TaskNode

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

The persistent task-graph models: nodes plus the LLM-emitted curator intents that mutate them, a doubly-linked tree keyed by the run's own task count.

TaskNode — A persisted task-graph node: an id counting up within the run, 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
graph_version	int	0

• Written by: graph/{curator, storage}
• Read by: graph/{order, replay}, tools/{_dag_tools, schema}, workflows/{_advice, _compactor, _dag_focus, _guards, _parallel_dispatch, loop}
• Guarded by: test_graph_storage.py (20 test files exercise it)

Run/machine wire snapshot

agent6.viewmodel.state · mutable container + 12 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/{_interact, _repl, _steer_menu, _task_tree, answer_cmd}, ui/tui/{app, composer, conversation, dashboard, logview, modals, prompts}, ui/web/{_sse, actions, model}, viewmodel/{init, snapshot}
• Guarded by: golden_session_state.json, test_viewmodel_state.py (9 test files exercise it)