diff --git a/.agents/notes/implemented/architecture/2026-10-08-persistent-ptc-sandbox.i18n.yaml b/.agents/notes/implemented/architecture/2026-10-08-persistent-ptc-sandbox.i18n.yaml index f98f7ce3da..0fc2300e86 100644 --- a/.agents/notes/implemented/architecture/2026-10-08-persistent-ptc-sandbox.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-10-08-persistent-ptc-sandbox.i18n.yaml @@ -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 diff --git a/.agents/notes/implemented/architecture/2026-10-08-persistent-ptc-sandbox.md b/.agents/notes/implemented/architecture/2026-10-08-persistent-ptc-sandbox.md index 76f0fd9627..b3304761b0 100644 --- a/.agents/notes/implemented/architecture/2026-10-08-persistent-ptc-sandbox.md +++ b/.agents/notes/implemented/architecture/2026-10-08-persistent-ptc-sandbox.md @@ -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 diff --git a/.agents/notes/implemented/architecture/2026-10-08-persistent-ptc-sandbox.zh.md b/.agents/notes/implemented/architecture/2026-10-08-persistent-ptc-sandbox.zh.md index 2330ac5148..5fc58c1580 100644 --- a/.agents/notes/implemented/architecture/2026-10-08-persistent-ptc-sandbox.zh.md +++ b/.agents/notes/implemented/architecture/2026-10-08-persistent-ptc-sandbox.zh.md @@ -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 生命周期下跟踪保留与临时所有者。权限预 **修改运行中进程的策略。** 现有后端在启动时应用限制。现有接口无法把任意保留对象、打开的句柄和后台工作转移到另一策略。释放环境让权限切换具有确定的完成时点。 -**保留提权环境。** 单次审批不能授权未来程序或空闲期间的后台工作。独立临时所有者明确了审批生效的范围,同时保留原环境。 +**通过权限预设协调清理。** 文件策略也有直接调用方。文件策略所有者为两类调用方提供同一个清理操作,工具注册表不需要了解面向用户的预设选择。 + +**保留提权环境。** 单次审批不能授权未来程序或空闲期间的后台工作。省略状态所有者明确了审批生效的范围,同时保留原环境。 ## 影响 diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index 03ecc4f537..7f92299935 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -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) | diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md index 47beb36de4..248ba24e6a 100644 --- a/docs/event-producer-consumer.zh.md +++ b/docs/event-producer-consumer.zh.md @@ -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) | diff --git a/docs/module-graph.md b/docs/module-graph.md index ff80b923fa..63a00c948d 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -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) | diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md index c486f9860c..9b3a1e2036 100644 --- a/docs/module-graph.zh.md +++ b/docs/module-graph.zh.md @@ -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) | diff --git a/docs/persistence-catalog.i18n.yaml b/docs/persistence-catalog.i18n.yaml index eb88104328..485bf5d492 100644 --- a/docs/persistence-catalog.i18n.yaml +++ b/docs/persistence-catalog.i18n.yaml @@ -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 diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md index 192081c1fc..6b35721e8f 100644 --- a/docs/persistence-catalog.md +++ b/docs/persistence-catalog.md @@ -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 | |---|---|---| diff --git a/docs/persistence-catalog.zh.md b/docs/persistence-catalog.zh.md index e9e4b68d2f..fc35811f68 100644 --- a/docs/persistence-catalog.zh.md +++ b/docs/persistence-catalog.zh.md @@ -685,7 +685,7 @@ export type SessionEvent = { '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 = { } ``` -来源:[`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) | 属性 | 存在性 | 类型 | |---|---|---| diff --git a/docs/persistence-schema.json b/docs/persistence-schema.json index 6feffa31be..745b397bc5 100644 --- a/docs/persistence-schema.json +++ b/docs/persistence-schema.json @@ -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" ] }, { diff --git a/docs/subsystems/permission-presets.i18n.yaml b/docs/subsystems/permission-presets.i18n.yaml index 5e3159df65..48c465b9d1 100644 --- a/docs/subsystems/permission-presets.i18n.yaml +++ b/docs/subsystems/permission-presets.i18n.yaml @@ -15,5 +15,5 @@ en: 43a7b661b747091f zh: ee6b4f1ddb8cf6f2 /permission-presets/switching-and-the-permission-preset-event: - en: 1a5cf90e95baebd5 - zh: 527d7e8c7439c002 + en: 41ce3067c67bc3e6 + zh: 916765e1e8a28521 diff --git a/docs/subsystems/permission-presets.md b/docs/subsystems/permission-presets.md index 1a3ef12f9a..b7e9b2258b 100644 --- a/docs/subsystems/permission-presets.md +++ b/docs/subsystems/permission-presets.md @@ -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 - - -#### `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): Promise -``` - -Types: [SandboxMode](sandbox.md) · [Session](session.md) - -Source: [`packages/interaction/permission-presets/src/index.ts`](../../packages/interaction/permission-presets/src/index.ts) - #### `permission-presets/catalog-changed` — emit diff --git a/docs/subsystems/permission-presets.zh.md b/docs/subsystems/permission-presets.zh.md index b14a32d62e..23b4b626ed 100644 --- a/docs/subsystems/permission-presets.zh.md +++ b/docs/subsystems/permission-presets.zh.md @@ -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 - - -#### `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): Promise -``` - -Types: [SandboxMode](sandbox.zh.md) · [Session](session.zh.md) - -Source: [`packages/interaction/permission-presets/src/index.ts`](../../packages/interaction/permission-presets/src/index.ts) - #### `permission-presets/catalog-changed` — emit diff --git a/docs/subsystems/ptc-runtime.i18n.yaml b/docs/subsystems/ptc-runtime.i18n.yaml index b2bf82bf4a..f56417148e 100644 --- a/docs/subsystems/ptc-runtime.i18n.yaml +++ b/docs/subsystems/ptc-runtime.i18n.yaml @@ -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 diff --git a/docs/subsystems/ptc-runtime.md b/docs/subsystems/ptc-runtime.md index 6ed445063b..afcf5237a9 100644 --- a/docs/subsystems/ptc-runtime.md +++ b/docs/subsystems/ptc-runtime.md @@ -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 diff --git a/docs/subsystems/ptc-runtime.zh.md b/docs/subsystems/ptc-runtime.zh.md index c4b91e32a9..64134149d2 100644 --- a/docs/subsystems/ptc-runtime.zh.md +++ b/docs/subsystems/ptc-runtime.zh.md @@ -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 格式。 ## 绑定:宿主函数作为程序全局变量 diff --git a/docs/subsystems/sandbox.i18n.yaml b/docs/subsystems/sandbox.i18n.yaml index c521840364..9dcbd27926 100644 --- a/docs/subsystems/sandbox.i18n.yaml +++ b/docs/subsystems/sandbox.i18n.yaml @@ -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 diff --git a/docs/subsystems/sandbox.md b/docs/subsystems/sandbox.md index 05be79018f..4ccaea289a 100644 --- a/docs/subsystems/sandbox.md +++ b/docs/subsystems/sandbox.md @@ -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 + /** User-facing consequence reported after a successful policy change. */ + notice?: string +} +``` + ## 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 + +/** + * 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(sessionId: SessionId, signal: AbortSignal, run: (signal: AbortSignal) => Promise): Promise + /** * 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) diff --git a/docs/subsystems/sandbox.zh.md b/docs/subsystems/sandbox.zh.md index 843be48f65..dc1386f42d 100644 --- a/docs/subsystems/sandbox.zh.md +++ b/docs/subsystems/sandbox.zh.md @@ -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 + /** User-facing consequence reported after a successful policy change. */ + notice?: string +} +``` + ## 包装后的 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 + +/** + * 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(sessionId: SessionId, signal: AbortSignal, run: (signal: AbortSignal) => Promise): Promise + /** * 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) diff --git a/docs/upgrade-guide/v0.2.1-alpha.1/permission-preset-await/guide.i18n.yaml b/docs/upgrade-guide/v0.2.1-alpha.1/permission-preset-await/guide.i18n.yaml index b2e08917d9..5a0c9c4989 100644 --- a/docs/upgrade-guide/v0.2.1-alpha.1/permission-preset-await/guide.i18n.yaml +++ b/docs/upgrade-guide/v0.2.1-alpha.1/permission-preset-await/guide.i18n.yaml @@ -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 diff --git a/docs/upgrade-guide/v0.2.1-alpha.1/permission-preset-await/guide.md b/docs/upgrade-guide/v0.2.1-alpha.1/permission-preset-await/guide.md index 6e913b746c..8699a24e44 100644 --- a/docs/upgrade-guide/v0.2.1-alpha.1/permission-preset-await/guide.md +++ b/docs/upgrade-guide/v0.2.1-alpha.1/permission-preset-await/guide.md @@ -8,7 +8,7 @@ English | [中文](guide.zh.md) ## Change -`ctx.permissionPresets.set(session, name)` returns `Promise`. 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`. 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 diff --git a/docs/upgrade-guide/v0.2.1-alpha.1/permission-preset-await/guide.zh.md b/docs/upgrade-guide/v0.2.1-alpha.1/permission-preset-await/guide.zh.md index b95a179149..12aa7e8ea5 100644 --- a/docs/upgrade-guide/v0.2.1-alpha.1/permission-preset-await/guide.zh.md +++ b/docs/upgrade-guide/v0.2.1-alpha.1/permission-preset-await/guide.zh.md @@ -8,7 +8,7 @@ description: "权限预设调用方必须等待执行资源清理后,再使用 ## 变更 -`ctx.permissionPresets.set(session, name)` 返回 `Promise`。保留的执行资源释放且权限事件提交后,Promise 才会完成。返回的字符串说明清空了哪些资源。无效预设和清理失败会使 Promise 拒绝。 +`ctx.permissionPresets.set(session, name)` 返回 `Promise`。保留的执行资源释放且权限事件提交后,Promise 才会完成。返回的字符串说明清空了哪些资源。独立的 `setSandboxMode(session, mode)` 导出被 `await ctx.sandboxPolicy.setMode(session, mode)` 替代,直接选择模式也使用同一个清理操作。模式变化也会取消待审批的 PTC 调用和默认 `per-call` 模式中正在执行的程序,并等待嵌套工具完成清理。无效预设和清理失败会使 Promise 拒绝。 ## 迁移 diff --git a/packages/boot/plugin-manager/tests/tools.spec.ts b/packages/boot/plugin-manager/tests/tools.spec.ts index bc7da82dfe..c6d486ac2a 100644 --- a/packages/boot/plugin-manager/tests/tools.spec.ts +++ b/packages/boot/plugin-manager/tests/tools.spec.ts @@ -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() diff --git a/packages/core/tools/README.i18n.yaml b/packages/core/tools/README.i18n.yaml index ddaca5a6c0..e0ffa07121 100644 --- a/packages/core/tools/README.i18n.yaml +++ b/packages/core/tools/README.i18n.yaml @@ -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 diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md index e5eb73bb6c..17ee26991f 100644 --- a/packages/core/tools/README.md +++ b/packages/core/tools/README.md @@ -133,7 +133,7 @@ New sub-calls use `:ptc:` 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. ### Extension points diff --git a/packages/core/tools/README.zh.md b/packages/core/tools/README.zh.md index bd2cad52ff..2b63d653d6 100644 --- a/packages/core/tools/README.zh.md +++ b/packages/core/tools/README.zh.md @@ -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 调用,并等待嵌套工具清理完成,运行时向该服务登记保留进程的清理操作。单次提权省略状态所有者,在临时环境中执行;普通调用仍可访问原环境的变量。 ### 扩展点 diff --git a/packages/core/tools/package.json b/packages/core/tools/package.json index bc33bd8970..1e4fa8ba01 100644 --- a/packages/core/tools/package.json +++ b/packages/core/tools/package.json @@ -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:*" } } diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts index e506d99da0..b42734158d 100644 --- a/packages/core/tools/src/index.ts +++ b/packages/core/tools/src/index.ts @@ -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. diff --git a/packages/core/tools/src/ptc-owners.ts b/packages/core/tools/src/ptc-owners.ts deleted file mode 100644 index 632aeb84b1..0000000000 --- a/packages/core/tools/src/ptc-owners.ts +++ /dev/null @@ -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> - controllers: Set - phase: 'ready' | 'changing' | 'disposed' -} - -/** Keeps admission closed until permission changes and resource disposal settle. */ -export class PtcOwners { - private readonly agents = new WeakMap() - - /** - * 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 } { - 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 => { - 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 => { - 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) } - }, - } - } -} diff --git a/packages/core/tools/src/ptc.ts b/packages/core/tools/src/ptc.ts index 99ece37b5d..f54a2024fc 100644 --- a/packages/core/tools/src/ptc.ts +++ b/packages/core/tools/src/ptc.ts @@ -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) => Promise /** Captures the calling Session current directory before program creation. */ resolveWorkingDirectory: (exec: ToolRunContext) => Promise /** 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>() 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 => { 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. diff --git a/packages/core/tools/tests/ptc-owners.spec.ts b/packages/core/tools/tests/ptc-owners.spec.ts deleted file mode 100644 index 0d49a99456..0000000000 --- a/packages/core/tools/tests/ptc-owners.spec.ts +++ /dev/null @@ -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() - const released = Promise.withResolvers() - 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() - const disposingEntered = Promise.withResolvers() - const released = Promise.withResolvers() - 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() } -}) diff --git a/packages/core/tools/tests/ptc.spec.ts b/packages/core/tools/tests/ptc.spec.ts index 7cd0412632..1c251bd630 100644 --- a/packages/core/tools/tests/ptc.spec.ts +++ b/packages/core/tools/tests/ptc.spec.ts @@ -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('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() const answer = Promise.withResolvers() 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() } }) diff --git a/packages/core/tools/tsconfig.json b/packages/core/tools/tsconfig.json index 87c345b9d9..95c7ee1a48 100644 --- a/packages/core/tools/tsconfig.json +++ b/packages/core/tools/tsconfig.json @@ -46,9 +46,6 @@ }, { "path": "../../session/working-directory" - }, - { - "path": "../../interaction/permission-presets" } ] } diff --git a/packages/experimental/auto-review/tests/auto-review.spec.ts b/packages/experimental/auto-review/tests/auto-review.spec.ts index 2d77ca3df8..c6591a1154 100644 --- a/packages/experimental/auto-review/tests/auto-review.spec.ts +++ b/packages/experimental/auto-review/tests/auto-review.spec.ts @@ -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', { diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts index 1b58fd32f8..8a2eb5ae18 100644 --- a/packages/extensions/tool-cordis/src/api-catalog.ts +++ b/packages/extensions/tool-cordis/src/api-catalog.ts @@ -1643,7 +1643,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ }, { signature: 'set(session: Session, name: string): Promise', - 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', + 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(sessionId: SessionId, signal: AbortSignal, run: (signal: AbortSignal) => Promise): Promise', + 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): Promise', - 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;\n notice?: string;\n}', + }, { name: 'SaveFileAttachment', declaration: 'export interface SaveFileAttachment {\n data: Uint8Array;\n name?: string;\n}', diff --git a/packages/interaction/permission-presets/README.i18n.yaml b/packages/interaction/permission-presets/README.i18n.yaml index ed914cb6c2..ef3a9d1488 100644 --- a/packages/interaction/permission-presets/README.i18n.yaml +++ b/packages/interaction/permission-presets/README.i18n.yaml @@ -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 diff --git a/packages/interaction/permission-presets/README.md b/packages/interaction/permission-presets/README.md index 7b0450b03b..8c778827ef 100644 --- a/packages/interaction/permission-presets/README.md +++ b/packages/interaction/permission-presets/README.md @@ -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` diff --git a/packages/interaction/permission-presets/README.zh.md b/packages/interaction/permission-presets/README.zh.md index 3e9bc9cecf..18eb6fbc04 100644 --- a/packages/interaction/permission-presets/README.zh.md +++ b/packages/interaction/permission-presets/README.zh.md @@ -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` diff --git a/packages/interaction/permission-presets/src/index.ts b/packages/interaction/permission-presets/src/index.ts index dd4ee6928a..841621910d 100644 --- a/packages/interaction/permission-presets/src/index.ts +++ b/packages/interaction/permission-presets/src/index.ts @@ -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): Promise - } } 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 private readonly changing = new WeakSet() @@ -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 { 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') diff --git a/packages/interaction/permission-presets/tests/permission-presets.spec.ts b/packages/interaction/permission-presets/tests/permission-presets.spec.ts index 6847577b1e..81557fe8b4 100644 --- a/packages/interaction/permission-presets/tests/permission-presets.spec.ts +++ b/packages/interaction/permission-presets/tests/permission-presets.spec.ts @@ -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() } +}) diff --git a/packages/interaction/permission-presets/tests/projection.spec.ts b/packages/interaction/permission-presets/tests/projection.spec.ts index 603a728ad2..388a9efa8c 100644 --- a/packages/interaction/permission-presets/tests/projection.spec.ts +++ b/packages/interaction/permission-presets/tests/projection.spec.ts @@ -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', diff --git a/packages/ptc-runtime/ptc-runtime-node/README.i18n.yaml b/packages/ptc-runtime/ptc-runtime-node/README.i18n.yaml index 227d4326df..b01b3cc11d 100644 --- a/packages/ptc-runtime/ptc-runtime-node/README.i18n.yaml +++ b/packages/ptc-runtime/ptc-runtime-node/README.i18n.yaml @@ -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 diff --git a/packages/ptc-runtime/ptc-runtime-node/README.md b/packages/ptc-runtime/ptc-runtime-node/README.md index 38a66c26f5..7b830faacb 100644 --- a/packages/ptc-runtime/ptc-runtime-node/README.md +++ b/packages/ptc-runtime/ptc-runtime-node/README.md @@ -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 diff --git a/packages/ptc-runtime/ptc-runtime-node/README.zh.md b/packages/ptc-runtime/ptc-runtime-node/README.zh.md index 8e8ca00396..0f235453b5 100644 --- a/packages/ptc-runtime/ptc-runtime-node/README.zh.md +++ b/packages/ptc-runtime/ptc-runtime-node/README.zh.md @@ -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 尾部;空闲期间的失败写入宿主日志。清理期间无法观测进程范围时,释放所有者会重试终止;清理成功前拒绝新执行。确认进程退出后仍未排空的管道会产生诊断,但不阻止释放环境。 ### 截止时间与取消 diff --git a/packages/ptc-runtime/ptc-runtime-node/src/index.ts b/packages/ptc-runtime/ptc-runtime-node/src/index.ts index f0e0ba4fc5..e34bd29640 100644 --- a/packages/ptc-runtime/ptc-runtime-node/src/index.ts +++ b/packages/ptc-runtime/ptc-runtime-node/src/index.ts @@ -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 { diff --git a/packages/ptc-runtime/ptc-runtime-node/src/persistent.ts b/packages/ptc-runtime/ptc-runtime-node/src/persistent.ts index 88fa939d7c..b7c5a43145 100644 --- a/packages/ptc-runtime/ptc-runtime-node/src/persistent.ts +++ b/packages/ptc-runtime/ptc-runtime-node/src/persistent.ts @@ -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 + 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 + private stopped: Promise | undefined private starting?: Promise 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, code: string): Promise { @@ -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 { + private stop(): Promise { 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) } diff --git a/packages/ptc-runtime/ptc-runtime-node/tests/persistent-host.spec.ts b/packages/ptc-runtime/ptc-runtime-node/tests/persistent-host.spec.ts index d578e21573..45925a11e3 100644 --- a/packages/ptc-runtime/ptc-runtime-node/tests/persistent-host.spec.ts +++ b/packages/ptc-runtime/ptc-runtime-node/tests/persistent-host.spec.ts @@ -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') diff --git a/packages/ptc-runtime/ptc-runtime-node/tests/persistent-sandbox.spec.ts b/packages/ptc-runtime/ptc-runtime-node/tests/persistent-sandbox.spec.ts index 08fc71304c..ff53875d6c 100644 --- a/packages/ptc-runtime/ptc-runtime-node/tests/persistent-sandbox.spec.ts +++ b/packages/ptc-runtime/ptc-runtime-node/tests/persistent-sandbox.spec.ts @@ -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() + 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') +}) diff --git a/packages/ptc-runtime/ptc-runtime-node/tests/persistent.spec.ts b/packages/ptc-runtime/ptc-runtime-node/tests/persistent.spec.ts index b9fcbaee95..01c7061c2d 100644 --- a/packages/ptc-runtime/ptc-runtime-node/tests/persistent.spec.ts +++ b/packages/ptc-runtime/ptc-runtime-node/tests/persistent.spec.ts @@ -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') diff --git a/packages/ptc-runtime/ptc-runtime/README.i18n.yaml b/packages/ptc-runtime/ptc-runtime/README.i18n.yaml index e180cd8cbb..6062a8c287 100644 --- a/packages/ptc-runtime/ptc-runtime/README.i18n.yaml +++ b/packages/ptc-runtime/ptc-runtime/README.i18n.yaml @@ -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 diff --git a/packages/ptc-runtime/ptc-runtime/README.md b/packages/ptc-runtime/ptc-runtime/README.md index 137df870a2..1c0c76327a 100644 --- a/packages/ptc-runtime/ptc-runtime/README.md +++ b/packages/ptc-runtime/ptc-runtime/README.md @@ -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 diff --git a/packages/ptc-runtime/ptc-runtime/README.zh.md b/packages/ptc-runtime/ptc-runtime/README.zh.md index daa93f0bdd..902bb9b559 100644 --- a/packages/ptc-runtime/ptc-runtime/README.zh.md +++ b/packages/ptc-runtime/ptc-runtime/README.zh.md @@ -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)`。不同对象不会共享环境;省略所有者时使用临时环境。无状态提供方忽略所有权。同一保留环境的调用不能重叠。 ### 可移植地命名绑定 diff --git a/packages/ptc-runtime/ptc-runtime/src/index.ts b/packages/ptc-runtime/ptc-runtime/src/index.ts index b53a48d0ae..be6b8b2eb2 100644 --- a/packages/ptc-runtime/ptc-runtime/src/index.ts +++ b/packages/ptc-runtime/ptc-runtime/src/index.ts @@ -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. diff --git a/packages/sandbox/sandbox-policy/README.i18n.yaml b/packages/sandbox/sandbox-policy/README.i18n.yaml index 4d502fa1f9..bb35868667 100644 --- a/packages/sandbox/sandbox-policy/README.i18n.yaml +++ b/packages/sandbox/sandbox-policy/README.i18n.yaml @@ -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 diff --git a/packages/sandbox/sandbox-policy/README.md b/packages/sandbox/sandbox-policy/README.md index 88648e8c8f..2ce040db36 100644 --- a/packages/sandbox/sandbox-policy/README.md +++ b/packages/sandbox/sandbox-policy/README.md @@ -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 | diff --git a/packages/sandbox/sandbox-policy/README.zh.md b/packages/sandbox/sandbox-policy/README.zh.md index 5f7334cb28..13bd0f3689 100644 --- a/packages/sandbox/sandbox-policy/README.zh.md +++ b/packages/sandbox/sandbox-policy/README.zh.md @@ -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` 事件与可接受的模式值 | diff --git a/packages/sandbox/sandbox-policy/src/index.ts b/packages/sandbox/sandbox-policy/src/index.ts index e97796db5c..2ea2a17f63 100644 --- a/packages/sandbox/sandbox-policy/src/index.ts +++ b/packages/sandbox/sandbox-policy/src/index.ts @@ -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 + /** User-facing consequence reported after a successful policy change. */ + notice?: string +} + +interface Execution { + sessionId: SessionId + controller: AbortController + done: Promise +} + /** 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>() + private readonly executions = new Map>() + private readonly activeExecution = new AsyncLocalStorage() + private readonly changing = new Set() + private readonly committing = new Set() + 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 { + 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(sessionId: SessionId, signal: AbortSignal, run: (signal: AbortSignal) => Promise): Promise { + this.assertAvailable(sessionId) + const controller = new AbortController() + const done = Promise.withResolvers() + 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. diff --git a/packages/sandbox/sandbox-policy/src/session-mode.ts b/packages/sandbox/sandbox-policy/src/session-mode.ts index 0bc7110efc..04664e8af9 100644 --- a/packages/sandbox/sandbox-policy/src/session-mode.ts +++ b/packages/sandbox/sandbox-policy/src/session-mode.ts @@ -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 }) -} diff --git a/packages/sandbox/sandbox-policy/tests/mode-change.spec.ts b/packages/sandbox/sandbox-policy/tests/mode-change.spec.ts new file mode 100644 index 0000000000..77e181819c --- /dev/null +++ b/packages/sandbox/sandbox-policy/tests/mode-change.spec.ts @@ -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() + const resourceDone = Promise.withResolvers() + const operationDone = Promise.withResolvers() + const observed = Promise.withResolvers() + 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() + const done = Promise.withResolvers() + 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() + const done = Promise.withResolvers() + 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() + const done = Promise.withResolvers() + 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() + const disposalEntered = Promise.withResolvers() + const done = Promise.withResolvers() + 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() } +}) diff --git a/packages/sandbox/sandbox-policy/tests/policy.spec.ts b/packages/sandbox/sandbox-policy/tests/policy.spec.ts index 7d75fe263c..51eb8325b6 100644 --- a/packages/sandbox/sandbox-policy/tests/policy.spec.ts +++ b/packages/sandbox/sandbox-policy/tests/policy.spec.ts @@ -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' }) diff --git a/packages/session/working-directory/tests/admission.spec.ts b/packages/session/working-directory/tests/admission.spec.ts index 8b024e5f60..220483e48b 100644 --- a/packages/session/working-directory/tests/admission.spec.ts +++ b/packages/session/working-directory/tests/admission.spec.ts @@ -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') { diff --git a/packages/subagent/subagent/tests/activation-policy.spec.ts b/packages/subagent/subagent/tests/activation-policy.spec.ts index 38d9d44005..48052ad0c3 100644 --- a/packages/subagent/subagent/tests/activation-policy.spec.ts +++ b/packages/subagent/subagent/tests/activation-policy.spec.ts @@ -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, diff --git a/packages/subagent/subagent/tests/continuation-inheritance.spec.ts b/packages/subagent/subagent/tests/continuation-inheritance.spec.ts index e44c170dae..9b332090c1 100644 --- a/packages/subagent/subagent/tests/continuation-inheritance.spec.ts +++ b/packages/subagent/subagent/tests/continuation-inheritance.spec.ts @@ -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) diff --git a/packages/terminal/terminal-bash/tests/index.spec.ts b/packages/terminal/terminal-bash/tests/index.spec.ts index a68c798321..a0ea51121d 100644 --- a/packages/terminal/terminal-bash/tests/index.spec.ts +++ b/packages/terminal/terminal-bash/tests/index.spec.ts @@ -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) diff --git a/packages/test-support/session-snapshot/tests/fixtures/parent-sandbox-override.ts b/packages/test-support/session-snapshot/tests/fixtures/parent-sandbox-override.ts index 262bd8a579..5299c05df8 100644 --- a/packages/test-support/session-snapshot/tests/fixtures/parent-sandbox-override.ts +++ b/packages/test-support/session-snapshot/tests/fixtures/parent-sandbox-override.ts @@ -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') }) } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index b85f6c16a2..e5228fdbd7 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -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 diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts index 2c012bde12..5cd7e07dfc 100644 --- a/scripts/gen-cordis-catalog.ts +++ b/scripts/gen-cordis-catalog.ts @@ -562,6 +562,7 @@ export const LINK_MAP: Readonly> = { TerminalSpawnRequest: 'terminal.md', TerminalSpawnResult: 'terminal.md', SandboxPolicyRequest: 'sandbox.md', + SandboxPolicyResource: 'sandbox.md', SshConnection: 'ssh.md', SshStreamEndpoint: 'ssh.md', ScopeKey: 'scope.md', diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json index 0a78f5191a..8dcd2c14a1 100644 --- a/scripts/type-equiv.manifest.json +++ b/scripts/type-equiv.manifest.json @@ -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",