pi-agent-cli-lc 0.3.0__tar.gz → 0.5.0__tar.gz

{pi_agent_cli_lc-0.3.0 → pi_agent_cli_lc-0.5.0}/.gitignore

@@ -4,6 +4,7 @@ __pycache__/
 .eggs/
 dist/
 build/
+!tui/crates/build/
 .pytest_cache/
 .pytest-audit/
 .mypy_cache/

pi_agent_cli_lc-0.5.0/AGENTS.md

@@ -0,0 +1,125 @@
+# pi-agent-cli
+
+Standard-ACP agent over `AgentHarness`. Two modes:
+
+| Mode | Entry | Purpose |
+|------|-------|---------|
+| ACP stdio | `python -m pi_agent_cli` | TUI-spawned agent; `/new` `/resume` `/quit` map to ACP methods |
+| Headless | `python -m pi_agent_cli -p "prompt"` | One-shot turn, prints assistant text, exits |
+
+Headless flags: `--system-prompt`, `--append-system-prompt`, `--no-context-files`, `--no-git-context` — see `--help`. `--trust-project-extensions` works in both modes (see Project extensions).
+
+## Config
+
+Home: `~/.pi-python/` (override with `PI_HOME`). One resolver, `pi_agent_core.home.pi_home` (re-exported as `config.pi_home`), serves the CLI, the extension loader (`<home>/extensions`, exposed to extensions as `pi.home`) and the workflow extension (saved workflows, journals); `create_session_harness` hands the session's home to the harness so they cannot disagree. Two config files with distinct owners:
+
+| File | Owner | Scope |
+|------|-------|-------|
+| `agent.toml` | Python agent | model, permission, skills, prompt overrides |
+| `config.toml` | Rust TUI only | TUI settings (`[ui]`, theme, sandbox); a key the TUI knows, written with another type, stops it |
+
+Keep the two files apart. The TUI is strict about the keys it knows and tolerant of the keys it does not know (measured with `zypi`; execution log section 10.10, item 3). A `config.toml` that is missing, has an unknown table or key, or has a Python `[model]` table starts normally. These stop `zypi` with exit code 1: a top-level `permission = "ask"` (the TUI expects a table there), a `[[models]]` array, and invalid TOML. A wrong type for `[agent].command` is ignored without a message. The agent reads `agent.toml`; only when that file does not exist does it fall back to `config.toml` (`load_config`, kept for old setups). The TUI reads `[agent].command` from `agent.toml` and, if that file does not set it, from `config.toml` (`acp/spawn.rs`); it reads no other agent key.
+
+`local.env` in home loads `KEY=VALUE` pairs into env without overwriting (secrets stay out of TOML). See `agent.example.toml` for all keys.
+
+## Model selection (`/model`)
+
+Standard ACP **Session Config Options** — `session/set_model` is gone upstream (SDK ≥ 0.11). `new_session` / `load_session` / `resume_session` return `configOptions` with one select (`id="model"`, `category="model"`, `currentValue`, `options`); the client switches with `session/set_config_option` (`PiAcpAgent.set_config_option` → `harness.set_model`, response carries the full option set). Choices = `[model]` + optional `[[models]]` tables in `agent.toml` (`ModelChoice`, `CliConfig.model_choices()`). The model is persisted in the session (`model_change`) and restored on load/resume if still configured. Legacy `_meta` hints (`pi/currentModelId`, `pi/currentModelDisplayName`, `pi/provider`) are still emitted for older clients. Each choice carries its own `api_key_env`: `get_api_key` answers only for that choice's provider (`factory.api_key_for_choice`), and `Model.reasoning` follows `CliConfig.model_reasoning` whichever choice is active.
+
+## Project trust
+
+A project's own content is used only if the project is trusted: `<cwd>/.pi-python/extensions` (imported — i.e. executed — when a session opens), `<cwd>/.pi-python/workflows` (each `*.py` becomes a slash command with a description the repository wrote, and a command that has the model run the script), `<cwd>/.pi/SYSTEM.md`, `<cwd>/.pi/APPEND_SYSTEM.md`, and `[skills].paths` entries relative to the project (`.pi/skills`) — `trust_fingerprint.gated_project_resources` lists them. Never read the decision from a file inside the project, or a repository could trust itself. Not gated: entry-point packages, `~/.pi-python/extensions`, `<pi home>/workflows` (the user's own), `AGENTS.md` / `CLAUDE.md` (upstream loads them whatever the trust), prompts set in `agent.toml`, and absolute or `~` skills paths. The workflows are read by the dynamic-workflows extension, not by the CLI: it asks `pi.project_trusted` (the harness's `trust_project_extensions`, final by the time extensions activate), so an extension that reads anything under `<cwd>/.pi-python/` must do the same. Design: `docs/specs/2026-09-22-phase7-extension-api-design.md` §4.4.
+
+`extension_trust.decide_project_trust(config, cwd, home=)` returns a `ProjectTrustDecision` (hashes files: call it off the event loop). Order: `PI_TRUST_PROJECT_EXTENSIONS` / `--trust-project-extensions` → `default_project_trust = "always"` (or the older `trust_project_extensions`; an explicit `default_project_trust` wins) → `[extensions] trusted_projects` in the **home** `agent.toml` (absolute paths; subdirectories count) → nothing gated (`nothing`) → files cannot be fingerprinted (`unpinnable`: no question, use `trusted_projects`) → an answer saved in `<home>/agent/trust.json` whose fingerprint still matches (`saved`) → `default_project_trust = "never"` → otherwise `undecided` / `changed` (a saved answer for other files), which an ACP client is asked about. `project_extensions_trusted` is the file-free subset (configuration and command line only).
+
+- **Who asks.** Only the ACP agent (`agent.py`), and only when the decision `can_ask` and a client is connected. Headless never asks (upstream pi does not prompt in non-interactive modes either) but honours `saved`. The question (`trust_prompt.py`) is preceded by an ordinary agent message naming the directory, the files and what each does (the TUI shows a permission request's title and options only), then a `session/request_permission` with `Don't trust` (`reject_once`, first) and `Trust and remember` (`allow_always`). **No `allow_once` option, deliberately**: clients may answer tool permissions for the user (the TUI's YOLO mode takes the first `allow_once`), and this is not that decision. Only the exact trust option id, selected, is a yes (never reuse `permissions.outcome_allows`, which treats every id not starting with `reject` as yes); asking happens whatever the `permission` mode says.
+- **When.** After the `session/new` (`load`, `resume`) response has gone out — clients drop requests for sessions they have not registered (`_deferred_session_setup`) — and extensions load only after the answer; `prompt()` waits for it (`session/cancel` or closing the session ends the wait; `_SessionTrust`). One question per project at a time (`_project_locks`); the later session decides afresh and normally finds the saved answer. The answer is checked against the disk again after the dialog (`modified` if the files moved), then `TrustStore.remember` (atomic, fail-closed; an unwritable store leaves the session trusted and says so). Refusals are not remembered. `ProjectTrust` is the session's live answer that `create_session_harness`, `load_system_prompt_options` and `load_session_resources` read, so a yes takes effect without rebuilding the session (`AgentHarness.set_trust_project_extensions`, valid until extensions load).
+- **What was left out** is logged and reported to the user with the reason (`untrusted_project_notice(why=)`: not decided, changed since trusted, changed while asked, declined, could not ask, `never`, unpinnable) — ACP agent message after `session/new`, headless stderr.
+- **Fingerprint** (`trust_fingerprint.fingerprint_resources`): SHA-256 over file contents of everything gated (recursive; `__pycache__` and `.git` skipped; symlinks followed with a loop guard; regular files only; at most 2000 entries and 64 MiB, else `None`) — contents, not mtimes. Stored per exact directory (`TrustStore`: `project_key` = `normcase(realpath)`), not per subtree.
+
+## Tool permissions
+
+`permission` in `agent.toml` is `ask` (default), `auto` or `always-approve`; only `ask` ever asks (headless forces `auto`). In `ask` mode a tool call goes to the client as `session/request_permission` **unless the tool declares itself harmless** (`permissions.needs_permission`): `annotations.readOnlyHint is True`, or `destructiveHint is False` and `openWorldHint is False`. Names and meanings are MCP's, with MCP's worst-case defaults — no annotations means asked — and the values must be real booleans. Tool names no longer matter (there is no allow-list).
+
+- **Where annotations live.** `ToolAnnotations` (`pi_agent_core.types`) on `SimpleTool`, `CodingTool` and `ToolDefinition` (extensions); `from_langchain_tool` reads the four hints from `tool.metadata`. `AgentHarness.check_tool_call` looks the tool up **by name in the session's own tool table** and puts its annotations on `ToolCallEvent.annotations` — the session's loop and workflow sub-agents share that path, so a sub-agent's call is judged by the session's tool of the same name (a name the session lacks is asked about).
+- **Our own tools.** `read` / `grep` / `find` / `ls`: read-only. `web_search` / `fetch_url`: read-only and open-world. `goal_update` / `goal_complete`: not read-only, not destructive, not open-world (they only keep notes in the session). `bash` / `edit` / `write` and `workflow` say nothing on purpose. A new tool that only reads, or only keeps the agent's own notes, should say so, or `ask` mode will interrupt the user for it.
+- **Hints are the author's word**, never verified. There is no per-tool allow-list in `agent.toml`; to let an undeclared third-party tool through, give it annotations or use `auto`.
+- **What `zypi` offers is what the agent honours: two modes.** The TUI tells the agent `ask` or `always-approve` (`pi/yolo_mode_changed`: Shift+Tab, `--always-approve`, `--permission-mode bypassPermissions`). It also used to offer Plan, Auto and a settings "Default", which the agent does not honour — there is no `session/set_mode` handler (Plan restricted nothing while the screen said `plan`), `auto` behaves like `always-approve` (the screen promised a classifier), and `_permission_mode_from_notification` drops `default`. They are hidden in the pager (`tui/crates/codegen/pi-pager/src/app/agent_modes.rs`: three constants, the code behind them kept) and `--permission-mode` takes only `default` and `bypassPermissions`. To give the agent a real Plan or Auto, implement it here and flip the constant there; the pager's old paths and tests come back with it (`docs/PLAN/archive/PLAN-RUST-AGENT-RUNTIME-REMOVAL-EXECUTION-LOG.md` section 10.13).
+
+A prompt that arrives while a turn the client did not start (a `workflow` result delivered through `trigger_message`) is still running waits for that turn rather than failing `busy`; `session/cancel` and closing the session end the wait, and two prompts in flight from the client are still `busy` (`PiAcpAgent._run_prompt`). The ACP v2-draft `state_update` is deliberately not sent: the v1 SDK and the Rust crate under the TUI reject it. Design: `docs/specs/2026-09-22-phase7-extension-api-design.md` §12 and §13.
+
+## TUI spawn
+
+The Rust TUI (`zypi`) spawns the Python agent via (priority order):
+
+1. `PI_AGENT_COMMAND` env var
+2. `[agent].command` in `agent.toml`, then in `config.toml`
+3. `PI_PYTHON` env var (appends `-m pi_agent_cli`)
+
+**The agent's stderr.** The TUI owns the screen, and its own fd 2 is `/dev/null` (`pi_tty_utils::redirect_native_stderr`), so the agent's stderr goes to `<home>/logs/agent.stderr.log` instead (`acp/spawn.rs`, `agent_stderr`): appended across runs, one `--- agent started <time> (zypi pid N) ---` line per spawn, mode 0600 on Unix (a traceback can quote prompts, paths and keys), and a log longer than 1 MiB is moved to `agent.stderr.log.1` at the next spawn. A log that cannot be opened is skipped, not fatal. This is where a Python traceback or a warning from the agent ends up; the agent should still write diagnostics to stderr, not stdout (stdout is the ACP channel). `-p` runs are not redirected: there the agent's stderr is the user's terminal.
+
+**When the agent exits on its own.** The stdio bridge (`acp/spawn.rs`) waits on the child next to the cancel token, so an agent that dies is noticed instead of leaving requests to hang. It drains what the agent had already written, builds one message (`agent_exit_message`: the program, its exit status, and the last 12 lines / 4 KiB of `agent.stderr.log`), fails every pending request, and ends the bridge with that message. `connect()` reports a failed `initialize` as that message (`explain_failed_start`): `failed to spawn ACP agent` plus the program and `PI_AGENT_COMMAND` for a program that is not there, `exited on its own (exit status: 1)` plus the traceback's tail for a Python that lacks `pi_agent_cli`. Once the TUI is up, `AgentProcessGuard` prints `Error: …` on the restored terminal. So an agent must not exit on an error it can handle, and anything it prints to stderr before it dies reaches the user. `zypi`'s own exit status is unchanged. `tui/crates/codegen/pi-pager/tests/python_agent_e2e.rs` runs the pager's ACP client against this agent, including these failures (needs a Python with `pi_agent_cli`: `PI_E2E_PYTHON`; `PI_E2E_REQUIRED=1` makes its absence a failure, as in `tui-ci.yml`).
+
+## MCP servers
+
+The agent connects to **no** MCP server (Phase 4 non-goal; tools come from the harness and its extensions). `session/new`, `load` and `resume` accept `mcp_servers` and ignore them, which departs from ACP, whose session setup says an agent MUST support stdio servers; `initialize` advertises no `mcpCapabilities` (no `http`, no `sse`). The departure is made visible instead of silent: each time a session is set up with a non-empty list, the agent logs a warning and sends one agent message naming the servers (`mcp_notice`, from `_deferred_session_setup`, after the response has flushed like the other notices). Only the **names** are used: `env`, `headers`, `args` and `url` routinely hold tokens. `zypi` itself sends an empty list (it used to forward whatever it found in `.mcp.json`, `~/.claude.json` and Cursor's `mcp.json`), so there the notice never appears; it is for other ACP clients (an editor that passes its own servers). `tests/test_mcp_notice.py`. To implement MCP, start from the notice: it is the one place that sees the list.
+
+## Listing sessions
+
+`session/list` returns `SESSION_LIST_PAGE_SIZE` (50) sessions at a time, newest first, with `nextCursor` while more follow; the TUI keeps asking until it is gone. The order is the harness's (`JsonlSessionRepo.list_page`): creation time, which the session file names start with, so a page reads a file's header only when it gets that far and costs the files it looks at, not the directory (a `cwd` filter makes it skip other projects' files). `nextCursor` is opaque to the client and carries the file name the next page continues below; the agent keeps nothing between requests, so a cursor survives a restart, a session created meanwhile is simply newer than the cursor, and one deleted meanwhile moves nothing. A page that carries a cursor is never followed by an empty one (the agent looks one session ahead). A string the agent did not issue is `invalid_params`. `updated_at` is still the file's mtime, so it need not be in the order of the list.
+
+Looking a session up by id (`load` / `resume` / `pi/session/delete`) is `JsonlSessionRepo.find`: the file name ends in `-<id>.jsonl`, so only that file's header is read. `scripts/session_list_bench.py` measures all of this against the real agent (`start`, first page, every page, `session/load`) on a synthetic home; numbers and the decisions that rest on them are in `docs/PLAN/archive/PLAN-RUST-AGENT-RUNTIME-REMOVAL-EXECUTION-LOG.md` §10.11.
+
+## Two things the TUI and the agent agree on beyond ACP v1
+
+- **`_meta.sessionId` on `session/new`** is the TUI's `--session-id`: ACP v1 has no field for the id of a new session. The agent (`_chosen_session_id`, `_create_session_with_id`) takes it as the session's id. It must be a UUID in any form `uuid.UUID` reads, and comes back canonical (lower case, hyphens); anything else is `invalid_params`, because the id ends up in a file name. An id already in use is `invalid_params` too, whatever directory the session that has it belongs to: the repository would not refuse it (file names start with the creation time, so a second file with the same id fits beside the first), and a later `session/load` would find either. Requests for the same id at once make one session (`_chosen_id_lock`); two agent processes on one home are not covered. The question is `JsonlSessionRepo.has_session`, which opens a file only when its name does not already say it belongs to another session (`find` would read every header for an id nobody has); the one thing it takes on trust is a file renamed by hand to carry another id. What a free id still costs is the directory listing, about 0.07 s at 1,000 sessions and 0.3 s at 5,000 on both Windows and WSL2, against 8–20 ms for a session with an id of the agent's own (`scripts/session_list_bench.py`, the last block of its output). Nearly all of that is `LocalExecutionEnv.list_dir` building a `FileInfo` per entry (`os.listdir` of the same 5,000 files: 2–11 ms), which `session/list` pays on every page too. `tests/test_session_chosen_id.py`.
+- **`_meta["pi/cwd"]` in the response that opens a session** (`new`, `load`, `resume`) is the directory the session works in. `load` and `resume` take a `cwd` as well, and the one saved with the session wins; a client that only knows where it was started (`zypi --resume <id>` from another directory) learns the real one here. Nothing in the TUI reads it yet.
+
+## ACP contract tests
+
+`tests/test_acp_stdio_contract.py` drives an agent *process* over stdio the way the TUI does: `initialize`, `session/new`, streamed `prompt`, the `model` config option, `session/list` (first-prompt title), `session/load` replay and `session/resume` across a restart, `session/close`, a client-chosen id on `session/new` (and a taken one refused), the directory `session/load` reports, unknown methods answered with an error, exit code 0 on stdin EOF. It uses the mock LLM (`PI_USE_MOCK=1`) and a throw-away `PI_HOME`. Set `PI_ACP_CONTRACT_COMMAND` to run the same suite against another stdio ACP agent (it must honour `PI_HOME` and answer prompts with `Hello from mock`, without network), e.g. a future `pi-rust`.
+
+The mock LLM never calls a tool, so the tool side of the contract has its own file: `tests/test_acp_stdio_tools.py` drives `tests/_tool_agent.py` (the real `serve()` with a scripted LLM turn that calls one tool; `PI_TEST_TOOL_CALL` picks the call, `PI_TEST_PERMISSION` the mode) and checks, over the wire, what the pager relies on: in `ask` mode a `write` call is announced as a `tool_call` update, then put as `session/request_permission` (title, kind, `raw_input`, the two options `allow-once` / `reject-once`) before the tool runs; `allow-once` runs it, `reject-once` and a `cancelled` outcome do not and the turn still ends; `auto` never asks; `session/cancel` ends a prompt as `cancelled` (while a question is open, and while a `bash` call runs, which is then reaped; POSIX only), and is harmless with nothing running or for an unknown session. The scripted stream ends `aborted` once the signal is set, as the LangChain adapter does, so these tests do not depend on a real provider's abort handling.
+
+`__main__.serve()` starts `run_agent(..., use_unstable_protocol=True)`: `initialize` advertises `session/close` and `session/resume`, which the SDK serves only with that flag.
+
+## Stopping the agent
+
+The agent must reap the tools it is running when its client goes away: the TUI closes the agent's stdin and kills it only after a grace period (`acp/spawn.rs`, `AGENT_EOF_GRACE`). `serve()` ends on EOF on stdin (`run_agent` returns, `asyncio.run` cancels the turns in flight, each `bash` tool kills its process group) and on SIGTERM / SIGHUP (the main task is cancelled, same path); all exit 0. SIGHUP matters because a terminal that goes away, or a TUI killed while it is the session leader, sends it to the foreground process group, which includes the agent; its default action kills the agent before it can reap anything. A repeated signal gets the default action (the handlers remove themselves on the first one), so an agent that hangs while it stops — a thread that cannot be cancelled keeps `asyncio.run` from returning — can still be killed. SIGKILL cannot be handled and orphans the tools. `tests/test_acp_shutdown.py` runs `tests/_tool_agent.py` (the real `serve()` with a scripted `bash` call, or a stuck thread) and checks EOF, SIGTERM, SIGHUP and the repeated signal; POSIX only.
+
+**`-p` runs** have no stdin to close: `zypi -p` starts the agent as a child on the user's own terminal. They get the same stop signals (`_print_main`: the turn is cancelled, the tools are reaped, the exit status is 128 + the signal number), and zypi names itself in `PI_AGENT_PARENT_PID`, which the agent turns into a watch: every 0.5 s it checks `os.getppid()` and stops the same way once that pid is no longer its parent. That is how a zypi killed alone (`kill -9`, `kill <pid>`, an IDE's stop button) is noticed; a terminal hang-up or Ctrl+C reaches both anyway. The variable counts only if it names the agent's actual parent, or a process that is already gone (the parent died while the agent was starting); a live process that is not the parent is a wrapper script in between, and the watch stays off. `main()` removes the variable from the environment first thing, so a tool or a nested `-p` cannot inherit it. POSIX only: on Windows `getppid()` keeps naming the dead parent. `tests/test_print_shutdown.py` runs `tests/_print_agent.py` (the real `main()` with a scripted `bash` call) and checks both signals, a killed parent, an unrelated live pid, a parent that is already gone, and which values count. End to end, against a built `zypi` (Linux), `scripts/tui_pty/exit_matrix.py` (TUI: six ways out, two launch styles, with or without `--sandbox`) and `scripts/tui_pty/print_exit.py` (`zypi -p`, only zypi signalled) check that nothing is left running; see the README there.
+
+## System prompt pipeline
+
+`build_system_prompt` (`system_prompt.py`) assembles:
+
+1. Base prompt with tool snippets and `prompt_guidelines`
+2. `append_system_prompt` (config or CLI flag)
+3. Context files — `context_files.py` walks cwd → repo root collecting `AGENTS.md`, `CLAUDE.md`; a custom `.pi/SYSTEM.md` / `.pi/APPEND_SYSTEM.md` replaces or extends the base prompt only for a trusted project (see Project trust)
+4. Git status — `<git_status>` from `git_context.py` when cwd is a repo (`[git]` / `--no-git-context`); the prompt inputs (files, git subprocesses) are built in a worker thread, and `timeout_seconds` is one budget for the whole snapshot
+5. Skills from `[skills].paths`, formatted as `<available_skills>`
+
+`build_coding_agent_harness_system_prompt` (`create_harness.py`) wraps this for harness use.
+
+## Modules
+
+| Module | Role |
+|--------|------|
+| `agent.py` | `PiAcpAgent` — ACP methods, permission handling, event projection |
+| `config.py` | TOML loading, `pi_home()`, `CliConfig` dataclass |
+| `factory.py` | `create_session_harness` — wires tools, model, stream_fn, skills into harness |
+| `extension_trust.py` | `decide_project_trust` / `ProjectTrust`: whether a project may load its own extensions, saved workflows, prompt files and skills; the "skipped" and "could not be saved" notices |
+| `trust_fingerprint.py` | The gated resources of a project and a content fingerprint of them |
+| `trust_store.py` | `<home>/agent/trust.json`: answers saved per directory with the fingerprint they were about |
+| `trust_prompt.py` | The `session/request_permission` question (shape, option ids, how an answer is read) and its explanation message |
+| `extension_notices.py` | The "these extensions failed to load" notice (`AgentHarness.failed_extensions`): ACP agent message after `session/new`, headless stderr |
+| `mcp_notice.py` | The "these MCP servers were ignored" notice: names only, never `env` / `headers` / `args` / `url` |
+| `system_prompt.py` | `build_system_prompt`, tool snippet/guideline consumption |
+| `context_files.py` | AGENTS.md / CLAUDE.md / .pi/SYSTEM.md discovery |
+| `git_context.py` | Read-only branch and `git status` snapshot for the system prompt |
+| `headless.py` | `-p` one-shot mode, prompt override application |
+| `events.py` | Internal events → ACP `session_update` projection |
+| `permissions.py` | Tool permission gating (ask / auto / always-approve); in `ask` mode a tool is asked about unless its annotations say it is harmless (see Tool permissions) |
+| `session_list.py` | `session/list` display data: first-user-message title and file-mtime `updated_at` (bounded read), `SESSION_LIST_PAGE_SIZE`, the opaque `nextCursor` (`encode_cursor` / `decode_cursor`) |
+| `create_harness.py` | Harness-level system prompt, coding tool wiring |
+| `benchmarks/` | Pelican benchmark suite, evaluator, Docker runner |

{pi_agent_cli_lc-0.3.0 → pi_agent_cli_lc-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pi-agent-cli-lc
-Version: 0.3.0
+Version: 0.5.0
 Summary: Standard ACP agent over AgentHarness (no x.ai extensions)
 Project-URL: Homepage, https://github.com/zy1233/pi-python
 Project-URL: Repository, https://github.com/zy1233/pi-python
@@ -20,8 +20,8 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: agent-client-protocol>=0.12.0
-Requires-Dist: pi-agent-core-lc==0.3.0
-Requires-Dist: pi-agent-harness-lc==0.3.0
+Requires-Dist: pi-agent-core-lc==0.5.0
+Requires-Dist: pi-agent-harness-lc==0.5.0
 Requires-Dist: pydantic>=2.0
 Description-Content-Type: text/markdown
 

pi_agent_cli_lc-0.5.0/agent.example.toml

@@ -0,0 +1,82 @@
+# Copy to ~/.pi-python/agent.toml (or set PI_HOME).
+# Python ACP agent settings ONLY — do not duplicate these keys in config.toml
+# (the Rust TUI reads config.toml with its own typed schema: a key it knows, such as a top-level
+# `permission = "ask"`, stops it at start).
+# LLM keys are read from environment variables — never put secrets in this file.
+
+permission = "ask" # ask | auto | always-approve
+# `ask` asks before each tool call, except for tools that declare themselves harmless: read-only
+# or only keeping the agent's own notes (read, grep, find, ls, web_search, fetch_url, goal_*).
+# A tool that declares nothing is asked about; bash, edit, write and workflow always are.
+
+thinking_level = "off" # off | minimal | low | medium | high | xhigh
+max_turns = 50
+
+[model]
+provider = "deepseek"
+id = "deepseek-ai/DeepSeek-V4-Flash"
+base_url = "https://api.siliconflow.cn/v1"
+api_key_env = "REAL_LLM_API_KEY" # key for `provider` only; other providers use their own (e.g. ANTHROPIC_API_KEY)
+# Can the model reason? A thinking_level other than "off" is sent to the provider only if so.
+# Unset: any level but "off" says it can. `false` keeps a model that rejects reasoning parameters out of them.
+# reasoning = true
+
+# Extra models for the TUI `/model` picker (ACP session config option "model").
+# `[model]` above is always offered first; unset fields inherit from it, but
+# base_url / api_key_env / supports_images only when `provider` is unset or the same.
+# [[models]]
+# id = "deepseek-ai/DeepSeek-V4-Pro"
+# name = "DeepSeek V4 Pro"
+#
+# [[models]]
+# provider = "openai"
+# id = "gpt-4.1"
+# base_url = "https://api.openai.com/v1"
+# api_key_env = "OPENAI_API_KEY"
+
+[skills]
+# ".pi/skills" is relative to the project, so it loads only for a trusted project (see [extensions]).
+paths = ["~/.pi-python/skills", ".pi/skills"]
+
+[agent]
+# Used by the Rust TUI when PI_AGENT_COMMAND is unset (Windows: prefer a venv python.exe).
+command = "python -m pi_agent_cli"
+
+[prompt]
+# no_context_files = false
+# custom_system_prompt = "You are a helpful assistant."
+# custom_system_prompt_file = "~/.pi-python/agent/SYSTEM.md"
+# append_system_prompt = "Always run tests after edits."
+# append_system_prompt_file = "~/.pi-python/agent/APPEND_SYSTEM.md"
+
+[git]
+# A `git status` snapshot (branch name and the paths of changed and untracked files) is added to
+# the system prompt at the start of a session, so it is sent to the model provider with every
+# request. Set enabled = false if such names are sensitive.
+# enabled = true
+# timeout_seconds = 2   # one budget for the whole snapshot (up to four git commands), not per command
+# max_status_lines = 40
+
+[extensions]
+# Project trust. Extensions in <project>/.pi-python/extensions run arbitrary Python as soon as a
+# session opens, saved workflows in <project>/.pi-python/workflows become slash commands that
+# have the model run their scripts, and the project's .pi/SYSTEM.md, .pi/APPEND_SYSTEM.md and
+# project-relative [skills] paths decide what the model is told, so none of them is used until
+# the project is trusted. Only this file, the command line and your own answers decide that
+# (never a config inside the project). Installed extension packages, ~/.pi-python/extensions,
+# your own saved workflows (~/.pi-python/workflows), AGENTS.md and absolute or ~ skills paths
+# are not affected.
+#
+# An ACP client (the TUI) asks about a project that ships such files, once per directory.
+# "Trust and remember" is saved in ~/.pi-python/agent/trust.json with a fingerprint of those
+# files, so you are asked again when one of them changes (after a git pull, say). Delete the
+# project's entry from that file to take the trust back. Headless (-p) runs never ask, but
+# honour an answer given earlier for the same files.
+# default_project_trust = "ask"         # "ask" (default): ask in an ACP client
+#                                       # "never": do not ask; only the entries and answers below apply
+#                                       # "always": trust every project without asking
+# trusted_projects = ["~/work/my-repo"] # absolute or ~ paths, never asked about; subdirectories are
+#                                       # trusted too (Windows: use forward slashes, "C:/work/my-repo")
+# trust_project_extensions = false      # older switch: true means default_project_trust = "always"
+#                                       # (an explicit default_project_trust wins)
+# One-off alternatives: --trust-project-extensions, or PI_TRUST_PROJECT_EXTENSIONS=1

pi_agent_cli_lc-0.5.0/config.toml.example

@@ -0,0 +1,8 @@
+# Rust TUI config for ~/.pi-python/config.toml
+#
+# Leave this file empty, or write only keys that the TUI knows.
+# Python agent settings belong in agent.toml — NOT here.
+#
+# Top-level ``permission = "ask"`` will break TUI startup (the TUI expects a
+# ``[permission]`` table, not a string). A ``[[models]]`` array and invalid TOML
+# stop it too. Keys that the TUI does not know are ignored.

pi_agent_cli_lc-0.5.0/pi_agent_cli/__main__.py

@@ -0,0 +1,311 @@
+"""stdio entry: python -m pi_agent_cli
+
+Default: ACP agent on stdio.
+`python -m pi_agent_cli -p "..."`: one-shot headless turn (no TUI).
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import contextlib
+import json
+import os
+import signal
+import sys
+from pathlib import Path
+from typing import Any
+
+from acp import run_agent
+
+from pi_agent_cli.agent import PiAcpAgent
+from pi_agent_cli.config import load_local_env
+from pi_agent_cli.extension_trust import TRUST_ENV
+from pi_agent_cli.headless import HeadlessPromptOverrides, resolve_print_prompt, run_print
+
+_PROMPT_CLI_FLAG_NAMES = (
+    "system_prompt",
+    "system_prompt_file",
+    "append_system_prompt",
+    "append_system_prompt_file",
+    "no_context_files",
+    "no_git_context",
+)
+
+
+# SIGHUP is what a closing terminal sends to its foreground process group, which includes the
+# agent when the TUI is started from a shell. Windows has neither signal handlers nor SIGHUP.
+_STOP_SIGNALS = tuple(
+    getattr(signal, name) for name in ("SIGTERM", "SIGHUP") if hasattr(signal, name)
+)
+
+# `zypi -p` gives this process the user's own terminal as stdin, so the way the TUI's agent learns
+# that its client is gone (EOF on stdin) does not exist there. zypi names itself in this variable
+# instead, and the run stops once that process is no longer the parent: the kernel re-parents a
+# child whatever killed its parent, SIGKILL included.
+PARENT_PID_ENV = "PI_AGENT_PARENT_PID"
+PARENT_POLL_SECONDS = 0.5
+
+
+class _StopRequest:
+    """Ends the main task once, and remembers what asked for it."""
+
+    def __init__(self, task: asyncio.Task[Any]) -> None:
+        self._task = task
+        self.signum: int | None = None
+
+    def install_signal_handlers(self) -> None:
+        """Stop on SIGTERM / SIGHUP the way EOF on stdin stops the stdio agent.
+
+        The main task is cancelled, so `asyncio.run` cancels the in-flight turns and each running
+        tool's process group is reaped. Without a handler the signal ends the process at once and
+        its tools outlive it. (SIGKILL cannot be handled; there the tools are orphaned.)
+        """
+        loop = asyncio.get_running_loop()
+        for stop_signal in _STOP_SIGNALS:
+            with contextlib.suppress(NotImplementedError, RuntimeError):
+                loop.add_signal_handler(stop_signal, self.request, int(stop_signal))
+
+    def request(self, signum: int) -> None:
+        if self.signum is not None:
+            return
+        self.signum = signum
+        # A repeated signal gets the default action, so a process that hangs while it shuts down
+        # (a thread that cannot be cancelled) can still be stopped.
+        loop = asyncio.get_running_loop()
+        for stop_signal in _STOP_SIGNALS:
+            with contextlib.suppress(NotImplementedError, RuntimeError):
+                loop.remove_signal_handler(stop_signal)
+        self._task.cancel()
+
+
+async def serve(agent: PiAcpAgent) -> None:
+    """Serve ``agent`` over stdio until stdin closes or the process is told to stop."""
+    main_task = asyncio.current_task()
+    if main_task is not None:
+        _StopRequest(main_task).install_signal_handlers()
+    # `session/close` and `session/resume` are unstable in the SDK and answered with
+    # "Method not found" unless this flag is set, although `initialize` advertises both.
+    with contextlib.suppress(asyncio.CancelledError):
+        await run_agent(agent, use_unstable_protocol=True)
+
+
+def _process_exists(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True  # it exists, it is just not ours
+    return True
+
+
+def _take_parent_pid() -> int | None:
+    """The pid in ``PI_AGENT_PARENT_PID`` if this run should stop when that process goes away.
+
+    The variable is removed either way, so nothing this process starts (a tool, a nested
+    ``pi -p``) inherits a parent that is not its own. It counts when it names this process's
+    parent, or a process that no longer exists (the parent died while this one was starting; the
+    first check then stops the run). A live process that is not the parent is a wrapper in
+    between, and what this process should wait on is not its pid.
+    """
+    raw = os.environ.pop(PARENT_PID_ENV, None)
+    if os.name != "posix" or raw is None:
+        return None
+    try:
+        pid = int(raw)
+    except ValueError:
+        return None
+    if not 0 < pid < 2**31:
+        return None
+    if pid == os.getppid() or not _process_exists(pid):
+        return pid
+    return None
+
+
+async def _watch_parent(parent_pid: int, stop: _StopRequest) -> None:
+    """Ask for a stop once ``parent_pid`` is no longer this process's parent."""
+    while os.getppid() == parent_pid:
+        await asyncio.sleep(PARENT_POLL_SECONDS)
+    stop.request(signal.SIGTERM)
+
+
+async def _print_main(
+    prompt: str,
+    *,
+    cwd: Path | None,
+    prompt_overrides: HeadlessPromptOverrides,
+    parent_pid: int | None,
+) -> int:
+    """One ``-p`` turn, ended early by a stop signal or by the death of the process that started it.
+
+    A stop cancels the turn the way it does for the stdio agent, so the process group of every
+    running tool is reaped; the exit status is 128 plus the signal number, as a shell reports a
+    killed process.
+    """
+    task = asyncio.current_task()
+    if task is None:
+        return await run_print(prompt, cwd=cwd, prompt_overrides=prompt_overrides)
+    stop = _StopRequest(task)
+    stop.install_signal_handlers()
+    watcher = (
+        asyncio.create_task(_watch_parent(parent_pid, stop)) if parent_pid is not None else None
+    )
+    try:
+        return await run_print(prompt, cwd=cwd, prompt_overrides=prompt_overrides)
+    except asyncio.CancelledError:
+        if stop.signum is None:
+            raise
+        return 128 + stop.signum
+    finally:
+        if watcher is not None:
+            watcher.cancel()
+
+
+async def _amain() -> None:
+    await serve(PiAcpAgent())
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pi-agent-cli",
+        description="Standard ACP agent over AgentHarness (stdio), or one-shot -p print.",
+    )
+    src = parser.add_mutually_exclusive_group()
+    src.add_argument(
+        "-p",
+        "--print",
+        dest="print_prompt",
+        metavar="PROMPT",
+        help="Run one prompt, print the assistant text, and exit (no TUI, no ACP stdio).",
+    )
+    src.add_argument(
+        "--prompt-json",
+        metavar="JSON",
+        help="Single-turn prompt as a JSON string or list of content blocks.",
+    )
+    src.add_argument(
+        "--prompt-file",
+        metavar="PATH",
+        type=Path,
+        help="Read the single-turn prompt from a file.",
+    )
+    parser.add_argument(
+        "--cwd",
+        metavar="PATH",
+        type=Path,
+        help="Working directory for the headless session (default: process cwd).",
+    )
+    system = parser.add_mutually_exclusive_group()
+    system.add_argument(
+        "--system-prompt",
+        "--system-prompt-override",
+        dest="system_prompt",
+        metavar="TEXT",
+        help="Replace the default system prompt (headless only).",
+    )
+    system.add_argument(
+        "--system-prompt-file",
+        metavar="PATH",
+        type=Path,
+        help="Read the system prompt override from a file (headless only).",
+    )
+    append = parser.add_mutually_exclusive_group()
+    append.add_argument(
+        "--append-system-prompt",
+        "--rules",
+        dest="append_system_prompt",
+        metavar="TEXT",
+        help="Append text to the system prompt (headless only).",
+    )
+    append.add_argument(
+        "--append-system-prompt-file",
+        metavar="PATH",
+        type=Path,
+        help="Read append text from a file (headless only).",
+    )
+    parser.add_argument(
+        "--no-context-files",
+        action="store_true",
+        help="Skip AGENTS.md / CLAUDE.md discovery (headless only).",
+    )
+    parser.add_argument(
+        "--no-git-context",
+        action="store_true",
+        help="Omit the <git_status> section from the system prompt (headless only).",
+    )
+    parser.add_argument(
+        "--trust-project-extensions",
+        action="store_true",
+        help=(
+            "Load extensions from <project>/.pi-python/extensions, which run arbitrary "
+            f"Python (same as {TRUST_ENV}=1). Without it they are skipped unless the "
+            "project is listed under [extensions] trusted_projects in agent.toml."
+        ),
+    )
+    return parser
+
+
+def _apply_trust_flag(args: argparse.Namespace) -> None:
+    """``--trust-project-extensions`` is ``PI_TRUST_PROJECT_EXTENSIONS=1`` for this process."""
+    if args.trust_project_extensions:
+        os.environ[TRUST_ENV] = "1"
+
+
+def _prompt_overrides_from_args(args: argparse.Namespace) -> HeadlessPromptOverrides:
+    return HeadlessPromptOverrides(
+        system_prompt=args.system_prompt,
+        system_prompt_file=args.system_prompt_file,
+        append_system_prompt=args.append_system_prompt,
+        append_system_prompt_file=args.append_system_prompt_file,
+        no_context_files=True if args.no_context_files else None,
+        no_git_context=True if args.no_git_context else None,
+    )
+
+
+def _has_prompt_cli_flags(args: argparse.Namespace) -> bool:
+    return any(getattr(args, name) for name in _PROMPT_CLI_FLAG_NAMES)
+
+
+def main() -> None:
+    parent_pid = _take_parent_pid()  # first: nothing started from here may inherit the variable
+    load_local_env()
+    parser = _build_parser()
+    args = parser.parse_args()
+    _apply_trust_flag(args)
+    headless = any(
+        value is not None for value in (args.print_prompt, args.prompt_json, args.prompt_file)
+    )
+    if not headless and _has_prompt_cli_flags(args):
+        print(
+            "error: --system-prompt, --append-system-prompt, --no-context-files, "
+            "and --no-git-context require headless mode "
+            "(-p, --prompt-json, or --prompt-file)",
+            file=sys.stderr,
+        )
+        raise SystemExit(2)
+    if headless:
+        try:
+            prompt = resolve_print_prompt(
+                print_prompt=args.print_prompt,
+                prompt_json=args.prompt_json,
+                prompt_file=args.prompt_file,
+            )
+        except (OSError, ValueError, json.JSONDecodeError) as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            raise SystemExit(2) from exc
+        raise SystemExit(
+            asyncio.run(
+                _print_main(
+                    prompt,
+                    cwd=args.cwd,
+                    prompt_overrides=_prompt_overrides_from_args(args),
+                    parent_pid=parent_pid,
+                )
+            )
+        )
+    asyncio.run(_amain())
+
+
+if __name__ == "__main__":
+    main()