Metadata-Version: 2.4
Name: pawnlogic
Version: 0.3.0
Summary: A fully autonomous terminal AI agent — multi-model routing, persistent memory, real tool execution
Author-email: john0123412 <junjohn05@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/john0123412/PawnLogic
Project-URL: Repository, https://github.com/john0123412/PawnLogic
Project-URL: Issues, https://github.com/john0123412/PawnLogic/issues
Project-URL: Changelog, https://github.com/john0123412/PawnLogic/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/john0123412/PawnLogic/blob/main/GUIDE.md
Keywords: ai-agent,llm,ctf,cli,autonomous,multi-model,security,pwn
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: POSIX :: Linux
Classifier: Environment :: Console
Classifier: Topic :: Security
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Intended Audience :: Developers
Classifier: Development Status :: 4 - Beta
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-dotenv>=1.0
Requires-Dist: rich>=13.0
Requires-Dist: prompt_toolkit>=3.0
Requires-Dist: loguru>=0.7
Requires-Dist: anthropic>=0.40
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.0; extra == "dev"
Requires-Dist: pexpect>=4.8; sys_platform != "win32" and extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: PyYAML>=6.0; extra == "dev"
Provides-Extra: docker
Requires-Dist: docker>=6.0; extra == "docker"
Provides-Extra: browser
Requires-Dist: scrapling>=0.2; extra == "browser"
Requires-Dist: patchright>=1.40; extra == "browser"
Provides-Extra: ctf
Requires-Dist: pwntools>=4.11; extra == "ctf"
Requires-Dist: ROPgadget>=7.4; extra == "ctf"
Requires-Dist: ropper>=1.13; extra == "ctf"
Dynamic: license-file

**[English](README.md)** | [Chinese](README_zh-CN.md)

# PawnLogic

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Version](https://img.shields.io/pypi/v/pawnlogic.svg?label=version)](https://pypi.org/project/pawnlogic/)
[![PyPI](https://img.shields.io/pypi/v/pawnlogic.svg?cache=no)](https://pypi.org/project/pawnlogic/)
[![CI](https://github.com/john0123412/PawnLogic/actions/workflows/main_ci.yml/badge.svg)](https://github.com/john0123412/PawnLogic/actions/workflows/main_ci.yml)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20WSL2-lightgrey.svg)]()

PawnLogic is a terminal-first autonomous AI agent with multi-provider model
routing, persistent memory, real local tool execution, MCP integration, and a
CTF-oriented toolchain. The current public release is **0.3.0**.

## System Requirements

- Linux or WSL2
- Python 3.10+
- `pip`
- `git` only for source checkouts, development, or git-backed skill packs
- `~/.local/bin` in `PATH` when using the global `pawn` launcher
- Optional: Docker for container tools, browser dependencies for Patchright /
  Scrapling, and CTF packages for pwn workflows

## Quick Start

**Option A: install from PyPI**

```bash
pip install pawnlogic
pawn
```

The first run opens the API key configuration flow. Runtime files are created
under `~/.pawnlogic/`, not inside the project directory.

**Option B: one-line installer**

```bash
curl -fsSL https://raw.githubusercontent.com/john0123412/PawnLogic/main/install.sh | bash
pawn
```

The installer creates an isolated venv under `~/.local/share/pawnlogic`,
installs the official PyPI package, and writes `~/.local/bin/pawn`.

**Option C: source checkout for development**

```bash
git clone https://github.com/john0123412/PawnLogic.git
cd PawnLogic
python3 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
pawn
```

Optional extras:

```bash
pip install "pawnlogic[docker]"    # Docker SDK integration
pip install "pawnlogic[browser]"   # Scrapling + Patchright browser tools
pip install "pawnlogic[ctf]"       # pwntools, ROPgadget, ropper
pip install -e ".[dev,ctf]"        # source checkout with tests and CTF tools
```

`pawnlogic[ctf]` installs CTF tooling dependencies only. CTF skill packs are
optional extension assets that users install explicitly, for example with
`/sp install <repo_url>` into `~/.pawnlogic/skills`. Third-party skill packs are
not bundled into PyPI distributions unless their upstream license and notices
have been reviewed for redistribution.
Skill-pack manifests are runtime discovery metadata only; they do not authorize
redistribution without a matching `THIRD_PARTY_NOTICES.md` entry.
Git-backed skill-pack installs accept only `https://`, `ssh://`, or
`git@host:owner/repo.git` remotes.

Source-checkout launcher fallback:

```bash
./pawn.sh
```

CLI entry points:

```bash
pawn
pawn --debug
pawn --eval "summarize this repository"
pawn --eval "summarize this repository" --json
python -m pawnlogic --help
```

Default `pawn` uses user-friendly output and hides raw tool-call internals,
parser diagnostics, detailed reasoning streams, and low-level API errors.
Use `pawn --debug` or `/mode` when you need detailed diagnostics.
With `--json`, each line is an independent NDJSON record. Existing `text`,
`chunk`, and `json` records remain stable; versioned Agent lifecycle records
use the additive `{"type":"event","data":{...}}` envelope.

## What's New

Version 0.3.0 turns PawnLogic into an extensible agent host while keeping the
core distribution small and preserving existing public contracts:

- Extensions are discovered through the `pawnlogic.extensions` entry point
  group and stay disabled until you enable them. Discovery reads metadata
  without importing extension code, and `/extension list|status|enable|disable`
  owns the lifecycle. Installing a distribution is not authorization to run it.
- A shared Network Policy decides every HTTP(S) target for web, browser, MCP,
  and Docker callers. Credentials, cloud metadata, and special address ranges
  are denied, private targets need explicit authorization, every redirect is
  re-evaluated, and non-interactive confirmation fails closed.
- Delegated agents request models and tools through host policy. Prompts and
  tool arguments cannot bypass provider visibility, user allowlists, capability
  filtering, or budgets.
- Structured context tracks prompt budget with atomic tool-call groups, so
  trimming never silently corrupts protected anchors, pins, or tool groups.
- Knowledge retrieval reads a bounded, provenance-aware corpus with SQLite as
  the durable authority. Optional projections only affect ranking, and their
  absence or staleness is never fatal.
- A versioned Agent Event stream reports turns, retrieval, tools, policy,
  usage, and delegation. Payloads are recursively redacted, subscriber failures
  never stop execution, and the NDJSON sink gains a typed `event` record so
  automation no longer needs to parse terminal output.
- Multi-agent orchestration is deterministic and serial, with task lineage,
  deadlines, cooperative cancellation, and atomic token, tool, and cost budget
  claims. Concurrency above one fails closed until isolation is proven.
- Releases are gated on more than a successful upload: a production tag must
  point at a commit on `main`, and the published distribution is reinstalled
  from the index and smoke-tested before the GitHub Release is created.

See [CHANGELOG.md](CHANGELOG.md) for the full release history.

## Key Capabilities

| Capability | Description |
|-----------|-------------|
| Multi-provider models | Built-in DeepSeek, OpenAI, and Anthropic aliases plus custom OpenAI-compatible or Anthropic-style providers through `/provider`. |
| Delegated agents | Bounded sub-agents use host-controlled dynamic model routing, user allow/deny policy, token/tool/cost budgets, capability-filtered Tools, and deterministic serial orchestration with task lineage. |
| Structured context | Versioned task state, Tool-call-safe trimming, `ctx_trim_to` targeting, and host-selected delegated context keep long sessions bounded without copying raw parent history. |
| Persistent workspace | SQLite-backed sessions, searchable history, memory commands, bounded provenance-aware knowledge retrieval, per-session workspaces, and audit logs under `~/.pawnlogic/`. |
| Real tool execution | Host shell, code sandbox, file operations, URL fetch, browser automation, Docker containers, and CTF helpers. |
| Trust-boundary UX | User-mode warnings make it explicit when a tool crosses local host, container, browser, network, delegate, or plaintext HTTP boundaries. |
| Optional Extensions | Installed packages can advertise `pawnlogic.extensions` entry points. Discovery does not load their code, and `/extension enable <name>` is always explicit. |
| MCP integration | Stdio MCP servers can be configured from `~/.pawnlogic/mcp_configs.json`, with roots and stderr logging handled by PawnLogic. |
| CTF / pwn workflows | Optional pwn tooling, Docker container helpers, GDB automation, ROP chain support, libc leak workflows, and user-installed local skill packs. |
| Release hygiene | CI runs Ruff, typed-island mypy, docs guard, and fast Python 3.11 PR checks first, then release/manual validation covers Python 3.10/3.11/3.12, packaging, dynamic E2E, docs structure, language policy, package build, and Trusted Publishing guardrails. Production PyPI publishing is tag-only through Trusted Publishing; manual workflow dispatch targets TestPyPI only. |

## Supported Models

PawnLogic ships with preconfigured model aliases. Only active providers with a
configured API key are shown in `/model` and Tab completion.

| Provider | Aliases | Notes |
|----------|---------|-------|
| DeepSeek | `ds-v4-flash`, `ds-v4-pro` | Default provider; fast primary model plus flagship reasoning model. |
| OpenAI | `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-4o`, `gpt-4.1`, `o3` | Coding, vision, multimodal, low-latency, and reasoning aliases. |
| Anthropic | `claude-opus`, `claude-sonnet`, `claude-haiku` | Opus, Sonnet, and Haiku aliases for Anthropic's Messages API path. |

Custom provider model descriptions come from
`~/.pawnlogic/custom_providers.json`. Re-running `/provider update <name>`
refreshes selected models and writes English fallback descriptions for fetched
models when the provider does not supply a useful description.

Delegated tasks automatically prefer an eligible fast worker when no model
request is supplied; they do not automatically reuse the current conversation
model. `/worker` lists every model currently visible through `/model`, including
eligible custom-provider aliases. `/agent policy` can allow or deny aliases,
select the default routing mode, and cap cost or concurrency. Explicit model
requests are preferences: provider visibility, user policy, capability, and
budget checks remain authoritative.
Structured tasks and results carry task/parent IDs, deadlines, usage, and
failure records. Shared orchestration budgets are reserved atomically, and
cancellation is cooperative. The current core orchestrator is deliberately
serial: a persisted `max-concurrency` value of `2` is a policy ceiling for a
future isolated executor, not permission to run the current shared Workspace
and RuntimeContext concurrently.

## Provider Management

```bash
/provider                         # open the provider TUI
/provider add <name> <base_url> <ENV_KEY> [anthropic]
/provider fetch <name>            # fetch available models and select aliases
/provider update <name>           # re-fetch provider models
/provider activate <name>         # show selected provider models
/provider deactivate <name>       # hide provider models
/provider list                    # show provider and key status
/provider test <model>            # test connectivity for a model alias
/setkey                           # run key setup again
/keys                             # show configured key status
```

API keys are stored in `~/.pawnlogic/.env`. Provider configs, model aliases,
and descriptions are stored in `~/.pawnlogic/custom_providers.json` without
secret values. Provider setup does not write keys into shell startup files.

Plain `http://` provider endpoints are allowed for local relays and lab
setups, but user-friendly mode prints a trust-boundary warning because requests
and API keys are not protected by TLS.

Unstable custom providers can be tuned through environment variables in
`~/.pawnlogic/.env`: `PAWNLOGIC_API_RETRY_MAX` controls total request attempts
including the first attempt, `PAWNLOGIC_API_RETRY_AFTER_MAX` caps provider
`Retry-After` delays, and `PAWNLOGIC_API_CONNECT_TIMEOUT`,
`PAWNLOGIC_API_READ_TIMEOUT`, and `PAWNLOGIC_API_NONSTREAM_TIMEOUT` tune
connection and response wait times.

## Quick Command Reference

```bash
/model [alias]                    # switch model
/mode                             # toggle user-friendly/debug output
/chat find <keyword>              # search all sessions
/think <prompt>                   # run one deeper reasoning turn
/compact                          # summarize and compact context
/undo [n]                         # roll back recent turns
/deep                             # full-power mode
/init_project [desc]              # initialize project state
/pwnenv                           # check CTF toolchain integrity
/ctf init <name>                  # start CTF workspace metadata
/ctf solved [flag]                # mark a confirmed CTF flag as solved
/ctf writeup                      # export a CTF writeup draft
/sp install <repo_url>            # install a git-backed skill pack
/extension list                   # list installed Extensions
/extension enable <name>          # explicitly enable an Extension
/extension disable <name>         # disable an Extension
/worker [alias|auto]              # inspect or set the preferred worker
/agent policy show                # inspect delegated-agent policy
/agent run <role> <objective>     # print a safe delegate_task request template
```

Run `/help` inside PawnLogic for the full command list.

## Trust Boundary

PawnLogic is an agent execution tool, not a security sandbox. It intentionally
executes real tools with the current user's permissions when you ask it to do
so. Pattern filters, Docker boundaries, and capability profiles reduce
accidents; they do not contain a determined attacker.

Web fetches and browser navigation evaluate HTTP(S) targets through the shared
Network Policy before use. URLs are normalized; embedded credentials,
cloud-metadata/internal targets, and loopback, link-local, multicast,
unspecified, or reserved addresses are denied. Private-network targets require
explicit authorization, and non-interactive requests fail closed when
confirmation would otherwise be required. Redirect destinations are normalized,
resolved, and evaluated again before they are followed, including any
target-scoped authorization. Model-generated Tool arguments cannot grant
private-network authorization, and confirmed private targets bypass remote
reader services.

Docker `bridge`/`host` networking and legacy `uvx mcp-server-fetch` startup use
capability-only authorization because no concrete URL is available at the gate.
Authorize Docker networking with `allow_network=true` or
`PAWNLOGIC_DOCKER_ALLOW_NETWORK=true`; authorize the legacy MCP network install
with `allow_network_install=true` or
`PAWNLOGIC_MCP_ALLOW_NETWORK_INSTALL=true`. These approvals grant only the
named capability; they are not URL-target approvals.

User-friendly mode prints explicit trust-boundary notices for host shell
execution, Docker container exec, browser/network-capable tools, private
network URL access, delegated sub-agents, and plaintext HTTP providers. Use
`pawn --debug` when you need lower-level tool arguments and diagnostics.
Docker file mounts are workspace-bound by default, including read-only mounts;
outside read-only challenge files require explicit `allow_host_read_mount`.

Host shell execution now passes through an operation policy before subprocess
startup. Low-risk commands run normally, medium-risk commands are classified
for audit, high-risk commands require explicit interactive confirmation, and
critical operations are denied by default. Non-interactive execution, including
`pawn --eval`, fails closed when a high-risk command would require
confirmation. `DANGEROUS_PATTERNS` remains only one misuse/risk classifier; it
is not a sandbox boundary and cannot stop a malicious local user.

## Optional Extensions

Python distributions may advertise Extension metadata through the
`pawnlogic.extensions` entry-point group. PawnLogic can list installed
Extensions without loading their code. Installation never enables an
Extension automatically.

```bash
/extension list
/extension status [name]
/extension enable <name>
/extension disable <name>
```

Enabled names are stored under `~/.pawnlogic/extensions/enabled.json`.
Extension startup failures are isolated from core startup, and contribution
name conflicts are rejected instead of overwriting built-in Tools or commands.
Dependency-heavy or security-sensitive Extensions must remain independently
packaged and published. The core wheel contains no `pawnlogic_security` package,
security console script, or security dependency; installing such a distribution
would still require explicit `/extension enable <name>` authorization.

## MCP Tool Integration

For pip or one-line installer users, PawnLogic creates editable templates in
`~/.pawnlogic/` on startup:

```bash
pawn
cp ~/.pawnlogic/mcp_configs.example.json ~/.pawnlogic/mcp_configs.json
# edit ~/.pawnlogic/mcp_configs.json and add keys with /setkey or ~/.pawnlogic/.env
pawn
```

For source checkout users, the repository template can also be copied directly:

```bash
cp mcp_configs.example.json ~/.pawnlogic/mcp_configs.json
```

Supported example MCP servers include Tavily search, Playwright browser
automation, and a filesystem bridge. External `fetch` MCP is disabled in the
example because `uvx mcp-server-fetch` may contact PyPI during startup; use
PawnLogic's built-in `fetch_url` unless you explicitly enable that MCP server.

MCP subprocess stderr is written to
`~/.pawnlogic/logs/mcp/<server>.stderr.log` by default. Set top-level
`"debug_stderr": true` in `mcp_configs.json` when you want raw MCP stderr on
the console. PawnLogic advertises MCP roots for the current working directory
and `~/.pawnlogic/workspace`.

## Data Layout

All runtime data and API keys are stored in `~/.pawnlogic/`.

```text
~/.pawnlogic/
├── .env                    # API keys
├── custom_providers.json   # user provider configs, no keys
├── mcp_configs.json        # MCP server declarations
├── pawn.db                 # sessions, messages, knowledge base
├── global_skills.md        # GSA skill archive
├── skills/                 # optional user-installed skill packs
├── workspace/              # per-session working directories
└── logs/                   # audit logs
```

The project directory contains no secrets and is safe to commit or share.

## Documentation

| Document | Description |
|----------|-------------|
| [**README.md**](README.md) | This page |
| [**README_zh-CN.md**](README_zh-CN.md) | Chinese README |
| [**GUIDE.md**](GUIDE.md) | Full reference: commands, architecture, and FAQ |
| [**GUIDE_zh-CN.md**](GUIDE_zh-CN.md) | Chinese full reference |
| [**CHANGELOG.md**](CHANGELOG.md) | Version history and release notes |
| [**CONTRIBUTING.md**](CONTRIBUTING.md) | Contribution, provider, and test workflow |
| [**SECURITY.md**](SECURITY.md) | Vulnerability reporting policy |
| [**THIRD_PARTY_NOTICES.md**](THIRD_PARTY_NOTICES.md) | Third-party attribution and redistribution notes |

## Support

- GitHub: [github.com/john0123412/PawnLogic](https://github.com/john0123412/PawnLogic)
- Issues: use GitHub Issues for bugs and feature requests.
