DeepSeek/deepseek-harness
1
0
Fork 0
mirror of https://github.com/deepseek-ai/deepseek-harness synced 2026-08-15 21:04:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge codex/goal-commands into codex/ralph-tool

Browse Source
This commit is contained in:
Tianyi Cui
2026-07-20 01:52:57 +08:00
parent b808026859 fdce57cf4a
commit e2b8e2b1eb
490 changed files with 1662 additions and 1803 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
examples/README.md
View File

@@ -41,7 +41,7 @@ An unattended coding agent driven through the Python SDK: JSON-RPC stdio, foregr
The **self-referential** demo: the coding spine plus [`@deepseek-ai/dsh-tool-cordis`](../packages/cordis/tool-cordis), whose three tools (`cordis_inspect` / `cordis_mount` / `cordis_unmount`) let the agent inspect the live cordis runtime it runs inside, mount model-written plugins into it (an event listener, a brand-new tool for itself, or a service another mount injects), and dispose them again — all dynamic mounts grouped under one `cordis-dynamic` fiber subtree. The `ctx.fs`/`ctx.web` services ride along provider-only, as the capabilities those plugins build on.
Run with: `pnpm run demo:cordis` (needs `DEEPSEEK_API_KEY`). See [cordis-agent/README.md](cordis-agent/README.md) for the staged demo script and [the toolset RFC](../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md) for the design and sandbox caveats.
Run with: `pnpm run demo:cordis` (needs `DEEPSEEK_API_KEY`). See [cordis-agent/README.md](cordis-agent/README.md) for the staged demo script and [the toolset Agent Note](../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md) for the design and sandbox caveats.
## acp-agent

6
examples/acp-agent/README.md
View File

@@ -29,15 +29,15 @@ Add to your Zed `settings.json` under `agent_servers`:
}
```
The editor sets each session's `cwd` to the project it opens, and bash uses that directory as its workdir. The current sandbox write boundary is nevertheless fixed when the server starts (`workspaceRoot: process.cwd()`), so launch the server from the workspace it should be allowed to modify; making that root session-scoped is deferred in the [sandbox RFC](../../docs/rfc/implemented/feature/2026-07-06-sandbox.md). Filesystem tools are omitted from the confined default because they execute in-process and do not ride the bash sandbox.
The editor sets each session's `cwd` to the project it opens, and bash uses that directory as its workdir. The current sandbox write boundary is nevertheless fixed when the server starts (`workspaceRoot: process.cwd()`), so launch the server from the workspace it should be allowed to modify; making that root session-scoped is deferred in the [sandbox Agent Note](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md). Filesystem tools are omitted from the confined default because they execute in-process and do not ride the bash sandbox.
## Snapshot tests (record-once / replay-deterministic)
This example hosts the ACP snapshot suite. It replays through `dsh-llm-replay`, which reconstructs model streams from `assistant/chunk` events in each scenario's session JSONL. Recording runs the real ACP agent and harvests its logs; refresh keeps the committed transcript as mock input and rewrites current replay outputs. `replay.override.json` covers throw and hang cases that chunks cannot express, and an optional `workspace/` seeds files. The [snapshot RFC](../../docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md) owns the ACP harness design.
This example hosts the ACP snapshot suite. It replays through `dsh-llm-replay`, which reconstructs model streams from `assistant/chunk` events in each scenario's session JSONL. Recording runs the real ACP agent and harvests its logs; refresh keeps the committed transcript as mock input and rewrites current replay outputs. `replay.override.json` covers throw and hang cases that chunks cannot express, and an optional `workspace/` seeds files. The [snapshot Agent Note](../../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md) owns the ACP harness design.
## Permissions and sandboxing
The default tree composes [`@deepseek-ai/dsh-sandbox-local`](../../packages/sandbox/sandbox-local/), [`@deepseek-ai/dsh-bash-sandbox`](../../packages/bash/bash-sandbox/), [`@deepseek-ai/dsh-user-approval`](../../packages/ui/user-approval/), and [`@deepseek-ai/dsh-permission`](../../packages/ui/permission/). Bash starts in `workspace-write`; a denied operation returns a structured marker, and a retry with `sandbox_permissions` plus `justification` becomes a one-shot `session/request_permission` prompt in the editor. "Allow once" runs exactly that retry under the wider mode ([sandbox RFC § Escalation](../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)).
The default tree composes [`@deepseek-ai/dsh-sandbox-local`](../../packages/sandbox/sandbox-local/), [`@deepseek-ai/dsh-bash-sandbox`](../../packages/bash/bash-sandbox/), [`@deepseek-ai/dsh-user-approval`](../../packages/ui/user-approval/), and [`@deepseek-ai/dsh-permission`](../../packages/ui/permission/). Bash starts in `workspace-write`; a denied operation returns a structured marker, and a retry with `sandbox_permissions` plus `justification` becomes a one-shot `session/request_permission` prompt in the editor. "Allow once" runs exactly that retry under the wider mode ([sandbox Agent Note § Escalation](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)).
- **One session config option is live**: a capable client shows one `Permissions` select. `workspace-write` means workspace-confined bash plus `ask`; `danger-full-access` means unconfined bash plus `never`. Switching writes one `permission/preset` event through to the sandbox-mode and approval-policy events, and `session/load` reports the resumed value.
- **Every approval is one-shot**: the choices are `Allow once` and `Reject`; a dismissal, rejection, missing editor, or unavailable runner fails closed.

6
examples/acp-agent/tests/acp.snapshot.ts
View File

@@ -9,8 +9,8 @@ import { defineAcpSnapshotSuite, type Scenario, type SnapshotSuiteOptions } from
* uniformity guard, the fixture guards). Fixtures live under `snapshots/<name>/`;
* `pnpm run test:snapshot:record` re-records model transcripts against the real
* API; `pnpm run test:snapshot:refresh` rewrites current replay expected outputs keyless.
* See the package README (packages/support/acp-snapshot) and the snapshot RFC,
* docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md.
* See the package README (packages/support/acp-snapshot) and the snapshot Agent Note,
* .agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md.
*/
// The dsh-acp-demo bin (the demo:acp entry), this example's cordis.yml, and
@@ -140,7 +140,7 @@ const SCENARIOS: Scenario[] = [
// (the model's reaction to a deny/block/force-continue is part of the captured transcript).
// SessionStart/SubagentStart are excluded because detached injection races log
// order; SubagentStop writes no transcript, so an expected output could not prove it ran.
// Unit tests cover those points; the hook-snapshot-matrix RFC owns the rationale.
// Unit tests cover those points; the hook-snapshot-matrix Agent Note owns the rationale.
{ name: 'hook-cc-promptsubmit-context', hasModelTurn: true, recorded: true },
{ name: 'hook-cc-pretool-deny', hasModelTurn: true, recorded: true },
{ name: 'hook-cc-pretool-ask', hasModelTurn: true, recorded: true },

2
examples/cordis-agent/README.md
View File

@@ -1,6 +1,6 @@
# cordis-agent
The self-referential harness demo: the coding spine (DeepSeek V4 + local bash on the stdio chat app) plus [`@deepseek-ai/dsh-tool-cordis`](../../packages/cordis/tool-cordis/README.md), which hands the model three tools over the **live cordis runtime it is running inside** — inspect it, mount new plugins into it, and dispose them again. The `ctx.fs` and `ctx.web` services are mounted (provider-only, no model-facing file/web tools) so the plugins the agent writes have real capabilities to build on; Node built-ins are trapped in the sandbox and redirect to those services. The design (sandbox semantics, mount lifecycle, cross-mount composition, caveats) lives in [the toolset RFC](../../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md).
The self-referential harness demo: the coding spine (DeepSeek V4 + local bash on the stdio chat app) plus [`@deepseek-ai/dsh-tool-cordis`](../../packages/cordis/tool-cordis/README.md), which hands the model three tools over the **live cordis runtime it is running inside** — inspect it, mount new plugins into it, and dispose them again. The `ctx.fs` and `ctx.web` services are mounted (provider-only, no model-facing file/web tools) so the plugins the agent writes have real capabilities to build on; Node built-ins are trapped in the sandbox and redirect to those services. The design (sandbox semantics, mount lifecycle, cross-mount composition, caveats) lives in [the toolset Agent Note](../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md).
## Run it

2
examples/cordis-agent/cordis.yml
View File

@@ -5,7 +5,7 @@
# Trust stance: the vm and context façade limit accidental global/framework
# access but are not a security boundary; mounted code can reach live capabilities
# such as `ctx.bash`. Grant this toolset like bash access. See
# ../../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md.
# ../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md.
# Hot-module reload for the dev/demo loop (needs `node --expose-internals`).
- id: hmr

1
examples/jsonrpc-agent/README.md
View File

@@ -18,6 +18,7 @@ The surrounding runtime also loads JSONL session persistence and automatic conte
| `DEEPSEEK_API_KEY` | Credential passed to the OpenAI-compatible host endpoint |
| `DEEPSEEK_BASE_URL` | Host endpoint used by `dsh-llm-deepseek` |
| `DSH_CWD` | Agent workspace for bash and filesystem tools |
| `DSH_MAX_TOKENS_AS_SUCCESS` | `true` (default) accepts token-limited results; `false` reports them as errors |
| `DSH_SESSION_ROOT` | JSONL trajectory directory |
| `DSH_SYSTEM_PROMPT` | Deployment-provided coding persona |

2
examples/jsonrpc-agent/cordis.yml
View File

@@ -4,7 +4,7 @@
- id: jsonrpc
name: '@deepseek-ai/dsh-jsonrpc'
config:
maxTokensAsSuccess: true
maxTokensAsSuccess: !!js "process.env.DSH_MAX_TOKENS_AS_SUCCESS === undefined ? true : JSON.parse(process.env.DSH_MAX_TOKENS_AS_SUCCESS)"
- id: llm-deepseek
name: '@deepseek-ai/dsh-llm-deepseek'

52
examples/jsonrpc-agent/tests/keyless-smoke.e2e.ts
View File

@@ -43,7 +43,11 @@ function waitForLine(
}
describe('jsonrpc-agent keyless smoke', () => {
it('boots the real Cordis tree and serves initialize/shutdown over clean stdout', async () => {
it.each([
{ label: 'accepts max-token results by default', envValue: undefined, expectedStatus: 'ok' },
{ label: 'accepts max-token results when enabled through env', envValue: 'true', expectedStatus: 'ok' },
{ label: 'reports max-token results as errors when disabled through env', envValue: 'false', expectedStatus: 'error' },
])('$label', async ({ envValue, expectedStatus }) => {
const root = await mkdtemp(join(tmpdir(), 'dsh-jsonrpc-agent-smoke-'))
const modelRequests: Record<string, unknown>[] = []
const modelServer = createServer((request, response) => {
@@ -55,7 +59,7 @@ describe('jsonrpc-agent keyless smoke', () => {
response.writeHead(200, { 'content-type': 'text/event-stream' })
response.write('data: {"choices":[{"delta":{"role":"assistant","content":null}}]}\n\n')
response.write('data: {"choices":[{"delta":{"content":"done"}}]}\n\n')
response.write('data: {"choices":[{"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":3,"completion_tokens":1}}\n\n')
response.write('data: {"choices":[{"delta":{},"finish_reason":"length"}],"usage":{"prompt_tokens":3,"completion_tokens":1}}\n\n')
response.end('data: [DONE]\n\n')
})
})
@@ -76,6 +80,7 @@ describe('jsonrpc-agent keyless smoke', () => {
DEEPSEEK_BASE_URL: `http://127.0.0.1:${address.port}`,
DSH_CWD: root,
DSH_SESSION_ROOT: join(root, '.sessions'),
...(envValue === undefined ? {} : { DSH_MAX_TOKENS_AS_SUCCESS: envValue }),
},
stdio: ['pipe', 'pipe', 'pipe'],
})
@@ -112,6 +117,16 @@ describe('jsonrpc-agent keyless smoke', () => {
method: 'session/prompt',
params: { sessionId: 'main', contentBlocks: [{ type: 'text', text: 'inspect tools' }] },
})}\n`)
const finished = await waitForLine(lines, value => value.method === 'session.finished', () => stderr)
expect(finished).toMatchObject({
jsonrpc: '2.0',
method: 'session.finished',
params: {
sessionId: 'main',
status: expectedStatus,
reason: { kind: 'max-tokens' },
},
})
const prompt = await waitForLine(lines, value => value.id === 2, () => stderr)
expect(prompt).toMatchObject({ jsonrpc: '2.0', id: 2, result: { accepted: true } })
const tools = modelRequests[0]?.tools as { function?: { name?: string } }[]
@@ -143,4 +158,37 @@ describe('jsonrpc-agent keyless smoke', () => {
await rm(root, { recursive: true, force: true })
}
}, 40_000)
it('rejects an invalid max-token success env value', async () => {
const child = spawn(process.execPath, [
'--expose-internals',
'--import',
'tsx',
binScript,
configPath,
], {
cwd: repoRoot,
env: {
...process.env,
DEEPSEEK_API_KEY: 'keyless-smoke-no-call',
DSH_MAX_TOKENS_AS_SUCCESS: 'sometimes',
},
stdio: ['ignore', 'pipe', 'pipe'],
})
let stdout = ''
let stderr = ''
child.stdout.setEncoding('utf8')
child.stdout.on('data', (chunk: string) => { stdout += chunk })
child.stderr.setEncoding('utf8')
child.stderr.on('data', (chunk: string) => { stderr += chunk })
const exitCode = await new Promise<number | null>((resolve, reject) => {
child.once('error', reject)
child.once('exit', resolve)
})
expect(exitCode, stderr).toBe(1)
expect(stdout).toBe('')
expect(stderr).toContain('plugin(s) failed to load: @deepseek-ai/dsh-jsonrpc')
}, 10_000)
})

2
examples/repl-agent/README.md
View File

@@ -27,7 +27,7 @@ The id is wired through `cordis.yml` (`resumeSessionId: !!js process.env.RESUME_
## Code Mode
[`code-mode.cordis.yml`](code-mode.cordis.yml) overlays the same tree with the worker-thread runtime and `tools: { mode: code }`. The model receives one `run_code` transport plus a generated TypeScript SDK for the visible tools; only program output returns to model context. Use `mode: both` to expose native calls alongside `run_code`. See the [Code Mode RFC](../../docs/rfc/implemented/feature/2026-06-15-code-mode.md) for the execution contract.
[`code-mode.cordis.yml`](code-mode.cordis.yml) overlays the same tree with the worker-thread runtime and `tools: { mode: code }`. The model receives one `run_code` transport plus a generated TypeScript SDK for the visible tools; only program output returns to model context. Use `mode: both` to expose native calls alongside `run_code`. See the [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) for the execution contract.
```sh
pnpm run demo:code-mode # this overlay under the REPL (default UI)

2
examples/tui-agent/README.md
View File

@@ -20,4 +20,4 @@ Run `pnpm run demo:code-mode tui` for the sibling Code Mode overlay.
## Snapshot tests
`tests/snapshots/<scenario>/session.jsonl` supplies recorded user prompts and model chunks; sibling child logs drive subagents and workflows. The keyless suite executes those scripts through the real loop and tool implementations, then compares readable expected terminal cell/style output. Use `pnpm run test:snapshot:refresh` for presentation-only changes and `pnpm run test:snapshot:record` with a DeepSeek key when a recorded model journey changes. The implemented [TUI snapshot RFC](../../docs/rfc/implemented/testing/2026-07-18-tui-terminal-state-snapshots.md) owns the scenario matrix and the split between recorded journeys, transient package snapshots, and PTY coverage.
`tests/snapshots/<scenario>/session.jsonl` supplies recorded user prompts and model chunks; sibling child logs drive subagents and workflows. The keyless suite executes those scripts through the real loop and tool implementations, then compares readable expected terminal cell/style output. Use `pnpm run test:snapshot:refresh` for presentation-only changes and `pnpm run test:snapshot:record` with a DeepSeek key when a recorded model journey changes. The implemented [TUI snapshot Agent Note](../../.agents/notes/implemented/testing/2026-07-18-tui-terminal-state-snapshots.md) owns the scenario matrix and the split between recorded journeys, transient package snapshots, and PTY coverage.