pi-background-tasks 0.9.0 → 1.0.3

package/src/core/fusion/web-fetch.ts

@@ -3,9 +3,10 @@ import { lookup as nodeLookup } from 'node:dns/promises';
 import * as http from 'node:http';
 import * as https from 'node:https';
 import { isIP } from 'node:net';
+import { performance } from 'node:perf_hooks';
 import { TextDecoder } from 'node:util';
 
-import TurndownService from 'turndown';
+import type TurndownService from 'turndown';
 
 export const FUSION_WEB_FETCH_TIMEOUT_MS = 60_000;
 export const FUSION_WEB_FETCH_MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
@@ -117,6 +118,10 @@ interface TableReplacement {
   markdown: string;
 }
 
+type TurndownServiceConstructor = typeof TurndownService;
+
+let turndownServiceLoad: Promise<TurndownServiceConstructor> | undefined;
+
 const USER_AGENT = 'pi-background-tasks fusion_web_fetch/1.0';
 const ACCEPT_HEADER = 'text/markdown, text/html;q=0.9, application/xhtml+xml;q=0.8, text/plain;q=0.7';
 const METADATA_HOSTNAMES = new Set([
@@ -150,6 +155,7 @@ const IPV4_DENY_RANGES: readonly [number, number][] = [
 const IPV6_DENY_RANGES: readonly [bigint, number][] = [
   [ipv6ToBigIntLiteral('::'), 128],
   [ipv6ToBigIntLiteral('::1'), 128],
+  [ipv6ToBigIntLiteral('64:ff9b::'), 96],
   [ipv6ToBigIntLiteral('64:ff9b:1::'), 48],
   [ipv6ToBigIntLiteral('100::'), 64],
   [ipv6ToBigIntLiteral('2001:2::'), 48],
@@ -187,18 +193,19 @@ export async function fusionWebFetch(
   const effective = mergeOptions(options);
   const requestedFormat = req.extract ?? 'markdown';
   const start = effective.now();
+  const deadlineMs = start + effective.timeoutMs;
   const requestedUrl = normalizeRequestUrl(req.url).url;
   let currentUrl = requestedUrl;
 
   for (let redirectCount = 0; ; redirectCount += 1) {
-    const remainingMs = start + effective.timeoutMs - effective.now();
+    const remainingMs = deadlineMs - effective.now();
     if (remainingMs <= 0) {
       throw new FusionWebFetchError('request_timeout', 'fusion_web_fetch request timeout elapsed', {
         url: currentUrl.toString(),
       });
     }
 
-    const result = await fetchOne(currentUrl, effective, remainingMs, redirectCount > 0);
+    const result = await fetchOne(currentUrl, effective, deadlineMs, redirectCount > 0);
     if (result.kind === 'redirect') {
       if (redirectCount >= effective.maxRedirects) {
         throw new FusionWebFetchError(
@@ -211,7 +218,7 @@ export async function fusionWebFetch(
       continue;
     }
 
-    const extracted = extractContent(result.body, result.contentType, requestedFormat);
+    const extracted = await extractContent(result.body, result.contentType, requestedFormat);
     const capped = capUtf8Bytes(extracted.content, effective.maxOutputBytes);
     return {
       url: requestedUrl.toString(),
@@ -234,7 +241,7 @@ function mergeOptions(options: FusionWebFetchOptions): EffectiveOptions {
     request: options.request ?? defaultTransportRequest,
     agent: options.agent ?? false,
     createConnection: options.createConnection,
-    now: options.now ?? Date.now,
+    now: options.now ?? (() => performance.now()),
     timeoutMs: options.timeoutMs ?? FUSION_WEB_FETCH_TIMEOUT_MS,
     maxResponseBytes: options.maxResponseBytes ?? FUSION_WEB_FETCH_MAX_RESPONSE_BYTES,
     maxOutputBytes: options.maxOutputBytes ?? FUSION_WEB_FETCH_MAX_OUTPUT_BYTES,
@@ -305,11 +312,23 @@ function normalizeRedirectUrl(baseUrl: URL, location: string): URL {
 async function fetchOne(
   url: URL,
   options: EffectiveOptions,
-  remainingMs: number,
+  deadlineMs: number,
   redirectHop: boolean,
 ): Promise<FetchOneResult> {
   const normalized = normalizeRequestUrl(url.toString());
-  const vetted = await vetHost(normalized.hostname, options, redirectHop, normalized.url.toString());
+  const vetted = await vetHost(
+    normalized.hostname,
+    options,
+    redirectHop,
+    normalized.url.toString(),
+    deadlineMs,
+  );
+  const remainingMs = deadlineMs - options.now();
+  if (remainingMs <= 0) {
+    throw new FusionWebFetchError('request_timeout', 'fusion_web_fetch request timeout elapsed', {
+      url: normalized.url.toString(),
+    });
+  }
   return await executeRequest(normalized.url, vetted.selectedAddress, options, remainingMs);
 }
 
@@ -318,6 +337,7 @@ async function vetHost(
   options: EffectiveOptions,
   redirectHop: boolean,
   url: string,
+  deadlineMs: number,
 ): Promise<VettedHost> {
   if (METADATA_HOSTNAMES.has(hostname) || hostname === 'localhost' || hostname.endsWith('.localhost')) {
     throwAddressError(redirectHop, `fusion_web_fetch blocked host: ${hostname}`, url);
@@ -326,7 +346,9 @@ async function vetHost(
   const literalFamily = isIP(hostname);
   const literalAddress: FusionDnsAddress = { address: hostname, family: literalFamily === 4 ? 4 : 6 };
   const resolvedAddresses =
-    literalFamily === 0 ? await resolveWithLookup(hostname, options.lookup, url) : [literalAddress];
+    literalFamily === 0
+      ? await resolveWithLookup(hostname, options.lookup, url, deadlineMs - options.now())
+      : [literalAddress];
 
   if (resolvedAddresses.length === 0) {
     throw new FusionWebFetchError('dns_failure', `DNS lookup returned no addresses for ${hostname}`, { url });
@@ -358,15 +380,38 @@ async function resolveWithLookup(
   hostname: string,
   lookup: FusionDnsLookup,
   url: string,
+  remainingMs: number,
 ): Promise<readonly FusionDnsAddress[]> {
+  if (remainingMs <= 0) {
+    throw new FusionWebFetchError('request_timeout', 'fusion_web_fetch request timeout elapsed', { url });
+  }
+  let timer: NodeJS.Timeout | undefined;
   try {
-    return await lookup(hostname);
+    return await Promise.race([
+      lookup(hostname),
+      new Promise<never>((_resolve, reject) => {
+        timer = setTimeout(
+          () =>
+            reject(
+              new FusionWebFetchError(
+                'request_timeout',
+                'fusion_web_fetch request timeout elapsed during DNS lookup',
+                { url },
+              ),
+            ),
+          Math.max(1, remainingMs),
+        );
+      }),
+    ]);
   } catch (error) {
+    if (error instanceof FusionWebFetchError) throw error;
     throw new FusionWebFetchError(
       'dns_failure',
       `DNS lookup failed for ${hostname}: ${error instanceof Error ? error.message : 'unknown error'}`,
       error instanceof Error ? { url, cause: error } : { url },
     );
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
   }
 }
 
@@ -434,7 +479,9 @@ function executeRequest(
       const status = response.statusCode ?? 0;
       const location = firstHeader(response, 'location');
       if (isRedirectStatus(status)) {
-        response.resume();
+        // Redirect payloads are never consumed. Destroy the response/socket before
+        // advancing so an endless or oversized redirect body cannot outlive this hop.
+        response.destroy();
         if (location === undefined || location.trim().length === 0) {
           settleReject(
             new FusionWebFetchError('http_error', `fusion_web_fetch redirect status ${String(status)} lacks Location`, {
@@ -638,18 +685,18 @@ function readContentLength(value: string | undefined, url: string, status: numbe
   return Number(trimmed);
 }
 
-function extractContent(
+async function extractContent(
   body: Buffer,
   contentType: string,
   requestedFormat: 'text' | 'markdown',
-): ExtractionResult {
+): Promise<ExtractionResult> {
   try {
     const mediaType = mediaTypeFromContentType(contentType);
     const decoded = decodeBody(body, contentType);
     if (mediaType === 'text/plain') return { content: decoded, format: 'text' };
     if (mediaType === 'text/markdown') return { content: decoded, format: 'markdown' };
     if (requestedFormat === 'text') return { content: htmlToText(decoded), format: 'text' };
-    return { content: htmlToMarkdown(decoded), format: 'markdown' };
+    return { content: await htmlToMarkdown(decoded), format: 'markdown' };
   } catch (error) {
     if (error instanceof FusionWebFetchError) throw error;
     throw new FusionWebFetchError(
@@ -695,10 +742,11 @@ function stripAsciiQuotes(value: string): string {
   return value;
 }
 
-function htmlToMarkdown(html: string): string {
+async function htmlToMarkdown(html: string): Promise<string> {
+  const TurndownServiceClass = await loadTurndownService();
   const stripped = stripUnsafeHtmlBlocks(html);
   const tables = replaceTablesWithTokens(stripped);
-  const turndown = new TurndownService({ bulletListMarker: '-', codeBlockStyle: 'fenced', headingStyle: 'atx' });
+  const turndown = new TurndownServiceClass({ bulletListMarker: '-', codeBlockStyle: 'fenced', headingStyle: 'atx' });
   let markdown = turndown.turndown(tables.html).trim();
   for (const table of tables.replacements) {
     markdown = markdown.replace(table.token, table.markdown);
@@ -706,6 +754,47 @@ function htmlToMarkdown(html: string): string {
   return markdown.trim();
 }
 
+async function loadTurndownService(): Promise<TurndownServiceConstructor> {
+  if (turndownServiceLoad === undefined) {
+    turndownServiceLoad = import('turndown').then((module) => module.default);
+  }
+  try {
+    return await turndownServiceLoad;
+  } catch (error) {
+    turndownServiceLoad = undefined;
+    throw normalizeTurndownLoadError(error);
+  }
+}
+
+function normalizeTurndownLoadError(error: unknown): Error {
+  if (isMissingTurndownDependency(error)) {
+    const details = error instanceof Error ? { cause: error } : {};
+    return new FusionWebFetchError(
+      'extraction_failed',
+      'fusion_web_fetch markdown extraction dependency "turndown" is missing from pi-background-tasks; repair the package install with `pi update --extensions` or `npm install --omit=dev --prefix <pi-background-tasks>`.',
+      details,
+    );
+  }
+  if (error instanceof Error) return error;
+  return new Error(`fusion_web_fetch markdown extraction dependency failed to load: ${String(error)}`);
+}
+
+function isMissingTurndownDependency(error: unknown): boolean {
+  const code = errorCode(error);
+  if (code !== 'MODULE_NOT_FOUND' && code !== 'ERR_MODULE_NOT_FOUND') return false;
+  return errorMessage(error).includes('turndown');
+}
+
+function errorCode(error: unknown): string | undefined {
+  if (typeof error !== 'object' || error === null) return undefined;
+  const code = Reflect.get(error, 'code');
+  return typeof code === 'string' ? code : undefined;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
 function htmlToText(html: string): string {
   const withoutBlocks = stripUnsafeHtmlBlocks(html);
   const withBreaks = withoutBlocks

package/src/core/fusion/workflows.ts

@@ -9,84 +9,145 @@ import {
   fusionValidateCandidateSystemPrompt,
 } from './prompts.js';
 import {
-  FUSION_DEFAULT_CAPABILITY,
+  FUSION_INSPECT_TOOLS,
+  FUSION_NO_TOOLS_CAPABILITY,
+  FUSION_RESEARCH_TOOLS,
   FUSION_VALIDATE_CAPABILITY,
   FusionError,
   type FusionCapability,
+  type FusionContextKind,
+  type FusionPublicWorkflowName,
   type FusionWorkflowId,
 } from './types.js';
 
-export const FUSION_BRAINSTORM_TOOL_NAME = 'fusion_brainstorm';
-export const FUSION_VALIDATE_TOOL_NAME = 'fusion_validate';
+export const FUSION_REASON_TOOL_NAME = 'fusion_reason' as const;
+export const FUSION_INVESTIGATE_TOOL_NAME = 'fusion_investigate' as const;
+export const FUSION_RESEARCH_TOOL_NAME = 'fusion_research' as const;
+export const FUSION_VALIDATE_TOOL_NAME = 'fusion_validate' as const;
 
-/**
- * How a workflow decides which capability its candidate children run with.
- *
- * `caller_selected` lets the tool schema offer a capability argument and defaults
- * to the least-privileged profile. `fixed` pins one capability for every run and
- * makes each other value a loud orchestration failure rather than a silent
- * downgrade.
- */
-export type FusionCapabilityPolicy = 'caller_selected' | 'fixed';
+/** @deprecated v4 recursion-denylist compatibility only; do not register new public APIs with this name. */
+export const FUSION_BRAINSTORM_TOOL_NAME = 'fusion_brainstorm' as const;
 
-/**
- * Stage framing for one Fusion workflow.
- *
- * Everything a workflow can vary lives here: the four system prompts, the
- * capability policy, and presentation strings. Everything else - the conversation
- * projection, canonical input schema, budget policy, evaluation schema, artifact
- * store, and state machine - is shared and must never be branched per workflow.
- */
 export interface FusionWorkflowProfile {
   readonly id: FusionWorkflowId;
-  readonly toolName: string;
-  /** First character of the run id, so artifact directories are self-describing. */
-  readonly runIdPrefix: string;
-  readonly capabilityPolicy: FusionCapabilityPolicy;
-  /** The only capability permitted when `capabilityPolicy` is `fixed`. */
-  readonly fixedCapability: FusionCapability | undefined;
-  readonly defaultCapability: FusionCapability;
+  readonly publicName: FusionPublicWorkflowName;
+  readonly toolName: FusionPublicWorkflowName;
+  /** Human-readable run-id prefix, e.g. `reason-<hex>`. */
+  readonly runIdPrefix: `${FusionWorkflowId}-`;
+  readonly contextKind: FusionContextKind;
+  readonly candidateCapability: FusionCapability;
+  readonly candidateTools: readonly string[];
+  readonly evaluatorCapability: typeof FUSION_NO_TOOLS_CAPABILITY;
+  readonly evaluatorTools: readonly [];
+  readonly mergeCapability: typeof FUSION_NO_TOOLS_CAPABILITY;
+  readonly mergeTools: readonly [];
   readonly candidateSystemPrompt: (capability: FusionCapability) => string;
   readonly evaluatorSystemPrompt: string;
   readonly evaluationRepairSystemPrompt: string;
   readonly mergerSystemPrompt: string;
-  /** Human-readable noun used in progress lines and rendered results. */
   readonly label: string;
 }
 
-export const FUSION_BRAINSTORM_WORKFLOW: FusionWorkflowProfile = Object.freeze({
-  id: 'brainstorm',
-  toolName: FUSION_BRAINSTORM_TOOL_NAME,
-  runIdPrefix: 'f',
-  capabilityPolicy: 'caller_selected',
-  fixedCapability: undefined,
-  defaultCapability: FUSION_DEFAULT_CAPABILITY,
+function freezeProfile(profile: FusionWorkflowProfile): FusionWorkflowProfile {
+  const empty = Object.freeze([]) as readonly [];
+  return Object.freeze({
+    ...profile,
+    candidateTools: Object.freeze([...profile.candidateTools]),
+    evaluatorTools: empty,
+    mergeTools: empty,
+  });
+}
+
+export const FUSION_REASON_WORKFLOW = freezeProfile({
+  id: 'reason',
+  publicName: FUSION_REASON_TOOL_NAME,
+  toolName: FUSION_REASON_TOOL_NAME,
+  runIdPrefix: 'reason-',
+  contextKind: 'session_projection',
+  candidateCapability: FUSION_NO_TOOLS_CAPABILITY,
+  candidateTools: [],
+  evaluatorCapability: FUSION_NO_TOOLS_CAPABILITY,
+  evaluatorTools: [],
+  mergeCapability: FUSION_NO_TOOLS_CAPABILITY,
+  mergeTools: [],
+  candidateSystemPrompt: fusionCandidateSystemPrompt,
+  evaluatorSystemPrompt: FUSION_EVALUATOR_SYSTEM_PROMPT,
+  evaluationRepairSystemPrompt: FUSION_EVALUATION_REPAIR_SYSTEM_PROMPT,
+  mergerSystemPrompt: FUSION_MERGER_SYSTEM_PROMPT,
+  label: 'fusion reason',
+});
+
+export const FUSION_INVESTIGATE_WORKFLOW = freezeProfile({
+  id: 'investigate',
+  publicName: FUSION_INVESTIGATE_TOOL_NAME,
+  toolName: FUSION_INVESTIGATE_TOOL_NAME,
+  runIdPrefix: 'investigate-',
+  contextKind: 'clean_task',
+  candidateCapability: 'inspect',
+  candidateTools: FUSION_INSPECT_TOOLS,
+  evaluatorCapability: FUSION_NO_TOOLS_CAPABILITY,
+  evaluatorTools: [],
+  mergeCapability: FUSION_NO_TOOLS_CAPABILITY,
+  mergeTools: [],
   candidateSystemPrompt: fusionCandidateSystemPrompt,
   evaluatorSystemPrompt: FUSION_EVALUATOR_SYSTEM_PROMPT,
   evaluationRepairSystemPrompt: FUSION_EVALUATION_REPAIR_SYSTEM_PROMPT,
   mergerSystemPrompt: FUSION_MERGER_SYSTEM_PROMPT,
-  label: 'fusion',
+  label: 'fusion investigate',
 });
 
-export const FUSION_VALIDATE_WORKFLOW: FusionWorkflowProfile = Object.freeze({
+export const FUSION_RESEARCH_WORKFLOW = freezeProfile({
+  id: 'research',
+  publicName: FUSION_RESEARCH_TOOL_NAME,
+  toolName: FUSION_RESEARCH_TOOL_NAME,
+  runIdPrefix: 'research-',
+  contextKind: 'clean_task',
+  candidateCapability: 'research',
+  candidateTools: FUSION_RESEARCH_TOOLS,
+  evaluatorCapability: FUSION_NO_TOOLS_CAPABILITY,
+  evaluatorTools: [],
+  mergeCapability: FUSION_NO_TOOLS_CAPABILITY,
+  mergeTools: [],
+  candidateSystemPrompt: fusionCandidateSystemPrompt,
+  evaluatorSystemPrompt: FUSION_EVALUATOR_SYSTEM_PROMPT,
+  evaluationRepairSystemPrompt: FUSION_EVALUATION_REPAIR_SYSTEM_PROMPT,
+  mergerSystemPrompt: FUSION_MERGER_SYSTEM_PROMPT,
+  label: 'fusion research',
+});
+
+export const FUSION_VALIDATE_WORKFLOW = freezeProfile({
   id: 'validate',
+  publicName: FUSION_VALIDATE_TOOL_NAME,
   toolName: FUSION_VALIDATE_TOOL_NAME,
-  runIdPrefix: 'v',
-  capabilityPolicy: 'fixed',
-  fixedCapability: FUSION_VALIDATE_CAPABILITY,
-  defaultCapability: FUSION_VALIDATE_CAPABILITY,
+  runIdPrefix: 'validate-',
+  contextKind: 'clean_task',
+  candidateCapability: FUSION_VALIDATE_CAPABILITY,
+  candidateTools: FUSION_INSPECT_TOOLS,
+  evaluatorCapability: FUSION_NO_TOOLS_CAPABILITY,
+  evaluatorTools: [],
+  mergeCapability: FUSION_NO_TOOLS_CAPABILITY,
+  mergeTools: [],
   candidateSystemPrompt: fusionValidateCandidateSystemPrompt,
   evaluatorSystemPrompt: FUSION_VALIDATE_EVALUATOR_SYSTEM_PROMPT,
   evaluationRepairSystemPrompt: FUSION_VALIDATE_EVALUATION_REPAIR_SYSTEM_PROMPT,
   mergerSystemPrompt: FUSION_VALIDATE_MERGER_SYSTEM_PROMPT,
-  label: 'validate',
+  label: 'fusion validate',
 });
 
 const PROFILES_BY_ID: Readonly<Record<FusionWorkflowId, FusionWorkflowProfile>> = Object.freeze({
-  brainstorm: FUSION_BRAINSTORM_WORKFLOW,
+  reason: FUSION_REASON_WORKFLOW,
+  investigate: FUSION_INVESTIGATE_WORKFLOW,
+  research: FUSION_RESEARCH_WORKFLOW,
   validate: FUSION_VALIDATE_WORKFLOW,
 });
 
+export const FUSION_WORKFLOW_PROFILES = Object.freeze([
+  FUSION_REASON_WORKFLOW,
+  FUSION_INVESTIGATE_WORKFLOW,
+  FUSION_RESEARCH_WORKFLOW,
+  FUSION_VALIDATE_WORKFLOW,
+] as const);
+
 export function fusionWorkflowProfile(id: FusionWorkflowId): FusionWorkflowProfile {
   const profile = PROFILES_BY_ID[id];
   if (profile === undefined) {
@@ -98,33 +159,26 @@ export function fusionWorkflowProfile(id: FusionWorkflowId): FusionWorkflowProfi
   return profile;
 }
 
-/**
- * Resolve the candidate capability for one run under its workflow's policy.
- *
- * A `fixed` workflow rejects each other capability instead of quietly substituting
- * its own: silently accepting `reason` for a validation run would produce a review
- * that never read the code, which is exactly the failure this workflow exists to
- * prevent.
- */
-export function resolveWorkflowCapability(
+export function assertWorkflowCapability(
   profile: FusionWorkflowProfile,
   requested: FusionCapability | undefined,
 ): FusionCapability {
-  if (profile.capabilityPolicy === 'caller_selected') {
-    return requested ?? profile.defaultCapability;
-  }
-  const fixed = profile.fixedCapability;
-  if (fixed === undefined) {
+  if (requested !== undefined && requested !== profile.candidateCapability) {
     throw new FusionError(
-      `fusion workflow ${profile.id} declares a fixed capability policy without a capability`,
+      `fusion workflow ${profile.id} always runs candidates with the ${profile.candidateCapability} capability; received ${String(requested)}`,
       { code: 'orchestration_failed', childCreated: false },
     );
   }
-  if (requested !== undefined && requested !== fixed) {
-    throw new FusionError(
-      `fusion workflow ${profile.id} always runs candidates with the ${fixed} capability; received ${String(requested)}`,
-      { code: 'orchestration_failed', childCreated: false },
-    );
-  }
-  return fixed;
+  return profile.candidateCapability;
 }
+
+/** @deprecated v4 artifact/testing alias. The retired public tool is never registered. */
+export const FUSION_BRAINSTORM_WORKFLOW = FUSION_REASON_WORKFLOW;
+
+export const FUSION_REASON = FUSION_REASON_WORKFLOW;
+export const FUSION_INVESTIGATE = FUSION_INVESTIGATE_WORKFLOW;
+export const FUSION_RESEARCH = FUSION_RESEARCH_WORKFLOW;
+export const FUSION_VALIDATE = FUSION_VALIDATE_WORKFLOW;
+
+/** @deprecated v5 workflows do not default; retained for old imports. */
+export const resolveWorkflowCapability = assertWorkflowCapability;

package/src/extension.ts

@@ -559,7 +559,6 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
       const current = PACKAGE_VERSION ?? 'unknown';
       const latest = latestKnownVersion;
       const pinnedNpm = latest ? `${PACKAGE_NAME}@${latest}` : `${PACKAGE_NAME}@<version>`;
-      const pinnedGit = latest ? `${GIT_INSTALL_TARGET}@v${latest}` : `${GIT_INSTALL_TARGET}@<tag>`;
       const lines = [
         latest
           ? `pi-background-tasks ${current} is installed; ${latest} is the latest published version.`
@@ -567,8 +566,9 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
         'Update from npm:',
         `  pi install npm:${PACKAGE_NAME}@latest`,
         `  pi install npm:${pinnedNpm}`,
-        'Or update from git tags:',
-        `  pi install ${pinnedGit}`,
+        'Git releases are independent of npm versions; use main only when you want current repository state:',
+        `  pi install ${GIT_INSTALL_TARGET}@main`,
+        `For a pinned git release, first verify the tag exists, then use ${GIT_INSTALL_TARGET}@<existing-tag>.`,
         'This command only prints update instructions; it does not install or self-update.',
       ];
       ctx.ui.notify(lines.join('\n'), 'info');