@steipete/oracle 0.18.0 → 0.19.0

package/dist/src/mcp/tools/wait.js

@@ -0,0 +1,182 @@
+import { realpathSync, watch } from "node:fs";
+import { z } from "zod";
+import { sessionStore } from "../../sessionStore.js";
+import { waitInputSchema } from "../types.js";
+import { consultArtifactSummaryShape, consultImageSummaryShape, consultModelSummaryShape, readSessionLogTail, summarizeArtifactsForConsult, summarizeImageArtifactsForConsult, summarizeModelRunsForConsult, } from "./consult.js";
+const TERMINAL_SESSION_STATUSES = new Set(["completed", "partial", "error", "cancelled"]);
+const DEFAULT_FALLBACK_INTERVAL_MS = 1_000;
+const waitInputShape = {
+    id: z.string().min(1, "Session id is required.").describe("Oracle session id or slug."),
+    timeoutMs: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe("How long to wait for a terminal session state. Omit to wait indefinitely; 0 returns an immediate snapshot. A wait timeout never cancels the Oracle session."),
+};
+const waitOutputShape = {
+    sessionId: z.string(),
+    status: z.string(),
+    waitStatus: z.enum(["terminal", "timed_out"]),
+    timedOut: z.boolean(),
+    cancelled: z.boolean(),
+    output: z.string(),
+    models: z.array(consultModelSummaryShape).optional(),
+    artifacts: z.array(consultArtifactSummaryShape).optional(),
+    images: z.array(consultImageSummaryShape).optional(),
+};
+function abortReason(signal) {
+    return signal.reason instanceof Error
+        ? signal.reason
+        : new DOMException("Oracle session wait was cancelled.", "AbortError");
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw abortReason(signal);
+    }
+}
+export function isTerminalSessionStatus(status) {
+    return TERMINAL_SESSION_STATUSES.has(status);
+}
+export function createSessionChangeSource(directory) {
+    let watcher;
+    let notified = false;
+    let pendingWake;
+    const onWake = () => {
+        if (!pendingWake) {
+            notified = true;
+            return;
+        }
+        const wake = pendingWake;
+        pendingWake = undefined;
+        wake();
+    };
+    const onError = () => {
+        const failedWatcher = watcher;
+        watcher = undefined;
+        failedWatcher?.off("change", onWake);
+        failedWatcher?.off("error", onError);
+        failedWatcher?.close();
+        onWake();
+    };
+    try {
+        // Windows short-path aliases can trigger a native libuv prefix assertion.
+        watcher = watch(realpathSync.native(directory));
+        watcher.on("change", onWake);
+        watcher.on("error", onError);
+    }
+    catch {
+        // A timer fallback below keeps waits correct when filesystem notifications
+        // are unavailable or the session directory is on an unsupported volume.
+    }
+    return {
+        wait(delayMs, signal) {
+            throwIfAborted(signal);
+            return new Promise((resolve, reject) => {
+                let settled = false;
+                const finish = (error) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timer);
+                    if (pendingWake === wake)
+                        pendingWake = undefined;
+                    signal?.removeEventListener("abort", onAbort);
+                    if (error)
+                        reject(error);
+                    else
+                        resolve();
+                };
+                const wake = () => finish();
+                const onAbort = () => finish(abortReason(signal));
+                const timer = setTimeout(wake, delayMs);
+                pendingWake = wake;
+                signal?.addEventListener("abort", onAbort, { once: true });
+                if (signal?.aborted) {
+                    onAbort();
+                    return;
+                }
+                if (notified) {
+                    notified = false;
+                    queueMicrotask(wake);
+                }
+            });
+        },
+        close() {
+            watcher?.off("change", onWake);
+            watcher?.off("error", onError);
+            watcher?.close();
+            watcher = undefined;
+        },
+    };
+}
+const defaultWaitDeps = {
+    readSession: (id) => sessionStore.readSession(id),
+    getSessionDir: async (id) => (await sessionStore.getPaths(id)).dir,
+    createChangeSource: createSessionChangeSource,
+    now: Date.now,
+};
+export async function waitForSessionTerminal({ id, timeoutMs, signal, fallbackIntervalMs = DEFAULT_FALLBACK_INTERVAL_MS, }, deps = defaultWaitDeps) {
+    throwIfAborted(signal);
+    const deadline = timeoutMs === undefined ? undefined : deps.now() + timeoutMs;
+    let metadata = await deps.readSession(id);
+    if (!metadata) {
+        throw new Error(`Session "${id}" not found.`);
+    }
+    if (isTerminalSessionStatus(metadata.status)) {
+        return { metadata, waitStatus: "terminal", timedOut: false };
+    }
+    if (timeoutMs === 0) {
+        return { metadata, waitStatus: "timed_out", timedOut: true };
+    }
+    const directory = await deps.getSessionDir(id);
+    const changes = deps.createChangeSource(directory);
+    try {
+        // Close the read/watch race: the session may have completed while the
+        // filesystem watcher was being installed.
+        metadata = (await deps.readSession(id)) ?? metadata;
+        while (!isTerminalSessionStatus(metadata.status)) {
+            throwIfAborted(signal);
+            const remaining = deadline === undefined ? undefined : deadline - deps.now();
+            if (remaining !== undefined && remaining <= 0) {
+                return { metadata, waitStatus: "timed_out", timedOut: true };
+            }
+            const delayMs = Math.max(1, Math.min(fallbackIntervalMs, remaining ?? fallbackIntervalMs));
+            await changes.wait(delayMs, signal);
+            metadata = (await deps.readSession(id)) ?? metadata;
+        }
+        return { metadata, waitStatus: "terminal", timedOut: false };
+    }
+    finally {
+        changes.close();
+    }
+}
+export async function runWaitTool(input, extra) {
+    const { id, timeoutMs } = waitInputSchema.parse(input);
+    const result = await waitForSessionTerminal({ id, timeoutMs, signal: extra?.signal });
+    const { metadata } = result;
+    const logTail = (await readSessionLogTail(metadata.id, 4_000)) ?? "";
+    const summary = `Session ${metadata.id} (${metadata.status}; wait=${result.waitStatus})`;
+    return {
+        content: [{ type: "text", text: [summary, logTail || "(log empty)"].join("\n") }],
+        structuredContent: {
+            sessionId: metadata.id,
+            status: metadata.status,
+            waitStatus: result.waitStatus,
+            timedOut: result.timedOut,
+            cancelled: metadata.status === "cancelled",
+            output: logTail,
+            models: summarizeModelRunsForConsult(metadata.models),
+            artifacts: summarizeArtifactsForConsult(metadata.artifacts),
+            images: summarizeImageArtifactsForConsult(metadata.artifacts),
+        },
+    };
+}
+export function registerWaitTool(server) {
+    server.registerTool("wait", {
+        title: "Wait for an oracle session",
+        description: "Wait for an existing Oracle session to reach a terminal state without agent-side polling. Omit timeoutMs to wait indefinitely, or set a bounded caller wait. Wait timeout or request cancellation never cancels the Oracle session; call wait again with the same id to continue waiting.",
+        inputSchema: z.object(waitInputShape),
+        outputSchema: z.object(waitOutputShape),
+    }, async (input, context) => runWaitTool(input, { signal: context.mcpReq.signal }));
+}

package/dist/src/mcp/types.js

@@ -29,6 +29,7 @@ export const consultInputSchema = z
     browserKeepBrowser: z.boolean().optional(),
     generateImage: z.string().optional(),
     outputPath: z.string().optional(),
+    waitForCompletion: z.boolean().optional(),
     dryRun: z.boolean().optional(),
     search: z.boolean().optional(),
     slug: z.string().optional(),
@@ -41,3 +42,9 @@ export const sessionsInputSchema = z.object({
     includeAll: z.boolean().optional(),
     detail: z.boolean().optional(),
 });
+export const waitInputSchema = z
+    .object({
+    id: z.string().min(1, "Session id is required."),
+    timeoutMs: z.number().int().nonnegative().optional(),
+})
+    .strict();

package/dist/src/oracle/errors.js

@@ -26,6 +26,17 @@ export class BrowserAutomationError extends OracleUserError {
         this.name = "BrowserAutomationError";
     }
 }
+/**
+ * The caller went away. Distinct from a failure: nothing was wrong with the run,
+ * it simply stopped being wanted, and a caller that reads this should not retry
+ * or report a problem.
+ */
+export class BrowserRunCancelledError extends OracleUserError {
+    constructor(message = "Browser run cancelled: the caller disconnected.") {
+        super("browser-automation", message, { stage: "run-cancelled" });
+        this.name = "BrowserRunCancelledError";
+    }
+}
 export class PromptValidationError extends OracleUserError {
     constructor(message, details, cause) {
         super("prompt-validation", message, details, cause);

package/dist/src/oracle/providerRoutePlan.js

@@ -75,7 +75,8 @@ function buildResolvedProviderRoute(input) {
     });
     const provider = state.provider;
     const isAzureOpenAI = state.isAzureOpenAI;
-    let baseUrl = input.baseUrl?.trim();
+    // Azure owns the endpoint, including metadata lookups before request dispatch.
+    let baseUrl = isAzureOpenAI ? undefined : input.baseUrl?.trim();
     const providerQualifiedOpenRouterCandidate = !isAzureOpenAI && providerMode !== "openai" && input.model.includes("/");
     if (baseUrl &&
         providerQualifiedOpenRouterCandidate &&
@@ -83,7 +84,7 @@ function buildResolvedProviderRoute(input) {
         !isCustomBaseUrl(baseUrl)) {
         baseUrl = undefined;
     }
-    if (!baseUrl) {
+    if (!baseUrl && !isAzureOpenAI) {
         let envBaseUrl;
         if (input.model.startsWith("grok")) {
             envBaseUrl = env.XAI_BASE_URL?.trim() || "https://api.x.ai/v1";

package/dist/src/remote/client.js

@@ -6,30 +6,43 @@ 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) {
+        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 +53,7 @@ export function createRemoteBrowserExecutor({ host, token }) {
                 if (settled)
                     return;
                 settled = true;
+                callerSignal?.removeEventListener("abort", onCallerAbort);
                 reject(error);
             };
             const req = http.request({
@@ -107,17 +121,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 +225,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 +249,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 +266,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 +290,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 +320,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--;
+        };
+    }
+}