Skip to content

docs(pi): describe handler folder layout #6367

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
BillLeoutsakosvl346 wants to merge 4 commits into from
+36 −0
Closed

docs(pi): describe handler folder layout #6367

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
62d20ff
docs(pi): describe handler folder layout
Aug 7, 2026
cc38817
Pi Babysit: address PR #6367 feedback
Aug 7, 2026
a685801
Pi: In apps/sim/executor/handlers/pi/README.md only, convert the fold…
Aug 7, 2026
d411532
Pi: Without re-reading the file first, state from memory the exact tw…
Aug 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions apps/sim/executor/handlers/pi/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# PI Handler

@BillLeoutsakosvl346 BillLeoutsakosvl346 Aug 7, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Use Pi rather than PI here. The registered block is named “Pi Coding Agent,” and the implementation consistently uses “Pi” for both the product and SDK.


Implements the PI block executor. Each sub-mode delegates to a dedicated backend while sharing common infrastructure.

## Folder layout

| Path | Responsibility |
| --- | --- |
| `pi-handler.ts` | Single dispatcher — reads the block's mode and routes to the correct backend |
| `core/backend.ts` | Backend contracts — all run-params types, `PiRunContext`, `PiRunResult`, and `PiBackendRun` |
| `core/context.ts` | Skills-resolution and memory helpers (`resolvePiSkills`, `loadPiMemory`, `buildPiPrompt`, `appendPiMemory`) |
| `core/events.ts` | Streaming event helpers |
| `core/keys.ts` | API-key resolution utilities |
| `core/pi-sdk.ts` | Thin wrapper around the PI SDK client |

@BillLeoutsakosvl346 BillLeoutsakosvl346 Aug 7, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not just a thin SDK client wrapper: it dynamically loads the SDK, converts backend-neutral tool specs, creates the model runtime, resolves models, and builds the sealed resource loader. Please describe those SDK integration utilities more accurately; also capitalize the name as Pi SDK.

| `core/redaction.ts` | Secret redaction for logs and responses |
| `cloud/shared.ts` | Shared GitHub and sandbox utilities (repo helpers, polling, etc.) |

@BillLeoutsakosvl346 BillLeoutsakosvl346 Aug 7, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cloud/shared.ts does not implement polling or GitHub API helpers. It primarily contains sandbox paths/timeouts, clone/finalization support, shell scripts, abort racing, marker parsing, and git-secret scrubbing. Polling is implemented under cloud/babysit/, so the parenthetical should be corrected.

| `cloud/github-pr.ts` | Low-level GitHub PR API wrappers |
| `cloud/authoring/backend.ts` | Create PR and Update PR implementation |
| `cloud/review/backend.ts` | Review Code implementation |
| `cloud/review/tools.ts` | Tool definitions injected into the review agent |
| `cloud/review/tools-script.ts` | Script loaded by the review tools |
| `cloud/babysit/backend.ts` | PR review / check continuation (babysit mode) |
| `cloud/babysit/github.ts` | GitHub status/check polling helpers |
| `cloud/babysit/round.ts` | Single babysit iteration logic |

@BillLeoutsakosvl346 BillLeoutsakosvl346 Aug 7, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

round.ts defines and validates the agent-authored round decision file; it does not implement a babysit iteration. The iteration and finalization flow lives in cloud/babysit/backend.ts. A responsibility such as “Babysit round decision schema and parser” would match this file.

| `local/backend.ts` | Local Dev mode — SSH-connected local machine |
| `local/sim-tools.ts` | Sim-side tool implementations |
| `local/ssh-tools.ts` | SSH tool implementations |
| `search/tool.ts` | Search tool definition |
| `search/normalize.ts` | Result normalisation |
| `search/extension-source.ts` | Extension-based source adapter |

## Dispatch flow

`pi-handler.ts` is the sole entry point registered in the executor. It inspects the block's `mode` field and calls the matching backend's `run()` method. All backends receive a typed `PiRunContext` (from `core/backend.ts`) and stream incremental events back through `core/events.ts`.

@BillLeoutsakosvl346 BillLeoutsakosvl346 Aug 7, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The backends do not expose run() methods. They are plain PiBackendRun functions (runCloudPi, runCloudBranchPi, runCloudReviewPi, and runLocalPi) passed to runPi. Please describe the dispatcher as invoking the matching backend function so the architectural contract is accurate.


<!-- memory-probe: Path | Responsibility -->

@cursor cursor Bot Aug 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stray memory probe comment

Low Severity

A memory-probe HTML comment, mirroring the table header, was inadvertently left at the end of the README.md. It appears to be temporary scaffolding, as it's not part of the intended documentation and isn't found elsewhere in the repository.

Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit d411532. Configure here.

Loading