From 0c78c4c710da09d18c1da10b43a5c83033f8063a Mon Sep 17 00:00:00 2001 From: LogosVeritas Date: Wed, 28 Oct 2026 21:14:21 +0800 Subject: [PATCH] fix(sdk): return RunResult after native command activity --- .../profiles/sdk/checkpoints.expected.e2e.ts | 1 - .../profiles/sdk/dynamic-tool-cache.e2e.ts | 1 - .../tests/profiles/sdk/user-questions.e2e.ts | 1 - .../profile-continuation.worker.ts | 1 - docs/event-producer-consumer.md | 4 +- docs/event-producer-consumer.zh.md | 4 +- docs/module-graph.md | 3 +- docs/module-graph.zh.md | 3 +- .../sdk-run-commands/guide.i18n.yaml | 12 +- .../v0.2.2-alpha.2/sdk-run-commands/guide.md | 19 +- .../sdk-run-commands/guide.zh.md | 19 +- docs/user/guide/python-sdk.md | 4 +- docs/user/guide/python-sdk.zh.md | 4 +- packages/sdk/client/README.i18n.yaml | 16 +- packages/sdk/client/README.md | 19 +- packages/sdk/client/README.zh.md | 19 +- packages/sdk/client/src/api.ts | 62 ++- packages/sdk/client/src/index.ts | 1 - packages/sdk/client/src/types.ts | 12 +- .../tests/cot-translation-projection.spec.ts | 1 - packages/sdk/client/tests/fake-runtime.ts | 3 + packages/sdk/client/tests/fixtures/query.ts | 30 +- packages/sdk/client/tests/run.spec.ts | 82 ++-- packages/sdk/client/tests/sdk-client.spec.ts | 31 +- packages/sdk/protocol/README.i18n.yaml | 4 +- packages/sdk/protocol/README.md | 3 +- packages/sdk/protocol/README.zh.md | 3 +- packages/sdk/protocol/src/types.ts | 8 + packages/sdk/server/README.i18n.yaml | 4 +- packages/sdk/server/README.md | 4 +- packages/sdk/server/README.zh.md | 4 +- packages/sdk/server/package.json | 1 + packages/sdk/server/src/query-activity.ts | 161 ++++++ packages/sdk/server/src/server.ts | 28 +- packages/sdk/server/tests/commands.spec.ts | 2 +- .../sdk/server/tests/query-activity.spec.ts | 462 ++++++++++++++++++ packages/sdk/server/tsconfig.json | 3 + python/sdk/README.i18n.yaml | 4 +- python/sdk/README.md | 14 +- python/sdk/README.zh.md | 14 +- python/sdk/examples/README.i18n.yaml | 12 +- python/sdk/examples/README.md | 8 +- python/sdk/examples/README.zh.md | 8 +- python/sdk/examples/compact.py | 17 +- python/sdk/examples/goal.py | 57 +-- python/sdk/examples/minimal.py | 11 +- python/sdk/examples/permission.py | 17 +- python/sdk/examples/plan.py | 25 +- python/sdk/src/deepseek_harness/__init__.py | 3 +- python/sdk/src/deepseek_harness/api.py | 87 ++-- python/sdk/src/deepseek_harness/client.py | 9 - python/sdk/tests/run_installed_commands.py | 1 + .../tests/test_command_attachments_runtime.py | 50 +- python/sdk/tests/test_commands_runtime.py | 28 +- python/sdk/tests/test_goal_example.py | 85 ++-- .../tests/test_goal_result_text_runtime.py | 29 ++ python/sdk/tests/test_goal_runtime.py | 66 +-- python/sdk/tests/test_plan_runtime.py | 18 +- python/sdk/tests/test_run.py | 97 +++- snapshots/sdk/sdk.snapshot.ts | 46 +- 60 files changed, 1264 insertions(+), 481 deletions(-) create mode 100644 packages/sdk/server/src/query-activity.ts create mode 100644 packages/sdk/server/tests/query-activity.spec.ts create mode 100644 python/sdk/tests/test_goal_result_text_runtime.py diff --git a/apps/cli/tests/profiles/sdk/checkpoints.expected.e2e.ts b/apps/cli/tests/profiles/sdk/checkpoints.expected.e2e.ts index efa4eb722e..8f486aa25d 100644 --- a/apps/cli/tests/profiles/sdk/checkpoints.expected.e2e.ts +++ b/apps/cli/tests/profiles/sdk/checkpoints.expected.e2e.ts @@ -58,7 +58,6 @@ describe.skipIf(!existsSync(dshBin))('sdk-minimal durability checkpoints', () => }) onTestFinished(async () => { await harness.close() }) const result = await harness.run('Reply OK without calling tools.') - if ('commandId' in result) throw new Error('Expected prompt activity, received a command result') expect(modelRequests).toBe(disabled ? 1 : 0) const terminal = result.events.findLast(event => event.type === 'turn/end') expect(terminal).toMatchObject({ data: { reason: { kind: disabled ? 'completed' : 'error' } } }) diff --git a/apps/cli/tests/profiles/sdk/dynamic-tool-cache.e2e.ts b/apps/cli/tests/profiles/sdk/dynamic-tool-cache.e2e.ts index 17411c93de..ec5fe6ad94 100644 --- a/apps/cli/tests/profiles/sdk/dynamic-tool-cache.e2e.ts +++ b/apps/cli/tests/profiles/sdk/dynamic-tool-cache.e2e.ts @@ -101,7 +101,6 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('SDK native tool updates with rea const events: SessionEvent[] = [] const run = async (prompt: string) => { const result = await session.run(prompt) - if ('commandId' in result) throw new Error('Expected prompt activity, received a command result') events.push(...result.events) const failures = result.events.filter(event => event.type === 'assistant/attempt').map(event => ({ turn: event.data.turn, diff --git a/apps/cli/tests/profiles/sdk/user-questions.e2e.ts b/apps/cli/tests/profiles/sdk/user-questions.e2e.ts index 9d302090f8..b13b0dd542 100644 --- a/apps/cli/tests/profiles/sdk/user-questions.e2e.ts +++ b/apps/cli/tests/profiles/sdk/user-questions.e2e.ts @@ -77,7 +77,6 @@ it.each([ return } const result = await pending - if ('commandId' in result) throw new Error('Expected prompt activity, received a command result') expect(seen).toEqual([{ requestId: expect.any(String) as string, sessionId: 'question-session', questions }]) expect(result.finalResponse).toBe('answer received') expect(requests).toHaveLength(2) diff --git a/benchmarks/agent-continuation/profile-continuation.worker.ts b/benchmarks/agent-continuation/profile-continuation.worker.ts index 765986806f..f744add964 100644 --- a/benchmarks/agent-continuation/profile-continuation.worker.ts +++ b/benchmarks/agent-continuation/profile-continuation.worker.ts @@ -59,7 +59,6 @@ async function run(root: string): Promise { const booted = performance.now() for (let turn = 0; turn < WORKLOAD.profileTurns; turn++) { const result = await harness.run('Read the synthetic file ' + String(turn), { sessionId: PARENT_ID }) - if ('commandId' in result) throw new Error('Expected prompt activity, received a command result') requests += result.events.filter(event => event.type === 'assistant/message').length for (const event of result.events) { if (event.type !== 'tool/result') continue diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index e4318ec102..f645ad75b8 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -14,7 +14,7 @@ Application listeners are outside this package matrix. Desktop Host subscribes t | `agent-preset/selected` | `emit` | [`packages/preset/agent-preset-registry/src/types.ts:66`](../packages/preset/agent-preset-registry/src/types.ts) | [`agent-preset-registry`](../packages/preset/agent-preset-registry) (`emit`) | [`cua`](../packages/experimental/cua), `remotes` | | `agent/assistant-stream` | `emit` | [`packages/core/agent/src/runtime-types.ts:399`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`headless`](../packages/bundle/headless), `session-controller` | | `agent/created` | `serial` | [`packages/core/agent/src/runtime-types.ts:290`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`serial`) | `agent-team`, `browser-use-runtime`, `claude-code-mods`, [`creation-recommendations`](../packages/experimental/creation-recommendations), [`cua`](../packages/experimental/cua), [`file-reference-local`](../packages/context/file-reference-local), [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/experimental/hooks-claude-code), [`hooks-codex`](../packages/experimental/hooks-codex), `liveshare`, [`loader-smoke`](../packages/test-support/loader-smoke), [`permission-presets`](../packages/interaction/permission-presets), `session-controller`, `tool-agent-team`, [`tool-subagent`](../packages/subagent/tool-subagent) | -| `agent/disposed` | `emit` | [`packages/core/agent/src/runtime-types.ts:299`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`action-cards`](../packages/experimental/action-cards), [`agent-loop`](../packages/core/agent-loop), `claude-code-mods`, [`creation-recommendations`](../packages/experimental/creation-recommendations), [`file-reference-local`](../packages/context/file-reference-local), [`goal-round-driver`](../packages/goal/goal-round-driver), `session-controller`, [`subagent`](../packages/subagent/subagent), `tool-agent-team` | +| `agent/disposed` | `emit` | [`packages/core/agent/src/runtime-types.ts:299`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`action-cards`](../packages/experimental/action-cards), [`agent-loop`](../packages/core/agent-loop), `claude-code-mods`, [`creation-recommendations`](../packages/experimental/creation-recommendations), [`file-reference-local`](../packages/context/file-reference-local), [`goal-round-driver`](../packages/goal/goal-round-driver), `server`, `session-controller`, [`subagent`](../packages/subagent/subagent), `tool-agent-team` | | `agent/error` | `emit` | [`packages/core/agent/src/runtime-types.ts:429`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`deepseek-account`](../packages/credentials/deepseek-account), [`goal-round-driver`](../packages/goal/goal-round-driver), [`headless`](../packages/bundle/headless), `server`, `session-controller`, [`session-telemetry`](../packages/session/session-telemetry), [`subagent`](../packages/subagent/subagent) | | `agent/inbox/claimed` | `emit` | [`packages/core/agent/src/runtime-types.ts:328`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-round-driver`](../packages/goal/goal-round-driver), [`subagent`](../packages/subagent/subagent), [`tool-jobs`](../packages/jobs/tool-jobs), [`user-questions`](../packages/interaction/user-questions) | | `agent/inbox/discarded` | `emit` | [`packages/core/agent/src/runtime-types.ts:336`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-round-driver`](../packages/goal/goal-round-driver), [`subagent`](../packages/subagent/subagent), [`user-questions`](../packages/interaction/user-questions) | @@ -51,7 +51,7 @@ Application listeners are outside this package matrix. Desktop Host subscribes t | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:67`](../packages/fs/fs/src/index.ts) | `liveshare` (`waterfall`), [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`workspace-changes`](../packages/deliverables/workspace-changes) | | `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:77`](../packages/fs/fs/src/index.ts) | `liveshare` (`emit`), [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`skill-filesystem`](../packages/skill/skill-filesystem), `workspace-files` | | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:59`](../packages/fs/fs/src/index.ts) | `liveshare` (`waterfall`), [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`workspace-changes`](../packages/deliverables/workspace-changes) | -| `goal/activation-changed` | `emit` | [`packages/goal/goal/src/types.ts:147`](../packages/goal/goal/src/types.ts) | [`goal`](../packages/goal/goal) (`emit`) | `remotes` | +| `goal/activation-changed` | `emit` | [`packages/goal/goal/src/types.ts:147`](../packages/goal/goal/src/types.ts) | [`goal`](../packages/goal/goal) (`emit`) | `remotes`, `server` | | `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:114`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-round-driver`](../packages/goal/goal-round-driver) | | `hmr/change` | `emit` | [`packages/boot/hmr/src/index.ts:35`](../packages/boot/hmr/src/index.ts) | [`hmr`](../packages/boot/hmr) (`emit`) | - | | `hmr/reload` | `emit` | [`packages/boot/hmr/src/index.ts:40`](../packages/boot/hmr/src/index.ts) | [`hmr`](../packages/boot/hmr) (`emit`) | - | diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md index cb38f9f44c..7ce80c178c 100644 --- a/docs/event-producer-consumer.zh.md +++ b/docs/event-producer-consumer.zh.md @@ -16,7 +16,7 @@ | `agent-preset/selected` | `emit` | [`packages/preset/agent-preset-registry/src/types.ts:66`](../packages/preset/agent-preset-registry/src/types.ts) | [`agent-preset-registry`](../packages/preset/agent-preset-registry) (`emit`) | [`cua`](../packages/experimental/cua), `remotes` | | `agent/assistant-stream` | `emit` | [`packages/core/agent/src/runtime-types.ts:399`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`headless`](../packages/bundle/headless), `session-controller` | | `agent/created` | `serial` | [`packages/core/agent/src/runtime-types.ts:290`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`serial`) | `agent-team`, `browser-use-runtime`, `claude-code-mods`, [`creation-recommendations`](../packages/experimental/creation-recommendations), [`cua`](../packages/experimental/cua), [`file-reference-local`](../packages/context/file-reference-local), [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/experimental/hooks-claude-code), [`hooks-codex`](../packages/experimental/hooks-codex), `liveshare`, [`loader-smoke`](../packages/test-support/loader-smoke), [`permission-presets`](../packages/interaction/permission-presets), `session-controller`, `tool-agent-team`, [`tool-subagent`](../packages/subagent/tool-subagent) | -| `agent/disposed` | `emit` | [`packages/core/agent/src/runtime-types.ts:299`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`action-cards`](../packages/experimental/action-cards), [`agent-loop`](../packages/core/agent-loop), `claude-code-mods`, [`creation-recommendations`](../packages/experimental/creation-recommendations), [`file-reference-local`](../packages/context/file-reference-local), [`goal-round-driver`](../packages/goal/goal-round-driver), `session-controller`, [`subagent`](../packages/subagent/subagent), `tool-agent-team` | +| `agent/disposed` | `emit` | [`packages/core/agent/src/runtime-types.ts:299`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`action-cards`](../packages/experimental/action-cards), [`agent-loop`](../packages/core/agent-loop), `claude-code-mods`, [`creation-recommendations`](../packages/experimental/creation-recommendations), [`file-reference-local`](../packages/context/file-reference-local), [`goal-round-driver`](../packages/goal/goal-round-driver), `server`, `session-controller`, [`subagent`](../packages/subagent/subagent), `tool-agent-team` | | `agent/error` | `emit` | [`packages/core/agent/src/runtime-types.ts:429`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`deepseek-account`](../packages/credentials/deepseek-account), [`goal-round-driver`](../packages/goal/goal-round-driver), [`headless`](../packages/bundle/headless), `server`, `session-controller`, [`session-telemetry`](../packages/session/session-telemetry), [`subagent`](../packages/subagent/subagent) | | `agent/inbox/claimed` | `emit` | [`packages/core/agent/src/runtime-types.ts:328`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-round-driver`](../packages/goal/goal-round-driver), [`subagent`](../packages/subagent/subagent), [`tool-jobs`](../packages/jobs/tool-jobs), [`user-questions`](../packages/interaction/user-questions) | | `agent/inbox/discarded` | `emit` | [`packages/core/agent/src/runtime-types.ts:336`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-round-driver`](../packages/goal/goal-round-driver), [`subagent`](../packages/subagent/subagent), [`user-questions`](../packages/interaction/user-questions) | @@ -53,7 +53,7 @@ | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:67`](../packages/fs/fs/src/index.ts) | `liveshare` (`waterfall`), [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`workspace-changes`](../packages/deliverables/workspace-changes) | | `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:77`](../packages/fs/fs/src/index.ts) | `liveshare` (`emit`), [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`skill-filesystem`](../packages/skill/skill-filesystem), `workspace-files` | | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:59`](../packages/fs/fs/src/index.ts) | `liveshare` (`waterfall`), [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`workspace-changes`](../packages/deliverables/workspace-changes) | -| `goal/activation-changed` | `emit` | [`packages/goal/goal/src/types.ts:147`](../packages/goal/goal/src/types.ts) | [`goal`](../packages/goal/goal) (`emit`) | `remotes` | +| `goal/activation-changed` | `emit` | [`packages/goal/goal/src/types.ts:147`](../packages/goal/goal/src/types.ts) | [`goal`](../packages/goal/goal) (`emit`) | `remotes`, `server` | | `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:114`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-round-driver`](../packages/goal/goal-round-driver) | | `hmr/change` | `emit` | [`packages/boot/hmr/src/index.ts:35`](../packages/boot/hmr/src/index.ts) | [`hmr`](../packages/boot/hmr) (`emit`) | - | | `hmr/reload` | `emit` | [`packages/boot/hmr/src/index.ts:40`](../packages/boot/hmr/src/index.ts) | [`hmr`](../packages/boot/hmr) (`emit`) | - | diff --git a/docs/module-graph.md b/docs/module-graph.md index 396099dd71..29cfda9a32 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -1485,6 +1485,7 @@ flowchart TD pkg_sdk_jsonrpc_server --> pkg_agent pkg_sdk_jsonrpc_server --> pkg_attachment pkg_sdk_jsonrpc_server --> pkg_commands + pkg_sdk_jsonrpc_server --> pkg_goal pkg_sdk_jsonrpc_server --> pkg_llm pkg_sdk_jsonrpc_server --> pkg_llm_deepseek_api_key pkg_sdk_jsonrpc_server --> pkg_schedule @@ -1868,5 +1869,5 @@ flowchart TD | [`client-test-runtime`](../packages/test-support/client-runtime) | `test-support` | [`api-gateway`](../packages/api/gateway), [`api-session-controller`](../packages/api/session-controller), [`api-workspace-controller`](../packages/api/workspace-controller), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-hmr`](../packages/client/hmr), [`client-modules`](../packages/client/modules), [`client-store`](../packages/client/store), [`client-ui-chat`](../packages/client/ui-chat), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`client-web`](../packages/client/web), [`remote-mock`](../packages/test-support/remote-mock), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol) | | [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/sdk/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) | | [`tool-schedule`](../packages/schedule/tool-schedule) | `schedule` | [`llm`](../packages/llm/llm), [`schedule`](../packages/schedule/schedule), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) | -| [`sdk-jsonrpc-server`](../packages/sdk/server) | `sdk` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`commands`](../packages/interaction/commands), [`llm`](../packages/llm/llm), [`llm-deepseek-api-key`](../packages/llm/llm-deepseek-api-key), [`schedule`](../packages/schedule/schedule), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`user-approval`](../packages/interaction/user-approval), [`user-questions`](../packages/interaction/user-questions), [`working-directory`](../packages/session/working-directory) | +| [`sdk-jsonrpc-server`](../packages/sdk/server) | `sdk` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`llm`](../packages/llm/llm), [`llm-deepseek-api-key`](../packages/llm/llm-deepseek-api-key), [`schedule`](../packages/schedule/schedule), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`user-approval`](../packages/interaction/user-approval), [`user-questions`](../packages/interaction/user-questions), [`working-directory`](../packages/session/working-directory) | diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md index 626afc9a49..2c435b7492 100644 --- a/docs/module-graph.zh.md +++ b/docs/module-graph.zh.md @@ -1487,6 +1487,7 @@ flowchart TD pkg_sdk_jsonrpc_server --> pkg_agent pkg_sdk_jsonrpc_server --> pkg_attachment pkg_sdk_jsonrpc_server --> pkg_commands + pkg_sdk_jsonrpc_server --> pkg_goal pkg_sdk_jsonrpc_server --> pkg_llm pkg_sdk_jsonrpc_server --> pkg_llm_deepseek_api_key pkg_sdk_jsonrpc_server --> pkg_schedule @@ -1870,5 +1871,5 @@ flowchart TD | [`client-test-runtime`](../packages/test-support/client-runtime) | `test-support` | [`api-gateway`](../packages/api/gateway), [`api-session-controller`](../packages/api/session-controller), [`api-workspace-controller`](../packages/api/workspace-controller), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-hmr`](../packages/client/hmr), [`client-modules`](../packages/client/modules), [`client-store`](../packages/client/store), [`client-ui-chat`](../packages/client/ui-chat), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`client-web`](../packages/client/web), [`remote-mock`](../packages/test-support/remote-mock), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol) | | [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/sdk/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) | | [`tool-schedule`](../packages/schedule/tool-schedule) | `schedule` | [`llm`](../packages/llm/llm), [`schedule`](../packages/schedule/schedule), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) | -| [`sdk-jsonrpc-server`](../packages/sdk/server) | `sdk` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`commands`](../packages/interaction/commands), [`llm`](../packages/llm/llm), [`llm-deepseek-api-key`](../packages/llm/llm-deepseek-api-key), [`schedule`](../packages/schedule/schedule), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`user-approval`](../packages/interaction/user-approval), [`user-questions`](../packages/interaction/user-questions), [`working-directory`](../packages/session/working-directory) | +| [`sdk-jsonrpc-server`](../packages/sdk/server) | `sdk` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`llm`](../packages/llm/llm), [`llm-deepseek-api-key`](../packages/llm/llm-deepseek-api-key), [`schedule`](../packages/schedule/schedule), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`user-approval`](../packages/interaction/user-approval), [`user-questions`](../packages/interaction/user-questions), [`working-directory`](../packages/session/working-directory) | diff --git a/docs/upgrade-guide/v0.2.2-alpha.2/sdk-run-commands/guide.i18n.yaml b/docs/upgrade-guide/v0.2.2-alpha.2/sdk-run-commands/guide.i18n.yaml index e5444d2f37..8e0de6c4de 100644 --- a/docs/upgrade-guide/v0.2.2-alpha.2/sdk-run-commands/guide.i18n.yaml +++ b/docs/upgrade-guide/v0.2.2-alpha.2/sdk-run-commands/guide.i18n.yaml @@ -3,14 +3,14 @@ # After editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.2-alpha.2/sdk-run-commands/guide.md /: - en: 66fb7f6d320077f7 - zh: 5972bcc5548dcdeb + en: 695ee5740865d684 + zh: 83cb4df5ecf20a99 /sdk-run-accepts-native-commands: en: 54f8a31426f4758c zh: 283820d3f187092e /sdk-run-accepts-native-commands/change: - en: 4ded2e89cef962d2 - zh: 097e25c63d81bc15 + en: 478742169aa04c50 + zh: 3324d99f4206d1fc /sdk-run-accepts-native-commands/migration: - en: 302378fd8aeb24c5 - zh: 854a98cf76e83323 + en: 484261a946a13012 + zh: bab28bbde44fbc61 diff --git a/docs/upgrade-guide/v0.2.2-alpha.2/sdk-run-commands/guide.md b/docs/upgrade-guide/v0.2.2-alpha.2/sdk-run-commands/guide.md index 815a7b1379..4ceab1e4fd 100644 --- a/docs/upgrade-guide/v0.2.2-alpha.2/sdk-run-commands/guide.md +++ b/docs/upgrade-guide/v0.2.2-alpha.2/sdk-run-commands/guide.md @@ -1,6 +1,6 @@ --- kind: upgrade-guide -description: "SDK run routes native commands by definition identity and returns prompt activity or command results." +description: "SDK run recognizes native commands and returns RunResult after its input completes." --- # SDK run accepts native commands @@ -9,17 +9,16 @@ English | [中文](guide.zh.md) ## Change -Python `DeepSeekHarness.run()` and `Session.run()`, and their TypeScript equivalents, keep the existing public `run()` entry for strings and content-block arrays and route both as prompts or commands. Ordinary input returns `RunResult`; supported commands return `RunCommandResult`. Commands are identified by their official definition IDs and execute under their current registered names. English and Chinese aliases follow renamed definitions; an unrelated exact-name replacement remains ordinary input. See the [supported command rules](../../../../packages/sdk/server/README.md#command-input). +Python and TypeScript `run()` accept strings and content-block arrays through the existing entry and always return `RunResult`. Supported native commands are recognized by their definition identities and effective registered names. English and Chinese aliases follow renamed definitions; unrelated exact-name replacements remain ordinary input. See the [supported command rules](../../../../packages/sdk/server/README.md#command-input). -Arrays no longer bypass native routing: `run([{"type": "text", "text": "/compact"}])` executes compaction. Commands with encoded raster images follow native attachment rules; `/plan off` with an image returns a command error without changing plan state. Command completion does not mean subsequent planning, review, or goal rounds have finished. Handler refusals remain command results; routing and transport failures raise or reject. +`final_response` / `finalResponse` contains the final assistant text, or an empty string when the activity emits none. State-only commands return the native handler's result text. `finish_reason` / `finishReason` reports the terminal outcome. Every result retains its Session id, root events and Session-tree notifications. State-only commands finish without waiting for a model turn; `/plan ` waits for its admitted activity, including native review and any approved continuation. Goal creation and resume wait across automatic rounds until the goal stops and its closing activity ends. Low-level strict command calls still return `CommandExecution` after the native handler settles. -`run("")`, `run([])`, and inputs containing only blank text now fail before Session creation or prompt enqueue. Image-only input remains accepted. Strict command identity checks use the initialized receiving Agent's catalog. Identity rejection retains that Session without executing a handler or submitting a prompt. +Content-block arrays no longer bypass native routing. A recognized command requires one text block and optional encoded raster images; native handlers enforce image admission. `/plan off` with an image fails without changing plan state. Empty arrays and blank-only input reject before Session creation; image-only input remains accepted. Identity rejection by the strict endpoint retains its initialized Session without executing a handler or submitting a prompt. ## Migration -1. Filter empty or blank input before `run()`. Check the returned type before reading `final_response` in Python or `finalResponse` in TypeScript: use `isinstance(result, RunResult)` or `'finalResponse' in result`. Both results carry `session_id`/`sessionId`, including for an automatically created Session. `RunCommandResult` also retains the native `CommandExecution` fields, including `command_id`/`commandId` and `result.kind`. -2. For literal queued input, use Python `client.session_prompt(session_id, blocks)` or TypeScript `client.prompt(sessionId, blocks)`. Subscribe first and manage notifications and `session/wait`; these methods return receipts, not `RunResult`. Enqueue acceptance does not guarantee the model accepts empty input. Runtime skill recognition still applies. -3. For images, select an image-capable model and use the existing `run([text_block, image_block])` form. Encoded images contain `type: "image"`, base64 `data`, and `mimeType`. A matched command requires one complete text block and only encoded images beside it; extra text or other attachments reject without prompt fallback. Images may precede the text block. -4. Custom `session/query` clients send `{ sessionId, contentBlocks, delivery }`; delivery is `queue` or `steer` for ordinary prompts. `session/command` keeps `{ sessionId, line }` and accepts ASCII registered names or canonical English aliases of supported definitions. Chinese aliases use `run()`/`session/query`; a matching name alone does not establish builtin identity. -5. Python malformed command responses from `run()` and `session_command()` raise `SdkProtocolError`, retaining the validation error as their cause. Generic `request(response_model=...)` keeps its caller-selected model validation behavior. -6. Keep `on_notification`/`onNotification` for activity. Both command entry points send lifecycle notifications before their response; forwarding transports must preserve this order. Follow the server's command-completion rules for subsequent model work. +1. Keep the existing `result.final_response` / `result.finalResponse` access for prompts and commands. Inspect `finish_reason` / `finishReason` for failure; command ids and native outcomes remain in `command/run` and `command/done` events. Save the result's Session id to continue or restore it. +2. Keep the user-question callback alive for plan review. State-changing command failures appear in `RunResult`; routing, malformed protocol data and transport failures still raise or reject. A timeout or observer failure does not roll back runtime work. +3. For literal queued input, use Python `client.session_prompt(session_id, blocks)` or TypeScript `client.prompt(sessionId, blocks)`, and manage its subsequent activity. Runtime skill recognition still applies. +4. Custom `session/query` clients send `{ sessionId, contentBlocks, delivery }`. Command responses acknowledge the native handler; the matching `session.query.completed` notification carries the final input outcome. Preserve notification order and subscribe before sending. `session/command` retains its strict, attachment-free behavior. +5. Filter empty input before calling `run()`. Use an image-capable model and the existing `run([text_block, image_block])` form for images. Python malformed native command responses raise `SdkProtocolError`, preserving their validation cause; generic caller-selected response models retain their validation behavior. diff --git a/docs/upgrade-guide/v0.2.2-alpha.2/sdk-run-commands/guide.zh.md b/docs/upgrade-guide/v0.2.2-alpha.2/sdk-run-commands/guide.zh.md index 1968791eaf..aaefe1939c 100644 --- a/docs/upgrade-guide/v0.2.2-alpha.2/sdk-run-commands/guide.zh.md +++ b/docs/upgrade-guide/v0.2.2-alpha.2/sdk-run-commands/guide.zh.md @@ -1,6 +1,6 @@ --- kind: upgrade-guide -description: "SDK run 按定义身份路由原生命令,返回提示词活动或命令结果。" +description: "SDK run 识别原生命令,并在本次输入完成后返回 RunResult。" --- # SDK run 接受原生命令 @@ -9,17 +9,16 @@ description: "SDK run 按定义身份路由原生命令,返回提示词活动 ## 变更 -Python 的 `DeepSeekHarness.run()`、`Session.run()` 及其 TypeScript 对应方法,沿用现有公开 `run()` 入口接收字符串与内容块数组,并将两者路由为提示词或命令。普通输入返回 `RunResult`,受支持命令返回 `RunCommandResult`。命令按官方定义 ID 识别,并以当前注册名执行。中英文别名跟随重命名后的定义,无关的精确同名替换仍作为普通输入。详见[受支持命令规则](../../../../packages/sdk/server/README.zh.md#command-input)。 +Python 和 TypeScript 的 `run()` 通过原有入口接受字符串和内容块数组,始终返回 `RunResult`。受支持原生命令按定义身份和实际注册名识别。中英文别名跟随重命名的定义;无关的同名替代命令仍作为普通输入。见[支持的命令规则](../../../../packages/sdk/server/README.zh.md#command-input)。 -数组不再绕过原生路由:`run([{"type": "text", "text": "/compact"}])` 会执行压缩。命令携带编码栅格图片时遵循原生附件规则;`/plan off` 携带图片会返回命令错误,且不改变计划状态。命令完成不表示后续计划、审阅或目标轮次已经结束。处理器拒绝仍是命令结果,路由与传输失败会抛出异常或拒绝。 +`final_response` / `finalResponse` 包含最终助手文本;活动未输出助手文本时为空字符串。仅改变状态的命令返回原生 handler 的结果文本。`finish_reason` / `finishReason` 表示结束结果。每份结果都保留 Session id、根会话事件和会话树通知。仅改变状态的命令无需等待模型 turn;`/plan ` 等待其提交的活动,包括原生审阅及获批后的后续执行。目标创建和恢复跨越自动轮次等待,直到目标停止及最后的活动结束。底层严格命令调用仍在原生 handler 完成后返回 `CommandExecution`。 -`run("")`、`run([])` 及仅包含空白文本的输入会在创建 Session 或入队前失败,仅图片输入仍被接受。严格命令的身份校验使用已初始化的接收 Agent 目录。身份校验拒绝会保留该 Session,不执行 handler,也不提交 prompt。 +内容块数组不再绕过原生命令路由。已识别命令要求一个文本块及可选的编码位图;原生 handler 执行图片准入。`/plan off` 带图片会失败且不改变计划状态。空数组和纯空白输入在创建 Session 前拒绝;纯图片输入仍然接受。严格端点拒绝命令身份时保留已经初始化的 Session,不执行 handler 或提交提示词。 ## 迁移 -1. 在调用 `run()` 前过滤空输入或空白输入。在 Python 读取 `final_response` 或 TypeScript 读取 `finalResponse` 前检查返回类型:使用 `isinstance(result, RunResult)` 或 `'finalResponse' in result`。两种结果都包含 `session_id`/`sessionId`,包括自动创建的 Session。`RunCommandResult` 还保留原生 `CommandExecution` 字段,包括 `command_id`/`commandId` 及 `result.kind`。 -2. 原样排队输入使用 Python `client.session_prompt(session_id, blocks)` 或 TypeScript `client.prompt(sessionId, blocks)`。先订阅,再管理通知及 `session/wait`;这些方法返回回执,而不是 `RunResult`。入队被接受不保证模型接受空输入。运行时技能识别仍适用。 -3. 图片输入选择支持图片的模型,沿用 `run([text_block, image_block])`。编码图片包含 `type: "image"`、base64 `data` 和 `mimeType`。匹配到的命令要求一个完整文本块,其余只能是编码图片;额外文本或其他附件会被拒绝,不回退为提示词。图片可放在文本块之前。 -4. 自定义 `session/query` 客户端发送 `{ sessionId, contentBlocks, delivery }`,普通提示词的 delivery 为 `queue` 或 `steer`。`session/command` 保留 `{ sessionId, line }`,接受受支持定义的 ASCII 注册名或英文规范别名。中文别名使用 `run()`/`session/query`;名称相同不代表内置定义身份。 -5. Python 的 `run()` 和 `session_command()` 收到格式错误的命令响应时抛出 `SdkProtocolError`,并保留校验错误作为 cause。通用 `request(response_model=...)` 保留调用方所选模型的校验行为。 -6. 继续使用 `on_notification`/`onNotification` 观察活动。两个命令入口都先发送生命周期通知,再返回响应;转发方必须保序。后续模型工作遵循服务端的命令完成规则。 +1. 普通提示词和命令均继续使用 `result.final_response` / `result.finalResponse`。通过 `finish_reason` / `finishReason` 检查失败;命令 id 和原生结果保留在 `command/run` 与 `command/done` 事件中。保存结果的 Session id,以便继续或恢复会话。 +2. 计划审阅期间保持用户问题回调可用。状态变更命令的失败体现在 `RunResult` 中;路由、协议数据格式和传输失败仍抛出或拒绝。超时或观察回调失败不会回滚运行时工作。 +3. 需要按原文排队输入时,使用 Python `client.session_prompt(session_id, blocks)` 或 TypeScript `client.prompt(sessionId, blocks)`,并管理后续活动。运行时技能识别仍然适用。 +4. 自定义 `session/query` 客户端发送 `{ sessionId, contentBlocks, delivery }`。命令响应确认原生 handler 完成;对应的 `session.query.completed` 通知携带本次输入的最终结果。保持通知顺序,并在发送前订阅。`session/command` 保持严格、无附件的行为。 +5. 调用 `run()` 前过滤空输入。图片使用支持图片的模型及原有 `run([text_block, image_block])` 形式。Python 对格式错误的原生命令响应抛出 `SdkProtocolError`,保留校验原因;调用者自行选择的通用响应模型保留原有校验行为。 diff --git a/docs/user/guide/python-sdk.md b/docs/user/guide/python-sdk.md index 8250c9151d..38f6a2a531 100644 --- a/docs/user/guide/python-sdk.md +++ b/docs/user/guide/python-sdk.md @@ -98,7 +98,7 @@ The script prints the final assistant response or the command result supplied by ```python from pathlib import Path -from deepseek_harness import DeepSeekHarness, RunResult +from deepseek_harness import DeepSeekHarness workspace = Path("/absolute/path/to/disposable-workspace").resolve() dsh_home = Path("/absolute/path/to/example-dsh-home").resolve() @@ -115,7 +115,7 @@ with DeepSeekHarness( session_id="example-001", ) -print(result.final_response if isinstance(result, RunResult) else result.result.text) +print(result.final_response) ``` The SDK starts the bundled `dsh --profile sdk-minimal` process lazily and reuses it until context-manager exit. The profile, its persistent patch, the home patch, and any ordered `patches` tuple form the application configuration. There is no separate Python runtime bin or complete-config option. diff --git a/docs/user/guide/python-sdk.zh.md b/docs/user/guide/python-sdk.zh.md index d69fafcd60..cd321cfad6 100644 --- a/docs/user/guide/python-sdk.zh.md +++ b/docs/user/guide/python-sdk.zh.md @@ -98,7 +98,7 @@ python python/sdk/examples/minimal.py ` ```python from pathlib import Path -from deepseek_harness import DeepSeekHarness, RunResult +from deepseek_harness import DeepSeekHarness workspace = Path("/absolute/path/to/disposable-workspace").resolve() dsh_home = Path("/absolute/path/to/example-dsh-home").resolve() @@ -115,7 +115,7 @@ with DeepSeekHarness( session_id="example-001", ) -print(result.final_response if isinstance(result, RunResult) else result.result.text) +print(result.final_response) ``` SDK 会延迟启动内置的 `dsh --profile sdk-minimal` 进程,并复用到上下文管理器退出。Profile、其持久 patch、home patch 与任何有序 `patches` tuple 共同组成应用配置。不存在独立 Python 运行时 bin 或完整配置选项。 diff --git a/packages/sdk/client/README.i18n.yaml b/packages/sdk/client/README.i18n.yaml index ea487c70d8..7d8ccdad3b 100644 --- a/packages/sdk/client/README.i18n.yaml +++ b/packages/sdk/client/README.i18n.yaml @@ -18,14 +18,14 @@ en: 6c37c21a2e53376b zh: e707d3e81c1242bd /deepseek-ai-dsh-sdk-client/use-this-package/running-agent-turns-with-deepseekharness: - en: 0e155c826651ff5e - zh: 874fceaa9c13e3fa + en: 917f83f3388eaef4 + zh: 457977edc30d14fd /deepseek-ai-dsh-sdk-client/use-this-package/run-text-and-native-commands: - en: cb3ec67ee5c0575d - zh: 33a6b19ef65b5d14 + en: 0fb753f5fca657a9 + zh: 4a3009a8e4010239 /deepseek-ai-dsh-sdk-client/use-this-package/lower-level-control-with-harnessclient: - en: 823c71066513eb8d - zh: 83970539344ea4f7 + en: 52ec138e57a66472 + zh: fc6f6ea086f7d850 /deepseek-ai-dsh-sdk-client/use-this-package/native-user-questions: en: f5b9d6a7363bd9e5 zh: f53b3786d22a729d @@ -36,8 +36,8 @@ en: ac3c6eae3f8248fc zh: b929079016396c8e /deepseek-ai-dsh-sdk-client/understand-the-implementation/source-map: - en: 2a4da3d0785201b6 - zh: 56bbe428222a5805 + en: ee896439a5c07ca3 + zh: 1b18751fe2db250e /deepseek-ai-dsh-sdk-client/understand-the-implementation/owned-activity-flow: en: 94a42babac5f1c7d zh: df9e42ed02f7d002 diff --git a/packages/sdk/client/README.md b/packages/sdk/client/README.md index b997ad6066..90e4a93207 100644 --- a/packages/sdk/client/README.md +++ b/packages/sdk/client/README.md @@ -49,10 +49,10 @@ await using harness = new DeepSeekHarness({ maxTokens: 49_152, }) const result = await harness.run('say hi') -console.log('finalResponse' in result ? result.finalResponse : result.result) +console.log(result.finalResponse) ``` -The subprocess starts lazily on first use and stays owned by the instance across `run()` calls; call `close()` (or use `await using`) so the child is always reaped. `start()` memoizes the bounded `initialize` handshake, which carries the workspace cwd, provider/model route, optional adapter-owned `reasoningEffort`, and optional positive `maxTokens` output cap. The server validates that exact route before it accepts prompts; an omitted effort preserves the model's default. `initializeTimeoutMs` defaults to 10 seconds, and its diagnostic names the selected profile with the retained stderr tail. `run(input, { sessionId?, onNotification?, delivery? })` accepts text or `SdkPromptContentBlock[]`; an inline raster block carries canonical base64 plus `mimeType` and becomes a durable attachment inside the runtime. For ordinary input, the call owns one activity interval: it queues the prompt, waits until its message id appears in a durable inbox receipt, then collects through the next whole-agent `idle`. That path returns `RunResult { sessionId, finalResponse, events, notifications }`, where `finalResponse` is the last committed root-session assistant text in that interval — not a response causally assigned to the prompt, because steering, injected context, and other queued work may contribute before idle. `session(id?)` opens a named or fresh session handle. When a failed handshake is cleaned up successfully, the instance installs a fresh client so a later call retries with a new process until terminal `close()`; if initialization and cleanup both fail, `start()` returns an ordered `AggregateError` and retains the failed client instead of spawning beside a process whose exit is unproved. `maxTokens` caps each root-agent request output and is inherited by in-process descendants; compaction plugins own their separate summary limits. +The subprocess starts lazily on first use and stays owned by the instance across `run()` calls; call `close()` (or use `await using`) so the child is always reaped. `start()` memoizes the bounded `initialize` handshake, which carries the workspace cwd, provider/model route, optional adapter-owned `reasoningEffort`, and optional positive `maxTokens` output cap. The server validates that exact route before it accepts prompts; an omitted effort preserves the model's default. `initializeTimeoutMs` defaults to 10 seconds, and its diagnostic names the selected profile with the retained stderr tail. `run(input, { sessionId?, onNotification?, delivery? })` accepts text or `SdkPromptContentBlock[]`; an inline raster block carries canonical base64 plus `mimeType` and becomes a durable attachment inside the runtime. For ordinary input, the call owns one activity interval: it queues the prompt, waits until its message id appears in a durable inbox receipt, then collects through the next whole-agent `idle`. That path returns `RunResult { sessionId, finalResponse, finishReason, events, notifications }`, where `finalResponse` is the last committed root-session assistant text in that interval — not a response causally assigned to the prompt, because steering, injected context, and other queued work may contribute before idle. `session(id?)` opens a named or fresh session handle. When a failed handshake is cleaned up successfully, the instance installs a fresh client so a later call retries with a new process until terminal `close()`; if initialization and cleanup both fail, `start()` returns an ordered `AggregateError` and retains the failed client instead of spawning beside a process whose exit is unproved. `maxTokens` caps each root-agent request output and is inherited by in-process descendants; compaction plugins own their separate summary limits. ### Run text and native commands @@ -66,27 +66,26 @@ import { DeepSeekHarness } from '@deepseek-ai/dsh-sdk-client' await using harness = new DeepSeekHarness({ profile: 'sdk', dshHome: '/absolute/path/to/dsh-home' }) const session = harness.session() const result = await session.run('/compact') -if ('commandId' in result) console.log(result.result) -else console.log(result.finalResponse) +console.log(result.finalResponse) ``` -Both string and content-block input return `RunCommandResult` for a command or `RunResult` for ordinary prompt activity. Both results include `sessionId`, including when `harness.run()` creates a fresh Session. `RunCommandResult` extends the native `CommandExecution` with that Session identity. Commands settle without requiring a turn or idle notification. Business refusals remain `result.kind === "error"`; routing, protocol, transport and observer failures reject. A command retains `commandId` and optional summary `sourceEventSeq` instead of selecting an assistant reply. To bypass native command routing, use the low-level `client.prompt(sessionId, blocks)` and manage the subsequent subscription and wait yourself; runtime skill recognition still applies. +String and content-block input always return `RunResult` with `sessionId`, `finalResponse`, `finishReason`, root events and Session-tree notifications. State-only commands return native result text; commands that submit model work wait for that activity and return its final assistant text, or an empty string when none is emitted. Native refusals use `finishReason === "error"`; routing, protocol, transport and observer failures reject. Command ids and native outcomes remain in `command/run` and `command/done` events. For literal queued input, use the low-level `client.prompt(sessionId, blocks)` and manage subsequent activity; runtime skill recognition still applies. -Every call owns a subscription installed before sending and released before settlement. `onNotification` observes ordinary receipt-to-idle activity in wire order. Command callbacks replay Session-tree notifications from subscription through their own `command/done` after the command response; overlapping work can appear in that interval. Concurrent calls keep their own results, so a running model turn can coexist with a command's native busy result. Timeout or observer failure does not roll back runtime work or authorize automatic retry; command completion does not end independent model activity. +Every call subscribes before sending and releases its subscription before settlement. `onNotification` observes the input's Session-tree activity in wire order; the interval can include overlapping work. The SDK consumes internal completion receipts. Concurrent calls retain independent results, including a native busy result during model activity. Timeout or observer failure does not roll back runtime work or authorize automatic retry. Launch options supply initial values. A permission command changes only its target Session; later inputs and restoration retain that state, other Sessions keep theirs, and new Sessions use configured defaults. It does not update the options object or saved user defaults. An approval-policy change during a running turn can inject a notice and cause another step. See [permission presets](../../interaction/permission-presets/README.md) for native transition and restoration behavior. -`run('/plan')` enters plan mode; `/plan off` leaves; `/plan ` enters and steers the message. The call returns `RunCommandResult` while model work and review can continue. Enter first and run ordinary text when a `RunResult` is needed. For combined input, subscribe before `run()` and wait through `client.request('session/wait', { sessionId })`; keep question handling alive until the work finishes. Plan state does not change permissions. +`run('/plan')` enters plan mode; `/plan off` leaves; `/plan ` enters and steers the body. `run()` waits for submitted model activity, native review and approved continuation without an extra caller-owned subscription or wait. Answer plan review through the user-question handler; the `exit_plan_mode` plan is in the question's `detail`. Plan mode does not change permissions. Goal creation and resume through `run()` wait across automatic rounds until the goal stops and the last reply ends; pause or clear returns `aborted`, while blocking or lost activation reports failure. ### Lower-level control with HarnessClient `client.executeCommand(sessionId, line)` accepts ASCII registered names or canonical English aliases of supported builtin definitions, without prompt fallback or attachments; it requires a non-blank permission preset and returns the native `CommandExecution`. Use `run()` for Chinese aliases. A non-blank unknown preset reaches the native handler and returns `result.kind === "error"`. Subscribe before the command call when notifications are needed. A request timeout abandons only the local wait; runtime work can continue afterward. -Native goal creation and resume can start automatic rounds after the command call returns. Subscribe before sending; observe a terminal `goal/change` operation before using `session/wait` for the closing reply. Idle between rounds is not goal completion. See the [server semantics](../server/README.md) for pause, clear, restoration, and permission behavior. +With `client.executeCommand()`, goal creation and resume can start automatic rounds after the call returns. Subscribe before sending; observe a terminal `goal/change` operation before using `session/wait` for the closing reply. Idle between rounds is not goal completion. See the [server semantics](../server/README.md) for pause, clear, restoration, and permission behavior. `HarnessClient` is the protocol client under the run API: explicit `start()`, `initialize()`, `prompt()`, `request()`, and `close()`, plus notification subscriptions. `prompt()` returns the queued message id as soon as the runtime accepts it and never waits for agent activity. `subscribe(filter?)` returns a `NotificationSubscription` (awaitable `next()`, non-blocking `tryNext()`, async iteration); `subscribeSessionTree(id)` scopes to one session and the descendants discovered from `subagent.started` lineage edges — the runtime notifies for every session in its context, and scoping is client-side, exactly like the Python SDK. -Task-owning consumers can subscribe before `prompt()`, then call `request('session/wait', { sessionId })` and drain queued notifications with `tryNext()`. This waits for managed descendants and their root summary turns; `HarnessSession.run()` retains its next-idle interval. `validatedSessionEvent()` validates the event envelope and the assistant/turn fields consumed by SDK readers before they enter an output fold. +Task-owning consumers can subscribe before `prompt()`, then call `request('session/wait', { sessionId })` and drain queued notifications with `tryNext()`. This waits for managed descendants and their root summary turns; `HarnessSession.run()` retains its next-idle interval for ordinary prompts. `validatedSessionEvent()` validates the event envelope and the assistant/turn fields consumed by SDK readers before they enter an output fold. The client exports typed errors for every failure mode: `JsonRpcResponseError` (a wire error response, code and data preserved), `RequestTimeoutError` (a configured bound elapsed), `SdkProtocolError` (a response outside the documented protocol), and `TransportClosedError` (the runtime is gone — the message carries the exit code and a bounded stderr tail). `close()` requests protocol `shutdown` (bounded by `shutdownTimeoutMs`, default 1000 ms), then walks a stdin-EOF → SIGTERM → SIGKILL ladder until the process has exited; it is idempotent, and a closed client refuses reuse. `HarnessClientOptions.env` replaces the child environment entirely when given (`undefined` inherits the parent's); callers own credential policy — `scrubbedParentEnv` from `dsh-subprocess` is the shared scrub base for isolation-minded launches. @@ -118,7 +117,7 @@ The client is two layers over one wire: `DeepSeekHarness` (owned runs) over `Har | [`src/api.ts`](src/api.ts) | `DeepSeekHarness` + `HarnessSession`: unified input routing, owned activity intervals and command results | | [`src/client.ts`](src/client.ts) | `HarnessClient`: spawn, handshake, requests, subscription fan-out, typed errors | | [`src/dispose.ts`](src/dispose.ts) | Private teardown ladder: stdin EOF → SIGTERM → SIGKILL to actual exit | -| [`src/types.ts`](src/types.ts) | Launch and timeout options, notifications, `RunResult` and `RunCommandResult` | +| [`src/types.ts`](src/types.ts) | Launch and timeout options, notifications, `RunResult` | | [`src/index.ts`](src/index.ts) | Consumer interface: the two client layers and caller-facing types | ### Owned activity flow diff --git a/packages/sdk/client/README.zh.md b/packages/sdk/client/README.zh.md index 829df894e1..9a3474be0c 100644 --- a/packages/sdk/client/README.zh.md +++ b/packages/sdk/client/README.zh.md @@ -49,10 +49,10 @@ await using harness = new DeepSeekHarness({ maxTokens: 49_152, }) const result = await harness.run('say hi') -console.log('finalResponse' in result ? result.finalResponse : result.result) +console.log(result.finalResponse) ``` -子进程在首次使用时惰性启动,并在多次 `run()` 调用之间持续归实例所有;请调用 `close()`(或使用 `await using`),子进程才总能被回收。`start()` 会记忆化有界的 `initialize` 握手,其中包含工作区 cwd、提供方/模型路由、可选且由适配器持有的 `reasoningEffort`,以及可选的正整数 `maxTokens` 输出上限。服务器会在接受提示词前校验该确切路由;省略推理强度时保留模型自身的默认值。`initializeTimeoutMs` 默认 10 秒,诊断会写明所选 profile 并附带保留的 stderr 尾部。`run(input, { sessionId?, onNotification?, delivery? })` 接受文本或 `SdkPromptContentBlock[]`;内联栅格图像块携带规范 base64 与 `mimeType`,并在运行时内变成持久附件。对于普通输入,该调用拥有一个活动区间:它将提示词排入队列,等待其消息 id 出现在持久入队回执中,然后持续收集到整个 agent 下一次进入 `idle`。该路径返回 `RunResult { sessionId, finalResponse, events, notifications }`,其中 `finalResponse` 是该区间内根会话最后提交的助手文本——并非因果上归属于该提示词的响应,因为 steering(中途引导)、注入的上下文和其他排队工作都可能在 idle 前参与其中。`session(id?)` 打开具名或全新的会话句柄。握手失败且清理成功时,实例会换入全新客户端,使后续调用用新进程重试,直到终结性的 `close()`;如果初始化和清理均失败,`start()` 会返回保留两个原因的有序 `AggregateError`,并继续保留失败的客户端,避免在原进程退出尚未得到证明时启动另一个进程。`maxTokens` 限制每个根 agent 请求的输出量,并由进程内后代继承;压缩(compaction)插件单独持有摘要上限。 +子进程在首次使用时惰性启动,并在多次 `run()` 调用之间持续归实例所有;请调用 `close()`(或使用 `await using`),子进程才总能被回收。`start()` 会记忆化有界的 `initialize` 握手,其中包含工作区 cwd、提供方/模型路由、可选且由适配器持有的 `reasoningEffort`,以及可选的正整数 `maxTokens` 输出上限。服务器会在接受提示词前校验该确切路由;省略推理强度时保留模型自身的默认值。`initializeTimeoutMs` 默认 10 秒,诊断会写明所选 profile 并附带保留的 stderr 尾部。`run(input, { sessionId?, onNotification?, delivery? })` 接受文本或 `SdkPromptContentBlock[]`;内联栅格图像块携带规范 base64 与 `mimeType`,并在运行时内变成持久附件。对于普通输入,该调用拥有一个活动区间:它将提示词排入队列,等待其消息 id 出现在持久入队回执中,然后持续收集到整个 agent 下一次进入 `idle`。该路径返回 `RunResult { sessionId, finalResponse, finishReason, events, notifications }`,其中 `finalResponse` 是该区间内根会话最后提交的助手文本——并非因果上归属于该提示词的响应,因为 steering(中途引导)、注入的上下文和其他排队工作都可能在 idle 前参与其中。`session(id?)` 打开具名或全新的会话句柄。握手失败且清理成功时,实例会换入全新客户端,使后续调用用新进程重试,直到终结性的 `close()`;如果初始化和清理均失败,`start()` 会返回保留两个原因的有序 `AggregateError`,并继续保留失败的客户端,避免在原进程退出尚未得到证明时启动另一个进程。`maxTokens` 限制每个根 agent 请求的输出量,并由进程内后代继承;压缩(compaction)插件单独持有摘要上限。 ### 运行文本与原生命令 @@ -66,27 +66,26 @@ import { DeepSeekHarness } from '@deepseek-ai/dsh-sdk-client' await using harness = new DeepSeekHarness({ profile: 'sdk', dshHome: '/absolute/path/to/dsh-home' }) const session = harness.session() const result = await session.run('/compact') -if ('commandId' in result) console.log(result.result) -else console.log(result.finalResponse) +console.log(result.finalResponse) ``` -字符串和内容块输入被识别为命令时都返回 `RunCommandResult`,普通提示词活动返回 `RunResult`。两种结果都包含 `sessionId`,包括 `harness.run()` 创建新 Session 的情况。`RunCommandResult` 在原生 `CommandExecution` 上增加该 Session 标识。命令完成不需要 turn 或 idle 通知。业务拒绝仍为 `result.kind === "error"`;路由、协议、传输和观察回调失败会拒绝 Promise。命令保留 `commandId` 及可选摘要 `sourceEventSeq`,不会选取助手回复作为结果。要绕过原生命令路由,使用低层 `client.prompt(sessionId, blocks)` 并自行管理后续订阅与等待;运行时 skill(技能)识别仍然适用。 +字符串和内容块输入始终返回 `RunResult`,包含 `sessionId`、`finalResponse`、`finishReason`、根会话事件和会话树通知。仅改变状态的命令返回原生结果文本;提交模型工作的命令等待对应活动并返回最终助手文本,未输出助手文本时返回空字符串。原生拒绝通过 `finishReason === "error"` 表达,路由、协议、传输和观察回调失败会拒绝 Promise。命令 id 和原生结果保留在 `command/run`、`command/done` 事件中。需要按原文排队时,使用底层 `client.prompt(sessionId, blocks)` 并管理后续活动;运行时技能识别仍然适用。 -每次调用都拥有自己的订阅,在发送前安装,在调用完成前释放。`onNotification` 按线上的顺序观察普通输入从入队回执到 idle 的活动。命令回调在命令响应到达后,按顺序交付从订阅时刻到自身 `command/done` 的 Session 树通知;该区间可能包含重叠工作的通知。并发调用保留各自结果,所以运行中的模型轮次可以与命令的原生 busy 结果并存。超时或观察回调失败不回滚运行时工作,也不授权自动重试;命令完成不会结束独立的模型活动。 +每次调用在发送前建立订阅,并在结束前释放。`onNotification` 按传输顺序接收本次输入的会话树活动;区间可以包含其他重叠工作。内部完成回执由 SDK 消费。并发调用保留各自结果,因此模型运行期间仍能取得另一条命令的忙碌错误。超时或观察回调失败不回滚运行时工作,也不授权自动重试。 启动选项提供初始值。权限命令只修改目标 Session;后续输入与恢复保留该状态,其他 Session 保留自己的状态,新 Session 使用配置默认值。命令不修改选项对象或已保存的用户默认值。运行中的审批策略变化可以注入通知并触发下一步骤。原生转换与恢复行为见[权限 preset](../../interaction/permission-presets/README.zh.md)。 -`run('/plan')` 进入计划模式;`/plan off` 退出;`/plan ` 进入并 steer 正文。调用返回 `RunCommandResult` 时,模型工作和审阅仍可能继续。需要 `RunResult` 时,先进入,再运行普通文本。组合输入应在 `run()` 前订阅,并通过 `client.request('session/wait', { sessionId })` 等待;保持问答处理器存活直到工作结束。计划状态不修改权限。 +`run('/plan')` 进入计划模式;`/plan off` 退出;`/plan ` 进入并通过 steer 提交正文。`run()` 等待提交的模型活动、原生审阅及获批后的执行,无需调用者另行订阅或等待。通过用户问题处理器回答计划审阅;`exit_plan_mode` 的计划正文位于问题的 `detail`。计划模式不改变权限。通过 `run()` 创建或恢复目标时,会跨越自动轮次等待,直到目标停止及最后回复结束;暂停或清除返回 `aborted`,目标阻塞或失去激活状态报告失败。 ### 用 HarnessClient 做低层控制 `client.executeCommand(sessionId, line)` 接受受支持内置定义的 ASCII 注册名或英文规范别名,不回退为提示词,也不接受附件;permission preset 必须非空,返回原生 `CommandExecution`。中文别名使用 `run()`。非空的未知 preset 会进入原生 handler,返回 `result.kind === "error"`。需要通知时,应在命令调用前订阅。请求超时仅放弃本地等待,运行时工作仍可继续。 -原生目标创建和恢复可在命令调用返回后启动自动轮次。发送前应订阅;先观察终态 `goal/change` 操作,再用 `session/wait` 等待收尾回复。轮次之间的 idle 不代表目标完成。暂停、清除、恢复和权限行为见[服务端语义](../server/README.zh.md)。 +使用 `client.executeCommand()` 时,目标创建和恢复可在调用返回后启动自动轮次。发送前应订阅;先观察终态 `goal/change` 操作,再用 `session/wait` 等待收尾回复。轮次之间的 idle 不代表目标完成。暂停、清除、恢复和权限行为见[服务端语义](../server/README.zh.md)。 `HarnessClient` 是运行 API 之下的协议客户端:显式 `start()`、`initialize()`、`prompt()`、`request()` 与 `close()`,外加通知订阅。`prompt()` 在运行时接受排队消息后立即返回该消息的 id,绝不等待 agent 活动。`subscribe(filter?)` 返回 `NotificationSubscription`(可等待的 `next()`、非阻塞 `tryNext()`、异步迭代);`subscribeSessionTree(id)` 把范围限定到一个会话及从 `subagent.started` 血缘边发现的后代——运行时对上下文内每个会话都发通知,范围限定在客户端完成,与 Python SDK 完全一致。 -拥有完整任务的消费者可以先订阅,再调用 `prompt()`,随后调用 `request('session/wait', { sessionId })`,并通过 `tryNext()` 取完已排队的通知。这会等待受管理后代及其触发的根 Agent 摘要轮次;`HarnessSession.run()` 仍以首次空闲作为活动区间终点。`validatedSessionEvent()` 在事件进入输出折叠前,校验事件封装及 SDK 读取方使用的 assistant/turn 字段。 +拥有完整任务的消费者可以先订阅,再调用 `prompt()`,随后调用 `request('session/wait', { sessionId })`,并通过 `tryNext()` 取完已排队的通知。这会等待受管理后代及其触发的根 Agent 摘要轮次;`HarnessSession.run()` 对普通提示词仍以首次空闲作为活动区间终点。`validatedSessionEvent()` 在事件进入输出折叠前,校验事件封装及 SDK 读取方使用的 assistant/turn 字段。 本客户端为每种失败模式导出类型化错误:`JsonRpcResponseError`(协议错误响应,保留 code 与 data)、`RequestTimeoutError`(配置的时限已到)、`SdkProtocolError`(响应超出文档化协议)、`TransportClosedError`(运行时已消失——消息携带退出码与有界 stderr 尾部)。`close()` 先请求协议 `shutdown`(受 `shutdownTimeoutMs` 约束,默认 1000 毫秒),然后走 stdin-EOF → SIGTERM → SIGKILL 阶梯直到进程退出;幂等,已关闭的客户端拒绝复用。`HarnessClientOptions.env` 给定时整体替换子进程环境(`undefined` 原样继承父进程环境);凭据策略归调用方——`dsh-subprocess` 的 `scrubbedParentEnv` 是面向隔离启动的共享擦除基底。 @@ -118,7 +117,7 @@ else console.log(result.finalResponse) | [`src/api.ts`](src/api.ts) | `DeepSeekHarness` + `HarnessSession`:统一输入路由、自有活动区间与命令结果 | | [`src/client.ts`](src/client.ts) | `HarnessClient`:spawn、握手、请求、订阅扇出、类型化错误 | | [`src/dispose.ts`](src/dispose.ts) | 私有关闭阶梯:stdin EOF → SIGTERM → SIGKILL 直到真正退出 | -| [`src/types.ts`](src/types.ts) | 启动与超时选项、通知、`RunResult` 与 `RunCommandResult` | +| [`src/types.ts`](src/types.ts) | 启动与超时选项、通知、`RunResult` | | [`src/index.ts`](src/index.ts) | 消费方接口:两层客户端与面向调用方的类型 | ### 自有活动流程 diff --git a/packages/sdk/client/src/api.ts b/packages/sdk/client/src/api.ts index a5afc24dac..967027b0e3 100644 --- a/packages/sdk/client/src/api.ts +++ b/packages/sdk/client/src/api.ts @@ -10,7 +10,7 @@ import { resolve } from 'node:path' import type { SessionEvent, TurnEndReason } from '@deepseek-ai/dsh-session' import { createProcessHarnessClient, HarnessClient, isRecord, queryInput, SdkProtocolError } from './client.ts' import type { RuntimeProcessOptions } from './launch.ts' -import type { RunCommandResult, ContentBlock, DeepSeekHarnessOptions, HarnessNotification, RunResult, SdkPromptContentBlock } from './types.ts' +import type { ContentBlock, DeepSeekHarnessOptions, HarnessNotification, RunResult, SdkPromptContentBlock } from './types.ts' /** * Reusable SDK for running DeepSeek Harness agent turns in a runtime @@ -122,9 +122,9 @@ export class DeepSeekHarness implements AsyncDisposable { * Run text or content blocks on a fresh or named Session through native input routing. * @param input - prompt or command text, optionally accompanied by image content blocks. * @param options - optional Session identity, delivery and notification observer. - * @returns ordinary prompt activity or the native command result, both with the receiving Session id. + * @returns the completed input's RunResult, including its Session id. */ - run(input: string | SdkPromptContentBlock[], options?: RunOptions): Promise { + run(input: string | SdkPromptContentBlock[], options?: RunOptions): Promise { return this.session(options?.sessionId).run(input, options) } @@ -169,9 +169,8 @@ export interface RunOptions { /** Ordinary prompt delivery, defaulting to queue; commands retain their native execution timing. */ delivery?: 'queue' | 'steer' /** - * Observe prompt activity from receipt through idle. Command callbacks replay - * Session-tree notifications from subscription through their own command/done - * after the response; either interval can include overlapping work. + * Observe the input's Session-tree activity in wire order until completion. + * The interval can include overlapping work from other inputs. */ onNotification?: (notification: HarnessNotification) => void } @@ -181,19 +180,20 @@ function resolveRunDelivery(requested: RunOptions['delivery']): 'queue' | 'steer return requested ?? 'queue' } -/** Collect an ordinary prompt's notifications from its inbox receipt through idle. */ -class PromptActivity { +/** Collect one input's root events and Session-tree notifications from its admission. */ +class RunActivity { private received = false private readonly events: SessionEvent[] = [] private readonly notifications: HarnessNotification[] = [] - constructor(private readonly sessionId: string, private readonly messageId: string) {} + constructor(private readonly sessionId: string, private readonly receipt: { messageId: string } | { commandId: string }) {} /** Ignore pre-receipt traffic; validate root events before invoking the observer. */ record(notification: HarnessNotification, onNotification?: RunOptions['onNotification']): boolean { + if (notification.method === 'session.query.completed') return false if (!this.received) { if (notification.method !== 'session.event' || notification.params.sessionId !== this.sessionId - || !isInboxReceipt(notification.params.event, this.messageId)) return false + || !this.matchesReceipt(notification.params.event)) return false this.received = true } const event = notification.method === 'session.event' && notification.params.sessionId === this.sessionId @@ -204,9 +204,17 @@ class PromptActivity { return true } - result(): RunResult { + private matchesReceipt(event: unknown): boolean { + return 'messageId' in this.receipt ? isInboxReceipt(event, this.receipt.messageId) + : isRecord(event) && event.type === 'command/run' && isRecord(event.data) + && event.data.commandId === this.receipt.commandId + } + + result(completed?: { finalResponse: string; finishReason: string }): RunResult { + const terminal = this.events.findLast(event => event.type === 'turn/end') return { - sessionId: this.sessionId, finalResponse: finalResponse(this.events), + sessionId: this.sessionId, finalResponse: completed?.finalResponse ?? finalResponse(this.events), + finishReason: completed?.finishReason ?? terminal?.data.reason.kind ?? null, events: this.events, notifications: this.notifications, } } @@ -245,11 +253,12 @@ export class HarnessSession { * Run text or content blocks through native prompt-or-command routing. * @param input - prompt or command text, optionally accompanied by image content blocks; image-only input is an ordinary prompt. * @param options - input delivery and a per-notification observer. - * @returns the prompt's receipt-to-idle activity or a settled command with this Session id; command - * completion does not wait for later model work. Handler errors remain results. + * @returns RunResult after prompt activity, a state-only command, or command-started model work ends. + * Goal creation and resume include automatic rounds through goal termination and the closing reply. + * Native handler refusals return finishReason="error". * @throws on routing, protocol, transport or observer failure; runtime work is not rolled back. */ - async run(input: string | SdkPromptContentBlock[], options?: Omit): Promise { + async run(input: string | SdkPromptContentBlock[], options?: Omit): Promise { const delivery = resolveRunDelivery(options?.delivery) await this.harness.start() const client = this.harness.client @@ -257,16 +266,23 @@ export class HarnessSession { try { const response = await queryInput(client, this.id, input, delivery) if (response.kind === 'command') { - for (let notification = subscription.tryNext(); notification !== undefined; notification = subscription.tryNext()) { - options?.onNotification?.(notification) - const event = notification.params.event - if (notification.method === 'session.event' && notification.params.sessionId === this.id - && isRecord(event) && event.type === 'command/done' && isRecord(event.data) - && event.data.commandId === response.execution.commandId) break + const activity = new RunActivity(this.id, { commandId: response.execution.commandId }) + while (true) { + const notification = await subscription.next() + const params = notification.params + if (notification.method === 'session.query.completed' && params.sessionId === this.id) { + if (typeof params.commandId !== 'string' || params.commandId.length === 0) { + throw new SdkProtocolError('Invalid session.query.completed command identity') + } + if (params.commandId !== response.execution.commandId) continue + if (typeof params.finalResponse !== 'string' || typeof params.finishReason !== 'string' + || params.finishReason.length === 0) throw new SdkProtocolError('Invalid session.query.completed result') + return activity.result({ finalResponse: params.finalResponse, finishReason: params.finishReason }) + } + activity.record(notification, options?.onNotification) } - return { ...response.execution, sessionId: this.id } } - const activity = new PromptActivity(this.id, response.messageId) + const activity = new RunActivity(this.id, { messageId: response.messageId }) while (true) { const notification = await subscription.next() if (!activity.record(notification, options?.onNotification)) continue diff --git a/packages/sdk/client/src/index.ts b/packages/sdk/client/src/index.ts index 91de7583c5..b4b01de4a5 100644 --- a/packages/sdk/client/src/index.ts +++ b/packages/sdk/client/src/index.ts @@ -22,7 +22,6 @@ export { JsonRpcResponseError } from '@deepseek-ai/dsh-sdk-protocol' export type { ContentBlock, CommandExecution, - RunCommandResult, SdkEncodedImageBlock, SdkPromptContentBlock, SdkUserQuestionAnswer, diff --git a/packages/sdk/client/src/types.ts b/packages/sdk/client/src/types.ts index c764b29905..369eb4250c 100644 --- a/packages/sdk/client/src/types.ts +++ b/packages/sdk/client/src/types.ts @@ -70,24 +70,20 @@ export interface DeepSeekHarnessOptions extends HarnessClientOptions { approvalRequests?: boolean } -/** One owned session activity interval, from enqueue receipt through idle. */ +/** Result of one SDK input, including the model activity or native operation it owns. */ export interface RunResult { /** The session the activity ran on. */ sessionId: string - /** Concatenated text of the interval's last assistant message (empty when none). */ + /** Final assistant text (empty when absent), native state-only result text, or a failure diagnostic. */ finalResponse: string + /** Model turn ending or native operation outcome; null when no terminal reason was recorded. */ + finishReason: string | null /** Every `session.event` payload for the root session, in wire order. */ events: SessionEvent[] /** Every notification for the root session and discovered descendants, in wire order. */ notifications: HarnessNotification[] } -/** A high-level run's native command outcome and its receiving Session. */ -export interface RunCommandResult extends CommandExecution { - /** Session to use for subsequent input, observation, or persisted restoration. */ - sessionId: string -} - /** Re-exported content-block alias so SDK callers need no extra import. */ export type { ContentBlock } export type { CommandExecution } diff --git a/packages/sdk/client/tests/cot-translation-projection.spec.ts b/packages/sdk/client/tests/cot-translation-projection.spec.ts index 35931111cf..5c6f97a4fb 100644 --- a/packages/sdk/client/tests/cot-translation-projection.spec.ts +++ b/packages/sdk/client/tests/cot-translation-projection.spec.ts @@ -56,7 +56,6 @@ it('preserves common translation requests and results in SDK events without repl }) try { const result = await harness.run([{ type: 'text', text: 'Keep the original response.' }]) - if ('commandId' in result) throw new Error('expected ordinary prompt activity') const projection = { finalResponse: result.finalResponse, auditEvents: result.events.filter(isTranslationAudit), diff --git a/packages/sdk/client/tests/fake-runtime.ts b/packages/sdk/client/tests/fake-runtime.ts index 7652a01290..08573a2027 100644 --- a/packages/sdk/client/tests/fake-runtime.ts +++ b/packages/sdk/client/tests/fake-runtime.ts @@ -338,6 +338,9 @@ reader.on('line', (line) => { const execution: unknown = env.FAKE_COMMAND_RESULT === undefined ? { commandId: 'command-1', result: { kind: 'success', text: '/compact' } } : JSON.parse(env.FAKE_COMMAND_RESULT) + const completed = execution as { commandId?: string; result?: { kind?: string; text?: string } } + notify('session.query.completed', { sessionId: frame.params?.sessionId, commandId: completed.commandId, + finalResponse: completed.result?.text ?? '', finishReason: completed.result?.kind === 'error' ? 'error' : 'completed' }) respond({ kind: 'command', execution }) return } diff --git a/packages/sdk/client/tests/fixtures/query.ts b/packages/sdk/client/tests/fixtures/query.ts index 576c375aaa..cd6cfdb277 100644 --- a/packages/sdk/client/tests/fixtures/query.ts +++ b/packages/sdk/client/tests/fixtures/query.ts @@ -42,7 +42,17 @@ createInterface({ input: process.stdin }).on('line', (line) => { process.exit(13) } if (process.env.QUERY_RESULT !== undefined) { - respond(JSON.parse(process.env.QUERY_RESULT)) + const response = JSON.parse(process.env.QUERY_RESULT) as { + kind?: string + execution?: { commandId: string; result?: { kind: string; text?: string } } + } | null + if (response?.kind === 'command' && response.execution?.result !== undefined) { + notify('session.query.completed', { sessionId, commandId: response.execution.commandId, + finalResponse: response.execution.result.text ?? '', + finishReason: response.execution.result.kind === 'error' ? 'error' : 'completed', + ...JSON.parse(process.env.QUERY_COMPLETION ?? '{}') as object }) + } + respond(response) return } if (text === process.env.QUERY_ERROR_TEXT) { @@ -58,6 +68,8 @@ createInterface({ input: process.stdin }).on('line', (line) => { const finish = (): void => { commandFinishes.delete(sessionId) event(sessionId, 'command/done', { commandId, ...result }) + notify('session.query.completed', { sessionId, commandId, finalResponse: result.text, + finishReason: result.kind === 'error' ? 'error' : 'completed' }) respond({ kind: 'command', execution: { commandId, result } }) } if (process.env.QUERY_HOLD_COMMAND !== undefined && !promptFinishes.has(sessionId)) { @@ -67,6 +79,22 @@ createInterface({ input: process.stdin }).on('line', (line) => { } return } + if (text === '/plan hold' || text === '/plan disconnect') { + const commandId = `command-${queries.length}` + event(sessionId, 'command/run', { commandId, name: 'plan' }) + event(sessionId, 'agent/inbox/spliced', { inserted: [{ id: `input-${queries.length}` }] }) + event(sessionId, 'command/done', { commandId, kind: 'success', text: 'plan enabled' }) + respond({ kind: 'command', execution: { commandId, result: { kind: 'success', text: 'plan enabled' } } }) + if (text === '/plan disconnect') process.exit(13) + promptFinishes.set(sessionId, () => { + promptFinishes.delete(sessionId) + event(sessionId, 'assistant/message', { message: { content: [{ type: 'text', text: 'the generated plan' }] } }) + event(sessionId, 'turn/end', { reason: { kind: 'completed' } }) + notify('session.status', { sessionId, status: 'idle' }) + notify('session.query.completed', { sessionId, commandId, finalResponse: 'the generated plan', finishReason: 'completed' }) + }) + return + } const messageId = `input-${queries.length}` event(sessionId, 'assistant/message', { message: { content: [{ type: 'text', text: 'before receipt' }] } }) event(sessionId, 'agent/inbox/spliced', { diff --git a/packages/sdk/client/tests/run.spec.ts b/packages/sdk/client/tests/run.spec.ts index 2415f0a3b9..5dcf8f3d3e 100644 --- a/packages/sdk/client/tests/run.spec.ts +++ b/packages/sdk/client/tests/run.spec.ts @@ -5,7 +5,7 @@ import { createProcessDeepSeekHarness } from '../src/api.ts' import * as sdk from '../src/index.ts' import { JsonRpcResponseError, RequestTimeoutError, SdkProtocolError, TransportClosedError } from '../src/index.ts' import type { SdkEncodedImageBlock, SdkPromptContentBlock } from '../src/index.ts' -import type { RunCommandResult, HarnessNotification, RunResult } from '../src/types.ts' +import type { HarnessNotification, RunResult } from '../src/types.ts' function harnessWith(environment: Record = {}, requestTimeoutMs?: number) { const harness = createProcessDeepSeekHarness({ @@ -20,11 +20,6 @@ function harnessWith(environment: Record = {}, requestTimeoutMs? return harness } -function activity(result: RunResult | RunCommandResult): RunResult { - if ('commandId' in result) throw new Error('expected ordinary prompt activity') - return result -} - const images: [SdkEncodedImageBlock, SdkEncodedImageBlock] = [ { type: 'image', data: 'aW1hZ2U=', mimeType: 'image/png', name: 'diagram.png' }, { type: 'image', data: 'c2Vjb25k', mimeType: 'image/jpeg' }, @@ -34,6 +29,8 @@ it('exposes run while keeping its routing request helper internal', () => { expect(sdk.HarnessClient.prototype).not.toHaveProperty('query') expect(sdk).not.toHaveProperty('queryInput') expectTypeOf().not.toHaveProperty('query') + expect(sdk).not.toHaveProperty('RunCommandResult') + expectTypeOf>>().toEqualTypeOf() }) it('returns generated Session identities that can receive subsequent input', async () => { @@ -43,7 +40,7 @@ it('returns generated Session identities that can receive subsequent input', asy expect(first.sessionId).toEqual(expect.any(String)) expect(first.sessionId).not.toBe('') expect(second.sessionId).not.toBe(first.sessionId) - const continued = activity(await harness.run('continue', { sessionId: first.sessionId })) + const continued = await harness.run('continue', { sessionId: first.sessionId }) expect(continued.sessionId).toBe(first.sessionId) expect(continued.finalResponse).toBe('reply:continue') expect(await harness.client.request('test/state')).toHaveProperty('queries', [ @@ -60,16 +57,17 @@ it.each(['session', 'harness'])('runs a native command through the %s entry with const result = entry === 'session' ? await harness.session('main').run('/compact', { onNotification }) : await harness.run('/compact', { sessionId: 'main', onNotification }) - expect(result).toEqual({ sessionId: 'main', commandId: 'command-1', result: { kind: 'success', text: 'compacted', sourceEventSeq: 0 } }) - expect(notifications.map(notification => (notification.params.event as { type: string }).type)) + expect(result).toMatchObject({ sessionId: 'main', finalResponse: 'compacted', finishReason: 'completed' }) + expect(notifications.filter(notification => notification.method === 'session.event') + .map(notification => (notification.params.event as { type: string }).type)) .toEqual(['command/run', 'command/done']) }) it('preserves prompt text and observes its receipt-to-idle activity', async () => { const notifications: HarnessNotification[] = [] - const result = activity(await harnessWith().session('main').run(' first\n', { + const result = await harnessWith().session('main').run(' first\n', { onNotification: (notification) => { notifications.push(notification) }, - })) + }) expect(result.finalResponse).toBe('reply: first\n') expect(result.notifications).toEqual(notifications) expect(result.events.some(event => event.type === 'assistant/message' && event.data.message.content.some(block => @@ -83,7 +81,7 @@ it.each(['session', 'harness'])('forwards native command content blocks through const result = entry === 'session' ? await harness.session('images').run(contentBlocks) : await harness.run(contentBlocks, { sessionId: 'images' }) - expect(result).toEqual({ ...execution, sessionId: 'images' }) + expect(result).toMatchObject({ sessionId: 'images', finalResponse: '', finishReason: 'completed' }) expect(await harness.client.request('test/state')).toHaveProperty('queries', [ { sessionId: 'images', contentBlocks, delivery: 'queue' }, ]) @@ -100,7 +98,7 @@ it.each([ const result = entry === 'session' ? await harness.session('images').run(contentBlocks, { delivery }) : await harness.run(contentBlocks, { sessionId: 'images', delivery }) - expect(activity(result).finalResponse).toBe(`reply:${text ?? ''}`) + expect(result.finalResponse).toBe(`reply:${text ?? ''}`) expect(await harness.client.request('test/state')).toHaveProperty('queries', [ { sessionId: 'images', contentBlocks, delivery }, ]) @@ -112,8 +110,8 @@ it('normalizes text and preserves block order through run', async () => { const contentBlocks: SdkPromptContentBlock[] = [ images[0], { type: 'text', text: 'inspect ' }, images[1], { type: 'text', text: 'both' }, ] - expect(activity(await harness.run(' inspect\n', { sessionId: 'images', delivery: 'steer' })).finalResponse).toBe('reply: inspect\n') - expect(activity(await harness.run(contentBlocks, { sessionId: 'images' })).finalResponse).toBe('reply:inspect \nboth') + expect((await harness.run(' inspect\n', { sessionId: 'images', delivery: 'steer' })).finalResponse).toBe('reply: inspect\n') + expect((await harness.run(contentBlocks, { sessionId: 'images' })).finalResponse).toBe('reply:inspect \nboth') expect(await harness.client.executeCommand('images', ' /plan inspect ')).toEqual({ commandId: 'strict-command-1', result: { kind: 'success' }, }) @@ -128,9 +126,8 @@ it('normalizes text and preserves block order through run', async () => { it('returns native command results for text-only blocks', async () => { const harness = harnessWith() const contentBlocks: SdkPromptContentBlock[] = [{ type: 'text', text: '/compact' }] - expect(await harness.session('blocks').run(contentBlocks)).toEqual({ - sessionId: 'blocks', - commandId: 'command-1', result: { kind: 'success', text: 'compacted', sourceEventSeq: 0 }, + expect(await harness.session('blocks').run(contentBlocks)).toMatchObject({ + sessionId: 'blocks', finalResponse: 'compacted', finishReason: 'completed', }) expect(await harness.client.request('test/state')).toHaveProperty('queries', [ { sessionId: 'blocks', contentBlocks, delivery: 'queue' }, @@ -141,19 +138,19 @@ it('retains a rejected command outcome without retrying its content as a prompt' const execution = { commandId: 'rejected-command', result: { kind: 'error', text: 'command rejected images' } } const harness = harnessWith({ QUERY_RESULT: JSON.stringify({ kind: 'command', execution }) }) expect(await harness.session('images').run([{ type: 'text', text: '/plan off' }, ...images])) - .toEqual({ ...execution, sessionId: 'images' }) + .toMatchObject({ sessionId: 'images', finalResponse: 'command rejected images', finishReason: 'error' }) expect(await harness.client.request('test/state')).toHaveProperty('methods', ['initialize', 'session/query', 'test/state']) }) it('steers ordinary text when delivery requests the next step', async () => { - const result = activity(await harnessWith().session('main').run('next', { delivery: 'steer' })) + const result = await harnessWith().session('main').run('next', { delivery: 'steer' }) expect(result.notifications[0]).toMatchObject({ params: { event: { type: 'agent/inbox/spliced', data: { target: 'next-step' }, } } }) }) it('keeps root result events separate from descendant notifications', async () => { - const result = activity(await harnessWith().session('main').run('with-child')) + const result = await harnessWith().session('main').run('with-child') expect(result.finalResponse).toBe('reply:with-child') expect(result.notifications.some(notification => notification.params.sessionId === 'child')).toBe(true) expect(result.notifications.some(notification => notification.params.sessionId === 'unrelated')).toBe(false) @@ -163,7 +160,7 @@ it('keeps root result events separate from descendant notifications', async () = it('retains independent results for concurrent calls on one Session', async () => { const session = harnessWith().session('main') const results = await Promise.all([session.run('first'), session.run('second')]) - expect(results.map(result => activity(result).finalResponse)).toEqual(['reply:first', 'reply:second']) + expect(results.map(result => result.finalResponse)).toEqual(['reply:first', 'reply:second']) }) it('returns a busy command result while another run waits for model activity', async () => { @@ -174,13 +171,13 @@ it('returns a busy command result while another run waits for model activity', a if (notification.method === 'session.status' && notification.params.status === 'running') entered.resolve(undefined) } }) await entered.promise - expect(await session.run('/compact')).toEqual({ sessionId: 'main', commandId: 'command-2', result: { kind: 'error', text: 'busy' } }) + expect(await session.run('/compact')).toMatchObject({ sessionId: 'main', finalResponse: 'busy', finishReason: 'error' }) await harness.client.request('test/release') - expect(activity(await running).finalResponse).toBe('reply:hold') + expect((await running).finalResponse).toBe('reply:hold') }) it.each(['/model', ' /compact extra '])('preserves unsupported command input as text: %s', async (text) => { - expect(activity(await harnessWith().session('main').run(text)).finalResponse).toBe(`reply:${text}`) + expect((await harnessWith().session('main').run(text)).finalResponse).toBe(`reply:${text}`) }) it('returns a command result without lifecycle notifications', async () => { @@ -189,7 +186,7 @@ it('returns a command result without lifecycle notifications', async () => { const result = await harnessWith({ QUERY_RESULT: JSON.stringify({ kind: 'command', execution }) }).session('main').run('/compact', { onNotification: (notification) => { notifications.push(notification) }, }) - expect(result).toEqual({ ...execution, sessionId: 'main' }) + expect(result).toEqual({ sessionId: 'main', finalResponse: '', finishReason: 'completed', events: [], notifications: [] }) expect(notifications).toEqual([]) }) @@ -205,7 +202,7 @@ it.each(['ordinary', '/compact'])('releases its subscription after an observer r await expect(harness.session('main').run(text, { onNotification() { throw new Error('observer failed') } })) .rejects.toThrow('observer failed') expect(closes[0]).toHaveBeenCalled() - expect(activity(await harness.session('main').run('after')).finalResponse).toBe('reply:after') + expect((await harness.session('main').run('after')).finalResponse).toBe('reply:after') }) it('propagates routing rejection without retrying as a prompt', async () => { @@ -238,8 +235,37 @@ it('reports runtime loss from run', async () => { }) it('steers text content blocks when delivery requests the next step', async () => { - const result = activity(await harnessWith().session('main').run([{ type: 'text', text: 'next' }], { delivery: 'steer' })) + const result = await harnessWith().session('main').run([{ type: 'text', text: 'next' }], { delivery: 'steer' }) expect(result.notifications[0]).toMatchObject({ params: { event: { type: 'agent/inbox/spliced', data: { target: 'next-step' }, } } }) }) + +it('keeps run pending after the plan command until its model output arrives', async () => { + const harness = harnessWith() + const admitted = Promise.withResolvers() + const running = harness.session('plan').run('/plan hold', { onNotification(notice) { + const event = notice.params.event as { type?: string } | undefined + if (event?.type === 'command/done') admitted.resolve(undefined) + } }) + let returned = false + void running.then(() => { returned = true }) + await admitted.promise + expect(returned).toBe(false) + await harness.client.request('test/release') + expect(await running).toMatchObject({ sessionId: 'plan', finalResponse: 'the generated plan', finishReason: 'completed' }) +}) + +it.each([{ commandId: null }, { finalResponse: 1 }, { finishReason: null }, { finishReason: '' }])( + 'rejects malformed command completion: %j', async (completion) => { + const harness = harnessWith({ + QUERY_RESULT: JSON.stringify({ kind: 'command', execution: { commandId: 'c', result: { kind: 'success' } } }), + QUERY_COMPLETION: JSON.stringify(completion), + }) + await expect(harness.session('plan').run('/plan')).rejects.toThrow(SdkProtocolError) + }, +) + +it('reports transport loss after the command has acknowledged its model work', async () => { + await expect(harnessWith().session('plan').run('/plan disconnect')).rejects.toThrow(TransportClosedError) +}) diff --git a/packages/sdk/client/tests/sdk-client.spec.ts b/packages/sdk/client/tests/sdk-client.spec.ts index 9a3ef01e83..4f65881880 100644 --- a/packages/sdk/client/tests/sdk-client.spec.ts +++ b/packages/sdk/client/tests/sdk-client.spec.ts @@ -20,8 +20,6 @@ import { SdkProtocolError, TransportClosedError, type HarnessNotification, - type CommandExecution, - type RunResult, type SdkPromptContentBlock, } from '../src/index.ts' import { createProcessDeepSeekHarness, finalResponse } from '../src/api.ts' @@ -65,11 +63,6 @@ async function tempDir(prefix: string): Promise { return dir } -function promptActivity(result: RunResult | CommandExecution): RunResult { - if ('commandId' in result) throw new Error('expected ordinary prompt activity') - return result -} - describe('DeepSeekHarness', () => { it('queues literal slash text and images through the low-level prompt method', async () => { const harness = harnessWith() @@ -90,7 +83,7 @@ describe('DeepSeekHarness', () => { expect(await harness.client.executeCommand(session.id, ' /compact ')).toEqual({ commandId: 'command-1', result: { kind: 'success', text: ' /compact ' }, }) - expect(await session.run('/compact')).toMatchObject({ commandId: 'command-1', result: { kind: 'success' } }) + expect(await session.run('/compact')).toMatchObject({ finalResponse: '/compact', finishReason: 'completed' }) }) it.each([ @@ -133,7 +126,7 @@ describe('DeepSeekHarness', () => { const harness = harnessWith() const session = await harness.resumeSession('saved-session') expect(session.id).toBe('saved-session') - expect(promptActivity(await session.run([{ type: 'text', text: 'continue' }])).sessionId).toBe('saved-session') + expect((await session.run([{ type: 'text', text: 'continue' }])).sessionId).toBe('saved-session') }) it('propagates resume failures', async () => { @@ -203,7 +196,7 @@ describe('DeepSeekHarness', () => { async * [Symbol.asyncIterator]() {}, })) - const result = promptActivity(await new HarnessSession(harness, 'owned').run([{ type: 'text', text: 'go' }])) + const result = await new HarnessSession(harness, 'owned').run([{ type: 'text', text: 'go' }]) expect(result.notifications.map(notification => notification.method)) .toEqual(['session.event', 'session.status']) @@ -292,7 +285,7 @@ describe('DeepSeekHarness', () => { async * [Symbol.asyncIterator]() {}, })) - const result = promptActivity(await new HarnessSession(harness, 'owned').run([{ type: 'text', text: 'go' }])) + const result = await new HarnessSession(harness, 'owned').run([{ type: 'text', text: 'go' }]) expect(result.events).toEqual([receipt, nativeResult, ptcStart, ptcResult]) expect(result.events.find(event => event.type === 'tool/ptc-dispatch')?.data.meta) @@ -306,7 +299,7 @@ describe('DeepSeekHarness', () => { it('runs a turn end to end and reuses the runtime across sessions', async () => { const harness = harnessWith({ FAKE_TEXT: 'turn answer' }) - const first = promptActivity(await harness.run([{ type: 'text', text: 'say hi' }])) + const first = await harness.run([{ type: 'text', text: 'say hi' }]) expect(first.finalResponse).toBe('turn answer') expect(first.events.map(event => event.type)).toEqual([ 'agent/inbox/spliced', 'turn/start', 'assistant/message', 'turn/end', @@ -324,7 +317,7 @@ describe('DeepSeekHarness', () => { ]) // Same subprocess, second session: ids differ, protocol state is reusable. - const second = promptActivity(await harness.run([{ type: 'text', text: 'again' }])) + const second = await harness.run([{ type: 'text', text: 'again' }]) expect(second.sessionId).not.toBe(first.sessionId) await harness.close() }) @@ -332,10 +325,10 @@ describe('DeepSeekHarness', () => { it('keeps events root-scoped while streaming notifications for the session tree', async () => { const harness = harnessWith({ FAKE_SUBAGENT: '1' }) const seen: HarnessNotification[] = [] - const result = promptActivity(await harness.run([{ type: 'text', text: 'delegate' }], { + const result = await harness.run([{ type: 'text', text: 'delegate' }], { sessionId: 'parent-1', onNotification: (n) => { seen.push(n) }, - })) + }) // The child session's events arrive through subagent.started lineage. expect(seen.map(n => n.method)).toContain('subagent.started') @@ -464,7 +457,7 @@ describe('DeepSeekHarness', () => { // First start: the scripted runtime fails the handshake and is reaped. await expect(harness.start()).rejects.toThrow('scripted first-boot failure') // Retry spawns a NEW subprocess through a fresh client (close is permanent). - const result = promptActivity(await harness.run([{ type: 'text', text: 'again' }])) + const result = await harness.run([{ type: 'text', text: 'again' }]) expect(harness.client).not.toBe(firstClient) expect(result.finalResponse).toBe('second boot answer') await harness.close() @@ -482,7 +475,7 @@ describe('DeepSeekHarness', () => { { await using harness = createProcessDeepSeekHarness(fakeLaunch()) captured = harness - const result = promptActivity(await harness.run([{ type: 'text', text: 'scoped' }])) + const result = await harness.run([{ type: 'text', text: 'scoped' }]) expect(result.finalResponse).toBe('hello from fake runtime') } // After scope exit the runtime is closed: reuse fails loudly. @@ -788,7 +781,7 @@ describe('wire payload validation', () => { it('accepts the complete hook cancellation cause', async () => { const harness = harnessWith({ FAKE_REASON_KIND: 'aborted', FAKE_ABORT_REASON_KIND: 'hook' }) - const result = promptActivity(await harness.run([{ type: 'text', text: 'hook-abort' }])) + const result = await harness.run([{ type: 'text', text: 'hook-abort' }]) const end = result.events.findLast(event => event.type === 'turn/end') expect(end?.data.reason).toEqual({ kind: 'aborted', reason: { kind: 'hook', reason: 'scripted hook abort' } }) }) @@ -851,7 +844,7 @@ describe('server-to-client SDK requests', () => { describe('SDK cancellation reason projection', () => { it.each(['user', 'parent', 'disposed', 'legacy'])('retains the %s cancellation cause', async (kind) => { const harness = harnessWith({ FAKE_REASON_KIND: 'aborted', FAKE_ABORT_REASON_KIND: kind }) - const result = promptActivity(await harness.run([{ type: 'text', text: 'cancelled' }])) + const result = await harness.run([{ type: 'text', text: 'cancelled' }]) expect(result.events.findLast(event => event.type === 'turn/end')?.data.reason) .toEqual({ kind: 'aborted', reason: { kind } }) }) diff --git a/packages/sdk/protocol/README.i18n.yaml b/packages/sdk/protocol/README.i18n.yaml index 9e1102faf9..062e29ad86 100644 --- a/packages/sdk/protocol/README.i18n.yaml +++ b/packages/sdk/protocol/README.i18n.yaml @@ -21,8 +21,8 @@ en: be53c71505c0d1b4 zh: 6210dee577715539 /deepseek-ai-dsh-sdk-protocol/use-this-package/the-sdk-methods: - en: e0b3af7691d4f714 - zh: ecad2771befa34d6 + en: 01c229bdd9227930 + zh: 3d85b3bbea123899 /deepseek-ai-dsh-sdk-protocol/use-this-package/native-user-questions: en: 65ea66231b17b6cf zh: 8e1c57d0c27f842f diff --git a/packages/sdk/protocol/README.md b/packages/sdk/protocol/README.md index 4dc3bd96a6..c75477c7ba 100644 --- a/packages/sdk/protocol/README.md +++ b/packages/sdk/protocol/README.md @@ -53,6 +53,7 @@ Both wire ends share one method set: client-to-server requests, opt-in server-to | server→client | `user-question.cancelled` | `SdkUserQuestionCancelled` | | server→client | `session.event` | `SessionEventNotification` (every session in the runtime, unfiltered) | | server→client | `session.status` | `SessionStatusNotification` (whole-agent `running`/`idle` transition) | +| server→client | `session.query.completed` | `{ sessionId, commandId, finalResponse, finishReason }` | | server→client | `subagent.started` | `SubagentStartedNotification` | | server→client | `subagent.finished` | `SubagentFinishedNotification` (in-process runs only) | @@ -64,7 +65,7 @@ Both wire ends share one method set: client-to-server requests, opt-in server-to `session/command` accepts `{ sessionId, line }` after initialization and delegates the [supported builtin definitions through their ASCII registered names or canonical English aliases](../server/README.md#command-input) to the native registry. Chinese aliases use `session/query`. A non-blank preset is required; bare `/permission` is rejected. It returns `CommandExecution` after the handler settles, including an unknown preset or other business failure as `result.kind: "error"`. Unavailable or unsupported commands and malformed requests reject with a JSON-RPC error. There is no prompt fallback or attachment input; use `session/query` to submit commands with encoded images. No inbox receipt or ordinary turn is required. `session/prompt` queues content blocks without native slash-command routing; runtime skill recognition still applies. -Command lifecycle notifications precede their response on the same stream for both `session/command` and the command result of `session/query`. Forwarders must preserve this order. +Command lifecycle notifications precede the native handler response for both `session/command` and `session/query`. A command query additionally ends high-level observation with `session.query.completed` for the same `commandId`, after model activity it starts; goal creation and resume include goal termination and closing activity. State-only commands need no model turn, and their completion notification can precede the response. SDKs consume this receipt internally and return `RunResult`; forwarders must preserve order. Shutdown cancels unfinished observation. `session/resume` accepts a non-empty persisted `{ sessionId }` and returns `{}` after restoring that exact session. It requires initialization and the original persistence store, sends no new input, and rejects missing, unreadable, incompatible, or occupied sessions without creating a replacement. Historical events remain in the stored log; notifications report newly committed events. diff --git a/packages/sdk/protocol/README.zh.md b/packages/sdk/protocol/README.zh.md index 8e438225a1..e1014dc9e3 100644 --- a/packages/sdk/protocol/README.zh.md +++ b/packages/sdk/protocol/README.zh.md @@ -53,6 +53,7 @@ kind: "package-library" | server→client | `user-question.cancelled` | `SdkUserQuestionCancelled` | | server→client | `session.event` | `SessionEventNotification`(运行时内每个会话,不过滤) | | server→client | `session.status` | `SessionStatusNotification`(整个 agent(智能体)的 `running`/`idle` 转换) | +| server→client | `session.query.completed` | `{ sessionId, commandId, finalResponse, finishReason }` | | server→client | `subagent.started` | `SubagentStartedNotification` | | server→client | `subagent.finished` | `SubagentFinishedNotification`(仅进程内运行) | @@ -64,7 +65,7 @@ kind: "package-library" `session/command` 在初始化后接受 `{ sessionId, line }`,将[支持内置定义的 ASCII 注册名或英文规范别名](../server/README.zh.md#command-input)委托给原生注册器。中文别名使用 `session/query`。preset 必须非空,裸 `/permission` 会被拒绝。Handler 结束后返回 `CommandExecution`,未知 preset 或其他业务失败以 `result.kind: "error"` 返回。命令不可用、不受支持或请求格式错误时返回 JSON-RPC 错误。不回退为普通 prompt,也不接受附件;携带编码图片的命令使用 `session/query`。不要求 inbox 回执或普通 turn。`session/prompt` 将内容块排入队列,不经过原生 slash command 路由;运行时 skill(技能)识别仍然适用。 -对于 `session/command` 和 `session/query` 的命令结果,命令生命周期通知都在同一流上先于对应响应到达。转发方必须保留这一顺序。 +`session/command` 和 `session/query` 的命令生命周期通知先于原生 handler 响应到达。命令查询另以同一 `commandId` 的 `session.query.completed` 通知结束高层观察,等待命令启动的模型活动;目标创建和恢复还等待目标终止及收尾活动。状态命令无需模型 turn,其完成通知可以先于响应到达。SDK 内部消费该回执并返回 `RunResult`,转发器必须保持顺序。关闭会取消尚未结束的观察。 `session/resume` 接受非空的持久化 `{ sessionId }`,恢复该会话后返回 `{}`。它要求先完成初始化并使用原持久化存储,不发送新输入;会话缺失、不可读、不兼容或被占用时,请求失败且不创建替代会话。历史事件保留在存储日志中,通知只报告新提交的事件。 diff --git a/packages/sdk/protocol/src/types.ts b/packages/sdk/protocol/src/types.ts index 7f9ba131a4..221f4884fe 100644 --- a/packages/sdk/protocol/src/types.ts +++ b/packages/sdk/protocol/src/types.ts @@ -116,6 +116,7 @@ export interface SessionQueryParams { /** * A prompt's enqueue receipt or a settled native command; neither means all Session work ended. * Command lifecycle notifications precede the command response on the same stream. + * High-level command activity ends with its correlated session.query.completed notification. */ export type SessionQueryResult = | ({ kind: 'prompt' } & SessionPromptResult) @@ -204,6 +205,13 @@ export interface HarnessSdkNotificationMap { 'user-question.cancelled': SdkUserQuestionCancelled 'session.event': SessionEventNotification 'session.status': SessionStatusNotification + /** Completion of a command query, including model activity and automatic goal rounds it starts. */ + 'session.query.completed': { + sessionId: SessionId + commandId: CommandExecution['commandId'] + finalResponse: string + finishReason: string + } 'subagent.started': SubagentStartedNotification 'subagent.finished': SubagentFinishedNotification } diff --git a/packages/sdk/server/README.i18n.yaml b/packages/sdk/server/README.i18n.yaml index 947d3572c1..882b90262a 100644 --- a/packages/sdk/server/README.i18n.yaml +++ b/packages/sdk/server/README.i18n.yaml @@ -15,8 +15,8 @@ en: d152484eb41ac6b4 zh: 09388d293f9be9cb /deepseek-ai-dsh-sdk-jsonrpc-server/use-this-package: - en: 43fc5d41059a31b2 - zh: 494ecf14a627703f + en: 737e5f55044d878f + zh: 5f2996ba3a549fe4 /deepseek-ai-dsh-sdk-jsonrpc-server/use-this-package/wiring: en: 47a33e9397e36e15 zh: e6d173820f9ea6e5 diff --git a/packages/sdk/server/README.md b/packages/sdk/server/README.md index 28194177d5..613f2472f2 100644 --- a/packages/sdk/server/README.md +++ b/packages/sdk/server/README.md @@ -47,9 +47,9 @@ The first text block supplies the complete command line; encoded images may prec Permission commands change only the receiving Session. Later queries and restored Sessions retain its persisted permission facts; other Sessions keep their own state and new Sessions use the configured defaults. Neither the caller's launch configuration nor saved user defaults are rewritten. Model selection is not an SDK slash command; its resume override remains the separate behavior described above. -Without attachments, `/plan` and `/plan off` change only native plan state. `/plan` with images or a body submits them through native steer, with images before the trimmed body; `/plan off` with images returns a command error without changing plan state. Attachment acceptance follows the same native registry and handler checks as Desktop; command completion does not wait for that model activity or the review. `session/wait` observes subsequent Session work. User-question answers preserve approval and feedback; `{ cancelled: true }` becomes native `ASK_CANCELLED`, allowing plan review to end the turn without leaving plan mode. +Without attachments, `/plan` and `/plan off` change only native plan state. `/plan` with images or a body submits through native steer, with images before the trimmed body; `/plan off` with images returns an error without changing state. High-level `run()` waits for submitted model activity, review and approved continuation, including input queued behind an earlier cancellation. The native response acknowledges handler settlement; the matching `session.query.completed` notification ends high-level activity. User-question answers preserve approval and feedback; `{ cancelled: true }` becomes native `ASK_CANCELLED`, ending the turn without leaving plan mode. -`/goal` delegates its full grammar to the [native goal command](../../goal/command-goal/README.md). Creation and resume arm automatic goal rounds; pause aborts a running turn, while clear stops continuation without aborting the current request. Command completion is separate from goal completion. `session/wait` can return between goal rounds: observe a terminal `goal/change` operation first, then wait for any closing model reply. Restoration retains goal state but leaves activation disarmed until `/goal resume`. Goal commands do not change permissions or SDK initialization settings. +`/goal` delegates grammar to the [native goal command](../../goal/command-goal/README.md). High-level `run()` waits across automatic rounds after creation or resume, until goal termination and closing activity, including reference input queued during compaction. Completion returns `completed`, pause or clear returns `aborted`, and blocking or nonterminal loss of activation reports failure. The first durable goal termination is retained while closing activity finishes; later clear or resume operations do not replace it. The completion notification carries the final assistant text, or an empty string when none is emitted; goal status remains in the finish reason and events. State-only controls return native handler text without waiting for unrelated activity. Low-level `session/wait` can still return between rounds. Restoration preserves goal state and waits for `/goal resume` to re-arm execution. Goal commands do not change permissions or SDK launch settings. Creation and edit accept images as reference material before the next round; show, pause, resume, and clear reject attachments without changing goal state. Compact and permission commands also reject attachments. Handler refusals never fall back to ordinary prompts; an image may already be stored before the handler refuses, as on Desktop. These SDK inputs accept raster images, not general file uploads or client-supplied attachment references. diff --git a/packages/sdk/server/README.zh.md b/packages/sdk/server/README.zh.md index 66cecaab21..c6c3c357be 100644 --- a/packages/sdk/server/README.zh.md +++ b/packages/sdk/server/README.zh.md @@ -47,9 +47,9 @@ Host 与桌面适配器共用 `dsh-commands/builtin` 的定义身份及中英文 权限命令只修改接收命令的 Session。后续输入和恢复的 Session 保留其持久化权限事实;其他 Session 保留各自状态,新 Session 使用配置的默认值。调用方的启动配置和已保存的用户默认值均不会被重写。模型选择不是 SDK slash 命令;恢复时的模型覆盖仍按上文描述的独立行为执行。 -不带附件时,`/plan` 和 `/plan off` 只改变原生计划状态。`/plan` 带图片或正文时,通过原生 steer 提交,图片位于去除首尾空白的正文前;`/plan off` 带图片时返回命令错误,不修改计划状态。附件接受规则复用 Desktop 的原生注册器与处理器校验;命令完成不等待后续模型活动或审查,`session/wait` 可观察后续 Session 工作。问答响应保留批准和反馈语义;`{ cancelled: true }` 转为原生 `ASK_CANCELLED`,使关闭计划审查结束轮次而不退出计划模式。 +不带附件时,`/plan` 和 `/plan off` 只改变原生计划状态。带图片或正文的 `/plan` 通过原生 steer 提交,图片位于去除首尾空白的正文前;`/plan off` 带图片时返回错误且不改变状态。高层 `run()` 等待提交的模型活动、审阅及获批后的后续执行,也包括等待先前取消收尾后才开始执行的输入。原生命令响应确认 handler 完成;对应的 `session.query.completed` 通知确认高层活动结束。问答响应保留批准和反馈语义;`{ cancelled: true }` 转为原生 `ASK_CANCELLED`,使关闭审阅结束 turn 而不退出计划模式。 -`/goal` 将完整语法委托给[原生目标命令](../../goal/command-goal/README.zh.md)。创建和恢复会启用自动目标轮次;暂停中止运行中的轮次,清除则停止续跑而不中止当前请求。命令完成与目标完成相互独立。`session/wait` 可能在目标轮次之间返回:应先观察终态 `goal/change` 操作,再等待可能的模型收尾回复。恢复会话保留目标状态,但 activation 保持 disarmed,直到执行 `/goal resume`。目标命令不改变权限或 SDK 初始化设置。 +`/goal` 将语法委托给[原生目标命令](../../goal/command-goal/README.zh.md)。高层 `run()` 创建或恢复目标时跨越自动轮次等待,直到目标终止及收尾活动结束,也包括压缩期间排队的参考输入。完成返回 `completed`,暂停或清除返回 `aborted`,阻塞或非终态失去激活状态报告失败。等待收尾活动结束时保留首次持久化的目标终止状态,后续 clear 或 resume 操作不会替换它。完成通知携带最终助手文本,未输出助手文本时为空字符串;目标状态由结束原因和事件表达。仅改变状态的控制命令返回原生 handler 文本,不等待无关活动。底层 `session/wait` 仍可在轮次之间返回。恢复会话保留目标状态,直到 `/goal resume` 才重新激活。目标命令不改变权限或 SDK 启动设置。 创建和编辑接受图片,作为下一轮前的参考材料;查看、暂停、恢复和清除拒绝附件,不修改目标状态。压缩和权限命令也拒绝附件。处理器拒绝后绝不回退为普通提示词;与 Desktop 相同,图片可能在处理器拒绝前已被存储。这些 SDK 输入接受栅格图片,不接受一般文件上传或客户端提供的附件引用。 diff --git a/packages/sdk/server/package.json b/packages/sdk/server/package.json index abb6c300ba..dc745bf7a1 100644 --- a/packages/sdk/server/package.json +++ b/packages/sdk/server/package.json @@ -37,6 +37,7 @@ "@deepseek-ai/dsh-agent": "workspace:*", "@deepseek-ai/dsh-attachment": "workspace:*", "@deepseek-ai/dsh-commands": "workspace:*", + "@deepseek-ai/dsh-goal": "workspace:*", "@deepseek-ai/dsh-llm": "workspace:*", "@deepseek-ai/dsh-llm-deepseek-api-key": "workspace:*", "@deepseek-ai/dsh-schedule": "workspace:*", diff --git a/packages/sdk/server/src/query-activity.ts b/packages/sdk/server/src/query-activity.ts new file mode 100644 index 0000000000..17a4fc9148 --- /dev/null +++ b/packages/sdk/server/src/query-activity.ts @@ -0,0 +1,161 @@ +/** Observe command-admitted activity through quiescence and preserve a goal's first terminal outcome. */ + +import type { Context } from '@deepseek-ai/cordis' +import type { Agent } from '@deepseek-ai/dsh-agent' +import type { GoalView } from '@deepseek-ai/dsh-goal' +import type { CommandExecution, JsonRpcTransportPeer } from '@deepseek-ai/dsh-sdk-protocol' + +/** One command's SDK completion observer; its listeners end at completion, rejection, or shutdown. */ +export class QueryActivity { + private readonly disposers: (() => void)[] = [] + private commandId: CommandExecution['commandId'] | undefined + private result: CommandExecution['result'] | undefined + private closed = false + private input = false + private inputIdle = false + private goalId: GoalView['id'] | undefined + private goalOutcome: 'completed' | 'aborted' | 'error' | undefined + private goalStopped = false + private response: string | undefined + private turnReason = 'completed' + + /** + * Subscribe before the native command starts so fast input and completion cannot be lost. + * @param ctx - server-owned context; goal services remain optional for other commands. + * @param agent - exact receiving Agent. + * @param transport - SDK notification stream. + * @param ownsInvocation - whether the current async operation is this native invocation. + * @param signal - server lifetime; abort releases observation without cancelling unrelated work. + * @param onClose - remove this closed observer from its owner's registry. + */ + constructor( + ctx: Context, + private readonly agent: Agent, + private readonly transport: JsonRpcTransportPeer, + ownsInvocation: () => boolean, + signal: AbortSignal, + private readonly onClose: (activity: QueryActivity) => void, + ) { + this.disposers.push(ctx.on('session/event', (session, event) => { + if (session !== agent.session) return + const own = this.result === undefined && ownsInvocation() + // Nested native commands retain the outer invocation's completion identity. + if (own && event.type === 'command/run') this.commandId ??= event.data.commandId + if (own && event.type === 'agent/inbox/spliced' + && event.data.inserted.some(message => message.source.kind === 'user')) { + this.input = true + } + if (event.type === 'goal/change') { + const change = event.data + if (own && (change.operation === 'create' || change.operation === 'resume')) { + this.goalId = change.goal.id + } + if (change.operation === 'clear') { + if (change.cleared.id === this.goalId) this.goalOutcome ??= 'aborted' + } else if (change.goal.id === this.goalId && change.goal.phase !== 'active') { + const goal = change.goal + this.goalOutcome ??= goal.phase === 'complete' + ? 'completed' + : goal.phase === 'paused' + ? 'aborted' + : 'error' + } + } + if (this.input || this.goalId !== undefined) { + if (event.type === 'assistant/message') { + this.response = event.data.message.content.flatMap(block => block.type === 'text' ? [block.text] : []).join('') + } + if (event.type === 'turn/end') this.turnReason = event.data.reason.kind + } + this.check() + })) + this.disposers.push(ctx.on('goal/activation-changed', (change) => { + if (change.sessionId !== agent.session.id || change.goal?.id !== this.goalId + || change.goal?.activation !== 'disarmed') return + // Terminal mutations also change activation before their durable event is forwarded. + // Only a still-active goal needs a separate failure report here. + if (ctx.get('goals')?.get(agent)?.phase === 'active') { + this.goalStopped = true + this.check() + } + })) + this.disposers.push(ctx.on('agent/status', ({ agent: current }) => { + if (current !== agent) return + this.check() + })) + this.disposers.push(ctx.on('agent/error', ({ agent: current }) => { + if (current === agent && (this.input || this.goalId !== undefined)) this.turnReason = 'error' + })) + this.disposers.push(ctx.on('agent/disposed', ({ agent: current }) => { + if (current === agent) this.finish('error', 'The Session Agent was disposed before the input finished.') + })) + const abort = (): void => { this.close() } + signal.addEventListener('abort', abort, { once: true }) + this.disposers.push(() => { signal.removeEventListener('abort', abort) }) + } + + /** + * Retain native settlement; admitted input waits through replacement work before completing. + * @param execution - the already-logged native result. + */ + accept(execution: CommandExecution): void { + this.commandId = execution.commandId + this.result = execution.result + if (this.input) { + // A cancelled driver can publish idle before starting the command's queued input. + void this.agent.whenIdle().then(() => { + if (this.closed) return + this.inputIdle = true + this.check() + }) + } + this.check() + } + + /** Report withdrawal of the optional provider needed by an active goal query. */ + goalUnavailable(): void { + if (this.goalId !== undefined) this.finish('error', 'The goal service was unloaded before the goal finished.') + } + + /** Release all listeners when the request fails or the server shuts down. */ + close(): void { + if (this.closed) return + this.closed = true + for (const dispose of this.disposers.splice(0)) dispose() + this.onClose(this) + } + + private check(): void { + if (this.closed || this.result === undefined) return + const result = this.result + if (result.kind === 'error') { + this.finish('error', result.text) + return + } + if (this.input && !this.inputIdle) return + if (this.goalId !== undefined) { + const outcome = this.goalOutcome ?? (this.goalStopped ? 'error' : undefined) + if (outcome === undefined || this.agent.status !== 'idle') return + const reason = outcome === 'completed' ? this.turnReason : outcome + const failure = this.goalOutcome === undefined ? 'Goal execution stopped before reaching a terminal state.' : '' + this.finish(reason, this.response || failure) + return + } + if (this.input) { + this.finish(this.turnReason, this.response ?? '') + return + } + this.finish('completed', result.text ?? '') + } + + private finish(finishReason: string, finalResponse: string): void { + if (this.closed) return + try { + if (this.commandId !== undefined) this.transport.notify('session.query.completed', { + sessionId: this.agent.session.id, commandId: this.commandId, finishReason, finalResponse, + }) + } finally { + this.close() + } + } +} diff --git a/packages/sdk/server/src/server.ts b/packages/sdk/server/src/server.ts index ecc8c6645d..2d908ff644 100644 --- a/packages/sdk/server/src/server.ts +++ b/packages/sdk/server/src/server.ts @@ -6,7 +6,9 @@ */ import type { Context } from '@deepseek-ai/cordis' +import { AsyncLocalStorage } from 'node:async_hooks' import { resolve } from 'node:path' +import { QueryActivity } from './query-activity.ts' import { SdkUserQuestionBridge } from './user-questions.ts' import { queryCommand } from './query-input.ts' import { queryCommandImages, queryContent } from './query-content.ts' @@ -104,6 +106,9 @@ export class HarnessSdkJsonRpcServer { private readonly sessions = new Map() private readonly sessionCreations = new Map>() private readonly commandTasks = new Set>() + private readonly queryInvocation = new AsyncLocalStorage() + private readonly queryActivities = new Set() + private readonly goalLifetime: { dispose(): Promise } private readonly disposers: (() => void)[] = [] private shutdownTask: Promise> | undefined private shuttingDown = false @@ -120,6 +125,11 @@ export class HarnessSdkJsonRpcServer { private readonly transport: JsonRpcTransportPeer, private readonly options: HarnessSdkJsonRpcServerOptions = {}, ) { + this.goalLifetime = ctx.inject(['goals'], (goalCtx) => { + goalCtx.effect(() => () => { + for (const activity of this.queryActivities) activity.goalUnavailable() + }) + }) this.disposers.push(ctx.on('approval/request', async (request, next) => { if (!this.approvalRequests || !this.ownsAgent(request.agent)) return next() const params: ApprovalRequestParams = { @@ -289,7 +299,7 @@ export class HarnessSdkJsonRpcServer { /** * Dispatch text as a Desktop-style input; native commands own Session state changes. * @param params - ordered content blocks, receiving Session and ordinary-prompt delivery. - * @returns an enqueue receipt for text or the supported native command's result. + * @returns a prompt receipt or native command acknowledgment; command activity completes by notification. * @throws on runtime failure; a recognized command failure never falls back to a prompt. */ async query(params: SessionQueryParams): Promise { @@ -305,7 +315,19 @@ export class HarnessSdkJsonRpcServer { const line = queryCommand(text.text, commands.list(rec.handle.agent)) if (line !== undefined) { const images = queryCommandImages(params.contentBlocks, text) - return { kind: 'command', execution: await this.runCommand({ sessionId: params.sessionId, line }, images) } + const activity: QueryActivity = new QueryActivity(this.ctx, rec.handle.agent, this.transport, + () => this.queryInvocation.getStore() === activity, this.lifetime.signal, + (current) => { this.queryActivities.delete(current) }) + this.queryActivities.add(activity) + try { + const execution = await this.queryInvocation.run(activity, + () => this.runCommand({ sessionId: params.sessionId, line }, images)) + activity.accept(execution) + return { kind: 'command', execution } + } catch (error) { + activity.close() + throw error + } } } } @@ -482,6 +504,7 @@ export class HarnessSdkJsonRpcServer { const pendingCreations = [...this.sessionCreations.values()] await Promise.allSettled(pendingCreations) await Promise.allSettled([...this.commandTasks]) + this.queryInvocation.disable() this.sessionCreations.clear() this.scheduledSessions.clear() const records = [...this.sessions.values()] @@ -500,6 +523,7 @@ export class HarnessSdkJsonRpcServer { failures.push(error) } const teardownResults = await Promise.allSettled([ + this.goalLifetime.dispose(), ...records.map(rec => Promise.resolve().then(() => rec.handle.dispose())), ...(this.llmFiber === undefined ? [] : [Promise.resolve().then(() => this.llmFiber?.dispose())]), ]) diff --git a/packages/sdk/server/tests/commands.spec.ts b/packages/sdk/server/tests/commands.spec.ts index a5c82bb963..054f55c58e 100644 --- a/packages/sdk/server/tests/commands.spec.ts +++ b/packages/sdk/server/tests/commands.spec.ts @@ -262,7 +262,7 @@ describe('SDK command dispatch', () => { expect(handler).toHaveBeenCalledTimes(2) const commandId = handler.mock.calls[1]![0].commandId expect(result).toMatchObject({ kind: 'command', execution: { commandId, result: { kind: 'success', text: 'native outcome' } } }) - expect(receivedAtQueryResolution).toMatchObject([ + expect(receivedAtQueryResolution.filter(item => item.method === 'session.event')).toMatchObject([ { method: 'session.event', params: { sessionId, event: { type: 'command/run', data: { commandId, name } } } }, { method: 'session.event', params: { sessionId, event: { type: 'command/done', data: { commandId, kind: 'success' } } } }, ]) diff --git a/packages/sdk/server/tests/query-activity.spec.ts b/packages/sdk/server/tests/query-activity.spec.ts new file mode 100644 index 0000000000..2c5bf3f75f --- /dev/null +++ b/packages/sdk/server/tests/query-activity.spec.ts @@ -0,0 +1,462 @@ +/** Command input completion includes its admitted model activity without changing native handler results. */ +import { Context } from '@deepseek-ai/cordis' +import AgentLoop from '@deepseek-ai/dsh-agent-loop' +import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit' +import { AttachmentId, type AttachmentStore } from '@deepseek-ai/dsh-attachment' +import CommandRuntime, { CommandDefinitionId, type CommandDefinition } from '@deepseek-ai/dsh-commands' +import GoalService from '@deepseek-ai/dsh-goal' +import * as GoalDriver from '@deepseek-ai/dsh-goal-round-driver' +import * as GoalCommand from '@deepseek-ai/dsh-command-goal' +import PlanMode from '@deepseek-ai/dsh-plan-mode' +import { createUserMessage, type GenerateOptions, type StreamChunk } from '@deepseek-ai/dsh-llm' +import { SessionId } from '@deepseek-ai/dsh-session' +import { describe, expect, it, onTestFinished, vi } from 'vitest' +import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts' +import { HarnessSdkJsonRpcServer } from '../src/server.ts' + +class GatedModel extends MockAdapter { + readonly entered = Promise.withResolvers() + readonly release = Promise.withResolvers() + private gated = false + + override async *stream(options: GenerateOptions): AsyncIterable { + if (!this.gated) { + this.gated = true + const cancelled = Promise.withResolvers() + const abort = (): void => { cancelled.resolve(undefined) } + options.signal?.addEventListener('abort', abort, { once: true }) + try { + this.entered.resolve(undefined) + if (!options.signal?.aborted) await Promise.race([this.release.promise, cancelled.promise]) + } finally { + options.signal?.removeEventListener('abort', abort) + } + } + yield* super.stream(options) + } +} + +async function setup(model = new MockAdapter([]), goal = false) { + const ctx = new Context() + await mountAgentLoopTestDependencies(ctx, { workingDirectory: true }) + const loop = await ctx.plugin(AgentLoop, { agents: [] }) + await ctx.plugin(CommandRuntime) + let goals: { dispose(): Promise } | undefined + if (goal) { + goals = await ctx.plugin(GoalService, { defaultMaxGoalRounds: 2 }) + await ctx.plugin(GoalCommand) + await ctx.plugin(GoalDriver) + } + ctx.effect(() => ctx.llm.registerAdapter(['query-activity'], model)) + const notices: { method: string; params: object }[] = [] + const completed = Promise.withResolvers() + const server = new HarnessSdkJsonRpcServer(ctx, { + request: async () => { throw new Error('Unexpected host request') }, + notify: (method, params) => { + if (params === undefined) throw new Error('SDK activity notifications require parameters') + notices.push({ method, params }) + if (method === 'session.query.completed') completed.resolve(params) + }, + }) + onTestFinished(async () => { try { await server.shutdown() } finally { await ctx.fiber.dispose() } }) + await server.initialize({ cwd: process.cwd(), provider: 'query-activity', model: 'model' }) + const sessionId = SessionId('query-activity') + const run = (text: string) => server.query({ sessionId, contentBlocks: [{ type: 'text', text }], delivery: 'queue' }) + const register = (handler: CommandDefinition['handler']) => ctx.commands.register({ + name: 'plan', definitionId: CommandDefinitionId('@deepseek-ai/dsh-plan-mode'), description: 'Plan', handler, + }) + return { ctx, server, loop, goals, notices, completed: completed.promise, run, register, sessionId, model } +} + +describe('SDK query activity completion', () => { + it.each(['success', 'error'] as const)('returns a state-only %s without a turn or idle', async (kind) => { + const h = await setup() + h.register(() => ({ kind, text: 'native result' })) + const response = await h.run('/plan') + expect(response).toMatchObject({ kind: 'command', execution: { result: { kind, text: 'native result' } } }) + expect(await h.completed).toMatchObject({ finalResponse: 'native result', finishReason: kind === 'success' ? 'completed' : 'error' }) + expect(h.model.requests).toHaveLength(0) + }) + + it('waits for command-admitted input and returns its final model reply', async () => { + const h = await setup(new MockAdapter([textResponse('the plan')])) + h.register(({ agent }) => { + agent.steer(createUserMessage({ content: [{ type: 'text', text: 'plan the task' }], source: { kind: 'user' } })) + return { kind: 'success', text: 'mode enabled' } + }) + await h.run('/plan task') + expect(await h.completed).toMatchObject({ finalResponse: 'the plan', finishReason: 'completed' }) + expect(h.notices.at(-1)?.method).toBe('session.query.completed') + expect(h.notices.at(-2)).toMatchObject({ method: 'session.status', params: { status: 'idle' } }) + }) + + it('waits for plan input submitted while a paused goal is still cancelling', async () => { + class CancellingModel extends GatedModel { + readonly firstEntered = Promise.withResolvers() + readonly releaseCancellation = Promise.withResolvers() + private first = true + + override async *stream(options: GenerateOptions): AsyncIterable { + if (this.first) { + this.first = false + this.firstEntered.resolve(undefined) + await this.releaseCancellation.promise + throw new Error('cancelled goal request') + } + yield* super.stream(options) + } + } + const model = new CancellingModel([[ + { type: 'block-start', index: 0, blockType: 'reasoning' }, + { type: 'reasoning-delta', index: 0, text: 'plan reasoning' }, + { type: 'block-end', index: 0, block: { type: 'reasoning', text: 'plan reasoning' } }, + ...textResponse('new plan reply').map(chunk => 'index' in chunk ? { ...chunk, index: chunk.index + 1 } : chunk), + ]]) + const h = await setup(model, true) + await h.ctx.plugin(PlanMode, { section: 'Plan the task.' }) + try { + await h.run('/goal work') + await model.firstEntered.promise + await h.run('/goal pause') + const response = await h.run('/plan new task') + if (response.kind !== 'command') throw new Error('Expected plan command acknowledgment') + const commandId = response.execution.commandId + const completions = () => h.notices.filter(item => item.method === 'session.query.completed' + && 'commandId' in item.params && item.params.commandId === commandId) + model.releaseCancellation.resolve(undefined) + await model.entered.promise + expect(completions()).toEqual([]) + model.release.resolve(undefined) + await h.server.wait({ sessionId: h.sessionId }) + expect(completions()).toMatchObject([{ params: { finalResponse: 'new plan reply', finishReason: 'completed' } }]) + } finally { + model.releaseCancellation.resolve(undefined) + model.release.resolve(undefined) + } + }) + + it('keeps another command\'s model input out of a suspended state-only invocation', async () => { + const h = await setup(new MockAdapter(['hang'])) + const entered = Promise.withResolvers() + const release = Promise.withResolvers() + onTestFinished(() => { release.resolve(undefined) }) + h.register(async ({ agent, rawInput }) => { + if (rawInput.trim() === 'state') { + entered.resolve(undefined) + await release.promise + return { kind: 'success', text: 'state updated' } + } + agent.steer(createUserMessage({ content: [{ type: 'text', text: 'task' }], source: { kind: 'user' } })) + return { kind: 'success' } + }) + const state = h.run('/plan state') + await entered.promise + await h.run('/plan task') + expect(h.notices.filter(item => item.method === 'session.query.completed')).toEqual([]) + release.resolve(undefined) + await state + expect(await h.completed).toMatchObject({ finalResponse: 'state updated', finishReason: 'completed' }) + const agent = h.ctx.agents.get(h.sessionId)! + agent.cancel({ kind: 'user' }) + await agent.whenIdle() + expect(h.notices.filter(item => item.method === 'session.query.completed')).toHaveLength(2) + }) + + it('waits across goal rounds and reports the configured round limit', async () => { + const h = await setup(new MockAdapter([textResponse('first round'), textResponse('second round')]), true) + await h.run('/goal finish the task') + expect(await h.completed).toMatchObject({ finalResponse: 'second round', finishReason: 'error' }) + expect(h.model.requests).toHaveLength(2) + expect(h.notices.filter(item => item.method === 'session.query.completed')).toHaveLength(1) + expect(h.ctx.goals.get(h.ctx.agents.get(h.sessionId)!)).toMatchObject({ phase: 'blocked', roundsStarted: 2 }) + }) + + it('waits for the last reply after the goal becomes complete', async () => { + const model = new MockAdapter([() => { + const agent = h.ctx.agents.get(h.sessionId)! + const goal = h.ctx.goals.get(agent)! + h.ctx.goals.complete(agent, { id: goal.id, revision: goal.revision }) + expect(h.notices.filter(item => item.method === 'session.query.completed')).toEqual([]) + return textResponse('final reply') + }]) + const h = await setup(model, true) + await h.run('/goal finish the task') + expect(await h.completed).toMatchObject({ finalResponse: 'final reply', finishReason: 'completed' }) + }) + + it.each([ + ['complete', 'completed'], ['pause', 'aborted'], ['clear', 'aborted'], ['block', 'error'], + ] as const)('returns empty model text when a goal ends through %s without a reply', async (operation, finishReason) => { + const model = new GatedModel([textResponse('')]) + const h = await setup(model, true) + try { + await h.run('/goal work') + await model.entered.promise + const agent = h.ctx.agents.get(h.sessionId)! + const goal = h.ctx.goals.get(agent)! + const ref = { id: goal.id, revision: goal.revision } + if (operation === 'block') h.ctx.goals.block(agent, ref, { code: 'cannot-proceed', message: 'Missing input.' }) + else h.ctx.goals[operation](agent, ref) + model.release.resolve(undefined) + expect(await h.completed).toMatchObject({ finalResponse: '', finishReason }) + } finally { + model.release.resolve(undefined) + } + }) + + it('preserves goal completion when clear arrives before the final reply finishes', async () => { + const model = new GatedModel([textResponse('final reply')]) + const h = await setup(model, true) + try { + const response = await h.run('/goal work') + if (response.kind !== 'command') throw new Error('Expected goal command acknowledgment') + await model.entered.promise + const agent = h.ctx.agents.get(h.sessionId)! + const goal = h.ctx.goals.get(agent)! + h.ctx.goals.complete(agent, { id: goal.id, revision: goal.revision }) + expect(h.notices.filter(item => item.method === 'session.query.completed')).toEqual([]) + await h.run('/goal clear') + expect(await h.completed).toMatchObject({ finalResponse: 'Goal cleared.', finishReason: 'completed' }) + expect(h.notices.filter(item => item.method === 'session.query.completed')).toHaveLength(1) + model.release.resolve(undefined) + await h.server.wait({ sessionId: h.sessionId }) + expect(h.notices.filter(item => item.method === 'session.query.completed')).toMatchObject([ + { params: { finalResponse: 'Goal cleared.', finishReason: 'completed' } }, + { params: { commandId: response.execution.commandId, finalResponse: 'final reply', finishReason: 'completed' } }, + ]) + expect(h.ctx.goals.get(agent)).toBeUndefined() + } finally { + model.release.resolve(undefined) + } + }) + + it('finishes visibly when goal persistence failure disarms continuation before a model request', async () => { + const h = await setup(new MockAdapter([]), true) + vi.spyOn(h.ctx.sessions, 'flush').mockRejectedValue(new Error('checkpoint unavailable')) + await h.run('/goal finish the task') + expect(await h.completed).toHaveProperty('finishReason', 'error') + expect(await h.completed).toHaveProperty('finalResponse', expect.stringContaining('stopped')) + expect(h.model.requests).toHaveLength(0) + }) + + it('releases active query observers when the server shuts down', async () => { + const h = await setup(new MockAdapter(['hang'])) + h.register(({ agent }) => { + agent.steer(createUserMessage({ content: [{ type: 'text', text: 'task' }], source: { kind: 'user' } })) + return { kind: 'success' } + }) + await h.run('/plan task') + await h.server.shutdown() + expect(h.notices.filter(item => item.method === 'session.query.completed')).toEqual([]) + }) + + it('lets clear return while the original goal run waits for its current reply', async () => { + const model = new GatedModel([textResponse('current reply')]) + const h = await setup(model, true) + await h.run('/goal work') + await model.entered.promise + await h.run('/goal clear') + expect(await h.completed).toMatchObject({ finishReason: 'completed', finalResponse: 'Goal cleared.' }) + expect(h.notices.filter(item => item.method === 'session.query.completed')).toHaveLength(1) + model.release.resolve(undefined) + await h.server.wait({ sessionId: h.sessionId }) + expect(h.notices.filter(item => item.method === 'session.query.completed').at(-1)?.params) + .toMatchObject({ finishReason: 'aborted', finalResponse: 'current reply' }) + }) + + it('waits for goal reference input queued behind maintenance after clear', async () => { + const model = new GatedModel([textResponse('reference reply')]) + const h = await setup(model, true) + const store: Pick = { + saveImages: async () => [{ attachmentId: AttachmentId('reference'), mediaType: 'image/png', bytes: 1, width: 1, height: 1 }], + } + h.ctx.provide('attachments', store as AttachmentStore) + await h.server.getWorkingDirectory({ sessionId: h.sessionId }) + const agent = h.ctx.agents.get(h.sessionId)! + const releaseMaintenance = Promise.withResolvers() + const maintenance = agent.runMaintenance(() => releaseMaintenance.promise) + try { + const response = await h.server.query({ sessionId: h.sessionId, delivery: 'queue', contentBlocks: [ + { type: 'text', text: '/goal inspect the reference' }, + { type: 'image', data: 'AQ==', mimeType: 'image/png' }, + ] }) + if (response.kind !== 'command') throw new Error('Expected goal command acknowledgment') + await h.run('/goal clear') + expect(await h.completed).toMatchObject({ finalResponse: 'Goal cleared.', finishReason: 'completed' }) + releaseMaintenance.resolve(undefined) + await model.entered.promise + expect(h.notices.filter(item => item.method === 'session.query.completed')).toHaveLength(1) + model.release.resolve(undefined) + await h.server.wait({ sessionId: h.sessionId }) + expect(h.notices.filter(item => item.method === 'session.query.completed')).toMatchObject([ + { params: { finalResponse: 'Goal cleared.', finishReason: 'completed' } }, + { params: { commandId: response.execution.commandId, finalResponse: 'reference reply', finishReason: 'aborted' } }, + ]) + expect(model.requests[0]?.messages.flatMap(message => message.content).some(block => block.type === 'image')).toBe(true) + } finally { + releaseMaintenance.resolve(undefined) + model.release.resolve(undefined) + await maintenance + } + }) + + it('settles a paused goal and observes a later resumed run independently', async () => { + const model = new GatedModel([textResponse('cancelled'), () => { + const agent = h.ctx.agents.get(h.sessionId)! + const goal = h.ctx.goals.get(agent)! + h.ctx.goals.complete(agent, { id: goal.id, revision: goal.revision }) + return textResponse('resumed reply') + }]) + const h = await setup(model, true) + await h.run('/goal work') + await model.entered.promise + await h.run('/goal pause') + await h.server.wait({ sessionId: h.sessionId }) + expect(h.notices.filter(item => item.method === 'session.query.completed').map(item => item.params)) + .toContainEqual(expect.objectContaining({ finishReason: 'aborted' })) + await h.run('/goal resume') + await h.server.wait({ sessionId: h.sessionId }) + // Goal startup checkpoints can precede the first running interval. + const agent = h.ctx.agents.get(h.sessionId)! + if (h.ctx.goals.get(agent)?.phase !== 'complete') { + await new Promise((resolve) => { + const off = h.ctx.on('agent/status', ({ agent: current, status }) => { + if (current === agent && status === 'idle' && h.ctx.goals.get(agent)?.phase === 'complete') { + off() + resolve() + } + }) + onTestFinished(() => { off() }) + }) + } + expect(h.notices.filter(item => item.method === 'session.query.completed').at(-1)?.params) + .toMatchObject({ finishReason: 'completed', finalResponse: 'resumed reply' }) + }) + + it('ignores other Sessions and reports a failing admitted model operation', async () => { + const h = await setup(new MockAdapter([])) + const gate = Promise.withResolvers() + const entered = Promise.withResolvers() + h.register(async ({ agent }) => { + entered.resolve(undefined) + await gate.promise + agent.steer(createUserMessage({ content: [{ type: 'text', text: 'task' }], source: { kind: 'user' } })) + return { kind: 'success' } + }) + h.ctx.on('agent/pre-step', () => { throw new Error('request preparation failed') }) + const running = h.run('/plan task') + await entered.promise + const other = await h.ctx.agents.create({ + sessionId: SessionId('outside-sdk'), meta: { cwd: process.cwd() }, + agentOptions: { provider: 'query-activity', model: 'model' }, + }) + await other.dispose() + await h.server.prompt({ sessionId: 'other', contentBlocks: [{ type: 'text', text: 'other task' }] }) + await h.server.wait({ sessionId: 'other' }).catch((error: unknown) => { expect(error).toBeInstanceOf(Error) }) + gate.resolve(undefined) + await running + expect(await h.completed).toMatchObject({ finishReason: 'error' }) + }) + + it('reports a goal Agent failure followed by disarmed continuation', async () => { + const model = new GatedModel([textResponse('')]) + const h = await setup(model, true) + await h.run('/goal work') + await model.entered.promise + const agent = h.ctx.agents.get(h.sessionId)! + h.ctx.emit('agent/error', { agent, turn: 1, step: 1, error: new Error('driver failed') }) + h.ctx.goals.disarm(agent) + model.release.resolve(undefined) + expect(await h.completed).toHaveProperty('finishReason', 'error') + expect(await h.completed).toHaveProperty('finalResponse', expect.stringContaining('stopped')) + }) + + it('reports a host-cleared goal as aborted even when the last model turn failed', async () => { + const h = await setup(new MockAdapter([]), true) + h.ctx.on('agent/pre-step', () => { throw new Error('request preparation failed') }) + h.ctx.on('agent/error', ({ agent }) => { + const goal = h.ctx.goals.get(agent) + if (goal !== undefined) h.ctx.goals.clear(agent, { id: goal.id, revision: goal.revision }) + }) + await h.run('/goal work') + expect(await h.completed).toMatchObject({ finishReason: 'aborted', finalResponse: '' }) + }) + + it('ends a goal query when its provider unloads', async () => { + const model = new GatedModel([textResponse('unfinished')]) + const h = await setup(model, true) + await h.run('/goal work') + await model.entered.promise + await h.goals!.dispose() + expect(await h.completed).toMatchObject({ finishReason: 'error' }) + }) + + it('keeps unrelated plan activity alive when the optional goal provider unloads', async () => { + const model = new GatedModel([textResponse('plan reply')]) + const h = await setup(model, true) + h.register(({ agent }) => { + agent.steer(createUserMessage({ content: [{ type: 'text', text: 'task' }], source: { kind: 'user' } })) + return { kind: 'success' } + }) + await h.run('/plan task') + await model.entered.promise + await h.goals!.dispose() + expect(h.notices.filter(item => item.method === 'session.query.completed')).toEqual([]) + model.release.resolve(undefined) + expect(await h.completed).toMatchObject({ finishReason: 'completed', finalResponse: 'plan reply' }) + }) + + it('correlates provider loss before the native command response arrives', async () => { + const h = await setup(new GatedModel([textResponse('unfinished')]), true) + const entered = Promise.withResolvers() + const release = Promise.withResolvers() + h.ctx.commands.register({ + name: 'start-goal', definitionId: CommandDefinitionId('@deepseek-ai/dsh-command-goal'), description: 'Start goal', + handler: async ({ agent }) => { + h.ctx.goals.create(agent, { objective: 'work' }) + entered.resolve(undefined) + await release.promise + return { kind: 'success', text: 'accepted' } + }, + }) + const response = h.run('/start-goal') + await entered.promise + await h.goals!.dispose() + const completed = await h.completed + release.resolve(undefined) + const acknowledged = await response + if (acknowledged.kind !== 'command') throw new Error('Expected native command acknowledgment') + expect(completed).toMatchObject({ commandId: acknowledged.execution.commandId, finishReason: 'error' }) + }) + + it.each([false, true])('releases a command still entering its handler during loop disposal (shutdown=%s)', async (shutdown) => { + const h = await setup() + const gate = Promise.withResolvers() + const entered = Promise.withResolvers() + let stopping: Promise | undefined + if (shutdown) h.ctx.on('agent/disposed', () => { stopping = h.server.shutdown() }) + h.register(async () => { entered.resolve(undefined); await gate.promise; return { kind: 'success' } }) + const running = h.run('/plan') + const rejected = expect(running).rejects.toThrow() + await entered.promise + await h.loop.dispose() + gate.resolve(undefined) + await rejected + await stopping + const completions = h.notices.filter(item => item.method === 'session.query.completed') + if (shutdown) expect(completions).toEqual([]) + else expect(completions[0]?.params).toHaveProperty('finishReason', 'error') + }) + + it('rejects disposal before the executor has assigned a command identity', async () => { + const h = await setup() + h.register(() => ({ kind: 'success' })) + const execute = h.ctx.commands.execute.bind(h.ctx.commands) + vi.spyOn(h.ctx.commands, 'execute').mockImplementation(async (...args) => { + await h.loop.dispose() + return execute(...args) + }) + await expect(h.run('/plan')).rejects.toThrow() + expect(h.notices.filter(item => item.method === 'session.query.completed')).toEqual([]) + }) +}) diff --git a/packages/sdk/server/tsconfig.json b/packages/sdk/server/tsconfig.json index 5bb2b23171..d1e5858086 100644 --- a/packages/sdk/server/tsconfig.json +++ b/packages/sdk/server/tsconfig.json @@ -49,6 +49,9 @@ }, { "path": "../../interaction/commands" + }, + { + "path": "../../goal/goal" } ] } diff --git a/python/sdk/README.i18n.yaml b/python/sdk/README.i18n.yaml index 5b43e9ce25..a9c5afd777 100644 --- a/python/sdk/README.i18n.yaml +++ b/python/sdk/README.i18n.yaml @@ -12,8 +12,8 @@ en: ac793c588b13ce87 zh: 502015cda46de3ac /deepseek-harness-python-sdk/run-text-and-commands: - en: 477bb559cbf13f84 - zh: c5825be4ae2f1508 + en: 945bbaded33412ab + zh: b9905a5225de1f86 /deepseek-harness-python-sdk/client-approvals: en: fc69be1beb8abff1 zh: 91b56781931a6f68 diff --git a/python/sdk/README.md b/python/sdk/README.md index 13b639ac15..2bf9f087ca 100644 --- a/python/sdk/README.md +++ b/python/sdk/README.md @@ -33,7 +33,7 @@ The Python SDK has no separate application entrypoint. It launches the bundled ` Every launch requires an explicit Harness home. Pass `dsh_home` or provide a non-empty `DSH_HOME` in the child environment. The SDK deliberately never discovers `~/.dsh`. ```py -from deepseek_harness import DeepSeekHarness, RunResult +from deepseek_harness import DeepSeekHarness with DeepSeekHarness( dsh_home="/absolute/path/to/isolated-dsh-home", @@ -45,7 +45,7 @@ with DeepSeekHarness( ) as harness: result = harness.run("Say hi.", session_id="example-001") -print(result.final_response if isinstance(result, RunResult) else result.result.text) +print(result.final_response) ``` `DeepSeekHarness` starts lazily and reuses its runtime until `close()` or context-manager exit. The initial profile handshake has an independent 30-second default bound through `initialize_timeout_seconds`; ordinary activity remains unbounded after its protocol response, whose wait can be limited with `request_timeout_seconds`. A timeout names the selected profile and includes retained runtime diagnostics. `cwd` is the agent workspace; `runtime_cwd` independently selects the subprocess working directory. Both become absolute before launch. `provider`, `model`, optional `reasoning_effort`, and optional positive `max_tokens` are sent during JSON-RPC initialization. `base_url` and `api_key` explicitly override `DEEPSEEK_BASE_URL` and `DEEPSEEK_API_KEY` in the child environment. @@ -63,21 +63,21 @@ with DeepSeekHarness(dsh_home="/absolute/path/to/saved-home") as harness: `session.run(input, on_notification=..., delivery="queue")` is the public prompt-or-command input entry for strings and content-block arrays. Both use the runtime's [supported command forms and Desktop aliases](../../packages/sdk/server/README.md#command-input); unrecognized input remains an ordinary prompt with its original block order. `delivery="steer"` targets the next available step for ordinary input, including images. Command admission and timing remain owned by the native handler. -The call returns `RunResult` for an ordinary prompt's inbox-receipt-to-idle interval, or `RunCommandResult` after a command settles. Both results include `session_id`, including when `harness.run()` creates a fresh Session. `RunCommandResult` extends the native `CommandExecution` with that Session identity. Use `isinstance(result, RunResult)` before reading `final_response`; otherwise inspect the command's `result.kind`. A command retains its `command_id` and optional `source_event_seq`, rather than selecting an earlier assistant reply. +Every call returns `RunResult`, including the receiving `session_id`, root events and Session-tree notifications. `final_response` contains the final assistant text, or an empty string when the activity emits none. State-only commands return the native handler's result text. `finish_reason` reports the terminal outcome. Native command identities and outcomes remain in `command/run` and `command/done` events. -Content-block arrays use the same command routing as strings. Both `session.run([{"type": "text", "text": "/compact"}])` and `session.run("/compact")` invoke native compaction and return `RunCommandResult`. To bypass native command routing, call the low-level `client.session_prompt(session_id, blocks)` and manage the subsequent subscription and wait yourself; runtime skill recognition still applies. +Content-block arrays use the same command routing as strings. Both `session.run([{"type": "text", "text": "/compact"}])` and `session.run("/compact")` invoke native compaction and return `RunResult`. To bypass native command routing, call the low-level `client.session_prompt(session_id, blocks)` and manage subsequent activity; runtime skill recognition still applies. Select a model that supports image input. Submit a command and image in the existing content-block array, for example `session.run([{"type": "text", "text": "/plan Analyze this image."}, {"type": "image", "data": image_base64, "mimeType": "image/png"}])`; `harness.run()` accepts the same input. Plan input and goal creation or editing accept images; `/plan off`, goal controls, compact, and permission commands reject them through the [native attachment rules](../../packages/sdk/server/README.md#command-input). Native command input supports encoded raster images, not general file uploads or client-supplied attachment references. -Each call subscribes before sending and releases its subscription before returning or raising. `on_notification` receives the ordinary activity interval in wire order; command callbacks replay Session-tree notifications from subscription through their own `command/done` after the command response, so that interval can include overlapping work. Calls may overlap without consuming each other's results. Handler refusals return `RunCommandResult.result.kind="error"`; routing, protocol, transport and observer failures raise. Malformed native-command responses from `run()` or `session_command()` raise `SdkProtocolError`, with the model validation error retained as the cause. A timeout or observer failure does not roll back runtime work or authorize an automatic retry. `request_timeout_seconds` bounds the protocol response wait, not later ordinary prompt activity. +Each call subscribes before sending and releases its subscription before returning or raising. `on_notification` receives the input's Session-tree activity in wire order; the interval can include overlapping work. Calls may overlap without consuming each other's results. Native refusals return `finish_reason="error"`; routing, protocol, transport and observer failures raise. Malformed native-command responses raise `SdkProtocolError`, retaining their validation cause. A timeout or observer failure does not roll back runtime work or authorize an automatic retry. `request_timeout_seconds` bounds the protocol response wait, not later input activity. The default full `sdk` profile provides the supported native commands; `sdk-minimal` keeps unsupported input on its ordinary prompt path. `/compact` can make an auxiliary model request and completes without a normal turn or idle notification; empty history can succeed without a summary. The lower-level `HarnessClient.session_command(session_id, line)` accepts ASCII registered names or canonical English aliases of supported builtin definitions, without prompt fallback or attachments, and returns the native `CommandExecution`. Use `run()` for Chinese aliases. See the [compaction example](examples/README.md#compact-a-full-sdk-session). `/permission ` changes only the receiving Session. An unknown preset returns a command error without changing policy. Later input and restoration retain successful changes; other Sessions and the caller's `DeepSeekHarnessConfig` keep their own values. A running approval-policy change can inject a notice and cause another model step. See the [permission example](examples/README.md#change-session-permissions). -`/plan` enters plan mode, `/plan off` leaves, and `/plan ` enters then submits the trimmed message through native steer. Its `RunCommandResult` confirms command completion, not completion of planning or review. Enter with `/plan` then run ordinary text when a `RunResult` is needed. For combined input, subscribe before `run()` and use `session/wait` while keeping the question handler alive, as in the [plan example](examples/README.md#review-a-plan). Plan guidance and `exit_plan_mode` follow their native lifecycle without changing permission settings. +`/plan` enters plan mode, `/plan off` leaves, and `/plan ` enters then submits the trimmed message through native steer. `run()` waits for submitted model activity, including native review and approved continuation; no separate subscription or `session/wait` call is required. Keep `on_user_question` available for review, as in the [plan example](examples/README.md#review-a-plan). Plans submitted through `exit_plan_mode` arrive in the review question's `detail`; `final_response` contains the final assistant text. Plan mode does not change permission settings. -`/goal` shows the current goal; `/goal `, `edit `, `pause`, `resume`, and `clear` use the native handler. Creation and resume can start automatic rounds after `run()` returns. Subscribe before sending, observe terminal `goal/change` operations, then call `session/wait` for any closing model reply. Idle between rounds is not goal completion. A restored active goal stays disarmed until explicit resume. See the [goal example](examples/README.md#run-a-goal). +`/goal` shows the current goal. Creation and resume through `run()` wait across automatic rounds until the goal stops and its closing activity finishes. Completion returns `completed`, pause or clear returns `aborted`, and blocking or lost activation reports failure. State-only controls return without waiting for unrelated activity. A restored active goal stays disarmed until explicit resume. See the [goal example](examples/README.md#run-a-goal). ## Client approvals diff --git a/python/sdk/README.zh.md b/python/sdk/README.zh.md index 2be97e77b9..5d0534c5c2 100644 --- a/python/sdk/README.zh.md +++ b/python/sdk/README.zh.md @@ -33,7 +33,7 @@ Python SDK 没有独立的应用入口。它以 `--profile sdk` 启动内置的 每次启动都必须显式指定 Harness home。请传入 `dsh_home`,或在子进程环境中提供非空的 `DSH_HOME`。SDK 刻意不会发现 `~/.dsh`。 ```py -from deepseek_harness import DeepSeekHarness, RunResult +from deepseek_harness import DeepSeekHarness with DeepSeekHarness( dsh_home="/absolute/path/to/isolated-dsh-home", @@ -45,7 +45,7 @@ with DeepSeekHarness( ) as harness: result = harness.run("Say hi.", session_id="example-001") -print(result.final_response if isinstance(result, RunResult) else result.result.text) +print(result.final_response) ``` `DeepSeekHarness` 延迟启动运行时,并在调用 `close()` 或退出上下文管理器前复用该进程。首次 profile 握手通过 `initialize_timeout_seconds` 使用独立的 30 秒默认上限;普通活动在协议响应后仍不设时限;`request_timeout_seconds` 可以限制协议响应的等待。超时诊断会指明所选 profile,并包含保留的运行时诊断。`cwd` 是 agent workspace;`runtime_cwd` 独立选择子进程工作目录。两者都会在启动前转成绝对路径。`provider`、`model`、可选的 `reasoning_effort` 和可选的正整数 `max_tokens` 通过 JSON-RPC 初始化发送。`base_url` 与 `api_key` 会显式覆盖子进程环境中的 `DEEPSEEK_BASE_URL` 与 `DEEPSEEK_API_KEY`。 @@ -63,21 +63,21 @@ with DeepSeekHarness(dsh_home="/absolute/path/to/saved-home") as harness: `session.run(input, on_notification=..., delivery="queue")` 是字符串和内容块数组共用的公开提示词/命令输入入口。两者都使用运行时的[命令形式与 Desktop 别名](../../packages/sdk/server/README.zh.md#command-input)识别规则;未识别的输入保持普通提示词及原始内容块顺序。对普通输入,包括图片,`delivery="steer"` 指向下一个可用步骤。命令的接纳规则与执行时序仍由原生处理器负责。 -普通提示词返回其入队回执到下一次 idle 区间的 `RunResult`,命令则在执行结束后返回 `RunCommandResult`。两种结果都包含 `session_id`,包括 `harness.run()` 创建新 Session 的情况。`RunCommandResult` 在原生 `CommandExecution` 上增加该 Session 标识。读取 `final_response` 前使用 `isinstance(result, RunResult)` 检查类型,否则检查命令的 `result.kind`。命令保留自己的 `command_id` 和可选 `source_event_seq`,不会选取更早的助手回复作为结果。 +每次调用都返回 `RunResult`,包含接收输入的 `session_id`、根会话事件和会话树通知。`final_response` 包含最终助手文本;活动未输出助手文本时为空字符串。仅改变状态的命令返回原生 handler 的结果文本。`finish_reason` 表示结束结果。原生命令身份与结果保留在 `command/run` 和 `command/done` 事件中。 -内容块数组与字符串使用相同的命令路由。`session.run([{"type": "text", "text": "/compact"}])` 和 `session.run("/compact")` 都调用原生压缩并返回 `RunCommandResult`。要绕过原生命令路由,调用低层 `client.session_prompt(session_id, blocks)` 并自行管理后续订阅与等待;运行时 skill(技能)识别仍然适用。 +内容块数组与字符串使用相同的命令路由。`session.run([{"type": "text", "text": "/compact"}])` 和 `session.run("/compact")` 都调用原生压缩并返回 `RunResult`。要绕过原生命令路由,调用底层 `client.session_prompt(session_id, blocks)` 并管理后续活动;运行时 skill(技能)识别仍然适用。 先选择支持图片输入的模型。通过现有内容块数组同时提交命令和图片,例如 `session.run([{"type": "text", "text": "/plan Analyze this image."}, {"type": "image", "data": image_base64, "mimeType": "image/png"}])`;`harness.run()` 接受相同输入。计划输入和目标创建、编辑接受图片;`/plan off`、目标控制、压缩和权限命令按[原生附件规则](../../packages/sdk/server/README.zh.md#command-input)拒绝图片。原生命令输入支持编码栅格图片,不支持一般文件上传或客户端提供的附件引用。 -每次调用在发送前订阅,并在返回或抛出异常前释放自己的订阅。`on_notification` 按线上的顺序接收普通活动区间通知;命令回调在命令响应到达后,按顺序交付从订阅时刻到自身 `command/done` 的 Session 树通知,因此该区间可能包含重叠工作的通知。调用可以重叠,不会消耗彼此的结果。处理器拒绝返回 `RunCommandResult.result.kind="error"`,路由、协议、传输和观察回调失败则抛出异常。`run()` 或 `session_command()` 收到格式错误的原生命令响应时抛出 `SdkProtocolError`,并保留模型校验错误作为 cause。超时或观察回调失败不回滚运行时工作,也不授权自动重试。`request_timeout_seconds` 限制协议响应等待,不限制之后的普通提示词活动。 +每次调用在发送前订阅,并在返回或抛出异常前释放订阅。`on_notification` 按传输顺序接收本次输入的会话树活动;区间可以包含重叠工作。调用可以重叠,不会消耗彼此的结果。原生拒绝返回 `finish_reason="error"`;路由、协议、传输和观察回调失败则抛出异常。格式错误的原生命令响应抛出 `SdkProtocolError`,保留校验原因。超时或观察回调失败不回滚运行时工作,也不授权自动重试。`request_timeout_seconds` 限制协议响应等待,不限制之后的输入活动。 默认的完整 `sdk` profile 提供已支持的原生命令;`sdk-minimal` 将未支持的输入保留在普通提示词路径。`/compact` 可以发起辅助模型请求,其完成不需要普通 turn 或 idle 通知;空历史可以在不生成摘要时成功。底层 `HarnessClient.session_command(session_id, line)` 接受受支持内置定义的 ASCII 注册名或英文规范别名,不回退为提示词,也不接受附件,返回原生 `CommandExecution`。中文别名使用 `run()`。见[压缩示例](examples/README.zh.md#compact-a-full-sdk-session)。 `/permission ` 只修改接收命令的 Session。未知 preset 返回命令错误,不改变策略。后续输入与恢复保留成功的修改,其他 Session 和调用方的 `DeepSeekHarnessConfig` 保留自己的值。运行中的审批策略变化可以注入通知并触发下一模型步骤。见[权限示例](examples/README.zh.md#change-session-permissions)。 -`/plan` 进入计划模式,`/plan off` 退出,`/plan ` 进入后通过原生 steer 提交去除首尾空白的正文。其 `RunCommandResult` 确认命令执行结束,不代表计划生成或审阅结束。需要 `RunResult` 时,先用 `/plan` 进入,再运行普通文本。组合输入应在 `run()` 前订阅,并保持问答处理器存活,通过 `session/wait` 观察后续工作,见[计划示例](examples/README.zh.md#review-a-plan)。计划指导和 `exit_plan_mode` 遵循原生生命周期,不修改权限设置。 +`/plan` 进入计划模式,`/plan off` 退出,`/plan ` 进入后通过原生 steer 提交去除首尾空白的正文。`run()` 等待提交的模型活动,包括原生审阅及获批后的后续执行;无需单独订阅或调用 `session/wait`。审阅期间保持 `on_user_question` 可用,见[计划示例](examples/README.zh.md#review-a-plan)。通过 `exit_plan_mode` 提交的计划位于审阅问题的 `detail` 中;`final_response` 包含最终助手文本。计划模式不修改权限设置。 -`/goal` 查看当前目标;`/goal `、`edit `、`pause`、`resume` 和 `clear` 使用原生处理器。创建和恢复可以在 `run()` 返回后启动自动轮次。发送前订阅,观察终态 `goal/change` 操作后,再调用 `session/wait` 等待可能的模型收尾。轮次之间的 idle 不代表目标完成。恢复的活动目标在显式 resume 前保持 disarmed。见[目标示例](examples/README.zh.md#run-a-goal)。 +`/goal` 显示当前目标。通过 `run()` 创建或恢复目标时,会跨越自动轮次等待,直到目标停止及最后的活动结束。完成返回 `completed`,暂停或清除返回 `aborted`,阻塞或失去激活状态报告失败。仅改变状态的控制命令不等待无关活动。恢复的活跃目标保持未激活状态,直到显式 resume。见[目标示例](examples/README.zh.md#run-a-goal)。 ## 客户端审批 diff --git a/python/sdk/examples/README.i18n.yaml b/python/sdk/examples/README.i18n.yaml index c815d981fd..c98cf68e1b 100644 --- a/python/sdk/examples/README.i18n.yaml +++ b/python/sdk/examples/README.i18n.yaml @@ -9,17 +9,17 @@ en: ac09bb6bc3ab76a0 zh: e69d1e2bd796f3bf /python-sdk-example/compact-a-full-sdk-session: - en: 7749773f97211ac1 - zh: 594348ae66a2ef6c + en: 6325ac9aaf9b9b67 + zh: 004a0ba5c2ff341b /python-sdk-example/change-session-permissions: en: 1fe5e06c6842a53b zh: ff0836d8cffaeef7 /python-sdk-example/review-a-plan: - en: ce1851c8373d0f98 - zh: 6bd4a5099f2b29e3 + en: 7a6d2d7929724240 + zh: 8a938c71a827f09b /python-sdk-example/run-a-goal: - en: f4748b8e074f3497 - zh: 271aa49d20d83a73 + en: 59f62e70dc508bd6 + zh: bb10e2db241a2e92 /python-sdk-example/add-plugins: en: 5e1e30dac13f6c9e zh: 0af98ebb75c88f43 diff --git a/python/sdk/examples/README.md b/python/sdk/examples/README.md index 04f330f1b2..284fcfca59 100644 --- a/python/sdk/examples/README.md +++ b/python/sdk/examples/README.md @@ -40,7 +40,7 @@ python python/sdk/examples/compact.py \ --workspace /absolute/path/to/disposable-workspace ``` -The script prints command ids and outcomes separately from model responses. A failed turn or command stops the example. See [Run text and commands](../README.md#run-text-and-commands) for completion and error behavior; `minimal.py` uses the same `run()` entry, with capabilities supplied by its selected profile. +The script prints `RunResult.final_response` for prompts and commands. An unsuccessful `finish_reason` stops the example. See [Run text and commands](../README.md#run-text-and-commands) for completion and error behavior; `minimal.py` uses the same `run()` entry, with capabilities supplied by its selected profile. ## Change Session permissions @@ -59,7 +59,7 @@ The command changes the Session's policy while the printed launch setting remain ## Review a plan -The [plan example](plan.py) sends `/plan ` through `run()` and keeps the Session notification subscription and question handler alive after command completion. Enter `a` to approve, `k` to give feedback, or `d` to dismiss; cancellation or EOF before an answer dismisses the review. Approval allows implementation from a later model step, so choose an isolated workspace. +The [plan example](plan.py) sends `/plan ` through `run()` and keeps the Session notification subscription and question handler alive within that call until plan activity finishes. Enter `a` to approve, `k` to give feedback, or `d` to dismiss; cancellation or EOF before an answer dismisses the review. Approval allows implementation from a later model step, so choose an isolated workspace. ```sh python python/sdk/examples/plan.py \ @@ -68,7 +68,7 @@ python python/sdk/examples/plan.py \ "Plan the requested change and present it for review." ``` -The native plan is carried in `exit_plan_mode`, not written to a workspace document. Permissions remain workspace-write. Dismissal leaves plan mode active and ends the current turn. The example waits through `session/wait` and rejects truncated or failed root turns; its question callback is independent of the protocol reader. Ctrl+C stops the example even while it is waiting for input. +The native plan is carried in `exit_plan_mode`, not written to a workspace document. Permissions remain workspace-write. Dismissal leaves plan mode active and ends the current turn. The example waits through `run()` and rejects truncated or failed root turns; its question callback is independent of the protocol reader. Ctrl+C stops the example even while it is waiting for input. Piped answers use the parent process's stdin encoding and leave later lines for subsequent questions. UTF-16 and UTF-32 input requires an explicit little-endian or big-endian encoding. Truncated characters at EOF are reported as input errors. @@ -84,7 +84,7 @@ python python/sdk/examples/goal.py \ "Calculate 17 * 19, verify the result, and complete the goal without changing files." ``` -`--timeout-seconds` requires a finite positive value and bounds the initial command wait and subsequent observation (300 seconds by default). A timeout reports failure and closes the runtime; it does not mark the goal complete. The persisted goal can be inspected after restoration and explicitly resumed. `session/wait` alone is insufficient because automatic rounds have idle gaps. +`--timeout-seconds` requires a finite positive value and bounds the initial command wait and subsequent observation (300 seconds by default). A timeout reports failure and closes the runtime; it does not mark the goal complete. The persisted goal can be inspected after restoration and explicitly resumed. `run()` includes the automatic rounds and final reply. ## Add plugins diff --git a/python/sdk/examples/README.zh.md b/python/sdk/examples/README.zh.md index dc6f24cbe6..33da1494d6 100644 --- a/python/sdk/examples/README.zh.md +++ b/python/sdk/examples/README.zh.md @@ -40,7 +40,7 @@ python python/sdk/examples/compact.py \ --workspace /absolute/path/to/disposable-workspace ``` -脚本将命令 id 和结果与模型回复分开打印。轮次或命令失败时,示例会停止。完成和错误行为见[运行文本与命令](../README.zh.md#run-text-and-commands);`minimal.py` 使用同一个 `run()` 入口,能力由所选 profile 提供。 +脚本对提示词和命令均打印 `RunResult.final_response`。不成功的 `finish_reason` 会停止示例。完成和错误行为见[运行文本与命令](../README.zh.md#run-text-and-commands);`minimal.py` 使用同一个 `run()` 入口,能力由所选 profile 提供。 ## 修改 Session 权限 @@ -59,7 +59,7 @@ python python/sdk/examples/permission.py \ ## 审查计划 -[计划示例](plan.py) 通过 `run()` 发送 `/plan `,并在命令完成后保持 Session 通知订阅和问答处理器运行。输入 `a` 批准、`k` 提供反馈、`d` 关闭;取消或作答前遇到 EOF 会关闭审查。批准后模型可以从后续步骤开始实施,因此应选择隔离的工作区。 +[计划示例](plan.py) 通过 `run()` 发送 `/plan `,并在这次调用中保持 Session 通知订阅和问答处理器运行,直到计划活动结束。输入 `a` 批准、`k` 提供反馈、`d` 关闭;取消或作答前遇到 EOF 会关闭审查。批准后模型可以从后续步骤开始实施,因此应选择隔离的工作区。 ```sh python python/sdk/examples/plan.py \ @@ -68,7 +68,7 @@ python python/sdk/examples/plan.py \ "Plan the requested change and present it for review." ``` -原生计划通过 `exit_plan_mode` 携带,而不是写入工作区文档。权限仍为 workspace-write。关闭审查会保留计划模式并结束当前轮次。示例通过 `session/wait` 等待,并报告根轮次截断或失败;问答回调独立于协议读取线程。等待输入时也可以通过 Ctrl+C 结束示例。 +原生计划通过 `exit_plan_mode` 携带,而不是写入工作区文档。权限仍为 workspace-write。关闭审查会保留计划模式并结束当前轮次。示例通过 `run()` 等待,并报告根轮次截断或失败;问答回调独立于协议读取线程。等待输入时也可以通过 Ctrl+C 结束示例。 管道答案使用父进程的 stdin 编码,后续行保留给后续问题。UTF-16 和 UTF-32 输入须明确指定小端或大端编码。EOF 处截断的字符会作为输入错误报告。 @@ -84,7 +84,7 @@ python python/sdk/examples/goal.py \ "Calculate 17 * 19, verify the result, and complete the goal without changing files." ``` -`--timeout-seconds` 必须是有限正数,用于限制首次命令等待及之后的观察时间,默认为 300 秒。超时会报告失败并关闭运行时,不会将目标标记为完成。恢复会话后可查看持久化目标,再显式恢复执行。自动轮次之间存在 idle 间隙,因此仅调用 `session/wait` 不足以等待目标结束。 +`--timeout-seconds` 必须是有限正数,用于限制首次命令等待及之后的观察时间,默认为 300 秒。超时会报告失败并关闭运行时,不会将目标标记为完成。恢复会话后可查看持久化目标,再显式恢复执行。`run()` 包含自动轮次及最后回复。 ## 添加插件 diff --git a/python/sdk/examples/compact.py b/python/sdk/examples/compact.py index c1edf0efad..ce58a3d1cd 100644 --- a/python/sdk/examples/compact.py +++ b/python/sdk/examples/compact.py @@ -7,21 +7,14 @@ import argparse import os from pathlib import Path -from deepseek_harness import RunCommandResult, DeepSeekHarness, RunResult +from deepseek_harness import DeepSeekHarness, RunResult -def display(result: RunResult | RunCommandResult) -> None: +def display(result: RunResult) -> None: """Print the input's result and stop on a reported failure.""" - if isinstance(result, RunCommandResult): - print(f"Command {result.command_id}: {result.result.kind}") - if result.result.kind == "error": - raise RuntimeError(result.result.text) - if result.result.text is not None: - print(result.result.text) - else: - if result.finish_reason != "completed": - raise RuntimeError(f"Agent turn ended with {result.finish_reason}: {result.final_response}") - print(result.final_response) + if result.finish_reason != "completed": + raise RuntimeError(f"Input ended with {result.finish_reason}: {result.final_response}") + print(result.final_response) def main() -> None: diff --git a/python/sdk/examples/goal.py b/python/sdk/examples/goal.py index 0da5196c76..a07a5ab4e6 100644 --- a/python/sdk/examples/goal.py +++ b/python/sdk/examples/goal.py @@ -6,19 +6,13 @@ from __future__ import annotations import argparse import math import os -import time from pathlib import Path +from concurrent.futures import ThreadPoolExecutor, TimeoutError as FutureTimeoutError -from pydantic import BaseModel - -from deepseek_harness import RunCommandResult, DeepSeekHarness, Notification +from deepseek_harness import DeepSeekHarness, Notification from deepseek_harness.api import final_response -class WaitResult(BaseModel): - """The empty session/wait result.""" - - def display(notification: Notification) -> dict | None: """Print durable assistant output and return the observed root Session event.""" if notification.method != "session.event": @@ -49,43 +43,22 @@ def main() -> None: with DeepSeekHarness( dsh_home=str(args.dsh_home.resolve()), cwd=str(args.workspace.resolve()), profile="sdk", model=args.model, env={"DSH_PERMISSION_MODE": "workspace-write"}, - request_timeout_seconds=args.timeout_seconds, ) as harness: session = harness.start_session() - with harness.client.subscribe_notifications(lambda notice: notice.payload.get("sessionId") == session.id) as notifications: - deadline = time.monotonic() + args.timeout_seconds - - def remaining_seconds() -> float: - remaining = deadline - time.monotonic() - if remaining <= 0: - raise TimeoutError("Goal observation timed out") - return remaining - - def observe(notification: Notification) -> dict | None: - remaining_seconds() - event = display(notification) - remaining_seconds() - return event - - execution = session.run(f"/goal {args.objective}") - if not isinstance(execution, RunCommandResult): - raise RuntimeError("The SDK profile did not execute the requested command") - print(execution.result.text, flush=True) - if execution.result.kind == "error": - raise RuntimeError(execution.result.text) - while True: - event = observe(notifications.next(timeout_seconds=remaining_seconds())) - if event is not None and event["type"] == "goal/change" and event["data"]["operation"] in { - "complete", "block", "pause", "clear", - }: - break - # A terminal goal event can precede the model's closing reply. - harness.client.request( - "session/wait", {"sessionId": session.id}, response_model=WaitResult, - timeout_seconds=remaining_seconds(), - on_notification=observe, notification_subscription=notifications, + with ThreadPoolExecutor(max_workers=1) as worker: + running = worker.submit( + session.run, f"/goal {args.objective}", + on_notification=lambda notice: display(notice) if notice.payload.get("sessionId") == session.id else None, ) - remaining_seconds() + try: + result = running.result(timeout=args.timeout_seconds) + except FutureTimeoutError as error: + raise TimeoutError("Goal observation timed out") from error + finally: + if not running.done(): + harness.close() + if result.finish_reason != "completed": + raise RuntimeError(f"Goal activity ended with {result.finish_reason}: {result.final_response}") if __name__ == "__main__": diff --git a/python/sdk/examples/minimal.py b/python/sdk/examples/minimal.py index d869cc7a33..8d8fa14af8 100644 --- a/python/sdk/examples/minimal.py +++ b/python/sdk/examples/minimal.py @@ -7,7 +7,7 @@ import argparse import os from pathlib import Path -from deepseek_harness import RunCommandResult, DeepSeekHarness +from deepseek_harness import DeepSeekHarness def main() -> None: @@ -41,12 +41,9 @@ def main() -> None: profile=args.profile, ) as harness: result = harness.run(args.prompt, session_id=args.session_id) - if isinstance(result, RunCommandResult): - if result.result.kind == "error": - raise RuntimeError(result.result.text) - print(result.result.text or "") - else: - print(result.final_response) + if result.finish_reason not in (None, "completed"): + raise RuntimeError(f"Input ended with {result.finish_reason}: {result.final_response}") + print(result.final_response) if __name__ == "__main__": diff --git a/python/sdk/examples/permission.py b/python/sdk/examples/permission.py index 4403612684..cb54b389e8 100644 --- a/python/sdk/examples/permission.py +++ b/python/sdk/examples/permission.py @@ -7,21 +7,14 @@ import argparse import os from pathlib import Path -from deepseek_harness import RunCommandResult, DeepSeekHarness, RunResult +from deepseek_harness import DeepSeekHarness, RunResult -def display(result: RunResult | RunCommandResult) -> None: +def display(result: RunResult) -> None: """Print the input's result and stop on a reported failure.""" - if isinstance(result, RunCommandResult): - print(f"Command {result.command_id}: {result.result.kind}") - if result.result.kind == "error": - raise RuntimeError(result.result.text) - if result.result.text is not None: - print(result.result.text) - else: - if result.finish_reason != "completed": - raise RuntimeError(f"Agent turn ended with {result.finish_reason}: {result.final_response}") - print(result.final_response) + if result.finish_reason != "completed": + raise RuntimeError(f"Input ended with {result.finish_reason}: {result.final_response}") + print(result.final_response) def main() -> None: diff --git a/python/sdk/examples/plan.py b/python/sdk/examples/plan.py index bcce4340f2..b1b95730a4 100644 --- a/python/sdk/examples/plan.py +++ b/python/sdk/examples/plan.py @@ -8,19 +8,12 @@ import os import subprocess import sys import threading -from contextlib import closing from pathlib import Path -from pydantic import BaseModel - -from deepseek_harness import RunCommandResult, DeepSeekHarness, Notification, UserQuestionRequest +from deepseek_harness import DeepSeekHarness, Notification, UserQuestionRequest from deepseek_harness.api import final_response -class WaitResult(BaseModel): - """The empty session/wait result.""" - - class _PlanReviews: """Own cancellable readers with the parent's stdin encoding and join review callbacks before exit.""" @@ -156,7 +149,7 @@ def display(notification: Notification, session_id: str) -> None: def main() -> None: - """Keep the runtime and question handler alive after the plan command completes.""" + """Keep the runtime and question handler alive until the plan activity finishes.""" parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--dsh-home", required=True, type=Path) parser.add_argument("--workspace", type=Path, default=Path.cwd()) @@ -171,17 +164,9 @@ def main() -> None: env={"DSH_PERMISSION_MODE": "workspace-write"}, ) as harness: session = harness.start_session() - with closing(harness.client.subscribe_session_notifications(session.id)) as notifications: - execution = session.run(f"/plan {args.task}") - if not isinstance(execution, RunCommandResult): - raise RuntimeError("The SDK profile did not execute the requested command") - print(execution.result.text, flush=True) - if execution.result.kind == "error": - raise RuntimeError(execution.result.text) - harness.client.request( - "session/wait", {"sessionId": session.id}, response_model=WaitResult, - on_notification=lambda notice: display(notice, session.id), notification_subscription=notifications, - ) + result = session.run(f"/plan {args.task}", on_notification=lambda notice: display(notice, session.id)) + if result.finish_reason != "completed": + raise RuntimeError(f"Plan activity ended with {result.finish_reason}: {result.final_response}") if __name__ == "__main__": diff --git a/python/sdk/src/deepseek_harness/__init__.py b/python/sdk/src/deepseek_harness/__init__.py index cb71031306..fdc6bda037 100644 --- a/python/sdk/src/deepseek_harness/__init__.py +++ b/python/sdk/src/deepseek_harness/__init__.py @@ -1,4 +1,4 @@ -from .api import RunCommandResult, DeepSeekHarness, DeepSeekHarnessConfig, RunResult, Session +from .api import DeepSeekHarness, DeepSeekHarnessConfig, RunResult, Session from .client import HarnessClient, HarnessConfig, UserQuestionHandler from .errors import SdkProtocolError from .models import ( @@ -12,7 +12,6 @@ __all__ = [ "DeepSeekHarnessConfig", "Session", "RunResult", - "RunCommandResult", "CommandExecution", "CommandResult", "CommandSuccessResult", diff --git a/python/sdk/src/deepseek_harness/api.py b/python/sdk/src/deepseek_harness/api.py index f4c44d827b..53deb8ada5 100644 --- a/python/sdk/src/deepseek_harness/api.py +++ b/python/sdk/src/deepseek_harness/api.py @@ -6,7 +6,7 @@ from pathlib import Path from typing import Callable, Literal from .client import HarnessClient, HarnessConfig, UserQuestionHandler -from .errors import SdkProtocolError, TransportClosedError +from .errors import SdkProtocolError from .models import CommandExecution, JsonObject, Notification @@ -43,32 +43,35 @@ class DeepSeekHarnessConfig: @dataclass(slots=True) class RunResult: + """Completed input with result text, outcome, root events and Session-tree notifications.""" + session_id: str final_response: str + """Final assistant text (empty when absent), native state-only result text, or a failure diagnostic.""" finish_reason: str | None events: list[JsonObject] notifications: list[Notification] -class RunCommandResult(CommandExecution): - """Settled native command result with the Session id for continued interaction.""" +class _RunActivity: + """Collect one input's root events and Session-tree notifications from its admission.""" - session_id: str - - -class _PromptActivity: - """Collect an ordinary prompt's notifications from its inbox receipt through idle.""" - - def __init__(self, session_id: str, message_id: str) -> None: + def __init__(self, session_id: str, receipt_kind: Literal["prompt", "command"], receipt_id: str) -> None: self.session_id = session_id - self.message_id = message_id + self.receipt_kind = receipt_kind + self.receipt_id = receipt_id self.received = False self.events: list[JsonObject] = [] self.notifications: list[Notification] = [] def record(self, notification: Notification, on_notification: Callable[[Notification], None] | None = None) -> bool: + if notification.method == "session.query.completed": + return False if not self.received: - if not _is_inbox_receipt(notification, self.session_id, self.message_id): + if self.receipt_kind == "prompt": + if not _is_inbox_receipt(notification, self.session_id, self.receipt_id): + return False + elif not _is_command_event(notification, self.session_id, self.receipt_id, "command/run"): return False self.received = True self.notifications.append(notification) @@ -80,10 +83,12 @@ class _PromptActivity: self.events.append(event) return True - def result(self) -> RunResult: + def result(self, completed: JsonObject | None = None) -> RunResult: return RunResult( - session_id=self.session_id, final_response=final_response(self.events), - finish_reason=finish_reason(self.events), events=self.events, notifications=self.notifications, + session_id=self.session_id, + final_response=completed["finalResponse"] if completed is not None else final_response(self.events), + finish_reason=completed["finishReason"] if completed is not None else finish_reason(self.events), + events=self.events, notifications=self.notifications, ) @@ -180,8 +185,8 @@ class DeepSeekHarness: session_id: str | None = None, on_notification: Callable[[Notification], None] | None = None, delivery: Literal["queue", "steer"] = "queue", - ) -> RunResult | RunCommandResult: - """Run input on a fresh or named Session, returning its id with either result kind.""" + ) -> RunResult: + """Run input to completion on a fresh or named Session and return its RunResult.""" return self.start_session(session_id).run(input, on_notification=on_notification, delivery=delivery) @@ -206,20 +211,21 @@ class Session: *, on_notification: Callable[[Notification], None] | None = None, delivery: Literal["queue", "steer"] = "queue", - ) -> RunResult | RunCommandResult: + ) -> RunResult: """Run text or content blocks through native input routing. - Input returns the prompt's receipt-to-idle RunResult or a settled - RunCommandResult. Both include this Session's id. Command completion does - not wait for later model work. + Ordinary prompts finish at the next idle after their inbox receipt. + State-only commands finish with their native outcome. Commands that + submit model input wait for that activity; goal creation and resume wait + through automatic rounds and the last reply after the goal stops. The first text block selects native commands. Matched commands require one text block with only encoded images beside it; native handlers decide which commands accept those images. Ordinary prompts retain block order and use the requested queue or steer delivery. Notifications retain - wire order. Command callbacks replay Session-tree notifications - from subscription through their own command/done after the response, - including overlapping work. Handler errors remain command results; - routing, transport and observer failures raise without rolling back work. + wire order. Every result retains this Session id, its root events and + Session-tree notifications, including overlapping work. Native refusals + return finish_reason="error". Routing, transport and observer failures + raise without rolling back work. """ if delivery not in ("queue", "steer"): raise ValueError("run delivery must be queue or steer") @@ -227,20 +233,21 @@ class Session: with self.harness.client.subscribe_session_notifications(self.id) as subscription: response = self.harness.client._query(self.id, input, delivery) if isinstance(response, CommandExecution): - execution = response + activity = _RunActivity(self.id, "command", response.command_id) while True: - try: - notification = subscription._next_queued() - except TransportClosedError: - break - if notification is None: - break - if on_notification is not None: - on_notification(notification) - if _is_command_done(notification, self.id, execution.command_id): - break - return RunCommandResult(session_id=self.id, commandId=execution.command_id, result=execution.result) - activity = _PromptActivity(self.id, response) + notification = subscription.next() + payload = notification.payload + if notification.method == "session.query.completed" and payload.get("sessionId") == self.id: + if not isinstance(payload.get("commandId"), str) or not payload["commandId"]: + raise SdkProtocolError("Invalid session.query.completed command identity") + if payload["commandId"] != response.command_id: + continue + if (not isinstance(payload.get("finalResponse"), str) + or not isinstance(payload.get("finishReason"), str) or not payload["finishReason"]): + raise SdkProtocolError("Invalid session.query.completed result") + return activity.result(payload) + activity.record(notification, on_notification) + activity = _RunActivity(self.id, "prompt", response) while True: notification = subscription.next() if not activity.record(notification, on_notification): @@ -268,11 +275,11 @@ def _is_inbox_receipt(notification: Notification, session_id: str, message_id: s ) -def _is_command_done(notification: Notification, session_id: str, command_id: str) -> bool: +def _is_command_event(notification: Notification, session_id: str, command_id: str, event_type: str) -> bool: if notification.method != "session.event" or notification.payload.get("sessionId") != session_id: return False event = notification.payload.get("event") - if not isinstance(event, dict) or event.get("type") != "command/done": + if not isinstance(event, dict) or event.get("type") != event_type: return False data = event.get("data") return isinstance(data, dict) and data.get("commandId") == command_id diff --git a/python/sdk/src/deepseek_harness/client.py b/python/sdk/src/deepseek_harness/client.py index 95d1d828ca..17637e257b 100644 --- a/python/sdk/src/deepseek_harness/client.py +++ b/python/sdk/src/deepseek_harness/client.py @@ -705,15 +705,6 @@ class NotificationSubscription: raise item return item - def _next_queued(self) -> Notification | None: - try: - item = self._notifications.get_nowait() - except queue.Empty: - return None - if isinstance(item, BaseException): - raise item - return item - def drain(self, on_notification: Callable[[Notification], None]) -> None: while True: try: diff --git a/python/sdk/tests/run_installed_commands.py b/python/sdk/tests/run_installed_commands.py index b222998e6e..22f98d8735 100644 --- a/python/sdk/tests/run_installed_commands.py +++ b/python/sdk/tests/run_installed_commands.py @@ -15,6 +15,7 @@ TEST_FILES = ( "test_commands_runtime.py", "test_command_attachments_runtime.py", "test_goal_runtime.py", + "test_goal_result_text_runtime.py", "test_plan_runtime.py", "test_plan_example.py", "test_plan_input.py", diff --git a/python/sdk/tests/test_command_attachments_runtime.py b/python/sdk/tests/test_command_attachments_runtime.py index 0052460c7b..5bf4d0450e 100644 --- a/python/sdk/tests/test_command_attachments_runtime.py +++ b/python/sdk/tests/test_command_attachments_runtime.py @@ -12,7 +12,7 @@ import pytest from deepseek_harness import CommandExecution, RunResult from deepseek_harness.errors import JsonRpcError from test_commands_runtime import ( - _Completion, _SESSION_ID, _WAIT_SECONDS, _command_pair, _of_type, + _Completion, _SESSION_ID, _WAIT_SECONDS, _command_pair, _native_result, _of_type, _read_events, _request_texts, _runtime, _wait_activity, ) from test_goal_runtime import _command, _until @@ -66,8 +66,8 @@ def test_plan_image_reaches_the_model_and_persists_as_a_reference( with _runtime(tmp_path, [_Completion("IMAGE_PLAN_READY")], model=_IMAGE_MODEL) as runtime: session = runtime.harness.start_session(_SESSION_ID) execution = runtime.call(session.run, content) - assert isinstance(execution, CommandExecution) - assert execution.result.kind == "success", execution.result.text + assert isinstance(execution, RunResult) + assert execution.finish_reason == "completed" and execution.final_response == "IMAGE_PLAN_READY" _wait_activity(runtime, session) [request] = runtime.model.captured() _assert_request_images(request, picture) @@ -95,8 +95,9 @@ def test_plan_off_compact_and_permission_reject_images_without_applying_the_comm executions = [] for line in ["/plan off", "/compact", "/permission danger-full-access"]: execution = runtime.call(session.run, [{"type": "text", "text": line}, picture]) - assert isinstance(execution, CommandExecution) - assert execution.result.kind == "error" + assert isinstance(execution, RunResult) + assert execution.finish_reason == "error" + execution = _native_result(execution) assert "attachment" in execution.result.text.lower() executions.append((line.split()[0][1:], execution)) assert "Plan mode off" in _command(runtime, session, "/plan off").result.text @@ -121,10 +122,10 @@ def test_goal_create_and_edit_images_reach_following_requests_as_durable_referen second = _Completion("REVISED_GOAL_IMAGE", blocked=True) with _runtime(tmp_path, [first, second], model=_IMAGE_MODEL) as runtime: session = runtime.harness.start_session(_SESSION_ID) - created = runtime.call(session.run, [original, {"type": "text", "text": "/goal Inspect the original picture."}]) + created = runtime.call(runtime.harness.client._query, session.id, [original, {"type": "text", "text": "/goal Inspect the original picture."}], "queue") assert isinstance(created, CommandExecution) and created.result.kind == "success" assert first.entered.wait(_WAIT_SECONDS), runtime.model.failures - edited = runtime.call(session.run, [revised, {"type": "text", "text": "/goal edit Inspect the revised picture."}]) + edited = runtime.call(runtime.harness.client._query, session.id, [revised, {"type": "text", "text": "/goal edit Inspect the revised picture."}], "queue") assert isinstance(edited, CommandExecution) and edited.result.kind == "success" _command(runtime, session, "/goal clear") assert not first.release.is_set() @@ -152,6 +153,35 @@ def test_goal_create_and_edit_images_reach_following_requests_as_durable_referen }] +def test_cleared_goal_waits_for_its_image_input_queued_during_compaction(tmp_path: Path) -> None: + picture = _image() + summary = _Completion("Retain the earlier task.", blocked=True) + reply = _Completion("REFERENCE_INPUT_REPLY", blocked=True) + with _runtime(tmp_path, [_Completion("EARLIER_REPLY"), summary, reply], model=_IMAGE_MODEL) as runtime: + session = runtime.harness.start_session(_SESSION_ID) + runtime.call(session.run, "Retain this earlier task. " * 256) + compacting = runtime.workers.submit(session.run, "/compact") + assert summary.entered.wait(_WAIT_SECONDS), runtime.model.failures + with runtime.harness.client.subscribe_session_notifications(session.id) as notices: + running = runtime.workers.submit(session.run, [ + {"type": "text", "text": "/goal Inspect the reference."}, picture, + ]) + _until(notices, "goal/change", "create") + cleared = session.run("/goal clear") + assert cleared.finish_reason == "completed" and cleared.final_response == "Goal cleared." + summary.release.set() + assert compacting.result(timeout=_WAIT_SECONDS).finish_reason == "completed" + assert reply.entered.wait(_WAIT_SECONDS), runtime.model.failures + assert not running.done() + _assert_request_images(runtime.model.captured()[-1], picture) + reply.release.set() + result = running.result(timeout=_WAIT_SECONDS) + assert result.finish_reason == "aborted" and result.final_response == "REFERENCE_INPUT_REPLY" + events = _read_events(runtime.logs) + _command_pair(events, result, "goal") + assert [event["data"]["operation"] for event in _of_type(events, "goal/change")] == ["create", "clear"] + + def test_goal_controls_with_images_leave_the_active_request_and_goal_unchanged(tmp_path: Path) -> None: first = _Completion("CURRENT_GOAL_REQUEST_FINISHED", blocked=True) with _runtime(tmp_path, [first], model=_IMAGE_MODEL) as runtime: @@ -162,7 +192,8 @@ def test_goal_controls_with_images_leave_the_active_request_and_goal_unchanged(t rejected = [] for line in ["/goal", "/goal pause", "/goal resume", "/goal clear", "/goal edit", "/goal Duplicate goal"]: execution = runtime.call(session.run, [{"type": "text", "text": line}, _image()]) - assert isinstance(execution, CommandExecution) and execution.result.kind == "error" + assert isinstance(execution, RunResult) and execution.finish_reason == "error" + execution = _native_result(execution) rejected.append(execution) assert "Status: active" in _command(runtime, session, "/goal").result.text assert not first.release.is_set() and len(runtime.model.captured()) == 1 @@ -238,7 +269,8 @@ def test_invalid_image_batch_cannot_enter_plan_mode_or_deliver_a_partial_prompt( ]) assert "command" in str(ambiguous.value).lower() rejected = runtime.call(session.run, [{"type": "text", "text": "/plan Inspect the pictures."}, *images]) - assert isinstance(rejected, CommandExecution) and rejected.result.kind == "error" + assert isinstance(rejected, RunResult) and rejected.finish_reason == "error" + rejected = _native_result(rejected) assert "base64" in rejected.result.text with pytest.raises(JsonRpcError, match="base64"): runtime.call(session.run, [*images, {"type": "text", "text": "Inspect the pictures."}]) diff --git a/python/sdk/tests/test_commands_runtime.py b/python/sdk/tests/test_commands_runtime.py index 6aefaabef4..15ad0764d7 100644 --- a/python/sdk/tests/test_commands_runtime.py +++ b/python/sdk/tests/test_commands_runtime.py @@ -302,7 +302,20 @@ def _of_type(events: list[dict], name: str) -> list[dict]: return [event for event in events if event["type"] == name] -def _command_pair(events: list[dict], execution: CommandExecution, name: str = "compact") -> None: +def _native_result(result: RunResult) -> CommandExecution: + """Read the native outcome retained in a high-level result's command lifecycle events.""" + started = next(event for event in result.events if event["type"] == "command/run") + identity = started["data"]["commandId"] + done = next(event["data"] for event in result.events + if event["type"] == "command/done" and event["data"]["commandId"] == identity) + return CommandExecution.model_validate({"commandId": identity, "result": { + key: value for key, value in done.items() if key in ("kind", "text", "sourceEventSeq") + }}) + + +def _command_pair(events: list[dict], execution: CommandExecution | RunResult, name: str = "compact") -> None: + if isinstance(execution, RunResult): + execution = _native_result(execution) runs = [event for event in _of_type(events, "command/run") if event["data"]["commandId"] == execution.command_id] done = [event for event in _of_type(events, "command/done") @@ -348,7 +361,8 @@ def test_compact_without_history_returns_without_a_model_turn(tmp_path: Path) -> raise finally: observer.close() - assert isinstance(execution, CommandExecution) + assert isinstance(execution, RunResult) + execution = _native_result(execution) assert done["commandId"] == execution.command_id assert execution.result.kind == "success" assert execution.result.source_event_seq is None @@ -370,7 +384,8 @@ def test_compact_rejects_busy_agent_before_the_model_is_released(tmp_path: Path) assert response.entered.wait(_WAIT_SECONDS), runtime.model.failures assert not running.done() and not response.release.is_set() execution = runtime.call(session.run, "/compact", delivery="queue") - assert isinstance(execution, CommandExecution) + assert isinstance(execution, RunResult) + execution = _native_result(execution) assert execution.result.kind == "error" assert not response.release.is_set() assert not running.done() @@ -405,7 +420,8 @@ def run_compaction_scenario(tmp_path: Path, *, capture_patch: Path | None = None assert not compacting.done(), "command returned before its summary request completed" summary_response.release.set() execution = compacting.result(timeout=_WAIT_SECONDS) - assert isinstance(execution, CommandExecution) + assert isinstance(execution, RunResult) + execution = _native_result(execution) assert execution.result.kind == "success" assert execution.result.source_event_seq is not None @@ -526,8 +542,8 @@ def _permission_facts(events: list[dict]) -> list[dict]: def _permission_command(runtime: _Runtime, session: Session, preset: str) -> CommandExecution: result = runtime.call(session.run, f"/permission {preset}") - assert isinstance(result, CommandExecution) - return result + assert isinstance(result, RunResult) + return _native_result(result) def test_permission_changes_only_the_selected_session_and_retains_prompt_semantics(tmp_path: Path) -> None: diff --git a/python/sdk/tests/test_goal_example.py b/python/sdk/tests/test_goal_example.py index d14b52b854..10b7b84076 100644 --- a/python/sdk/tests/test_goal_example.py +++ b/python/sdk/tests/test_goal_example.py @@ -5,9 +5,9 @@ from __future__ import annotations import json import runpy import sys +import threading from concurrent.futures import ThreadPoolExecutor from pathlib import Path -from types import SimpleNamespace import pytest @@ -17,8 +17,8 @@ from deepseek_harness import DeepSeekHarness _EXAMPLE = Path(__file__).resolve().parents[1] / "examples/goal.py" -@pytest.mark.parametrize("pending", ["command", "goal-event", "wrapup", "complete", "goal-queue", "wrapup-queue"]) -def test_goal_example_bounds_pending_work_and_reaps_runtime( +@pytest.mark.parametrize("pending", ["command", "activity", "complete", "error", "interrupt"]) +def test_goal_example_bounds_the_whole_run_and_reaps_runtime( tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], pending: str, ) -> None: peer = tmp_path / "goal-peer.py" @@ -41,26 +41,25 @@ for line in sys.stdin: send({"id": frame["id"], "result": {"serverInfo": {"name": "goal-example-peer"}}}) elif method == "session/query": assert frame["params"]["contentBlocks"] == [{"type": "text", "text": "/goal Finish this task"}] - session = frame["params"]["sessionId"] if pending == "command": continue - if pending in ("wrapup", "complete", "wrapup-queue"): + session = frame["params"]["sessionId"] + for kind in ("command/run", "command/done"): send({"method": "session.event", "params": {"sessionId": session, "event": { - "type": "goal/change", "data": {"operation": "complete"}}}}) - elif pending == "goal-queue": - for operation in ("create", "edit"): - send({"method": "session.event", "params": {"sessionId": session, "event": { - "type": "goal/change", "data": {"operation": operation}}}}) + "type": kind, "data": {"commandId": "goal-command"}}}}) send({"id": frame["id"], "result": {"kind": "command", "execution": { "commandId": "goal-command", "result": {"kind": "success", "text": "Goal set"}}}}) - elif method == "session/wait": - if pending == "wrapup": + if pending in ("activity", "interrupt"): continue - for _ in range(2 if pending == "wrapup-queue" else 1): + if pending == "complete": + send({"method": "session.event", "params": {"sessionId": session, "event": { + "type": "goal/change", "data": {"operation": "complete"}}}}) send({"method": "session.event", "params": {"sessionId": session, "event": { "type": "assistant/message", "data": {"message": { "content": [{"type": "text", "text": "Closing reply"}]}}}}}) - send({"id": frame["id"], "result": {}}) + send({"method": "session.query.completed", "params": {"sessionId": session, + "commandId": "goal-command", "finalResponse": "Closing reply" if pending == "complete" else "Goal stopped", + "finishReason": "completed" if pending == "complete" else "error"}}) elif method == "shutdown": send({"id": frame["id"], "result": {}}) break @@ -79,49 +78,47 @@ for line in sys.stdin: return harness monkeypatch.setitem(example["main"].__globals__, "DeepSeekHarness", configured_harness) - queued = pending in {"goal-queue", "wrapup-queue"} - displayed = [] - if queued: - clock = [0.0] + if pending == "interrupt": + entered = threading.Event() display = example["display"] - - def advance_after_display(notification): - event = display(notification) - if event is not None: - displayed.append(event["type"]) - if pending == "goal-queue" or event["type"] == "assistant/message": - clock[0] = 11.0 - return event - - # Advance only the example clock while the real transport retains its own timeout. - monkeypatch.setitem(example["main"].__globals__, "time", SimpleNamespace(monotonic=lambda: clock[0])) - monkeypatch.setitem(example["main"].__globals__, "display", advance_after_display) - timeout = "10" if pending == "complete" or queued else "1" + def observe(notice): + if notice.method == "session.event" and notice.payload["event"]["type"] == "command/done": + entered.set() + return display(notice) + class InterruptedExecutor(ThreadPoolExecutor): + def submit(self, *args, **kwargs): + future = super().submit(*args, **kwargs) + def interrupt(timeout=None): + assert entered.wait(10), "command must be observed before interrupting its wait" + raise KeyboardInterrupt + monkeypatch.setattr(future, "result", interrupt) + return future + monkeypatch.setitem(example["main"].__globals__, "display", observe) + monkeypatch.setitem(example["main"].__globals__, "ThreadPoolExecutor", InterruptedExecutor) + timeout = "1" if pending in {"command", "activity"} else "10" monkeypatch.setattr(sys, "argv", [str(_EXAMPLE), "--dsh-home", str(tmp_path / "home"), "--workspace", str(tmp_path), "--timeout-seconds", timeout, "Finish this task"]) - # The outer bound also releases an implementation that forgets its own deadline. with ThreadPoolExecutor(max_workers=1) as workers: execution = workers.submit(example["main"]) try: - if pending == "complete": - execution.result(timeout=30) - else: - expected = {"command": "session/query timed out", "goal-event": "SDK notification", - "wrapup": "session/wait timed out", "goal-queue": "Goal observation timed out", - "wrapup-queue": "Goal observation timed out"}[pending] - with pytest.raises(TimeoutError, match=expected): + if pending in {"command", "activity"}: + with pytest.raises(TimeoutError, match="Goal observation timed out"): execution.result(timeout=30) + elif pending == "interrupt": + with pytest.raises(KeyboardInterrupt): + execution.result(timeout=30) + elif pending == "error": + with pytest.raises(RuntimeError, match="Goal stopped"): + execution.result(timeout=30) + else: + execution.result(timeout=30) finally: for harness in harnesses: harness.close() [harness] = harnesses assert harness.client._proc is None frames = [json.loads(line) for line in observed.read_text(encoding="utf-8").splitlines()] - methods = [frame["method"] for frame in frames] - assert methods == ["initialize", "session/query", - *(["session/wait"] if pending in {"wrapup", "complete", "wrapup-queue"} else []), "shutdown"] - if queued: - assert displayed == (["goal/change"] if pending == "goal-queue" else ["goal/change", "assistant/message"]) + assert [frame["method"] for frame in frames] == ["initialize", "session/query", "shutdown"] if pending == "complete": output = capsys.readouterr().out assert "Goal: complete" in output diff --git a/python/sdk/tests/test_goal_result_text_runtime.py b/python/sdk/tests/test_goal_result_text_runtime.py new file mode 100644 index 0000000000..db799fee92 --- /dev/null +++ b/python/sdk/tests/test_goal_result_text_runtime.py @@ -0,0 +1,29 @@ +"""Goal run results preserve empty assistant text through the shipped SDK profile.""" + +from pathlib import Path + +from test_commands_runtime import _Completion, _runtime, _SESSION_ID +from test_goal_runtime import _completion_steps + + +def test_completed_goal_without_assistant_text_returns_empty_result(tmp_path: Path) -> None: + with _runtime(tmp_path, _completion_steps(_Completion("")), + initial_permission="workspace-write") as runtime: + session = runtime.harness.start_session(_SESSION_ID) + result = runtime.call(session.run, "/goal Finish the task.") + assert result.final_response == "" and result.finish_reason == "completed" + assert any(event["type"] == "goal/change" and event["data"]["operation"] == "complete" + for event in result.events) + cleared = runtime.call(session.run, "/goal clear") + assert cleared.final_response == "Goal cleared." and cleared.finish_reason == "completed" + assert len(runtime.model.captured()) == 3 + + +def test_blocked_goal_without_assistant_text_returns_empty_result(tmp_path: Path) -> None: + with _runtime(tmp_path, [_Completion("")], max_goal_rounds=1) as runtime: + session = runtime.harness.start_session(_SESSION_ID) + result = runtime.call(session.run, "/goal Finish the task.") + assert result.final_response == "" and result.finish_reason == "error" + assert any(event["type"] == "goal/change" and event["data"]["goal"]["phase"] == "blocked" + for event in result.events) + assert len(runtime.model.captured()) == 1 diff --git a/python/sdk/tests/test_goal_runtime.py b/python/sdk/tests/test_goal_runtime.py index d8c42ab4d7..f3b13051c8 100644 --- a/python/sdk/tests/test_goal_runtime.py +++ b/python/sdk/tests/test_goal_runtime.py @@ -9,7 +9,7 @@ import threading import pytest from pathlib import Path -from deepseek_harness import CommandExecution, Session +from deepseek_harness import CommandExecution, RunResult, Session from deepseek_harness.client import NotificationSubscription from test_commands_runtime import ( _Completion, _Runtime, _SESSION_ID, _WAIT_SECONDS, _WaitResult, _assert_request_permission, @@ -19,7 +19,7 @@ from test_commands_runtime import ( def _command(runtime: _Runtime, session: Session, text: str, *, kind: str = "success") -> CommandExecution: - result = runtime.call(session.run, text) + result = runtime.call(runtime.harness.client._query, session.id, text, "queue") assert isinstance(result, CommandExecution) assert result.result.kind == kind, result.result.text return result @@ -64,61 +64,31 @@ def test_goal_reads_and_invalid_controls_do_not_start_model_work(tmp_path: Path) _command_pair(events, execution, "goal") -def test_goal_continues_rounds_and_finishes_wrapup_after_completion_event(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: +@pytest.mark.parametrize("clear_before_reply", [False, True]) +def test_goal_continues_rounds_and_finishes_wrapup_after_completion_event( + tmp_path: Path, clear_before_reply: bool, +) -> None: final = _Completion("GOAL_DONE", blocked=True) with _runtime(tmp_path, [_Completion("PROGRESS"), *_completion_steps(final)], initial_permission="workspace-write", max_goal_rounds=3) as runtime: session = runtime.harness.start_session(_SESSION_ID) with runtime.harness.client.subscribe_session_notifications(session.id) as events: - execution = _command(runtime, session, "/目标 Verify the small change.") + running = runtime.workers.submit(session.run, "/目标 Verify the small change.") completed = _until(events, "goal/change", "complete") assert completed["goal"]["phase"] == "complete" and completed["roundsStarted"] == 2 assert final.entered.wait(_WAIT_SECONDS) - client = runtime.harness.client - sent = threading.Event() - replied = threading.Event() - wait_ids = set() - write = client._write_message - handle = client._handle_message - - def record_send(message: dict) -> None: - is_wait = message.get("method") == "session/wait" - if is_wait: - wait_ids.add(message["id"]) - write(message) - if is_wait: - sent.set() - - def record_response(message: object) -> None: - if isinstance(message, dict) and "method" not in message and message.get("id") in wait_ids: - replied.set() - handle(message) - - monkeypatch.setattr(client, "_write_message", record_send) - monkeypatch.setattr(client, "_handle_message", record_response) - waiting = runtime.workers.submit(client.request, "session/wait", {"sessionId": session.id}, response_model=_WaitResult) - assert sent.wait(_WAIT_SECONDS) - # Observe the reader directly so caller scheduling cannot hide an early response. - runtime.call(client.get_working_directory, session.id) - assert not replied.is_set() and not final.release.is_set() + assert not running.done() + if clear_before_reply: + cleared = runtime.call(session.run, "/goal clear") + assert cleared.final_response == "Goal cleared." and cleared.finish_reason == "completed" + assert not running.done() final.release.set() - assert waiting.result(timeout=_WAIT_SECONDS).model_dump() == {} - assert _until(events, "turn/end")["turn"] == 2 - requests = runtime.model.captured() - assert len(requests) == 4 - assert 'Objective: "Verify the small change."\nRound: 1/3' in "\n".join(_request_texts(requests[0])) - assert 'Round: 2/3' in "\n".join(_request_texts(requests[1])) - assert '' in "\n".join(_request_texts(requests[-1])) - for request in requests: - _assert_request_permission(request, "workspace-write", "ask") - assert runtime.harness.config.env["DSH_PERMISSION_MODE"] == "workspace-write" - events = _read_events(runtime.logs) - _command_pair(events, execution, "goal") - assert [e["data"]["turn"] for e in _of_type(events, "turn/start")] == [1, 2] - assert [e["data"] for e in _of_type(events, "step/start")] == [ - {"turn": 1, "step": 1}, {"turn": 2, "step": 1}, {"turn": 2, "step": 2}, {"turn": 2, "step": 3}, - ] - assert len(_permission_facts(events)) == 3 + result = running.result(timeout=_WAIT_SECONDS) + assert isinstance(result, RunResult) + assert result.final_response == "GOAL_DONE" and result.finish_reason == "completed" + operations = ["create", "complete", *(["clear"] if clear_before_reply else [])] + assert [event["data"]["operation"] for event in result.events if event["type"] == "goal/change"] == operations + _command_pair(_read_events(runtime.logs), result, "goal") def test_pause_aborts_then_edit_and_resume_use_revised_goal_without_changing_other_sessions(tmp_path: Path) -> None: diff --git a/python/sdk/tests/test_plan_runtime.py b/python/sdk/tests/test_plan_runtime.py index 05c64c5094..3d73d7d3e7 100644 --- a/python/sdk/tests/test_plan_runtime.py +++ b/python/sdk/tests/test_plan_runtime.py @@ -7,10 +7,10 @@ from pathlib import Path import pytest -from deepseek_harness import CommandExecution, RunCommandResult, RunResult, Session, UserQuestionRequest +from deepseek_harness import CommandExecution, RunResult, Session, UserQuestionRequest from test_commands_runtime import ( _Completion, _Runtime, _SESSION_ID, _WAIT_SECONDS, _assert_request_permission, - _command_pair, _of_type, _permission_facts, _read_events, + _command_pair, _native_result, _of_type, _permission_facts, _read_events, _request_texts, _runtime, _text_blocks, _wait_activity, ) @@ -20,7 +20,7 @@ _GUIDANCE = "You are in plan mode." def _command(runtime: _Runtime, session: Session, text: str) -> CommandExecution: - result = runtime.call(session.run, text) + result = runtime.call(runtime.harness.client._query, session.id, text, "queue") assert isinstance(result, CommandExecution) assert result.result.kind == "success", result.result.text return result @@ -217,14 +217,14 @@ def test_plan_state_survives_resume_without_changing_permissions(tmp_path: Path) def test_top_level_plan_result_identifies_the_session_for_wait_continue_and_resume(tmp_path: Path) -> None: first = _Completion("PLAN_READY", blocked=True) with _runtime(tmp_path, [first, _Completion("CONTINUED_PLAN")], initial_permission="workspace-write") as runtime: - execution = runtime.call(runtime.harness.run, "/plan Design this change without tools.") - assert isinstance(execution, RunCommandResult) - assert execution.result.kind == "success" + running = runtime.workers.submit(runtime.harness.run, "/plan Design this change without tools.") assert first.entered.wait(_WAIT_SECONDS), runtime.model.failures - assert not first.release.is_set() - session = runtime.harness.start_session(execution.session_id) + assert not running.done() first.release.set() - _wait_activity(runtime, session) + execution = running.result(timeout=_WAIT_SECONDS) + assert isinstance(execution, RunResult) + assert execution.finish_reason == "completed" and execution.final_response == "PLAN_READY" + session = runtime.harness.start_session(execution.session_id) continued = runtime.call(runtime.harness.run, "Continue this plan without tools.", session_id=execution.session_id) assert isinstance(continued, RunResult) assert continued.session_id == execution.session_id diff --git a/python/sdk/tests/test_run.py b/python/sdk/tests/test_run.py index 7a0dee7c39..8fdd639186 100644 --- a/python/sdk/tests/test_run.py +++ b/python/sdk/tests/test_run.py @@ -10,7 +10,7 @@ from concurrent.futures import ThreadPoolExecutor import pytest from pydantic import BaseModel, ValidationError -from deepseek_harness import CommandExecution, RunCommandResult, DeepSeekHarness, Notification, RunResult, SdkProtocolError +from deepseek_harness import CommandExecution, DeepSeekHarness, Notification, RunResult, SdkProtocolError from deepseek_harness.errors import JsonRpcError @@ -28,6 +28,7 @@ import sys serial = 0 pending_commands = [] pending_prompts = [] +pending_plans = [] def send(frame): print(json.dumps({"jsonrpc": "2.0", **frame}), flush=True) @@ -43,6 +44,8 @@ def command(frame, number): identity = "command-" + str(number) event(session, "command/run", {"commandId": identity}) event(session, "command/done", {"commandId": identity, "kind": "success"}) + send({"method": "session.query.completed", "params": {"sessionId": session, "commandId": identity, + "finalResponse": "command completed", "finishReason": "completed"}}) send({"id": frame["id"], "result": {"kind": "command", "execution": { "commandId": identity, "result": {"kind": "success", "text": "command completed"}}}}) @@ -71,17 +74,33 @@ for line in sys.stdin: assert set(params) == {"sessionId", "contentBlocks", "delivery"} assert params["delivery"] in ("queue", "steer") text = input_text(frame) - if text == "hold-command": + if text == "/plan hold": + identity = "plan-" + str(serial) + event(params["sessionId"], "command/run", {"commandId": identity}) + event(params["sessionId"], "command/done", {"commandId": identity, "kind": "success"}) + send({"id": frame["id"], "result": {"kind": "command", "execution": { + "commandId": identity, "result": {"kind": "success", "text": "Plan enabled"}}}}) + pending_plans.append((frame, identity)) + elif text == "hold-command": pending_commands.append((frame, serial)) elif text in ("/compact", "/plan Describe this image."): command(frame, serial) elif text == "silent-command": + send({"method": "session.query.completed", "params": {"sessionId": params["sessionId"], + "commandId": "silent", "finalResponse": "", "finishReason": "completed"}}) send({"id": frame["id"], "result": {"kind": "command", "execution": { "commandId": "silent", "result": {"kind": "success"}}}}) elif text == "rpc-error": send({"id": frame["id"], "error": {"code": -32602, "message": "query rejected"}}) elif text == "custom-response": - send({"id": frame["id"], "result": json.loads(os.environ["QUERY_RESPONSE"])}) + response = json.loads(os.environ["QUERY_RESPONSE"]) + execution = response.get("execution") if isinstance(response, dict) else None + if isinstance(execution, dict) and isinstance(execution.get("result"), dict): + send({"method": "session.query.completed", "params": {"sessionId": params["sessionId"], + "commandId": execution.get("commandId"), "finalResponse": execution["result"].get("text", ""), + "finishReason": "error" if execution["result"].get("kind") == "error" else "completed", + **json.loads(os.environ.get("QUERY_COMPLETION", "{}"))}}) + send({"id": frame["id"], "result": response}) elif text == "bad-route": send({"id": frame["id"], "result": {"kind": "unknown"}}) elif text == "bad-execution": @@ -100,6 +119,11 @@ for line in sys.stdin: else: finish(frame) elif method == "release": + for original, identity in pending_plans: + finish(original) + send({"method": "session.query.completed", "params": {"sessionId": original["params"]["sessionId"], + "commandId": identity, "finalResponse": "Generated plan", "finishReason": "completed"}}) + pending_plans.clear() for original, number in pending_commands: command(original, number) pending_commands.clear() @@ -145,11 +169,11 @@ def test_run_returns_command_without_waiting_for_idle(sdk: DeepSeekHarness, entr notifications = [] result = (sdk.run("/compact", session_id="main", on_notification=notifications.append) if entry == "harness" else sdk.start_session("main").run("/compact", on_notification=notifications.append)) - assert isinstance(result, CommandExecution) - assert isinstance(result, RunCommandResult) + assert isinstance(result, RunResult) + assert isinstance(result, RunResult) assert result.session_id == "main" - assert result.result.kind == "success" - assert [notice.payload["event"]["type"] for notice in notifications] == ["command/run", "command/done"] + assert result.finish_reason == "completed" + assert [notice.payload["event"]["type"] for notice in notifications if notice.method == "session.event"] == ["command/run", "command/done"] assert_released(sdk) @@ -158,7 +182,7 @@ def test_top_level_command_results_identify_distinct_sessions_and_allow_continui ) -> None: first = sdk.run("/compact") second = sdk.run("/compact") - assert isinstance(first, RunCommandResult) and isinstance(second, RunCommandResult) + assert isinstance(first, RunResult) and isinstance(second, RunResult) assert first.session_id and second.session_id and first.session_id != second.session_id continued = sdk.run("continue the first session", session_id=first.session_id) assert isinstance(continued, RunResult) @@ -185,11 +209,10 @@ def test_run_adds_session_identity_without_changing_command_results(peer: Path, })}, ) as sdk: returned = sdk.run("custom-response") - assert isinstance(returned, RunCommandResult) + assert isinstance(returned, RunResult) assert returned.session_id - assert returned.model_dump(by_alias=True, exclude_none=True) == { - **execution, "session_id": returned.session_id, - } + assert returned.final_response == result.get("text", "") + assert returned.finish_reason == ("error" if result["kind"] == "error" else "completed") low_level = sdk.client._query(returned.session_id, "custom-response", "queue") assert isinstance(low_level, CommandExecution) assert low_level.model_dump(by_alias=True, exclude_none=True) == execution @@ -236,8 +259,8 @@ def test_run_forwards_content_blocks_with_the_routed_result_and_notifications( ) ) if text == "/plan Describe this image.": - assert isinstance(result, CommandExecution) - assert [notice.payload["event"]["type"] for notice in notifications] == ["command/run", "command/done"] + assert isinstance(result, RunResult) + assert [notice.payload["event"]["type"] for notice in notifications if notice.method == "session.event"] == ["command/run", "command/done"] else: assert isinstance(result, RunResult) assert result.final_response == "answer for " + text @@ -267,7 +290,7 @@ def test_concurrent_runs_keep_their_own_results(sdk: DeepSeekHarness) -> None: try: assert entered.wait(5), "the first run must observe its receipt" second = workers.submit(session.run, "/compact") - assert isinstance(second.result(timeout=5), CommandExecution) + assert isinstance(second.result(timeout=5), RunResult) finally: release(sdk) result = first.result(timeout=5) @@ -279,7 +302,7 @@ def test_concurrent_runs_keep_their_own_results(sdk: DeepSeekHarness) -> None: def test_command_result_needs_no_notifications(sdk: DeepSeekHarness) -> None: notices = [] result = sdk.start_session("main").run("silent-command", on_notification=notices.append) - assert isinstance(result, CommandExecution) + assert isinstance(result, RunResult) assert notices == [] assert_released(sdk) @@ -290,7 +313,7 @@ def test_run_reports_routing_failures_without_retry(sdk: DeepSeekHarness, text: with pytest.raises(error): session.run(text) assert_released(sdk) - assert isinstance(session.run("/compact"), CommandExecution) + assert isinstance(session.run("/compact"), RunResult) @pytest.mark.parametrize("text", ["ordinary", "/compact"]) @@ -310,7 +333,7 @@ def test_command_timeout_keeps_runtime_responsive(sdk: DeepSeekHarness) -> None: sdk.client.config.request_timeout_seconds = 5 assert_released(sdk) release(sdk) - assert isinstance(sdk.start_session("main").run("/compact"), CommandExecution) + assert isinstance(sdk.start_session("main").run("/compact"), RunResult) def test_run_requires_supported_delivery(sdk: DeepSeekHarness) -> None: @@ -338,4 +361,40 @@ def test_run_rejects_invalid_routing_responses_as_protocol_errors(peer: Path, tm if isinstance(response, dict) and response.get("kind") == "command": assert isinstance(raised.value.__cause__, ValidationError) assert_released(sdk) - assert isinstance(sdk.start_session("main").run("/compact"), CommandExecution) + assert isinstance(sdk.start_session("main").run("/compact"), RunResult) + + +def test_plan_run_waits_for_model_output_after_the_command_receipt(sdk: DeepSeekHarness) -> None: + admitted = threading.Event() + session = sdk.start_session("plan") + def observe(notice: Notification) -> None: + if notice.method == "session.event" and notice.payload["event"]["type"] == "command/done": + admitted.set() + with ThreadPoolExecutor(max_workers=1) as workers: + running = workers.submit(session.run, "/plan hold", on_notification=observe) + try: + assert admitted.wait(5) + assert not running.done() + finally: + release(sdk) + result = running.result(timeout=5) + assert isinstance(result, RunResult) + assert result.final_response == "Generated plan" and result.finish_reason == "completed" + assert_released(sdk) + + +@pytest.mark.parametrize("completion", [{"commandId": None}, {"finalResponse": 1}, {"finishReason": None}, {"finishReason": ""}]) +def test_run_rejects_malformed_completion_and_releases_its_subscription( + peer: Path, tmp_path: Path, completion: dict, +) -> None: + with DeepSeekHarness( + cwd=str(tmp_path), dsh_home=str(tmp_path / "home"), + _launch_args=(sys.executable, str(peer)), + env={"REQUEST_LOG": str(tmp_path / "requests.jsonl"), + "QUERY_COMPLETION": json.dumps(completion), + "QUERY_RESPONSE": json.dumps({"kind": "command", "execution": { + "commandId": "c", "result": {"kind": "success"}}})}, + ) as sdk: + with pytest.raises(SdkProtocolError): + sdk.run("custom-response") + assert_released(sdk) diff --git a/snapshots/sdk/sdk.snapshot.ts b/snapshots/sdk/sdk.snapshot.ts index 47a85ea141..0375936af9 100644 --- a/snapshots/sdk/sdk.snapshot.ts +++ b/snapshots/sdk/sdk.snapshot.ts @@ -57,7 +57,6 @@ import { } from '@deepseek-ai/dsh-session-snapshot' import { DeepSeekHarness, - type CommandExecution, type HarnessNotification, type NotificationSubscription, type RunResult, @@ -656,22 +655,38 @@ async function waitForRootEvent( function collectCommandNotifications( subscription: NotificationSubscription, sessionId: string, - execution: CommandExecution, + result: RunResult, notifications: HarnessNotification[], observe: (notification: HarnessNotification) => void, ): void { + const run = result.events.find(event => event.type === 'command/run') + if (run === undefined) throw new Error('Command RunResult has no command/run event') + const commandId = run.data.commandId + const done = result.events.find(event => event.type === 'command/done' && event.data.commandId === commandId) + if (done === undefined || done.type !== 'command/done') throw new Error('Command RunResult has no command/done event') + expect(result.finishReason).not.toBeNull() + if (done.data.kind === 'error') { + expect(result.finishReason).toBe('error') + expect(result.finalResponse).toBe(done.data.text) + } else { + const assistant = result.events.findLast(event => event.type === 'assistant/message') + if (assistant !== undefined) { + expect(result.finalResponse).toBe(assistant.data.message.content + .flatMap(block => block.type === 'text' ? [block.text] : []).join('')) + } + } let started = false for (let notification = subscription.tryNext(); notification !== undefined; notification = subscription.tryNext()) { observe(notification) const event = notification.params.sessionId === sessionId ? notificationEvent(notification) : undefined const data = event?.data as JsonObject | undefined - if (event?.type === 'command/run' && data?.commandId === execution.commandId) started = true + if (event?.type === 'command/run' && data?.commandId === commandId) started = true if (!started) continue notifications.push(notification) - if (event?.type !== 'command/done' || data?.commandId !== execution.commandId) continue - expect(execution.result.kind).toBe(data.kind) - expect(execution.result.text).toBe(data.text) - if (execution.result.kind === 'success') expect(execution.result.sourceEventSeq).toBe(data.sourceEventSeq) + if (event?.type !== 'command/done' || data?.commandId !== commandId) continue + expect(done.data.kind).toBe(data.kind) + expect(done.data.text).toBe(data.text) + expect(done.data.sourceEventSeq).toBe(data.sourceEventSeq) return } throw new Error('SDK command response arrived without its preceding command lifecycle notifications') @@ -883,8 +898,21 @@ async function runScenario(scenario: CorpusScenario): Promise<{ })) ?? [], { type: 'text', text: action.line }, ] : action.line) - if (!('commandId' in execution)) throw new Error('SDK command input returned prompt activity') expect(execution.sessionId).toBe(sessionId) + if (scenario.name === 'plan-review' && action === actions.find(item => item.kind === 'command')) { + expect(execution).toMatchObject({ finalResponse: 'SDK_PLAN_APPROVED', finishReason: 'completed' }) + expect(execution.events.filter(event => event.type === 'turn/end')) + .toMatchObject([{ data: { turn: 2, reason: { kind: 'completed' } } }]) + } + if (scenario.name === 'goal-rounds') { + expect(execution).toMatchObject({ finalResponse: 'SDK_GOAL_DONE', finishReason: 'completed' }) + expect(execution.events.filter(event => event.type === 'goal/change').map(event => event.data.operation)) + .toEqual(['create', 'complete']) + expect(execution.events.filter(event => event.type === 'turn/end')).toMatchObject([ + { data: { turn: 2, reason: { kind: 'completed' } } }, + { data: { turn: 3, reason: { kind: 'completed' } } }, + ]) + } collectCommandNotifications(subscription, sessionId, execution, notifications, observe) continue } @@ -923,7 +951,6 @@ async function runScenario(scenario: CorpusScenario): Promise<{ observe(message) }, }) - if ('commandId' in outcome) throw new Error('SDK prompt input returned a command result') result = outcome } else { const outcome = await session.run(materializeInput(action.content, scenario, cwd, liveSessions), { @@ -932,7 +959,6 @@ async function runScenario(scenario: CorpusScenario): Promise<{ observe(notification) }, }) - if ('commandId' in outcome) throw new Error('SDK prompt input returned a command result') result = outcome } results.push(result)