opensource/kilocode
3
0
Fork 0
mirror of https://github.com/Kilo-Org/kilocode.git synced 2026-09-21 14:07:20 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/main' into resolve-terminal-bench-kilo

Browse Source 
# Conflicts:
#	packages/sdk/js/src/v2/gen/types.gen.ts
This commit is contained in:
Josh Lambert
2026-06-05 16:51:49 -04:00
parent 210f587826 9a53a602d4
commit 706aa5fba6
637 changed files with 26676 additions and 6796 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/brain-circuit-data-disclosure.md
-6
View File
@@ -1,6 +0,0 @@
---
"kilo-code": patch
"@kilocode/kilo-ui": patch
---
Use a brain circuit icon for free-model data collection disclosures.
.changeset/calm-icons-fetch.md
+5
View File
@@ -0,0 +1,5 @@
---
"@kilocode/cli": patch
---
Prevent icon images fetched from the web from causing provider request errors.
.changeset/calm-marketplace-skills-install.md
-5
View File
@@ -1,5 +0,0 @@
---
"kilo-code": patch
---
Make Marketplace skill installation resilient to missing project directories and overlapping install attempts.
.changeset/clean-mcp-json.md
+5
View File
@@ -0,0 +1,5 @@
---
"@kilocode/cli": patch
---
Write strict JSON when adding MCP servers to `kilo.json` configuration files.
.changeset/console-diff-refresh.md
-5
View File
@@ -1,5 +0,0 @@
---
"@kilocode/cli": patch
---
Keep Kilo Console terminals and worktree changes visible while refreshing diffs.
.changeset/console-favicon.md
-5
View File
@@ -1,5 +0,0 @@
---
"@kilocode/cli": patch
---
Use the updated favicon in Kilo Console.
.changeset/fresh-compaction-order.md
-6
View File
@@ -1,6 +0,0 @@
---
"@kilocode/cli": patch
"kilo-code": patch
---
Keep post-compaction tool calls and follow-up messages ordered after the compaction summary in the CLI and VS Code transcript.
.changeset/ignore-control-scroll-intent.md
+6
View File
@@ -0,0 +1,6 @@
---
"@kilocode/kilo-ui": patch
"kilo-code": patch
---
Keep chat auto-scroll active when interacting with question answers and other controls.
.changeset/observe-chat-resize.md
+6
View File
@@ -0,0 +1,6 @@
---
"@kilocode/kilo-ui": patch
"kilo-code": patch
---
Keep chat pinned to the latest output when the visible message area resizes without overriding an intentional scroll position.
.changeset/quiet-cloud-session-timeouts.md
-7
View File
@@ -1,7 +0,0 @@
---
"@kilocode/cli": patch
"@kilocode/kilo-gateway": patch
"kilo-code": patch
---
Restore Cloud Agent transcripts in VS Code session previews and stop cloud session previews or continuation from loading indefinitely when a request stalls.
.changeset/quiet-session-export.md
+5
View File
@@ -0,0 +1,5 @@
---
"@kilocode/cli": patch
---
Temporarily disable free-model session and Git workspace data export.
.changeset/shell-permission-descriptions.md
-5
View File
@@ -1,5 +0,0 @@
---
"kilo-code": patch
---
Show shell command descriptions in permission approval prompts.
.changeset/stable-models-snapshot.md
+5
View File
@@ -0,0 +1,5 @@
---
"@kilocode/cli": patch
---
Fail publication builds when the bundled models snapshot cannot be downloaded or validated, and load the snapshot as JSON data in compiled binaries.
.changeset/stable-tool-scroll.md
-5
View File
@@ -1,5 +0,0 @@
---
"kilo-code": patch
---
Keep chat auto-scroll stable while edit, write, and patch tools hand off between assistant steps.
.changeset/stable-working-indicator.md
+5
View File
@@ -0,0 +1,5 @@
---
"kilo-code": patch
---
Reduce chat layout movement when live output finishes and session actions appear.
.changeset/steady-review-drafts.md
-5
View File
@@ -1,5 +0,0 @@
---
"kilo-code": patch
---
Preserve unfinished inline review comments while diffs refresh.
.changeset/steady-session-forks.md
-5
View File
@@ -1,5 +0,0 @@
---
"@kilocode/cli": patch
---
Restore full-session forks in Agent Manager after the HTTP API migration.
.changeset/steady-sidebar-reload.md
+5
View File
@@ -0,0 +1,5 @@
---
"kilo-code": patch
---
Keep the Explorer and other primary sidebar views open when VS Code reloads while Kilo Code is hidden.
.changeset/user-driven-auto-scroll.md
+6
View File
@@ -0,0 +1,6 @@
---
"@kilocode/kilo-ui": patch
"kilo-code": patch
---
Keep chat auto-scroll following after programmatic or layout-driven scroll position changes.
.changeset/vscode-lazy-historical-tool-details.md
-5
View File
@@ -1,5 +0,0 @@
---
"kilo-code": patch
---
Speed up VS Code session switching for long transcripts by lazily mounting collapsed historical tool details, sharing timeline hover infrastructure across activity bars, omitting transcript metadata that the webview does not use, and avoiding shimmer markup for inactive historical labels.
.github/workflows/codeql-kotlin.yml
+62
View File
@@ -0,0 +1,62 @@
# kilocode_change - new file
name: "CodeQL Kotlin"
on:
push:
branches: ["main"]
paths:
- "packages/kilo-jetbrains/**"
- ".github/workflows/codeql-kotlin.yml"
pull_request:
branches: ["main"]
paths:
- "packages/kilo-jetbrains/**"
- ".github/workflows/codeql-kotlin.yml"
schedule:
- cron: "29 10 * * 5"
workflow_dispatch:
jobs:
analyze:
name: Analyze (java-kotlin)
runs-on: ubuntu-latest
permissions:
security-events: write
packages: read
actions: read
contents: read
steps:
- name: Checkout repository
uses: actions/checkout@v6
- name: Setup Bun
uses: ./.github/actions/setup-bun
- name: Setup Java
uses: actions/setup-java@v4
with:
distribution: temurin
java-version: "21"
- name: Setup Gradle
uses: gradle/actions/setup-gradle@v4
with:
cache-read-only: ${{ github.ref != 'refs/heads/main' }}
- name: Initialize CodeQL
uses: github/codeql-action/init@v4
with:
languages: java-kotlin
build-mode: manual
config-file: ./.github/codeql/codeql-config.yml
- name: Build Java/Kotlin
shell: bash
run: ./gradlew typecheck --rerun-tasks --no-build-cache
working-directory: packages/kilo-jetbrains
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@v4
with:
category: "/language:java-kotlin"
.github/workflows/codeql.yml
+25 -61
View File
@@ -14,11 +14,11 @@ name: "CodeQL Advanced"
on:
push:
branches: [ "main" ]
branches: ["main"]
pull_request:
branches: [ "main" ]
branches: ["main"]
schedule:
- cron: '29 10 * * 5'
- cron: "29 10 * * 5"
workflow_dispatch:
jobs:
@@ -45,12 +45,10 @@ jobs:
fail-fast: false
matrix:
include:
- language: actions
build-mode: none
- language: java-kotlin
build-mode: manual
- language: javascript-typescript
build-mode: none
- language: actions
build-mode: none
- language: javascript-typescript
build-mode: none
# CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'rust', 'swift'
# Use `c-cpp` to analyze code written in C, C++ or both
# Use 'java-kotlin' to analyze code written in Java, Kotlin or both
@@ -60,58 +58,24 @@ jobs:
# If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
# your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
steps:
- name: Checkout repository
uses: actions/checkout@v6
- name: Checkout repository
uses: actions/checkout@v6
# Add any setup steps before running the `github/codeql-action/init` action.
# This includes steps like installing compilers or runtimes (`actions/setup-node`
# or others). This is typically only required for manual builds.
# - name: Setup runtime (example)
# uses: actions/setup-example@v1
- name: Setup Bun
if: matrix.language == 'java-kotlin'
uses: ./.github/actions/setup-bun
# Initializes the CodeQL tools for scanning.
- name: Initialize CodeQL
uses: github/codeql-action/init@v4
with:
languages: ${{ matrix.language }}
build-mode: ${{ matrix.build-mode }}
config-file: ./.github/codeql/codeql-config.yml
# If you wish to specify custom queries, you can do so here or in a config file.
# By default, queries listed here will override any specified in a config file.
# Prefix the list here with "+" to use these queries and those in the config file.
- name: Setup Java
if: matrix.language == 'java-kotlin'
uses: actions/setup-java@v4
with:
distribution: temurin
java-version: "21"
# For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
# queries: security-extended,security-and-quality
- name: Setup Gradle
if: matrix.language == 'java-kotlin'
uses: gradle/actions/setup-gradle@v4
with:
cache-read-only: ${{ github.ref != 'refs/heads/main' }}
# Initializes the CodeQL tools for scanning.
- name: Initialize CodeQL
uses: github/codeql-action/init@v4
with:
languages: ${{ matrix.language }}
build-mode: ${{ matrix.build-mode }}
config-file: ./.github/codeql/codeql-config.yml
# If you wish to specify custom queries, you can do so here or in a config file.
# By default, queries listed here will override any specified in a config file.
# Prefix the list here with "+" to use these queries and those in the config file.
# For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
# queries: security-extended,security-and-quality
# If the analyze step fails for one of the languages you are analyzing with
# "We were unable to automatically build your code", modify the matrix above
# to set the build mode to "manual" for that language. Then modify this step
# to build your code.
# ℹ️ Command-line programs to run using the OS shell.
# 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
- name: Build Java/Kotlin
if: matrix.language == 'java-kotlin'
shell: bash
run: ./gradlew typecheck
working-directory: packages/kilo-jetbrains
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@v4
with:
category: "/language:${{matrix.language}}"
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@v4
with:
category: "/language:${{matrix.language}}"
.github/workflows/publish.yml
+182 -1
View File
@@ -118,8 +118,187 @@ jobs:
outputs:
version: ${{ needs.version.outputs.version }}
build-vscode:
# kilocode_change start - execute supported Unix CLI binaries before packaging VSIX artifacts
validate-cli-unix:
name: Validate CLI (${{ matrix.target }})
needs: build-cli
runs-on: ${{ matrix.runner }}
timeout-minutes: 15
strategy:
fail-fast: false
matrix:
include:
- target: darwin-arm64
runner: macos-15
uname: arm64
package: "@kilocode/cli-darwin-arm64"
mode: host
- target: darwin-x64
runner: macos-13
uname: x86_64
package: "@kilocode/cli-darwin-x64"
mode: host
- target: linux-arm64
runner: ubuntu-24.04-arm
uname: aarch64
package: "@kilocode/cli-linux-arm64"
mode: host
- target: linux-x64
runner: ubuntu-24.04
uname: x86_64
package: "@kilocode/cli-linux-x64"
mode: host
- target: alpine-arm64
runner: ubuntu-24.04-arm
uname: aarch64
package: "@kilocode/cli-linux-arm64-musl"
mode: alpine
platform: linux/arm64
- target: alpine-x64
runner: ubuntu-24.04
uname: x86_64
package: "@kilocode/cli-linux-x64-musl"
mode: alpine
platform: linux/amd64
steps:
- uses: actions/download-artifact@v8
with:
name: kilo-cli.tar.zst
path: /tmp
skip-decompress: true
- name: Unpack CLI dist
run: |
mkdir -p dist
tar --zstd -xf /tmp/kilo-cli.tar.zst -C dist
- name: Run CLI smoke test
run: |
test "$(uname -m)" = "${{ matrix.uname }}"
smoke_host() {
binary="$1"
"$binary" --version
root="$(mktemp -d)"
trap 'rm -rf "$root"' RETURN
(
unset KILO_MODELS_PATH KILO_MODELS_URL KILO_CONFIG KILO_CONFIG_DIR
export XDG_DATA_HOME="$root/data"
export XDG_CACHE_HOME="$root/cache"
export XDG_CONFIG_HOME="$root/config"
export XDG_STATE_HOME="$root/state"
export KILO_DISABLE_MODELS_FETCH=1
export KILO_DISABLE_PROJECT_CONFIG=1
export KILO_CONFIG_CONTENT='{"enabled_providers":["anthropic"]}'
export ANTHROPIC_API_KEY=dummy
"$binary" --pure models anthropic | grep -q '^anthropic/'
)
}
if [ "${{ matrix.mode }}" = "host" ]; then
smoke_host "./dist/${{ matrix.package }}/bin/kilo"
exit 0
fi
docker run --rm \
--platform "${{ matrix.platform }}" \
-v "$PWD/dist:/dist:ro" \
-e PACKAGE="${{ matrix.package }}" \
alpine:3.22 \
sh -c '
set -eu
# kilocode_change start - Bun musl binaries link against libstdc++ and libgcc_s
# (GCC C++ runtime). Alpine does not ship these by default; they are available
# as optional packages and must be installed for any Bun-compiled musl binary to run.
apk add --no-cache libstdc++ libgcc
# kilocode_change end
binary="/dist/$PACKAGE/bin/kilo"
"$binary" --version
root="$(mktemp -d)"
trap '\''rm -rf "$root"'\'' EXIT
unset KILO_MODELS_PATH KILO_MODELS_URL KILO_CONFIG KILO_CONFIG_DIR
export XDG_DATA_HOME="$root/data"
export XDG_CACHE_HOME="$root/cache"
export XDG_CONFIG_HOME="$root/config"
export XDG_STATE_HOME="$root/state"
export KILO_DISABLE_MODELS_FETCH=1
export KILO_DISABLE_PROJECT_CONFIG=1
export KILO_CONFIG_CONTENT='\''{"enabled_providers":["anthropic"]}'\''
export ANTHROPIC_API_KEY=dummy
"$binary" --pure models anthropic | grep -q "^anthropic/"
'
validate-cli-windows:
name: Validate CLI (windows-${{ matrix.arch }})
needs: build-cli
runs-on: ${{ matrix.runner }}
timeout-minutes: 20
strategy:
fail-fast: false
matrix:
include:
- arch: arm64
runner: windows-11-arm
package: "@kilocode/cli-windows-arm64"
- arch: x64
runner: windows-2025
package: "@kilocode/cli-windows-x64"
steps:
- uses: actions/download-artifact@v8
with:
name: kilo-cli.tar.zst
path: ${{ runner.temp }}
skip-decompress: true
- name: Install zstd
shell: pwsh
run: |
if (-not (Get-Command zstd -ErrorAction SilentlyContinue)) {
choco install zstandard -y --no-progress
}
- name: Unpack CLI dist
shell: pwsh
run: |
New-Item -ItemType Directory -Force -Path dist | Out-Null
zstd -d --stdout "$env:RUNNER_TEMP\kilo-cli.tar.zst" | tar -xf - -C dist
- name: Run CLI smoke test
shell: pwsh
run: |
$package = "${{ matrix.package }}".Replace("/", "\")
$binary = ".\dist\$package\bin\kilo.exe"
& $binary --version
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
$root = Join-Path $env:RUNNER_TEMP ([guid]::NewGuid().ToString())
New-Item -ItemType Directory -Force -Path $root | Out-Null
try {
foreach ($name in "KILO_MODELS_PATH", "KILO_MODELS_URL", "KILO_CONFIG", "KILO_CONFIG_DIR") {
Remove-Item "Env:$name" -ErrorAction SilentlyContinue
}
$env:XDG_DATA_HOME = Join-Path $root "data"
$env:XDG_CACHE_HOME = Join-Path $root "cache"
$env:XDG_CONFIG_HOME = Join-Path $root "config"
$env:XDG_STATE_HOME = Join-Path $root "state"
$env:KILO_DISABLE_MODELS_FETCH = "1"
$env:KILO_DISABLE_PROJECT_CONFIG = "1"
$env:KILO_CONFIG_CONTENT = '{"enabled_providers":["anthropic"]}'
$env:ANTHROPIC_API_KEY = "dummy"
$output = & $binary --pure models anthropic
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
if (-not ($output -match "(?m)^anthropic/")) {
throw "Compiled Windows binary did not list Anthropic models from the sidecar snapshot"
}
} finally {
Remove-Item -Recurse -Force $root -ErrorAction SilentlyContinue
}
# kilocode_change end
build-vscode:
needs:
- build-cli
- validate-cli-unix
- validate-cli-windows
runs-on: blacksmith-4vcpu-ubuntu-2404
if: github.repository == 'Kilo-Org/kilocode'
steps:
@@ -181,6 +360,8 @@ jobs:
- version
- build-cli
- build-vscode
- validate-cli-unix # kilocode_change
- validate-cli-windows # kilocode_change
- smoke-test
runs-on: ubuntu-24.04
steps:
.kilo/plans/1780256109130-stellar-forest.md
+109
View File
@@ -0,0 +1,109 @@
# Plan: JetBrains Feedback & Support Button
## Goal
Add the VS Code empty-state `Feedback & Support` affordance to the JetBrains plugin, including a non-modal popup with the same three destinations:
- GitHub issues: `https://github.com/Kilo-Org/kilocode/issues/new/choose`
- Discord: `https://kilo.ai/discord`
- Customer support: `https://kilo.ai/support`
The popup must hide when clicking outside or pressing Escape.
## Findings
- The JetBrains empty state is `packages/kilo-jetbrains/frontend/src/main/kotlin/ai/kilocode/client/session/ui/EmptySessionPanel.kt`.
- It already renders the logo, welcome copy, recents, and `Show History`; this is the right place to add the button.
- The VS Code implementation is:
- Button: `packages/kilo-vscode/webview-ui/src/components/chat/MessageList.tsx`
- Popup content: `packages/kilo-vscode/webview-ui/src/components/chat/FeedbackDialog.tsx`
- Styling: `packages/kilo-vscode/webview-ui/src/styles/welcome.css`
- Local IntelliJ API source is available at `$INTELLIJ_REPO=/Users/kirillk/products/intellij-community`.
- IntelliJ popup API confirmed in local source:
- `JBPopupFactory.getInstance().createComponentPopupBuilder(content, focusComponent)`
- `setModalContext(false)` for non-modal context
- `setRequestFocus(false)` / `setFocusable(false)` if we want the popup not to steal focus
- `setCancelOnClickOutside(true)` for outside-click dismissal
- `setCancelKeyEnabled(true)` for Escape dismissal
- `setCancelOnWindowDeactivation(true)` and `setCancelOnOtherWindowOpen(true)` are available and appropriate for cleanup
- IntelliJ platform icons found in `AllIcons`:
- Feedback button: `AllIcons.Ide.Feedback`
- GitHub action: `AllIcons.Vcs.Vendors.Github`
- Support/help action: `AllIcons.Actions.Help` or `AllIcons.General.ContextHelp`
- Discord: no platform icon found. Add a Discord icon by borrowing the existing VS Code/kilo-ui Discord SVG artwork and adapting it into the JetBrains plugin resources with IntelliJ-compatible SVG colors and dark variant if needed.
## Implementation Steps
1. Add localized JetBrains bundle keys.
- Add base English strings to `frontend/src/main/resources/messages/KiloBundle.properties`:
- `feedback.button=Feedback & Support`
- `feedback.dialog.message=We'd love to hear your feedback or help with any issues you're experiencing.`
- `feedback.dialog.github=Report an issue on GitHub`
- `feedback.dialog.discord=Join our Discord community`
- `feedback.dialog.support=Customer Support`
- Reuse existing cancel text if present; otherwise add `common.cancel=Cancel` only if needed.
- Add matching keys to localized `KiloBundle_*.properties` files. If accurate translations are not already available from the VS Code i18n files, copy the VS Code translations for matching locales where practical and leave English fallback only if the JetBrains bundle mechanism supports it cleanly.
2. Extend `EmptySessionPanel` UI.
- Add a new retained `FeedbackButton`, styled to match VS Code conceptually:
- feedback icon + `Feedback & Support` text
- dashed link-colored border
- transparent background
- hand cursor
- hover state fills with link color and flips foreground/background for contrast
- Use IntelliJ theme APIs instead of raw colors:
- link color: `JBUI.CurrentTheme.Link.Foreground.ENABLED`
- hover link color: `JBUI.CurrentTheme.Link.Foreground.HOVERED` if useful
- editor/panel background from existing session style or `UiStyle.Colors.editorBackground()` / component background
- spacing via `UiStyle.Gap` / `JBUI.Borders`
- rounded arc via `UiStyle.Arc.component()` or `JBUI.getInt("Button.arc", 6)` at paint time
- Add the feedback button below the existing `Show History` button in the empty-state south area, keeping the current centered layout.
- Keep Swing mutations on EDT and preserve retained-component behavior.
3. Implement the feedback popup in frontend Swing code.
- Add a small popup builder method/class inside `EmptySessionPanel.kt` or a new nearby UI file if the file would become too large.
- Content should mirror VS Code:
- Kilo logo at top using existing `/icons/kilo-content.svg`
- message text
- three action buttons/rows for GitHub, Discord, and Customer Support
- every action should have an icon: `AllIcons.Vcs.Vendors.Github` for GitHub, the borrowed Discord SVG for Discord, and `AllIcons.Actions.Help` or `AllIcons.General.ContextHelp` for Customer Support
- optional Cancel button if it fits the JetBrains UX; Escape/outside click already dismisses
- Add the Discord icon asset under `frontend/src/main/resources/icons/` using the plugin's existing icon naming pattern, for example `discord.svg` and `discord_dark.svg` if the borrowed asset needs separate theme variants.
- Load the Discord icon with `IconLoader.getIcon("/icons/discord.svg", EmptySessionPanel::class.java)` or a small Kilo-owned icon object if multiple call sites need it.
- Use `BrowserUtil.browse(url)` to open links.
- Close the popup after opening a URL.
- Use `JBPopupFactory.createComponentPopupBuilder(content, null)` and configure:
- `.setModalContext(false)`
- `.setRequestFocus(false)`
- `.setFocusable(false)` unless keyboard tabbing inside popup is desired; if buttons need keyboard focus, use `.setFocusable(true)` with `.setRequestFocus(false)`
- `.setCancelOnClickOutside(true)`
- `.setCancelKeyEnabled(true)`
- `.setCancelOnWindowDeactivation(true)`
- `.setCancelOnOtherWindowOpen(true)`
- `.setResizable(false)`
- `.setMovable(false)`
- Show with `popup.showUnderneathOf(feedbackButton)`.
4. Add test coverage in `EmptySessionPanelTest.kt`.
- Assert feedback button text uses `KiloBundle.message("feedback.button")`.
- Assert feedback button has hand cursor and visible border semantics.
- Add an injectable browse callback or popup action callback only if needed for testing without launching browsers; keep it minimal and avoid production-only test hooks if component traversal can exercise enough behavior.
- Add a test that clicking the feedback button creates/shows popup content, if feasible in `BasePlatformTestCase`; otherwise test the retained popup content builder/action rows directly through package-internal methods.
- Assert the three action labels exist and URL callbacks map to the same URLs as VS Code.
- Assert the Discord action has an icon, so the plan cannot regress to a text-only Discord row.
5. Add release note.
- This is user-facing for the JetBrains plugin, so add a patch changeset under `.changeset/` unless the repo has a JetBrains-specific release-note mechanism that supersedes changesets.
- Suggested text: `Add Feedback & Support to the JetBrains empty session screen.`
6. Verify.
- Run the focused frontend/JetBrains tests first, preferably from `packages/kilo-jetbrains/`:
- `./gradlew :frontend:test --tests "ai.kilocode.client.session.ui.EmptySessionPanelTest"`
- Run JetBrains typecheck from `packages/kilo-jetbrains/`:
- `bun run typecheck` or `./gradlew typecheck`
- If touching only frontend UI and tests pass, no backend/SDK generation is needed.
## Notes
- Do not add Kotlin UI DSL, Compose, or JCEF.
- Do not modify shared opencode files; this work is entirely under `packages/kilo-jetbrains/` plus a changeset.
- Prefer platform icons where available, but explicitly borrow/add the Discord icon because `AllIcons` does not provide one and the popup should match the VS Code button set visually.
.kilo/skills/release-jetbrains/SKILL.md
+133
View File
@@ -0,0 +1,133 @@
---
name: release-jetbrains
description: Use when releasing the Kilo JetBrains plugin -- resolve a version ("next rc" or explicit), run the prepare workflow, edit and commit a filtered human-readable changelog on the release PR, then watch publish to completion.
---
# JetBrains Release
Use this skill when releasing the Kilo JetBrains plugin.
This skill drives the existing JetBrains release workflows. It must not move, delete, or recreate JetBrains release tags. It must always confirm the resolved version with the user before dispatching the prepare workflow because the prepare workflow creates an immutable `jetbrains/v<version>` tag.
## Preconditions
- Run from the repository root.
- `gh` must be authenticated for `Kilo-Org/kilocode` with permission to dispatch workflows, read PRs, and write contents. Merge permission is only required if the user asks the skill to merge the release PR automatically.
- Check auth with `gh auth status`. For GitHub CLI OAuth, refresh common release scopes with `gh auth refresh -s repo -s workflow`; `repo` covers private-repo contents and PR operations, and `workflow` allows workflow dispatch. If using a fine-grained token instead, grant repository permissions for Actions read/write, Contents read/write, and Pull requests read/write. Merging still requires normal repository collaborator permission or a token/user allowed by branch protection.
- Reference `packages/kilo-jetbrains/RELEASING.md` for manual recovery rules.
- Do not locally check out the generated release branch. The helper scripts update the release branch through GitHub to avoid disturbing the current worktree.
## Version Resolution
Resolve the user's version request:
```bash
bun .kilo/skills/release-jetbrains/script/resolve-version.ts --spec "next rc"
```
Accepted specs:
| Spec | Meaning |
|---|---|
| `next rc` | If the latest JetBrains tag is an RC, increment its `rc.n`; otherwise start the next patch RC at `rc.1`. |
| `next stable` | If the latest JetBrains tag is an RC, use its base version; otherwise use the next patch stable. |
| `x.y.z-rc.n` | Explicit RC release. |
| `x.y.z` | Explicit stable release. |
Show the resolved `version`, `kind`, and default `fromTagDefault` to the user and ask for confirmation before continuing.
## Prepare Workflow
After confirmation, dispatch and watch the prepare workflow:
```bash
bun .kilo/skills/release-jetbrains/script/dispatch-prepare.ts --kind rc --version 7.0.1-rc.7
```
Pass a generous Bash timeout, such as `1800000` ms, because the script blocks on `gh run watch --exit-status`. If the shell times out but the workflow is still running, re-attach with:
```bash
bun .kilo/skills/release-jetbrains/script/dispatch-prepare.ts --kind rc --version 7.0.1-rc.7 --run-id <run-id>
```
The script prints `prNumber`, `prUrl`, `runUrl`, and `branch` on success.
## Changelog Draft
Create a changelog draft after the prepare PR exists:
1. Read the PR body with `gh pr view <pr> --json body`.
2. Extract `JetBrains-From-Tag`, `JetBrains-Tag`, and `## Generated Notes`.
3. Use the release range and path filter as the primary relevance signal:
```bash
git log --oneline <from-tag>..<tag> -- packages/opencode packages/kilo-jetbrains
```
Keep JetBrains and CLI/runtime changes. Drop unrelated VS Code, docs, gateway, telemetry, i18n, desktop, and webview-only changes unless they affect the CLI bundled into the JetBrains plugin.
Rewrite terse commit or PR titles into user-facing bullets grouped under `### Added`, `### Fixed`, and `### Changed`. Keep the exact generated header format:
```markdown
## [<version>] - <date>
```
Write the editable draft to:
```text
packages/kilo-jetbrains/build/release/<version>-changelog.md
```
Include source context in an HTML comment so it is easy to edit but not shipped:
```markdown
<!-- CONTEXT - deleted automatically on commit. Source PRs in range:
- #1234 feat(jetbrains): ... https://github.com/Kilo-Org/kilocode/pull/1234
- #1235 fix(cli): ... https://github.com/Kilo-Org/kilocode/pull/1235
-->
```
Ask the user to edit the file and confirm when done.
## Commit Changelog
After the user confirms the draft is ready, strip the `<!-- CONTEXT ... -->` block into a temporary cleaned file, then commit the cleaned section to the release branch:
```bash
bun .kilo/skills/release-jetbrains/script/update-changelog.ts --version 7.0.1-rc.7 --file /path/to/clean-section.md
```
The script updates `packages/kilo-jetbrains/CHANGELOG.md` on `jetbrains/release/v<version>` through the GitHub contents API and commits with:
```text
docs(jetbrains): edit changelog for v<version>
```
## Approve And Publish
Ask the user to approve the release changelog and metadata. By default, have the user merge the release PR manually in GitHub, then watch the publish workflow:
```bash
bun .kilo/skills/release-jetbrains/script/watch-publish.ts --pr <number> --version 7.0.1-rc.7
```
Only merge automatically when the user explicitly asks for it and `gh` has merge permission:
```bash
bun .kilo/skills/release-jetbrains/script/watch-publish.ts --pr <number> --version 7.0.1-rc.7 --merge
```
Pass a generous Bash timeout, such as `1800000` ms. If the shell times out, re-attach with:
```bash
bun .kilo/skills/release-jetbrains/script/watch-publish.ts --pr <number> --version 7.0.1-rc.7 --run-id <run-id>
```
Report the Marketplace channel and GitHub Release URL. RC versions publish to the `eap` channel; stable versions publish to the default Marketplace channel.
## Recovery
- If prepare created the tag but failed before creating a PR, rerun prepare for the same version. The existing workflow reuses the tag if it points to the same commit.
- If a tag points to an unexpected SHA, stop and inspect manually. Do not move or delete release tags casually.
- If publish fails after merge, rerun the failed workflow only if Marketplace did not already accept the version.
- If Marketplace succeeds but GitHub Release upload fails, manually create or edit the GitHub Release for `jetbrains/v<version>` using the reviewed changelog.
.kilo/skills/release-jetbrains/script/dispatch-prepare.ts
+73
View File
@@ -0,0 +1,73 @@
#!/usr/bin/env bun
import { $ } from "bun"
import { parseArgs } from "util"
const repo = process.env.GH_REPO ?? process.env.GITHUB_REPOSITORY ?? "Kilo-Org/kilocode"
const workflow = "prepare-jetbrains-release.yml"
const { values } = parseArgs({
args: Bun.argv.slice(2),
options: {
kind: { type: "string" },
version: { type: "string" },
"from-tag": { type: "string" },
"run-id": { type: "string" },
help: { type: "boolean", short: "h", default: false },
},
})
if (values.help) {
console.log(`Usage: bun .kilo/skills/release-jetbrains/script/dispatch-prepare.ts --kind <rc|stable> --version <version> [--from-tag <tag>] [--run-id <id>]`)
process.exit(0)
}
const kind = values.kind
const ver = values.version
const branch = `jetbrains/release/v${ver}`
if (kind !== "rc" && kind !== "stable") throw new Error("--kind must be rc or stable")
if (!ver) throw new Error("--version is required")
const id = values["run-id"] ?? (await dispatch())
const url = `https://github.com/${repo}/actions/runs/${id}`
console.log(`prepareRunId=${id}`)
console.log(`runUrl=${url}`)
await $`gh run watch ${id} --repo ${repo} --exit-status`
const pr = (await $`gh pr view ${branch} --repo ${repo} --json number,url`.json()) as { number: number; url: string }
console.log(
JSON.stringify(
{
prNumber: pr.number,
prUrl: pr.url,
runUrl: url,
branch,
},
null,
2,
),
)
async function dispatch() {
const before = new Set((await runs()).map((run) => run.databaseId))
const args = ["workflow", "run", workflow, "--repo", repo, "-f", `kind=${kind}`, "-f", `version=${ver}`]
if (values["from-tag"]) args.push("-f", `from_tag=${values["from-tag"]}`)
await $`gh ${args}`
for (const _ of Array.from({ length: 60 })) {
const run = (await runs()).find((item) => !before.has(item.databaseId))
if (run) return String(run.databaseId)
await Bun.sleep(1000)
}
throw new Error(`No new ${workflow} run appeared after dispatch`)
}
async function runs() {
return (await $`gh run list --repo ${repo} --workflow ${workflow} --event workflow_dispatch --json databaseId,createdAt,status --limit 100`.json()) as {
databaseId: number
createdAt: string
status: string
}[]
}
.kilo/skills/release-jetbrains/script/resolve-version.ts
+107
View File
@@ -0,0 +1,107 @@
#!/usr/bin/env bun
import { $ } from "bun"
import semver from "semver"
import { parseArgs } from "util"
const { values } = parseArgs({
args: Bun.argv.slice(2),
options: {
spec: { type: "string" },
help: { type: "boolean", short: "h", default: false },
},
})
if (values.help) {
console.log(`Usage: bun .kilo/skills/release-jetbrains/script/resolve-version.ts --spec <next rc|next stable|version>`)
process.exit(0)
}
const spec = values.spec?.trim().toLowerCase()
if (!spec) throw new Error("--spec is required")
await $`git fetch origin main --tags`.quiet()
const tags = await list()
const hit = explicit(spec) ?? next(spec, tags)
const from = base(hit.version, hit.kind, tags)
console.log(
JSON.stringify(
{
version: hit.version,
kind: hit.kind,
fromTagDefault: from,
},
null,
2,
),
)
type Kind = "rc" | "stable"
type Tag = { tag: string; version: string }
function explicit(spec: string) {
if (/^\d+\.\d+\.\d+-rc\.\d+$/.test(spec)) return { version: spec, kind: "rc" as Kind }
if (/^\d+\.\d+\.\d+$/.test(spec)) return { version: spec, kind: "stable" as Kind }
return undefined
}
function next(spec: string, tags: Tag[]) {
const latest = [...tags].sort((a, b) => semver.rcompare(a.version, b.version))[0]
if (!latest) throw new Error("No JetBrains release tags found; pass an explicit version")
const parsed = semver.parse(latest.version)
if (!parsed) throw new Error(`Invalid latest JetBrains tag: ${latest.tag}`)
if (spec === "next rc") return rc(parsed)
if (spec === "next stable") return stable(parsed)
throw new Error("--spec must be 'next rc', 'next stable', x.y.z-rc.n, or x.y.z")
}
function rc(ver: semver.SemVer) {
const pre = ver.prerelease
if (pre[0] === "rc" && typeof pre[1] === "number") {
return { version: `${ver.major}.${ver.minor}.${ver.patch}-rc.${pre[1] + 1}`, kind: "rc" as Kind }
}
return { version: `${ver.major}.${ver.minor}.${ver.patch + 1}-rc.1`, kind: "rc" as Kind }
}
function stable(ver: semver.SemVer) {
if (ver.prerelease.length) return { version: `${ver.major}.${ver.minor}.${ver.patch}`, kind: "stable" as Kind }
return { version: `${ver.major}.${ver.minor}.${ver.patch + 1}`, kind: "stable" as Kind }
}
function base(ver: string, kind: Kind, tags: Tag[]) {
const want = semver.parse(ver)
if (!want) throw new Error(`Invalid semver: ${ver}`)
const prior = tags
.filter((item) => !semver.prerelease(item.version) && semver.lt(item.version, ver))
.sort((a, b) => semver.rcompare(a.version, b.version))
if (kind === "stable") {
const hit = prior[0]
if (!hit) return null
return hit.tag
}
const prerelease = tags
.filter((item) => {
const parsed = semver.parse(item.version)
if (!parsed) return false
if (parsed.major !== want.major || parsed.minor !== want.minor || parsed.patch !== want.patch) return false
return Boolean(semver.prerelease(item.version)) && semver.lt(item.version, ver)
})
.sort((a, b) => semver.rcompare(a.version, b.version))
return (prerelease[0] ?? prior[0])?.tag ?? null
}
async function list() {
const text = await $`git tag --list ${"jetbrains/v*"}`.text()
return text
.split(/\r?\n/)
.map((item) => item.trim())
.filter(Boolean)
.map((tag) => ({ tag, version: tag.replace(/^jetbrains\/v/, "") }))
.filter((item) => semver.valid(item.version))
}
.kilo/skills/release-jetbrains/script/update-changelog.ts
+78
View File
@@ -0,0 +1,78 @@
#!/usr/bin/env bun
import { $ } from "bun"
import { parseArgs } from "util"
const repo = process.env.GH_REPO ?? process.env.GITHUB_REPOSITORY ?? "Kilo-Org/kilocode"
const path = "packages/kilo-jetbrains/CHANGELOG.md"
const { values } = parseArgs({
args: Bun.argv.slice(2),
options: {
version: { type: "string" },
file: { type: "string" },
help: { type: "boolean", short: "h", default: false },
},
})
if (values.help) {
console.log(`Usage: bun .kilo/skills/release-jetbrains/script/update-changelog.ts --version <version> --file <section.md>`)
process.exit(0)
}
const ver = values.version
const file = values.file
if (!ver) throw new Error("--version is required")
if (!file) throw new Error("--file is required")
const branch = `jetbrains/release/v${ver}`
const section = strip((await Bun.file(file).text()).trim())
validate(section, ver)
const current = (await $`gh api ${`repos/${repo}/contents/${path}`} -f ref=${branch}`.json()) as {
content: string
encoding: string
sha: string
}
if (current.encoding !== "base64") throw new Error(`Unexpected content encoding: ${current.encoding}`)
const text = Buffer.from(current.content.replace(/\s/g, ""), "base64").toString("utf8")
const pattern = regex(ver)
if (!pattern.test(text)) throw new Error(`${path} is missing a section for ${ver} on ${branch}`)
const next = text.replace(pattern, `\n${section}\n`).replace(/\n{3,}/g, "\n\n").trimEnd() + "\n"
if (next === text) {
console.log("CHANGELOG.md already contains the provided section")
process.exit(0)
}
const body = {
message: `docs(jetbrains): edit changelog for v${ver}`,
content: Buffer.from(next).toString("base64"),
sha: current.sha,
branch,
}
const tmp = await temp(body)
await $`gh api ${`repos/${repo}/contents/${path}`} --method PUT --input ${tmp}`
console.log(`Committed changelog update to ${branch}`)
function strip(text: string) {
return text.replace(/<!--\s*CONTEXT[\s\S]*?-->/g, "").trim()
}
function validate(section: string, ver: string) {
if (!section.startsWith(`## [${ver}]`)) throw new Error(`Section must start with ## [${ver}]`)
if (!/^### (Added|Fixed|Changed)$/m.test(section)) {
throw new Error("Section must contain at least one Added, Fixed, or Changed heading")
}
}
function regex(ver: string) {
const safe = ver.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
return new RegExp(`\n?## \\[${safe}\\][\\s\\S]*?(?=\n## \\[|$)`)
}
async function temp(body: object) {
const file = `/tmp/kilo-jetbrains-changelog-${Date.now()}.json`
await Bun.write(file, JSON.stringify(body))
return file
}
.kilo/skills/release-jetbrains/script/watch-publish.ts
+87
View File
@@ -0,0 +1,87 @@
#!/usr/bin/env bun
import { $ } from "bun"
import { parseArgs } from "util"
const repo = process.env.GH_REPO ?? process.env.GITHUB_REPOSITORY ?? "Kilo-Org/kilocode"
const workflow = "publish-jetbrains.yml"
const { values } = parseArgs({
args: Bun.argv.slice(2),
options: {
pr: { type: "string" },
version: { type: "string" },
merge: { type: "boolean", default: false },
"run-id": { type: "string" },
help: { type: "boolean", short: "h", default: false },
},
})
if (values.help) {
console.log(`Usage: bun .kilo/skills/release-jetbrains/script/watch-publish.ts --pr <number> --version <version> [--merge] [--run-id <id>]`)
process.exit(0)
}
const pr = values.pr
const ver = values.version
if (!pr) throw new Error("--pr is required")
if (!ver) throw new Error("--version is required")
const branch = `jetbrains/release/v${ver}`
const id = values["run-id"] ?? (values.merge ? await merge() : await find())
const url = `https://github.com/${repo}/actions/runs/${id}`
console.log(`publishRunId=${id}`)
console.log(`runUrl=${url}`)
await $`gh run watch ${id} --repo ${repo} --exit-status`
const rel = (await $`gh release view ${`jetbrains/v${ver}`} --repo ${repo} --json url,isPrerelease`.json()) as {
url: string
isPrerelease: boolean
}
console.log(
JSON.stringify(
{
version: ver,
marketplaceChannel: rel.isPrerelease ? "eap" : "default",
releaseUrl: rel.url,
runUrl: url,
},
null,
2,
),
)
async function merge() {
const before = new Set((await runs()).map((run) => run.databaseId))
await $`gh pr merge ${pr} --repo ${repo} --merge`
for (const _ of Array.from({ length: 120 })) {
const run = (await runs()).find((item) => item.headBranch === branch && !before.has(item.databaseId))
if (run) return String(run.databaseId)
await Bun.sleep(1000)
}
throw new Error(`No new ${workflow} run appeared after merging PR ${pr}`)
}
async function find() {
for (const _ of Array.from({ length: 120 })) {
const run = (await runs()).find((item) => item.headBranch === branch && active(item.status))
if (run) return String(run.databaseId)
await Bun.sleep(1000)
}
throw new Error(`No ${workflow} run found for ${branch}. Merge PR ${pr} first, or pass --merge to merge it automatically.`)
}
function active(status: string) {
return status === "queued" || status === "in_progress" || status === "waiting" || status === "requested" || status === "pending"
}
async function runs() {
return (await $`gh run list --repo ${repo} --workflow ${workflow} --event pull_request --json databaseId,createdAt,headBranch,status --limit 100`.json()) as {
databaseId: number
createdAt: string
headBranch: string
status: string
}[]
}
.opencode-version
+1 -1
View File
@@ -1 +1 @@
v1.14.42
v1.14.46
.opencode/tui.json
+2 -3
View File
@@ -1,4 +1,3 @@
{
"$schema": "https://opencode.ai/tui.json",
"keybinds": {}
}
"$schema": "https://opencode.ai/tui.json"
}
CONTRIBUTING.md
+2 -2
View File
@@ -16,7 +16,7 @@ The Kilo Community is [on Discord](https://kilo.ai/discord).
## Prerequisites
- **Bun 1.3.13+** — required for all packages.
- **Bun 1.3.14+** — required for all packages.
- **Java 21** — required by the JetBrains plugin. The root `bun turbo typecheck` and `bun turbo test:ci` commands include `@kilocode/kilo-jetbrains` and will fail without Java 21.
The preferred way to install Java is via [SDKMAN](https://sdkman.io/install):
@@ -41,7 +41,7 @@ The Kilo Community is [on Discord](https://kilo.ai/discord).
## Developing Kilo CLI
- **Requirements:** Bun 1.3.13+, Java 21 (see [Prerequisites](#prerequisites) above)
- **Requirements:** Bun 1.3.14+, Java 21 (see [Prerequisites](#prerequisites) above)
- Install dependencies and start the CLI from the repo root:
```bash
bun.lock
+87 -31
View File
@@ -33,7 +33,7 @@
},
"packages/core": {
"name": "@opencode-ai/core",
"version": "7.3.22",
"version": "7.3.33",
"bin": {
"opencode": "./bin/opencode",
},
@@ -68,7 +68,7 @@
},
"packages/http-recorder": {
"name": "@opencode-ai/http-recorder",
"version": "7.3.22",
"version": "7.3.33",
"dependencies": {
"@effect/platform-node": "catalog:",
"effect": "catalog:",
@@ -81,10 +81,11 @@
},
"packages/kilo-console": {
"name": "@kilocode/kilo-console",
"version": "7.3.22",
"version": "7.3.33",
"dependencies": {
"@kilocode/kilo-web-ui": "workspace:*",
"@kilocode/sdk": "workspace:*",
"@lottiefiles/dotlottie-web": "0.74.0",
"@opencode-ai/ui": "workspace:*",
"@solidjs/router": "catalog:",
"ghostty-web": "0.4.0",
@@ -102,7 +103,7 @@
},
"packages/kilo-docs": {
"name": "@kilocode/kilo-docs",
"version": "7.3.22",
"version": "7.3.33",
"dependencies": {
"@docsearch/css": "^4",
"@docsearch/js": "^4",
@@ -132,12 +133,13 @@
},
"packages/kilo-gateway": {
"name": "@kilocode/kilo-gateway",
"version": "7.3.22",
"version": "7.3.33",
"dependencies": {
"@ai-sdk/alibaba": "1.0.17",
"@ai-sdk/anthropic": "3.0.71",
"@ai-sdk/mistral": "3.0.27",
"@ai-sdk/openai": "3.0.53",
"@ai-sdk/openai-compatible": "2.0.37",
"@ai-sdk/openai-compatible": "2.0.41",
"@clack/prompts": "1.0.0-alpha.1",
"@kilocode/plugin": "workspace:*",
"@kilocode/sdk": "workspace:*",
@@ -168,7 +170,7 @@
},
"packages/kilo-i18n": {
"name": "@kilocode/kilo-i18n",
"version": "7.3.22",
"version": "7.3.33",
"devDependencies": {
"@tsconfig/node22": "catalog:",
"@types/bun": "catalog:",
@@ -178,7 +180,7 @@
},
"packages/kilo-indexing": {
"name": "@kilocode/kilo-indexing",
"version": "7.3.22",
"version": "7.3.33",
"dependencies": {
"@aws-sdk/client-bedrock-runtime": "3.1005.0",
"@aws-sdk/credential-provider-ini": "3.972.31",
@@ -210,11 +212,11 @@
},
"packages/kilo-jetbrains": {
"name": "@kilocode/kilo-jetbrains",
"version": "7.3.22",
"version": "7.3.33",
},
"packages/kilo-telemetry": {
"name": "@kilocode/kilo-telemetry",
"version": "7.3.22",
"version": "7.3.33",
"dependencies": {
"@kilocode/kilo-gateway": "workspace:*",
"posthog-node": "4.4.0",
@@ -228,7 +230,7 @@
},
"packages/kilo-ui": {
"name": "@kilocode/kilo-ui",
"version": "7.3.22",
"version": "7.3.33",
"dependencies": {
"@kilocode/sdk": "workspace:*",
"@kobalte/core": "0.13.11",
@@ -265,7 +267,7 @@
},
"packages/kilo-vscode": {
"name": "kilo-code",
"version": "7.3.22",
"version": "7.3.33",
"dependencies": {
"@anthropic-ai/sdk": "^0.39.0",
"@kilocode/kilo-gateway": "workspace:*",
@@ -331,7 +333,7 @@
},
"packages/kilo-web-ui": {
"name": "@kilocode/kilo-web-ui",
"version": "7.3.22",
"version": "7.3.33",
"dependencies": {
"@kilocode/kilo-ui": "workspace:*",
"@kobalte/core": "catalog:",
@@ -346,7 +348,7 @@
},
"packages/llm": {
"name": "@opencode-ai/llm",
"version": "7.3.22",
"version": "7.3.33",
"dependencies": {
"@smithy/eventstream-codec": "4.2.14",
"@smithy/util-utf8": "4.2.2",
@@ -364,7 +366,7 @@
},
"packages/opencode": {
"name": "@kilocode/cli",
"version": "7.3.22",
"version": "7.3.33",
"bin": {
"kilo": "./bin/kilo",
"kilocode": "./bin/kilo",
@@ -407,6 +409,7 @@
"@kilocode/kilo-indexing": "workspace:*",
"@kilocode/kilo-telemetry": "workspace:*",
"@kilocode/plugin": "workspace:*",
"@kilocode/plugin-atomic-chat": "workspace:*",
"@kilocode/sdk": "workspace:*",
"@lydell/node-pty": "catalog:",
"@modelcontextprotocol/sdk": "1.29.0",
@@ -509,6 +512,7 @@
"@types/bun": "catalog:",
"@types/cross-spawn": "catalog:",
"@types/mime-types": "3.0.1",
"@types/node": "catalog:",
"@types/npm-package-arg": "6.1.4",
"@types/npmcli__arborist": "6.3.3",
"@types/semver": "^7.5.8",
@@ -527,7 +531,7 @@
},
"packages/plugin": {
"name": "@kilocode/plugin",
"version": "7.3.22",
"version": "7.3.33",
"dependencies": {
"@kilocode/sdk": "workspace:*",
"effect": "catalog:",
@@ -553,9 +557,23 @@
"@opentui/solid",
],
},
"packages/plugin-atomic-chat": {
"name": "@kilocode/plugin-atomic-chat",
"version": "7.3.33",
"dependencies": {
"@kilocode/plugin": "workspace:*",
},
"devDependencies": {
"@tsconfig/node22": "catalog:",
"@types/node": "catalog:",
"@typescript/native-preview": "catalog:",
"typescript": "catalog:",
"vitest": "^4.0.16",
},
},
"packages/script": {
"name": "@opencode-ai/script",
"version": "7.3.22",
"version": "7.3.33",
"dependencies": {
"semver": "^7.6.3",
},
@@ -566,7 +584,7 @@
},
"packages/sdk/js": {
"name": "@kilocode/sdk",
"version": "7.3.22",
"version": "7.3.33",
"dependencies": {
"cross-spawn": "catalog:",
},
@@ -581,7 +599,7 @@
},
"packages/storybook": {
"name": "@opencode-ai/storybook",
"version": "7.3.22",
"version": "7.3.33",
"devDependencies": {
"@opencode-ai/ui": "workspace:*",
"@solidjs/meta": "catalog:",
@@ -604,7 +622,7 @@
},
"packages/ui": {
"name": "@opencode-ai/ui",
"version": "7.3.22",
"version": "7.3.33",
"dependencies": {
"@kilocode/sdk": "workspace:*",
"@kobalte/core": "catalog:",
@@ -707,10 +725,10 @@
"@tailwindcss/vite": "4.1.11",
"@tsconfig/bun": "1.0.9",
"@tsconfig/node22": "22.0.2",
"@types/bun": "1.3.12",
"@types/bun": "1.3.14",
"@types/cross-spawn": "6.0.6",
"@types/luxon": "3.7.1",
"@types/node": "24.12.2",
"@types/node": "24.12.4",
"@types/semver": "7.7.1",
"@typescript/native-preview": "7.0.0-dev.20260316.1",
"ai": "6.0.168",
@@ -1326,6 +1344,8 @@
"@kilocode/plugin": ["@kilocode/plugin@workspace:packages/plugin"],
"@kilocode/plugin-atomic-chat": ["@kilocode/plugin-atomic-chat@workspace:packages/plugin-atomic-chat"],
"@kilocode/sdk": ["@kilocode/sdk@workspace:packages/sdk/js"],
"@kobalte/core": ["@kobalte/core@0.13.11", "", { "dependencies": { "@floating-ui/dom": "^1.5.1", "@internationalized/date": "^3.4.0", "@internationalized/number": "^3.2.1", "@kobalte/utils": "^0.9.1", "@solid-primitives/props": "^3.1.8", "@solid-primitives/resize-observer": "^2.0.26", "solid-presence": "^0.1.8", "solid-prevent-scroll": "^0.1.4" }, "peerDependencies": { "solid-js": "^1.8.15" } }, "sha512-hK7TYpdib/XDb/r/4XDBFaO9O+3ZHz4ZWryV4/3BfES+tSQVgg2IJupDnztKXB0BqbSRy/aWlHKw1SPtNPYCFQ=="],
@@ -1354,6 +1374,8 @@
"@leichtgewicht/ip-codec": ["@leichtgewicht/ip-codec@2.0.5", "", {}, "sha512-Vo+PSpZG2/fmgmiNzYK9qWRh8h/CHrwD0mo1h1DzL4yzHNSfWYujGTYsWGreD000gcgmZ7K4Ys6Tx9TxtsKdDw=="],
"@lottiefiles/dotlottie-web": ["@lottiefiles/dotlottie-web@0.74.0", "", {}, "sha512-rG12+dJSVhQDdleGr9epR7zU/UJ6hh8jzBDHAurClHP5t5dSrOh3eP3UCFxolpVPcobaRVYsBnYg4HQokQewpg=="],
"@lukeed/ms": ["@lukeed/ms@2.0.2", "", {}, "sha512-9I2Zn6+NJLfaGoz9jN3lpwDgAYvfGeNYdbAIjJOqzs4Tpc+VU3Jqq4IofSUBKajiDS8k9fZIg18/z13mpk1bsA=="],
"@lydell/node-pty": ["@lydell/node-pty@1.2.0-beta.10", "", { "optionalDependencies": { "@lydell/node-pty-darwin-arm64": "1.2.0-beta.10", "@lydell/node-pty-darwin-x64": "1.2.0-beta.10", "@lydell/node-pty-linux-arm64": "1.2.0-beta.10", "@lydell/node-pty-linux-x64": "1.2.0-beta.10", "@lydell/node-pty-win32-arm64": "1.2.0-beta.10", "@lydell/node-pty-win32-x64": "1.2.0-beta.10" } }, "sha512-Fv+A3+MZVA8qhkBIZsM1E6dCdHNMyXXz22mAYiMWd03LlyK///F3OH6CKPX9mj4id7LUlxpr45yPzyBVy9aDPw=="],
@@ -2088,7 +2110,7 @@
"@types/babel__traverse": ["@types/babel__traverse@7.28.0", "", { "dependencies": { "@babel/types": "^7.28.2" } }, "sha512-8PvcXf70gTDZBgt9ptxJ8elBeBjcLOAcOtoO/mPJjtji1+CdGbHgm77om1GrsPxsiE+uXIpNSK64UYaIwQXd4Q=="],
"@types/bun": ["@types/bun@1.3.12", "", { "dependencies": { "bun-types": "1.3.12" } }, "sha512-DBv81elK+/VSwXHDlnH3Qduw+KxkTIWi7TXkAeh24zpi5l0B2kUg9Ga3tb4nJaPcOFswflgi/yAvMVBPrxMB+A=="],
"@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
"@types/cacache": ["@types/cacache@20.0.1", "", { "dependencies": { "@types/node": "*", "minipass": "*" } }, "sha512-QlKW3AFoFr/hvPHwFHMIVUH/ZCYeetBNou3PCmxu5LaNDvrtBlPJtIA6uhmU9JRt9oxj7IYoqoLcpxtzpPiTcw=="],
@@ -2196,7 +2218,7 @@
"@types/mssql": ["@types/mssql@9.1.11", "", { "dependencies": { "@types/node": "*", "tarn": "^3.0.1", "tedious": "*" } }, "sha512-vcujgrDbDezCxNDO4KY6gjwduLYOKfrexpRUwhoysRvcXZ3+IgZ/PMYFDgh8c3cQIxZ6skAwYo+H6ibMrBWPjQ=="],
"@types/node": ["@types/node@24.12.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g=="],
"@types/node": ["@types/node@24.12.4", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-GUUEShf+PBCGW2KaXwcIt3Yk+e3pkKwWKb9GSyM9WQVE+ep2jzmHdGsHzu4wgcZy5fN9FBdVzjpBQsYlpfpgLA=="],
"@types/node-fetch": ["@types/node-fetch@2.6.13", "", { "dependencies": { "@types/node": "*", "form-data": "^4.0.4" } }, "sha512-QGpRVpzSaUs30JBSGPjOg4Uveu384erbHBoT1zeONvyCfwQxIkUshLAOqN/k9EjGviPRmWTTe6aH2qySWKTVSw=="],
@@ -2534,7 +2556,7 @@
"bun-pty": ["bun-pty@0.4.8", "", {}, "sha512-rO70Mrbr13+jxHHHu2YBkk2pNqrJE5cJn29WE++PUr+GFA0hq/VgtQPZANJ8dJo6d7XImvBk37Innt8GM7O28w=="],
"bun-types": ["bun-types@1.3.12", "", { "dependencies": { "@types/node": "*" } }, "sha512-HqOLj5PoFajAQciOMRiIZGNoKxDJSr6qigAttOX40vJuSp6DN/CxWp9s3C1Xwm4oH7ybueITwiaOcWXoYVoRkA=="],
"bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
"bundle-name": ["bundle-name@4.1.0", "", { "dependencies": { "run-applescript": "^7.0.0" } }, "sha512-tjwM5exMg6BGRI+kNmTntNsvdZS1X8BFYS6tnJ2hdH0kVxM6/eVZ2xy+FqStSWvYmtfFMDLIxurorHwDKfDz5Q=="],
@@ -4532,6 +4554,8 @@
"@antfu/install-pkg/package-manager-detector": ["package-manager-detector@1.6.0", "", {}, "sha512-61A5ThoTiDG/C8s8UMZwSorAGwMJ0ERVGj2OjoW5pAalsNOg15+iQiPzrLJ4jhZ1HJzmC2PIHT2oEiH3R5fzNA=="],
"@anthropic-ai/sdk/@types/node": ["@types/node@24.12.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g=="],
"@aws-crypto/sha1-browser/@smithy/util-utf8": ["@smithy/util-utf8@2.3.0", "", { "dependencies": { "@smithy/util-buffer-from": "^2.2.0", "tslib": "^2.6.2" } }, "sha512-R8Rdn8Hy72KKcebgLiv8jQcQkXoLMOGGv5uI1/k0l+snqkOzQ1R0ChUBCxWMlBsFMekWjq0wRudIweFs7sKT5A=="],
"@aws-crypto/sha256-browser/@smithy/util-utf8": ["@smithy/util-utf8@2.3.0", "", { "dependencies": { "@smithy/util-buffer-from": "^2.2.0", "tslib": "^2.6.2" } }, "sha512-R8Rdn8Hy72KKcebgLiv8jQcQkXoLMOGGv5uI1/k0l+snqkOzQ1R0ChUBCxWMlBsFMekWjq0wRudIweFs7sKT5A=="],
@@ -4592,10 +4616,10 @@
"@kilocode/kilo-docs/typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
"@kilocode/kilo-gateway/@ai-sdk/openai-compatible": ["@ai-sdk/openai-compatible@2.0.37", "", { "dependencies": { "@ai-sdk/provider": "3.0.8", "@ai-sdk/provider-utils": "4.0.21" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-+POSFVcgiu47BK64dhsI6OpcDC0/VAE2ZSaXdXGNNhpC/ava++uSRJYks0k2bpfY0wwCTgpAWZsXn/dG2Yppiw=="],
"@kilocode/kilo-indexing/glob": ["glob@13.0.6", "", { "dependencies": { "minimatch": "^10.2.2", "minipass": "^7.1.3", "path-scurry": "^2.0.2" } }, "sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw=="],
"@manypkg/find-root/@types/node": ["@types/node@24.12.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g=="],
"@manypkg/find-root/find-up": ["find-up@4.1.0", "", { "dependencies": { "locate-path": "^5.0.0", "path-exists": "^4.0.0" } }, "sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw=="],
"@manypkg/find-root/fs-extra": ["fs-extra@8.1.0", "", { "dependencies": { "graceful-fs": "^4.2.0", "jsonfile": "^4.0.0", "universalify": "^0.1.0" } }, "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g=="],
@@ -4736,6 +4760,30 @@
"@textlint/linter-formatter/strip-ansi": ["strip-ansi@6.0.1", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="],
"@types/cacache/@types/node": ["@types/node@24.12.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g=="],
"@types/cross-spawn/@types/node": ["@types/node@24.12.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g=="],
"@types/mssql/@types/node": ["@types/node@24.12.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g=="],
"@types/node-fetch/@types/node": ["@types/node@24.12.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g=="],
"@types/npm-registry-fetch/@types/node": ["@types/node@24.12.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g=="],
"@types/npmcli__arborist/@types/node": ["@types/node@24.12.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g=="],
"@types/npmlog/@types/node": ["@types/node@24.12.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g=="],
"@types/pacote/@types/node": ["@types/node@24.12.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g=="],
"@types/qrcode/@types/node": ["@types/node@24.12.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g=="],
"@types/readable-stream/@types/node": ["@types/node@24.12.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g=="],
"@types/ssri/@types/node": ["@types/node@24.12.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g=="],
"@types/ws/@types/node": ["@types/node@24.12.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g=="],
"@typescript-eslint/visitor-keys/eslint-visitor-keys": ["eslint-visitor-keys@5.0.1", "", {}, "sha512-tD40eHxA35h0PEIZNeIjkHoDR4YjjJp34biM0mDvplBe//mB+IHCqHDGV7pxF+7MklTvighcCPPZC7ynWyjdTA=="],
"@vitest/expect/@standard-schema/spec": ["@standard-schema/spec@1.1.0", "", {}, "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w=="],
@@ -4774,6 +4822,8 @@
"ai-gateway-provider/@openrouter/ai-sdk-provider": ["@openrouter/ai-sdk-provider@2.5.1", "", { "peerDependencies": { "ai": "^6.0.0", "zod": "^3.25.0 || ^4.0.0" } }, "sha512-r1fJL1Cb3gQDa2MpWH/sfx1BsEW0uzlRriJM6eihaKqbtKDmZoBisF32VcVaQYassighX7NGCkF68EsrZA43uQ=="],
"apache-arrow/@types/node": ["@types/node@24.12.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g=="],
"archiver-utils/glob": ["glob@10.5.0", "", { "dependencies": { "foreground-child": "^3.1.0", "jackspeak": "^3.1.2", "minimatch": "^9.0.4", "minipass": "^7.1.2", "package-json-from-dist": "^1.0.0", "path-scurry": "^1.11.1" }, "bin": { "glob": "dist/esm/bin.mjs" } }, "sha512-DfXN8DfhJ7NH3Oe7cFmu3NCu1wKbkReJ8TorzSAFbSKrlNaQSKfIzqYqVY8zlbs2NLBbWpRiU52GX2PbaBVNkg=="],
"archiver-utils/is-stream": ["is-stream@2.0.1", "", {}, "sha512-hFoiJiTl63nn+kstHGBtewWSKnQLpyb155KHheA1l39uvtO9nWIop1p3udqPcUd/xbF1VLMO4n7OI6p7RbngDg=="],
@@ -4808,6 +4858,8 @@
"buffer/ieee754": ["ieee754@1.2.1", "", {}, "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA=="],
"bun-types/@types/node": ["@types/node@24.12.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g=="],
"c12/chokidar": ["chokidar@5.0.0", "", { "dependencies": { "readdirp": "^5.0.0" } }, "sha512-TQMmc3w+5AxjpL8iIiwebF73dRDF4fBIieAqGn9RGCWaEVwQ6Fb2cGe31Yns0RRIzii5goJ1Y7xbMwo1TxMplw=="],
"c12/dotenv": ["dotenv@17.4.2", "", {}, "sha512-nI4U3TottKAcAD9LLud4Cb7b2QztQMUEfHbvhTH09bqXTxnSie8WnjPALV/WMCrJZ6UV/qHJ6L03OqO3LcdYZw=="],
@@ -5022,6 +5074,8 @@
"pretty-format/ansi-styles": ["ansi-styles@5.2.0", "", {}, "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA=="],
"protobufjs/@types/node": ["@types/node@24.12.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g=="],
"proxy-addr/ipaddr.js": ["ipaddr.js@1.9.1", "", {}, "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g=="],
"qrcode/yargs": ["yargs@15.4.1", "", { "dependencies": { "cliui": "^6.0.0", "decamelize": "^1.2.0", "find-up": "^4.1.0", "get-caller-file": "^2.0.1", "require-directory": "^2.1.1", "require-main-filename": "^2.0.0", "set-blocking": "^2.0.0", "string-width": "^4.2.0", "which-module": "^2.0.0", "y18n": "^4.0.0", "yargs-parser": "^18.1.2" } }, "sha512-aePbxDmcYW++PaqBsJ+HYUFwCdv4LVvdnhBy78E57PIor8/OVvhMrADFFEDh8DHDFRv/O9i3lPhsENjO7QX0+A=="],
@@ -5092,6 +5146,8 @@
"tar-fs/tar-stream": ["tar-stream@2.2.0", "", { "dependencies": { "bl": "^4.0.3", "end-of-stream": "^1.4.1", "fs-constants": "^1.0.0", "inherits": "^2.0.3", "readable-stream": "^3.1.1" } }, "sha512-ujeqbceABgwMZxEJnk2HDY2DlnUZ+9oEcb1KzTVfYHio0UE6dG71n60d8D2I4qNvleWrrXpmjpt7vZeF1LnMZQ=="],
"tedious/@types/node": ["@types/node@24.12.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g=="],
"tedious/iconv-lite": ["iconv-lite@0.6.3", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" } }, "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw=="],
"tedious/sprintf-js": ["sprintf-js@1.1.3", "", {}, "sha512-Oo+0REFV59/rz3gfJNKQiBlwfHaSESl1pcGyABQsnnIfWOFt6JNj5gCog2U6MLZ//IGYD+nA8nI+mTShREReaA=="],
@@ -5170,12 +5226,12 @@
"@hey-api/openapi-ts/open/wsl-utils": ["wsl-utils@0.3.1", "", { "dependencies": { "is-wsl": "^3.1.0", "powershell-utils": "^0.1.0" } }, "sha512-g/eziiSUNBSsdDJtCLB8bdYEUMj4jR7AGeUo96p/3dTafgjHhpF4RiCFPiRILwjQoDXx5MqkBr4fwWtR3Ky4Wg=="],
"@kilocode/kilo-gateway/@ai-sdk/openai-compatible/@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@4.0.21", "", { "dependencies": { "@ai-sdk/provider": "3.0.8", "@standard-schema/spec": "^1.1.0", "eventsource-parser": "^3.0.6" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-MtFUYI1/8mgDvRmaBDjbLJPFFrMG777AvSgyIFQtZHIMzm88R/12vYBBpnk7pfiWLFE1DSZzY4WDYzGbKAcmiw=="],
"@manypkg/find-root/find-up/locate-path": ["locate-path@5.0.0", "", { "dependencies": { "p-locate": "^4.1.0" } }, "sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g=="],
"@morphllm/morphsdk/ai/@ai-sdk/gateway": ["@ai-sdk/gateway@3.0.95", "", { "dependencies": { "@ai-sdk/provider": "3.0.8", "@ai-sdk/provider-utils": "4.0.23", "@vercel/oidc": "3.1.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-ZmUNNbZl3V42xwQzPaNUi+s8eqR2lnrxf0bvB6YbLXpLjHYv0k2Y78t12cNOfY0bxGeuVVTLyk856uLuQIuXEQ=="],
"@morphllm/morphsdk/openai/@types/node": ["@types/node@24.12.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g=="],
"@morphllm/morphsdk/openai/zod": ["zod@3.25.76", "", {}, "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ=="],
"@octokit/core/@octokit/types/@octokit/openapi-types": ["@octokit/openapi-types@24.2.0", "", {}, "sha512-9sIH3nSUttelJSXUrmGzl7QUBFul0/mB8HRYl3fOlgHbIWG+WnYDXU3v/2zMtAvuzZ/ed00Ei6on975FhBfzrg=="],
@@ -5468,6 +5524,8 @@
"jszip/readable-stream/string_decoder": ["string_decoder@1.1.1", "", { "dependencies": { "safe-buffer": "~5.1.0" } }, "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg=="],
"kilo-code/openai/@types/node": ["@types/node@24.12.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g=="],
"lazystream/readable-stream/safe-buffer": ["safe-buffer@5.1.2", "", {}, "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g=="],
"lazystream/readable-stream/string_decoder": ["string_decoder@1.1.1", "", { "dependencies": { "safe-buffer": "~5.1.0" } }, "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg=="],
@@ -5578,8 +5636,6 @@
"@eslint/eslintrc/minimatch/brace-expansion/balanced-match": ["balanced-match@1.0.2", "", {}, "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw=="],
"@kilocode/kilo-gateway/@ai-sdk/openai-compatible/@ai-sdk/provider-utils/@standard-schema/spec": ["@standard-schema/spec@1.1.0", "", {}, "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w=="],
"@manypkg/find-root/find-up/locate-path/p-locate": ["p-locate@4.1.0", "", { "dependencies": { "p-limit": "^2.2.0" } }, "sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A=="],
"@morphllm/morphsdk/ai/@ai-sdk/gateway/@vercel/oidc": ["@vercel/oidc@3.1.0", "", {}, "sha512-Fw28YZpRnA3cAHHDlkt7xQHiJ0fcL+NRcIqsocZQUSmbzeIKRpwttJjik5ZGanXP+vlA4SbTg+AbA3bP363l+w=="],
flake.nix
+7 -7
View File
@@ -21,26 +21,26 @@
devShells = forEachSystem (pkgs: {
default =
let
# Pin bun to the version declared in package.json (packageManager: "bun@1.3.13").
# nixpkgs-unstable currently ships 1.3.11, so we fetch the official release directly.
# Pin bun to the version declared in package.json (packageManager: "bun@1.3.14").
# The locked nixpkgs revision ships 1.3.11, so we fetch the official release directly.
bun =
let
sources = {
"aarch64-linux" = {
name = "bun-linux-aarch64";
hash = "sha256-cLrkGzkIsKEg4eWMXIrzDnSvrjuNEbDT/djnh937SyI=";
hash = "sha256-on/7Y6gxA3WDbg1vZorhf6jY0YuIw3yCHGUzGXOhmjs=";
};
"x86_64-linux" = {
name = "bun-linux-x64";
hash = "sha256-ecB3H6i5LDOq5B4VoODTB+qZ0OLwAxfHHGxTI3p44lo=";
hash = "sha256-lR7iruhV8IWVruxiJSJqKY0/6oOj3NZGXAnLzN9+hI8=";
};
"aarch64-darwin" = {
name = "bun-darwin-aarch64";
hash = "sha256-VGfj9l26Umuf6pjwzOBO+vwMY+Fpcz7Ce4dqOtMtoZA=";
hash = "sha256-2LliIYKK1vl6x6wKt+lYcjQa92MAHogD6CZ2UsJlJiA=";
};
"x86_64-darwin" = {
name = "bun-darwin-x64";
hash = "sha256-5abItk9BmSUjLREeyxPiXwq/VeVPeSNB+YdiP9B3gAk=";
hash = "sha256-QYPfM3RiPlurMVxUfPoJdFM81FfYa3O2OfeoeXTNZjM=";
};
};
source =
@@ -49,7 +49,7 @@
in
pkgs.stdenv.mkDerivation rec {
pname = "bun";
version = "1.3.13";
version = "1.3.14";
src = pkgs.fetchurl {
url = "https://github.com/oven-sh/bun/releases/download/bun-v${version}/${source.name}.zip";
inherit (source) hash;
nix/hashes.json
+4 -4
View File
@@ -1,8 +1,8 @@
{
"nodeModules": {
"x86_64-linux": "sha256-STfDdoDiRwXnQ3B8lueNSZp4iJFL9TAME6R+dnxI1eU=",
"aarch64-linux": "sha256-v/N0eCo1pa3n5QTMdLHBYICIEdI0BiNEsMzgRbOEXfA=",
"aarch64-darwin": "sha256-gC6iPlR+UTo336ukkHIzHKQMwxFOdyTIl9UCIh/XVdw=",
"x86_64-darwin": "sha256-es6bcIwldn0sKHnC7TqOaL+IST3zZ3JrHbH8ojGbQQ0="
"x86_64-linux": "sha256-NSqthrARPWAxKVFfHuiUp3SqBqHzjVHFdEezBvZNm3c=",
"aarch64-linux": "sha256-DMgFksIgPHSgScquewbdiVcXxWsa3Zf0sFFqaVWYtgw=",
"aarch64-darwin": "sha256-uvoPjl4VBh7ErdmWlDD/chyXSc9KYDye3Fht0V6XD+A=",
"x86_64-darwin": "sha256-O4Mn1R2YrhHvizOZomST8p7PU/IpUj7+zr0SHis6QN0="
}
}
package.json
+4 -4
View File
@@ -4,7 +4,7 @@
"description": "AI-powered development tool",
"private": true,
"type": "module",
"packageManager": "bun@1.3.13",
"packageManager": "bun@1.3.14",
"scripts": {
"dev": "bun run --cwd packages/opencode --conditions=browser src/index.ts",
"dev:storybook": "bun --cwd packages/storybook storybook",
@@ -28,7 +28,7 @@
"@effect/opentelemetry": "4.0.0-beta.57",
"@effect/platform-node": "4.0.0-beta.57",
"@npmcli/arborist": "9.4.0",
"@types/bun": "1.3.12",
"@types/bun": "1.3.14",
"@types/cross-spawn": "6.0.6",
"@octokit/rest": "22.0.0",
"@hono/zod-validator": "0.4.2",
@@ -37,7 +37,7 @@
"ulid": "3.0.1",
"@kobalte/core": "0.13.11",
"@types/luxon": "3.7.1",
"@types/node": "24.12.2",
"@types/node": "24.12.4",
"@types/semver": "7.7.1",
"@tsconfig/node22": "22.0.2",
"@tsconfig/bun": "1.0.9",
@@ -151,6 +151,6 @@
"solid-js@1.9.10": "patches/solid-js@1.9.10.patch",
"mammoth@1.12.0": "patches/mammoth@1.12.0.patch"
},
"version": "7.3.22",
"version": "7.3.33",
"peerDependencies": {}
}
packages/containers/bun-node/Dockerfile
+1 -1
View File
@@ -6,7 +6,7 @@ FROM ${REGISTRY}/build/base:24.04
SHELL ["/bin/bash", "-lc"]
ARG NODE_VERSION=24.4.0
ARG BUN_VERSION=1.3.13
ARG BUN_VERSION=1.3.14
ENV BUN_INSTALL=/opt/bun
ENV PATH=/opt/bun/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
packages/core/package.json
+1 -1
View File
@@ -1,6 +1,6 @@
{
"$schema": "https://json.schemastore.org/package.json",
"version": "7.3.22",
"version": "7.3.33",
"name": "@opencode-ai/core",
"type": "module",
"license": "MIT",
packages/opencode/src/util/effect-zod.ts → packages/core/src/effect-zod.ts
View File
packages/core/src/flag/flag.ts
+11
View File
@@ -1,4 +1,5 @@
import { Config } from "effect"
import { InstallationChannel } from "../installation/version"
function truthy(key: string) {
const value = process.env[key]?.toLowerCase()
@@ -10,6 +11,13 @@ function falsy(key: string) {
return value === "false" || value === "0"
}
// Channels where new experiments default to ON (unstable / internal users).
// Stable channels (`prod`, `latest`) stay opt-in.
const UNSTABLE_CHANNELS = new Set(["dev", "beta", "local"])
function unstableDefault(key: string) {
return truthy(key) || (!falsy(key) && UNSTABLE_CHANNELS.has(InstallationChannel))
}
function number(key: string) {
const value = process.env[key]
if (!value) return undefined
@@ -47,6 +55,9 @@ export const Flag = {
KILO_DISABLE_CLAUDE_CODE_PROMPT: KILO_DISABLE_CLAUDE_CODE || truthy("KILO_DISABLE_CLAUDE_CODE_PROMPT"),
KILO_DISABLE_CLAUDE_CODE_SKILLS,
KILO_DISABLE_EXTERNAL_SKILLS: truthy("KILO_DISABLE_EXTERNAL_SKILLS"), // kilocode_change
// Default-on for dev/beta/local; opt-in for stable. Set
// KILO_EXPERIMENTAL_CUSTOMIZE_SKILL=false to force off, =true to force on.
KILO_EXPERIMENTAL_CUSTOMIZE_SKILL: unstableDefault("KILO_EXPERIMENTAL_CUSTOMIZE_SKILL"),
KILO_FAKE_VCS: process.env["KILO_FAKE_VCS"],
KILO_SERVER_PASSWORD: process.env["KILO_SERVER_PASSWORD"],
KILO_SERVER_USERNAME: process.env["KILO_SERVER_USERNAME"],
packages/opencode/src/util/schema.ts → packages/core/src/schema.ts
View File
packages/extensions/zed/extension.toml
+6 -6
View File
@@ -1,7 +1,7 @@
id = "kilo"
name = "Kilo"
description = "The open source coding agent."
version = "7.3.22"
version = "7.3.33"
schema_version = 1
authors = ["Anomaly"]
repository = "https://github.com/Kilo-Org/kilocode"
@@ -11,26 +11,26 @@ name = "Kilo"
icon = "./icons/opencode.svg"
[agent_servers.opencode.targets.darwin-aarch64]
archive = "https://github.com/Kilo-Org/kilocode/releases/download/v7.3.22/opencode-darwin-arm64.zip"
archive = "https://github.com/Kilo-Org/kilocode/releases/download/v7.3.33/opencode-darwin-arm64.zip"
cmd = "./opencode"
args = ["acp"]
[agent_servers.opencode.targets.darwin-x86_64]
archive = "https://github.com/Kilo-Org/kilocode/releases/download/v7.3.22/opencode-darwin-x64.zip"
archive = "https://github.com/Kilo-Org/kilocode/releases/download/v7.3.33/opencode-darwin-x64.zip"
cmd = "./opencode"
args = ["acp"]
[agent_servers.opencode.targets.linux-aarch64]
archive = "https://github.com/Kilo-Org/kilocode/releases/download/v7.3.22/opencode-linux-arm64.tar.gz"
archive = "https://github.com/Kilo-Org/kilocode/releases/download/v7.3.33/opencode-linux-arm64.tar.gz"
cmd = "./opencode"
args = ["acp"]
[agent_servers.opencode.targets.linux-x86_64]
archive = "https://github.com/Kilo-Org/kilocode/releases/download/v7.3.22/opencode-linux-x64.tar.gz"
archive = "https://github.com/Kilo-Org/kilocode/releases/download/v7.3.33/opencode-linux-x64.tar.gz"
cmd = "./opencode"
args = ["acp"]
[agent_servers.opencode.targets.windows-x86_64]
archive = "https://github.com/Kilo-Org/kilocode/releases/download/v7.3.22/opencode-windows-x64.zip"
archive = "https://github.com/Kilo-Org/kilocode/releases/download/v7.3.33/opencode-windows-x64.zip"
cmd = "./opencode.exe"
args = ["acp"]
packages/http-recorder/package.json
+1 -1
View File
@@ -1,6 +1,6 @@
{
"$schema": "https://json.schemastore.org/package.json",
"version": "7.3.22",
"version": "7.3.33",
"name": "@opencode-ai/http-recorder",
"type": "module",
"license": "MIT",
packages/kilo-console/package.json
+4 -2
View File
@@ -1,6 +1,6 @@
{
"name": "@kilocode/kilo-console",
"version": "7.3.22",
"version": "7.3.33",
"private": true,
"type": "module",
"scripts": {
@@ -13,6 +13,7 @@
"dependencies": {
"@kilocode/kilo-web-ui": "workspace:*",
"@kilocode/sdk": "workspace:*",
"@lottiefiles/dotlottie-web": "0.74.0",
"@opencode-ai/ui": "workspace:*",
"@solidjs/router": "catalog:",
"ghostty-web": "0.4.0",
@@ -26,5 +27,6 @@
"typescript": "catalog:",
"vite": "catalog:",
"vite-plugin-solid": "catalog:"
}
},
"peerDependencies": {}
}
packages/kilo-console/public/logo.lottie
BIN
View File
Binary file not shown.
packages/kilo-console/src/components/LoadingLogo.tsx
+34
View File
@@ -0,0 +1,34 @@
import { DotLottie } from "@lottiefiles/dotlottie-web"
import { onCleanup, onMount } from "solid-js"
const src = `${import.meta.env.BASE_URL}logo.lottie`
export function LoadingLogo(props: { class?: string }) {
let canvas: HTMLCanvasElement | undefined
onMount(() => {
if (!canvas) return
const motion = !window.matchMedia("(prefers-reduced-motion: reduce)").matches
const player = new DotLottie({
autoplay: motion,
canvas,
loop: motion,
src,
renderConfig: {
autoResize: true,
},
})
onCleanup(() => player.destroy())
})
return (
<canvas
ref={(node) => (canvas = node)}
class={`console-loading-logo${props.class ? ` ${props.class}` : ""}`}
role="img"
aria-label="Kilo loading animation"
/>
)
}
packages/kilo-console/src/components/LoadingScreen.tsx
+20
View File
@@ -0,0 +1,20 @@
import { LoadingLogo } from "./LoadingLogo"
type Variant = "fullscreen" | "content"
export function LoadingScreen(props: { variant: Variant }) {
return (
<section
class="console-loading"
classList={{
"console-loading-fullscreen": props.variant === "fullscreen",
"console-loading-content": props.variant === "content",
}}
role="status"
aria-live="polite"
aria-label="Loading Kilo Console"
>
<LoadingLogo />
</section>
)
}
packages/kilo-console/src/layouts/ConfigLayout.tsx
+2 -3
View File
@@ -1,6 +1,7 @@
import { Show } from "solid-js"
import type { JSX } from "solid-js"
import { Card } from "@kilocode/kilo-web-ui/card"
import { LoadingScreen } from "../components/LoadingScreen"
import { ConfigProvider } from "../context/ConfigProvider"
import { useConfig } from "../context/config"
import { ConfigSidebar } from "../routes/config/ConfigSidebar"
@@ -43,9 +44,7 @@ function ConfigContent(props: { children?: JSX.Element }) {
</Card>
</Show>
<Show when={ctx.data.loading && !ctx.data()}>
<Card class="banner" variant="info">
Loading dashboard data...
</Card>
<LoadingScreen variant="content" />
</Show>
{props.children}
</section>
packages/kilo-console/src/routes/projects/ProjectConsoleRoute.tsx
+3 -6
View File
@@ -2,6 +2,7 @@ import { A, useLocation, useParams } from "@solidjs/router"
import { createEffect, createMemo, createResource, createSignal, For, onCleanup, Show } from "solid-js"
import { Card } from "@kilocode/kilo-web-ui/card"
import { Icon } from "@kilocode/kilo-web-ui/icon"
import { LoadingScreen } from "../../components/LoadingScreen"
import {
createProjectPty,
createProjectWorktree,
@@ -677,14 +678,10 @@ export function ProjectConsoleRoute() {
<main class="project-console-main">
<Show when={!query() && discoverable(search())}>
<Card class="banner" variant="info">
Discovering Kilo server...
</Card>
<LoadingScreen variant="fullscreen" />
</Show>
<Show when={snap.loading && !snap()}>
<Card class="banner" variant="info">
Loading project console...
</Card>
<LoadingScreen variant="fullscreen" />
</Show>
<Show when={snap.error || failure()}>
<Card class="banner" variant="error">
packages/kilo-console/src/routes/projects/ProjectsRoute.tsx
+3 -6
View File
@@ -2,6 +2,7 @@ import { createEffect, createMemo, createResource, createSignal, For, Show } fro
import { A } from "@solidjs/router"
import { Card } from "@kilocode/kilo-web-ui/card"
import { SearchField } from "../../components/SearchField"
import { LoadingScreen } from "../../components/LoadingScreen"
import {
discover,
forgetCached,
@@ -131,15 +132,11 @@ export function ProjectsRoute() {
</header>
<Show when={!query() && discoverable()}>
<Card class="banner" variant="info">
Discovering Kilo server...
</Card>
<LoadingScreen variant="fullscreen" />
</Show>
<Show when={items.loading && !items()}>
<Card class="banner" variant="info">
Loading projects...
</Card>
<LoadingScreen variant="fullscreen" />
</Show>
<Show when={items.error}>
packages/kilo-console/src/styles.css
+1
View File
@@ -1,4 +1,5 @@
@import "./styles/base.css";
@import "./styles/loading.css";
@import "./styles/config.css";
@import "./styles/cli-ui.css";
@import "./styles/resolved.css";
packages/kilo-console/src/styles/loading.css
+46
View File
@@ -0,0 +1,46 @@
.console-loading {
display: grid;
place-items: center;
background: var(--background);
}
.console-loading-fullscreen {
position: fixed;
z-index: 1000;
inset: 0;
width: 100vw;
height: 100vh;
}
.kilo-console .content {
position: relative;
}
.kilo-console .content > .console-loading-content {
position: absolute;
z-index: 10;
inset: 0;
}
.console-loading-logo {
display: block;
width: min(10rem, 28vw);
height: auto;
aspect-ratio: 1;
opacity: 0.5;
pointer-events: none;
}
.console-loading-fullscreen .console-loading-logo {
width: min(13rem, 31vw);
}
@media (max-width: 560px) {
.console-loading-logo {
width: min(8rem, 34vw);
}
.console-loading-fullscreen .console-loading-logo {
width: min(10rem, 36vw);
}
}
packages/kilo-docs/__tests__/heading.test.ts
+17
View File
@@ -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")
})
})
packages/kilo-docs/lib/nav/ai-providers.ts
+1
View File
@@ -55,6 +55,7 @@ export const AiProvidersNav: NavSection[] = [
links: [
{ href: "/ai-providers/ollama", children: "Ollama" },
{ href: "/ai-providers/lmstudio", children: "LM Studio" },
{ href: "/ai-providers/atomic-chat", children: "Atomic Chat" },
{ href: "/ai-providers/vscode-lm", children: "VS Code LM API" },
{
href: "/ai-providers/openai-compatible",
packages/kilo-docs/lib/nav/contributing.ts
+63 -55
View File
@@ -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",
children: "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",
},
],
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",
},
],
},
packages/kilo-docs/lychee.toml
+2 -1
View File
@@ -32,8 +32,9 @@ exclude = [
'^https?://api\.voyageai\.com/v1/embeddings/?$',
'^https?://generativelanguage\.googleapis\.com/v1beta/openai/?$',
'^https?://search\.parallel\.ai/mcp/?$',
# xAI API and OAuth endpoints require request parameters or non-GET methods.
# xAI API and OAuth endpoints require request parameters or reject plain link checks.
'^https?://api\.x\.ai/v1/?$',
'^https?://accounts\.x\.ai/?$',
'^https?://auth\.x\.ai/?$',
'^https?://auth\.x\.ai/oauth2/(authorize|device/code|token)/?$',
'https://opencode.ai/pages/config',
packages/kilo-docs/markdoc/nodes/heading.markdoc.ts
+8 -2
View File
@@ -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()
}
packages/kilo-docs/markdoc/partials/install-jetbrains.md
+3 -1
View File
@@ -35,8 +35,10 @@ Try the [v7 Early Access Program plugin](#jetbrains-early-access) for a JetBrain
The v7 EAP plugin is available for users who want to try the newest JetBrains experience before it reaches the default Marketplace channel. It uses a JetBrains-native UI and is designed to work well with JetBrains remote development.
Follow the [v7 roadmap and release milestone](https://github.com/Kilo-Org/kilocode/milestone/1) for planned work and release progress.
{% callout type="info" %}
The v7 EAP plugin supports JetBrains IDEs with 261+ builds. EAP builds may update more frequently than the default Marketplace release. Share feedback in the JetBrains channel on the [Kilo Discord](https://kilo.ai/discord).
The v7 EAP plugin is compatible with JetBrains IDE builds 261 and later. EAP builds update frequently, so we recommend enabling automatic plugin updates in your JetBrains IDE from **Settings/Preferences → System Settings → Updates → Update plugins automatically**. Share feedback in the JetBrains channel on the [Kilo Discord](https://kilo.ai/discord).
{% /callout %}
To install the EAP build and receive updates:
packages/kilo-docs/markdoc/tags/index.ts
+1
View File
@@ -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"
packages/kilo-docs/markdoc/tags/linebreak.markdoc.ts
+4
View File
@@ -0,0 +1,4 @@
export const linebreak = {
render: "br",
selfClosing: true,
}
packages/kilo-docs/package.json
+4 -2
View File
@@ -1,12 +1,14 @@
{
"name": "@kilocode/kilo-docs",
"version": "7.3.22",
"version": "7.3.33",
"private": true,
"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",
packages/kilo-docs/pages/ai-providers/atomic-chat.md
+112
View File
@@ -0,0 +1,112 @@
---
title: "Using Atomic Chat with Kilo Code | Local LLMs"
description: "Run local models in Kilo Code via Atomic Chat's OpenAI-compatible API. Setup for VS Code and the CLI."
sidebar_label: Atomic Chat
---
# Using Atomic Chat With Kilo Code
[Kilo Code](https://kilocode.ai/) supports [Atomic Chat](https://atomic.chat/) as a local provider. Atomic Chat runs models on your machine and exposes an OpenAI-compatible API (default `http://127.0.0.1:1337/v1`).
**Website:** [https://atomic.chat/](https://atomic.chat/)
**Repository:** [https://github.com/AtomicBot-ai/Atomic-Chat](https://github.com/AtomicBot-ai/Atomic-Chat)
## Prerequisites
1. Install [Atomic Chat](https://atomic.chat/) (macOS or Windows).
2. Download and load a model in the app.
3. Enable the **local API server** (default port **1337**).
4. Confirm the API responds:
```bash
curl http://127.0.0.1:1337/v1/models
```
## Configuration in Kilo Code
Kilo Code ships the `@kilocode/plugin-atomic-chat` plugin by default. It **does not** call localhost unless you opt in (see below). When enabled, it discovers models from `GET /v1/models` and can warn if the selected model is not loaded.
**Localhost HTTP runs only when one of these is true:**
- You configure `provider.atomic-chat` in `kilo.jsonc`
- You set `"model": "atomic-chat/..."` (or per-agent model uses `atomic-chat`)
- You enable optional auto-detect: `"atomicChat": { "autoDetect": true }` (probes ports **1337** and **1338**)
Otherwise no requests are made to Atomic Chat (suitable for restricted environments).
{% tabs %}
{% tab label="VSCode" %}
Open **Settings** (gear icon) → **Providers** → **Atomic Chat**. No API key is required for the default local server. Adjust the base URL if Atomic Chat uses a non-default host or port.
{% /tab %}
{% tab label="CLI" %}
**Config file** (`~/.config/kilo/kilo.jsonc` or `./kilo.jsonc`):
```jsonc
{
"provider": {
"atomic-chat": {
"options": {
"baseURL": "http://127.0.0.1:1337/v1",
},
},
},
}
```
Set your default model (use an id from `curl http://127.0.0.1:1337/v1/models`):
```jsonc
{
"model": "atomic-chat/gemma-4-E4B-it-IQ4_XS",
}
```
Optional auto-detect without a provider block:
```jsonc
{
"atomicChat": { "autoDetect": true },
}
```
To disable the provider entirely, use `disabled_providers: ["atomic-chat"]` or remove `@kilocode/plugin-atomic-chat` from the `plugin` array in your config.
{% /tab %}
{% /tabs %}
## Custom or unlisted models
If a loaded model does not appear in the picker, register it under `provider.atomic-chat.models`:
```jsonc
{
"model": "atomic-chat/my-local-model",
"provider": {
"atomic-chat": {
"models": {
"my-local-model": {
"id": "exact-id-from-v1-models",
"name": "My Local Model",
},
},
},
},
}
```
See [Custom Models](/docs/code-with-ai/agents/custom-models) for all model fields.
## Tips
- Prefer capable models with large context windows; agent workflows use long prompts.
- Keep only the models you need loaded in Atomic Chat to save memory.
- For embeddings via Atomic Chat, use the **openai-compatible** indexing provider with the same base URL.
## Related
- [LM Studio](/docs/ai-providers/lmstudio)
- [Ollama](/docs/ai-providers/ollama)
- [Local models overview](/docs/automate/extending/local-models)
packages/kilo-docs/pages/ai-providers/index.md
+1
View File
@@ -33,6 +33,7 @@ Major AI companies offering powerful models via API:
Run models on your own hardware for privacy and offline use:
- **[Atomic Chat](/docs/ai-providers/atomic-chat)** - Local models with TurboQuant inference and auto-discovery in Kilo Code
- **[Ollama](/docs/ai-providers/ollama)** - Easy local model management
- **[LM Studio](/docs/ai-providers/lmstudio)** - Desktop app for local models
- **[OpenAI Compatible](/docs/ai-providers/openai-compatible)** - Any OpenAI-compatible endpoint
packages/kilo-docs/pages/automate/extending/local-models.md
+6 -6
View File
@@ -5,7 +5,7 @@ description: "Run AI models locally with Kilo Code"
# Using Local Models
Kilo Code supports running language models locally on your own machine using [Ollama](https://ollama.com/) and [LM Studio](https://lmstudio.ai/). This offers several advantages:
Kilo Code supports running language models locally on your own machine using [Ollama](https://ollama.com/), [LM Studio](https://lmstudio.ai/), and [Atomic Chat](https://atomic.chat/). This offers several advantages:
- **Privacy:** Your code and data never leave your computer.
- **Offline Access:** You can use Kilo Code even without an internet connection.
@@ -21,10 +21,11 @@ Kilo Code supports running language models locally on your own machine using [Ol
## Supported Local Model Providers
Kilo Code currently supports two main local model providers:
Kilo Code supports several local model providers:
1. **Ollama:** A popular open-source tool for running large language models locally. It supports a wide range of models.
2. **LM Studio:** A user-friendly desktop application that simplifies the process of downloading, configuring, and running local models. It also provides a local server that emulates the OpenAI API.
2. **LM Studio:** A user-friendly desktop application that simplifies downloading and running local models, with a local server that emulates the OpenAI API.
3. **[Atomic Chat](https://atomic.chat/):** Open-source local AI with TurboQuant-optimized inference, a built-in chat UI, and an OpenAI-compatible API on port **1337**. Kilo Code can discover loaded models when you opt in (`provider.atomic-chat`, `atomicChat.autoDetect`, or an `atomic-chat/...` model).
## Setting Up Local Models
@@ -32,12 +33,11 @@ For detailed setup instructions, see:
- [Setting up Ollama](/docs/ai-providers/ollama)
- [Setting up LM Studio](/docs/ai-providers/lmstudio)
Both providers offer similar capabilities but with different user interfaces and workflows. Ollama provides more control through its command-line interface, while LM Studio offers a more user-friendly graphical interface.
- [Setting up Atomic Chat](/docs/ai-providers/atomic-chat)
## Troubleshooting
- **"No connection could be made because the target machine actively refused it":** This usually means that the Ollama or LM Studio server isn't running, or is running on a different port/address than Kilo Code is configured to use. Double-check the Base URL setting.
- **"No connection could be made because the target machine actively refused it":** This usually means that Atomic Chat, Ollama, or LM Studio isn't running, or is on a different port than Kilo Code expects (Atomic Chat: `http://127.0.0.1:1337/v1`, LM Studio: `http://127.0.0.1:1234/v1`, Ollama: `http://127.0.0.1:11434`). Double-check the Base URL setting.
- **Slow Response Times:** Local models can be slower than cloud-based models, especially on less powerful hardware. If performance is an issue, try using a smaller model.
packages/kilo-docs/pages/code-with-ai/agents/auto-model.md
+5 -3
View File
@@ -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 |
|---|---|---|
@@ -34,7 +34,9 @@ The underlying models behind each Auto Model tier are updated server-side as bet
- **Free** — Routes to the best available free models on OpenRouter, splitting traffic across them. Because free model availability shifts over time as providers change promotional periods, the mapping is updated server-side — you always get the best free option without having to track what's currently available. Quality will be lower than paid tiers, and the models may change over time.
{% callout type="warning" title="Data handling for Auto Free" %}
Auto Free may route your requests to providers that log prompts and outputs and use them to improve their services. In particular, it may route to NVIDIA's free endpoints, which are provided under the [NVIDIA API Trial Terms of Service](https://assets.ngc.nvidia.com/products/api-catalog/legal/NVIDIA%20API%20Trial%20Terms%20of%20Service.pdf) — trial use only, not for production or sensitive data. Do not submit personal or confidential data when using Auto Free.
Auto Free may route your requests to providers that log prompts and outputs and use them to improve their services. Do not submit personal or confidential data when using Auto Free. In particular, it may route to NVIDIA's free endpoints.
For NVIDIA free endpoints (Super/Ultra/etc): Trial use only - do not submit personal or confidential data. Your use is logged for security purposes and to improve NVIDIA products and services. The logged session data for improvement purposes is not linked to your identity or any persistent identifier. For more information about our data processing practices, see our [Privacy Policy](https://www.nvidia.com/en-us/about-nvidia/privacy-policy/). By interacting with this endpoint, you consent to our collection, recording, and use of such information and the [NVIDIA API Trial Terms of Service](https://assets.ngc.nvidia.com/products/api-catalog/legal/NVIDIA%20API%20Trial%20Terms%20of%20Service.pdf).
{% /callout %}
## Benefits
packages/kilo-docs/pages/contributing/architecture/agent-observability.md
-150
View File
@@ -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)
packages/kilo-docs/pages/contributing/architecture/auto-model-tiers.md
-184
View File
@@ -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
packages/kilo-docs/pages/contributing/architecture/automation-services.md
+190
View File
@@ -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
packages/kilo-docs/pages/contributing/architecture/benchmarking.md
-306
View File
@@ -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)
packages/kilo-docs/pages/contributing/architecture/cli-runtime.md
+331
View File
@@ -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 <url>` | 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<br/>Workspace root and worktrees"]
server["One editor-owned<br/>kilo serve server"]
store["InstanceStore"]
root["Workspace-root<br/>local runtime instance"]
worktree["Worktree<br/>local runtime instance"]
sse["One process-wide<br/>/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 <host> --port <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/<project-id>/<worktree-hash>
```
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
packages/kilo-docs/pages/contributing/architecture/cloud-platform.md
+397
View File
@@ -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<br/>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<br/>Security Agent state"]
subgraph sync ["Finding sync"]
direction LR
interactive["Interactive web sync"] --> web["Web Security Agent handler"] --> github
cron["security-sync<br/>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<br/>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<br/>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<br/>tied to Kilo user"]
instanceDO["Per-instance Durable Object"]
dbConnection["Kilo database connection"]
end
db["Kilo database<br/>Instances<br/>Short-lived access codes<br/>Image catalog<br/>Billing and user preferences"]
proxy["Fly proxy<br/>Per-user Fly app<br/>Per-user encryption<br/>Routes to pinned instance"]
subgraph flyInstance ["Fly instance: owner-scoped runtime"]
direction TB
subgraph container ["KiloClaw container"]
direction TB
controller["KiloClaw controller<br/>Supervises OpenClaw gateway<br/>Exposes control endpoints<br/>Proxies HTTP and WebSocket traffic"]
openclaw["OpenClaw<br/>Gateway and Control UI"]
tools["Pre-installed tools and skills"]
controller --> openclaw
tools --> openclaw
end
volume["Persistent Fly volume<br/>/root/.openclaw config<br/>/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
packages/kilo-docs/pages/contributing/architecture/cloud-security.md
+427
View File
@@ -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<br/>Durable Object"]
redeem["Hyperdrive-backed redemption<br/>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
packages/kilo-docs/pages/contributing/architecture/config-schema.md
+91 -19
View File
@@ -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.<new_key>' /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,<br/>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<br/>Effect Schema"] --> generated["Locally generated schema<br/>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.<new_key>' /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
packages/kilo-docs/pages/contributing/architecture/development-patterns.md
+195
View File
@@ -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 <tag>
bun run merge.ts --version <tag> --dry-run
bun run merge.ts --version <tag>
```
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
packages/kilo-docs/pages/contributing/architecture/enterprise-mcp-controls.md
-111
View File
@@ -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
packages/kilo-docs/pages/contributing/architecture/feature-template.md
-42
View File
@@ -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.
packages/kilo-docs/pages/contributing/architecture/features.md
-23
View File
@@ -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).
packages/kilo-docs/pages/contributing/architecture/index.md
+204 -261
View File
@@ -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"]
Choose the path closest to the change you are making:
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 |
| Contributor path | Suggested order |
|---|---|
| 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 |
| 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) |
## Client Layer
## Repository boundaries
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.
### 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 |
|---|---|
| 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 |
A reconciler loop running every 5 seconds drives all state transitions: dispatching agents, transitioning beads, polling PR status, managing convoys, and recovering from failures.
### Supporting Services
| Service | Purpose |
|---|---|
| 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:
- Define which tools are available
- Set custom system prompts
- Configure file restrictions
- Examples: Code, Architect, Debug, Ask
### Model Context Protocol (MCP)
MCP enables extending the agent with external tools:
- Servers provide additional capabilities
- Standardized protocol for tool communication
- Configured via `mcp.json`
### Checkpoints
Git-based state management for safe exploration:
- Creates commits to track changes
- Enables rolling back to previous states
- Shadow repository for isolation
### Worktrees
Git worktree isolation for parallel task execution:
- 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
## Development Patterns
### Client-Server Communication
All clients communicate with the CLI via its HTTP + SSE API. The `@kilocode/sdk` package provides a TypeScript client:
```typescript
import { KiloClient } from "@kilocode/sdk"
const client = new KiloClient({ baseUrl: "http://localhost:3000" })
const session = await client.session.create({ ... })
```
### Module Export Pattern
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.
```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"
```
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.
### CLI Server API
The CLI server uses Effect `HttpApi` and publishes an OpenAPI-compatible HTTP + SSE API consumed by `@kilocode/sdk`.
- 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.
### 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) {
// ...
},
})
```
## Build System
The project uses:
- **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
## Repositories
Architecture pages cross two repositories:
| Repository | Contents |
|---|---|
| [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 |
| [Kilo&#8209;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&#8209;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 |
## Further Reading
## Three architecture layers
- [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
| 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 |
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.
## Terms used throughout
| 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.
```mermaid
flowchart LR
subgraph clients ["Local clients"]
tui["Kilo CLI TUI"]
run["kilo run"]
console["Kilo Console"]
editors["VS Code and JetBrains"]
end
subgraph local ["Local Kilo CLI boundary"]
daemon["Local daemon manager"]
server["kilo serve server"]
runtime["Kilo CLI runtime"]
router["Provider router"]
end
subgraph cloud ["Kilo Cloud shared services"]
web["Web control plane"]
workers["Automation Workers, queues, and Durable Objects"]
gateway["Kilo Gateway"]
agent["Cloud Agent"]
end
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
```
### Two execution paths
| 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. |
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.
## Adjacent hosted boundaries
The core execution spine is not the full cloud product catalog. These service families and hosted runtimes attach to it for specific product flows:
```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
```
| 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) |
## Local entry points and clients
These local surfaces live in [`Kilo-Org/kilocode`](https://github.com/Kilo-Org/kilocode). Package paths below are relative to that repository root.
| 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 |
## Cloud service families
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.
| 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 |
## Supporting packages
These supporting packages also live in [`Kilo-Org/kilocode`](https://github.com/Kilo-Org/kilocode). Package paths below are relative to that repository root.
| 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` |
## Architecture pages
| 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 |
## Development pages
After system-boundary pages, continue with Development Patterns for implementation rules. Use CLI Config Schema when changing config keys or editor-facing schema publication.
| Page | What it covers |
|---|---|
| [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
packages/kilo-docs/pages/contributing/architecture/jetbrains-plugin.md
+160
View File
@@ -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<Unit>` 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
<PathManager.getSystemPath()>/kilo/bin/kilo
<PathManager.getSystemPath()>/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
packages/kilo-docs/pages/contributing/architecture/mcp-oauth-authorization.md
-572
View File
@@ -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<OAuthTokens>
/**
* Gets stored tokens for a server, if available and valid
*/
getStoredTokens(serverUrl: string): Promise<OAuthTokens | null>
/**
* Clears stored tokens for a server (for logout/re-auth)
*/
clearTokens(serverUrl: string): Promise<void>
/**
* Refreshes tokens if refresh token is available
*/
refreshTokens(serverUrl: string): Promise<OAuthTokens | null>
}
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<AuthorizationServerMetadata>
/**
* Fetches Protected Resource Metadata (RFC 9728)
*/
fetchResourceMetadata(metadataUrl: string): Promise<ProtectedResourceMetadata>
/**
* Fetches Authorization Server Metadata (RFC 8414 / OIDC Discovery)
*/
fetchAuthServerMetadata(issuerUrl: string): Promise<AuthorizationServerMetadata>
}
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<void>
/**
* Retrieves stored tokens
*/
getTokens(serverUrl: string): Promise<OAuthTokens | null>
/**
* Removes stored tokens
*/
removeTokens(serverUrl: string): Promise<void>
/**
* Lists all servers with stored tokens
*/
listServers(): Promise<string[]>
}
```
#### 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<void> {
// ... 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<AuthorizationResult>
}
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<string, unknown>,
) {
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
packages/kilo-docs/pages/contributing/architecture/onboarding-improvements.md
-148
View File
@@ -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
packages/kilo-docs/pages/contributing/architecture/organization-modes-library.md
-71
View File
@@ -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
packages/kilo-docs/pages/contributing/architecture/per-message-feedback.md
-75
View File
@@ -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 (`<leader>=` / `<leader>-`) 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.
packages/kilo-docs/pages/contributing/architecture/track-repo-url.md
-42
View File
@@ -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`.
packages/kilo-docs/pages/contributing/architecture/voice-transcription.md
-133
View File
@@ -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)
packages/kilo-docs/pages/contributing/architecture/vscode-extension.md
+180
View File
@@ -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=<base64 kilo:password>` 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
packages/kilo-docs/pages/contributing/development-environment.md
+1 -1
View File
@@ -16,7 +16,7 @@ This document will help you set up your development environment and understand h
Before you begin, make sure you have the following installed:
1. **Git** - For version control
2. **Bun 1.3.13+** - Required for installing dependencies and running scripts
2. **Bun 1.3.14+** - Required for installing dependencies and running scripts
3. **Visual Studio Code** - Our recommended IDE for development
4. **Java 21** - Required only when running JetBrains plugin checks or repo-level checks that include `@kilocode/kilo-jetbrains`
packages/kilo-docs/pages/contributing/features/agent-observability.md
+94
View File
@@ -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).
packages/kilo-docs/pages/contributing/features/benchmarking.md
+110
View File
@@ -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)
packages/kilo-docs/pages/contributing/features/enterprise-mcp-controls.md
+108
View File
@@ -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
packages/kilo-docs/pages/contributing/features/index.md
+17
View File
@@ -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.
packages/kilo-docs/pages/contributing/features/onboarding-improvements.md
+72
View File
@@ -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
packages/kilo-docs/pages/contributing/features/template.md
+73
View File
@@ -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.
packages/kilo-docs/pages/contributing/index.md
+1 -1
View File
@@ -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
packages/kilo-docs/pages/deploy-secure/security-reviews.md
+1 -1
View File
@@ -9,7 +9,7 @@ Most teams are drowning in Dependabot alerts. The majority of reported CVEs aren
Kilo's Security Agent fixes this. It syncs your Dependabot alerts, triages them with AI, and performs deep codebase analysis to determine whether each vulnerability is actually reachable in your code. Non-exploitable findings can be auto-dismissed and synced back to GitHub.
Available on **Teams** and **Enterprise** plans.
Available for all users.
---
packages/kilo-docs/pages/gateway/models-and-providers.md
+7 -7
View File
@@ -60,20 +60,20 @@ Several models are available at no cost, subject to rate limits:
| Model ID | Description |
|---|---|
| `x-ai/grok-code-fast-1:optimized:free` | xAI Grok Code Fast 1 Optimized |
| `nvidia/nemotron-3-super-120b-a12b:free` | NVIDIA Nemotron 3 Super 120B |
| `arcee-ai/trinity-large-thinking:free` | Arcee Trinity Large |
| `stepfun/step-3.7-flash:free` | StepFun Step 3.7 Flash |
| `poolside/laguna-m.1:free` | Poolside Laguna M.1 |
| `nvidia/nemotron-3-ultra-550b-a55b:free` | NVIDIA Nemotron 3 Ultra |
| `openrouter/free` | Best available free model |
Free models are available to both authenticated and anonymous users. Anonymous users are rate-limited to 200 requests per hour per IP address.
{% callout type="warning" title="Nemotron 3 Super Free (NVIDIA free endpoints)" %}
Provided under the [NVIDIA API Trial Terms of Service](https://assets.ngc.nvidia.com/products/api-catalog/legal/NVIDIA%20API%20Trial%20Terms%20of%20Service.pdf). Trial use only — not for production or sensitive data. Prompts and outputs are logged by NVIDIA to improve its models and services. Do not submit personal or confidential data.
{% callout type="warning" title="NVIDIA free endpoints" %}
For NVIDIA free endpoints (Super/Ultra/etc): Trial use only - do not submit personal or confidential data. Your use is logged for security purposes and to improve NVIDIA products and services. The logged session data for improvement purposes is not linked to your identity or any persistent identifier. For more information about our data processing practices, see our [Privacy Policy](https://www.nvidia.com/en-us/about-nvidia/privacy-policy/). By interacting with this endpoint, you consent to our collection, recording, and use of such information and the [NVIDIA API Trial Terms of Service](https://assets.ngc.nvidia.com/products/api-catalog/legal/NVIDIA%20API%20Trial%20Terms%20of%20Service.pdf).
{% /callout %}
## 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.
@@ -104,7 +104,7 @@ Great balance of price and capability. The resolved model depends on the API int
Free with limited capability. No credits required. The resolved model is selected dynamically per session from a curated set of available free models; the mapping updates server-side as free model availability shifts.
{% callout type="warning" title="Data handling for Auto Free" %}
Auto Free may route your requests to providers that log prompts and outputs and use them to improve their services — including NVIDIA's free endpoints, which are provided under the [NVIDIA API Trial Terms of Service](https://assets.ngc.nvidia.com/products/api-catalog/legal/NVIDIA%20API%20Trial%20Terms%20of%20Service.pdf) (trial use only, not for production or sensitive data). Do not submit personal or confidential data when using Auto Free.
Auto Free may route your requests to providers that log prompts and outputs and use them to improve their services. Do not submit personal or confidential data when using Auto Free. In particular, it may route to NVIDIA's free endpoints (see NVIDIA Trial Terms of Service above).
{% /callout %}
### `kilo-auto/small`
packages/kilo-docs/pages/getting-started/using-kilo-for-free.md
+3 -1
View File
@@ -24,7 +24,9 @@ Kilo provides free models for coding tasks through the Kilo Gateway and partner
The easiest way to get started is [**Auto Free**](/docs/code-with-ai/agents/auto-model) (`kilo-auto/free`). This is a Kilo-provided model tier that automatically routes your requests to the best available free models — no configuration needed.
{% callout type="warning" title="Data handling for Auto Free" %}
Auto Free may route your requests to providers that log prompts and outputs and use them to improve their services — including NVIDIA's free endpoints, which are provided under the [NVIDIA API Trial Terms of Service](https://assets.ngc.nvidia.com/products/api-catalog/legal/NVIDIA%20API%20Trial%20Terms%20of%20Service.pdf) (trial use only, not for production or sensitive data). Do not submit personal or confidential data when using Auto Free.
Auto Free may route your requests to providers that log prompts and outputs and use them to improve their services. Do not submit personal or confidential data when using Auto Free. In particular, it may route to NVIDIA's free endpoints.
For NVIDIA free endpoints (Super/Ultra/etc): Trial use only - do not submit personal or confidential data. Your use is logged for security purposes and to improve NVIDIA products and services. The logged session data for improvement purposes is not linked to your identity or any persistent identifier. For more information about our data processing practices, see our [Privacy Policy](https://www.nvidia.com/en-us/about-nvidia/privacy-policy/). By interacting with this endpoint, you consent to our collection, recording, and use of such information and the [NVIDIA API Trial Terms of Service](https://assets.ngc.nvidia.com/products/api-catalog/legal/NVIDIA%20API%20Trial%20Terms%20of%20Service.pdf).
{% /callout %}
### Finding Other Free Models
packages/kilo-docs/previous-docs-redirects.js
+80 -2
View File
@@ -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,
},
packages/kilo-docs/public/img/kiloclaw/kiloclaw-architecture.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 321 KiB

packages/kilo-docs/public/img/npm-package-readme/kilo-cli.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 38 KiB

Some files were not shown because too many files have changed in this diff Show More