@clien-ai/mcp 0.15.1 → 0.18.0

package/dist/tools/scoped-research.js

@@ -40,9 +40,10 @@ import { contentTypeProvenanceLine } from './content-type-display.js';
 import { publicationDateLine } from './publication-date-display.js';
 import { readSemanticTheme } from '../types/semantic-theme.js';
 import { apiCall, categorizeFetchError, promoteCompletedJob, webJobUrl, } from './research.js';
-import { safeInline, safeId, truncate, firstQuoteWithCount } from './render-safety.js';
+import { safeInline, safeId, safeFactValue, truncate, firstQuoteWithCount } from './render-safety.js';
 import { permanentFailureMessage } from './permanent-failure.js';
 import { OperationIdSchema, operationRetryHint, resolveOperationId } from './operation-id.js';
+import { buildDisambiguation, fetchRecentRuns } from './status.js';
 import { resolveMarketSignals, } from './market-signals.js';
 // Per-endpoint timeouts. Node fetch has no implicit timeout, so a hung endpoint would otherwise
 // wedge the MCP server forever (mirrors research.ts:START/EVENTS/REPORT_TIMEOUT_MS).
@@ -170,6 +171,27 @@ export const ScanMarketInputSchema = z.object({
         'discover competitors — use `scan_competitors` for the landscape.'),
     ...sharedScopedFields,
 });
+/**
+ * FUL-1144 — what a dropped scoped call can recover by.
+ *
+ * ⚠️ NO `operation_id` HERE, deliberately. There is no read endpoint that maps an operation id to
+ * a job: the only thing that resolves one is `POST /api/validate/scoped/start`, and a status tool
+ * must never be a POST that can start (and charge for) a run. A caller holding its operation_id
+ * already has the right tool — re-calling the SAME scoped tool with the SAME operation_id and
+ * inputs replays the committed start without a second charge and re-attaches to it.
+ */
+export const ScopedStatusInputSchema = z.object({
+    job_id: z
+        .string()
+        .uuid()
+        .optional()
+        .describe('UUID of the scoped run (scan_competitors / search_forums / scan_market) to check. ' +
+        'OPTIONAL — omit it when a dropped call left you without one: this tool then lists your ' +
+        'recent runs, each with its job_id and topic, so you can re-call with the one you were ' +
+        'running. Where the id IS readable: the error text of a call that failed or timed out ' +
+        'after starting. It is also printed to the MCP server stderr log as ' +
+        '`[clien-mcp] <tool> started job_id=<uuid>` — which reaches the human operator, not you.'),
+});
 export class ScopedResearchToolError extends ToolError {
 }
 const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -212,6 +234,192 @@ export async function scanMarket(input, deps) {
     }
     return runScopedResearchTool('market', parsed.data, deps);
 }
+/**
+ * `scoped_research_status` (FUL-1144) — recover a scoped run after a dropped call.
+ *
+ * The scoped tools are multi-minute synchronous calls; when the pipe drops mid-scan the job keeps
+ * running (and was paid for), but before this tool the caller had no way to read it back. This is
+ * the scoped counterpart of `clien_research_status`, built from the SAME pieces the live tools use
+ * so a recovered result cannot drift from a live one:
+ *
+ *   - state + refund truth: one drained `/events` snapshot through `pollScopedJob`. The refund
+ *     sentence is `scopedFailureText` → `buildFailureGuidance` over the server's own
+ *     `refundedCredits` / `refundPending` / `errorCategory` / `startedSandbox`; nothing is inferred.
+ *   - result: `fetchScopedReport` (the FUL-719 projection) → `buildScopedResult` (every renderer
+ *     and its render-safety guards), exactly as the live call would have returned it.
+ *   - persistence: the same idempotent `POST /promote` the live call ends with, so a run whose
+ *     call dropped before that step reaches the Research tab now rather than on the ~10-minute
+ *     sweep. The route answers `already_promoted` on a repeat.
+ *   - discovery: `fetchRecentRuns` + `buildDisambiguation` from `status.ts`.
+ */
+export async function getScopedResearchStatus(input, deps) {
+    const parsed = ScopedStatusInputSchema.safeParse(input ?? {});
+    if (!parsed.success) {
+        throw new ScopedResearchToolError(`Invalid input — ${formatZodError(parsed.error)}`);
+    }
+    const fetchImpl = deps.fetch ?? fetch;
+    const ctx = { config: deps.config, session: deps.session, fetch: fetchImpl };
+    let jobId = parsed.data.job_id;
+    if (!jobId) {
+        // ⚠️ NEVER AUTO-PICK FROM A LIST OF SEVERAL. `GET /api/validate` returns hero and scoped runs
+        // together with nothing to tell them apart (the summary row carries no mode), so "the one
+        // active run" may be a `clien_research` run while the scan the caller lost has already
+        // finished. Only a list of exactly one is unambiguous; anything else is shown, not guessed.
+        const jobs = await fetchRecentRuns(ctx, deps, 'scan_competitors, search_forums or scan_market');
+        const [only] = jobs;
+        if (!only || jobs.length > 1)
+            return buildDisambiguation(jobs, 'recent', SCOPED_STATUS_TOOL);
+        // A server-sent id: state it only if it can be stated exactly.
+        const serverId = safeId(only.id);
+        if (!serverId) {
+            throw new ScopedResearchToolError('Your one recent run came back with an unreadable job id. Please try again.');
+        }
+        jobId = serverId;
+    }
+    const poll = await pollScopedJob(ctx, jobId, {
+        sleep: deps.sleep ?? defaultSleep,
+        pollIntervalMs: deps.pollIntervalMs ?? deps.config.pollIntervalMs,
+        deadline: Number.POSITIVE_INFINITY,
+        onProgress: deps.onProgress,
+        invalidateSession: deps.invalidateSession,
+        label: 'Research run',
+        config: deps.config,
+        projectId: null,
+        snapshot: true,
+    });
+    const projectId = poll.projectId ?? null;
+    const jobLink = webJobUrl(deps.config, jobId, projectId);
+    const status = safeInline(poll.status, 40) ?? 'unknown';
+    const base = {
+        job_id: jobId,
+        status: poll.status,
+        project_id: projectId,
+        promoted: false,
+        promotion_error_code: null,
+        promotion_retryable: null,
+        report_data: null,
+        ...(poll.totalCostCents !== undefined ? { total_cost_cents: poll.totalCostCents } : {}),
+    };
+    if (!TERMINAL_STATUSES.has(poll.status)) {
+        const activity = poll.lastMessage ? ` Latest activity: ${poll.lastMessage}.` : '';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Job ${jobId} is still running (phase: "${status}").${activity} It keeps running on ` +
+                        `the server — do NOT start it again. Call ${SCOPED_STATUS_TOOL} with this same job_id ` +
+                        `in a minute or two, or view ${jobLink}.`,
+                },
+            ],
+            _meta: { ...base, done: false },
+        };
+    }
+    if (poll.status !== 'complete') {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Job ${jobId}: ${scopedFailureText({ label: 'Research run', noun: 'results' }, poll, jobLink)}`,
+                },
+            ],
+            _meta: {
+                ...base,
+                done: true,
+                ...(poll.errorCategory !== undefined ? { error_category: poll.errorCategory } : {}),
+                ...(poll.refundedCredits !== undefined ? { refunded_credits: poll.refundedCredits } : {}),
+                ...(poll.refundPending ? { refund_pending: true } : {}),
+            },
+        };
+    }
+    const { reportData, hasMarkdown } = await fetchScopedReport(ctx, jobId, deps.config, projectId);
+    // Only a full `clien_research` run writes report markdown. Its report owes the trust digest,
+    // which this tool does not render — so hand it to the tool that does rather than a partial view.
+    if (hasMarkdown) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Job ${jobId} is a full clien_research run, not a scoped scan. Call ` +
+                        'clien_research_status (or get_report) with this same job_id for its report and trust digest.',
+                },
+            ],
+            _meta: { ...base, done: true },
+        };
+    }
+    const mode = scopedModeOf(reportData);
+    if (!mode) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Job ${jobId} completed, but its stored result carries no competitor, community or ` +
+                        `market section, so there is nothing to show here. View ${jobLink}.`,
+                },
+            ],
+            _meta: { ...base, done: true, report_data: reportData },
+        };
+    }
+    const promotion = projectId ? await promoteScopedJob(ctx, jobId) : NO_PROMOTION;
+    const result = buildScopedResult({
+        mode,
+        jobId,
+        status: poll.status,
+        projectId,
+        promotion,
+        reportData,
+        // The list and events routes do not return the topic for a job id; the renderers fall back to
+        // "this topic" rather than printing a topic nobody stated.
+        topic: '',
+        totalCostCents: poll.totalCostCents,
+    });
+    const [first] = result.content;
+    return {
+        ...result,
+        content: [
+            {
+                type: 'text',
+                text: `Recovered ${MODE_META[mode].tool} job ${jobId} (complete).\n\n${first?.text ?? ''}`,
+            },
+        ],
+        _meta: { ...result._meta, done: true, mode },
+    };
+}
+const SCOPED_STATUS_TOOL = 'scoped_research_status';
+/**
+ * The drop-recovery paragraph every scoped tool's description ends with (FUL-1144). One function,
+ * so the three adverts cannot drift apart about how a paid, still-running scan is recovered.
+ */
+export function scopedDropRecoveryAdvert(tool) {
+    return ('IMPORTANT: if the call drops mid-flight with "MCP error -32000", the job keeps running on the ' +
+        'backend — do NOT start it again (a fresh call starts a new run and debits again). Recover it: ' +
+        `call \`${SCOPED_STATUS_TOOL}\` — with NO arguments it lists your recent runs (job_id + topic) ` +
+        'so you can pick this one, then re-call it with that job_id for the state, the result, or the ' +
+        'refund outcome. If you set an `operation_id`, re-calling this tool with the SAME operation_id ' +
+        'and the SAME inputs also re-attaches to the run without a second charge. The job_id is logged ' +
+        `to the MCP server stderr as \`[clien-mcp] ${tool} started job_id=…\`, which reaches the human ` +
+        'operator rather than you.');
+}
+/**
+ * Which scoped researcher produced `reportData`, read from the one envelope each mode writes
+ * (`agent/src/scoped-research.ts`: `webResearch` / `forumResearch` / `marketResearch`, never two).
+ * `null` when none is present — a run that recorded no findings — or, defensively, more than one.
+ */
+function scopedModeOf(reportData) {
+    if (!reportData)
+        return null;
+    const present = (key) => {
+        const value = reportData[key];
+        return value !== null && typeof value === 'object' && !Array.isArray(value);
+    };
+    const modes = [];
+    if (present('webResearch'))
+        modes.push('web');
+    if (present('forumResearch'))
+        modes.push('forum');
+    if (present('marketResearch'))
+        modes.push('market');
+    return modes.length === 1 ? modes[0] : null;
+}
 async function runScopedResearchTool(mode, input, deps) {
     const { topic, product_name, project_id, project_name } = input;
     // FUL-810: one paid start, one id — see operation-id.ts.
@@ -287,52 +495,17 @@ async function runScopedResearchTool(mode, input, deps) {
     // outcome (the user's money) and a cause-keyed retry hint so the calling
     // agent advises correctly without re-deriving intent from the prose.
     if (poll.status !== 'complete') {
-        const reason = poll.lastMessage ? ` (${poll.lastMessage})` : '';
         // Shared with clien_research_status — the refund note is an ELIGIBILITY
         // hint, not a promise (see buildFailureGuidance). NOTE: on a THROWN scoped
         // failure this reaches the caller only as prose (ToolError carries no
         // structured _meta); an agent that needs the machine-readable fields calls
-        // clien_research_status, which returns them in _meta. (review follow-up.)
-        const { refundNote, retryHint, retryPointless } = buildFailureGuidance({
-            errorCategory: poll.errorCategory,
-            refundedCredits: poll.refundedCredits,
-            refundPending: poll.refundPending,
-            startedSandbox: poll.startedSandbox,
-        });
-        /**
-         * ⚠️ THE CLOSING INSTRUCTION IS PART OF THE RETRY ADVICE (FUL-845 round-5).
-         *
-         * "Try a more specific topic" used to close every one of these, including
-         * the branch where `retryHint` has just said, in the same sentence, that
-         * retrying will not help until we fix our own configuration. A calling
-         * agent reading both does the thing it was last told to do: it re-words the
-         * topic and buys the same failure again. The run never reached a sandbox —
-         * the topic was never read by anything, so it cannot be the problem.
-         *
-         * The link stays on both branches: it is where the run's own words are.
-         */
-        const jobLink = webJobUrl(deps.config, jobId, projectId);
-        const nextStep = retryPointless
-            ? `View ${jobLink}.`
-            : `Try a more specific topic, or view ${jobLink}.`;
-        throw new ScopedResearchToolError(`${meta.label} ${poll.status === 'failed' ? 'failed' : 'was cancelled'}${reason}. ` +
-            `No ${meta.noun} were produced.${refundNote}${retryHint} ${nextStep}`, { jobId });
+        // scoped_research_status, which returns them in _meta. (review follow-up.)
+        throw new ScopedResearchToolError(scopedFailureText(meta, poll, webJobUrl(deps.config, jobId, projectId)), { jobId });
     }
     // 5. Promote into the Research collections (best-effort — needs a project; standalone runs skip).
-    let promotion = {
-        promoted: false,
-        errorCode: null,
-        retryable: null,
-        // FUL-479: a scoped `scan_market` run IS eligible for market authority now, so this is no
-        // longer null on every path — `promoteScopedJob` fills it from the server's own discriminator
-        // below, and `buildScopedResult` refuses to claim a saved snapshot without it.
-        marketUpdated: null,
-    };
-    if (projectId) {
-        promotion = await promoteScopedJob(ctx, jobId);
-    }
+    const promotion = projectId ? await promoteScopedJob(ctx, jobId) : NO_PROMOTION;
     // 6. Fetch the structured report.
-    const reportData = await fetchScopedReport(ctx, jobId, deps.config, projectId);
+    const { reportData } = await fetchScopedReport(ctx, jobId, deps.config, projectId);
     // 7. Extract the RICH slice + build the result.
     return buildScopedResult({
         mode,
@@ -345,6 +518,49 @@ async function runScopedResearchTool(mode, input, deps) {
         totalCostCents: poll.totalCostCents,
     });
 }
+/**
+ * No promotion attempted (a standalone run). FUL-479: a scoped `scan_market` run IS eligible for
+ * market authority, so `marketUpdated` is not null on every path — `promoteScopedJob` fills it from
+ * the server's own discriminator, and `buildScopedResult` refuses to claim a saved snapshot without it.
+ */
+const NO_PROMOTION = {
+    promoted: false,
+    errorCode: null,
+    retryable: null,
+    marketUpdated: null,
+};
+/**
+ * The sentence a failed or cancelled scoped run is reported with — by the live tool (thrown) and by
+ * `scoped_research_status` (returned). One copy, so the recovery read can never word the refund
+ * differently from the call it recovers. The refund note comes from the SERVER's own fields via
+ * `buildFailureGuidance`; nothing here infers a refund.
+ */
+function scopedFailureText(meta, poll, jobLink) {
+    const reason = poll.lastMessage ? ` (${poll.lastMessage})` : '';
+    const { refundNote, retryHint, retryPointless } = buildFailureGuidance({
+        errorCategory: poll.errorCategory,
+        refundedCredits: poll.refundedCredits,
+        refundPending: poll.refundPending,
+        startedSandbox: poll.startedSandbox,
+    });
+    /**
+     * ⚠️ THE CLOSING INSTRUCTION IS PART OF THE RETRY ADVICE (FUL-845 round-5).
+     *
+     * "Try a more specific topic" used to close every one of these, including
+     * the branch where `retryHint` has just said, in the same sentence, that
+     * retrying will not help until we fix our own configuration. A calling
+     * agent reading both does the thing it was last told to do: it re-words the
+     * topic and buys the same failure again. The run never reached a sandbox —
+     * the topic was never read by anything, so it cannot be the problem.
+     *
+     * The link stays on both branches: it is where the run's own words are.
+     */
+    const nextStep = retryPointless
+        ? `View ${jobLink}.`
+        : `Try a more specific topic, or view ${jobLink}.`;
+    return (`${meta.label} ${poll.status === 'failed' ? 'failed' : 'was cancelled'}${reason}. ` +
+        `No ${meta.noun} were produced.${refundNote}${retryHint} ${nextStep}`);
+}
 /**
  * Poll /events until a terminal status. Backs off on transient 5xx / poll timeouts (2s,5s,10s, then
  * bail after 3 consecutive), invalidates the session on a genuine 401, and enforces `deadline`.
@@ -359,14 +575,17 @@ async function pollScopedJob(ctx, jobId, deps) {
     let refundedCredits;
     let refundPending = false;
     let startedSandbox;
+    let projectId;
     let hasMore = false;
     let consecutiveServerErrors = 0;
     while (!TERMINAL_STATUSES.has(status) || hasMore) {
-        if (!TERMINAL_STATUSES.has(status) && Date.now() > deps.deadline) {
+        if (!deps.snapshot && !TERMINAL_STATUSES.has(status) && Date.now() > deps.deadline) {
             throw new ScopedResearchToolError(`${deps.label} did not complete within the allotted time. The job may still be running — ` +
                 `check ${webJobUrl(deps.config, jobId, deps.projectId)}.`, { jobId });
         }
-        await deps.sleep(deps.pollIntervalMs);
+        // A snapshot reads immediately: nothing is being waited for.
+        if (!deps.snapshot)
+            await deps.sleep(deps.pollIntervalMs);
         let response;
         try {
             response = await apiCall(ctx, 'GET', `/api/validate/${jobId}/events?since=${lastSequence}&limit=${hasMore ? 1000 : 100}`, {
@@ -401,6 +620,9 @@ async function pollScopedJob(ctx, jobId, deps) {
             refundPending = data?.job?.refundPending === true;
             if (typeof data?.job?.startedSandbox === 'boolean')
                 startedSandbox = data.job.startedSandbox;
+            if (typeof data?.job?.projectId === 'string' || data?.job?.projectId === null) {
+                projectId = data.job.projectId;
+            }
             if (typeof data?.lastSequence === 'number')
                 lastSequence = data.lastSequence;
             const summary = summarizeEvent(data?.events);
@@ -409,10 +631,20 @@ async function pollScopedJob(ctx, jobId, deps) {
             await emitProgress(deps, {
                 progress: PHASE_PROGRESS[status] ?? 0.5,
                 total: 1,
-                message: summary ?? `phase: ${status}`,
+                // FUL-1254: the server's job status, flattened like the event text `summary` carries.
+                message: summary ?? `phase: ${safeInline(status, 40) ?? 'unknown'}`,
             });
+            // Snapshot: stop once the pages are drained, whatever the status.
+            if (deps.snapshot && !hasMore)
+                break;
             continue;
         }
+        // The events route answers 404 for a job that does not exist OR belongs to another account —
+        // deliberately indistinguishable, so this says both.
+        if (response.status === 404) {
+            throw new ScopedResearchToolError(`No research job found with id ${jobId} on this account. The id may belong to a different ` +
+                'account, may be malformed, or may never have existed.', { jobId });
+        }
         const category = categorizeFetchError(response.status);
         if (category === 'auth') {
             if (response.refreshError?.kind === 'transient') {
@@ -434,7 +666,16 @@ async function pollScopedJob(ctx, jobId, deps) {
         const text = await response.text().catch(() => '');
         throw new ScopedResearchToolError(`Unexpected error polling ${deps.label.toLowerCase()} events (HTTP ${response.status}): ${truncate(text, 200)}`, { jobId });
     }
-    return { status, lastMessage, totalCostCents, errorCategory, refundedCredits, refundPending, startedSandbox };
+    return {
+        status,
+        lastMessage,
+        totalCostCents,
+        errorCategory,
+        refundedCredits,
+        refundPending,
+        startedSandbox,
+        ...(projectId !== undefined ? { projectId } : {}),
+    };
 }
 /**
  * Backoff helper for transient poll failures. Returns true if the caller should `continue` (backed
@@ -472,7 +713,11 @@ async function promoteScopedJob(ctx, jobId) {
     }
     return outcome;
 }
-/** GET the structured report (JSON variant). Returns report_data (may be null). */
+/**
+ * GET the structured report (JSON variant). Returns report_data (may be null) and whether the job
+ * carries report MARKDOWN — which only a full `clien_research` run writes, so the recovery read can
+ * tell a hero job id from a scoped one without guessing from the payload's shape.
+ */
 async function fetchScopedReport(ctx, jobId, config, projectId) {
     let response;
     try {
@@ -508,7 +753,10 @@ async function fetchScopedReport(ctx, jobId, config, projectId) {
     //
     // Projected at the FETCH boundary rather than at the emit site so nothing downstream — the
     // extractors included — ever holds the raw payload.
-    return projectReportDataForMcp(json?.reportData ?? null) ?? null;
+    return {
+        reportData: projectReportDataForMcp(json?.reportData ?? null) ?? null,
+        hasMarkdown: typeof json?.reportMarkdown === 'string' && json.reportMarkdown.trim().length > 0,
+    };
 }
 // ------------------------------------------------------------------
 // Result building
@@ -770,13 +1018,20 @@ function renderCompetitors(competitors, topic, persistenceLine) {
         const urlText = safeInline(c.url, 200);
         const url = urlText ? `\n   ${urlText}` : '';
         // FUL-179: the M1b company-metadata fields. Rendered as a single "·"-joined line so a
-        // competitor missing all four adds no noise, and one with a couple stays compact. These are
+        // competitor missing all of them adds no noise, and one with a couple stays compact. These are
         // un-receipted (see CompetitorProfileSchema) — presented as plain facts, not cited claims.
+        // FUL-1217(a): `Serves` (where it operates) comes LAST, after HQ, matching the order the
+        // report claim spine grades the facts in. A competitor without it renders exactly as before.
+        // FUL-1249: `safeFactValue`, not `safeInline` — the same guard `list_competitors` uses.
+        // This line prints no brackets, and the TRUST note below says the ABSENCE of one means
+        // "not checked", so a value carrying `[GROUNDED]` (or ` · HQ: …`) must not be able to
+        // supply one.
         const meta = [
-            ['Funding', safeInline(c.funding, 80)],
-            ['Employees', safeInline(c.employeeCount, 40)],
-            ['Founded', safeInline(c.founded, 40)],
-            ['HQ', safeInline(c.hqLocation, 80)],
+            ['Funding', safeFactValue(c.funding, 80)],
+            ['Employees', safeFactValue(c.employeeCount, 40)],
+            ['Founded', safeFactValue(c.founded, 40)],
+            ['HQ', safeFactValue(c.hqLocation, 80)],
+            ['Serves', safeFactValue(c.serviceArea, 80)],
         ]
             .filter(([, v]) => v !== null)
             .map(([label, v]) => `${label}: ${v}`);
@@ -792,7 +1047,7 @@ function renderCompetitors(competitors, topic, persistenceLine) {
     });
     // FUL-247: state the ABSENCE of grounding here, in the text.
     //
-    // This surface renders the SAME four company facts as `list_competitors`, and
+    // This surface renders the SAME five company facts as `list_competitors`, and
     // that tool now suffixes each one with a `[GROUNDED]`-style bracket. The
     // divergence is legitimate — `CompetitorProfileSchema` has no `*_grounding`
     // fields at all, because these are raw values a research agent just wrote and
@@ -802,7 +1057,7 @@ function renderCompetitors(competitors, topic, persistenceLine) {
     // can read the silence as "nothing flagged" rather than "categorically
     // unverified". The tool description says so, but a description is read once and
     // may be far outside the context window by now — so say it beside the facts.
-    const hasCompanyFacts = competitors.some((c) => Boolean(c.funding || c.employeeCount || c.founded || c.hqLocation));
+    const hasCompanyFacts = competitors.some((c) => Boolean(c.funding || c.employeeCount || c.founded || c.hqLocation || c.serviceArea));
     const trustLine = hasCompanyFacts
         ? '\n\nTRUST: the company facts above are UN-RECEIPTED — this surface has no per-fact ' +
             'grounding to show, so the ABSENCE of a `[GROUNDED]`-style bracket here means "not ' +
@@ -1011,7 +1266,7 @@ async function handleScopedStartError(response, label, operationId) {
     }
     if (status === 503 && parsed?.code === 'FEATURE_UNAVAILABLE') {
         // FUL-479 kill switch. Distinguished from the circuit breaker below because the two ask for
-        // OPPOSITE responses: the breaker is a transient outage and "try again in 30 minutes" is the
+        // OPPOSITE responses: the breaker is a transient outage and "try again in a few minutes" is the
         // right advice, while this is a capability the deployment has not switched on — retrying will
         // return the same 503 forever. Nothing was started and nothing was charged, and the agent is
         // told to stop rather than to wait.
@@ -1022,7 +1277,9 @@ async function handleScopedStartError(response, label, operationId) {
             'whatever market data the project already holds.');
     }
     if (status === 503 && parsed?.code === 'CIRCUIT_BREAKER_OPEN') {
-        throw new ScopedResearchToolError(parsed?.error ?? parsed?.message ?? 'Our research infrastructure is experiencing issues. Please try again in 30 minutes.');
+        throw new ScopedResearchToolError(parsed?.error ??
+            parsed?.message ??
+            'Research is temporarily unavailable because a provider is down. Please try again in a few minutes.');
     }
     if (status === 401) {
         throw new ScopedResearchToolError('Authentication failed. Re-run the tool to re-authenticate.');
@@ -1069,12 +1326,19 @@ function summarizeEvent(events) {
     const last = events[events.length - 1];
     if (!last)
         return null;
-    const type = last.eventType ?? 'event';
+    // FUL-1144: event text is server/agent-written and lands in model-visible prose — in a thrown
+    // failure line here, and in `scoped_research_status`'s returned text — so it is flattened, not
+    // just clipped. `truncate` bounds length; only `safeInline` stops a newline forging a line.
+    const type = safeInline(last.eventType, 40) ?? 'event';
     const data = last.eventData ?? {};
-    if (typeof data.message === 'string' && data.message.length > 0)
-        return truncate(`${type}: ${data.message}`, 120);
-    if (typeof data.phase === 'string')
-        return truncate(`${type}: ${data.phase}`, 120);
+    if (typeof data.message === 'string') {
+        const message = safeInline(data.message, 120);
+        if (message)
+            return truncate(`${type}: ${message}`, 120);
+    }
+    const phase = safeInline(data.phase, 40);
+    if (phase)
+        return truncate(`${type}: ${phase}`, 120);
     return type;
 }
 function formatZodError(error) {