Agent flow concept

This page defines the meaning that the agent-flow surface is allowed to show. It is a visualization of an OMP session shape, not a second OMP runtime. The shipped mock and its two views are documented in agent-flow-prototypes; the surrounding Svelte Flow graph remains a presentation surface, like the focused examples indexed by demos.

The story to make visible

The primary actor is Main, the root session that can launch a task subagent wave. Direct task children occupy a sibling group; a task may launch a nested subagent under its own parent. Sibling agents can exchange messages through the peer-facing hub vocabulary while the parent waits, works, or composes a result. An advisor is different again: it is an observation span attached to a host, not another task in the ownership tree.

A seat is the operator-facing containment context around that work. The useful reading order is operator seat, Main session, direct task children, nested child, and advisor sublane. seat is a visualization field in the mock, not a claim that an OMP JSONL record exposes a canonical seat identifier. The hierarchy answers “where is this session contained?”; the wave view answers “which relations became visible over time?” Neither view is permission to infer execution that was not recorded.

flowchart LR
    Seat["operator seat"] --> Main["Main session"]
    Main --> Wave["task spawn wave"]
    Wave --> TaskA["task subagent"]
    Wave --> TaskB["sibling task"]
    TaskB --> Nested["nested subagent"]
    TaskA -.-> Message["sibling hub message"]
    Message -.-> TaskB
    Main -.-> Advisor["advisor span on host"]
    Main --> Signal["signal wake-up"]
    Signal --> Receipt["live receipt readback"]

The visual vocabulary has a strict division of labour:

• ownership is parent and containment, not a timestamped causal edge;
• activity is a span or state at a chosen time;
• spawn, message, and result are three different relations;
• a signal wakes or nudges a seat, while a receipt readback is later evidence that must be observed;
• a return can be an observed result or yield without proving parent acceptance or terminal process state.

Model and derivation

The normalized real-data target has a Trace containing agents, spans, edges, todos, and turns. Its agent identity includes id, parent, kind, label, start, end, status, and depth; its edge identity includes kind, from, to, t, and an optional spanId. The real schema’s edge kinds are exactly spawn, message, and result. A todo can be blocked; the real agent status union is only running, done, or failed.

The shipped mock uses a smaller declarative vocabulary that is deliberately inspectable:

record	fields and meaning
Scene	id, title, summary, mock: true, durationMs, agents, events
SceneAgent	id, label, role, optional parent, seat, lane
SceneEvent	id, t, kind, actor, optional target, label, optional detail, optional durationMs
EventKind	seat.start, agent.spawn, agent.start, hub.message, agent.block, agent.unblock, agent.result, advisor.span, signal, receipt.readback
Frame	t, agents, messages, advisors, spawned, completed, blocked, signalled, receiptVerified

frameAt(scene, t) is the semantic boundary: it orders the scene events, applies only events at or before t, and returns a new Frame. Frame.agents intentionally excludes advisors; active advisor windows live in Frame.advisors. A hub message has a bounded MESSAGE_FLIGHT_MS of 250 milliseconds, so a travelling pulse is a short presentation of one recorded event rather than a second receive event.

This is a time-indexed projection, not an imperative replay. Seeking recomputes the frame from the selected timestamp; it does not replay sends, mutate a mailbox, or run a child. The same rule means that a future result cannot colour an earlier frame as done. A status is what the evidence says at t, not what the scene eventually says at its end.

Rules that prevent false stories

1. Spawn, message, and result are three relations. agent.spawn expresses a parent launching a child; hub.message expresses a directed peer exchange; agent.result expresses a recorded return toward a parent or explicit target. Ownership through parent is not interchangeable with any of those edges.
2. A hub message is one event. Store one (from, to, t) observation with its event identity and deduplicate any mirrored sender/receiver representation before drawing. Never count the sender record and receiver record as two messages, and never use a message pulse to claim that the recipient read it.
3. Advisors are spans on a host, never task children. Keep an advisor in its attached sublane or Frame.advisors; do not add an advisor to the task fan-out, infer a parent task edge, or turn advisor prose into autonomous work.
4. No frame may be coloured with final state. Derive the visible state from the event prefix through t. A child that is eventually done remains pending, running, waiting, or blocked in earlier frames according to the evidence; an open or unknown end stays open or unknown.
5. A signal is a wake-up. A receipt needs live readback. The signal step can say that a watcher was nudged or a peer was woken, but only an independently observed readback can say that the expected completion receipt was seen. Delivery, acknowledgement, and work completion are separate observations.
6. Return is not terminal completion. A child may yield repeatedly after steering, a child yield may have no matching toolResult, and a parent-side acceptance time may be absent. Draw a result relation when the return is evidenced; do not turn every return into a terminal check or infer success from a last transcript timestamp.

Blocked deserves a special caution. The real normalized schema places blocked on a todo task status, not on Agent.status; an open hub.wait is visible waiting work, not proof of a blocked agent. The mock’s AgentStatus includes pending, waiting, and blocked because the scene needs an explicit illustrative state. A future adapter must preserve that distinction instead of silently presenting the mock union as OMP’s native lifecycle.

Implementation plan and boundaries

The concept can be implemented as four boring layers:

1. Normalize a supported source into stable identifiers, relative times, ownership, spans, typed edges, and provenance. Preserve missing ends and unknown status instead of filling gaps with a final answer.
2. Derive stateAt or frameAt as a pure function of source data and trace time. Pre-index event timestamps, make equal-time ordering stable, and make backward seeks use derivation rather than inverse DOM effects.
3. Project the same frame into two layouts: fixed lanes for temporal waves and seat/session groups for containment. Keep selection, viewport, focus, and theme outside semantic state.
4. Render each relation and state with redundant channels, then expose the same identity through focusable controls, labels, a legend, and an event list. Pause must freeze motion; reduced motion must retain the same endpoints, order, and explanation.

The plan deliberately does not adopt a force-directed constellation, a puppet runtime, an autonomous game world, or a second agent runner. The assistant page’s local-first boundary is a useful precedent: a presentation can explain and propose without pretending to have applied or executed work. Operational publication and runtime evidence remain the responsibility of private page (sign-in required).

Mock data versus a future real adapter

What is mocked now:

• both 24-second scenes, their agent labels, roles, seat paths, lanes, event times, durations, and explanatory details;
• the Main fan-out, sibling messages, nested scout, advisor span, blocked/unblocked branch, result returns, signal, and receipt readback;
• the extended visual status union and the completion meaning shown by the panel;
• the receiptVerified boolean and the bounded message-flight pulse.

What a real adapter would need before it could replace the scenes:

• a declared source and scope, subscribed before work starts; live RPC lifecycle events such as agent_start, agent_end, turn boundaries, and tool execution updates, or a carefully reduced session export with explicit capture completeness;
• spawn joins from task-result progress identifiers and child transcript paths, not guessed header parent ids;
• structured message sender, recipient, and receipt fields, never body regular expressions; one stable message identity even when a source mirrors it;
• separate evidence for child yield, parent acceptance, terminal status, signal delivery, and receipt readback, including repeated yields and open spans;
• provenance and nullable or unknown values for scheduler concurrency, missing ends, model history, process lifetime, and any unsupported relation;
• a host/session mapping for seats that does not confuse a browser projection with process ownership, plus an explicit permission boundary for any readback.

No live adapter is being built now. The route is a deterministic, authored mock and carries a visible MOCK DATA marker. It does not read OMP sessions, subscribe to RPC, connect to Collab, poll a registry, or claim that a signal or receipt happened outside the scene definition.

Research provenance

The following sources were opened before citation. Each entry records both the part used and the tempting interpretation that was rejected.

• /home/loca/dev/sflw-research/2026-09-15_agent-trace-viz/spec/TRACE-SCHEMA.md — heading # Normalized trace schema v1 (zero-text) and heading ## Reduction from omp session JSONL (observed 2026-09-15, omp session format version: 3).
  • Contributed: the Trace, Agent, Span, Edge, TodoSnapshot, and Turn field vocabulary; relative milliseconds; text-free export; and the strict spawn/message/result edge set.
  • Rejected: treating the schema’s Agent.status as a source for blocked state or treating a null end as success, because the schema only names running, done, and failed and keeps open ends open.
• /home/loca/dev/sflw-research/2026-09-15_agent-trace-viz/notes/07-omp-trace-source.md — heading # omp session JSONL as a multi-agent trace source: what is reconstructable, heading ### On-disk topology and reconstructable identity, and heading ### What the persisted files do not reconstruct.
  • Contributed: the real OMP path convention, task-result details.progress[] join, structured Hub message fields, repeated-yield observation, and the list of lifecycle facts that persisted JSONL cannot prove.
  • Rejected: foreign header parent ids, body parsing, last-line-as-done, and session_exit as a successful child completion, because the observed capture disproved each shortcut.
• /home/loca/dev/sflw-research/2026-09-15_agent-trace-viz/notes/08-verification-log.md — heading # Verification log — integrator checks (2026-09-15) and heading ## 4. Proof defects found in the browser and fixed (all [O]).
  • Contributed: the mirrored-message dedup key, the open-yield handling, and the regression where final status leaked backward into earlier frames.
  • Rejected: keyed rendering or state derivation that assumes one source row is one unique message or that an agent’s final status is valid at every earlier timestamp.
• /home/loca/dev/sflw-research/2026-09-15_agent-trace-viz/notes/02-trace-visual-grammar.md — heading # The visual grammar of traces: flame, waterfall, swimlane, storyline, git-graph and friends, heading ### Swimlanes plus typed edges are the replay base layer, and heading ### Track and waterfall views preserve elapsed work.
  • Contributed: fixed identity lanes, a shared time axis, typed edge signatures, and the distinction between ownership nesting and elapsed spans.
  • Rejected: a flame graph as the default replay, a force-directed constellation, and any layout that merges sibling identity or implies causality from proximity.
• /home/loca/dev/sflw-research/2026-09-15_agent-trace-viz/notes/04-replay-scrubbing-time-model.md — heading # Replay, scrubbing and the time model: from session-replay players to trace formats, heading ### Pure derived state and source limits, heading ### Constructing the warp from actual work, and heading ### Semantics of compression and live capture.
  • Contributed: view = f(trace, t), half-open span intervals, timestamp-derived seeking, and the reversible bounded-gap idea for skip-idle.
  • Rejected: shipping skip-idle or interpreting an unobserved gap as idle in this mock; the route keeps its authored 24-second clock and does not invent hidden activity.
• /home/loca/dev/sflw-research/2026-09-15_agent-trace-viz/notes/05-multi-agent-topology-vis.md — heading # Visualizing spawn, fan-out, fan-in and hub messaging between agents, heading ### Three relations, three persistent signatures, heading ### Recommendation for 1 main + 7 tasks + 1 nested + advisors, and heading ### Motion and interaction contract.
  • Contributed: the hierarchy-first lane order, nested child placement, advisor sublane, fork/message/return signatures, bounded motion, and 24-pixel interaction targets.
  • Rejected: message bundling as a new broadcast event, radial presentation, reply arrows unsupported by the source, and colour as the sole relation or state carrier.
• /home/loca/dev/sflw-research/2026-09-15_agent-trace-viz/notes/06-zero-word-encoding-and-a11y.md — heading # Zero-word encoding: what shape, colour and motion can carry alone — and how to keep it accessible, heading ### WCAG 2.2 checklist for the zero-word surface, and heading ### Names, descriptions and status are not visual text.
  • Contributed: shape, outline, position, accessible names, focusable descriptions, contrast, pause, reduced motion, and non-hover discovery as part of the rendering contract.
  • Rejected: hover-only explanations, colour-only state, decorative motion as a substitute for quantity, and an inaccessible wordless graphic.
• /home/loca/dev/sflw-research/2026-09-15_agent-trace-viz/STAGE.md — heading # The Stage — an agent office puppet theater above the trace, heading ## 1. One data model, two views, and heading ## 4. The five show beats.
  • Contributed: the fixed-seat metaphor, Main/direct-task/nested/advisor spatial grammar, shared-time two-view idea, and the principle that the presentation must not invent work.
  • Rejected: an autonomous game-world runtime and the terminal plaque attached to every RETURN beat, because repeated yields make return different from terminal completion.
• /home/loca/dev/sflw-research/2026-09-15_agent-puppet-control/spec/SPEC.md — heading # Puppet YAML v1 — spec (drafted before research 2026-09-15, refined after the six notes and the live proof), heading ## 2. Cue forms (all normalize to the canonical form in §5), heading ## 4. Layers and sequencing rules, and heading ## 5. Canonical cue (compiler input) and timeline item (compiler output).
  • Contributed: declarative cue thinking, actor/layer rows, absolute at, relative delay, monotonic cursor, and flat timeline output as useful vocabulary for deterministic presentation.
  • Rejected: Puppet YAML as the agent-trace source, its rig/clip runtime, and any claim that it supplies an ease field; v1 has no ease/easing key.
• /home/loca/dev/sflw-research/2026-09-15_agent-puppet-control/spec/puppet.schema.json — JSON title and description fields for Puppet YAML v1 scene, plus the scene, layer, and canonical-cue definitions (this file has no Markdown headings).
  • Contributed: confirmation that the puppet contract is a strict scene/cue schema with bounded layers, not a live OMP trace schema.
  • Rejected: importing its additionalProperties: false cue contract or actor rig assumptions into the mock’s SceneEvent; the two data models serve different sources.
• /home/loca/dev/sflw-research/2026-09-15_agent-puppet-control/proof/scenes/kitchen.yaml — top-level scene: mapping and cues including together, at 12s, delay, and all (YAML has no Markdown headings).
  • Contributed: a concrete example of explicit parallel and absolute-time choreography.
  • Rejected: using a kitchen puppet scene as evidence of agents, messages, or completion; it is a 3D choreography fixture, not OMP telemetry.
• /home/loca/dev/sflw-research/2026-09-15_agent-puppet-control/proof/README.md — heading # Puppet YAML proof, heading ## What the proof compiles, and heading ### Live player — served over HTTP in Chromium (headless, SwiftShader).
  • Contributed: the proof discipline that seek reconstructs state from absolute time and that compiled output should be inspectable.
  • Rejected: its Three.js player, rig assets, and runtime as the SvelteKit implementation; the proof explicitly has no Svelte runtime.
• /home/loca/dev/sflw-research/2026-09-15_agent-puppet-control/sum.yml — top comment # sum.yml — everything established in 2026-09-15_agent-puppet-control, condensed and key improvements.v1_1 (YAML has no further Markdown headings).
  • Contributed: the negative fact that ease and easing are backlog improvements, not Puppet v1 fields.
  • Rejected: attributing an easing API or borrowed easing semantics to this route; no such v1 contract exists.
• /home/loca/dev/sflw-research/2026-09-15_agent-puppet-control/viz/timeline-lanes.svg — SVG text labels solid = clip, hatched = procedural, and dashed border = idle fill (SVG has no Markdown heading).
  • Contributed: hatching and dash patterns as non-colour channels for timeline meaning.
  • Rejected: importing clip, procedural, or idle-fill semantics into OMP agent state; only the redundant visual-channel lesson transfers.
• /home/loca/dev/sflw-research/2026-09-15_agent-puppet-control/viz/cue-anatomy.svg — SVG text label One cue, three forms, one runtime call — nothing else exists in Puppet YAML v1 and the CANONICAL cue panel (SVG has no Markdown heading).
  • Contributed: the value of one normalized, inspectable intermediate representation.
  • Rejected: treating an agent-flow event as a Puppet cue or implying that a future adapter is a new scene DSL.
• /home/loca/dev/sflw-research/2026-09-15_agent-trace-viz/viz/channel-budget.svg — SVG labels icon silhouette, ring / terminal, solid fill, bounded motion, and horizontal extent (SVG has no Markdown heading).
  • Contributed: redundant channels for kind, state, completion, motion, and duration.
  • Rejected: making colour or motion carry a relation alone; every important distinction gets a static twin.
• /home/loca/dev/sflw-research/2026-09-15_agent-trace-viz/viz/lanes-anatomy.svg — SVG callouts lane head: kind glyph + alive dot; ring becomes ✓/✗ at end, hub.wait: dashed, low-opacity, no spinner, and message arc + one dot travel 250 ms (SVG has no Markdown heading).
  • Contributed: lane-head/state glyph mapping, quiet waiting, and the bounded message travel cue.
  • Rejected: a spinner that claims work during hub.wait or a terminal glyph before the selected time reaches an evidenced end.
• /home/loca/dev/sflw-research/2026-09-15_agent-trace-viz/viz/glyph-states.svg — SVG labels running at t, done (success), hub.wait (neutral), and blocked (SVG has no Markdown heading).
  • Contributed: bounded running treatment, static reduced-motion ring, check/cross terminals, neutral wait, and barred blocked affordance.
  • Rejected: infinite activity after pause or a final check that leaks backward through the replay.
• /home/loca/dev/sflw-research/2026-09-15_agent-trace-viz/viz/skip-idle-warp.svg — SVG labels gap 2700s → 300s, gap 400s → 300s, and idle gap: min(gap, cap) (SVG has no Markdown heading).
  • Contributed: the distinction between an illustrative chart number and the general bounded-gap rule.
  • Rejected: treating the illustrative 300-second number as a product default; the proof rule is a positive cap and the mock does not ship a warp.
• /home/loca/dev/sflw-research/2026-09-09_omp-cockpit/README.md — heading # OMP Cockpit — existing engines, one operator surface, heading ## Verdict, and heading ## Verification and remaining acceptance boundary.
  • Contributed: the operator-versus-engine boundary, partial coverage language, explicit unknowns, and the acknowledgement-versus-processed distinction.
  • Rejected: assuming a browser card or presence registry exposes every in-process subagent, todo, usage value, or completion state.
• /home/loca/dev/sflw-research/2026-09-09_omp-cockpit/explainer/Xplain.content.json — levels[id=expert], levels[id=fifteen], and distinction Acknowledged versus Completed (JSON has no Markdown headings).
  • Contributed: the plain-language rule that “message received” is not “work finished” and that unknown is not zero.
  • Rejected: using a delivery acknowledgement as a terminal result or filling missing telemetry with a reassuring zero.
• /home/loca/dev/sflw-research/2026-09-14_omp-webgui/notes/01-native-surfaces.md — heading ## Live collab session GUI, heading ### Guest powers versus host-only commands, and heading #### Caveat beneath it.
  • Contributed: host-authoritative session vocabulary, the distinction between view/control guests, and the warning that the existing guest is a surface rather than a new host.
  • Rejected: reconstructing or replacing the native transcript/Hub runtime in this mock, and treating a browser projection as process ownership.
• /home/loca/dev/sflw-research/2026-09-14_omp-webgui/notes/02-drive-seams.md — heading ### Commands and state projection, heading ### Host tools, URIs, and subagents, and heading ### Agent Hub and peer messaging.
  • Contributed: get_subagents, set_subagent_subscription, get_subagent_messages, lifecycle events, and the rule that prompt acceptance is not completion.
  • Rejected: assuming a prompt response, default-off subscription, or delivery acknowledgement supplies a complete child lifecycle; a future adapter must subscribe and correlate explicitly.
• /home/loca/dev/sflw-research/2026-09-14_omp-webgui/notes/04-community-gui.md — heading ## Adopt / reject for a daisy+Svelte OSX GUI and heading ### Reject (explicit).
  • Contributed: the narrow boundary between a useful layout vocabulary and a second runtime, especially the decision that a peer bus is not a GUI.
  • Rejected: importing React/Next/Tauri trees, installing a stale deck as chrome, or treating agent-collective as an omniscient visual source.

See agent-flow-prototypes for the exact shipped route, controls, fields, and honest limitations. Return to index for the wiki map, or use private page (sign-in required) for publication and runtime procedures.