Deep Analysis

OpenClaw Prompt Construction & Agent Loop

How a user message flows through string assembly, the pi-agent-core harness, stream wrapping, tool execution, and compaction — with full lineage tracking.

github.com/openclaw/openclaw ~3,290 lines in run/attempt.ts 14 source files analyzed

System Prompt Construction

25+ string components assembled into the final system prompt — exact file lineage

System Prompt Assembly — Flow Diagram

Mermaid

flowchart TB
    subgraph ROOT[" "]
        direction TB
        BOOT["Bootstrap
resolveBootstrapContextForRun()
bootstrap-files.ts"]
        ID["Identity
'You are a personal assistant
 running inside OpenClaw.'"]
        TOOLS["Tooling Section
26 ordered tools
coreToolSummaries map"]
        SAFETY["Safety Constitution
+ CLI Quick Reference
+ Self-Update Rules"]
        DYN1["Skills
buildSkillsSection()"]
        DYN2["Memory
buildMemorySection()"]
        DYN3["Docs
buildDocsSection()"]
        DYN4["Messaging
buildMessagingSection()"]
        DYN5["Voice / Reactions"]
        PROJ["Project Context
context files sorted by
CONTEXT_FILE_ORDER map"]
        RUNTIME["Runtime Footer
SYSTEM_PROMPT_CACHE_BOUNDARY
+ Runtime line
+ Heartbeat"]
        PROVIDER["Provider Transform
transformProviderSystemPrompt()
provider-runtime.js"]
    end
    BOOT --> ID --> TOOLS --> SAFETY --> DYN1 --> DYN2 --> DYN3 --> DYN4 --> DYN5 --> PROJ --> RUNTIME --> PROVIDER
    style BOOT fill:#0a1628,stroke:#00E5FF,stroke-width:2px,color:#00E5FF
    style ID fill:#0a1628,stroke:#c792ea,stroke-width:1px,color:#c792ea
    style TOOLS fill:#0a1628,stroke:#00E5FF,stroke-width:1px,color:#00E5FF
    style SAFETY fill:#0a1628,stroke:#FF00AA,stroke-width:1px,color:#FF00AA
    style DYN1 fill:#0a1628,stroke:#c3e88d,stroke-width:1px,color:#c3e88d
    style DYN2 fill:#0a1628,stroke:#c3e88d,stroke-width:1px,color:#c3e88d
    style DYN3 fill:#0a1628,stroke:#c3e88d,stroke-width:1px,color:#c3e88d
    style DYN4 fill:#0a1628,stroke:#c3e88d,stroke-width:1px,color:#c3e88d
    style DYN5 fill:#0a1628,stroke:#c3e88d,stroke-width:1px,color:#c3e88d
    style PROJ fill:#0a1628,stroke:#FFAB40,stroke-width:1px,color:#FFAB40
    style RUNTIME fill:#0a1628,stroke:#89DDFF,stroke-width:1px,color:#89DDFF
    style PROVIDER fill:#1a0a28,stroke:#c792ea,stroke-width:2px,color:#c792ea

Component Lineage Table — 25 String Components

Component / Function	Source File	Lines	Description
buildAgentSystemPrompt()	src/agents/system-prompt.ts	439–1048	Master builder — orchestrates all sections in order
buildFullBootstrapPromptLines()	src/agents/bootstrap-prompt.ts	1–13	Full bootstrap: read BOOTSTRAP.md, complete workflow
buildLimitedBootstrapPromptLines()	src/agents/bootstrap-prompt.ts	15–25	Limited: explain blocker, suggest next step
BOOTSTRAP.md content	.pi/prompts/cl.md	58 lines	Changelog audit skill — audit entries before release
BOOTSTRAP.md content	.pi/prompts/is.md	22 lines	Issue analysis skill — audit GitHub issues
buildBootstrapPromptWarning()	src/agents/bootstrap-budget.ts	—	Prepends "⚠️ Bootstrap budget..." warning if near limit
buildSkillsSection()	src/agents/system-prompt.ts	156–172	Skills instructions: "scan available_skills..."
buildMemorySection()	src/agents/system-prompt.ts	174–187	Memory citations guidance via plugins/memory-state.ts
buildDocsSection()	src/agents/system-prompt.ts	395–425	Docs links: docs.openclaw.ai, GitHub, Discord, ClawhHub
buildMessagingSection()	src/agents/system-prompt.ts	335–382	sessions_spawn, sessions_send, subagents guidance
buildVoiceSection()	src/agents/system-prompt.ts	384–393	TTS hint via buildTtsSystemPromptHint()
buildHeartbeatSection()	src/agents/system-prompt.ts	127–138	"If heartbeat poll: reply HEARTBEAT_OK"
buildExecutionBiasSection()	src/agents/system-prompt.ts	299–313	"Actionable request: act in this turn..."
Safety Constitution	src/agents/system-prompt.ts	672–678	No independent goals, prioritize safety, no manipulation
CLI Quick Reference	src/agents/system-prompt.ts	777–788	openclaw gateway status/restart, config.schema.lookup
Self-Update Rules	src/agents/system-prompt.ts	793–803	Updates only on explicit user request
Silent Reply Rules	src/agents/system-prompt.ts	955–970	SILENT_REPLY_TOKEN when nothing to say
buildProjectContextSection()	src/agents/system-prompt.ts	95–125	Loads workspace files: agents.md, soul.md, identity.md...
CONTEXT_FILE_ORDER map	src/agents/system-prompt.ts	44–52	File priority: agents.md(10) → soul.md(20) → ... → memory.md(70)
buildWebchatCanvasSection()	src/agents/system-prompt.ts	275–297	[embed...] directives for webchat only
buildOwnerIdentityLine()	src/agents/system-prompt.ts	232–246	"Authorized senders: [hash or raw numbers]"
buildTimeSection()	src/agents/system-prompt.ts	248–253	"## Current Date & Time — Time zone: {tz}"
SYSTEM_PROMPT_CACHE_BOUNDARY	src/agents/system-prompt-cache-boundary.ts	—	"--- SYSTEM PROMPT CACHE BOUNDARY ---" separator
buildRuntimeLine()	src/agents/system-prompt.ts	1006–1048	"Runtime: agent=X \| os=Y \| node=Z \| model=A \| channel=B"
Provider overrides	src/plugins/provider-runtime.js	—	transformProviderSystemPrompt() wraps final output

Context File Loading Priority

Files sorted by CONTEXT_FILE_ORDER map then alphabetically. heartbeat.md is marked dynamic (below cache boundary).

agents.md → 10 soul.md → 20 identity.md → 30 user.md → 40 tools.md → 50 bootstrap.md → 60 memory.md → 70 heartbeat.md → dynamic

Bootstrap Prompt Files

.pi/prompts/cl.md — Changelog Audit

---
description: Audit changelog entries
---
Audit changelog entries for all commits
since the last release.

## Process
1. Find last release tag
2. List commits since that tag
3. Read each package's [Unreleased] section
4. Check: skip changelog updates,
   doc-only, release housekeeping
5. Cross-package duplication rule:
   → duplicate to coding-agent
6. Add New Features section
7. Report missing entries

.pi/prompts/is.md — Issue Analysis

---
description: Analyze GitHub issues
---
Analyze GitHub issue(s): $ARGUMENTS

1. Read the issue in full
2. For bugs:
   - Ignore root cause (likely wrong)
   - Read all related code files
   - Trace code path
   - Propose a fix
3. For features:
   - Read related files
   - Propose concise implementation
   - List affected files

Do NOT implement unless asked.

The Agent Run Attempt

From runEmbeddedAttempt() to the turn loop — all 3,290 lines of the core harness

runEmbeddedAttempt() — High-Level Flow

Mermaid

flowchart TD
    START["User Message
arrives at channel"] --> P1["Phase 1: Setup
AbortController, mkdir
resolveUserPath()"]
    P1 --> P2["Phase 2: Resolve Model
resolveModelAsync()
normalizeResolvedModel()"]
    P2 --> P3["Phase 3: Sandbox
resolveSandboxContext()"]
    P3 --> P4["Phase 4: Session Manager
SessionManager.open()
guardSessionManager()"]
    P4 --> P5["Phase 5: System Prompt
buildSystemPromptOverride()
→ buildEmbeddedSystemPrompt()"]
    P5 --> P6["Phase 6: Tool Setup
splitSdkTools()
createAgentSession()"]
    P6 --> P7["Phase 7: Stream Wrapping
10 x wrapStreamFn()
(stream-resolution.ts)"]
    P7 --> P8["Phase 8: History Prep
sanitizeSessionHistory()
filterHeartbeatPairs()
limitHistoryTurns()"]
    P8 --> P9["Phase 9: Hook Runner
resolvePromptBuildHookResult()
llm_input hooks (async)"]
    P9 --> P10["Phase 10: Prompt Submit
activeSession.prompt()
← THE CORE CALL"]
    P10 --> TURN["Turn Loop
pi-agent-core:
LLM → tool_use →
execute → result →
LLM (repeat)"]
    TURN --> TOOL{"stop_reason
= tool_use?"}
    TOOL -->|Yes| EXEC["Execute Tool
(sequential)"]
    EXEC --> MORE{"More
tool_use?"}
    MORE -->|Yes| EXEC2["Next Tool"]
    EXEC2 --> MORE
    MORE -->|No| NEXT["Next LLM call"]
    NEXT --> TURN
    TOOL -->|No| DONE["Return final answer"]
    DONE --> COMP{"Overflow?"}
    COMP -->|Yes| COMPACT["Compaction
(background)"]
    COMP -->|No| RESULT[("EmbeddedRunAttempt
Result")]
    style START fill:#0a1628,stroke:#00E5FF,stroke-width:2px,color:#00E5FF
    style P10 fill:#0a1628,stroke:#FFAB40,stroke-width:2px,color:#FFAB40
    style TURN fill:#0a1628,stroke:#FFAB40,stroke-width:2px,color:#FFAB40
    style EXEC fill:#0a1628,stroke:#FF00AA,stroke-width:1px,color:#FF00AA
    style EXEC2 fill:#0a1628,stroke:#FF00AA,stroke-width:1px,color:#FF00AA
    style COMPACT fill:#1a0a28,stroke:#c792ea,stroke-width:2px,color:#c792ea
    style DONE fill:#0a2820,stroke:#c3e88d,stroke-width:2px,color:#c3e88d

runEmbeddedAttempt() — 12-Phase Breakdown

Phase	Lines	Key Functions	Purpose
1. Setup	579–610	resolveUserPath(), AbortController, mkdir workspace	Resolve paths, create abort controller, ensure workspace exists
2. Model Resolution	—	resolveModelAsync(), normalizeResolvedModel()	Resolve provider, model ID, API format (openai/anthropic/etc.)
3. Sandbox	—	resolveSandboxContext()	Determine if running in Docker sandbox, mount paths
4. Session Manager	1284–1290	SessionManager.open(), guardSessionManager()	Open/update session file, install tool result guards
5. System Prompt	1200–1201	buildSystemPromptOverride() → buildEmbeddedSystemPrompt()	Assemble all 25+ prompt components from Section 01
6. Tool Setup	1330–1413	splitSdkTools(), toClientToolDefinitions(), createAgentSession()	Build tool allowlist, create session with tools
7. Stream Wrapping	1556–1866	10 x wrapStreamFn*() wrappers	Wrap streamFn with transforms (see Section 03)
8. History Prep	1869–1967	sanitizeSessionHistory(), limitHistoryTurns(), filterHeartbeatPairs()	Prune, truncate, sanitize transcript before LLM call
9. Hook Runner	2258–2267	resolvePromptBuildHookResult()	Fire llm_input hooks (async, fire-and-forget)
10. Prompt Submit	2649–2702	activeSession.prompt() — THE CORE CALL	Send to LLM; pi-agent-core handles turn loop internally
11. Compaction Wait	2750–2784	waitForCompactionRetryWithAggregateTimeout()	Wait for background compaction (up to 60s aggregate)
12. Result Return	—	EmbeddedRunAttemptResult	Return transcript, usage metrics, compaction count

Key Insight: Turn Loop is Inside pi-agent-core

activeSession.prompt() delegates the turn loop to @mariozechner/pi-agent-core. That library's prompt() method:

Sends the current transcript (messages + system prompt) to the LLM API
Receives a streaming response
When the model emits tool_use blocks → executes tools sequentially
Appends each tool_result back to the transcript
Loops back until stop_reason ≠ "tool_use"
Emits streamed text blocks back to OpenClaw via subscription callbacks

Stream Wrapping Chain

10 sequential wrappers applied bottom-up to transform the raw LLM stream

Stream Wrapper Stack — Applied Bottom-Up

Mermaid

flowchart LR
    subgraph WRAPPERS["Wrappers Applied Bottom-Up (outermost = last applied)"]
        W10["10 Diagnostic Events
wrapStreamFnWith
DiagnosticModelCallEvents()
attempt.ts:1853"]
        W9["9 Idle Timeout
streamWithIdleTimeout()
llm-idle-timeout.ts"]
        W8["8 Sensitive Stop
wrapStreamFnHandle
SensitiveStopReason()
attempt.ts:1829"]
        W7["7 Payload Logger
createAnthropic
PayloadLogger().wrap()
anthropic-payload-log.ts"]
        W6["6 XAI HTML Decode
wrapStreamFnDecode
XaiToolCallArguments()
attempt.ts:1816"]
        W5["5 Argument Repair
wrapStreamFnRepair
MalformedToolCall
Arguments()
attempt.ts:1810"]
        W4["4 Trim Tool Names
wrapStreamFnTrim
ToolCallNames()
attempt.ts:1796"]
        W3["3 Sanitize Tool Calls
wrapStreamFnSanitize
MalformedToolCalls()
attempt.ts:1791"]
        W2["2 Yield Abort Gate
anonymous closure
attempt.ts:1778"]
        W1["1 Provider Transport
resolveEmbedded
AgentStreamFn()
stream-resolution.ts:64"]
    end
    MODEL["LLM API
Provider Transport"] --> W1 --> W2 --> W3 --> W4 --> W5 --> W6 --> W7 --> W8 --> W9 --> W10 --> OUTPUT["Final Stream
to UI / Subscription"]
    style W1 fill:#0a1628,stroke:#00E5FF,stroke-width:2px,color:#00E5FF
    style W10 fill:#1a0a28,stroke:#c792ea,stroke-width:2px,color:#c792ea
    style W9 fill:#1a0a28,stroke:#89DDFF,stroke-width:1px,color:#89DDFF
    style W8 fill:#1a0a28,stroke:#FF5252,stroke-width:1px,color:#FF5252
    style OUTPUT fill:#0a2820,stroke:#c3e88d,stroke-width:2px,color:#c3e88d

Stream Wrapper Detail

#	Wrapper Function	Source	What It Does
1	resolveEmbeddedAgentStreamFn()	stream-resolution.ts:64	Selects transport: OpenAI WS, Anthropic Vertex, or pi streamSimple
2	Yield Abort Gate	attempt.ts:1778	Intercepts "sessions_yield" abort; returns createYieldAbortedResponse()
3	wrapStreamFnSanitizeMalformedToolCalls()	attempt.ts:1791	Fixes malformed tool call JSON in streaming response
4	wrapStreamFnTrimToolCallNames()	attempt.ts:1796	Trims whitespace from tool names; guards against unknown-tool loop (3 strikes)
5	wrapStreamFnRepairMalformedToolCallArguments()	attempt.ts:1810	Repairs malformed JSON args in tool call input blocks
6	wrapStreamFnDecodeXaiToolCallArguments()	attempt.ts:1816	Decodes HTML entities (e.g. <) in xAI tool call arguments
7	createAnthropicPayloadLogger().wrapStreamFn()	anthropic-payload-log.ts	Logs full request/response payloads for debugging
8	wrapStreamFnHandleSensitiveStopReason()	attempt.ts:1829	Catches provider-specific "sensitive" stop reasons before error bubble
9	streamWithIdleTimeout()	llm-idle-timeout.ts	Aborts if model is silent for > idleTimeoutMs (configurable per trigger)
10	wrapStreamFnWithDiagnosticModelCallEvents()	attempt.ts:1853	Emits diagnostic events per model API call (runId, sessionId, provider...)
Conditional wrappers (applied additionally when conditions are met):
C1	wrapStreamFnTextTransforms()	plugin-text-transforms.ts	Provider-specific input/output text transforms
C2	cacheTrace.wrapStreamFn()	cache-trace.ts	Records prompt cache stages for observability
C3	Google Prompt Cache	google-prompt-cache.ts	Uses Google's cached prompt feature if available

Turn Loop & Parallelism

Sequential tool execution, parallel compaction, async hooks — precise boundaries

Turn Loop — Tool Execution & Parallelism

Mermaid

flowchart TD
    A["LLM emits
tool_use block"] --> B{"tool_use
stop?"}
    B -->|Yes| C["Execute Tool 1
(sequential)"]
    C --> D{"More
tool_use?"}
    D -->|Yes| E["Execute Tool 2"]
    E --> F["..."]
    F --> D
    D -->|No| G["Next LLM call
full transcript"]
    G --> A
    B -->|No| H["Return final answer"]
    H --> I{"Compaction
needed?"}
    I -->|Yes| P1["Compaction
runs in background"]
    I -->|No| OUT["Done"]
    P1 --> PAR["Parallel:
Compaction + LLM Input Hooks
Payload Logging + Context Engine"]
    PAR --> OUT
    style A fill:#0a1628,stroke:#FFAB40,stroke-width:2px,color:#FFAB40
    style B fill:#0a1628,stroke:#FFAB40,stroke-width:2px,color:#FFAB40
    style H fill:#0a2820,stroke:#c3e88d,stroke-width:2px,color:#c3e88d
    style I fill:#0a1628,stroke:#89DDFF,stroke-width:1px,color:#89DDFF
    style P1 fill:#1a0a28,stroke:#c792ea,stroke-width:2px,color:#c792ea
    style PAR fill:#1a0a28,stroke:#c792ea,stroke-width:1px,color:#c792ea
    style OUT fill:#0a2820,stroke:#c3e88d,stroke-width:2px,color:#c3e88d

Compaction — Preemptive vs Background

Mermaid

flowchart TD
    PRE["shouldPreemptivelyCompact
BeforePrompt()
preemptive-compaction.ts"] --> DEC["Overflow?"]
    DEC -->|tool_result chars only| TRUNC["Truncate tool results
truncateOversized
ToolResultsInSession
Manager()"]
    DEC -->|needs full compaction| BOTH["Compact + Truncate"]
    DEC -->|compact only| ONLY["Compaction only"]
    TRUNC --> DONE_T["Use truncated
transcript"]
    BOTH --> BG["Background
Compaction"]
    ONLY --> BG
    BG --> GRACE["Grace Period
(60s aggregate timeout)"]
    GRACE -->|succeeds| DONE_C["Use compacted
transcript"]
    GRACE -->|timeout| PREV["Proceed with
pre-compaction state
+ warn log"]
    style BG fill:#1a0a28,stroke:#c792ea,stroke-width:2px,color:#c792ea
    style TRUNC fill:#0a2820,stroke:#c3e88d,stroke-width:1px,color:#c3e88d
    style DONE_T fill:#0a2820,stroke:#c3e88d,stroke-width:1px,color:#c3e88d
    style DONE_C fill:#0a2820,stroke:#c3e88d,stroke-width:1px,color:#c3e88d
    style PREV fill:#1a0a28,stroke:#FF5252,stroke-width:1px,color:#FF5252

✓ Parallel Activities

Compaction — background while LLM thinks. compactWithSafetyTimeout() with grace period. If it overruns, run proceeds with pre-compaction state.
LLM Input Hooks — llm_input hooks fire asynchronously before each LLM call (fire-and-forget, attempt.ts:2539–2566).
Payload Logging — createAnthropicPayloadLogger records without blocking.
Context Engine — assembleAttemptContextEngine() preprocesses messages in parallel (attempt.ts:1923–1958).

✗ Sequential Only

Tool calls within a turn — always sequential, order-dependent. Each tool_result appended before the next LLM call.
History truncation — synchronous: limitHistoryTurns() must complete before activeSession.prompt().
Stream wrapper application — synchronous chain applied before any LLM I/O.
Abort timer scheduling — synchronous: scheduleAbortTimer() sets up timeout before prompt starts.

Harness Selection

How OpenClaw picks between the built-in pi harness and plugin harnesses (Codex, Claude Code...)

Agent Harness Selection — Decision Tree

Mermaid

flowchart TD
    START["selectAgentHarness()
harness/selection.ts:74"] --> POL["resolvePinned
AgentHarnessPolicy()
or resolveAgent
HarnessPolicy()"]
    POL --> MODE{"Runtime mode?"}
    MODE -->|"pi"| PI["Return
createPiAgentHarness()
reason: forced_pi"]
    MODE -->|"plugin (forced)"| FIND["Find harness
by ID in registry"]
    FIND -->|found| PLUGIN["Return harness
reason: forced_plugin"]
    FIND -->|not found + fallback| FALLBACK["Fallback to
piHarness
reason: forced_
plugin_fallback_
to_pi"]
    FIND -->|not found + no fallback| ERROR["Throw Error
'PI fallback disabled'"]
    MODE -->|"auto"| CAND["Evaluate all
plugin harnesses"]
    CAND --> SUP{"supports()?"}
    SUP -->|yes| SORT["Sort by priority"]
    SUP -->|no| SKIP["Skip"]
    SORT --> BEST["Best candidate?"]
    BEST -->|yes| SEL["Return harness
reason: auto_plugin"]
    BEST -->|no + fallback| PI_FALL["Return piHarness
reason: auto_pi_
fallback"]
    BEST -->|no + no fallback| ERROR
    SKIP --> SORT
    PI --> RESULT["AgentHarness
selected"]
    PLUGIN --> RESULT
    FALLBACK --> RESULT
    SEL --> RESULT
    PI_FALL --> RESULT
    style PI fill:#0a1628,stroke:#00E5FF,stroke-width:2px,color:#00E5FF
    style PLUGIN fill:#0a1628,stroke:#FF00AA,stroke-width:2px,color:#FF00AA
    style SEL fill:#0a1628,stroke:#c3e88d,stroke-width:2px,color:#c3e88d
    style ERROR fill:#1a0a28,stroke:#FF5252,stroke-width:2px,color:#FF5252

Harness Policy Resolution

Selection Reason	Condition	Harness
pinned	agentHarnessId pinned via config	pi or plugin (forced)
forced_pi	runtime="pi" in policy	piHarness (embedded)
forced_plugin	runtime="plugin-id" (specific)	Named plugin harness
forced_plugin_fallback_to_pi	plugin not registered + fallback≠none	piHarness
auto_plugin	runtime="auto" + plugin supports provider	Highest-priority supporting plugin
auto_pi_fallback	runtime="auto" + no plugin supports	piHarness (built-in)

pi-agent-core Imports

Two core packages from @mariozechner:

@mariozechner/pi-agent-core @mariozechner/pi-coding-agent

These provide: createAgentSession(), SessionManager, DefaultResourceLoader, and the StreamFn type.

Core Types & Tool Payloads

EmbeddedRunAttemptParams, tool call/request/result types, and session manager interfaces

EmbeddedRunAttemptParams — Key Fields

Field	Type	Description
sessionId	string	Unique run session ID
sessionKey	string	Routing key (user/session)
sessionFile	string	Disk path to session JSON file
provider	string	"anthropic" \| "openai" \| "openai-codex"...
modelId	string	"claude-sonnet-4-7-20250514"
model	ProviderRuntimeModel	Resolved model with api, baseUrl, contextWindow
prompt	string	Current user message
thinkLevel	ThinkLevel	"off" \| "fast" \| "medium" \| "high"
reasoningLevel	ReasoningLevel	"off" \| "summary" \| "block"
timeoutMs	number	Run timeout (default: from config)
config	OpenClawConfig	Full runtime config
workspaceDir	string	Agent working directory
authStorage	AuthStorage	API key storage
toolsAllow	string[]	Explicit tool allowlist
abortSignal	AbortSignal	External abort from gateway

Tool Result Payload Flow

ToolUse:      { id, name, input: Record<string, unknown> }
ToolResult:   { toolUseId, content: string }
StopReason:   "tool_use" | "end_turn" | "max_tokens" | "stop_sequence" | ...

// Per-turn message flow:
UserMessage
  → activeSession.prompt()
  → LLM emits: tool_use{id, "read", {path:"/foo.txt"}}
  → ToolExecutor.execute("read", {path:"/foo.txt"})
  → ToolResult{toolUseId: id, content: "file contents..."}
  → transcript.push(tool_result)
  → LLM (next iteration)
  → until stop_reason ≠ "tool_use"

Complete Architecture

End-to-end flow from user message to LLM API call to response

Full System Architecture

Mermaid

flowchart TD
    CH["User Message
Telegram / Discord / Signal..."] --> GW["Gateway
app-lifecycle.ts"]
    GW --> HS["Harness Selection
selectAgentHarness()"]
    HS --> RT["Runtime Plan
buildAgentRuntimePlan()"]
    RT --> ATT["runEmbeddedAttempt()
attempt.ts:579"]
    ATT --> A1["Model Resolution"]
    A1 --> A2["Sandbox Setup"]
    A2 --> A3["Session Manager Init"]
    A3 --> A4["System Prompt Builder"]
    A4 --> A5["Tool Registration"]
    A5 --> A6["Stream Wrapping
10 x wrapStreamFn()"]
    A6 --> A7["History Prep
sanitize / filter / limit"]
    A7 --> A8["LLM Input Hooks
(fire-and-forget)"]
    A8 --> A9["activeSession.prompt()"]
    A9 --> LOOP["Turn Loop
pi-agent-core"]
    LOOP --> LLM["LLM API Call
(provider transport)"]
    LLM --> RESP{"Response?"}
    RESP -->|tool_use| TOOL["Execute Tool
Sequential"]
    TOOL --> APP["Append tool_result
to transcript"]
    APP --> LOOP
    RESP -->|final text| DONE["Stream to UI
subscription"]
    RESP -->|stop_reason| COMP{"Overflow?"}
    COMP -->|yes| COMPACT["Compaction
background"]
    COMP -->|no| OUT["Return result"]
    LLM -.->|"provider"| PROVIDER["OpenAI / Azure
Anthropic Claude
Vertex AI / Codex"]
    style ATT fill:#0a1628,stroke:#00E5FF,stroke-width:1px
    style LOOP fill:#0a1628,stroke:#FFAB40,stroke-width:2px,color:#FFAB40
    style TOOL fill:#0a1628,stroke:#FF00AA,stroke-width:1px,color:#FF00AA
    style COMPACT fill:#1a0a28,stroke:#c792ea,stroke-width:1px,color:#c792ea
    style DONE fill:#0a2820,stroke:#c3e88d,stroke-width:2px,color:#c3e88d
    style OUT fill:#0a2820,stroke:#c3e88d,stroke-width:2px,color:#c3e88d

Key Files Referenced

File	Role	Lines
src/agents/system-prompt.ts	Master system prompt builder — all 25+ sections	1,048
src/agents/bootstrap-prompt.ts	Bootstrap prompt lines builder (full/limited)	25
src/agents/context.ts	Memory section and context file handling	—
src/agents/pi-embedded-runner/run/attempt.ts	runEmbeddedAttempt — THE core harness	3,290
src/agents/pi-embedded-runner/compact.ts	Background compaction orchestration	1,287
src/agents/pi-embedded-runner/model.ts	Model resolution + context window cache	1,121
src/agents/pi-embedded-runner/stream-resolution.ts	Stream transport selection (WS/HTTP/Vertex)	132
src/agents/harness/selection.ts	Harness selection decision tree	399
src/agents/pi-embedded-runner/run/payloads.ts	Tool call/request/result type definitions	—
src/plugins/provider-runtime.js	Provider plugin hooks + system prompt transforms	—
src/plugins/memory-state.js	Memory citations prompt section builder	—
src/agents/bootstrap-budget.ts	Bootstrap warning prepend logic	—
src/agents/session-write-lock.js	Session write lock for concurrent safety	—
src/agents/session-compaction-checkpoints.js	Compaction checkpoint snapshot system	—
.pi/prompts/cl.md	Bootstrap skill: Changelog Audit	58
.pi/prompts/is.md	Bootstrap skill: Issue Analysis	22