@gpzhang2001/sharpkit-shell 0.2.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 gpzhang2001
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,29 @@
+# @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

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,48 @@
+# Third-Party Notices
+
+This project builds on and derives assets from the following upstream
+projects. Their licenses and attribution requirements are acknowledged here
+as required by Apache-2.0 §4.
+
+## strix — https://github.com/usestrix/strix
+
+Copyright 2025 OmniSecure Inc. Licensed under the Apache License, Version 2.0.
+
+sharpkit is an independent TypeScript reimplementation of strix's pentest
+domain assets on the DeepSeek Harness plugin architecture (no strix code is
+executed; no Python runtime is required). The following files are carried
+**verbatim or near-verbatim** from strix and remain subject to the above
+notice:
+
+| sharpkit path | Origin | Changes |
+| --- | --- | --- |
+| `packages/preset/src/system_prompt.jinja` | `strix/agents/prompts/system_prompt.jinja` | none (byte-identical template) |
+| `packages/skills/skills/**` (75 knowledge packs, 11 categories) | `strix/strix/skills/**` | none (migrated verbatim) |
+| `sandbox-image/caido_api.py` | `strix/strix/tools/proxy/caido_api.py` | none (byte-identical) |
+| `sandbox-image/docker-entrypoint.sh` | `strix/containers/docker-entrypoint.sh` | none (byte-identical) |
+| `sandbox-image/Dockerfile` | `strix/containers/Dockerfile` | COPY source paths adapted to the standalone context; added overridable `GOPROXY`/`KALI_MIRROR` build args |
+| `packages/preset/src/skills.ts` | `strix/strix/skills/__init__.py` | reimplemented in TypeScript (selection/validation semantics) |
+
+The following subsystems are **semantic ports** (behavior-preserving
+reimplementation, no verbatim text): the SARIF writer and vulnerability
+artifact writers (`packages/tool-reporting/src/{sarif,writers,state}.ts` ←
+`strix/report/*`), the reporting/analysis tool schemas
+(`packages/tool-reporting`, `packages/tool-analysis` ← `strix/tools/*`), the
+Caido client (`packages/tool-proxy/src/client.ts` ← the client half of
+`strix/tools/proxy/caido_api.py`), the sandbox session manager
+(`packages/sandbox` ← `strix/runtime/*`), and the scan-mode preset semantics
+(`packages/preset` ← `strix/agents/factory.py` + `core/inputs.py`).
+
+## DeepSeek Harness (dsh) — https://github.com/deepseek-ai/deepseek-harness
+
+MIT License. Copyright (c) DeepSeek.
+
+dsh is a runtime dependency only (`@deepseek-ai/dsh-*` npm packages); no dsh
+source is embedded or modified in this repository.
+
+## Sandbox image components
+
+The built `sharpkit-sandbox` image bundles Kali Linux and third-party security
+tools (nmap, sqlmap, nuclei, Caido, agent-browser, chromium, and others), each
+under its own license inside the image. Distributing a built image is the
+operator's responsibility; this repository ships only the build recipe.

package/lib/index.d.ts

@@ -0,0 +1,81 @@
+import z from "@deepseek-ai/schemastery";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/index.d.ts
+var [STDIN_UNAVAILABLE] = [
+	0,
+	() => [],
+	[]
+];
+var [ConfigSource] = [
+	1,
+	() => [],
+	[
+		"",
+		"",
+		""
+	]
+];
+var [Config] = [
+	2,
+	() => [ConfigSource],
+	[
+		"",
+		"",
+		"",
+		"",
+		"",
+		"",
+		"",
+		"",
+		""
+	]
+];
+var [_0] = [
+	3,
+	() => [],
+	["", ""],
+	sideEffect(_0)
+];
+var [name] = [
+	4,
+	() => [],
+	[]
+];
+var [inject] = [
+	5,
+	() => [],
+	[]
+];
+var [Config] = [
+	6,
+	() => [Config, z],
+	["", ""]
+];
+var [workdirError] = [
+	7,
+	() => [],
+	["", ""]
+];
+var [clampTimeout] = [
+	8,
+	() => [],
+	[
+		"",
+		"",
+		""
+	]
+];
+var [apply] = [
+	9,
+	() => [Context, Config],
+	[
+		"",
+		"",
+		"",
+		""
+	]
+];
+//#endregion
+export { Config, ConfigSource, STDIN_UNAVAILABLE, apply, clampTimeout, inject, name, workdirError };
+
+//# sourceMappingURL=index.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.ts","names":["Schema"],"sources":["../src/index.d.ts"],"sourcesContent":["/**\n * `exec_command` / `write_stdin` model-facing shell tools over the pentest\n * sandbox — strix SDK ShellTool semantics (tools/shell/README.md + factory\n * wrapping): a fresh non-interactive login shell per call by default, PTY\n * processes for interactive work driven by `write_stdin` (chars=\"\" polls),\n * workdir restricted to the workspace, per-call timeout clamped by config,\n * and `run_in_background` mapped onto the dsh jobs runtime\n * (job_output/job_list/job_kill come free). Every exec passes an ask\n * approval gate (config-gated; the registry resolves `ask` through the\n * host's approval service and fails closed when none is composed).\n * @module @gpzhang2001/sharpkit-shell\n */\nimport type { Context } from '@deepseek-ai/cordis';\nimport type Schema from '@deepseek-ai/schemastery';\n/** strix's exact refusal text for write_stdin against a non-PTY process. */\nexport declare const STDIN_UNAVAILABLE = \"stdin is not available for this process. Start the command with 'tty=true' in 'exec_command' before using 'write_stdin'.\";\n/** One source tree Config entry (mutable twin of the sandbox spec for schemastery). */\nexport interface ConfigSource {\n    workspaceSubdir: string;\n    sourcePath: string;\n    protectMetadata?: boolean;\n}\n/** Deployment-tunable configuration. */\nexport interface Config {\n    /** Sandbox session cache key; the orchestrator pre-creates the real session under this id. */\n    readonly scanId?: string;\n    /** Source trees for the session this tool creates when none exists yet. */\n    readonly sources?: ConfigSource[];\n    /** Ask-approval gate on every exec_command (fail-closed without an approval service). */\n    readonly requireApproval?: boolean;\n    /** Expose run_in_background (needs a jobs provider at runtime). */\n    readonly enableRunInBackground?: boolean;\n    /** Default per-call timeout; model values are clamped into [1, maxTimeoutMs]. */\n    readonly defaultTimeoutMs?: number;\n    /** Hard ceiling for the model's timeout_ms and the tool's own deadline. */\n    readonly maxTimeoutMs?: number;\n    /** Container workspace root (workdir validation). */\n    readonly workspaceRoot?: string;\n    /** Unpolled PTY output ceiling in bytes (approx; the tail is kept). */\n    readonly maxTtyBufferBytes?: number;\n}\ndeclare module '@deepseek-ai/dsh-jobs' {\n    interface JobKindMap {\n        'pentest-exec': 'pentest-exec';\n    }\n}\nexport declare const name = \"pentest-tool-shell\";\nexport declare const inject: string[];\nexport declare const Config: Schema<Config>;\n/**\n * Validate a workdir against the workspace root (strix workdir contract),\n * segment by segment: no absolute escape, no `..`/`.`/empty segments, no\n * trailing slash.\n * @param cwd - the requested working directory.\n * @param workspaceRoot - container workspace root.\n * @returns null when valid, else strix's exact error text.\n */\nexport declare function workdirError(cwd: string | undefined, workspaceRoot: string): string | null;\n/** Clamp a requested timeout into the configured window. */\nexport declare function clampTimeout(requested: number | undefined, defaultTimeoutMs: number, maxTimeoutMs: number): number;\nexport declare function apply(ctx: Context, config?: Config): void;\n"],"mappings":";;;AAEA,IAAW,CAAC,qBAAqB;CAAC;OAAS,CAAC;CAAG,CAAC;AAAC;AACjD,IAAW,CAAC,gBAAgB;CAAC;OAAS,CAAC;CAAG;EAAC;EAAI;EAAI;CAAE;AAAC;AACtD,IAAW,CAAC,UAAU;CAAC;OAAS,CAAC,YAAY;CAAG;EAAC;EAAI;EAAI;EAAI;EAAI;EAAI;EAAI;EAAI;EAAI;CAAE;AAAC;AACpF,IAAI,CAAC,MAAM;CAAC;OAAS,CAAC;CAAG,CAAC,IAAI,EAAE;CAAG,WAAW,EAAE;AAAC;AACjD,IAAW,CAAC,QAAQ;CAAC;OAAS,CAAC;CAAG,CAAC;AAAC;AACpC,IAAW,CAAC,UAAU;CAAC;OAAS,CAAC;CAAG,CAAC;AAAC;AACtC,IAAW,CAAC,UAAU;CAAC;OAAS,CAAC,QAAQA,CAAM;CAAG,CAAC,IAAI,EAAE;AAAC;AAC1D,IAAW,CAAC,gBAAgB;CAAC;OAAS,CAAC;CAAG,CAAC,IAAI,EAAE;AAAC;AAClD,IAAW,CAAC,gBAAgB;CAAC;OAAS,CAAC;CAAG;EAAC;EAAI;EAAI;CAAE;AAAC;AACtD,IAAW,CAAC,SAAS;CAAC;OAAS,CAAC,SAAS,MAAM;CAAG;EAAC;EAAI;EAAI;EAAI;CAAE;AAAC"}

package/lib/index.js

@@ -0,0 +1,308 @@
+import z from "@deepseek-ai/schemastery";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region src/chars.ts
+/**
+* Escape decoding for `write_stdin` chars, ported verbatim from strix
+* factory.py `_decode_chars_escape` (\\uXXXX, \\xNN, and the C-style short
+* escapes; unknown escapes and backslash-free strings pass through).
+* @module @gpzhang2001/sharpkit-shell/chars
+*/
+const ESCAPE_RE = /\\(?:u[0-9a-fA-F]{4}|x[0-9a-fA-F]{2}|[0abtnvfr\\])/g;
+const SHORT_ESCAPES = {
+	"\\\\": "\\",
+	"\\n": "\n",
+	"\\t": "	",
+	"\\r": "\r",
+	"\\0": "\0",
+	"\\a": "\x07",
+	"\\b": "\b",
+	"\\v": "\v",
+	"\\f": "\f"
+};
+/**
+* Decode the model-facing escape forms in a `chars` argument.
+* @param chars - the raw argument value.
+* @returns the decoded characters to deliver to the process.
+*/
+function decodeCharsEscape(chars) {
+	if (!chars.includes("\\")) return chars;
+	return chars.replace(ESCAPE_RE, (token) => {
+		const short = SHORT_ESCAPES[token];
+		if (short !== void 0) return short;
+		return String.fromCodePoint(Number.parseInt(token.slice(2), 16));
+	});
+}
+//#endregion
+//#region src/index.ts
+/** strix's exact refusal text for write_stdin against a non-PTY process. */
+const STDIN_UNAVAILABLE = "stdin is not available for this process. Start the command with 'tty=true' in 'exec_command' before using 'write_stdin'.";
+const name = "pentest-tool-shell";
+const inject = ["tools", "pentestSandbox"];
+const Config = z.object({
+	scanId: z.string().default("pentest"),
+	sources: z.array(z.object({
+		workspaceSubdir: z.string(),
+		sourcePath: z.string(),
+		protectMetadata: z.boolean()
+	})),
+	requireApproval: z.boolean().default(true),
+	enableRunInBackground: z.boolean().default(true),
+	defaultTimeoutMs: z.number().default(12e4),
+	maxTimeoutMs: z.number().default(6e5),
+	workspaceRoot: z.string().default("/workspace"),
+	maxTtyBufferBytes: z.number().default(1048576)
+});
+/**
+* Validate a workdir against the workspace root (strix workdir contract),
+* segment by segment: no absolute escape, no `..`/`.`/empty segments, no
+* trailing slash.
+* @param cwd - the requested working directory.
+* @param workspaceRoot - container workspace root.
+* @returns null when valid, else strix's exact error text.
+*/
+function workdirError(cwd, workspaceRoot) {
+	if (cwd === void 0) return null;
+	if (cwd === workspaceRoot) return null;
+	const prefix = `${workspaceRoot}/`;
+	return cwd.startsWith(prefix) && cwd.slice(prefix.length).split("/").every((segment) => segment !== "" && segment !== "." && segment !== "..") ? null : `exec_command: workdir must be a path inside ${workspaceRoot} (or omitted to use the turn's cwd). Got: '${cwd}'.`;
+}
+/** Clamp a requested timeout into the configured window. */
+function clampTimeout(requested, defaultTimeoutMs, maxTimeoutMs) {
+	return Math.min(Math.max(1, requested ?? defaultTimeoutMs), maxTimeoutMs);
+}
+function apply(ctx, config = {}) {
+	const ttyProcesses = /* @__PURE__ */ new Map();
+	const session = () => ctx.pentestSandbox.createSession({
+		scanId: config.scanId ?? "pentest",
+		...config.sources !== void 0 ? { sources: config.sources.map((source) => ({
+			workspaceSubdir: source.workspaceSubdir,
+			sourcePath: source.sourcePath,
+			...source.protectMetadata !== void 0 ? { protectMetadata: source.protectMetadata } : {}
+		})) } : {}
+	});
+	if (config.requireApproval !== false) ctx.on("tools/pre-execute", async (exec, next) => {
+		if (exec.name === "exec_command") return {
+			kind: "ask",
+			reason: "pentest: run a command inside the attack sandbox"
+		};
+		return next();
+	});
+	const workspaceRoot = config.workspaceRoot ?? "/workspace";
+	const defaultTimeoutMs = config.defaultTimeoutMs ?? 12e4;
+	const maxTimeoutMs = config.maxTimeoutMs ?? 6e5;
+	const maxTtyBufferBytes = config.maxTtyBufferBytes ?? 1048576;
+	const backgroundEnabled = config.enableRunInBackground !== false;
+	ctx.tools.register(defineTool({
+		name: "exec_command",
+		description: `Run a shell command inside the pentest sandbox (Kali container) in a fresh non-interactive bash login shell. Set tty=true for interactive programs (REPLs, ssh, msfconsole) and then drive them with write_stdin; run_in_background starts a job for long scans and returns a job id for job_output/job_kill.${backgroundEnabled ? "" : " (run_in_background is disabled in this deployment.)"}`,
+		parameters: {
+			cmd: {
+				type: "string",
+				required: true,
+				description: "The shell command line to execute."
+			},
+			...backgroundEnabled ? { run_in_background: {
+				type: "boolean",
+				description: "Start as a background job; returns a job id (long scans)."
+			} } : {},
+			cwd: {
+				type: "string",
+				description: `Working directory inside ${workspaceRoot}.`
+			},
+			timeout_ms: {
+				type: "integer",
+				description: "Per-call timeout in milliseconds (clamped by deployment)."
+			},
+			tty: {
+				type: "boolean",
+				description: "Run under a PTY for interactive input via write_stdin."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					kind: {
+						type: "string",
+						required: true,
+						enum: [
+							"foreground",
+							"tty",
+							"background"
+						]
+					},
+					exit_code: { type: "integer" },
+					signal: { type: "string" },
+					timed_out: { type: "boolean" },
+					stdout: { type: "string" },
+					stderr: { type: "string" },
+					process_id: { type: "string" },
+					job_id: { type: "string" }
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => {
+				if (value.kind === "foreground") return [{
+					type: "text",
+					text: `exit_code=${value.exit_code === null ? "none" : String(value.exit_code)}${value.timed_out === true ? " (timed out)" : ""}\nstdout:\n${value.stdout}\nstderr:\n${value.stderr}`
+				}];
+				if (value.kind === "tty") return [{
+					type: "text",
+					text: `PTY process ${value.process_id} started. Poll with write_stdin(process_id="${value.process_id}", chars=""); send input via chars; deliver Ctrl-C with chars="\\x03".`
+				}];
+				return [{
+					type: "text",
+					text: `started background job ${value.job_id} (job_output to read, job_kill to stop)`
+				}];
+			}
+		},
+		timeoutMs: maxTimeoutMs,
+		presentCall: (args) => ({
+			card: "terminal",
+			title: String(args.cmd ?? "")
+		}),
+		presentResult: (args, result) => {
+			const text = result.content.filter((block) => block.type === "text").map((block) => block.text).join("\n");
+			return {
+				card: "terminal",
+				output: text === "" ? String(args.cmd ?? "") : text
+			};
+		},
+		execute: async (args, exec) => {
+			const cwdProblem = workdirError(args.cwd, workspaceRoot);
+			if (cwdProblem !== null) throw new Error(cwdProblem);
+			if (args.tty === true && args.run_in_background === true) throw new Error("exec_command: tty=true and run_in_background cannot be combined — start a PTY process and drive it with write_stdin, or start a background job without a PTY.");
+			if (args.run_in_background === true && !backgroundEnabled) throw new Error("run_in_background is disabled for this deployment (enableRunInBackground: false)");
+			const sandbox = await session();
+			if (args.tty === true) {
+				const process = await sandbox.execTty(args.cmd, { cwd: args.cwd });
+				const tracked = {
+					process,
+					buffer: "",
+					cursor: 0,
+					settled: void 0
+				};
+				process.subscribe((chunk) => {
+					tracked.buffer += chunk;
+					if (tracked.buffer.length > maxTtyBufferBytes) {
+						const excess = tracked.buffer.length - maxTtyBufferBytes;
+						tracked.buffer = tracked.buffer.slice(excess);
+						tracked.cursor = Math.max(0, tracked.cursor - excess);
+					}
+				});
+				process.done.then((outcome) => {
+					tracked.settled = {
+						exitCode: outcome.exitCode,
+						signal: outcome.signal
+					};
+				}, () => {
+					tracked.settled = {
+						exitCode: null,
+						signal: null
+					};
+				});
+				ttyProcesses.set(process.id, tracked);
+				return {
+					kind: "tty",
+					process_id: process.id
+				};
+			}
+			if (args.run_in_background === true) {
+				const jobs = ctx.get("jobs");
+				if (jobs === void 0) throw new Error("run_in_background needs a jobs provider (load @deepseek-ai/dsh-jobs-local)");
+				const job = sandbox.execJob(args.cmd, { cwd: args.cwd });
+				let cancelled = false;
+				return {
+					kind: "background",
+					job_id: jobs.start({
+						kind: "pentest-exec",
+						label: args.cmd,
+						...exec.agent !== void 0 ? { owner: exec.agent } : {},
+						run: () => ({
+							cancel: () => {
+								cancelled = true;
+								job.terminate();
+							},
+							done: job.done.then((outcome) => cancelled ? {
+								status: "killed",
+								detail: "cancelled by request"
+							} : {
+								status: outcome.exitCode === 0 ? "completed" : "failed",
+								detail: `exit code: ${outcome.exitCode === null ? "none" : String(outcome.exitCode)}`
+							}),
+							readOutput: () => job.readOutput()
+						})
+					})
+				};
+			}
+			const result = await sandbox.exec(args.cmd, {
+				cwd: args.cwd,
+				timeoutMs: clampTimeout(args.timeout_ms, defaultTimeoutMs, maxTimeoutMs),
+				signal: exec.signal
+			});
+			return {
+				kind: "foreground",
+				...result.exitCode !== null ? { exit_code: result.exitCode } : {},
+				...result.signal !== null ? { signal: result.signal } : {},
+				timed_out: result.timedOut,
+				stdout: result.stdout,
+				stderr: result.stderr
+			};
+		}
+	}));
+	ctx.tools.register(defineTool({
+		name: "write_stdin",
+		description: "Send characters to a PTY-backed process started by exec_command(tty=true). chars=\"\" polls for new output without sending anything. Escapes (\\n, \\t, \\x03 for Ctrl-C, \\uXXXX) are decoded.",
+		parameters: {
+			process_id: {
+				type: "string",
+				required: true,
+				description: "The process id returned by exec_command(tty=true)."
+			},
+			chars: {
+				type: "string",
+				required: true,
+				description: "Characters to write (\"\" to poll for output only)."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					output: {
+						type: "string",
+						required: true
+					},
+					running: {
+						type: "boolean",
+						required: true
+					},
+					exit_code: { type: "integer" }
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: `${value.running ? "(running)" : `(exited${value.exit_code === void 0 ? "" : ` exit_code=${String(value.exit_code)}`})`}\n${value.output}`
+			}]
+		},
+		execute: async (args) => {
+			const tracked = ttyProcesses.get(args.process_id);
+			if (tracked === void 0) throw new Error(STDIN_UNAVAILABLE);
+			const chars = decodeCharsEscape(args.chars);
+			if (chars !== "") await tracked.process.write(chars);
+			const delta = tracked.buffer.slice(tracked.cursor);
+			tracked.cursor = tracked.buffer.length;
+			if (tracked.settled !== void 0) ttyProcesses.delete(args.process_id);
+			return {
+				output: delta,
+				running: tracked.settled === void 0,
+				...tracked.settled !== void 0 && tracked.settled.exitCode !== null ? { exit_code: tracked.settled.exitCode } : {}
+			};
+		}
+	}));
+}
+//#endregion
+export { Config, STDIN_UNAVAILABLE, apply, clampTimeout, inject, name, workdirError };
+
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/chars.ts","../src/index.ts"],"sourcesContent":["/**\n * Escape decoding for `write_stdin` chars, ported verbatim from strix\n * factory.py `_decode_chars_escape` (\\\\uXXXX, \\\\xNN, and the C-style short\n * escapes; unknown escapes and backslash-free strings pass through).\n * @module @gpzhang2001/sharpkit-shell/chars\n */\n\nconst ESCAPE_RE = /\\\\(?:u[0-9a-fA-F]{4}|x[0-9a-fA-F]{2}|[0abtnvfr\\\\])/g\n\nconst SHORT_ESCAPES: Record<string, string> = {\n  '\\\\\\\\': '\\\\',\n  '\\\\n': '\\n',\n  '\\\\t': '\\t',\n  '\\\\r': '\\r',\n  '\\\\0': '\\x00',\n  '\\\\a': '\\x07',\n  '\\\\b': '\\x08',\n  '\\\\v': '\\x0b',\n  '\\\\f': '\\x0c',\n}\n\n/**\n * Decode the model-facing escape forms in a `chars` argument.\n * @param chars - the raw argument value.\n * @returns the decoded characters to deliver to the process.\n */\nexport function decodeCharsEscape(chars: string): string {\n  if (!chars.includes('\\\\')) return chars\n  return chars.replace(ESCAPE_RE, token => {\n    const short = SHORT_ESCAPES[token]\n    if (short !== undefined) return short\n    return String.fromCodePoint(Number.parseInt(token.slice(2), 16))\n  })\n}\n","/**\n * `exec_command` / `write_stdin` model-facing shell tools over the pentest\n * sandbox — strix SDK ShellTool semantics (tools/shell/README.md + factory\n * wrapping): a fresh non-interactive login shell per call by default, PTY\n * processes for interactive work driven by `write_stdin` (chars=\"\" polls),\n * workdir restricted to the workspace, per-call timeout clamped by config,\n * and `run_in_background` mapped onto the dsh jobs runtime\n * (job_output/job_list/job_kill come free). Every exec passes an ask\n * approval gate (config-gated; the registry resolves `ask` through the\n * host's approval service and fails closed when none is composed).\n * @module @gpzhang2001/sharpkit-shell\n */\n\nimport type { Context } from '@deepseek-ai/cordis'\nimport type Schema from '@deepseek-ai/schemastery'\nimport z from '@deepseek-ai/schemastery'\nimport { defineTool } from '@deepseek-ai/dsh-tools'\nimport type { SandboxTtyProcess } from '@gpzhang2001/sharpkit-sandbox'\nimport { decodeCharsEscape } from './chars.ts'\n\n/** strix's exact refusal text for write_stdin against a non-PTY process. */\nexport const STDIN_UNAVAILABLE = \"stdin is not available for this process. Start the command with 'tty=true' in 'exec_command' before using 'write_stdin'.\"\n\n/** One source tree Config entry (mutable twin of the sandbox spec for schemastery). */\nexport interface ConfigSource {\n  workspaceSubdir: string\n  sourcePath: string\n  protectMetadata?: boolean\n}\n\n/** Deployment-tunable configuration. */\nexport interface Config {\n  /** Sandbox session cache key; the orchestrator pre-creates the real session under this id. */\n  readonly scanId?: string\n  /** Source trees for the session this tool creates when none exists yet. */\n  readonly sources?: ConfigSource[]\n  /** Ask-approval gate on every exec_command (fail-closed without an approval service). */\n  readonly requireApproval?: boolean\n  /** Expose run_in_background (needs a jobs provider at runtime). */\n  readonly enableRunInBackground?: boolean\n  /** Default per-call timeout; model values are clamped into [1, maxTimeoutMs]. */\n  readonly defaultTimeoutMs?: number\n  /** Hard ceiling for the model's timeout_ms and the tool's own deadline. */\n  readonly maxTimeoutMs?: number\n  /** Container workspace root (workdir validation). */\n  readonly workspaceRoot?: string\n  /** Unpolled PTY output ceiling in bytes (approx; the tail is kept). */\n  readonly maxTtyBufferBytes?: number\n}\n\nimport type {} from '@deepseek-ai/dsh-jobs'\n\ndeclare module '@deepseek-ai/dsh-jobs' {\n  interface JobKindMap {\n    'pentest-exec': 'pentest-exec'\n  }\n}\n\n/** One tracked PTY process with a read cursor for polling. */\ninterface TrackedTty {\n  readonly process: SandboxTtyProcess\n  buffer: string\n  cursor: number\n  settled: { exitCode: number | null; signal: string | null } | undefined\n}\n\nexport const name = 'pentest-tool-shell'\n\nexport const inject = ['tools', 'pentestSandbox']\n\nexport const Config: Schema<Config> = z.object({\n  scanId: z.string().default('pentest'),\n  sources: z.array(z.object({\n    workspaceSubdir: z.string(),\n    sourcePath: z.string(),\n    protectMetadata: z.boolean(),\n  })),\n  requireApproval: z.boolean().default(true),\n  enableRunInBackground: z.boolean().default(true),\n  defaultTimeoutMs: z.number().default(120_000),\n  maxTimeoutMs: z.number().default(600_000),\n  workspaceRoot: z.string().default('/workspace'),\n  maxTtyBufferBytes: z.number().default(1_048_576),\n})\n\n/**\n * Validate a workdir against the workspace root (strix workdir contract),\n * segment by segment: no absolute escape, no `..`/`.`/empty segments, no\n * trailing slash.\n * @param cwd - the requested working directory.\n * @param workspaceRoot - container workspace root.\n * @returns null when valid, else strix's exact error text.\n */\nexport function workdirError(cwd: string | undefined, workspaceRoot: string): string | null {\n  if (cwd === undefined) return null\n  if (cwd === workspaceRoot) return null\n  const prefix = `${workspaceRoot}/`\n  const inside = cwd.startsWith(prefix)\n    && cwd.slice(prefix.length).split('/').every(segment => segment !== '' && segment !== '.' && segment !== '..')\n  return inside ? null : `exec_command: workdir must be a path inside ${workspaceRoot} (or omitted to use the turn's cwd). Got: '${cwd}'.`\n}\n\n/** Clamp a requested timeout into the configured window. */\nexport function clampTimeout(requested: number | undefined, defaultTimeoutMs: number, maxTimeoutMs: number): number {\n  const value = requested ?? defaultTimeoutMs\n  return Math.min(Math.max(1, value), maxTimeoutMs)\n}\n\nexport function apply(ctx: Context, config: Config = {}): void {\n  const ttyProcesses = new Map<string, TrackedTty>()\n\n  const session = () =>\n    ctx.pentestSandbox.createSession({\n      scanId: config.scanId ?? 'pentest',\n      ...(config.sources !== undefined ? { sources: config.sources.map(source => ({\n        workspaceSubdir: source.workspaceSubdir,\n        sourcePath: source.sourcePath,\n        ...(source.protectMetadata !== undefined ? { protectMetadata: source.protectMetadata } : {}),\n      })) } : {}),\n    })\n\n  if (config.requireApproval !== false) {\n    void ctx.on('tools/pre-execute', async (exec, next) => {\n      if (exec.name === 'exec_command') return { kind: 'ask' as const, reason: 'pentest: run a command inside the attack sandbox' }\n      return next()\n    })\n  }\n\n  const workspaceRoot = config.workspaceRoot ?? '/workspace'\n  const defaultTimeoutMs = config.defaultTimeoutMs ?? 120_000\n  const maxTimeoutMs = config.maxTimeoutMs ?? 600_000\n  const maxTtyBufferBytes = config.maxTtyBufferBytes ?? 1_048_576\n  const backgroundEnabled = config.enableRunInBackground !== false\n\n  ctx.tools.register(defineTool({\n    name: 'exec_command',\n    description: `Run a shell command inside the pentest sandbox (Kali container) in a fresh non-interactive bash login shell. Set tty=true for interactive programs (REPLs, ssh, msfconsole) and then drive them with write_stdin; run_in_background starts a job for long scans and returns a job id for job_output/job_kill.${backgroundEnabled ? '' : ' (run_in_background is disabled in this deployment.)'}`,\n    parameters: {\n      cmd: { type: 'string', required: true, description: 'The shell command line to execute.' },\n      ...(backgroundEnabled ? { run_in_background: { type: 'boolean', description: 'Start as a background job; returns a job id (long scans).' } } : {}),\n      cwd: { type: 'string', description: `Working directory inside ${workspaceRoot}.` },\n      timeout_ms: { type: 'integer', description: 'Per-call timeout in milliseconds (clamped by deployment).' },\n      tty: { type: 'boolean', description: 'Run under a PTY for interactive input via write_stdin.' },\n    },\n    output: {\n      schema: {\n        type: 'object',\n        properties: {\n          kind: { type: 'string', required: true, enum: ['foreground', 'tty', 'background'] },\n          exit_code: { type: 'integer' },\n          signal: { type: 'string' },\n          timed_out: { type: 'boolean' },\n          stdout: { type: 'string' },\n          stderr: { type: 'string' },\n          process_id: { type: 'string' },\n          job_id: { type: 'string' },\n        },\n        additionalProperties: false,\n      },\n      render: (_args, value) => {\n        if (value.kind === 'foreground') {\n          return [{ type: 'text', text: `exit_code=${value.exit_code === null ? 'none' : String(value.exit_code)}${value.timed_out === true ? ' (timed out)' : ''}\\nstdout:\\n${value.stdout}\\nstderr:\\n${value.stderr}` }]\n        }\n        if (value.kind === 'tty') {\n          return [{ type: 'text', text: `PTY process ${value.process_id} started. Poll with write_stdin(process_id=\"${value.process_id}\", chars=\"\"); send input via chars; deliver Ctrl-C with chars=\"\\\\x03\".` }]\n        }\n        return [{ type: 'text', text: `started background job ${value.job_id} (job_output to read, job_kill to stop)` }]\n      },\n    },\n    timeoutMs: maxTimeoutMs,\n    presentCall: args => ({ card: 'terminal', title: String(args.cmd ?? '') }),\n    presentResult: (args, result) => {\n      const text = result.content.filter(block => block.type === 'text').map(block => block.text).join('\\n')\n      return { card: 'terminal', output: text === '' ? String(args.cmd ?? '') : text }\n    },\n    execute: async (args, exec) => {\n      const cwdProblem = workdirError(args.cwd, workspaceRoot)\n      if (cwdProblem !== null) throw new Error(cwdProblem)\n      if (args.tty === true && args.run_in_background === true) {\n        throw new Error('exec_command: tty=true and run_in_background cannot be combined — start a PTY process and drive it with write_stdin, or start a background job without a PTY.')\n      }\n      if (args.run_in_background === true && !backgroundEnabled) throw new Error('run_in_background is disabled for this deployment (enableRunInBackground: false)')\n      const sandbox = await session()\n      if (args.tty === true) {\n        const process = await sandbox.execTty(args.cmd, { cwd: args.cwd })\n        const tracked: TrackedTty = { process, buffer: '', cursor: 0, settled: undefined }\n        process.subscribe(chunk => {\n          tracked.buffer += chunk\n          // Bound unpolled output; keep the tail and re-base the read cursor.\n          if (tracked.buffer.length > maxTtyBufferBytes) {\n            const excess = tracked.buffer.length - maxTtyBufferBytes\n            tracked.buffer = tracked.buffer.slice(excess)\n            tracked.cursor = Math.max(0, tracked.cursor - excess)\n          }\n        })\n        void process.done.then(\n          outcome => {\n            tracked.settled = { exitCode: outcome.exitCode, signal: outcome.signal }\n          },\n          () => {\n            tracked.settled = { exitCode: null, signal: null }\n          },\n        )\n        ttyProcesses.set(process.id, tracked)\n        return { kind: 'tty' as const, process_id: process.id }\n      }\n      if (args.run_in_background === true) {\n        const jobs = ctx.get('jobs')\n        if (jobs === undefined) throw new Error('run_in_background needs a jobs provider (load @deepseek-ai/dsh-jobs-local)')\n        const job = sandbox.execJob(args.cmd, { cwd: args.cwd })\n        let cancelled = false\n        const jobId = jobs.start({\n          kind: 'pentest-exec',\n          label: args.cmd,\n          ...exec.agent !== undefined ? { owner: exec.agent } : {},\n          run: () => ({\n            cancel: () => {\n              cancelled = true\n              job.terminate()\n            },\n            done: job.done.then(outcome =>\n              // A killed docker-exec tree can still report exit code 0; the\n              // cancellation flag is the authoritative kill signal.\n              cancelled\n                ? { status: 'killed' as const, detail: 'cancelled by request' }\n                : {\n                    status: outcome.exitCode === 0 ? 'completed' as const : 'failed' as const,\n                    detail: `exit code: ${outcome.exitCode === null ? 'none' : String(outcome.exitCode)}`,\n                  }),\n            readOutput: () => job.readOutput(),\n          }),\n        })\n        return { kind: 'background' as const, job_id: jobId }\n      }\n      const result = await sandbox.exec(args.cmd, { cwd: args.cwd, timeoutMs: clampTimeout(args.timeout_ms, defaultTimeoutMs, maxTimeoutMs), signal: exec.signal })\n      return {\n        kind: 'foreground' as const,\n        ...(result.exitCode !== null ? { exit_code: result.exitCode } : {}),\n        ...(result.signal !== null ? { signal: result.signal } : {}),\n        timed_out: result.timedOut,\n        stdout: result.stdout,\n        stderr: result.stderr,\n      }\n    },\n  }))\n\n  ctx.tools.register(defineTool({\n    name: 'write_stdin',\n    description: 'Send characters to a PTY-backed process started by exec_command(tty=true). chars=\"\" polls for new output without sending anything. Escapes (\\\\n, \\\\t, \\\\x03 for Ctrl-C, \\\\uXXXX) are decoded.',\n    parameters: {\n      process_id: { type: 'string', required: true, description: 'The process id returned by exec_command(tty=true).' },\n      chars: { type: 'string', required: true, description: 'Characters to write (\"\" to poll for output only).' },\n    },\n    output: {\n      schema: {\n        type: 'object',\n        properties: {\n          output: { type: 'string', required: true },\n          running: { type: 'boolean', required: true },\n          exit_code: { type: 'integer' },\n        },\n        additionalProperties: false,\n      },\n      render: (_args, value) => [{\n        type: 'text',\n        text: `${value.running ? '(running)' : `(exited${value.exit_code === undefined ? '' : ` exit_code=${String(value.exit_code)}`})`}\\n${value.output}`,\n      }],\n    },\n    execute: async args => {\n      const tracked = ttyProcesses.get(args.process_id)\n      if (tracked === undefined) throw new Error(STDIN_UNAVAILABLE)\n      const chars = decodeCharsEscape(args.chars)\n      if (chars !== '') await tracked.process.write(chars)\n      const delta = tracked.buffer.slice(tracked.cursor)\n      tracked.cursor = tracked.buffer.length\n      if (tracked.settled !== undefined) ttyProcesses.delete(args.process_id)\n      return {\n        output: delta,\n        running: tracked.settled === undefined,\n        ...(tracked.settled !== undefined && tracked.settled.exitCode !== null ? { exit_code: tracked.settled.exitCode } : {}),\n      }\n    },\n  }))\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@gpzhang2001/sharpkit-shell",
+  "description": "exec_command / write_stdin model-facing shell tools over the sharpkit sandbox",
+  "version": "0.2.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gpzhang2001/sharpkit.git",
+    "directory": "packages/tool-shell"
+  },
+  "type": "module",
+  "license": "Apache-2.0",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "dependencies": {
+    "@deepseek-ai/schemastery": "3.18.2",
+    "@gpzhang2001/sharpkit-sandbox": "^0.2.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-jobs": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.1.2-rc.1",
+    "@gpzhang2001/sharpkit-sandbox": "^0.1.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.2",
+    "@deepseek-ai/dsh-jobs": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-tools": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-llm": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-jobs-local": "0.1.2-rc.1"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "scripts": {
+    "build": "cp ../../LICENSE ../../THIRD_PARTY_NOTICES.md . && tsdown && mv -f lib/index.ts lib/index.d.ts && mv -f lib/index.ts.map lib/index.d.ts.map"
+  }
+}

package/src/chars.ts

@@ -0,0 +1,34 @@
+/**
+ * Escape decoding for `write_stdin` chars, ported verbatim from strix
+ * factory.py `_decode_chars_escape` (\\uXXXX, \\xNN, and the C-style short
+ * escapes; unknown escapes and backslash-free strings pass through).
+ * @module @gpzhang2001/sharpkit-shell/chars
+ */
+
+const ESCAPE_RE = /\\(?:u[0-9a-fA-F]{4}|x[0-9a-fA-F]{2}|[0abtnvfr\\])/g
+
+const SHORT_ESCAPES: Record<string, string> = {
+  '\\\\': '\\',
+  '\\n': '\n',
+  '\\t': '\t',
+  '\\r': '\r',
+  '\\0': '\x00',
+  '\\a': '\x07',
+  '\\b': '\x08',
+  '\\v': '\x0b',
+  '\\f': '\x0c',
+}
+
+/**
+ * Decode the model-facing escape forms in a `chars` argument.
+ * @param chars - the raw argument value.
+ * @returns the decoded characters to deliver to the process.
+ */
+export function decodeCharsEscape(chars: string): string {
+  if (!chars.includes('\\')) return chars
+  return chars.replace(ESCAPE_RE, token => {
+    const short = SHORT_ESCAPES[token]
+    if (short !== undefined) return short
+    return String.fromCodePoint(Number.parseInt(token.slice(2), 16))
+  })
+}

package/src/index.ts

@@ -0,0 +1,284 @@
+/**
+ * `exec_command` / `write_stdin` model-facing shell tools over the pentest
+ * sandbox — strix SDK ShellTool semantics (tools/shell/README.md + factory
+ * wrapping): a fresh non-interactive login shell per call by default, PTY
+ * processes for interactive work driven by `write_stdin` (chars="" polls),
+ * workdir restricted to the workspace, per-call timeout clamped by config,
+ * and `run_in_background` mapped onto the dsh jobs runtime
+ * (job_output/job_list/job_kill come free). Every exec passes an ask
+ * approval gate (config-gated; the registry resolves `ask` through the
+ * host's approval service and fails closed when none is composed).
+ * @module @gpzhang2001/sharpkit-shell
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type Schema from '@deepseek-ai/schemastery'
+import z from '@deepseek-ai/schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { SandboxTtyProcess } from '@gpzhang2001/sharpkit-sandbox'
+import { decodeCharsEscape } from './chars.ts'
+
+/** strix's exact refusal text for write_stdin against a non-PTY process. */
+export const STDIN_UNAVAILABLE = "stdin is not available for this process. Start the command with 'tty=true' in 'exec_command' before using 'write_stdin'."
+
+/** One source tree Config entry (mutable twin of the sandbox spec for schemastery). */
+export interface ConfigSource {
+  workspaceSubdir: string
+  sourcePath: string
+  protectMetadata?: boolean
+}
+
+/** Deployment-tunable configuration. */
+export interface Config {
+  /** Sandbox session cache key; the orchestrator pre-creates the real session under this id. */
+  readonly scanId?: string
+  /** Source trees for the session this tool creates when none exists yet. */
+  readonly sources?: ConfigSource[]
+  /** Ask-approval gate on every exec_command (fail-closed without an approval service). */
+  readonly requireApproval?: boolean
+  /** Expose run_in_background (needs a jobs provider at runtime). */
+  readonly enableRunInBackground?: boolean
+  /** Default per-call timeout; model values are clamped into [1, maxTimeoutMs]. */
+  readonly defaultTimeoutMs?: number
+  /** Hard ceiling for the model's timeout_ms and the tool's own deadline. */
+  readonly maxTimeoutMs?: number
+  /** Container workspace root (workdir validation). */
+  readonly workspaceRoot?: string
+  /** Unpolled PTY output ceiling in bytes (approx; the tail is kept). */
+  readonly maxTtyBufferBytes?: number
+}
+
+import type {} from '@deepseek-ai/dsh-jobs'
+
+declare module '@deepseek-ai/dsh-jobs' {
+  interface JobKindMap {
+    'pentest-exec': 'pentest-exec'
+  }
+}
+
+/** One tracked PTY process with a read cursor for polling. */
+interface TrackedTty {
+  readonly process: SandboxTtyProcess
+  buffer: string
+  cursor: number
+  settled: { exitCode: number | null; signal: string | null } | undefined
+}
+
+export const name = 'pentest-tool-shell'
+
+export const inject = ['tools', 'pentestSandbox']
+
+export const Config: Schema<Config> = z.object({
+  scanId: z.string().default('pentest'),
+  sources: z.array(z.object({
+    workspaceSubdir: z.string(),
+    sourcePath: z.string(),
+    protectMetadata: z.boolean(),
+  })),
+  requireApproval: z.boolean().default(true),
+  enableRunInBackground: z.boolean().default(true),
+  defaultTimeoutMs: z.number().default(120_000),
+  maxTimeoutMs: z.number().default(600_000),
+  workspaceRoot: z.string().default('/workspace'),
+  maxTtyBufferBytes: z.number().default(1_048_576),
+})
+
+/**
+ * Validate a workdir against the workspace root (strix workdir contract),
+ * segment by segment: no absolute escape, no `..`/`.`/empty segments, no
+ * trailing slash.
+ * @param cwd - the requested working directory.
+ * @param workspaceRoot - container workspace root.
+ * @returns null when valid, else strix's exact error text.
+ */
+export function workdirError(cwd: string | undefined, workspaceRoot: string): string | null {
+  if (cwd === undefined) return null
+  if (cwd === workspaceRoot) return null
+  const prefix = `${workspaceRoot}/`
+  const inside = cwd.startsWith(prefix)
+    && cwd.slice(prefix.length).split('/').every(segment => segment !== '' && segment !== '.' && segment !== '..')
+  return inside ? null : `exec_command: workdir must be a path inside ${workspaceRoot} (or omitted to use the turn's cwd). Got: '${cwd}'.`
+}
+
+/** Clamp a requested timeout into the configured window. */
+export function clampTimeout(requested: number | undefined, defaultTimeoutMs: number, maxTimeoutMs: number): number {
+  const value = requested ?? defaultTimeoutMs
+  return Math.min(Math.max(1, value), maxTimeoutMs)
+}
+
+export function apply(ctx: Context, config: Config = {}): void {
+  const ttyProcesses = new Map<string, TrackedTty>()
+
+  const session = () =>
+    ctx.pentestSandbox.createSession({
+      scanId: config.scanId ?? 'pentest',
+      ...(config.sources !== undefined ? { sources: config.sources.map(source => ({
+        workspaceSubdir: source.workspaceSubdir,
+        sourcePath: source.sourcePath,
+        ...(source.protectMetadata !== undefined ? { protectMetadata: source.protectMetadata } : {}),
+      })) } : {}),
+    })
+
+  if (config.requireApproval !== false) {
+    void ctx.on('tools/pre-execute', async (exec, next) => {
+      if (exec.name === 'exec_command') return { kind: 'ask' as const, reason: 'pentest: run a command inside the attack sandbox' }
+      return next()
+    })
+  }
+
+  const workspaceRoot = config.workspaceRoot ?? '/workspace'
+  const defaultTimeoutMs = config.defaultTimeoutMs ?? 120_000
+  const maxTimeoutMs = config.maxTimeoutMs ?? 600_000
+  const maxTtyBufferBytes = config.maxTtyBufferBytes ?? 1_048_576
+  const backgroundEnabled = config.enableRunInBackground !== false
+
+  ctx.tools.register(defineTool({
+    name: 'exec_command',
+    description: `Run a shell command inside the pentest sandbox (Kali container) in a fresh non-interactive bash login shell. Set tty=true for interactive programs (REPLs, ssh, msfconsole) and then drive them with write_stdin; run_in_background starts a job for long scans and returns a job id for job_output/job_kill.${backgroundEnabled ? '' : ' (run_in_background is disabled in this deployment.)'}`,
+    parameters: {
+      cmd: { type: 'string', required: true, description: 'The shell command line to execute.' },
+      ...(backgroundEnabled ? { run_in_background: { type: 'boolean', description: 'Start as a background job; returns a job id (long scans).' } } : {}),
+      cwd: { type: 'string', description: `Working directory inside ${workspaceRoot}.` },
+      timeout_ms: { type: 'integer', description: 'Per-call timeout in milliseconds (clamped by deployment).' },
+      tty: { type: 'boolean', description: 'Run under a PTY for interactive input via write_stdin.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          kind: { type: 'string', required: true, enum: ['foreground', 'tty', 'background'] },
+          exit_code: { type: 'integer' },
+          signal: { type: 'string' },
+          timed_out: { type: 'boolean' },
+          stdout: { type: 'string' },
+          stderr: { type: 'string' },
+          process_id: { type: 'string' },
+          job_id: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        if (value.kind === 'foreground') {
+          return [{ type: 'text', text: `exit_code=${value.exit_code === null ? 'none' : String(value.exit_code)}${value.timed_out === true ? ' (timed out)' : ''}\nstdout:\n${value.stdout}\nstderr:\n${value.stderr}` }]
+        }
+        if (value.kind === 'tty') {
+          return [{ type: 'text', text: `PTY process ${value.process_id} started. Poll with write_stdin(process_id="${value.process_id}", chars=""); send input via chars; deliver Ctrl-C with chars="\\x03".` }]
+        }
+        return [{ type: 'text', text: `started background job ${value.job_id} (job_output to read, job_kill to stop)` }]
+      },
+    },
+    timeoutMs: maxTimeoutMs,
+    presentCall: args => ({ card: 'terminal', title: String(args.cmd ?? '') }),
+    presentResult: (args, result) => {
+      const text = result.content.filter(block => block.type === 'text').map(block => block.text).join('\n')
+      return { card: 'terminal', output: text === '' ? String(args.cmd ?? '') : text }
+    },
+    execute: async (args, exec) => {
+      const cwdProblem = workdirError(args.cwd, workspaceRoot)
+      if (cwdProblem !== null) throw new Error(cwdProblem)
+      if (args.tty === true && args.run_in_background === true) {
+        throw new Error('exec_command: tty=true and run_in_background cannot be combined — start a PTY process and drive it with write_stdin, or start a background job without a PTY.')
+      }
+      if (args.run_in_background === true && !backgroundEnabled) throw new Error('run_in_background is disabled for this deployment (enableRunInBackground: false)')
+      const sandbox = await session()
+      if (args.tty === true) {
+        const process = await sandbox.execTty(args.cmd, { cwd: args.cwd })
+        const tracked: TrackedTty = { process, buffer: '', cursor: 0, settled: undefined }
+        process.subscribe(chunk => {
+          tracked.buffer += chunk
+          // Bound unpolled output; keep the tail and re-base the read cursor.
+          if (tracked.buffer.length > maxTtyBufferBytes) {
+            const excess = tracked.buffer.length - maxTtyBufferBytes
+            tracked.buffer = tracked.buffer.slice(excess)
+            tracked.cursor = Math.max(0, tracked.cursor - excess)
+          }
+        })
+        void process.done.then(
+          outcome => {
+            tracked.settled = { exitCode: outcome.exitCode, signal: outcome.signal }
+          },
+          () => {
+            tracked.settled = { exitCode: null, signal: null }
+          },
+        )
+        ttyProcesses.set(process.id, tracked)
+        return { kind: 'tty' as const, process_id: process.id }
+      }
+      if (args.run_in_background === true) {
+        const jobs = ctx.get('jobs')
+        if (jobs === undefined) throw new Error('run_in_background needs a jobs provider (load @deepseek-ai/dsh-jobs-local)')
+        const job = sandbox.execJob(args.cmd, { cwd: args.cwd })
+        let cancelled = false
+        const jobId = jobs.start({
+          kind: 'pentest-exec',
+          label: args.cmd,
+          ...exec.agent !== undefined ? { owner: exec.agent } : {},
+          run: () => ({
+            cancel: () => {
+              cancelled = true
+              job.terminate()
+            },
+            done: job.done.then(outcome =>
+              // A killed docker-exec tree can still report exit code 0; the
+              // cancellation flag is the authoritative kill signal.
+              cancelled
+                ? { status: 'killed' as const, detail: 'cancelled by request' }
+                : {
+                    status: outcome.exitCode === 0 ? 'completed' as const : 'failed' as const,
+                    detail: `exit code: ${outcome.exitCode === null ? 'none' : String(outcome.exitCode)}`,
+                  }),
+            readOutput: () => job.readOutput(),
+          }),
+        })
+        return { kind: 'background' as const, job_id: jobId }
+      }
+      const result = await sandbox.exec(args.cmd, { cwd: args.cwd, timeoutMs: clampTimeout(args.timeout_ms, defaultTimeoutMs, maxTimeoutMs), signal: exec.signal })
+      return {
+        kind: 'foreground' as const,
+        ...(result.exitCode !== null ? { exit_code: result.exitCode } : {}),
+        ...(result.signal !== null ? { signal: result.signal } : {}),
+        timed_out: result.timedOut,
+        stdout: result.stdout,
+        stderr: result.stderr,
+      }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'write_stdin',
+    description: 'Send characters to a PTY-backed process started by exec_command(tty=true). chars="" polls for new output without sending anything. Escapes (\\n, \\t, \\x03 for Ctrl-C, \\uXXXX) are decoded.',
+    parameters: {
+      process_id: { type: 'string', required: true, description: 'The process id returned by exec_command(tty=true).' },
+      chars: { type: 'string', required: true, description: 'Characters to write ("" to poll for output only).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          output: { type: 'string', required: true },
+          running: { type: 'boolean', required: true },
+          exit_code: { type: 'integer' },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: `${value.running ? '(running)' : `(exited${value.exit_code === undefined ? '' : ` exit_code=${String(value.exit_code)}`})`}\n${value.output}`,
+      }],
+    },
+    execute: async args => {
+      const tracked = ttyProcesses.get(args.process_id)
+      if (tracked === undefined) throw new Error(STDIN_UNAVAILABLE)
+      const chars = decodeCharsEscape(args.chars)
+      if (chars !== '') await tracked.process.write(chars)
+      const delta = tracked.buffer.slice(tracked.cursor)
+      tracked.cursor = tracked.buffer.length
+      if (tracked.settled !== undefined) ttyProcesses.delete(args.process_id)
+      return {
+        output: delta,
+        running: tracked.settled === undefined,
+        ...(tracked.settled !== undefined && tracked.settled.exitCode !== null ? { exit_code: tracked.settled.exitCode } : {}),
+      }
+    },
+  }))
+}