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

pentesting 0.100.5 → 0.100.10

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,261 @@
-# 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 |
+# 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 stops the current turn and auto loop; queued input uses revisioned FIFO amend/replace semantics 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 | Persistent lead ledger with explicit dispatch; breadth defaults to one and is hard-capped at four                                                                   |
+| Subagents                   | Explicit delegation to built-in specialists, including `crypto`, `rev`, and `pwn`; one selected agent can run up to four tasks concurrently                           |
+| MCP & skills                | Dynamic MCP tool discovery, layered markdown skills                                                                                                                   |
+| Memory                      | Ebbinghaus-style decaying notes + hybrid lexical/semantic/graph retrieval                                                                                             |
+---
+Delegation is explicit. One `task` call selects one agent and may run its tasks
+concurrently; separate top-level calls are sequenced. `explore dispatch` instead
+uses `builder` clones with category overlays and waits for the batch. Both paths
+share permissions, budgets, lineage, and evidence checks.
+### Core algorithms
+| Area | Implementation | Time / space |
+| --- | --- | --- |
+| Exploration | Score-ranked BFS/DFS guidance, parent backtracking, global reseeding; append-only leads folded into a `HashMap` | Snapshot/advice `O(R + L log L)` time, `O(L)` working and `O(R)` stored space |
+| Knowledge | BM25 + 768-D cosine search + BFS over adjacency maps/visited sets, fused by RRF; fixed 20-round PageRank at index build | Query `O(M + N(Q + D + log N) + V log V + E)` time and `O(N + V + D)` working space; index storage `O(M + ND + V + E)` |
+| Runtime control | FIFO queues plus semaphore-bounded `join_all` fan-out | `O(T)` scheduling/result state, at most four active children per batch |
+`R` is lead records, `L` live leads, `M` searchable text, `N` notes, `Q` query
+terms, `D = 768`, and `V/E` graph nodes/links. Memory decay is constant-time per
+note. Kruskal, Prim, and a generic divide-and-conquer engine are not runtime
+components; agents may apply them to a target when useful.
+---
+## 🚀 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 resource-intensive work; and leave a redacted resource
+report. Automated CI/CD is disabled. 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:
+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
+```
+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`.
+### Interactive commands
+Sessions start with auto mode off. Esc stops both the current turn and autonomous continuation. Queued input is replayed in FIFO order.
+| Command | Purpose |
 | --- | --- |
-| 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.
-### 🐳 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
-```
-### 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
-```
-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.
+| `/help` | List every command |
+| `/model [query]` | Choose a provider/model or custom endpoint |
+| `/goal <objective>` · `/auto` | Record a goal, then toggle autonomous continuation; Esc stops it |
+| `/status` · `/usage` | Inspect run state, gates, budgets, tokens, and requests |
+| `/context` · `/memory` | Inspect context-budget snapshots and stored memories |
+| `/agent` · `/builder` · `/planner` · `/researcher` | Select the active agent |
+| `/new` · `/retry` · `/compact` | Start fresh, retry the last turn, or compact context |
+| `/config` · `/tools` · `/skill` | Configure the runtime and inspect capabilities |
+| `/workflow report` | Export the active run as Markdown |
+| `/update` · `/exit` | Update the native release or quit |
+On native Windows Git Bash, the repository smoke path builds the capped Docker
+image and then opens this interactive TUI without WSL:
+```bash
+npm run check
+```
 ### 🔌 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; `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.
+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 upgrade --technique auto # 4. Recon, select, retry, and verify a real PTY
+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** — `upgrade --technique auto` explicitly runs a bounded `recon → select → helper → probe` controller, choosing an allowlisted shell and retrying only evidence-backed failures across `python3`, `python`, `python2`, `script`, and `expect`. Omission is still rejected: use a concrete technique for one exact CLI attempt; unusual custom `text` commands are available through the `session_control`/JSONL API. CLI `pty-upgrade` sends one concrete catalog helper and never starts adaptive fallback.
+- **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.
+- **Guard** — the JSONL control plane is a workspace-internal Unix socket only (absolute paths, symlink escapes, and non-socket files are rejected). Every request carries a protocol version and a correlating `request_id`, is bounded to 1 MiB in / 4 MiB out, and `timeout_ms` is capped at 5 minutes and rejected before any bytes reach the session. A small fixed worker pool multiplexes the socket so a long adaptive `upgrade` never blocks `health` / `observe` / `close`, and injected secrets are redacted from responses and sensitive audit records. `probe` / recon fields are the target's own self-report, not a security attestation.
+---
+## ⚙️ 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*
+`explore` is always available. Use `/config` to set the engagement kind, flag
+verification, and frontier limits; settings persist in the installed runtime's
+user config. Breadth defaults to one and is capped at four. Leads are persistent,
+deduplicated, and dispatched explicitly.
+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);
+});