@gpzhang2001/sharpkit-shell

exec_command / write_stdin：沙箱内命令执行与 PTY 交互（对齐原版 Shell 工具语义）。

工具

exec_command（inject: ['tools', 'pentestSandbox']）

• cmd 必填；cwd 必须在 workspace 内（strix 精确错误文案）；tty、timeout_ms（钳制到 [1, maxTimeoutMs]）、run_in_background（Config 门控）
• 默认路径：fresh 非交互 bash -lc，超时竞速终止，尊重 exec.signal（协作式取消）
• tty=true：启动 PTY 返回 process_id，交给 write_stdin 驱动（Ctrl-C 写 \x03）
• run_in_background=true：ctx.jobs.start（kind pentest-exec，JobKindMap 扩展），readOutput 增量、cancel→terminate 且 done 映射 killed；免费获得 job_output/job_list/job_kill

write_stdin

• 仅对运行中的 PTY 进程有效；未知/已退出 → strix 精确错误文案
• chars="" 非阻塞轮询新输出；转义解码（\n \t \r \0 \a \b \v \f \\、\xNN、\uXXXX）逐字移植 _decode_chars_escape

横切

• 审批门：tools/pre-execute 对 exec_command 返回 ask（Config requireApproval 默认 true；无审批服务的组合会 fail-closed 拒绝）
• 会话：ctx.pentestSandbox.createSession({scanId}) create_or_reuse——编排方用真实 scanId 预建会话即可共享

Config

scanId（默认 pentest）、sources、requireApproval、enableRunInBackground、defaultTimeoutMs（120s）、maxTimeoutMs（600s，工具声明 deadline）、workspaceRoot。

测试

• tests/shell.test.ts：纯函数（转义/workdir/钳制）+ fake sandbox 全路径（含审批 ask 决策）
• tests/integration.test.ts：真实 sandbox + 真实 jobs（docker 门控）：前台/PTY/后台 job 增量输出与 kill