ai_ops/docs/session-walkthrough.md

Session Walkthrough (Concrete Example)

This document walks through one successful provider run end-to-end using:

• session id: ui-session-mlzw94bv-cb753677
• run id: 9287775f-a507-492a-9afa-347ed3f3a6b3
• execution mode: provider
• provider: claude
• manifest: .ai_ops/manifests/test.json

Use this as a mental model and as a debugging template for future sessions.

1) What happened in this run

The manifest defines two sequential nodes:

1. write-node (persona: writer)
2. copy-node (persona: copy-editor)

Edge routing is write-node -> copy-node on success.

In this run:

1. write-node succeeded on attempt 1 and emitted validation_passed and tasks_planned.
2. copy-node succeeded on attempt 1 and emitted validation_passed.
3. Session aggregate status was success.

2) Timeline from runtime events

From .ai_ops/events/runtime-events.ndjson:

1. 2026-02-24T00:55:28.632Z session.started
2. 2026-02-24T00:55:48.705Z node.attempt.completed for write-node with status=success
3. 2026-02-24T00:55:48.706Z domain.validation_passed for write-node
4. 2026-02-24T00:55:48.706Z domain.tasks_planned for write-node
5. 2026-02-24T00:56:14.237Z node.attempt.completed for copy-node with status=success
6. 2026-02-24T00:56:14.238Z domain.validation_passed for copy-node
7. 2026-02-24T00:56:14.242Z session.completed with status=success

3) How artifacts map to runtime behavior

Run metadata (UI-level)

state/<session>/ui-run-meta.json stores run summary fields:

• run/provider/mode
• status (running, success, failure, cancelled)
• start/end timestamps

For this run:

{
  "sessionId": "ui-session-mlzw94bv-cb753677",
  "status": "success",
  "executionMode": "provider",
  "provider": "claude"
}

Handoffs (node input payloads)

state/<session>/handoffs/*.json stores payload handoffs per node.

write-node.json:

{
  "nodeId": "write-node",
  "payload": { "prompt": "be yourself" }
}

copy-node.json includes fromNodeId: "write-node" and carries the story generated by the writer node.

Important: this is the payload pipeline edge transfer. If a downstream node output looks strange, inspect this file first.

Session state (flags + metadata + history)

state/<session>/state.json is cumulative session state:

• flags: merged boolean flags from node results
• metadata: merged metadata from node results/behavior patches
• history: domain-event history entries

For this run, state includes:

• flags: story_written=true, copy_edited=true
• history events:
  • write-node: validation_passed
  • write-node: tasks_planned
  • copy-node: validation_passed

Project context pointer

.ai_ops/project-context.json tracks cross-session pointers like:

• sessions/<session>/last_completed_node
• sessions/<session>/last_attempt
• sessions/<session>/final_state

This lets operators and tooling locate the final state file for any completed session.

4) Code path (from button click to persisted state)

1. UI starts run via UiRunService.startRun(...).
2. Service loads config, parses manifest, creates engine, writes initial run meta.
3. Engine runSession(...) initializes state and writes entry handoff.
4. Pipeline executes ready nodes:
   • builds fresh node context (handoff + state)
   • renders persona system prompt
   • invokes provider executor
   • receives actor result
5. Lifecycle observer persists:
   • state flags/metadata/history
   • runtime events (node.attempt.completed, domain.*)
   • project context pointers (last_completed_node, last_attempt)
6. Pipeline evaluates edges and writes downstream handoffs.
7. Pipeline computes aggregate status and emits session.completed.
8. UI run service writes final ui-run-meta.json status from pipeline summary.

Primary entrypoints:

• src/ui/run-service.ts
• src/agents/orchestration.ts
• src/agents/pipeline.ts
• src/agents/lifecycle-observer.ts
• src/agents/state-context.ts
• src/ui/provider-executor.ts

5) Mental model that keeps this manageable

Think of one session as five stores and one loop:

1. Manifest (static plan): node graph + routing rules.
2. Handoffs (per-node input payload snapshots).
3. State (session memory): flags + metadata + domain history.
4. Runtime events (timeline/audit side channel).
5. Project context (cross-session pointers and shared context).
6. Loop: dequeue ready node -> execute -> persist result/events -> enqueue next nodes.

If you track those six things, behavior becomes deterministic and explainable.

6) Debug checklist for any future session id

Given <sid>, inspect in this order:

1. state/<sid>/ui-run-meta.json
2. .ai_ops/events/runtime-events.ndjson filtered by <sid>
3. state/<sid>/handoffs/*.json
4. state/<sid>/state.json
5. .ai_ops/project-context.json pointer entries for <sid>

Interpretation:

1. No session.started: run failed before pipeline began.
2. node.attempt.completed with failureCode=provider_*: provider/runtime issue.
3. Missing downstream handoff file: edge condition did not pass.
4. history has validation_failed: retry/unrolled path or remediation branch likely triggered.
5. ui-run-meta disagrees with runtime events: check run-service status mapping and restart server on new code.