Architecture Overview

Architecture Overview

Console Interaction Path

Console / Feishu -> Session runtime services -> Scheduler -> Agent

The Console and Feishu adapters share the same session-first conversation semantics:

• Entry adapters handle transport-specific concerns such as SSE, long connections, and message parsing.
• Session runtime services own session lifecycle, runtime routing, and projection assembly.
• Scheduler mediates execution for persistent roots and child agents.
• Agent executes the actual work, with results projected back as SDK execution facts.

Main runtime services

The session runtime service layer includes:

• SessionContextService for session creation and forking
• SessionRuntimeService for routing session input through the scheduler
• SessionViewService for session list and detail projections
• SchedulerTreeViewService for tree responses used by the Console UI

Key Domain Objects

Object	Description
Session	Primary conversation container. Users create, switch, and resume sessions across entrypoints.
Task	Unit of work inside a session. Created implicitly when the first message arrives.
Run	Execution-level realization of task work, derived from SDK run and step records.

Design Principles

1. Console is a projection layer. It views SDK execution facts instead of creating a second execution truth.
2. One session = one task by default. The mental model stays simple.
3. Fork for branching. When work diverges, fork to a new session instead of overloading one thread.
4. Scheduler-mediated execution. Console no longer calls agent.start() directly.
5. RunStep-first projections. Task and run views are built from SDK-provided execution records.

Runtime boundaries

At a high level, Agiwo keeps these layers separate:

• Agent owns prompts, execution, hooks, tools, and step lifecycle
• Scheduler owns orchestration, wake logic, and child runtime control
• storage and trace layers persist runtime facts
• the Console projects those facts back to operators