How JacqOS Runs Agents

Most agent frameworks run your agents inside a workflow graph — step one calls step two, step two calls step three. If step two crashes, you retry from a checkpoint. If two agents need the same data, you wire them together with a message bus.

JacqOS works differently. There is no workflow graph. Instead, your agents run inside a continuous observation-evaluation-effect loop. Observations arrive, the evaluator derives facts and intents, the shell executes effects, and the results become new observations. Every step is durable, traceable, and replayable.

The runtime loop

Here is the complete execution cycle:

Observations → Mappers → Atoms → Evaluator → Facts + Intents → Shell → Effects → new Observations

1. Observations arrive. User input, API responses, timer fires, LLM results — every piece of external evidence enters as an immutable observation in the append-only log.
2. Mappers extract atoms. Your Rhai mappers transform raw observation payloads into semantic atoms — small, typed pieces of evidence the evaluator can reason about.
3. The evaluator derives facts and intents. Your .dh ontology rules run over the atoms to produce derived facts (what the system believes) and intents (what the system wants to do). The evaluator reaches a fixed point before any intent fires.
4. The shell executes effects. Each intent maps to a declared capability (http.fetch, llm.complete, timer.schedule). The shell admits the intent, executes the external call, and records every step as observations.
5. Results feed back. Effect results become new observations, and the cycle repeats until no new intents are derived — the system reaches quiescence.

This loop is not a pipeline that runs once. It runs continuously, re-evaluating after every new observation. Facts can be asserted and retracted as evidence changes.

In live mode, jacqos serve exposes this same loop over local HTTP and SSE: append observations, run a lineage, and subscribe to durable lineage events. Chat and webhook adapters use those same surfaces; they do not get a separate control plane.

Why there is no workflow graph

In a workflow system, truth lives in the current step of the graph. If you need to know what the system believes, you have to inspect which step is active and what state it accumulated along the way.

In JacqOS, truth lives in the derived model — the set of facts the evaluator computes from all observations. There is no “current step.” Every agent sees the same facts, derived from the same evidence, at the same time. If you add a new agent, it reads the same model. If you replay the same observations, you get the same facts.

This eliminates three categories of bugs:

• Stale context. Agents never hold cached copies of state — they query the derived model.
• Ordering dependence. The evaluator derives facts to a fixed point regardless of observation arrival order.
• Hidden state. If a developer cannot see it in observations, atoms, facts, intents, or effects, it does not exist in the system.

Actor identity is provenance, not orchestration

JacqOS records who produced evidence without turning that actor into the runtime’s control plane. The portable observation envelope reserves actor_id, actor_kind, agent_id, authority_scope, model identity, and review identity for audit and cloud handoff. In current local apps, put any identity fields the ontology must reason about in the observation payload and map them into atoms.

The boundary is important:

• agent_id tells you which agent role produced or requested something; it does not create a workflow node.
• authority_scope tells you what authority was claimed; it does not grant permission until your rules accept it.
• review_id and review_digest bind a human decision to evidence; they do not mutate facts directly.
• package_digest and capability bindings still decide which deployed package may execute effects.

This is what lets Studio answer “who did what, and under whose authority?” while replay stays deterministic from the observation log.

Observations are the only truth

The append-only observation log is the single source of truth. Facts are derived, not stored. This means:

• Replay is exact. Run jacqos replay fixtures/happy-path.jsonl and you get the same facts every time, from a clean database.
• Provenance is automatic. Every derived fact traces back to the specific observations that produced it.
• Branching is safe. Fork a child lineage to test a new evaluator version against real observations without affecting the primary lineage.

Effects are declared, not called

Agents do not make API calls directly. Instead, your .dh rules derive intent.* relations, and the shell executes them through declared capabilities:

rule intent.reserve_slot(req, slot) :-
  booking_request(req, _, slot),
  slot_available(slot),
  not booking_terminal(req).

The shell then:

1. Admits the intent (durably recorded before any external call)
2. Executes through the declared capability (http.fetch, llm.complete)
3. Records every step as observations with full provenance

This means effects survive crashes, support reconciliation for ambiguous outcomes, and replay deterministically from recorded provider captures and observations.

The evaluation cycle in practice

Here is what happens when a booking request arrives in the appointment-booking example:

1. An intake.booking_request observation arrives
2. The mapper extracts atoms: booking_request("REQ-1", "Smith", "RS-2024-03")
3. The evaluator derives slot_available("RS-2024-03") from provider data
4. The evaluator derives intent.reserve_slot("REQ-1", "RS-2024-03")
5. The shell admits the intent and calls the clinic API via http.fetch
6. The API response becomes a new observation
7. The evaluator re-runs: slot_hold_active("REQ-1", "RS-2024-03") is derived
8. confirmation_pending is derived, leading to intent.send_confirmation
9. The cycle continues until quiescence

Each step is an observation in the log. Open Studio and trace backward from any fact to the observations that produced it.

Hot reload and feedback loops

During development, the jacqos dev command watches your .dh and .rhai files. When you save a change:

1. The evaluator reloads in under 250ms — no compilation step
2. All facts are re-derived from the existing observation log
3. Any new intents or invariant violations appear immediately

This means your feedback loop is: edit a rule, save, see the new derived facts. No build, no restart, no re-ingestion.

Next steps

• Effects and Intents — declare capabilities, understand the intent lifecycle, and handle crashes
• Live Ingress — append live observations, connect adapters, and subscribe to durable events
• LLM Agents — safely integrate LLMs with the candidate-evidence pattern
• Multi-Agent Patterns — coordinate agents through shared reality
• Crash Recovery — handle ambiguous effect outcomes