diff --git a/docs/api/PROTOCOL.md b/docs/api/PROTOCOL.md index 53c7b65..e69e370 100644 --- a/docs/api/PROTOCOL.md +++ b/docs/api/PROTOCOL.md @@ -57,6 +57,11 @@ sequenceDiagram LQ-->>G: starts work immediately else lane busy Note over LQ: work queued (FIFO) for this lane + opt mode=interrupt and newer request arrives + LQ->>SB: request cancellation of active lane run + SB->>A: cancel() (best effort) + G-->>C: transient preempt notice (queue.preempt) + end end G->>A: process(message) in that session diff --git a/docs/architecture/AGENT_DIAGRAM.md b/docs/architecture/AGENT_DIAGRAM.md index 542f677..1e4b2ce 100644 --- a/docs/architecture/AGENT_DIAGRAM.md +++ b/docs/architecture/AGENT_DIAGRAM.md @@ -14,6 +14,14 @@ flowchart LR 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)] @@ -29,6 +37,9 @@ flowchart LR 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)] @@ -37,6 +48,13 @@ flowchart LR NET[Sandbox Network\n(egress policy)] end + CD --> CG + CO --> CG + CE --> CG + + CG --> RT + CE --> RT + CH --> CA GW --> RT CA --> RT @@ -57,6 +75,10 @@ flowchart LR ST --> NET TE -->|web tools| WEB + TE -->|google tools| GA + GA --> GOOG + GA <--> AS + GA --> TF ``` ## Big Picture (Runtime Data Flow) @@ -228,10 +250,15 @@ sequenceDiagram 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) @@ -241,7 +268,13 @@ sequenceDiagram AR->>NA: process(userMessage) NA->>MR: chat(messages + tools) MR->>MC: provider request - MC-->>MR: response (content or tool_calls) + 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 @@ -249,6 +282,16 @@ sequenceDiagram 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) diff --git a/docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md b/docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md index 10d8ffb..d87c87c 100644 --- a/docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md +++ b/docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md @@ -15,11 +15,16 @@ If you only want the protocol surface, see `docs/api/PROTOCOL.md`. ```mermaid flowchart LR + subgraph CFG[Config + Runtime Policy] + QP[server.queue policy\nmode/cap/overflow/overrides] + end + subgraph GW[Gateway Process] WS[WebSocket connection\n(connectionId)] GS[GatewayServer] LQ[LaneQueue\nper-session FIFO] SB[SessionBridge\nconnectionId -> sessionId -> AgentOrchestrator] + AQ[AuditLogger\nqueue.preempt events] end subgraph CORE[Flynn Core] @@ -29,8 +34,10 @@ flowchart LR end WS --> GS + QP --> GS GS --> LQ GS --> SB + LQ --> AQ SB --> AO SB --> SM @@ -97,4 +104,3 @@ Key files: - `src/gateway/handlers/agent.ts` - `src/backends/native/orchestrator.ts` - diff --git a/docs/plans/state.json b/docs/plans/state.json index 424c1f6..cb17b72 100644 --- a/docs/plans/state.json +++ b/docs/plans/state.json @@ -7,7 +7,7 @@ "status": "completed", "date": "2026-02-24", "updated": "2026-02-24", - "summary": "Completed a repo-wide audit and implemented hardening/refactors for Google OAuth token handling, router fallback correctness, config-profile consolidation, and audit logging path behavior. Added Google service coverage to `flynn doctor`, introduced a unified `flynn google-auth` command, aligned fallback-chain defaults with runtime semantics, expanded provider capability type coverage, and produced operator/agent-facing documentation plus REPORT.md.", + "summary": "Completed a repo-wide audit and implemented hardening/refactors for Google OAuth token handling, router fallback correctness, config-profile consolidation, and audit logging path behavior. Added Google service coverage to `flynn doctor`, introduced a unified `flynn google-auth` command, aligned fallback-chain defaults with runtime semantics, expanded provider capability type coverage, produced operator/agent-facing documentation plus REPORT.md, and refreshed Mermaid architecture/protocol diagrams to match the new flows.", "files_modified": [ "src/auth/google.ts", "src/google/oauth.ts", @@ -28,6 +28,9 @@ "README.md", "docs/operations/GOOGLE_AUTH.md", "docs/architecture/AGENT_REPO_MAP.md", + "docs/architecture/AGENT_DIAGRAM.md", + "docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md", + "docs/api/PROTOCOL.md", "REPORT.md", "docs/plans/state.json" ],