pi-oracle 0.6.13 → 0.6.14

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.6.14 - 2026-05-02
+
+### Fixed
+- deduped oracle completion wake-ups by marking one-time best-effort delivery in job state before the poller sends the follow-up turn, preventing repeated identical completion notifications across poller scans
+- clarified completion wake-up guidance so agents treat the wake-up as a read/inspect prompt rather than an automatic auth refresh or resubmission instruction
+
+### Changed
+- `oracle_read` and `/oracle-status` summaries for active jobs now include elapsed time, phase elapsed time, and a poll/backoff hint so manual checks waste fewer turns
+- `oracle_submit` preset schema and prompt guidance now list the canonical preset ids directly for tool callers
+
 ## 0.6.13 - 2026-05-01
 
 ### Changed

package/README.md

@@ -48,7 +48,7 @@ pi install https://github.com/fitchmultz/pi-oracle
 4. Optional: create `~/.pi/agent/extensions/oracle.json` if you want non-default settings.
 5. Run `/oracle-auth`.
 6. Run `/oracle Review the current pending changes. Include the whole repo unless a narrower archive is clearly better.`
-7. Wait for a best-effort wake-up, or check `/oracle-status`.
+7. Wait for the one-time best-effort wake-up, or check `/oracle-status`.
 
 The `/oracle` prompt now runs an early oracle preflight before it gathers repo context, so missing persisted-session or local auth/config blockers fail before the agent spends time reading files.
 
@@ -56,7 +56,7 @@ For explicitly narrow requests, `/oracle` should still prefer a context-rich rel
 
 If a local archive still exceeds the 250 MB limit after default exclusions and automatic whole-repo pruning, the agent should treat that as a retryable archive-selection failure: shrink the archive automatically, retry with a smaller relevant slice, and explain what it cut only if it still cannot fit after the allowed retry budget.
 
-If you miss the wake-up, the result is still saved durably in the oracle job directory and can be read later.
+If you miss the one-time wake-up, the result is still saved durably in the oracle job directory and can be read later.
 
 ## Example requests
 
@@ -87,7 +87,7 @@ flowchart LR
     C --> D["Detached worker starts isolated ChatGPT runtime"]
     D --> E["Archive + prompt sent to ChatGPT.com"]
     E --> F["Response/artifacts saved under oracle job dir"]
-    F --> G["Best-effort wake-up to matching pi session"]
+    F --> G["One-time best-effort wake-up to matching pi session"]
 ```
 
 If concurrency is full, the job is queued and starts automatically later.
@@ -162,7 +162,7 @@ Project config should only override safe, non-privileged settings.
 
 - Jobs persist their response and any artifacts under `${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/` by default.
 - Jobs can queue automatically if runtime capacity is full.
-- Completion delivery into `pi` is best-effort wake-up based.
+- Completion delivery into `pi` is one-time best-effort wake-up based; duplicate poller scans are deduped in job state.
 - If you miss the wake-up, use `/oracle-read [job-id]` to inspect the saved response preview.
 - `/oracle-status [job-id]` still shows saved job metadata and lists recent job ids when you omit the id.
 - Agent callers can use `oracle_read({ jobId })`.

package/docs/ORACLE_DESIGN.md

@@ -484,12 +484,12 @@ The extension still uses the same general `pi`-native background completion patt
 - detached worker writes `${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-*` state
 - poller scans jobs on an interval
 - completed job durability lives in oracle job state plus saved response/artifact files, not in synthetic session-history assistant messages
-- when a matching job reaches `complete`, `failed`, or `cancelled`, the poller issues bounded best-effort wake-up reminders to whichever matching session is currently live
+- when a matching job reaches `complete`, `failed`, or `cancelled`, the poller issues one best-effort wake-up to whichever matching session is currently live, then records `notifiedAt` so later scans do not duplicate the completion message
 - those wake-ups direct the receiver to `/oracle-read [job-id]` as the primary completion-consumption path, while still surfacing saved response/artifact paths as secondary context; `/oracle-status` remains useful for metadata and job-id discovery, and agent callers can still use `oracle_read` when they need tool output in-turn
-- manual `oracle_read`, `/oracle-read`, or `/oracle-status` inspection settles further reminder retries once the terminal job has been opened and persists provenance about which path/session settled the wake-up
-- manual inspection before the first wake-up attempt is recorded separately as observation metadata and does not suppress the first reminder send
+- wake-up content explicitly tells agents not to treat completion as an automatic `oracle_auth`, `oracle_submit`, or `oracle_cancel` retry instruction
+- manual `oracle_read`, `/oracle-read`, or `/oracle-status` inspection after a wake-up persists provenance about which path/session settled the wake-up
 - if no wake-up lands, the job remains available via `/oracle-read`, `/oracle-status`, `oracle_read`, and the saved `${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/` response/artifact files
-- because completion delivery is best-effort, pruning uses explicit terminal-job age policy instead of pretending a durable session notification happened
+- because completion delivery is best-effort, pruning uses explicit terminal-job age policy plus `notifiedAt`/wakeup state instead of pretending a durable session notification was appended
 - recently sent wake-ups keep response/artifact files retained briefly so follow-up turns do not point at deleted paths if cleanup or pruning races with delivery
 
 ## What was removed by this pivot

package/extensions/oracle/lib/poller.ts

@@ -15,6 +15,7 @@ import {
   hasPersistedOriginSession,
   isActiveOracleJob,
   listOracleJobDirs,
+  markJobNotified,
   noteWakeupRequested,
   readJob,
   recordNotificationTarget,
@@ -324,7 +325,6 @@ async function scan(
         await releaseNotificationClaim(jobId, notificationClaimant).catch(() => undefined);
         return;
       }
-      requestWakeupTurn(pi, deliverable);
       const notedWakeup = await noteWakeupRequested(jobId);
       if (!notedWakeup) {
         await releaseNotificationClaim(jobId, notificationClaimant).catch(() => undefined);
@@ -334,6 +334,13 @@ async function scan(
         await releaseNotificationClaim(jobId, notificationClaimant).catch(() => undefined);
         return;
       }
+      await hooks.beforeMarkJobNotified?.(deliverable);
+      await markJobNotified(jobId, notificationClaimant, {
+        notificationSessionKey: pollerKey,
+        notificationSessionFile: currentSessionFile,
+      });
+      if (await releaseWakeupLeaseIfInactive(wakeupTargetLeaseKey, lifecycle)) return;
+      requestWakeupTurn(pi, deliverable);
       if (snapshot.hasUI) {
         snapshot.ui.notify(`Oracle job ${claimed.id} is ${claimed.status}.`, "info");
       }

package/extensions/oracle/lib/tools.ts

@@ -71,7 +71,8 @@ const ORACLE_SUBMIT_PARAMS = Type.Object({
   preset: Type.Optional(
     Type.String({
       description:
-        "ChatGPT model preset. Omit to use the configured default preset. Canonical ids are preferred; matching human-readable preset labels and common hyphen/space variants are normalized automatically.",
+        `ChatGPT model preset. Omit to use the configured default preset. Canonical ids: ${ORACLE_SUBMIT_PRESET_IDS.join(", ")}. ` +
+        "Matching human-readable preset labels and common hyphen/space variants are normalized automatically.",
     }),
   ),
   followUpJobId: Type.Optional(Type.String({ description: "Earlier oracle job id whose chat thread should be continued." })),
@@ -1101,7 +1102,9 @@ export function registerOracleTools(pi: ExtensionAPI, workerPath: string, authWo
       "For any other submit-time error, stop and report the error instead of retrying automatically.",
       "If oracle_submit returns a queued job instead of an immediately dispatched one, treat that as success and stop exactly the same way.",
       "After a successful or queued oracle_submit, stop; do not continue the task while the oracle job is running. If oracle_submit failed with retryable archive_too_large, narrow the archive and retry first.",
-      "Use `preset` as the only model-selection parameter on oracle_submit. Canonical ids are preferred, and matching human-readable preset labels are normalized automatically. Omit preset to use the configured default.",
+      "Use `preset` as the only model-selection parameter on oracle_submit. " +
+      `Canonical ids: ${ORACLE_SUBMIT_PRESET_IDS.join(", ")}. ` +
+      "matching human-readable preset labels are normalized automatically. Omit preset to use the configured default.",
     ],
     parameters: ORACLE_SUBMIT_PARAMS,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {

package/extensions/oracle/shared/job-lifecycle-helpers.mjs

@@ -287,9 +287,6 @@ export function markOracleJobNotified(job, options = {}) {
     notificationEntryId: options.notificationEntryId ?? job.notificationEntryId,
     notificationSessionKey: options.notificationSessionKey ?? job.notificationSessionKey,
     notificationSessionFile: options.notificationSessionFile ?? job.notificationSessionFile,
-    wakeupAttemptCount: 0,
-    wakeupLastRequestedAt: undefined,
-    wakeupSettledAt: undefined,
     notifyClaimedAt: undefined,
     notifyClaimedBy: undefined,
   });

package/extensions/oracle/shared/job-observability-helpers.d.mts

@@ -4,6 +4,7 @@ export interface OracleJobSummaryLike {
   id: string;
   status: string;
   phase: string;
+  phaseAt?: string;
   createdAt: string;
   queuedAt?: string;
   submittedAt?: string;
@@ -38,6 +39,7 @@ export interface OracleJobSummaryOptions {
   includeWorkerLogPath?: boolean;
   nowMs?: number;
   heartbeatStaleMs?: number;
+  suggestedPollAfterSeconds?: number;
 }
 
 export interface OracleSubmitResponseOptions {

package/extensions/oracle/shared/job-observability-helpers.mjs

@@ -48,6 +48,7 @@ function formatAutoPrunedArchiveMessage(autoPrunedPrefixes) {
 
 const ACTIVE_SUMMARY_STATUSES = new Set(["preparing", "submitted", "waiting"]);
 const DEFAULT_ORACLE_HEARTBEAT_STALE_MS = 3 * 60 * 1000;
+const DEFAULT_ACTIVE_JOB_POLL_HINT_SECONDS = 15;
 
 /**
  * @param {string | undefined} value
@@ -99,6 +100,31 @@ function formatHeartbeatFreshness(job, options = {}) {
   return `heartbeat: ${freshness} (${formatElapsed(elapsedMs)} ${submittedMs !== undefined ? "since submit" : "since create"})`;
 }
 
+/**
+ * @param {OracleJobSummaryLike} job
+ * @param {OracleJobSummaryOptions} [options]
+ * @returns {string[]}
+ */
+function formatActiveProgressLines(job, options = {}) {
+  if (!ACTIVE_SUMMARY_STATUSES.has(job.status)) return [];
+  const nowMs = Number.isFinite(options.nowMs) ? options.nowMs : Date.now();
+  const submittedMs = parseTimestamp(job.submittedAt);
+  const createdMs = parseTimestamp(job.createdAt);
+  const phaseMs = parseTimestamp(job.phaseAt);
+  const baselineMs = submittedMs ?? createdMs;
+  const elapsedLine = baselineMs === undefined
+    ? undefined
+    : `elapsed: ${formatElapsed(nowMs - baselineMs)} ${submittedMs !== undefined ? "since submit" : "since create"}`;
+  const phaseElapsedLine = phaseMs === undefined
+    ? undefined
+    : `phase-elapsed: ${formatElapsed(nowMs - phaseMs)} in ${job.phase}`;
+  const pollHintSeconds = Number.isFinite(options.suggestedPollAfterSeconds)
+    ? Math.max(1, Math.round(options.suggestedPollAfterSeconds))
+    : DEFAULT_ACTIVE_JOB_POLL_HINT_SECONDS;
+  const pollHint = `poll-hint: wait about ${pollHintSeconds}s before checking again, or stop and wait for the one-time completion wake-up`;
+  return [elapsedLine, phaseElapsedLine, pollHint].filter(Boolean);
+}
+
 /**
  * @param {{ id: string; status: string }} job
  * @returns {string}
@@ -142,6 +168,7 @@ export function formatOracleJobSummary(job, options = {}) {
     `project: ${job.projectId}`,
     `session: ${job.sessionId}`,
     formatHeartbeatFreshness(job, options),
+    ...formatActiveProgressLines(job, options),
     job.completedAt ? `completed: ${job.completedAt}` : undefined,
     job.followUpToJobId ? `follow-up-to: ${job.followUpToJobId}` : undefined,
     job.chatUrl ? `chat: ${job.chatUrl}` : undefined,
@@ -175,7 +202,8 @@ export function buildOracleWakeupNotificationContent(job, options = {}) {
   const artifactsPath = options.artifactsPath ?? `artifacts unavailable for ${job.id}`;
   return [
     `Oracle job ${job.id} is ${job.status}.`,
-    `Use /oracle-read ${job.id} to inspect the saved response preview. /oracle-status ${job.id} still shows saved job metadata. Agent callers can use oracle_read({ jobId: "${job.id}" }) if they need tool output in the current turn.`,
+    "This is a one-time completion wake-up, not a retry instruction. Do not call oracle_auth, oracle_submit, or oracle_cancel automatically from this wake-up.",
+    `Use /oracle-read ${job.id} to inspect the saved response preview. /oracle-status ${job.id} still shows saved job metadata. Agent callers can use oracle_read({ jobId: "${job.id}" }) once if they need tool output in the current turn.`,
     responseLine,
     `Artifacts: ${artifactsPath}`,
     formatOracleLifecycleEvent(getLatestOracleJobLifecycleEvent(job)) ? `Last event: ${formatOracleLifecycleEvent(getLatestOracleJobLifecycleEvent(job))}` : undefined,
@@ -199,7 +227,7 @@ export function formatOracleSubmitResponse(job, options) {
     `Response will be written to: ${job.responsePath}`,
     formatOracleLifecycleEvent(getLatestOracleJobLifecycleEvent(job)) ? `Last event: ${formatOracleLifecycleEvent(getLatestOracleJobLifecycleEvent(job))}` : undefined,
     options.queued ? "The job will start automatically when capacity is available." : undefined,
-    "Stop now and wait for the oracle completion wake-up.",
+    "Do not poll now; wait for the one-time oracle completion wake-up.",
   ]
     .filter(Boolean)
     .join("\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-oracle",
-  "version": "0.6.13",
+  "version": "0.6.14",
   "description": "ChatGPT web-oracle extension for pi with isolated browser auth, async jobs, and project-context archives.",
   "private": false,
   "license": "MIT",