Skip to content

architecture.md

Latest commit

 

History

History
83 lines (72 loc) · 2.46 KB

architecture.md

File metadata and controls

83 lines (72 loc) · 2.46 KB

Architecture

Overview

GitHub Event
    │
    ▼
action.yml (composite)
    │  oven-sh/setup-bun@v2
    │  Install Cortex Code CLI
    │  Write connections.toml
    │  bun install --frozen-lockfile
    │
    ▼
src/entrypoints/run-cortex.ts
    │
    ├── detectMode() → review | mention | fix
    │
    ├── buildPrompt() → PR diff + metadata + system prompt
    │
    └── query() [Cortex Code Agent SDK]
            │
            ├── canUseTool (security gate)
            │       ├── Block all SQL tools
            │       ├── Block sensitive file paths
            │       └── Enforce permission mode
            │
            └── Event stream
                    ├── assistant events → buffer output
                    ├── tool_use events → update progress comment
                    └── result event → finalize
                            │
                            ├── sanitizeOutput()
                            ├── upsertComment() → GitHub PR comment
                            └── [fix mode] commitFixes() + pushChanges()

Security gate internals

The canUseTool callback is called by the SDK before every tool execution. The security gate is a pure function with no side effects:

createSecurityGate(permissions) → async (toolName, input) → PermissionResult

Denial reasons are logged to GitHub Actions output for debugging.

Fail-closed design: If the gate throws an error, the tool call is denied (not allowed).

Snowflake connection purpose

The connections.toml written to ~/.snowflake/ provides authentication for the Cortex Code CLI to access Snowflake LLMs. It does not grant the agent any data access -- the SQL tool is blocked by canUseTool before any query could be attempted.

Event flow for PR review

pull_request (opened/synchronize)
    │
    ▼
detectMode() → review
    │
    ▼
buildReviewPrompt()
    ├── git diff origin/main...HEAD
    ├── git diff --name-only
    └── PR metadata from GITHUB_EVENT_PATH
    │
    ▼
ProgressTracker.start() → create "Reviewing..." comment
    │
    ▼
query({ prompt, systemPrompt, canUseTool: gate })
    │  streams events
    ▼
output buffer accumulates assistant text
    │
    ▼
sanitizeOutput() → strip ANSI, redact patterns
    │
    ▼
upsertComment() → update/replace progress comment with review