Waggle OS -- Agent Behavior Visual

Single Agent Flow

From user message to streamed response -- the core request lifecycle

User

Security

LLM / AI

Tool

Gate

Output

💬 User Message

🛡 Injection Scan 3 pattern sets

✨ GEPA Expansion prompt augmentation

⚙ Build System Prompt persona + spec + memory + skills

🧠 Recall Memory hybrid search

📐 Behavioral Spec agent rules

🎭 Persona 22 built-in roles

🤖 LLM Call via LiteLLM router

▶ Stream Tokens SSE: token events

🔧 Tool Calls iterative loop

🔒 Approval Gate autonomy-aware

✅ Response + Memory Save cognify + trace recording

packages/agent/src/agent-loop.ts -- runAgentLoop() packages/agent/src/orchestrator.ts -- buildSystemPrompt(), recallMemory() packages/server/src/local/routes/chat.ts -- SSE streaming + approval hooks

Multi-Agent Orchestration

Parent agent spawns specialist sub-agents for complex tasks via the SubagentOrchestrator

Parent Agent

Sub-Agent

Orchestrator

Result

👑 Parent Agent detects complex task

🎯 Workflow Composer selects execution mode

🏭 SubagentOrchestrator supervisor / worker pattern

PARALLEL EXECUTION

🔍 Researcher role: researcher

Result A

📊 Analyst role: analyst

Result B

💻 Coder role: coder

Result C

📦 Aggregate Results concatenate | last | synthesize

👑 Parent Continues integrates results

packages/agent/src/subagent-orchestrator.ts -- SubagentOrchestrator, WorkflowTemplate packages/agent/src/workflow-composer.ts -- WorkflowPlan, ExecutionMode selection packages/agent/src/capability-router.ts -- per-capability routing

Tool Execution

From LLM tool_call to execution result, with filtering and tiered approval

🤖 LLM emits tool_call name + arguments

🔍 Tool Filter allowlist + denylist + governance

🛡 Scan Arguments anti-injection

🔒 Approval Gate Normal / Trusted / YOLO

⚡ Execute run tool function

↩ Result to LLM next iteration

Autonomy Levels

Normal

Default. Every flagged tool requires explicit user confirmation before execution.

All needsConfirmation tools gated
SSE: approval_required event
User clicks Approve / Deny

Trusted

Auto-approves common write operations. Still gates critical and destructive tools.

file_write, edit_file, bash auto-pass
read_other_workspace auto-pass
Critical blacklist still gated

YOLO

Everything auto-passes except a hardcoded critical blacklist that NEVER auto-passes.

rm -rf stays gated
git push --force to main stays gated
Database drops stay gated

packages/agent/src/tool-filter.ts -- filterToolsForContext() packages/agent/src/confirmation.ts -- needsConfirmationWithAutonomy(), AutonomyLevel packages/agent/src/agent-loop.ts -- tool call processing loop

Skill Request Flow

From skill discovery to installation to pattern promotion across scopes

🤖 Agent detects skill gap capability acquisition

🔎 Search Marketplace MCP catalog + skill store

🔑 Tier Check Free: built-in only / Pro+: marketplace

📥 Install Skill parse frontmatter

✅ Skill Active tools + workflows available

📈 Pattern Promotion personal -> workspace -> team

packages/agent/src/skill-frontmatter.ts -- parseSkillFrontmatter() packages/agent/src/capability-acquisition.ts -- skill gap detection + marketplace search packages/shared/src/tiers.ts -- tier gating for marketplace access packages/shared/src/mcp-catalog.ts -- 148+ MCP server catalog

Streaming UX

SSE events from the server and how the chat UI renders each one

🌐 Server (SSE Source) POST /api/chat -- reply.hijack() -- text/event-stream

event: <type>\ndata: <json>\n\n

🖥 Chat UI (EventSource) renders events as they arrive

SSE Event	Payload	UI Rendering
token	`{content: "..."}`	Appended to the assistant message bubble character by character, creating the typing effect
step	`{content: "Recalling..."}`	Shows a status indicator below the message -- "Recalling relevant memories...", "GEPA: Expanded prompt", budget warnings
tool	`{name, input}`	Tool execution card appears: tool name, collapsible input preview, spinning indicator while running
tool_result	`{name, result, duration, isError}`	Tool card updates: shows result preview, duration badge, green check or red X for errors
gepa_choices	`{original, expanded, choices}`	Expansion card with original vs expanded prompt comparison; clickable choices for ask-first mode
approval_required	`{toolName, args, riskLevel}`	Confirmation dialog: tool name, argument preview, risk level badge, Approve / Deny buttons
model_switch	`{model, reason, primary}`	Toast notification: "Switched to [model] -- [reason]" with the original model shown
file_created	`{filePath, fileAction}`	File creation badge in the message footer -- clickable to open the file in the workspace
notification	`{type, title, body}`	System notification toast (e.g., "Auto-saved 3 memories from this exchange")
done	`{content, usage, toolsUsed}`	Message finalized. Token counter updates. Tool summary shown. Loading state cleared
error	`{message}`	Red error banner in the chat. If retryable, a "Retry" button appears

packages/server/src/local/routes/chat.ts -- sendEvent() helper, all SSE event emissions apps/web/src/ -- chat UI components that consume these events

Workflow Harness

State-machine templates for multi-step tasks with phase gates and trace recording

Harness

Phase

Gate

Evolution

💬 User Task

🎯 Match Harness pattern matching

⚙ Initialize Run state machine created

Research & Verify

1

Research

Gather sources

2

Synthesize

Merge findings

3

Verify

Cross-check

Code Review & Fix

1

Understand

Read context

2

Review

Find issues

3

Fix

Apply fixes

4

Verify

Run tests

🚧 Phase Gate quality + safety checks

💾 Checkpoint phase output saved

📝 Trace Recorded feeds evolution system

🔄 Evolution Feedback traces -> judge -> GEPA -> deploy

packages/agent/src/workflow-harness.ts -- WorkflowHarness, HarnessRunState, advancePhase() packages/agent/src/builtin-harnesses.ts -- 3 built-in templates packages/agent/src/trace-recorder.ts -- TraceRecorder, TraceHandle packages/agent/src/compose-evolution.ts -- EvolveSchema + GEPA composition