diff --git a/packages/kilo-docs/__tests__/heading.test.ts b/packages/kilo-docs/__tests__/heading.test.ts new file mode 100644 index 00000000000..ab312a04405 --- /dev/null +++ b/packages/kilo-docs/__tests__/heading.test.ts @@ -0,0 +1,17 @@ +import { Tag } from "@markdoc/markdoc" +import { describe, expect, it } from "vitest" +import { heading } from "../markdoc/nodes/heading.markdoc" + +describe("heading", () => { + it("includes inline code text in generated ids", () => { + const tag = heading.transform( + { + transformAttributes: () => ({}), + transformChildren: () => [new Tag("code", {}, ["kilo-auto/frontier"])], + }, + {}, + ) + + expect(tag.attributes.id).toBe("kilo-autofrontier") + }) +}) diff --git a/packages/kilo-docs/lib/nav/contributing.ts b/packages/kilo-docs/lib/nav/contributing.ts index 14f4dae5e63..a0c6404ceac 100644 --- a/packages/kilo-docs/lib/nav/contributing.ts +++ b/packages/kilo-docs/lib/nav/contributing.ts @@ -1,10 +1,10 @@ -import { NavSection } from "../types" +import type { NavSection } from "../types" export const ContributingNav: NavSection[] = [ { title: "Getting Started", links: [ - { href: "/contributing", children: "Contributing Overview" }, + { href: "/contributing", children: "Overview" }, { href: "/contributing/development-environment", children: "Development Environment", @@ -20,61 +20,69 @@ export const ContributingNav: NavSection[] = [ links: [ { href: "/contributing/architecture", - children: "Architecture Overview", - }, - { - href: "/contributing/architecture/features", - children: "Features", - subLinks: [ - { - href: "/contributing/architecture/agent-observability", - children: "Agent Observability", - }, - { - href: "/contributing/architecture/auto-model-tiers", - children: "Auto Model Tiers", - }, - { - href: "/contributing/architecture/benchmarking", - children: "Benchmarking", - }, - { - href: "/contributing/architecture/config-schema", - children: "CLI Config Schema", - }, - { - href: "/contributing/architecture/enterprise-mcp-controls", - children: "Enterprise MCP Controls", - }, - { - href: "/contributing/architecture/mcp-oauth-authorization", - children: "MCP OAuth Authorization", - }, - { - href: "/contributing/architecture/onboarding-improvements", - children: "Onboarding Improvements", - }, - { - href: "/contributing/architecture/organization-modes-library", - children: "Organization Modes Library", - }, - { - href: "/deploy-secure/security-reviews", - children: "Agentic Security Reviews", - }, - { - href: "/contributing/architecture/track-repo-url", - children: "Track Repo URL", - }, - { - href: "/contributing/architecture/voice-transcription", - children: "Voice Transcription", - }, - { - href: "/contributing/architecture/per-message-feedback", - children: "Per-Message Feedback", - }, - ], + children: "Overview", + }, + { + href: "/contributing/architecture/cli-runtime", + children: "CLI Runtime", + }, + { + href: "/contributing/architecture/vscode-extension", + children: "VS Code Extension", + }, + { + href: "/contributing/architecture/jetbrains-plugin", + children: "JetBrains Plugin", + }, + { + href: "/contributing/architecture/cloud-platform", + children: "Cloud Platform", + }, + { + href: "/contributing/architecture/automation-services", + children: "Automation Services", + }, + { + href: "/contributing/architecture/cloud-security", + children: "Cloud Security", + }, + ], + }, + { + title: "Development", + links: [ + { + href: "/contributing/architecture/development-patterns", + children: "Development Patterns", + }, + { + href: "/contributing/architecture/config-schema", + children: "CLI Config Schema", + }, + ], + }, + { + title: "Feature Proposals", + links: [ + { + href: "/contributing/features", + children: "Overview", + }, + { + href: "/contributing/features/enterprise-mcp-controls", + children: "Enterprise MCP Controls", + }, + { + href: "/contributing/features/onboarding-improvements", + children: "Onboarding Improvements", + }, + { + href: "/contributing/features/agent-observability", + children: "Agent Observability", + }, + { + href: "/contributing/features/benchmarking", + children: "Benchmarking", }, ], }, diff --git a/packages/kilo-docs/markdoc/nodes/heading.markdoc.ts b/packages/kilo-docs/markdoc/nodes/heading.markdoc.ts index 862c179dcd4..3c5741af8d0 100644 --- a/packages/kilo-docs/markdoc/nodes/heading.markdoc.ts +++ b/packages/kilo-docs/markdoc/nodes/heading.markdoc.ts @@ -2,14 +2,20 @@ import { Tag } from "@markdoc/markdoc" import { Heading } from "../../components" +function text(child) { + if (typeof child === "string") return child + if (Tag.isTag(child)) return child.children.map(text).join(" ") + return "" +} + function generateID(children, attributes) { if (attributes.id && typeof attributes.id === "string") { return attributes.id } return children - .filter((child) => typeof child === "string") + .map(text) .join(" ") - .replace(/[?]/g, "") + .replace(/[?/]/g, "") .replace(/\s+/g, "-") .toLowerCase() } diff --git a/packages/kilo-docs/markdoc/tags/index.ts b/packages/kilo-docs/markdoc/tags/index.ts index 6fc54c6d902..30d74d45ae9 100644 --- a/packages/kilo-docs/markdoc/tags/index.ts +++ b/packages/kilo-docs/markdoc/tags/index.ts @@ -10,3 +10,4 @@ export * from "./video.markdoc" export * from "./youtube.markdoc" export * from "./flow-diagram.markdoc" export * from "./browser-frame.markdoc" +export * from "./linebreak.markdoc" diff --git a/packages/kilo-docs/markdoc/tags/linebreak.markdoc.ts b/packages/kilo-docs/markdoc/tags/linebreak.markdoc.ts new file mode 100644 index 00000000000..7be1c9c14d5 --- /dev/null +++ b/packages/kilo-docs/markdoc/tags/linebreak.markdoc.ts @@ -0,0 +1,4 @@ +export const linebreak = { + render: "br", + selfClosing: true, +} diff --git a/packages/kilo-docs/package.json b/packages/kilo-docs/package.json index d39efa89812..a22d8dbd803 100644 --- a/packages/kilo-docs/package.json +++ b/packages/kilo-docs/package.json @@ -5,8 +5,10 @@ "scripts": { "dev": "next dev --webpack --port 3002", "build": "next build --webpack", + "lint": "bun run --cwd ../.. lint packages/kilo-docs", "start": "next start", - "test": "vitest run" + "test": "vitest run", + "typecheck": "tsc --noEmit" }, "dependencies": { "@docsearch/css": "^4", diff --git a/packages/kilo-docs/pages/code-with-ai/agents/auto-model.md b/packages/kilo-docs/pages/code-with-ai/agents/auto-model.md index 1ed07cf5261..50b318de242 100644 --- a/packages/kilo-docs/pages/code-with-ai/agents/auto-model.md +++ b/packages/kilo-docs/pages/code-with-ai/agents/auto-model.md @@ -1,11 +1,11 @@ --- title: "Auto Model" -description: "Smart model routing that automatically selects the optimal AI model based on your current mode" +description: "Smart model routing that selects an AI model for each Auto Model tier" --- # Auto Model -Auto Model is a smart model routing system that automatically selects the optimal AI model based on the Kilo Code mode you're using. It comes in multiple tiers so you can balance cost and capability to fit your needs. +Auto Model is a smart routing system that selects an underlying model for each request. Each tier uses its own routing strategy so you can balance cost and capability to fit your needs. | Tier | Best For | Pricing | |---|---|---| diff --git a/packages/kilo-docs/pages/contributing/architecture/agent-observability.md b/packages/kilo-docs/pages/contributing/architecture/agent-observability.md deleted file mode 100644 index c99994d9fb8..00000000000 --- a/packages/kilo-docs/pages/contributing/architecture/agent-observability.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -title: "Agent Observability" -description: "Observability and monitoring for agentic coding systems" ---- - -# Kilo Code - Agent Observability - -## Problem Statement - -Agentic coding systems like Kilo Code operate with significant autonomy, executing multi-step tasks that involve LLM inference, tool execution, file manipulation, and external API calls. These systems mix traditional systems observability (i.e. request/response) with agentic behavior (i.e. planning, reasoning, and tool use). - -At the lower level, we can observe the system as a traditional API, but at the higher level, we need to observe the agent's behavior and the quality of its outputs. - -Some examples of customer-facing error modes: - -- Model API calls may be slow or fail due to rate limits, network issues, or model unavailability -- Model API calls may produce invalid JSON or malformed responses -- An agent may get stuck in a loop, repeatedly attempting the same failing operation -- Sessions may degrade gradually as context windows fill up -- The agent may complete a task technically but produce incorrect or unhelpful output -- Users may abandon sessions out of frustration without explicit error signals - -All of these contribute to the overall reliability and user experience of the system. - -## Goals - -1. Detect and alert on acute incidents within minutes -2. Surface slow-burn degradations within hours -3. Facilitate root cause analysis when issues occur -4. Track quality and efficiency trends over time -5. Build a foundation for continuous improvement of the agent - -**Non-goals for this proposal:** - -- Automated remediation -- A/B testing infrastructure -- Offline benchmarking and model/agent comparison (covered by [Benchmarking](/docs/contributing/architecture/benchmarking)) - -## Proposed Approach - -Focus on the lower-level systems observability first, then build up to higher-level agentic behavior observability. - -## Phase 1: Systems Observability - -**Objective:** Establish awareness and alerting for hard failures. - -This phase focuses on systems metrics we can capture with minimal changes, providing immediate operational visibility. - -### Phase 1a: LLM observability and alerting - -#### Metrics to Capture - -Capture these metrics per LLM API call: - -- Provider -- Model -- Tool -- Latency -- Success / Failure -- Error type and message (if failed) -- Token counts -- Source (CLI/JetBrains/VSCode/etc) - -#### Dashboards - -Common dashboards which offer filtering based on provider, model, and tool: - -- Error rate -- Latency -- Token usage - -#### Alerting - -Implement [multi-window, multi-burn-rate alerting](https://sre.google/workbook/alerting-on-slos/) against error budgets: - -| Window | Burn Rate | Action | Use Case | -|---|---|---|---| -| 5 min | 14.4x | Page | Major Outage | -| 30 min | 6x | Page | Incident | -| 6 hr | 1x | Ticket | Change in behavior | - -Paging should **only occur on Recommended Models when using the Kilo Gateway**. All other alerts should be tickets, and some may be configured to be ignored. - -**Initial alert conditions:** - -- LLM API error rate exceeds SLO (per tool/model/provider) -- Tool error rate exceeds SLO (per tool/model/provider) -- p50/p90 latency exceeds SLO (per tool/model/provider) - -### Phase 1b: Session metrics - -#### Metrics to Capture - -**Per-session (aggregated at session close or timeout):** - -- Session duration -- Time from user input to first model response -- Total turns/steps -- Total tool calls by tool type -- Total errors by error type - - Agent stuck errors (repetitive tool calls, etc) - - Tool call errors -- Total tokens consumed -- Context condensing frequency -- Termination reason (user closed, timeout, explicit completion, error) - -#### Alerting - -None. - -## Phase 2: Agent Tool Usage - -**Objective:** Detect how agents are using tools in a given session. - -### Metrics to Capture - -**Loop and repetition detection:** - -- Count of identical tool calls within a session (same tool + same arguments) -- Count of identical failing tool calls (same tool + same arguments + same error) -- Detection of oscillation patterns (alternating between two states) - -**Progress indicators:** - -- Unique files touched per session -- Unique tools used per session -- Ratio of repeated to unique operations - -### Alerting - -None to start, we will learn. - -## Phase 3: Session Outcome Tracking - -**Objective:** Understand whether sessions are successful from the user's perspective. - -Hard errors and behavior metrics tell us about failures, but we also need signal on overall session health. - -### Metrics to Capture - -**Explicit signals:** - -- User feedback (thumbs up/down) rate and sentiment -- User abandonment patterns (session ends mid-task without completion signal) - -**Implicit signals:** - -May require LLM analysis of session transcripts to detect: - -- Session termination classification (completed, abandoned, errored, timed out) diff --git a/packages/kilo-docs/pages/contributing/architecture/auto-model-tiers.md b/packages/kilo-docs/pages/contributing/architecture/auto-model-tiers.md deleted file mode 100644 index 043f65a4b10..00000000000 --- a/packages/kilo-docs/pages/contributing/architecture/auto-model-tiers.md +++ /dev/null @@ -1,184 +0,0 @@ ---- -title: "Auto Model Tiers" -description: "Architecture of the Auto Model tiers — a family of smart model tiers that match users to the right models without requiring AI expertise" ---- - -# Auto Model Tiers - -## Overview - -Auto Model is a routing system that automatically selects the optimal AI model based on the user's current mode (Code, Architect, Debug, etc.). It comes in multiple tiers so that every user — regardless of budget, preference, or expertise — gets a "just works" experience without needing to understand the AI model landscape. - -Three tiers are user-facing, and one is internal: - -| Tier ID | Audience | Pricing | -|---|---|---| -| `kilo-auto/frontier` | Best paid models | Paid | -| `kilo-auto/balanced` | Strong performance, lower cost | Paid | -| `kilo-auto/free` | Best available free models | Free | -| `kilo-auto/small` | Internal — background tasks | Varies | - -## Problem - -### Users shouldn't need to be AI model experts - -The AI model landscape is overwhelming. There are hundreds of models across dozens of providers, with different pricing, capabilities, context windows, and availability. Most developers just want to write code — they don't want to research which model is best for their task, budget, and workflow. - -Without Auto Model, three groups are underserved: - -1. **Free users** — They see a list of free models that changes on promotional periods and shifting availability. Which one is the best? Which is good for a particular task? They have no way to know without trial and error. - -2. **Cost-conscious users** — They want something better than free but cheaper than frontier. Open-weight models are useful and significantly cheaper, but which one? Which version? The answer changes every few weeks. - -3. **Background tasks** — Kilo uses small models for things like generating session titles and commit messages. These should be invisible and reliable, not dependent on the user's model selection or credit status. - -### Free model churn creates a moving target - -Free models on OpenRouter appear and disappear based on promotional periods. A model that works well today may be gone next week. Users who manually selected a free model discover it's unavailable. Auto Model tiers absorb this churn — when the best free model changes, the mapping updates server-side and users keep working. - -## Tiers - -### Auto: Frontier - -**Who it's for**: Users who want the best available models and are willing to pay for them. - -**What it does**: Routes between the best paid models based on the task — stronger reasoning models for planning and architecture, faster models for code generation and editing. Optimizes for the best balance of capability, speed, and token efficiency. - -**Pricing**: Paid. Uses credits. - -For the current mode-to-model mappings, see the [Auto Model user docs](/docs/code-with-ai/agents/auto-model#tiers). - -### Auto: Balanced - -**Who it's for**: Cost-conscious developers who want better results than free models at a fraction of frontier cost. - -**What it does**: Routes to a cost-effective model based on the API interface used by the client. Requests using the Completions API (default) route to `qwen/qwen3.6-plus`; Responses API requests route to `openai/gpt-5.5`; Messages API requests route to `anthropic/claude-sonnet-4.6`. Unlike Frontier, Balanced does not vary its underlying model by mode. - -**Pricing**: Paid, but significantly cheaper than Frontier. - -For the current mode-to-model mappings, see the [Auto Model user docs](/docs/code-with-ai/agents/auto-model#tiers). - -### Auto: Free - -**Who it's for**: Users who want to try Kilo without a credit card, students, hobbyists, and anyone exploring AI-assisted coding. - -**What it does**: Routes each session to one of the best available free models, selected deterministically based on the session (or user/IP) so a given session sticks with one model. The full candidate pool is determined server-side from curated preferred free models, and updated transparently as availability changes due to promotional periods. Users always get the best free option without having to track which models are currently available. - -**Pricing**: Free. No credits required. - -**Constraints**: Free models do not vary by mode — the same model is used for every mode within a session. Quality will be lower than Frontier or Balanced tiers — this is a tradeoff users accept by choosing free. - -**Data handling**: Auto Free may route to providers that log prompts and outputs and use them to improve their services, including NVIDIA's free endpoints (governed by the [NVIDIA API Trial Terms of Service](https://assets.ngc.nvidia.com/products/api-catalog/legal/NVIDIA%20API%20Trial%20Terms%20of%20Service.pdf)). This is surfaced to users alongside Auto Free mentions in the user-facing docs. - -### Auto: Small (internal) - -**Who it's for**: Not user-facing. Used internally by Kilo for lightweight background tasks (session titles, commit messages, conversation summaries). - -**What it does**: Automatically selects the right small model for lightweight tasks. When the account has a positive balance, it uses a fast paid small model; otherwise it falls back to a free small model. - -**Why it matters**: Users never think about background tasks, and they shouldn't have to. Auto: Small ensures these tasks always work, always feel fast, and never waste credits on an expensive model when a cheap one will do. - -**Implementation**: The `getSmallModel()` function in `packages/opencode/src/provider/provider.ts` prioritizes `kilo-auto/small` when the Kilo provider is active. If the user's provider doesn't have a dedicated small model, it falls back globally to `kilo-auto/small` when available. - -## User experience - -### Model picker - -The three user-facing tiers appear in the model selector: - -| Display Name | Description shown to user | -|---|---| -| Auto: Frontier | Best paid models, automatically matched to your task | -| Auto: Balanced | Strong performance at lower cost | -| Auto: Free | Best free models, no credits required | - -Auto: Small does not appear in the model picker. It is filtered out by the UI (see `KILO_AUTO_SMALL_IDS` in the VS Code extension). - -### Defaults - -- **All new users**: Default to `kilo-auto/free` (defined in `packages/kilo-gateway/src/api/constants.ts`) - -This means a brand-new user gets a working experience immediately — no model selection or credits required. - -### What users see - -The UI shows the tier name (e.g., "Auto: Frontier"), not the underlying model. Users don't need to know or care that their planning request went to Opus and their coding request went to Sonnet. The abstraction is the product. - -## Implementation architecture - -Auto Model uses a split client/server architecture. The actual model-to-mode mappings are not hardcoded in the client — they're served dynamically from the Kilo API, making it possible to update routing without client releases. - -### Server side (Kilo API) - -The Kilo API at `api.kilo.ai` defines which underlying models each `kilo-auto/*` tier routes to per mode. Each auto model is returned with an `opencode.variants` field — a map of mode-specific provider options: - -```json -{ - "opencode": { - "variants": { - "architect": { "model": "anthropic/claude-opus-4.7", ... }, - "code": { "model": "anthropic/claude-sonnet-4.6", ... } - } - } -} -``` - -This is fetched via `packages/kilo-gateway/src/api/models.ts` which parses the `opencode.variants` field from the API response. - -### Client side - -The client-side chain works as follows: - -1. **Model fetching**: `packages/opencode/src/provider/model-cache.ts` caches Kilo Gateway models with a 5-minute TTL, fetching from the Kilo API. - -2. **Variant passthrough**: `packages/opencode/src/provider/transform.ts` — the `variants()` function passes through server-defined variants for Kilo Gateway models directly, rather than computing them locally. - -3. **Variant storage**: `packages/opencode/src/provider/provider.ts` stores `variants` on the model object when the provider is `kilo`. - -4. **Agent variant resolution**: Each agent (mode) specifies a `variant` in its config (`packages/opencode/src/config/config.ts`). At prompt time, `packages/opencode/src/session/prompt.ts` resolves the variant from the agent config and attaches it to the user message. - -5. **LLM call merging**: At call time, `packages/opencode/src/session/llm.ts` merges the variant's options (including the actual underlying model ID) into the provider options sent to OpenRouter. - -### Key files - -| File | Role | -|---|---| -| `packages/kilo-gateway/src/api/constants.ts` | Default model constants (`DEFAULT_MODEL`, `DEFAULT_FREE_MODEL`) | -| `packages/kilo-gateway/src/api/models.ts` | Fetches models from Kilo API, parses `opencode.variants` | -| `packages/opencode/src/provider/model-cache.ts` | Caches Kilo Gateway models with 5-min TTL | -| `packages/opencode/src/provider/provider.ts` | Preserves variants for kilo provider; `getSmallModel()` prioritizes `kilo-auto/small` | -| `packages/opencode/src/provider/transform.ts` | Passes through server-defined variants for Kilo Gateway models | -| `packages/opencode/src/session/prompt.ts` | Resolves variant from agent config, attaches to user messages | -| `packages/opencode/src/session/llm.ts` | Merges variant options into LLM call parameters | -| `packages/opencode/src/config/config.ts` | Agent config schema includes `variant` field | - -## Requirements - -- Unauthenticated users default to `kilo-auto/free` with no configuration required -- All tiers use mode-based routing where the underlying models support it -- When a tier routes to different model families across turns in a conversation, thinking/reasoning blocks from the previous model are stripped to prevent compatibility errors -- Auto Model requires **VS Code/JetBrains extension v5.2.3+** or **CLI v1.0.15+** for mode-based switching. Older versions fall back to a single model for all requests. - -## Risks - -| Risk | User impact | Mitigation | -|---|---|---| -| Free model disappears mid-session | User's next message fails | Fallback chain: primary → secondary → tertiary free model. Graceful error only if all options exhausted. | -| Model quality variance across free/balanced tiers | Inconsistent experience compared to Frontier | Set clear expectations in UI. Curate model lists, don't just pick the cheapest. | -| Cross-family model switching breaks context | Thinking blocks from Model A incompatible with Model B | Strip thinking blocks when the underlying model family changes between turns. Frontier stays within one family so this primarily affects Free tier (which may switch models). | -| Users don't understand the tier differences | Wrong tier selected, poor experience | Clear descriptions in the model picker. Good defaults (Free for all new users) so most users never need to actively choose. | - -## Data and compliance - -- **Frontier**: Uses Anthropic models with no training on user data. -- **Balanced**: As a paid tier, underlying providers are selected with data-handling policies suitable for professional use. Prefer providers with stronger privacy posture when updating the routing. -- **Free**: May route to providers that log prompts and outputs and use them to improve their services, including NVIDIA's free endpoints (see [NVIDIA API Trial Terms of Service](https://assets.ngc.nvidia.com/products/api-catalog/legal/NVIDIA%20API%20Trial%20Terms%20of%20Service.pdf)). Users should avoid submitting personal or confidential data. Surface this disclosure in proximity to every user-facing Auto Free mention. -- **Small**: Same concern as Balanced/Free — the model selected depends on credit status, which may route to providers with different policies. - -## Features for the future - -- **Resolved model transparency**: Show the actual model being used on hover/click for users who want to know -- **Per-agent tier overrides**: Let users pick Frontier for their code agent but Free for explore -- **Auto model changelog**: A status page or in-product notification when tier mappings change -- **Tier analytics**: Dashboard showing which models each tier resolves to, latency, error rates, quality metrics -- **Enterprise open-weight preference**: Organizations that require open-weight models for auditability could enforce the Balanced tier across their team diff --git a/packages/kilo-docs/pages/contributing/architecture/automation-services.md b/packages/kilo-docs/pages/contributing/architecture/automation-services.md new file mode 100644 index 00000000000..6f8b73ff0af --- /dev/null +++ b/packages/kilo-docs/pages/contributing/architecture/automation-services.md @@ -0,0 +1,190 @@ +--- +title: "Automation Services Architecture" +description: "Architecture of Kilo Cloud automation services that dispatch scoped work" +--- + +# Automation Services Architecture + +Automation services turn commands, source-control events, labels, review requests, HTTP webhooks, and schedules into scoped work. + +{% callout type="info" title="Static source scope" %} +This page describes cloud automation boundaries present in `Kilo-Org/cloud`. Static source shows supported code paths, Worker bindings, and deployable surfaces. It does not prove live production enablement or rollout policy. +{% /callout %} + +## How to use this page + +Use this page for trigger-to-execution workflows: what starts work, which owner authorizes it, where orchestration state lives, when Cloud Agent launches, how output returns, and how stuck work recovers. Use [Cloud Platform](/docs/contributing/architecture/cloud-platform) for hosted service topology and [Cloud Security](/docs/contributing/architecture/cloud-security) for trust boundaries. + +## Ownership model + +Automation state and credentials are scoped to owner where supported. Owner is personal user or organization. Personal and organization paths stay separate so credentials, concurrency, findings, and callbacks do not collapse into global automation state. + +| Dimension | Model | +|---|---| +| Owner scope | Personal user owner or organization owner, handled separately where supported | +| Source-control target | GitHub is primary across automation; GitLab target support exists in selected paths | +| Command ingress | GitHub, Slack, and Linear command surfaces are distinct from target repository support | +| Credentials | Web control plane resolves user, bot, or installation token and passes scoped access to Worker or Cloud Agent | +| Callback auth | Workers use internal secrets, service bindings, or per-run callback secrets depending on flow | +| Cloud Agent sandbox | Launches inherit policy-selected sandbox allocation and session-specific workspace paths; see [Cloud Agent](/docs/contributing/architecture/cloud-platform#cloud-agent) | + +## Common lifecycle + +Most automation paths follow same shape. Individual services can stop before Cloud Agent or select different destination. + +```mermaid +flowchart LR + trigger["Command, webhook, label, schedule, or manual dispatch"] + web["Web control plane"] + worker["Worker, queue, or Durable Object"] + agent["Cloud Agent when coding work is needed"] + output["Callback, status update, or product-facing output"] + scm["GitHub or GitLab target repository"] + + trigger --> web + trigger --> worker + web --> worker + worker --> agent + worker --> output + agent --> scm + agent --> output + output --> web +``` + +| Stage | Responsibility | +|---|---| +| Trigger | Accept command, source-control event, label, webhook, schedule, or manual dispatch | +| Authorization owner | Resolve personal or organization scope and permitted credentials | +| Orchestration | Store durable work state and coordinate queues, Durable Objects, callbacks, and alarms | +| Execution target | Launch Cloud Agent only when repository or structured coding work requires it; some flows stop earlier or select another destination | +| Output | Post review, label, pull request, finding state, callback, or destination message | +| Recovery | Retry queue delivery, enforce timeout alarm, reconcile stale state, or dispatch next waiting item | + +## Service inventory + +| Service | Trigger | Orchestration boundary | Execution target | Output or recovery | +|---|---|---|---|---| +| Kilo Bot | GitHub, Slack, or Linear command ingress | Web control plane bot libraries | Cloud Agent for requested repository work | Command response and coding-session result | +| Code Review | Pull-request webhook or review dispatch | Database queue and `code-review-infra` Durable Object per review | Cloud Agent review session | Pull-request feedback; dispatch next waiting review | +| Auto Triage | GitHub issue event or dispatch queue | Web duplicate check and `auto-triage-infra` Durable Object per ticket | Cloud Agent only when classification session is needed | Labels, status, callback, and timeout alarm | +| Auto Fix | `kilo-auto-fix` label or dispatch rule | `auto-fix-infra` Durable Object per fix ticket | Cloud Agent branch and pull-request work | Pull request and lifecycle status callback | +| Security Agent | Interactive or scheduled Dependabot sync plus analysis queue | `security-sync` and `security-auto-analysis` Workers | Model triage in `security-auto-analysis`; Cloud Agent only for selected deep analysis | Finding state, audit records, and stale-analysis cleanup | +| Webhook Agent Ingest | HTTP webhook or scheduled alarm | `webhook-agent-ingest` queue and `TriggerDO` | Cloud Agent or Kilo Chat destination | Destination delivery and queue retry behavior | + +## Kilo Bot ingress and source-control targets + +Kilo Bot command ingress and repository target support are separate concerns. + +| Concern | Current static-source statement | +|---|---| +| Command ingress | GitHub, Slack, and Linear are current Kilo Bot command surfaces | +| GitHub target | Supported across bot, review, triage, fix, security, and Cloud Agent paths | +| GitLab target | Supported in selected Cloud Agent and bot context paths | +| GitLab command ingress | GitLab repository support does not imply note or comment-triggered Kilo Bot commands | + +Do not document GitLab issue notes or merge-request comments as current Kilo Bot trigger surfaces unless source adds explicit ingress handling. + +## Code Review + +Code Review queues pull-request work in database, enforces per-owner concurrency in Next.js dispatch layer, and starts `CodeReviewOrchestrator` Durable Object when slot is available. + +| Concern | Behavior | +|---|---| +| Trigger | Pull-request webhook or review dispatch | +| Authorization owner | Per-owner dispatch slots separate concurrent review work | +| Queue | Reviews wait in database as pending rows | +| Orchestration | Durable Object keeps Cloud Agent connection alive | +| Output | Review feedback is posted back to pull request | +| Recovery | Worker updates database and triggers dispatch of next pending review | + +## Auto Triage + +Auto Triage classifies GitHub issues and applies labels or status updates. Duplicate check happens through web backend. Non-duplicate issues can launch Cloud Agent classification through prepare, initiate, and callback flow. + +| Concern | Behavior | +|---|---| +| Trigger | GitHub issue event or dispatch queue | +| Duplicate check | Calls Next.js API and can complete without Cloud Agent | +| Execution | Cloud Agent session runs structured classification prompt when needed | +| Callback | `POST /tickets/:ticketId/classification-callback` with per-ticket secret | +| Output | High-confidence classification applies labels such as `kilo-auto-fix` for downstream Auto Fix | +| Recovery | Durable Object alarm marks stuck ticket failed | + +## Auto Fix + +Auto Fix receives dispatch requests when issues are selected for automated fixes. Durable Object manages fix session state, launches Cloud Agent, and reports status to backend. + +| Concern | Behavior | +|---|---| +| Trigger | Label or dispatch rule selects issue for fixing | +| Orchestration | `AutoFixOrchestrator` owns fix session state | +| Execution | Cloud Agent creates branch and pull request | +| Output | Worker reports lifecycle updates to internal backend API | + +## Security Agent + +Security Agent splits finding sync from analysis. Findings, queue rows, and owner state remain scoped to personal or organization owner. + +| Concern | Owner | +|---|---| +| Interactive finding sync | Web product checks owner integration permissions, fetches Dependabot alerts, normalizes results, and upserts findings | +| Scheduled finding sync | `security-sync` six-hour cron selects enabled GitHub security-scan owners and emits one owner-level queue message per owner | +| Scheduled sync consumer | `security-sync` filters owner repositories, resolves owner-scoped GitHub credentials through Git Token Service binding, and updates findings, SLA dates, and audit state through Hyperdrive | +| Analysis lifecycle | `security-auto-analysis` claims queued analysis rows, runs model triage, and launches Cloud Agent only when deep analysis is needed | +| Cleanup | Web cron reconciles stale `running` findings only when no matching queue row remains `pending` or `running` | + +Static source proves scheduled sync and separate auto-analysis infrastructure. It does not prove newly synced findings are automatically enqueued for analysis. See [Cloud Platform](/docs/contributing/architecture/cloud-platform#security-agent) for durable topology and [Cloud Security](/docs/contributing/architecture/cloud-security#security-agent-sync-and-cleanup) for trust boundaries. + +## App Builder orchestration boundaries + +App Builder is prompt-driven product orchestration, not normal automation ingress. Cloud Agent owns generated-app coding and iteration. Preview, deployment build, and public deployed-app ingress use separate service boundaries. See [Cloud Platform](/docs/contributing/architecture/cloud-platform#app-generation-boundaries) for canonical phase topology and [Cloud Security](/docs/contributing/architecture/cloud-security#generated-application-preview-and-deployment) for trust boundaries. + +## Webhook Agent Ingest + +Webhook Agent Ingest handles configured trigger endpoints and schedules. `TriggerDO` stores trigger config and scheduled alarms. Queue consumer dispatches selected destination. + +| Dimension | Variants | Notes | +|---|---|---| +| Activation | HTTP webhook | Can apply configured webhook authentication before queued delivery | +| Activation | Scheduled | Uses cron expression and Durable Object alarm; webhook auth is not applicable | +| Destination | `cloud_agent` | Launches Cloud Agent session with webhook or scheduled platform marker | +| Destination | `kiloclaw_chat` | Posts to user-scoped Kilo Chat destination through Kilo Chat service binding | + +```mermaid +flowchart LR + http["HTTP webhook"] + schedule["TriggerDO scheduled alarm"] + queue["Webhook delivery queue"] + consumer["Queue consumer"] + agent["Cloud Agent"] + chat["Kilo Chat destination"] + + http --> queue + schedule --> queue + queue --> consumer + consumer --> agent + consumer --> chat +``` + +## Source map + +Paths below are relative to [`Kilo-Org/cloud`](https://github.com/Kilo-Org/cloud). + +| Service | Source paths | +|---|---| +| Kilo Bot | `apps/web/src/lib/bot/`{% linebreak /%}`apps/web/src/lib/bots/`{% linebreak /%}`apps/web/src/lib/slack-bot/` | +| Code Review | `apps/web/src/lib/code-reviews/`{% linebreak /%}`services/code-review-infra/` | +| Auto Triage | `apps/web/src/lib/auto-triage/`{% linebreak /%}`services/auto-triage-infra/` | +| Auto Fix | `apps/web/src/lib/auto-fix/`{% linebreak /%}`services/auto-fix-infra/` | +| Security Agent | `apps/web/src/lib/security-agent/`{% linebreak /%}`services/security-sync/`{% linebreak /%}`services/security-auto-analysis/` | +| App Builder preview | `apps/web/src/lib/app-builder/`{% linebreak /%}`services/app-builder/` | +| Generated-app deployment | `services/deploy-infra/builder/`{% linebreak /%}`services/deploy-infra/dispatcher/` | +| Webhook Agent Ingest | `services/webhook-agent-ingest/` | +| Cloud Agent | `services/cloud-agent-next/` | + +## Related pages + +- [Architecture Overview](/docs/contributing/architecture) - local and hosted execution map +- [Cloud Platform](/docs/contributing/architecture/cloud-platform) - hosted layers, Cloudflare terms, Cloud Agent topology, and adjacent hosted runtimes +- [Cloud Security](/docs/contributing/architecture/cloud-security) - trust boundaries, persistence, controls, privacy, and shared responsibility +- [Development Patterns](/docs/contributing/architecture/development-patterns) - choose code-ownership seam before changing architecture-facing contracts diff --git a/packages/kilo-docs/pages/contributing/architecture/benchmarking.md b/packages/kilo-docs/pages/contributing/architecture/benchmarking.md deleted file mode 100644 index a0548e6eb17..00000000000 --- a/packages/kilo-docs/pages/contributing/architecture/benchmarking.md +++ /dev/null @@ -1,306 +0,0 @@ ---- -title: "Benchmarking" -description: "Design for benchmarking Kilo Code against models and other agents" ---- - -# Benchmarking - -## Summary - -This document proposes a benchmarking system for Kilo Code with two primary goals: - -1. **Compare models against one another** using the same agent -- measuring task completion, token cost, and total time -2. **Compare agents against one another** using the same model -- e.g., Kilo Code vs Claude Code, or Kilo Code v1.0 vs v1.1 - -The design leverages existing open source infrastructure rather than building a custom harness: - -- **[Harbor](https://harborframework.com)** as the evaluation framework, with **[Terminal-Bench](https://tbench.ai)** and other datasets for task definitions -- **[ATIF](https://harborframework.com/docs/agents/trajectory-format)** (Agent Trajectory Interchange Format) for structured, per-step trace logging -- **[Opik](https://www.comet.com/docs/opik)** for trace ingestion, step-level LLM judge evaluation, and root cause analysis - -The key engineering deliverable is a **Kilo Code Harbor adapter** that runs Kilo CLI autonomously in containerized environments and emits ATIF-compliant trajectories. - -{% callout type="info" %} -This is separate from [production observability](/docs/contributing/architecture/agent-observability), which monitors real user sessions via PostHog. Benchmarking is an offline evaluation system for comparing quality, cost, and performance across models and agents. -{% /callout %} - -## Problem Statement - -As Kilo Code evolves, we need systematic answers to questions like: - -- Did our latest release make the agent better or worse? -- Which model gives the best results for our users at a given price point? -- How does Kilo Code compare to Claude Code, Codex, or other agents on the same tasks? -- When a benchmark score drops, what specific step or decision caused the regression? - -Today we have no structured way to answer these questions. Manual testing is not reproducible, and our existing PostHog telemetry does not capture the turn-by-turn detail needed for easy comparative analysis. - -## Goals - -1. Run Kilo Code against standardized benchmark datasets in a reproducible, containerized environment -2. Compare model performance (same agent, different models) on task completion, token cost, and wall-clock time -3. Compare agent performance (same model, different agents or Kilo versions) on the same metrics -4. Capture detailed per-step traces for root cause analysis when results differ -5. Make it easy to create custom task sets for targeted evaluation or marketing purposes - -**Non-goals:** - -- Production monitoring (covered by [Agent Observability](/docs/contributing/architecture/agent-observability)) -- Automated remediation based on benchmark results - -## Architecture - -``` -┌─────────────────────────────────────────────────────────┐ -│ Harbor Framework │ -│ │ -│ ┌──────────────┐ ┌─────────────┐ ┌─────────────────┐ │ -│ │Terminal-Bench│ │ SWE-bench │ │ Custom Tasks │ │ -│ │ 2.0 │ │ │ │ (Kilo-specific) │ │ -│ └──────┬───────┘ └──────┬──────┘ └───────┬─────────┘ │ -│ └────────────────┼─────────────────┘ │ -│ ▼ │ -│ ┌───────────────────────┐ │ -│ │ Containerized Trial │ │ -│ │ │ │ -│ │ ┌─────────────────┐ │ │ -│ │ │ Agent Under │ │ │ -│ │ │ Test │ │ │ -│ │ │ (kilo --auto) │ │ │ -│ │ └────────┬────────┘ │ │ -│ │ │ │ │ -│ │ ▼ │ │ -│ │ ┌─────────────────┐ │ │ -│ │ │ Model API │ │ │ -│ │ │ (Opus, GPT-5, │ │ │ -│ │ │ Gemini, etc.) │ │ │ -│ │ └─────────────────┘ │ │ -│ └───────────┬───────────┘ │ -│ │ │ -│ ▼ │ -│ ┌───────────────────────┐ │ -│ │ ATIF Trajectory │ │ -│ │ (per-step traces) │ │ -│ └───────────┬───────────┘ │ -└──────────────────────────┼──────────────────────────────┘ - │ - ┌────────────┴────────────┐ - ▼ ▼ -┌──────────────────────┐ ┌──────────────────────────┐ -│ tbench.ai Dashboard │ │ Opik │ -│ - Leaderboard │ │ - Step-level traces │ -│ - Task pass/fail │ │ - LLM judge per step │ -│ - Asciinema replay │ │ - Cost attribution │ -│ - Aggregate scores │ │ - Root cause comparison │ -└──────────────────────┘ └──────────────────────────┘ -``` - -## Components - -### Harbor Framework - -[Harbor](https://harborframework.com) is the evaluation framework built by the Terminal-Bench team. It provides: - -- **Containerized environments** for reproducible task execution -- **Pre-integrated agents**: Claude Code, Codex, Gemini CLI, OpenHands, Terminus-2 -- **A registry of benchmark datasets**: Terminal-Bench, SWE-bench, LiveCodeBench, and more -- **Cloud scaling** via Daytona, Modal, and E2B for running trials in parallel -- **Automatic ATIF trajectory generation** for all integrated agents - -Harbor is the standard evaluation framework used by many frontier labs. Rather than building our own harness, we write a Kilo Code adapter and plug into the existing ecosystem. - -### ATIF (Agent Trajectory Interchange Format) - -[ATIF](https://harborframework.com/docs/agents/trajectory-format) is a standardized JSON format for logging the complete interaction history of an agent run. Each trajectory captures: - -- **Every step**: User messages, agent responses, tool calls, observations -- **Per-step metrics**: Token counts (prompt, completion, cached), cost in USD, latency -- **Tool call detail**: Function name, arguments, and observation results -- **Reasoning content**: The agent's internal reasoning at each step (when available) -- **Aggregate metrics**: Total tokens, total cost, total steps - -This granularity is what enables step-level comparison between runs -- not just "did it pass or fail" but "at step 7, Agent A chose tool X while Agent B chose tool Y." - -### Opik - -[Opik](https://www.comet.com/docs/opik) (by Comet) provides trace ingestion and analysis with a first-class Harbor integration. Running benchmarks through Opik is as simple as: - -```bash -opik harbor run -d terminal-bench@head -a kilo -m anthropic/claude-opus-4 -``` - -Opik adds value beyond what the tbench.ai dashboard provides: - -| Capability | tbench.ai Dashboard | Opik | -|---|---|---| -| Task-level pass/fail | Yes | Yes | -| Aggregate leaderboard | Yes | No | -| Asciinema replay | Yes | No | -| Step-level trace view | No | Yes | -| Step-level LLM judge | No | Yes | -| Cost attribution per step | No | Yes | -| Side-by-side trace comparison | No | Yes | -| Root cause analysis | No | Yes | - -The two dashboards are complementary: tbench.ai for high-level leaderboard comparisons, Opik for drilling into why a specific run succeeded or failed. - -### Datasets - -Harbor's registry provides access to established benchmark datasets. The choice of dataset can vary depending on what you are evaluating: - -| Dataset | Focus | Use Case | -|---|---|---| -| Terminal-Bench 2.0 | CLI/terminal tasks (89 tasks) | General agent capability on hard, realistic tasks | -| SWE-bench | Real GitHub issues in real repos | Software engineering task completion | -| LiveCodeBench | Competitive programming problems | Code generation quality | -| Custom task sets | Whatever you define | Targeted evaluation, marketing, regression testing | - -#### Creating Custom Task Sets - -Creating a custom Harbor task set is straightforward. Each task consists of: - -1. **A Dockerfile** defining the environment (OS, installed packages, repo state) -2. **A task description** (the prompt given to the agent) -3. **A verification script** (tests that determine pass/fail) -4. **Optionally, a reference solution** - -This makes it easy to create task sets that target specific Kilo Code capabilities -- for example, a set of refactoring tasks, or a set of multi-file debugging scenarios. Custom sets can be published to the Harbor registry or kept private. - -See the [Harbor task tutorial](https://www.tbench.ai/docs/task-tutorial) for a step-by-step guide. - -## Deliverables - -### 1. Kilo Code Harbor Adapter - -The primary engineering deliverable. This adapter: - -- **Installs Kilo CLI** in a Docker container -- **Configures autonomous execution** using `kilo run --auto`, which disables all permission prompts so the agent runs fully unattended -- **Translates Harbor task prompts** into Kilo CLI invocations -- **Emits ATIF-compliant trajectories** capturing every step, tool call, and metric - -The adapter follows the same pattern as existing Harbor agents (see the [OpenHands adapter](https://harborframework.com/docs/agents/trajectory-format#openhands-example) for reference). The key implementation detail is the `populate_context_post_run` method that converts Kilo's execution log into ATIF format. - -**Autonomous execution is critical.** Harbor runs containerized trials in parallel and expects agents to execute from start to finish without human intervention. The adapter must ensure: - -- No interactive prompts for API keys (injected via environment variables) -- No permission dialogs for file writes, command execution, etc. -- Graceful timeout handling if the agent gets stuck - -### 2. Custom Task Set Template - -Documentation and examples for creating Kilo-specific task sets: - -- Template Dockerfile and verification script -- Guidelines for writing good task descriptions -- Examples of tasks that highlight coding agent capabilities -- Instructions for publishing to Harbor's registry or running privately - -This enables the team to create targeted benchmarks for marketing, regression testing, or capability evaluation. - -### 3. Opik Integration - -Configure the Opik-Harbor integration for Kilo Code benchmark runs: - -- Set up `opik harbor run` with the Kilo Code adapter -- Define standard LLM judge criteria for step-level evaluation: - - **Tool choice correctness**: Did the agent use the right tool at each step? - - **Reasoning quality**: Was the agent's reasoning at each step sound? - - **Efficiency**: Were there unnecessary or redundant steps? -- Create saved views for common comparison scenarios (model-vs-model, version-vs-version) - -### 4. CI Regression Detection - -{% callout type="note" %} -Lower priority. Implement after the core benchmarking system is working. -{% /callout %} - -Run a small subset of benchmark tasks (10-15) on release branches to catch regressions before shipping. Harbor supports this pattern natively. The subset should be chosen for: - -- Fast execution (under 5 minutes per task) -- High signal (tasks that historically differentiate good and bad agent behavior) -- Stability (deterministic verification, not flaky) - -## Example Workflows - -### Comparing Models - -Run the same Kilo Code agent against Terminal-Bench with different models: - -```bash -# Run with Claude Opus -opik harbor run -d terminal-bench@2.0 -a kilo -m anthropic/claude-opus-4 - -# Run with GPT-5 -opik harbor run -d terminal-bench@2.0 -a kilo -m openai/gpt-5 - -# Run with Gemini 3 Pro -opik harbor run -d terminal-bench@2.0 -a kilo -m google/gemini-3-pro -``` - -Compare results in tbench.ai for aggregate scores and in Opik for step-level analysis of where models diverge. - -### Comparing Agents - -Run different agents against the same dataset with the same model: - -```bash -# Run Kilo Code -opik harbor run -d terminal-bench@2.0 -a kilo -m anthropic/claude-opus-4 - -# Run Claude Code -opik harbor run -d terminal-bench@2.0 -a claude-code -m anthropic/claude-opus-4 -``` - -### Comparing Kilo Versions - -Test a new release against the previous version: - -```bash -# Run current release -opik harbor run -d terminal-bench@2.0 -a kilo@v2.0 -m anthropic/claude-opus-4 - -# Run candidate release -opik harbor run -d terminal-bench@2.0 -a kilo@v2.1-rc1 -m anthropic/claude-opus-4 -``` - -Use Opik's trace comparison view to identify specific steps where the new version regressed or improved. - -### Running a Custom Task Set - -```bash -# Run against a custom Kilo-specific dataset -opik harbor run -d kilo-refactoring@1.0 -a kilo -m anthropic/claude-opus-4 -``` - -## LLM Judge: Two Levels - -Harbor provides task-level judging (did the agent solve the task?). Opik adds step-level evaluation: - -| Level | Tool | What It Tells You | -|---|---|---| -| **Task-level** | Harbor | Pass/fail, score, total time, total cost | -| **Step-level** | Opik | At step N, the agent chose tool X when it should have used tool Y. The reasoning was flawed because of Z. This step cost $0.03 and took 4 seconds. | - -Step-level evaluation is where root cause debugging happens. When a benchmark score drops between versions, you can trace back to the exact decision point that caused the regression. - -## Relationship to Production Observability - -This benchmarking system is complementary to, but separate from, the [Agent Observability](/docs/contributing/architecture/agent-observability) system: - -| Concern | Benchmarking | Production Observability | -|---|---|---| -| **Purpose** | Offline evaluation of agent quality | Real-time monitoring of user sessions | -| **Data source** | Controlled benchmark tasks | Real user interactions | -| **Tools** | Harbor, Opik, tbench.ai | PostHog, custom metrics | -| **When** | Before release, on-demand | Continuously in production | -| **Output** | Leaderboard scores, trace comparisons | Alerts, dashboards, SLO tracking | - -## References - -- [Harbor Framework Documentation](https://harborframework.com/docs) -- [Terminal-Bench 2.0 Paper](https://huggingface.co/papers/2601.11868) -- [ATIF Specification (RFC)](https://github.com/laude-institute/harbor/blob/main/docs/rfcs/0001-trajectory-format.md) -- [Opik Harbor Integration](https://www.comet.com/docs/opik/integrations/harbor) -- [tbench.ai Dashboard](https://www.tbench.ai/docs/dashboard) -- [Harbor Task Tutorial](https://www.tbench.ai/docs/task-tutorial) diff --git a/packages/kilo-docs/pages/contributing/architecture/cli-runtime.md b/packages/kilo-docs/pages/contributing/architecture/cli-runtime.md new file mode 100644 index 00000000000..5cb25aa0895 --- /dev/null +++ b/packages/kilo-docs/pages/contributing/architecture/cli-runtime.md @@ -0,0 +1,331 @@ +--- +title: "CLI Runtime Architecture" +description: "Architecture of the Kilo CLI runtime, daemon, server, persistence, SDK, and indexing" +--- + +# CLI Runtime Architecture + +The CLI (`packages/opencode/`) is Kilo Code's local agent engine. It owns agent execution, tools, sessions, provider integration, configuration, local persistence, directory routing, and HTTP surfaces used by editor clients and Kilo Console. + +{% callout type="info" title="Scope" %} +This page describes repository-defined local runtime behavior. It is not an endpoint catalog or a statement about cloud deployment configuration. +{% /callout %} + +## Concepts + +These terms describe local execution. They are separate from hosted Cloud Agent sessions described in [Cloud Platform](/docs/contributing/architecture/cloud-platform). + +| Term | Meaning | +|---|---| +| Kilo CLI runtime | Local agent engine in `packages/opencode/` | +| `kilo serve` server | Local HTTP and SSE process used by editor clients and Kilo Console; selected browser-oriented paths also use WebSocket | +| Local daemon | Detached reusable `kilo serve` server managed by `kilo daemon` commands | +| Directory context | Normalized local filesystem directory used to select local runtime state | +| Local runtime instance | Directory-keyed runtime context inside one Kilo CLI process | +| Local routing workspace | Optional routing context that can resolve to a local directory or remote target | +| Worktree directory | Alternate git worktree path used as directory context for isolated concurrent work | +| Process-shared state | Runtime service state shared by every directory context in one Kilo CLI process | +| Modes | Configurable agent presets for tools, prompts, restrictions, and behavior | +| MCP | Protocol for extending agent tools | + +One `kilo serve` process can host several local runtime instances. Directory-keyed state stays isolated. Process-shared service state does not. + +## Command entry points + +| Entry point | Command or caller | Runtime model | +|---|---|---| +| Interactive TUI | `kilo` | Attaches to local daemon when available; otherwise starts Bun worker and sends SDK-shaped requests over RPC | +| Headless run | `kilo run` | Uses daemon attach when available, then embedded server fetch fallback | +| Attached run | `kilo run --attach ` | Targets explicit running `kilo serve` server | +| Explicit API server | `kilo serve` | Starts HTTP + SSE server for external local clients | +| Local daemon | `kilo daemon start` | Starts detached `kilo serve` child for reuse | +| Browser console | `kilo console` | Starts or reuses local daemon and opens daemon-served `/console` UI | +| Editor-spawned server | VS Code or JetBrains client | Starts bundled `kilo serve --port 0` child owned by editor client, not local daemon manager | + +```mermaid +flowchart LR + run["kilo run"] + tui["kilo TUI"] + daemon["Detached daemon: kilo serve"] + worker["Bun worker"] + rpc["RPC-backed fetch and global events"] + embedded["Embedded Server.Default().app.fetch"] + serve["Explicit kilo serve"] + editors["VS Code or JetBrains"] + editorServer["Editor-owned kilo serve --port 0"] + runtime["Kilo CLI runtime"] + + run -->|"default first choice"| daemon + run -->|"fallback"| embedded + run -->|"--attach"| serve + tui -->|"default when available"| daemon + tui -->|"fallback"| worker --> rpc --> embedded + editors --> editorServer + daemon --> runtime + embedded --> runtime + serve --> runtime + editorServer --> runtime +``` + +TUI fallback is not direct call from UI thread to embedded fetch. UI thread starts `worker.ts`; worker RPC method constructs request, calls `Server.Default().app.fetch()`, and forwards global events back to UI thread. + +## One server with multiple directory contexts + +Each running editor host starts one editor-owned `kilo serve` server. That server can handle coding sessions for workspace root and additional worktree directories at same time. It does not start separate server process for each directory. + +```mermaid +flowchart LR + views["Editor views
Workspace root and worktrees"] + server["One editor-owned
kilo serve server"] + store["InstanceStore"] + root["Workspace-root
local runtime instance"] + worktree["Worktree
local runtime instance"] + sse["One process-wide
/global/event stream"] + + views -->|"request includes directory"| server + server --> store + store -->|"select by directory"| root + store -->|"select by directory"| worktree + root -->|"event includes directory metadata"| sse + worktree -->|"event includes directory metadata"| sse + sse -->|"client routes event to matching view"| views +``` + +| Step | What happens | Why it matters | +|---|---|---| +| Send request | Editor client includes directory with local API request | CLI can distinguish workspace root from worktree directory | +| Select state | `InstanceStore` normalizes directory and selects directory-keyed local runtime instance | Sessions for alternate directories keep isolated runtime state | +| Return events | Server publishes event with directory metadata through shared `/global/event` SSE stream | Editor client routes event to matching directory and session view | + +This distinction matters for Agent Manager worktrees and JetBrains workspace caches. Directory-keyed state stays isolated. Process-wide event stream and server-owned service state remain shared; snapshot slow-track guard is one example. Authentication, provider routing, SSE, and snapshots appear in later sections. + +## Authentication boundaries + +Three credential boundaries coexist. Keep them separate when tracing request path or changing authentication code. + +| Boundary | Protects | Owner | +|---|---|---| +| Local `kilo serve` access | HTTP, SSE, and selected WebSocket access to local server | Kilo CLI server and spawning local client | +| Outbound provider authentication | Model provider, Kilo Gateway, catalog, and indexing access | Kilo CLI provider router and auth stores | +| Remote MCP OAuth | Browser authorization and credentials for remote MCP server | Kilo CLI MCP runtime | + +### Local `kilo serve` access + +Server Basic Auth is optional. It becomes required when `KILO_SERVER_PASSWORD` is non-empty. Default username is `kilo`; `KILO_SERVER_USERNAME` can override it. + +| Path or mode | Authentication behavior | +|---|---| +| Normal HTTP and SSE | Basic `Authorization` header when server password is configured | +| Browser WebSocket | `auth_token` query parameter accepts base64 `username:password` because browser WebSocket constructors cannot set arbitrary headers | +| Public UI assets | Selected manifest and icon GET paths bypass Basic Auth so browser metadata can load | +| PTY ticket issue | Authenticated `POST /pty/{ptyID}/connect-token` requires expected ticket header and allowed origin | +| PTY ticket connect | `GET /pty/{ptyID}/connect?ticket=...` bypasses Basic middleware, then consumes single-use, scope-bound ticket in PTY handler | +| PTY shell child | Removes `KILO_SERVER_PASSWORD` and `KILO_SERVER_USERNAME` from spawned user-shell environment | + +PTY connect supports two browser-oriented modes: loopback query credential mode (`auth_token`) used by current Console and VS Code Agent Manager paths, and short-lived ticket mode exposed by server API. + +### Outbound provider authentication + +Provider auth records use `api`, `oauth`, or `wellknown` variants in `${Global.Path.data}/auth.json`, written with mode `0600`. `KILO_AUTH_CONTENT` can supply process-local auth JSON. Separate v2 multi-account auth store also exists for account-oriented flows. + +| Path | Behavior | +|---|---| +| Direct providers | Use provider-specific keys, OAuth records, environment values, and configured endpoints | +| Kilo Gateway | Resolves Kilo model access and model catalog through gateway client | +| Anonymous Kilo | If no Kilo key exists, provider loader sets API key value `anonymous`; gateway model catalog can fall back to public unauthenticated endpoint | +| Organization catalog | Kilo model fetch includes organization ID when resolved from config, auth, or environment | +| Model cache | Caches provider model results for five minutes; failed loads invalidate cache for retry | +| Custom endpoints | Provider config can override endpoint and credential options | +| Indexing auth | Resolves indexing-specific Kilo config first, then provider config, auth record, provider options, and `KILO_API_KEY` / `KILO_ORG_ID` environment values | + +### Remote MCP OAuth + +Remote MCP OAuth belongs to CLI runtime. Static headers remain supported. For OAuth servers, CLI handles browser authorization and stores credentials in protected local state; editor clients invoke CLI-owned flow instead of storing MCP credentials themselves. + +## Directory routing and local runtime instances + +Instance routes select directory context in this order: + +1. `directory` query parameter. +2. `x-kilo-directory` request header. +3. Server process cwd. + +Local routing workspace selection is separate. Session workspace, `workspace` query parameter, and `KILO_WORKSPACE_ID` can select workspace context. Configured `KILO_WORKSPACE_ID` keeps requests local to current workspace runtime. Other selected workspaces resolve through workspace-routing adapter to local directory or remote target. + +| Request plan | Behavior | +|---|---| +| Local | Provides resolved directory and optional workspace ID to request handlers | +| Remote | Proxies HTTP or WebSocket request to adapter target | +| Missing workspace | Returns workspace-not-found response | +| Workspace-routing local | Keeps selected local routes and `/console` on local server instead of proxying | + +Remote HTTP proxy responses can include sync fence metadata. Router waits for matching sync progress before returning. `InstanceStore` normalizes directory keys, deduplicates concurrent boots with deferred entry, and disposes directory state through registered cleanup hooks. + +## Core subsystems + +| Subsystem | Purpose | +|---|---| +| Agent runtime | Orchestrates messages, model calls, permissions, questions, and multi-step execution | +| Tool registry | Loads built-in, Kilo-specific, MCP, and readiness-gated semantic search tools | +| LSP client | Provides diagnostics and language intelligence | +| Config service | Merges global, project, organization, managed, and runtime inputs | +| Instance store | Caches normalized directory-scoped runtime contexts | +| SQLite and storage services | Persist structured records and remaining JSON-owned data | +| Snapshot service | Tracks git-backed file baselines for diffs and revert flows | +| Provider router | Resolves direct providers, Kilo Gateway, custom endpoints, and credentials | +| HTTP server | Publishes REST, WebSocket, and SSE surfaces | + +## Daemon lifecycle + +`kilo daemon start|status|stop|restart` manage detached local `kilo serve` child. `kilo console` calls same start path, so it reuses healthy daemon instead of spawning second process. + +| Area | Behavior | +|---|---| +| State file | `${Global.Path.state}/daemon.json`, written with mode `0600` | +| Log file | `${Global.Path.log}/daemon.log`, created with mode `0600` | +| Port allocation | For `--port 0`, scans `4097..4116` and chooses available port | +| Child process | Detached `kilo serve --hostname --port ` process | +| Health | Probes authenticated `/global/health` with 2 second timeout | +| Reuse | Reuses daemon only when process is alive, health succeeds, and installed version matches | +| Cleanup | Terminates stale process when present, clears stale state, then starts replacement | +| Opt-out | `KILO_NO_DAEMON` disables automatic attach by clients; explicit daemon commands still manage daemon | + +Daemon credentials differ from editor-spawned server credentials. Current daemon source stores username `kilo`, password `kilo`, and base64 Basic token in `daemon.json`. File permissions protect this local credential record. Editor clients generate random passwords per spawned server. + +## Persistence + +SQLite is default structured store. + +| Area | Behavior | +|---|---| +| Default database | `${Global.Path.data}/kilo.db` | +| Override | `KILO_DB`; relative paths resolve under data directory; `:memory:` is accepted | +| Runtime pragmas | WAL journal, normal sync, 5 second busy timeout, foreign keys, passive checkpoint, bounded cache | +| Schema changes | Drizzle migrations load from bundled journal in compiled binary or migration directories in development | +| Main tables | Projects, sessions, messages, parts, todos, permissions, session messages, workspaces, sync events, accounts, and account state | +| Legacy migration | On first database creation, CLI runs one-time JSON-to-SQLite migration for projects, sessions, messages, parts, todos, permissions, and shares | + +Some JSON-backed storage remains. Session diffs still use storage path `session_diff`, and configuration, auth, and selected local state files retain their own owners. Snapshot storage is separate from SQLite and JSON storage. + +## Snapshot state boundary + +Snapshot baselines use separate git directory per project worktree: + +```text +${Global.Path.data}/snapshot// +``` + +Snapshot implementation state is directory-keyed through `InstanceState`. One `Snapshot.Service` also owns process-shared slow-snapshot guard state outside directory cache. This distinction matters when multiple Agent Manager worktrees use same `kilo serve` process. + +Slow initial tracking has guarded behavior: + +| Condition | Behavior | +|---|---| +| Fast track | Returns snapshot hash normally | +| Slow interactive track | After default 10 seconds, can prompt to keep waiting or disable snapshots for project | +| Managed Agent Manager turn | Sends `snapshotInitialization: "wait"`; waits without inline question so concurrent started sessions retain baselines | +| Visible long track | Adds temporary progress part after short delay, updates spinner, and removes part when done | +| Disable choice | Writes `"snapshot": false` to project config without disposing active turn | +| Dismissed or untargeted timeout | Interrupts or skips track and suppresses repeat prompt for active service scope | + +## SDK contract + +CLI server contract flows through generated and handwritten layers: + +1. Effect `HttpApi` groups under `packages/opencode/src/server/routes/instance/httpapi/` define routes. +2. `packages/opencode/src/server/routes/instance/httpapi/public.ts` normalizes public OpenAPI to legacy-compatible request and response shapes. +3. Kilo-specific API groups and handlers live under `packages/opencode/src/kilocode/server/httpapi/` and enter shared API through narrow injection seams. +4. `packages/sdk/js/script/build.ts` generates TypeScript v2 client from CLI OpenAPI. +5. `packages/sdk/js/src/v2/client.ts` adds `createKiloClient()` wrapper for directory and workspace routing, Electron and Node fetch compatibility, and clearer empty-response errors. +6. Root `./script/generate.ts` runs SDK generation, emits tracked OpenAPI artifact, updates CLI docs, and formats outputs. +7. JetBrains Gradle build generates build-local OpenAPI, normalizes it, and generates Kotlin OkHttp client. + +Regenerate checked-in JavaScript SDK output after server endpoint changes. Do not hand-edit generated client files. + +## Config precedence + +Later sources override earlier values during instance config load: + +| Order | Source | +|---|---| +| 1 | Legacy Kilo migrations | +| 2 | Organization modes | +| 3 | Auth-record `.well-known/opencode` remote config | +| 4 | Global config files | +| 5 | Explicit `KILO_CONFIG` file | +| 6 | Project `kilo.json[c]` and `opencode.json[c]` files plus discovered config directories | +| 7 | `KILO_CONFIG_DIR` directory | +| 8 | `KILO_CONFIG_CONTENT` | +| 9 | Active Kilo Cloud organization config | +| 10 | Managed config directory | +| 11 | macOS managed preferences | +| 12 | Runtime flag-derived permission, tool, compaction, and plugin behavior | + +Global config files load from `${Global.Path.config}`. Project updates prefer existing config files found in ancestor `.kilo`, `.kilocode`, or `.opencode` directories, then existing project root config files, then create `.kilo/kilo.json`. Global indexing settings can carry provider and storage defaults, but global `indexing.enabled` is stripped so project enablement remains local in effective instance config. + +Signed-in organization modes become normal agent configuration during load. They override migrated legacy modes and remain overridable by later config sources in table. + +Runtime config loading is separate from editor-facing JSON Schema publication. Cloud-served schema improves validation and completion for `kilo.json` and `kilo.jsonc`; it does not load, apply, or override effective runtime config. When adding or changing config key, follow [CLI Config Schema](/docs/contributing/architecture/config-schema) so CLI source and cloud overlay stay aligned. + +## Global and instance SSE + +| Stream | Scope | Payload | +|---|---|---| +| `/event` | One local runtime instance bus | Direct event payloads until instance disposal | +| `/global/event` | Process-wide multiplexed bus | Wrapper with payload and available directory, project, and workspace metadata | + +Both streams send initial `server.connected` event and heartbeat every 10 seconds. VS Code and JetBrains consume `/global/event` so one server connection can route events for multiple directories. + +## Kilo Console + +`kilo console` starts or reuses daemon, opens `/console`, and prints Console launch URL. Browser launch URL embeds daemon Basic credentials so initial request authenticates. + +| Area | Behavior | +|---|---| +| Frontend | Solid/Vite app in `packages/kilo-console/` | +| Server route | `/console` assets resolved by CLI UI handler | +| Release build | CLI executable build copies Console assets beside binary under `bin/console` | +| SDK | Console calls generated JavaScript SDK through `createKiloClient()` | +| Discovery | Console scans `4097..4116` loopback daemon URLs, ranks healthy hits, then tries cached URL fallback | + +Source development can serve built Console assets from package output or build them on demand. This is development behavior, not production deployment claim. + +## Codebase indexing + +`packages/kilo-indexing/` owns indexing engine. CLI bridge injects indexing plugin by default unless default plugins are disabled, then starts indexing asynchronously per normalized directory during instance bootstrap. + +| Area | Behavior | +|---|---| +| Bootstrap | `KilocodeBootstrap` forks indexing initialization so instance startup is not blocked | +| Worker | Dedicated indexing worker owns `CodeIndexManager` and search calls | +| Cache | CLI bridge caches worker entry by directory and disposes it with instance | +| Status | `GET /indexing/status` and `indexing.status` bus event expose progress | +| Tool | `semantic_search` is registered only after indexing reports readiness | +| Worktrees | Agent Manager `.kilo/worktrees/` and legacy `.kilocode/worktrees/` paths return disabled status | +| Empty VS Code window | Extension sets `KILO_DISABLE_CODEBASE_INDEXING=vscode-no-workspace`; bridge reports disabled status | +| Embeddings | Supports Kilo, OpenAI, Ollama, OpenAI-compatible, Gemini, Mistral, Vercel AI Gateway, Bedrock, OpenRouter, and Voyage configuration | +| Vector stores | Supports Qdrant and LanceDB | + +## Source map + +Paths below are relative to [`Kilo-Org/kilocode`](https://github.com/Kilo-Org/kilocode). + +| Concern | Source paths | +|---|---| +| CLI entry points | `packages/opencode/src/cli/cmd/` | +| Daemon | `packages/opencode/src/kilocode/daemon/` | +| HTTP server | `packages/opencode/src/server/` | +| Directory and workspace routing | `packages/opencode/src/server/routes/instance/httpapi/middleware/workspace-routing.ts` | +| SQLite | `packages/opencode/src/storage/db.ts` | +| Snapshots | `packages/opencode/src/snapshot/index.ts`{% linebreak /%}`packages/opencode/src/kilocode/snapshot/track.ts` | +| SDK | `packages/sdk/js/`{% linebreak /%}`script/generate.ts` | +| Console | `packages/kilo-console/`{% linebreak /%}`packages/opencode/src/kilocode/console/` | +| Indexing | `packages/kilo-indexing/`{% linebreak /%}`packages/opencode/src/kilocode/indexing.ts` | + +## Related pages + +- [Architecture Overview](/docs/contributing/architecture) - local and hosted execution map +- [VS Code Extension](/docs/contributing/architecture/vscode-extension) - extension-host ownership, Agent Manager, and webview bridge +- [JetBrains Plugin](/docs/contributing/architecture/jetbrains-plugin) - split-mode client, bundled server lifecycle, and workspace cache +- [Development Patterns](/docs/contributing/architecture/development-patterns) - API generation, code-ownership seams, and fork-maintenance rules +- [CLI Config Schema](/docs/contributing/architecture/config-schema) - editor validation contract for CLI config keys diff --git a/packages/kilo-docs/pages/contributing/architecture/cloud-platform.md b/packages/kilo-docs/pages/contributing/architecture/cloud-platform.md new file mode 100644 index 00000000000..770c4ccc72f --- /dev/null +++ b/packages/kilo-docs/pages/contributing/architecture/cloud-platform.md @@ -0,0 +1,397 @@ +--- +title: "Cloud Platform Architecture" +description: "Architecture overview for Kilo Cloud services and hosted runtimes" +--- + +# Cloud Platform Architecture + +Kilo Cloud is hosted platform layer for authentication, model routing, billing, product configuration, automation, and scoped execution services. Cloud implementation lives in open-source [`Kilo-Org/cloud`](https://github.com/Kilo-Org/cloud) repository. + +{% callout type="info" title="Static source scope" %} +This page describes Worker surfaces, bindings, routes, and code paths present in `Kilo-Org/cloud`. Static source shows deployable architecture, not live production enablement, rollout percentages, retention configuration, or vendor settings. Validate live environment before making production or compliance claims. Use [Kilo Cloud Security Architecture](/docs/contributing/architecture/cloud-security) for trust boundaries and data flows. +{% /callout %} + +## How to use this page + +Use this page to understand hosted service topology: which product boundaries exist, where long-running work executes, and how hosted runtimes relate. For trigger-to-execution workflows, continue to [Automation Services](/docs/contributing/architecture/automation-services). For trust boundaries and controls, continue to [Cloud Security](/docs/contributing/architecture/cloud-security). + +## Hosted layers + +| Layer | Responsibility | Examples | +|---|---|---| +| Web control plane | Identity, organization authorization, billing, product configuration, and API orchestration | Next.js application in `apps/web/` | +| Shared cloud services | Model routing, asynchronous orchestration, real-time delivery, persistence adapters, and operational services | Kilo Gateway, Workers, queues, Durable Objects, R2, KV, Hyperdrive | +| Scoped execution | Runs code or owner-scoped runtime workloads | Cloud Agent, App Builder preview sandbox, deployment builder sandbox, KiloClaw runtime, Gas Town container | +| External providers | Services outside Kilo Cloud trust boundary | Model providers, source-control providers, messaging providers, telemetry providers | + +Where these pages say `owner`, they mean personal user or organization that authorizes scoped product state and credentials. + +## Cloudflare terms + +| Term | Meaning in these docs | +|---|---| +| Worker | Deployed service boundary that handles HTTP requests, queue messages, schedules, or service-binding calls | +| Durable Object | Stateful Cloudflare actor with stable identity, storage, and alarm support | +| Queue | Asynchronous delivery boundary used to separate ingress from long-running work | +| Dead-letter queue | Queue for messages that exhausted normal delivery attempts | +| Service binding | Direct Worker-to-Worker call boundary configured in Wrangler | +| R2 | Object storage for scoped blobs, assets, attachments, or export data | +| KV | Distributed key-value storage for cache, mapping, rollout, and dedup state; not strongly consistent authority | +| Hyperdrive | Cloudflare binding used to connect Workers to PostgreSQL | +| Sandbox | Isolated container execution binding used by selected hosted workloads | + +## Product topology + +```mermaid +flowchart LR + clients["Browser, editor, and mobile clients"] + web["Web control plane"] + gateway["Kilo Gateway"] + automation["Automation Workers"] + agent["Cloud Agent"] + preview["App Builder preview"] + deployBuilder["Deployment builder"] + deployEdge["Deployment dispatcher"] + claw["KiloClaw"] + chat["Kilo Chat / Event Service / Notifications"] + town["Gas Town"] + wasteland["Wasteland"] + repos["GitHub and GitLab repositories"] + providers["Model providers and gateways"] + stores["PostgreSQL, Durable Objects, queues, R2, KV, and analytics stores"] + + clients --> web + clients --> gateway + web -. "short-lived connection ticket" .-> clients + clients -->|"ticketed WebSocket"| chat + web --> automation --> agent + web --> agent + web --> preview + web --> deployBuilder --> deployEdge + web --> claw + chat --> claw + agent --> repos + agent --> providers + claw --> providers + town --> repos + town --> providers + town --> wasteland + gateway --> stores + agent --> stores + preview --> stores + deployBuilder --> stores + claw --> stores + chat --> stores + wasteland --> stores +``` + +Not every hosted flow launches Cloud Agent. Shared services also route model requests, deliver chat events, dispatch notifications, serve generated applications, and coordinate owner-scoped runtimes. + +## Service families + +| Family | Primary services | Role | +|---|---|---| +| Session execution | `cloud-agent-next`{% linebreak /%}`session-ingest`{% linebreak /%}`git-token-service`{% linebreak /%}`notifications` | Hosted coding sessions, session ingestion, repository credentials, and completion push | +| Automation | `code-review-infra`{% linebreak /%}`auto-triage-infra`{% linebreak /%}`auto-fix-infra`{% linebreak /%}`security-auto-analysis`{% linebreak /%}`security-sync`{% linebreak /%}`webhook-agent-ingest` | Queue-backed review, triage, fix, security, and configured trigger flows | +| App generation | `app-builder`{% linebreak /%}`db-proxy`{% linebreak /%}`images-mcp`{% linebreak /%}`deploy-infra/builder`{% linebreak /%}`deploy-infra/dispatcher` | Generated-app preview, data access, image tools, build orchestration, and deployed-app ingress | +| KiloClaw | `kiloclaw`{% linebreak /%}`kiloclaw-billing`{% linebreak /%}`gmail-push`{% linebreak /%}`kiloclaw-inbound-email` | Owner-scoped assistant runtime coordination, billing, and external ingress | +| Real-time chat | `kilo-chat`{% linebreak /%}`event-service`{% linebreak /%}`notifications` | Conversation state, WebSocket delivery, and mobile push | +| Multi-agent orchestration | `gastown`{% linebreak /%}`wasteland` | Town execution and collaborative commons | +| Evaluation and operations | `o11y`{% linebreak /%}`kilo-ops`{% linebreak /%}`model-eval-ingest` | Metrics, alerts, operations, and model-evaluation ingestion | +| Attribution | `ai-attribution` | AI-edit attribution events | + +## Kilo Gateway + +Gateway consists of cloud API routes plus `packages/kilo-gateway/` client integration in `Kilo-Org/kilocode`. It handles account-aware and anonymous-free model access. See [Cloud Security](/docs/contributing/architecture/cloud-security#model-request-gateway) for request branches and endpoint families. + +| Responsibility | Description | +|---|---| +| Authentication | Resolves signed-in account and organization context when required | +| Anonymous free access | Allows eligible free-model requests without account auth under IP-derived context and limits | +| Provider routing | Routes managed-key, BYOK, custom-endpoint, and configured-gateway requests | +| Catalogs | Serves model, provider, embedding-model, and transcription-model surfaces | +| Usage and billing | Records applicable token usage, credits, entitlements, and billing metadata | + +Auto Model clients send stable `kilo-auto/*` tier IDs. Gateway resolves tiers server-side before provider routing so mappings can change without client releases. See [Models and Providers](/docs/gateway/models-and-providers#auto-models) for current tier behavior. + +Eligible gateway requests can include normalized project label for usage attribution and grouping. Label identifies project without sending full repository URL. + +## Cloud Agent + +`services/cloud-agent-next/` is current Cloud Agent session runtime. Each launched unit is a Cloud Agent execution session. Runtime uses queue-first orchestration and session messages. + +Every Cloud Agent execution session receives separate workspace and home paths. Policy-selected sandbox allocation is not universally one container per session. + +| Layer | Isolation rule | +|---|---| +| Working directory | Separate per execution session | +| Home directory | Separate per execution session | +| Git workspace | Separate per execution session | +| Sandbox identity | Policy-selected | +| Default allocation | May share owner-scoped sandbox across sessions | +| Selected organization flows | May use per-session sandbox | +| Devcontainer flows | Use per-session DIND sandbox | + +```mermaid +flowchart TB + callers["Web control plane and automation Workers"] + session["CloudAgentSession Durable Object"] + sandbox["Sandbox"] + small["SandboxSmall"] + dind["SandboxDIND"] + ingest["Session Ingest binding"] + tokens["Git Token Service binding"] + notify["Notifications binding"] + r2["R2 session bucket"] + db["Hyperdrive -> PostgreSQL"] + callback["Callback queue"] + report["Report queue"] + dlq["Report dead-letter queue"] + + callers --> session + session --> sandbox + session --> small + session --> dind + session --> ingest + session --> tokens + session --> notify + session --> r2 + session --> db + session --> callback + session --> report --> dlq +``` + +`services/cloud-agent-next/wrangler.jsonc` defines these bindings. Presence in Wrangler config proves deployable topology, not active production allocation counts or rollout policy. + +## Automation boundaries + +[Automation Services](/docs/contributing/architecture/automation-services) owns trigger, owner-scope, queue, callback, output, and recovery details. This table only shows how automation relates to hosted platform. + +| Service | Hosted execution relationship | +|---|---| +| Kilo Bot | Launches Cloud Agent for requested repository work | +| Code Review | Runs queued review sessions through Cloud Agent | +| Auto Triage | Can classify issue without Cloud Agent during duplicate check; launches Cloud Agent when classification session is needed | +| Auto Fix | Launches Cloud Agent to create issue-fix pull request | +| Security Agent | Runs model triage in `security-auto-analysis`; launches Cloud Agent only for selected deep analysis | +| Webhook Agent Ingest | Delivers configured prompt to Cloud Agent or Kilo Chat destination | + +## App generation boundaries + +App Builder is product orchestration, not normal automation ingress. + +```mermaid +flowchart TB + prompt["User prompt"] --> web["Web App Builder orchestration"] --> coding["Cloud Agent
coding and iteration"] + + subgraph previewBoundary ["Preview boundary: services/app-builder/"] + direction LR + worker["app-builder Worker"] --> repo["GitRepositoryDO"] --> preview["PreviewDO"] --> previewSandbox["Preview Sandbox container"] + end + + subgraph deployBoundary ["Deployment build boundary: services/deploy-infra/builder/"] + direction LR + builder["Deployment builder"] --> orchestrator["DeploymentOrchestrator"] --> buildSandbox["Deployment build Sandbox container"] + end + + subgraph ingressBoundary ["Public ingress boundary: services/deploy-infra/dispatcher/"] + direction LR + dispatcher["Public wildcard ingress"] --> app["Dispatched generated application"] + end + + coding --> worker + coding --> builder + buildSandbox --> dispatcher +``` + +| Boundary | Ownership | +|---|---| +| Coding and iteration | Cloud Agent edits generated application code | +| Preview | `services/app-builder/` owns preview routing and preview sandbox containers | +| Deployment build | `services/deploy-infra/builder/` owns build orchestration in separate sandbox boundary | +| Public deployed-app ingress | `services/deploy-infra/dispatcher/` owns wildcard ingress and dispatch namespace routing | + +## Webhook Agent Ingest + +`services/webhook-agent-ingest/` is configured-trigger boundary. It accepts HTTP webhooks and scheduled alarms, then dispatches selected Cloud Agent or Kilo Chat destination. [Automation Services](/docs/contributing/architecture/automation-services#webhook-agent-ingest) owns activation, authentication, queue, and alarm details. + +## Security Agent + +Security Agent keeps finding sync, analysis dispatch, and sandbox execution separate. + +```mermaid +flowchart TB + github["GitHub Dependabot API"] + postgres["PostgreSQL
Security Agent state"] + + subgraph sync ["Finding sync"] + direction LR + interactive["Interactive web sync"] --> web["Web Security Agent handler"] --> github + cron["security-sync
six-hour cron"] --> queue["Owner-level sync queue"] --> tokens["Git Token Service binding"] --> github + github --> postgres + end + + subgraph analysis ["Analysis"] + direction LR + postgres -->|"Queued analysis row"| worker["security-auto-analysis"] --> triage["Model gateway triage"] --> deep{"Deep analysis needed?"} + deep -->|"Yes"| agent["Cloud Agent
deep analysis"] --> callback["Finding-scoped callback"] --> postgres + deep -->|"No"| postgres + end + + subgraph cleanup ["Stale-analysis cleanup"] + direction LR + cleanupCron["Web cleanup cron"] --> reconcile["Reconcile stale running findings
without active queue work"] --> postgres + end +``` + +PostgreSQL holds owner-scoped findings, analysis queue rows, owner pause or block state, Security Agent configuration, and audit records. See [Automation Services](/docs/contributing/architecture/automation-services#security-agent) for queue lifecycle and its static-source limitation, and [Cloud Security](/docs/contributing/architecture/cloud-security#security-agent-sync-and-cleanup) for trust boundaries. + +## Chat events and notifications + +```mermaid +sequenceDiagram + participant Client as Browser or mobile client + participant Ticket as Event Service ticket API + participant Events as Event Service + participant Session as UserSessionDO + participant Chat as Kilo Chat conversation-state DOs + participant Notify as NotificationChannelDO + participant Expo + participant Queue as Receipt queue + + Client->>Ticket: Request short-lived connection ticket + Ticket-->>Client: Return short-lived ticket + Client->>Events: Open WebSocket with ticket + Events->>Session: Register presence + Chat->>Events: Fan out conversation event + Events-->>Client: Deliver WebSocket event + Chat->>Notify: Request selected conversation push + Notify->>Events: Check presence context + Events-->>Notify: Return presence context + alt User already present + Notify-->>Chat: Suppress push + else Push needed + Notify->>Expo: Send push + Expo-->>Notify: Return receipt + Notify->>Queue: Enqueue receipt + Queue->>Notify: Process receipt and stale-token cleanup + end +``` + +Kilo Chat stores conversation state in Durable Objects and fans events out through Event Service. Notifications checks Event Service presence context before selected pushes and processes Expo receipts asynchronously. See [Cloud Security](/docs/contributing/architecture/cloud-security#chat-events-and-notifications) for ticket and push-delivery trust boundaries. + +## KiloClaw + +KiloClaw is owner-scoped hosted OpenClaw runtime coordination. Durable Objects track instance lifecycle, routing, configuration, and reconciliation. Runtime provider support includes Fly, docker-local development, and Northflank paths; source support does not prove active provider rollout. See [Cloud Security](/docs/contributing/architecture/cloud-security#kiloclaw-ingress) for ingress controls. + +| Ingress path | Auth or validation | Entry boundary | Async handoff | Target | +|---|---|---|---|---| +| Browser request | JWT auth | KiloClaw proxy | None | Owner-scoped runtime | +| One-time access code | Redeemed code and auth cookie | Access gateway | None | Owner-scoped OpenClaw UI | +| Controller machine check-in | Machine API key and derived gateway token | KiloClaw controller route | None | Owner-scoped runtime controller | +| Kilo Chat RPC | Service binding | KiloClaw binding | None | Owner-scoped runtime | +| Cloudflare Email Routing | Alias lookup and bounded parse | `kiloclaw-inbound-email` | Queue | KiloClaw platform service | +| Gmail Pub/Sub push | Google OIDC validation | `gmail-push` | Queue | Owner-scoped runtime controller | + +KiloClaw resolves owner or instance scope before runtime delivery. Table compares ingress boundaries; it does not describe global shared destinations. + +### Fly-provider topology example + +```mermaid +flowchart TB + subgraph worker ["Cloudflare Worker"] + direction LR + auth["JWT auth
tied to Kilo user"] + instanceDO["Per-instance Durable Object"] + dbConnection["Kilo database connection"] + end + + db["Kilo database
Instances
Short-lived access codes
Image catalog
Billing and user preferences"] + proxy["Fly proxy
Per-user Fly app
Per-user encryption
Routes to pinned instance"] + + subgraph flyInstance ["Fly instance: owner-scoped runtime"] + direction TB + subgraph container ["KiloClaw container"] + direction TB + controller["KiloClaw controller
Supervises OpenClaw gateway
Exposes control endpoints
Proxies HTTP and WebSocket traffic"] + openclaw["OpenClaw
Gateway and Control UI"] + tools["Pre-installed tools and skills"] + controller --> openclaw + tools --> openclaw + end + volume["Persistent Fly volume
/root/.openclaw config
/root/clawd workspace"] + volume --> openclaw + end + + dbConnection <--> db + worker <--> proxy + proxy <--> controller +``` + +## Gas Town and Wasteland + +Gas Town is multi-agent orchestration for coding work on repositories. `TownDO` owns town state and `TownContainerDO` owns town container execution. Active town work uses 5-second alarm cadence. Idle towns use 5-minute cadence. + +| Gas Town concept | Role | +|---|---| +| Town | Workspace or project with one or more rigs | +| Rig | Repository attached to town | +| Bead | Unit of work such as issue, task, merge request, or message | +| Convoy | Related beads with dependency tracking | +| Mayor | Persistent coordinator that decomposes and delegates work | +| Polecat | Worker agent that edits code and creates pull requests | +| Refinery | Review agent that runs quality gates and handles merge flow | +| Triage | Ephemeral agent for ambiguous automated-check outcomes | + +Gas Town binds separate `wasteland` Worker through `WASTELAND_SERVICE`. Wasteland uses `WastelandDO` and `WastelandRegistryDO` Durable Objects and DoltHub-backed collaborative commons paths. + +```mermaid +flowchart LR + town["Gas Town TownDO"] + container["TownContainerDO"] + binding["WASTELAND_SERVICE binding"] + wasteland["Wasteland Worker"] + dos["WastelandDO and WastelandRegistryDO"] + dolt["DoltHub-backed collaborative commons"] + + town --> container + town --> binding --> wasteland --> dos --> dolt +``` + +## Observability + +`services/o11y/` is current metrics and alert infrastructure. Higher-order agent outcome analysis remains roadmap work unless backed by separate implementation. + +| Surface | Static-source behavior | +|---|---| +| Alert evaluation | Worker cron runs every minute | +| API metrics | Analytics Engine dataset plus Pipeline stream | +| Session metrics | Analytics Engine dataset plus Pipeline stream | +| Export | Pipelines dual-write R2 Parquet data for Snowflake export infrastructure | +| Alert deduplication | KV namespace stores TTL-based cooldown state | +| Alert configuration | `AlertConfigDO` stores strongly consistent config | +| Session connection | `session-ingest` binds to `o11y` and emits session metrics | + +## Source map + +Paths below are relative to [`Kilo-Org/cloud`](https://github.com/Kilo-Org/cloud). + +| Concern | Source paths | +|---|---| +| Cloud Agent session service and bindings | `services/cloud-agent-next/`{% linebreak /%}`services/cloud-agent-next/wrangler.jsonc` | +| Session ingestion and Git tokens | `services/session-ingest/`{% linebreak /%}`services/git-token-service/` | +| Automation Workers | `services/code-review-infra/`{% linebreak /%}`services/auto-triage-infra/`{% linebreak /%}`services/auto-fix-infra/`{% linebreak /%}`services/webhook-agent-ingest/` | +| Security Agent | `apps/web/src/lib/security-agent/`{% linebreak /%}`services/security-auto-analysis/`{% linebreak /%}`services/security-sync/` | +| App generation and deployment | `services/app-builder/`{% linebreak /%}`services/db-proxy/`{% linebreak /%}`services/images-mcp/`{% linebreak /%}`services/deploy-infra/` | +| KiloClaw | `services/kiloclaw/`{% linebreak /%}`services/kiloclaw-billing/`{% linebreak /%}`services/gmail-push/`{% linebreak /%}`services/kiloclaw-inbound-email/` | +| Chat, events, and notifications | `services/kilo-chat/`{% linebreak /%}`services/event-service/`{% linebreak /%}`services/notifications/` | +| Multi-agent orchestration | `services/gastown/`{% linebreak /%}`services/wasteland/` | +| Observability and operations | `services/o11y/`{% linebreak /%}`services/kilo-ops/`{% linebreak /%}`services/model-eval-ingest/` | +| Attribution | `services/ai-attribution/` | + +## Related pages + +- [Architecture Overview](/docs/contributing/architecture) - local and hosted execution map +- [Automation Services](/docs/contributing/architecture/automation-services) - trigger-to-execution workflows, queue ownership, callbacks, and recovery +- [Cloud Security](/docs/contributing/architecture/cloud-security) - trust boundaries, persistence, controls, privacy, and shared responsibility +- [Development Patterns](/docs/contributing/architecture/development-patterns) - choose code-ownership seam before changing architecture-facing contracts diff --git a/packages/kilo-docs/pages/contributing/architecture/cloud-security.md b/packages/kilo-docs/pages/contributing/architecture/cloud-security.md new file mode 100644 index 00000000000..12d574aa2d9 --- /dev/null +++ b/packages/kilo-docs/pages/contributing/architecture/cloud-security.md @@ -0,0 +1,427 @@ +--- +title: "Kilo Cloud Security Architecture" +description: "Security architecture overview for Kilo Cloud" +--- + +# Kilo Cloud Security Architecture + +This page gives contributors and customer security reviewers a high-level view of Kilo Cloud security architecture. It covers logical topology, trust boundaries, data flows, persistence, execution isolation, external integrations, and shared responsibility. + +{% callout type="info" title="Static source scope" %} +This overview is based on deployable code and configuration in open-source `Kilo-Org/cloud` repository. Static source does not prove live production enablement, rollout percentages, exact regions, retention enforcement, backup policy, WAF rules, credential rotation, or vendor settings. Validate those against live production inventory before making contractual, production, or compliance claims. +{% /callout %} + +{% callout type="info" title="How to use this page" %} +Cloud contributors should read [Cloud Platform](/docs/contributing/architecture/cloud-platform) first, then use this page as cross-cutting security reference. Security reviewers can start here: selected security-specific flows repeat so trust boundaries remain understandable, while linked platform sections provide full topology detail. Use [Automation Services](/docs/contributing/architecture/automation-services) for trigger, queue, callback, and recovery details. +{% /callout %} + +## Executive overview + +Kilo Cloud combines web control plane with Cloudflare-hosted services and scoped execution environments. + +- Browser, editor, and mobile clients connect to public application, gateway, and event surfaces. +- Vercel-hosted Next.js application provides account management, organization authorization, billing, product configuration, and API orchestration. +- Cloudflare Workers provide feature-specific ingress, service bindings, queue-backed workflows, durable coordination, real-time streams, and selected sandbox orchestration. +- Managed PostgreSQL stores relational control-plane records. Durable Objects, queues, KV, R2, and feature-specific analytical stores hold scoped state. +- Cloud Agent coding sessions run in Cloudflare sandbox containers with session-specific workspaces and policy-selected sandbox allocation. +- Generated-app preview and deployment builds run in boundaries separate from Cloud Agent coding sessions. +- KiloClaw assistant instances run in owner-scoped provider-backed runtimes with instance-scoped storage and encrypted configuration delivery. +- Gas Town binds to Wasteland as separate multi-agent orchestration boundary. + +## Logical topology + +```mermaid +flowchart LR + subgraph customer["Customer and Internet-controlled inputs"] + clients["Browser, editor, and mobile clients"] + repos["Customer repositories"] + integrations["Webhooks, email, push, and source-control events"] + end + + subgraph public["Public ingress"] + webEdge["Web application edge"] + gateway["Model gateway routes"] + cloudEdge["Feature-specific Worker ingress"] + deployEdge["Deployment dispatcher"] + end + + subgraph control["Control and service layer"] + web["Web and API application"] + workers["Cloud service Workers"] + chat["Kilo Chat / Event Service / Notifications"] + async["Queues and Durable Objects"] + end + + subgraph execution["Scoped execution"] + agent["Cloud Agent policy-selected sandbox"] + preview["App Builder preview sandbox"] + build["Deployment builder sandbox"] + claw["Owner-scoped KiloClaw runtime"] + town["Gas Town Town container"] + wasteland["Wasteland commons boundary"] + end + + subgraph stores["Managed persistence"] + postgres["Managed PostgreSQL"] + durable["Durable Object state"] + objects["R2 object storage"] + analytics["Analytics and operational stores"] + end + + subgraph providers["External providers"] + model["Model gateways and providers"] + source["Source-control providers"] + messaging["Expo, Gmail, and messaging providers"] + telemetry["Monitoring and telemetry providers"] + end + + clients --> webEdge --> web + clients --> gateway --> model + clients --> cloudEdge + integrations --> cloudEdge + clients --> deployEdge + web --> workers + workers --> async --> durable + workers --> chat + workers --> agent + workers --> preview + workers --> build + workers --> claw + workers --> town --> wasteland + agent --> repos + agent --> source + agent --> model + claw --> model + chat --> messaging + web --> postgres + workers --> postgres + workers --> objects + workers --> analytics + web --> telemetry + workers --> telemetry +``` + +| Layer | Security relevance | +|---|---| +| Client applications | User-controlled environments where authentication begins | +| Web control plane | Identity, organization authorization, billing, configuration, and API orchestration | +| Cloud service layer | Authenticated APIs, asynchronous workflows, durable coordination, streaming, and integration delivery | +| Managed persistence | Scoped records, durable state, queue delivery, object storage, and operational telemetry | +| Cloud Agent execution | Policy-selected sandbox containers with session-specific workspace and home directory | +| Generated-app preview | App Builder preview `Sandbox` container reached through preview routing | +| Generated-app deployment | Deployment builder `Sandbox` container plus dispatcher public wildcard ingress | +| KiloClaw execution | Owner-scoped provider-backed runtime with persistent storage | +| Gas Town and Wasteland | Town-owned container execution plus separate collaborative commons Worker | +| External providers | Third-party trust boundaries invoked by enabled capabilities | + +## Trust boundaries + +| Boundary | What crosses it | Primary controls | +|---|---|---| +| Clients to public application surfaces | Sessions, bearer tokens, requests, WebSockets, and customer input | Session or token validation, organization-aware authorization, security headers, short-lived event tickets, and selected origin allowlists | +| External systems to feature ingress | Webhooks, inbound email, Gmail Pub/Sub push, and source-control events | Provider proof where applicable, optional customer webhook secret, bounded payload handling, validation, idempotency, and queued processing | +| Web control plane to Workers | Session preparation, orchestration, integration delivery, and callbacks | Service credentials, scoped callback tokens, or Cloudflare service bindings by flow | +| Workers to persistence | Relational records, Durable Object state, queue messages, objects, and telemetry | Scoped identifiers, schema validation, service-specific authorization, and feature storage separation | +| Control plane to Cloud Agent | Repository metadata, task input, credentials, and runtime configuration | Policy-selected sandbox identity, session-specific paths, and just-in-time scoped credentials | +| Control plane to generated-app preview | Generated source and preview request traffic | App Builder `PreviewDO`, preview routing, bearer-protected status APIs, and separate preview sandbox | +| Control plane to deployment builder | Generated source and build input | `DeploymentOrchestrator`, build sandbox container, and deployment event callbacks | +| Internet to deployed applications | Public wildcard deployed-app requests | Dispatcher routes, dispatch namespace, KV mappings, and dispatcher rate limit | +| Control plane to KiloClaw runtime | Owner routing, config, proxy traffic, and machine lifecycle | JWT auth, one-time code redemption, derived gateway tokens, machine API keys, Durable Object owner scope, and encrypted config delivery | +| Gas Town to Wasteland | Collaborative orchestration operations | `WASTELAND_SERVICE` binding and separate Wasteland Durable Objects | +| Kilo Cloud to third parties | Repository operations, model requests, billing, notifications, and telemetry | Provider credentials, opt-in where applicable, scoped tokens, and feature-specific routing | + +## Identity and access + +Web control plane uses JWT-backed application sessions and supports multiple sign-in methods. Repository-supported providers include Google, Apple, GitHub, GitLab, Discord, LinkedIn OpenID Connect, WorkOS enterprise SSO, and email magic links. + +Kilo Cloud uses several authorization contexts: + +- Browser sessions for web product use. +- Signed bearer tokens for non-browser clients and selected cloud services. +- Organization membership and role checks for tenant-scoped operations. +- Administrative authorization for restricted operations. +- Internal service credentials, callback tokens, and Cloudflare service bindings. +- Short-lived one-time Event Service connection tickets. +- Provider-specific signature or token checks on supported external ingress. + +Application records commonly scope to user or organization. Cloud Agent durable state scopes to session while sandbox allocation remains policy-selected. KiloClaw runtime scopes to owner or instance rather than global assistant process. + +## Data and persistence + +| Data category | Examples | Processing context | +|---|---|---| +| Identity and account | Email, name, profile metadata, provider links, and account state | Sign-in, account administration, support, and privacy flows | +| Organization and access | Membership, roles, invitations, SSO domains, and audit actors | Tenant authorization and enterprise administration | +| Billing | Customer IDs, subscription state, transaction references, and invoices | Entitlement, reconciliation, and financial record keeping | +| Usage and operations | Model, token counts, costs, feature status, session IDs, timestamps, and error summaries | Metering, support, and reliability | +| Repository and automation | Repository metadata, refs, issue or review context, webhook payloads, and findings | Source control, Cloud Agent work, review automation, and security features | +| AI and session content | Prompts, responses, conversation history, attachments, and session events | Inference, Cloud Agent sessions, KiloClaw, and enabled experiments | +| Integration config | OAuth metadata, provider config, webhook settings, and customer secrets | Enabled integrations and owner-scoped runtime config | +| Network and abuse telemetry | IP address, user agent, browser signals, and risk metadata | Abuse prevention, fraud controls, and investigation | +| Mobile and notification | Device tokens, notification status, and mobile-store transaction metadata | Mobile auth, subscriptions, and notifications | + +| Persistence surface | Primary role | Security review note | +|---|---|---| +| Managed PostgreSQL | Relational system of record and workflow state | Vendor, regions, backups, and network controls require live validation | +| Durable Objects | Scoped coordination and feature state | Used for sessions, chat, notifications, ingestion, preview, and orchestration | +| Queues | Async processing, retries, and dead-letter handling | Used to separate public ingress and long-running work | +| R2 | Session blobs, attachments, feature assets, templates, and telemetry export | Bucket lifecycle, encryption, residency, and deletion require live validation | +| KV | Cache, rollout, mapping, and dedup state | Not strongly consistent authority | +| Analytical stores | Analytics Engine datasets, Pipeline export, and optional specialized stores | Active providers and retention require live validation | +| Runtime storage | Owner-scoped KiloClaw workspace and config persistence | Separate execution boundary tied to assigned runtime provider | + +## Core data flows + +### Model request gateway + +Gateway exposes endpoint families for chat API kinds, autocomplete, transcription, embeddings, catalogs, anonymous free access, custom LLM endpoints, and BYOK routing. + +| Family | Static-source surfaces | +|---|---| +| Chat APIs | `/api/gateway` and `/api/openrouter` aliases for chat completions, responses, and messages | +| FIM and edit | `/api/fim/completions`, `/api/edit/completions` | +| Transcription | Audio transcription routes | +| Embeddings | Embedding proxy routes | +| Catalogs | Models, transcription models, embedding models, providers, models-by-provider, and validation routes | +| Provider choice | Managed provider path, direct BYOK, custom LLM endpoint, organization settings, and configured gateway paths | +| Anonymous free | Eligible free-model requests only, with IP-derived context and limits | + +Authenticated and anonymous requests diverge after model eligibility and free-model limit checks. + +```mermaid +flowchart TB + client["Client model request"] + route["Gateway route and API-kind validation"] + free["Eligible free model?"] + auth["Valid account auth?"] + signed["Authenticated account / organization context"] + ip["IP-derived anonymous context anon:{ip}"] + reject["Reject paid unauthenticated request"] + limits["Free-model rate limit and usage log"] + provider["Managed, BYOK, custom, or configured provider routing"] + usage["Usage and billing metadata"] + + client --> route --> free + free -->|yes| limits --> auth + free -->|no| auth + auth -->|yes| signed --> provider + auth -->|no, eligible free| ip --> provider + auth -->|no, paid| reject + provider --> usage +``` + +Static source details: + +- Paid model requests require authentication. +- Anonymous access applies only to eligible free models. +- Anonymous context derives from request IP and uses synthetic ID format `anon:{ip_address}`. +- Free-model requests use rate limits. General path checks IP-based usage; server-side feature traffic from Cloudflare IPs can use user-based limits. +- Anonymous free requests also use promotion limit by IP. +- `free_model_usage` records support limits. `apps/web/vercel.json` defines hourly cleanup cron and cleanup route code removes rows older than seven days in batches. + +Seven-day cleanup is code-defined retention path, not proof of live retention execution. Validate deployed cron and database policy before external retention claim. + +### Cloud Agent session + +```mermaid +sequenceDiagram + participant Client + participant Web as Web control plane + participant Service as Cloud Agent + participant State as CloudAgentSession DO + participant Sandbox as Policy-selected sandbox + participant Source as Source-control provider + participant Model as Model gateway or provider + + Client->>Web: Start authorized coding task + Web->>Service: Create scoped session + Service->>State: Persist admitted work and metadata + Service->>Sandbox: Prepare workspace and execution environment + Sandbox->>Source: Fetch authorized repository content + Sandbox->>Model: Send configured model request + Sandbox-->>State: Stream session events + State-->>Client: Replay and stream authorized output +``` + +Every Cloud Agent execution session receives separate workspace and home paths. Policy-selected sandbox allocation is not universally one container per session. Default allocation may share owner-scoped sandbox across sessions; selected organization flows may use per-session sandbox; devcontainer flows use per-session DIND sandbox. See [Cloud Agent](/docs/contributing/architecture/cloud-platform#cloud-agent) for canonical topology, isolation matrix, and binding inventory. + +### Generated application preview and deployment + +```mermaid +flowchart LR + prompt["App Builder prompt"] + coding["Cloud Agent coding and iteration"] + preview["app-builder PreviewDO"] + previewSandbox["Preview Sandbox container"] + builder["deploy-infra/builder DeploymentOrchestrator"] + buildSandbox["Deployment build Sandbox container"] + dispatcher["deploy-infra/dispatcher public wildcard ingress"] + app["Dispatched generated app"] + + prompt --> coding --> preview --> previewSandbox + coding --> builder --> buildSandbox --> dispatcher --> app +``` + +App Builder orchestrates prompt-driven product flow. Cloud Agent owns coding and iteration only. `services/app-builder/` owns preview routing and preview sandbox; `services/deploy-infra/builder/` owns deployment build sandbox; `services/deploy-infra/dispatcher/` owns public deployed-app ingress. See [App generation boundaries](/docs/contributing/architecture/cloud-platform#app-generation-boundaries) for canonical phase topology. Deployment builder config enables Sentry instrumentation; static source currently includes `sendDefaultPii: true`. Treat deployment telemetry payload shape, masking, access, and retention as review item, not assumed privacy property. + +### Chat events and notifications + +```mermaid +sequenceDiagram + participant Client as Browser or mobile client + participant Ticket as Event Service ticket API + participant Events as Event Service + participant Session as UserSessionDO + participant Chat as Kilo Chat conversation-state DOs + participant Notify as NotificationChannelDO + participant Expo + participant Queue as Receipt queue + + Client->>Ticket: Request bearer-authenticated connection ticket + Ticket-->>Client: Return short-lived ticket + Client->>Events: Open WebSocket with ticket + Events->>Session: Register per-user presence + Chat->>Events: Fan out conversation event + Events-->>Client: Deliver WebSocket event + Chat->>Notify: Request selected conversation push + Notify->>Events: Check presence context + Events-->>Notify: Return presence context + alt User already present + Notify-->>Chat: Suppress push + else Push needed + Notify->>Expo: Send push + Expo-->>Notify: Return receipt + Notify->>Queue: Enqueue delayed receipt + Queue->>Notify: Process receipt and stale-token cleanup + end +``` + +Kilo Chat binds to Event Service and Notifications. Event Service consumes one-time tickets before WebSocket upgrade and places connections in per-user Durable Objects. Notifications service uses per-user Durable Objects, checks presence context for conversation pushes, sends Expo push, and processes delayed receipts. See [Chat, events, and notifications](/docs/contributing/architecture/cloud-platform#chat-events-and-notifications) for canonical service topology. + +### KiloClaw ingress + +```mermaid +flowchart TB + subgraph ingress ["Public and external ingress"] + direction LR + browser["Browser request"] --> jwt["JWT validation"] + code["One-time code"] --> access["Access gateway form"] + machine["Runtime machine"] --> machineAuth["API key + gateway token"] + chat["Kilo Chat RPC binding"] + email["Cloudflare Email Routing"] --> parse["Alias lookup + bounded parse"] + gmail["Gmail Pub/Sub push"] --> oidc["Google OIDC validation"] + end + + subgraph coordination ["KiloClaw coordination"] + direction LR + proxy["KiloClaw proxy"] + scope["Resolve owner or instance scope"] + instance["Owner- or instance-scoped
Durable Object"] + redeem["Hyperdrive-backed redemption
Auth cookie + derived gateway token"] + controller["/api/controller/checkin"] + emailQueue["Inbound email queue"] + gmailQueue["Gmail delivery queue"] + platform["KiloClaw platform delivery"] + controllerDelivery["KiloClaw controller delivery"] + end + + runtime["Provider-backed runtime"] + ui["OpenClaw UI"] + + jwt --> proxy --> scope + access --> redeem --> scope + machineAuth --> controller --> scope + chat --> scope + parse --> emailQueue --> platform --> scope + oidc --> gmailQueue --> controllerDelivery --> scope + scope --> instance --> runtime + scope --> ui +``` + +KiloClaw separates lifecycle coordination from runtime process. Fly is provider path and legacy fallback, docker-local supports development, and Northflank support exists in provider model. Active rollout must be checked in live environment. See [KiloClaw](/docs/contributing/architecture/cloud-platform#kiloclaw) for canonical runtime topology. + +### Gas Town and Wasteland + +Gas Town and Wasteland are separate trust boundaries. Gas Town owns town state and container execution. It calls Wasteland through `WASTELAND_SERVICE` binding; Wasteland owns separate Durable Objects and DoltHub-backed collaborative commons paths. See [Gas Town and Wasteland](/docs/contributing/architecture/cloud-platform#gas-town-and-wasteland) for canonical topology and orchestration concepts. + +### Security Agent sync and cleanup + +Security Agent interactive web sync and scheduled Worker sync are separate paths. `services/security-sync` config defines six-hour cron, owner-level queue, Hyperdrive access, and Git Token Service binding. `apps/web/vercel.json` defines stale cleanup every 15 minutes. Cleanup marks stale `running` findings failed only when no matching queue row remains `pending` or `running`. Static source does not prove scheduled sync enqueues newly synced findings for auto-analysis. + +| Boundary | Control | +|---|---| +| GitHub vulnerability access | Installation tokens and `vulnerability_alerts` permission | +| Owner scope | Findings, analysis queue rows, sync queue messages, and owner state scope to one user or organization owner | +| Scheduled sync credentials | Git Token Service binding resolves owner-scoped GitHub credentials | +| Internal worker calls | Bearer auth, internal API secret, or service bindings depending on flow | +| Analysis callback | Derived callback token scopes completion to Security Agent callback and finding ID | +| Sandbox execution | Optional deep analysis inherits Cloud Agent policy-selected sandbox allocation and session-specific workspace isolation | +| Auditability | Finding sync and analysis activity write to Security Agent audit surfaces | + +See [Cloud Platform](/docs/contributing/architecture/cloud-platform#security-agent) for topology and [Automation Services](/docs/contributing/architecture/automation-services#security-agent) for queue ownership. + +## Observability + +Observability is a security-review boundary because operational metrics and exports can contain customer-linked identifiers and diagnostic content. `services/o11y/` defines Worker-backed metrics, alerts, Analytics Engine datasets, Pipeline streams, R2 Parquet export infrastructure, KV cooldown state, and `AlertConfigDO`. See [Observability](/docs/contributing/architecture/cloud-platform#observability) for canonical topology. Active providers, access, filtering, and retention require live validation. + +Higher-order agent outcome analysis is roadmap work unless separate source proves implementation. + +## Security controls summary + +| Control area | Architecture-level control | +|---|---| +| Authentication | JWT-backed sessions, bearer tokens, machine tokens, one-time code redemption, and provider-specific ingress proof | +| Authorization | User, organization, role, owner, instance, and administrative checks by operation | +| Abuse prevention | Turnstile, fraud telemetry, blocking logic, free-model limits, bounded external payload handling, and deployment threat scanning | +| Internal service separation | Service bindings, callback tokens, and service credentials separate public access from orchestration | +| Execution isolation | Cloud Agent workspaces, preview sandbox, deployment builder sandbox, town container, and owner-scoped KiloClaw runtimes | +| Secret handling | Protected config storage, encrypted delivery for supported runtime secrets, fail-closed KiloClaw bootstrap, and sensitive-log prohibitions | +| Privacy | Soft-delete and anonymization workflows, webhook-header redaction, explicit experiment paths, and purpose-specific retention paths | +| Reliability | Durable coordination, queues, retries, dead-letter patterns, idempotency handling, and reconciliation | +| Browser hardening | HSTS, framing restrictions, MIME protection, referrer policy, cross-origin policies, permissions restrictions, and configurable CSP | +| Observability | Structured metrics, log aggregation, alerts, R2 Parquet export infrastructure, and production-managed access and retention | + +## Third-party integration categories + +| Status | Meaning | +|---|---| +| Platform dependency | Represented as part of architecture or deployment path | +| Feature-dependent | Invoked when capability is enabled; live production enablement needs validation | +| Customer-configured | Opt-in integration or endpoint selected by customer | +| Runtime-selected | Supported by repository but active provider or rollout is outside static source | +| Production validation required | Referenced by source but live settings must be checked before external claim | + +| Category | Examples | Security role | +|---|---|---| +| Hosting and storage | Vercel, Cloudflare, managed PostgreSQL, runtime hosting, caches, vector indexes, Snowflake | Hosting, edge, persistence, runtime, indexing, and analytics | +| Identity and source control | Google, Apple, GitHub, GitLab, Discord, LinkedIn, WorkOS, Turnstile, Stytch, Google Web Risk | Sign-in, SSO, abuse prevention, repositories, webhooks, and deployment scanning | +| Models and search | OpenRouter, Vercel AI Gateway, direct providers, BYOK, custom endpoints, Exa, Mistral | Inference, search, embeddings, and customer-selected outbound boundaries | +| Billing and messaging | Stripe, Apple App Store, Churnkey, Impact.com, Mailgun, Customer.io, Expo, Gmail, Slack, Discord, Telegram, Linear | Billing, messages, mobile push, email, and customer-configured communication | +| Monitoring and operations | Sentry, PostHog, Axiom, Analytics Engine, Pipelines, Better Stack | Error reporting, analytics, logs, export, and heartbeat monitoring | + +## Privacy logging and retention + +Kilo Cloud includes user soft-delete flows that anonymize direct user PII, invalidate auth material, delete many user-owned records and integrations, remove selected object-storage content, and request deletion from selected downstream services. Financial, audit, anti-abuse, and product-specific records can have retention exceptions. + +Operational telemetry can contain customer-linked identifiers and diagnostic content. Telemetry-enabled product surfaces can also submit assistant-response feedback with limited correlation metadata. Production access, filtering, retention, and vendor config remain required review areas. Pay special attention to deployment-builder Sentry payloads, mobile diagnostics, replay masking, screenshots, object storage, Durable Object state, vector stores, analytical stores, runtime volumes, and backups. + +Data paths vary by product and enabled integration. State residency and retention commitments require validation against live production inventory. + +## Shared responsibility + +Kilo Cloud provides platform controls for auth, scoped authorization, internal-service separation, durable coordination, execution isolation, and protected handling of supported secrets. + +Customers remain responsible for decisions that expand enabled trust boundaries: + +- Repositories, organizations, users, and source-control installations they authorize. +- Models, BYOK credentials, custom endpoints, and optional integrations they enable. +- Setup commands, repository code, MCP servers, and third-party tools they permit inside isolated session or owner-scoped runtime. +- Customer-configured endpoints and credentials meeting customer security, privacy, and compliance needs. +- Generated changes reviewed before merge or deployment. + +## Related pages + +- [Architecture Overview](/docs/contributing/architecture) - local and hosted execution map +- [Cloud Platform](/docs/contributing/architecture/cloud-platform) - hosted layers, Cloudflare terms, Cloud Agent topology, and adjacent hosted runtimes +- [Automation Services](/docs/contributing/architecture/automation-services) - trigger-to-execution workflows, queue ownership, callbacks, and recovery +- [Development Patterns](/docs/contributing/architecture/development-patterns) - choose code-ownership seam before changing architecture-facing contracts diff --git a/packages/kilo-docs/pages/contributing/architecture/config-schema.md b/packages/kilo-docs/pages/contributing/architecture/config-schema.md index c4cba931c05..2fa79869a20 100644 --- a/packages/kilo-docs/pages/contributing/architecture/config-schema.md +++ b/packages/kilo-docs/pages/contributing/architecture/config-schema.md @@ -1,33 +1,105 @@ --- title: "CLI Config Schema" -description: "How the Kilo CLI config JSON Schema is served at app.kilo.ai/config.json" +description: "How CLI runtime config and editor-facing JSON Schema stay aligned" --- # CLI Config Schema -The JSON Schema referenced by `"$schema": "https://app.kilo.ai/config.json"` in `kilo.json` files is served by the cloud repo. It is a runtime overlay of the upstream opencode schema with Kilo-specific additions on top. +Kilo config has two related but separate paths: -## Flow +- Kilo CLI runtime loads and merges config locally. +- Cloud-served JSON Schema gives editors validation and completion for `kilo.json` and `kilo.jsonc`. -1. Client fetches `https://app.kilo.ai/config.json`. -2. Cloud route `apps/web/src/app/config.json/route.ts` fetches `https://opencode.ai/config.json`, runs `merge()` on it, and returns the result. -3. `merge()` overlays three sections from `apps/web/src/app/config.json/extras.ts`: - - `top` — top-level keys like `commit_message`, `remote_control`, nullable `model` / `small_model` - - `agents` — Kilo primary agents (`ask`, `debug`, `orchestrator`) - - `experimental` — `codebase_search`, `openTelemetry` +JSON Schema does not load, apply, or override runtime config. -## Adding a new Kilo-only config key +```jsonc +{ + "$schema": "https://app.kilo.ai/config.json" +} +``` -The source of truth is the zod schema in `packages/opencode/src/config/config.ts`. The cloud overlay must match it. +## Two separate paths -1. Add the zod field with a `kilocode_change` marker in `config.ts`. -2. Generate the JSON Schema shape: `bun --bun packages/opencode/script/schema.ts /tmp/kilo.json`, then `jq '.properties.' /tmp/kilo.json`. -3. Paste the shape into the correct bucket in `apps/web/src/app/config.json/extras.ts` in the [cloud repo](https://github.com/Kilo-Org/cloud). - - Top-level → `top`; under `experimental` → `experimental`; new primary agent → `agents`; anywhere else → add a new bucket and extend `merge()` in `route.ts`. -4. Add an assertion in `apps/web/src/tests/cli-config-schema.test.ts`. +```mermaid +flowchart LR + subgraph runtime ["Runtime config loading"] + files["Global, project, organization,
managed, and runtime config sources"] --> loader["Kilo CLI config loader"] --> effective["Effective runtime config"] + end -If step 3 is skipped, users with `$schema: https://app.kilo.ai/config.json` will see "unknown property" warnings for the new key. + subgraph schema ["Editor validation and completion"] + info["Config.Info
Effect Schema"] --> generated["Locally generated schema
for verification"] + upstream["https://opencode.ai/config.json"] --> overlay["Kilo Cloud merge route"] + extras["Kilo extras.ts overlay buckets"] --> overlay --> endpoint["https://app.kilo.ai/config.json"] --> editor["Editor validation and completion"] + generated -. "Keep aligned" .-> extras + end +``` -## Caching +Changing runtime config precedence affects first path. Adding or changing config key affects both paths because editor schema must describe keys CLI accepts. See [CLI Runtime config precedence](/docs/contributing/architecture/cli-runtime#config-precedence) for runtime merge order. -The cloud route caches the upstream fetch for 1 hour (`next: { revalidate: 3600 }`) and emits `s-maxage=3600, stale-while-revalidate=3600`, so the response is served from the Cloudflare + Vercel edge cache for all but one request per hour per region. +## Source of truth + +Canonical CLI config source is Effect Schema `Config.Info` in `packages/opencode/src/config/config.ts` in [`Kilo-Org/kilocode`](https://github.com/Kilo-Org/kilocode). CLI derives `.zod` compatibility surface from Effect Schema for plugin and SDK consumers. Do not maintain separate handwritten Zod definition for Kilo config fields. + +## Cloud schema endpoint + +Static source review of [`Kilo-Org/cloud`](https://github.com/Kilo-Org/cloud) shows this route behavior: + +1. Editor fetches `https://app.kilo.ai/config.json` because config file references `$schema`. +2. Cloud route `apps/web/src/app/config.json/route.ts` fetches `https://opencode.ai/config.json`. +3. Route runs `merge()` and returns upstream schema with Kilo additions and overrides. +4. `merge()` overlays buckets from `apps/web/src/app/config.json/extras.ts`. + +Cloud source defines 1-hour upstream revalidation and edge-cache headers. This describes checked-in route behavior, not live deployment or cache state. + +## Overlay buckets + +Reviewed cloud source overlays: + +| Bucket | Purpose | +|---|---| +| `top` | Top-level Kilo keys and overrides | +| `agents` | Kilo primary agents under `agent` | +| `experimental` | Kilo experimental keys under `experimental` | + +Nested CLI fields outside these buckets need dedicated overlay bucket and matching `merge()` logic. + +## Failure mode + +If cloud overlay misses valid CLI field, CLI can accept config while editor reports `unknown property`. Opposite drift is also possible: cloud schema can advertise field that runtime no longer accepts. + +Treat schema synchronization as cross-repository contract. Tests should detect both missing valid fields and stale overlay entries. Keep branch-specific drift findings in tracked issues or test output, not this architecture page. + +## Adding or changing Kilo-only config key + +1. Add or update Effect Schema field with `kilocode_change` marker in `packages/opencode/src/config/config.ts`. +2. Generate JSON Schema shape: + +```sh +bun --bun packages/opencode/script/schema.ts /tmp/kilo.json +jq '.properties.' /tmp/kilo.json +``` + +3. Update matching bucket in `apps/web/src/app/config.json/extras.ts` in [cloud repo](https://github.com/Kilo-Org/cloud). +4. Extend `merge()` in `apps/web/src/app/config.json/route.ts` when new nested bucket is required. +5. Add assertion in `apps/web/src/tests/cli-config-schema.test.ts`. +6. Audit stale overlay entries as well as missing additions. + +{% callout type="warning" title="Cross-repository change" %} +CLI schema source lives in `Kilo-Org/kilocode`. Public editor schema overlay lives in `Kilo-Org/cloud`. Config-key change is incomplete until both repositories agree. +{% /callout %} + +## Source map + +Repository column identifies source root for each relative path. + +| Repository | Source path | Role | +|---|---|---| +| `Kilo-Org/kilocode` | `packages/opencode/src/config/config.ts` | Canonical Effect Schema and derived `.zod` surface | +| `Kilo-Org/cloud` | `apps/web/src/app/config.json/route.ts` | Cloud overlay route | +| `Kilo-Org/cloud` | `apps/web/src/app/config.json/extras.ts` | Kilo overlay buckets | +| `Kilo-Org/cloud` | `apps/web/src/tests/cli-config-schema.test.ts` | Cloud schema assertions | + +## Related pages + +- [CLI Runtime](/docs/contributing/architecture/cli-runtime#config-precedence) - runtime config loading and precedence +- [Development Patterns](/docs/contributing/architecture/development-patterns) - shared-file markers, Kilo-owned boundaries, and cross-repository contributor workflow diff --git a/packages/kilo-docs/pages/contributing/architecture/development-patterns.md b/packages/kilo-docs/pages/contributing/architecture/development-patterns.md new file mode 100644 index 00000000000..574182c09d1 --- /dev/null +++ b/packages/kilo-docs/pages/contributing/architecture/development-patterns.md @@ -0,0 +1,195 @@ +--- +title: "Development Patterns" +description: "Contributor patterns for Kilo architecture implementation and fork maintenance" +--- + +# Development Patterns + +This page turns architecture boundaries into contributor decisions. Read [Architecture Overview](/docs/contributing/architecture) and relevant subsystem page first, then use this guide before editing architecture-facing code in `Kilo-Org/kilocode` or its cross-repository contracts. + +{% callout type="info" title="Default rule" %} +Prefer Kilo-owned seams over broad changes to shared OpenCode files. Follow neighboring style when changing existing modules. +{% /callout %} + +## How to use this page + +1. Identify owning subsystem in architecture docs. +2. Choose narrowest source boundary that can hold change. +3. Update generated or cross-repository contracts when public surface changes. +4. Run smallest relevant checks plus affected repository guards. + +## Where should change live? + +| Change shape | Preferred location or action | Reason | +|---|---|---| +| Additive Kilo CLI behavior | `packages/opencode/src/kilocode/` | Keeps Kilo-only behavior out of upstream-owned files | +| Kilo CLI test for additive behavior | `packages/opencode/test/kilocode/` | Avoids shared tests that encode only Kilo behavior | +| Required shared OpenCode edit | Small import, route, or injection seam in shared file plus `kilocode_change` marker | Keeps upstream diff narrow and merge review obvious | +| VS Code, JetBrains, docs, indexing, UI, gateway, or telemetry change | Existing Kilo-owned package | These packages are Kilo-owned; do not add `kilocode_change` markers | +| CLI server endpoint change | Effect `HttpApi` route plus handler; then run root SDK generator | Keeps server contract and generated JavaScript SDK aligned | +| JetBrains API contract change | Shared CLI OpenAPI change; let Gradle regenerate build-local Kotlin client | Kotlin client is generated during JetBrains build | +| Kilo-only config-key change | Update CLI Effect Schema and cloud JSON Schema overlay | Runtime acceptance and editor validation are separate cross-repository paths | +| Docs page move or removal | Update nav and add permanent redirect | Preserves external links and bookmarks | + +## Kilo-owned boundaries + +Kilo CLI forks upstream OpenCode. Prefer Kilo-owned directories and packages for additive behavior: + +| Prefer | Avoid unless necessary | +|---|---| +| `packages/opencode/src/kilocode/` | Broad edits to shared `packages/opencode/src/` files | +| `packages/opencode/test/kilocode/` | Shared tests that encode only Kilo behavior | +| `packages/kilo-vscode/`, `packages/kilo-jetbrains/`, `packages/kilo-docs/`, `packages/kilo-indexing/` | Moving Kilo-only behavior into upstream-owned modules | +| Narrow import or route seams in shared files | Refactors that enlarge upstream merge conflicts | + +## Shared OpenCode files + +Use `kilocode_change` markers when Kilo-specific code must modify shared upstream files. + +| Change shape | Marker | +|---|---| +| One line | Trailing `// kilocode_change` | +| Multi-line block | `// kilocode_change start` and `// kilocode_change end` | +| New file in shared path | Top-level `// kilocode_change - new file` | +| JSX or TSX | JSX comment equivalents | + +Marker exemptions apply to paths already owned by Kilo, including paths whose names contain `kilocode` and Kilo packages such as `packages/kilo-vscode/` or `packages/kilo-ui/`. Do not add markers there. + +| Guard | When to run | +|---|---| +| `bun run script/check-opencode-annotations.ts` | PR touches `packages/opencode/`; verifies shared OpenCode Kilo edits are annotated | +| `bun run script/check-opencode-promise-facades.ts` | Service adapter changes; prevents new runtime-backed Promise facades in shared Effect services | +| `bun run check-kilocode-change` from `packages/kilo-vscode/` | VS Code or Kilo UI changes; markers must not appear in fully Kilo-owned packages | +| `bun run script/check-workflows.ts` | Workflow add or remove changes; keeps workflow allowlist explicit | + +## CLI server API + +CLI server uses Effect `HttpApi` and publishes OpenAPI-compatible HTTP + SSE surfaces consumed by JavaScript SDK and JetBrains build-local Kotlin client. + +| Rule | Reason | +|---|---| +| Define shared routes under `packages/opencode/src/server/routes/instance/httpapi/` | Keeps route contract close to runtime handlers | +| Normalize public spec in `packages/opencode/src/server/routes/instance/httpapi/public.ts` | Preserves legacy-compatible request and response shapes during Effect migration | +| Put additive Kilo groups and handlers under `packages/opencode/src/kilocode/server/httpapi/` | Reduces edits in shared upstream-owned files | +| Inject Kilo APIs through narrow shared seam | Keeps upstream diff small and marker placement obvious | +| Preserve route spans and stable attributes | Keeps diagnostics and telemetry understandable | + +## SDK generation + +[CLI Runtime SDK contract](/docs/contributing/architecture/cli-runtime#sdk-contract) owns generation pipeline detail. Contributor rules are short: + +| Change | Action | +|---|---| +| Add or change CLI server endpoint | Run root `./script/generate.ts` after route and handler edits | +| JavaScript SDK generated files under `packages/sdk/js/src/v2/gen/` | Do not edit by hand | +| JavaScript SDK wrapper behavior | Edit handwritten `packages/sdk/js/src/v2/client.ts` | +| JetBrains generated Kotlin client | Let Gradle regenerate build-local client from normalized OpenAPI | + +## CLI config schema + +Runtime config loading and editor validation are separate paths. New Kilo-only config key requires CLI Effect Schema change in `Kilo-Org/kilocode` and JSON Schema overlay change in `Kilo-Org/cloud`. Follow [CLI Config Schema](/docs/contributing/architecture/config-schema) for exact workflow. + +## Module export pattern + +For new public APIs, prefer flat ESM exports inside module, then namespace re-exports from index files when grouped access helps callers. + +```typescript +// packages/opencode/src/session/session.ts +export const create = fn(CreateSchema, async (input) => { + // ... +}) + +export const list = fn(ListSchema, async (input) => { + // ... +}) + +// packages/opencode/src/session/index.ts +export * as Session from "./session" +``` + +Import specific export when practical. Use namespace shape (`Session.create`) when preserving existing API or grouped module access improves clarity. Existing Kilo-owned namespaces remain valid; do not refactor them solely for style. + +## Tool implementation + +Tools use `Tool.define("id", Effect.gen(...))` with Effect Schema validation and typed execution. + +```typescript +export const ExampleTool = Tool.define( + "example", + Effect.gen(function* () { + return { + description: "Example tool", + parameters: Schema.Struct({ + value: Schema.String, + }), + execute(args) { + return Effect.succeed({ + title: args.value, + metadata: {}, + output: args.value, + }) + }, + } + }), +) +``` + +Reuse tool helpers, permission gates, and telemetry conventions before adding abstractions. Tests should exercise implementation behavior rather than duplicating logic in mocks. + +## Build system + +| Area | Tooling | +|---|---| +| Package manager | Bun workspaces | +| Task orchestration | Turborepo | +| CLI executable | Bun compile build in `packages/opencode/script/build.ts` | +| VS Code extension and webviews | esbuild | +| JetBrains plugin | Gradle, Kotlin JVM toolchain 21, build-local OpenAPI generation | +| Type checking | `tsgo` through `bun turbo typecheck`; Gradle compile checks for JetBrains | +| Tests | Package-level Bun test, Vitest, or Gradle test depending on package | +| Docs | Next.js, Markdoc, Mermaid, and custom Markdoc components | + +## Documentation changes + +When adding or moving docs pages: + +- Create page under `pages/`. +- Update matching navigation file in `lib/nav/`. +- Add redirects when removing or moving routes. +- Use compact markdown tables with unpadded cells. +- Use `/docs` prefix for docs image paths. + +## Source map + +Paths below are relative to [`Kilo-Org/kilocode`](https://github.com/Kilo-Org/kilocode). + +| Concern | Source path | +|---|---| +| Tool definition API | `packages/opencode/src/tool/tool.ts` | +| Tool example | `packages/opencode/src/tool/read.ts` | +| Server APIs | `packages/opencode/src/server/routes/instance/httpapi/` | +| Public OpenAPI normalization | `packages/opencode/src/server/routes/instance/httpapi/public.ts` | +| Kilo route seam | `packages/opencode/src/kilocode/server/httpapi/` | +| JavaScript SDK generation | `packages/sdk/js/script/build.ts`{% linebreak /%}`script/generate.ts` | +| JetBrains client generation | `packages/kilo-jetbrains/backend/build.gradle.kts` | +| Upstream merge automation | `script/upstream/` | + +## Upstream merge workflow + +`bun install` runs `script/setup-git.ts`, which sets repo-local merge conflict style to `zdiff3`. Base-aware markers make manual resolution and syntax-aware tooling more useful. Upstream automation under `script/upstream/` applies transforms before merge, forces `zdiff3` for merge operation, and runs `mergiraf` against remaining textual conflicts. `mergiraf` is required by merge script. + +From `script/upstream/`, use: + +```bash +bun run analyze.ts --version +bun run merge.ts --version --dry-run +bun run merge.ts --version +``` + +Keep Kilo-specific logic extracted, shared seams narrow, markers accurate, and CI guards green before upstream merge work lands. + +## Related pages + +- [Architecture Overview](/docs/contributing/architecture) - system layers and reading paths +- [CLI Runtime](/docs/contributing/architecture/cli-runtime) - local runtime ownership and SDK contract +- [CLI Config Schema](/docs/contributing/architecture/config-schema) - cross-repository config-key workflow diff --git a/packages/kilo-docs/pages/contributing/architecture/enterprise-mcp-controls.md b/packages/kilo-docs/pages/contributing/architecture/enterprise-mcp-controls.md deleted file mode 100644 index 682bb26c326..00000000000 --- a/packages/kilo-docs/pages/contributing/architecture/enterprise-mcp-controls.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: "Enterprise MCP Controls" -description: "Enterprise MCP controls architecture" ---- - -# Enterprise MCP Controls - -### Overview - -Enterprise customers need to maintain control over the tools their developers use to ensure security, compliance, and cost management. Developers using Kilo Code can configure and use any MCP (Model Context Protocol) server, including public marketplace offerings or arbitrary custom servers. This lack of administrative oversight introduces risk for our enterprise customers, as it allows for the potential use of unvetted, insecure, or costly tool calls. - -This document specifies a new feature, **Enterprise MCP Controls**, which allows organization administrators to define an **allowlist** of approved MCP servers. Kilo Code (CLI/Extension) can enforce this allowlist, ensuring that developers within the organization can only use sanctioned MCPs. - -### MVP Requirements - -#### 1. Dashboard App - -- **View and Manage Allowlist:** Organization administrators must have a dedicated section in the dashboard to manage their MCP allowlist. -- **Default Configuration:** By default, new and existing organizations will have **all** marketplace MCPs enabled to ensure no disruption of service. -- **Marketplace MCPs:** The dashboard must display a comprehensive list of all MCPs available in the official Kilo Code Marketplace. -- **Selection UI:** Administrators must be able to easily select and deselect MCPs to add or remove them from the organization's allowlist. -- **Audit Logs:** Any changes made to MCP allow list must show up in the Audit Logs - -#### 2. Extension - -- **Allowlist Enforcement:** The VS Code extension and future CLI must strictly enforce the organization's MCP allowlist. -- **Filtered Marketplace:** The in-extension "MCP Marketplace" view must **only** display MCPs that are on the organization's allowlist. -- **Ignore Disallowed MCPs:** If an MCP server configured in `mcp.json` is **not** on the allowlist, the extension must ignore it. It should not be activated, displayed as an option, or used for any operations. -- **User Feedback:** The extension should provide clear, non-blocking visual feedback to the developer indicating which locally configured MCPs are disallowed by their organization's policy (e.g., graying out the entry, showing a warning icon). - -## System Design - -When the Enterprise MCP Controls feature is enabled, extension users can no longer use locally configured MCP definitions. Instead of pulling MCP configurations from the end-user's filesystem, the configuration will be pulled from the Kilo Code API, scoped to the organization. - -#### How Kilo/MCP works today - -!![How MCP works today](/docs/img/enterprise-mcp-controls-today.png) - -#### How Kilo/MCP works with enterprise controls - -!![How MCP works with enterprise controls](/docs/img/enterprise-mcp-controls-with-ent-control.png) - -### Schema - -We will piggy-back off of the existing organization.settings jsonb field for administrator to configure MCP Controls: - -```ts -const OrganizationSettings_MCPControls = z.object({ - mcp_controls_enabled: z.boolean().optional(), - mcp_controls_allowed_marketplace_servers: z.string().optional(), -}) -``` - -For end-users, since the mcp.json payload is no longer configurable locally, they will need to configure it via the Kilo Code dashboard. Since these configurations often contain API keys, we will encrypt the entire payload prior to insertion: - -```sql -create table if not exists organization_member_mcp_configs ( - id uuid not null default uuid_generate_v4(), - organization_id uuid not null references organizations(id), - kilo_user_id text not null references kilocode_users(id), - config bytea not null, - created_at timestamptz not null default now() -) -``` - -The config payload definition should look something like: - -```ts -const OrganizationMemberMCPConfig = z - .object({ mcp_id: z.string(), parameters: z.record(z.string(), z.string()) }) - .array() -``` - -### Dashboard App - -#### Owner experience - -There will be a new page in the left-hand navigation for Enterprise users only called "MCP Control" `/organizations/:id/mcp-control`. For owners, this page will allow control of which MCP marketplace items are allowed. It will `GET /api/marketplace/mcps` to retrieve the canonical list of MCP servers in our marketplace. It will also call the relevant getOrganization trpc function to get the org settings. By default, this feature is turned off. Also by default, all MCP servers will be selected. - -#### Organization user experience - -!![Organization user experience](/docs/img/enterprise-mcp-controls-org-user-install.png) - -When org users want to configure and use an MCP server and if organizations.settings.mcp_controls_enabled is true, they will be directed to the Kilo Code dashboard application `/organizations/:id/mcp-control`. Users will be able to enable, disable, and configure approved MCP servers. - -There will be a configuration UI similar to what's in the extension today. All configurations are encrypted and saved in our database. - -### Extension - -When organizations.settings.mcp_controls_enabled is true, the MCP marketplace view should be replaced with a link to configure MCP on the Kilo Code dashboard. When it is false-y, the experience is the same as it is today. - -## Scope and implementation plan - -Rough plan. These action items will become tickets after spec is approved: - -- Backend - - Schema changes for new organization_member_mcp_configs table - - Implement org settings endpoint changes to allow for mcp-control features (enabled, allow list) - - Implement TRPC routes for org members to update approved mcp installation settings - - Implement mcp-control UI for administrators - - Implement mcp server installation UI for end users -- Extension - - When organizations.settings.mcp_controls_enabled is true, the MCP marketplace view should be replaced with a link to configure MCP on the Kilo Code dashboard - -## Features for the future - -- Org-provided custom MCP server configurations (i.e. non-marketplace MCPs) -- Project-level MCP configurations -- Tool call audits - who is running what tool and why? - - Split out by user, project, MCP server (if applicable) - - Why? If you're really concerned about locking down MCP servers then the only way to know if our product is truly doing what it's saying it is is to provide admins with tool call audit logs diff --git a/packages/kilo-docs/pages/contributing/architecture/feature-template.md b/packages/kilo-docs/pages/contributing/architecture/feature-template.md deleted file mode 100644 index 3552a4cbce6..00000000000 --- a/packages/kilo-docs/pages/contributing/architecture/feature-template.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: "Spec Template" -description: "Template for proposing new feature designs" ---- - -# Template - -# Overview - -This section provides a concise description of the problem being addressed and the proposed solution. - -What is important for the solution to accomplish? What can be left out of scope for now? Scope projects as tightly as possible, because smaller projects let us ship faster, get feedback faster, and avoid snowballing scope creep. - -# Requirements - -This section outlines the requirements that the solution will fulfill. Be comprehensive and detailed. - -Find the minimum requirements that will deliver the minimal solution described in the Overview. Avoid the urge to solve all the problems at once. - -- - -### Non-requirements - -- - -# System Design - -This is the core of the technical specification, detailing the architectural decisions and implementation plan. If possible, include diagrams! - -## Scope/Implementation - -This section should be a bulleted list of tasks that will eventually become github issues. - -- - -# Compliance Considerations - -This section addresses any relevant compliance aspects, specifically regarding SOC 2. - -# Features for the future - -Talks about what we might want to build or improve upon in the future, but is out-of-scope of this spec. diff --git a/packages/kilo-docs/pages/contributing/architecture/features.md b/packages/kilo-docs/pages/contributing/architecture/features.md deleted file mode 100644 index 2b187d17d45..00000000000 --- a/packages/kilo-docs/pages/contributing/architecture/features.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: "Architecture Features" -description: "Overview of current and planned features in Kilo Code" ---- - -# Architecture Features - -These pages document the architecture and design of current or planned features, as well as any unique development patterns. - -| Feature | Description | -|---|---| -| [Agent Observability](/docs/contributing/architecture/agent-observability) | Observability and monitoring for agentic systems | -| [Auto Model Tiers](/docs/contributing/architecture/auto-model-tiers) | Multi-tier auto model routing (Frontier, Free, Open) | -| [Benchmarking](/docs/contributing/architecture/benchmarking) | Benchmarking Kilo Code across models and agents | -| [Enterprise MCP Controls](/docs/contributing/architecture/enterprise-mcp-controls) | Admin controls for MCP server allowlists | -| [MCP OAuth Authorization](/docs/contributing/architecture/mcp-oauth-authorization) | OAuth 2.1-based authorization for MCP servers | -| [Onboarding Improvements](/docs/contributing/architecture/onboarding-improvements) | User onboarding and engagement features | -| [Organization Modes Library](/docs/contributing/architecture/organization-modes-library) | Shared modes for teams and enterprise | -| [Agentic Security Reviews](/docs/deploy-secure/security-reviews) | AI-powered security vulnerability analysis | -| [Track Repo URL](/docs/contributing/architecture/track-repo-url) | Usage tracking by repository/project | -| [Voice Transcription](/docs/contributing/architecture/voice-transcription) | Live voice input for chat | - -To propose a new feature design, consider using the [Spec Template](/docs/contributing/architecture/feature-template). diff --git a/packages/kilo-docs/pages/contributing/architecture/index.md b/packages/kilo-docs/pages/contributing/architecture/index.md index 42bb014b319..dee4cb93f9a 100644 --- a/packages/kilo-docs/pages/contributing/architecture/index.md +++ b/packages/kilo-docs/pages/contributing/architecture/index.md @@ -1,279 +1,222 @@ --- title: "Architecture Overview" -description: "Overview of the Kilo platform architecture" +description: "Overview of the Kilo Code platform architecture" --- # Architecture Overview -This document provides a high-level overview of the Kilo platform architecture to help contributors understand how the different components fit together. +This page maps Kilo Code's repository-defined architecture. It introduces the local runtime, editor clients, cloud service boundaries, and hosted execution products before the subsystem pages add implementation detail. -## System Architecture +{% callout type="info" title="Scope" %} +Use these pages for stable system boundaries and contributor-wide contracts. Source code remains the reference for feature-level implementation details. Static source shows code paths and deployable surfaces, not production enablement, traffic, retention, or vendor configuration. +{% /callout %} -Kilo is an AI coding platform built around a central CLI engine that powers every client surface — the terminal, VS Code, and the cloud. The architecture follows a layered approach where all clients communicate with the CLI over HTTP + SSE, and the CLI connects to AI providers either directly or through Kilo Cloud. +## How to read these pages -```mermaid -graph LR - tui["Kilo CLI (TUI)"] - vscode["VS Code Extension"] - - subgraph cli ["Kilo CLI Engine"] - provider["Provider Router"] - end - - subgraph cloud ["Kilo Cloud"] - gateway["Kilo Gateway"] - cloudagent["Cloud Agent"] - bot["Kilo Bot"] - claw["KiloClaw"] - gastown["Gas Town"] - review["Code Review"] - triage["Auto Triage"] - appbuilder["App Builder"] - end - - providers["Inference Providers: Anthropic, OpenAI, Google, OpenRouter + 500 more"] - - tui -->|SDK| cli - vscode -->|SDK| cli - cloudagent -->|Sandbox| cli - - provider -- Direct --> providers - provider -- Gateway --> gateway - gateway --> providers - claw --> gateway - gastown -->|Container| cli - gastown --> gateway - - bot --> cloudagent - review --> cloudagent - triage --> cloudagent - appbuilder --> cloudagent -``` - -## Kilo CLI — The Foundation - -The CLI (`packages/opencode/`) is the core engine that all products are built on. It contains the AI agent runtime, tool execution, session management, provider integrations, and an HTTP server. Each client spawns or connects to a `kilo serve` process and communicates via HTTP + SSE using the `@kilocode/sdk`. - -The CLI can run in several modes: - -- **`kilo`** — Interactive TUI for terminal-based coding -- **`kilo run`** — Headless single-prompt execution -- **`kilo serve`** — HTTP server mode for client integrations - -Key subsystems inside the CLI: - -| Subsystem | Purpose | -|---|---| -| Agent Runtime | Orchestrates AI conversations, tool calls, and multi-step task execution | -| Tools Service | Built-in tools for file editing, shell execution, search, and more | -| MCP Servers | Model Context Protocol support for extending with external tools | -| LSP Client | Language Server Protocol integration for code intelligence | -| Session Manager | Persistent session state, conversation history, and checkpoints | -| Provider Router | Connects to 500+ AI models via direct APIs or Kilo Gateway | -| HTTP Server | REST API + SSE streaming for client communication | -| Config System | Project and global configuration, modes, and permissions | - -## Client Layer - -All clients are thin wrappers over the CLI engine. - -### VS Code Extension - -The VS Code extension (`packages/kilo-vscode/`) bundles the CLI binary and spawns `kilo serve` as a child process. It includes: - -- **Sidebar Chat** — Primary coding assistant interface -- **Agent Manager** — Multi-session orchestration panel with git worktree isolation for running parallel tasks - -### TUI - -The built-in terminal UI ships with the CLI itself — a SolidJS interface rendered in the terminal via OpenTUI. - -## Kilo Cloud - -Kilo Cloud is the hosted platform layer that provides authentication, provider routing, and autonomous agent services. The cloud infrastructure lives in a separate repository. - -### Kilo Gateway - -The gateway (`packages/kilo-gateway/` in this repo, plus API routes in the cloud) handles: - -- **Authentication** — Device flow auth, token management, and account linking -- **Provider Routing** — Routes AI requests through Kilo's managed API keys or the user's own keys -- **Model Catalog** — Serves the available model list and provider configuration -- **Usage & Billing** — Tracks token consumption and manages credits - -### Cloud Agent - -A Cloudflare Worker within Kilo Cloud that runs the Kilo CLI in isolated sandbox environments. It powers cloud-based AI coding tasks triggered via the web dashboard, webhooks, or automation workflows. It provides a secure API for: - -- Creating and managing coding sessions with full GitHub/GitLab integration -- Running AI tasks in Docker containers with the CLI pre-installed -- Streaming results back via WebSocket - -### Kilo Bot - -The GitHub/GitLab bot that responds to issue comments and PR mentions. It dispatches work to the Cloud Agent, enabling users to trigger AI coding tasks directly from their repositories. +Choose the path closest to the change you are making: -### KiloClaw - -A multi-tenant compute platform running on Fly.io, orchestrated by a Cloudflare Worker. Each user gets a dedicated persistent machine running an OpenClaw gateway, coordinated via Durable Objects for state management and self-healing reconciliation. - -{% image src="/docs/img/kiloclaw/kiloclaw-architecture.png" alt="KiloClaw infrastructure architecture diagram" width="800" caption="KiloClaw infrastructure architecture" /%} - -### Code Review - -An automated code review service that subscribes to GitHub webhooks, dispatches reviews through the Cloud Agent, and posts feedback directly on pull requests. Supports per-organization concurrency limits and automatic queuing. - -### Auto Triage - -An automated issue triage service that classifies GitHub issues (bug, feature, question), detects duplicates via vector similarity search, and optionally creates fix PRs for high-confidence actionable issues. - -### App Builder - -A service that builds and deploys user applications via the Cloud Agent. Users can generate full applications from prompts, with the App Builder orchestrating the Cloud Agent to scaffold, iterate, and deploy the result. - -### Gas Town - -A multi-agent orchestration platform that coordinates autonomous AI coding agents working on real Git repositories. Gas Town runs entirely on Cloudflare — a central Durable Object manages all state, while Docker containers on Cloudflare Containers run agent processes via the Kilo CLI. - -Key concepts: - -- **Town** — A workspace/project that contains one or more rigs (repositories) -- **Rig** — A Git repository attached to a town where agents perform work -- **Bead** — A unit of work (issue, task, merge request, or message) -- **Convoy** — A batch of related beads with dependency tracking, dispatched together - -Agents operate in a hierarchy: - -| Agent | Role | +| Contributor path | Suggested order | |---|---| -| Mayor | Persistent conversational coordinator — decomposes tasks and delegates to worker agents | -| Polecat | Worker agent — clones repo worktrees, writes code, commits, pushes, and creates PRs | -| Refinery | Code review agent — reviews polecat branches, runs quality gates, merges or requests rework | -| Triage | Ephemeral agent that resolves ambiguous situations detected by automated patrol checks | +| Local CLI or editor client | Architecture Overview -> [CLI Runtime](/docs/contributing/architecture/cli-runtime) -> [VS Code Extension](/docs/contributing/architecture/vscode-extension) or [JetBrains Plugin](/docs/contributing/architecture/jetbrains-plugin) | +| Hosted platform or automation | Architecture Overview -> [Cloud Platform](/docs/contributing/architecture/cloud-platform) -> [Automation Services](/docs/contributing/architecture/automation-services) | +| Security review | Architecture Overview -> [Cloud Platform](/docs/contributing/architecture/cloud-platform) -> [Cloud Security](/docs/contributing/architecture/cloud-security) | +| Architecture-facing implementation | Relevant architecture page -> [Development Patterns](/docs/contributing/architecture/development-patterns) | +| CLI config ownership or key change | [CLI Runtime](/docs/contributing/architecture/cli-runtime#config-precedence) -> [CLI Config Schema](/docs/contributing/architecture/config-schema) -> [Development Patterns](/docs/contributing/architecture/development-patterns) | -A reconciler loop running every 5 seconds drives all state transitions: dispatching agents, transitioning beads, polling PR status, managing convoys, and recovering from failures. +## Repository boundaries -### Supporting Services +Architecture pages cross two repositories: -| Service | Purpose | +| Repository | Contents | |---|---| -| Webhook Agent Ingest | Named webhook endpoints that capture HTTP requests and queue delivery to Cloud Agent | -| AI Attribution | Tracks line-level AI-generated code attribution when users accept or reject edits | -| Session Ingest | Ingests and stores CLI session data for analytics | -| Observability | Telemetry pipelines for monitoring cloud services | - -## Key Concepts - -### Modes - -Modes are configurable presets that customize the agent's behavior: +| [Kilo‑Org/kilocode](https://github.com/Kilo-Org/kilocode) | Kilo CLI runtime, local daemon, Kilo Console, VS Code extension, JetBrains plugin, JavaScript SDK, codebase indexing, Kilo Gateway client, telemetry, docs, and shared UI packages | +| [Kilo‑Org/cloud](https://github.com/Kilo-Org/cloud) | Web control plane, Kilo Gateway routes, Cloud Agent session runtime, automation, generated-application preview and deployment services, KiloClaw, Gas Town, billing, and supporting Workers | -- Define which tools are available -- Set custom system prompts -- Configure file restrictions -- Examples: Code, Architect, Debug, Ask +## Three architecture layers -### Model Context Protocol (MCP) +| Layer | Responsibility | Typical boundaries | +|---|---|---| +| Local runtime and clients | Runs local coding sessions and connects editor surfaces to one local agent engine | Kilo CLI runtime, `kilo serve` server, local daemon, Kilo Console, VS Code extension, JetBrains plugin | +| Kilo Cloud shared services | Handles hosted identity, authorization, model routing, billing, orchestration, and shared product services | Web control plane, Kilo Gateway, Workers, queues, Durable Objects, persistence | +| Hosted product runtimes and automation | Runs scoped cloud work for coding, app generation, assistants, security analysis, and multi-agent orchestration | Cloud Agent, Automation Services, App Builder, Security Agent, KiloClaw, Gas Town, Wasteland | -MCP enables extending the agent with external tools: +Local execution and hosted execution are separate boundaries. Editor clients use a local `kilo serve` server. Hosted automation can launch Cloud Agent execution sessions when cloud coding work is required. -- Servers provide additional capabilities -- Standardized protocol for tool communication -- Configured via `mcp.json` +## Terms used throughout -### Checkpoints +| Term | Meaning | +|---|---| +| Kilo Code | Umbrella product across local clients, Kilo CLI runtime, and Kilo Cloud services | +| Kilo CLI runtime | Local agent engine in `packages/opencode/`; owns tools, sessions, config, persistence, and provider routing | +| `kilo serve` server | Local HTTP and SSE process used by editor clients and Kilo Console; selected browser-oriented paths also use WebSocket | +| Local daemon | Detached reusable `kilo serve` server managed by `kilo daemon` commands | +| Directory context | Normalized local filesystem directory used to select local runtime state | +| Local runtime instance | Directory-keyed runtime context inside one Kilo CLI process | +| Local routing workspace | Optional routing context that can resolve to a local directory or remote target | +| Worktree directory | Alternate git worktree path used as a directory context for isolated concurrent work | +| Web control plane | Hosted Kilo Cloud application layer for identity, organization authorization, billing, product configuration, and API orchestration | +| Kilo Gateway | First-party hosted model-routing boundary | +| Cloud Agent | Hosted coding-session capability. A Cloud Agent execution session is one hosted run; current session runtime implementation lives in `services/cloud-agent-next/`. | + +## Core execution spine + +The three layers appear in two primary execution shapes: local client requests and hosted cloud work. -Git-based state management for safe exploration: +```mermaid +flowchart LR + subgraph clients ["Local clients"] + tui["Kilo CLI TUI"] + run["kilo run"] + console["Kilo Console"] + editors["VS Code and JetBrains"] + end -- Creates commits to track changes -- Enables rolling back to previous states -- Shadow repository for isolation + subgraph local ["Local Kilo CLI boundary"] + daemon["Local daemon manager"] + server["kilo serve server"] + runtime["Kilo CLI runtime"] + router["Provider router"] + end -### Worktrees + subgraph cloud ["Kilo Cloud shared services"] + web["Web control plane"] + workers["Automation Workers, queues, and Durable Objects"] + gateway["Kilo Gateway"] + agent["Cloud Agent"] + end -Git worktree isolation for parallel task execution: + trigger["Hosted product or automation trigger"] + repos["Repositories"] + models["Model providers and external gateways"] + + tui -->|"daemon attach when available"| server + tui -->|"worker-backed fallback"| runtime + run -->|"attach when available"| server + run -->|"embedded fallback"| runtime + console -->|"starts or reuses"| daemon + daemon -->|"owns detached child"| server + editors -->|"start editor-owned child over HTTP + SSE"| server + server --> runtime --> router + router -->|"direct provider"| models + router --> gateway --> models + + trigger --> web + trigger --> workers + web --> workers --> agent + web --> agent + agent --> repos + agent --> models +``` -- Each agent session can operate in its own worktree -- Prevents conflicts between concurrent tasks -- Used by the Agent Manager in VS Code for multi-session workflows +### Two execution paths -## Development Patterns +| Path | Starts from | Runs in | What to remember | +|---|---|---|---| +| Local coding | Kilo CLI, Kilo Console, VS Code, or JetBrains | Kilo CLI runtime on developer machine | Editor clients talk to local `kilo serve` server. Local runtime owns coding session and sends model requests directly or through Kilo Gateway. | +| Hosted work | Webhook, source-control event, command, schedule, or hosted product | Kilo Cloud services; Cloud Agent when coding is required | Cloud services coordinate work. Only flows that need repository changes launch Cloud Agent execution session. | -### Client-Server Communication +This distinction is central: using editor does not move coding session into Cloud Agent. Cloud services also route model requests, deliver chat events, dispatch notifications, serve generated applications, and coordinate adjacent hosted boundaries without launching Cloud Agent. -All clients communicate with the CLI via its HTTP + SSE API. The `@kilocode/sdk` package provides a TypeScript client: +## Adjacent hosted boundaries -```typescript -import { KiloClient } from "@kilocode/sdk" +The core execution spine is not the full cloud product catalog. These service families and hosted runtimes attach to it for specific product flows: -const client = new KiloClient({ baseUrl: "http://localhost:3000" }) -const session = await client.session.create({ ... }) +```mermaid +flowchart LR + web["Web control plane"] + workers["Automation Services"] + agent["Cloud Agent"] + builder["App Builder"] + preview["Generated-application preview"] + deploy["Generated-application deployment"] + security["Security Agent"] + chat["Kilo Chat, events, and notifications"] + claw["KiloClaw"] + town["Gas Town"] + wasteland["Wasteland"] + + web --> workers --> agent + web --> builder --> agent + builder --> preview + builder --> deploy + web --> security + security -->|"optional deep analysis"| agent + web --> claw + chat --> claw + web --> town --> wasteland ``` -### Module Export Pattern +| Boundary | Role | Topology or workflow | Security review | +|---|---|---|---| +| Automation Services | Turns commands, source-control events, labels, webhooks, and schedules into scoped work | [Automation Services](/docs/contributing/architecture/automation-services) | [Trust boundaries](/docs/contributing/architecture/cloud-security#trust-boundaries) | +| App Builder | Coordinates generated-application coding, preview, build, and deployment boundaries | [Cloud Platform](/docs/contributing/architecture/cloud-platform#app-generation-boundaries) | [Preview and deployment](/docs/contributing/architecture/cloud-security#generated-application-preview-and-deployment) | +| Security Agent | Syncs findings and analyzes risk; selected deep analysis can launch Cloud Agent | [Cloud Platform](/docs/contributing/architecture/cloud-platform#security-agent) | [Sync and cleanup](/docs/contributing/architecture/cloud-security#security-agent-sync-and-cleanup) | +| KiloClaw | Coordinates owner-scoped hosted assistant runtimes | [Cloud Platform](/docs/contributing/architecture/cloud-platform#kiloclaw) | [KiloClaw ingress](/docs/contributing/architecture/cloud-security#kiloclaw-ingress) | +| Gas Town and Wasteland | Coordinate multi-agent repository work and collaborative commons paths | [Cloud Platform](/docs/contributing/architecture/cloud-platform#gas-town-and-wasteland) | [Trust boundaries](/docs/contributing/architecture/cloud-security#trust-boundaries) | -The CLI uses flat ESM exports inside each module, then re-exports the module as a namespace from an index file when callers need grouped access. Avoid adding new `export namespace` declarations; top-level exports are easier to tree-shake and work better with Node's type-stripping runtime. +## Local entry points and clients -```typescript -// packages/opencode/src/session/session.ts -export const create = fn(CreateSchema, async (input) => { - // ... -}) +These local surfaces live in [`Kilo-Org/kilocode`](https://github.com/Kilo-Org/kilocode). Package paths below are relative to that repository root. -export const list = fn(ListSchema, async (input) => { - // ... -}) +| Surface | Package in `Kilo-Org/kilocode` | Runtime model | +|---|---|---| +| Kilo CLI TUI | `packages/opencode/` | Interactive local client with daemon attach and worker-backed fallback paths | +| `kilo run` | `packages/opencode/` | Headless prompt execution through explicit attach, daemon attach, or embedded fallback | +| `kilo serve` | `packages/opencode/` | Local HTTP + SSE server for local clients | +| Kilo Console | `packages/kilo-console/`{% linebreak /%}`packages/opencode/` | Browser UI served at `/console` by a started or reused local daemon | +| VS Code extension | `packages/kilo-vscode/` | Extension host starts one shared editor-owned `kilo serve` server and routes webviews through HTTP + global SSE; SDK directory selects local runtime instance | +| JetBrains plugin | `packages/kilo-jetbrains/` | Split-mode Swing plugin; backend module starts one editor-owned `kilo serve` server and caches workspace clients by directory | -// packages/opencode/src/session/index.ts -export * as Session from "./session" -``` +## Cloud service families -Prefer importing the specific export when possible. Use the namespace re-export (`Session.create`, `Session.list`) when a caller benefits from grouped module access or when preserving the existing public shape. +Hosted service families live in [`Kilo-Org/cloud`](https://github.com/Kilo-Org/cloud). Paths below are relative to that repository root unless another repository is named. -### CLI Server API +| Boundary | Primary source paths | Role | +|---|---|---| +| Kilo Cloud | `apps/web/`{% linebreak /%}`services/` | Hosted platform repository for identity, billing, routing, product configuration, automation, and scoped execution services | +| Web control plane | `apps/web/` | Hosted application layer for authorization, configuration, and API orchestration | +| Kilo Gateway | `apps/web/src/app/api/gateway/`{% linebreak /%}`apps/web/src/lib/ai-gateway/`{% linebreak /%}Local integration: `Kilo-Org/kilocode/packages/kilo-gateway/` | First-party model-routing boundary and local client integration | +| Cloud Agent | `services/cloud-agent-next/` | Hosted coding-session capability with policy-selected sandbox allocation | +| Automation Services | `services/code-review-infra/`{% linebreak /%}`services/auto-triage-infra/`{% linebreak /%}`services/auto-fix-infra/`{% linebreak /%}`services/security-auto-analysis/`{% linebreak /%}`services/security-sync/`{% linebreak /%}`services/webhook-agent-ingest/` | Trigger-driven review, triage, fix, security, and configured webhook flows | +| Adjacent hosted boundaries | `services/app-builder/`{% linebreak /%}`services/kiloclaw/`{% linebreak /%}`services/gastown/`{% linebreak /%}`services/wasteland/`{% linebreak /%}Supporting services | App Builder, KiloClaw, Gas Town, Wasteland, chat, notifications, and supporting services | -The CLI server uses Effect `HttpApi` and publishes an OpenAPI-compatible HTTP + SSE API consumed by `@kilocode/sdk`. +## Supporting packages -- Keep the generated SDK output stable when updating Effect `HttpApi` routes. -- Regenerate `packages/sdk/js/` after server endpoint changes. -- Keep request handling observable with route spans and stable attributes where possible. +These supporting packages also live in [`Kilo-Org/kilocode`](https://github.com/Kilo-Org/kilocode). Package paths below are relative to that repository root. -### Tool Implementation - -Tools follow a consistent pattern with Zod schema validation: - -```typescript -export const ReadTool = Tool.define({ - name: "read", - description: "Read a file", - parameters: z.object({ - path: z.string(), - }), - async execute(params) { - // ... - }, -}) -``` +| Package in `Kilo-Org/kilocode` | Role | +|---|---| +| `packages/kilo-indexing/` | Per-directory asynchronous codebase indexing engine behind Kilo CLI bridge | +| `packages/sdk/js/` | Generated JavaScript client and handwritten wrapper for local server APIs | +| `packages/kilo-gateway/` | Local Kilo Gateway client integration used by Kilo CLI runtime | +| `packages/kilo-console/` | Browser UI served by local daemon at `/console` | -## Build System +## Architecture pages -The project uses: +| Page | What it covers | +|---|---| +| [CLI Runtime](/docs/contributing/architecture/cli-runtime) | Local execution modes, daemon, server authentication, routing, persistence, snapshots, SDK, config, SSE, Kilo Console, and indexing | +| [VS Code Extension](/docs/contributing/architecture/vscode-extension) | Shared local `kilo serve` ownership, webview bridge, Agent Manager, PTYs, recovery, bundled resources, and build outputs | +| [JetBrains Plugin](/docs/contributing/architecture/jetbrains-plugin) | Split-mode modules, RPC, bundled local `kilo serve` lifecycle, Kotlin SDK, recovery, and remote-development constraints | +| [Cloud Platform](/docs/contributing/architecture/cloud-platform) | Hosted service inventory, Cloud Agent topology, shared cloud boundaries, and adjacent hosted runtimes | +| [Automation Services](/docs/contributing/architecture/automation-services) | Trigger-driven Workers, queues, callbacks, ownership, and scoped execution paths | +| [Cloud Security](/docs/contributing/architecture/cloud-security) | Cloud trust boundaries, data flows, persistence, isolation, controls, and third-party categories | -- **Bun** — Package management (monorepo workspaces) and runtime -- **Turborepo** — Monorepo task orchestration -- **esbuild** — Bundling for the CLI and VS Code extension -- **TypeScript** — Type checking via `tsgo` across all packages -- **Vitest / Bun test** — Test runner +## Development pages -## Repositories +After system-boundary pages, continue with Development Patterns for implementation rules. Use CLI Config Schema when changing config keys or editor-facing schema publication. -| Repository | Contents | +| Page | What it covers | |---|---| -| [Kilo-Org/kilocode](https://github.com/Kilo-Org/kilocode) | CLI engine, VS Code extension, SDK, gateway client, telemetry, docs, UI components | -| Cloud (private) | Web dashboard, Cloud Agent, Kilo Bot, KiloClaw, Gas Town, code review, auto triage, billing, and supporting Cloudflare Workers | - -## Further Reading - -- [Development Environment](/docs/contributing/development-environment) — Setup guide -- [Architecture Features](/docs/contributing/architecture/features) — Detailed feature specs -- [Ecosystem](/docs/contributing/ecosystem) — Related projects and integrations +| [Development Patterns](/docs/contributing/architecture/development-patterns) | Code-ownership decisions, shared-file seams, SDK generation, validation guards, and fork maintenance | +| [CLI Config Schema](/docs/contributing/architecture/config-schema) | Separate runtime-loading and editor-validation paths for cross-repository config contract | + +## Related pages + +- [CLI Runtime](/docs/contributing/architecture/cli-runtime) - local runtime, server, routing, persistence, and SDK contracts +- [Cloud Platform](/docs/contributing/architecture/cloud-platform) - hosted layers, Cloud Agent topology, and adjacent hosted boundaries +- [Cloud Security](/docs/contributing/architecture/cloud-security) - cross-cutting trust boundaries, controls, and shared responsibility +- [Development Patterns](/docs/contributing/architecture/development-patterns) - code-ownership decisions and contributor workflow +- [Development Environment](/docs/contributing/development-environment) - setup guide +- [Ecosystem](/docs/contributing/ecosystem) - related projects and integrations +- [KiloClaw Overview](/docs/kiloclaw/overview) - customer-facing KiloClaw docs diff --git a/packages/kilo-docs/pages/contributing/architecture/jetbrains-plugin.md b/packages/kilo-docs/pages/contributing/architecture/jetbrains-plugin.md new file mode 100644 index 00000000000..d54224b8f8a --- /dev/null +++ b/packages/kilo-docs/pages/contributing/architecture/jetbrains-plugin.md @@ -0,0 +1,160 @@ +--- +title: "JetBrains Plugin Architecture" +description: "Architecture of the Kilo JetBrains split-mode plugin" +--- + +# JetBrains Plugin Architecture + +The JetBrains plugin (`packages/kilo-jetbrains/`) is a split-mode Swing client of [Kilo CLI runtime](/docs/contributing/architecture/cli-runtime). Frontend module renders IDE UI. Backend module owns project-local logic and one bundled `kilo serve` server. Shared module defines cross-process RPC contracts and serializable payloads. + +{% callout type="info" title="Scope" %} +This page describes repository-defined plugin architecture and development checks. It does not claim Marketplace rollout state or remote-host deployment configuration. +{% /callout %} + +## Split-mode modules + +[CLI Runtime](/docs/contributing/architecture/cli-runtime) defines shared local-server authentication, directory routing, provider routing, persistence, and SSE contracts. This page starts at JetBrains client boundary. + +| Module | Runs where | Responsibility | +|---|---|---| +| `shared` | Frontend and backend | `@Rpc` interfaces, `RemoteApi` contracts, serializable DTOs, shared logging helpers | +| `frontend` | JetBrains frontend | Swing UI, typing assistance, latency-sensitive client work, backend RPC calls | +| `backend` | JetBrains backend | Project model, analysis, CLI extraction and process lifecycle, HTTP/SSE, workspace state, RPC implementations | + +In monolithic IDE mode, all modules load in one process and RPC calls remain in-process suspend calls. In remote development, frontend and backend can run in separate processes. Payloads crossing boundary use `kotlinx.serialization`. + +```mermaid +flowchart LR + subgraph frontend ["JetBrains frontend"] + swing["Swing UI"] + rpcClient["RPC clients"] + end + + subgraph backend ["JetBrains backend"] + rpcImpl["RPC providers"] + app["Backend app service"] + conn["KiloConnectionService"] + workspaces["Directory workspace cache"] + cli["Extracted kilo serve --port 0"] + end + + runtime["Kilo CLI runtime"] + + swing --> rpcClient --> rpcImpl --> app + app --> conn --> cli --> runtime + app --> workspaces --> cli +``` + +## Frontend-to-backend RPC + +Shared RPC surfaces separate app, workspace, session, and migration behavior. + +| Contract | Scope | Examples | +|---|---|---| +| `KiloAppRpcApi` | Application | Connect, state flow, health, retry, restart, reinstall, model state, profile, login, telemetry | +| `KiloWorkspaceRpcApi` | Directory | Resolve real backend project directory, workspace state flow, reload, file lookup, open file | +| `KiloSessionRpcApi` | Session and directory | Create/list sessions, prompt, stream events, permission and question replies, config update | +| `KiloMigrationRpcApi` | Legacy migration | Detect, run, and observe migration state | + +Frontend calls RPC from coroutines, not Event Dispatch Thread (EDT). Swing creation, mutation, and access remain on EDT. Long-lived RPC calls and flows should use JetBrains durable patterns so UI can survive reconnect and backend restart. + +## Bundled CLI lifecycle + +Backend extracts CLI resource from plugin JAR into IntelliJ system path: + +```text +/kilo/bin/kilo +/kilo/bin/kilo.exe # Windows +``` + +It chooses platform resource by OS and CPU architecture, reuses extracted binary when resource size matches, and can force re-extraction during reinstall flow. This editor-owned child is separate from detached local daemon managed by `kilo daemon`. + +| Area | Behavior | +|---|---| +| Spawn | Runs extracted binary as `kilo serve --port 0` | +| Port | CLI server prefers `4096`, then asks OS for free port; backend reads listening line from stdout | +| Authentication | Generates random 32-byte hex password and passes `KILO_SERVER_PASSWORD`; username defaults to `kilo` | +| Environment | Sets JetBrains client/platform metadata, question tool enablement, telemetry level, Claude Code disable flag, and default edit/bash ask permissions unless overridden | +| Ownership | Backend app service owns CLI manager and connection lifecycle | +| Shutdown | Kills process descendants, then process; uses forced termination after timeout when needed | + +## Generated Kotlin client + +JetBrains backend does not consume checked-in JavaScript SDK. Gradle owns build-local client flow: + +1. Generate CLI OpenAPI into backend build directory. +2. Normalize spec for Kotlin generation. +3. Run OpenAPI Kotlin generator with `jvm-okhttp4` library. +4. Compile generated Kotlin source with backend. + +Generated `DefaultApi` handles typed CLI endpoint calls. Selected paths use raw HTTP when generated client shape is unsuitable for specific request behavior. + +## Connection and recovery + +Backend connection service uses bundled OkHttp clients and `/global/event` SSE. + +| Signal or path | Behavior | +|---|---| +| API client | No call/read timeout for generated API and SSE | +| App-load client | Bounded timeout for startup requests | +| Health client | 3 second timeout for `/global/health` polling | +| SSE | OkHttp EventSource connects to `/global/event` | +| Heartbeat | Server emits every 10 seconds; watcher reconnects after 15 seconds without event | +| Health poll | Runs every 10 seconds and forces reconnect on failure | +| SSE failure | Waits 250 ms, reconnects stream if process lives, or delegates full backend reconnect | +| Process monitor | On child exit, clears process state, reports error, and schedules reconnect | + +## Workspace routing + +Backend workspace manager caches workspace clients by directory path. Root project and worktree are same routing shape: worktree is alternate directory key. First lookup creates workspace object and starts load; disconnect clears cache. + +This mirrors CLI `InstanceStore`: directory remains isolation key while one editor-owned `kilo serve` process serves multiple workspace contexts. + +## Remote development constraints + +Split mode changes path and UI assumptions: + +| Constraint | Rule | +|---|---| +| Project path | Frontend base path can be synthetic; resolve real project directory through backend RPC before CLI calls | +| UI toolkit | Use Swing and IntelliJ platform components; do not use JCEF because it does not work for remote split-mode host arrangement | +| RPC traffic | Debounce UI events, batch requests, cache results, and page large payloads | +| First paint | Render empty state promptly and fill backend data progressively | +| Blocking I/O | Keep in backend/background context; switch to `Dispatchers.IO` inside callee | + +## Development checks + +JetBrains Kotlin toolchain is Java 21. Check `java -version` before Gradle verification. + +| Check | Command from `packages/kilo-jetbrains/` | +|---|---| +| Typecheck | `./gradlew typecheck` | +| Tests | `./gradlew test` | +| Full plugin build | `bun run build` | +| Gradle plugin assembly with prepared CLI binaries | `./gradlew buildPlugin` | +| Sandbox IDE | `./gradlew runIde` | +| Split backend sandbox | `./gradlew runIdeBackend` | +| Split-mode run configs | `./gradlew generateSplitModeRunConfigurations` | + +Run `Plugin DevKit | Code | Frontend and Backend API Usage` inspection when moving code across split boundary. + +## Source map + +Paths below are relative to [`Kilo-Org/kilocode`](https://github.com/Kilo-Org/kilocode). + +| Concern | Source path | +|---|---| +| Split modules | `packages/kilo-jetbrains/settings.gradle.kts` and module XML descriptors | +| Contributor constraints | `packages/kilo-jetbrains/AGENTS.md` | +| CLI lifecycle | `packages/kilo-jetbrains/backend/src/main/kotlin/ai/kilocode/backend/cli/KiloBackendCliManager.kt` | +| Connection recovery | `packages/kilo-jetbrains/backend/src/main/kotlin/ai/kilocode/backend/app/KiloBackendConnectionService.kt` | +| Workspace cache | `packages/kilo-jetbrains/backend/src/main/kotlin/ai/kilocode/backend/workspace/KiloBackendWorkspaceManager.kt` | +| Kotlin client generation | `packages/kilo-jetbrains/backend/build.gradle.kts` | +| RPC contracts | `packages/kilo-jetbrains/shared/src/main/kotlin/ai/kilocode/rpc/` | + +## Related pages + +- [Architecture Overview](/docs/contributing/architecture) - local and hosted execution map +- [CLI Runtime](/docs/contributing/architecture/cli-runtime) - shared local-server, routing, persistence, and SSE behavior +- [VS Code Extension](/docs/contributing/architecture/vscode-extension) - corresponding editor-client architecture for VS Code +- [Development Patterns](/docs/contributing/architecture/development-patterns) - choose code-ownership seam and validation workflow before editing plugin contracts diff --git a/packages/kilo-docs/pages/contributing/architecture/mcp-oauth-authorization.md b/packages/kilo-docs/pages/contributing/architecture/mcp-oauth-authorization.md deleted file mode 100644 index 79c16269a76..00000000000 --- a/packages/kilo-docs/pages/contributing/architecture/mcp-oauth-authorization.md +++ /dev/null @@ -1,572 +0,0 @@ ---- -title: "MCP OAuth Authorization" -description: "OAuth 2.1-based authorization flow for MCP servers" ---- - -# MCP OAuth Authorization - -### Overview - -Many MCP servers require authentication to access protected resources. Currently, Kilo Code only supports static credential configuration (API keys, tokens) which must be manually entered and stored. This creates friction for users and security concerns for enterprises. - -The MCP specification defines an OAuth 2.1-based authorization flow that enables secure, user-friendly authentication without requiring users to manually manage credentials. This document specifies how Kilo Code will implement the MCP Authorization specification to support OAuth-enabled MCP servers. - -### Goals - -1. **Eliminate manual credential management** - Users authenticate via browser-based OAuth flows instead of copying/pasting API keys -2. **Improve security** - Tokens are obtained through secure OAuth flows with PKCE, reducing credential exposure -3. **Support enterprise SSO** - Organizations can use their existing identity providers -4. **Maintain compatibility** - Continue supporting static credentials for servers that don't implement OAuth - -### Non-Goals (MVP) - -- Token refresh automation (will use re-authentication flow initially) -- Dynamic Client Registration (will rely on Client ID Metadata Documents) -- Multiple authorization server selection (will use first available) - -## MCP Authorization Specification Summary - -The MCP Authorization spec (Protocol Revision 2025-11-25) defines an OAuth 2.1-based flow for HTTP-based MCP transports. Key components: - -### Roles - -- **MCP Server** - Acts as OAuth 2.1 Resource Server, accepts access tokens -- **MCP Client** (Kilo Code) - Acts as OAuth 2.1 Client, obtains tokens on behalf of users -- **Authorization Server** - Issues access tokens (may be hosted with MCP server or separate) - -### Discovery Flow - -1. Client makes unauthenticated request to MCP server -2. Server returns `401 Unauthorized` with `WWW-Authenticate` header containing `resource_metadata` URL -3. Client fetches Protected Resource Metadata (RFC 9728) to discover authorization server(s) -4. Client fetches Authorization Server Metadata (RFC 8414 or OpenID Connect Discovery) -5. Client initiates OAuth authorization flow - -### Client Registration - -The spec supports three approaches (in priority order): - -1. **Pre-registration** - Client has existing credentials for the server -2. **Client ID Metadata Documents** - Client uses HTTPS URL as client_id pointing to metadata JSON -3. **Dynamic Client Registration** - Client registers dynamically via RFC 7591 - -### Authorization Flow - -1. Generate PKCE code verifier and challenge -2. Open browser with authorization URL including `resource` parameter (RFC 8707) -3. User authenticates and authorizes -4. Receive authorization code via redirect -5. Exchange code for access token -6. Use access token in `Authorization: Bearer` header for MCP requests - -## System Design - -### Architecture Overview - -``` -┌─────────────────────────────────────────────────────────────────────────────────┐ -│ MCP OAuth Authorization Flow │ -├─────────────────────────────────────────────────────────────────────────────────┤ -│ │ -│ ┌──────────────┐ 1. MCP Request ┌──────────────────┐ │ -│ │ │ ───────────────────► │ │ │ -│ │ Kilo Code │ │ MCP Server │ │ -│ │ Extension │ ◄─────────────────── │ (Resource │ │ -│ │ │ 2. 401 + metadata │ Server) │ │ -│ └──────┬───────┘ └──────────────────┘ │ -│ │ │ -│ │ 3. Fetch resource metadata │ -│ │ 4. Fetch auth server metadata │ -│ ▼ │ -│ ┌──────────────┐ ┌──────────────────┐ │ -│ │ OAuth │ 5. Auth Request │ │ │ -│ │ Service │ ───────────────────► │ Authorization │ │ -│ │ │ │ Server │ │ -│ │ - Discovery │ ◄─────────────────── │ │ │ -│ │ - PKCE │ 8. Token Response │ - User Auth │ │ -│ │ - Tokens │ │ - Consent │ │ -│ └──────┬───────┘ └──────────────────┘ │ -│ │ ▲ │ -│ │ 6. Open browser │ 7. User authenticates │ -│ ▼ │ │ -│ ┌──────────────┐ ┌────────┴─────────┐ │ -│ │ Browser │ ─────────────────────►│ User │ │ -│ │ │ │ │ │ -│ └──────────────┘ └──────────────────┘ │ -│ │ -└─────────────────────────────────────────────────────────────────────────────────┘ -``` - -### New Components - -#### 1. McpOAuthService - -A new service responsible for managing OAuth flows for MCP servers: - -```typescript -// src/services/mcp/oauth/McpOAuthService.ts - -interface McpOAuthService { - /** - * Initiates OAuth flow for an MCP server that returned 401 - * @param serverUrl The MCP server URL - * @param wwwAuthenticateHeader The WWW-Authenticate header from 401 response - * @returns Promise resolving to access token - */ - initiateOAuthFlow(serverUrl: string, wwwAuthenticateHeader: string): Promise - - /** - * Gets stored tokens for a server, if available and valid - */ - getStoredTokens(serverUrl: string): Promise - - /** - * Clears stored tokens for a server (for logout/re-auth) - */ - clearTokens(serverUrl: string): Promise - - /** - * Refreshes tokens if refresh token is available - */ - refreshTokens(serverUrl: string): Promise -} - -interface OAuthTokens { - accessToken: string - tokenType: string - expiresAt?: number - refreshToken?: string - scope?: string -} -``` - -#### 2. McpAuthorizationDiscovery - -Handles the discovery of authorization server metadata: - -```typescript -// src/services/mcp/oauth/McpAuthorizationDiscovery.ts - -interface McpAuthorizationDiscovery { - /** - * Discovers authorization server from WWW-Authenticate header or well-known URIs - */ - discoverAuthorizationServer(serverUrl: string, wwwAuthenticateHeader?: string): Promise - - /** - * Fetches Protected Resource Metadata (RFC 9728) - */ - fetchResourceMetadata(metadataUrl: string): Promise - - /** - * Fetches Authorization Server Metadata (RFC 8414 / OIDC Discovery) - */ - fetchAuthServerMetadata(issuerUrl: string): Promise -} - -interface ProtectedResourceMetadata { - resource: string - authorization_servers: string[] - scopes_supported?: string[] - // ... other RFC 9728 fields -} - -interface AuthorizationServerMetadata { - issuer: string - authorization_endpoint: string - token_endpoint: string - scopes_supported?: string[] - response_types_supported: string[] - code_challenge_methods_supported?: string[] - client_id_metadata_document_supported?: boolean - registration_endpoint?: string - // ... other RFC 8414 fields -} -``` - -#### 3. McpOAuthTokenStorage - -Secure storage for OAuth tokens: - -```typescript -// src/services/mcp/oauth/McpOAuthTokenStorage.ts - -interface McpOAuthTokenStorage { - /** - * Stores tokens securely using VS Code SecretStorage - */ - storeTokens(serverUrl: string, tokens: OAuthTokens): Promise - - /** - * Retrieves stored tokens - */ - getTokens(serverUrl: string): Promise - - /** - * Removes stored tokens - */ - removeTokens(serverUrl: string): Promise - - /** - * Lists all servers with stored tokens - */ - listServers(): Promise -} -``` - -#### 4. Client ID Metadata Document Hosting - -For Client ID Metadata Documents, Kilo Code needs to host a metadata document. We will use static hosting on kilocode.ai: - -- Host at `https://kilocode.ai/.well-known/oauth-client/vscode-extension.json` -- Simple, reliable, no runtime dependencies -- Authorization servers can cache the document effectively -- No attack surface from dynamic generation logic - -Metadata document: - -```json -{ - "client_id": "https://kilocode.ai/.well-known/oauth-client/vscode-extension.json", - "client_name": "Kilo Code", - "client_uri": "https://kilocode.ai", - "logo_uri": "https://kilocode.ai/logo.png", - "redirect_uris": ["http://127.0.0.1:0/callback", "vscode://kilocode.kilo-code/oauth/callback"], - "grant_types": ["authorization_code"], - "response_types": ["code"], - "token_endpoint_auth_method": "none" -} -``` - -### Integration with McpHub - -The existing `McpHub` class needs modifications to support OAuth: - -```typescript -// Modifications to McpHub.ts - -class McpHub { - private oauthService: McpOAuthService - - private async connectToServer(name: string, config: ServerConfig, source: "global" | "project"): Promise { - // ... existing connection logic ... - - // For HTTP-based transports, handle OAuth - if (config.type === "sse" || config.type === "streamable-http") { - try { - await this.connectWithOAuth(name, config, source) - } catch (error) { - if (this.isOAuthRequired(error)) { - // Initiate OAuth flow - const tokens = await this.oauthService.initiateOAuthFlow(config.url, error.wwwAuthenticateHeader) - // Retry connection with token - await this.connectWithToken(name, config, source, tokens) - } else { - throw error - } - } - } - } - - private isOAuthRequired(error: unknown): boolean { - // Check if error is 401 with WWW-Authenticate header - return error instanceof HttpError && error.status === 401 && error.headers?.["www-authenticate"] - } -} -``` - -### Configuration Schema Updates - -Update the server configuration schema to support OAuth: - -```typescript -// Extended server config for OAuth-enabled servers -const OAuthServerConfigSchema = BaseConfigSchema.extend({ - type: z.enum(["sse", "streamable-http"]), - url: z.string().url(), - headers: z.record(z.string()).optional(), - - // OAuth configuration - oauth: z - .object({ - // Override client_id if pre-registered - clientId: z.string().optional(), - clientSecret: z.string().optional(), - - // Override scopes to request - scopes: z.array(z.string()).optional(), - - // Disable OAuth for this server (use static headers instead) - disabled: z.boolean().optional(), - }) - .optional(), -}) -``` - -### Browser-Based Authorization Flow - -The OAuth flow requires opening a browser for user authentication: - -```typescript -// src/services/mcp/oauth/McpOAuthBrowserFlow.ts - -interface McpOAuthBrowserFlow { - /** - * Opens browser for authorization and waits for callback - */ - authorize(params: AuthorizationParams): Promise -} - -interface AuthorizationParams { - authorizationEndpoint: string - clientId: string - redirectUri: string - scope: string - state: string - codeChallenge: string - codeChallengeMethod: "S256" - resource: string -} - -interface AuthorizationResult { - code: string - state: string -} -``` - -**Redirect URI Handling:** - -Two approaches for receiving the OAuth callback: - -1. **Local HTTP Server** (Primary) - - Start temporary HTTP server on random port - - Use `http://127.0.0.1:{port}/callback` as redirect URI - - Server receives callback, extracts code, closes - -2. **VS Code URI Handler** (Fallback) - - Register `vscode://kilocode.kilo-code/oauth/callback` URI handler - - Works when local server isn't possible - - Requires VS Code to be running - -### Token Management - -#### Storage - -Tokens are stored using VS Code's SecretStorage API: - -```typescript -// Key format: mcp-oauth-{serverUrlHash} -const storageKey = `mcp-oauth-${hashServerUrl(serverUrl)}` - -// Stored value (encrypted by VS Code) -interface StoredTokenData { - accessToken: string - refreshToken?: string - expiresAt?: number - scope?: string - serverUrl: string - issuedAt: number -} -``` - -#### Token Lifecycle - -1. **Initial Authentication** - - User triggers connection to OAuth-enabled MCP server - - Server returns 401, OAuth flow initiated - - User authenticates in browser - - Tokens stored securely - -2. **Subsequent Connections** - - Check for stored tokens - - If valid, use directly - - If expired and refresh token available, attempt refresh - - If refresh fails or no refresh token, re-authenticate - -3. **Token Refresh** (Future Enhancement) - - Background refresh before expiry - - Automatic retry on 401 with new token - -### Error Handling - -```typescript -// OAuth-specific errors -class McpOAuthError extends Error { - constructor( - message: string, - public code: OAuthErrorCode, - public serverUrl: string, - public details?: Record, - ) { - super(message) - } -} - -enum OAuthErrorCode { - DISCOVERY_FAILED = "discovery_failed", - AUTHORIZATION_FAILED = "authorization_failed", - TOKEN_EXCHANGE_FAILED = "token_exchange_failed", - TOKEN_REFRESH_FAILED = "token_refresh_failed", - PKCE_NOT_SUPPORTED = "pkce_not_supported", - USER_CANCELLED = "user_cancelled", - TIMEOUT = "timeout", -} -``` - -### User Experience - -#### Connection Flow - -1. User adds/enables OAuth-enabled MCP server -2. Extension detects OAuth requirement (401 response) -3. Notification: "MCP server requires authentication. Click to sign in." -4. User clicks -> Browser opens to authorization server -5. User authenticates and authorizes -6. Browser redirects back -> Extension receives token -7. Connection completes -> Server shows as connected - -#### UI Indicators - -- **Authenticated servers**: Show lock icon with "Authenticated" status -- **Authentication required**: Show warning icon with "Sign in required" action -- **Authentication expired**: Show refresh icon with "Re-authenticate" action - -#### Settings UI - -Add OAuth status to MCP server settings: - -``` -┌─────────────────────────────────────────────────────────────┐ -│ MCP Server: github-mcp │ -├─────────────────────────────────────────────────────────────┤ -│ Status: Connected │ -│ Type: streamable-http │ -│ URL: https://mcp.github.com │ -│ │ -│ Authentication │ -│ - Method: OAuth 2.0 │ -│ - Status: Authenticated │ -│ - Expires: 2024-01-15 10:30 AM │ -│ - [Sign Out] [Re-authenticate] │ -└─────────────────────────────────────────────────────────────┘ -``` - -## Security Considerations - -### PKCE Requirement - -All OAuth flows MUST use PKCE with S256 challenge method: - -```typescript -function generatePKCE(): { verifier: string; challenge: string } { - // Generate 32-byte random verifier - const verifier = base64UrlEncode(crypto.randomBytes(32)) - - // Create S256 challenge - const challenge = base64UrlEncode(crypto.createHash("sha256").update(verifier).digest()) - - return { verifier, challenge } -} -``` - -### State Parameter - -Generate cryptographically random state to prevent CSRF: - -```typescript -const state = base64UrlEncode(crypto.randomBytes(32)) -// Store state locally and verify on callback -``` - -### Token Storage Security - -- Use VS Code SecretStorage (encrypted, per-workspace) -- Never log tokens -- Clear tokens on extension uninstall -- Support manual token revocation - -### Resource Parameter - -Always include `resource` parameter to bind tokens to specific MCP server: - -```typescript -const authUrl = new URL(authorizationEndpoint) -authUrl.searchParams.set("resource", mcpServerUrl) -``` - -### Redirect URI Validation - -- Only accept callbacks on registered redirect URIs -- Validate state parameter matches -- Use localhost with random port (not predictable) - -## Scope and Implementation Plan - -### Phase 1: Core OAuth Infrastructure - -- [ ] Create `McpOAuthService` with basic flow support -- [ ] Implement `McpAuthorizationDiscovery` for metadata fetching -- [ ] Implement `McpOAuthTokenStorage` using SecretStorage -- [ ] Add PKCE generation utilities -- [ ] Create local HTTP server for OAuth callbacks - -### Phase 2: McpHub Integration - -- [ ] Modify `McpHub.connectToServer()` to detect OAuth requirements -- [ ] Add OAuth retry logic for 401 responses -- [ ] Update server configuration schema for OAuth options -- [ ] Add token injection to HTTP transports - -### Phase 3: Client ID Metadata Document - -- [ ] Host Kilo Code client metadata at kilocode.ai -- [ ] Implement client_id URL generation -- [ ] Add fallback to pre-registration for unsupported servers - -### Phase 4: User Experience - -- [ ] Add OAuth status indicators to MCP server UI -- [ ] Implement "Sign in" / "Sign out" actions -- [ ] Add authentication expiry notifications -- [ ] Create re-authentication flow - -### Phase 5: Testing & Documentation - -- [ ] Unit tests for OAuth service components -- [ ] Integration tests with mock OAuth server -- [ ] End-to-end tests with real OAuth-enabled MCP servers -- [ ] User documentation for OAuth-enabled servers - -## Future Enhancements - -- **Automatic token refresh** - Background refresh before expiry -- **Dynamic Client Registration** - Support RFC 7591 for servers that require it -- **Multiple authorization servers** - UI for selecting preferred auth server -- **Enterprise SSO integration** - Support for organization identity providers -- **Token sharing across workspaces** - Optional global token storage -- **Offline token caching** - Support for offline scenarios with cached tokens - -## Appendix: MCP Authorization Spec Compliance Checklist - -### Required (MUST) - -- [ ] Use PKCE with S256 for all authorization requests -- [ ] Include `resource` parameter in authorization and token requests -- [ ] Support WWW-Authenticate header parsing for resource metadata discovery -- [ ] Support well-known URI fallback for resource metadata -- [ ] Support both OAuth 2.0 and OpenID Connect discovery endpoints -- [ ] Use Authorization header with Bearer scheme for token transmission -- [ ] Validate PKCE support before proceeding with authorization - -### Recommended (SHOULD) - -- [ ] Support Client ID Metadata Documents -- [ ] Use scope from WWW-Authenticate header when provided -- [ ] Fall back to scopes_supported when scope not in challenge -- [ ] Implement step-up authorization for insufficient_scope errors - -### Optional (MAY) - -- [ ] Support Dynamic Client Registration (RFC 7591) -- [ ] Support pre-registered client credentials -- [ ] Implement token refresh flows diff --git a/packages/kilo-docs/pages/contributing/architecture/onboarding-improvements.md b/packages/kilo-docs/pages/contributing/architecture/onboarding-improvements.md deleted file mode 100644 index 9dc9a222336..00000000000 --- a/packages/kilo-docs/pages/contributing/architecture/onboarding-improvements.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: "Onboarding Improvements" -description: "Onboarding and engagement improvements architecture" ---- - -# Onboarding Improvements - -# Overview - -New users get minimal onboarding with generic prompts and no feature guidance. This causes poor engagement and users miss key capabilities. Existing users lack visibility into new features. - -This spec proposes improved welcome screens, interactive tutorials, and in-product changelog to drive better activation and feature adoption. - -# Requirements - -- Replace generic "CSS gradient generator" prompt with 4+ contextually relevant starter prompts with visual icons -- Implement interactive tutorial system highlighting key UI elements (modes, mcp, settings) -- Display in-product changelog with smart visibility rules for returning users -- Remember tutorial completion state to avoid showing it repeatedly to users -- Implement analytics tracking for onboarding completion rates and user engagement metrics - -# Tasks - -## Welcome Screen Redesign - -Redesign welcome screen with visual appeal and actionable starter prompts. - -**Layout Structure:** - -``` -+----------------------------------+ -| [KiloCode Logo] | -| "Welcome to KiloCode" | -| | -| +--------+ +--------+ | -| | Card 1 | | Card 2 | | -| +--------+ +--------+ | -| | -| +--------+ +--------+ | -| | Card 3 | | Card 4 | | -| +--------+ +--------+ | -| | -| [Skip] [Start Tutorial] | -+----------------------------------+ -``` - -**Starter Prompt Cards Ideas** - -- **Debug Helper**: 🐛 "Help me fix a bug in my code" -- **Feature Builder**: ⚡ "Add a new feature to my project" -- **Documentation**: 📝 "Generate documentation for this file" -- **Code Review**: 🔍 "Review my current changes by running `git diff` and analyzing the output" - -Each card will have: - -- Hover state with subtle elevation -- Click to populate chat input -- Icon using VS Code's codicon library - -## In-App Tutorial Flow - -Users aren't guided through Kilo Code's modes or key features. The existing tab-based tutorial is easily dismissed, causing users to miss critical functionality. - -Replace the tab-based tutorial with an in-app experience using specific highlighting flows to guide users through core functionality. - -**Tutorial Flow** - -``` -Step 1: Welcome -├── Highlight: Entire interface -├── Content: "Welcome to KiloCode! Let's take a quick tour." -└── Actions: [Skip Tour] [Next] - -Step 2: Mode Selection -├── Highlight: Mode selector buttons -├── Content: "Choose between Chat, Edit, and Architect modes for different tasks" -└── Actions: [Back] [Next] - -Step 3: Side Panels & MCP Configuration -├── Highlight: Left sidebar -├── Content: "Access history, memory, and configure MCP servers for enhanced capabilities" -└── Actions: [Back] [Next] - -Step 4: Starting a Chat -├── Highlight: Input area -├── Content: "Type your request here or use @ to reference files" -└── Actions: [Back] [Next] - -Step 5: Starter Prompts -├── Highlight: Starter prompt area -├── Content: "Use these prompts to get started quickly with common tasks" -└── Actions: [Back] [Finish] -``` - -## Kilo Provider Settings UI Improvements - -The "Set API Key" button is at the bottom of settings, making Kilo Code setup hard to discover and complete. - -**Improvements:** - -- Move "Set API Key" button next to API key input field -- Rearrange layout for better flow -- Make Kilo Code provider setup prominent -- Reduce setup friction - -## Analytics Integration - -Track user interactions to identify where users drop off in the product funnel. This data enables targeted improvements to increase activation rates. - -**Key Funnel Events to Track:** - -**Onboarding Funnel:** - -- `onboarding.started` -- `onboarding.tutorial.completed` -- `onboarding.tutorial.skipped` -- `onboarding.prompt.selected` (with prompt type) -- `onboarding.finished` - Critical completion milestone - -**Product Engagement Funnel:** - -- `chat.started` - First interaction with core functionality -- `mode.changed` (with mode type) - Feature discovery and usage -- `changelog.viewed` - Re-engagement with new features -- `changelog.dismissed` -- `provider.configured` - Setup completion -- `file.referenced` - Advanced feature usage (@-mentions) -- `mcp.configured` - Power user feature adoption - -**Drop-off Analysis Goals:** - -- Identify at what point users stop progressing through onboarding -- Measure conversion from onboarding completion to first chat -- Track mode adoption rates and feature discovery patterns -- Understand re-engagement effectiveness through changelog interactions - -## In-Product Changelog - -Re-engage inactive users by highlighting new features and improvements. Acts as a reminder system to reactivate dormant users and keep active users informed. - -## Features for the Future - -- **User Drop-off Funnel Analysis**: Implement comprehensive PostHog funnel tracking to identify where users abandon the onboarding flow and create targeted recovery strategies -- **Contextual Project Analysis**: Detect and analyze user's project structure to provide personalized first-action recommendations based on their codebase -- Progressive disclosure of advanced features over time -- Personalized onboarding flows based on user role (frontend dev, backend dev, DevOps) -- AI-powered prompt suggestions based on actual project code patterns -- Integration with Kilo Code teams for company/repo-personalized onboarding diff --git a/packages/kilo-docs/pages/contributing/architecture/organization-modes-library.md b/packages/kilo-docs/pages/contributing/architecture/organization-modes-library.md deleted file mode 100644 index bcabb1c18bf..00000000000 --- a/packages/kilo-docs/pages/contributing/architecture/organization-modes-library.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: "Organization Modes Library" -description: "Organization modes library architecture" ---- - -# Organization Modes Library - -# Overview - -We want to expand the value of teams & enterprise and make it more useful for collaboration and hopefully increase 'lock in' to the Kilo platform. We can build something _like_ a prompt library, but a bit more powerful. We can leverage Kilo's unique "modes" which already has "marketplace" support to enable teams & enterprises to define and manage modes on the backend webapp and have those modes show up in the modes marketplace if the user is using an organization in the extension. This feature is mostly valuable in larger organizations where they work on many different repositories. If you have very few repositories, then the value is low since you can also store custom modes within the git repo, effectively sharing it with anyone who uses the repo already. - -# Requirements - -This section outlines the detailed requirements that the solution will fulfill. - -- Ability for an organization to have custom modes visible in the web UI. -- Fetch the organization custom modes and show them by default if you switch to an organization alongside any other modes you have manually installed & the "base" modes like "code" "architect" etc. Important consideration here is the organization also has a "code" mode it should overwrite the built in one. This allows the organization owners to modify the built in prompts. -- Ability for team members (or owners only?) to do crud on modes on the UI of the web, including uploading/downloading yaml directly, editing the yaml, and having a form style editor as seen in the extension. -- Web ui showing a list of modes and common info like when created, who created, and when updated. -- Auditing of Custom Mode CRUD operations in the Kilo backend web UI. - -### Non-requirements - -- Disabling the mode marketplace or removing built-in modes. -- Disabling custom modes created locally by an organization member. -- Ability to upload modes from the extension into the web backend via a special extension button. -- Extending the mode definition to include a suggested model to use with the mode (that would be nice though) - -# System Design - -![Organization Modes Library UI](/docs/img/organization-modes-library-1.png) - -![Organization Modes Library Editor](/docs/img/organization-modes-library-2.png) - -Currently extension fetches available modes from the "mode marketplace" by downloading a "modes.yaml" file from our backend. We will add an endpoint the extension can call with a user & org id and it can return any organization modes. Those will be merged into the mode list and dropdown shown to the user. - -The organization modes themselves will be saved in postgres, and there will be both a form style editing UI based on what's in the extension. - -Will add a new section to the backend UI to view custom org modes, edit them, create new ones, etc. - -Schema change: - -```sql -CREATE TABLE organization_modes ( - id uuid primary key, - organization_id uuid not null, - name text not null, - slug text not null, - created_by text not null, - created_at timestamptz default now(), - updated_at timestamptz default now(), - config jsonb -) -``` - -We're recommending using jsonb for the non _critical_ pieces of the modes so it's easier to keep in sync with the extension vs a schema we have to migrate (not everyone updates to the most recent extension immediately, for example) - -# Scope and implementation - -- Schema migration -- Make CRUD ui on backend, feature flagged out to only our organization to begin with. Estimate this is 1 day of work. -- Make endpoint to return org modes -- Render org modes in extension. Estimating 2 days for this because we are both unfamiliar with how to work on extension, and there be dragons there. - -# Compliance Considerations - -Should log any mode CRUD operations to audit logs for enterprise. Otherwise, none. - -## Open questions - -- Teams or enterprise? My vote is teams diff --git a/packages/kilo-docs/pages/contributing/architecture/per-message-feedback.md b/packages/kilo-docs/pages/contributing/architecture/per-message-feedback.md deleted file mode 100644 index 834906dc84e..00000000000 --- a/packages/kilo-docs/pages/contributing/architecture/per-message-feedback.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: "Per-Message Feedback" -description: "Thumbs up/down feedback on assistant messages sent to Kilo via telemetry" ---- - -# Per-Message Feedback (Thumbs Up / Down) - -## Problem - -We have no signal on which assistant responses are helpful and which aren't. Without per-response feedback, we can't: - -- Correlate model or prompt changes to user-perceived quality -- Identify specific bad responses in the Kilo Gateway logs for investigation -- Detect patterns where certain providers, models, or prompt paths consistently underperform - -Aggregate metrics like session completion rate or token cost are too coarse to understand individual response quality. A lightweight thumbs-up/down on each message can help close the feedback loop. - -## Proposal - -Add a thumbs-up / thumbs-down widget next to the existing copy button on every assistant message. Ratings are sent to Kilo via the existing PostHog telemetry pipeline. The UI is hidden entirely when telemetry is disabled. - -### Scope - -| Surface | Approach | -|---|---| -| VS Code extension | Thumbs buttons inline next to the copy button | -| TUI | Keybinds (`=` / `-`) on the last assistant message | - -### Telemetry Payload - -We deliberately collect fewer identifiers for non-Kilo providers, since those IDs can't be correlated to upstream data and add tracking surface without product benefit. Users of non-Kilo GW models would also not expect or want us to collect that information in Kilo GW from other providers. - -**Third party providers (Anthropic, OpenAI, local, etc.):** -`providerID`, `modelID`, `variant?`, `rating`, `previousRating?` - -**Kilo Gateway turns (`providerID` starts with `"kilo"`):** -Same fields plus `sessionID`, `messageID`, and `parentMessageID` (= the `x-kilo-request` header the gateway already saw). This lets backend analysts join feedback against gateway logs to diagnose specific bad responses. - -Event name: `"Feedback Submitted"` — a single event string in both telemetry enum registries so PostHog sees one event regardless of source. - -### UX - -- **Toggleable**: click the same button again to clear, or click the opposite to switch. Each change fires a new event with `rating` and `previousRating`. -- **In-memory state**: ratings are keyed by message ID and held in the webview/TUI session. Persisting across reloads is deferred to a follow-up. -- **Gated on telemetry**: if the user has VS Code telemetry disabled, the buttons don't render at all. For the CLI when telemetry is off, the keybinds are no-ops. - -### Architecture (high level) - -``` -[webview button / TUI keybind] - → existing telemetry proxy or Telemetry.track() - → POST /telemetry/capture (webview path) - → Telemetry.track("Feedback Submitted", {…}) - → PostHog -``` - -No new server endpoints, no SDK regeneration, no PostHog-side changes. The `/telemetry/capture` route and both telemetry proxy paths already exist and accept arbitrary event names. - -### Kilo Gateway Detection - -The webview uses `providerID.startsWith("kilo")` to decide whether to include correlation IDs — this matches the outbound header gating in `packages/opencode/src/session/llm.ts`. The TUI can use the more precise `model.api.npm === "@kilocode/kilo-gateway"` check since it has access to the full provider resolution in-process. - -## What's Out of Scope - -- Free-text comments on thumbs-down -- 1–5 scale or star rating -- Persisting ratings across page reloads / session switches -- Changing prior-message actions (copy + thumbs) to hover-only -- Shared web UI / desktop surface - -## Open Questions - -- Should ratings persist on the `MessageV2.Assistant` schema so they survive reloads? -- Confirm with the PostHog dashboard owner that the proposed event + property names fit existing conventions. -- Whether to add free-text comments for thumbs-down in a follow-up. diff --git a/packages/kilo-docs/pages/contributing/architecture/track-repo-url.md b/packages/kilo-docs/pages/contributing/architecture/track-repo-url.md deleted file mode 100644 index e080af94e96..00000000000 --- a/packages/kilo-docs/pages/contributing/architecture/track-repo-url.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: "Track Repo URL" -description: "Track repository URL architecture" ---- - -# Track Usage by Project - -# Overview - -We will define a "project" as a **repository** and will be identified by `project.id`. We can automatically get the `project.id` from the git remote `origin` if it doesn't exist, but also introduce the concept of a `.kilocode/config.json` file which you can use to manually set (and override in the case of an `origin` remote existing) `project.id`. This allows for "automagic" configuration in most cases, but for an override and helps with things like monorepos which can contain multiple "projects." It also stands in for places where the code structure is less defined like using kilo-cli or running Kilo cloud agents on checked out pieces of code, etc. - -This will allow us to track which projects are used for every LLM call in the `microdollar_usage` table. We can then add this very easily to reporting to show how much of your costs are going to each "project" (identified by unique `project.id`). This feature is a prerequisite for "project based settings." - -## System Design - -![System Design](/docs/img/track-repo-url-system-design.png) - -### Example config - -```jsonc -{ - // Example configuration for project settings - "project": { - // Kilo Code project ID - "id": "my-project", - }, -} -``` - -## Implementation Plan - -- Modify extension to get the `project.id` by getting the `origin` url from the git remotes. -- Modify extension to support an optional `.kilocode/config.json` and add the addition of `project.id` to the config file there. -- Modify extension to send `project.id` in a header to our backend OpenRouter endpoint (maybe `X_KILOCODE_PROJECTID`) -- Add some kind of json-schema to this file for some auto-complete goodness. -- Modify **all** backend requests to include the `project.id` if it exists as an http header. -- Modify `microdollar_usage` and add the `project_id` column. -- Modify usage details to support grouping by `repo_url` and seeing "who worked on **what**, when, and how much did it cost." - -# Compliance Considerations - -I don't think it will hurt to save this, particularly since they can remove it by setting `project.id: ""` in `.kilocode/config.json`. diff --git a/packages/kilo-docs/pages/contributing/architecture/voice-transcription.md b/packages/kilo-docs/pages/contributing/architecture/voice-transcription.md deleted file mode 100644 index 7fcfd8d7d88..00000000000 --- a/packages/kilo-docs/pages/contributing/architecture/voice-transcription.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: "Voice Transcription" -description: "Voice transcription architecture" ---- - -# Voice Transcription - -# Overview - -Developers can code 3-5x faster by dictating rather than typing, yet Kilo Code currently has no voice input capability. This creates friction for users who want to quickly describe complex features or iterate on ideas hands-free. - -This spec proposes adding live voice transcription to the chat interface, replacing the send button with a microphone icon when the text box is empty. Users can speak naturally while seeing real-time transcription appear in the input field, dramatically improving coding velocity for voice-preferred workflows. - -The MVP will use OpenAI's Realtime API with FFmpeg-based audio streaming for low-latency transcription (~100ms). This mirrors the approach used by Cursor and Cline, proven to work well in VS Code environments. - -# Requirements - -- **Microphone Icon UI**: Add microphone icon button that allows starting/stopping the transcription -- **Live Transcription Display**: Show real-time transcription in the chat text box as user speaks -- **FFmpeg Audio Streaming**: Use FFmpeg to capture and stream audio to transcription API -- **Realtime API Integration**: Use OpenAI's Realtime API for near-instant transcription -- **Visual Recording Indicator**: Show clear UI state when recording is active (animated volume bars or similar) -- **Typing Stops Recording**: Any keyboard input immediately stops transcription and returns to normal mode -- **Cross-Platform FFmpeg Docs**: Provide installation instructions for Windows, macOS, and Linux -- **OpenAI Provider Required**: Feature only available when user has configured an OpenAI API key in their provider settings. (This uses the user's own OpenAI credits, not Kilo Code credits.) - -### Non-requirements - -- Custom glossary / file / workflow support (future enhancement) -- Real-time volume visualization (future enhancement) -- Alternative transcription providers beyond OpenAI (future) -- Kilo Code provider integration for voice transcription (future) -- **Usage cost tracking/display** (not in initial version, but should be added in a future version since costs are separate from Kilo Code credits) -- Server-side/backend transcription (future) -- FFmpeg automatic installation or bundling -- Voice commands or shortcuts beyond start/stop - -# System Design - -## Architecture Overview - -![Voice Transcription Architecture](/docs/img/voice-transcription-architecture.png) - -The system follows a straightforward streaming architecture where user voice input is captured by FFmpeg, streamed as PCM16 audio to OpenAI's Realtime API via WebSocket, and transcribed text is displayed live in the chat input box. Typing interrupts recording instantly. - -## Core Components - -### 1. Audio Capture Service - -- Spawn FFmpeg as child process from extension host -- Platform-specific audio input configuration: - - **macOS**: `avfoundation` - - **Windows**: `dshow` (DirectShow) - - **Linux**: `alsa` or `pulse` -- Stream PCM16 format at 24kHz mono (required by OpenAI) -- Handle permissions errors and FFmpeg availability checks - -### 2. WebSocket Connection - -- Direct WebSocket connection from extension to OpenAI Realtime API -- Secure API key storage in extension settings (existing provider system) -- Base64 encode audio chunks for transmission -- Handle connection lifecycle (connect, stream, disconnect) - -### 3. UI State Management - -- **Empty Input State**: Show microphone icon -- **Recording State**: Animate microphone, show "Recording..." indicator -- **Transcribing State**: Show live transcription with typing cursor -- **Manual Stop**: Typing any key stops recording and clears recording indicator -- **Error State**: Show clear error message if FFmpeg not found or permissions denied - -### 4. Cost Considerations - -- OpenAI Realtime API: **$0.60 per minute** -- **Cost is charged to user's OpenAI account**, not Kilo Code credits -- Display cost warning in settings or first-time use -- Consider adding usage tracking/warnings for high-volume users - -## FFmpeg Detection & Setup - -**Installation Check Flow**: - -1. On extension activation, verify FFmpeg is available via `ffmpeg -version` -2. If not found, show dismissible banner with installation instructions -3. Link to documentation with platform-specific guides -4. Gracefully disable voice feature if FFmpeg unavailable - -**Documentation Structure**: - -- `docs/user-guide/voice-transcription-setup.md` - - Prerequisites section - - Platform-specific installation - - Troubleshooting common issues - - Permissions setup (especially macOS) - -## Scope/Implementation - -### Phase 1: Core Infrastructure - -- Add FFmpeg detection on extension startup -- Create `AudioCaptureService` class with platform-specific FFmpeg spawning -- Implement WebSocket connection to OpenAI Realtime API -- Add basic error handling and cleanup - -### Phase 2: UI Integration - -- Add microphone icon component to chat input -- Implement state management for recording/transcribing modes -- Wire up transcription events to populate chat input box -- Add typing detection to stop recording -- Add visual recording indicator - -### Phase 3: Polish & Docs - -- Write cross-platform FFmpeg installation guide -- Add cost warning in settings UI -- Test on Windows, macOS, Linux -- Handle edge cases (permissions, no FFmpeg, API errors) -- Add analytics tracking for feature usage - -# Features for the future - -- **Custom Glossary**: Use OpenAI Whisper API's glossary parameter for code-specific terminology -- **Real-time Volume Indicator**: Show live audio input levels during recording -- **Chunked Whisper API Mode**: Add cheaper option ($0.06/min) for users who can tolerate 2-5s latency -- **Provider Flexibility**: Support alternative transcription providers (Deepgram, AssemblyAI) -- **Server-side Transcription**: Move transcription to backend for better security/control -- **Voice Commands**: Implement "stop recording," "send message," and other voice shortcuts -- **Automatic FFmpeg Installation**: Bundle or auto-install FFmpeg to reduce setup friction -- **Recording History**: Save voice recordings locally for debugging or replay -- **Multi-language Support**: Extend beyond English with language detection -- **Usage Cost Tracking**: Display voice transcription costs somewhere (since this would be separate from Kilo Code credits) diff --git a/packages/kilo-docs/pages/contributing/architecture/vscode-extension.md b/packages/kilo-docs/pages/contributing/architecture/vscode-extension.md new file mode 100644 index 00000000000..eff1bef6bb5 --- /dev/null +++ b/packages/kilo-docs/pages/contributing/architecture/vscode-extension.md @@ -0,0 +1,180 @@ +--- +title: "VS Code Extension Architecture" +description: "Architecture of the Kilo VS Code extension and Agent Manager" +--- + +# VS Code Extension Architecture + +The VS Code extension (`packages/kilo-vscode/`) is a client of [Kilo CLI runtime](/docs/contributing/architecture/cli-runtime). It bundles platform CLI binary, starts one shared editor-owned `kilo serve` server on demand, and drives that server through generated SDK HTTP calls plus global SSE. + +{% callout type="info" title="Scope" %} +This page covers extension-host ownership, webview routing, Agent Manager, local terminal paths, recovery, bundled resources, and build outputs. It is not full extension feature inventory. +{% /callout %} + +## Shared server ownership + +[CLI Runtime](/docs/contributing/architecture/cli-runtime) defines shared local-server authentication, directory routing, provider routing, persistence, and SSE contracts. This page starts at VS Code client boundary. + +Activation creates one `KiloConnectionService`. It owns one `ServerManager`, one active SDK client, and one SSE adapter. `ServerManager` owns child process lifecycle. This editor-owned child is separate from detached local daemon managed by `kilo daemon`. + +```mermaid +flowchart LR + subgraph host ["VS Code extension host"] + consumers["Sidebar, tabs, panels, services"] + service["KiloConnectionService"] + manager["ServerManager"] + sdk["Generated SDK client"] + sse["SdkSSEAdapter"] + end + + server["bin/kilo serve --port 0"] + runtime["Kilo CLI runtime"] + + consumers --> service + service --> manager --> server + service --> sdk --> server + service --> sse -->|/global/event| server + server --> runtime +``` + +| Area | Behavior | +|---|---| +| Startup | Lazy on client demand; autocomplete prewarm can start server during activation | +| Binary | Uses extension `bin/kilo`, or `bin/kilo.exe` on Windows | +| Port | Starts `kilo serve --port 0`; CLI server prefers `4096`, then asks OS for free port | +| Authentication | Generates random 32-byte hex password per spawn and passes it as `KILO_SERVER_PASSWORD`; username defaults to `kilo` | +| Reuse | Sidebar, editor tabs, panels, Agent Manager, and host services share active server | +| Exit | `ServerManager` clears dead child; connection service clears SDK/SSE state and enters error state | +| Replacement | Later retry or connection attempt starts replacement server | + +## Shared consumers + +Shared service has more consumers than chat tabs: + +| Family | Consumers | +|---|---| +| Chat | Sidebar provider and editor-tab providers | +| Panels | Settings, profile and marketplace surfaces, sub-agent viewers, Agent Manager, KiloClaw | +| Diff | Diff Viewer, Diff Virtual, and diff source catalog | +| Editor assistance | Autocomplete and commit-message generation | +| Integrations | Browser automation MCP registration and KiloClaw bootstrap | + +New mutable state must account for concurrent consumers and multiple directory contexts on one process. + +## Webview bridge + +Main chat webviews use host-mediated message bridge: + +```text +webview vscode.postMessage() + -> KiloProvider host handler + -> generated SDK HTTP request + -> CLI runtime + -> /global/event SSE + -> SdkSSEAdapter + -> KiloConnectionService subscribers + -> KiloProvider directory/session filtering and stream coalescing + -> webview postMessage() +``` + +Global SSE carries wrapped events for multiple directories. Connection service broadcasts incoming payload plus directory to subscribers. Providers resolve session scope, maintain message-to-session lookup where events omit direct session ID, filter for relevant views, and coalesce high-frequency stream updates before posting UI messages. + +## Agent Manager + +Agent Manager is extension feature, not separate product. It opens as editor tab and manages parallel sessions, optional worktrees, terminals, diffs, setup scripts, and extra editor windows. + +| Aspect | Sidebar | Agent Manager | +|---|---|---| +| Primary use | One active chat view | Multi-session orchestration | +| Git isolation | Workspace root by default | Optional worktree per session | +| Backend | Shared `kilo serve` process | Same shared process | +| Request routing | Workspace directory | Session worktree path passed as SDK `directory` | +| CLI instance key | Normalized workspace root | Normalized worktree directory | + +Agent Manager request path is: + +```text +session worktree path -> SDK directory -> CLI directory-routing middleware -> InstanceStore directory key +``` + +Agent Manager persists state in `.kilo/agent-manager.json` and worktrees under `.kilo/worktrees/`. Startup migration moves Agent Manager-owned data from legacy `.kilocode/` paths when target items do not already exist and repairs git worktree refs. + +## State boundaries + +Directory-keyed CLI state is isolated by worktree path. Process-owned state remains shared because all Agent Manager sessions use one CLI process. Snapshot implementation state is directory-keyed, but slow-snapshot prompt guard belongs to shared `Snapshot.Service` scope. Managed Agent Manager prompts pass `snapshotInitialization: "wait"` so slow baseline setup waits without interrupting concurrently started sessions. + +## Terminal surfaces + +VS Code extension has two terminal paths: + +| Surface | Owner | Use | +|---|---|---| +| VS Code integrated terminal | VS Code host | Shell terminals and setup-script execution surfaced through editor | +| CLI PTY WebSocket tab | Agent Manager and `kilo serve` server | Server-created PTY session streamed over loopback WebSocket | + +Agent Manager PTY WebSocket URL uses `auth_token=` query mode because browser WebSocket API cannot attach Basic header. Webview CSP permits loopback HTTP and WebSocket origins for active server port. CLI also exposes scope-bound short-lived PTY ticket API as alternate browser WebSocket auth mode. + +## Config split + +| Config owner | Examples | +|---|---| +| VS Code settings | `kilo-code.new.*` extension UI, proxy, autocomplete, and integration settings | +| CLI config | Global and project `kilo.jsonc`, `kilo.json`, compatible OpenCode files, provider auth, tools, permissions, modes | + +Extension-specific behavior belongs in VS Code settings. Agent runtime behavior belongs in CLI config so TUI, Console, VS Code, and JetBrains can share it. + +## Bundled resources + +| Resource | Behavior | +|---|---| +| CLI executable | Platform binary under extension `bin/`; Windows uses `kilo.exe` | +| CLI Tree-sitter WASM | Copied under `bin/tree-sitter`; backend spawn sets `KILO_TREE_SITTER_WASM_DIR` | +| FFmpeg helper | Bundled for supported targets for speech capture; capture code also checks system fallback paths | +| Empty-window cwd | Uses extension global storage directory when no VS Code workspace folder exists | +| Empty-window indexing | Sets `KILO_DISABLE_CODEBASE_INDEXING=vscode-no-workspace` so CLI reports indexing disabled | + +Speech-to-text captures audio locally, then sends completed recording through shared editor-owned `kilo serve` server to authenticated Kilo Gateway transcription path. It is batch transcription, not direct provider streaming. + +## Recovery + +| Failure signal | Response | +|---|---| +| Missing SSE events for 15 seconds | SSE adapter aborts attempt and reconnects | +| SSE reconnect | Starts at 250 ms delay and backs off to 5 seconds until stream opens | +| Health poll | Every 10 seconds, checks `/global/health` with 3 second timeout; failure forces SSE reconnect | +| Server exit | Clears connection state, reports error, and lets later retry or connection attempt spawn replacement | +| Extension disposal | Stops polls, disposes SSE, and sends server process group termination with kill fallback | + +## Builds + +| Build | Source | Output | +|---|---|---| +| Extension host | `src/extension.ts` | `dist/extension.js` | +| Sidebar and editor chat webview | `webview-ui/src/index.tsx` | `dist/webview.js` | +| Agent Manager webview | `webview-ui/agent-manager/index.tsx` | `dist/agent-manager.js` | +| KiloClaw webview | `webview-ui/kiloclaw/index.tsx` | `dist/kiloclaw.js` | +| Diff Viewer webview | `webview-ui/diff-viewer/index.tsx` | `dist/diff-viewer.js` | +| Diff Virtual webview | `webview-ui/diff-virtual/index.tsx` | `dist/diff-virtual.js` | +| Shared Shiki worker | synthetic worker entry | `dist/shiki-worker.js` | + +Extension host bundle targets Node/CommonJS. Browser webviews and shared worker use esbuild browser bundles. Run `bun run typecheck`, `bun run lint`, and targeted unit tests from `packages/kilo-vscode/` after changing this area. + +## Source map + +Paths below are relative to [`Kilo-Org/kilocode`](https://github.com/Kilo-Org/kilocode). + +| Concern | Source path | +|---|---| +| Activation | `packages/kilo-vscode/src/extension.ts` | +| Editor-owned server child process | `packages/kilo-vscode/src/services/cli-backend/server-manager.ts` | +| Shared SDK and SSE ownership | `packages/kilo-vscode/src/services/cli-backend/connection-service.ts` | +| SSE reconnect adapter | `packages/kilo-vscode/src/services/cli-backend/sdk-sse-adapter.ts` | +| Agent Manager | `packages/kilo-vscode/src/agent-manager/` | +| Build entries | `packages/kilo-vscode/esbuild.js` | + +## Related pages + +- [Architecture Overview](/docs/contributing/architecture) - local and hosted execution map +- [CLI Runtime](/docs/contributing/architecture/cli-runtime) - shared local-server, routing, persistence, and SSE behavior +- [JetBrains Plugin](/docs/contributing/architecture/jetbrains-plugin) - corresponding editor-client architecture for JetBrains +- [Development Patterns](/docs/contributing/architecture/development-patterns) - choose code-ownership seam and validation workflow before editing extension contracts diff --git a/packages/kilo-docs/pages/contributing/features/agent-observability.md b/packages/kilo-docs/pages/contributing/features/agent-observability.md new file mode 100644 index 00000000000..4b1a347cedd --- /dev/null +++ b/packages/kilo-docs/pages/contributing/features/agent-observability.md @@ -0,0 +1,94 @@ +--- +title: "Agent Observability" +description: "Current observability capabilities and roadmap for agentic coding systems" +--- + +# Agent Observability + +{% callout type="info" title="Status" %} +Partial - API metrics, session ingestion, storage, and burn-rate alert infrastructure exist. Higher-order agent behavior and outcome analysis remain roadmap work. +{% /callout %} + +## Overview + +Agentic coding systems combine model requests, tool execution, file changes, and external API calls. Traditional request metrics catch hard failures. Agent behavior signals are also needed to investigate loops, degraded sessions, and poor outcomes. + +Current cloud service context is documented in [Cloud Platform observability](/docs/contributing/architecture/cloud-platform#observability). + +## Current implementation + +| Capability | Status | Notes | +|---|---|---| +| API metrics ingestion | Current | Operational request metrics ingestion exists | +| Session metrics ingestion | Current | Session-level ingestion exists | +| Burn-rate alert evaluation | Current | Alert evaluation runs against stored metrics | +| Alert config storage | Current | Alert configuration storage exists | +| Analytics Engine storage | Current | API and session metrics datasets exist | +| Export pipelines | Current infrastructure | Metrics export infrastructure exists for downstream analysis | +| Per-message feedback | Current | Explicit user feedback signal exists | + +## Roadmap + +| Capability | Status | Goal | +|---|---|---| +| Oscillation detection | Planned or partial | Detect repeated or alternating agent actions | +| Unique-file progress metrics | Planned or partial | Track files touched during session | +| Unique-tool progress metrics | Planned or partial | Track tool diversity and repeated operations | +| Session termination classification | Planned | Distinguish completion, abandonment, timeout, and errors | +| Higher-order outcome analysis | Planned | Assess usefulness and task success beyond hard errors | + +## Operational metrics roadmap + +Use existing ingestion and alert infrastructure as base for dashboards and service-level objectives. Metric coverage should be validated before treating any field as available in production analysis. + +### API metrics + +Candidate dimensions for model requests: + +- Provider +- Model +- Tool +- Latency +- Success or failure +- Error type +- Token counts +- Client source + +### Session metrics + +Candidate session aggregates: + +- Session duration +- Time to first model response +- Turns and tool calls +- Errors by type +- Tokens consumed +- Context compaction frequency +- Termination reason + +### Alert policy + +Burn-rate evaluation infrastructure exists. Proposed alert routing should page only for recommended models using Kilo Gateway; other conditions can create tickets or remain disabled. + +| Window | Burn rate | Proposed action | +|---|---|---| +| 5 min | 14.4x | Page for major outage | +| 30 min | 6x | Page for incident | +| 6 hr | 1x | Create ticket for behavior change | + +## Agent behavior roadmap + +Initial behavior analysis should focus on repeated operations and progress signals: + +| Signal | Purpose | +|---|---| +| Identical tool calls | Detect repeated actions with same tool and arguments | +| Identical failing calls | Detect retries that repeat same failure | +| Oscillation patterns | Detect alternating states without progress | +| Unique files touched | Estimate breadth of session changes | +| Unique tools used | Compare progress against repeated operations | +| Repeated-to-unique ratio | Identify sessions that may be stuck | + +## Outcome roadmap + +Hard errors and behavior metrics do not prove user success. Later work can combine explicit per-message feedback with session termination analysis and other outcome signals. Offline model and agent comparison belongs in [Benchmarking](/docs/contributing/features/benchmarking). diff --git a/packages/kilo-docs/pages/contributing/features/benchmarking.md b/packages/kilo-docs/pages/contributing/features/benchmarking.md new file mode 100644 index 00000000000..61f8b7480aa --- /dev/null +++ b/packages/kilo-docs/pages/contributing/features/benchmarking.md @@ -0,0 +1,110 @@ +--- +title: "Benchmarking" +description: "Current evaluation evidence and roadmap for benchmarking Kilo Code" +--- + +# Benchmarking + +{% callout type="info" title="Status" %} +Partial - inspected repositories show a Harbor-facing smoke-eval workflow and cloud `model-eval-ingest` promotion sync. Broader Harbor adapters, ATIF traces, Opik workflows, and commands remain unverified roadmap items. +{% /callout %} + +## Overview + +Benchmarking should answer two questions: + +1. How do models compare when used by same Kilo Code agent? +2. How do agents or Kilo Code versions compare when used with same model? + +This page separates inspected repository evidence from roadmap. It does not guarantee private benchmark tooling, external adapters, or example commands are available to contributors. + +{% callout type="info" %} +Benchmarking is separate from [production observability](/docs/contributing/features/agent-observability). Observability monitors real sessions. Benchmarking runs controlled evaluation tasks. +{% /callout %} + +## Current evidence + +| Capability | Status | Evidence and limits | +|---|---|---| +| Harbor-facing smoke eval | Current workflow | `.github/workflows/smoke-test.yml` checks out private `Kilo-Org/kilo-bench`, installs dependencies, and runs two smoke tasks through repository scripts | +| CLI release smoke coverage | Current workflow | Workflow can test latest npm CLI or requested release asset before validating results | +| Smoke result artifacts | Current workflow | Workflow uploads result, trajectory, and agent setup files for inspection | +| Cloud model eval ingest | Current service | Static source inspection found `services/model-eval-ingest/` promotion sync surface | +| Private `kilo-bench` internals | Not verified here | Private repository scripts, adapter behavior, and supported local commands are outside inspected docs scope | +| Live production enablement | Not verified here | Static source does not prove deployment, rollout, retention, or vendor configuration | + +## Roadmap + +| Capability | Status | Intended use | +|---|---|---| +| Contributor-facing Harbor adapter | Unverified roadmap | Run Kilo CLI autonomously in controlled evaluation environments | +| ATIF trajectory adapter | Unverified roadmap | Emit structured step-level traces for comparison | +| Opik integration | Unverified roadmap | Ingest traces and compare evaluation runs | +| Standard model comparison workflow | Planned | Compare quality, cost, and wall-clock time across models | +| Standard agent comparison workflow | Planned | Compare agents or Kilo Code versions on same tasks | +| Custom task-set template | Planned | Build focused regression or capability suites | +| CI regression suite beyond smoke eval | Planned | Run stable subset before release | + +## Inspected smoke-eval workflow + +Current repository workflow runs small smoke evaluation after checking out private benchmark repository. It uses private repository script `./scripts/run_eval.sh`, validates output with `scripts/validate_smoke_test.py`, and uploads selected artifacts. + +| Task | Dataset selection | Expected scope recorded in workflow | +|---|---|---| +| `hello-world` | `hello-world` | Small smoke task | +| `log-summary-date-ranges` | `terminal-bench-sample` with included task name | Small terminal benchmark sample | + +This evidence shows smoke coverage exists. It does not establish public Harbor adapter contract or contributor-ready local CLI. + +## Cloud model-eval-ingest evidence + +Static source inspection found cloud `model-eval-ingest` service for promotion sync. Treat this as current repository-defined surface only. Validate deployed environment and operational behavior separately before making production claims. + +## Proposed evaluation design + +Broader design can use open-source evaluation components if adapter availability is verified during implementation. + +| Component | Roadmap role | Verification needed | +|---|---|---| +| [Harbor](https://harborframework.com) | Evaluation harness and datasets | Confirm supported Kilo adapter and invocation contract | +| [ATIF](https://harborframework.com/docs/agents/trajectory-format) | Structured trajectories | Confirm emitted fields and reasoning-data policy | +| [Opik](https://www.comet.com/docs/opik) | Trace ingestion and analysis | Confirm Harbor integration setup and Kilo adapter support | +| Terminal-Bench or other datasets | Controlled tasks | Confirm versions, licensing, and task selection | + +Potential architecture: + +```text +Evaluation task set + -> controlled trial environment + -> verified Kilo adapter + -> model request + -> result and optional trajectory artifacts + -> smoke validation, aggregate analysis, or trace analysis +``` + +## Proposed comparison dimensions + +| Comparison | Fixed input | Variable | Measures | +|---|---|---|---| +| Model comparison | Kilo Code agent and task set | Model | Completion, cost, and wall-clock time | +| Agent comparison | Model and task set | Agent or Kilo Code version | Completion, cost, and wall-clock time | +| Trace analysis | Evaluation task | Run trajectory | Tool choices, errors, and repeated steps | + +## Command verification requirement + +Do not document `opik harbor run -a kilo`, `kilo --auto`, or `kilo run --auto` as ready-to-run interfaces until adapter and autonomous CLI invocation are verified in relevant repository. Private `kilo-bench` workflow commands are implementation evidence, not public usage guarantees. + +## Future deliverables + +- Verify and document supported autonomous CLI invocation +- Verify Harbor adapter ownership and availability +- Define ATIF export fields and data-handling policy +- Validate Opik ingestion path before publishing commands +- Publish contributor workflow only after local reproduction succeeds +- Expand smoke coverage into stable regression subset where cost and runtime allow + +## References + +- [Harbor Framework Documentation](https://harborframework.com/docs) +- [ATIF Specification](https://github.com/laude-institute/harbor/blob/main/docs/rfcs/0001-trajectory-format.md) +- [Opik Harbor Integration](https://www.comet.com/docs/opik/integrations/harbor) diff --git a/packages/kilo-docs/pages/contributing/features/enterprise-mcp-controls.md b/packages/kilo-docs/pages/contributing/features/enterprise-mcp-controls.md new file mode 100644 index 00000000000..c645e46377a --- /dev/null +++ b/packages/kilo-docs/pages/contributing/features/enterprise-mcp-controls.md @@ -0,0 +1,108 @@ +--- +title: "Enterprise MCP Controls" +description: "Proposal for organization-managed MCP controls" +--- + +# Enterprise MCP Controls + +{% callout type="info" title="Status" %} +Proposal - no matching organization MCP allowlist implementation exists yet. Schema, endpoints, dashboard flows, and client enforcement described here are tentative. +{% /callout %} + +## Overview + +Developers can configure MCP (Model Context Protocol) servers, including marketplace servers and custom servers. Enterprise customers may need organization policy for which MCP servers their developers can use. + +This proposal adds an organization-managed allowlist of approved marketplace MCP servers and dashboard-managed member configuration. It is a design document, not current architecture. + +## MVP requirements + +### Dashboard app + +- Give organization administrators a dashboard section for MCP policy. +- Show marketplace MCP servers and let administrators select approved entries. +- Default policy to disabled. If policy is enabled, start with marketplace MCP servers selected to avoid unexpected disruption. +- Record allowlist changes in audit logs. +- Let organization members configure approved servers in dashboard. + +### Client behavior + +- Keep existing local MCP behavior when organization policy is disabled. +- When organization policy is enabled, replace local MCP configuration with dashboard-managed configuration scoped to organization and member. +- Do not activate or use disallowed local MCP entries. +- If client still detects disallowed local entries while policy is enabled, it may show non-blocking policy feedback. Those entries do not need to appear as activatable MCP options. +- Replace extension marketplace configuration UI with link to dashboard while organization policy is enabled. + +This resolves two distinct cases: local entries rejected by policy need not be activated, while dashboard-managed configuration replacement is proposed behavior only when policy is enabled. + +## System design + +### Current MCP configuration + +{% image src="/docs/img/enterprise-mcp-controls-today.png" alt="Current MCP configuration flow" /%} + +### Proposed policy-enabled configuration + +{% image src="/docs/img/enterprise-mcp-controls-with-ent-control.png" alt="Proposed enterprise MCP controls flow" /%} + +When organization policy is enabled, client pulls dashboard-managed configuration instead of using end-user filesystem definitions. Policy-disabled organizations keep existing local behavior. + +## Tentative schema + +{% callout type="warning" title="Tentative design" %} +Following schema has not shipped. Names, storage layout, encryption approach, and API shape may change during implementation review. +{% /callout %} + +Organization settings could hold allowlist policy: + +```ts +const OrganizationSettings_MCPControls = z.object({ + mcp_controls_enabled: z.boolean().optional(), + mcp_controls_allowed_marketplace_servers: z.string().optional(), +}) +``` + +Dashboard-managed member configuration may require encrypted storage: + +```sql +create table if not exists organization_member_mcp_configs ( + id uuid not null default uuid_generate_v4(), + organization_id uuid not null references organizations(id), + kilo_user_id text not null references kilocode_users(id), + config bytea not null, + created_at timestamptz not null default now() +) +``` + +Payload shape could start with: + +```ts +const OrganizationMemberMCPConfig = z + .object({ mcp_id: z.string(), parameters: z.record(z.string(), z.string()) }) + .array() +``` + +## Tentative dashboard and API surface + +| Surface | Proposed behavior | +|---|---| +| `/organizations/:id/mcp-control` | Let owners manage allowlist and members configure approved MCP servers | +| `GET /api/marketplace/mcps` | Retrieve marketplace MCP list for policy UI | +| Organization settings API | Read and update enabled state and allowlist | +| Member MCP config API | Store encrypted approved MCP configuration | + +These routes and endpoints are placeholders for implementation design. They are not documented as available APIs. + +## Scope and implementation plan + +| Area | Proposed work | +|---|---| +| Backend | Add policy schema, encrypted member config storage, audit logging, and organization/member APIs | +| Dashboard | Add administrator allowlist UI and member configuration UI | +| Client | Fetch policy-enabled configuration, ignore disallowed local entries, and link to dashboard configuration | + +## Future work + +- Organization-provided custom MCP server configurations outside marketplace +- Project-level MCP configurations +- Tool-call audit reports grouped by user, project, and MCP server diff --git a/packages/kilo-docs/pages/contributing/features/index.md b/packages/kilo-docs/pages/contributing/features/index.md new file mode 100644 index 00000000000..4336da762ea --- /dev/null +++ b/packages/kilo-docs/pages/contributing/features/index.md @@ -0,0 +1,17 @@ +--- +title: "Feature Proposals" +description: "Design proposals and roadmaps for Kilo Code features" +--- + +# Feature Proposals + +These pages contain design proposals and roadmaps for features under consideration or implementation. They are planning documents, not current-state architecture references. Each page records its implementation status near the top. + +| Feature | Status | Description | +|---|---|---| +| [Enterprise MCP Controls](/docs/contributing/features/enterprise-mcp-controls) | Proposal | Organization policy controls for MCP server configuration | +| [Onboarding Improvements](/docs/contributing/features/onboarding-improvements) | Partial | Welcome-screen work and proposed onboarding improvements | +| [Agent Observability](/docs/contributing/features/agent-observability) | Partial | Current operational metrics and planned agent-quality signals | +| [Benchmarking](/docs/contributing/features/benchmarking) | Partial | Current smoke-eval evidence and broader evaluation roadmap | + +Use the [proposal template](/docs/contributing/features/template) for new feature designs. diff --git a/packages/kilo-docs/pages/contributing/features/onboarding-improvements.md b/packages/kilo-docs/pages/contributing/features/onboarding-improvements.md new file mode 100644 index 00000000000..2c8b40f14b9 --- /dev/null +++ b/packages/kilo-docs/pages/contributing/features/onboarding-improvements.md @@ -0,0 +1,72 @@ +--- +title: "Onboarding Improvements" +description: "Partial roadmap for onboarding and engagement improvements" +--- + +# Onboarding Improvements + +{% callout type="info" title="Status" %} +Partial - welcome-screen work exists. Starter cards, interactive tutorial, changelog, provider-settings changes, and funnel events below remain roadmap items unless marked current. +{% /callout %} + +## Overview + +New users need a clearer first-run path and better discovery of product features. This roadmap separates current welcome-screen work from proposed onboarding changes. + +## Current implementation + +| Capability | Status | Notes | +|---|---|---| +| Welcome screen | Current | Existing first-run surface provides starting context for new users | + +## Roadmap requirements + +| Capability | Status | Proposed behavior | +|---|---|---| +| Starter prompt cards | Planned | Replace generic prompt with contextual actions and codicon visuals | +| Interactive tutorial | Planned | Guide users through current UI controls and chat input | +| Tutorial completion state | Planned | Avoid showing completed or skipped tutorial repeatedly | +| In-product changelog | Planned | Surface relevant product changes to returning users | +| Kilo provider settings layout | Planned | Put provider setup action beside relevant field and improve discoverability | +| Onboarding analytics | Planned | Track onboarding progress and later product engagement | + +## Proposed welcome-screen extension + +Add starter prompt cards to welcome screen. Each card should populate chat input when selected and use VS Code codicons rather than emoji. + +| Card | Prompt | +|---|---| +| Debug helper | Help me fix a bug in my code | +| Feature builder | Add a new feature to my project | +| Documentation | Generate documentation for this file | +| Code review | Review my current changes by running `git diff` and analyzing output | + +## Proposed tutorial flow + +Earlier design notes referred to Chat, Edit, and Architect modes. Treat those names as historical examples, not current UI requirements. Implementation should target controls available when tutorial is built. + +| Step | Focus | Content | +|---|---|---| +| Welcome | Interface | Explain purpose of short tour | +| Agent or mode selection | Current selector UI | Explain available task behaviors | +| Side panels and MCP | Sidebar | Point to history and MCP configuration | +| Starting chat | Input area | Explain prompts and file references | +| Starter prompts | Welcome actions | Show common first tasks | + +## Proposed analytics + +Events remain roadmap items. Final names and payloads require telemetry review before implementation. + +| Funnel | Candidate events | +|---|---| +| Onboarding | `onboarding.started`, `onboarding.tutorial.completed`, `onboarding.tutorial.skipped`, `onboarding.prompt.selected`, `onboarding.finished` | +| Engagement | `chat.started`, `mode.changed`, `changelog.viewed`, `changelog.dismissed`, `provider.configured`, `file.referenced`, `mcp.configured` | + +## Future work + +- Funnel analysis for onboarding drop-off +- Project-aware first-action recommendations +- Progressive disclosure of advanced features +- Role-specific onboarding flows +- Prompt suggestions based on project code +- Team and repository-specific onboarding diff --git a/packages/kilo-docs/pages/contributing/features/template.md b/packages/kilo-docs/pages/contributing/features/template.md new file mode 100644 index 00000000000..5e18e78d993 --- /dev/null +++ b/packages/kilo-docs/pages/contributing/features/template.md @@ -0,0 +1,73 @@ +--- +title: "Feature Proposal Template" +description: "Template for proposing new feature designs" +--- + +# Feature proposal template + +{% callout type="info" title="Status" %} +Proposal - replace this sentence with concise status detail. Use Partial only when page clearly separates shipped behavior from roadmap. +{% /callout %} + +## Status guidance + +Every proposal page must include visible Status callout near title. Use one lifecycle label: + +| Status | Use when | +|---|---| +| `Proposal` | Design only; no matching implementation exists | +| `Partial` | Some pieces shipped; page separates current behavior from roadmap | +| `Historical` | Page remains for design history; implementation shipped elsewhere or changed materially | +| `Superseded` | Another proposal or implementation reference replaced page | + +For `Partial` pages, add separate current implementation and roadmap tables. Do not mix shipped behavior with tentative schema, endpoints, commands, or rollout claims. + +## Overview + +Describe problem and proposed solution. State intended outcome and boundaries. Keep scope small enough to ship and evaluate. + +## Requirements + +List minimum requirements needed for proposed solution. + +- + +### Non-requirements + +List work intentionally excluded from this proposal. + +- + +## Current implementation + +For `Partial` proposals, list shipped capabilities with evidence scope. Remove this section for design-only proposals. + +| Capability | Status | Notes | +|---|---|---| +| Example capability | Current | Describe verified current behavior | + +## Roadmap + +List tentative behavior separately from current implementation. + +| Capability | Status | Proposed behavior | +|---|---|---| +| Example capability | Planned | Describe intended change | + +## System design + +Document proposed architecture and implementation decisions. Mark tentative schema, endpoints, commands, and vendor integrations as proposed until verified. + +## Scope and implementation + +List work items that can become GitHub issues. + +- + +## Compliance considerations + +Describe relevant security, privacy, data-handling, and SOC 2 considerations. + +## Future work + +List ideas intentionally deferred beyond current proposal. diff --git a/packages/kilo-docs/pages/contributing/index.md b/packages/kilo-docs/pages/contributing/index.md index c8d3c50f174..a7fab46e38e 100644 --- a/packages/kilo-docs/pages/contributing/index.md +++ b/packages/kilo-docs/pages/contributing/index.md @@ -179,7 +179,7 @@ To contribute: ## Engineering Specs -For larger features, we write engineering specs to align on requirements before implementation. Check out the [Architecture](/docs/contributing/architecture) section to see planned features and learn how to contribute specs. +For larger features, we write engineering specs to align on requirements before implementation. Check the [Feature Proposals](/docs/contributing/features) section to see planned features and learn how to contribute specs. ## Documentation Contributions diff --git a/packages/kilo-docs/pages/gateway/models-and-providers.md b/packages/kilo-docs/pages/gateway/models-and-providers.md index fc692771c85..59616f0af74 100644 --- a/packages/kilo-docs/pages/gateway/models-and-providers.md +++ b/packages/kilo-docs/pages/gateway/models-and-providers.md @@ -73,7 +73,7 @@ Provided under the [NVIDIA API Trial Terms of Service](https://assets.ngc.nvidia ## Auto models -Auto virtual models automatically select the best underlying model based on the task type. The selection is controlled by the `x-kilocode-mode` request header. +Auto virtual models select an underlying model using tier-specific routing. Frontier uses the `x-kilocode-mode` request header. Balanced uses the API interface, Free uses deterministic affinity across available candidates, and Small uses account balance. {% callout type="info" title="Underlying models can change" %} The mappings below reflect the current routing. The underlying models behind each `kilo-auto/*` tier are updated server-side as better options become available or as providers change pricing and availability — the tier IDs themselves remain stable. diff --git a/packages/kilo-docs/previous-docs-redirects.js b/packages/kilo-docs/previous-docs-redirects.js index 270e4874ccf..5da3b5d9837 100644 --- a/packages/kilo-docs/previous-docs-redirects.js +++ b/packages/kilo-docs/previous-docs-redirects.js @@ -637,9 +637,87 @@ module.exports = [ basePath: false, permanent: true, }, + { + source: "/docs/contributing/architecture/auto-model-tiers", + destination: "/docs/contributing/architecture/cloud-platform#kilo-gateway", + basePath: false, + permanent: true, + }, + { + source: "/docs/contributing/architecture/mcp-oauth-authorization", + destination: "/docs/contributing/architecture/cli-runtime#remote-mcp-oauth", + basePath: false, + permanent: true, + }, + { + source: "/docs/contributing/architecture/organization-modes-library", + destination: "/docs/contributing/architecture/cli-runtime#config-precedence", + basePath: false, + permanent: true, + }, + { + source: "/docs/contributing/architecture/track-repo-url", + destination: "/docs/contributing/architecture/cloud-platform#kilo-gateway", + basePath: false, + permanent: true, + }, + { + source: "/docs/contributing/architecture/voice-transcription", + destination: "/docs/contributing/architecture/vscode-extension#bundled-resources", + basePath: false, + permanent: true, + }, + { + source: "/docs/contributing/architecture/per-message-feedback", + destination: "/docs/contributing/architecture/cloud-security#privacy-logging-and-retention", + basePath: false, + permanent: true, + }, + { + source: "/docs/contributing/architecture/security-agent", + destination: "/docs/contributing/architecture/cloud-platform#security-agent", + basePath: false, + permanent: true, + }, { source: "/docs/contributing/architecture/onboarding-engagement-improvements", - destination: "/docs/contributing/architecture/onboarding-improvements", + destination: "/docs/contributing/features/onboarding-improvements", + basePath: false, + permanent: true, + }, + { + source: "/docs/contributing/architecture/features", + destination: "/docs/contributing/features", + basePath: false, + permanent: true, + }, + { + source: "/docs/contributing/architecture/enterprise-mcp-controls", + destination: "/docs/contributing/features/enterprise-mcp-controls", + basePath: false, + permanent: true, + }, + { + source: "/docs/contributing/architecture/onboarding-improvements", + destination: "/docs/contributing/features/onboarding-improvements", + basePath: false, + permanent: true, + }, + { + source: "/docs/contributing/architecture/agent-observability", + destination: "/docs/contributing/features/agent-observability", + basePath: false, + permanent: true, + }, + { + source: "/docs/contributing/architecture/benchmarking", + destination: "/docs/contributing/features/benchmarking", + basePath: false, + permanent: true, + }, + { + source: "/docs/contributing/architecture/feature-template", + destination: "/docs/contributing/features/template", basePath: false, permanent: true, }, @@ -821,7 +899,7 @@ module.exports = [ }, { source: "/docs/contributing/architecture/vercel-ai-gateway", - destination: "/docs/contributing/architecture/features", + destination: "/docs/contributing/features", basePath: false, permanent: true, }, diff --git a/packages/kilo-docs/public/img/kiloclaw/kiloclaw-architecture.png b/packages/kilo-docs/public/img/kiloclaw/kiloclaw-architecture.png deleted file mode 100644 index 30e085f9cb0..00000000000 Binary files a/packages/kilo-docs/public/img/kiloclaw/kiloclaw-architecture.png and /dev/null differ diff --git a/packages/kilo-docs/public/img/organization-modes-library-1.png b/packages/kilo-docs/public/img/organization-modes-library-1.png deleted file mode 100644 index 083e35a9133..00000000000 Binary files a/packages/kilo-docs/public/img/organization-modes-library-1.png and /dev/null differ diff --git a/packages/kilo-docs/public/img/organization-modes-library-2.png b/packages/kilo-docs/public/img/organization-modes-library-2.png deleted file mode 100644 index ac7dc6b64a9..00000000000 Binary files a/packages/kilo-docs/public/img/organization-modes-library-2.png and /dev/null differ diff --git a/packages/kilo-docs/public/img/track-repo-url-system-design.png b/packages/kilo-docs/public/img/track-repo-url-system-design.png deleted file mode 100644 index 9db8a4c27c7..00000000000 Binary files a/packages/kilo-docs/public/img/track-repo-url-system-design.png and /dev/null differ diff --git a/packages/kilo-docs/public/img/voice-transcription-architecture.png b/packages/kilo-docs/public/img/voice-transcription-architecture.png deleted file mode 100644 index 51d32d16dc2..00000000000 Binary files a/packages/kilo-docs/public/img/voice-transcription-architecture.png and /dev/null differ