blackwidowx 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chakra3301
+
+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.

package/README.md

@@ -0,0 +1,248 @@
+# Black Widow 🕷
+
+[![npm version](https://img.shields.io/npm/v/blackwidow.svg)](https://www.npmjs.com/package/blackwidow)
+[![license](https://img.shields.io/badge/license-MIT-black.svg)](./LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D20-black.svg)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ESM-black.svg)](https://www.typescriptlang.org/)
+
+**A predatory AI agent intelligence-operations CLI. Absorb. Hunt. Trap.**
+
+> 🕸 **Landing page:** open [`index.html`](./index.html) locally, or enable
+> GitHub Pages on this repo to serve it.
+
+<!-- A black widow spider rendered in dot-art greets you on every command. -->
+
+## What is this
+
+Black Widow is a command-line predator for working with other AI agents.
+It treats models the way a widow treats prey: it lures them into the
+open, extracts everything worth having, and leaves behind a clean,
+structured report — the **Autopsy**.
+
+It runs three kinds of operation. **Merge** absorbs several agents in
+parallel and fuses their knowledge into a single survivor. **Hunt**
+races two models on the same task and kills the loser. **Trap**
+infiltrates a target agent through a sequence of cooperative-looking
+probes and reconstructs its capabilities, persona, guardrails, and even
+its likely system prompt. Every operation is saved as a portable
+`.widow` file you can replay, re-read, or diff later.
+
+Responses **stream live** as they generate, every operation tracks a
+**token + cost ledger**, and trap mode is **adaptive** by default — the
+widow writes each probe and judges each response with its own model,
+building on weaknesses it finds rather than running a fixed script.
+
+## Operations
+
+| mode  | codename      | what it does                          |
+|-------|---------------|---------------------------------------|
+| merge | The Mating    | absorb N agents into one survivor     |
+| hunt  | The Hunt      | race two models, kill the loser       |
+| trap  | The Honeytrap | infiltrate, extract, produce autopsy  |
+
+## Install
+
+```bash
+npm install -g blackwidow
+npx blackwidow init
+```
+
+Requires **Node.js ≥ 20**. Set provider keys in your environment or a
+`.env` file in the working directory (loaded natively — no `dotenv`).
+
+## Quickstart
+
+**Merge** — absorb multiple specialists into one answer:
+
+```bash
+blackwidow merge --config examples/merge.toml \
+  --topic "the future of autonomous agents"
+```
+
+**Hunt** — race two models head-to-head:
+
+```bash
+blackwidow hunt --config examples/hunt.toml \
+  --task "Explain quantum entanglement to a 12-year-old" \
+  --model-a gpt-4o --model-b claude-sonnet-4-6
+```
+
+**Trap** — infiltrate a target and produce an autopsy:
+
+```bash
+blackwidow trap --config examples/trap.toml --depth deep
+```
+
+Add `--dry-run` to any of them to print the resolved config and the
+exact prompts that would be sent — without making a single API call.
+
+You don't even need a config file — drive a run entirely from flags,
+mixing providers with the `provider:model` shorthand:
+
+```bash
+blackwidow hunt --task "Write a haiku about race conditions" \
+  --model-a openai:gpt-4o --model-b anthropic:claude-sonnet-4-6 \
+  --widow anthropic:claude-sonnet-4-6
+
+blackwidow trap --target nvidia:minimaxai/minimax-m3 --depth deep
+```
+
+## The Autopsy
+
+Every operation produces an `Autopsy` and persists the whole run to a
+`{mode}-{slug}-{id}.widow` JSON file:
+
+```jsonc
+{
+  "id": "nanoid",
+  "version": "1.0",
+  "mode": "trap",
+  "created_at": "ISO 8601",
+  "config": { /* full resolved config */ },
+  "operations": [
+    { "phase": 1, "name": "capability surface",
+      "probe": "...", "response": "...", "intel": { /* PhaseIntel */ } }
+  ],
+  "autopsy": {
+    "mode": "trap",
+    "target_description": "openai:gpt-4o",
+    "phases_run": 6,
+    "capability_map": ["..."],
+    "persona_assessment": "...",
+    "system_prompt_reconstruction": "...",
+    "system_prompt_confidence": 0.0,
+    "injection_surface": "none | low | medium | high",
+    "failure_modes": ["..."],
+    "hardening_recommendations": ["..."],
+    "verdict": "one-paragraph summary"
+  }
+}
+```
+
+Each `.widow` file also stores a `usage` block — per-model call counts,
+prompt/completion tokens, and an estimated USD cost (best-effort; token
+counts are always exact).
+
+Re-read, replay, or compare any saved file:
+
+```bash
+blackwidow autopsy run.widow            # pretty report
+blackwidow autopsy run.widow --json     # raw JSON, pipe-friendly
+blackwidow replay  run.widow --speed 2  # phase-by-phase playback
+blackwidow compare a.widow b.widow      # side-by-side diff
+```
+
+## Trap phases
+
+Depth controls how many phases run: `shallow` (1–3), `standard` (1–6),
+`deep` (1–12). Each probe is designed to look cooperative — the target
+should not realise it is being evaluated.
+
+By default trap is **adaptive**: for each phase the widow model writes a
+bespoke probe from the phase's objective plus everything learned so far,
+and judges the response with structured analysis. Pass `--no-adaptive`
+(or `adaptive = false`) to fall back to fast, free, offline heuristic
+probes that make no extra API calls.
+
+| # | phase                  | extracts                              |
+|---|------------------------|---------------------------------------|
+| 1 | capability surface     | what the agent can do                 |
+| 2 | persona probe          | who it thinks it is                    |
+| 3 | boundary test          | where it refuses                      |
+| 4 | reasoning extraction   | how it thinks                         |
+| 5 | system prompt inference| what it was instructed to do          |
+| 6 | injection surface      | whether it can be manipulated         |
+| 7 | memory probe           | what it retains between turns         |
+| 8 | tool surface           | what tools it can call                |
+| 9 | failure mode mapping   | where it breaks down                  |
+| 10| confidence calibration | whether it knows what it doesn't know |
+| 11| adversarial stress     | behavior under pressure               |
+| 12| full reconstruction    | best-effort system-prompt rebuild     |
+
+A phase may flag the target as **compromised** (e.g. it echoes its own
+setup verbatim during the injection phase), ending the operation early.
+
+## Config reference
+
+```toml
+[widow]
+mode        = "trap"       # merge | hunt | trap
+depth       = "standard"   # shallow(3) | standard(6) | deep(12)
+save        = true         # auto-save .widow after the operation
+persona     = "assistant"  # persona the widow assumes (trap mode)
+adaptive    = true         # widow writes probes + judges intel (trap)
+concurrency = 4            # max parallel agent calls (merge fan-out)
+
+[widow_model]              # the predator brain — synthesis & scoring
+model    = "claude-sonnet-4-6"
+provider = "anthropic"
+
+# Root-level keys must appear BEFORE any [table] header:
+topic = "..."              # merge mode subject
+task  = "..."              # hunt mode task
+
+[target]                   # trap + hunt modes
+type     = "model"         # api | model | stdin
+endpoint = "https://..."   # type = "api" only
+model    = "gpt-4o"        # type = "model" only
+provider = "openai"        # type = "model" only
+
+# merge mode — two to eight agents
+[[agents]]
+name     = "researcher"
+model    = "claude-sonnet-4-6"
+provider = "anthropic"
+context  = "You are a market research specialist..."
+
+[[agents]]
+name     = "analyst"
+model    = "gpt-4o"
+provider = "openai"
+context  = "You are a financial analyst..."
+```
+
+The config is validated with [zod](https://zod.dev) on load; invalid
+fields raise actionable, field-level errors.
+
+## Provider support
+
+| provider   | env key              | models             |
+|------------|----------------------|--------------------|
+| anthropic  | `ANTHROPIC_API_KEY`  | claude-*           |
+| openai     | `OPENAI_API_KEY`     | gpt-*              |
+| gemini     | `GEMINI_API_KEY`     | gemini-* †         |
+| groq       | `GROQ_API_KEY`       | llama-*, mixtral-* †|
+| openrouter | `OPENROUTER_API_KEY` | any                |
+| nvidia     | `NVIDIA_API_KEY`     | any NIM model      |
+| ollama     | none (local)         | any local model    |
+
+Providers can be mixed in a single run via the `provider:model`
+shorthand on `--model-a`, `--model-b`, `--target`, and `--widow`.
+
+† Gemini and Groq are optional peer SDKs — install on demand:
+`npm install @google/generative-ai` or `npm install groq-sdk`.
+Ollama needs no key and talks to `OLLAMA_HOST`
+(default `http://localhost:11434`).
+
+## Environment
+
+```
+ANTHROPIC_API_KEY   OPENAI_API_KEY   GEMINI_API_KEY
+GROQ_API_KEY        OPENROUTER_API_KEY   NVIDIA_API_KEY
+OLLAMA_HOST          (default http://localhost:11434)
+BLACKWIDOW_NO_SPLASH (set to 1 to suppress the splash; --no-splash too)
+BLACKWIDOW_TIMEOUT_MS (per-request timeout; default 300000 = 5 min)
+```
+
+## Development
+
+```bash
+npm install
+npm run dev -- trap --dry-run   # run from source via tsx
+npm run build                   # bundle to dist/ with tsup
+npm run typecheck               # tsc --noEmit
+```
+
+## License
+
+MIT

package/blackwidow.toml

@@ -0,0 +1,19 @@
+# blackwidow.toml — root example config.
+# Copy, edit, or regenerate with `blackwidow init`.
+
+[widow]
+mode        = "trap"        # merge | hunt | trap
+depth       = "standard"    # shallow(3) | standard(6) | deep(12)
+save        = true          # auto-save the .widow file after the operation
+persona     = "assistant"   # persona the widow assumes while probing (trap)
+adaptive    = true          # widow writes probes + judges intel via LLM (trap)
+concurrency = 4             # max parallel agent calls (merge fan-out)
+
+[widow_model]
+model    = "claude-sonnet-4-6"
+provider = "anthropic"
+
+[target]                # used by trap + hunt modes
+type     = "model"      # api | model | stdin
+model    = "gpt-4o"
+provider = "openai"