docs(pi): unify split package trees; move live OMP pages to core
Two directories documented one concept (pi npm packages): top-level packages/ (browser-use, permission-system) and pi/packages/ (peon, web-access, subagents). Merged into pi/packages/ — one row per package in a single index, detail pages kept as archive records. The root index's 'OMP packages and skills' section was doubly wrong (packages/ was pi, not OMP); it becomes a Skills tooling section pointing at the consolidated /skills/ tree. Moved the two LIVE omp pages out of the retired-harness banner: pi/statusline.md -> core/statusline.md, pi/subagent-limits.md -> core/subagent-limits.md (both document omp behavior against agent/config.yml + the installed bundle; pi/index.md itself admitted the mis-shelf). Retargeted every inbound link (core/index, system/ dankserver, log x2, pi/index, settings x2, moved files' own xrefs). Refs #29
This commit is contained in:
Frank committed
1 parent
39385636be
commit
99b9a6a17c
13 files changed
+53
-80
No files matched your search
+18
-32
@@ -1,37 +1,28 @@
|
||||
# Pi Configuration
|
||||
# Pi Configuration (archive)
|
||||
|
||||
> **Archive note (2026-10-18).** Most pages in this directory document the retired
|
||||
> **pi** harness (settings.json / models.json, `frank-default-*` endpoints, verified
|
||||
> 2026-08-28). The live harness is **omp** — its config is `agent/config.yml` +
|
||||
> `agent/models.yml` in this repo, the current fleet endpoints are on
|
||||
> [System hosts](/system/index.md), and omp-specific knowledge lands in pages like
|
||||
> [OMP Status Line Customization](/pi/statusline.md) below. Read pi pages as
|
||||
> historical records, not current state.
|
||||
> **Archive (2026-10-18).** This directory documents the retired **pi** harness
|
||||
> (`settings.json` / `models.json`, `frank-default-*` endpoints). The live
|
||||
> harness is **omp**: config in `agent/config.yml` + `agent/models.yml` (this
|
||||
> repo), fleet endpoints on [System hosts](/system/index.md). Read these pages
|
||||
> as historical records, not current state. Knowledge that survived the harness
|
||||
> move lives under [Core](/core/index.md):
|
||||
> [OMP Status Line](/core/statusline.md) and
|
||||
> [OMP Subagent Limits](/core/subagent-limits.md).
|
||||
|
||||
## Configuration Files
|
||||
## Configuration Files (pi-era)
|
||||
|
||||
- [Pi Settings System (settings.json)](/core/settings.md) — Main `settings.json` reference. Providers, models, packages, subagent overrides.
|
||||
- [Pi Models Configuration](/pi/models.md) — `models.json` reference. Provider definitions, model specs, endpoints.
|
||||
- [OMP Status Line Customization](/pi/statusline.md) — How presets, composer shapes, and segment arrays actually interact; the fleet's tuned bar.
|
||||
- [Pi Settings System (settings.json)](/core/settings.md) — Main `settings.json` record. Providers, models, packages, subagent overrides.
|
||||
- [Pi Models Configuration](/pi/models.md) — `models.json` record. Provider definitions, model specs, endpoints.
|
||||
|
||||
## Extensions
|
||||
## Extensions (pi-era)
|
||||
|
||||
- [Pi Packages](/pi/packages/index.md) — Installed npm packages that extend pi functionality.
|
||||
- [Pi Peon](/pi/packages/pi-peon.md) — CESP/OpenPeon sound-pack player for lifecycle events.
|
||||
- [Pi Web Access](/pi/packages/pi-web-access.md) — Web search, URL fetching, GitHub cloning, PDF extraction, video understanding.
|
||||
- [Pi Browser Use](/packages/pi-browser-use.md) — Browser automation extension wrapping chrome-devtools-mcp with a `browser_` prefix.
|
||||
- [Pi Permission System](/packages/pi-permission-system.md) — Permission enforcement and policy configuration for subagent extensions.
|
||||
- [Pi Packages](/pi/packages/index.md) — installed npm packages: peon, web-access, subagents, browser-use, permission-system.
|
||||
|
||||
## Skills
|
||||
## Skills (pi-era)
|
||||
|
||||
- [Pi Skills](/pi/skills.md) — Installed agent skills. Symlinked from `~/.agents/skills/` and `~/.pi/agent/skills/`.
|
||||
- [Pi Skills](/pi/skills.md) — installed skills inventory. Current skill toolchain: [Skills](/skills/index.md).
|
||||
|
||||
## Subagent Architecture
|
||||
|
||||
- [OMP Subagent Limits & Fan-out Policy](/pi/subagent-limits.md) — Live caps: concurrency 2, no nested spawns (and the `maxRecursionDepth: 0` trap), per-endpoint in-flight ceilings, isolation policy.
|
||||
- [Pi Subagents](/pi/packages/pi-subagents.md) — (historical) pi-era delegation system. Chains, parallel execution, TUI clarification.
|
||||
|
||||
## Architecture
|
||||
## Architecture (pi-era)
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
@@ -51,7 +42,7 @@ graph TD
|
||||
M --> O[dankclaw 192.168.0.143:7770]
|
||||
```
|
||||
|
||||
## Note on the Live Default
|
||||
## Note on the Live Default (historical)
|
||||
|
||||
In the pi era, `models.json` defined the live provider set: the main session
|
||||
provider was `llamacpp` with default model `frank-default-large` (Dankclaw);
|
||||
@@ -60,8 +51,3 @@ to `frank-default-large`. Two scopes owned settings: the user
|
||||
`~/.pi/settings.json` (main → Dankclaw/large) and the project
|
||||
`/home/dank/.pi/agent/settings.json` (main → Dankserver/small); when they
|
||||
disagreed, the project-scope file won for the agent's own main session.
|
||||
|
||||
> **Note:** This documentation describes the pi-coding-agent harness (config
|
||||
> format, packages, skill system) as general reference material. The live
|
||||
> harness is OMP at `~/.omp/`; OMP-managed skills live in
|
||||
> `~/.omp/agent/managed-skills/`.
|
||||
@@ -1,29 +1,27 @@
|
||||
# Pi Packages
|
||||
|
||||
Pi extends its functionality through npm packages installed via `pi install`. Each package provides extensions, skills, prompts, or themes.
|
||||
Pi extended itself through npm packages (`pi install npm:<name>`), each
|
||||
bundling extensions, skills, prompts, or themes. The harness is retired
|
||||
(2026-10-18); this page is the merged census of what was installed — one row
|
||||
per package, detail pages kept as historical records.
|
||||
|
||||
## Installed Packages
|
||||
## Installed packages
|
||||
|
||||
| Package | Version | Description |
|
||||
|---------|---------|-------------|
|
||||
| [[pi-peon|pi-peon]] | 0.1.1 | CESP/OpenPeon sound-pack player for pi lifecycle events |
|
||||
| [[pi-web-access|pi-web-access]] | 0.22.0 | Web search, URL fetching, GitHub cloning, PDF extraction, video understanding |
|
||||
| Package | Version | Detail | What it did |
|
||||
|---------|---------|--------|-------------|
|
||||
| `@wierdbytes/pi-peon` | 0.1.1 | [Pi Peon](pi-peon.md) | CESP/OpenPeon sound-pack player for pi lifecycle events. |
|
||||
| `pi-web-access` | 0.22.0 | [Pi Web Access](pi-web-access.md) | Web search, URL fetching, GitHub cloning, PDF extraction, video understanding. |
|
||||
| `pi-subagents` | 0.36.0 | [Pi Subagents](pi-subagents.md) | Core subagent delegation — chains, parallel execution, TUI clarification. |
|
||||
| `pi-browser-use` | — | [Pi Browser Use](pi-browser-use.md) | Browser automation wrapping chrome-devtools-mcp behind a `browser_` prefix. |
|
||||
| `pi-permission-system` | — | [Pi Permission System](pi-permission-system.md) | Permission enforcement and policy configuration; upstream docs are 10 interlinked pages. |
|
||||
|
||||
## Core Extension
|
||||
## Where the concepts live now
|
||||
|
||||
| Package | Version | Description |
|
||||
|---------|---------|-------------|
|
||||
| [[pi-subagents|pi-subagents]] | 0.36.0 | Core subagent delegation — chains, parallel execution, TUI clarification |
|
||||
|
||||
---
|
||||
* Subagent delegation → [OMP Subagent Limits & Fan-out Policy](/core/subagent-limits.md) (live caps).
|
||||
* Skill/package distribution → [Skills](/skills/index.md) (Agent Skills standard + `skills` CLI).
|
||||
* Web access → the `web/searxng` provider and MCP tooling; see [Agentic web research](/agentic-web-research/index.md).
|
||||
|
||||
## See Also
|
||||
|
||||
- [[settings|settings]] — Package configuration in settings.json
|
||||
- [pi](../index.md) — Pi configuration overview
|
||||
|
||||
* [Pi Peon](pi-peon.md) — CESP/OpenPeon sound-pack player for pi lifecycle events — peons, GLaDOS, battlecruisers, and 300+ community sound packs.
|
||||
|
||||
* [Pi Subagents](pi-subagents.md) — Core pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification.
|
||||
|
||||
* [Pi Web Access](pi-web-access.md) — Web search, URL fetching, GitHub cloning, PDF extraction, and video understanding for Pi. Zero-config with Exa MCP.
|
||||
- [Pi Settings System](/core/settings.md) — where these packages were registered (`settings.json` archive).
|
||||
- [Pi Configuration](/pi/index.md) — pi-era overview.
|
||||
@@ -0,0 +1,117 @@
|
||||
---
|
||||
type: reference
|
||||
title: Pi Browser Use
|
||||
description: Browser automation extension wrapping chrome-devtools-mcp with a browser_ prefix for pi-coding-agent.
|
||||
resource: https://github.com/TGYD-helige/pi
|
||||
tags:
|
||||
- pi
|
||||
- package
|
||||
- browser
|
||||
- chrome-devtools-mcp
|
||||
- unverified
|
||||
timestamp: 2026-08-28
|
||||
---
|
||||
[pi-browser-use](https://github.com/TGYD-helige/pi) is a pi-coding-agent extension that wraps [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp), exposing all browser automation tools with a unified `browser_` prefix.
|
||||
|
||||
**License:** Apache-2.0
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
- **Dynamic tool discovery** — auto-proxies all upstream chrome-devtools-mcp tools with `browser_` prefix
|
||||
- **Tool description augmentation** — adds usage hints for key tools
|
||||
- **Result post-processing** — strips embedded snapshots, detects overlay/stale element issues
|
||||
- **Optional visual analysis** — `browser_analyze_screenshot` via configurable vision model
|
||||
- **Standalone mode** — runnable as independent MCP server via CLI
|
||||
|
||||
### Requirements
|
||||
|
||||
Node.js >= 20, Chrome (stable or newer), `@earendil-works/pi-coding-agent >= 0.74.0`.
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pi install npm:@amaster.ai/pi-browser-use
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
### As pi-coding-agent Extension (Recommended)
|
||||
|
||||
Auto-discovers and loads on `session_start`. Configure in `.pi/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"pi-browser-use": {
|
||||
"headless": true,
|
||||
"channel": "stable",
|
||||
"viewport": "1280x720",
|
||||
"experimentalVision": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### As Standalone MCP Server
|
||||
|
||||
```bash
|
||||
npx @amaster.ai/pi-browser-use --headless --viewport=1280x720
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Session Mode
|
||||
|
||||
| Mode | Description |
|
||||
|------|-------------|
|
||||
| `persistent` (default) | Reuses shared profile at `~/.pi/browser-profile` |
|
||||
| `isolated` | Fresh ephemeral profile each session |
|
||||
| `existing` | Connects to running browser instance |
|
||||
|
||||
### Browser Options
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `headless` | `boolean` | `false` | Run headless |
|
||||
| `channel` | `string` | — | Chrome channel: `canary`, `dev`, `beta`, `stable` |
|
||||
| `viewport` | `string` | — | Viewport size, for example `1280x720` |
|
||||
| `userDataDir` | `string` | — | Custom user data directory |
|
||||
|
||||
### Vision Model
|
||||
|
||||
```json
|
||||
{
|
||||
"pi-browser-use": {
|
||||
"visionModel": {
|
||||
"provider": "openai",
|
||||
"model": "gpt-4o"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Resolves API key and base URL from the model registry automatically.
|
||||
|
||||
---
|
||||
|
||||
## Key Tools
|
||||
|
||||
| Tool | Hint |
|
||||
|------|------|
|
||||
| `browser_click` | Use element uid from snapshot; UIDs invalidated after action |
|
||||
| `browser_fill` | Does not work on canvas/custom widgets |
|
||||
| `browser_press_key` | Accepts single key name only |
|
||||
| `browser_take_snapshot` | Call first to get uids, and after every state-changing action |
|
||||
|
||||
---
|
||||
|
||||
## Cross-References
|
||||
|
||||
- See [Skills](/skills/index.md) for the skill toolchain that replaced pi-package distribution.
|
||||
- See [OKF Specification](/references/okf-spec.md) for the knowledge bundle format.
|
||||
@@ -81,5 +81,5 @@ The `/peon` command opens an interactive settings modal with:
|
||||
|
||||
## See Also
|
||||
|
||||
- [packages](../../packages/index.md) — Package overview
|
||||
- [Pi Packages](index.md) — Package overview
|
||||
- [pi](../index.md) — Pi configuration
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
type: reference
|
||||
title: Pi Permission System
|
||||
description: Permission enforcement and policy configuration system for pi-coding-agent extensions.
|
||||
resource: https://github.com/gotgenes/pi-permission-system
|
||||
tags:
|
||||
- pi
|
||||
- package
|
||||
- permissions
|
||||
- unverified
|
||||
timestamp: 2026-08-28
|
||||
---
|
||||
[pi-permission-system](https://github.com/gotgenes/pi-permission-system) is the permission enforcement and policy configuration system for pi-coding-agent extensions.
|
||||
|
||||
---
|
||||
|
||||
## Documentation Index
|
||||
|
||||
| Document | File | Description |
|
||||
|----------|------|-------------|
|
||||
| Overview | README.md | Package overview, install, quick start, feature list |
|
||||
| Configuration | configuration.md | Full policy reference, runtime knobs, per-agent overrides, common recipes |
|
||||
| Session Approvals | session-approvals.md | Session-scoped rules, pattern suggestions, bash arity table |
|
||||
| Cross-Extension API | cross-extension-api.md | Service accessor, event bus, decision/UI-prompt broadcasts |
|
||||
| Subagent Integration | subagent-integration.md | Permission forwarding, coexistence with subagent extensions |
|
||||
| Frontmatter Convention | permission-frontmatter-for-subagent-extensions.md | Convention guide for subagent extension authors |
|
||||
| OpenCode Compatibility | opencode-compatibility.md | Shared concepts, divergences, porting guide |
|
||||
| Troubleshooting | troubleshooting.md | Common issues, diagnostic logging, threat model |
|
||||
| Migration: Legacy → Flat | legacy-to-flat.md | Migration from pre-v2 config layout |
|
||||
| Migration: Strict Validation | strict-config-validation.md | Strict config validation (breaking) — reading and fixing rejected configs |
|
||||
|
||||
---
|
||||
|
||||
## Cross-References
|
||||
|
||||
- See [Skills](/skills/index.md) for the skill toolchain that replaced pi-package distribution.
|
||||
- See [AGENTS.md Format](/core/agents-md-format.md) for the system-level instruction format that governs how this system is referenced in agent contracts.
|
||||
@@ -1,199 +0,0 @@
|
||||
---
|
||||
type: reference
|
||||
title: OMP Status Line Customization
|
||||
description: How the omp status line actually works — presets vs custom arrays, composer-shape segment routing, the context meter (box/band only), the 27-segment catalog, and the fleet's tuned layout.
|
||||
tags:
|
||||
- omp
|
||||
- tui
|
||||
- statusline
|
||||
- config
|
||||
timestamp: 2026-10-18
|
||||
---
|
||||
|
||||
# OMP Status Line Customization
|
||||
|
||||
Ground truth from the installed bundle (`@oh-my-pi/pi-coding-agent/dist/cli.js`),
|
||||
verified live on blankpad 2026-10-18 and re-audited line-by-line against the
|
||||
minified source the same day (see [Audit log](#audit-log)). Status knobs live
|
||||
in `agent/config.yml` under `statusLine:`; the two composer knobs
|
||||
(`composer.shape`, `composer.tokenRate`) under `composer:`. The file is
|
||||
file-watched — edits repaint a running session without restart (verify
|
||||
visually: niri screenshot, see [niri capture recipe](../system/index.md)).
|
||||
`/settings` (Appearance tab) previews these live with sample data.
|
||||
|
||||
## Preset vs custom — the trap
|
||||
|
||||
`statusLine.preset` ships whole configurations. **`leftSegments` /
|
||||
`rightSegments` are ignored unless `preset: custom`** (`s ? user ?? preset
|
||||
: preset` in the resolver). **`segmentOptions` is NOT gated** — user options
|
||||
merge over the preset's own options under *every* preset.
|
||||
|
||||
| preset | leftSegments | rightSegments | separator |
|
||||
|---|---|---|---|
|
||||
| `default` | pi vim model mode collab stream path git pr context_pct cost | session_name | powerline-thin |
|
||||
| `minimal` | vim path git | session_name mode context_pct | slash |
|
||||
| `compact` | vim model mode git pr | session_name cost context_pct | powerline-thin |
|
||||
| `full` | pi vim hostname model mode path git pr subagents | session_name cache_hit token_in token_out token_rate cache_read cost context_pct time_spent time | powerline |
|
||||
| `nerd` | pi vim hostname model mode path git pr session subagents | session_name token_in token_out cache_read cache_write token_rate cost context_pct context_total time_spent time | powerline |
|
||||
| `ascii` | vim model mode path git pr | session_name token_total cost context_pct | ascii |
|
||||
| `custom` | your `statusLine.leftSegments` | your `statusLine.rightSegments` | powerline-thin |
|
||||
|
||||
The built-in default for `statusLine.leftSegments`/`rightSegments` themselves
|
||||
is the `ascii`-era pair (`vim model mode path git pr` / `session_name
|
||||
token_total cost context_pct`) — a config carrying those arrays with a named
|
||||
preset is running the preset, not the arrays. The fleet runs `preset: custom`.
|
||||
|
||||
## Composer shape routes the segments
|
||||
|
||||
`composer.shape` decides *where* the two arrays render. Eight shapes ship in
|
||||
the bundle; the plugin API can register more (`zG()` = built-ins + a live
|
||||
registration map). Internally each shape carries `statusAttachment`,
|
||||
`bottomBar`, `bottomBarGap`:
|
||||
|
||||
| shape | attach | bottom bar | leftSegments | rightSegments |
|
||||
|---|---|---|---|---|
|
||||
| `band` (fleet, default) | top-band | none | merged single row above editor, left | same row, right (`session_name` skipped — title rides the working row) |
|
||||
| `box` | top-border | none | box top border | box top border |
|
||||
| `claude` | top-rule-chip | left | bottom strip, left | top rule chip, right-aligned |
|
||||
| `rule` | top-rule-chip | left + gap | like claude, gap above strip | like claude |
|
||||
| `pi` | none | full | single bottom bar | single bottom bar |
|
||||
| `borderless` | none | full | single bottom bar | single bottom bar |
|
||||
| `field` / `rail` | none | full + gap (filled surface) | single bottom bar | single bottom bar |
|
||||
|
||||
The chip/strip layouts paint their rules as **session-accent fillers, not
|
||||
meters** — the context meter exists only in `box` and `band`
|
||||
(see next section). The top-rule chip renders right segments only, the bottom
|
||||
strip left segments only.
|
||||
|
||||
The working row is composer chrome, not segment-addressable: session title +
|
||||
shimmer, plus the tok/s readout when `composer.tokenRate: true` (default
|
||||
false). The readout is estimated from streamed deltas, corrected by billed
|
||||
output counts; the bundle also mentions a native-composer-bar placement in
|
||||
filled styles.
|
||||
|
||||
## The context meter
|
||||
|
||||
`statusLine.contextLine` (enum `off` / `percentage` / `annotated` /
|
||||
`embedded`, default `embedded`) tunes the rule between the segment groups.
|
||||
The knob description says "box composer only" — **that is wrong**: the meter
|
||||
renders in `box` **and** `band`; in every other shape the rule is a constant
|
||||
session-accent filler regardless of this setting (live-verified claude with
|
||||
`off` vs `embedded`: identical, and not context-proportional).
|
||||
|
||||
In box/band:
|
||||
|
||||
- `off` → plain accent rule (single color, full width).
|
||||
- `embedded` → the inline labeled meter: `60% ——— × 200K`. Requires
|
||||
`contextWindow > 0`, a `context_pct`/`context_total` segment present in
|
||||
either array, and at least one non-context segment. The context segment(s)
|
||||
are **hoisted out of the arrays** — they never render as text in this mode.
|
||||
- `percentage` / `annotated` → unlabeled proportional meter painted into the
|
||||
rule (live-verified in band: colored fill ∝ usage at the rule's right end);
|
||||
`context_pct` stays a normal text segment.
|
||||
|
||||
Fill length ∝ `min(100, contextPercent)`; >100% paints the raw percent and
|
||||
shortens the meter. Meter/segment color thresholds scale with window size —
|
||||
warning at ≥ min(50 %, 150K tokens), purple ≥ min(70 %, 270K), error ≥
|
||||
min(90 %, 500K); below that the theme's `statusLineContext` color.
|
||||
|
||||
## Segment universe (27)
|
||||
|
||||
`pi`, `status`, `model`, `mode`, `path`, `git`, `pr`, `subagents`,
|
||||
`token_in`, `token_out`, `token_total`, `token_rate`, `cost`, `context_pct`,
|
||||
`context_total`, `time_spent`, `time`, `session`, `hostname`, `cache_read`,
|
||||
`cache_write`, `cache_hit`, `session_name`, `usage`, `collab`, `stream`, `vim`.
|
||||
|
||||
Zero/inactive segments render nothing — dead weight costs no width.
|
||||
|
||||
| segment | renders | trigger / notes |
|
||||
|---|---|---|
|
||||
| `pi` | brand glyph + turn-elapsed | while streaming; focused-agent ghost id (warning color) when a subagent is focused |
|
||||
| `status` | hook/extension statuses, dot-joined | extension pushes via `ctx.ui.setStatus()` (ordered by key); suppressed in footer when `statusLine.showHookStatus: false` |
|
||||
| `model` | display `name` + thinking level | suffix hidden by `segmentOptions.model.showThinkingLevel: false`; `statusLine.compactThinkingLevel: true` (default) swaps in a compact glyph; fast-mode, advisor/tariff badges attach here |
|
||||
| `mode` | `Plan` / `Prewalk` / `Goal` / `Vibe` / `Loop …` | only in those modes (paused variants add a pause glyph); there is **no yolo/auto-approval display** in this segment |
|
||||
| `path` | cwd or `project/worktree` label | see [Path segment](#path-segment-and-stripworkprefix) |
|
||||
| `git` | branch + dirty badges | `+N` staged, `*N` unstaged, `?N` untracked (`segmentOptions.git.showStaged/showUnstaged/showUntracked`, default true); `showBranch: false` hides branch text and keeps badges (git icon carries them); color flips on dirty |
|
||||
| `pr` | `#<number>` hyperlink | only once the session has an associated PR |
|
||||
| `subagents` | count | hidden at 0; when subagents are actively running the composer paints its own live badge and this segment self-suppresses |
|
||||
| `token_in` / `token_out` | cumulative session input/output tokens | hidden at 0; `cache_read` / `cache_write` likewise cumulative |
|
||||
| `token_total` | `input + output + cache_write + orchestration_in + orchestration_out` | hidden at 0 |
|
||||
| `token_rate` | `N.N tok/s` | hidden when not streaming (the working-row readout is a separate, `composer.tokenRate`-gated thing) |
|
||||
| `cost` | session cost | includes subagent-tree + advisor cost; `↑`/`↓` peak/off-peak arrow for time-priced providers |
|
||||
| `context_pct` | `NN.N%/200K` (or window alone when percent is unknown) | hoisted into the meter in `embedded` box/band; auto-compact speculation icon rides along |
|
||||
| `context_total` | absolute context tokens | also hoisted by the embedded meter |
|
||||
| `time_spent` | active session time | hidden under 1 s; this is *active* time, not wall clock |
|
||||
| `time` | wall clock | `segmentOptions.time.format: "12h"/"24h"`, `showSeconds` |
|
||||
| `session` | first 8 chars of session id (`new` before resume exists) | resume-by-id handle |
|
||||
| `session_name` | session title, accent | in `band` it renders on the working row instead |
|
||||
| `hostname` | short hostname | accent-tinted with session color |
|
||||
| `usage` | rate-limit windows | 5h / daily / 7d / monthly bars + tier badge, when the provider reports them |
|
||||
| `collab` | `collab:N` / `collab guest:N` | only in collab sessions |
|
||||
| `stream` | `● LIVE <viewers>` / `● REC` | only while streaming/recording |
|
||||
| `vim` | mode glyph/word | only while vim keybindings are active; selected-line count appended (` 3L`); `display` icon vs text comes from the vim runtime, not config |
|
||||
|
||||
## Path segment and `stripWorkPrefix`
|
||||
|
||||
`segmentOptions.path.stripWorkPrefix` (default **true** — the code tests
|
||||
`!== false`) gates two behaviors in the `path` renderer:
|
||||
|
||||
1. **Worktree sessions:** `true` never shows the disk path — it renders the
|
||||
logical `projectName/worktreeName` label (bare `projectName` when the
|
||||
current branch is named after the worktree) with the worktree glyph.
|
||||
`false` opts out and shows the real cwd with a folder glyph, plus a
|
||||
` ↳ relativeRepoRoot` suffix inside a repo. Base-directory-only is not
|
||||
renderable in either mode.
|
||||
2. **All sessions:** `true` uses the pretty display path (scratch sessions
|
||||
get the scratch-folder icon); `false` uses the raw absolute cwd.
|
||||
|
||||
`abbreviate` (default **true**: home → `~`; `false` keeps the full path —
|
||||
also affects tool labels/errors per upstream docs) and `maxLength` (clip,
|
||||
default 40) apply afterwards in both modes. The fleet runs `true` — logical
|
||||
label, worktree glyph (verified live 2026-10-18; an earlier trial of `false`
|
||||
for the full cwd was rejected by eye).
|
||||
|
||||
## Status knobs (registry-verified)
|
||||
|
||||
`statusLine.preset` · `.leftSegments` · `.rightSegments` · `.segmentOptions` ·
|
||||
`.separator` (`powerline` `powerline-thin` `slash` `pipe` `block` `none`
|
||||
`ascii`; default `powerline-thin`) · `.contextLine` · `.sessionAccent`
|
||||
(default true; hashes the session name into the editor border *and* the
|
||||
accent-tinted segments/meter color) · `.transparent` (terminal background,
|
||||
no status bg fill) · `.showHookStatus` · `.compactThinkingLevel` (default
|
||||
true). Plus `symbolPreset` at top level (`unicode` `nerd` `ascii` — segment
|
||||
glyphs follow it).
|
||||
|
||||
## Fleet configuration (2026-10-18)
|
||||
|
||||
- Shape `band`: one merged status row. Left group: `session_name`→working
|
||||
row (skipped), `vim`, `mode`, `hostname`, `path`, `git` (no branch text —
|
||||
worktree branches are autogenerated names), `pr`. Right group (array order
|
||||
= paint order, so the last entry hugs the screen edge): `model`, `cost`,
|
||||
`context_pct`, `time_spent` — `context_pct` hoists out of the run to paint
|
||||
the labeled inline meter (`60% ——— × 200K`) between the groups under
|
||||
`contextLine: embedded`.
|
||||
- Deliberately cut: `token_rate` (working-row readout covers it), `time`
|
||||
(panel clock), `cache_*` (noise), `context_total` (implied by the meter),
|
||||
`subagents` (live badge supersedes it), `session`, `token_in`/`token_out`
|
||||
(cumulative totals are in `/session` anyway).
|
||||
- `models.yml`: frank-archon's display `name` slimmed to `"frank-archon"`
|
||||
(endpoint suffix dropped); frank-dragoon/frank-zealot keep their endpoint
|
||||
suffixes. `name:` is free-form display, `id:` is the wiring — renaming ids
|
||||
is the cutover procedure, see [Pi Models](/pi/models.md).
|
||||
|
||||
## Audit log
|
||||
|
||||
2026-10-18 full-source re-audit corrected the first pass of this page:
|
||||
|
||||
- ~~claude shape's top rule is the context meter~~ — **false**. The
|
||||
meter code path runs only for `box`/`band`; claude/rule/pi/borderless/
|
||||
field/rail rules are constant session-accent fillers. (Earlier reading
|
||||
mistook the accent rule for a meter.)
|
||||
- ~~working-row composer-bar variant is "Tern-only"~~ — **false**; the
|
||||
tok/s readout is the `composer.tokenRate` option (default false), title
|
||||
placement is composer chrome.
|
||||
- ~~`segmentOptions` gated to `preset: custom`~~ — **false**; options merge
|
||||
under every preset, only the segment *arrays* are gated.
|
||||
- ~~`mode` covers yolo~~ — **false**; states are Plan/Prewalk/Goal/Vibe/Loop.
|
||||
- `contextLine` "(box composer only)" — the *bundle description* is wrong;
|
||||
band honors it too (verified live: `off` plain rule, `percentage` rule
|
||||
meter, `embedded` inline meter, screenshots + code).
|
||||
@@ -1,97 +0,0 @@
|
||||
---
|
||||
type: reference
|
||||
title: OMP Subagent Limits & Fan-out Policy
|
||||
description: The live caps on omp subagents — concurrency 2, no nested spawns, per-endpoint in-flight ceilings, 30-min runtime, soft request budget, and the isolated-workspace policy; includes the maxRecursionDepth=0 trap.
|
||||
tags:
|
||||
- omp
|
||||
- subagents
|
||||
- config
|
||||
- fleet
|
||||
timestamp: 2026-10-19
|
||||
---
|
||||
|
||||
# OMP Subagent Limits & Fan-out Policy
|
||||
|
||||
Enforced caps on subagents spawned through the `task` tool / eval `agent()`+`workpool()`
|
||||
from this workstation (config root `agent/config.yml`, machine-live tier — the live-sync
|
||||
heartbeat commits it). Set 2026-10-19; values verified against the live config and the
|
||||
enforcement code in the installed bundle (`@oh-my-pi/pi-coding-agent/dist/cli.js`).
|
||||
|
||||
## The caps in force
|
||||
|
||||
| Key | Value | Default | Effect |
|
||||
|---|---|---|---|
|
||||
| `task.maxConcurrency` | 2 | 32 | Session-scoped semaphore; excess spawns queue, never drop. |
|
||||
| `task.maxRecursionDepth` | 1 | 2 | Subagents cannot spawn their own subagents. See depth semantics. |
|
||||
| `task.maxRuntimeMs` | 1800000 | 0 (off) | Hard 30-min wall clock per subagent; overrun = `aborted`. |
|
||||
| `task.softRequestBudget` | 120 | 200 | Wrap-up notice at 120 assistant requests; force-stopped to yield at 180 (1.5×). |
|
||||
| `task.agentIdleTtlMs` | 420000 | same | Finished subagents parked to disk after 7 min idle (revivable via `agent://`). |
|
||||
| `task.enableEffort` | false | false | Per-spawn `effort` hint hidden from the schema. |
|
||||
| `task.isolation.enabled` | true | false | `isolated: true` spawns run in a copy of the checkout; only successful patches land (merge=patch, apply). Opt-in per spawn. |
|
||||
| `task.completionProbe` | false | true | No periodic completeness side-requests into running subagents. |
|
||||
| `tools.maxTimeout` | 600 | 0 (off) | No agent may request a tool timeout above 10 min; kills `timeout: 0` runaways. |
|
||||
| `providers.maxInFlightRequests` | see below | {} (unlimited) | Per-provider ceiling on concurrent LLM requests, shared across local omp processes. |
|
||||
|
||||
## Depth semantics — never set `maxRecursionDepth: 0`
|
||||
|
||||
Bundle predicate (`U_`): a session at `taskDepth` *s* keeps the `task` tool iff
|
||||
`n < 0 || s < n` where `n = maxRecursionDepth`. The preflight repeats the check
|
||||
(`Cannot spawn another agent at task depth s; maximum depth is n`).
|
||||
|
||||
- `n = 1` → main (depth 0) spawns; children (depth 1) have `task` stripped. **This is
|
||||
"no nested subagents".**
|
||||
- `n = 0` → `0 < 0` fails → **not even the main session can spawn anything.** Don't.
|
||||
- `n < 0` → cap disabled.
|
||||
|
||||
## Per-endpoint in-flight ceilings
|
||||
|
||||
```yaml
|
||||
providers:
|
||||
maxInFlightRequests:
|
||||
"llamacpp (dankserver)": 3 # main session + up to 2 task/reviewer subagents
|
||||
"llamacpp (dankclaw)": 2 # frank-dragoon: security-reviewer + fallbacks
|
||||
"llamacpp (dankclaw-3090)": 3 # frank-zealot: scout/sonic/librarian/designer + smol/tiny/plan/commit/vision roles
|
||||
```
|
||||
|
||||
- Keys are **provider ids** = the quoted block labels in `agent/models.yml`
|
||||
(one provider per host:port). The consumer does a flat map lookup by provider id;
|
||||
absent or ≤0 = unlimited, otherwise clamped to ≥1.
|
||||
- Scope is **per machine, per config root**: it bounds what *this workstation's* omp
|
||||
processes put on each endpoint. Other workstations, OpenWebUI, and any non-omp
|
||||
client are not counted. Requests past the ceiling queue, never fail.
|
||||
- `web/searxng` intentionally uncapped.
|
||||
|
||||
## Isolation note
|
||||
|
||||
`task.isolation.enabled: true` makes the per-spawn `isolated` flag available — it is
|
||||
**opt-in per spawn**, not a blanket sandbox. Requires a git repo; unavailable in plan
|
||||
mode; baseline snapshot capped at 1 GiB; backends resolve via `isolation.backend: auto`
|
||||
(overlayfs/reflink/rcopy chain on this box). Given *the checkout is the deployment*,
|
||||
prefer `isolated: true` for any subagent that edits tracked files.
|
||||
|
||||
## Deliberately not set
|
||||
|
||||
- `bash.gitGuard` — offered 2026-10-19, declined; destructive-git protection stays opt-in.
|
||||
- `task.disabledAgents` — no bundled agent type warrants a ban.
|
||||
- `task.agentAccountPools`, `tier.subagent` — no-op against keyless local endpoints.
|
||||
- `PI_TASK_MAX_OUTPUT_BYTES` / `PI_TASK_MAX_OUTPUT_LINES` — 500 KB / 5000 line defaults are sane.
|
||||
- `before_subagent_spawn` hook — programmable spawn policy; revisit if these caps prove insufficient.
|
||||
|
||||
## Verification
|
||||
|
||||
`cfg://task`, `cfg://providers/maxInFlightRequests` reflect all rows above; persisted
|
||||
copies in `agent/config.yml`. Depth semantics confirmed against the shipped bundle, not
|
||||
just the setting description.
|
||||
|
||||
# Citations
|
||||
|
||||
- `agent/config.yml` (live config, this repo)
|
||||
- `agent/models.yml` — provider id block labels
|
||||
- `@oh-my-pi/pi-coding-agent/dist/cli.js` — `U_` depth predicate, in-flight map lookup
|
||||
- omp docs: `omp://tools/task.md` § Limits & Caps
|
||||
|
||||
# See Also
|
||||
|
||||
- [/pi/statusline.md](/pi/statusline.md) — the omp-era bundle-audit page pattern this page follows
|
||||
- [/pi/packages/pi-subagents.md](/pi/packages/pi-subagents.md) — retired pi-era subagent system (historical)
|
||||
- [/system/index.md](/system/index.md) — fleet endpoints these ceilings target
|
||||
Reference in new issue
Block a user