Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

extensions/pipi/README.md

Raw
Rendered preview
pipi

pipi

Delegate one task to a native child Pi session, optionally using reusable agents and structured output.

Demo: delegate a read-only review and expand its result, configuration, and child-session locator

Use in Pi

Ask Pi to delegate a bounded task through pipi. No preset required; child inherits parent model and active tools unless overridden.

{"prompt":"Inspect auth flow and report risks","tools":["read","grep","find"]}

Calls block until completion; concurrent calls run independently. Cancellation stops child work, including nested pipi calls. Results include outcome, native final assistant message or submitted JSON, session ID/file, new-work usage and effective config. Use returned sessionId or sessionFile as sessionId to continue; fork:true forks natively instead. Without a session ID, fork:true forks parent history. Continuation uses current preset and call config.

Reusable agents

Under Pi agent directory, create pipi/agents/<name>/config.json with a required description and optional call configuration. Optional instructions.md adds plain Markdown instructions as sections.pipi_agent. Folder name is unique agent name; lowercase ASCII recommended. No startup directory creation or registration needed. Discovery refreshes before each parent run; directories without config are ignored, invalid presets are excluded with diagnostics, explicit unavailable names fail.

{"description":"Investigate repository behavior without editing","tools":["read","grep","find"]}

Call {"agent":"reviewer","prompt":"Review authentication"} after saving that config under pipi/agents/reviewer/config.json. Explicit call values replace preset fields; resource path lists add to preset paths. Call tier overrides preset model; explicit call model wins over tier. sections.pipi_agent replaces preset instructions. Prefer improving existing presets over adding near-duplicates.

Structured output

{"prompt":"Count matching files","outputSchema":{"type":"integer"}}

Schema enables a child-local submission tool. Last valid submission during this call wins; transcript submissions from previous calls never count. One reminder follows natural completion without submission; second completion fails explicitly. Errors or cancellation remain errors or cancellation even after valid submission. Omitted schema inherits preset; object replaces; null disables. Submission requirement survives forceSystemPrompt.

Configuration and resources

Native images input accepts image content blocks alongside prompt. Call options: model as provider/model, tier, thinkingLevel, tools, extensions, skills, prompts, flags, cwd, noExtensions, noSkills, noPromptTemplates, noContextFiles. Prompt controls: sections, customPrompt, appendSystemPrompt, forceSystemPrompt. Custom prompts have native guidance-loss semantics; default retains normal Pi guidance. Tools use native plain replacement and +/- modification syntax. Call-local resource paths are additive. Resource selectors retain native +path/-path/!pattern semantics for inherited and call-local resources. Relative call paths resolve from parent workspace; inherited CLI paths keep their original startup location. Dynamic extensions are ordinary files under pipi/dynamic/<name>/index.ts; discover their relative entry paths before loading explicitly with extensions. Start with one entry file; grow only when needed.

User recommendations configure tiny/small/medium/large/huge through pipi.modelTiers and optional provider-specific pipi.providerModelTiers. Each tier can specify model (provider/model or null for inherited model), thinkingLevel, and selection instructions; provider-specific fields override base recommendations. Recommendations appear in orchestrator context and do not restrict explicit model selection.

{"pipi":{"modelTiers":{"small":{"model":"openai-codex/gpt-6-luna","thinkingLevel":"high","instructions":"Few local decisions; low consequence."}}}}

Explicit model wins; omitted model/tier inherits parent on fresh calls, native saved model on continuation. An unconfigured tier uses inherited model with its default recommended thinking level; unknown explicit models fail without fallback graphs.

Boundaries

Child resources are rediscovered for child workspace, respecting trust. Parent file-based resources, including hook-only permission extensions, remain available across workspace changes. Runtime-only extensions, programmatic flags, runtime auth overrides and provider-context prompt transforms cannot be introspected exactly. Requested/effective config and diagnostics expose mismatches rather than promising exact cloning. No per-child environment override. Child sessions persist using native storage; complete transcripts are accessible through returned locator. New and forked child sessions are named PiPi · <agent, tier, or model> · <prompt>, so pi --resume lists them recognisably under their parent. Result usage counts only new work persisted in that child session, excluding persisted descendant sessions; unpersisted provider work is not observable. A persisted child session is its own native usage ledger, so the parent tool result carries no native usage and parent session totals exclude delegated work. Human previews and model-facing text are bounded; structured result retains native final message. Use separate sessions or native forks for concurrent work instead of competing writers on one continued session.

Installation

Reference

Setting names

Setting Environment
pipi
pipi.timeoutMs PIPI_TIMEOUT_MS

Setting values

Setting Default Valid values Purpose
pipi.timeoutMs 14400000 Integer 1000–2147483647 Call deadline: Wall-clock deadline per pipi call; an expired deadline aborts the child and preserves its session for continuation.

Object fields

Paths below describe fields inside their parent settings object, not literal top-level keys. [] denotes an array element; see setup above for examples and defaults.

Field
pipi.modelTiers
pipi.providerModelTiers
<img src="assets/banner.svg" alt="pipi" height="70">

# pipi

Delegate one task to a native child Pi session, optionally using reusable agents and structured output.

![Demo: delegate a read-only review and expand its result, configuration, and child-session locator](assets/demo.gif)

## Use in Pi

Ask Pi to delegate a bounded task through `pipi`.
No preset required; child inherits parent model and active tools unless overridden.

```json
{"prompt":"Inspect auth flow and report risks","tools":["read","grep","find"]}
```

Calls block until completion; concurrent calls run independently.
Cancellation stops child work, including nested pipi calls.
Results include outcome, native final assistant message or submitted JSON, session ID/file, new-work usage and effective config.
Use returned `sessionId` or `sessionFile` as `sessionId` to continue; `fork:true` forks natively instead.
Without a session ID, `fork:true` forks parent history.
Continuation uses current preset and call config.

### Reusable agents

Under Pi agent directory, create `pipi/agents/<name>/config.json` with a required `description` and optional call configuration.
Optional `instructions.md` adds plain Markdown instructions as `sections.pipi_agent`.
Folder name is unique agent name; lowercase ASCII recommended.
No startup directory creation or registration needed.
Discovery refreshes before each parent run; directories without config are ignored, invalid presets are excluded with diagnostics, explicit unavailable names fail.

```json
{"description":"Investigate repository behavior without editing","tools":["read","grep","find"]}
```

Call `{"agent":"reviewer","prompt":"Review authentication"}` after saving that config under `pipi/agents/reviewer/config.json`.
Explicit call values replace preset fields; resource path lists add to preset paths.
Call tier overrides preset model; explicit call model wins over tier.
`sections.pipi_agent` replaces preset instructions.
Prefer improving existing presets over adding near-duplicates.

### Structured output

```json
{"prompt":"Count matching files","outputSchema":{"type":"integer"}}
```

Schema enables a child-local submission tool.
Last valid submission during this call wins; transcript submissions from previous calls never count.
One reminder follows natural completion without submission; second completion fails explicitly.
Errors or cancellation remain errors or cancellation even after valid submission.
Omitted schema inherits preset; object replaces; null disables.
Submission requirement survives `forceSystemPrompt`.

### Configuration and resources

Native `images` input accepts image content blocks alongside `prompt`.
Call options: `model` as `provider/model`, `tier`, `thinkingLevel`, `tools`, `extensions`, `skills`, `prompts`, `flags`, `cwd`, `noExtensions`, `noSkills`, `noPromptTemplates`, `noContextFiles`.
Prompt controls: `sections`, `customPrompt`, `appendSystemPrompt`, `forceSystemPrompt`.
Custom prompts have native guidance-loss semantics; default retains normal Pi guidance.
Tools use native plain replacement and +/- modification syntax.
Call-local resource paths are additive.
Resource selectors retain native +path/-path/!pattern semantics for inherited and call-local resources.
Relative call paths resolve from parent workspace; inherited CLI paths keep their original startup location.
Dynamic extensions are ordinary files under `pipi/dynamic/<name>/index.ts`; discover their relative entry paths before loading explicitly with `extensions`.
Start with one entry file; grow only when needed.

User recommendations configure tiny/small/medium/large/huge through `pipi.modelTiers` and optional provider-specific `pipi.providerModelTiers`.
Each tier can specify `model` (`provider/model` or null for inherited model), `thinkingLevel`, and selection `instructions`; provider-specific fields override base recommendations.
Recommendations appear in orchestrator context and do not restrict explicit model selection.

```json
{"pipi":{"modelTiers":{"small":{"model":"openai-codex/gpt-6-luna","thinkingLevel":"high","instructions":"Few local decisions; low consequence."}}}}
```
Explicit model wins; omitted model/tier inherits parent on fresh calls, native saved model on continuation.
An unconfigured tier uses inherited model with its default recommended thinking level; unknown explicit models fail without fallback graphs.

### Boundaries

Child resources are rediscovered for child workspace, respecting trust.
Parent file-based resources, including hook-only permission extensions, remain available across workspace changes.
Runtime-only extensions, programmatic flags, runtime auth overrides and provider-context prompt transforms cannot be introspected exactly.
Requested/effective config and diagnostics expose mismatches rather than promising exact cloning.
No per-child environment override.
Child sessions persist using native storage; complete transcripts are accessible through returned locator.
New and forked child sessions are named `PiPi · <agent, tier, or model> · <prompt>`, so `pi --resume` lists them recognisably under their parent.
Result usage counts only new work persisted in that child session, excluding persisted descendant sessions; unpersisted provider work is not observable.
A persisted child session is its own native usage ledger, so the parent tool result carries no native usage and parent session totals exclude delegated work.
Human previews and model-facing text are bounded; structured result retains native final message.
Use separate sessions or native forks for concurrent work instead of competing writers on one continued session.

[Installation](../../README.md#install)

## Reference

<!-- config:start -->
### Setting names

| Setting | Environment |
| --- | --- |
| `pipi` |   |
| `pipi.timeoutMs` | `PIPI_TIMEOUT_MS` |

#### Setting values

| Setting | Default | Valid values | Purpose |
| --- | --- | --- | --- |
| `pipi.timeoutMs` | `14400000` | Integer 1000–2147483647 | Call deadline: Wall-clock deadline per pipi call; an expired deadline aborts the child and preserves its session for continuation. |

#### Object fields

Paths below describe fields inside their parent settings object, not literal top-level keys.
`[]` denotes an array element; see setup above for examples and defaults.

| Field |
| --- |
| `pipi.modelTiers` |
| `pipi.providerModelTiers` |
<!-- config:end -->