pi-oracle 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.3.3 - 2026-04-11
+
+### Added
+- `oracle_submit` now accepts canonical preset ids plus matching human-readable preset labels/common hyphen-space variants and normalizes them back to the canonical preset id at submit time
+- lock sweeping now gives in-flight `.tmp-*` lock/state directories a dedicated grace window so concurrent sweep does not delete another process's atomic publish
+
+### Changed
+- oracle submit metadata/docs now point preset discovery at the canonical registry/README while keeping execute-time normalization for flexible caller input
+
+### Fixed
+- closed a concurrent stale-lock sweep race that could reclaim another process's in-flight lock publish before metadata landed
+- oracle sanity coverage now verifies preset alias validation/normalization and the `.tmp-*` grace window behavior end-to-end
+
+## 0.3.2 - 2026-04-08
+
+### Changed
+- README now lists the available oracle preset ids directly, so users can choose `defaults.preset` values without having to inspect source files
+
+### Fixed
+- closed a README usability gap where preset-based configuration was documented without actually enumerating the shipped preset ids
+- oracle sanity coverage now verifies that the README lists every preset from the canonical `ORACLE_SUBMIT_PRESETS` registry
+
 ## 0.3.1 - 2026-04-08
 
 ### Changed

package/README.md

@@ -112,6 +112,21 @@ Notes:
 - If the packaged default is fine, you can omit `defaults.preset` entirely.
 - You usually do not need to set browser paths unless auto-detection fails.
 
+## Available presets
+
+| Preset id | Description |
+| --- | --- |
+| `pro_standard` | Pro - Standard |
+| `pro_extended` | Pro - Extended |
+| `thinking_light` | Thinking - Light |
+| `thinking_standard` | Thinking - Standard |
+| `thinking_extended` | Thinking - Extended |
+| `thinking_heavy` | Thinking - Heavy |
+| `instant` | Instant |
+| `instant_auto_switch` | Instant - Auto-switch to Thinking Enabled |
+
+`oracle_submit` accepts either the canonical preset id or the matching human-readable preset label; common space/hyphen variants are normalized automatically at submit time. Keep `defaults.preset` in config on the canonical preset id.
+
 Other useful settings:
 - `browser.runMode`
 - `browser.args`

package/docs/ORACLE_DESIGN.md

@@ -133,7 +133,7 @@ The authenticated seed profile remains the source of truth for future oracle run
 
 ### `oracle_submit`
 
-Agent-facing submissions use **`preset`**; the canonical registry is `ORACLE_SUBMIT_PRESETS` in `extensions/oracle/lib/config.ts`. **`preset` is the only model-selection parameter** on `oracle_submit`. There are no `modelFamily`, `effort`, or `autoSwitchToThinking` fields.
+Agent-facing submissions use **`preset`**; the canonical registry is `ORACLE_SUBMIT_PRESETS` in `extensions/oracle/lib/config.ts`. **`preset` is the only model-selection parameter** on `oracle_submit`. There are no `modelFamily`, `effort`, or `autoSwitchToThinking` fields. Submit-time inputs accept canonical preset ids plus matching human-readable labels/common hyphen-space variants, and the tool normalizes them back to the canonical id before persisting job state.
 
 1. resolve the preset (submit-time or config default) into an execution snapshot
 2. resolve optional `followUpJobId` into a prior `chatUrl` and `conversationId`

package/extensions/oracle/lib/config.ts

@@ -29,6 +29,117 @@ export type OracleSubmitPresetId = keyof typeof ORACLE_SUBMIT_PRESETS;
 
 export type OracleSubmitPreset = typeof ORACLE_SUBMIT_PRESETS[OracleSubmitPresetId];
 
+export const ORACLE_SUBMIT_PRESET_IDS = Object.freeze(Object.keys(ORACLE_SUBMIT_PRESETS) as OracleSubmitPresetId[]);
+
+function normalizeOracleSubmitPresetLookupKey(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[_-]+/g, " ")
+    .replace(/[^\p{L}\p{N}\s]/gu, " ")
+    .replace(/\s+/g, " ");
+}
+
+function splitOracleSubmitPresetWords(value: string): string[] {
+  return value
+    .trim()
+    .replace(/[_-]+/g, " ")
+    .replace(/[^\p{L}\p{N}\s]/gu, " ")
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+function lowercaseWords(words: readonly string[]): string[] {
+  return words.map((word) => word.toLowerCase());
+}
+
+function titleCaseWords(words: readonly string[]): string[] {
+  return words.map((word) => (word ? `${word[0]?.toUpperCase() ?? ""}${word.slice(1)}` : word));
+}
+
+function buildOracleSubmitPresetSeparatorVariants(words: readonly string[]): string[] {
+  const normalizedWords = words.map((word) => word.trim()).filter(Boolean);
+  if (normalizedWords.length === 0) return [];
+
+  const variants = new Set<string>();
+  const build = (index: number, current: string): void => {
+    if (index >= normalizedWords.length) {
+      variants.add(current);
+      return;
+    }
+    for (const separator of [" ", "-"] as const) {
+      build(index + 1, `${current}${separator}${normalizedWords[index]}`);
+    }
+  };
+
+  build(1, normalizedWords[0]!);
+  return [...variants];
+}
+
+function buildOracleSubmitPresetJoinVariants(words: readonly string[]): string[] {
+  const normalizedWords = words.map((word) => word.trim()).filter(Boolean);
+  if (normalizedWords.length === 0) return [];
+
+  const lowercase = lowercaseWords(normalizedWords);
+  const titleWords = titleCaseWords(lowercase);
+  return [
+    ...buildOracleSubmitPresetSeparatorVariants(normalizedWords),
+    ...buildOracleSubmitPresetSeparatorVariants(lowercase),
+    ...buildOracleSubmitPresetSeparatorVariants(titleWords),
+  ];
+}
+
+function buildOracleSubmitPresetAliases(id: OracleSubmitPresetId, preset: OracleSubmitPreset): string[] {
+  const idWords = splitOracleSubmitPresetWords(id);
+  const labelWords = splitOracleSubmitPresetWords(preset.label);
+  return [
+    id,
+    ...buildOracleSubmitPresetJoinVariants(idWords),
+    preset.label,
+    preset.label.toLowerCase(),
+    ...buildOracleSubmitPresetJoinVariants(labelWords),
+  ].filter(Boolean);
+}
+
+function buildOracleSubmitPresetLookupArtifacts(): {
+  acceptedInputs: readonly string[];
+  lookup: ReadonlyMap<string, OracleSubmitPresetId>;
+} {
+  const lookup = new Map<string, OracleSubmitPresetId>();
+  const aliases = new Set<string>();
+
+  for (const [id, preset] of Object.entries(ORACLE_SUBMIT_PRESETS) as [OracleSubmitPresetId, OracleSubmitPreset][]) {
+    for (const alias of buildOracleSubmitPresetAliases(id, preset)) {
+      const normalized = normalizeOracleSubmitPresetLookupKey(alias);
+      if (!normalized) continue;
+      const existing = lookup.get(normalized);
+      if (existing && existing !== id) {
+        throw new Error(`Conflicting oracle_submit preset alias: ${alias} matches both ${existing} and ${id}`);
+      }
+      lookup.set(normalized, id);
+      if (alias !== id) aliases.add(alias);
+    }
+  }
+
+  return {
+    acceptedInputs: Object.freeze([...ORACLE_SUBMIT_PRESET_IDS, ...[...aliases].sort((left, right) => left.localeCompare(right))]),
+    lookup,
+  };
+}
+
+const ORACLE_SUBMIT_PRESET_LOOKUP_ARTIFACTS = buildOracleSubmitPresetLookupArtifacts();
+
+export const ORACLE_SUBMIT_PRESET_ACCEPTED_INPUTS = ORACLE_SUBMIT_PRESET_LOOKUP_ARTIFACTS.acceptedInputs;
+
+export function coerceOracleSubmitPresetId(value: string): OracleSubmitPresetId {
+  const normalized = normalizeOracleSubmitPresetLookupKey(value);
+  const presetId = ORACLE_SUBMIT_PRESET_LOOKUP_ARTIFACTS.lookup.get(normalized);
+  if (presetId) return presetId;
+  throw new Error(
+    `Unknown oracle_submit preset: ${value}. Use one of the canonical ids (${ORACLE_SUBMIT_PRESET_IDS.join(", ")}) or a matching preset label.`,
+  );
+}
+
 export function getOracleSubmitPresetById(id: OracleSubmitPresetId): OracleSubmitPreset {
   const found = ORACLE_SUBMIT_PRESETS[id];
   if (!found) {
@@ -336,7 +447,7 @@ function normalizeLegacyBrowserConfig(root: Record<string, unknown>): Record<str
   return root;
 }
 
-const PRESET_IDS = Object.keys(ORACLE_SUBMIT_PRESETS) as unknown as readonly OracleSubmitPresetId[];
+const PRESET_IDS = ORACLE_SUBMIT_PRESET_IDS;
 
 function validateOracleConfig(value: unknown): OracleConfig {
   const root = normalizeLegacyBrowserConfig(expectObject(value, "root"));

package/extensions/oracle/lib/locks.ts

@@ -12,6 +12,8 @@ const LEASES_DIR = join(ORACLE_STATE_DIR, "leases");
 const DEFAULT_WAIT_MS = 30_000;
 const POLL_MS = 200;
 export const ORACLE_METADATA_WRITE_GRACE_MS = 1_000;
+/** Incomplete `.tmp-*` dirs are in-flight atomic creates; a 1s grace is too short under multi-process sweep + slow FS. */
+export const ORACLE_TMP_STATE_DIR_GRACE_MS = 60_000;
 
 export interface OracleLockHandle {
   path: string;
@@ -90,7 +92,8 @@ function isIncompleteStateDirStale(path: string, now = Date.now()): boolean {
   try {
     const stats = statSync(path);
     const baselineMs = Math.max(stats.mtimeMs, stats.ctimeMs);
-    return now - baselineMs >= ORACLE_METADATA_WRITE_GRACE_MS;
+    const graceMs = basename(path).startsWith(".tmp-") ? ORACLE_TMP_STATE_DIR_GRACE_MS : ORACLE_METADATA_WRITE_GRACE_MS;
+    return now - baselineMs >= graceMs;
   } catch {
     return false;
   }
@@ -138,13 +141,13 @@ async function maybeReclaimStaleLock(path: string, now = Date.now()): Promise<bo
   return true;
 }
 
-export async function sweepStaleLocks(): Promise<string[]> {
+export async function sweepStaleLocks(now = Date.now()): Promise<string[]> {
   const dir = getLocksDir();
   const removed: string[] = [];
 
   for (const name of readdirSync(dir)) {
     const path = join(dir, name);
-    if (await maybeReclaimStaleLock(path)) {
+    if (await maybeReclaimStaleLock(path, now)) {
       removed.push(path);
     }
   }

package/extensions/oracle/lib/tools.ts

@@ -1,3 +1,8 @@
+// Purpose: Register oracle extension tools and implement submit/read/cancel behavior.
+// Responsibilities: Validate tool parameters, create archives, enqueue or dispatch jobs, and surface job state.
+// Scope: Tool-facing orchestration only; durable job storage, locks, runtime leases, and config live in sibling modules.
+// Usage: Imported by the oracle extension entrypoint and sanity tests to register tools against the pi API.
+// Invariants/Assumptions: The pi runtime validates TypeBox schemas before execute, while execute owns semantic normalization.
 import { randomUUID } from "node:crypto";
 import { lstat, mkdtemp, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -6,10 +11,9 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import { isLockTimeoutError, withGlobalReconcileLock, withLock } from "./locks.js";
 import {
+  coerceOracleSubmitPresetId,
   loadOracleConfig,
-  ORACLE_SUBMIT_PRESETS,
   resolveOracleSubmitPreset,
-  type OracleSubmitPresetId,
 } from "./config.js";
 import {
   appendCleanupWarnings,
@@ -48,10 +52,6 @@ import {
   tryAcquireRuntimeLease,
 } from "./runtime.js";
 
-function stringEnum(values: readonly string[], description: string) {
-  return Type.Union(values.map((value) => Type.Literal(value)), { description });
-}
-
 const ORACLE_SUBMIT_PARAMS = Type.Object({
   prompt: Type.String({ description: "Prompt text to send to ChatGPT web." }),
   files: Type.Array(Type.String({ description: "Project-relative file or directory path to include in the archive." }), {
@@ -59,10 +59,10 @@ const ORACLE_SUBMIT_PARAMS = Type.Object({
     minItems: 1,
   }),
   preset: Type.Optional(
-    stringEnum(
-      [...Object.keys(ORACLE_SUBMIT_PRESETS)] as const,
-      "ChatGPT model preset. Omit to use the configured default preset.",
-    ),
+    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.",
+    }),
   ),
   followUpJobId: Type.Optional(Type.String({ description: "Earlier oracle job id whose chat thread should be continued." })),
 });
@@ -579,7 +579,7 @@ export function registerOracleTools(pi: ExtensionAPI, workerPath: string): void
     label: "Oracle Submit",
     description:
       "Dispatch a background ChatGPT web oracle job after gathering context. Always pass a prompt and exact project-relative archive inputs. " +
-      "Optional ChatGPT model: set parameter `preset`, or omit it for configured defaults (see `preset` field for allowed ids).",
+      "Optional ChatGPT model: set parameter `preset`, or omit it for configured defaults; canonical preset ids are listed in the README and ORACLE_SUBMIT_PRESETS registry, and matching labels are normalized at submit time.",
     promptSnippet: "Dispatch a background ChatGPT web oracle job after gathering repo context.",
     promptGuidelines: [
       "Gather context before calling oracle_submit.",
@@ -591,7 +591,7 @@ export function registerOracleTools(pi: ExtensionAPI, workerPath: string): void
       "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 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.",
       "Stop after dispatching oracle_submit; do not continue the task while the oracle job is running.",
-      "Use `preset` as the only model-selection parameter on oracle_submit. Allowed values come from the tool schema enum. Omit preset to use the configured default.",
+      "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.",
     ],
     parameters: ORACLE_SUBMIT_PARAMS,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -599,7 +599,7 @@ export function registerOracleTools(pi: ExtensionAPI, workerPath: string): void
       const originSessionFile = requirePersistedSessionFile(getSessionFile(ctx), "submit oracle jobs");
       const projectId = getProjectId(ctx.cwd);
       const sessionId = getSessionId(originSessionFile, projectId);
-      const presetId = (params.preset as OracleSubmitPresetId | undefined) ?? config.defaults.preset;
+      const presetId = typeof params.preset === "string" ? coerceOracleSubmitPresetId(params.preset) : config.defaults.preset;
       const selection = resolveOracleSubmitPreset(presetId);
       const followUp = resolveFollowUp(params.followUpJobId, ctx.cwd);
       try {

package/extensions/oracle/worker/state-locks.d.mts

@@ -1,4 +1,5 @@
 export const ORACLE_METADATA_WRITE_GRACE_MS: number;
+export const ORACLE_TMP_STATE_DIR_GRACE_MS: number;
 
 export function acquireLock(
   stateDir: string,

package/extensions/oracle/worker/state-locks.mjs

@@ -6,6 +6,7 @@ import { basename, join } from "node:path";
 const DEFAULT_WAIT_MS = 30_000;
 const POLL_MS = 200;
 export const ORACLE_METADATA_WRITE_GRACE_MS = 1_000;
+export const ORACLE_TMP_STATE_DIR_GRACE_MS = 60_000;
 
 async function sleep(ms) {
   await new Promise((resolve) => setTimeout(resolve, ms));
@@ -76,7 +77,8 @@ function isIncompleteStateDirStale(path, now = Date.now()) {
   try {
     const stats = statSync(path);
     const baselineMs = Math.max(stats.mtimeMs, stats.ctimeMs);
-    return now - baselineMs >= ORACLE_METADATA_WRITE_GRACE_MS;
+    const graceMs = basename(path).startsWith(".tmp-") ? ORACLE_TMP_STATE_DIR_GRACE_MS : ORACLE_METADATA_WRITE_GRACE_MS;
+    return now - baselineMs >= graceMs;
   } catch {
     return false;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-oracle",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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

@@ -14,7 +14,8 @@ Required workflow:
 6. 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 tool schema enum / canonical preset registry.
+- 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.
@@ -27,7 +28,7 @@ Rules:
 - 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 **`preset`** id from the tool schema enum.
+- Prefer the configured default (omit **`preset`**) unless the task clearly needs a different model; 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.