pi-oracle 0.3.0 → 0.3.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +18 -0
- package/README.md +156 -105
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,23 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.3.2 - 2026-04-08
|
|
4
|
+
|
|
5
|
+
### Changed
|
|
6
|
+
- README now lists the available oracle preset ids directly, so users can choose `defaults.preset` values without having to inspect source files
|
|
7
|
+
|
|
8
|
+
### Fixed
|
|
9
|
+
- closed a README usability gap where preset-based configuration was documented without actually enumerating the shipped preset ids
|
|
10
|
+
- oracle sanity coverage now verifies that the README lists every preset from the canonical `ORACLE_SUBMIT_PRESETS` registry
|
|
11
|
+
|
|
12
|
+
## 0.3.1 - 2026-04-08
|
|
13
|
+
|
|
14
|
+
### Changed
|
|
15
|
+
- rewrote the GitHub-facing README to work better as a landing page, with a sharper value prop, clearer install guidance, a real quickstart, example requests, a minimal config example, troubleshooting, and a high-level flow diagram
|
|
16
|
+
- README now explains when to use `pi-oracle`, when not to use it first, where outputs live, and what to do if a wake-up is missed
|
|
17
|
+
|
|
18
|
+
### Fixed
|
|
19
|
+
- removed the stale legacy model wording from the README example flow and aligned user-facing setup docs with the preset-based configuration model
|
|
20
|
+
|
|
3
21
|
## 0.3.0 - 2026-04-08
|
|
4
22
|
|
|
5
23
|
### Changed
|
package/README.md
CHANGED
|
@@ -1,153 +1,204 @@
|
|
|
1
1
|
# pi-oracle
|
|
2
2
|
|
|
3
|
-
`pi-oracle` is a `pi`
|
|
3
|
+
`pi-oracle` is a `pi` package that lets the agent hand off difficult, long-running tasks to ChatGPT.com through the web app instead of the API.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
-
|
|
5
|
+
Use it when you want:
|
|
6
|
+
- your real ChatGPT account
|
|
7
7
|
- web-model behavior instead of API usage
|
|
8
|
-
- large
|
|
9
|
-
- async background execution
|
|
10
|
-
-
|
|
11
|
-
- legacy project-scoped jobs created before that change remain readable via project status/read commands, but skip best-effort wake-up routing after upgrade
|
|
8
|
+
- large repo/context uploads
|
|
9
|
+
- async background execution
|
|
10
|
+
- durable saved responses/artifacts plus best-effort wake-ups back into `pi`
|
|
12
11
|
|
|
13
|
-
Normal oracle jobs run in an isolated browser profile, not
|
|
12
|
+
Normal oracle jobs run in an isolated browser profile, not your active Chrome window.
|
|
14
13
|
|
|
15
|
-
Status: experimental public beta
|
|
14
|
+
> Status: experimental public beta. Validated primarily on macOS with Google Chrome and `pi` 0.65.0+.
|
|
16
15
|
|
|
17
|
-
|
|
18
|
-
This package intentionally uses the current `session_start`-based session lifecycle and does not ship backward-compatibility shims for removed extension events.
|
|
16
|
+
## When to use it
|
|
19
17
|
|
|
20
|
-
|
|
18
|
+
Use `pi-oracle` for:
|
|
19
|
+
- big code reviews of a repo or pending changes
|
|
20
|
+
- architectural or migration analysis that benefits from a large uploaded archive
|
|
21
|
+
- long-running prompts that may take minutes to finish
|
|
22
|
+
- follow-up questions in the same ChatGPT thread later
|
|
21
23
|
|
|
22
|
-
|
|
23
|
-
-
|
|
24
|
-
|
|
25
|
-
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
24
|
+
Do not reach for it first for:
|
|
25
|
+
- normal short coding tasks that `pi` can handle directly
|
|
26
|
+
- workflows that must never upload project archives to ChatGPT.com
|
|
27
|
+
- environments outside the current supported setup
|
|
28
|
+
|
|
29
|
+
## Install
|
|
30
|
+
|
|
31
|
+
npm:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
pi install npm:pi-oracle
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
GitHub:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
pi install https://github.com/fitchmultz/pi-oracle
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Quickstart
|
|
44
|
+
|
|
45
|
+
1. Make sure ChatGPT already works in your local Chrome profile.
|
|
46
|
+
2. Make sure these are installed: Google Chrome, `agent-browser`, `tar`, and `zstd`.
|
|
47
|
+
3. Optional: create `~/.pi/agent/extensions/oracle.json` if you want non-default settings.
|
|
48
|
+
4. Run `/oracle-auth`.
|
|
49
|
+
5. Run `/oracle Review the current pending changes. Include the whole repo unless a narrower archive is clearly better.`
|
|
50
|
+
6. Wait for a best-effort wake-up, or check `/oracle-status`.
|
|
51
|
+
|
|
52
|
+
If you miss the wake-up, the result is still saved durably in the oracle job directory and can be read later.
|
|
53
|
+
|
|
54
|
+
## Example requests
|
|
55
|
+
|
|
56
|
+
```text
|
|
57
|
+
/oracle Review the current pending changes. Include the whole repo unless a narrower archive is clearly better. Give me a prioritized code review with concrete fixes.
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
```text
|
|
61
|
+
/oracle Read the codebase and explain the highest-risk auth/session failure modes, including what to test before shipping.
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## High-level flow
|
|
65
|
+
|
|
66
|
+
```mermaid
|
|
67
|
+
flowchart LR
|
|
68
|
+
A["/oracle request"] --> B["Agent gathers repo context"]
|
|
69
|
+
B --> C["oracle_submit builds archive"]
|
|
70
|
+
C --> D["Detached worker starts isolated ChatGPT runtime"]
|
|
71
|
+
D --> E["Archive + prompt sent to ChatGPT.com"]
|
|
72
|
+
E --> F["Response/artifacts saved under oracle job dir"]
|
|
73
|
+
F --> G["Best-effort wake-up to matching pi session"]
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
If concurrency is full, the job is queued and starts automatically later.
|
|
77
|
+
|
|
78
|
+
## What the package adds
|
|
79
|
+
|
|
80
|
+
User-facing commands:
|
|
81
|
+
- `/oracle <request>` — prompt template that tells the agent to gather context and dispatch an oracle job
|
|
82
|
+
- `/oracle-auth` — sync ChatGPT cookies from your real Chrome profile into the isolated oracle auth profile
|
|
83
|
+
- `/oracle-status [job-id]` — inspect job status
|
|
84
|
+
- `/oracle-cancel [job-id]` — cancel queued or active job
|
|
85
|
+
- `/oracle-clean <job-id|all>` — remove temp files for terminal jobs
|
|
86
|
+
|
|
87
|
+
Agent-facing tools:
|
|
29
88
|
- `oracle_submit`
|
|
30
89
|
- `oracle_read`
|
|
31
90
|
- `oracle_cancel`
|
|
32
91
|
|
|
33
|
-
|
|
34
|
-
1. gathers a project archive
|
|
35
|
-
2. if runtime capacity is full, persists as `queued` and starts automatically later
|
|
36
|
-
3. otherwise opens ChatGPT in an isolated runtime profile
|
|
37
|
-
4. uploads the archive and sends the prompt
|
|
38
|
-
5. waits in the background
|
|
39
|
-
6. persists the response and any artifacts under the oracle job directory (`${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/` by default)
|
|
40
|
-
- old terminal jobs are later pruned according to cleanup retention settings
|
|
41
|
-
- when directory inputs are expanded, project archives automatically skip common bulky generated caches and top-level build outputs such as `node_modules/`, `target/`, virtualenv caches, coverage outputs, and `dist/`/`build/`/`out/`, unless you explicitly pass those directories
|
|
42
|
-
- whole-repo archive defaults also skip obvious credentials/private data such as `.env` files, key material, credential dotfiles, local database files, and root `secrets/` directories unless you explicitly pass them
|
|
43
|
-
- if a whole-repo archive is still too large after default exclusions, submit automatically prunes the largest nested directories with generic generated-output names like `build/`, `dist/`, `out/`, `coverage/`, and `tmp/` outside obvious source roots like `src/` and `lib/`, and successful submissions report what was pruned
|
|
44
|
-
7. persists the response/artifacts durably in oracle job state and issues best-effort wake-ups to whichever matching `pi` session is currently live
|
|
45
|
-
|
|
46
|
-
## Example
|
|
92
|
+
## Minimal config
|
|
47
93
|
|
|
48
|
-
|
|
49
|
-
|
|
94
|
+
Most users can start with the packaged defaults and only set the Chrome profile if needed.
|
|
95
|
+
|
|
96
|
+
`~/.pi/agent/extensions/oracle.json`
|
|
97
|
+
|
|
98
|
+
```json
|
|
99
|
+
{
|
|
100
|
+
"defaults": {
|
|
101
|
+
"preset": "<preset id from ORACLE_SUBMIT_PRESETS>"
|
|
102
|
+
},
|
|
103
|
+
"auth": {
|
|
104
|
+
"chromeProfile": "Default"
|
|
105
|
+
}
|
|
106
|
+
}
|
|
50
107
|
```
|
|
51
108
|
|
|
52
|
-
|
|
109
|
+
Notes:
|
|
110
|
+
- `defaults.preset` is the default ChatGPT model preset for oracle jobs.
|
|
111
|
+
- The canonical preset ids live in `extensions/oracle/lib/config.ts`.
|
|
112
|
+
- If the packaged default is fine, you can omit `defaults.preset` entirely.
|
|
113
|
+
- You usually do not need to set browser paths unless auto-detection fails.
|
|
114
|
+
|
|
115
|
+
## Available presets
|
|
116
|
+
|
|
117
|
+
| Preset id | Description |
|
|
118
|
+
| --- | --- |
|
|
119
|
+
| `pro_standard` | Pro - Standard |
|
|
120
|
+
| `pro_extended` | Pro - Extended |
|
|
121
|
+
| `thinking_light` | Thinking - Light |
|
|
122
|
+
| `thinking_standard` | Thinking - Standard |
|
|
123
|
+
| `thinking_extended` | Thinking - Extended |
|
|
124
|
+
| `thinking_heavy` | Thinking - Heavy |
|
|
125
|
+
| `instant` | Instant |
|
|
126
|
+
| `instant_auto_switch` | Instant - Auto-switch to Thinking Enabled |
|
|
127
|
+
|
|
128
|
+
Other useful settings:
|
|
129
|
+
- `browser.runMode`
|
|
130
|
+
- `browser.args`
|
|
131
|
+
- `browser.authSeedProfileDir`
|
|
132
|
+
- `browser.runtimeProfilesDir`
|
|
133
|
+
- `cleanup.completeJobRetentionMs`
|
|
134
|
+
- `cleanup.failedJobRetentionMs`
|
|
53
135
|
|
|
54
|
-
|
|
55
|
-
- paying API costs for every long review
|
|
56
|
-
- blocking the agent for 10–90 minutes
|
|
57
|
-
- stealing focus from the user’s active browser session
|
|
136
|
+
Project config should only override safe, non-privileged settings.
|
|
58
137
|
|
|
59
|
-
##
|
|
138
|
+
## What happens to outputs
|
|
60
139
|
|
|
61
|
-
|
|
62
|
-
-
|
|
63
|
-
-
|
|
64
|
-
-
|
|
65
|
-
- isolated auth seed profile + per-job runtime profile clones
|
|
66
|
-
- concurrent jobs across different projects/sessions
|
|
67
|
-
- workerless queued jobs when the global concurrency limit is full
|
|
68
|
-
- same-conversation exclusion for follow-ups
|
|
69
|
-
- plain-text responses
|
|
70
|
-
- artifact capture, including multi-artifact runs
|
|
71
|
-
|
|
72
|
-
Not promised yet:
|
|
73
|
-
- cross-platform support
|
|
74
|
-
- immunity to future ChatGPT UI changes
|
|
75
|
-
- fully polished partial-artifact terminal semantics
|
|
140
|
+
- Jobs persist their response and any artifacts under `${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/` by default.
|
|
141
|
+
- Jobs can queue automatically if runtime capacity is full.
|
|
142
|
+
- Completion delivery into `pi` is best-effort wake-up based.
|
|
143
|
+
- If you miss the wake-up, use `oracle_read(jobId)` or `/oracle-status`.
|
|
76
144
|
|
|
77
145
|
## Requirements
|
|
78
146
|
|
|
79
147
|
- macOS
|
|
80
148
|
- Google Chrome installed
|
|
81
149
|
- ChatGPT already signed into a local Chrome profile
|
|
82
|
-
- `pi` 0.65.0 or newer
|
|
150
|
+
- `pi` 0.65.0 or newer
|
|
83
151
|
- `agent-browser` available on the machine
|
|
84
152
|
- `tar` and `zstd` available
|
|
85
153
|
|
|
86
|
-
##
|
|
154
|
+
## Troubleshooting
|
|
87
155
|
|
|
88
|
-
|
|
156
|
+
### `/oracle-auth` fails or says login is required
|
|
89
157
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
158
|
+
- Make sure ChatGPT works in the same local Chrome profile you configured.
|
|
159
|
+
- Re-run `/oracle-auth`.
|
|
160
|
+
- If ChatGPT is half-logged-in or challenge flow state looks weird, finish the login/challenge in the headed auth browser and retry.
|
|
93
161
|
|
|
94
|
-
|
|
162
|
+
### You hit a challenge / verification page
|
|
95
163
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
```
|
|
164
|
+
- Solve it in the auth/bootstrap browser if prompted.
|
|
165
|
+
- Then re-run `/oracle-auth` before submitting jobs again.
|
|
99
166
|
|
|
100
|
-
|
|
167
|
+
### You see "Oracle requires a persisted pi session"
|
|
101
168
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
3. Run `/oracle-auth`.
|
|
105
|
-
4. Run a tiny `/oracle` smoke test.
|
|
169
|
+
- Do not run oracle from `pi --no-session`.
|
|
170
|
+
- Start a normal persisted `pi` session, then use `/oracle` again.
|
|
106
171
|
|
|
107
|
-
|
|
172
|
+
### A job finished but no wake-up arrived
|
|
108
173
|
|
|
109
|
-
|
|
110
|
-
-
|
|
111
|
-
- project: `.pi/extensions/oracle.json`
|
|
174
|
+
- Use `/oracle-status [job-id]` or `oracle_read(jobId)`.
|
|
175
|
+
- Results are still saved on disk even if the reminder turn does not land.
|
|
112
176
|
|
|
113
|
-
|
|
114
|
-
- `defaults.preset`
|
|
115
|
-
- `browser.args`
|
|
116
|
-
- `browser.executablePath`
|
|
117
|
-
- `browser.authSeedProfileDir`
|
|
118
|
-
- `browser.runtimeProfilesDir`
|
|
119
|
-
- `auth.chromeProfile`
|
|
120
|
-
- `auth.chromeCookiePath`
|
|
121
|
-
- `cleanup.completeJobRetentionMs`
|
|
122
|
-
- `cleanup.failedJobRetentionMs`
|
|
177
|
+
### `agent-browser`, `tar`, or `zstd` is missing
|
|
123
178
|
|
|
124
|
-
|
|
179
|
+
- Install the missing local dependency and rerun the command.
|
|
180
|
+
|
|
181
|
+
### Auto-detection picked the wrong Chrome profile
|
|
182
|
+
|
|
183
|
+
- Set `auth.chromeProfile` in `~/.pi/agent/extensions/oracle.json`.
|
|
184
|
+
- Re-run `/oracle-auth`.
|
|
185
|
+
|
|
186
|
+
### You want more details about a failed run
|
|
187
|
+
|
|
188
|
+
- Inspect the job directory under `${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/`.
|
|
189
|
+
- The worker log and captured diagnostics are stored there.
|
|
190
|
+
|
|
191
|
+
## Detailed docs
|
|
125
192
|
|
|
126
|
-
|
|
127
|
-
-
|
|
128
|
-
- completed/cancelled jobs are pruned after `cleanup.completeJobRetentionMs` based on terminal-job age, but recent wake-up sends keep response/artifact files retained briefly so follow-up turns do not point at deleted paths
|
|
129
|
-
- failed jobs are pruned after `cleanup.failedJobRetentionMs`
|
|
130
|
-
- `/oracle-cancel` can cancel queued or active jobs
|
|
131
|
-
- `/oracle-clean` refuses non-terminal jobs, including queued ones, refuses terminal jobs whose worker is still live, also refuses recently woken jobs during a short post-send retention grace window, performs runtime cleanup before removing terminal job directories, and reports cleanup warnings if any residual cleanup step fails
|
|
132
|
-
|
|
133
|
-
Detailed design and maintainer docs:
|
|
134
|
-
- `docs/ORACLE_DESIGN.md`
|
|
135
|
-
- `docs/ORACLE_RECOVERY_DRILL.md`
|
|
136
|
-
|
|
137
|
-
Completion notification semantics:
|
|
138
|
-
- oracle responses and artifacts are always persisted durably in oracle job state under the configured oracle jobs dir (`${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/` by default)
|
|
139
|
-
- completion delivery into pi sessions is best-effort wake-up based; the extension no longer appends synthetic assistant completion messages into session history
|
|
140
|
-
- wake-up content tells the receiving assistant to call `oracle_read(jobId)` as the canonical completion-consumption path, with saved file paths included as secondary context
|
|
141
|
-
- manual `oracle_read` or `/oracle-status` inspection settles further reminder retries once the terminal job has been opened, and now persists settlement provenance for postmortems
|
|
142
|
-
- manual inspection before the first wake-up attempt is recorded as observation only and does not suppress the first reminder send
|
|
143
|
-
- if a wake-up does not land, the job remains available via its saved response/artifacts and status commands
|
|
193
|
+
- `docs/ORACLE_DESIGN.md` — architecture, lifecycle, queueing, persistence, presets, and recovery behavior
|
|
194
|
+
- `docs/ORACLE_RECOVERY_DRILL.md` — safe expired-auth recovery validation drill
|
|
144
195
|
|
|
145
196
|
## Privacy / local data
|
|
146
197
|
|
|
147
198
|
This extension is local-first, but it does read and persist local data:
|
|
148
199
|
- `/oracle-auth` reads ChatGPT cookies from a local Chrome profile
|
|
149
200
|
- job archives are uploaded to ChatGPT.com
|
|
150
|
-
- responses and artifacts are written under the configured oracle jobs dir
|
|
201
|
+
- responses and artifacts are written under the configured oracle jobs dir
|
|
151
202
|
|
|
152
203
|
Review the code and design docs before using it with sensitive material.
|
|
153
204
|
|