@lincoln504/pi-research 1.3.12 → 1.4.1

package/src/prompts/system-lead-router.md

@@ -0,0 +1,122 @@
+# Research Lead — Routing
+
+You decide whether this research run continues or ends.
+
+You are given the message in two parts.
+
+**NEW SINCE YOUR LAST DECISION** holds the **full reports** from the researchers that have just finished. This is the evidence your decision turns on — read it. Each report is preceded by the **coverage digest** its own researcher wrote for it: treat that as a *claim*, and check it against the report underneath. A digest saying `Gaps: none` above a thin or hedged report is the single most important thing you can catch, because nobody else will.
+
+**REVIEWED IN EARLIER ROUNDS** holds only the coverage digests of reports you already read in full on a previous round and already judged. They are not repeated in full — you have seen them.
+
+Everything specific to this run — the root query, the current round and round budget, the agenda so far, the queries already executed, any additional user guidance, and the phase guidance for this particular round — is supplied in a **RUN CONTEXT** block at the END of the message you are given, after the reports. Read that block before deciding; the instructions below tell you how to decide, the RUN CONTEXT tells you what you are deciding about.
+
+You never write the report. When you decide the research is complete, a separate synthesis step reads every full report and writes it. Your output is a decision, not prose.
+
+## CRITICAL: Steering Compliance Checkpoint
+- **STRICT STEERING**: If the RUN CONTEXT block carries an "ADDITIONAL USER GUIDANCE" section, you MUST treat every point in it as a **mandatory rule and instruction** for your decisions, next round goals, and queries. Do not ignore them. They are directional requirements.
+- **STEERING SATISFACTION**: Before deciding to FINISH, you MUST explicitly verify that ALL user steering requirements are actually covered by the findings — not merely claimed by a digest. If ANY steering requirement is unaddressed, or only superficially covered, you MUST DELEGATE — do NOT finish. The user's guidance takes priority over round budget or feeling that research is "complete enough."
+
+{{disabled_tools_section}}
+
+---
+
+## Complexity-Aware Decision Thresholds
+
+**Complexity Level**: {{complexity_label}}
+
+{{complexity_guidance}}
+
+The phase guidance for the current round appears in the RUN CONTEXT block; it refines these thresholds for where this run currently sits in its round budget.
+
+---
+
+## Reading the evidence
+
+For **earlier rounds** you have only the digest, and you already judged that work when it arrived. For **new reports** you have the prose; the digest beside it is a claim to verify.
+
+Read a digest as follows:
+
+- **`Covered`** tells you what is established. Treat a specific, concrete `Covered` line as reliable; treat a vague one ("general background on the topic") as weak coverage that may need a follow-up.
+- **`Gaps`** is a researcher telling you directly what it could not reach. A non-"none" `Gaps` line on a topic the root query asks about is the strongest possible signal to delegate.
+- **`Unsubstantiated`** flags claims that were looked for and not grounded. Delegating a targeted follow-up on those is usually higher value than opening a new angle.
+- **`Sources: 0` or a very low count** means that researcher produced little usable material regardless of what its other lines claim. Re-cover that goal.
+- **A digest that says coverage is unknown** was derived mechanically because that researcher emitted no digest of its own. For a new report that costs you nothing — read the report. For an earlier round it means coverage there is unverified, so weigh it accordingly.
+
+**Verify the new reports rather than trusting their digests.** For each new report, read the prose and ask whether it actually establishes what its `Covered` line claims. Specific, sourced prose backs the claim up. Hedged prose, "not found in sources", a handful of thin paragraphs, or a report that never reaches its stated topic does not — in that case the goal is still open however confidently the digest is worded, and you should delegate it again.
+
+Then compare everything covered — earlier digests plus what the new reports actually establish — against the root query and the initial agenda. What the root query asks for and nothing covers is a gap.
+
+---
+
+## Decision Framework
+
+**FINISH if:** Coverage across the new reports and the earlier digests meets the complexity-specific synthesis criteria above. ("Finish" is the decision; the literal value you emit for it is `"action": "synthesize"`.)
+**DELEGATE if:** Coverage meets the complexity-specific delegation criteria above.
+**Note on Guidance**: If the user provides additional guidance mid-research (via Alt+Enter or direct follow-up), those messages will be provided to you. You MUST incorporate them into your next round's delegation goals and queries.
+
+**STAY IN SCOPE (every delegation):**
+- Going deeper on in-scope material is always welcome. Widening to new areas (breadth) is the drift to avoid — only do it when genuinely appropriate and helpful for the topic.
+- A gap is missing depth on what was asked — not a broader topic next to it. Don't add anything the query didn't ask for, even if it came up in the findings.
+- Match the query's scope-bounding constraints exactly — don't broaden them, don't narrow them.
+
+**COMMON MISTAKES TO AVOID:**
+- Do NOT finish early just because you've done "enough" rounds. Finish only when the evidence shows comprehensive coverage across all major topics the query asks about.
+- Do NOT finish with gaps remaining, hoping they can be "filled in later". Complete the research first.
+- Do NOT invent a gap outside the query's scope just to keep going or fill the budget. Finish what was asked; don't add what wasn't.
+- Do NOT write findings, prose, or a report. You have read findings, but writing the report is a separate step's job. A `reason` is one sentence.
+
+Use unique, targeted queries for any new researchers.
+
+**Decision**: Return valid JSON in a code block:
+
+**If the research is complete**:
+```json
+{
+  "action": "synthesize",
+  "reason": "<one sentence naming the coverage that makes this complete>"
+}
+```
+
+**If delegating**:
+```json
+{
+  "action": "delegate",
+  "researchers": [
+    {
+      "id": "<CURRENT_ROUND>.1",
+      "name": "<Researcher Specialty>",
+      "goal": "<Focused gap or new angle to investigate>",
+      "queries": ["<query_1>", "<query_2>", "<query_3>", "..."]
+    }
+  ],
+  "allQueries": ["<flat_list_of_all_queries_from_all_new_researchers>"]
+}
+```
+
+**DELEGATION REQUIREMENTS**:
+- **CRITICAL — Queries are mandatory**: Every researcher MUST have at least one query. Never plan a researcher without queries. Researchers receive ONLY the search results you delegate to them.
+- **Maximize queries**: For EACH researcher, generate the maximum number of targeted, specific queries within the budget. Do not plan fewer than needed — fill the budget. Queries should target primary sources and authoritative evidence.
+- **YouTube discovery**: For roughly one in {{youtube_query_every_n}} queries, append the word `youtube` to the query text (e.g. `"<topic> analysis youtube"`). DuckDuckGo rarely surfaces YouTube on its own, and YouTube links let researchers read video transcripts. Skip only when the gap is clearly unsuited to video.
+- **Temporal anchoring**: Anchor every new time-sensitive query to the current month and year shown at the top of this prompt. Use that exact year (and month where relevant); never default to an older year than the one shown there unless the user explicitly asks about the past.
+- **Flexible coverage**: Use up to {{max_team_size}} researchers to cover distinct angles in parallel. Scale based on research gaps — a single well-targeted researcher is often sufficient for focused gaps.
+- **Source diversity**: Encourage researchers to find multiple authoritative sources per topic area to enable comprehensive citations in the final synthesis.
+
+---
+
+## Quality Standards for Delegation
+
+When delegating, ensure:
+- **Query Specificity**: Each new query targets distinct, unexplored territory
+- **No Redundancy**: Do not repeat queries from previous rounds
+- **Specialized Focus**: Each new researcher has a clear, distinct angle
+- **Gap-Driven**: Only delegate when the evidence shows a gap that existing coverage cannot resolve
+- **Progressive Depth**: New queries go deeper, or to a new angle still inside the query's scope — never outside it, and never repeating surface-level coverage
+
+---
+
+## Output Requirements
+
+- **Researcher IDs**: Use Round.Index format — the current round number from the RUN CONTEXT block, then the researcher index. In round 3 that is **3.1**, **3.2**, and so on.
+- **Query Budget**: Use the complexity-specific budget ({{query_budget}} per researcher). Fill each researcher's query budget completely.
+- **Team Size**: Scale researcher count to match the gaps. Use up to {{max_team_size}} researchers when delegating, but a single well-targeted researcher is often sufficient for focused gaps. Don't pad the team when fewer researchers will cover the remaining gaps efficiently.
+- **Format**: ONLY return valid JSON in a code block. Never return report prose.

package/src/prompts/system-lead-synthesizer.md

@@ -0,0 +1,46 @@
+# Research Lead — Synthesis
+
+You write the final report for this research run.
+
+The research is finished. Every researcher report collected during the run is supplied to you in full, followed by a **Global Source List**, followed by a **RUN CONTEXT** block carrying the root query and any additional user guidance. Read the RUN CONTEXT block before writing: the instructions below tell you how to write, it tells you what the report is about.
+
+You do not decide anything and you do not plan further research. Your only output is the report.
+
+## CRITICAL: Steering Compliance
+If the RUN CONTEXT block carries an "ADDITIONAL USER GUIDANCE" section, treat every point in it as a **mandatory rule** governing the report's content, structure, and emphasis. The user's guidance overrides your own judgment about what to include or how to organize.
+
+{{disabled_tools_section}}
+
+---
+
+## Synthesis Protocol
+
+1. **Organization**: Organize the report logically **BY TOPIC**. Do NOT structure it by researcher or round.
+2. **Anonymity**: Do NOT reference "researchers", "agents", "reports", or the research process. Present the findings as a direct, unified knowledge base.
+3. **Master Links List**: A **Global Source List** has been provided to you, after the findings. Use these sequential numbers [1], [2], [3], etc., for all inline citations. The researcher reports provided to you have already been normalized to these global numbers. This list includes all URLs found during live research and any relevant entries from the **Local and Global Knowledge Stores**.
+4. **Exhaustive Synthesis**: Use ALL findings from ALL reports. Include every fact, date, name, and statistic verbatim. Longer is better.
+5. **Strict Grounding**: Every sentence must come from a report. Use [N] inline citations. No prior knowledge.
+6. **CRITICAL — Links at Bottom Only**:
+   - Write all topic sections first with inline citations [1], [2], etc., using the numbers from the **Global Source List**.
+   - Place exactly ONE `CITED LINKS` section at the VERY END of the entire synthesis.
+   - This section must contain the complete master list of all unique URLs exactly as provided in the **Global Source List**.
+   - Do NOT include any links within topic sections or subsections.
+   - Format: `[1] https://url.com [Source: ...] — brief description` on each line.
+
+> **MANDATORY TERMINATION RULE**: Your synthesis is not complete until it ends with `CITED LINKS`. Do NOT close the JSON object or stop generating until this section is written in full. A synthesis without `CITED LINKS` is a failed output.
+
+---
+
+## Output Requirements
+
+- **Synthesis Quality**: Logical topic-based structure in plain prose, maximal detail, NO mention of researchers, NO markdown headings or bullets.
+- **Format**: ONLY return valid JSON in a code block:
+
+```json
+{
+  "action": "synthesize",
+  "content": "<Plain prose report with [N] citations, organized by topic. No markdown headings, bullets, or bold text. Followed by the mandatory CITED LINKS section.>"
+}
+```
+
+{{partial_synthesis_section}}

package/src/tools/research-knowledge-search.ts

@@ -54,6 +54,7 @@ import { loadPrompt } from '../core/llm/prompts.ts';
 import { formatParentContext } from '../orchestration/session-context.ts';
 import { getConfig, type ConfigInterface, type Config } from '../config.ts';
 import { createKnowledgeSearchPanel } from '../tui/knowledge-search-panel.ts';
+import { isCancellation } from '../utils/cancellation.ts';
 
 // ---------------------------------------------------------------------------
 // Phase 1: Tool Parameters
@@ -439,6 +440,7 @@ export async function runBackgroundExtraction(
   maxTokens: number,
   thinkingLevel: Config['LLM_THINKING_LEVEL'],
   signal?: AbortSignal,
+  sessionId?: string,
 ): Promise<ResearchKnowledgeSynthesisResponse> {
   const promptTemplate = loadPrompt('research-knowledge-search-extractor');
   if (!promptTemplate) {
@@ -479,7 +481,8 @@ export async function runBackgroundExtraction(
         }, buildSafeOptions(model, {
           apiKey: auth.apiKey,
           headers: auth.headers,
-          signal
+          signal,
+          sessionId,
         }, maxTokens, thinkingLevel)),
         llmTimeout,
         'knowledge-search-extraction',
@@ -537,6 +540,7 @@ export async function runBackgroundExtraction(
       context: 'Knowledge search extraction — synthesizing answer from reference documents',
       serviceName: 'ResearchKnowledgeSearch',
       signal,
+      sessionId,
       // Match the budget of the call being repaired so a large synthesis is not re-truncated
       // at repairJsonWithLlm's smaller default (16384). Mirrors the planning-service repairs.
       maxTokens,
@@ -972,6 +976,11 @@ export function createResearchKnowledgeSearchTool(iface?: ConfigInterface): Tool
           config.SYNTHESIS_MAX_TOKENS,
           config.LLM_THINKING_LEVEL,
           signal,
+          // Cache/session-affinity hint only (keeps repeated calls on the same warmed
+          // replica) — same resolution research-config.ts uses, since this tool has no
+          // researchId of its own to key on. ctx.sessionId is read defensively: it is
+          // not on every host's ExtensionContext shape, hence the `as any`.
+          (ctx as any).sessionId || ctx.sessionManager?.getSessionId(),
         );
 
         const durationMs = Date.now() - startTime;
@@ -983,7 +992,6 @@ export function createResearchKnowledgeSearchTool(iface?: ConfigInterface): Tool
         return buildSteeringResult(result, urls);
       } catch (error) {
         const durationMs = Date.now() - startTime;
-        const msg = error instanceof Error ? error.message : String(error);
 
         // A CANCELLED search is not an empty store. Reporting the miss string here
         // told the calling agent, definitively, that the knowledge store has
@@ -991,7 +999,7 @@ export function createResearchKnowledgeSearchTool(iface?: ConfigInterface): Tool
         // the very work the user just interrupted. Propagate the abort instead;
         // the run is ending either way. (Same misclassification as the search
         // layer's "browser workers may be unavailable" on Ctrl-C.)
-        if (signal?.aborted || (error instanceof Error && error.name === 'AbortError') || /^(aborted|research (aborted|cancelled))$/i.test(msg)) {
+        if (isCancellation(error, signal)) {
           metrics.observe('research_knowledge_search_duration_ms', durationMs, { status: 'cancelled' });
           metrics.increment('research_knowledge_search_total', 1, { status: 'cancelled' });
           logger.debug('[research-knowledge-search] Cancelled mid-search — propagating rather than reporting an empty store.');

package/src/tools/scrape.ts

@@ -31,6 +31,7 @@ import { ServiceNames } from '../core/service-interfaces.ts';
 import type { IKnowledgeStoreService } from '../core/service-interfaces.ts';
 import { logger } from '../logger.ts';
 import { metrics } from '../utils/metrics.ts';
+import { isCancellation } from '../utils/cancellation.ts';
 
 export function createScrapeTool(options: {
   ctx: ExtensionContext;
@@ -267,6 +268,11 @@ export function createScrapeTool(options: {
         }, container);
         freshResults = Array.isArray(results) ? results : [];
       } catch (error) {
+          // A cancelled scrape is not a failed scrape — see isCancellation.
+          if (isCancellation(error, signal)) {
+            metrics.increment('tool_scrape_calls_total', 1, { status: 'cancelled' });
+            throw error;
+          }
           const message = error instanceof Error ? error.message : String(error);
           logger.error(`[scrape tool] Scrape failed: ${message}`);
           metrics.increment('tool_scrape_calls_total', 1, { status: 'error' });

package/src/tools/search.ts

@@ -13,6 +13,7 @@ import type { SystemResearchState } from '../orchestration/deep-research-types.t
 import { logger } from '../logger.ts';
 import { type Config, getConfig } from '../config.ts';
 import { metrics } from '../utils/metrics.ts';
+import { isCancellation } from '../utils/cancellation.ts';
 import { tryGetServiceContainerFromCtx } from '../core/service-registry.ts';
 
 export function createSearchTool(options: {
@@ -134,6 +135,12 @@ export function createSearchTool(options: {
         };
       } catch (error) {
         const elapsed = Date.now() - startTime;
+        // A cancelled search is not a failed search — see isCancellation.
+        if (isCancellation(error, signal)) {
+          metrics.observe('tool_search_duration_ms', elapsed, { status: 'cancelled' });
+          metrics.increment('tool_search_calls_total', 1, { status: 'cancelled' });
+          throw error;
+        }
         metrics.observe('tool_search_duration_ms', elapsed, { status: 'error' });
         metrics.increment('tool_search_calls_total', 1, { status: 'error' });
         const msg = error instanceof Error ? error.message : String(error);

package/src/tools/security.ts

@@ -11,6 +11,7 @@ import { searchSecurityDatabases } from '../security/index.ts';
 import type { ToolUsageTracker } from '../utils/tool-usage-tracker.ts';
 import { getMaxGatheringCalls } from '../constants.ts';
 import { metrics } from '../utils/metrics.ts';
+import { isCancellation } from '../utils/cancellation.ts';
 import type { SecuritySearchParams } from '../security/types.ts';
 
 const MAX_DESCRIPTION_CHARS = 300;
@@ -78,7 +79,24 @@ export function createSecuritySearchTool(options: {
       _extensionCtx,
     ): Promise<AgentToolResult<unknown>> {
       const startTime = Date.now();
-      metrics.increment('tool_security_search_calls_total', 1);
+
+      // Every exit path below increments `tool_security_search_calls_total` itself
+      // (labeled with its own status) — there is no separate unconditional increment
+      // here. There used to be one, which double-counted every single call: sumCounter
+      // matches both the bare key and every labeled variant of the same base name, so
+      // the Session Metrics / Research Summary view reported exactly 2x the real count.
+
+      // Validate BEFORE spending the budget: a rejected call did no work, and charging
+      // it against the shared MAX_GATHERING_CALLS allowance turns a malformed call into
+      // a permanently lost one. See youtube-transcript for the sharpest case (a single
+      // allowed call, forfeited by a schema violation).
+      if (!Value.Check(SecuritySearchParamsSchema, params)) {
+          metrics.increment('tool_security_search_calls_total', 1, { status: 'invalid_params' });
+          return {
+            content: [{ type: 'text', text: 'Invalid parameters for security_search tool.' }],
+            details: { error: 'invalid_parameters' },
+          };
+      }
 
       // Record call in tracker - returns false if limit reached
       const allowed = options.tracker.recordCall('security_search');
@@ -90,14 +108,6 @@ export function createSecuritySearchTool(options: {
           };
       }
 
-      if (!Value.Check(SecuritySearchParamsSchema, params)) {
-          metrics.increment('tool_security_search_calls_total', 1, { status: 'invalid_params' });
-          return {
-            content: [{ type: 'text', text: 'Invalid parameters for security_search tool.' }],
-            details: { error: 'invalid_parameters' },
-          };
-      }
-
       const p = params as SecuritySearchParamsType;
 
       const terms = p.terms;
@@ -167,6 +177,14 @@ export function createSecuritySearchTool(options: {
         results = await searchSecurityDatabases(searchParams, signal);
       } catch (error) {
         const duration = Date.now() - startTime;
+        // A cancelled search is not a database outage — see isCancellation. The
+        // "temporary issue - try again later" text below invites exactly the retry
+        // the user just interrupted.
+        if (isCancellation(error, signal)) {
+          metrics.observe('tool_security_search_duration_ms', duration, { status: 'cancelled' });
+          metrics.increment('tool_security_search_calls_total', 1, { status: 'cancelled' });
+          throw error;
+        }
         metrics.observe('tool_security_search_duration_ms', duration, { status: 'error' });
         metrics.increment('tool_security_search_calls_total', 1, { status: 'error' });
         const errorMsg = error instanceof Error ? error.message : String(error);

package/src/tools/stackexchange.ts

@@ -10,6 +10,7 @@ import { Value } from 'typebox/value';
 import { stackexchangeCommand } from '../stackexchange/index.ts';
 import type { ToolUsageTracker } from '../utils/tool-usage-tracker.ts';
 import { getMaxGatheringCalls } from '../constants.ts';
+import { isCancellation } from '../utils/cancellation.ts';
 
 export function createStackexchangeTool(options: {
   ctx: ExtensionContext;
@@ -74,6 +75,15 @@ export function createStackexchangeTool(options: {
       _onUpdate,
       extensionCtx,
     ): Promise<AgentToolResult<unknown>> {
+      // Validate BEFORE spending the budget — see security.ts. A rejected call did no
+      // work and must not consume one of MAX_GATHERING_CALLS.
+      if (!Value.Check(StackExchangeParamsSchema, params)) {
+          return {
+            content: [{ type: 'text', text: 'Invalid parameters for stackexchange tool.' }],
+            details: { error: 'invalid_parameters' },
+          };
+      }
+
       // Record call in tracker - returns false if limit reached
       const allowed = tracker.recordCall('stackexchange');
       if (!allowed) {
@@ -83,13 +93,6 @@ export function createStackexchangeTool(options: {
           };
       }
 
-      if (!Value.Check(StackExchangeParamsSchema, params)) {
-          return {
-            content: [{ type: 'text', text: 'Invalid parameters for stackexchange tool.' }],
-            details: { error: 'invalid_parameters' },
-          };
-      }
-
       const p = params as StackExchangeParams;
       const command = p.command;
 
@@ -105,6 +108,9 @@ export function createStackexchangeTool(options: {
           signal,
         });
       } catch (error) {
+        // A cancelled query was never rate-limited — see isCancellation. Naming a
+        // quota the run never hit is a cause the agent can carry into its report.
+        if (isCancellation(error, signal)) throw error;
         const errorMsg = error instanceof Error ? error.message : String(error);
         return {
           content: [

package/src/tools/youtube-transcript.ts

@@ -24,6 +24,7 @@ import { cacheScrapedContent, registerScrapedLinks, registerTranscribedLinks, re
 import { type Config, getConfig } from '../config.ts';
 import { logger } from '../logger.ts';
 import { metrics } from '../utils/metrics.ts';
+import { isCancellation } from '../utils/cancellation.ts';
 
 export function createYoutubeTranscriptTool(options: {
   ctx: ExtensionContext;
@@ -75,18 +76,12 @@ export function createYoutubeTranscriptTool(options: {
       _onUpdate: AgentToolUpdateCallback<unknown>,
       extensionCtx: ExtensionContext,
     ): Promise<AgentToolResult<unknown>> {
-      // Rate-limit enforcement (one call per researcher).
-      if (tracker) {
-        const allowed = tracker.recordCall('youtube_transcript');
-        if (!allowed) {
-          metrics.increment('tool_youtube_transcript_calls_total', 1, { status: 'rate_limited' });
-          return {
-            content: [{ type: 'text', text: tracker.getLimitMessage('youtube_transcript') }],
-            details: { blocked: true, reason: 'limit_reached' },
-          };
-        }
-      }
-
+      // Validate BEFORE spending the budget. Charging a rejected call is not a rate
+      // limit, it is a forfeit: this tool's schema caps `urls` at maxVideos while the
+      // per-researcher allowance is a single call, so a researcher passing one URL too
+      // many got a validation error AND lost its only call — and the retry was then told
+      // "You have already used your one youtube_transcript call", which is false. The
+      // round loses transcripts entirely. grep and search already validate first.
       if (!Value.Check(YoutubeParamsSchema, params)) {
         metrics.increment('tool_youtube_transcript_calls_total', 1, { status: 'invalid_params' });
         return {
@@ -105,6 +100,19 @@ export function createYoutubeTranscriptTool(options: {
         };
       }
 
+      // Rate-limit enforcement (one call per researcher), now that the call is one that
+      // would actually do work.
+      if (tracker) {
+        const allowed = tracker.recordCall('youtube_transcript');
+        if (!allowed) {
+          metrics.increment('tool_youtube_transcript_calls_total', 1, { status: 'rate_limited' });
+          return {
+            content: [{ type: 'text', text: tracker.getLimitMessage('youtube_transcript') }],
+            details: { blocked: true, reason: 'limit_reached' },
+          };
+        }
+      }
+
       // Resolve config against the live cwd for timeout/lang. The video cap stays
       // `maxVideos` (the factory value the schema's maxItems was built from) so the
       // schema gate and the command-level cap can never disagree. The PoToken
@@ -151,6 +159,12 @@ export function createYoutubeTranscriptTool(options: {
 
         return result;
       } catch (error) {
+        // A cancelled batch is not bot-protection — see isCancellation. "Continue
+        // with the rest of your research" is the opposite of what a Ctrl-C means.
+        if (isCancellation(error, signal)) {
+          metrics.increment('tool_youtube_transcript_calls_total', 1, { status: 'cancelled' });
+          throw error;
+        }
         const errorMsg = error instanceof Error ? error.message : String(error);
         logger.error(`[youtube_transcript tool] Failed: ${errorMsg}`);
         metrics.increment('tool_youtube_transcript_calls_total', 1, { status: 'error' });

package/src/utils/cancellation.ts

@@ -0,0 +1,36 @@
+/**
+ * Cancellation detection shared by the agent-facing tools.
+ *
+ * Every tool wrapper is built to never throw: a failure becomes prose the agent
+ * reads and acts on. That contract is right for a failure and wrong for a
+ * cancellation, because the prose is written to explain a *fault* — "this may be
+ * due to API rate limiting", "unable to search security databases, try again
+ * later", "may be due to network issues or YouTube bot-protection". When the user
+ * presses Ctrl-C, the in-flight work rejects with an abort and those sentences are
+ * simply false. The agent believes them: it retries, spends budget the user just
+ * asked it to stop spending, and can carry the invented cause into the report.
+ *
+ * A cancellation must therefore propagate. The run is ending either way, and the
+ * throw is what unwinds the agent loop instead of feeding it a fabricated fault.
+ */
+
+/**
+ * True when `error` represents the abort of `signal` (or an abort in general)
+ * rather than a genuine failure of the work.
+ *
+ * The message-shape check is the load-bearing part in practice. Cancellation
+ * crosses several layers here — worker IPC, HTTP to the browser leader, the
+ * research orchestrator's own abort plumbing — and only some of them preserve
+ * `AbortError` as the error name; the rest arrive as a plain Error whose message
+ * is the reason string. `signal.aborted` alone is not sufficient either: a tool
+ * may be handed no signal at all, and a signal can abort after the failure it is
+ * being asked to explain.
+ */
+export function isCancellation(error: unknown, signal?: AbortSignal | null): boolean {
+  if (signal?.aborted) return true;
+  if (error instanceof Error && error.name === 'AbortError') return true;
+  const message = error instanceof Error ? error.message : String(error);
+  return /^(aborted|the operation was aborted|research (aborted|cancelled|canceled)|operation cancelled|operation canceled)\.?$/i.test(
+    message.trim(),
+  );
+}