@blade-ai/orca 0.2.50 → 0.2.51-darwin-x64
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/README.md +64 -381
- package/package.json +15 -20
- package/vendor/x86_64-apple-darwin/bin/orca +0 -0
- package/bin/orca.js +0 -102
package/README.md
CHANGED
|
@@ -1,408 +1,91 @@
|
|
|
1
1
|
# Orca
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A DeepSeek-native coding agent for your terminal.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Give Orca a task and it reads code, edits files, runs commands, verifies the
|
|
6
|
+
result, and keeps working until the task is done or it needs you. Use the TUI
|
|
7
|
+
for interactive work or `orca exec` for scripts and CI. Orca is built in Rust,
|
|
8
|
+
runs locally, and is MIT licensed.
|
|
6
9
|
|
|
7
|
-
|
|
10
|
+
[English](README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja-JP.md) · [Tiếng Việt](README.vi.md) · [한국어](README.ko-KR.md) · [Español](README.es-419.md) · [Português](README.pt-BR.md)
|
|
8
11
|
|
|
9
|
-
|
|
12
|
+
[Website](https://orcaagent.dev/) · [Changelog](https://orcaagent.dev/changelog/) · [Releases](https://github.com/echoVic/blade-deepseek/releases/latest) · [npm](https://www.npmjs.com/package/@blade-ai/orca)
|
|
13
|
+
|
|
14
|
+
## Install
|
|
10
15
|
|
|
11
16
|
```bash
|
|
12
17
|
npm install -g @blade-ai/orca
|
|
13
|
-
orca --version
|
|
14
18
|
```
|
|
15
19
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
Supported npm platforms:
|
|
19
|
-
|
|
20
|
-
- macOS Apple Silicon (`darwin/arm64`)
|
|
21
|
-
- macOS Intel (`darwin/x64`)
|
|
22
|
-
- Linux x64 (`linux/x64`)
|
|
23
|
-
- Linux ARM64 (`linux/arm64`)
|
|
24
|
-
|
|
25
|
-
### curl
|
|
20
|
+
Or install the native binary directly:
|
|
26
21
|
|
|
27
22
|
```bash
|
|
28
23
|
curl -fsSL https://orcaagent.dev/install.sh | sh
|
|
29
24
|
```
|
|
30
25
|
|
|
31
|
-
The
|
|
32
|
-
|
|
26
|
+
The npm package supports macOS and Linux on ARM64 and x64. Prebuilt archives
|
|
27
|
+
are also available from [GitHub Releases](https://github.com/echoVic/blade-deepseek/releases/latest).
|
|
33
28
|
|
|
34
|
-
|
|
35
|
-
curl -fsSL https://orcaagent.dev/install.sh | \
|
|
36
|
-
INSTALL_DIR=/usr/local/bin ORCA_VERSION=0.2.50 sh
|
|
37
|
-
```
|
|
29
|
+
## Use
|
|
38
30
|
|
|
39
|
-
|
|
31
|
+
```bash
|
|
32
|
+
export DEEPSEEK_API_KEY=sk-...
|
|
40
33
|
|
|
41
|
-
|
|
34
|
+
orca # open the TUI
|
|
35
|
+
orca exec "fix the failing test" # run headlessly
|
|
36
|
+
orca exec --verifier "cargo test" "fix it" # verify before finishing
|
|
37
|
+
orca --mode=acp # connect an ACP client
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
In the TUI, `@` searches files, skills, plugins, and MCP resources. Use
|
|
41
|
+
`/plan` for read-only planning, `/goal` for a persistent objective,
|
|
42
|
+
`/workflows` for background work, and `/trust` to manage the current folder's
|
|
43
|
+
sandbox permissions.
|
|
44
|
+
|
|
45
|
+
## What it does
|
|
46
|
+
|
|
47
|
+
- Uses DeepSeek's reasoning and tool-use semantics directly, with SSE streaming,
|
|
48
|
+
prefix-cache-friendly prompts, automatic context management, and retry logic.
|
|
49
|
+
- Reads, searches, edits, and writes code; runs shell commands; and can verify
|
|
50
|
+
the result with a command you choose.
|
|
51
|
+
- Gates risky actions with `suggest`, sandboxed `auto-edit`, full-access
|
|
52
|
+
`full-auto`, and read-only `plan` modes, plus per-folder trust.
|
|
53
|
+
- Saves local conversation history with resume, fork, search, rename, archive,
|
|
54
|
+
and compression support.
|
|
55
|
+
- Runs persistent goals without a fixed turn ceiling, plus subagents and
|
|
56
|
+
JavaScript workflows for longer tasks that need continuation or parallel work.
|
|
57
|
+
- Loads project instructions, skills, plugins, custom tools, MCP tools, and MCP
|
|
58
|
+
resources after the workspace is trusted.
|
|
59
|
+
- Exposes stable JSONL, app-server, and Agent Client Protocol (ACP) contracts
|
|
60
|
+
for editors, harnesses, and CI.
|
|
61
|
+
|
|
62
|
+
Configuration priority is environment variables, CLI arguments, config files,
|
|
63
|
+
then defaults. Run `orca --help` or `orca exec --help` for the full command
|
|
64
|
+
surface. User configuration lives at `~/.orca/config.toml`; trusted projects
|
|
65
|
+
can also provide `.orca/config.toml`, `AGENTS.md`, rules, skills, and workflows.
|
|
66
|
+
|
|
67
|
+
More detail:
|
|
68
|
+
|
|
69
|
+
- [Persistent Goal Mode](docs/goal-mode.md)
|
|
70
|
+
- [Harness and app-server contract](docs/harness-contract.md)
|
|
71
|
+
- [Dynamic workflow design](docs/claude-code-workflow-parity.md)
|
|
72
|
+
- [Production roadmap](docs/production-roadmap.md)
|
|
42
73
|
|
|
43
74
|
## Community
|
|
44
75
|
|
|
45
76
|
- QQ group: `472309526`
|
|
46
|
-
- Telegram
|
|
47
|
-
|
|
48
|
-
## Contributing and Support
|
|
49
|
-
|
|
50
|
-
- Read [CONTRIBUTING.md](CONTRIBUTING.md) before contributing. Open an issue first for large or compatibility-sensitive changes.
|
|
51
|
-
- Report bugs with the [bug report form](https://github.com/echoVic/blade-deepseek/issues/new?template=bug_report.yml).
|
|
52
|
-
- Propose features with the [feature request form](https://github.com/echoVic/blade-deepseek/issues/new?template=feature_request.yml).
|
|
53
|
-
- Suggest documentation improvements with the [documentation form](https://github.com/echoVic/blade-deepseek/issues/new?template=documentation.yml).
|
|
54
|
-
- Use [SUPPORT.md](SUPPORT.md) for questions and help.
|
|
55
|
-
- Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
|
|
56
|
-
|
|
57
|
-
## Quick Start
|
|
58
|
-
|
|
59
|
-
```sh
|
|
60
|
-
# Set your API key
|
|
61
|
-
export DEEPSEEK_API_KEY=sk-...
|
|
62
|
-
|
|
63
|
-
# Run a task
|
|
64
|
-
orca exec "fix this test"
|
|
65
|
-
|
|
66
|
-
# With options
|
|
67
|
-
orca exec --approval-mode full-auto "refactor the auth module"
|
|
68
|
-
orca exec --model deepseek-v4-pro "explain this codebase"
|
|
69
|
-
orca exec --verifier "cargo test" "fix the failing test"
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
## Terminal UI
|
|
73
|
-
|
|
74
|
-
The interactive TUI keeps long-running sessions compact without changing the
|
|
75
|
-
content sent to the model:
|
|
76
|
-
|
|
77
|
-
- Pastes over 1,000 characters appear as `[Pasted Content N chars]` in the
|
|
78
|
-
composer and expand only for submission. Long submitted messages remain a
|
|
79
|
-
bounded transcript preview.
|
|
80
|
-
- Goal objectives, task-plan steps, tool targets, and Goal status notices are
|
|
81
|
-
shortened by terminal display width with a visible ellipsis.
|
|
82
|
-
- Approval dialogs keep the decision options visible when commands or previews
|
|
83
|
-
are long, and slash/file candidate menus scroll with the current selection.
|
|
84
|
-
- Drag over the transcript to select text with a theme-aware highlight;
|
|
85
|
-
releasing the button copies it to the system clipboard via OSC 52 (with
|
|
86
|
-
`pbcopy` fallback on macOS) and shows a `copied N chars` notice. Double-click
|
|
87
|
-
copies the word under the cursor, dragging past the first/last row
|
|
88
|
-
auto-scrolls to grow the selection, and a `Jump to bottom` pill re-arms
|
|
89
|
-
auto-follow after scrolling up.
|
|
90
|
-
- The status line preserves permission mode and context pressure first on narrow
|
|
91
|
-
terminals, then adds token, cost, and shortcut metadata as space permits.
|
|
92
|
-
- Permission modes use semantic colors: `suggest` blue, `auto-edit` violet,
|
|
93
|
-
`full-auto` red, and `plan` teal.
|
|
94
|
-
- `@` opens one unified Mention menu for streaming multi-root files, Skills,
|
|
95
|
-
Plugins, and MCP Resources. The visible token stays editable while Orca keeps
|
|
96
|
-
a hidden atomic target binding, so equal names from different roots or
|
|
97
|
-
providers expand to the object the user actually selected.
|
|
98
|
-
- Completed agent-message, reasoning, and proposed-plan rows keep the same
|
|
99
|
-
opaque ids while streaming, after approval continuation, and when a saved
|
|
100
|
-
thread is reopened or resumed. Live and cold history reduce one durable model
|
|
101
|
-
response instead of replacing the streamed rows with another assistant shape.
|
|
102
|
-
- If DeepSeek ends a turn without visible content or a tool call, Orca performs
|
|
103
|
-
one bounded corrective retry without persisting the incomplete response or
|
|
104
|
-
repeating already displayed reasoning. Terminal provider failures retain a
|
|
105
|
-
redacted diagnostic in session and task history for later analysis.
|
|
106
|
-
|
|
107
|
-
## Configuration
|
|
108
|
-
|
|
109
|
-
Priority chain (highest wins): Environment variables > CLI arguments > Config file > Defaults.
|
|
110
|
-
|
|
111
|
-
### Environment Variables
|
|
112
|
-
|
|
113
|
-
- `DEEPSEEK_API_KEY` — API key (required)
|
|
114
|
-
- `DEEPSEEK_MODEL` — Model override
|
|
115
|
-
- `DEEPSEEK_BASE_URL` — API base URL override
|
|
116
|
-
- `DEEPSEEK_REASONING_EFFORT` — Reasoning effort override (`high` or `max`; default `max`)
|
|
117
|
-
- `ORCA_NODE_PATH` — Node.js executable used by workflow scripts when `node` is not on `PATH` (npm installs set this automatically)
|
|
118
|
-
|
|
119
|
-
### Config File
|
|
120
|
-
|
|
121
|
-
`~/.orca/config.toml`:
|
|
122
|
-
|
|
123
|
-
```toml
|
|
124
|
-
model = "auto"
|
|
125
|
-
reasoning_effort = "max"
|
|
126
|
-
api_key = "sk-..."
|
|
127
|
-
base_url = "https://api.deepseek.com"
|
|
128
|
-
```
|
|
129
|
-
|
|
130
|
-
Project-local `.orca/config.toml`, `AGENTS.md`, `.orca/rules`, project skills,
|
|
131
|
-
and named project workflows are loaded only after the folder is trusted. New
|
|
132
|
-
folders use a strict read-only, no-network default sandbox. Manage trust with:
|
|
133
|
-
|
|
134
|
-
```sh
|
|
135
|
-
orca trust show --cwd /path/to/project
|
|
136
|
-
orca trust add --cwd /path/to/project
|
|
137
|
-
orca trust remove --cwd /path/to/project
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
The TUI exposes the same state through `/trust`, `/trust add`, and
|
|
141
|
-
`/trust remove`.
|
|
142
|
-
|
|
143
|
-
### Updates
|
|
144
|
-
|
|
145
|
-
When `update_check` is enabled, Orca checks for a newer release before opening the interactive TUI. If a newer release is available, Orca shows a startup prompt with `Update now`, `Skip`, and `Skip until next version`. Choosing `Update now` updates the currently running install: npm-managed launches run the npm upgrade command, while direct binary launches rerun the curl installer into the current executable's directory. Choosing either skip option continues into the TUI.
|
|
146
|
-
|
|
147
|
-
If you installed with curl and later switch to npm, make sure the npm global bin directory appears before `~/.local/bin` on `PATH`, or remove the older curl-installed `~/.local/bin/orca`. Otherwise your shell may keep running the curl-installed binary.
|
|
148
|
-
|
|
149
|
-
Disable the startup check with:
|
|
150
|
-
|
|
151
|
-
```toml
|
|
152
|
-
update_check = false
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
Hooks may return structured JSON on stdout. `{"action":"deny","reason":"..."}` blocks, `{"action":"modify","modified_target":"..."}` rewrites a tool target, and `{"action":"inject","context":"..."}` adds model context. When JSON declares an `action`, Orca validates the action and required string fields so typoed or malformed structured outputs fail visibly. Plain non-JSON stdout and JSON without `action` are treated as injected context for compatibility. Supported events are `session_start`, `session_end`, `pre_tool_use`, `post_tool_use`, `pre_model_call`, `post_model_call`, `on_budget_warning`, `pre_compact`, and `post_compact`.
|
|
156
|
-
|
|
157
|
-
Custom tools can be added with TOML descriptors under `~/.orca/tools/`:
|
|
158
|
-
|
|
159
|
-
```toml
|
|
160
|
-
name = "deploy"
|
|
161
|
-
description = "Deploy the current branch"
|
|
162
|
-
action_kind = "write"
|
|
163
|
-
command = "./scripts/deploy.sh"
|
|
164
|
-
schema = { target = { type = "string", description = "environment" } }
|
|
165
|
-
```
|
|
166
|
-
|
|
167
|
-
External tool commands run from the workspace directory. Raw JSON arguments are
|
|
168
|
-
always provided on stdin and, when they are at most 64 KiB, are also mirrored
|
|
169
|
-
in `ORCA_TOOL_ARGS` for compatibility.
|
|
170
|
-
|
|
171
|
-
Tool output truncation can be configured under `[tools]`. Byte mode preserves the historical 8 KiB default; token mode adds an explicit warning with original token and line counts before compacting large outputs:
|
|
172
|
-
|
|
173
|
-
```toml
|
|
174
|
-
[tools]
|
|
175
|
-
output_truncation = { mode = "tokens", limit = 2000 }
|
|
176
|
-
```
|
|
177
|
-
|
|
178
|
-
### Defaults
|
|
179
|
-
|
|
180
|
-
- Model: `auto` (main loop uses `deepseek-v4-pro`, auxiliary tasks use `deepseek-v4-flash`)
|
|
181
|
-
- Reasoning effort: `max`
|
|
182
|
-
- Base URL: `https://api.deepseek.com`
|
|
183
|
-
- Approval mode: `suggest`
|
|
184
|
-
- Output format: `text`
|
|
185
|
-
- Max turns: 128
|
|
186
|
-
|
|
187
|
-
## Command
|
|
188
|
-
|
|
189
|
-
```sh
|
|
190
|
-
orca exec [options] <prompt>
|
|
191
|
-
orca --mode=server
|
|
192
|
-
orca --mode=acp
|
|
193
|
-
orca trust [show|add|remove] --cwd <path>
|
|
194
|
-
```
|
|
195
|
-
|
|
196
|
-
For headless harnesses, `orca exec` also accepts prompt input from stdin:
|
|
197
|
-
|
|
198
|
-
```sh
|
|
199
|
-
printf 'fix the failing test\n' | orca exec --output-format jsonl
|
|
200
|
-
printf 'review this diff\n' | orca exec --output-format jsonl -
|
|
201
|
-
printf 'compiler output\n' | orca exec --output-format jsonl 'summarize this failure'
|
|
202
|
-
```
|
|
203
|
-
|
|
204
|
-
When no prompt argument is provided, stdin becomes the prompt. A lone `-` also
|
|
205
|
-
forces reading the prompt from stdin. When a prompt argument and piped stdin are
|
|
206
|
-
both provided, stdin is appended to the prompt inside a `<stdin>...</stdin>`
|
|
207
|
-
context block.
|
|
208
|
-
|
|
209
|
-
Options:
|
|
210
|
-
|
|
211
|
-
- `--output-format text|jsonl` — Output format (default: text)
|
|
212
|
-
- `--cwd <path>` — Workspace directory
|
|
213
|
-
- `--approval-mode suggest|auto-edit|full-auto` — Approval policy
|
|
214
|
-
- `--model auto|deepseek-v4-flash|deepseek-v4-pro` — Model to use; `auto` defaults to Pro for the main loop and Flash for auxiliary tasks
|
|
215
|
-
- `--base-url <url>` — API base URL
|
|
216
|
-
- `--verifier <command>` — Post-run verification command
|
|
217
|
-
- `--resume <session|latest>` — Continue from a saved conversation transcript
|
|
218
|
-
- `--fork <session|latest>` — Continue from a saved transcript in a new child session with parent metadata
|
|
219
|
-
- `--continue` / `--last` — Continue from the latest saved conversation transcript
|
|
220
|
-
- `--no-history` — Disable local transcript persistence for this run
|
|
221
|
-
- `--save-history` — Persist transcript even with `--output-format jsonl`
|
|
222
|
-
- top-level `--continue` / `--last` — Open the latest saved conversation in TUI mode
|
|
223
|
-
- top-level `--resume <session|latest>` — Open a saved conversation in TUI mode
|
|
224
|
-
- top-level `--fork <session|latest>` — Fork a saved conversation in TUI mode
|
|
225
|
-
- top-level `--session-picker` — Choose a saved conversation before entering TUI mode
|
|
226
|
-
- top-level `--mode=server` — Run the JSONL app-server, including thread/turn
|
|
227
|
-
methods, multi-root `fuzzyFileSearch/*`, unified `mention/search/*`, and
|
|
228
|
-
atomic structured Mention input. Selecting a candidate or sending structured
|
|
229
|
-
Mention input creates a binding; plain `@...` text stays literal. See
|
|
230
|
-
[the harness contract](docs/harness-contract.md)
|
|
231
|
-
- top-level `--mode=acp` — Run the stdio Agent Client Protocol adapter. ACP
|
|
232
|
-
sessions and prompts project onto `RuntimeHost`; the internal JSONL server
|
|
233
|
-
remains available and unchanged.
|
|
234
|
-
|
|
235
|
-
Approval modes also select the default execution boundary:
|
|
236
|
-
|
|
237
|
-
- `suggest` asks before mutating or external actions.
|
|
238
|
-
- `auto-edit` runs actions without interruption while keeping the workspace
|
|
239
|
-
sandbox; requests to write outside it, use blocked network access, or retry
|
|
240
|
-
without a sandbox still require a permission response.
|
|
241
|
-
- `full-auto` enables full access (`danger-full-access`) and does not fall back
|
|
242
|
-
to a post-failure permission prompt for sandbox escape.
|
|
243
|
-
- `plan` keeps the shell read-only and denies mutations.
|
|
244
|
-
|
|
245
|
-
## Workflows
|
|
246
|
-
|
|
247
|
-
`orca workflow run <script-or-name>` runs an Orca dynamic workflow.
|
|
248
|
-
Named workflows resolve from the nearest `.orca/workflows/` directory first,
|
|
249
|
-
then `~/.orca/workflows/`. Project workflows win over user workflows.
|
|
250
|
-
Workflow tool calls launch background tasks and return task metadata immediately;
|
|
251
|
-
the final workflow report is delivered back into the active TUI session as a
|
|
252
|
-
task notification.
|
|
253
|
-
If a backgrounded TUI turn pauses for tool approval, approving it from the
|
|
254
|
-
workflow/tasks panel continues the stored provider response. The originally
|
|
255
|
-
approved tool call is not prompted again; later approval-requiring tools still
|
|
256
|
-
follow the active approval policy.
|
|
257
|
-
|
|
258
|
-
Workflow scripts are JavaScript modules beginning with:
|
|
259
|
-
|
|
260
|
-
```js
|
|
261
|
-
export const meta = { name: "audit", description: "Audit code", phases: ["scan"] };
|
|
262
|
-
```
|
|
263
|
-
|
|
264
|
-
## Conversation History
|
|
265
|
-
|
|
266
|
-
Text-mode `orca exec` saves local JSONL transcripts under `~/.orca/sessions/YYYY/MM/DD/`.
|
|
267
|
-
JSONL mode is side-effect free by default for harness use; pass `--save-history` when a machine-readable run should also be resumable.
|
|
268
|
-
|
|
269
|
-
```sh
|
|
270
|
-
orca history list
|
|
271
|
-
orca history list --all
|
|
272
|
-
orca history show latest
|
|
273
|
-
orca history rename latest "short title"
|
|
274
|
-
orca history search "needle"
|
|
275
|
-
orca history compress latest
|
|
276
|
-
orca history archive latest
|
|
277
|
-
orca history delete <session>
|
|
278
|
-
orca exec --resume latest "continue the refactor"
|
|
279
|
-
orca exec --continue "continue the refactor"
|
|
280
|
-
orca exec --fork latest "try another approach"
|
|
281
|
-
orca --session-picker
|
|
282
|
-
```
|
|
283
|
-
|
|
284
|
-
`--resume` and `--fork` accept a full session ID, a filename/session prefix, or `latest`. Resumed runs create a new transcript that includes the loaded context plus the new turn. Forked runs also write `parent_id` and `forked: true` metadata. Context compaction is persisted as `context.collapsed` records, appends are guarded with file locks on Unix, `history search` uses local ripgrep when available, and `history compress` rewrites large transcripts as `.jsonl.zst` while keeping list/show/search support.
|
|
285
|
-
|
|
286
|
-
In the TUI, `Esc` during an idle composer backtracks to the previous user message and places that prompt back in the input box for editing and re-asking.
|
|
287
|
-
|
|
288
|
-
## Persistent Goal Mode
|
|
289
|
-
|
|
290
|
-
TUI sessions support persistent goals with `/goal`. A goal is stored by session id in `~/.orca/goals_1.json` or `$ORCA_HOME/goals_1.json`, so it survives process restarts when the session is saved.
|
|
291
|
-
|
|
292
|
-
```text
|
|
293
|
-
/goal # show the current goal
|
|
294
|
-
/goal ship the refactor # create or replace the active goal and start it
|
|
295
|
-
/goal edit finish the parser # update the objective and reactivate it
|
|
296
|
-
/goal pause # stop automatic continuation
|
|
297
|
-
/goal resume # reactivate and continue when idle
|
|
298
|
-
/goal clear # delete the goal for this session
|
|
299
|
-
```
|
|
300
|
-
|
|
301
|
-
While a goal is active, Orca automatically starts another turn after a successful turn and injects goal-mode instructions as pinned context. There is no fixed turn or continuation limit. The loop stops when the goal is paused, cleared, blocked, completed, budget-limited, interrupted, waiting on an interaction or workflow, or repeatedly makes no progress. Goal turns expose `get_goal`, `create_goal`, and `update_goal`; the model can only use `update_goal` to request a verified `complete` or `blocked` terminal state, while `/goal` commands own pause, resume, edit, and clear.
|
|
302
|
-
|
|
303
|
-
The running timer for an active Goal is cumulative: Orca displays persisted time from completed Goal turns plus the elapsed time of the current turn. Time between turns, while the Goal is paused, or while Orca is closed is excluded. `/goal resume` preserves the elapsed time, tokens used, token budget, objective, and original creation timestamp instead of starting the Goal's accounting over.
|
|
304
|
-
|
|
305
|
-
Persistent goals require recorded history. If history is disabled with `--no-history`, `/goal` reports an error instead of creating ephemeral goal state.
|
|
306
|
-
|
|
307
|
-
## Tools
|
|
308
|
-
|
|
309
|
-
Built-in tools:
|
|
310
|
-
|
|
311
|
-
| Tool | Description |
|
|
312
|
-
|------|-------------|
|
|
313
|
-
| `read_file` | Read file contents (UTF-8, truncated at 8KB) |
|
|
314
|
-
| `glob` | Find files and directories by glob pattern or fuzzy path query; preferred for file discovery |
|
|
315
|
-
| `list_files` | Compatibility alias for directory listing |
|
|
316
|
-
| `grep` | Search with ripgrep (regex, line numbers) |
|
|
317
|
-
| `bash` | Execute shell commands via `sh -c` |
|
|
318
|
-
| `edit` | Exact text replacement in files |
|
|
319
|
-
| `write_file` | Create or overwrite a file |
|
|
320
|
-
| `git_status` | Show git working tree status |
|
|
321
|
-
| `web_search` | Search the web for current information |
|
|
322
|
-
| `subagent` | Run a synchronous child agent for a delegated task |
|
|
323
|
-
| `Workflow` | Launch a background dynamic workflow |
|
|
324
|
-
| `update_plan` | Update the visible task plan |
|
|
325
|
-
| `get_goal` | Read active persistent goal state during goal mode |
|
|
326
|
-
| `create_goal` | Create a persistent goal during goal mode when no unfinished goal exists |
|
|
327
|
-
| `update_goal` | Mark active persistent goal complete or blocked from goal mode |
|
|
328
|
-
| `request_user_input` | Ask a structured clarification question; TUI answers continue the same turn |
|
|
329
|
-
| `list_skills` | List Markdown skills from user and project skill directories |
|
|
330
|
-
| `read_skill` | Read a skill's Markdown instructions by id |
|
|
331
|
-
| `list_mcp_resources` | List read-only resources exposed by configured MCP servers |
|
|
332
|
-
| `read_mcp_resource` | Read a specific MCP resource by server name and URI |
|
|
333
|
-
|
|
334
|
-
Tools are registered through a canonical tool registry with capability metadata. Approval behavior is derived from those capabilities: read-only tools run directly, write tools follow write approval policy, shell tools follow shell approval policy, network tools follow network policy, and agent/workflow tools follow agent policy. Tool arguments are validated before execution, including common JSON Schema object keywords plus `oneOf` and `anyOf`, so provider-advertised schemas and runtime rejection behavior stay aligned. `glob` is the model-facing file discovery tool and supports both normal glob patterns and `mode: "fuzzy"` path queries; `list_files` remains accepted for older prompts and saved sessions. `request_user_input` stays deterministic in headless runs and becomes interactive in TUI sessions.
|
|
335
|
-
|
|
336
|
-
Markdown skills live under `$ORCA_HOME/skills/*/SKILL.md`, `~/.orca/skills/*/SKILL.md`, or project `.orca/skills/*/SKILL.md`. The model can inspect them with `list_skills` and `read_skill`; when a prompt explicitly mentions a skill id such as `$debugging`, Orca injects that skill's instructions into the model context for the turn.
|
|
337
|
-
|
|
338
|
-
MCP tools and custom external tools can be added at startup. External tools live under `~/.orca/tools/*.toml` or `$ORCA_HOME/tools/*.toml`, and configured MCP server tools are exposed with namespaced tool names. MCP resources can also be listed and read through the read-only resource tools.
|
|
339
|
-
|
|
340
|
-
## Architecture
|
|
341
|
-
|
|
342
|
-
- **Agent Loop**: prompt → model → tool_call → execute → feed result → next turn (up to 128 turns)
|
|
343
|
-
- **Subagents**: Synchronous child agent loops share the parent workspace, provider/model config, and approval policy, then return a concise result to the parent
|
|
344
|
-
- **Persistent Goal Mode**: TUI sessions can persist a long-running objective, auto-continue successful turns, and stop through `/goal` controls or goal-mode tools
|
|
345
|
-
- **SSE Streaming**: Real-time reasoning and content deltas via Server-Sent Events
|
|
346
|
-
- **Context Window**: DeepSeek V4 1M-token context, 80% threshold compaction with response reserve (preserves system + recent messages)
|
|
347
|
-
- **Conversation History**: Local JSONL transcripts support listing, inspection, resume/fork, full-text search, archive/delete/rename, and zstd compression
|
|
348
|
-
- **HTTP Client**: Singleton with 30s connect / 120s request / 300s streaming timeouts, exponential backoff retry (3 attempts, handles 429/5xx)
|
|
349
|
-
- **Approval Policy**: Tool capabilities drive approval; `suggest` prompts for mutating or external actions, `auto-edit` allows actions inside its workspace sandbox, `full-auto` combines automatic approval with `danger-full-access`, and `plan` denies mutations
|
|
350
|
-
- **Verification**: Optional post-completion verifier command with pass/fail status
|
|
351
|
-
- **Release Gate**: `scripts/release/verify-published.mjs` checks the GitHub Release, npm registry, and `npm exec` smoke path after publishing
|
|
352
|
-
|
|
353
|
-
## Event Stream (JSONL)
|
|
354
|
-
|
|
355
|
-
When `--output-format jsonl` is used, each line is a versioned event:
|
|
356
|
-
|
|
357
|
-
```json
|
|
358
|
-
{"version":"1","run_id":"run-...","seq":0,"timestamp_ms":1780647978857,"type":"session.started","payload":{}}
|
|
359
|
-
```
|
|
360
|
-
|
|
361
|
-
Event types: `session.started`, `turn.started`, `assistant.reasoning.delta`, `assistant.message.delta`, `provider.replay.updated`, `approval.requested`, `approval.resolved`, `tool.call.requested`, `tool.call.completed`, `subagent.started`, `subagent.completed`, `verification.started`, `verification.completed`, `error`, `session.completed`.
|
|
362
|
-
|
|
363
|
-
## Agent Client Protocol (ACP)
|
|
364
|
-
|
|
365
|
-
Orca supports the [Agent Client Protocol](https://agentclientprotocol.com) as a
|
|
366
|
-
parallel entry point alongside the internal JSONL protocol. This lets code
|
|
367
|
-
editors (Zed, etc.) communicate with Orca using the standard ACP JSON-RPC wire
|
|
368
|
-
format over stdio.
|
|
369
|
-
|
|
370
|
-
```bash
|
|
371
|
-
orca --mode=acp
|
|
372
|
-
```
|
|
373
|
-
|
|
374
|
-
The ACP adapter projects protocol messages onto existing internals:
|
|
375
|
-
|
|
376
|
-
| ACP method | Orca mechanism |
|
|
377
|
-
|---|---|
|
|
378
|
-
| `session/new` | `RuntimeHost::start_thread` |
|
|
379
|
-
| `session/load` | Resume from conversation history |
|
|
380
|
-
| `session/prompt` | `RuntimeThreadHandle::start_turn_with_config` |
|
|
381
|
-
| `session/update` | `EventObserver` → projected `SessionUpdate` |
|
|
382
|
-
| `session/cancel` | `OperationHandle::interrupt()` |
|
|
383
|
-
|
|
384
|
-
Supported methods: `initialize`, `authenticate` (no-op), `session/new`,
|
|
385
|
-
`session/load`, `session/prompt`, `session/cancel`, plus streaming
|
|
386
|
-
`session/update` notifications (message chunks, reasoning chunks, tool calls,
|
|
387
|
-
tool call updates, and plan updates).
|
|
388
|
-
|
|
389
|
-
The internal JSONL protocol (`--mode=server`) remains unchanged and available.
|
|
390
|
-
|
|
391
|
-
## Exit Codes
|
|
77
|
+
- [Telegram](https://t.me/+11No1w5ZbTMyZTQ1)
|
|
392
78
|
|
|
393
|
-
|
|
394
|
-
- `1`: failed
|
|
395
|
-
- `2`: verification failed
|
|
396
|
-
- `3`: approval required or denied
|
|
397
|
-
- `4`: budget exhausted
|
|
398
|
-
- `130`: cancelled
|
|
79
|
+
## Contributing
|
|
399
80
|
|
|
400
|
-
|
|
81
|
+
Read [CONTRIBUTING.md](CONTRIBUTING.md) before contributing. Open an issue first
|
|
82
|
+
for large or compatibility-sensitive changes.
|
|
401
83
|
|
|
402
|
-
-
|
|
403
|
-
-
|
|
404
|
-
-
|
|
84
|
+
- [Report a bug](https://github.com/echoVic/blade-deepseek/issues/new?template=bug_report.yml)
|
|
85
|
+
- [Request a feature](https://github.com/echoVic/blade-deepseek/issues/new?template=feature_request.yml)
|
|
86
|
+
- [Ask for help](SUPPORT.md)
|
|
87
|
+
- [Report a vulnerability](SECURITY.md)
|
|
405
88
|
|
|
406
|
-
##
|
|
89
|
+
## License
|
|
407
90
|
|
|
408
|
-
|
|
91
|
+
[MIT](LICENSE)
|
package/package.json
CHANGED
|
@@ -1,30 +1,25 @@
|
|
|
1
1
|
{
|
|
2
|
-
"name": "@blade-ai/orca",
|
|
3
|
-
"version": "0.2.50",
|
|
4
|
-
"description": "Orca CLI: a DeepSeek-native coding agent.",
|
|
5
|
-
"homepage": "https://orcaagent.dev/",
|
|
6
2
|
"license": "MIT",
|
|
7
|
-
"
|
|
8
|
-
"orca": "bin/orca.js"
|
|
9
|
-
},
|
|
10
|
-
"type": "module",
|
|
11
|
-
"engines": {
|
|
12
|
-
"node": ">=16"
|
|
13
|
-
},
|
|
3
|
+
"homepage": "https://orcaagent.dev/",
|
|
14
4
|
"files": [
|
|
15
|
-
"
|
|
5
|
+
"vendor",
|
|
16
6
|
"README.md",
|
|
17
7
|
"LICENSE"
|
|
18
8
|
],
|
|
19
9
|
"repository": {
|
|
20
10
|
"type": "git",
|
|
21
|
-
"url": "git+https://github.com/echoVic/blade-deepseek.git"
|
|
22
|
-
|
|
11
|
+
"url": "git+https://github.com/echoVic/blade-deepseek.git"
|
|
12
|
+
},
|
|
13
|
+
"engines": {
|
|
14
|
+
"node": ">=16"
|
|
23
15
|
},
|
|
24
|
-
"
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
"
|
|
29
|
-
|
|
16
|
+
"name": "@blade-ai/orca",
|
|
17
|
+
"version": "0.2.51-darwin-x64",
|
|
18
|
+
"description": "Native Orca binary for darwin/x64.",
|
|
19
|
+
"os": [
|
|
20
|
+
"darwin"
|
|
21
|
+
],
|
|
22
|
+
"cpu": [
|
|
23
|
+
"x64"
|
|
24
|
+
]
|
|
30
25
|
}
|
|
Binary file
|
package/bin/orca.js
DELETED
|
@@ -1,102 +0,0 @@
|
|
|
1
|
-
#!/usr/bin/env node
|
|
2
|
-
|
|
3
|
-
import { spawn } from "node:child_process";
|
|
4
|
-
import { existsSync, realpathSync } from "node:fs";
|
|
5
|
-
import { createRequire } from "node:module";
|
|
6
|
-
import path from "node:path";
|
|
7
|
-
import { fileURLToPath } from "node:url";
|
|
8
|
-
|
|
9
|
-
const __filename = fileURLToPath(import.meta.url);
|
|
10
|
-
const __dirname = path.dirname(__filename);
|
|
11
|
-
const require = createRequire(import.meta.url);
|
|
12
|
-
|
|
13
|
-
const TARGETS = {
|
|
14
|
-
"darwin:arm64": {
|
|
15
|
-
packageName: "@blade-ai/orca-darwin-arm64",
|
|
16
|
-
targetTriple: "aarch64-apple-darwin"
|
|
17
|
-
},
|
|
18
|
-
"darwin:x64": {
|
|
19
|
-
packageName: "@blade-ai/orca-darwin-x64",
|
|
20
|
-
targetTriple: "x86_64-apple-darwin"
|
|
21
|
-
},
|
|
22
|
-
"linux:arm64": {
|
|
23
|
-
packageName: "@blade-ai/orca-linux-arm64",
|
|
24
|
-
targetTriple: "aarch64-unknown-linux-gnu"
|
|
25
|
-
},
|
|
26
|
-
"linux:x64": {
|
|
27
|
-
packageName: "@blade-ai/orca-linux-x64",
|
|
28
|
-
targetTriple: "x86_64-unknown-linux-gnu"
|
|
29
|
-
}
|
|
30
|
-
};
|
|
31
|
-
|
|
32
|
-
const target = TARGETS[`${process.platform}:${process.arch}`];
|
|
33
|
-
if (!target) {
|
|
34
|
-
throw new Error(`Unsupported platform: ${process.platform} (${process.arch})`);
|
|
35
|
-
}
|
|
36
|
-
|
|
37
|
-
function findExecutable() {
|
|
38
|
-
let vendorRoot;
|
|
39
|
-
try {
|
|
40
|
-
const packageJsonPath = require.resolve(`${target.packageName}/package.json`);
|
|
41
|
-
vendorRoot = path.join(path.dirname(packageJsonPath), "vendor");
|
|
42
|
-
} catch {
|
|
43
|
-
vendorRoot = path.join(__dirname, "..", "vendor");
|
|
44
|
-
}
|
|
45
|
-
|
|
46
|
-
const executable = path.join(vendorRoot, target.targetTriple, "bin", "orca");
|
|
47
|
-
if (existsSync(executable)) {
|
|
48
|
-
return executable;
|
|
49
|
-
}
|
|
50
|
-
|
|
51
|
-
throw new Error(
|
|
52
|
-
`Missing optional dependency ${target.packageName}. Reinstall with: npm install -g @blade-ai/orca`
|
|
53
|
-
);
|
|
54
|
-
}
|
|
55
|
-
|
|
56
|
-
const binaryPath = findExecutable();
|
|
57
|
-
const env = {
|
|
58
|
-
...process.env,
|
|
59
|
-
ORCA_MANAGED_BY_NPM: "1",
|
|
60
|
-
ORCA_MANAGED_PACKAGE_ROOT: realpathSync(path.join(__dirname, "..")),
|
|
61
|
-
ORCA_NODE_PATH: process.env.ORCA_NODE_PATH || process.execPath
|
|
62
|
-
};
|
|
63
|
-
|
|
64
|
-
const child = spawn(binaryPath, process.argv.slice(2), {
|
|
65
|
-
stdio: "inherit",
|
|
66
|
-
env
|
|
67
|
-
});
|
|
68
|
-
|
|
69
|
-
child.on("error", (error) => {
|
|
70
|
-
console.error(error);
|
|
71
|
-
process.exit(1);
|
|
72
|
-
});
|
|
73
|
-
|
|
74
|
-
const handledSignals = ["SIGINT", "SIGTERM", "SIGHUP"];
|
|
75
|
-
const forwardSignal = (signal) => {
|
|
76
|
-
if (!child.killed) {
|
|
77
|
-
child.kill(signal);
|
|
78
|
-
}
|
|
79
|
-
};
|
|
80
|
-
|
|
81
|
-
for (const signal of handledSignals) {
|
|
82
|
-
process.on(signal, () => forwardSignal(signal));
|
|
83
|
-
}
|
|
84
|
-
|
|
85
|
-
const result = await new Promise((resolve) => {
|
|
86
|
-
child.on("exit", (code, signal) => {
|
|
87
|
-
if (signal) {
|
|
88
|
-
resolve({ type: "signal", signal });
|
|
89
|
-
} else {
|
|
90
|
-
resolve({ type: "code", exitCode: code ?? 1 });
|
|
91
|
-
}
|
|
92
|
-
});
|
|
93
|
-
});
|
|
94
|
-
|
|
95
|
-
if (result.type === "signal") {
|
|
96
|
-
for (const signal of handledSignals) {
|
|
97
|
-
process.removeAllListeners(signal);
|
|
98
|
-
}
|
|
99
|
-
process.kill(process.pid, result.signal);
|
|
100
|
-
} else {
|
|
101
|
-
process.exit(result.exitCode);
|
|
102
|
-
}
|