@youdie006/prodex 0.23.0 → 0.24.0

package/dist/chatgpt-browser.js

@@ -3082,6 +3082,7 @@ export function transcriptAnswerExpression(conversationId) {
 }
 // ChatGPT marks citations with private-use delimiters (U+E200 opens, U+E202
 // separates, U+E201 closes) and keeps the real sources in content_references.
+const CITATION_DELIMITER_PATTERN = /[\uE200-\uE206]/;
 const CITATION_MARKER_PATTERN = /\uE200[^\uE200-\uE206]*(?:[\uE202\uE204-\uE206][^\uE200-\uE206]*)*[\uE201\uE203]/g;
 /**
  * Turn those markers into ordinary markdown links, so a saved answer keeps the
@@ -3091,7 +3092,11 @@ const CITATION_MARKER_PATTERN = /\uE200[^\uE200-\uE206]*(?:[\uE202\uE204-\uE206]
 export function resolveTranscriptCitations(text, references = []) {
     const byMarker = new Map();
     for (const reference of references) {
-        if (reference && typeof reference.matched_text === "string" && reference.matched_text.length > 0) {
+        // Only substitute on text that IS a marker. A `sources_footnote` reference
+        // carries matched_text " " - a single space - and substituting on that
+        // replaced every space in the document, fusing a 47k-character report into
+        // one run-on word.
+        if (reference && typeof reference.matched_text === "string" && CITATION_DELIMITER_PATTERN.test(reference.matched_text)) {
             byMarker.set(reference.matched_text, reference);
         }
     }

package/dist/cli-help.js

@@ -257,6 +257,14 @@ export function printProBrowserHelp(stdout, sourceCli) {
     const modelsUsage = sourceCli
         ? `${cli} pro browser models${sourceCliOption} [--port 9333] [--timeout-ms 15000]`
         : "prodex pro browser models [--source-cli /absolute/path/to/dist/cli.js] [--port 9333] [--timeout-ms 15000]";
+    const projectsUsage = sourceCli
+        ? `${cli} pro browser projects${sourceCliOption} [--port 9333] [--timeout-ms 15000]  # read-only: exact sidebar project names`
+        : "prodex pro browser projects [--source-cli /absolute/path/to/dist/cli.js] [--port 9333] [--timeout-ms 15000]  # read-only: exact sidebar project names";
+    // A send that outlives its budget is not a lost answer, but only if agents
+    // know this exists - and this help is where onboarding sends them.
+    const recoverUsage = sourceCli
+        ? `${cli} pro browser recover${sourceCliOption} [--cwd /absolute/path/to/repo] [--port 9333] --target-url <thread-url> [--timeout-ms 60000]  # fetch a finished answer (deep research reports too) from a thread whose send timed out`
+        : "prodex pro browser recover [--source-cli /absolute/path/to/dist/cli.js] [--cwd /absolute/path/to/repo] [--port 9333] --target-url <thread-url> [--timeout-ms 60000]  # fetch a finished answer (deep research reports too) from a thread whose send timed out";
     stdout(`${cli} pro browser
 
 Commands:
@@ -264,7 +272,9 @@ Commands:
   ${checkUsage}
   ${smokeUsage}
   ${modelsUsage}
+  ${projectsUsage}
   ${askUsage}
+  ${recoverUsage}
 
 Visible-browser sends require a manual browser session and stop on login, captcha, Cloudflare, permission, rate-limit, or usage-limit blockers.
 Model/project selection (ask):

package/dist/cli-pro.js

@@ -1155,12 +1155,36 @@ Rules:
 Write the debate in the language of the topic.`;
 }
 /**
- * MCP-facing wrapper around the visible-browser ask flow. Reuses the full CLI
- * path (send pacing, task/session/receipt persistence, artifact save) by
- * invoking runAskProCommand with captured io, then returns structured fields
- * instead of printed lines. Registered only on the local stdio MCP server -
- * never on the HTTP MCP surface, which is exposed to ChatGPT itself.
+ * MCP-side counterpart to `pro browser recover`. A consult that outlives its
+ * budget hands back the thread it landed in, but until now the only way to act
+ * on that was a shell command - which an agent reaching prodex over MCP may not
+ * be able to run. Recovery has to be reachable the same way the consult was.
  */
+export async function performBrowserRecoverForMcp(cwd, input) {
+    const stdoutLines = [];
+    const stderrLines = [];
+    const argv = [
+        "browser",
+        "recover",
+        "--target-url",
+        input.thread,
+        ...(input.timeout_ms !== undefined ? ["--timeout-ms", String(input.timeout_ms)] : [])
+    ];
+    await runProCommand(argv, {
+        cwd,
+        stdout: (line) => stdoutLines.push(line),
+        stderr: (line) => stderrLines.push(line)
+    }, async () => 0);
+    const header = stdoutLines[0] ?? "";
+    const [taskId = "", status = "", thread = ""] = header.split("\t");
+    return {
+        task_id: taskId,
+        status,
+        thread,
+        answer: stdoutLines.slice(2).join("\n"),
+        notes: stderrLines
+    };
+}
 export async function performBrowserConsultForMcp(cwd, input, onProgress) {
     const stdoutLines = [];
     const stderrLines = [];

package/dist/cli.js

@@ -19,7 +19,7 @@ import { printHelpIfRequested, assertNoExtraArgs, assertOnlyOptions, formatCliCo
 import { listRawResultsForInspection, listTasksForInspection, runReceiptsCommand, runResultsCommand, runSessionsCommand, runTasksCommand } from "./cli-ledger.js";
 import { isMissingFileError, errorMessage, formatBrowserCheckCommand, formatBrowserLoginCommand, formatInitCommand, formatReleaseStatusCommand, formatSetupCommand, sourceAwareReleaseMessage, sourceAwareSetupMessage } from "./cli-shared.js";
 import { TOKEN_BEARING_MCP_URL_AUTHORITY_WARNING, redactServerUrl, runInitCommand, runSetupCommand, runStartCommand, runStatusCommand, runTunnelCommand } from "./cli-server.js";
-import { assertNoMissingTerminalConsultResults, assertNoOrphanConsultResults, formatConfigWarningLine, isConsultRecord, performBrowserConsultForMcp, runAskProCommand, runChatgptCommand, runConsultsCommand, runProCommand } from "./cli-pro.js";
+import { assertNoMissingTerminalConsultResults, assertNoOrphanConsultResults, formatConfigWarningLine, isConsultRecord, performBrowserConsultForMcp, performBrowserRecoverForMcp, runAskProCommand, runChatgptCommand, runConsultsCommand, runProCommand } from "./cli-pro.js";
 import { CLI_VERSION, printClaudeHelp, printDoctorHelp, printHelp, printMcpHelp, printOnboardHelp, printProjectHelp, printReleaseHelp } from "./cli-help.js";
 const execFileAsync = promisify(execFile);
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -208,7 +208,8 @@ export async function runCli(args, io = defaultIo()) {
         // pro_consult is stdio-only: the HTTP MCP surface is exposed to ChatGPT
         // itself (and possibly a tunnel) and must never drive the user's browser.
         await runMcpServer(mcpCwd, {
-            browserConsult: (input, onProgress) => performBrowserConsultForMcp(mcpCwd, input, onProgress)
+            browserConsult: (input, onProgress) => performBrowserConsultForMcp(mcpCwd, input, onProgress),
+            browserRecover: (input) => performBrowserRecoverForMcp(mcpCwd, input)
         });
         return 0;
     }
@@ -322,11 +323,21 @@ repo: ${cwd}
    ${cli} pro browser check${sourceCliOption} --cwd ${quotedCwd}
    ${cli} pro browser smoke${sourceCliOption} --cwd ${quotedCwd}
    Sharing the browser with other agents? Sends queue behind an in-flight response automatically; pass --busy-wait-ms 0 to fail fast instead.
+   Hand ChatGPT a real file - the only way it can open a pdf, pptx, xlsx or image:
+   ${cli} ask --cwd ${quotedCwd} --attach deck.pptx "Review slides 40-60"  # uploads the file itself
+   ${cli} ask --cwd ${quotedCwd} --file notes.md "Summarize"  # pastes a text file's CONTENTS into the prompt
+   Both are restricted to paths inside the repo. Repeat either flag for several files.
+   Turn on a composer tool for one send:
+   ${cli} ask --cwd ${quotedCwd} --tool web-search "What shipped in Node 24?"  # current facts with sources
+   ${cli} ask --cwd ${quotedCwd} --tool deep-research "Compare managed Postgres providers"  # full browsed report; runs ~10 minutes, budget rises to 30
+   Any other label the composer menu shows works too, so a tool ChatGPT adds later needs no prodex release.
+   A send that outlives its budget did not lose the answer - ChatGPT usually finishes after prodex stops waiting:
+   ${cli} pro browser recover --target-url <thread-url> --cwd ${quotedCwd}  # fetches the finished answer (deep research reports too) and records it
 
 2. Let coding agents consult ChatGPT (stdio MCP: Claude, Codex, Cursor, ...):
    ${cli} claude config --cwd ${quotedCwd}${sourceCliOption}
    ${cli} claude prompt --cwd ${quotedCwd}${sourceCliOption}
-   Agents get the bridge/ledger tools plus pro_consult (ask ChatGPT Pro directly; see docs/clients.md for Codex timeout and approval notes).
+   Agents get the bridge/ledger tools plus pro_consult (ask ChatGPT Pro directly; see docs/clients.md for Codex timeout and approval notes) and pro_recover (collect an answer that finished after a consult stopped waiting - including a deep research report).
    Saved setup defaults (--model/--project) apply to agent consults too - pin them once per repo so consults stop landing in the general chat list.
    Agents often run the MCP as \`prodex mcp\` with no --cwd, which misses a per-repo default. For a default that applies from ANY directory, set PRODEX_DEFAULT_PROJECT and PRODEX_DEFAULT_MODEL (in the agent's MCP env block, or your shell) to YOUR project/model. No project? Consults just go to the general chat. List your exact project names with \`${cli} pro browser projects\`.
    ${cli} pro debate-prompt --topic "your question"${sourceCliOption}  # structured GPT Pro debate prompt for your agent

package/dist/mcp.js

@@ -154,7 +154,7 @@ export function createServer(cwd = process.cwd(), options = {}) {
                     .array(McpShortTextSchema)
                     .max(4)
                     .optional()
-                    .describe("ChatGPT composer tools to enable for this consult: \"deep-research\" (a multi-minute browsed report - the timeout rises to 30 minutes automatically), \"web-search\" (current facts), \"create-image\". Deep research often replies with a CLARIFYING QUESTION first; answer it with a normal follow-up consult in the same thread."),
+                    .describe("ChatGPT composer tools to enable for this consult: \"deep-research\" (a browsed report; prodex presses start and waits out the run, which takes about ten minutes, so the timeout rises to 30 minutes automatically and the FULL report comes back as the answer - if the budget still runs out, the blocker carries the thread and pro_recover collects the report later), \"web-search\" (current facts, with the sources kept as links), \"create-image\". Deep research sometimes replies with a CLARIFYING QUESTION instead; answer it with a normal follow-up consult in the same thread."),
                 attach: z
                     .array(McpShortTextSchema)
                     .max(10)
@@ -187,6 +187,16 @@ export function createServer(cwd = process.cwd(), options = {}) {
             return asText(await browserConsult(input, onProgress));
         });
     }
+    const browserRecover = options.browserRecover;
+    if (browserRecover) {
+        server.registerTool("pro_recover", {
+            description: "Fetch a ChatGPT answer that finished AFTER a consult stopped waiting, and record it as a normal consult receipt. Use this whenever pro_consult came back with a timeout or a still-running blocker: those carry the thread URL, and the answer is almost always sitting in that thread. This is also how a deep research report is collected - a research run takes about ten minutes and keeps going even when the consult that started it has already returned. Reading is cheap and does not send anything, so it is safe to retry.",
+            inputSchema: {
+                thread: McpShortTextSchema.min(1).describe("The ChatGPT conversation URL from the blocker (its `thread` field)."),
+                timeout_ms: z.number().int().positive().max(600_000).optional()
+            }
+        }, async (input) => asText(await browserRecover(input)));
+    }
     return server;
 }
 export async function runMcpServer(cwd = process.cwd(), options = {}) {

package/docs/claude.md

@@ -99,6 +99,7 @@ The server currently exposes ledger-first tools:
 - `repo_write_file_apply`
 - `repo_stage_reviewed_paths`
 - `pro_consult`
+- `pro_recover`
 
 `bridge_complete_task` and `bridge_block_task` close tasks by writing durable `.bridge/results` records; they do not modify repo files. `bridge_fetch_result_artifact` only returns text artifacts that are listed on a result record and stored under `.bridge/artifacts/pro-consults/` or `.bridge/artifacts/results/`; it does not expose arbitrary `.bridge/artifacts` files. Newly finalized result artifacts record a sha256, and fetch rejects the artifact if its content changed afterward. The bridge rejects oversized result artifacts before task finalization; if a Pro browser answer is too large for `bridge_fetch_result_artifact`, it stays in the result summary with `answer_artifact_warning` instead of listing an unfetchable artifact.
 
@@ -106,7 +107,9 @@ Write tools are narrow and receipt-gated, and they require a git worktree with a
 
 `pro_consult` lets Claude ask your logged-in ChatGPT (Pro) directly: it drives the same explicit visible-browser consult as `prodex pro browser ask` (human-paced, blocker-gated, receipt-recorded, answer saved under `.bridge/artifacts/pro-consults/`) and can take minutes for Pro extended reasoning. It requires a prior `prodex pro browser login` session and is registered only on the local stdio MCP server — the HTTP MCP surface never exposes it, so nothing reachable through a tunnel or ChatGPT itself can drive your browser.
 
-No shell, public tunnel, direct ungated write, or direct ungated staging tools are exposed through the Claude stdio MCP server; the only browser-facing tool is the explicit `pro_consult` consult described above.
+`pro_recover` collects an answer that finished after a consult stopped waiting. A timed-out or still-running consult returns the thread it landed in, and the answer is almost always sitting there; this is also how a deep research report is collected, since a research run keeps going after the consult that started it has returned. It reads a thread and sends nothing, so retrying it is safe. Like `pro_consult`, it is registered only on the local stdio MCP server.
+
+No shell, public tunnel, direct ungated write, or direct ungated staging tools are exposed through the Claude stdio MCP server; the only browser-facing tools are the explicit `pro_consult` consult and the read-only `pro_recover` described above.
 
 ## First Prompt
 

package/docs/clients.md

@@ -48,6 +48,13 @@ consult you expect. Claude Code needs no change: its default stdio tool
 timeout is effectively unlimited (~28h) unless you tightened `MCP_TOOL_TIMEOUT`
 or a per-server `"timeout"`.
 
+A deep research consult (`tools: ["deep-research"]`) is the longest of these:
+the run takes about ten minutes and prodex raises its own budget to 30, so a
+client timeout below that aborts the call while the research keeps going. That
+is recoverable rather than lost - `pro_recover` with the thread from the
+blocker collects the report afterwards - but a client budget that covers the
+run avoids the round trip.
+
 Approval gate (verified on Codex 0.142.5): Codex asks for per-call approval
 before invoking prodex MCP tools. In interactive `codex` sessions you simply
 approve the prompt. In non-interactive `codex exec`, the approval cannot be

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youdie006/prodex",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Local receipt bus for coordinating Codex execution with ChatGPT Pro/Projects consultation.",
   "author": "youdie006",
   "license": "MIT",