codex-chatgpt-control 0.2.0-alpha.1 → 0.5.0-alpha.1

package/dist/src/commands/messages.js

@@ -1,12 +1,16 @@
+import { createHash } from "node:crypto";
 import { readPageState } from "../browser/page-state.js";
 import { resultError, resultOk } from "../errors.js";
-import { latestAssistantTurnHasResponseActions, readAssistantGenerationState } from "../dom/generation-state.js";
+import { EMPTY_GENERATION_STATE, latestAssistantTurnHasResponseActions, readAssistantGenerationState } from "../dom/generation-state.js";
 import { countPageMessages, isTransientAssistantText, readLatestMessage, readLatestMessageText, readLatestMessageTextSnapshot, readMessages } from "../dom/messages.js";
-import { composerTextbox, sendButton } from "../dom/selectors.js";
+import { composerTextbox, copyResponseButtons, sendButton } from "../dom/selectors.js";
+import { readWaitDomSnapshot, waitTextMetadata } from "../dom/wait-snapshot.js";
 import { normalizeLineBreaks, normalizeWhitespace } from "../dom/visible-text.js";
 import { contextFromPage } from "./context.js";
+import { createDeadline } from "./deadline.js";
 import { withCommandOutputText } from "./output.js";
-import { bootstrap } from "./session.js";
+import { createSingleFlightProbe } from "./probes.js";
+import { ensurePage } from "./session.js";
 export function isResponseComplete(snapshot) {
     return snapshot.latestText.trim().length > 0
         && !isTransientAssistantText(snapshot.latestText)
@@ -94,8 +98,14 @@ export async function submitMessage(env, args = {}) {
         }
         if (userTurn === undefined) {
             const latestUser = await readLatestMessage(page, "user", "normalized_text");
+            const generation = await readAssistantGenerationState(page).catch(() => EMPTY_GENERATION_STATE);
+            const turnCount = await countPageMessages(page).catch(() => undefined);
             if (submittedUserTurnMatches(latestUser?.text, args.text)) {
-                return resultOk(submitData(latestUser?.text, await countPageMessages(page).catch(() => undefined)), await contextFromPage(page));
+                return resultOk(submitData(latestUser?.text, turnCount, generation.active ? "submitted_generating" : "submitted", generation), await contextFromPage(page));
+            }
+            const turnAdvanced = previousTurnCount !== undefined && turnCount !== undefined && turnCount > previousTurnCount;
+            if (turnAdvanced || generation.active) {
+                return resultOk(submitData(undefined, turnCount, generation.active ? "submitted_generating" : "submitted_unconfirmed", generation), await contextFromPage(page), ["Submitted prompt could not be matched to a rendered user turn yet, but ChatGPT page state indicates progress."]);
             }
             return {
                 ok: false,
@@ -109,7 +119,7 @@ export async function submitMessage(env, args = {}) {
                 context: await contextFromPage(page)
             };
         }
-        return resultOk(submitData(userTurn, await countPageMessages(page).catch(() => undefined)), await contextFromPage(page));
+        return resultOk(submitData(userTurn, await countPageMessages(page).catch(() => undefined), "submitted", await readAssistantGenerationState(page).catch(() => EMPTY_GENERATION_STATE)), await contextFromPage(page));
     }
     catch (error) {
         return resultError(error instanceof Error ? error : new Error(String(error)), await contextFromPage(page));
@@ -222,7 +232,16 @@ async function readVisibleTextForSubmit(page) {
     if (typeof page.evaluate !== "function") {
         return undefined;
     }
-    return page.evaluate(() => document.body?.innerText ?? "");
+    // Attachment/upload status renders inside the composer form; prefer that region over
+    // the whole page so the not-ready poll does not serialize the full document text.
+    return page.evaluate(() => {
+        const composerForm = document.querySelector("main form") ?? document.querySelector("form");
+        const scopedText = composerForm?.innerText;
+        if (scopedText !== undefined && scopedText.trim().length > 0) {
+            return scopedText;
+        }
+        return document.body?.innerText ?? "";
+    });
 }
 async function sendTimeoutWarnings(page) {
     const state = await readSendButtonState(page).catch(() => undefined);
@@ -259,76 +278,135 @@ export async function waitForMessage(env, args = {}) {
     const stableMs = args.stableMs ?? (args.mode === "deep_research" ? 10_000 : 2_000);
     const pollMs = args.pollMs ?? 750;
     const started = Date.now();
-    let lastTargetText = "";
+    const deadline = createDeadline(timeoutMs, started);
+    const probeTimeoutMs = Math.max(50, Math.min(1000, Math.max(pollMs, Math.floor(timeoutMs / 4))));
+    const waitWarnings = new Set();
+    // One combined DOM probe per poll: counts, latest-text metadata, generation state, and
+    // response actions come back in a single evaluate, sampled from the same DOM instant.
+    // The full assistant text never crosses the bridge during polling; it is fetched once
+    // at loop exit. Page-state blocker scans run on a coarser cadence below.
+    const waitSnapshotProbe = createSingleFlightProbe("wait snapshot", readWaitDomSnapshot);
+    const pageStateProbe = createSingleFlightProbe("page state", readPageState);
+    const PAGE_STATE_POLL_STRIDE = 4;
+    let pollIndex = 0;
+    let lastTargetKey = "";
     let lastChangedAt = Date.now();
+    let lastObservedTextLength = 0;
     let latestAssistantCount = await countPageMessages(page, "assistant").catch(() => 0);
+    let lastGeneration = EMPTY_GENERATION_STATE;
     while (Date.now() - started < timeoutMs) {
-        const state = await readPageState(page).catch(() => undefined);
-        if (state?.blocker !== undefined && state.blocker.kind !== "modal") {
-            return {
-                ok: false,
-                status: "blocked",
-                warnings: [],
-                blocker: state.blocker,
-                context: await contextFromPage(page)
-            };
-        }
-        const progress = await readAssistantProgressSnapshot(page)
-            .catch(() => fallbackAssistantProgressSnapshot(page, latestAssistantCount));
-        latestAssistantCount = progress.assistantTurnCount;
-        const targetReached = waitTargetReached(args, progress);
-        const latestText = targetReached ? normalizeWhitespace(progress.latestText ?? "") : "";
-        if (latestText !== lastTargetText) {
-            lastTargetText = latestText;
+        const probeResult = await waitSnapshotProbe(page, deadline, { timeoutMs: probeTimeoutMs });
+        addWarnings(waitWarnings, probeResult.warnings);
+        const snapshot = await waitSnapshotFromProbeResult(page, probeResult, latestAssistantCount);
+        latestAssistantCount = snapshot.assistantTurnCount;
+        const targetReached = waitTargetReached(args, snapshot);
+        const targetKey = targetReached && snapshot.text.length > 0
+            ? `${snapshot.text.length}:${snapshot.text.hash}`
+            : "";
+        if (targetKey !== lastTargetKey) {
+            lastTargetKey = targetKey;
             lastChangedAt = Date.now();
         }
-        const snapshot = {
-            latestText,
-            stableMs,
-            textStableForMs: Date.now() - lastChangedAt,
-            generation: await readAssistantGenerationState(page),
-            hasResponseActions: await latestAssistantTurnHasResponseActions(page)
-        };
-        if (targetReached && snapshot.generation.stopped && latestText.length > 0) {
+        if (targetReached && snapshot.text.length > 0) {
+            lastObservedTextLength = snapshot.text.length;
+        }
+        if (pollIndex % PAGE_STATE_POLL_STRIDE === 0) {
+            const state = await pageStateFromProbe(pageStateProbe(page, deadline, { timeoutMs: probeTimeoutMs }), waitWarnings);
+            if (state?.blocker !== undefined && state.blocker.kind !== "modal") {
+                return {
+                    ok: false,
+                    status: "blocked",
+                    warnings: [...waitWarnings],
+                    blocker: state.blocker,
+                    context: await contextFromPage(page)
+                };
+            }
+        }
+        pollIndex += 1;
+        const hasResponseActions = await resolveResponseActions(page, snapshot);
+        lastGeneration = snapshot.generation;
+        if (targetReached && snapshot.generation.stopped && snapshot.text.length > 0) {
+            const stoppedText = normalizeWhitespace(await fetchLatestAssistantText(page) ?? "");
+            // A failed re-read must not fabricate an empty capture: real text was observed in
+            // the snapshot, so omit response content entirely and tell the caller how to get it.
+            const data = stoppedText.length > 0
+                ? waitDataFromText(args, false, stoppedText, latestAssistantCount, Date.now() - started)
+                : waitDataWithoutText(latestAssistantCount, Date.now() - started);
+            data.completionState = "stopped";
+            data.generationActive = snapshot.generation.active;
+            data.generationSignals = snapshot.generation.signals;
+            if (stoppedText.length === 0) {
+                waitWarnings.add(`The interrupted assistant text (~${snapshot.text.length} chars observed) could not be re-read at wait exit; call messages.readLatest on the same thread to capture it.`);
+            }
             return withCommandOutputText({
                 ok: false,
                 status: "partial",
-                data: {
-                    complete: false,
-                    responseText: latestText,
-                    assistantTurnCount: latestAssistantCount,
-                    elapsedMs: Date.now() - started
-                },
+                data,
                 warnings: [
+                    ...waitWarnings,
+                    ...(stoppedText.length > 0 ? responseContentWarnings(args, false) : []),
                     "ChatGPT generation appears to have been stopped or interrupted before completion.",
                     ...snapshot.generation.signals.map(signal => `Generation state signal: ${signal}`)
                 ],
                 context: await contextFromPage(page)
             });
         }
-        if (targetReached && isResponseComplete(snapshot)) {
-            return withCommandOutputText(resultOk({ complete: true, responseText: latestText, assistantTurnCount: latestAssistantCount, elapsedMs: Date.now() - started }, await contextFromPage(page)));
+        const metadataComplete = targetReached
+            && snapshot.text.length > 0
+            && !snapshot.text.transient
+            && Date.now() - lastChangedAt >= stableMs
+            && !snapshot.generation.active
+            && !snapshot.generation.stopped
+            && hasResponseActions;
+        if (metadataComplete) {
+            // Fetch the text once and confirm it still matches the stable snapshot before
+            // declaring completion; a hash mismatch means the answer moved on mid-fetch.
+            const latestText = normalizeWhitespace(await fetchLatestAssistantText(page) ?? "");
+            const fetchedMetadata = waitTextMetadata(latestText);
+            const completionSnapshot = {
+                latestText,
+                stableMs,
+                textStableForMs: Date.now() - lastChangedAt,
+                generation: snapshot.generation,
+                hasResponseActions
+            };
+            if (fetchedMetadata.hash === snapshot.text.hash && isResponseComplete(completionSnapshot)) {
+                const data = waitDataFromText(args, true, latestText, latestAssistantCount, Date.now() - started);
+                data.completionState = "complete";
+                data.generationActive = false;
+                data.generationSignals = snapshot.generation.signals;
+                return withCommandOutputText(resultOk(data, await contextFromPage(page), [...waitWarnings, ...responseContentWarnings(args, true)]));
+            }
+            if (latestText.length > 0) {
+                lastTargetKey = `${fetchedMetadata.length}:${fetchedMetadata.hash}`;
+                lastChangedAt = Date.now();
+                lastObservedTextLength = fetchedMetadata.length;
+            }
         }
         await sleep(page, pollMs);
     }
-    if (lastTargetText.length > 0) {
-        return withCommandOutputText({
-            ok: false,
-            status: "partial",
-            data: {
-                complete: false,
-                responseText: lastTargetText,
-                assistantTurnCount: latestAssistantCount,
-                elapsedMs: Date.now() - started
-            },
-            warnings: ["Timed out after receiving partial assistant text."],
-            context: await contextFromPage(page)
-        });
+    if (lastObservedTextLength > 0) {
+        const partialText = await fetchLatestAssistantText(page);
+        if (partialText !== undefined && normalizeWhitespace(partialText).length > 0) {
+            const normalizedPartialText = normalizeWhitespace(partialText);
+            const data = waitDataFromText(args, false, normalizedPartialText, latestAssistantCount, Date.now() - started);
+            data.completionState = completionStateFromGeneration(lastGeneration, false, normalizedPartialText.length > 0);
+            data.generationActive = lastGeneration.active;
+            data.generationSignals = lastGeneration.signals;
+            return withCommandOutputText({
+                ok: false,
+                status: "partial",
+                data,
+                warnings: [...waitWarnings, ...responseContentWarnings(args, false), "Timed out after receiving partial assistant text."],
+                context: await contextFromPage(page)
+            });
+        }
+        waitWarnings.add(`Partial assistant text (${lastObservedTextLength} chars) was observed during polling but could not be re-read at wait exit.`);
     }
     return {
         ok: false,
         status: "timeout",
-        warnings: [],
+        warnings: [...waitWarnings],
         error: {
             name: "WaitTimeout",
             message: "No assistant response appeared before the timeout.",
@@ -337,6 +415,107 @@ export async function waitForMessage(env, args = {}) {
         context: await contextFromPage(page)
     };
 }
+async function fetchLatestAssistantText(page) {
+    const first = await readLatestMessageText(page, "assistant").catch(() => undefined);
+    if (first !== undefined) {
+        return first;
+    }
+    // One retry: exit-time reads race DOM reflow/navigation, and a transient failure here
+    // would otherwise discard an answer the polling snapshots proved exists.
+    await sleep(page, 150);
+    return readLatestMessageText(page, "assistant").catch(() => undefined);
+}
+function waitDataWithoutText(assistantTurnCount, elapsedMs) {
+    return { complete: false, assistantTurnCount, elapsedMs };
+}
+async function resolveResponseActions(page, snapshot) {
+    if (snapshot.hasResponseActions !== undefined) {
+        return snapshot.hasResponseActions;
+    }
+    // No conversation-turn markers: fall back to the structural copy-button locator, as
+    // the standalone response-actions probe does.
+    try {
+        const copyButtons = copyResponseButtons(page);
+        const count = await copyButtons.count?.();
+        if (count !== undefined) {
+            return count > 0;
+        }
+        return await copyButtons.isVisible?.() === true;
+    }
+    catch {
+        return false;
+    }
+}
+async function waitSnapshotFromProbeResult(page, result, previousAssistantTurnCount) {
+    if (result.ok && result.value !== undefined) {
+        return result.value;
+    }
+    if (!result.ok && (result.timedOut === true || result.skipped === true)) {
+        return {
+            turnCount: 0,
+            assistantTurnCount: previousAssistantTurnCount,
+            text: waitTextMetadata(""),
+            generation: EMPTY_GENERATION_STATE,
+            hasResponseActions: false
+        };
+    }
+    return fallbackWaitSnapshot(page, previousAssistantTurnCount);
+}
+/**
+ * Degraded snapshot for pages where the combined evaluate is unavailable or failed.
+ * Reuses the standalone facet probes, which carry their own content/locator fallbacks;
+ * text metadata is computed SDK-side from the extracted text.
+ */
+async function fallbackWaitSnapshot(page, previousAssistantTurnCount) {
+    const progress = await fallbackAssistantProgressSnapshot(page, previousAssistantTurnCount);
+    const generation = await readAssistantGenerationState(page).catch(() => EMPTY_GENERATION_STATE);
+    const hasResponseActions = await latestAssistantTurnHasResponseActions(page).catch(() => false);
+    const snapshot = {
+        turnCount: progress.turnCount ?? 0,
+        assistantTurnCount: progress.assistantTurnCount,
+        text: waitTextMetadata(progress.latestText),
+        generation,
+        hasResponseActions
+    };
+    if (progress.latestAssistantTurnIndex !== undefined) {
+        snapshot.latestAssistantTurnIndex = progress.latestAssistantTurnIndex;
+    }
+    return snapshot;
+}
+function waitDataFromText(args, complete, responseText, assistantTurnCount, elapsedMs) {
+    const data = {
+        complete,
+        assistantTurnCount,
+        elapsedMs
+    };
+    if (args.responseContent === "metadata") {
+        data.responseContent = "metadata";
+        data.responseChars = responseText.length;
+        data.responseSha256 = createHash("sha256").update(responseText).digest("hex");
+        return data;
+    }
+    data.responseText = responseText;
+    return data;
+}
+function responseContentWarnings(args, complete) {
+    if (args.responseContent !== "metadata")
+        return [];
+    return [
+        complete
+            ? "Assistant response text was omitted because responseContent is metadata; call readLatest to capture the completed answer."
+            : "Partial assistant text was omitted because responseContent is metadata; call wait again on the same thread or readLatest after completion."
+    ];
+}
+async function pageStateFromProbe(probe, warnings) {
+    const result = await probe;
+    addWarnings(warnings, result.warnings);
+    return result.ok ? result.value : undefined;
+}
+function addWarnings(target, warnings) {
+    for (const warning of warnings) {
+        target.add(warning);
+    }
+}
 export async function readLatest(env, args = {}) {
     const boot = await ensurePage(env);
     if (!boot.ok) {
@@ -391,9 +570,51 @@ export async function readLatest(env, args = {}) {
         data.thoughtDurationText = latest.thoughtDurationText;
     if (latest.sourcesAvailable !== undefined)
         data.sourcesAvailable = latest.sourcesAvailable;
+    if (role === "assistant") {
+        const generation = await readAssistantGenerationState(page).catch(() => EMPTY_GENERATION_STATE);
+        data.completionState = completionStateFromGeneration(generation, undefined, latest.text.trim().length > 0);
+        data.generationActive = generation.active;
+        data.generationSignals = generation.signals;
+    }
     return withCommandOutputText(resultOk(data, await contextFromPage(page), data.warnings ?? []));
 }
+export async function messageStatus(env, args = {}) {
+    const boot = await ensurePage(env);
+    if (!boot.ok) {
+        return boot;
+    }
+    const page = env.page;
+    // Reuse the combined wait-snapshot evaluate for counts and generation state in a single
+    // round trip; it never carries full assistant text, so a bounded preview is fetched
+    // separately below only when the snapshot proves an assistant turn has text.
+    const snapshot = await readWaitDomSnapshot(page).catch(() => undefined) ?? await fallbackWaitSnapshot(page, 0);
+    const maxPreviewChars = Math.max(0, args.maxPreviewChars ?? 240);
+    const latestText = snapshot.text.length > 0
+        ? normalizeWhitespace(await fetchLatestAssistantText(page) ?? "")
+        : "";
+    const data = {
+        turnCount: snapshot.turnCount,
+        assistantTurnCount: snapshot.assistantTurnCount,
+        completionState: completionStateFromGeneration(snapshot.generation, undefined, latestText.length > 0),
+        generationActive: snapshot.generation.active,
+        generationSignals: snapshot.generation.signals
+    };
+    if (snapshot.latestAssistantTurnIndex !== undefined)
+        data.latestAssistantTurnIndex = snapshot.latestAssistantTurnIndex;
+    if (latestText.length > 0) {
+        data.latestAssistantTextLength = latestText.length;
+        data.latestAssistantPreview = latestText.length > maxPreviewChars
+            ? `${latestText.slice(0, Math.max(0, maxPreviewChars - 1))}...`
+            : latestText;
+    }
+    return resultOk(data, await contextFromPage(page));
+}
 export async function askMessage(env, args) {
+    const normalizedPrompt = normalizeAskPrompt(args);
+    if (!normalizedPrompt.ok) {
+        return normalizedPrompt.result;
+    }
+    const prompt = normalizedPrompt.text;
     const boot = await ensurePage(env);
     if (!boot.ok) {
         return boot;
@@ -401,7 +622,7 @@ export async function askMessage(env, args) {
     const page = env.page;
     const beforeTurnCount = await countPageMessages(page).catch(() => undefined);
     const beforeAssistantTurnCount = await countPageMessages(page, "assistant").catch(() => undefined);
-    const composeArgs = { text: args.text, mode: "replace" };
+    const composeArgs = { text: prompt, mode: "replace" };
     if (args.timeoutMs !== undefined) {
         composeArgs.timeoutMs = args.timeoutMs;
     }
@@ -409,7 +630,7 @@ export async function askMessage(env, args) {
     if (!compose.ok) {
         return forwardFailure(compose);
     }
-    const submitArgs = { text: args.text };
+    const submitArgs = { text: prompt };
     if (beforeTurnCount !== undefined) {
         submitArgs.previousTurnCount = beforeTurnCount;
     }
@@ -466,7 +687,7 @@ export async function askMessage(env, args) {
         return forwardFailure(waitFailure);
     }
     const state = await readPageState(page).catch(() => undefined);
-    const data = { prompt: args.text };
+    const data = { prompt };
     const complete = waitResult?.data?.complete ?? (waitResult === undefined ? undefined : false);
     if (complete !== undefined) {
         data.complete = complete;
@@ -480,6 +701,7 @@ export async function askMessage(env, args) {
     if (state?.title !== undefined) {
         data.title = state.title;
     }
+    applyMessageState(data, submit.data, waitResult?.data);
     if (waitFailure !== undefined) {
         data.complete = false;
         return withCommandOutputText({
@@ -517,7 +739,7 @@ export async function waitAndRead(env, args = {}) {
         }
         return forwardFailure(read);
     }
-    const data = askReadData("", read.data?.text, wait.data?.complete);
+    const data = askReadData("", read.data?.text, wait.data?.complete, wait.data, read.data);
     const warnings = [...read.warnings, ...wait.warnings];
     if (!wait.ok && wait.status === "partial") {
         data.complete = false;
@@ -534,12 +756,6 @@ export async function waitAndRead(env, args = {}) {
     }
     return withCommandOutputText(resultOk(data, read.context, warnings));
 }
-async function ensurePage(env) {
-    if (env.page !== undefined) {
-        return resultOk({}, await contextFromPage(env.page));
-    }
-    return bootstrap(env, { preferExistingTab: true });
-}
 async function waitForSubmittedUserTurn(page, text, previousTurnCount, timeoutMs) {
     const started = Date.now();
     const wanted = text === undefined ? undefined : normalizeWhitespace(text);
@@ -601,27 +817,6 @@ function renderSubmittedTurnMarkdownSyntax(text, preserveFenceLanguage = true) {
         .replace(/\*([^*]+)\*/g, "$1")
         .replace(/_([^_]+)_/g, "$1");
 }
-async function readAssistantProgressSnapshot(page) {
-    if (typeof page.evaluate === "function") {
-        return page.evaluate(() => {
-            const nodes = Array.from(document.querySelectorAll("[data-message-author-role]"));
-            const assistantNodes = nodes.filter(node => node.getAttribute("data-message-author-role") === "assistant");
-            const latestAssistant = assistantNodes.at(-1);
-            const latestAssistantTurnIndex = latestAssistant === undefined ? undefined : nodes.indexOf(latestAssistant) + 1;
-            const snapshot = {
-                turnCount: nodes.length,
-                assistantTurnCount: assistantNodes.length
-            };
-            const latestText = latestAssistant?.innerText ?? latestAssistant?.textContent ?? undefined;
-            if (latestText !== undefined)
-                snapshot.latestText = latestText;
-            if (latestAssistantTurnIndex !== undefined)
-                snapshot.latestAssistantTurnIndex = latestAssistantTurnIndex;
-            return snapshot;
-        });
-    }
-    return fallbackAssistantProgressSnapshot(page, 0);
-}
 async function fallbackAssistantProgressSnapshot(page, previousAssistantTurnCount) {
     const messages = await readMessages(page, { format: "normalized_text" }).catch(() => undefined);
     if (messages !== undefined) {
@@ -680,7 +875,7 @@ async function sleep(page, ms) {
     }
     await new Promise(resolve => setTimeout(resolve, ms));
 }
-function submitData(userTurnText, turnCount) {
+function submitData(userTurnText, turnCount, submissionState, generation) {
     const data = { submitted: true };
     if (userTurnText !== undefined) {
         data.userTurnText = userTurnText;
@@ -688,9 +883,13 @@ function submitData(userTurnText, turnCount) {
     if (turnCount !== undefined) {
         data.turnCount = turnCount;
     }
+    data.submissionState = submissionState;
+    data.completionState = completionStateFromGeneration(generation);
+    data.generationActive = generation.active;
+    data.generationSignals = generation.signals;
     return data;
 }
-function askReadData(prompt, responseText, complete) {
+function askReadData(prompt, responseText, complete, wait, read) {
     const data = { prompt };
     if (responseText !== undefined) {
         data.responseText = responseText;
@@ -698,8 +897,71 @@ function askReadData(prompt, responseText, complete) {
     if (complete !== undefined) {
         data.complete = complete;
     }
+    applyMessageState(data, undefined, wait, read);
     return data;
 }
+function applyMessageState(data, submit, wait, read) {
+    if (submit?.submissionState !== undefined)
+        data.submissionState = submit.submissionState;
+    const completionState = wait?.completionState ?? read?.completionState ?? submit?.completionState;
+    if (completionState !== undefined)
+        data.completionState = completionState;
+    const generationActive = wait?.generationActive ?? read?.generationActive ?? submit?.generationActive;
+    if (generationActive !== undefined)
+        data.generationActive = generationActive;
+    const generationSignals = wait?.generationSignals ?? read?.generationSignals ?? submit?.generationSignals;
+    if (generationSignals !== undefined)
+        data.generationSignals = generationSignals;
+}
+function completionStateFromGeneration(generation, complete, hasPartialText = false) {
+    if (complete === true)
+        return "complete";
+    if (generation.active)
+        return "generating";
+    if (generation.stopped)
+        return "stopped";
+    if (complete === false || hasPartialText)
+        return "partial";
+    return "unknown";
+}
+function normalizeAskPrompt(args) {
+    const text = args.text;
+    const prompt = args.prompt;
+    if (text !== undefined && prompt !== undefined && text !== prompt) {
+        return {
+            ok: false,
+            result: {
+                ok: false,
+                status: "error",
+                warnings: [],
+                error: {
+                    name: "InvalidAskArgs",
+                    message: "messages.ask received both text and prompt with different values.",
+                    recoverable: false
+                },
+                context: { timestamp: new Date().toISOString() }
+            }
+        };
+    }
+    const normalized = text ?? prompt;
+    if (normalized === undefined || normalized.trim().length === 0) {
+        return {
+            ok: false,
+            result: {
+                ok: false,
+                status: "error",
+                warnings: [],
+                error: {
+                    name: "InvalidAskArgs",
+                    message: "messages.ask requires a non-empty text or prompt argument.",
+                    recoverable: false
+                },
+                context: { timestamp: new Date().toISOString() }
+            }
+        };
+    }
+    return { ok: true, text: normalized };
+}
 function readRole(read) {
     return typeof read === "object" ? read.role : undefined;
 }

package/dist/src/commands/modes.d.ts

@@ -1,8 +1,11 @@
-import type { CommandResult, RuntimeEnv, SelectToolArgs, SetModeArgs } from "../types.js";
+import type { CommandResult, GetModeArgs, RuntimeEnv, SelectToolArgs, SetModeArgs } from "../types.js";
 export declare function setMode(env: RuntimeEnv, args: SetModeArgs): Promise<CommandResult<{
     selected: string[];
     candidates: string[];
 }>>;
+export declare function getMode(env: RuntimeEnv, args?: GetModeArgs): Promise<CommandResult<{
+    modes: string[];
+}>>;
 export declare function selectTool(env: RuntimeEnv, args: SelectToolArgs): Promise<CommandResult<{
     selected?: string;
     candidates: string[];