ton/pi_harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(coding-agent): expose session metadata to bash tools (#6967)

Browse Source
This commit is contained in:
Armin Ronacher
2026-07-22 20:15:02 +02:00
committed by GitHub
parent c55ae2faa5
commit bb3d7d399c
16 changed files with 278 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/coding-agent/docs/environment-variables.md
+88
View File
@@ -0,0 +1,88 @@
# Environment Variables
Pi uses environment variables in three ways:
- Variables such as `PI_OFFLINE` configure the Pi process.
- Pi sets `PI_CODING_AGENT` so child processes can detect that they run inside Pi.
- Commands run by the LLM-callable bash tool receive `PI_*` variables describing the current session.
Provider API-key variables are documented separately in [Providers](providers.md#environment-variables-or-auth-file).
## Process Marker
The CLI and RPC entry points set `PI_CODING_AGENT=true`. Child processes inherit it and can use it to detect that they run inside Pi. It is not session-specific and is not set automatically when Pi is embedded through the SDK.
## Bash Tool Session Environment
Commands run by the bash tool receive the current Pi session state:
| Variable | Description |
|----------|-------------|
| `PI_SESSION_ID` | Current session ID |
| `PI_SESSION_FILE` | Absolute path to the current session JSONL file; unset for ephemeral sessions |
| `PI_PROVIDER` | Currently selected model provider |
| `PI_MODEL` | Currently selected model ID |
| `PI_REASONING_LEVEL` | Current effective reasoning level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` |
The values are resolved when each command starts. Switching models or changing the reasoning level therefore affects the next bash command without restarting Pi. `PI_PROVIDER` and `PI_MODEL` identify the selected Pi model, not a different upstream model that a router may choose internally.
When asked which model or provider is running, inspect these variables instead of inferring the answer from the system prompt:
```bash
printf '%s/%s\n' "$PI_PROVIDER" "$PI_MODEL"
printf 'reasoning=%s session=%s\n' "$PI_REASONING_LEVEL" "$PI_SESSION_ID"
```
The session file can be inspected directly when the session is persistent:
```bash
if [ -n "$PI_SESSION_FILE" ]; then
tail -n 1 "$PI_SESSION_FILE"
fi
```
These variables are injected into the LLM-callable bash tool. They are not injected into user-entered `!` or `!!` commands.
### Custom Bash Tools
Bash tools created with `createBashTool()` expose the session environment by default when registered with Pi. Injection happens before `spawnHook`, so a hook receives the variables in `ctx.env`:
```typescript
const bashTool = createBashTool(cwd, {
spawnHook: (ctx) => ({
...ctx,
env: { ...ctx.env, CI: "1" },
}),
});
```
Disable session metadata independently of the spawn hook:
```typescript
const bashTool = createBashTool(cwd, {
exposeSessionEnvironment: false,
spawnHook: (ctx) => ctx,
});
```
When disabled, Pi removes inherited values for these variables so nested Pi processes do not expose stale parent-session metadata.
## Pi Process Configuration
These variables are read by Pi itself:
| Variable | Description |
|----------|-------------|
| `PI_CODING_AGENT_DIR` | Override the config directory; default is `~/.pi/agent` |
| `PI_CODING_AGENT_SESSION_DIR` | Override session storage; overridden by `--session-dir` |
| `PI_PACKAGE_DIR` | Override the package directory, useful for Nix/Guix store paths |
| `PI_OFFLINE` | Disable startup network operations, including update checks, package updates, and install/update telemetry |
| `PI_SKIP_VERSION_CHECK` | Disable the `pi.dev` latest-version request |
| `PI_TELEMETRY` | Override install/update telemetry and provider attribution headers: `1`/`true`/`yes` or `0`/`false`/`no` |
| `PI_CACHE_RETENTION` | Set to `long` for extended provider prompt caching where supported |
| `PI_SHARE_VIEWER_URL` | Override the base URL used by `/share` |
| `PI_HARDWARE_CURSOR` | Set to `1` to show the hardware cursor; see [Terminal setup](terminal-setup.md) |
| `VISUAL`, `EDITOR` | External editor fallback when `externalEditor` is unset |
| `HTTP_PROXY`, `HTTPS_PROXY` | Proxy outbound HTTP requests |
Provider credentials such as `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and cloud-provider configuration are listed in [Providers](providers.md#environment-variables-or-auth-file).
packages/coding-agent/docs/extensions.md
+11 -3
View File
@@ -982,9 +982,9 @@ ctx.sessionManager.buildContextEntries() // Active branch entries with compac
ctx.sessionManager.getLeafId() // Current leaf entry ID
```
### ctx.modelRegistry / ctx.model
### ctx.modelRegistry / ctx.model / ctx.thinkingLevel
Access to models, providers, and resolved authentication. `ctx.modelRegistry.getProvider(id)` returns the effective pi-ai provider, while `getProviderAuth(id)` resolves its current API key, headers, base URL, and provider-scoped environment without requiring a loaded model. `ctx.model` is the active model.
Access to models, providers, and resolved authentication. `ctx.modelRegistry.getProvider(id)` returns the effective pi-ai provider, while `getProviderAuth(id)` resolves its current API key, headers, base URL, and provider-scoped environment without requiring a loaded model. `ctx.model` is the active model, and `ctx.thinkingLevel` is its current effective thinking level.
### ctx.signal
@@ -2096,7 +2096,15 @@ const bashTool = createBashTool(cwd, {
});
```
See [examples/extensions/ssh.ts](../examples/extensions/ssh.ts) for a complete SSH example with `--ssh` flag.
`createBashTool()` exposes the current session to commands through `PI_SESSION_ID`, `PI_SESSION_FILE`, `PI_PROVIDER`, `PI_MODEL`, and `PI_REASONING_LEVEL`. Injection happens before `spawnHook`, so hooks receive these values in `env` and preserve them when they spread the existing environment as above. Set `exposeSessionEnvironment: false` to disable them:
```typescript
const bashTool = createBashTool(cwd, {
exposeSessionEnvironment: false,
});
```
See [Bash tool session environment](environment-variables.md#bash-tool-session-environment) for variable semantics. See [examples/extensions/ssh.ts](../examples/extensions/ssh.ts) for a complete SSH example with `--ssh` flag.
### Output Truncation
packages/coding-agent/docs/index.md
+1
View File
@@ -68,6 +68,7 @@ For the full first-run flow, see [Quickstart](quickstart.md).
## Reference
- [Environment variables](environment-variables.md) - Pi process configuration and session metadata available to bash tools.
- [Session format](session-format.md) - JSONL session file format, entry types, and SessionManager API.
## Platform setup
packages/coding-agent/docs/usage.md
-13
View File
@@ -289,19 +289,6 @@ pi --tools read,grep,find,ls -p "Review the code"
pi --exclude-tools ask_question
```
### Environment Variables
| Variable | Description |
|----------|-------------|
| `PI_CODING_AGENT_DIR` | Override config directory; default is `~/.pi/agent` |
| `PI_CODING_AGENT_SESSION_DIR` | Override session storage directory; overridden by `--session-dir` |
| `PI_PACKAGE_DIR` | Override package directory, useful for Nix/Guix store paths |
| `PI_OFFLINE` | Disable startup network operations, including update checks, package update checks, and install/update telemetry |
| `PI_SKIP_VERSION_CHECK` | Skip the Pi version update check at startup. This prevents the `pi.dev` latest-version request |
| `PI_TELEMETRY` | Override install/update telemetry and provider attribution headers: `1`/`true`/`yes` or `0`/`false`/`no`. This does not disable update checks |
| `PI_CACHE_RETENTION` | Set to `long` for extended prompt cache where supported |
| `VISUAL`, `EDITOR` | Fallback external editor for Ctrl+G when `externalEditor` is unset; defaults to Notepad on Windows and `nano` elsewhere |
## Design Principles
Pi keeps the core small and pushes workflow-specific behavior into extensions, skills, prompt templates, and packages.