keycode-ai 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +85 -0
- package/LICENSE +201 -0
- package/README.md +547 -2
- package/dist/app/agent.d.ts +126 -0
- package/dist/app/agent.js +613 -0
- package/dist/app/agent.js.map +1 -0
- package/dist/app/commands.d.ts +15 -0
- package/dist/app/commands.js +281 -0
- package/dist/app/commands.js.map +1 -0
- package/dist/app/compact.d.ts +23 -0
- package/dist/app/compact.js +75 -0
- package/dist/app/compact.js.map +1 -0
- package/dist/app/export.d.ts +6 -0
- package/dist/app/export.js +56 -0
- package/dist/app/export.js.map +1 -0
- package/dist/app/factory.d.ts +106 -0
- package/dist/app/factory.js +687 -0
- package/dist/app/factory.js.map +1 -0
- package/dist/app/onboarding.d.ts +6 -0
- package/dist/app/onboarding.js +32 -0
- package/dist/app/onboarding.js.map +1 -0
- package/dist/app/subagent.d.ts +16 -0
- package/dist/app/subagent.js +14 -0
- package/dist/app/subagent.js.map +1 -0
- package/dist/app/trust.d.ts +6 -0
- package/dist/app/trust.js +74 -0
- package/dist/app/trust.js.map +1 -0
- package/dist/app/trustManifest.d.ts +18 -0
- package/dist/app/trustManifest.js +171 -0
- package/dist/app/trustManifest.js.map +1 -0
- package/dist/artifacts/store.d.ts +43 -0
- package/dist/artifacts/store.js +159 -0
- package/dist/artifacts/store.js.map +1 -0
- package/dist/cli/auth.d.ts +7 -0
- package/dist/cli/auth.js +68 -0
- package/dist/cli/auth.js.map +1 -0
- package/dist/cli/doctor.d.ts +19 -0
- package/dist/cli/doctor.js +205 -0
- package/dist/cli/doctor.js.map +1 -0
- package/dist/cli/extra.d.ts +2 -0
- package/dist/cli/extra.js +989 -0
- package/dist/cli/extra.js.map +1 -0
- package/dist/cli/headless.d.ts +20 -0
- package/dist/cli/headless.js +224 -0
- package/dist/cli/headless.js.map +1 -0
- package/dist/cli/index.d.ts +3 -0
- package/dist/cli/index.js +283 -0
- package/dist/cli/index.js.map +1 -0
- package/dist/contracts/message.d.ts +34 -0
- package/dist/contracts/message.js +10 -0
- package/dist/contracts/message.js.map +1 -0
- package/dist/contracts/permissions.d.ts +16 -0
- package/dist/contracts/permissions.js +9 -0
- package/dist/contracts/permissions.js.map +1 -0
- package/dist/contracts/provider.d.ts +65 -0
- package/dist/contracts/provider.js +2 -0
- package/dist/contracts/provider.js.map +1 -0
- package/dist/contracts/session.d.ts +101 -0
- package/dist/contracts/session.js +11 -0
- package/dist/contracts/session.js.map +1 -0
- package/dist/contracts/tool.d.ts +81 -0
- package/dist/contracts/tool.js +15 -0
- package/dist/contracts/tool.js.map +1 -0
- package/dist/core/budget.d.ts +11 -0
- package/dist/core/budget.js +22 -0
- package/dist/core/budget.js.map +1 -0
- package/dist/core/context.d.ts +27 -0
- package/dist/core/context.js +92 -0
- package/dist/core/context.js.map +1 -0
- package/dist/extensions/commands.d.ts +23 -0
- package/dist/extensions/commands.js +103 -0
- package/dist/extensions/commands.js.map +1 -0
- package/dist/extensions/customAgents.d.ts +19 -0
- package/dist/extensions/customAgents.js +85 -0
- package/dist/extensions/customAgents.js.map +1 -0
- package/dist/extensions/frontmatter.d.ts +6 -0
- package/dist/extensions/frontmatter.js +73 -0
- package/dist/extensions/frontmatter.js.map +1 -0
- package/dist/extensions/hooks.d.ts +63 -0
- package/dist/extensions/hooks.js +145 -0
- package/dist/extensions/hooks.js.map +1 -0
- package/dist/extensions/loops.d.ts +27 -0
- package/dist/extensions/loops.js +119 -0
- package/dist/extensions/loops.js.map +1 -0
- package/dist/extensions/plugins.d.ts +29 -0
- package/dist/extensions/plugins.js +119 -0
- package/dist/extensions/plugins.js.map +1 -0
- package/dist/extensions/skills.d.ts +21 -0
- package/dist/extensions/skills.js +89 -0
- package/dist/extensions/skills.js.map +1 -0
- package/dist/extensions/statusline.d.ts +13 -0
- package/dist/extensions/statusline.js +30 -0
- package/dist/extensions/statusline.js.map +1 -0
- package/dist/extensions/styles.d.ts +14 -0
- package/dist/extensions/styles.js +79 -0
- package/dist/extensions/styles.js.map +1 -0
- package/dist/extensions/teams.d.ts +44 -0
- package/dist/extensions/teams.js +79 -0
- package/dist/extensions/teams.js.map +1 -0
- package/dist/extensions/themes.d.ts +25 -0
- package/dist/extensions/themes.js +109 -0
- package/dist/extensions/themes.js.map +1 -0
- package/dist/extensions/workflows.d.ts +28 -0
- package/dist/extensions/workflows.js +65 -0
- package/dist/extensions/workflows.js.map +1 -0
- package/dist/gateway/index.d.ts +25 -0
- package/dist/gateway/index.js +125 -0
- package/dist/gateway/index.js.map +1 -0
- package/dist/integrations/background.d.ts +35 -0
- package/dist/integrations/background.js +167 -0
- package/dist/integrations/background.js.map +1 -0
- package/dist/integrations/browser.d.ts +36 -0
- package/dist/integrations/browser.js +80 -0
- package/dist/integrations/browser.js.map +1 -0
- package/dist/integrations/github.d.ts +44 -0
- package/dist/integrations/github.js +72 -0
- package/dist/integrations/github.js.map +1 -0
- package/dist/integrations/ide.d.ts +29 -0
- package/dist/integrations/ide.js +69 -0
- package/dist/integrations/ide.js.map +1 -0
- package/dist/integrations/import.d.ts +14 -0
- package/dist/integrations/import.js +76 -0
- package/dist/integrations/import.js.map +1 -0
- package/dist/integrations/playwrightDriver.d.ts +8 -0
- package/dist/integrations/playwrightDriver.js +70 -0
- package/dist/integrations/playwrightDriver.js.map +1 -0
- package/dist/integrations/pr.d.ts +23 -0
- package/dist/integrations/pr.js +81 -0
- package/dist/integrations/pr.js.map +1 -0
- package/dist/integrations/remote.d.ts +107 -0
- package/dist/integrations/remote.js +636 -0
- package/dist/integrations/remote.js.map +1 -0
- package/dist/integrations/runner.d.ts +30 -0
- package/dist/integrations/runner.js +56 -0
- package/dist/integrations/runner.js.map +1 -0
- package/dist/integrations/worktrees.d.ts +17 -0
- package/dist/integrations/worktrees.js +40 -0
- package/dist/integrations/worktrees.js.map +1 -0
- package/dist/integrations/ws.d.ts +9 -0
- package/dist/integrations/ws.js +102 -0
- package/dist/integrations/ws.js.map +1 -0
- package/dist/lsp/client.d.ts +51 -0
- package/dist/lsp/client.js +251 -0
- package/dist/lsp/client.js.map +1 -0
- package/dist/mcp/client.d.ts +56 -0
- package/dist/mcp/client.js +152 -0
- package/dist/mcp/client.js.map +1 -0
- package/dist/mcp/management.d.ts +20 -0
- package/dist/mcp/management.js +97 -0
- package/dist/mcp/management.js.map +1 -0
- package/dist/mcp/tools.d.ts +3 -0
- package/dist/mcp/tools.js +26 -0
- package/dist/mcp/tools.js.map +1 -0
- package/dist/notifications/index.d.ts +25 -0
- package/dist/notifications/index.js +63 -0
- package/dist/notifications/index.js.map +1 -0
- package/dist/permissions/audit.d.ts +25 -0
- package/dist/permissions/audit.js +58 -0
- package/dist/permissions/audit.js.map +1 -0
- package/dist/permissions/broker.d.ts +20 -0
- package/dist/permissions/broker.js +51 -0
- package/dist/permissions/broker.js.map +1 -0
- package/dist/permissions/dangerous.d.ts +7 -0
- package/dist/permissions/dangerous.js +42 -0
- package/dist/permissions/dangerous.js.map +1 -0
- package/dist/permissions/pipeline.d.ts +34 -0
- package/dist/permissions/pipeline.js +217 -0
- package/dist/permissions/pipeline.js.map +1 -0
- package/dist/permissions/prompt.d.ts +2 -0
- package/dist/permissions/prompt.js +33 -0
- package/dist/permissions/prompt.js.map +1 -0
- package/dist/permissions/rules.d.ts +7 -0
- package/dist/permissions/rules.js +176 -0
- package/dist/permissions/rules.js.map +1 -0
- package/dist/platform/index.d.ts +16 -0
- package/dist/platform/index.js +55 -0
- package/dist/platform/index.js.map +1 -0
- package/dist/privacy/index.d.ts +27 -0
- package/dist/privacy/index.js +98 -0
- package/dist/privacy/index.js.map +1 -0
- package/dist/providers/anthropic.d.ts +25 -0
- package/dist/providers/anthropic.js +225 -0
- package/dist/providers/anthropic.js.map +1 -0
- package/dist/providers/budget.d.ts +24 -0
- package/dist/providers/budget.js +47 -0
- package/dist/providers/budget.js.map +1 -0
- package/dist/providers/capabilities.d.ts +9 -0
- package/dist/providers/capabilities.js +39 -0
- package/dist/providers/capabilities.js.map +1 -0
- package/dist/providers/credentials.d.ts +21 -0
- package/dist/providers/credentials.js +81 -0
- package/dist/providers/credentials.js.map +1 -0
- package/dist/providers/fake.d.ts +32 -0
- package/dist/providers/fake.js +95 -0
- package/dist/providers/fake.js.map +1 -0
- package/dist/providers/openai.d.ts +27 -0
- package/dist/providers/openai.js +243 -0
- package/dist/providers/openai.js.map +1 -0
- package/dist/providers/presets.d.ts +20 -0
- package/dist/providers/presets.js +166 -0
- package/dist/providers/presets.js.map +1 -0
- package/dist/providers/registry.d.ts +27 -0
- package/dist/providers/registry.js +127 -0
- package/dist/providers/registry.js.map +1 -0
- package/dist/providers/retry.d.ts +22 -0
- package/dist/providers/retry.js +69 -0
- package/dist/providers/retry.js.map +1 -0
- package/dist/providers/sse.d.ts +5 -0
- package/dist/providers/sse.js +74 -0
- package/dist/providers/sse.js.map +1 -0
- package/dist/providers/textProtocol.d.ts +10 -0
- package/dist/providers/textProtocol.js +45 -0
- package/dist/providers/textProtocol.js.map +1 -0
- package/dist/questions/broker.d.ts +16 -0
- package/dist/questions/broker.js +40 -0
- package/dist/questions/broker.js.map +1 -0
- package/dist/sandbox/command.d.ts +20 -0
- package/dist/sandbox/command.js +296 -0
- package/dist/sandbox/command.js.map +1 -0
- package/dist/sandbox/index.d.ts +21 -0
- package/dist/sandbox/index.js +32 -0
- package/dist/sandbox/index.js.map +1 -0
- package/dist/sdk/index.d.ts +14 -0
- package/dist/sdk/index.js +57 -0
- package/dist/sdk/index.js.map +1 -0
- package/dist/sdk/structured.d.ts +7 -0
- package/dist/sdk/structured.js +66 -0
- package/dist/sdk/structured.js.map +1 -0
- package/dist/storage/autoMemory.d.ts +22 -0
- package/dist/storage/autoMemory.js +93 -0
- package/dist/storage/autoMemory.js.map +1 -0
- package/dist/storage/checkpoints.d.ts +15 -0
- package/dist/storage/checkpoints.js +86 -0
- package/dist/storage/checkpoints.js.map +1 -0
- package/dist/storage/memory.d.ts +21 -0
- package/dist/storage/memory.js +137 -0
- package/dist/storage/memory.js.map +1 -0
- package/dist/storage/schema.d.ts +177 -0
- package/dist/storage/schema.js +120 -0
- package/dist/storage/schema.js.map +1 -0
- package/dist/storage/session.d.ts +56 -0
- package/dist/storage/session.js +305 -0
- package/dist/storage/session.js.map +1 -0
- package/dist/storage/settings.d.ts +17 -0
- package/dist/storage/settings.js +150 -0
- package/dist/storage/settings.js.map +1 -0
- package/dist/telemetry/otel.d.ts +21 -0
- package/dist/telemetry/otel.js +71 -0
- package/dist/telemetry/otel.js.map +1 -0
- package/dist/tools/agent.d.ts +13 -0
- package/dist/tools/agent.js +45 -0
- package/dist/tools/agent.js.map +1 -0
- package/dist/tools/artifact.d.ts +31 -0
- package/dist/tools/artifact.js +137 -0
- package/dist/tools/artifact.js.map +1 -0
- package/dist/tools/bash.d.ts +29 -0
- package/dist/tools/bash.js +191 -0
- package/dist/tools/bash.js.map +1 -0
- package/dist/tools/codemode.d.ts +13 -0
- package/dist/tools/codemode.js +77 -0
- package/dist/tools/codemode.js.map +1 -0
- package/dist/tools/edit.d.ts +11 -0
- package/dist/tools/edit.js +128 -0
- package/dist/tools/edit.js.map +1 -0
- package/dist/tools/glob.d.ts +10 -0
- package/dist/tools/glob.js +33 -0
- package/dist/tools/glob.js.map +1 -0
- package/dist/tools/grep.d.ts +20 -0
- package/dist/tools/grep.js +143 -0
- package/dist/tools/grep.js.map +1 -0
- package/dist/tools/index.d.ts +11 -0
- package/dist/tools/index.js +47 -0
- package/dist/tools/index.js.map +1 -0
- package/dist/tools/lsp.d.ts +30 -0
- package/dist/tools/lsp.js +206 -0
- package/dist/tools/lsp.js.map +1 -0
- package/dist/tools/notebook.d.ts +19 -0
- package/dist/tools/notebook.js +83 -0
- package/dist/tools/notebook.js.map +1 -0
- package/dist/tools/powershell.d.ts +10 -0
- package/dist/tools/powershell.js +83 -0
- package/dist/tools/powershell.js.map +1 -0
- package/dist/tools/question.d.ts +15 -0
- package/dist/tools/question.js +50 -0
- package/dist/tools/question.js.map +1 -0
- package/dist/tools/read.d.ts +10 -0
- package/dist/tools/read.js +188 -0
- package/dist/tools/read.js.map +1 -0
- package/dist/tools/shared.d.ts +8 -0
- package/dist/tools/shared.js +35 -0
- package/dist/tools/shared.js.map +1 -0
- package/dist/tools/skill.d.ts +9 -0
- package/dist/tools/skill.js +38 -0
- package/dist/tools/skill.js.map +1 -0
- package/dist/tools/tasks.d.ts +35 -0
- package/dist/tools/tasks.js +139 -0
- package/dist/tools/tasks.js.map +1 -0
- package/dist/tools/todo.d.ts +27 -0
- package/dist/tools/todo.js +40 -0
- package/dist/tools/todo.js.map +1 -0
- package/dist/tools/walk.d.ts +15 -0
- package/dist/tools/walk.js +144 -0
- package/dist/tools/walk.js.map +1 -0
- package/dist/tools/webfetch.d.ts +22 -0
- package/dist/tools/webfetch.js +201 -0
- package/dist/tools/webfetch.js.map +1 -0
- package/dist/tools/websearch.d.ts +33 -0
- package/dist/tools/websearch.js +129 -0
- package/dist/tools/websearch.js.map +1 -0
- package/dist/tools/write.d.ts +8 -0
- package/dist/tools/write.js +51 -0
- package/dist/tools/write.js.map +1 -0
- package/dist/tui/accessibility.d.ts +4 -0
- package/dist/tui/accessibility.js +24 -0
- package/dist/tui/accessibility.js.map +1 -0
- package/dist/tui/app.d.ts +21 -0
- package/dist/tui/app.js +280 -0
- package/dist/tui/app.js.map +1 -0
- package/dist/tui/format.d.ts +22 -0
- package/dist/tui/format.js +91 -0
- package/dist/tui/format.js.map +1 -0
- package/dist/tui/input.d.ts +9 -0
- package/dist/tui/input.js +71 -0
- package/dist/tui/input.js.map +1 -0
- package/dist/tui/permission.d.ts +2 -0
- package/dist/tui/permission.js +2 -0
- package/dist/tui/permission.js.map +1 -0
- package/dist/updates/index.d.ts +33 -0
- package/dist/updates/index.js +60 -0
- package/dist/updates/index.js.map +1 -0
- package/dist/util/clipboard.d.ts +1 -0
- package/dist/util/clipboard.js +30 -0
- package/dist/util/clipboard.js.map +1 -0
- package/dist/util/clock.d.ts +7 -0
- package/dist/util/clock.js +6 -0
- package/dist/util/clock.js.map +1 -0
- package/dist/util/errors.d.ts +19 -0
- package/dist/util/errors.js +64 -0
- package/dist/util/errors.js.map +1 -0
- package/dist/util/fsx.d.ts +4 -0
- package/dist/util/fsx.js +35 -0
- package/dist/util/fsx.js.map +1 -0
- package/dist/util/ids.d.ts +5 -0
- package/dist/util/ids.js +17 -0
- package/dist/util/ids.js.map +1 -0
- package/dist/util/logger.d.ts +13 -0
- package/dist/util/logger.js +23 -0
- package/dist/util/logger.js.map +1 -0
- package/dist/util/paths.d.ts +14 -0
- package/dist/util/paths.js +77 -0
- package/dist/util/paths.js.map +1 -0
- package/dist/util/redact.d.ts +6 -0
- package/dist/util/redact.js +44 -0
- package/dist/util/redact.js.map +1 -0
- package/dist/util/text.d.ts +4 -0
- package/dist/util/text.js +23 -0
- package/dist/util/text.js.map +1 -0
- package/dist/web/public/app.js +917 -0
- package/dist/web/public/favicon.svg +5 -0
- package/dist/web/public/index.html +197 -0
- package/dist/web/public/markdown.js +176 -0
- package/dist/web/public/styles.css +1245 -0
- package/package.json +55 -4
package/README.md
CHANGED
|
@@ -1,3 +1,548 @@
|
|
|
1
|
-
#
|
|
1
|
+
# KeyCode
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A free, local-first, bring-your-own-key coding agent for the terminal.
|
|
4
|
+
|
|
5
|
+
`KeyCode` is a clean-room reimplementation of the observable workflow of Claude
|
|
6
|
+
Code v2.1.322. It is not affiliated with Anthropic and does not require an
|
|
7
|
+
Anthropic account.
|
|
8
|
+
|
|
9
|
+
**Status:** working alpha. All 90 features have passing acceptance tests. Install
|
|
10
|
+
from a local tarball or run from `dist/`; no registry package yet.
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## Why
|
|
15
|
+
|
|
16
|
+
Coding agents should not require a subscription to be useful. `KeyCode` is built
|
|
17
|
+
around three rules:
|
|
18
|
+
|
|
19
|
+
1. **Free by default.** Every feature works with a free-tier API key or a local
|
|
20
|
+
model.
|
|
21
|
+
2. **Bring your own key.** No shared keys, no proxy, no account required.
|
|
22
|
+
3. **Local-first.** Your code, prompts, and sessions stay on your machine
|
|
23
|
+
unless you choose a hosted provider.
|
|
24
|
+
|
|
25
|
+
See `FEATURES.md` for the full free-key matrix.
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## Install
|
|
30
|
+
|
|
31
|
+
The npm package name is `keycode-ai`, but it is not published to the registry
|
|
32
|
+
yet. Build a tarball and install it globally:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
npm install
|
|
36
|
+
npm run pack:smoke # verifies the tarball in a clean consumer project
|
|
37
|
+
npm pack
|
|
38
|
+
npm install -g ./keycode-ai-0.1.0.tgz
|
|
39
|
+
keycode --version
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Or link the working tree while developing:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
npm install
|
|
46
|
+
npm run build
|
|
47
|
+
npm link
|
|
48
|
+
keycode --version
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Run without installing:
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
npm install
|
|
55
|
+
npm run build
|
|
56
|
+
node dist/cli/index.js --provider ollama
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
### Upgrade and remove
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
npm install -g ./keycode-ai-<new-version>.tgz
|
|
63
|
+
npm uninstall -g keycode-ai
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
The package ships `dist/`, `README.md`, `LICENSE`, and `CHANGELOG.md` only.
|
|
67
|
+
Tests, sources, and `node_modules` are excluded. `scripts/validate-package.mjs`
|
|
68
|
+
checks the bin mapping, version, shebang, and license. CI runs `npm run verify`
|
|
69
|
+
on Windows, macOS, and Linux with Node 22 and 24, plus a tarball install test.
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## Quickstart
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
# Option A: a free hosted key (macOS/Linux)
|
|
77
|
+
export GEMINI_API_KEY="your-key"
|
|
78
|
+
keycode --provider gemini --model gemini-2.5-flash
|
|
79
|
+
|
|
80
|
+
# Option A on Windows PowerShell
|
|
81
|
+
$env:GEMINI_API_KEY="your-key"
|
|
82
|
+
keycode --provider gemini --model gemini-2.5-flash
|
|
83
|
+
|
|
84
|
+
# Option B: a local model, no key
|
|
85
|
+
ollama serve
|
|
86
|
+
ollama pull gemma4:e2b
|
|
87
|
+
keycode --provider ollama --model gemma4:e2b
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Then, inside the TUI:
|
|
91
|
+
|
|
92
|
+
```
|
|
93
|
+
> explain this repository and run the tests
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
If you run from source instead, replace `keycode` with
|
|
97
|
+
`node dist/cli/index.js`.
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## Model guidance
|
|
102
|
+
|
|
103
|
+
Native tool calling produces the most reliable results. Free and local options:
|
|
104
|
+
|
|
105
|
+
| Provider | Recommended | Notes |
|
|
106
|
+
|---|---|---|
|
|
107
|
+
| Ollama | `qwen3-coder`, `llama3.1` | Best local tool use. `gemma4:e2b` is the smallest default; it can stop early or repeat work. |
|
|
108
|
+
| LM Studio / llama.cpp | Qwen3-Coder, Devstral | Pick a model whose template supports tools. |
|
|
109
|
+
| Gemini | `gemini-2.5-flash` | Large context, strong tool use. |
|
|
110
|
+
| Groq | `llama-3.3-70b-versatile`, `openai/gpt-oss-120b` | Fast; no vision. |
|
|
111
|
+
| OpenRouter | `qwen/qwen3-coder:free` | Free tier rates vary. |
|
|
112
|
+
| Cerebras | `qwen-3-32b` | Fast; no vision. |
|
|
113
|
+
| Mistral | `mistral-small-latest`, `codestral-latest` | |
|
|
114
|
+
| GitHub Models | `openai/gpt-4o-mini`, `openai/gpt-4.1` | |
|
|
115
|
+
|
|
116
|
+
The agent protects against common small-model failures:
|
|
117
|
+
|
|
118
|
+
- **Repeated calls:** three consecutive identical tool calls are blocked with
|
|
119
|
+
`REPEATED_TOOL_CALL` so the model must verify or finish.
|
|
120
|
+
- **Already-applied edits:** `Edit` returns a successful no-op instead of
|
|
121
|
+
failing and provoking a retry loop.
|
|
122
|
+
- **No native tools:** when a model declares `tools: false`, KeyCode appends a
|
|
123
|
+
documented text protocol to the prompt and parses this fenced block:
|
|
124
|
+
|
|
125
|
+
````text
|
|
126
|
+
```keycode-tool
|
|
127
|
+
{"name":"Read","input":{"file_path":"src/index.ts"}}
|
|
128
|
+
```
|
|
129
|
+
````
|
|
130
|
+
|
|
131
|
+
Native tool calls are always preferred; the text protocol is a fallback and
|
|
132
|
+
still goes through the permission pipeline.
|
|
133
|
+
|
|
134
|
+
If a model claims work is done without calling tools, ask it to verify with a
|
|
135
|
+
tool, or switch to a tool-capable model.
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## Release
|
|
140
|
+
|
|
141
|
+
Tag a commit with `v<version>` and push the tag. The release workflow reruns
|
|
142
|
+
`npm run verify` and `npm run pack:smoke`, packs the tarball, writes
|
|
143
|
+
`SHA256SUMS`, and attaches both to a GitHub release.
|
|
144
|
+
|
|
145
|
+
The npm package is `keycode-ai`; the executable is `keycode`. Publishing uses
|
|
146
|
+
the **Publish npm** workflow with an `NPM_TOKEN` secret, or a local
|
|
147
|
+
`npm publish --provenance --access public`. See `docs/releasing.md` and
|
|
148
|
+
`docs/install.md`.
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
## Web UI
|
|
153
|
+
|
|
154
|
+
`keycode remote` serves a local browser interface:
|
|
155
|
+
|
|
156
|
+
```powershell
|
|
157
|
+
keycode remote --provider ollama
|
|
158
|
+
# Remote Control: http://127.0.0.1:<port>/#token=...
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
Add `--open` to launch the default browser automatically. If the pairing dialog
|
|
162
|
+
appears, paste either the token or the full printed URL.
|
|
163
|
+
|
|
164
|
+
Open the printed URL. The interface supports:
|
|
165
|
+
|
|
166
|
+
- streamed replies and tool rows,
|
|
167
|
+
- neon glass theme with a grid background, SVG tool icons, and reduced-motion support,
|
|
168
|
+
- Markdown rendering, fenced code blocks, and copy buttons,
|
|
169
|
+
- edit and write diffs in the approval dialog,
|
|
170
|
+
- multiple-choice `AskUserQuestion` dialogs with radio/checkbox options and free-form answers,
|
|
171
|
+
- allow once / always / session / deny / cancel,
|
|
172
|
+
- session list, new session, resume with history, rename, fork, and delete,
|
|
173
|
+
- artifact panel with versioned HTML previews rendered inside the UI,
|
|
174
|
+
- provider/model switching that keeps the current session,
|
|
175
|
+
- editor context from the VS Code extension: active file and selection shown
|
|
176
|
+
above the composer and attached to prompts; **Detach** clears it,
|
|
177
|
+
- stop and reconnect,
|
|
178
|
+
- pairing by token, with the server bound to loopback only.
|
|
179
|
+
|
|
180
|
+
Static assets are public, but every conversation action and the WebSocket
|
|
181
|
+
require the token. The page reads it from the URL fragment, so it is not sent
|
|
182
|
+
with static file requests or written to logs; the WebSocket handshake sends it
|
|
183
|
+
once as a query parameter. `--permission-mode` defaults to `manual`, since
|
|
184
|
+
approvals happen in the browser.
|
|
185
|
+
|
|
186
|
+
If the token is lost, stop the server and run the command again; a new token is
|
|
187
|
+
generated. Pass `--token <value>` to reuse one on a trusted loopback setup.
|
|
188
|
+
|
|
189
|
+
---
|
|
190
|
+
|
|
191
|
+
## VS Code
|
|
192
|
+
|
|
193
|
+
`editors/vscode` contains an extension that starts `keycode remote` and opens the
|
|
194
|
+
same web UI in a VS Code editor tab.
|
|
195
|
+
|
|
196
|
+
```powershell
|
|
197
|
+
cd editors/vscode
|
|
198
|
+
npx @vscode/vsce package
|
|
199
|
+
code --install-extension keycode-vscode-0.1.0.vsix
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Then run **KeyCode: Open Chat** from the Command Palette. The extension has
|
|
203
|
+
settings for executable, provider, model, permission mode, working directory,
|
|
204
|
+
and whether to open in an editor tab or the external browser. The server is
|
|
205
|
+
stopped when the extension deactivates.
|
|
206
|
+
|
|
207
|
+
The extension is plain CommonJS, so there is no build step. It requires the
|
|
208
|
+
KeyCode CLI on `PATH` or an absolute `keycode.executable`. `npm run
|
|
209
|
+
extension:smoke` loads the extension with a mocked VS Code API and verifies the
|
|
210
|
+
real server launch in a temp workspace.
|
|
211
|
+
|
|
212
|
+
---
|
|
213
|
+
|
|
214
|
+
## Language servers
|
|
215
|
+
|
|
216
|
+
When language servers are configured, the agent gets an `LSP` tool for
|
|
217
|
+
diagnostics, hover, definition, and references:
|
|
218
|
+
|
|
219
|
+
```json
|
|
220
|
+
{
|
|
221
|
+
"lsp": {
|
|
222
|
+
"typescript": { "command": "typescript-language-server", "args": ["--stdio"] },
|
|
223
|
+
"python": { "command": "pyright-langserver", "args": ["--stdio"] }
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
Servers are started on first use and keyed by language id. The tool resolves
|
|
229
|
+
`.ts`, `.tsx`, `.js`, `.py`, `.rs`, `.go`, `.java`, `.c`, `.cpp`, `.json`,
|
|
230
|
+
`.md`, `.css`, `.html`, `.sh`, and `.ps1`, and accepts a `"*"` fallback. Line
|
|
231
|
+
and character inputs are 1-based. Requests time out; a failing server returns an
|
|
232
|
+
error result instead of breaking the turn.
|
|
233
|
+
|
|
234
|
+
KeyCode does not bundle language servers. Install them separately or point at
|
|
235
|
+
an absolute path. For TypeScript projects without a local `typescript`
|
|
236
|
+
installation, point the server at a `tsserver.js`:
|
|
237
|
+
|
|
238
|
+
```json
|
|
239
|
+
{
|
|
240
|
+
"lsp": {
|
|
241
|
+
"typescript": {
|
|
242
|
+
"command": "typescript-language-server",
|
|
243
|
+
"args": ["--stdio"],
|
|
244
|
+
"initializationOptions": {
|
|
245
|
+
"tsserver": { "path": "C:/Users/me/AppData/Roaming/npm/node_modules/typescript/lib/tsserver.js" }
|
|
246
|
+
}
|
|
247
|
+
}
|
|
248
|
+
}
|
|
249
|
+
}
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
`--bare` and `--safe-mode` skip LSP; `--restricted` removes the `LSP` tool.
|
|
253
|
+
LSP settings are ignored in untrusted workspaces.
|
|
254
|
+
|
|
255
|
+
---
|
|
256
|
+
|
|
257
|
+
## Artifacts, browser, and Code Mode
|
|
258
|
+
|
|
259
|
+
These are agent tools, not CLI-only features.
|
|
260
|
+
|
|
261
|
+
**Artifacts** are enabled by default. The `Artifact` tool can create, update,
|
|
262
|
+
list, inspect, comment on, set data for, and preview versioned local HTML files.
|
|
263
|
+
Previews bind to loopback and require a token. Disable them with:
|
|
264
|
+
|
|
265
|
+
```json
|
|
266
|
+
{ "artifacts": { "enabled": false } }
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
**Code Mode** is opt-in. Enable it with:
|
|
270
|
+
|
|
271
|
+
```json
|
|
272
|
+
{ "codeMode": true }
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
It runs JavaScript in a `node:vm` context with a persistent `state` object, a
|
|
276
|
+
`console.log` bridge, and `tools.call(name, input)`. It is permission-gated and
|
|
277
|
+
is not a security boundary.
|
|
278
|
+
|
|
279
|
+
**Browser** automation works out of the box through `playwright-core` and an
|
|
280
|
+
installed Chrome:
|
|
281
|
+
|
|
282
|
+
```json
|
|
283
|
+
{
|
|
284
|
+
"browser": {
|
|
285
|
+
"enabled": true,
|
|
286
|
+
"allowedDomains": ["example.com", "docs.example.com"],
|
|
287
|
+
"headless": true
|
|
288
|
+
}
|
|
289
|
+
}
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
Set `channel` (default `chrome`), `executablePath`, `headless`, and `timeoutMs`
|
|
293
|
+
as needed. The driver launches lazily on the first navigation and closes with
|
|
294
|
+
the session.
|
|
295
|
+
|
|
296
|
+
A custom driver module is still supported:
|
|
297
|
+
|
|
298
|
+
```json
|
|
299
|
+
{
|
|
300
|
+
"browser": {
|
|
301
|
+
"driver": "./browser-driver.mjs",
|
|
302
|
+
"allowedDomains": ["example.com"]
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
The module must export `createBrowserDriver(options)` or a default driver with
|
|
308
|
+
`navigate`, `click`, `type`, `readDom`, `screenshot`, and optional `close`.
|
|
309
|
+
Origins outside the allowlist are denied before the driver is called. Browser
|
|
310
|
+
settings are ignored in untrusted workspaces. `--restricted` removes the tool.
|
|
311
|
+
|
|
312
|
+
---
|
|
313
|
+
|
|
314
|
+
## Workspace trust
|
|
315
|
+
|
|
316
|
+
Project settings can run hooks, MCP servers, language servers, browser drivers,
|
|
317
|
+
and commands, and can add permission rules. Before any of that applies, KeyCode
|
|
318
|
+
shows a review:
|
|
319
|
+
|
|
320
|
+
- TUI: a terminal prompt lists each item and asks for approval.
|
|
321
|
+
- Web UI and VS Code: a project-trust banner opens a review dialog with
|
|
322
|
+
**Keep restricted** and **Trust workspace**.
|
|
323
|
+
|
|
324
|
+
The review lists:
|
|
325
|
+
|
|
326
|
+
- permission `allow`/`ask` rules,
|
|
327
|
+
- hook commands by event,
|
|
328
|
+
- MCP servers with their command or URL,
|
|
329
|
+
- LSP commands,
|
|
330
|
+
- browser driver modules,
|
|
331
|
+
- environment keys,
|
|
332
|
+
- project commands, skills, agents, and output styles with content hashes.
|
|
333
|
+
|
|
334
|
+
Approval is stored in `~/.keycode/trust.json` with a fingerprint. If any
|
|
335
|
+
project-controlled item changes, KeyCode asks again instead of silently applying
|
|
336
|
+
the new configuration.
|
|
337
|
+
|
|
338
|
+
Headless runs cannot prompt, so they stay restricted unless you pass `--trust`.
|
|
339
|
+
Untrusted project settings are ignored.
|
|
340
|
+
|
|
341
|
+
---
|
|
342
|
+
|
|
343
|
+
## Runtime operations
|
|
344
|
+
|
|
345
|
+
**Auto-memory** extraction is scheduled after every fifth completed turn by
|
|
346
|
+
default. Change it with `autoMemoryEvery`, or disable it with
|
|
347
|
+
`"autoMemory": false`. A fact is stored only when the model returns a durable
|
|
348
|
+
sentence; paused memory skips extraction and recall.
|
|
349
|
+
|
|
350
|
+
**Notifications** support a webhook and optional terminal OSC/bell:
|
|
351
|
+
|
|
352
|
+
```json
|
|
353
|
+
{
|
|
354
|
+
"notifications": {
|
|
355
|
+
"webhook": "http://127.0.0.1:9999/notify",
|
|
356
|
+
"terminal": false,
|
|
357
|
+
"dedupeMs": 5000
|
|
358
|
+
}
|
|
359
|
+
}
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
Events include `permission_required`, `input_needed`, and `task_complete`.
|
|
363
|
+
Webhook payloads contain `{ event, text, timestamp }`.
|
|
364
|
+
|
|
365
|
+
**OpenTelemetry** requires explicit privacy consent:
|
|
366
|
+
|
|
367
|
+
```json
|
|
368
|
+
{
|
|
369
|
+
"otel": {
|
|
370
|
+
"endpoint": "http://127.0.0.1:4318/v1/metrics",
|
|
371
|
+
"serviceName": "keycode",
|
|
372
|
+
"sampleRate": 1
|
|
373
|
+
}
|
|
374
|
+
}
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
Metrics are emitted for turns, input/output tokens, cost, and tool-call counts.
|
|
378
|
+
`telemetryEnabled()` still honors `privacy.json`, `KEYCODE_TELEMETRY=0`, and
|
|
379
|
+
`DO_NOT_TRACK=1`; without consent, no metrics are recorded.
|
|
380
|
+
|
|
381
|
+
---
|
|
382
|
+
|
|
383
|
+
## Security checks
|
|
384
|
+
|
|
385
|
+
- **WebFetch** resolves each hostname before requesting it and blocks results in
|
|
386
|
+
loopback, private, link-local, CGNAT, documentation, benchmark, multicast, and
|
|
387
|
+
metadata ranges. Redirects are re-validated with a fresh DNS lookup. An
|
|
388
|
+
explicitly allowlisted host bypasses these checks.
|
|
389
|
+
- **Write** and **Edit** scan content for common credentials before touching
|
|
390
|
+
disk. A new AWS, GitHub, Slack, Anthropic, OpenAI, Google, Groq, bearer, or
|
|
391
|
+
generic `api_key`/`token`/`secret`/`password` value is refused with
|
|
392
|
+
`SECRET_DETECTED`. Editing a file that already contains a credential is
|
|
393
|
+
allowed as long as the edit does not add another.
|
|
394
|
+
- **Audit logs** and transcripts continue to redact known secret formats.
|
|
395
|
+
|
|
396
|
+
DNS checks reduce SSRF risk but do not eliminate DNS rebinding between the check
|
|
397
|
+
and the connection; a pinned-IP transport is still future work.
|
|
398
|
+
|
|
399
|
+
---
|
|
400
|
+
|
|
401
|
+
## Permissions
|
|
402
|
+
|
|
403
|
+
Every tool call goes through one permission pipeline, including MCP tools.
|
|
404
|
+
|
|
405
|
+
- **Modes:** `manual` (default), `acceptEdits`, `plan`, `auto`, `dontAsk`,
|
|
406
|
+
`bypassPermissions`.
|
|
407
|
+
- **TUI:** when a tool needs approval, a dialog shows the request with a
|
|
408
|
+
command preview or an edit diff. Choose allow once / allow always / allow for
|
|
409
|
+
session / deny / cancel.
|
|
410
|
+
- **Headless:** there is no prompt, so an unapproved call is denied and the
|
|
411
|
+
result names the exact rule to add, for example:
|
|
412
|
+
`Add --allow "Bash(npm test)" or run interactively.`
|
|
413
|
+
- **Rules:** repeatable and evaluated deny → ask → allow:
|
|
414
|
+
|
|
415
|
+
```bash
|
|
416
|
+
node dist/cli/index.js --provider ollama \
|
|
417
|
+
--deny "Read(./.env)" \
|
|
418
|
+
--allow "Bash(npm test:*)" \
|
|
419
|
+
--allow "Edit(src/**)" \
|
|
420
|
+
-p "run the tests and fix failures"
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
A command rule without `:*` matches exactly, so `Bash(npm test)` does not
|
|
424
|
+
allow `npm test; curl ...`. Use `Bash(npm test:*)` to allow that command with
|
|
425
|
+
any arguments, or a glob such as `Bash(git *)` to opt into a family of
|
|
426
|
+
commands. Allow rules never extend to compound shell commands unless the rule
|
|
427
|
+
itself contains the operator.
|
|
428
|
+
|
|
429
|
+
`allow always` in the TUI persists a specific rule (command or path), not a
|
|
430
|
+
whole-tool grant.
|
|
431
|
+
|
|
432
|
+
---
|
|
433
|
+
|
|
434
|
+
## Sandbox
|
|
435
|
+
|
|
436
|
+
`--sandbox` confines commands to the workspace roots (plus `--add-dir` roots)
|
|
437
|
+
and blocks network egress by default.
|
|
438
|
+
|
|
439
|
+
```bash
|
|
440
|
+
node dist/cli/index.js --provider ollama --sandbox -p "run the tests"
|
|
441
|
+
node dist/cli/index.js --sandbox --sandbox-network --sandbox-allow-host api.example.com ...
|
|
442
|
+
```
|
|
443
|
+
|
|
444
|
+
Or in `settings.json`:
|
|
445
|
+
|
|
446
|
+
```json
|
|
447
|
+
{
|
|
448
|
+
"sandbox": { "enabled": true, "allowNetwork": false, "allowedHosts": ["api.example.com"] }
|
|
449
|
+
}
|
|
450
|
+
```
|
|
451
|
+
|
|
452
|
+
The JSON above belongs in a settings file, not in a PowerShell prompt:
|
|
453
|
+
`~/.keycode/settings.json` (all projects), `.keycode/settings.json` (project),
|
|
454
|
+
or `.keycode/settings.local.json` (local). Project layers only apply when the
|
|
455
|
+
workspace is trusted.
|
|
456
|
+
|
|
457
|
+
Enforcement:
|
|
458
|
+
|
|
459
|
+
- **macOS:** wraps commands with `/usr/bin/sandbox-exec` and a Seatbelt profile
|
|
460
|
+
that denies writes outside the roots and denies network unless allowed.
|
|
461
|
+
- **Linux:** wraps commands with `bwrap` (`--unshare-net`, read-only root,
|
|
462
|
+
writable workspace roots) when installed.
|
|
463
|
+
- **Windows (fallback):** no kernel sandbox. A static guard blocks redirection,
|
|
464
|
+
common write commands, and known network commands that target paths outside
|
|
465
|
+
the roots or hosts outside the allowlist, and startup prints the documented
|
|
466
|
+
fallback warning. Commands that perform I/O indirectly (for example a script
|
|
467
|
+
launched by an interpreter) are not contained by this fallback.
|
|
468
|
+
|
|
469
|
+
The guard also runs before every command on all platforms, so an approved
|
|
470
|
+
`bypassPermissions` command still cannot redirect output outside the roots.
|
|
471
|
+
|
|
472
|
+
Process-count and memory limits are not enforced yet.
|
|
473
|
+
|
|
474
|
+
---
|
|
475
|
+
|
|
476
|
+
## MCP servers
|
|
477
|
+
|
|
478
|
+
Enabled entries in `settings.json` under `mcpServers` (stdio or HTTP/SSE) are
|
|
479
|
+
connected on startup and exposed as `mcp__<server>__<tool>` tools. A failing
|
|
480
|
+
server produces a warning and does not abort the session.
|
|
481
|
+
|
|
482
|
+
```json
|
|
483
|
+
{
|
|
484
|
+
"mcpServers": {
|
|
485
|
+
"docs": { "type": "stdio", "command": "node", "args": ["server.mjs"] }
|
|
486
|
+
}
|
|
487
|
+
}
|
|
488
|
+
```
|
|
489
|
+
|
|
490
|
+
---
|
|
491
|
+
|
|
492
|
+
## Documents
|
|
493
|
+
|
|
494
|
+
| File | Purpose |
|
|
495
|
+
|---|---|
|
|
496
|
+
| `AGENTS.md` | Rules for coding agents: clean-room, safety, tests, git, definition of done. |
|
|
497
|
+
| `FEATURES.md` | Scope, free-key policy, provider matrix, parity decisions, non-goals. |
|
|
498
|
+
| `SPEC.md` | Architecture, contracts, all 90 features, one acceptance test each, three-part build plan. |
|
|
499
|
+
| `EVIDENCE.md` | Provenance: target hash, extraction method, observations, limitations. |
|
|
500
|
+
|
|
501
|
+
---
|
|
502
|
+
|
|
503
|
+
## The 90 features
|
|
504
|
+
|
|
505
|
+
| Domain | Count |
|
|
506
|
+
|---|---:|
|
|
507
|
+
| Core runtime | 10 |
|
|
508
|
+
| Providers and free keys | 9 |
|
|
509
|
+
| Tools | 19 |
|
|
510
|
+
| Safety | 9 |
|
|
511
|
+
| Memory and context | 7 |
|
|
512
|
+
| Extensibility | 12 |
|
|
513
|
+
| Integrations | 10 |
|
|
514
|
+
| User experience | 8 |
|
|
515
|
+
| Platform and operations | 6 |
|
|
516
|
+
| **Total** | **90** |
|
|
517
|
+
|
|
518
|
+
Each feature has exactly one acceptance test, named `T-<feature ID>`.
|
|
519
|
+
|
|
520
|
+
---
|
|
521
|
+
|
|
522
|
+
## Build plan
|
|
523
|
+
|
|
524
|
+
1. **Part 1 — Free key, real work (weeks 1-4).** REPL, sessions, streaming,
|
|
525
|
+
free providers, core tools, permissions, memory, basic TUI.
|
|
526
|
+
2. **Part 2 — Extensible and safe (weeks 5-8).** Web, MCP, LSP, subagents,
|
|
527
|
+
sandbox, hooks, skills, agents, plugins, teams, workflows, telemetry.
|
|
528
|
+
3. **Part 3 — Scale and integrate (weeks 9-12).** SDK, GitHub, IDE, browser,
|
|
529
|
+
Remote Control, self-hosted runner, background sessions, worktrees, release.
|
|
530
|
+
|
|
531
|
+
Details and exit gates are in `SPEC.md` section 12.
|
|
532
|
+
|
|
533
|
+
---
|
|
534
|
+
|
|
535
|
+
## Validate the spec
|
|
536
|
+
|
|
537
|
+
```bash
|
|
538
|
+
npm run validate:spec
|
|
539
|
+
```
|
|
540
|
+
|
|
541
|
+
This checks that all 90 features have unique IDs, exactly one matching test,
|
|
542
|
+
and a valid build part.
|
|
543
|
+
|
|
544
|
+
---
|
|
545
|
+
|
|
546
|
+
## License
|
|
547
|
+
|
|
548
|
+
Apache-2.0. See `LICENSE`.
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
import type { Usage } from "../contracts/message.js";
|
|
2
|
+
import type { ModelCapabilities, Provider, StopReason } from "../contracts/provider.js";
|
|
3
|
+
import type { Question, QuestionResult, Tool, ToolState } from "../contracts/tool.js";
|
|
4
|
+
import type { SessionStore } from "../storage/session.js";
|
|
5
|
+
import type { CheckpointStore, RewindMode } from "../storage/checkpoints.js";
|
|
6
|
+
import type { PermissionService } from "../permissions/pipeline.js";
|
|
7
|
+
import type { SandboxPolicy } from "../sandbox/index.js";
|
|
8
|
+
import type { BudgetGuard, Pricing } from "../providers/budget.js";
|
|
9
|
+
import { type Clock } from "../util/clock.js";
|
|
10
|
+
import { type Logger } from "../util/logger.js";
|
|
11
|
+
import { type CompactResult } from "./compact.js";
|
|
12
|
+
import type { HookDispatcher } from "../extensions/hooks.js";
|
|
13
|
+
export type AgentEvent = {
|
|
14
|
+
type: "text";
|
|
15
|
+
delta: string;
|
|
16
|
+
} | {
|
|
17
|
+
type: "thinking";
|
|
18
|
+
delta: string;
|
|
19
|
+
} | {
|
|
20
|
+
type: "tool_start";
|
|
21
|
+
id: string;
|
|
22
|
+
name: string;
|
|
23
|
+
input: unknown;
|
|
24
|
+
} | {
|
|
25
|
+
type: "tool_result";
|
|
26
|
+
id: string;
|
|
27
|
+
name: string;
|
|
28
|
+
ok: boolean;
|
|
29
|
+
text: string;
|
|
30
|
+
} | {
|
|
31
|
+
type: "usage";
|
|
32
|
+
inputTokens: number;
|
|
33
|
+
outputTokens: number;
|
|
34
|
+
cachedTokens?: number | undefined;
|
|
35
|
+
} | {
|
|
36
|
+
type: "done";
|
|
37
|
+
stopReason: StopReason;
|
|
38
|
+
} | {
|
|
39
|
+
type: "error";
|
|
40
|
+
error: unknown;
|
|
41
|
+
};
|
|
42
|
+
export interface AgentOptions {
|
|
43
|
+
sessionId: string;
|
|
44
|
+
store: SessionStore;
|
|
45
|
+
provider: Provider;
|
|
46
|
+
providerId: string;
|
|
47
|
+
model: string;
|
|
48
|
+
tools: Tool[];
|
|
49
|
+
permissions: PermissionService;
|
|
50
|
+
home: string;
|
|
51
|
+
cwd: string;
|
|
52
|
+
workspaceRoots: string[];
|
|
53
|
+
sandbox?: SandboxPolicy | undefined;
|
|
54
|
+
systemPrompt: string;
|
|
55
|
+
buildPrompt?: (() => string) | undefined;
|
|
56
|
+
clock?: Clock | undefined;
|
|
57
|
+
logger?: Logger | undefined;
|
|
58
|
+
budget?: BudgetGuard | undefined;
|
|
59
|
+
pricing?: Pricing | undefined;
|
|
60
|
+
capabilities?: ModelCapabilities | undefined;
|
|
61
|
+
autoCompactThreshold?: number | undefined;
|
|
62
|
+
effort?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
|
|
63
|
+
maxToolCalls?: number | undefined;
|
|
64
|
+
fallback?: {
|
|
65
|
+
provider: Provider;
|
|
66
|
+
model: string;
|
|
67
|
+
} | undefined;
|
|
68
|
+
checkpointStore?: CheckpointStore | undefined;
|
|
69
|
+
askQuestions?: ((questions: Question[]) => Promise<QuestionResult>) | undefined;
|
|
70
|
+
onEvent?: ((event: AgentEvent) => void) | undefined;
|
|
71
|
+
hooks?: HookDispatcher | undefined;
|
|
72
|
+
onTurnComplete?: ((result: TurnResult, signal: AbortSignal) => Promise<void> | void) | undefined;
|
|
73
|
+
}
|
|
74
|
+
export interface TurnResult {
|
|
75
|
+
text: string;
|
|
76
|
+
usage: Usage;
|
|
77
|
+
costUsd: number;
|
|
78
|
+
toolCalls: number;
|
|
79
|
+
stopReason: StopReason;
|
|
80
|
+
interrupted: boolean;
|
|
81
|
+
}
|
|
82
|
+
export declare class Agent {
|
|
83
|
+
private readonly options;
|
|
84
|
+
private readonly toolState;
|
|
85
|
+
private readonly subscribers;
|
|
86
|
+
private systemPrompt;
|
|
87
|
+
private turn;
|
|
88
|
+
private sessionUsage;
|
|
89
|
+
private sessionCost;
|
|
90
|
+
constructor(options: AgentOptions);
|
|
91
|
+
get sessionId(): string;
|
|
92
|
+
get providerId(): string;
|
|
93
|
+
get model(): string;
|
|
94
|
+
get effort(): AgentOptions["effort"];
|
|
95
|
+
get cwd(): string;
|
|
96
|
+
get usage(): Usage;
|
|
97
|
+
get costUsd(): number;
|
|
98
|
+
get state(): ToolState;
|
|
99
|
+
get workspaceRoots(): string[];
|
|
100
|
+
get prompt(): string;
|
|
101
|
+
setModel(model: string): void;
|
|
102
|
+
setEffort(effort: NonNullable<AgentOptions["effort"]>): void;
|
|
103
|
+
setWorkspace(cwd: string, workspaceRoots?: string[] | undefined): void;
|
|
104
|
+
private capabilities;
|
|
105
|
+
subscribe(handler: (event: AgentEvent) => void): () => void;
|
|
106
|
+
private emit;
|
|
107
|
+
private streamWithFallback;
|
|
108
|
+
private streamTurn;
|
|
109
|
+
private costFor;
|
|
110
|
+
private toolContext;
|
|
111
|
+
private repeatedCallResult;
|
|
112
|
+
private executeToolCall;
|
|
113
|
+
runTurn(input: string, signal: AbortSignal): Promise<TurnResult>;
|
|
114
|
+
sideQuestion(question: string, signal: AbortSignal): Promise<string>;
|
|
115
|
+
branch(name?: string): string;
|
|
116
|
+
rewind(checkpointId: string, mode: RewindMode): {
|
|
117
|
+
files: number;
|
|
118
|
+
messages: number;
|
|
119
|
+
};
|
|
120
|
+
compact(instructions?: string, signal?: AbortSignal): Promise<CompactResult>;
|
|
121
|
+
private maybeAutoCompact;
|
|
122
|
+
contextEstimate(): {
|
|
123
|
+
tokens: number;
|
|
124
|
+
messages: number;
|
|
125
|
+
};
|
|
126
|
+
}
|