refactor(ptc): move mode-change coordination into sandbox policy

This commit is contained in:
creatixchu committed 2026-10-08 16:43:00 +08:00
1 parent 614f16560f
commit 6885d662d2
69 files changed
+1038 -769

No files matched your search

@@ -9,11 +9,11 @@
en: 544adc32acc3f7d5
zh: 349562c3c637a5e6
/agent-note-retained-ptc-processes-follow-file-policy/decision:
en: 955de37d0e90a613
zh: 779983f7bbe165c7
en: 05f30bfaa620403c
zh: e8310aed0783169a
/agent-note-retained-ptc-processes-follow-file-policy/alternatives-considered:
en: a0b74a4d13652612
zh: 4efa845c1e3a3cc1
en: f4e534e9a0587a7b
zh: a4474cbfdf42f304
/agent-note-retained-ptc-processes-follow-file-policy/consequences:
en: 430304fd91f5d6f0
zh: 10380e3fa12a7e22
@@ -12,9 +12,9 @@ Retaining JavaScript variables does not require broader file access. A process t
`persistent-in-memory` starts its Node process through the same sandbox provider as `per-call`. A retained owner uses one resolved mode, workspace root and Session identity until release. The [memory decision](2026-09-23-best-effort-persistent-ptc.md) owns retained values, failure recovery and package composition; this note owns file authority.
The PTC consumer tracks retained and temporary owners under the Agent lifecycle. Permission preset changes run through an awaited waterfall before writing any permission events. PTC closes admission, cancels admitted calls, awaits environment release, and delegates the permission commit while admission remains closed. Cleanup failure prevents the permission change. Direct sandbox-event appends reject while retained environments remain; callers use the asynchronous permission preset setter to perform cleanup.
The file-policy service owns mode transitions. PTC reserves each Session execution before approval or directory resolution; Node registers each process for cleanup under the resolved policy's Session identity. `sandboxPolicy.setMode()` closes admission, cancels reservations and awaits registered resources before recording the new mode. Cleanup failure prevents the change. Direct sandbox-event appends reject while resources or operations are registered. Permission presets call the same setter as direct mode callers. The tools package keeps Agent ownership and omits the owner for temporary escalations; it does not depend on permission presets.
An approved one-time escalation receives a separate temporary owner. Its process is released before the call returns. It cannot access standing variables, and its declarations do not survive. The standing environment keeps its original policy and variables. Nested tools continue to apply their own permissions and approvals.
An approved one-time escalation omits the state owner and receives a fresh temporary environment. Its process is released before the call returns. It cannot access standing variables, and its declarations do not survive. The standing environment keeps its original policy and variables. Nested tools continue to apply their own permissions and approvals.
## Alternatives considered
@@ -22,7 +22,9 @@ An approved one-time escalation receives a separate temporary owner. Its process
**Changing the running process policy.** Existing backends apply restrictions at launch. Arbitrary retained objects, open handles and background work cannot be transferred into another policy with the existing interface. Releasing the environment gives the permission change a definite completion point.
**Keeping an elevated environment.** A one-time approval cannot authorize future programs or idle background work. A separate temporary owner makes the approval lifetime explicit while preserving the standing environment.
**Coordinating through permission presets.** File-policy changes also have direct callers. The file-policy owner provides one cleanup operation for both paths and keeps user-facing preset selection out of the tool registry.
**Keeping an elevated environment.** A one-time approval cannot authorize future programs or idle background work. Omitting the state owner makes the approval lifetime explicit while preserving the standing environment.
## Consequences
@@ -12,9 +12,9 @@ Status: implemented
`persistent-in-memory` 与 `per-call` 通过同一个沙箱提供方启动 Node 进程。保留状态的所有者在释放前使用固定的已解析权限模式、工作区根目录和 Session 身份。[内存决策](2026-09-23-best-effort-persistent-ptc.zh.md)负责保留值、失败恢复和包组成;本文负责文件权限。
PTC 消费者在 Agent 生命周期下跟踪保留与临时所有者。权限预设切换在写入任何权限事件前执行可等待的 waterfall。PTC 阻止新调用、取消已接纳的调用、等待环境释放,再在保持阻止新调用的状态下委托权限提交。清理失败会阻止权限切换。仍有保留环境时,直接追加沙箱事件会被拒绝;调用方通过异步权限预设 setter 完成清理。
文件策略服务负责模式切换。PTC 在审批或目录解析前登记 Session 执行;Node 按已解析策略中的 Session 身份登记每个进程的清理操作。`sandboxPolicy.setMode()` 阻止新调用、取消已登记调用,并在登记资源清理完成后记录新模式。清理失败会阻止切换。仍有登记资源或操作时,直接追加沙箱事件会被拒绝。权限预设和直接选择模式的调用方使用同一个 setter。工具包保留 Agent 所有权,并在临时提权时省略所有者;它不依赖权限预设。
单次获准的提权使用独立临时所有者。该次调用返回前释放进程,无法访问原环境的变量,也不会保留新声明。原环境保持原权限和变量。嵌套工具继续应用各自的权限和审批规则。
单次获准的提权省略状态所有者,使用全新的临时环境。该次调用返回前释放进程,无法访问原环境的变量,也不会保留新声明。原环境保持原权限和变量。嵌套工具继续应用各自的权限和审批规则。
## 考虑过的替代方案
@@ -22,7 +22,9 @@ PTC 消费者在 Agent 生命周期下跟踪保留与临时所有者。权限预
**修改运行中进程的策略。** 现有后端在启动时应用限制。现有接口无法把任意保留对象、打开的句柄和后台工作转移到另一策略。释放环境让权限切换具有确定的完成时点。
**保留提权环境。** 单次审批不能授权未来程序或空闲期间的后台工作。独立临时所有者明确了审批生效的范围,同时保留原环境。
**通过权限预设协调清理。** 文件策略也有直接调用方。文件策略所有者为两类调用方提供同一个清理操作,工具注册表不需要了解面向用户的预设选择。
**保留提权环境。** 单次审批不能授权未来程序或空闲期间的后台工作。省略状态所有者明确了审批生效的范围,同时保留原环境。
## 影响
+1 -2
View File
@@ -55,7 +55,6 @@ This matrix shows which packages dispatch each harness-owned event and which pac
| `hmr/reload` | `emit` | [`packages/boot/hmr/src/index.ts:37`](../packages/boot/hmr/src/index.ts) | [`hmr`](../packages/boot/hmr) (`emit`) | - |
| `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/types.ts:23`](../packages/llm/llm/src/types.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | [`acp`](../packages/acp/acp), `remotes` |
| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:75`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`llm-replay`](../packages/test-support/llm-replay), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-title`](../packages/session/session-title) |
| `permission-presets/apply` | `waterfall` | [`packages/interaction/permission-presets/src/index.ts:53`](../packages/interaction/permission-presets/src/index.ts) | [`permission-presets`](../packages/interaction/permission-presets) (`waterfall`) | [`tools`](../packages/core/tools) |
| `permission-presets/catalog-changed` | `emit` | [`packages/interaction/permission-presets/src/types.ts:48`](../packages/interaction/permission-presets/src/types.ts) | [`permission-presets`](../packages/interaction/permission-presets) (`events.dispatch`) | `remotes` |
| `plugin-manager/changed` | `emit` | [`packages/boot/plugin-manager/src/types.ts:264`](../packages/boot/plugin-manager/src/types.ts) | [`plugin-manager`](../packages/boot/plugin-manager) (`emit`) | `remotes` |
| `plugin-manager/install-log` | `emit` | [`packages/boot/plugin-manager/src/types.ts:270`](../packages/boot/plugin-manager/src/types.ts) | [`plugin-manager`](../packages/boot/plugin-manager) (`emit`) | `remotes` |
@@ -98,7 +97,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
| Event string | Dispatchers | Listeners |
| --- | --- | --- |
| `internal/config` | [`config-editor`](../packages/boot/config-editor) (`waterfall`) | [`llm-pi-ai`](../packages/llm/llm-pi-ai) |
| `internal/dispatch` | - | [`terminal-bash`](../packages/terminal/terminal-bash), [`tools`](../packages/core/tools) |
| `internal/dispatch` | - | [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`terminal-bash`](../packages/terminal/terminal-bash) |
| `internal/plugin` | - | `computer-use-cua-driver-native`, `inspector`, `loader`, [`lsp-stdio`](../packages/lsp/lsp-stdio), [`mcp-client`](../packages/mcp/mcp-client), `modules` |
| `internal/service` | - | `gateway` |
| `internal/status` | - | [`agent`](../packages/core/agent), `inspector`, `translator`, [`web`](../packages/web/web) |
+1 -2
View File
@@ -57,7 +57,6 @@
| `hmr/reload` | `emit` | [`packages/boot/hmr/src/index.ts:37`](../packages/boot/hmr/src/index.ts) | [`hmr`](../packages/boot/hmr) (`emit`) | - |
| `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/types.ts:23`](../packages/llm/llm/src/types.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | [`acp`](../packages/acp/acp), `remotes` |
| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:75`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`llm-replay`](../packages/test-support/llm-replay), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-title`](../packages/session/session-title) |
| `permission-presets/apply` | `waterfall` | [`packages/interaction/permission-presets/src/index.ts:53`](../packages/interaction/permission-presets/src/index.ts) | [`permission-presets`](../packages/interaction/permission-presets) (`waterfall`) | [`tools`](../packages/core/tools) |
| `permission-presets/catalog-changed` | `emit` | [`packages/interaction/permission-presets/src/types.ts:48`](../packages/interaction/permission-presets/src/types.ts) | [`permission-presets`](../packages/interaction/permission-presets) (`events.dispatch`) | `remotes` |
| `plugin-manager/changed` | `emit` | [`packages/boot/plugin-manager/src/types.ts:264`](../packages/boot/plugin-manager/src/types.ts) | [`plugin-manager`](../packages/boot/plugin-manager) (`emit`) | `remotes` |
| `plugin-manager/install-log` | `emit` | [`packages/boot/plugin-manager/src/types.ts:270`](../packages/boot/plugin-manager/src/types.ts) | [`plugin-manager`](../packages/boot/plugin-manager) (`emit`) | `remotes` |
@@ -100,7 +99,7 @@
| Event string | Dispatchers | Listeners |
| --- | --- | --- |
| `internal/config` | [`config-editor`](../packages/boot/config-editor) (`waterfall`) | [`llm-pi-ai`](../packages/llm/llm-pi-ai) |
| `internal/dispatch` | - | [`terminal-bash`](../packages/terminal/terminal-bash), [`tools`](../packages/core/tools) |
| `internal/dispatch` | - | [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`terminal-bash`](../packages/terminal/terminal-bash) |
| `internal/plugin` | - | `computer-use-cua-driver-native`, `inspector`, `loader`, [`lsp-stdio`](../packages/lsp/lsp-stdio), [`mcp-client`](../packages/mcp/mcp-client), `modules` |
| `internal/service` | - | `gateway` |
| `internal/status` | - | [`agent`](../packages/core/agent), `inspector`, `translator`, [`web`](../packages/web/web) |
+116 -117
View File
@@ -701,6 +701,16 @@ flowchart TD
pkg_llm_deepseek_account --> pkg_launch_environment
pkg_llm_deepseek_account --> pkg_llm
pkg_llm_deepseek_account --> pkg_llm_deepseek
pkg_tools --> pkg_agent
pkg_tools --> pkg_llm
pkg_tools --> pkg_ptc_runtime
pkg_tools --> pkg_sandbox
pkg_tools --> pkg_sandbox_policy
pkg_tools --> pkg_scope
pkg_tools --> pkg_session
pkg_tools --> pkg_system_prompt
pkg_tools --> pkg_user_approval
pkg_tools --> pkg_working_directory
pkg_command_goal --> pkg_commands
pkg_command_goal --> pkg_goal
pkg_command_goal --> pkg_llm
@@ -783,57 +793,6 @@ flowchart TD
pkg_terminal_bash --> pkg_subprocess
pkg_terminal_bash --> pkg_terminal
pkg_terminal_bash --> pkg_working_directory
pkg_tools --> pkg_agent
pkg_tools --> pkg_llm
pkg_tools --> pkg_permission_presets
pkg_tools --> pkg_ptc_runtime
pkg_tools --> pkg_sandbox
pkg_tools --> pkg_sandbox_policy
pkg_tools --> pkg_scope
pkg_tools --> pkg_session
pkg_tools --> pkg_system_prompt
pkg_tools --> pkg_user_approval
pkg_tools --> pkg_working_directory
pkg_command_compact --> pkg_commands
pkg_command_compact --> pkg_compaction
pkg_compaction_image_offload --> pkg_agent
pkg_compaction_image_offload --> pkg_compaction
pkg_compaction_image_offload --> pkg_llm
pkg_compaction_image_offload --> pkg_session
pkg_session_title_all_prompts_llm --> pkg_llm
pkg_session_title_all_prompts_llm --> pkg_session
pkg_session_title_all_prompts_llm --> pkg_session_title
pkg_session_title_all_prompts_llm --> pkg_session_title_llm
pkg_message_feedback --> pkg_brand
pkg_message_feedback --> pkg_command_feedback
pkg_message_feedback --> pkg_llm
pkg_message_feedback --> pkg_session
pkg_message_feedback --> pkg_session_persistence
pkg_message_feedback --> pkg_typert_protocol
pkg_session_title_first_prompt_llm --> pkg_llm
pkg_session_title_first_prompt_llm --> pkg_session
pkg_session_title_first_prompt_llm --> pkg_session_title
pkg_session_title_first_prompt_llm --> pkg_session_title_llm
pkg_ssh --> pkg_brand
pkg_ssh --> pkg_fs
pkg_ssh --> pkg_fs_local
pkg_ssh --> pkg_fs_sandbox
pkg_ssh --> pkg_sandbox
pkg_ssh --> pkg_sandbox_local
pkg_ssh --> pkg_sandbox_policy
pkg_ssh --> pkg_session_projection
pkg_ssh --> pkg_subprocess
pkg_ssh --> pkg_subprocess_local
pkg_llm_replay --> pkg_compaction
pkg_llm_replay --> pkg_deepseek_llm_api_extensions
pkg_llm_replay --> pkg_llm
pkg_llm_replay --> pkg_session
pkg_token_meter --> pkg_compaction
pkg_token_meter --> pkg_compaction_image_offload
pkg_token_meter --> pkg_llm
pkg_token_meter --> pkg_llm_retry
pkg_token_meter --> pkg_session
pkg_token_meter --> pkg_session_projection
pkg_agent_loop --> pkg_agent
pkg_agent_loop --> pkg_llm
pkg_agent_loop --> pkg_scope
@@ -896,6 +855,12 @@ flowchart TD
pkg_plan_mode --> pkg_system_prompt
pkg_plan_mode --> pkg_tools
pkg_plan_mode --> pkg_user_questions
pkg_command_compact --> pkg_commands
pkg_command_compact --> pkg_compaction
pkg_compaction_image_offload --> pkg_agent
pkg_compaction_image_offload --> pkg_compaction
pkg_compaction_image_offload --> pkg_llm
pkg_compaction_image_offload --> pkg_session
pkg_agent_instructions --> pkg_agent
pkg_agent_instructions --> pkg_fs
pkg_agent_instructions --> pkg_home_paths
@@ -947,6 +912,10 @@ flowchart TD
pkg_hooks_codex --> pkg_session_projection
pkg_hooks_codex --> pkg_tools
pkg_hooks_codex --> pkg_working_directory
pkg_session_title_all_prompts_llm --> pkg_llm
pkg_session_title_all_prompts_llm --> pkg_session
pkg_session_title_all_prompts_llm --> pkg_session_title
pkg_session_title_all_prompts_llm --> pkg_session_title_llm
pkg_tool_terminal --> pkg_agent
pkg_tool_terminal --> pkg_jobs
pkg_tool_terminal --> pkg_llm
@@ -962,6 +931,12 @@ flowchart TD
pkg_cordis_host_runner --> pkg_session
pkg_cordis_host_runner --> pkg_tools
pkg_cordis_host_runner --> pkg_typert_protocol
pkg_message_feedback --> pkg_brand
pkg_message_feedback --> pkg_command_feedback
pkg_message_feedback --> pkg_llm
pkg_message_feedback --> pkg_session
pkg_message_feedback --> pkg_session_persistence
pkg_message_feedback --> pkg_typert_protocol
pkg_repeat_tool_reminder --> pkg_agent
pkg_repeat_tool_reminder --> pkg_tools
pkg_tool_call_timeout_policy --> pkg_llm
@@ -999,13 +974,10 @@ flowchart TD
pkg_session_checkpoint_policy --> pkg_session
pkg_session_checkpoint_policy --> pkg_session_persistence
pkg_session_checkpoint_policy --> pkg_tools
pkg_session_telemetry_otel --> pkg_anonymous_user_id
pkg_session_telemetry_otel --> pkg_command_feedback
pkg_session_telemetry_otel --> pkg_llm
pkg_session_telemetry_otel --> pkg_message_feedback
pkg_session_telemetry_otel --> pkg_otel
pkg_session_telemetry_otel --> pkg_session
pkg_session_telemetry_otel --> pkg_session_telemetry
pkg_session_title_first_prompt_llm --> pkg_llm
pkg_session_title_first_prompt_llm --> pkg_session
pkg_session_title_first_prompt_llm --> pkg_session_title
pkg_session_title_first_prompt_llm --> pkg_session_title_llm
pkg_tool_working_directory --> pkg_tools
pkg_tool_working_directory --> pkg_working_directory
pkg_shell_env --> pkg_app_boot
@@ -1024,15 +996,20 @@ flowchart TD
pkg_tool_pwsh_persistent --> pkg_timeout
pkg_tool_pwsh_persistent --> pkg_tools
pkg_tool_pwsh_persistent --> pkg_working_directory
pkg_fs_ssh --> pkg_fs
pkg_fs_ssh --> pkg_sandbox
pkg_fs_ssh --> pkg_sandbox_policy
pkg_fs_ssh --> pkg_ssh
pkg_sandbox_ssh --> pkg_sandbox
pkg_sandbox_ssh --> pkg_ssh
pkg_subprocess_ssh --> pkg_ssh
pkg_subprocess_ssh --> pkg_subprocess
pkg_subprocess_ssh --> pkg_subprocess_local
pkg_ssh --> pkg_brand
pkg_ssh --> pkg_fs
pkg_ssh --> pkg_fs_local
pkg_ssh --> pkg_fs_sandbox
pkg_ssh --> pkg_sandbox
pkg_ssh --> pkg_sandbox_local
pkg_ssh --> pkg_sandbox_policy
pkg_ssh --> pkg_session_projection
pkg_ssh --> pkg_subprocess
pkg_ssh --> pkg_subprocess_local
pkg_llm_replay --> pkg_compaction
pkg_llm_replay --> pkg_deepseek_llm_api_extensions
pkg_llm_replay --> pkg_llm
pkg_llm_replay --> pkg_session
pkg_tool_workflow --> pkg_agent
pkg_tool_workflow --> pkg_jobs
pkg_tool_workflow --> pkg_llm
@@ -1044,14 +1021,12 @@ flowchart TD
pkg_plugin_package_inventory_deepseek --> pkg_agent_preset_registry
pkg_plugin_package_inventory_deepseek --> pkg_deepseek_llm_api_extensions
pkg_plugin_package_inventory_deepseek --> pkg_session
pkg_spill_policy --> pkg_attachment
pkg_spill_policy --> pkg_fs
pkg_spill_policy --> pkg_llm
pkg_spill_policy --> pkg_output_retention
pkg_spill_policy --> pkg_session
pkg_spill_policy --> pkg_spill
pkg_spill_policy --> pkg_token_meter
pkg_spill_policy --> pkg_tools
pkg_token_meter --> pkg_compaction
pkg_token_meter --> pkg_compaction_image_offload
pkg_token_meter --> pkg_llm
pkg_token_meter --> pkg_llm_retry
pkg_token_meter --> pkg_session
pkg_token_meter --> pkg_session_projection
pkg_session_query --> pkg_brand
pkg_session_query --> pkg_llm
pkg_session_query --> pkg_session
@@ -1068,10 +1043,6 @@ flowchart TD
pkg_api_settings_controller --> pkg_typert_protocol
pkg_web_app --> pkg_shell_env
pkg_web_app --> pkg_system_prompt
pkg_compaction_tool_result_pruner --> pkg_compaction
pkg_compaction_tool_result_pruner --> pkg_llm
pkg_compaction_tool_result_pruner --> pkg_session
pkg_compaction_tool_result_pruner --> pkg_token_meter
pkg_experimental_auto_review --> pkg_agent
pkg_experimental_auto_review --> pkg_agent_instructions
pkg_experimental_auto_review --> pkg_llm
@@ -1079,20 +1050,6 @@ flowchart TD
pkg_experimental_auto_review --> pkg_session
pkg_experimental_auto_review --> pkg_tools
pkg_experimental_auto_review --> pkg_working_directory
pkg_experimental_claude_code_mods --> pkg_agent
pkg_experimental_claude_code_mods --> pkg_commands
pkg_experimental_claude_code_mods --> pkg_fs
pkg_experimental_claude_code_mods --> pkg_llm
pkg_experimental_claude_code_mods --> pkg_scope
pkg_experimental_claude_code_mods --> pkg_session
pkg_experimental_claude_code_mods --> pkg_session_projection
pkg_experimental_claude_code_mods --> pkg_storage_domain
pkg_experimental_claude_code_mods --> pkg_subprocess
pkg_experimental_claude_code_mods --> pkg_token_meter
pkg_experimental_claude_code_mods --> pkg_tools
pkg_experimental_claude_code_mods --> pkg_typert_protocol
pkg_experimental_claude_code_mods --> pkg_user_questions
pkg_experimental_claude_code_mods --> pkg_working_directory
pkg_webhook --> pkg_agent
pkg_webhook --> pkg_agent_default_model
pkg_webhook --> pkg_agent_preset_registry
@@ -1117,6 +1074,13 @@ flowchart TD
pkg_mcp_client --> pkg_timeout
pkg_mcp_client --> pkg_tools
pkg_agent_preset --> pkg_agent_preset_registry
pkg_session_telemetry_otel --> pkg_anonymous_user_id
pkg_session_telemetry_otel --> pkg_command_feedback
pkg_session_telemetry_otel --> pkg_llm
pkg_session_telemetry_otel --> pkg_message_feedback
pkg_session_telemetry_otel --> pkg_otel
pkg_session_telemetry_otel --> pkg_session
pkg_session_telemetry_otel --> pkg_session_telemetry
pkg_tool_bash --> pkg_agent
pkg_tool_bash --> pkg_jobs
pkg_tool_bash --> pkg_llm
@@ -1139,6 +1103,15 @@ flowchart TD
pkg_tool_pwsh --> pkg_tools
pkg_tool_pwsh --> pkg_user_approval
pkg_tool_pwsh --> pkg_working_directory
pkg_fs_ssh --> pkg_fs
pkg_fs_ssh --> pkg_sandbox
pkg_fs_ssh --> pkg_sandbox_policy
pkg_fs_ssh --> pkg_ssh
pkg_sandbox_ssh --> pkg_sandbox
pkg_sandbox_ssh --> pkg_ssh
pkg_subprocess_ssh --> pkg_ssh
pkg_subprocess_ssh --> pkg_subprocess
pkg_subprocess_ssh --> pkg_subprocess_local
pkg_agent_loop_testkit --> pkg_agent
pkg_agent_loop_testkit --> pkg_agent_loop
pkg_agent_loop_testkit --> pkg_fs_local
@@ -1167,6 +1140,14 @@ flowchart TD
pkg_subagent --> pkg_util_time
pkg_subagent --> pkg_working_directory
pkg_subagent --> pkg_workspace
pkg_spill_policy --> pkg_attachment
pkg_spill_policy --> pkg_fs
pkg_spill_policy --> pkg_llm
pkg_spill_policy --> pkg_output_retention
pkg_spill_policy --> pkg_session
pkg_spill_policy --> pkg_spill
pkg_spill_policy --> pkg_token_meter
pkg_spill_policy --> pkg_tools
pkg_session_query_sqlite --> pkg_session
pkg_session_query_sqlite --> pkg_session_persistence
pkg_session_query_sqlite --> pkg_session_query
@@ -1188,13 +1169,10 @@ flowchart TD
pkg_plugin_manager --> pkg_tools
pkg_plugin_manager --> pkg_typert_protocol
pkg_plugin_manager --> pkg_user_approval
pkg_compaction_basic --> pkg_agent
pkg_compaction_basic --> pkg_commands
pkg_compaction_basic --> pkg_compaction
pkg_compaction_basic --> pkg_compaction_tool_result_pruner
pkg_compaction_basic --> pkg_llm
pkg_compaction_basic --> pkg_session
pkg_compaction_basic --> pkg_token_meter
pkg_compaction_tool_result_pruner --> pkg_compaction
pkg_compaction_tool_result_pruner --> pkg_llm
pkg_compaction_tool_result_pruner --> pkg_session
pkg_compaction_tool_result_pruner --> pkg_token_meter
pkg_experimental_browser_use_runtime --> pkg_agent
pkg_experimental_browser_use_runtime --> pkg_browser_use
pkg_experimental_browser_use_runtime --> pkg_mcp_client
@@ -1202,6 +1180,20 @@ flowchart TD
pkg_experimental_browser_use_runtime --> pkg_system_prompt
pkg_experimental_browser_use_runtime --> pkg_tools
pkg_experimental_browser_use_runtime --> pkg_working_directory
pkg_experimental_claude_code_mods --> pkg_agent
pkg_experimental_claude_code_mods --> pkg_commands
pkg_experimental_claude_code_mods --> pkg_fs
pkg_experimental_claude_code_mods --> pkg_llm
pkg_experimental_claude_code_mods --> pkg_scope
pkg_experimental_claude_code_mods --> pkg_session
pkg_experimental_claude_code_mods --> pkg_session_projection
pkg_experimental_claude_code_mods --> pkg_storage_domain
pkg_experimental_claude_code_mods --> pkg_subprocess
pkg_experimental_claude_code_mods --> pkg_token_meter
pkg_experimental_claude_code_mods --> pkg_tools
pkg_experimental_claude_code_mods --> pkg_typert_protocol
pkg_experimental_claude_code_mods --> pkg_user_questions
pkg_experimental_claude_code_mods --> pkg_working_directory
pkg_tool_session_query --> pkg_agent
pkg_tool_session_query --> pkg_llm
pkg_tool_session_query --> pkg_session
@@ -1283,6 +1275,13 @@ flowchart TD
pkg_headless --> pkg_session
pkg_headless --> pkg_session_query
pkg_headless --> pkg_subagent
pkg_compaction_basic --> pkg_agent
pkg_compaction_basic --> pkg_commands
pkg_compaction_basic --> pkg_compaction
pkg_compaction_basic --> pkg_compaction_tool_result_pruner
pkg_compaction_basic --> pkg_llm
pkg_compaction_basic --> pkg_session
pkg_compaction_basic --> pkg_token_meter
pkg_session_reference --> pkg_agent
pkg_session_reference --> pkg_compaction
pkg_session_reference --> pkg_llm
@@ -1647,6 +1646,7 @@ flowchart TD
| [`loader-smoke`](../packages/test-support/loader-smoke) | `test-support` | [`agent`](../packages/core/agent), [`http-proxy`](../packages/util/http-proxy), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
| [`workflow`](../packages/workflow/workflow) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
| [`llm-deepseek-account`](../packages/llm/llm-deepseek-account) | `llm` | [`deepseek-account`](../packages/credentials/deepseek-account), [`launch-environment`](../packages/util/launch-environment), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek) |
| [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`ptc-runtime`](../packages/ptc-runtime/ptc-runtime), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`user-approval`](../packages/interaction/user-approval), [`working-directory`](../packages/session/working-directory) |
| [`command-goal`](../packages/goal/command-goal) | `goal` | [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`llm`](../packages/llm/llm) |
| [`goal-round-driver`](../packages/goal/goal-round-driver) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
| [`fs-sandbox`](../packages/fs/fs-sandbox) | `fs` | [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
@@ -1664,15 +1664,6 @@ flowchart TD
| [`bash-sandbox`](../packages/shell/bash-sandbox) | `shell` | [`bash-local`](../packages/shell/bash-local), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell) |
| [`pwsh-sandbox`](../packages/shell/pwsh-sandbox) | `shell` | [`pwsh-local`](../packages/shell/pwsh-local), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell) |
| [`terminal-bash`](../packages/terminal/terminal-bash) | `terminal` | [`agent`](../packages/core/agent), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`subprocess`](../packages/subprocess/subprocess), [`terminal`](../packages/terminal/terminal), [`working-directory`](../packages/session/working-directory) |
| [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`ptc-runtime`](../packages/ptc-runtime/ptc-runtime), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`user-approval`](../packages/interaction/user-approval), [`working-directory`](../packages/session/working-directory) |
| [`command-compact`](../packages/compaction/command-compact) | `compaction` | [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction) |
| [`compaction-image-offload`](../packages/compaction/compaction-image-offload) | `compaction` | [`agent`](../packages/core/agent), [`compaction`](../packages/compaction/compaction), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
| [`session-title-all-prompts-llm`](../packages/experimental/session-title-all-prompts-llm) | `experimental` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`session-title-llm`](../packages/session/session-title-llm) |
| [`message-feedback`](../packages/feedback/message-feedback) | `feedback` | [`brand`](../packages/util/brand), [`command-feedback`](../packages/feedback/command-feedback), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`typert-protocol`](../packages/typert/protocol) |
| [`session-title-first-prompt-llm`](../packages/session/session-title-first-prompt-llm) | `session` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`session-title-llm`](../packages/session/session-title-llm) |
| [`ssh`](../packages/ssh/ssh) | `ssh` | [`brand`](../packages/util/brand), [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`fs-sandbox`](../packages/fs/fs-sandbox), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-local`](../packages/sandbox/sandbox-local), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session-projection`](../packages/session/session-projection), [`subprocess`](../packages/subprocess/subprocess), [`subprocess-local`](../packages/subprocess/subprocess-local) |
| [`llm-replay`](../packages/test-support/llm-replay) | `test-support` | [`compaction`](../packages/compaction/compaction), [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
| [`token-meter`](../packages/llm/token-meter) | `llm` | [`compaction`](../packages/compaction/compaction), [`compaction-image-offload`](../packages/compaction/compaction-image-offload), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
| [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
| [`agent-tool-presentation`](../packages/core/agent-tool-presentation) | `core` | [`tools`](../packages/core/tools) |
| [`tool-goal`](../packages/goal/tool-goal) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
@@ -1684,6 +1675,8 @@ flowchart TD
| [`tool-web`](../packages/web/tool-web) | `web` | [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) |
| [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) |
| [`plan-mode`](../packages/plan/plan-mode) | `plan` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-questions`](../packages/interaction/user-questions) |
| [`command-compact`](../packages/compaction/command-compact) | `compaction` | [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction) |
| [`compaction-image-offload`](../packages/compaction/compaction-image-offload) | `compaction` | [`agent`](../packages/core/agent), [`compaction`](../packages/compaction/compaction), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
| [`agent-instructions`](../packages/context/agent-instructions) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`home-paths`](../packages/util/home-paths), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
| [`file-reference-local`](../packages/context/file-reference-local) | `context` | [`agent`](../packages/core/agent), [`file-reference`](../packages/context/file-reference), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
| [`tool-present`](../packages/deliverables/tool-present) | `deliverables` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
@@ -1694,8 +1687,10 @@ flowchart TD
| [`experimental-computer-use-cua-driver-native`](../packages/experimental/computer-use-cua-driver-native) | `experimental` | [`computer-use`](../packages/computer-use/computer-use), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
| [`experimental-tool-worktree`](../packages/experimental/tool-worktree) | `experimental` | [`experimental-worktree`](../packages/experimental/worktree), [`tools`](../packages/core/tools) |
| [`hooks-codex`](../packages/experimental/hooks-codex) | `experimental` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/experimental/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
| [`session-title-all-prompts-llm`](../packages/experimental/session-title-all-prompts-llm) | `experimental` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`session-title-llm`](../packages/session/session-title-llm) |
| [`tool-terminal`](../packages/experimental/tool-terminal) | `experimental` | [`agent`](../packages/core/agent), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`system-prompt`](../packages/core/system-prompt), [`terminal`](../packages/terminal/terminal), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
| [`cordis-host-runner`](../packages/extensions/cordis-host-runner) | `extensions` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol) |
| [`message-feedback`](../packages/feedback/message-feedback) | `feedback` | [`brand`](../packages/util/brand), [`command-feedback`](../packages/feedback/command-feedback), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`typert-protocol`](../packages/typert/protocol) |
| [`repeat-tool-reminder`](../packages/guard/repeat-tool-reminder) | `guard` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools) |
| [`tool-call-timeout-policy`](../packages/guard/timeout-policy) | `guard` | [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
| [`tool-ask-user`](../packages/interaction/tool-ask-user) | `interaction` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools), [`user-questions`](../packages/interaction/user-questions) |
@@ -1704,37 +1699,40 @@ flowchart TD
| [`mcp-resources`](../packages/mcp/mcp-resources) | `mcp` | [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
| [`agent-preset-registry`](../packages/preset/agent-preset-registry) | `preset` | [`agent`](../packages/core/agent), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol) |
| [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy) | `session` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`tools`](../packages/core/tools) |
| [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | `session` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`command-feedback`](../packages/feedback/command-feedback), [`llm`](../packages/llm/llm), [`message-feedback`](../packages/feedback/message-feedback), [`otel`](../packages/telemetry/otel), [`session`](../packages/core/session), [`session-telemetry`](../packages/session/session-telemetry) |
| [`session-title-first-prompt-llm`](../packages/session/session-title-first-prompt-llm) | `session` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`session-title-llm`](../packages/session/session-title-llm) |
| [`tool-working-directory`](../packages/session/tool-working-directory) | `session` | [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
| [`shell-env`](../packages/shell/shell-env) | `shell` | [`app-boot`](../packages/boot/app-boot), [`home-paths`](../packages/util/home-paths), [`shell`](../packages/shell/shell), [`tools`](../packages/core/tools) |
| [`tool-bash-persistent`](../packages/shell/tool-bash-persistent) | `shell` | [`agent`](../packages/core/agent), [`output-retention`](../packages/util/output-retention), [`terminal`](../packages/terminal/terminal), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
| [`tool-pwsh-persistent`](../packages/shell/tool-pwsh-persistent) | `shell` | [`agent`](../packages/core/agent), [`output-retention`](../packages/util/output-retention), [`terminal`](../packages/terminal/terminal), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
| [`fs-ssh`](../packages/ssh/fs-ssh) | `ssh` | [`fs`](../packages/fs/fs), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`ssh`](../packages/ssh/ssh) |
| [`sandbox-ssh`](../packages/ssh/sandbox-ssh) | `ssh` | [`sandbox`](../packages/sandbox/sandbox), [`ssh`](../packages/ssh/ssh) |
| [`subprocess-ssh`](../packages/ssh/subprocess-ssh) | `ssh` | [`ssh`](../packages/ssh/ssh), [`subprocess`](../packages/subprocess/subprocess), [`subprocess-local`](../packages/subprocess/subprocess-local) |
| [`ssh`](../packages/ssh/ssh) | `ssh` | [`brand`](../packages/util/brand), [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`fs-sandbox`](../packages/fs/fs-sandbox), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-local`](../packages/sandbox/sandbox-local), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session-projection`](../packages/session/session-projection), [`subprocess`](../packages/subprocess/subprocess), [`subprocess-local`](../packages/subprocess/subprocess-local) |
| [`llm-replay`](../packages/test-support/llm-replay) | `test-support` | [`compaction`](../packages/compaction/compaction), [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
| [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
| [`plugin-package-inventory-deepseek`](../packages/llm/plugin-package-inventory-deepseek) | `llm` | [`agent`](../packages/core/agent), [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions), [`session`](../packages/core/session) |
| [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`attachment`](../packages/attachment/attachment), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools) |
| [`token-meter`](../packages/llm/token-meter) | `llm` | [`compaction`](../packages/compaction/compaction), [`compaction-image-offload`](../packages/compaction/compaction-image-offload), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
| [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-title`](../packages/session/session-title), [`tool-todo`](../packages/todo/tool-todo) |
| [`api-settings-controller`](../packages/api/settings-controller) | `api` | [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`credentials`](../packages/credentials/credentials), [`native-command`](../packages/util/native-command), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`typert-protocol`](../packages/typert/protocol) |
| [`web-app`](../packages/bundle/web-app) | `bundle` | [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt) |
| [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner) | `compaction` | [`compaction`](../packages/compaction/compaction), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
| [`experimental-auto-review`](../packages/experimental/auto-review) | `experimental` | [`agent`](../packages/core/agent), [`agent-instructions`](../packages/context/agent-instructions), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`session`](../packages/core/session), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
| [`experimental-claude-code-mods`](../packages/experimental/claude-code-mods) | `experimental` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`storage-domain`](../packages/storage/storage-domain), [`subprocess`](../packages/subprocess/subprocess), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`user-questions`](../packages/interaction/user-questions), [`working-directory`](../packages/session/working-directory) |
| [`webhook`](../packages/experimental/webhook) | `experimental` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`workspace`](../packages/workspace/workspace) |
| [`tool-cordis`](../packages/extensions/tool-cordis) | `extensions` | [`agent`](../packages/core/agent), [`app-boot`](../packages/boot/app-boot), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`tools`](../packages/core/tools) |
| [`host-plugin-inventory`](../packages/host/plugin-inventory) | `host` | [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`brand`](../packages/util/brand), [`typert-protocol`](../packages/typert/protocol) |
| [`mcp-client`](../packages/mcp/mcp-client) | `mcp` | [`attachment`](../packages/attachment/attachment), [`llm`](../packages/llm/llm), [`mcp-resources`](../packages/mcp/mcp-resources), [`scope`](../packages/core/scope), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
| [`agent-preset`](../packages/preset/agent-preset) | `preset` | [`agent-preset-registry`](../packages/preset/agent-preset-registry) |
| [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | `session` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`command-feedback`](../packages/feedback/command-feedback), [`llm`](../packages/llm/llm), [`message-feedback`](../packages/feedback/message-feedback), [`otel`](../packages/telemetry/otel), [`session`](../packages/core/session), [`session-telemetry`](../packages/session/session-telemetry) |
| [`tool-bash`](../packages/shell/tool-bash) | `shell` | [`agent`](../packages/core/agent), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval), [`working-directory`](../packages/session/working-directory) |
| [`tool-pwsh`](../packages/shell/tool-pwsh) | `shell` | [`agent`](../packages/core/agent), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval), [`working-directory`](../packages/session/working-directory) |
| [`fs-ssh`](../packages/ssh/fs-ssh) | `ssh` | [`fs`](../packages/fs/fs), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`ssh`](../packages/ssh/ssh) |
| [`sandbox-ssh`](../packages/ssh/sandbox-ssh) | `ssh` | [`sandbox`](../packages/sandbox/sandbox), [`ssh`](../packages/ssh/ssh) |
| [`subprocess-ssh`](../packages/ssh/subprocess-ssh) | `ssh` | [`ssh`](../packages/ssh/ssh), [`subprocess`](../packages/subprocess/subprocess), [`subprocess-local`](../packages/subprocess/subprocess-local) |
| [`agent-loop-testkit`](../packages/test-support/agent-loop-testkit) | `test-support` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`fs-local`](../packages/fs/fs-local), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
| [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`attachment`](../packages/attachment/attachment), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`user-approval`](../packages/interaction/user-approval), [`util-time`](../packages/util/time), [`working-directory`](../packages/session/working-directory), [`workspace`](../packages/workspace/workspace) |
| [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`attachment`](../packages/attachment/attachment), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools) |
| [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | `session-query` | [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-query`](../packages/session-query/session-query) |
| [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`llm`](../packages/llm/llm), [`mcp-client`](../packages/mcp/mcp-client), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`token-meter`](../packages/llm/token-meter), [`user-approval`](../packages/interaction/user-approval) |
| [`plugin-manager`](../packages/boot/plugin-manager) | `boot` | [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`brand`](../packages/util/brand), [`hmr`](../packages/boot/hmr), [`host-plugin-inventory`](../packages/host/plugin-inventory), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`subprocess`](../packages/subprocess/subprocess), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`user-approval`](../packages/interaction/user-approval) |
| [`compaction-basic`](../packages/compaction/compaction-basic) | `compaction` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
| [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner) | `compaction` | [`compaction`](../packages/compaction/compaction), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
| [`experimental-browser-use-runtime`](../packages/experimental/browser-use-runtime) | `experimental` | [`agent`](../packages/core/agent), [`browser-use`](../packages/browser-use/browser-use), [`mcp-client`](../packages/mcp/mcp-client), [`scope`](../packages/core/scope), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
| [`experimental-claude-code-mods`](../packages/experimental/claude-code-mods) | `experimental` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`storage-domain`](../packages/storage/storage-domain), [`subprocess`](../packages/subprocess/subprocess), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`user-questions`](../packages/interaction/user-questions), [`working-directory`](../packages/session/working-directory) |
| [`tool-session-query`](../packages/experimental/tool-session-query) | `experimental` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
| [`webhook-github`](../packages/experimental/webhook-github) | `experimental` | [`credentials`](../packages/credentials/credentials), [`host-webserver`](../packages/host/webserver), [`session`](../packages/core/session), [`webhook`](../packages/experimental/webhook) |
| [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
@@ -1746,6 +1744,7 @@ flowchart TD
| [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | `subagent` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
| [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-file-upload`](../packages/client/file-upload), [`commands`](../packages/interaction/commands), [`credentials`](../packages/credentials/credentials), [`file-reference`](../packages/context/file-reference), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`native-command`](../packages/util/native-command), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`settings`](../packages/settings/settings), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-values`](../packages/util/values), [`util-workspace-path`](../packages/util/workspace-path), [`working-directory`](../packages/session/working-directory), [`workspace`](../packages/workspace/workspace) |
| [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query), [`subagent`](../packages/subagent/subagent) |
| [`compaction-basic`](../packages/compaction/compaction-basic) | `compaction` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
| [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compaction`](../packages/compaction/compaction), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`spill`](../packages/spill/spill), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`typert-protocol`](../packages/typert/protocol) |
| [`experimental-agent-team`](../packages/experimental/agent-team) | `experimental` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent) |
| [`hooks-claude-code`](../packages/experimental/hooks-claude-code) | `experimental` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/experimental/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
+116 -117
View File
@@ -703,6 +703,16 @@ flowchart TD
pkg_llm_deepseek_account --> pkg_launch_environment
pkg_llm_deepseek_account --> pkg_llm
pkg_llm_deepseek_account --> pkg_llm_deepseek
pkg_tools --> pkg_agent
pkg_tools --> pkg_llm
pkg_tools --> pkg_ptc_runtime
pkg_tools --> pkg_sandbox
pkg_tools --> pkg_sandbox_policy
pkg_tools --> pkg_scope
pkg_tools --> pkg_session
pkg_tools --> pkg_system_prompt
pkg_tools --> pkg_user_approval
pkg_tools --> pkg_working_directory
pkg_command_goal --> pkg_commands
pkg_command_goal --> pkg_goal
pkg_command_goal --> pkg_llm
@@ -785,57 +795,6 @@ flowchart TD
pkg_terminal_bash --> pkg_subprocess
pkg_terminal_bash --> pkg_terminal
pkg_terminal_bash --> pkg_working_directory
pkg_tools --> pkg_agent
pkg_tools --> pkg_llm
pkg_tools --> pkg_permission_presets
pkg_tools --> pkg_ptc_runtime
pkg_tools --> pkg_sandbox
pkg_tools --> pkg_sandbox_policy
pkg_tools --> pkg_scope
pkg_tools --> pkg_session
pkg_tools --> pkg_system_prompt
pkg_tools --> pkg_user_approval
pkg_tools --> pkg_working_directory
pkg_command_compact --> pkg_commands
pkg_command_compact --> pkg_compaction
pkg_compaction_image_offload --> pkg_agent
pkg_compaction_image_offload --> pkg_compaction
pkg_compaction_image_offload --> pkg_llm
pkg_compaction_image_offload --> pkg_session
pkg_session_title_all_prompts_llm --> pkg_llm
pkg_session_title_all_prompts_llm --> pkg_session
pkg_session_title_all_prompts_llm --> pkg_session_title
pkg_session_title_all_prompts_llm --> pkg_session_title_llm
pkg_message_feedback --> pkg_brand
pkg_message_feedback --> pkg_command_feedback
pkg_message_feedback --> pkg_llm
pkg_message_feedback --> pkg_session
pkg_message_feedback --> pkg_session_persistence
pkg_message_feedback --> pkg_typert_protocol
pkg_session_title_first_prompt_llm --> pkg_llm
pkg_session_title_first_prompt_llm --> pkg_session
pkg_session_title_first_prompt_llm --> pkg_session_title
pkg_session_title_first_prompt_llm --> pkg_session_title_llm
pkg_ssh --> pkg_brand
pkg_ssh --> pkg_fs
pkg_ssh --> pkg_fs_local
pkg_ssh --> pkg_fs_sandbox
pkg_ssh --> pkg_sandbox
pkg_ssh --> pkg_sandbox_local
pkg_ssh --> pkg_sandbox_policy
pkg_ssh --> pkg_session_projection
pkg_ssh --> pkg_subprocess
pkg_ssh --> pkg_subprocess_local
pkg_llm_replay --> pkg_compaction
pkg_llm_replay --> pkg_deepseek_llm_api_extensions
pkg_llm_replay --> pkg_llm
pkg_llm_replay --> pkg_session
pkg_token_meter --> pkg_compaction
pkg_token_meter --> pkg_compaction_image_offload
pkg_token_meter --> pkg_llm
pkg_token_meter --> pkg_llm_retry
pkg_token_meter --> pkg_session
pkg_token_meter --> pkg_session_projection
pkg_agent_loop --> pkg_agent
pkg_agent_loop --> pkg_llm
pkg_agent_loop --> pkg_scope
@@ -898,6 +857,12 @@ flowchart TD
pkg_plan_mode --> pkg_system_prompt
pkg_plan_mode --> pkg_tools
pkg_plan_mode --> pkg_user_questions
pkg_command_compact --> pkg_commands
pkg_command_compact --> pkg_compaction
pkg_compaction_image_offload --> pkg_agent
pkg_compaction_image_offload --> pkg_compaction
pkg_compaction_image_offload --> pkg_llm
pkg_compaction_image_offload --> pkg_session
pkg_agent_instructions --> pkg_agent
pkg_agent_instructions --> pkg_fs
pkg_agent_instructions --> pkg_home_paths
@@ -949,6 +914,10 @@ flowchart TD
pkg_hooks_codex --> pkg_session_projection
pkg_hooks_codex --> pkg_tools
pkg_hooks_codex --> pkg_working_directory
pkg_session_title_all_prompts_llm --> pkg_llm
pkg_session_title_all_prompts_llm --> pkg_session
pkg_session_title_all_prompts_llm --> pkg_session_title
pkg_session_title_all_prompts_llm --> pkg_session_title_llm
pkg_tool_terminal --> pkg_agent
pkg_tool_terminal --> pkg_jobs
pkg_tool_terminal --> pkg_llm
@@ -964,6 +933,12 @@ flowchart TD
pkg_cordis_host_runner --> pkg_session
pkg_cordis_host_runner --> pkg_tools
pkg_cordis_host_runner --> pkg_typert_protocol
pkg_message_feedback --> pkg_brand
pkg_message_feedback --> pkg_command_feedback
pkg_message_feedback --> pkg_llm
pkg_message_feedback --> pkg_session
pkg_message_feedback --> pkg_session_persistence
pkg_message_feedback --> pkg_typert_protocol
pkg_repeat_tool_reminder --> pkg_agent
pkg_repeat_tool_reminder --> pkg_tools
pkg_tool_call_timeout_policy --> pkg_llm
@@ -1001,13 +976,10 @@ flowchart TD
pkg_session_checkpoint_policy --> pkg_session
pkg_session_checkpoint_policy --> pkg_session_persistence
pkg_session_checkpoint_policy --> pkg_tools
pkg_session_telemetry_otel --> pkg_anonymous_user_id
pkg_session_telemetry_otel --> pkg_command_feedback
pkg_session_telemetry_otel --> pkg_llm
pkg_session_telemetry_otel --> pkg_message_feedback
pkg_session_telemetry_otel --> pkg_otel
pkg_session_telemetry_otel --> pkg_session
pkg_session_telemetry_otel --> pkg_session_telemetry
pkg_session_title_first_prompt_llm --> pkg_llm
pkg_session_title_first_prompt_llm --> pkg_session
pkg_session_title_first_prompt_llm --> pkg_session_title
pkg_session_title_first_prompt_llm --> pkg_session_title_llm
pkg_tool_working_directory --> pkg_tools
pkg_tool_working_directory --> pkg_working_directory
pkg_shell_env --> pkg_app_boot
@@ -1026,15 +998,20 @@ flowchart TD
pkg_tool_pwsh_persistent --> pkg_timeout
pkg_tool_pwsh_persistent --> pkg_tools
pkg_tool_pwsh_persistent --> pkg_working_directory
pkg_fs_ssh --> pkg_fs
pkg_fs_ssh --> pkg_sandbox
pkg_fs_ssh --> pkg_sandbox_policy
pkg_fs_ssh --> pkg_ssh
pkg_sandbox_ssh --> pkg_sandbox
pkg_sandbox_ssh --> pkg_ssh
pkg_subprocess_ssh --> pkg_ssh
pkg_subprocess_ssh --> pkg_subprocess
pkg_subprocess_ssh --> pkg_subprocess_local
pkg_ssh --> pkg_brand
pkg_ssh --> pkg_fs
pkg_ssh --> pkg_fs_local
pkg_ssh --> pkg_fs_sandbox
pkg_ssh --> pkg_sandbox
pkg_ssh --> pkg_sandbox_local
pkg_ssh --> pkg_sandbox_policy
pkg_ssh --> pkg_session_projection
pkg_ssh --> pkg_subprocess
pkg_ssh --> pkg_subprocess_local
pkg_llm_replay --> pkg_compaction
pkg_llm_replay --> pkg_deepseek_llm_api_extensions
pkg_llm_replay --> pkg_llm
pkg_llm_replay --> pkg_session
pkg_tool_workflow --> pkg_agent
pkg_tool_workflow --> pkg_jobs
pkg_tool_workflow --> pkg_llm
@@ -1046,14 +1023,12 @@ flowchart TD
pkg_plugin_package_inventory_deepseek --> pkg_agent_preset_registry
pkg_plugin_package_inventory_deepseek --> pkg_deepseek_llm_api_extensions
pkg_plugin_package_inventory_deepseek --> pkg_session
pkg_spill_policy --> pkg_attachment
pkg_spill_policy --> pkg_fs
pkg_spill_policy --> pkg_llm
pkg_spill_policy --> pkg_output_retention
pkg_spill_policy --> pkg_session
pkg_spill_policy --> pkg_spill
pkg_spill_policy --> pkg_token_meter
pkg_spill_policy --> pkg_tools
pkg_token_meter --> pkg_compaction
pkg_token_meter --> pkg_compaction_image_offload
pkg_token_meter --> pkg_llm
pkg_token_meter --> pkg_llm_retry
pkg_token_meter --> pkg_session
pkg_token_meter --> pkg_session_projection
pkg_session_query --> pkg_brand
pkg_session_query --> pkg_llm
pkg_session_query --> pkg_session
@@ -1070,10 +1045,6 @@ flowchart TD
pkg_api_settings_controller --> pkg_typert_protocol
pkg_web_app --> pkg_shell_env
pkg_web_app --> pkg_system_prompt
pkg_compaction_tool_result_pruner --> pkg_compaction
pkg_compaction_tool_result_pruner --> pkg_llm
pkg_compaction_tool_result_pruner --> pkg_session
pkg_compaction_tool_result_pruner --> pkg_token_meter
pkg_experimental_auto_review --> pkg_agent
pkg_experimental_auto_review --> pkg_agent_instructions
pkg_experimental_auto_review --> pkg_llm
@@ -1081,20 +1052,6 @@ flowchart TD
pkg_experimental_auto_review --> pkg_session
pkg_experimental_auto_review --> pkg_tools
pkg_experimental_auto_review --> pkg_working_directory
pkg_experimental_claude_code_mods --> pkg_agent
pkg_experimental_claude_code_mods --> pkg_commands
pkg_experimental_claude_code_mods --> pkg_fs
pkg_experimental_claude_code_mods --> pkg_llm
pkg_experimental_claude_code_mods --> pkg_scope
pkg_experimental_claude_code_mods --> pkg_session
pkg_experimental_claude_code_mods --> pkg_session_projection
pkg_experimental_claude_code_mods --> pkg_storage_domain
pkg_experimental_claude_code_mods --> pkg_subprocess
pkg_experimental_claude_code_mods --> pkg_token_meter
pkg_experimental_claude_code_mods --> pkg_tools
pkg_experimental_claude_code_mods --> pkg_typert_protocol
pkg_experimental_claude_code_mods --> pkg_user_questions
pkg_experimental_claude_code_mods --> pkg_working_directory
pkg_webhook --> pkg_agent
pkg_webhook --> pkg_agent_default_model
pkg_webhook --> pkg_agent_preset_registry
@@ -1119,6 +1076,13 @@ flowchart TD
pkg_mcp_client --> pkg_timeout
pkg_mcp_client --> pkg_tools
pkg_agent_preset --> pkg_agent_preset_registry
pkg_session_telemetry_otel --> pkg_anonymous_user_id
pkg_session_telemetry_otel --> pkg_command_feedback
pkg_session_telemetry_otel --> pkg_llm
pkg_session_telemetry_otel --> pkg_message_feedback
pkg_session_telemetry_otel --> pkg_otel
pkg_session_telemetry_otel --> pkg_session
pkg_session_telemetry_otel --> pkg_session_telemetry
pkg_tool_bash --> pkg_agent
pkg_tool_bash --> pkg_jobs
pkg_tool_bash --> pkg_llm
@@ -1141,6 +1105,15 @@ flowchart TD
pkg_tool_pwsh --> pkg_tools
pkg_tool_pwsh --> pkg_user_approval
pkg_tool_pwsh --> pkg_working_directory
pkg_fs_ssh --> pkg_fs
pkg_fs_ssh --> pkg_sandbox
pkg_fs_ssh --> pkg_sandbox_policy
pkg_fs_ssh --> pkg_ssh
pkg_sandbox_ssh --> pkg_sandbox
pkg_sandbox_ssh --> pkg_ssh
pkg_subprocess_ssh --> pkg_ssh
pkg_subprocess_ssh --> pkg_subprocess
pkg_subprocess_ssh --> pkg_subprocess_local
pkg_agent_loop_testkit --> pkg_agent
pkg_agent_loop_testkit --> pkg_agent_loop
pkg_agent_loop_testkit --> pkg_fs_local
@@ -1169,6 +1142,14 @@ flowchart TD
pkg_subagent --> pkg_util_time
pkg_subagent --> pkg_working_directory
pkg_subagent --> pkg_workspace
pkg_spill_policy --> pkg_attachment
pkg_spill_policy --> pkg_fs
pkg_spill_policy --> pkg_llm
pkg_spill_policy --> pkg_output_retention
pkg_spill_policy --> pkg_session
pkg_spill_policy --> pkg_spill
pkg_spill_policy --> pkg_token_meter
pkg_spill_policy --> pkg_tools
pkg_session_query_sqlite --> pkg_session
pkg_session_query_sqlite --> pkg_session_persistence
pkg_session_query_sqlite --> pkg_session_query
@@ -1190,13 +1171,10 @@ flowchart TD
pkg_plugin_manager --> pkg_tools
pkg_plugin_manager --> pkg_typert_protocol
pkg_plugin_manager --> pkg_user_approval
pkg_compaction_basic --> pkg_agent
pkg_compaction_basic --> pkg_commands
pkg_compaction_basic --> pkg_compaction
pkg_compaction_basic --> pkg_compaction_tool_result_pruner
pkg_compaction_basic --> pkg_llm
pkg_compaction_basic --> pkg_session
pkg_compaction_basic --> pkg_token_meter
pkg_compaction_tool_result_pruner --> pkg_compaction
pkg_compaction_tool_result_pruner --> pkg_llm
pkg_compaction_tool_result_pruner --> pkg_session
pkg_compaction_tool_result_pruner --> pkg_token_meter
pkg_experimental_browser_use_runtime --> pkg_agent
pkg_experimental_browser_use_runtime --> pkg_browser_use
pkg_experimental_browser_use_runtime --> pkg_mcp_client
@@ -1204,6 +1182,20 @@ flowchart TD
pkg_experimental_browser_use_runtime --> pkg_system_prompt
pkg_experimental_browser_use_runtime --> pkg_tools
pkg_experimental_browser_use_runtime --> pkg_working_directory
pkg_experimental_claude_code_mods --> pkg_agent
pkg_experimental_claude_code_mods --> pkg_commands
pkg_experimental_claude_code_mods --> pkg_fs
pkg_experimental_claude_code_mods --> pkg_llm
pkg_experimental_claude_code_mods --> pkg_scope
pkg_experimental_claude_code_mods --> pkg_session
pkg_experimental_claude_code_mods --> pkg_session_projection
pkg_experimental_claude_code_mods --> pkg_storage_domain
pkg_experimental_claude_code_mods --> pkg_subprocess
pkg_experimental_claude_code_mods --> pkg_token_meter
pkg_experimental_claude_code_mods --> pkg_tools
pkg_experimental_claude_code_mods --> pkg_typert_protocol
pkg_experimental_claude_code_mods --> pkg_user_questions
pkg_experimental_claude_code_mods --> pkg_working_directory
pkg_tool_session_query --> pkg_agent
pkg_tool_session_query --> pkg_llm
pkg_tool_session_query --> pkg_session
@@ -1285,6 +1277,13 @@ flowchart TD
pkg_headless --> pkg_session
pkg_headless --> pkg_session_query
pkg_headless --> pkg_subagent
pkg_compaction_basic --> pkg_agent
pkg_compaction_basic --> pkg_commands
pkg_compaction_basic --> pkg_compaction
pkg_compaction_basic --> pkg_compaction_tool_result_pruner
pkg_compaction_basic --> pkg_llm
pkg_compaction_basic --> pkg_session
pkg_compaction_basic --> pkg_token_meter
pkg_session_reference --> pkg_agent
pkg_session_reference --> pkg_compaction
pkg_session_reference --> pkg_llm
@@ -1649,6 +1648,7 @@ flowchart TD
| [`loader-smoke`](../packages/test-support/loader-smoke) | `test-support` | [`agent`](../packages/core/agent), [`http-proxy`](../packages/util/http-proxy), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
| [`workflow`](../packages/workflow/workflow) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
| [`llm-deepseek-account`](../packages/llm/llm-deepseek-account) | `llm` | [`deepseek-account`](../packages/credentials/deepseek-account), [`launch-environment`](../packages/util/launch-environment), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek) |
| [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`ptc-runtime`](../packages/ptc-runtime/ptc-runtime), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`user-approval`](../packages/interaction/user-approval), [`working-directory`](../packages/session/working-directory) |
| [`command-goal`](../packages/goal/command-goal) | `goal` | [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`llm`](../packages/llm/llm) |
| [`goal-round-driver`](../packages/goal/goal-round-driver) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
| [`fs-sandbox`](../packages/fs/fs-sandbox) | `fs` | [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
@@ -1666,15 +1666,6 @@ flowchart TD
| [`bash-sandbox`](../packages/shell/bash-sandbox) | `shell` | [`bash-local`](../packages/shell/bash-local), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell) |
| [`pwsh-sandbox`](../packages/shell/pwsh-sandbox) | `shell` | [`pwsh-local`](../packages/shell/pwsh-local), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell) |
| [`terminal-bash`](../packages/terminal/terminal-bash) | `terminal` | [`agent`](../packages/core/agent), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`subprocess`](../packages/subprocess/subprocess), [`terminal`](../packages/terminal/terminal), [`working-directory`](../packages/session/working-directory) |
| [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`ptc-runtime`](../packages/ptc-runtime/ptc-runtime), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`user-approval`](../packages/interaction/user-approval), [`working-directory`](../packages/session/working-directory) |
| [`command-compact`](../packages/compaction/command-compact) | `compaction` | [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction) |
| [`compaction-image-offload`](../packages/compaction/compaction-image-offload) | `compaction` | [`agent`](../packages/core/agent), [`compaction`](../packages/compaction/compaction), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
| [`session-title-all-prompts-llm`](../packages/experimental/session-title-all-prompts-llm) | `experimental` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`session-title-llm`](../packages/session/session-title-llm) |
| [`message-feedback`](../packages/feedback/message-feedback) | `feedback` | [`brand`](../packages/util/brand), [`command-feedback`](../packages/feedback/command-feedback), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`typert-protocol`](../packages/typert/protocol) |
| [`session-title-first-prompt-llm`](../packages/session/session-title-first-prompt-llm) | `session` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`session-title-llm`](../packages/session/session-title-llm) |
| [`ssh`](../packages/ssh/ssh) | `ssh` | [`brand`](../packages/util/brand), [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`fs-sandbox`](../packages/fs/fs-sandbox), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-local`](../packages/sandbox/sandbox-local), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session-projection`](../packages/session/session-projection), [`subprocess`](../packages/subprocess/subprocess), [`subprocess-local`](../packages/subprocess/subprocess-local) |
| [`llm-replay`](../packages/test-support/llm-replay) | `test-support` | [`compaction`](../packages/compaction/compaction), [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
| [`token-meter`](../packages/llm/token-meter) | `llm` | [`compaction`](../packages/compaction/compaction), [`compaction-image-offload`](../packages/compaction/compaction-image-offload), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
| [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
| [`agent-tool-presentation`](../packages/core/agent-tool-presentation) | `core` | [`tools`](../packages/core/tools) |
| [`tool-goal`](../packages/goal/tool-goal) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
@@ -1686,6 +1677,8 @@ flowchart TD
| [`tool-web`](../packages/web/tool-web) | `web` | [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) |
| [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) |
| [`plan-mode`](../packages/plan/plan-mode) | `plan` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-questions`](../packages/interaction/user-questions) |
| [`command-compact`](../packages/compaction/command-compact) | `compaction` | [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction) |
| [`compaction-image-offload`](../packages/compaction/compaction-image-offload) | `compaction` | [`agent`](../packages/core/agent), [`compaction`](../packages/compaction/compaction), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
| [`agent-instructions`](../packages/context/agent-instructions) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`home-paths`](../packages/util/home-paths), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
| [`file-reference-local`](../packages/context/file-reference-local) | `context` | [`agent`](../packages/core/agent), [`file-reference`](../packages/context/file-reference), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
| [`tool-present`](../packages/deliverables/tool-present) | `deliverables` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
@@ -1696,8 +1689,10 @@ flowchart TD
| [`experimental-computer-use-cua-driver-native`](../packages/experimental/computer-use-cua-driver-native) | `experimental` | [`computer-use`](../packages/computer-use/computer-use), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
| [`experimental-tool-worktree`](../packages/experimental/tool-worktree) | `experimental` | [`experimental-worktree`](../packages/experimental/worktree), [`tools`](../packages/core/tools) |
| [`hooks-codex`](../packages/experimental/hooks-codex) | `experimental` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/experimental/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
| [`session-title-all-prompts-llm`](../packages/experimental/session-title-all-prompts-llm) | `experimental` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`session-title-llm`](../packages/session/session-title-llm) |
| [`tool-terminal`](../packages/experimental/tool-terminal) | `experimental` | [`agent`](../packages/core/agent), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`system-prompt`](../packages/core/system-prompt), [`terminal`](../packages/terminal/terminal), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
| [`cordis-host-runner`](../packages/extensions/cordis-host-runner) | `extensions` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol) |
| [`message-feedback`](../packages/feedback/message-feedback) | `feedback` | [`brand`](../packages/util/brand), [`command-feedback`](../packages/feedback/command-feedback), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`typert-protocol`](../packages/typert/protocol) |
| [`repeat-tool-reminder`](../packages/guard/repeat-tool-reminder) | `guard` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools) |
| [`tool-call-timeout-policy`](../packages/guard/timeout-policy) | `guard` | [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
| [`tool-ask-user`](../packages/interaction/tool-ask-user) | `interaction` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools), [`user-questions`](../packages/interaction/user-questions) |
@@ -1706,37 +1701,40 @@ flowchart TD
| [`mcp-resources`](../packages/mcp/mcp-resources) | `mcp` | [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
| [`agent-preset-registry`](../packages/preset/agent-preset-registry) | `preset` | [`agent`](../packages/core/agent), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol) |
| [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy) | `session` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`tools`](../packages/core/tools) |
| [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | `session` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`command-feedback`](../packages/feedback/command-feedback), [`llm`](../packages/llm/llm), [`message-feedback`](../packages/feedback/message-feedback), [`otel`](../packages/telemetry/otel), [`session`](../packages/core/session), [`session-telemetry`](../packages/session/session-telemetry) |
| [`session-title-first-prompt-llm`](../packages/session/session-title-first-prompt-llm) | `session` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`session-title-llm`](../packages/session/session-title-llm) |
| [`tool-working-directory`](../packages/session/tool-working-directory) | `session` | [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
| [`shell-env`](../packages/shell/shell-env) | `shell` | [`app-boot`](../packages/boot/app-boot), [`home-paths`](../packages/util/home-paths), [`shell`](../packages/shell/shell), [`tools`](../packages/core/tools) |
| [`tool-bash-persistent`](../packages/shell/tool-bash-persistent) | `shell` | [`agent`](../packages/core/agent), [`output-retention`](../packages/util/output-retention), [`terminal`](../packages/terminal/terminal), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
| [`tool-pwsh-persistent`](../packages/shell/tool-pwsh-persistent) | `shell` | [`agent`](../packages/core/agent), [`output-retention`](../packages/util/output-retention), [`terminal`](../packages/terminal/terminal), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
| [`fs-ssh`](../packages/ssh/fs-ssh) | `ssh` | [`fs`](../packages/fs/fs), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`ssh`](../packages/ssh/ssh) |
| [`sandbox-ssh`](../packages/ssh/sandbox-ssh) | `ssh` | [`sandbox`](../packages/sandbox/sandbox), [`ssh`](../packages/ssh/ssh) |
| [`subprocess-ssh`](../packages/ssh/subprocess-ssh) | `ssh` | [`ssh`](../packages/ssh/ssh), [`subprocess`](../packages/subprocess/subprocess), [`subprocess-local`](../packages/subprocess/subprocess-local) |
| [`ssh`](../packages/ssh/ssh) | `ssh` | [`brand`](../packages/util/brand), [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`fs-sandbox`](../packages/fs/fs-sandbox), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-local`](../packages/sandbox/sandbox-local), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session-projection`](../packages/session/session-projection), [`subprocess`](../packages/subprocess/subprocess), [`subprocess-local`](../packages/subprocess/subprocess-local) |
| [`llm-replay`](../packages/test-support/llm-replay) | `test-support` | [`compaction`](../packages/compaction/compaction), [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
| [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
| [`plugin-package-inventory-deepseek`](../packages/llm/plugin-package-inventory-deepseek) | `llm` | [`agent`](../packages/core/agent), [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions), [`session`](../packages/core/session) |
| [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`attachment`](../packages/attachment/attachment), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools) |
| [`token-meter`](../packages/llm/token-meter) | `llm` | [`compaction`](../packages/compaction/compaction), [`compaction-image-offload`](../packages/compaction/compaction-image-offload), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
| [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-title`](../packages/session/session-title), [`tool-todo`](../packages/todo/tool-todo) |
| [`api-settings-controller`](../packages/api/settings-controller) | `api` | [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`credentials`](../packages/credentials/credentials), [`native-command`](../packages/util/native-command), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`typert-protocol`](../packages/typert/protocol) |
| [`web-app`](../packages/bundle/web-app) | `bundle` | [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt) |
| [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner) | `compaction` | [`compaction`](../packages/compaction/compaction), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
| [`experimental-auto-review`](../packages/experimental/auto-review) | `experimental` | [`agent`](../packages/core/agent), [`agent-instructions`](../packages/context/agent-instructions), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`session`](../packages/core/session), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
| [`experimental-claude-code-mods`](../packages/experimental/claude-code-mods) | `experimental` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`storage-domain`](../packages/storage/storage-domain), [`subprocess`](../packages/subprocess/subprocess), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`user-questions`](../packages/interaction/user-questions), [`working-directory`](../packages/session/working-directory) |
| [`webhook`](../packages/experimental/webhook) | `experimental` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`workspace`](../packages/workspace/workspace) |
| [`tool-cordis`](../packages/extensions/tool-cordis) | `extensions` | [`agent`](../packages/core/agent), [`app-boot`](../packages/boot/app-boot), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`tools`](../packages/core/tools) |
| [`host-plugin-inventory`](../packages/host/plugin-inventory) | `host` | [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`brand`](../packages/util/brand), [`typert-protocol`](../packages/typert/protocol) |
| [`mcp-client`](../packages/mcp/mcp-client) | `mcp` | [`attachment`](../packages/attachment/attachment), [`llm`](../packages/llm/llm), [`mcp-resources`](../packages/mcp/mcp-resources), [`scope`](../packages/core/scope), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
| [`agent-preset`](../packages/preset/agent-preset) | `preset` | [`agent-preset-registry`](../packages/preset/agent-preset-registry) |
| [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | `session` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`command-feedback`](../packages/feedback/command-feedback), [`llm`](../packages/llm/llm), [`message-feedback`](../packages/feedback/message-feedback), [`otel`](../packages/telemetry/otel), [`session`](../packages/core/session), [`session-telemetry`](../packages/session/session-telemetry) |
| [`tool-bash`](../packages/shell/tool-bash) | `shell` | [`agent`](../packages/core/agent), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval), [`working-directory`](../packages/session/working-directory) |
| [`tool-pwsh`](../packages/shell/tool-pwsh) | `shell` | [`agent`](../packages/core/agent), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval), [`working-directory`](../packages/session/working-directory) |
| [`fs-ssh`](../packages/ssh/fs-ssh) | `ssh` | [`fs`](../packages/fs/fs), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`ssh`](../packages/ssh/ssh) |
| [`sandbox-ssh`](../packages/ssh/sandbox-ssh) | `ssh` | [`sandbox`](../packages/sandbox/sandbox), [`ssh`](../packages/ssh/ssh) |
| [`subprocess-ssh`](../packages/ssh/subprocess-ssh) | `ssh` | [`ssh`](../packages/ssh/ssh), [`subprocess`](../packages/subprocess/subprocess), [`subprocess-local`](../packages/subprocess/subprocess-local) |
| [`agent-loop-testkit`](../packages/test-support/agent-loop-testkit) | `test-support` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`fs-local`](../packages/fs/fs-local), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
| [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`attachment`](../packages/attachment/attachment), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`user-approval`](../packages/interaction/user-approval), [`util-time`](../packages/util/time), [`working-directory`](../packages/session/working-directory), [`workspace`](../packages/workspace/workspace) |
| [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`attachment`](../packages/attachment/attachment), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools) |
| [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | `session-query` | [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-query`](../packages/session-query/session-query) |
| [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`llm`](../packages/llm/llm), [`mcp-client`](../packages/mcp/mcp-client), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`token-meter`](../packages/llm/token-meter), [`user-approval`](../packages/interaction/user-approval) |
| [`plugin-manager`](../packages/boot/plugin-manager) | `boot` | [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`brand`](../packages/util/brand), [`hmr`](../packages/boot/hmr), [`host-plugin-inventory`](../packages/host/plugin-inventory), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`subprocess`](../packages/subprocess/subprocess), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`user-approval`](../packages/interaction/user-approval) |
| [`compaction-basic`](../packages/compaction/compaction-basic) | `compaction` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
| [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner) | `compaction` | [`compaction`](../packages/compaction/compaction), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
| [`experimental-browser-use-runtime`](../packages/experimental/browser-use-runtime) | `experimental` | [`agent`](../packages/core/agent), [`browser-use`](../packages/browser-use/browser-use), [`mcp-client`](../packages/mcp/mcp-client), [`scope`](../packages/core/scope), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
| [`experimental-claude-code-mods`](../packages/experimental/claude-code-mods) | `experimental` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`storage-domain`](../packages/storage/storage-domain), [`subprocess`](../packages/subprocess/subprocess), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`user-questions`](../packages/interaction/user-questions), [`working-directory`](../packages/session/working-directory) |
| [`tool-session-query`](../packages/experimental/tool-session-query) | `experimental` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
| [`webhook-github`](../packages/experimental/webhook-github) | `experimental` | [`credentials`](../packages/credentials/credentials), [`host-webserver`](../packages/host/webserver), [`session`](../packages/core/session), [`webhook`](../packages/experimental/webhook) |
| [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
@@ -1748,6 +1746,7 @@ flowchart TD
| [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | `subagent` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
| [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-file-upload`](../packages/client/file-upload), [`commands`](../packages/interaction/commands), [`credentials`](../packages/credentials/credentials), [`file-reference`](../packages/context/file-reference), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`native-command`](../packages/util/native-command), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`settings`](../packages/settings/settings), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-values`](../packages/util/values), [`util-workspace-path`](../packages/util/workspace-path), [`working-directory`](../packages/session/working-directory), [`workspace`](../packages/workspace/workspace) |
| [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query), [`subagent`](../packages/subagent/subagent) |
| [`compaction-basic`](../packages/compaction/compaction-basic) | `compaction` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
| [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compaction`](../packages/compaction/compaction), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`spill`](../packages/spill/spill), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`typert-protocol`](../packages/typert/protocol) |
| [`experimental-agent-team`](../packages/experimental/agent-team) | `experimental` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent) |
| [`hooks-claude-code`](../packages/experimental/hooks-claude-code) | `experimental` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/experimental/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
+10 -10
View File
@@ -138,8 +138,8 @@
en: 19917bc5438e60af
zh: 19917bc5438e60af
/session-persistence-event-catalog/events/permission/permission-preset-log-only:
en: dcefd8dba2719488
zh: d7045e2376878745
en: dcfeed1fa023a4ed
zh: 27b67061de31eec1
/session-persistence-event-catalog/events/plan:
en: 4294f78d26ed985b
zh: 4294f78d26ed985b
@@ -159,8 +159,8 @@
en: ec841ab8439335b0
zh: ec841ab8439335b0
/session-persistence-event-catalog/events/sandbox/sandbox-mode-log-only:
en: a7d4d90d43861111
zh: 2b87b4dcfe438bda
en: 13b953e773cdd090
zh: 49afa88164d7b84b
/session-persistence-event-catalog/events/schedule:
en: e5b55405bd2b69f5
zh: e5b55405bd2b69f5
@@ -1623,8 +1623,8 @@
en: c53129cf7214286c
zh: 8c5183b6dabbf714
/session-persistence-event-catalog/resolved-persistence-types/kind-ptc-mode:
en: 26b3b9239392dcc9
zh: f4c6c0195c9119fc
en: 8de77980e11a0562
zh: 6de199e70a666a71
/session-persistence-event-catalog/resolved-persistence-types/kind-repeat-tool-reminder:
en: e3a0ef98a197374e
zh: 95e9363529a62cc3
@@ -1830,14 +1830,14 @@
en: 22665480d164fdc7
zh: aa2c96be4a4fe468
/session-persistence-event-catalog/resolved-persistence-types/mode-source:
en: 3028b222670ce5ad
zh: cae4c9437e560d61
en: e984ad8b25ed2bb3
zh: 685548f81b2a3439
/session-persistence-event-catalog/resolved-persistence-types/policy-source:
en: 00f1d435f82d2753
zh: c2ab108ad2748a6c
/session-persistence-event-catalog/resolved-persistence-types/preset:
en: 1eedeca4754e579c
zh: 768d7396f4351ac8
en: 84966186304f972f
zh: 8b994edb472b6eea
/session-persistence-event-catalog/resolved-persistence-types/reason-turn:
en: 168c2ac7db7371b4
zh: f851223c95582eb9
+5 -5
View File
@@ -683,7 +683,7 @@ Source: [`packages/api/session-controller/src/types.ts:40`](../packages/api/sess
'permission/preset': { preset: string }
```
Source: [`packages/interaction/permission-presets/src/index.ts:72`](../packages/interaction/permission-presets/src/index.ts)
Source: [`packages/interaction/permission-presets/src/index.ts:60`](../packages/interaction/permission-presets/src/index.ts)
### `plan/*`
@@ -760,7 +760,7 @@ Source: [`packages/core/session/src/types.ts:390`](../packages/core/session/src/
}
```
Source: [`packages/sandbox/sandbox-policy/src/session-mode.ts:33`](../packages/sandbox/sandbox-policy/src/session-mode.ts)
Source: [`packages/sandbox/sandbox-policy/src/session-mode.ts:32`](../packages/sandbox/sandbox-policy/src/session-mode.ts)
### `schedule/*`
@@ -6747,7 +6747,7 @@ Sources: [`packages/session/session-title/src/types.ts:30`](../packages/session/
SHA-256: `dba54c09c6e7aafc9acbed7792ecc920d99f92d0784aeeed10af55f7fe0bc8cd`
Sources: [`packages/core/tools/src/ptc.ts:14`](../packages/core/tools/src/ptc.ts)
Sources: [`packages/core/tools/src/ptc.ts:15`](../packages/core/tools/src/ptc.ts)
| Property | Presence | Type |
|---|---|---|
@@ -7549,7 +7549,7 @@ Sources: [`packages/experimental/agent-team/src/types.ts:238`](../packages/exper
SHA-256: `9890113e97dd3541787bfe6704f2b223d3a890b5325ca0acae2b0398909b413e`
Sources: [`packages/sandbox/sandbox-policy/src/session-mode.ts:33`](../packages/sandbox/sandbox-policy/src/session-mode.ts)
Sources: [`packages/sandbox/sandbox-policy/src/session-mode.ts:32`](../packages/sandbox/sandbox-policy/src/session-mode.ts)
| Property | Presence | Type |
|---|---|---|
@@ -7575,7 +7575,7 @@ Sources: [`packages/interaction/user-approval/src/index.ts:40`](../packages/inte
SHA-256: `8a9c990773f798eac10ca8878e6bcc531ee080bc589cac956730e462cc6a09ad`
Sources: [`packages/interaction/permission-presets/src/index.ts:72`](../packages/interaction/permission-presets/src/index.ts)
Sources: [`packages/interaction/permission-presets/src/index.ts:60`](../packages/interaction/permission-presets/src/index.ts)
| Property | Presence | Type |
|---|---|---|
+5 -5
View File
@@ -685,7 +685,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
'permission/preset': { preset: string }
```
来源:[`packages/interaction/permission-presets/src/index.ts:72`](../packages/interaction/permission-presets/src/index.ts)
来源:[`packages/interaction/permission-presets/src/index.ts:60`](../packages/interaction/permission-presets/src/index.ts)
### `plan/*`
@@ -762,7 +762,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
}
```
来源:[`packages/sandbox/sandbox-policy/src/session-mode.ts:33`](../packages/sandbox/sandbox-policy/src/session-mode.ts)
来源:[`packages/sandbox/sandbox-policy/src/session-mode.ts:32`](../packages/sandbox/sandbox-policy/src/session-mode.ts)
### `schedule/*`
@@ -6749,7 +6749,7 @@ SHA-256: `b81e9de81a481b24e1e1f9adf038bfc59e57b4f35ce62f8f1e45284186f4f812`
SHA-256: `dba54c09c6e7aafc9acbed7792ecc920d99f92d0784aeeed10af55f7fe0bc8cd`
来源:[`packages/core/tools/src/ptc.ts:14`](../packages/core/tools/src/ptc.ts)
来源:[`packages/core/tools/src/ptc.ts:15`](../packages/core/tools/src/ptc.ts)
| 属性 | 存在性 | 类型 |
|---|---|---|
@@ -7551,7 +7551,7 @@ SHA-256: `0bcfaf5566d271028429ac7b562cb59053c9d78b8ae14708c35fac835108d1b1`
SHA-256: `9890113e97dd3541787bfe6704f2b223d3a890b5325ca0acae2b0398909b413e`
来源:[`packages/sandbox/sandbox-policy/src/session-mode.ts:33`](../packages/sandbox/sandbox-policy/src/session-mode.ts)
来源:[`packages/sandbox/sandbox-policy/src/session-mode.ts:32`](../packages/sandbox/sandbox-policy/src/session-mode.ts)
| 属性 | 存在性 | 类型 |
|---|---|---|
@@ -7577,7 +7577,7 @@ SHA-256: `11f70b595aa76897fc4e25a352bfa718c659f44b799e5aa14e84e5a38fe72912`
SHA-256: `8a9c990773f798eac10ca8878e6bcc531ee080bc589cac956730e462cc6a09ad`
来源:[`packages/interaction/permission-presets/src/index.ts:72`](../packages/interaction/permission-presets/src/index.ts)
来源:[`packages/interaction/permission-presets/src/index.ts:60`](../packages/interaction/permission-presets/src/index.ts)
| 属性 | 存在性 | 类型 |
|---|---|---|
+3 -3
View File
@@ -24061,7 +24061,7 @@
"digest": "8a9c990773f798eac10ca8878e6bcc531ee080bc589cac956730e462cc6a09ad",
"names": [],
"sources": [
"packages/interaction/permission-presets/src/index.ts:72"
"packages/interaction/permission-presets/src/index.ts:60"
]
},
{
@@ -24233,7 +24233,7 @@
"digest": "9890113e97dd3541787bfe6704f2b223d3a890b5325ca0acae2b0398909b413e",
"names": [],
"sources": [
"packages/sandbox/sandbox-policy/src/session-mode.ts:33"
"packages/sandbox/sandbox-policy/src/session-mode.ts:32"
]
},
{
@@ -25173,7 +25173,7 @@
"digest": "dba54c09c6e7aafc9acbed7792ecc920d99f92d0784aeeed10af55f7fe0bc8cd",
"names": [],
"sources": [
"packages/core/tools/src/ptc.ts:14"
"packages/core/tools/src/ptc.ts:15"
]
},
{
+2 -2
View File
@@ -15,5 +15,5 @@
en: 43a7b661b747091f
zh: ee6b4f1ddb8cf6f2
/permission-presets/switching-and-the-permission-preset-event:
en: 1a5cf90e95baebd5
zh: 527d7e8c7439c002
en: 41ce3067c67bc3e6
zh: 916765e1e8a28521
+3 -26
View File
@@ -70,7 +70,7 @@ interface PresetOption {
## Switching and the `permission/preset` event
`set(session, name)` resolves the preset (unknown names throw), runs Auto admission when applicable, appends a log-only `permission/preset` event unless `name` is already the effective preset, then writes each knob through its own setter — `setSandboxMode` from [dsh-sandbox-policy](../../packages/sandbox/sandbox-policy) and `setApprovalPolicy` from [dsh-user-approval](../../packages/interaction/user-approval) — only when that knob's effective value changes. The selection event precedes the knob events in the same turn, and re-selecting the effective preset appends nothing. Callers await completion and receive resource-reset notices; the `permission-presets/apply` waterfall releases retained PTC environments before any preset event is committed.
`set(session, name)` validates the preset and Auto admission, awaits [sandbox-policy](../../packages/sandbox/sandbox-policy) to release resources and commit a changed file policy, then records a changed preset identity and approval policy. It returns resource-reset notices. The file-policy owner coordinates cleanup for all callers, including callers that select a sandbox mode directly. Selecting the effective preset again appends nothing.
`permission/preset` is durable, log-only user intent: it stays out of the model transcript (the knob events own the model-visible consequences through their consumers), and it exists so `current()` can preserve which preset the user chose when two presets share a bundle. The `permissions` projection folds that selection with both knob events and retains the `session/end-seed` boundary used to distinguish a restored empty seed from a fresh session; replay needs no catch-up state or raw-log rescan. A restored `auto` selection requires the live Auto registration before Agent publication. The complete event declaration is in the [persistence log event catalog](../persistence-catalog.md); the method signatures are in the generated [service catalog](#ctxpermissionpresets--permissionpresetservice).
@@ -132,8 +132,8 @@ resolve(name: string): PresetSpec
optionOf(name: string): PresetOption
/**
* Record a changed preset, then update each changed knob through its own
* setter. Selecting the effective preset again appends nothing.
* Await file-policy cleanup, then record the changed preset and approval policy.
* Selecting the effective preset again appends nothing.
* @param session - the session the switch belongs to.
* @param name - the preset to switch to; unknown names reject.
* @returns Notices after old execution resources are released and the new preset is recorded.
@@ -149,29 +149,6 @@ Source: [`packages/interaction/permission-presets/src/index.ts`](../../packages/
### `permission-presets/*` events
<a id="permission-presetsapply--waterfall"></a>
#### `permission-presets/apply` — waterfall
Wrap a permission change while resources using the old policy are released. A rejection prevents the preset and its policy events from being recorded.
```ts cordis-catalog
/**
* Wrap a permission change while resources using the old policy are released.
* A rejection prevents the preset and its policy events from being recorded.
* @param next - Commit the validated preset and return change notices.
* @param session - Session receiving the new preset.
* @param sandboxMode - File policy selected by the preset.
* @returns Notices describing resources invalidated by the change.
* @mode waterfall
*/
'permission-presets/apply'(session: Session, sandboxMode: SandboxMode, next: () => Promise<string[]>): Promise<string[]>
```
Types: [SandboxMode](sandbox.md) · [Session](session.md)
Source: [`packages/interaction/permission-presets/src/index.ts`](../../packages/interaction/permission-presets/src/index.ts)
<a id="permission-presetscatalog-changed--emit"></a>
#### `permission-presets/catalog-changed` — emit
+3 -26
View File
@@ -70,7 +70,7 @@ interface PresetOption {
## 切换与 `permission/preset` 事件
`set(session, name)` 解析预设(未知名称抛出异常),在适用时运行 Auto 准入,在 `name` 尚不是生效预设时追加一条仅记日志的 `permission/preset` 事件,然后通过各旋钮自己的 setter([dsh-sandbox-policy](../../packages/sandbox/sandbox-policy) 的 `setSandboxMode` 与 [dsh-user-approval](../../packages/interaction/user-approval) 的 `setApprovalPolicy`)写入,且仅当该 knob 的生效值发生变化时才写。同一轮次内,选择事件先于旋钮事件出现;重新选择当前生效的预设则什么都不追加。 调用方等待完成并接收资源清空提示;`permission-presets/apply` waterfall 在任何预设事件提交前释放保留的 PTC 环境。
`set(session, name)` 验证预设和 Auto 准入,等待 [sandbox-policy](../../packages/sandbox/sandbox-policy) 释放资源并提交变化的文件策略,再记录变化的预设身份和审批策略,并返回资源清空提示。文件策略所有者为所有调用方协调清理,包括直接选择沙箱模式的调用方。重新选择当前生效预设不追加事件。
`permission/preset` 是持久、仅记日志的用户意图:它不进入模型 transcript(文本记录),模型可见的后果由 knob 事件经各自消费方承担;它存在是为了在两个预设共享同一个旋钮组合时,让 `current()` 仍能保住用户选择的究竟是哪一个预设。`permissions` 投影把该选择与两个 knob 事件一同折叠,并保留用于区分空恢复 seed 与新会话的 `session/end-seed` 边界;回放不需要任何追赶状态或原始日志重扫。恢复的 `auto` 选择在 agent 发布前必须存在 live Auto 注册。完整事件声明见[持久化日志事件目录](../persistence-catalog.zh.md);方法签名见生成的[服务目录](#ctxpermissionpresets--permissionpresetservice)。
@@ -132,8 +132,8 @@ resolve(name: string): PresetSpec
optionOf(name: string): PresetOption
/**
* Record a changed preset, then update each changed knob through its own
* setter. Selecting the effective preset again appends nothing.
* Await file-policy cleanup, then record the changed preset and approval policy.
* Selecting the effective preset again appends nothing.
* @param session - the session the switch belongs to.
* @param name - the preset to switch to; unknown names reject.
* @returns Notices after old execution resources are released and the new preset is recorded.
@@ -149,29 +149,6 @@ Source: [`packages/interaction/permission-presets/src/index.ts`](../../packages/
### `permission-presets/*` events
<a id="permission-presetsapply--waterfall"></a>
#### `permission-presets/apply` — waterfall
Wrap a permission change while resources using the old policy are released. A rejection prevents the preset and its policy events from being recorded.
```ts cordis-catalog
/**
* Wrap a permission change while resources using the old policy are released.
* A rejection prevents the preset and its policy events from being recorded.
* @param next - Commit the validated preset and return change notices.
* @param session - Session receiving the new preset.
* @param sandboxMode - File policy selected by the preset.
* @returns Notices describing resources invalidated by the change.
* @mode waterfall
*/
'permission-presets/apply'(session: Session, sandboxMode: SandboxMode, next: () => Promise<string[]>): Promise<string[]>
```
Types: [SandboxMode](sandbox.zh.md) · [Session](session.zh.md)
Source: [`packages/interaction/permission-presets/src/index.ts`](../../packages/interaction/permission-presets/src/index.ts)
<a id="permission-presetscatalog-changed--emit"></a>
#### `permission-presets/catalog-changed` — emit
+2 -2
View File
@@ -6,8 +6,8 @@
en: 337a6580d7571274
zh: f4ae98899120d122
/ptc-runtime/the-run-request-in-result-out:
en: ec7ae3790b868bb9
zh: 95b753e703b14731
en: 0305ed1d4f8bc618
zh: fcfeb156574b5779
/ptc-runtime/bindings-host-functions-as-program-globals:
en: 182147ddf388c600
zh: c0a7d77602c78bcd
+1 -1
View File
@@ -101,7 +101,7 @@ interface PtcRunResult {
}
```
`programFormat` distinguishes async function bodies from REPL statements. `stateOwner` is an in-process object identity for optional retained memory; distinct objects remain isolated. Consumers await `release(owner)` when that owner ends; cleanup failures reject that call. Omitted owners are one-shot, and stateless providers ignore ownership. The [persistent Node provider](../../packages/ptc-runtime/ptc-runtime-node/README.md#persistent-repl) defines reset and recovery behavior; no retained object enters the durable Session format. `retainsState` reports whether the provider preserves program memory.
`programFormat` distinguishes async function bodies from REPL statements. `stateOwner` is an in-process object identity for optional retained memory; distinct objects remain isolated. Consumers await `release(owner)` when that owner ends; cleanup failures reject that call. Omitted owners are one-shot, and stateless providers ignore ownership. The [persistent Node provider](../../packages/ptc-runtime/ptc-runtime-node/README.md#persistent-repl) defines reset and recovery behavior; no retained object enters the durable Session format.
## Bindings: host functions as program globals
+1 -1
View File
@@ -101,7 +101,7 @@ interface PtcRunResult {
}
```
`programFormat` 区分异步函数体与 REPL 语句。`stateOwner` 是标识可选保留内存的进程内对象身份;不同对象相互隔离。消费者在所有者结束时等待 `release(owner)`;清理失败时该调用拒绝。省略所有者时仅执行一次,无状态提供方忽略所有权。[持久 Node 提供方](../../packages/ptc-runtime/ptc-runtime-node/README.zh.md#persistent-repl)定义重置和恢复行为;保留对象不会进入持久 Session 格式。 `retainsState` 标明提供方是否保留程序内存。
`programFormat` 区分异步函数体与 REPL 语句。`stateOwner` 是标识可选保留内存的进程内对象身份;不同对象相互隔离。消费者在所有者结束时等待 `release(owner)`;清理失败时该调用拒绝。省略所有者时仅执行一次,无状态提供方忽略所有权。[持久 Node 提供方](../../packages/ptc-runtime/ptc-runtime-node/README.zh.md#persistent-repl)定义重置和恢复行为;保留对象不会进入持久 Session 格式。
## 绑定:宿主函数作为程序全局变量
+2 -2
View File
@@ -9,8 +9,8 @@
en: 11f91b55cc317334
zh: 296678c4675864c1
/process-sandbox/per-call-policy:
en: 7661eb4559bbc395
zh: 0dceeb0bba367862
en: 91bc8e44c050fccf
zh: 5c0a340694243a71
/process-sandbox/wrapped-argv-and-classification-dialects:
en: 2ba8930762e92e40
zh: 220f64da1a9e5d57
+43 -1
View File
@@ -93,6 +93,18 @@ interface SandboxPolicy extends SandboxExecutionPolicy {
}
```
`setMode()` coordinates Session mode changes. Callers execute cancellable work through `withExecution()`; providers register idempotent process cleanup with `registerResource()`. A change cancels operations, awaits their complete settlement and resource cleanup, then records the mode. It cannot be initiated from an operation that it must cancel. An optional synchronous commit receives the mode writer so a caller can revalidate state and record related events without yielding.
```ts type-equiv
/** A process or retained environment that must stop before its Session changes file policy. */
interface SandboxPolicyResource {
/** Idempotently stop the resource and await cleanup; rejection prevents the policy change. */
release(): Promise<void>
/** User-facing consequence reported after a successful policy change. */
notice?: string
}
```
<a id="wrapped-argv-and-classification-dialects"></a>
## Wrapped argv and classification dialects
@@ -207,6 +219,36 @@ The sandbox-policy service (`ctx.sandboxPolicy`). Owns the deployment default mo
*/
resolve(request: SandboxPolicyRequest = {}): SandboxExecutionPolicy
/**
* Cancel admitted operations and release registered resources before recording a new mode.
* An unchanged effective mode records the override without clearing resources.
* @param session - Session whose file policy changes.
* @param mode - Mode for subsequent executions.
* @param commit - Optional synchronous commit: validate caller state, invoke the supplied mode writer, then record related changes.
* @returns Resource-reset notices after the mode event is committed.
* @throws On concurrent changes, disposal, or cleanup failure; cleanup failures leave the mode unchanged.
*/
async setMode(session: Session, mode: SandboxMode, commit?: (writeMode: () => void) => void): Promise<string[]>
/**
* Register an execution resource under its Session's file policy.
* @param sessionId - Session identity carried in the resolved execution policy.
* @param resource - Awaited cleanup and optional reset notice.
* @returns Disposer for an already stopped resource; contributor unload awaits cleanup before detaching.
* @throws While the Session changes mode or this provider is disposed.
*/
registerResource(sessionId: SessionId, resource: SandboxPolicyResource): () => void
/**
* Run one cancellable operation, including asynchronous preparation and final cleanup.
* @param sessionId - Session whose standing mode applies to the operation.
* @param signal - Caller-owned cancellation.
* @param run - Operation that observes the combined signal and awaits its own cleanup before settling.
* @returns The operation's result; mode changes await its settlement even when it rejects.
* @throws While the Session changes mode or this provider is disposed.
*/
async withExecution<T>(sessionId: SessionId, signal: AbortSignal, run: (signal: AbortSignal) => Promise<T>): Promise<T>
/**
* Read the session override without applying the deployment default.
* @param session - session whose log supplies the override.
@@ -215,7 +257,7 @@ resolve(request: SandboxPolicyRequest = {}): SandboxExecutionPolicy
overrideOf(session: Session): SandboxMode | undefined
```
Types: [Session](session.md)
Types: [Session](session.md) · [SessionId](core.md)
Source: [`packages/sandbox/sandbox-policy/src/index.ts`](../../packages/sandbox/sandbox-policy/src/index.ts)
<!-- END GENERATED cordis-surface -->
+43 -1
View File
@@ -93,6 +93,18 @@ interface SandboxPolicy extends SandboxExecutionPolicy {
}
```
`setMode()` 协调 Session 模式切换。调用方通过 `withExecution()` 执行可取消工作,提供方通过 `registerResource()` 登记幂等进程清理。切换会取消操作,等待操作完成及资源清理,再记录模式。操作不能发起会取消自身的模式切换。可选的同步提交回调接收模式写入函数,调用方可以重新验证状态并连续记录相关事件。
```ts type-equiv
/** A process or retained environment that must stop before its Session changes file policy. */
interface SandboxPolicyResource {
/** Idempotently stop the resource and await cleanup; rejection prevents the policy change. */
release(): Promise<void>
/** User-facing consequence reported after a successful policy change. */
notice?: string
}
```
<a id="wrapped-argv-and-classification-dialects"></a>
## 包装后的 argv 与分类方言
@@ -207,6 +219,36 @@ The sandbox-policy service (`ctx.sandboxPolicy`). Owns the deployment default mo
*/
resolve(request: SandboxPolicyRequest = {}): SandboxExecutionPolicy
/**
* Cancel admitted operations and release registered resources before recording a new mode.
* An unchanged effective mode records the override without clearing resources.
* @param session - Session whose file policy changes.
* @param mode - Mode for subsequent executions.
* @param commit - Optional synchronous commit: validate caller state, invoke the supplied mode writer, then record related changes.
* @returns Resource-reset notices after the mode event is committed.
* @throws On concurrent changes, disposal, or cleanup failure; cleanup failures leave the mode unchanged.
*/
async setMode(session: Session, mode: SandboxMode, commit?: (writeMode: () => void) => void): Promise<string[]>
/**
* Register an execution resource under its Session's file policy.
* @param sessionId - Session identity carried in the resolved execution policy.
* @param resource - Awaited cleanup and optional reset notice.
* @returns Disposer for an already stopped resource; contributor unload awaits cleanup before detaching.
* @throws While the Session changes mode or this provider is disposed.
*/
registerResource(sessionId: SessionId, resource: SandboxPolicyResource): () => void
/**
* Run one cancellable operation, including asynchronous preparation and final cleanup.
* @param sessionId - Session whose standing mode applies to the operation.
* @param signal - Caller-owned cancellation.
* @param run - Operation that observes the combined signal and awaits its own cleanup before settling.
* @returns The operation's result; mode changes await its settlement even when it rejects.
* @throws While the Session changes mode or this provider is disposed.
*/
async withExecution<T>(sessionId: SessionId, signal: AbortSignal, run: (signal: AbortSignal) => Promise<T>): Promise<T>
/**
* Read the session override without applying the deployment default.
* @param session - session whose log supplies the override.
@@ -215,7 +257,7 @@ resolve(request: SandboxPolicyRequest = {}): SandboxExecutionPolicy
overrideOf(session: Session): SandboxMode | undefined
```
Types: [Session](session.zh.md)
Types: [Session](session.zh.md) · [SessionId](core.zh.md)
Source: [`packages/sandbox/sandbox-policy/src/index.ts`](../../packages/sandbox/sandbox-policy/src/index.ts)
<!-- END GENERATED cordis-surface -->
@@ -9,8 +9,8 @@
en: 5a24a61f18e1c839
zh: ec52b95c58fde7d1
/await-permission-preset-changes/change:
en: fdab63317018fac7
zh: b3b02231f11eb02c
en: 8fd53eee57300473
zh: e5dfdc6aa8e3340b
/await-permission-preset-changes/migration:
en: 5026cc30be6ec51d
zh: a3d525c00800da6b
@@ -8,7 +8,7 @@ English | [中文](guide.zh.md)
## Change
`ctx.permissionPresets.set(session, name)` returns `Promise<string[]>`. The promise resolves after retained execution resources are released and permission events are committed. Its strings describe cleared resources. Invalid presets and cleanup failures reject the promise.
`ctx.permissionPresets.set(session, name)` returns `Promise<string[]>`. The promise resolves after retained execution resources are released and permission events are committed. Its strings describe cleared resources. The standalone `setSandboxMode(session, mode)` export is replaced by `await ctx.sandboxPolicy.setMode(session, mode)` so direct mode changes use the same cleanup operation. A mode change also cancels pending approvals and in-flight PTC programs in the default `per-call` mode, waiting for nested tools to finish cleanup. Invalid presets and cleanup failures reject the promise.
## Migration
@@ -8,7 +8,7 @@ description: "权限预设调用方必须等待执行资源清理后,再使用
## 变更
`ctx.permissionPresets.set(session, name)` 返回 `Promise<string[]>`。保留的执行资源释放且权限事件提交后,Promise 才会完成。返回的字符串说明清空了哪些资源。无效预设和清理失败会使 Promise 拒绝。
`ctx.permissionPresets.set(session, name)` 返回 `Promise<string[]>`。保留的执行资源释放且权限事件提交后,Promise 才会完成。返回的字符串说明清空了哪些资源。独立的 `setSandboxMode(session, mode)` 导出被 `await ctx.sandboxPolicy.setMode(session, mode)` 替代,直接选择模式也使用同一个清理操作。模式变化也会取消待审批的 PTC 调用和默认 `per-call` 模式中正在执行的程序,并等待嵌套工具完成清理。无效预设和清理失败会使 Promise 拒绝。
## 迁移
@@ -4,7 +4,7 @@ import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
import ToolRuntime from '@deepseek-ai/dsh-tools'
import { ToolCallId } from '@deepseek-ai/dsh-llm'
import type { Agent } from '@deepseek-ai/dsh-agent'
import SandboxPolicy, { setSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
import SandboxPolicy from '@deepseek-ai/dsh-sandbox-policy'
import { Session, SessionId, SESSION_FORMAT_VERSION } from '@deepseek-ai/dsh-session'
import SessionProjections from '@deepseek-ai/dsh-session-projection'
import ApprovalService, { type ApprovalOutcome } from '@deepseek-ai/dsh-user-approval'
@@ -120,12 +120,12 @@ it('checks the calling session on each execution, including after permission is
const id = SessionId('manager-permissions')
const session = Session.create(id, undefined, { version: SESSION_FORMAT_VERSION, id, createdAt: 0, isSeeded: false })
const agent = { session } as unknown as Agent
setSandboxMode(session, 'workspace-write')
await ctx.sandboxPolicy.setMode(session, 'workspace-write')
expect((await call({ action: 'list_plugins' }, agent)).isError).toBe(true)
expect(manager.listPlugins).not.toHaveBeenCalled()
setSandboxMode(session, 'danger-full-access')
await ctx.sandboxPolicy.setMode(session, 'danger-full-access')
expect((await call({ action: 'list_plugins' }, agent)).isError).toBe(false)
setSandboxMode(session, 'read-only')
await ctx.sandboxPolicy.setMode(session, 'read-only')
expect((await call({ action: 'list_plugins' }, agent)).isError).toBe(true)
expect(manager.listPlugins).toHaveBeenCalledTimes(1)
})
@@ -179,7 +179,7 @@ it('rejects never policy without prompting and keeps full-access calls prompt-fr
const agent = activeAgent()
expect((await call({ action: 'set_plugin', target: 'include:demo', enabled: true }, agent)).isError).toBe(true)
expect(manager.setPluginEnabled).not.toHaveBeenCalled()
setSandboxMode(agent.session, 'danger-full-access')
await ctx.sandboxPolicy.setMode(agent.session, 'danger-full-access')
expect((await call({ action: 'set_plugin', target: 'include:demo', enabled: true }, agent)).isError).toBe(false)
expect(manager.setPluginEnabled).toHaveBeenCalledTimes(1)
expect(prompted).not.toHaveBeenCalled()
+2 -2
View File
@@ -45,8 +45,8 @@
en: dc44a88997777988
zh: 56454aeace1c8b77
/deepseek-ai-dsh-tools/understand-the-implementation/ptc-mode:
en: 006ae06e6c0ba1b7
zh: 8859d395bb12dd78
en: 030308aee84dd91e
zh: 9ae122234a445e86
/deepseek-ai-dsh-tools/understand-the-implementation/extension-points:
en: c2a14d6f22bc9428
zh: 89c1414fca465931
+1 -1
View File
@@ -133,7 +133,7 @@ New sub-calls use `<parent>:ptc:<n>` ids. Consumers treat these ids as opaque an
Successful image-bearing subcall results become deferred user-message context with `source.kind` set to `ptc-mode`. Other additional contexts retain their producing tool's attribution.
`run_code` accepts `timeoutMs` when the mounted runtime supports an override; its schema reports the configured default and maximum, and the runtime's usage instructions. The Node default is 120,000 ms with a 600,000 ms cap, including nested tool and approval waits. A wider `sandbox_permissions` mode requires a non-empty `justification` and approval before the program starts. The schema asks the model to write that reason in the current user's language. The grant applies to that complete execution; standing Session policy and nested tools retain their own authority. Programs are never replayed automatically: inspect earlier effects before explicitly retrying a denied program. Retained PTC environments follow the standing file policy. Permission preset changes await their cleanup before committing the new mode and return a variable-reset notice. One-time escalations use isolated temporary owners whose resources are released before the result returns; standing variables remain available to ordinary calls.
`run_code` accepts `timeoutMs` when the mounted runtime supports an override; its schema reports the configured default and maximum, and the runtime's usage instructions. The Node default is 120,000 ms with a 600,000 ms cap, including nested tool and approval waits. A wider `sandbox_permissions` mode requires a non-empty `justification` and approval before the program starts. The schema asks the model to write that reason in the current user's language. The grant applies to that complete execution; standing Session policy and nested tools retain their own authority. Programs are never replayed automatically: inspect earlier effects before explicitly retrying a denied program. Retained PTC environments follow the standing file policy. The file-policy service cancels admitted PTC calls in both Node modes before changing mode and waits for their nested tools to finish cleanup. The runtime registers its retained processes with that service for cleanup. One-time escalations omit the state owner and complete in a temporary environment; standing variables remain available to ordinary calls.
<a id="extension-points"></a>
### Extension points
+1 -1
View File
@@ -133,7 +133,7 @@ ctx.tools.register(defineTool({
成功且包含图片的子调用结果会成为延后的 user-message 上下文,其 `source.kind` 为 `ptc-mode`。其他 additional context 保留其生产工具的归属。
当已挂载运行时支持覆盖时,`run_code` 接受 `timeoutMs`;其 schema 报告配置的默认值和上限以及运行时使用说明。Node 默认值为 120,000 ms,上限为 600,000 ms,包含嵌套工具和审批等待。更宽的 `sandbox_permissions` 模式要求非空 `justification`,并在程序启动前获得审批。schema 提示模型使用当前用户的语言撰写理由。授权仅用于该次完整执行;常驻 Session 策略与嵌套工具保留各自权限。程序不会自动重放:显式重试被拒程序前,应检查先前已发生的效果。 保留状态的 PTC 环境遵循会话文件策略。权限预设切换等待环境清理后再提交新模式,并返回变量清空提示。单次提权使用独立的临时所有者,返回结果前释放其资源;普通调用仍可访问原环境的变量。
当已挂载运行时支持覆盖时,`run_code` 接受 `timeoutMs`;其 schema 报告配置的默认值和上限以及运行时使用说明。Node 默认值为 120,000 ms,上限为 600,000 ms,包含嵌套工具和审批等待。更宽的 `sandbox_permissions` 模式要求非空 `justification`,并在程序启动前获得审批。schema 提示模型使用当前用户的语言撰写理由。授权仅用于该次完整执行;常驻 Session 策略与嵌套工具保留各自权限。程序不会自动重放:显式重试被拒程序前,应检查先前已发生的效果。 保留状态的 PTC 环境遵循会话文件策略。文件策略服务在切换模式前取消两种 Node 模式下已接纳的 PTC 调用,并等待嵌套工具清理完成,运行时向该服务登记保留进程的清理操作。单次提权省略状态所有者,在临时环境中执行;普通调用仍可访问原环境的变量。
<a id="extension-points"></a>
### 扩展点
+2 -4
View File
@@ -46,8 +46,7 @@
"@deepseek-ai/dsh-user-approval": "workspace:*",
"@deepseek-ai/dsh-sandbox": "workspace:*",
"@deepseek-ai/dsh-sandbox-policy": "workspace:*",
"@deepseek-ai/dsh-working-directory": "workspace:*",
"@deepseek-ai/dsh-permission-presets": "workspace:*"
"@deepseek-ai/dsh-working-directory": "workspace:*"
},
"dependencies": {
"@deepseek-ai/dsh-brand": "workspace:*",
@@ -67,7 +66,6 @@
"@deepseek-ai/dsh-sandbox": "workspace:*",
"@deepseek-ai/dsh-sandbox-policy": "workspace:*",
"@deepseek-ai/dsh-working-directory": "workspace:*",
"@deepseek-ai/dsh-agent-loop-testkit": "workspace:*",
"@deepseek-ai/dsh-permission-presets": "workspace:*"
"@deepseek-ai/dsh-agent-loop-testkit": "workspace:*"
}
}
+6
View File
@@ -944,6 +944,12 @@ export class ToolRuntime extends Service {
*/
private requirePtcTransport(): ToolDefinition {
this.ptcTransport ??= createRunCodeTool(this, {
runSandboxExecution: (exec, run) => {
if (exec.agent === undefined) return run(exec.signal)
const policy = this.ctx.get('sandboxPolicy')
if (policy === undefined) throw new Error('dsh-tools: confined PTC runtime requires sandboxPolicy')
return policy.withExecution(exec.agent.session.id, exec.signal, run)
},
resolveWorkingDirectory: async (exec) => {
// Only Agent-owned PTC requires directory state; native registries
// and unowned programs can run without this service.
-99
View File
@@ -1,99 +0,0 @@
/** Agent-owned PTC resources across calls, temporary approvals, and permission changes. */
import { symbols } from '@deepseek-ai/cordis'
import type { Agent } from '@deepseek-ai/dsh-agent'
import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
import type { PtcRuntime } from '@deepseek-ai/dsh-ptc-runtime'
import type { SandboxExecutionPolicy } from '@deepseek-ai/dsh-sandbox'
import type {} from '@deepseek-ai/dsh-permission-presets'
interface OwnerState {
providers: Map<PtcRuntime, Set<object>>
controllers: Set<AbortController>
phase: 'ready' | 'changing' | 'disposed'
}
/** Keeps admission closed until permission changes and resource disposal settle. */
export class PtcOwners {
private readonly agents = new WeakMap<Agent, OwnerState>()
/**
* Reserve one execution before approval or directory resolution can yield.
* @param agent - Calling Agent, if the program has a durable conversation.
* @param runtime - Runtime receiving the program.
* @param signal - Cancellation of this tool call.
* @param temporary - Whether approval applies only to this execution.
* @param policy - Read the Agent's current standing file policy.
* @returns Owner and cancellation signal, with an awaited per-call cleanup.
*/
enter(
agent: Agent | undefined, runtime: PtcRuntime, signal: AbortSignal, temporary: boolean,
policy: () => SandboxExecutionPolicy | undefined,
): { owner: object | undefined; signal: AbortSignal; finish: () => Promise<void> } {
if (agent === undefined) {
return { owner: undefined, signal, finish: async () => {} }
}
let state = this.agents.get(agent)
if (state === undefined) {
state = { providers: new Map(), controllers: new Set(), phase: 'ready' }
this.agents.set(agent, state)
const owned = state
const isDisposed = (): boolean => owned.phase === 'disposed'
const clear = async (): Promise<void> => {
for (const controller of owned.controllers) controller.abort(new Error('PTC environment cleared for a permission change or Agent disposal'))
const results = await Promise.allSettled([...owned.providers].flatMap(([provider, owners]) =>
[...owners].map(owner => provider.release(owner))))
const failure = results.find(result => result.status === 'rejected')
if (failure?.status === 'rejected') throw failure.reason
owned.providers.clear()
}
agent.ctx.effect(() => async () => { owned.phase = 'disposed'; await clear() }, 'PTC retained environments')
agent.ctx.on('permission-presets/apply', async (session, mode, next) => {
if (session !== agent.session || policy()?.mode === mode) return next()
owned.phase = 'changing'
const retained = [...owned.providers.keys()].some(provider => provider.retainsState)
try {
await clear()
if (isDisposed()) throw new Error('PTC Agent was disposed during the permission change')
const notices = await next()
return retained ? [...notices, 'PTC variables were cleared after the sandbox mode changed. Recreate variables before using them.'] : notices
} finally {
if (!isDisposed()) owned.phase = 'ready'
}
}, { global: true })
agent.ctx.on('internal/dispatch', (_mode, name, args) => {
if (name !== 'session/event') return
const [session, event] = args as [Session, SessionEvent]
if (session !== agent.session || event.type !== 'sandbox/mode' || event.data.mode === policy()?.mode) return
if ([...owned.providers.keys()].some(provider => provider.retainsState)) {
throw new Error('release retained PTC environments before changing the sandbox mode; use the permission preset setter')
}
}, { global: true })
}
if (state.phase !== 'ready') throw new Error('PTC cannot start while its permission or lifecycle cleanup is in progress')
let provider = runtime
for (;;) {
const original = (provider as PtcRuntime & { [symbols.original]?: PtcRuntime })[symbols.original]
if (original === undefined) break
provider = original
}
const owner = temporary ? {} : agent
let owners = state.providers.get(provider)
if (owners === undefined) state.providers.set(provider, owners = new Set())
owners.add(owner)
const controller = new AbortController()
state.controllers.add(controller)
return {
owner,
signal: AbortSignal.any([signal, controller.signal]),
finish: async (): Promise<void> => {
try {
if (temporary) {
await provider.release(owner)
owners.delete(owner)
if (owners.size === 0 && state.providers.get(provider) === owners) state.providers.delete(provider)
}
} finally { state.controllers.delete(controller) }
},
}
}
}
+24 -8
View File
@@ -6,6 +6,7 @@
* @module @deepseek-ai/dsh-tools/src/ptc
*/
import { symbols } from '@deepseek-ai/cordis'
import { brandString } from '@deepseek-ai/dsh-brand'
import { createUserMessage, HarnessError } from '@deepseek-ai/dsh-llm'
declare module '@deepseek-ai/dsh-llm' {
@@ -25,7 +26,6 @@ import { defineTool, parameterSchemaSpecToJsonSchema } from './schema.ts'
import { TOOL_RUNTIME_SCHEDULER } from './index.ts'
import type { PtcDispatchLog, ToolDefinition, ToolExecutionResult, ToolRuntime, ToolRunContext } from './index.ts'
import type {} from './types.ts'
import { PtcOwners } from './ptc-owners.ts'
/** The model-facing name of the PTC mode tool. */
export const RUN_CODE_NAME = 'run_code'
@@ -283,6 +283,8 @@ type RunCodeOutput = { logs: string[]; result?: JsonValue; sandbox?: PtcRunSandb
* off its public service API and flow here as closures instead.
*/
export interface RunCodeBridgeOptions {
/** Scope execution through the file-policy owner, including approval and nested-call cleanup. */
runSandboxExecution: (exec: ToolRunContext, run: (signal: AbortSignal) => Promise<RunCodeOutput>) => Promise<RunCodeOutput>
/** Captures the calling Session current directory before program creation. */
resolveWorkingDirectory: (exec: ToolRunContext) => Promise<string | undefined>
/** Reads the approval channel when a program requests a wider sandbox mode. */
@@ -317,7 +319,7 @@ export interface RunCodeBridgeOptions {
*/
export function createRunCodeTool(registry: ToolRuntime, options: RunCodeBridgeOptions): ToolDefinition {
const { requireRuntime, peekRuntime, maxParallel, shapeDispatchLog } = options
const stateOwners = new PtcOwners()
const stateOwners = new WeakMap<object, WeakSet<PtcRuntime>>()
const definition = defineTool({
name: RUN_CODE_NAME,
// The description and `code` parameter description are placeholders here:
@@ -367,10 +369,7 @@ export function createRunCodeTool(registry: ToolRuntime, options: RunCodeBridgeO
throw new Error('invalid description: expected a non-empty string')
}
const runtime = requireRuntime()
const admission = stateOwners.enter(exec.agent, runtime, exec.signal, args.sandbox_permissions !== undefined,
() => runtime.sandboxMode === undefined ? undefined : options.resolveSandboxPolicy(exec))
const callSignal = admission.signal
try {
const run = async (callSignal: AbortSignal): Promise<RunCodeOutput> => {
validateEscalationArgs(args.sandbox_permissions, args.justification)
if (args.timeoutMs !== undefined && runtime.timeout === undefined) {
throw new Error('timeoutMs is not available for this PTC runtime')
@@ -686,9 +685,25 @@ export function createRunCodeTool(registry: ToolRuntime, options: RunCodeBridgeO
try {
let result: PtcRunResult
try {
if (exec.agent !== undefined) {
const agent = exec.agent
let runtimes = stateOwners.get(agent)
if (runtimes === undefined) stateOwners.set(agent, runtimes = new WeakSet())
// Cordis can wrap service returns repeatedly; cleanup belongs to the original provider.
let provider = runtime
for (;;) {
const original = (provider as PtcRuntime & { [symbols.original]?: PtcRuntime })[symbols.original]
if (original === undefined) break
provider = original
}
if (!runtimes.has(provider)) {
agent.ctx.effect(() => () => runtime.release(agent), 'PTC retained environment')
runtimes.add(provider)
}
}
result = await runtime.run(runtime.resolve({
program: args.code,
...admission.owner === undefined ? {} : { stateOwner: admission.owner },
...exec.agent === undefined || policy?.mode !== standingPolicy?.mode ? {} : { stateOwner: exec.agent },
bindings: [{
global: 'tools',
functions,
@@ -721,7 +736,8 @@ export function createRunCodeTool(registry: ToolRuntime, options: RunCodeBridgeO
} finally {
callSignal.removeEventListener('abort', onOuterAbort)
}
} finally { await admission.finish() }
}
return runtime.sandboxMode === undefined ? run(exec.signal) : options.runSandboxExecution(exec, run)
},
// The model-authored description is the call's always-visible UI label
// (the bash `description` precedent); the program itself rides rawInput.
@@ -1,149 +0,0 @@
import { Context } from '@deepseek-ai/cordis'
import type { Agent } from '@deepseek-ai/dsh-agent'
import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
import SessionProjections from '@deepseek-ai/dsh-session-projection'
import SandboxPolicy, { setSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
import PermissionPresets from '@deepseek-ai/dsh-permission-presets'
import Approval from '@deepseek-ai/dsh-user-approval'
import { PtcRuntime } from '@deepseek-ai/dsh-ptc-runtime'
import type { PtcRunRequest } from '@deepseek-ai/dsh-ptc-runtime'
import { expect, it, onTestFinished, vi } from 'vitest'
import { PtcOwners } from '../src/ptc-owners.ts'
class Runtime extends PtcRuntime {
language = 'typescript'
isolation = 'test'
override get retainsState() { return true }
resolve(request: PtcRunRequest) { return { ...request, cwd: process.cwd(), timeoutMs: null } }
run() { return Promise.resolve({ logs: [] }) }
}
async function setup() {
const ctx = new Context()
onTestFinished(async () => { await ctx.fiber.dispose() })
await ctx.plugin(SessionStore)
await ctx.plugin(SessionProjections)
await ctx.plugin(SandboxPolicy, { mode: 'workspace-write' })
await ctx.plugin(Approval)
ctx.provide('shell', { sandboxMode: 'workspace-write' })
await ctx.plugin(PermissionPresets, { presets: {
'read-only': { sandbox: 'read-only', approval: 'ask' },
'workspace-write': { sandbox: 'workspace-write', approval: 'ask' },
'danger-full-access': { sandbox: 'danger-full-access', approval: 'never' },
} })
await ctx.plugin(Runtime)
const session = ctx.sessions.create(SessionId('ptc-permission-owner'))
const agent = { ctx, session } as Agent
const owners = new PtcOwners()
const runtime = ctx.ptcRuntime
const enter = (temporary = false) => owners.enter(agent, runtime, new AbortController().signal, temporary,
() => ctx.sandboxPolicy.resolve({ session }))
return { ctx, session, agent, enter }
}
it('waits for cleanup before recording a permission change and fences new programs', async () => {
const { ctx, session, agent, enter } = await setup()
const call = enter()
await call.finish()
const entered = Promise.withResolvers<undefined>()
const released = Promise.withResolvers<undefined>()
const release = vi.spyOn(ctx.ptcRuntime, 'release').mockImplementation(async () => { entered.resolve(undefined); await released.promise })
const before = session.snapshotEvents()
const switching = ctx.permissionPresets.set(session, 'read-only')
try {
await entered.promise
expect(release).toHaveBeenCalledWith(agent)
expect(session.snapshotEvents()).toEqual(before)
expect(call.signal.aborted).toBe(false)
expect(() => enter()).toThrow('cleanup is in progress')
await expect(ctx.permissionPresets.set(session, 'danger-full-access')).rejects.toThrow('still in progress')
released.resolve(undefined)
expect(await switching).toEqual(['PTC variables were cleared after the sandbox mode changed. Recreate variables before using them.'])
expect(ctx.sandboxPolicy.resolve({ session }).mode).toBe('read-only')
const next = enter()
await next.finish()
} finally { released.resolve(undefined); await switching; release.mockRestore() }
})
it('keeps permission events unchanged when cleanup fails and rejects raw mode writes', async () => {
const { ctx, session, enter } = await setup()
await enter().finish()
const before = session.snapshotEvents()
expect(() => { setSandboxMode(session, 'read-only') }).toThrow('release retained PTC')
const release = vi.spyOn(ctx.ptcRuntime, 'release').mockRejectedValue(new Error('cleanup failed'))
try {
await expect(ctx.permissionPresets.set(session, 'read-only')).rejects.toThrow('cleanup failed')
expect(session.snapshotEvents()).toEqual(before)
} finally { release.mockRestore() }
})
it('does not reset retained state for the same sandbox mode or another session', async () => {
const { ctx, session, enter } = await setup()
await enter().finish()
const release = vi.spyOn(ctx.ptcRuntime, 'release')
try {
expect(await ctx.permissionPresets.set(session, 'workspace-write')).toEqual([])
const other = ctx.sessions.create(SessionId('ptc-other-owner'))
await ctx.permissionPresets.set(other, 'read-only')
expect(release).not.toHaveBeenCalled()
} finally { release.mockRestore() }
})
it('isolates temporary owners and awaits their release without clearing the standing owner', async () => {
const { ctx, agent, enter } = await setup()
const standing = enter()
await standing.finish()
const release = vi.spyOn(ctx.ptcRuntime, 'release')
try {
const elevated = enter(true)
expect(standing.owner).toBe(agent)
expect(elevated.owner).not.toBe(agent)
await elevated.finish()
expect(release).toHaveBeenCalledExactlyOnceWith(elevated.owner)
const next = enter()
expect(next.owner).toBe(agent)
await next.finish()
} finally { release.mockRestore() }
})
it('cancels admitted programs while switching permissions', async () => {
const { ctx, session, enter } = await setup()
const call = enter(true)
await ctx.permissionPresets.set(session, 'read-only')
expect(call.signal.aborted).toBe(true)
await call.finish()
})
it('keeps admission closed when Agent disposal overlaps a permission change', async () => {
const { ctx, session, enter } = await setup()
await enter().finish()
const entered = Promise.withResolvers<undefined>()
const disposingEntered = Promise.withResolvers<undefined>()
const released = Promise.withResolvers<undefined>()
let calls = 0
const release = vi.spyOn(ctx.ptcRuntime, 'release').mockImplementation(async () => {
if (++calls === 1) entered.resolve(undefined)
else disposingEntered.resolve(undefined)
await released.promise
})
const switching = ctx.permissionPresets.set(session, 'read-only')
const rejected = expect(switching).rejects.toThrow('disposed during the permission change')
await entered.promise
const disposing = ctx.fiber.dispose()
try {
await disposingEntered.promise
released.resolve(undefined)
await rejected
await disposing
expect(() => enter()).toThrow('cleanup is in progress')
} finally { released.resolve(undefined); await Promise.allSettled([switching, disposing]); release.mockRestore() }
})
it('returns no reset notice for a stateless runtime', async () => {
const { ctx, session, enter } = await setup()
const retention = vi.spyOn(ctx.ptcRuntime, 'retainsState', 'get').mockReturnValue(false)
try {
await enter().finish()
expect(await ctx.permissionPresets.set(session, 'read-only')).toEqual([])
} finally { retention.mockRestore() }
})
+17 -5
View File
@@ -2361,6 +2361,18 @@ describe('per-program execution controls', () => {
} finally { await ctx.fiber.dispose() }
})
it('reuses the standing owner when sandbox_permissions repeats the current mode', async () => {
const { ctx, runtime, session, agent, execute } = await controlledSetup()
const ask = vi.fn(() => Promise.resolve<ApprovalOutcome>('allowed-once'))
ctx.on('approval/request', ask)
try {
await ctx.sandboxPolicy.setMode(session, 'workspace-write')
expect((await execute({ sandbox_permissions: 'workspace-write', justification: 'Use current file permissions' })).isError).toBe(false)
expect(runtime.lastRequest?.stateOwner).toBe(agent)
expect(ask).not.toHaveBeenCalled()
} finally { await ctx.fiber.dispose() }
})
it('fails closed when no approval service is mounted', async () => {
const { ctx, runtime, execute } = await controlledSetup(false)
try {
@@ -2370,8 +2382,8 @@ describe('per-program execution controls', () => {
} finally { await ctx.fiber.dispose() }
})
it('cancels an outstanding approval without launching the program', async () => {
const { ctx, runtime, execute } = await controlledSetup()
it.each(['caller', 'policy'] as const)('cancels an outstanding approval after %s cancellation without launching the program', async (source) => {
const { ctx, runtime, session, execute } = await controlledSetup()
const asked = Promise.withResolvers<undefined>()
const answer = Promise.withResolvers<ApprovalOutcome>()
const controller = new AbortController()
@@ -2379,7 +2391,8 @@ describe('per-program execution controls', () => {
const result = execute({ sandbox_permissions: 'workspace-write', justification: 'Write generated source' }, controller.signal)
try {
await asked.promise
controller.abort('cancel outer approval')
if (source === 'caller') controller.abort('cancel outer approval')
else await ctx.sandboxPolicy.setMode(session, 'workspace-write')
expect((await result).isError).toBe(true)
expect(runtime.lastRequest).toBeUndefined()
} finally { answer.resolve('cancelled'); await result; await ctx.fiber.dispose() }
@@ -2437,8 +2450,7 @@ describe('per-program execution controls', () => {
expect(completed.isError).toBe(false)
expect(requests.map(req => req.toolName)).toEqual([RUN_CODE_NAME, 'echo'])
expect(runtime.lastRequest?.timeoutMs).toBe(1234)
expect(runtime.lastRequest?.stateOwner).not.toBe(agent)
expect(runtime.lastRequest?.stateOwner).toBeDefined()
expect(runtime.lastRequest?.stateOwner).toBeUndefined()
expect(ctx.sandboxPolicy.resolve({ session: agent.session }).mode).toBe('read-only')
} finally { answer.resolve('cancelled'); await result; await ctx.fiber.dispose() }
})
-3
View File
@@ -46,9 +46,6 @@
},
{
"path": "../../session/working-directory"
},
{
"path": "../../interaction/permission-presets"
}
]
}
@@ -1,3 +1,4 @@
import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
import { externalTestParent } from '../../../subagent/subagent/tests/external-activation-helpers.ts'
import { afterEach, describe, expect, it, vi } from 'vitest'
import { provideWorkingDirectoryFixture } from '@deepseek-ai/dsh-agent-loop-testkit'
@@ -137,6 +138,7 @@ async function harness(
await ctx.plugin(LlmRuntime)
await ctx.plugin(SessionStore)
await ctx.plugin(SessionProjectionRegistry)
await ctx.plugin(SandboxPolicyService, { mode: 'workspace-write' })
await ctx.plugin(SystemPrompt, {})
await ctx.plugin(ToolRuntime)
ctx.provide('shell', {
@@ -1523,6 +1525,7 @@ describe('cancellation and integration teardown', () => {
await invalid.plugin(LlmRuntime)
await invalid.plugin(SessionStore)
await invalid.plugin(SessionProjectionRegistry)
await invalid.plugin(SandboxPolicyService, { mode: 'workspace-write' })
await invalid.plugin(SystemPrompt, {})
await invalid.plugin(ToolRuntime)
invalid.provide('shell', {
@@ -1643,7 +1643,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
},
{
signature: 'set(session: Session, name: string): Promise<string[]>',
description: 'Record a changed preset, then update each changed knob through its own setter. Selecting the effective preset again appends nothing.',
description: 'Await file-policy cleanup, then record the changed preset and approval policy. Selecting the effective preset again appends nothing.',
parameters: [{ name: 'session', description: 'the session the switch belongs to.' }, { name: 'name', description: 'the preset to switch to; unknown names reject.' }],
returns: 'Notices after old execution resources are released and the new preset is recorded.',
},
@@ -1896,6 +1896,27 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
parameters: [{ name: 'request', description: 'optional session and approved mode override.' }],
returns: 'the fully resolved per-call mode and absolute workspace root.',
},
{
signature: 'async setMode(session: Session, mode: SandboxMode, commit?: (writeMode: () => void) => void): Promise<string[]>',
description: 'Cancel admitted operations and release registered resources before recording a new mode. An unchanged effective mode records the override without clearing resources.',
parameters: [{ name: 'session', description: 'Session whose file policy changes.' }, { name: 'mode', description: 'Mode for subsequent executions.' }, { name: 'commit', description: 'Optional synchronous commit: validate caller state, invoke the supplied mode writer, then record related changes.' }],
returns: 'Resource-reset notices after the mode event is committed.',
throws: ['On concurrent changes, disposal, or cleanup failure; cleanup failures leave the mode unchanged.'],
},
{
signature: 'registerResource(sessionId: SessionId, resource: SandboxPolicyResource): () => void',
description: 'Register an execution resource under its Session\'s file policy.',
parameters: [{ name: 'sessionId', description: 'Session identity carried in the resolved execution policy.' }, { name: 'resource', description: 'Awaited cleanup and optional reset notice.' }],
returns: 'Disposer for an already stopped resource; contributor unload awaits cleanup before detaching.',
throws: ['While the Session changes mode or this provider is disposed.'],
},
{
signature: 'async withExecution<T>(sessionId: SessionId, signal: AbortSignal, run: (signal: AbortSignal) => Promise<T>): Promise<T>',
description: 'Run one cancellable operation, including asynchronous preparation and final cleanup.',
parameters: [{ name: 'sessionId', description: 'Session whose standing mode applies to the operation.' }, { name: 'signal', description: 'Caller-owned cancellation.' }, { name: 'run', description: 'Operation that observes the combined signal and awaits its own cleanup before settling.' }],
returns: 'The operation\'s result; mode changes await its settlement even when it rejects.',
throws: ['While the Session changes mode or this provider is disposed.'],
},
{
signature: 'overrideOf(session: Session): SandboxMode | undefined',
description: 'Read the session override without applying the deployment default.',
@@ -4260,14 +4281,6 @@ export const EVENT_API: readonly EventApiEntry[] = [
description: 'Waterfall around every streaming model call (retry, replay, routing). Bound to the LlmRuntime; call `next()` to reach the resolved adapter\'s stream, or yield your own chunks to short-circuit.',
parameters: [{ name: 'options', description: 'the full request. A LOOP-built request carries the process-local {@link markAgentLoopRequest} identity and arrives deep-frozen (mutation throws): its content is a pure function of the session log (the reconstructability Agent Note), so listeners read it, never rewrite it. Hand-built calls do not carry that marker; callers own their request inputs and must keep them unchanged until the stream settles.' }],
},
{
name: 'permission-presets/apply',
mode: 'waterfall',
signature: '\'permission-presets/apply\'(session: Session, sandboxMode: SandboxMode, next: () => Promise<string[]>): Promise<string[]>',
summary: 'Wrap a permission change while resources using the old policy are released.',
description: 'Wrap a permission change while resources using the old policy are released. A rejection prevents the preset and its policy events from being recorded.',
parameters: [{ name: 'next', description: 'Commit the validated preset and return change notices.' }, { name: 'session', description: 'Session receiving the new preset.' }, { name: 'sandboxMode', description: 'File policy selected by the preset.' }],
},
{
name: 'permission-presets/catalog-changed',
mode: 'emit',
@@ -6580,6 +6593,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
name: 'SandboxPolicyRequest',
declaration: 'export interface SandboxPolicyRequest {\n session?: Session;\n mode?: SandboxMode;\n}',
},
{
name: 'SandboxPolicyResource',
declaration: 'export interface SandboxPolicyResource {\n release(): Promise<void>;\n notice?: string;\n}',
},
{
name: 'SaveFileAttachment',
declaration: 'export interface SaveFileAttachment {\n data: Uint8Array;\n name?: string;\n}',
@@ -36,8 +36,8 @@
en: 172f5c8af5705ada
zh: b424834e38adb25d
/deepseek-ai-dsh-permission-presets/understand-the-implementation/write-path:
en: 9dbc2c9aa03491a3
zh: b326ab5fb29e94ef
en: 739a2a260dade199
zh: fc53af3d09977191
/deepseek-ai-dsh-permission-presets/understand-the-implementation/read-side-and-custom:
en: c9ca792038f44654
zh: 83cc2641c800c114
@@ -82,7 +82,7 @@ The observable behavior is covered in [Use this package](#use-this-package); thi
### Write path
`set()` resolves the preset and synchronously runs Auto admission when applicable. Transitions append `permission/preset` only when the effective preset changes, then write each changed knob through its canonical setter — `setSandboxMode` from `dsh-sandbox-policy` and `setApprovalPolicy` from `dsh-user-approval`. The selection event therefore preserves user intent when two presets share a bundle. Switching between Auto and Full access records the new identity and the changed approval policy. A net-zero selection appends nothing. Callers await `set()` and receive cleanup notices. The `permission-presets/apply` waterfall holds new PTC admissions until retained execution resources are released and the preset is committed. Cleanup failure leaves permission events unchanged; concurrent changes to one Session reject.
`set()` validates the preset and Auto admission, then awaits `sandboxPolicy.setMode()` when the file policy changes. After cleanup and the sandbox event succeed, it records a changed `permission/preset` identity and approval policy. Callers await completion and receive resource-reset notices; cleanup failure leaves permission events unchanged. Concurrent changes to one Session reject. A net-zero selection appends nothing.
### Read side and `custom`
@@ -82,7 +82,7 @@ kind: "package-reference"
### 写入路径
`set()` 解析预设,并在适用时同步执行 Auto 准入检查。切换仅在有效预设变化时追加 `permission/preset`,再通过各自的权威 setter——`dsh-sandbox-policy` 的 `setSandboxMode` 与 `dsh-user-approval` 的 `setApprovalPolicy`——写入每个变化的旋钮。因此,两个预设共享同一组取值时,选择事件仍会保留用户意图。Auto 与 Full access 之间切换时,记录新的身份与变化的审批策略。净变化为零的选择不追加任何内容。 调用方等待 `set()` 完成,并接收清理提示。`permission-presets/apply` waterfall 在保留执行资源释放和预设提交前阻止新 PTC 调用。清理失败时权限事件保持不变;同一 Session 的并发切换会被拒绝。
`set()` 验证预设与 Auto 准入;文件策略变化时,等待 `sandboxPolicy.setMode()` 完成。清理与沙箱事件提交成功后,记录变化的 `permission/preset` 身份和审批策略。调用方等待完成并接收资源清空提示;清理失败时权限事件保持不变。同一 Session 的并发切换会被拒绝。没有实际变化的选择不追加事件。
### 读取侧与 `custom`
@@ -1,7 +1,7 @@
/**
* User-facing permission presets over the independent sandbox-mode and
* approval-policy knobs. A switch records the selected preset, then writes
* changed knobs through their canonical setters. Execution, prompt narration,
* approval-policy knobs. A switch awaits the file-policy owner, then records
* the selected preset and changed approval policy. Execution, prompt narration,
* and replay keep reading their knob folds. The preset event preserves user
* intent when two presets share a bundle. The Auto review integration may
* publish one fixed, current-session-only preset with a synchronous admission
@@ -22,7 +22,7 @@ import { z as zod } from 'zod'
import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
import { SANDBOX_MODES, setSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
import { SANDBOX_MODES } from '@deepseek-ai/dsh-sandbox-policy'
// Side-effect type import: declaration-merges `ctx.shell` (the capability fact
// `sandboxMode` this service reads), without a value dependency on the seam.
import type {} from '@deepseek-ai/dsh-shell'
@@ -40,18 +40,6 @@ declare module '@deepseek-ai/cordis' {
permissionPresets: PermissionPresetService
}
interface Events {
/**
* Wrap a permission change while resources using the old policy are released.
* A rejection prevents the preset and its policy events from being recorded.
* @param next - Commit the validated preset and return change notices.
* @param session - Session receiving the new preset.
* @param sandboxMode - File policy selected by the preset.
* @returns Notices describing resources invalidated by the change.
* @mode waterfall
*/
'permission-presets/apply'(session: Session, sandboxMode: SandboxMode, next: () => Promise<string[]>): Promise<string[]>
}
}
declare module '@deepseek-ai/dsh-session-projection/types' {
@@ -211,7 +199,7 @@ export class PermissionPresetService extends TypertRemoteService {
defaultPreset: z.string().volatile(),
})
static inject = ['shell', 'approval', 'sessions', 'sessionProjections']
static inject = ['shell', 'approval', 'sessions', 'sessionProjections', 'sandboxPolicy']
private readonly presets: Record<string, PresetSpec>
private readonly changing = new WeakSet<Session>()
@@ -404,8 +392,8 @@ export class PermissionPresetService extends TypertRemoteService {
}
/**
* Record a changed preset, then update each changed knob through its own
* setter. Selecting the effective preset again appends nothing.
* Await file-policy cleanup, then record the changed preset and approval policy.
* Selecting the effective preset again appends nothing.
* @param session - the session the switch belongs to.
* @param name - the preset to switch to; unknown names reject.
* @returns Notices after old execution resources are released and the new preset is recorded.
@@ -417,18 +405,23 @@ export class PermissionPresetService extends TypertRemoteService {
/** Apply one preset through its durable identity and canonical knob setters. */
private async apply(session: Session, name: string, setApproval: (policy: ApprovalPolicy) => void): Promise<string[]> {
const spec = this.resolve(name)
if (name === AUTO_PRESET) this.autoAdmit?.()
const current = this.current(session)
const knobs = this.permissionState(session)
if (this.changing.has(session)) throw new Error('permission: another preset change is still in progress')
this.changing.add(session)
try {
return await this.ctx.waterfall('permission-presets/apply', session, spec.sandbox, () => {
const commit = (writeMode?: () => void): void => {
this.resolve(name)
if (name === AUTO_PRESET) this.autoAdmit?.()
const current = this.current(session)
writeMode?.()
if (current !== name) session.append('permission/preset', { preset: name })
if (spec.sandbox !== (knobs.sandbox ?? this.ctx.shell.sandboxMode)) setSandboxMode(session, spec.sandbox)
if (spec.approval !== (knobs.approval ?? this.ctx.approval.config.policy ?? 'ask')) setApproval(spec.approval)
return Promise.resolve([])
})
const approval = this.permissionState(session).approval ?? this.ctx.approval.config.policy ?? 'ask'
if (spec.approval !== approval) setApproval(spec.approval)
}
if (spec.sandbox !== this.ctx.sandboxPolicy.resolve({ session }).mode) {
return await this.ctx.sandboxPolicy.setMode(session, spec.sandbox, commit)
}
commit()
return []
} finally { this.changing.delete(session) }
}
@@ -453,7 +446,7 @@ export class PermissionPresetService extends TypertRemoteService {
const name = this.defaultPreset
const spec = this.resolve(name)
session.append('permission/preset', { preset: name })
setSandboxMode(session, spec.sandbox)
session.append('sandbox/mode', { mode: spec.sandbox })
setApprovalPolicy(session, spec.approval)
return
}
@@ -463,7 +456,7 @@ export class PermissionPresetService extends TypertRemoteService {
session.append('permission/preset', { preset: effective })
}
if (sandbox === null) {
setSandboxMode(session, this.ctx.shell.sandboxMode as SandboxMode)
session.append('sandbox/mode', { mode: this.ctx.shell.sandboxMode as SandboxMode })
}
if (approval === null) {
setApprovalPolicy(session, this.ctx.approval.config.policy ?? 'ask')
@@ -1,3 +1,4 @@
import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
import { describe, expect, it, vi } from 'vitest'
import { Context } from '@deepseek-ai/cordis'
import SessionStore, {
@@ -23,6 +24,7 @@ async function mounted(options: {
const ctx = new Context()
await ctx.plugin(SessionStore)
if (options.projection !== false) await ctx.plugin(SessionProjectionRegistry)
await ctx.plugin(SandboxPolicyService, { mode: options.bashDefault ?? 'workspace-write' })
ctx.provide('shell', {
sandboxMode: 'bashDefault' in options ? options.bashDefault : 'workspace-write',
resolve() { throw new Error('permission tests do not execute bash') },
@@ -48,6 +50,7 @@ async function mountedStore(options: { approvalDefault?: ApprovalPolicy | undefi
const ctx = new Context()
await ctx.plugin(SessionStore)
await ctx.plugin(SessionProjectionRegistry)
await ctx.plugin(SandboxPolicyService, { mode: 'workspace-write' })
ctx.provide('shell', {
sandboxMode: 'workspace-write',
resolve() { throw new Error('permission tests do not execute bash') },
@@ -132,8 +135,8 @@ describe('PermissionPresetService', () => {
await ctx.permissionPresets.set(session, AUTO_PRESET)
expect(admissions).toBe(1)
expect(session.snapshotEvents().map(event => [event.type, event.data])).toEqual([
['permission/preset', { preset: AUTO_PRESET }],
['sandbox/mode', { mode: 'danger-full-access' }],
['permission/preset', { preset: AUTO_PRESET }],
])
expect(ctx.permissionPresets.current(session)).toBe(AUTO_PRESET)
@@ -228,8 +231,8 @@ describe('PermissionPresetService', () => {
const session = freshSession('sess-set')
await ctx.permissionPresets.set(session, 'danger-full-access')
expect(session.snapshotEvents().map(e => [e.type, e.data])).toEqual([
['permission/preset', { preset: 'danger-full-access' }],
['sandbox/mode', { mode: 'danger-full-access' }],
['permission/preset', { preset: 'danger-full-access' }],
['approval/policy', { policy: 'never' }],
])
})
@@ -251,8 +254,8 @@ describe('PermissionPresetService', () => {
await ctx.permissionPresets.set(session, 'danger-full-access')
const tail = session.snapshotEvents().slice(4)
expect(tail.map(e => [e.type, e.data])).toEqual([
['permission/preset', { preset: 'danger-full-access' }],
['sandbox/mode', { mode: 'danger-full-access' }],
['permission/preset', { preset: 'danger-full-access' }],
])
})
@@ -375,6 +378,7 @@ describe('new-session default', () => {
const ctx = new Context()
await ctx.plugin(SessionStore)
await ctx.plugin(SessionProjectionRegistry)
await ctx.plugin(SandboxPolicyService, { mode: 'workspace-write' })
ctx.provide('shell', {
sandboxMode: 'workspace-write',
resolve() { throw new Error('permission tests do not execute bash') },
@@ -396,6 +400,7 @@ describe('new-session default', () => {
const ctx = new Context()
await ctx.plugin(SessionStore)
await ctx.plugin(SessionProjectionRegistry)
await ctx.plugin(SandboxPolicyService, { mode: 'workspace-write' })
ctx.provide('shell', {
sandboxMode: 'workspace-write',
resolve() { throw new Error('permission tests do not execute bash') },
@@ -456,3 +461,27 @@ describe('new-session default', () => {
expect(ctx.permissionPresets.defaultPreset).toBe('workspace-write')
})
})
it('revalidates Auto after resource cleanup and commits no permission events if its integration disappeared', async () => {
const ctx = await mounted()
const auto = await mountAuto(ctx)
const session = freshSession('auto-disappeared-during-cleanup')
const unregister = ctx.sandboxPolicy.registerResource(session.id, { release: () => auto.dispose() })
try {
await expect(ctx.permissionPresets.set(session, AUTO_PRESET)).rejects.toThrow('unknown preset')
expect(session.snapshotEvents()).toEqual([])
} finally { unregister(); await ctx.fiber.dispose() }
})
it('rechecks approval policy at the commit point after cleanup', async () => {
const ctx = await mounted()
const auto = await mountAuto(ctx)
const session = freshSession('approval-changed-during-cleanup')
const unregister = ctx.sandboxPolicy.registerResource(session.id, { release: async () => {
session.append('approval/policy', { policy: 'never' })
} })
try {
await ctx.permissionPresets.set(session, AUTO_PRESET)
expect(session.snapshotEvents().filter(event => event.type === 'approval/policy').at(-1)?.data.policy).toBe('ask')
} finally { unregister(); await auto.dispose(); await ctx.fiber.dispose() }
})
@@ -1,3 +1,4 @@
import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
/**
* The `permissions` projection unit and the `/permission` command: mounting
* the permission service beside the projection registry serves only the
@@ -30,6 +31,7 @@ async function harness(options: {
const ctx = options.ctx ?? new Context()
await ctx.plugin(SessionStore)
await ctx.plugin(SessionProjectionRegistry)
await ctx.plugin(SandboxPolicyService, { mode: 'workspace-write' })
await ctx.plugin(CommandRuntime)
ctx.provide('shell', {
sandboxMode: 'workspace-write',
@@ -24,8 +24,8 @@
en: c79baab0c0a49ca7
zh: b90b78d0d75280fb
/deepseek-ai-dsh-ptc-runtime-node/use-this-package/in-memory-mode:
en: 30170c2ee6425f9d
zh: 9e86c8f857f9249d
en: e201e2beacc90a4d
zh: 507f1f5a031ba2e2
/deepseek-ai-dsh-ptc-runtime-node/use-this-package/deadlines-and-cancellation:
en: 6014e01f41d1ec22
zh: 33ddebf3cdb1f914
@@ -82,7 +82,7 @@ Each live Agent keeps its own process and top-level variables, functions, and im
Memory is best-effort and never saved to disk. Restart, Agent disposal, provider unload, cancellation, timeout, protocol failure, output overflow, or process exit clears it. Missing variables raise normal reference errors; reacquire handles and recreate declarations. Exceptions in the active evaluation settle once and preserve earlier mutations. Exceptions thrown by callbacks from a completed evaluation are not reported in a later result; await asynchronous work before completing an evaluation. The Session still records programs, tool dispatches and visible results; restoring a Session or forking an Agent starts with empty memory. Each evaluation resets the process working directory to its resolved cwd; program calls to `process.chdir()` do not persist across evaluations. Direct Node access follows the resolved file policy. A retained owner cannot change mode, workspace root or Session identity until its environment is released.
Service consumers pass an object as `stateOwner` to reuse its environment and await `release(owner)` when finished. Requests without an owner run in temporary processes. Permission preset changes stop and await retained environments before recording the new sandbox mode and report the loss of variables. A one-time approved escalation uses a separate environment and awaits its cleanup before returning; it cannot read the standing environment's variables or retain new declarations. Concurrent runs for one owner reject until execution and required cleanup complete; distinct owners may run concurrently. An idle environment has no expiration timer and keeps its process until release or failure. Raw stdout/stderr have no evaluation identity: bytes received during an evaluation share its output budget, even when written by an earlier child process; idle stdout is discarded and idle stderr retains only the bounded diagnostic tail. Await child-process completion before ending an evaluation. Process-exit diagnostics include the exit code and retained stderr tail; idle failures are written to the host logger.
Service consumers pass an object as `stateOwner` to reuse its environment and await `release(owner)` when finished. Requests without an owner run in temporary processes. The runtime registers each Session-owned process with `sandboxPolicy`. Its `setMode()` cancels admitted operations and awaits registered cleanup before recording a changed mode, and returns a variable-reset notice. Permission presets use the same operation. A one-time approved escalation uses a separate environment and awaits its cleanup before returning; it cannot read the standing environment's variables or retain new declarations. Concurrent runs for one owner reject until execution and required cleanup complete; distinct owners may run concurrently. An idle environment has no expiration timer and keeps its process until release or failure. Raw stdout/stderr have no evaluation identity: bytes received during an evaluation share its output budget, even when written by an earlier child process; idle stdout is discarded and idle stderr retains only the bounded diagnostic tail. Await child-process completion before ending an evaluation. Process-exit diagnostics include the exit code and retained stderr tail; idle failures are written to the host logger. If process observation fails during cleanup, releasing the owner retries termination; new runs remain blocked until cleanup succeeds. Pipes that fail to drain after confirmed process exit produce a diagnostic but do not prevent releasing the environment.
### Deadlines and cancellation
@@ -82,7 +82,7 @@ kind: "package-reference"
内存按尽力保留处理,不保存到磁盘。重启、Agent 销毁、提供方卸载、取消、超时、协议失败、输出超限或进程退出都会清除内存。缺失变量产生普通引用错误,模型需要重新获取句柄和创建声明。当前执行中的异常只结算一次,并保留此前发生的修改。已完成执行的回调抛出的异常不会在后续结果中报告;结束执行前应等待异步工作完成。Session 仍记录程序、工具分派和可见结果;恢复 Session 或派生 Agent 时从空内存开始。每次执行都会将进程工作目录重置为本次解析的 cwd;程序中的 `process.chdir()` 不跨执行保留。直接 Node 访问遵循已解析的文件策略。保留状态的所有者必须先释放环境,才能更改权限模式、工作区根目录或 Session 身份。
服务消费者通过 `stateOwner` 对象复用环境,并在结束时等待 `release(owner)`。没有所有者的请求在临时进程中执行。权限预设切换先停止并等待保留环境清理,再记录新沙箱模式,并提示变量已清空。单次获准的提权使用独立环境,返回前等待清理;该次执行无法访问原环境的变量,也不会保留新声明。执行及必要清理完成之前,同一所有者的并发调用会被拒绝;不同所有者可以并发。空闲环境没有过期计时器,进程保留到释放或失败为止。原始 stdout/stderr 不携带执行标识:执行期间收到的字节计入本次输出预算,包括较早启动的子进程此时写出的内容;空闲期间丢弃 stdout,只保留限额内的 stderr 诊断尾部。结束本次执行前,应等待子进程完成。进程退出诊断包含退出码和保留的 stderr 尾部;空闲期间的失败写入宿主日志。
服务消费者通过 `stateOwner` 对象复用环境,并在结束时等待 `release(owner)`。没有所有者的请求在临时进程中执行。运行时向 `sandboxPolicy` 登记每个归属 Session 的进程。`setMode()` 先取消已接纳的操作并等待登记资源清理,再记录变化的模式,并返回变量清空提示。权限预设使用同一个操作。单次获准的提权使用独立环境,返回前等待清理;该次执行无法访问原环境的变量,也不会保留新声明。执行及必要清理完成之前,同一所有者的并发调用会被拒绝;不同所有者可以并发。空闲环境没有过期计时器,进程保留到释放或失败为止。原始 stdout/stderr 不携带执行标识:执行期间收到的字节计入本次输出预算,包括较早启动的子进程此时写出的内容;空闲期间丢弃 stdout,只保留限额内的 stderr 诊断尾部。结束本次执行前,应等待子进程完成。进程退出诊断包含退出码和保留的 stderr 尾部;空闲期间的失败写入宿主日志。清理期间无法观测进程范围时,释放所有者会重试终止;清理成功前拒绝新执行。确认进程退出后仍未排空的管道会产生诊断,但不阻止释放环境。
### 截止时间与取消
@@ -63,8 +63,6 @@ export class NodePtcRuntime extends PtcRuntime {
}, 'Node ptc-runtime cleanup')
}
override get retainsState(): boolean { return this.inMemory !== undefined }
override get sandboxMode(): SandboxMode | undefined { return this.ctx.sandboxPolicy.defaultMode }
override release(owner: object): Promise<void> {
@@ -1,4 +1,5 @@
/** Node PTC in-memory execution with retained processes scoped to caller-owned objects. */
import { AsyncLocalStorage } from 'node:async_hooks'
import { stripTypeScriptTypes } from 'node:module'
import { isAbsolute } from 'node:path'
import { Context } from '@deepseek-ai/cordis'
@@ -29,6 +30,7 @@ interface Evaluation {
data: ProgramBootData
spec: PtcRunSpec
bindings: Map<string, PtcBindingNamespace>
reply: typeof replyToBinding
pending: number
pendingBytes: number
admit(text: string): void
@@ -37,6 +39,7 @@ interface Evaluation {
/** One managed process; all mutable program state belongs to this process alone. */
class Kernel {
private readonly unregister: (() => void) | undefined
private confined: ConfinedArgv | undefined
private handle?: SubprocessHandle
private channel?: JsonChannel
@@ -48,16 +51,24 @@ class Kernel {
private sequence = 0
private nextCall = 1
private stderr = ''
private stopped?: Promise<void>
private stopped: Promise<boolean> | undefined
private starting?: Promise<void>
private exitOutcome?: SubprocessOutcome
private readonly controller = new AbortController()
closed = false
constructor(private readonly ctx: Context, private readonly config: ResolvedConfig, readonly policy: SandboxExecutionPolicy) {}
constructor(
private readonly ctx: Context, private readonly config: ResolvedConfig, readonly policy: SandboxExecutionPolicy, retained: boolean,
) {
this.unregister = policy.sessionId === undefined ? undefined : ctx.sandboxPolicy.registerResource(policy.sessionId, {
release: () => this.dispose(),
...retained ? { notice: 'PTC variables were cleared after the sandbox mode changed. Recreate variables before using them.' } : {},
})
}
assertIdle(): void {
if (this.running || this.cleanupPending) throw new Error('persistent PTC does not accept concurrent runs for one state owner')
if (this.running) throw new Error('persistent PTC does not accept concurrent runs for one state owner')
if (this.cleanupPending) throw new Error('persistent PTC environment cleanup is incomplete; release the owner before running another program')
}
async run(spec: PtcRunSpec, bindings: Map<string, PtcBindingNamespace>, code: string): Promise<PtcRunResult> {
@@ -98,7 +109,7 @@ class Kernel {
data: { code, maxOutputBytes: this.config.maxOutputBytes, namespaces: [...bindings.values()].map(binding => ({
global: binding.global, names: Object.keys(binding.functions), ...binding.errorClass ? { errorClass: binding.errorClass } : {},
})) },
spec, bindings, pending: 0, pendingBytes: 0,
spec, bindings, reply: AsyncLocalStorage.bind(replyToBinding), pending: 0, pendingBytes: 0,
admit: (text) => {
if (!output.admit(text, logs)) {
logs.push(text)
@@ -112,8 +123,10 @@ class Kernel {
this.active = undefined
const outcome = error?.kind === 'output-limit' ? output.limit(logs)
: error ? output.failure(logs, error) : output.success(logs, value)
const cleanup = discard || outcome.error?.kind === 'output-limit' || spec.stateOwner === undefined ? this.stop() : Promise.resolve()
void cleanup.then(() => { result.resolve(outcome) }, (failure: unknown) => {
const cleanup = discard || outcome.error?.kind === 'output-limit' || spec.stateOwner === undefined ? this.stop() : Promise.resolve(true)
void cleanup.then((drained) => {
result.resolve(drained ? outcome : output.failure(logs, { kind: 'worker-exit', message: 'managed process exited but its output did not drain cleanly' }))
}, (failure: unknown) => {
result.resolve(output.failure(logs, { kind: 'worker-exit', message: `managed process cleanup failed: ${messageOf(failure)}` }))
})
},
@@ -134,7 +147,7 @@ class Kernel {
await this.stop()
}
private stop(): Promise<void> {
private stop(): Promise<boolean> {
if (this.stopped) return this.stopped
this.closed = true
this.cleanupPending = true
@@ -143,9 +156,13 @@ class Kernel {
this.stopped = (async () => {
await this.starting?.catch(() => {})
const handle = this.handle
if (!handle) return
if (!await terminateProcess(handle, this.config.graceMs)) throw new Error('persistent Node process output did not close cleanly')
})().then(() => { this.cleanupPending = false })
return handle === undefined || await terminateProcess(handle, this.config.graceMs)
})().then((drained) => {
this.unregister?.()
this.cleanupPending = false
if (!drained) this.ctx.logger.warn('persistent Node process exited but its output did not drain cleanly')
return drained
}, (error: unknown) => { this.stopped = undefined; throw error })
return this.stopped
}
@@ -250,7 +267,7 @@ class Kernel {
const fn = functions && Object.hasOwn(functions, payload.name) ? functions[payload.name] : undefined
const id = payload.id
void (async () => {
const reply = await replyToBinding(id, fn, args).finally(() => {
const reply = await evaluation.reply(id, fn, args).finally(() => {
evaluation.pending -= 1
evaluation.pendingBytes -= bytes
})
@@ -334,7 +351,7 @@ export class InMemoryExecution {
}
if (!kernel || kernel.closed) {
if (kernel) this.kernels.delete(kernel)
kernel = new Kernel(this.ctx, this.config, { ...spec.sandboxPolicy })
kernel = new Kernel(this.ctx, this.config, { ...spec.sandboxPolicy }, spec.stateOwner !== undefined)
this.kernels.add(kernel)
if (spec.stateOwner !== undefined) this.owners.set(spec.stateOwner, kernel)
}
@@ -397,7 +397,7 @@ it('logs an idle process failure with its bounded stderr tail', async () => {
} finally { reported.mockRestore() }
})
it('keeps an owner unavailable after release cleanup fails', async () => {
it('retries process observation before releasing an owner after cleanup fails', async () => {
const h = await setup()
h.onBoot(() => { h.emit(frame({ type: 'done' })) })
await h.start()
@@ -406,11 +406,12 @@ it('keeps an owner unavailable after release cleanup fails', async () => {
await expect(h.runtime.release(request.stateOwner!)).rejects.toBe(failure)
const reported = vi.spyOn(h.fiber.ctx.logger, 'error').mockImplementation(() => {})
try {
await expect(h.runtime.release(request.stateOwner!)).rejects.toBe(failure)
await expect(h.runtime.run(h.runtime.resolve(request))).rejects.toThrow('concurrent runs')
await expect(h.runtime.run(h.runtime.resolve(request))).rejects.toThrow('cleanup is incomplete')
h.waitForExit.mockResolvedValue(true)
await h.runtime.release(request.stateOwner!)
await h.fiber.dispose()
expect(reported).toHaveBeenCalled()
expect(h.waitForExit).toHaveBeenCalledOnce()
expect(reported).not.toHaveBeenCalled()
expect(h.waitForExit).toHaveBeenCalledTimes(2)
} finally { reported.mockRestore() }
})
@@ -424,7 +425,7 @@ it('reserves the owner while parse-output overflow releases its environment', as
const pending = h.runtime.run(h.runtime.resolve({ ...request, program: 'return 1' }))
try {
await cleanup.promise
await expect(h.runtime.run(h.runtime.resolve(request))).rejects.toThrow('concurrent runs')
await expect(h.runtime.run(h.runtime.resolve(request))).rejects.toThrow('cleanup is incomplete')
expect(h.spawn).toHaveBeenCalledOnce()
stopped.resolve(true)
expect((await pending).error?.kind).toBe('output-limit')
@@ -1,18 +1,19 @@
import { mkdtemp, mkdir, readFile, rm } from 'node:fs/promises'
import { homedir } from 'node:os'
import { join } from 'node:path'
import { SessionId } from '@deepseek-ai/dsh-session'
import { Context } from '@deepseek-ai/cordis'
import { SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox'
import { expect, it, onTestFinished, vi } from 'vitest'
import { mountRuntime } from './setup.ts'
async function setup(mode: 'read-only' | 'workspace-write' = 'read-only') {
async function setup(mode: 'read-only' | 'workspace-write' = 'read-only', executionMode: 'per-call' | 'persistent-in-memory' = 'persistent-in-memory') {
const root = await mkdtemp(join(homedir(), '.dsh-persistent-sandbox-'))
const cwd = join(root, 'workspace')
await mkdir(cwd)
const ctx = new Context()
onTestFinished(async () => { await ctx.fiber.dispose(); await rm(root, { recursive: true, force: true }) })
const { runtime } = await mountRuntime(ctx, { executionMode: 'persistent-in-memory' }, { mode, workspaceRoot: cwd })
const { runtime } = await mountRuntime(ctx, { executionMode }, { mode, workspaceRoot: cwd })
const owner = {}
const run = (program: string) => runtime.run(runtime.resolve({ program, bindings: [], stateOwner: owner }))
return { root, cwd, ctx, runtime, owner, run }
@@ -76,3 +77,72 @@ it('cancels a pending confinement operation before spawning', async () => {
spawn.mockRestore()
}
})
it('clears a registered live REPL through the file-policy setter before starting under the new mode', async () => {
const { ctx, cwd, runtime, owner } = await setup('workspace-write')
const session = ctx.sessions.create(SessionId('retained-policy-change'), { meta: { cwd } })
const run = (program: string) => runtime.run(runtime.resolve({
program, bindings: [], stateOwner: owner, sandboxPolicy: ctx.sandboxPolicy.resolve({ session }),
}))
const spawn = vi.spyOn(ctx.subprocess, 'spawn')
onTestFinished(() => { spawn.mockRestore() })
expect((await run('const retained = 7; retained')).value).toBe(7)
const started = spawn.mock.results[0]
if (started?.type !== 'return') throw new Error('the retained process did not start')
expect(await ctx.sandboxPolicy.setMode(session, 'read-only')).toEqual([
'PTC variables were cleared after the sandbox mode changed. Recreate variables before using them.',
])
await started.value.done
expect((await run('typeof retained')).value).toBe('undefined')
const denied = await run('await (await import("node:fs/promises")).writeFile("denied-after-switch.txt", "denied")')
expect(denied.sandbox).toMatchObject({ mode: 'read-only', denied: true })
await expect(readFile(join(cwd, 'denied-after-switch.txt'))).rejects.toMatchObject({ code: 'ENOENT' })
})
it('keeps a one-shot wider policy separate from standing variables and subsequent writes', async () => {
const { ctx, cwd, runtime, owner } = await setup()
const session = ctx.sessions.create(SessionId('temporary-policy'), { meta: { cwd } })
const standing = ctx.sandboxPolicy.resolve({ session })
const run = (program: string) => runtime.run(runtime.resolve({ program, bindings: [], stateOwner: owner, sandboxPolicy: standing }))
expect((await run('const retained = 7; retained')).value).toBe(7)
const result = await runtime.run(runtime.resolve({
program: 'const temporary = 9; await (await import("node:fs/promises")).writeFile("elevated.txt", typeof retained); temporary',
bindings: [], sandboxPolicy: { ...standing, mode: 'danger-full-access' },
}))
expect(result.value).toBe(9)
expect(await readFile(join(cwd, 'elevated.txt'), 'utf8')).toBe('undefined')
expect((await run('({ retained, temporary: typeof temporary })')).value).toEqual({ retained: 7, temporary: 'undefined' })
expect((await run('await (await import("node:fs/promises")).writeFile("denied.txt", "denied")')).sandbox?.denied).toBe(true)
await expect(readFile(join(cwd, 'denied.txt'))).rejects.toMatchObject({ code: 'ENOENT' })
expect(ctx.sandboxPolicy.resolve({ session }).mode).toBe('read-only')
})
it('preserves the current execution context for bindings in a reused REPL', async () => {
const { ctx, cwd, runtime, owner } = await setup('workspace-write')
const session = ctx.sessions.create(SessionId('reentrant-mode-change'), { meta: { cwd } })
const run = (program: string) => ctx.sandboxPolicy.withExecution(session.id, new AbortController().signal, signal =>
runtime.run(runtime.resolve({ program, signal, stateOwner: owner,
sandboxPolicy: ctx.sandboxPolicy.resolve({ session }),
bindings: [{ global: 'tools', functions: { change: () => ctx.sandboxPolicy.setMode(session, 'read-only') } }],
})))
expect((await run('const retained = 7; retained')).value).toBe(7)
const result = await run('await tools.change({})')
expect(result.error?.message).toContain('operation that the change must cancel')
expect(ctx.sandboxPolicy.resolve({ session }).mode).toBe('workspace-write')
expect((await run('retained')).value).toBe(7)
})
it.each(['per-call', 'persistent-in-memory'] as const)('waits for canceled %s execution before changing policy', async (executionMode) => {
const { ctx, cwd, runtime, owner } = await setup('workspace-write', executionMode)
const session = ctx.sessions.create(SessionId(`active-${executionMode}`), { meta: { cwd } })
const entered = Promise.withResolvers<undefined>()
const pending = ctx.sandboxPolicy.withExecution(session.id, new AbortController().signal, signal =>
runtime.run(runtime.resolve({ program: 'await tools.ready({}); await new Promise(() => {})',
signal, stateOwner: owner, sandboxPolicy: ctx.sandboxPolicy.resolve({ session }),
bindings: [{ global: 'tools', functions: { ready: async () => { entered.resolve(undefined); return null } } }],
})))
await entered.promise
await ctx.sandboxPolicy.setMode(session, 'read-only')
expect((await pending).error?.kind).toBe('abort')
expect(ctx.sandboxPolicy.resolve({ session }).mode).toBe('read-only')
})
@@ -229,7 +229,6 @@ describe('persistent Node REPL', () => {
it('resolves confinement and validates options before starting a process', async () => {
const { run, runtime } = await setup()
expect(runtime.sandboxMode).toBe('danger-full-access')
expect(runtime.retainsState).toBe(true)
expect(runtime.programFormat).toBe('repl')
expect(runtime.timeout).toEqual({ defaultMs: 120_000, maxMs: 600_000 })
expect(runtime.resolve({ program: '1', bindings: [], sandboxPolicy: { mode: 'read-only', workspaceRoot: process.cwd() } }).sandboxPolicy?.mode).toBe('read-only')
@@ -21,8 +21,8 @@
en: c856760ebc15d59e
zh: dc093083b29794e0
/deepseek-ai-dsh-ptc-runtime/use-this-package/choose-a-backend:
en: 7e90e1e4859e48aa
zh: d66d362d2f3260ac
en: fc0d515f0c3664f3
zh: 0a1b646b5cf92232
/deepseek-ai-dsh-ptc-runtime/use-this-package/name-your-bindings-portably:
en: 4e46c1672701b8df
zh: 0353c5855c9ff6be
+1 -1
View File
@@ -44,7 +44,7 @@ const result = await ctx.ptcRuntime.run(spec)
Backends expose `language` and `isolation` as diagnostic descriptors; neither grants authority or proves confinement. [`dsh-ptc-runtime-node`](../ptc-runtime-node/README.md) executes erasable TypeScript in a fresh managed Node process under the resolved sandbox policy. The private [`dsh-experimental-ptc-runtime-python`](../../experimental/ptc-runtime-python/README.md) provider executes Python in a fresh CPython subprocess without file confinement. `sandboxMode` advertises a provider's deployment file-policy mode, or is absent when that capability is unsupported.
For the optional [Node in-memory mode](../ptc-runtime-node/README.md#persistent-repl), pass the same `stateOwner` object across runs and await `release(owner)` at the owner's end. Different object identities never share an environment; omitted owners use a temporary environment. `retainsState` identifies providers that retain program memory; stateless providers ignore ownership. Calls for one retained owner must not overlap.
For the optional [Node in-memory mode](../ptc-runtime-node/README.md#persistent-repl), pass the same `stateOwner` object across runs and await `release(owner)` at the owner's end. Different object identities never share an environment; omitted owners use a temporary environment. Stateless providers ignore ownership. Calls for one retained owner must not overlap.
### Name your bindings portably
@@ -44,7 +44,7 @@ const result = await ctx.ptcRuntime.run(spec)
后端以 `language` 与 `isolation` 提供诊断描述符;两者都不授予权限或证明约束。[`dsh-ptc-runtime-node`](../ptc-runtime-node/README.zh.md) 在全新的受管 Node 进程中按已解析沙箱策略执行可擦除 TypeScript。私有的 [`dsh-experimental-ptc-runtime-python`](../../experimental/ptc-runtime-python/README.zh.md) 提供方在全新 CPython 子进程中执行 Python,不提供文件约束。`sandboxMode` 声明提供方的部署文件策略模式;不支持该能力时则缺省。
使用可选的[Node 内存保留模式](../ptc-runtime-node/README.zh.md#persistent-repl)时,跨调用传入同一个 `stateOwner` 对象,并在所有者结束时等待 `release(owner)`。不同对象不会共享环境;省略所有者时使用临时环境。`retainsState` 标明提供方是否保留程序内存;无状态提供方忽略所有权。同一保留环境的调用不能重叠。
使用可选的[Node 内存保留模式](../ptc-runtime-node/README.zh.md#persistent-repl)时,跨调用传入同一个 `stateOwner` 对象,并在所有者结束时等待 `release(owner)`。不同对象不会共享环境;省略所有者时使用临时环境。无状态提供方忽略所有权。同一保留环境的调用不能重叠。
### 可移植地命名绑定
@@ -124,9 +124,6 @@ export abstract class PtcRuntime extends Service {
/** Source evaluation form, independent of whether the provider retains state for an owner. */
get programFormat(): 'function-body' | 'repl' { return 'function-body' }
/** Whether calls with the same state owner can reuse program memory. */
get retainsState(): boolean { return false }
/**
* Release an owner's retained environment and await its execution resources.
* Stateless providers have no retained resources to release.
@@ -24,8 +24,8 @@
en: 01c4f068b702b49e
zh: a78ae88d3af889fe
/deepseek-ai-dsh-sandbox-policy/use-this-package/switching-a-session-s-mode:
en: 957d72691e470e5c
zh: c22a3a750af0e4a3
en: 0c3d46cbdac6baed
zh: 458bd879ffe066f2
/deepseek-ai-dsh-sandbox-policy/use-this-package/failures-and-recovery:
en: 9cef5f64a050f468
zh: 5dc42c148b2c902d
@@ -42,8 +42,8 @@
en: 999ecd77b3857811
zh: 2cc0a0b2aee08c17
/deepseek-ai-dsh-sandbox-policy/understand-the-implementation/source-map:
en: cc7dd675c9915f7d
zh: d719c4f9de39873a
en: 57522c5d497e3559
zh: 3f9ce43eb7df221d
/deepseek-ai-dsh-sandbox-policy/further-exploration:
en: 7b110e18967f2754
zh: 823c261edeae750a
+4 -2
View File
@@ -51,7 +51,9 @@ The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-a
### Switching a session's mode
A session's mode can be switched at runtime through a UI policy control or an explicit switch; the switch is recorded in the session log and takes effect on the session's next confined call. The switch survives restart through replay, and each session keeps its own mode — two sessions never see each other's state. A switched session keeps its immutable workspace cwd as the writable boundary.
Use `await ctx.sandboxPolicy.setMode(session, mode)` for runtime changes. The service cancels admitted operations, waits for registered resources to stop, and then appends the durable `sandbox/mode` event. Cleanup failure preserves the old mode; new reservations and resource registrations reject during the transition. An unchanged effective mode records the override without clearing resources. Permission presets use the same operation. Each Session retains its immutable workspace root, and its selected mode survives restart through replay.
Callers wrap approval, execution and final cleanup with `withExecution(sessionId, signal, run)`. A mode change waits for that complete operation to settle, including nested tools. An operation cannot initiate a mode change that would cancel itself. Providers register live processes with `registerResource(sessionId, resource)` and detach after successful cleanup. Resource cleanup is idempotent and awaited during mode changes or contributor unload. Direct mode-event writes reject while execution or resources are registered.
### Failures and recovery
@@ -84,7 +86,7 @@ The `sandbox:policy` contribution states the mode's capability-neutral file-effe
| File | Role |
|---|---|
| [`src/index.ts`](src/index.ts) | Plugin entry: `SandboxPolicyService`, `Config` schema, policy resolution and context contribution |
| [`src/session-mode.ts`](src/session-mode.ts) | The `sandbox/mode` event, its fold, and the write path |
| [`src/session-mode.ts`](src/session-mode.ts) | The `sandbox/mode` event and accepted mode values |
</details>
+4 -2
View File
@@ -51,7 +51,9 @@ kind: "package-reference"
### 切换会话模式
会话的模式可以在运行时通过 UI 策略控件或显式切换来更改;切换记录在会话日志中,并在该会话的下一次受限调用时生效。切换通过回放跨重启保留,每个会话保持自己的模式——两个会话绝不会看到彼此状态。切换后的会话继续以不可变的工作区 cwd 作为写入边界。
运行时切换使用 `await ctx.sandboxPolicy.setMode(session, mode)`。服务取消已接纳的操作,等待登记资源停止,再追加持久的 `sandbox/mode` 事件。清理失败时保留旧模式;切换期间拒绝新的执行登记和资源登记。有效模式未变化时,记录覆盖值并保留资源。权限预设使用同一个操作。每个 Session 保留不可变的工作区根目录,所选模式通过回放跨重启保留。
调用方通过 `withExecution(sessionId, signal, run)` 包含审批、执行和最终清理。模式切换会等待整个操作完成,包括嵌套工具。操作不能发起会取消自身的模式切换。提供方通过 `registerResource(sessionId, resource)` 登记存活进程,成功清理后移除登记。资源清理必须幂等;模式切换或贡献方卸载时都会等待清理完成。仍有执行或资源登记时,直接写入模式事件会被拒绝。
### 失败与恢复
@@ -84,7 +86,7 @@ kind: "package-reference"
| 文件 | 职责 |
|---|---|
| [`src/index.ts`](src/index.ts) | 插件入口:`SandboxPolicyService`、`Config` schema、策略解析与上下文贡献 |
| [`src/session-mode.ts`](src/session-mode.ts) | `sandbox/mode` 事件、其 fold 与写入路径 |
| [`src/session-mode.ts`](src/session-mode.ts) | `sandbox/mode` 事件与可接受的模式值 |
</details>
+160 -4
View File
@@ -3,8 +3,8 @@
* deployment's sandbox fallbacks plus per-session resolution: the file-effect
* {@link SandboxMode}, the `workspace-write` root, and the override kit (the
* `sandbox/mode` event, its fold, and its write path; the fold is the
* `sandboxMode` session-projection unit registered here, while the event and
* write path come from `./session-mode.ts`).
* `sandboxMode` session-projection unit and asynchronous setter live here;
* `./session-mode.ts` declares the durable event).
* Before each agent request, the owner also contributes the resolved policy to
* the cache-safe runtime-context snapshot. The agent loop logs that snapshot as
* model history, so replay reconstructs the same mode and root the enforcing
@@ -20,17 +20,18 @@
* @module @deepseek-ai/dsh-sandbox-policy
*/
import { AsyncLocalStorage } from 'node:async_hooks'
import { isAbsolute } from 'node:path'
import { Context, Service } from '@deepseek-ai/cordis'
import { z as zod } from 'zod'
import z from '@deepseek-ai/schemastery'
import type {} from '@deepseek-ai/dsh-agent'
import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox'
import type { Session } from '@deepseek-ai/dsh-session'
import type { Session, SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
import type {} from '@deepseek-ai/dsh-session-projection'
import type {} from '@deepseek-ai/dsh-system-prompt'
export { SANDBOX_MODES, setSandboxMode } from './session-mode.ts'
export { SANDBOX_MODES } from './session-mode.ts'
/** Preserve execution-world spelling; enforcing providers resolve filesystem identity on their host. */
function resolveWorkspaceRoot(path: string): string {
@@ -86,6 +87,20 @@ export interface SandboxPolicyRequest {
mode?: SandboxMode
}
/** A process or retained environment that must stop before its Session changes file policy. */
export interface SandboxPolicyResource {
/** Idempotently stop the resource and await cleanup; rejection prevents the policy change. */
release(): Promise<void>
/** User-facing consequence reported after a successful policy change. */
notice?: string
}
interface Execution {
sessionId: SessionId
controller: AbortController
done: Promise<void>
}
/** The sandbox-mode projection's state schema (state equals the public shape). */
const sandboxModeStateSchema = zod.union([
zod.literal('read-only'),
@@ -122,6 +137,13 @@ export class SandboxPolicyService extends Service {
readonly defaultMode: SandboxMode
/** The absolute `workspace-write` fallback root for calls without a session cwd. */
readonly workspaceRoot: string
private readonly resources = new Map<SessionId, Set<SandboxPolicyResource>>()
private readonly executions = new Map<SessionId, Set<Execution>>()
private readonly activeExecution = new AsyncLocalStorage<Execution>()
private readonly changing = new Set<SessionId>()
private readonly committing = new Set<SessionId>()
private disposed = false
constructor(ctx: Context, config: Config) {
super(ctx, 'sandboxPolicy')
// schemastery (static Config) already filled `mode`; the cast records that
@@ -129,6 +151,27 @@ export class SandboxPolicyService extends Service {
// the process cwd is real branching, resolved absolute either way.
this.defaultMode = config.mode as SandboxMode
this.workspaceRoot = resolveWorkspaceRoot(config.workspaceRoot ?? process.cwd())
ctx.effect(() => async () => {
this.disposed = true
for (const executions of this.executions.values()) {
for (const execution of executions) execution.controller.abort(new Error('sandbox policy is disposed'))
}
const results = await Promise.allSettled([...this.resources.values()].flatMap(resources =>
[...resources].map(resource => resource.release())))
const failure = results.find(result => result.status === 'rejected')
if (failure?.status === 'rejected') throw failure.reason
this.resources.clear()
this.executions.clear()
}, 'sandbox policy lifecycle')
ctx.on('internal/dispatch', (_mode, name, args) => {
if (name !== 'session/event') return
const [session, event] = args as [Session, SessionEvent]
if (event.type !== 'sandbox/mode' || this.committing.has(session.id)) return
if (!this.resources.has(session.id) && !this.executions.has(session.id) && !this.changing.has(session.id)) return
if (event.data.mode !== this.resolve({ session }).mode) {
throw new Error('sandbox resources are still registered; await sandboxPolicy.setMode() to change the mode')
}
}, { global: true })
ctx.sessionProjections.register({
key: 'sandboxMode',
@@ -170,6 +213,119 @@ export class SandboxPolicyService extends Service {
}
}
/**
* Cancel admitted operations and release registered resources before recording a new mode.
* An unchanged effective mode records the override without clearing resources.
* @param session - Session whose file policy changes.
* @param mode - Mode for subsequent executions.
* @param commit - Optional synchronous commit: validate caller state, invoke the supplied mode writer, then record related changes.
* @returns Resource-reset notices after the mode event is committed.
* @throws On concurrent changes, disposal, or cleanup failure; cleanup failures leave the mode unchanged.
*/
async setMode(session: Session, mode: SandboxMode, commit?: (writeMode: () => void) => void): Promise<string[]> {
this.assertAvailable(session.id)
const changed = this.resolve({ session }).mode !== mode
const active = this.activeExecution.getStore()
if (changed && active?.sessionId === session.id && this.executions.get(session.id)?.has(active)) {
throw new Error('sandbox mode cannot change from an operation that the change must cancel')
}
this.changing.add(session.id)
try {
const notices: string[] = []
if (changed) {
const executions = [...this.executions.get(session.id) ?? []]
for (const execution of executions) execution.controller.abort(new Error('sandbox mode is changing'))
const resources = [...this.resources.get(session.id) ?? []]
const pending = [
...executions.map(execution => execution.done.then(() => undefined)),
...resources.map(async (resource) => { await resource.release(); return resource.notice }),
]
if (pending.length > 0) {
const results = await Promise.allSettled(pending)
const failure = results.find(result => result.status === 'rejected')
if (failure?.status === 'rejected') throw failure.reason
for (const result of results) {
if (result.status === 'fulfilled' && result.value !== undefined) notices.push(result.value)
}
if (this.disposed) throw new Error('sandbox policy was disposed during the mode change')
}
}
const writeMode = (): void => {
this.committing.add(session.id)
try { session.append('sandbox/mode', { mode }) } finally { this.committing.delete(session.id) }
}
if (commit === undefined) writeMode()
else commit(writeMode)
return [...new Set(notices)]
} finally { this.changing.delete(session.id) }
}
/**
* Register an execution resource under its Session's file policy.
* @param sessionId - Session identity carried in the resolved execution policy.
* @param resource - Awaited cleanup and optional reset notice.
* @returns Disposer for an already stopped resource; contributor unload awaits cleanup before detaching.
* @throws While the Session changes mode or this provider is disposed.
*/
registerResource(sessionId: SessionId, resource: SandboxPolicyResource): () => void {
this.assertAvailable(sessionId)
let resources = this.resources.get(sessionId)
if (resources === undefined) this.resources.set(sessionId, resources = new Set())
const detach = (): void => {
resources.delete(resource)
if (resources.size === 0 && this.resources.get(sessionId) === resources) this.resources.delete(sessionId)
}
const unregister = this.ctx.effect(() => {
resources.add(resource)
return async () => {
if (resources.has(resource)) await resource.release()
detach()
}
}, 'sandbox execution resource')
return () => {
detach()
// Explicit removal follows successful cleanup; the effect then only detaches.
void unregister()
}
}
/**
* Run one cancellable operation, including asynchronous preparation and final cleanup.
* @param sessionId - Session whose standing mode applies to the operation.
* @param signal - Caller-owned cancellation.
* @param run - Operation that observes the combined signal and awaits its own cleanup before settling.
* @returns The operation's result; mode changes await its settlement even when it rejects.
* @throws While the Session changes mode or this provider is disposed.
*/
async withExecution<T>(sessionId: SessionId, signal: AbortSignal, run: (signal: AbortSignal) => Promise<T>): Promise<T> {
this.assertAvailable(sessionId)
const controller = new AbortController()
const done = Promise.withResolvers<undefined>()
const execution = { sessionId, controller, done: done.promise }
const release = this.ctx.effect(() => {
let executions = this.executions.get(sessionId)
if (executions === undefined) this.executions.set(sessionId, executions = new Set())
executions.add(execution)
return () => {
controller.abort(new Error('sandbox execution scope released'))
}
}, 'sandbox execution scope')
try {
return await this.activeExecution.run(execution, () => run(AbortSignal.any([signal, controller.signal])))
} finally {
const executions = this.executions.get(sessionId)
executions?.delete(execution)
if (executions?.size === 0) this.executions.delete(sessionId)
done.resolve(undefined)
release()
}
}
private assertAvailable(sessionId: SessionId): void {
if (this.disposed) throw new Error('sandbox policy is disposed')
if (this.changing.has(sessionId)) throw new Error('sandbox mode change is still in progress')
}
/**
* Read the session override without applying the deployment default.
* @param session - session whose log supplies the override.
@@ -18,7 +18,6 @@
* @module dsh-sandbox-policy/session-mode
*/
import type { Session } from '@deepseek-ai/dsh-session'
import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
declare module '@deepseek-ai/dsh-session/types' {
@@ -40,16 +39,3 @@ declare module '@deepseek-ai/dsh-session/types' {
/** Every {@link SandboxMode}, for option advertisement and runtime validation of untrusted mode strings. */
export const SANDBOX_MODES: readonly SandboxMode[] = ['read-only', 'workspace-write', 'danger-full-access']
/**
* THE write path for a session's sandbox-mode override: appends exactly one
* `sandbox/mode` event — the switch IS its event; nothing mutates mode state
* out of band. Takes effect on the session's next confined call (bash or fs)
* — consumers read the shared projection state.
* @param session - the session the override belongs to.
* @param mode - the mode every subsequent confined call in this session runs
* under (until the next switch).
*/
export function setSandboxMode(session: Session, mode: SandboxMode): void {
session.append('sandbox/mode', { mode })
}
@@ -0,0 +1,174 @@
import { Context } from '@deepseek-ai/cordis'
import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
import SessionProjections from '@deepseek-ai/dsh-session-projection'
import { expect, it, onTestFinished, vi } from 'vitest'
import SandboxPolicy from '../src/index.ts'
async function setup() {
const ctx = new Context()
onTestFinished(async () => { await ctx.fiber.dispose() })
await ctx.plugin(SessionStore)
await ctx.plugin(SessionProjections)
const fiber = await ctx.plugin(SandboxPolicy, { mode: 'workspace-write' })
const session = ctx.sessions.create(SessionId('mode-change'))
return { ctx, fiber, session, policy: ctx.sandboxPolicy }
}
it('waits for both resources and complete operations before recording a new mode', async () => {
const { session, policy } = await setup()
const resourceEntered = Promise.withResolvers<undefined>()
const resourceDone = Promise.withResolvers<undefined>()
const operationDone = Promise.withResolvers<undefined>()
const observed = Promise.withResolvers<AbortSignal>()
const unregister = policy.registerResource(session.id, {
release: async () => { resourceEntered.resolve(undefined); await resourceDone.promise }, notice: 'variables cleared',
})
const operation = policy.withExecution(session.id, new AbortController().signal, async (signal) => {
observed.resolve(signal)
await operationDone.promise
return 7
})
const signal = await observed.promise
const switching = policy.setMode(session, 'read-only')
try {
await resourceEntered.promise
expect(signal.aborted).toBe(true)
resourceDone.resolve(undefined)
await expect(policy.withExecution(session.id, new AbortController().signal, async () => 0)).rejects.toThrow('still in progress')
expect(() => policy.registerResource(session.id, { release: async () => {} })).toThrow('still in progress')
await expect(policy.setMode(session, 'danger-full-access')).rejects.toThrow('still in progress')
expect(session.snapshotEvents()).toEqual([])
operationDone.resolve(undefined)
expect(await operation).toBe(7)
expect(await switching).toEqual(['variables cleared'])
expect(policy.resolve({ session }).mode).toBe('read-only')
} finally {
resourceDone.resolve(undefined)
operationDone.resolve(undefined)
await Promise.allSettled([switching, operation])
unregister()
}
})
it('waits for sibling cleanup after a failure and preserves the old policy', async () => {
const { session, policy } = await setup()
const entered = Promise.withResolvers<undefined>()
const done = Promise.withResolvers<undefined>()
const first = policy.registerResource(session.id, { release: () => Promise.reject(new Error('cleanup failed')) })
const second = policy.registerResource(session.id, { release: async () => { entered.resolve(undefined); await done.promise } })
const switching = policy.setMode(session, 'read-only')
const rejected = expect(switching).rejects.toThrow('cleanup failed')
try {
await entered.promise
await expect(policy.withExecution(session.id, new AbortController().signal, async () => 0)).rejects.toThrow('still in progress')
done.resolve(undefined)
await rejected
expect(session.snapshotEvents()).toEqual([])
expect(policy.resolve({ session }).mode).toBe('workspace-write')
} finally { done.resolve(undefined); await Promise.allSettled([switching]); first(); second() }
})
it('keeps unchanged modes and other Sessions independent and deduplicates notices', async () => {
const { ctx, session, policy } = await setup()
const release = vi.fn(async () => {})
const first = policy.registerResource(session.id, { release, notice: 'variables cleared' })
const second = policy.registerResource(session.id, { release, notice: 'variables cleared' })
const third = policy.registerResource(session.id, { release })
try {
expect(await policy.setMode(session, 'workspace-write')).toEqual([])
const other = ctx.sessions.create(SessionId('other-mode-change'))
expect(await policy.setMode(other, 'read-only')).toEqual([])
expect(release).not.toHaveBeenCalled()
expect(await policy.setMode(session, 'read-only')).toEqual(['variables cleared'])
expect(release).toHaveBeenCalledTimes(3)
} finally { first(); second(); third() }
})
it('rejects direct mode appends while execution or resources are registered', async () => {
const { session, policy } = await setup()
await policy.withExecution(session.id, new AbortController().signal, async () => {
expect(() => { session.append('sandbox/mode', { mode: 'read-only' }) }).toThrow('await sandboxPolicy.setMode()')
session.append('sandbox/mode', { mode: 'workspace-write' })
session.append('turn/start', { turn: 1 })
await expect(policy.setMode(session, 'read-only')).rejects.toThrow('operation that the change must cancel')
expect(await policy.setMode(session, 'workspace-write')).toEqual([])
})
const unregister = policy.registerResource(session.id, { release: async () => {} })
expect(() => { session.append('sandbox/mode', { mode: 'read-only' }) }).toThrow('await sandboxPolicy.setMode()')
unregister()
session.append('sandbox/mode', { mode: 'read-only' })
expect(policy.resolve({ session }).mode).toBe('read-only')
})
it('releases a contributor resource before detaching its registration', async () => {
const { ctx, session, policy } = await setup()
const entered = Promise.withResolvers<undefined>()
const done = Promise.withResolvers<undefined>()
const contributor = await ctx.plugin((child) => {
child.sandboxPolicy.registerResource(session.id, { release: async () => { entered.resolve(undefined); await done.promise } })
})
const disposing = contributor.dispose()
try {
await entered.promise
expect(() => { session.append('sandbox/mode', { mode: 'read-only' }) }).toThrow('await sandboxPolicy.setMode()')
done.resolve(undefined)
await disposing
expect(await policy.setMode(session, 'read-only')).toEqual([])
} finally { done.resolve(undefined); await disposing }
})
it('cancels operations on provider unload and rejects new calls through the old service', async () => {
const { ctx, session, policy, fiber } = await setup()
const entered = Promise.withResolvers<AbortSignal>()
const done = Promise.withResolvers<undefined>()
const operation = policy.withExecution(session.id, new AbortController().signal, async (signal) => {
entered.resolve(signal)
await done.promise
})
const signal = await entered.promise
try {
await fiber.dispose()
expect(ctx.get('sandboxPolicy')).toBeUndefined()
expect(signal.aborted).toBe(true)
await expect(policy.withExecution(session.id, signal, async () => 0)).rejects.toThrow('disposed')
await expect(policy.setMode(session, 'read-only')).rejects.toThrow('disposed')
session.append('sandbox/mode', { mode: 'read-only' })
} finally { done.resolve(undefined); await operation }
})
it('refuses a mode commit after disposal during cleanup', async () => {
const { session, policy, fiber } = await setup()
const entered = Promise.withResolvers<undefined>()
const disposalEntered = Promise.withResolvers<undefined>()
const done = Promise.withResolvers<undefined>()
let calls = 0
const unregister = policy.registerResource(session.id, { release: async () => {
if (++calls === 1) entered.resolve(undefined)
else disposalEntered.resolve(undefined)
await done.promise
} })
const switching = policy.setMode(session, 'read-only')
const rejected = expect(switching).rejects.toThrow('disposed during the mode change')
await entered.promise
const disposing = fiber.dispose()
try {
await disposalEntered.promise
done.resolve(undefined)
await rejected
await disposing
expect(session.snapshotEvents()).toEqual([])
} finally { done.resolve(undefined); await Promise.allSettled([switching, disposing]); unregister() }
})
it('revalidates caller state after cleanup before committing related events', async () => {
const { session, policy } = await setup()
let available = true
const unregister = policy.registerResource(session.id, { release: async () => { available = false } })
try {
await expect(policy.setMode(session, 'read-only', (writeMode) => {
if (!available) throw new Error('selection is no longer available')
writeMode()
})).rejects.toThrow('selection is no longer available')
expect(session.snapshotEvents()).toEqual([])
} finally { unregister() }
})
@@ -11,7 +11,7 @@ import { describe, expect, it } from 'vitest'
import { Context } from '@deepseek-ai/cordis'
import type { Agent } from '@deepseek-ai/dsh-agent'
import { SESSION_FORMAT_VERSION, Session, SessionId } from '@deepseek-ai/dsh-session'
import SandboxPolicyService, { SANDBOX_MODES, setSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
import SandboxPolicyService, { SANDBOX_MODES } from '@deepseek-ai/dsh-sandbox-policy'
import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
import SystemPrompt, { renderContextSnapshot, renderPrompt } from '@deepseek-ai/dsh-system-prompt'
@@ -79,7 +79,7 @@ describe('SandboxPolicyService', () => {
const ctx = await mounted({ mode: 'workspace-write', workspaceRoot: '/fallback' })
const first = session('sess-first', '/projects/first')
const second = session('sess-second', '/projects/second')
setSandboxMode(second, 'read-only')
await ctx.sandboxPolicy.setMode(second, 'read-only')
expect(ctx.sandboxPolicy.resolve({ session: first })).toEqual({
mode: 'workspace-write',
@@ -125,7 +125,7 @@ describe('SandboxPolicyService', () => {
it('lets an approved mode outrank the session mode while retaining its root', async () => {
const ctx = await mounted({ workspaceRoot: '/fallback' })
const active = session('sess-approved', '/projects/approved')
setSandboxMode(active, 'read-only')
await ctx.sandboxPolicy.setMode(active, 'read-only')
expect(ctx.sandboxPolicy.resolve({ session: active, mode: 'danger-full-access' })).toEqual({
mode: 'danger-full-access',
workspaceRoot: '/projects/approved',
@@ -207,20 +207,20 @@ describe('sandbox:policy request context', () => {
const first = await policyContext(ctx, active)
expect(await policyContext(ctx, active)).toBe(first)
setSandboxMode(active, 'danger-full-access')
await ctx.sandboxPolicy.setMode(active, 'danger-full-access')
const danger = await policyContext(ctx, active)
expect(danger).toBe('Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.')
expect(await policyContext(ctx, active)).toBe(danger)
setSandboxMode(active, 'workspace-write')
await ctx.sandboxPolicy.setMode(active, 'workspace-write')
expect(await policyContext(ctx, active)).toBe(`Current DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: ${JSON.stringify('/projects/current')}. Some platform temporary areas may also be writable.`)
})
it('reconstructs resumed policy from the session log and omits diagnostics without an agent', async () => {
const active = session('sess-resume', '/projects/current')
setSandboxMode(active, 'workspace-write')
const resumed = Session.create(active.id, active.snapshotEvents(), active.header)
const ctx = await promptMounted({ mode: 'read-only' })
const active = session('sess-resume', '/projects/current')
await ctx.sandboxPolicy.setMode(active, 'workspace-write')
const resumed = Session.create(active.id, active.snapshotEvents(), active.header)
expect(await policyContext(ctx, resumed)).toContain('workspace-write')
expect((await ctx.systemPrompt.assemble()).contexts.find(context => context.name === 'sandbox:policy')?.text).toBe('')
@@ -236,14 +236,15 @@ describe('the sandbox/mode session kit', () => {
const ctx = await mounted()
const session = Session.create(SessionId('sess-fold'))
expect(ctx.sessionProjections.stateOf(session, 'sandboxMode')).toBeNull()
setSandboxMode(session, 'workspace-write')
setSandboxMode(session, 'read-only')
await ctx.sandboxPolicy.setMode(session, 'workspace-write')
await ctx.sandboxPolicy.setMode(session, 'read-only')
expect(ctx.sessionProjections.stateOf(session, 'sandboxMode')).toBe('read-only')
})
it('setSandboxMode appends exactly one sandbox/mode event per switch', () => {
it('setMode appends exactly one sandbox/mode event per switch', async () => {
const ctx = await mounted()
const session = Session.create(SessionId('sess-write'))
setSandboxMode(session, 'danger-full-access')
await ctx.sandboxPolicy.setMode(session, 'danger-full-access')
const modeEvents = session.snapshotEvents().filter(e => e.type === 'sandbox/mode')
expect(modeEvents).toHaveLength(1)
expect(modeEvents[0]?.data).toEqual({ mode: 'danger-full-access' })
@@ -6,7 +6,7 @@ import { Context } from '@deepseek-ai/cordis'
import { createUserMessage } from '@deepseek-ai/dsh-llm'
import { Session, SessionId } from '@deepseek-ai/dsh-session'
import { mountAgentLoopTestDependencies, mountAgentLoopTestHarness } from '@deepseek-ai/dsh-agent-loop-testkit'
import SandboxPolicy, { setSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
import SandboxPolicy from '@deepseek-ai/dsh-sandbox-policy'
import ApprovalService from '@deepseek-ai/dsh-user-approval'
import { describe, expect, it, vi } from 'vitest'
import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
@@ -32,7 +32,7 @@ describe.each(['pre-step', 'prepareCall'] as const)('%s context changes', (phase
if (changed) return
changed = true
await ctx.workingDirectory.set(agent, selected)
setSandboxMode(agent.session, 'danger-full-access')
await ctx.sandboxPolicy.setMode(agent.session, 'danger-full-access')
ctx.approval.setPolicy(agent, 'ask')
}
if (phase === 'pre-step') {
@@ -14,7 +14,7 @@ import AgentLoop from '@deepseek-ai/dsh-agent-loop'
import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
import SandboxedFileSystem from '@deepseek-ai/dsh-fs-sandbox'
import type { ContentBlock } from '@deepseek-ai/dsh-llm'
import SandboxPolicyService, { setSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
import { Session, SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
import ApprovalService from '@deepseek-ai/dsh-user-approval'
@@ -82,7 +82,7 @@ describe('in-process policy inheritance', () => {
async (preset) => {
const { ctx, parent } = await setupWalled([textResponse('child done')])
parent.session.append('permission/preset', { preset })
setSandboxMode(parent.session, 'danger-full-access')
await ctx.sandboxPolicy.setMode(parent.session, 'danger-full-access')
ctx.provide('permissionPresets', {
current: (session: Session) => session === parent.session ? preset : 'custom',
} as never)
@@ -108,7 +108,7 @@ describe('in-process policy inheritance', () => {
] as const)('captures $preset before child creation and overrides the $seedPreset fork prefix', async ({ seedPreset, preset }) => {
const { ctx, parent } = await setupWalled([textResponse('child done')])
parent.session.append('permission/preset', { preset: seedPreset })
setSandboxMode(parent.session, 'danger-full-access')
await ctx.sandboxPolicy.setMode(parent.session, 'danger-full-access')
const seed = parent.session.snapshotEvents()
parent.session.append('permission/preset', { preset })
let currentPreset: 'auto' | 'danger-full-access' = preset
@@ -136,7 +136,7 @@ describe('in-process policy inheritance', () => {
const script: Script = []
const { ctx, parent } = await setupWalled(script)
const blocked = join(workspace, 'spawn-blocked.txt')
setSandboxMode(parent.session, 'read-only')
await ctx.sandboxPolicy.setMode(parent.session, 'read-only')
// No parent approval override: the child pin must not depend on one.
expect(ctx.approval.overrideOf(parent.session)).toBeUndefined()
const parentLogLength = parent.session.snapshotEvents().length
@@ -204,9 +204,9 @@ describe('in-process policy inheritance', () => {
const script: Script = []
const { ctx, parent } = await setupWalled(script)
const blocked = join(workspace, 'fork-blocked.txt')
setSandboxMode(parent.session, 'workspace-write')
await ctx.sandboxPolicy.setMode(parent.session, 'workspace-write')
const seed = parent.session.snapshotEvents()
setSandboxMode(parent.session, 'read-only')
await ctx.sandboxPolicy.setMode(parent.session, 'read-only')
script.push(
toolCallResponse('write', 'write', { file_path: blocked, content: 'escaped' }),
textResponse('child done'),
@@ -228,7 +228,7 @@ describe('in-process policy inheritance', () => {
await expect(readFile(blocked, 'utf8')).rejects.toMatchObject({ code: 'ENOENT' })
expect(ctx.sandboxPolicy.overrideOf(child.session)).toBe('read-only')
setSandboxMode(child.session, 'danger-full-access')
await ctx.sandboxPolicy.setMode(child.session, 'danger-full-access')
expect(ctx.sandboxPolicy.overrideOf(child.session)).toBe('danger-full-access')
} finally {
await run.dispose()
@@ -238,10 +238,10 @@ describe('in-process policy inheritance', () => {
it('captures policy at delegation before asynchronous child creation', async () => {
const script: Script = [textResponse('child done')]
const { ctx, parent } = await setupWalled(script)
setSandboxMode(parent.session, 'read-only')
await ctx.sandboxPolicy.setMode(parent.session, 'read-only')
const starting = startPreparedActivation(spawnRequest(parent), {})
setSandboxMode(parent.session, 'danger-full-access')
await ctx.sandboxPolicy.setMode(parent.session, 'danger-full-access')
const run = await starting
try {
await run.result
@@ -287,7 +287,7 @@ describe('in-process policy inheritance', () => {
return Promise.resolve('allowed-once' as const)
})
const blocked = join(workspace, 'escalation-blocked.txt')
setSandboxMode(parent.session, 'read-only')
await ctx.sandboxPolicy.setMode(parent.session, 'read-only')
script.push(
toolCallResponse('write', 'write', {
file_path: blocked,
@@ -16,7 +16,7 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
import AgentLoop from '@deepseek-ai/dsh-agent-loop'
import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
import { createUserMessage } from '@deepseek-ai/dsh-llm'
import SandboxPolicyService, { setSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
import { Session, SessionId } from '@deepseek-ai/dsh-session'
import type { SessionEvent } from '@deepseek-ai/dsh-session'
import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
@@ -94,7 +94,7 @@ describe('continuable policy inheritance', () => {
async (preset) => {
const { ctx, parent } = await setup([textResponse('child done'), textResponse('resumed child done')])
parent.session.append('permission/preset', { preset })
setSandboxMode(parent.session, 'danger-full-access')
await ctx.sandboxPolicy.setMode(parent.session, 'danger-full-access')
const current = vi.fn((session: Session) => session === parent.session ? preset : 'custom')
ctx.provide('permissionPresets', { current } as never)
@@ -133,7 +133,7 @@ describe('continuable policy inheritance', () => {
] as const)('captures $preset before child creation and overrides the $seedPreset fork prefix', { timeout: 20_000 }, async ({ seedPreset, preset }) => {
const { ctx, parent } = await setup([textResponse('parent turn'), textResponse('forked child')])
parent.session.append('permission/preset', { preset: seedPreset })
setSandboxMode(parent.session, 'danger-full-access')
await ctx.sandboxPolicy.setMode(parent.session, 'danger-full-access')
parent.followup(createUserMessage({
content: [{ type: 'text', text: 'parent work' }],
source: { kind: 'user' },
@@ -159,7 +159,7 @@ describe('continuable policy inheritance', () => {
it('seeds the parent sandbox override and pins approval to never', { timeout: 20_000 }, async () => {
const { ctx, parent } = await setup([textResponse('child done')])
setSandboxMode(parent.session, 'danger-full-access')
await ctx.sandboxPolicy.setMode(parent.session, 'danger-full-access')
// No parent approval override: the child pin must not depend on one.
expect(ctx.approval.overrideOf(parent.session)).toBeUndefined()
let child: Agent | undefined
@@ -196,12 +196,12 @@ describe('continuable policy inheritance', () => {
it('captures policy at delegation before asynchronous child creation', { timeout: 20_000 }, async () => {
const { ctx, parent } = await setup([textResponse('child done')])
setSandboxMode(parent.session, 'read-only')
await ctx.sandboxPolicy.setMode(parent.session, 'read-only')
const starting = ctx.subagents.startActivation({ ...startSpec(parent), delivery: 'parent' })
// A parent switch after the synchronous capture belongs to the parent's
// future, not to this child.
setSandboxMode(parent.session, 'danger-full-access')
await ctx.sandboxPolicy.setMode(parent.session, 'danger-full-access')
const started = await starting
await waitNoActivation(ctx, started.childId)
@@ -244,7 +244,7 @@ describe('continuable policy inheritance', () => {
it('lets a later child-side switch win over the delegation snapshot', { timeout: 20_000 }, async () => {
const { ctx, parent } = await setup([textResponse('child done')])
setSandboxMode(parent.session, 'danger-full-access')
await ctx.sandboxPolicy.setMode(parent.session, 'danger-full-access')
let child: Agent | undefined
ctx.on('agent/created', ({ agent }) => {
if (agent !== parent) child = agent
@@ -254,7 +254,7 @@ describe('continuable policy inheritance', () => {
if (child === undefined) throw new Error('expected the continuable child to be created')
expect(ctx.sandboxPolicy.overrideOf(child.session)).toBe('danger-full-access')
// Last event wins: the child's own runtime switch beats the seeded snapshot.
setSandboxMode(child.session, 'read-only')
await ctx.sandboxPolicy.setMode(child.session, 'read-only')
expect(ctx.sandboxPolicy.overrideOf(child.session)).toBe('read-only')
await waitNoActivation(ctx, started.childId)
@@ -264,13 +264,13 @@ describe('continuable policy inheritance', () => {
it('cold-resumes on the persisted snapshot without re-capturing the parent', { timeout: 20_000 }, async () => {
const { ctx, parent } = await setup([textResponse('first'), textResponse('after resume')])
setSandboxMode(parent.session, 'read-only')
await ctx.sandboxPolicy.setMode(parent.session, 'read-only')
const started = await ctx.subagents.startActivation({ ...startSpec(parent), delivery: 'parent' })
await waitNoActivation(ctx, started.childId)
// The parent widens AFTER the child was created; the resumed child keeps
// the delegation-time snapshot from its own log.
setSandboxMode(parent.session, 'danger-full-access')
await ctx.sandboxPolicy.setMode(parent.session, 'danger-full-access')
await queueHostSubagentPrompt(
ctx.subagents,
parent,
@@ -295,13 +295,13 @@ describe('continuable policy inheritance', () => {
it('places inherited events after a fork prefix so fresh policy wins stale seed state', { timeout: 20_000 }, async () => {
const { ctx, parent } = await setup([textResponse('parent turn'), textResponse('forked child')])
// The stale mode lands inside the completed turn the fork seed replays.
setSandboxMode(parent.session, 'workspace-write')
await ctx.sandboxPolicy.setMode(parent.session, 'workspace-write')
parent.followup(createUserMessage({
content: [{ type: 'text', text: 'parent work' }],
source: { kind: 'user' },
}))
await parent.whenIdle()
setSandboxMode(parent.session, 'read-only')
await ctx.sandboxPolicy.setMode(parent.session, 'read-only')
const started = await ctx.subagents.startActivation({ ...startSpec(parent, 'fork'), delivery: 'parent' })
await waitNoActivation(ctx, started.childId)
@@ -8,7 +8,7 @@ import SessionStore, { SESSION_FORMAT_VERSION, Session, SessionId } from '@deeps
import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
import SandboxProvider from '@deepseek-ai/dsh-sandbox'
import type { ConfinedArgv, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
import SandboxPolicyService, { setSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
import TerminalSessionService, { TerminalBackendCleanupError, TerminalSessionId } from '@deepseek-ai/dsh-terminal'
import type { TerminalSendRequest, TerminalWaitReason } from '@deepseek-ai/dsh-terminal'
@@ -319,7 +319,7 @@ describe('BashTerminalBackend startup rollback', () => {
() => session,
)
const owner = agent(ctx, '/session-workspace')
setSandboxMode(owner.session, 'workspace-write')
await ctx.sandboxPolicy.setMode(owner.session, 'workspace-write')
expect(await backend.spawn(spec(owner))).toBe(session)
expect(spawned).toMatchObject({
@@ -658,7 +658,7 @@ describe('terminal-bash plugin shape', () => {
expect(() => {
session.append('turn/start', { turn: 1 })
}).not.toThrow()
expect(() => { setSandboxMode(session, 'read-only') }).not.toThrow()
await expect(ctx.sandboxPolicy.setMode(session, 'read-only')).resolves.toEqual([])
})
it('keeps the owner-lifetime sandbox fence after the local provider unloads', async () => {
@@ -688,15 +688,15 @@ describe('terminal-bash plugin shape', () => {
const created = await ctx.terminals.spawn(owner, { type: 'stub' })
const unrelated = ctx.sessions.create(SessionId('unrelated-mode'))
expect(() => { setSandboxMode(unrelated, 'read-only') }).not.toThrow()
await expect(ctx.sandboxPolicy.setMode(unrelated, 'read-only')).resolves.toEqual([])
expect(() => {
session.append('turn/start', { turn: 1 })
}).not.toThrow()
expect(() => { setSandboxMode(session, 'danger-full-access') }).not.toThrow()
await expect(ctx.sandboxPolicy.setMode(session, 'danger-full-access')).resolves.toEqual([])
await providerFiber.dispose()
expect(ctx.terminals.listBackends()).toEqual([])
expect(() => { setSandboxMode(session, 'read-only') }).toThrow(
await expect(ctx.sandboxPolicy.setMode(session, 'read-only')).rejects.toThrow(
'cannot change sandbox mode from "danger-full-access" to "read-only" while persistent terminal sessions are open or being created; wait for creation to settle and close them first',
)
expect(session.snapshotEvents().filter(event => event.type === 'sandbox/mode')).toHaveLength(1)
@@ -704,11 +704,11 @@ describe('terminal-bash plugin shape', () => {
const replacementFiber = await registerStubLocalBackend(ctx, () => stubLocalSession())
const second = await ctx.terminals.spawn(owner, { type: 'stub' })
await replacementFiber.dispose()
expect(() => { setSandboxMode(session, 'read-only') }).toThrow('open or being created')
await expect(ctx.sandboxPolicy.setMode(session, 'read-only')).rejects.toThrow('open or being created')
await ctx.terminals.kill(owner, created.sessionId)
await ctx.terminals.kill(owner, second.sessionId)
expect(() => { setSandboxMode(session, 'read-only') }).not.toThrow()
await expect(ctx.sandboxPolicy.setMode(session, 'read-only')).resolves.toEqual([])
expect(session.snapshotEvents().filter(event => event.type === 'sandbox/mode')).toHaveLength(2)
})
@@ -740,7 +740,7 @@ describe('terminal-bash plugin shape', () => {
const spawning = ctx.terminals.spawn(owner, { type: 'stub' })
expect(ctx.terminals.hasOwnerActivity(owner)).toBe(true)
expect(() => { setSandboxMode(session, 'read-only') }).toThrow('open or being created')
await expect(ctx.sandboxPolicy.setMode(session, 'read-only')).rejects.toThrow('open or being created')
gate.resolve(undefined)
const created = await spawning
await ctx.terminals.kill(owner, created.sessionId)
@@ -1,5 +1,5 @@
import type { Context } from '@deepseek-ai/cordis'
import { setSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
import type {} from '@deepseek-ai/dsh-sandbox-policy'
import type {} from '@deepseek-ai/dsh-agent'
export const name = 'parent-sandbox-override'
@@ -12,8 +12,8 @@ export const name = 'parent-sandbox-override'
* instead of falling back to the deployment default.
*/
export function apply(ctx: Context): void {
ctx.on('agent/created', ({ agent }) => {
ctx.on('agent/created', async ({ agent }) => {
if (agent.session.header.parentSession !== undefined) return
setSandboxMode(agent.session, 'read-only')
await ctx.sandboxPolicy.setMode(agent.session, 'read-only')
})
}
-3
View File
@@ -7134,9 +7134,6 @@ importers:
'@deepseek-ai/dsh-llm':
specifier: workspace:*
version: link:../../llm/llm
'@deepseek-ai/dsh-permission-presets':
specifier: workspace:*
version: link:../../interaction/permission-presets
'@deepseek-ai/dsh-ptc-runtime':
specifier: workspace:*
version: link:../../ptc-runtime/ptc-runtime
+1
View File
@@ -562,6 +562,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
TerminalSpawnRequest: 'terminal.md',
TerminalSpawnResult: 'terminal.md',
SandboxPolicyRequest: 'sandbox.md',
SandboxPolicyResource: 'sandbox.md',
SshConnection: 'ssh.md',
SshStreamEndpoint: 'ssh.md',
ScopeKey: 'scope.md',
+5
View File
@@ -1346,6 +1346,11 @@
"symbol": "SandboxPolicyRequest",
"source": "packages/sandbox/sandbox-policy/src/index.ts"
},
{
"doc": "docs/subsystems/sandbox.md",
"symbol": "SandboxPolicyResource",
"source": "packages/sandbox/sandbox-policy/src/index.ts"
},
{
"doc": "docs/subsystems/sandbox.md",
"symbol": "RunnerFailureRule",