pi-oracle 0.4.0 → 0.5.0

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

@@ -104,6 +104,7 @@ export declare function appendOracleJobLifecycleEvent<TJob extends OracleLifecyc
   event: Omit<OracleJobLifecycleEvent, "status" | "phase"> & { status?: OracleJobStatus; phase?: OracleJobPhase },
 ): TJob;
 export declare function getLatestOracleJobLifecycleEvent(job: Pick<OracleLifecycleTrackedJobLike, "lifecycleEvents">): OracleJobLifecycleEvent | undefined;
+export declare function getLatestOracleTerminalLifecycleEvent(job: Pick<OracleLifecycleTrackedJobLike, "lifecycleEvents">): OracleJobLifecycleEvent | undefined;
 export declare function markOracleJobCreated<TJob extends OracleLifecycleTrackedJobLike>(job: TJob, options?: { at?: string; source?: string; message?: string }): TJob;
 export declare function transitionOracleJobPhase<TJob extends OracleLifecycleTrackedJobLike>(
   job: TJob,

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

@@ -111,6 +111,19 @@ export function getLatestOracleJobLifecycleEvent(job) {
   return events.length > 0 ? events[events.length - 1] : undefined;
 }
 
+/**
+ * @param {Pick<OracleLifecycleTrackedJobLike, "lifecycleEvents">} job
+ * @returns {OracleJobLifecycleEvent | undefined}
+ */
+export function getLatestOracleTerminalLifecycleEvent(job) {
+  const events = job.lifecycleEvents || [];
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index];
+    if (event?.kind === "phase" && TERMINAL_ORACLE_JOB_STATUSES.includes(event.status)) return event;
+  }
+  return undefined;
+}
+
 /**
  * @template {OracleLifecycleTrackedJobLike} TJob
  * @param {TJob} job

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

@@ -32,6 +32,7 @@ export interface OracleJobSummaryOptions {
   queuePosition?: OracleQueuePositionLike;
   artifactsPath?: string;
   responsePreview?: string;
+  responseAvailable?: boolean;
   includeLatestEvent?: boolean;
   includeWorkerLogPath?: boolean;
 }
@@ -53,7 +54,7 @@ export declare function formatOracleLifecycleEvent(event: OracleJobLifecycleEven
 export declare function formatOracleJobSummary(job: OracleJobSummaryLike, options?: OracleJobSummaryOptions): string;
 export declare function buildOracleWakeupNotificationContent(
   job: OracleJobSummaryLike,
-  options?: { responsePath?: string; artifactsPath?: string },
+  options?: { responsePath?: string; responseAvailable?: boolean; artifactsPath?: string },
 ): string;
 export declare function formatOracleSubmitResponse(job: OracleJobSummaryLike & { promptPath: string; archivePath: string }, options: OracleSubmitResponseOptions): string;
 export declare function buildOracleStatusText(counts: OracleStatusCounts): string;

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

@@ -4,7 +4,7 @@
 // Usage: Imported by commands, tools, poller, and extension startup/status code to keep detached-oracle messaging consistent.
 // Invariants/Assumptions: Job summaries read from durable job state, and lifecycle event trails are bounded and already normalized by shared lifecycle helpers.
 
-import { getLatestOracleJobLifecycleEvent } from "./job-lifecycle-helpers.mjs";
+import { getLatestOracleJobLifecycleEvent, getLatestOracleTerminalLifecycleEvent } from "./job-lifecycle-helpers.mjs";
 
 /** @typedef {import("./job-observability-helpers.d.mts").OracleJobSummaryLike} OracleJobSummaryLike */
 /** @typedef {import("./job-observability-helpers.d.mts").OracleJobSummaryOptions} OracleJobSummaryOptions */
@@ -52,7 +52,22 @@ function formatAutoPrunedArchiveMessage(autoPrunedPrefixes) {
  * @returns {string}
  */
 export function formatOracleJobSummary(job, options = {}) {
-  const latestEvent = options.includeLatestEvent === false ? undefined : formatOracleLifecycleEvent(getLatestOracleJobLifecycleEvent(job));
+  const latestEventRaw = options.includeLatestEvent === false ? undefined : getLatestOracleJobLifecycleEvent(job);
+  const terminalEventRaw = getLatestOracleTerminalLifecycleEvent(job);
+  const latestEvent = formatOracleLifecycleEvent(latestEventRaw);
+  const terminalEvent = formatOracleLifecycleEvent(terminalEventRaw);
+  const sameEvent = Boolean(
+    latestEventRaw && terminalEventRaw &&
+    latestEventRaw.at === terminalEventRaw.at &&
+    latestEventRaw.source === terminalEventRaw.source &&
+    latestEventRaw.kind === terminalEventRaw.kind &&
+    latestEventRaw.message === terminalEventRaw.message,
+  );
+  const responseLine = options.responseAvailable === true
+    ? job.responsePath ? `response: ${job.responsePath}` : undefined
+    : job.responsePath ? "response: unavailable yet" : undefined;
+  const responseFormatLine = options.responseAvailable === true && job.responseFormat ? `response-format: ${job.responseFormat}` : undefined;
+  const latestEventLabel = latestEventRaw?.kind === "wakeup" ? "wakeup-event" : "last-event";
   return [
     `job: ${job.id}`,
     `status: ${job.status}`,
@@ -67,14 +82,15 @@ export function formatOracleJobSummary(job, options = {}) {
     job.followUpToJobId ? `follow-up-to: ${job.followUpToJobId}` : undefined,
     job.chatUrl ? `chat: ${job.chatUrl}` : undefined,
     job.conversationId ? `conversation: ${job.conversationId}` : undefined,
-    job.responsePath ? `response: ${job.responsePath}` : undefined,
-    job.responseFormat ? `response-format: ${job.responseFormat}` : undefined,
+    responseLine,
+    responseFormatLine,
     options.artifactsPath ? `artifacts: ${options.artifactsPath}` : undefined,
     typeof job.artifactFailureCount === "number" ? `artifact-failures: ${job.artifactFailureCount}` : undefined,
     options.includeWorkerLogPath === false ? undefined : job.workerLogPath ? `worker-log: ${job.workerLogPath}` : undefined,
     job.lastCleanupAt ? `last-cleanup: ${job.lastCleanupAt}` : undefined,
     job.cleanupWarnings?.length ? `cleanup-warnings: ${job.cleanupWarnings.join(" | ")}` : undefined,
-    latestEvent ? `last-event: ${latestEvent}` : undefined,
+    terminalEvent ? `terminal-event: ${terminalEvent}` : undefined,
+    latestEvent && !sameEvent ? `${latestEventLabel}: ${latestEvent}` : undefined,
     job.error ? `error: ${job.error}` : undefined,
     options.responsePreview ? "" : undefined,
     options.responsePreview,
@@ -85,16 +101,18 @@ export function formatOracleJobSummary(job, options = {}) {
 
 /**
  * @param {OracleJobSummaryLike} job
- * @param {{ responsePath?: string; artifactsPath?: string }} [options]
+ * @param {{ responsePath?: string; responseAvailable?: boolean; artifactsPath?: string }} [options]
  * @returns {string}
  */
 export function buildOracleWakeupNotificationContent(job, options = {}) {
-  const responsePath = options.responsePath ?? job.responsePath ?? `response unavailable for ${job.id}`;
+  const responseLine = options.responseAvailable === false
+    ? "Response file: unavailable yet"
+    : `Response file: ${options.responsePath ?? job.responsePath ?? `response unavailable for ${job.id}`}`;
   const artifactsPath = options.artifactsPath ?? `artifacts unavailable for ${job.id}`;
   return [
     `Oracle job ${job.id} is ${job.status}.`,
     `Use oracle_read with jobId ${job.id} to open the response and settle wake-up retries.`,
-    `Response file: ${responsePath}`,
+    responseLine,
     `Artifacts: ${artifactsPath}`,
     formatOracleLifecycleEvent(getLatestOracleJobLifecycleEvent(job)) ? `Last event: ${formatOracleLifecycleEvent(getLatestOracleJobLifecycleEvent(job))}` : undefined,
     job.error ? `Error: ${job.error}` : "After oracle_read, continue from the oracle output.",

package/extensions/oracle/worker/auth-bootstrap.mjs

@@ -20,7 +20,23 @@ if (!rawConfig) {
   process.exit(1);
 }
 
-const config = JSON.parse(rawConfig);
+const parsedConfigPayload = JSON.parse(rawConfig);
+const config =
+  parsedConfigPayload &&
+    typeof parsedConfigPayload === "object" &&
+    !Array.isArray(parsedConfigPayload) &&
+    Object.hasOwn(parsedConfigPayload, "config")
+    ? parsedConfigPayload.config
+    : parsedConfigPayload;
+const configLoad =
+  parsedConfigPayload &&
+    typeof parsedConfigPayload === "object" &&
+    !Array.isArray(parsedConfigPayload) &&
+    Object.hasOwn(parsedConfigPayload, "configLoad") &&
+    parsedConfigPayload.configLoad &&
+    typeof parsedConfigPayload.configLoad === "object"
+    ? parsedConfigPayload.configLoad
+    : undefined;
 const CHATGPT_LABELS = {
   composer: "Chat with ChatGPT",
   addFiles: "Add files and more",
@@ -65,6 +81,34 @@ function authSessionName() {
   return `${config.browser.sessionPrefix}-auth`;
 }
 
+function effectiveAuthConfigPath() {
+  return typeof configLoad?.effectiveAuthConfigPath === "string" && configLoad.effectiveAuthConfigPath
+    ? configLoad.effectiveAuthConfigPath
+    : join(process.env.PI_CODING_AGENT_DIR?.trim() || join(homedir(), ".pi", "agent"), "extensions", "oracle.json");
+}
+
+function authConfigRemediation() {
+  if (typeof configLoad?.remediation === "string" && configLoad.remediation) return configLoad.remediation;
+  if (typeof configLoad?.projectConfigPath === "string" && configLoad.projectConfigPath && configLoad.projectConfigExists) {
+    return (
+      `Set auth.chromeProfile / auth.chromeCookiePath in ${effectiveAuthConfigPath()}. ` +
+      `Project overrides are also read from ${configLoad.projectConfigPath}, but auth.* is loaded from ${effectiveAuthConfigPath()}.`
+    );
+  }
+  return `Set auth.chromeProfile / auth.chromeCookiePath in ${effectiveAuthConfigPath()}.`;
+}
+
+function authConfigSummary() {
+  if (typeof configLoad?.summary === "string" && configLoad.summary) return configLoad.summary;
+  const agentDirSuffix = typeof configLoad?.agentDir === "string" && configLoad.agentDir ? ` (agent dir: ${configLoad.agentDir})` : "";
+  const createSuffix = configLoad?.agentConfigExists === false ? " [create this file to override auth.*]" : "";
+  const lines = [`Effective oracle auth config: ${effectiveAuthConfigPath()}${agentDirSuffix}${createSuffix}`];
+  if (typeof configLoad?.projectConfigPath === "string" && configLoad.projectConfigPath && configLoad.projectConfigExists) {
+    lines.push(`Project oracle config also loaded: ${configLoad.projectConfigPath} (auth.* still comes from ${effectiveAuthConfigPath()}).`);
+  }
+  return lines.join("\n");
+}
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -457,7 +501,7 @@ async function readSourceCookies() {
 
   if (!hasSessionToken) {
     throw new Error(
-      `No ChatGPT session-token cookies were found in ${cookieSourceLabel()}. Make sure ChatGPT is logged into that Chrome profile, or set auth.chromeProfile / auth.chromeCookiePath in ~/.pi/agent/extensions/oracle.json.`,
+      `No ChatGPT session-token cookies were found in ${cookieSourceLabel()}. Make sure ChatGPT is logged into that Chrome profile. ${authConfigRemediation()}`,
     );
   }
 
@@ -731,7 +775,7 @@ async function waitForImportedAuthReady() {
     }
     if (classification.state === "login_required") {
       await captureDiagnostics("login-required");
-      throw new Error(classification.message);
+      throw new Error(`${classification.message} ${authConfigRemediation()}`);
     }
     await sleep(config.auth.pollMs);
   }
@@ -751,6 +795,7 @@ async function run() {
       await log(
         `Config summary: session=${authSessionName()} seedProfileDir=${profilePlan.targetDir} stagingProfileDir=${profilePlan.stagingDir} executable=${config.browser.executablePath || "(default)"} source=${cookieSourceLabel()}`,
       );
+      await log(authConfigSummary());
       const cookies = await readSourceCookies();
       await prepareStagedProfile(profilePlan);
       await launchTargetBrowser();
@@ -783,7 +828,7 @@ async function run() {
 
 run().catch((error) => {
   process.stderr.write(
-    `${error instanceof Error ? error.message : String(error)}\nSee ${LOG_PATH} and diagnostics in ${DIAGNOSTICS_DIR || "(oracle-auth diagnostics dir unavailable)"}\nIf needed, ensure the configured real Chrome profile is already logged into ChatGPT and grant macOS Keychain access when prompted.`,
+    `${error instanceof Error ? error.message : String(error)}\nSee ${LOG_PATH} and diagnostics in ${DIAGNOSTICS_DIR || "(oracle-auth diagnostics dir unavailable)"}\n${authConfigSummary()}\nIf needed, ensure the configured real Chrome profile is already logged into ChatGPT and grant macOS Keychain access when prompted.`,
   );
   process.exit(1);
 });

package/package.json

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

package/prompts/oracle.md

@@ -6,29 +6,35 @@ You are preparing an /oracle job.
 Do not answer the user's request directly yet.
 
 Required workflow:
-1. Understand the request.
-2. Gather repo context first by reading files and searching the codebase.
-3. Choose archive inputs for the oracle job.
-4. Craft a concise but complete oracle prompt for ChatGPT web.
-5. Call oracle_submit with the prompt and exact archive inputs.
-6. Stop immediately after dispatching the oracle job.
+1. Call `oracle_preflight` immediately.
+2. If `oracle_preflight` reports `ready: false`, stop immediately and report the blocking issue plus the suggested next step. Do not read files, search the codebase, or prepare archive inputs first.
+3. Understand the request and decide whether it is explicitly narrow or genuinely broad.
+4. Gather only the smallest repo context needed to choose archive inputs and write a strong oracle prompt.
+5. If the user scope is explicit and narrow, prefer a minimal targeted read/search set and dispatch as soon as you have enough context. Do not broaden into repo-wide exploration unless the narrow pass proves insufficient.
+6. If the request is broad, architectural, release-oriented, or otherwise repo-wide, gather broader context and usually archive `.`.
+7. Choose archive inputs for the oracle job.
+8. Craft a concise but complete oracle prompt for ChatGPT web.
+9. Call `oracle_submit` with the prompt and exact archive inputs.
+10. Stop immediately after dispatching the oracle job.
 
 Oracle model (`oracle_submit`):
 - To choose a specific ChatGPT model, pass **`preset`** with one of the allowed ids from the canonical preset registry.
 - Matching human-readable preset labels and common hyphen/space variants are also accepted and normalized automatically, but prefer canonical ids when readily available.
 - **Or** omit **`preset`** entirely to use the configured default model (from oracle config).
 - **`preset`** is the only model-selection parameter on `oracle_submit`. Do not pass `modelFamily`, `effort`, or `autoSwitchToThinking`.
-- If unsure which preset fits the task, ask the user.
+- If unsure, omit **`preset`** and use the configured default. Ask the user about model choice only when they explicitly want model control or the choice would materially change the result.
 
 Rules:
+- Use `oracle_preflight` before any expensive `/oracle` preparation so missing persisted-session or local auth/config blockers fail fast.
 - Always include an archive. Do not submit without context files.
-- By default, include the whole repository by passing `.`. Default archive exclusions apply automatically, including common bulky outputs and obvious credentials/private data like `.env` files, key material, credential dotfiles, local database files, and nested `secrets/` directories anywhere in the repo.
+- By default, include the whole repository by passing `.` when the request is genuinely broad, repo-wide, or unclear after a quick narrow pass. Default archive exclusions apply automatically, including common bulky outputs and obvious credentials/private data like `.env` files, key material, credential dotfiles, local database files, and nested `secrets/` directories anywhere in the repo.
 - Only limit file selection if the user explicitly requests it, if the task is clearly scoped to a smaller area, or if privacy/sensitivity requires it.
-- For very targeted asks like reviewing one function or explaining one stack trace, a smaller archive is preferable.
+- For very targeted asks like reviewing one function, one file, one stack trace, or one narrowly scoped question, start with the smallest obviously sufficient archive and expand only if that first pass proves insufficient.
+- Do not keep exploring once you already have enough context to submit well.
 - If the request depends on git state or pending changes (for example code review, ship readiness, or release approval), create a tracked diff bundle file inside the repo (for example under `.pi/`) containing `git status` plus `git diff` output, include that file in the archive, and tell the oracle to use it because the `.git` directory is not included in oracle exports.
 - When `files=["."]` and the post-exclusion archive is still too large, submit automatically prunes the largest nested directories matching generic generated-output names like `build/`, `dist/`, `out/`, `coverage/`, and `tmp/` outside obvious source roots like `src/` and `lib/` until the archive fits or no candidate remains. Successful submissions report what was pruned.
 - If a submitted oracle job later fails because upload is rejected, retry with a smaller archive in this order: (1) remove the largest obviously irrelevant/generated content, (2) if still too large, include modified files plus adjacent files plus directly relevant subtrees, (3) if still too large, explain the cut or ask the user.
-- Prefer the configured default (omit **`preset`**) unless the task clearly needs a different model; then choose a canonical **`preset`** id.
+- Prefer the configured default (omit **`preset`**) unless the task clearly needs a different model or the user explicitly asked for one; then choose a canonical **`preset`** id.
 - If `oracle_submit` itself fails because the local archive still exceeds the upload limit after default exclusions and automatic generic generated-output-dir pruning, or for any other submit-time error, stop and report the error. Do not retry automatically.
 - If `oracle_submit` returns a queued job instead of an immediately dispatched one, treat that as success and end your turn exactly the same way.
 - After oracle_submit returns, end your turn. Do not keep working while the oracle runs.