npm - pentesting - Versions diffs - 0.100.5 → 0.100.7 - Mend

pentesting 0.100.5 → 0.100.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/LICENSE CHANGED Viewed

@@ -1,28 +1,28 @@
-MIT License
-Copyright (c) 2026 agnusdei1207
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
----
-Note: This MIT license covers the published `pentesting` npm wrapper (the
-launcher in `bin/` and `lib/` plus its install scripts). The Builder runtime
-engine that the wrapper downloads and executes is a separate, proprietary
-component and is not licensed under these terms.
+MIT License
+Copyright (c) 2026 agnusdei1207
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+---
+Note: This MIT license covers the published `pentesting` npm wrapper (the
+launcher in `bin/` and `lib/` plus its install scripts). The Builder runtime
+engine that the wrapper downloads and executes is a separate, proprietary
+component and is not licensed under these terms.

package/README.md CHANGED Viewed

@@ -1,227 +1,280 @@
-# Pentesting 🔓
-> **Pentesting** is a local-first Rust coding agent CLI for authorized security work, with audited reverse-shell and PTY session control: catch callbacks, verify upgrades, pivot across sessions, and reclaim them cleanly.
-The runtime—not the model—owns routing, tool sandboxing, verification, completion adjudication, and PTY/session lifecycle management. PTYs are first-class runtime objects: upgrade state, resize authority, transcript capture, file-descriptor ownership, and close/revoke/gc reclamation are all tracked explicitly.
-<div align="center">
-  <img src="https://api.iconify.design/hugeicons:bash.svg" alt="pentesting bash icon" width="120" />
-  <h1>pentesting</h1>
-  <p>Security-Focused Agent Runtime</p>
-  [![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
-  [![npm](https://img.shields.io/npm/v/pentesting.svg)](https://www.npmjs.com/package/pentesting)
-</div>
----
-## ✅ Capabilities
-Agent-loop essentials plus a security-focused runtime layer.
-| Area | What it does |
-| --- | --- |
-| Model-driven loop | Streaming tool-use loop; the model decides when it's done |
-| Tool guardrails | Read-before-edit enforcement, repeat-call guard, policy-gated file/shell/network |
-| Permissions | Allow / Deny / Confirm, with once/always decisions persisted |
-| Context compaction | Automatic micro-pruning + model-triggered summarization, pre/post hooks |
-| Interrupt & steering | ESC to interrupt mid-turn, queue follow-ups while it works, and keep Enter submissions deterministic across PTY redraw/control-response noise |
-| Reverse-shell control plane | Accept and track multiple authorized callbacks, tag/probe sessions, send/observe/run commands, verify PTY upgrades, and keep transcript/ledger/evidence records |
-| PTY session control | Treat upgraded shells as managed PTY sessions with resize gating, transcript capture, FD accounting, and deterministic close/revoke/gc reclamation |
-| Frontier-guided exploration | Persistent, deduplicated lead frontier: the runtime enforces pivots and caps, and recommends breadth-first enumeration vs depth-first exploitation while the model drives |
-| Subagents | Broad-clone delegates with category focus overlays; independent deep-specialist leads (crypto/rev/pwn) run in the same parallel batch so the main line keeps moving |
-| MCP & skills | Dynamic MCP tool discovery, layered markdown skills |
-| Memory | Ebbinghaus-style decaying notes + hybrid lexical/semantic/graph retrieval |
----
-## 🚀 Quick Start
-Install globally, or run once with a Node package runner:
-```bash
-npm install -g pentesting && pentesting   # install
-npx pentesting                            # or run once, no install
-pnpm dlx pentesting
-yarn dlx pentesting
-```
-Requires Node.js 18.18+. Use npm/npx/pnpm/yarn; Bun and Deno runners are not supported.
+# Pentesting 🔓
+<div align="center">
+  <img src="https://api.iconify.design/hugeicons:bash.svg" alt="pentesting bash icon" width="120" />
+  <h1>pentesting</h1>
+  <p>Security-Focused Agent Runtime</p>
+[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![npm](https://img.shields.io/npm/v/pentesting.svg)](https://www.npmjs.com/package/pentesting)
+</div>
+---
+## ✅ Capabilities
+Agent-loop essentials plus a security-focused runtime layer.
+| Area                        | What it does                                                                                                                                                          |
+| --- | --- |
+| Model-driven loop           | Streaming action/observation loop; model Stop ends a turn, while verified artifacts close a mission and the full turn trajectory is persisted with the outcome        |
+| Tool guardrails             | Read-before-edit enforcement, repeat-call guard, policy-gated file/shell/network                                                                                      |
+| Permissions                 | Allow / Deny / Confirm, with once/always decisions persisted                                                                                                          |
+| Context compaction          | Automatic micro-pruning + model-triggered summarization, pre/post hooks                                                                                               |
+| Interrupt & steering        | ESC interruption plus a revisioned FIFO queue with explicit amend/replace intent and deterministic PTY Enter ownership                                                |
+| Reverse-shell control plane | Accept and track multiple authorized callbacks, tag/probe sessions, send/observe/run commands, verify PTY upgrades, and keep transcript/ledger/evidence records       |
+| PTY session control         | One actor owns each socket/PTY/pipe, command queue, transcript, and child lifecycle, with resize gating, FD accounting, and deterministic close/revoke/gc reclamation |
+| Frontier-guided exploration | Always-available bounded security tool with a lead ledger, explicit dispatch, and knowledge-preserving dead-probe pivots                                              |
+| Subagents                   | Broad-clone delegates with category focus overlays; independent deep-specialist leads (crypto/rev/pwn) run in the same parallel batch so the main line keeps moving   |
+| MCP & skills                | Dynamic MCP tool discovery, layered markdown skills                                                                                                                   |
+| Memory                      | Ebbinghaus-style decaying notes + hybrid lexical/semantic/graph retrieval                                                                                             |
+---
+The default execution path is one agent loop, but subagents remain available
+through the `task` tool for independently scoped work and bounded parallel
+exploration. Child runs use the same permissions and tool gateway, carry a
+focused overlay and runtime budget, and merge evidence back by reference.
+---
+## 🚀 Quick Start
+Install globally, or run once with a Node package runner:
+```bash
+npm install -g pentesting && pentesting   # install
+npx pentesting                            # or run once, no install
+pnpm dlx pentesting
+yarn dlx pentesting
+```
+Requires Node.js 18.18+. Use npm/npx/pnpm/yarn; Bun and Deno runners are not supported.
+### Docker-only development builds
+Repository builds and Rust tests must always use the resource-capped Docker
+wrappers. Host Cargo compilation is fail-closed; free disk or RAM does not make
+it an approved path.
+```bash
+scripts/dbuild.sh check --workspace --all-targets
+scripts/dbuild.sh test -p builder_domain
+scripts/dverify.sh focused
+scripts/dverify.sh full
+scripts/dbuild-image.sh validation                                                # once per fresh Docker cache
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts/dbuild.ps1 test -p builder_domain  # Windows
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts/nverify.ps1                  # Windows npm verify
+```
+The wrappers cap memory, CPU, PIDs, jobs, test threads, and time; verify storage
+before launch; serialize heavy work; and leave a redacted resource report. CI
+uses the same Docker-only path. Full policy: [Docker-only build safety](https://github.com/agnusdei1207/pentesting/blob/main/docs/BUILD_SAFETY.md).
 ### 🐳 Run with Docker
 No local Rust toolchain needed:
-```bash
-export OPENAI_API_KEY="sk-..."                 # provider API key or gateway token
-export OPENAI_BASE_URL="https://api.openai.com/v1"
-export OPENAI_MODEL="gpt-4o"
-export OPENAI_MAX_TOKENS="4096"
-docker run -it --rm \
-  -v "$(pwd):/workspace" \
-  -v pentesting-config:/root/.pentesting \
-  -w /workspace \
-  -e OPENAI_API_KEY \
-  -e OPENAI_BASE_URL \
-  -e OPENAI_MODEL \
-  -e OPENAI_MAX_TOKENS \
-  agnusdei1207/pentesting:latest
-```
-Provider environment variables are optional for startup. If they are omitted,
-the interactive TUI still launches and lets you configure/login inside the
-persistent `pentesting-config` volume.
-Or via Docker Compose:
-```bash
-PENTESTING_PROJECT_DIR=/path/to/project \
-OPENAI_API_KEY=sk-... \
-OPENAI_BASE_URL=https://api.openai.com/v1 \
-OPENAI_MODEL=gpt-4o \
-OPENAI_MAX_TOKENS=4096 \
-docker compose run --rm pentesting
-```
+Published images support `linux/amd64` only. Docker is the recommended runtime
+on Windows and macOS; Apple Silicon Macs run the amd64 image through Docker
+Desktop emulation. Native ARM64 images and binaries are not supported.
+```bash
+export OPENAI_API_KEY="sk-..."                 # provider API key or gateway token
+export OPENAI_BASE_URL="https://api.openai.com/v1"
+export OPENAI_MODEL="gpt-4o"
+export OPENAI_MAX_TOKENS="4096"
+docker run -it --rm \
+  -v "$(pwd):/workspace" \
+  -v pentesting-config:/root/.pentesting \
+  -w /workspace \
+  -e OPENAI_API_KEY \
+  -e OPENAI_BASE_URL \
+  -e OPENAI_MODEL \
+  -e OPENAI_MAX_TOKENS \
+  agnusdei1207/pentesting:latest
+```
+Provider environment variables are optional for startup. If they are omitted,
+the interactive TUI still launches and lets you configure/login inside the
+persistent `pentesting-config` volume.
+Or via Docker Compose:
+```bash
+PENTESTING_PROJECT_DIR=/path/to/project \
+OPENAI_API_KEY=sk-... \
+OPENAI_BASE_URL=https://api.openai.com/v1 \
+OPENAI_MODEL=gpt-4o \
+OPENAI_MAX_TOKENS=4096 \
+docker compose run --rm pentesting
+```
 ### Common commands
-```bash
-pentesting                                                # Interactive TUI
-pentesting --prompt "Enumerate the target and summarize next actions."
-pentesting shell-listener --bind 127.0.0.1 --port 4444   # Authorized reverse-shell listener
-pentesting --version
-```
+```bash
+pentesting                                                # Interactive TUI
+pentesting --prompt "Enumerate the target and summarize next actions."
+pentesting shell-listener --bind 127.0.0.1 --port 4444   # Authorized reverse-shell listener
+pentesting --version
+```
 Use `shell-listener` in authorized CTF/lab work to accept callbacks, tag sessions, run sentinel-tracked commands, verify PTY upgrades, and retain transcripts/evidence.
 Short version: the agent can catch a dumb reverse shell, upgrade it to a verified PTY, pivot to a second callback, and reclaim both sessions cleanly with `close` / `revoke` / `gc`.
-Inside a session, `/help` lists every command and `/update` pulls the latest release for supported native targets.
+### Interactive control defaults
-### 🔌 Reverse-shell & PTY sessions
+- `/model` owns a modal terminal surface. Returning from it restores the prior
+  transcript cursor before the fixed prompt/status rows are redrawn, so later
+  responses and errors append instead of overwriting the input area.
+- `/goal <task>` records the goal only. Autonomous continuation starts off and
+  can be enabled or stopped only with an explicit `/auto` command.
+- Tool/request budget exhaustion does not create a fresh turn while auto mode
+  is off. A submitted queued input takes precedence over autonomous follow-up.
+- Submitted type-ahead is consumed once in FIFO order at the next safe turn
+  boundary. Only explicit amend/replace intent may change that handoff.
-Catch and manage authorized shell callbacks: one listener, many targets, audited cleanup.
+On native Windows Git Bash, the repository smoke path builds the capped Docker
+image and then opens this interactive TUI without WSL:
 ```bash
-pentesting shell-listener --port 4444             # 1. Catch callbacks (tracks many at once)
-pentesting shell-session list                     # 2. See every live session + FD ownership
-pentesting shell-session run -- id                # 3. Run sentinel-bounded commands, capture output
-pentesting shell-session pty-upgrade              # 4. Inject the PTY helper; `upgrade` then verifies it
-pentesting shell-session revoke --session 1       # 5. Hard-close: reclaim FDs + archive evidence
+npm run check
 ```
-- **Track** — each callback is accepted, numbered, and tagged; `list` / `info` / `fdstat` / `lifecycle` show live state, byte counts, and FD ownership.
-- **Drive** — `run` wraps commands in a sentinel to capture exactly their output; `send` / `raw` / `signal` / `resize` give interactive control.
-- **Upgrade** — `pty-upgrade` sends the built-in helper and `upgrade` verifies a real PTY before remote resize is allowed; the agent must pick the method with `--technique` (`python3`, `python`, `python2`, `script`, `expect` — no default) after reconning what the target actually has, or send a fully custom command instead.
-- **Record** — per-session raw log, full-duplex transcript, command ledger, replay, and evidence manifest — with secret redaction for registered values.
-- **Reclaim** — `close` (graceful) and `revoke` (hard) release file descriptors immediately and archive the session; `gc` prunes closed sessions. Reclamation is tracked end-to-end, so FDs never leak.
----
-## ⚙️ Configuration
-Pentesting uses local storage by default. For normal use, configure only the model endpoint:
-### Example `.env` / shell setup
-```bash
-# OpenAI-compatible provider or gateway
-export OPENAI_API_KEY="sk-..."
-export OPENAI_BASE_URL="https://api.openai.com/v1"
-export OPENAI_MODEL="gpt-4o"
-export OPENAI_MAX_TOKENS="4096"
-# Runtime overrides (optional)
-export PENTESTING_CONFIG="$HOME/.config/pentesting"      # move the global config dir
-export PENTESTING_SKIP_DOWNLOAD=1                        # skip postinstall binary download (CI)
-```
-The TUI pre-fills output max tokens from known model names/provider metadata. `OPENAI_MAX_TOKENS` and the TUI field are explicit overrides for custom/self-hosted models.
-### Frontier-guided CTF exploration
-The global frontier engine default stays off, but CTF-shaped engagement config
-auto-applies the CTF runtime profile: `ctf-competition` autonomy, runtime
-exploration, autonomous continuation, and a completion gate that requires
-verified `flag_check` evidence. A ready-to-copy profile lives at
-`docs/config/ctf.toml`:
-```toml
-[engagement]
-kind = "ctf"
-flag_format = "flag\\{[^}]+\\}"
-require_flag_evidence = true
-[exploration]
-enabled = true
-max_frontier_nodes = 256
-max_breadth = 4
-```
-With the profile active, the runtime stores `explore` leads as
-`EvidenceKind::Lead` events, carries prior-run frontier/findings/verified flags
-forward, deduplicates leads, auto-pivots dead probes, enforces graph/cap limits,
-and injects a breadth/depth recommendation into mission control. The model still
-drives the work through `explore` and `task`; heavy independent leads such as
-crypto/rev/pwn ride the same parallel delegation batch rather than a detached
-background scheduler. Operators can inspect the current graph with `/frontier`,
-and the status row shows compact frontier progress during dispatch.
-Malformed tool-call output is fail-loud: unparsed tool-shaped markup is retried
-instead of accepted as a final answer, the TUI suppresses raw control markup, and
-large no-newline streams are bounded so rendering cannot hang behind usage-only
-progress ticks.
-The shipped contract is covered by
-`cargo test -p builder_app orch_spec::exploration_e2e`: it verifies the
-flag-off regression path plus breadth enumeration, depth descent, sibling
-breadth, dead-probe pivot, global reseed, seed digest, broad-clone overlay, and
-child result promotion.
-With Docker, mount both your project and the persistent runtime config volume, then pass the same variables through with `-e`:
-```bash
-docker run -it --rm \
-  -v "$(pwd):/workspace" \
-  -v pentesting-config:/root/.pentesting \
-  -w /workspace \
-  -e OPENAI_API_KEY \
-  -e OPENAI_BASE_URL \
-  -e OPENAI_MODEL \
-  -e OPENAI_MAX_TOKENS \
-  agnusdei1207/pentesting:latest
-```
-Those variables only pre-fill provider settings. Leaving them unset must not
-block the container from launching the TUI; configure the provider interactively
-inside the container instead.
-> **Note:** The command you run is always **`pentesting`**. The internal engine is **`builder`** — `pentesting` downloads and runs it under the hood; the engine name never surfaces in normal use.
----
-## 📖 Documentation
-* [`ARCHITECTURE.md`](ARCHITECTURE.md) — Runtime flow, agent team, memory model, crate map, tool surface, and supported targets.
-* Internal layout: service traits are split under `builder_app/src/services/*`; OpenAI request conversion is isolated under `dto/openai/request/*`.
-* [Public site](https://agnusdei1207.github.io/pentesting-public/) — Landing page and public runtime entry surface.
-* [`compose.yaml`](https://github.com/agnusdei1207/pentesting-public) — Docker Compose facade for pentesting sessions.
----
-## 🎹 From the Developer
-<div align="center">
-  <img src="https://github.com/user-attachments/assets/abe73474-f27b-4536-b358-fedef1e461f0" alt="Chopin Ballade No.4" width="600" />
-</div>
-<br/>
-> "I believe playing the piano is also a form of orchestration."
->
-> The harmony of polyphony — multiple voices — and homophony — a single melodic line.
->
-> Each voice sings its most beautiful song from its own place, yet when combined, they create one grand, beautiful melody. I believe this structure is no different from AI agents.
->
-> — *agnusdei1207*
+Inside a session, `/help` lists every command and `/update` pulls the latest release for supported native targets.
+### 🔌 Reverse-shell & PTY sessions
+Catch and manage authorized shell callbacks: one listener, many targets, audited cleanup.
+```bash
+pentesting shell-listener --port 4444             # 1. Catch callbacks (tracks many at once)
+pentesting shell-session list                     # 2. See every live session + FD ownership
+pentesting shell-session run -- id                # 3. Run sentinel-bounded commands, capture output
+pentesting shell-session pty-upgrade              # 4. Inject the PTY helper; `upgrade` then verifies it
+pentesting shell-session revoke --session 1       # 5. Hard-close: reclaim FDs + archive evidence
+```
+- **Track** — each callback is accepted, numbered, and tagged; one session actor exclusively owns its live descriptors, transcript, and child lifecycle. `list` / `info` / `fdstat` / `lifecycle` show state and byte counts without cloned reader/writer descriptors.
+- **Drive** — `run` wraps commands in a sentinel to capture exactly their output; `send` / `raw` / `signal` / `resize` give interactive control.
+- **Upgrade** — `pty-upgrade` sends the built-in helper and `upgrade` verifies a real PTY before remote resize is allowed; the agent must pick the method with `--technique` (`python3`, `python`, `python2`, `script`, `expect` — no default) after reconning what the target actually has, or send a fully custom command instead.
+- **Record** — per-session raw log, full-duplex transcript, command ledger, replay, and evidence manifest — with secret redaction for registered values.
+- **Reclaim** — `close` (graceful) and `revoke` (hard) release file descriptors immediately and archive the session; `gc` prunes closed sessions. Reclamation is tracked end-to-end, so FDs never leak.
+---
+## ⚙️ Configuration
+Pentesting uses local storage by default. For normal use, configure only the model endpoint:
+### Example `.env` / shell setup
+```bash
+# OpenAI-compatible provider or gateway
+export OPENAI_API_KEY="sk-..."
+export OPENAI_BASE_URL="https://api.openai.com/v1"
+export OPENAI_MODEL="gpt-4o"
+export OPENAI_MAX_TOKENS="4096"
+# Runtime overrides (optional)
+export PENTESTING_CONFIG="$HOME/.config/pentesting"      # move the global config dir
+export PENTESTING_SKIP_DOWNLOAD=1                        # skip postinstall binary download (CI)
+```
+The TUI pre-fills output max tokens from known model names/provider metadata. `OPENAI_MAX_TOKENS` and the TUI field are explicit overrides for custom/self-hosted models.
+### Frontier-guided CTF exploration
+There are no separate security, CTF, and frontier modes. Session/process,
+finding/verification, `flag_check`, and `explore` tools share one default
+security surface. Engagement metadata describes scope, target, and flag format;
+it does not unlock tools. CTF-shaped context may tailor the prompt, while
+`flag_check` remains a verification tool and evidence source instead of a
+default completion gate. `[exploration]` contains only resource caps. A
+ready-to-copy context lives at
+`docs/config/ctf.toml`:
+```toml
+[engagement]
+kind = "ctf"
+flag_format = "flag\\{[^}]+\\}"
+require_flag_evidence = false
+[exploration]
+max_frontier_nodes = 256
+max_breadth = 4
+```
+With the profile active, the runtime stores `explore` leads as bounded
+`EvidenceKind::Lead` events and reuses prior-run records by reference rather
+than copying them. A repeated dead probe suppresses that execution path but
+does not reject the underlying hypothesis; fresh evidence reopens it. The model
+still drives work through the explicit `explore` and `task` tools. Exploration
+does not replace the core execution strategy, add a background scheduler, or
+expose a passive `/frontier` UI/query path. Node, breadth, and depth limits bound
+its cost.
+Malformed tool-call output is fail-loud: unparsed tool-shaped markup is retried
+instead of accepted as a final answer, the TUI suppresses raw control markup, and
+long no-newline streams flush at soft text boundaries so rendering cannot hang
+behind usage-only progress ticks. The startup banner and live status row stay
+compact; generic run, token, and queued-input detail lives in `/status`.
+The shipped contract is covered by
+`scripts/dbuild.sh test -p builder_app orch_spec::exploration_e2e`: it verifies the
+always-available tool path plus breadth enumeration, depth descent, sibling
+breadth, dead-probe pivot, global reseed, seed digest, broad-clone overlay, and
+child result promotion.
+With Docker, mount both your project and the persistent runtime config volume, then pass the same variables through with `-e`:
+```bash
+docker run -it --rm \
+  -v "$(pwd):/workspace" \
+  -v pentesting-config:/root/.pentesting \
+  -w /workspace \
+  -e OPENAI_API_KEY \
+  -e OPENAI_BASE_URL \
+  -e OPENAI_MODEL \
+  -e OPENAI_MAX_TOKENS \
+  agnusdei1207/pentesting:latest
+```
+Those variables only pre-fill provider settings. Leaving them unset must not
+block the container from launching the TUI; configure the provider interactively
+inside the container instead.
+> **Note:** The command you run is always **`pentesting`**. The internal engine is **`builder`** — `pentesting` downloads and runs it under the hood; the engine name never surfaces in normal use.
+---
+## 📖 Documentation
+- [`ARCHITECTURE.md`](ARCHITECTURE.md) — Runtime flow, agent team, memory model, crate map, tool surface, and supported targets.
+- [Documentation map](https://github.com/agnusdei1207/pentesting/blob/main/docs/README.md) — Current authoritative documents versus historical plans and research notes.
+- [Integrated runtime design](https://github.com/agnusdei1207/pentesting/blob/main/docs/BUILDER-CONSOLIDATED-DEEP-DIVE.md) — Top-down explanation from the one-loop model to prompt, subagents, persistence, and PTY ownership.
+- [Minimal Core implementation](https://github.com/agnusdei1207/pentesting/blob/main/docs/plans/2026/07/10/minimal-core/README.md) — Implemented simplification record for the single turn/tool/security surface.
+- [Next-generation clean-break convergence](https://github.com/agnusdei1207/pentesting/blob/main/docs/plans/2026/07/10/next-generation-convergence/README.md) — Canonical contracts, deleted compatibility paths, and the phase-by-phase migration boundary.
+- Internal layout: service traits are split under `builder_app/src/services/*`; OpenAI request conversion is isolated under `dto/openai/request/*`.
+- [Public site](https://agnusdei1207.github.io/pentesting-public/) — Landing page and public runtime entry surface.
+- [`compose.yaml`](https://github.com/agnusdei1207/pentesting-public) — Docker Compose facade for pentesting sessions.
+---
+## 🎹 From the Developer
+<div align="center">
+  <img src="https://github.com/user-attachments/assets/abe73474-f27b-4536-b358-fedef1e461f0" alt="Chopin Ballade No.4" width="600" />
+</div>
+<br/>
+> "I believe playing the piano is also a form of orchestration."
+>
+> The harmony of polyphony — multiple voices — and homophony — a single melodic line.
+>
+> Each voice sings its most beautiful song from its own place, yet when combined, they create one grand, beautiful melody. I believe this structure is no different from AI agents.
+>
+> — *agnusdei1207*

package/bin/pentesting.mjs CHANGED Viewed

@@ -1,36 +1,36 @@
-#!/usr/bin/env node
-import { spawnSync } from "node:child_process";
-import {
-  pentestingEnvironment,
-  resolveBuilderBinary,
-  translateBuilderInvocation,
-} from "../lib/runtime.mjs";
-async function main() {
-  const invocation = translateBuilderInvocation(process.argv.slice(2));
-  for (const warning of invocation.warnings) {
-    console.warn(`[pentesting] ${warning}`);
-  }
-  const builderBinary = await resolveBuilderBinary({ downloadIfMissing: true });
-  const result = spawnSync(builderBinary, invocation.builderArgs, {
-    stdio: "inherit",
-    env: pentestingEnvironment(process.env),
-  });
-  if (result.error) {
-    console.error(
-      `pentesting could not start Builder (${result.error.message}). Set PENTESTING_BIN or reinstall the pentesting package.`,
-    );
-    process.exit(127);
-  }
-  process.exit(result.status ?? 1);
-}
-main().catch((error) => {
-  console.error(`[pentesting] ${error instanceof Error ? error.message : String(error)}`);
-  process.exit(1);
-});
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import {
+  pentestingEnvironment,
+  resolveBuilderBinary,
+  translateBuilderInvocation,
+} from "../lib/runtime.mjs";
+async function main() {
+  const invocation = translateBuilderInvocation(process.argv.slice(2));
+  for (const warning of invocation.warnings) {
+    console.warn(`[pentesting] ${warning}`);
+  }
+  const builderBinary = await resolveBuilderBinary({ downloadIfMissing: true });
+  const result = spawnSync(builderBinary, invocation.builderArgs, {
+    stdio: "inherit",
+    env: pentestingEnvironment(process.env),
+  });
+  if (result.error) {
+    console.error(
+      `pentesting could not start Builder (${result.error.message}). Set PENTESTING_BIN or reinstall the pentesting package.`,
+    );
+    process.exit(127);
+  }
+  process.exit(result.status ?? 1);
+}
+main().catch((error) => {
+  console.error(`[pentesting] ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+});