William Valentin
313 lines
9.9 KiB
Markdown
313 lines
9.9 KiB
Markdown
# Agent-Oriented Project Diagram
|
|
|
|
This is a high-signal, agent-oriented view of Flynn's structure and execution flow.
|
|
|
|
If you're new to the codebase, start here, then jump to the referenced files.
|
|
|
|
## System Map (Boundaries + Trust)
|
|
|
|
This is the fastest way to understand what runs where, and where the security boundaries sit.
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
subgraph EXT[External Systems]
|
|
MP[Model Providers\nAnthropic/OpenAI/Gemini/...\nvia ModelClient]
|
|
CH[Chat Networks\nTelegram/Discord/Slack/WhatsApp/...]
|
|
WEB[Web\nsearch/fetch targets]
|
|
GOOG[Google APIs\nGmail/Calendar/Docs/Drive/Tasks]
|
|
end
|
|
|
|
subgraph CFG[Config Sources]
|
|
CD[config/default.yaml]
|
|
CO[config/profiles/*.overlay.yaml]
|
|
CG[Generated config profile\nconfig/paas.yaml]
|
|
CE[ENV vars + expansion]
|
|
end
|
|
|
|
subgraph HOST[Host (Flynn Daemon)]
|
|
CA[ChannelAdapters]
|
|
GW[Gateway\nHTTP + WS JSON-RPC + Web UI]
|
|
RT[Routing\ncreateMessageRouter()]
|
|
SM[SessionManager\nSQLite]
|
|
OR[AgentOrchestrator]
|
|
NA[NativeAgent\n(tool loop)]
|
|
EB[Optional External Backends\nclaude_code/opencode/codex/gemini/pi_embedded]
|
|
MR[ModelRouter]
|
|
TP[ToolPolicy + ToolRegistry]
|
|
TE[ToolExecutor\nhooks + enforcement + audit]
|
|
MEM[Memory Store\nfiles + vector/keyword]
|
|
AU[Audit Logger\nredacted]
|
|
HS[Hooks/Autonomy\nconfirm/log/silent]
|
|
GA[Google OAuth Runtime\nsrc/google/oauth.ts]
|
|
AS[Auth Store\n~/.config/flynn/auth.json]
|
|
TF[Legacy Token Files\n~/.config/flynn/*-token.json]
|
|
end
|
|
|
|
subgraph SBX[Sandbox (per-session Docker)]
|
|
ST[Sandboxed Tools\nshell/process/fs writes]
|
|
FS[Sandbox FS\nworkspace mount (scoped)]
|
|
NET[Sandbox Network\n(egress policy)]
|
|
end
|
|
|
|
CD --> CG
|
|
CO --> CG
|
|
CE --> CG
|
|
|
|
CG --> RT
|
|
CE --> RT
|
|
|
|
CH --> CA
|
|
GW --> RT
|
|
CA --> RT
|
|
RT --> SM
|
|
RT --> OR
|
|
RT --> EB
|
|
OR --> NA
|
|
EB --> MP
|
|
NA --> MR
|
|
MR --> MP
|
|
|
|
NA --> TP
|
|
TP --> TE
|
|
TE --> HS
|
|
TE --> AU
|
|
TE --> MEM
|
|
|
|
TE -->|high-risk tools| ST
|
|
ST --> FS
|
|
ST --> NET
|
|
|
|
TE -->|web tools| WEB
|
|
TE -->|google tools| GA
|
|
GA --> GOOG
|
|
GA <--> AS
|
|
GA --> TF
|
|
```
|
|
|
|
## Big Picture (Runtime Data Flow)
|
|
|
|
```text
|
|
Inbound Message
|
|
(Telegram/Discord/Slack/WhatsApp/WebChat)
|
|
|
|
|
v
|
|
ChannelAdapter -> ChannelRegistry
|
|
| |
|
|
| v
|
|
| createMessageRouter()
|
|
| |
|
|
| v
|
|
| SessionManager
|
|
| |
|
|
| v
|
|
| AgentOrchestrator
|
|
| |
|
|
| v
|
|
| NativeAgent
|
|
| |
|
|
| ModelRouter.chat()
|
|
| |
|
|
| v
|
|
| ModelClient
|
|
|
|
|
+----> (optional, non-tool turns) ExternalBackend
|
|
(claude_code/opencode/codex/gemini/pi_embedded)
|
|
|
|
|
+----> (optional) PairingManager gate for unknown senders
|
|
|
|
Tool Calls (inside NativeAgent loop)
|
|
NativeAgent -> ToolRegistry (policy-filtered) -> ToolExecutor
|
|
| |
|
|
| v
|
|
| HookEngine + autonomy
|
|
| |
|
|
| v
|
|
| Tool.execute()
|
|
| |
|
|
| v
|
|
+---------------------------> AuditLogger (redacted)
|
|
|
|
Outbound Reply
|
|
-> ChannelAdapter.send() (text + optional attachments)
|
|
```
|
|
|
|
Key files:
|
|
|
|
- Routing + per-session agent creation: `src/daemon/routing.ts`
|
|
- Orchestration: `src/backends/native/orchestrator.ts`
|
|
- Tool loop: `src/backends/native/agent.ts`
|
|
- External backend adapters: `src/backends/external.ts`, `src/backends/piEmbedded.ts`
|
|
- Model routing: `src/models/router.ts`
|
|
- Tool policy + execution: `src/tools/policy.ts`, `src/tools/executor.ts`
|
|
- Canary backend telemetry summarization (offline evaluation): `src/audit/backendCanarySummary.ts`, `scripts/summarize-backend-canary.ts`
|
|
|
|
## Component Graph (Agent-Safety Boundary)
|
|
|
|
```text
|
|
+---------------------------+
|
|
| Config |
|
|
| (Zod schema + YAML) |
|
|
| src/config/schema.ts |
|
|
+-------------+-------------+
|
|
|
|
|
v
|
|
+-------------------+ +-------------+ +------------------+
|
|
| SkillRegistry | | ToolPolicy | | HookEngine |
|
|
| src/skills/* | | src/tools/* | | src/hooks/* |
|
|
+---------+---------+ +------+------+ +---------+--------+
|
|
| | |
|
|
| (system prompt) | (allow/deny) | (confirm/log/silent)
|
|
v v v
|
|
+-------------------+ +-------------+ +------------------+
|
|
| System Prompt | | ToolRegistry| | ToolExecutor |
|
|
| src/daemon/services.ts| src/tools/* | | src/tools/executor.ts
|
|
+---------+---------+ +------+------+ +---------+--------+
|
|
| | |
|
|
v | |
|
|
+-------------------+ | v
|
|
| AgentOrchestrator | | +-----------+
|
|
| src/backends/* | +------------> | AuditLogger|
|
|
+---------+---------+ | src/audit/*|
|
|
|
|
|
v
|
|
+-------------------+
|
|
| NativeAgent |
|
|
| src/backends/* |
|
|
+---------+---------+
|
|
|
|
|
v
|
|
+-------------------+
|
|
| ModelRouter |
|
|
| src/models/* |
|
|
+-------------------+
|
|
```
|
|
|
|
## Skills + Capabilities (What Gets Enforced)
|
|
|
|
Skills are local directories with:
|
|
|
|
- `SKILL.md` (instructions injected into the system prompt)
|
|
- `manifest.json` (metadata + optional `permissions`)
|
|
|
|
### Skill permissions enforcement points
|
|
|
|
- Tool availability: `ToolPolicy.resolveAllowedNames()` intersects allowed tools with `manifest.json.permissions`.
|
|
- Tool execution (defense in depth): `ToolExecutor.execute()` enforces:
|
|
- fs allowlists (`permissions.fs.read` / `permissions.fs.write`)
|
|
- net allowlists (best-effort for `web.fetch`)
|
|
- secret scopes (tools declare `requiredSecretScopes`, skills allow `permissions.secrets`)
|
|
- injection guard when untrusted content is present
|
|
|
|
Important default:
|
|
|
|
- If a request is routed into a skill context but the skill has no `permissions` manifest, **tool access is denied**.
|
|
|
|
Key files:
|
|
|
|
- Skill manifest types: `src/skills/types.ts`
|
|
- Loader validation: `src/skills/loader.ts`
|
|
- Policy intersection: `src/tools/policy.ts`
|
|
- Executor enforcement: `src/tools/executor.ts`
|
|
|
|
## Sandbox Execution (High-Risk Tools)
|
|
|
|
Flynn supports per-session Docker sandboxes.
|
|
|
|
Where sandboxing is applied today:
|
|
|
|
- `shell.exec` and `process.start` can be replaced with sandboxed implementations.
|
|
- Replacement is wired in `src/daemon/routing.ts` by cloning the ToolRegistry and swapping the tool implementations.
|
|
|
|
Skill context default:
|
|
|
|
- High-risk tool execution defaults to `sandbox` in skill context (when available).
|
|
- A skill can opt into host execution only by setting `permissions.execution_environment: "host"`.
|
|
|
|
Key files:
|
|
|
|
- Sandbox lifecycle: `src/sandbox/manager.ts`, `src/sandbox/docker.ts`
|
|
- Sandboxed tool wrappers: `src/sandbox/tools.ts`
|
|
- Wiring: `src/daemon/routing.ts`
|
|
|
|
## Prompt Injection Hardening (Practical)
|
|
|
|
Flynn treats content provenance as part of the control boundary:
|
|
|
|
- `web.fetch`, `web.search`, and `browser.content` outputs are treated as untrusted "fetched_content".
|
|
- Tool results are wrapped in provenance markers inside the tool loop.
|
|
- Once untrusted content is seen, ToolExecutor applies stricter gating (blocks obvious injection patterns for high-risk tools).
|
|
|
|
Key files:
|
|
|
|
- Provenance wrapping: `src/backends/native/agent.ts`
|
|
- Tool-call guard: `src/tools/executor.ts`
|
|
- System prompt safety guidance: `src/daemon/services.ts`
|
|
|
|
## Mermaid (For Fast Visual Scanning)
|
|
|
|
If your renderer supports Mermaid, this is the same information as a sequence diagram.
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
autonumber
|
|
participant U as User
|
|
participant CA as ChannelAdapter
|
|
participant CR as ChannelRegistry
|
|
participant SM as SessionManager
|
|
participant AR as AgentOrchestrator
|
|
participant NA as NativeAgent
|
|
participant MR as ModelRouter
|
|
participant MC as ModelClient
|
|
participant FC as Fallback Client
|
|
participant TP as ToolPolicy/Registry
|
|
participant TE as ToolExecutor
|
|
participant HE as HookEngine
|
|
participant AL as AuditLogger
|
|
participant GA as Google OAuth Runtime
|
|
participant AS as Auth Store
|
|
participant TF as Token Files
|
|
participant GP as Google APIs
|
|
|
|
U->>CA: message
|
|
CA->>CR: onMessage(InboundMessage)
|
|
CR->>SM: getSession(channel, sender)
|
|
SM-->>CR: Session
|
|
CR->>AR: getOrCreateAgent(session + routing)
|
|
AR->>NA: process(userMessage)
|
|
NA->>MR: chat(messages + tools)
|
|
MR->>MC: provider request
|
|
alt primary model success
|
|
MC-->>MR: response (content or tool_calls)
|
|
else primary model error
|
|
Note over MR: retry + tier/global fallback\n(skip duplicate clients)
|
|
MR->>FC: fallback provider request
|
|
FC-->>MR: fallback response
|
|
end
|
|
MR-->>NA: ChatResponse
|
|
|
|
alt model requests tool use
|
|
NA->>TP: filtered tool list (skill + policy)
|
|
NA->>TE: execute(tool, args, context)
|
|
TE->>HE: confirm/log/silent (autonomy)
|
|
HE-->>TE: approved/denied
|
|
alt google.* tool execution
|
|
TE->>GA: createGoogleOAuth2Client(service)
|
|
GA->>AS: load stored token
|
|
alt auth store token missing
|
|
GA->>TF: read legacy token file
|
|
TF-->>GA: token
|
|
GA->>AS: migrate token record
|
|
end
|
|
GA->>GP: API request with refreshed OAuth creds
|
|
end
|
|
TE->>AL: audit (redacted)
|
|
TE-->>NA: ToolResult
|
|
NA->>MR: chat(tool_result blocks)
|
|
end
|
|
|
|
NA-->>AR: assistant response
|
|
AR-->>CR: OutboundMessage
|
|
CR-->>CA: send()
|
|
CA-->>U: reply
|
|
```
|