@steipete/oracle 0.18.0 → 0.20.0

package/dist/src/oracle/run.js

@@ -36,6 +36,15 @@ const DEFAULT_TIMEOUT_PRO_MS = 60 * 60 * 1000;
 const GPT_5_6_API_MODELS = new Set(["gpt-5.6", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"]);
 const REASONING_EFFORTS = new Set(["none", "low", "medium", "high", "xhigh", "max"]);
 const REASONING_MODES = new Set(["standard", "pro"]);
+// Astra has a narrower effort range than the GPT-5.6 API family. Keep this
+// capability separate from GPT_5_6_API_MODELS so adding a model cannot
+// accidentally inherit a family's exact option set.
+const MODEL_REASONING_CAPABILITIES = new Map([
+    [
+        "gpt-6-astra",
+        { efforts: new Set(["low", "medium", "high", "xhigh", "max"]), modes: REASONING_MODES },
+    ],
+]);
 const defaultWait = (ms) => new Promise((resolve) => {
     setTimeout(resolve, ms);
 });
@@ -72,9 +81,13 @@ function runtimeKeySource({ route, providerMode, optionsApiKey, }) {
         return "XAI_API_KEY";
     return optionsApiKey ? "apiKey option" : route.keySource;
 }
-function validateReasoningOptions(options, route) {
+function validateReasoningOptions(options, route, modelConfig) {
     const { reasoningEffort, reasoningMode } = options;
-    if (!reasoningEffort && !reasoningMode)
+    const capabilities = GPT_5_6_API_MODELS.has(options.model)
+        ? { efforts: REASONING_EFFORTS, modes: REASONING_MODES }
+        : MODEL_REASONING_CAPABILITIES.get(options.model);
+    const effectiveEffort = reasoningEffort ?? modelConfig?.reasoning?.effort;
+    if (!reasoningEffort && !reasoningMode && !effectiveEffort)
         return;
     if (reasoningEffort && !REASONING_EFFORTS.has(reasoningEffort)) {
         throw new PromptValidationError(`Invalid reasoning effort "${reasoningEffort}". Expected none, low, medium, high, xhigh, or max.`, { model: options.model, reasoningEffort });
@@ -82,14 +95,20 @@ function validateReasoningOptions(options, route) {
     if (reasoningMode && !REASONING_MODES.has(reasoningMode)) {
         throw new PromptValidationError(`Invalid reasoning mode "${reasoningMode}". Expected standard or pro.`, { model: options.model, reasoningMode });
     }
-    if (!GPT_5_6_API_MODELS.has(options.model)) {
+    if ((reasoningEffort || reasoningMode) && !capabilities) {
         const option = reasoningMode
             ? `Reasoning mode "${reasoningMode}"`
             : `Reasoning effort "${reasoningEffort}"`;
         const guidance = reasoningMode
             ? `Use --model gpt-5.6-sol --reasoning-mode ${reasoningMode}.`
             : `Use --model gpt-5.6-sol --reasoning-effort ${reasoningEffort}.`;
-        throw new PromptValidationError(`${option} is available only for GPT-5.6 API models. ${guidance}`, { model: options.model, reasoningEffort, reasoningMode });
+        throw new PromptValidationError(`${option} is available only for GPT-5.6 or GPT-6 Astra API models. ${guidance}`, { model: options.model, reasoningEffort, reasoningMode });
+    }
+    if (effectiveEffort && capabilities && !capabilities.efforts.has(effectiveEffort)) {
+        throw new PromptValidationError(`Reasoning effort "${effectiveEffort}" is not supported for ${options.model}. Expected low, medium, high, xhigh, or max.`, { model: options.model, reasoningEffort: effectiveEffort, reasoningMode });
+    }
+    if (reasoningMode && capabilities && !capabilities.modes.has(reasoningMode)) {
+        throw new PromptValidationError(`Reasoning mode "${reasoningMode}" is not supported for ${options.model}. Expected standard or pro.`, { model: options.model, reasoningEffort, reasoningMode });
     }
     if (reasoningMode &&
         !route.isAzureOpenAI &&
@@ -166,6 +185,10 @@ export async function runOracle(options, deps = {}) {
         openRouterApiKey: resolverOpenRouterApiKey,
         modelOverrides: options.modelOverrides,
     });
+    // Validate the resolved default as well as explicit flags. This catches a
+    // model override such as Astra + reasoning.effort=none, while allowing an
+    // explicit supported effort to replace an invalid bundled/overridden default.
+    validateReasoningOptions(options, route, modelConfig);
     const isLongRunningModel = isProTierModel;
     const supportsBackground = modelConfig.supportsBackground !== false;
     const useBackground = supportsBackground ? (options.background ?? isLongRunningModel) : false;

package/dist/src/remote/client.js

@@ -6,30 +6,46 @@ import path from "node:path";
 import { mkdir, readFile, rename, rm, stat } from "node:fs/promises";
 import { appendArtifacts, computeFileSha256, resolveSessionArtifactsDir, resolveUniqueArtifactPath, sanitizeArtifactFilename, sanitizeArtifactMimeType, validateArtifactFile, } from "../browser/artifacts.js";
 import { MAX_REMOTE_ARTIFACT_BYTES, } from "./types.js";
+import { materializeStagedFallbackBundle } from "../browser/prompt.js";
+import { checkRemoteHealth } from "./health.js";
 import { parseHostPort } from "../bridge/connection.js";
+import { BrowserRunCancelledError } from "../oracle/errors.js";
 export function createRemoteBrowserExecutor({ host, token }) {
     // Return a drop-in replacement for runBrowserMode so the browser session runner can stay unchanged.
     return async function remoteBrowserExecutor(options) {
+        if (options.config?.researchMode === "search") {
+            throw new Error("Web Search is a local browser pilot; --remote-host does not negotiate this capability yet. Use local Chrome or --browser-attach-running.");
+        }
+        const callerSignal = options.signal;
+        if (callerSignal?.aborted)
+            throw new BrowserRunCancelledError("Browser run cancelled before the request was sent.");
+        if (callerSignal) {
+            const health = await checkRemoteHealth({ host, token, signal: callerSignal });
+            if (callerSignal.aborted)
+                throw new BrowserRunCancelledError();
+            if (health.capabilities?.runCancellation !== true)
+                throw new Error("Remote host does not support run cancellation; upgrade the host before using an AbortSignal.");
+        }
         const payload = {
             prompt: options.prompt,
             attachments: await serializeAttachments(options.attachments ?? []),
-            fallbackSubmission: options.fallbackSubmission
-                ? {
-                    prompt: options.fallbackSubmission.prompt,
-                    attachments: await serializeAttachments(options.fallbackSubmission.attachments ?? []),
-                }
-                : undefined,
+            fallbackSubmission: await serializeFallback(options.fallbackSubmission, { host, token }),
             browserConfig: options.config ?? {},
             options: {
                 heartbeatIntervalMs: options.heartbeatIntervalMs,
                 verbose: options.verbose,
                 sessionId: options.sessionId,
                 followUpPrompts: options.followUpPrompts,
+                cancelOnDisconnect: callerSignal ? true : undefined,
             },
         };
         const body = Buffer.from(JSON.stringify(payload));
         const { hostname, port } = parseHost(host);
         return new Promise((resolve, reject) => {
+            if (callerSignal?.aborted) {
+                reject(new Error("Browser run cancelled before the request was sent."));
+                return;
+            }
             const transferredFiles = [];
             const transferFailures = [];
             const transferPromises = [];
@@ -40,6 +56,7 @@ export function createRemoteBrowserExecutor({ host, token }) {
                 if (settled)
                     return;
                 settled = true;
+                callerSignal?.removeEventListener("abort", onCallerAbort);
                 reject(error);
             };
             const req = http.request({
@@ -107,17 +124,55 @@ export function createRemoteBrowserExecutor({ host, token }) {
                             return;
                         }
                         settled = true;
+                        callerSignal?.removeEventListener("abort", onCallerAbort);
                         resolve(mergeTransferredArtifacts(resolved, transferredFiles, transferFailures));
                     })().catch(fail);
                 });
                 res.on("error", fail);
             });
             req.on("error", fail);
+            // Destroying the request closes the socket, which is how the service learns
+            // to abort: its own disconnect handler fires and releases the slot and the
+            // browser tab.
+            const onCallerAbort = () => {
+                req.destroy();
+                fail(new BrowserRunCancelledError("Browser run cancelled: the caller aborted."));
+            };
+            callerSignal?.addEventListener("abort", onCallerAbort, { once: true });
             req.write(body);
             req.end();
         });
     };
 }
+async function serializeFallback(fallback, remote) {
+    if (!fallback)
+        return undefined;
+    if (fallback.pendingBundle) {
+        const health = await checkRemoteHealth(remote);
+        if (!health.ok || health.capabilities?.deferredFallbackBundling !== true) {
+            // Older hosts ignore bundle metadata, so send a ready-to-upload fallback.
+            const prepared = await materializeStagedFallbackBundle({
+                composerText: fallback.prompt,
+                attachments: fallback.attachments,
+                ...fallback.pendingBundle,
+            });
+            try {
+                return {
+                    prompt: prepared.composerText,
+                    attachments: await serializeAttachments(prepared.attachments),
+                };
+            }
+            finally {
+                await rm(path.dirname(prepared.bundled.bundlePath), { recursive: true, force: true });
+            }
+        }
+    }
+    return {
+        prompt: fallback.prompt,
+        attachments: await serializeAttachments(fallback.attachments),
+        bundle: fallback.pendingBundle,
+    };
+}
 async function serializeAttachments(attachments) {
     const serialized = [];
     for (const attachment of attachments) {
@@ -173,12 +228,17 @@ function handleEvent(params) {
             token: params.token,
             descriptor: event.artifact,
             sessionId: params.options.sessionId,
+            signal: params.options.signal,
             log: params.options.log,
         })
             .then((artifact) => {
             params.onArtifact(artifact);
         })
             .catch((error) => {
+            if (params.options.signal?.aborted) {
+                params.onError(new BrowserRunCancelledError());
+                return;
+            }
             const message = error instanceof Error ? error.message : String(error);
             const fallback = `Oracle captured the browser text response, but bridge artifact transfer failed for ${displayFilename}. Open the ChatGPT browser on the bridge host, download the ZIP/file shown in the current response, and copy it to a cloud-readable path. Reason: ${message}`;
             params.options.log?.(`[browser] ${fallback}`);
@@ -192,6 +252,7 @@ function handleEvent(params) {
     return null;
 }
 async function transferRemoteArtifact(params) {
+    params.signal?.throwIfAborted();
     validateRemoteArtifactDescriptor(params.descriptor);
     const sessionId = params.sessionId ?? params.descriptor.runId;
     const artifactsDir = resolveSessionArtifactsDir(sessionId);
@@ -208,6 +269,7 @@ async function transferRemoteArtifact(params) {
         token: params.token,
         targetPath: partPath,
         descriptor: params.descriptor,
+        signal: params.signal,
     }).catch(async (error) => {
         await rm(partPath, { force: true }).catch(() => undefined);
         throw error;
@@ -231,6 +293,10 @@ async function transferRemoteArtifact(params) {
         await rm(partPath, { force: true }).catch(() => undefined);
         throw new Error(`${validation.type} validation failed: ${validation.error ?? "invalid"}`);
     }
+    if (params.signal?.aborted) {
+        await rm(partPath, { force: true });
+        throw new BrowserRunCancelledError();
+    }
     await rename(partPath, finalPath);
     params.log?.(`[browser] Transferred artifact to ${finalPath}`);
     const publishedFilename = path.basename(finalPath);
@@ -257,6 +323,7 @@ async function downloadArtifactToFile(params) {
             port: params.port,
             path: params.path,
             method: "GET",
+            signal: params.signal,
             headers: params.token ? { authorization: `Bearer ${params.token}` } : undefined,
         }, (res) => {
             if (res.statusCode !== 200) {

package/dist/src/remote/health.js

@@ -30,7 +30,7 @@ export async function checkTcpConnection(host, timeoutMs = 2000) {
         socket.once("timeout", onTimeout);
     });
 }
-export async function checkRemoteHealth({ host, token, timeoutMs = 5000, }) {
+export async function checkRemoteHealth({ host, token, timeoutMs = 5000, signal, }) {
     const { hostname, port } = parseHostPort(host);
     const headers = { accept: "application/json" };
     if (token) {
@@ -43,6 +43,7 @@ export async function checkRemoteHealth({ host, token, timeoutMs = 5000, }) {
             path: "/health",
             headers,
             timeoutMs,
+            signal,
         });
         if (response.statusCode === 200 && typeof response.json === "object" && response.json) {
             const ok = response.json.ok === true;
@@ -90,6 +91,8 @@ function parseCapabilities(value) {
         return undefined;
     }
     return {
+        ...(raw.deferredFallbackBundling === true ? { deferredFallbackBundling: true } : {}),
+        ...(raw.runCancellation === true ? { runCancellation: true } : {}),
         artifactTransfer: true,
         artifactProtocolVersion,
         maxArtifactBytes: Math.min(maxArtifactBytes, MAX_REMOTE_ARTIFACT_BYTES),
@@ -105,7 +108,7 @@ function extractErrorMessage(json, bodyText) {
     const trimmed = bodyText.trim();
     return trimmed.length ? trimmed : null;
 }
-async function requestJson({ hostname, port, path, headers, timeoutMs, }) {
+async function requestJson({ hostname, port, path, headers, timeoutMs, signal, }) {
     return await new Promise((resolve, reject) => {
         const req = http.request({
             hostname,
@@ -113,6 +116,7 @@ async function requestJson({ hostname, port, path, headers, timeoutMs, }) {
             path,
             method: "GET",
             headers,
+            signal,
         }, (res) => {
             res.setEncoding("utf8");
             let body = "";

package/dist/src/remote/runSlots.js

@@ -0,0 +1,83 @@
+export class RunQueueFullError extends Error {
+    constructor() {
+        super("The browser run queue is full.");
+        this.name = "RunQueueFullError";
+    }
+}
+export class RunSlots {
+    maxConcurrent;
+    maxQueued;
+    active = 0;
+    waiting = [];
+    constructor(maxConcurrent, maxQueued) {
+        this.maxConcurrent = maxConcurrent;
+        this.maxQueued = maxQueued;
+        if (!Number.isSafeInteger(maxConcurrent) ||
+            maxConcurrent < 1 ||
+            !Number.isSafeInteger(maxQueued) ||
+            maxQueued < 0) {
+            throw new Error("Run capacity must be a positive integer and queue capacity a nonnegative integer.");
+        }
+    }
+    get activeCount() {
+        return this.active;
+    }
+    get queuedCount() {
+        return this.waiting.length;
+    }
+    get capacity() {
+        return this.maxConcurrent;
+    }
+    get queueCapacity() {
+        return this.maxQueued;
+    }
+    get isSaturated() {
+        return this.active >= this.maxConcurrent && this.waiting.length >= this.maxQueued;
+    }
+    positionFor() {
+        return this.active < this.maxConcurrent ? 0 : this.waiting.length + 1;
+    }
+    // Reservation is synchronous, including the queue bound; request-body reads cannot race it.
+    acquire(signal) {
+        if (signal?.aborted)
+            return Promise.reject(new Error("cancelled before a slot was available"));
+        if (this.active < this.maxConcurrent) {
+            this.active++;
+            return Promise.resolve(this.makeRelease());
+        }
+        if (this.waiting.length >= this.maxQueued)
+            return Promise.reject(new RunQueueFullError());
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                const index = this.waiting.indexOf(entry);
+                if (index < 0)
+                    return;
+                this.waiting.splice(index, 1);
+                entry.cleanup();
+                reject(new Error("cancelled while waiting for a slot"));
+            };
+            const entry = {
+                resolve,
+                reject,
+                cleanup: () => signal?.removeEventListener("abort", onAbort),
+            };
+            this.waiting.push(entry);
+            signal?.addEventListener("abort", onAbort, { once: true });
+        });
+    }
+    makeRelease() {
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            const next = this.waiting.shift();
+            if (next) {
+                next.cleanup();
+                next.resolve(this.makeRelease());
+            }
+            else
+                this.active--;
+        };
+    }
+}