@selesai/code 0.1.19 → 0.2.1

package/dist/extensions/pi-web-agent/src/orchestration/source-profile.ts

@@ -0,0 +1,101 @@
+import type { ResearchSourceKind } from './research-types.js';
+
+export type SourceProfileKind =
+  | 'official-docs'
+  | 'official-api'
+  | 'issue-thread'
+  | 'forum-thread'
+  | 'package-page'
+  | 'community';
+
+export type SourceProfile = {
+  kind: SourceProfileKind;
+  sourceKind: ResearchSourceKind;
+  shouldPreferHeadlessWhenWeak: boolean;
+};
+
+const COMMUNITY_FORUM_HOST_RE = /(^|\.)(community|forum|forums|discuss|discourse)\./;
+
+function profile(
+  kind: SourceProfileKind,
+  sourceKind: ResearchSourceKind,
+  shouldPreferHeadlessWhenWeak: boolean
+): SourceProfile {
+  return { kind, sourceKind, shouldPreferHeadlessWhenWeak };
+}
+
+function parseUrl(rawUrl: string): URL | undefined {
+  try {
+    return new URL(rawUrl);
+  } catch {
+    return undefined;
+  }
+}
+
+function isOfficialApi(host: string, path: string) {
+  return (
+    (host === 'playwright.dev' && path.startsWith('/docs/api/')) ||
+    (host === 'vitest.dev' && path.startsWith('/config/'))
+  );
+}
+
+function isOfficialDocs(host: string, path: string) {
+  return (
+    (host === 'playwright.dev' && path.startsWith('/docs/')) ||
+    (host === 'vitest.dev' && path.startsWith('/guide/')) ||
+    (host === 'github.com' && path.startsWith('/vitest-dev/vitest/') && path.includes('/docs/')) ||
+    host === 'learn.microsoft.com'
+  );
+}
+
+function isIssueThread(host: string, path: string) {
+  return host === 'github.com' && (path.includes('/issues/') || path.includes('/discussions/'));
+}
+
+function hasForumThreadPath(path: string) {
+  return (
+    path.includes('/forum/') ||
+    path.includes('/forums/') ||
+    path.includes('/t/') ||
+    path.includes('/topic/') ||
+    path.includes('/threads/')
+  );
+}
+
+function isForumThread(host: string, path: string) {
+  return (
+    (host === 'reddit.com' && path.includes('/comments/')) ||
+    (host === 'stackoverflow.com' && path.startsWith('/questions/')) ||
+    (COMMUNITY_FORUM_HOST_RE.test(`${host}.`) && hasForumThreadPath(path))
+  );
+}
+
+export function classifySourceProfile(rawUrl: string): SourceProfile {
+  const parsed = parseUrl(rawUrl);
+  if (!parsed) return profile('community', 'community', false);
+
+  const host = parsed.hostname.toLowerCase().replace(/^www\./, '');
+  const path = parsed.pathname.toLowerCase();
+
+  if (isOfficialApi(host, path)) {
+    return profile('official-api', 'official-api', false);
+  }
+
+  if (isOfficialDocs(host, path)) {
+    return profile('official-docs', 'official-docs', false);
+  }
+
+  if (isIssueThread(host, path)) {
+    return profile('issue-thread', 'issue-thread', true);
+  }
+
+  if (isForumThread(host, path)) {
+    return profile('forum-thread', 'community', true);
+  }
+
+  if (host === 'npmjs.com' && path.startsWith('/package/')) {
+    return profile('package-page', 'package-page', false);
+  }
+
+  return profile('community', 'community', false);
+}

package/dist/extensions/pi-web-agent/src/orchestration/stop-decider.ts

@@ -0,0 +1,81 @@
+import type { ResearchEvidence } from './research-types.js';
+import type { EvidenceQualityReport } from './evidence-quality.js';
+import { hasOfficialEvidence, strongEvidenceCount } from './evidence-ranker.js';
+
+export type ResearchStepDecision =
+  | { action: 'answer' }
+  | { action: 'answer-with-caveat' }
+  | { action: 'search-again' }
+  | { action: 'headless'; url: string };
+
+function activeCaveatReasons(evidence: ResearchEvidence[], quality?: EvidenceQualityReport) {
+  const reasons = quality?.caveatReasons ?? [];
+  if (!hasOfficialDocsAndApi(evidence)) return reasons;
+  return reasons.filter((reason) => reason !== 'low-diversity');
+}
+
+function hasQualityConcern(evidence: ResearchEvidence[], quality?: EvidenceQualityReport) {
+  return activeCaveatReasons(evidence, quality).length > 0;
+}
+
+function hasOfficialDocsAndApi(evidence: ResearchEvidence[]) {
+  return evidence.some((item) => item.sourceKind === 'official-docs') &&
+    evidence.some((item) => item.sourceKind === 'official-api');
+}
+
+function shouldSearchForBetterQuality({
+  evidence,
+  quality,
+  passIndex,
+  maxPasses
+}: {
+  evidence: ResearchEvidence[];
+  quality?: EvidenceQualityReport;
+  passIndex: number;
+  maxPasses: number;
+}) {
+  if (!quality) return false;
+  if (passIndex + 1 >= maxPasses) return false;
+  if (quality.flags.hasOnlyCommunityEvidence) return true;
+  if (quality.flags.hasLowDiversity && !hasOfficialDocsAndApi(evidence)) return true;
+  return false;
+}
+
+export function decideNextResearchStep({
+  evidence,
+  suggestedHeadlessUrls,
+  passIndex,
+  maxPasses,
+  headlessAttempts,
+  maxHeadlessAttempts,
+  quality
+}: {
+  evidence: ResearchEvidence[];
+  suggestedHeadlessUrls: string[];
+  passIndex: number;
+  maxPasses: number;
+  headlessAttempts: number;
+  maxHeadlessAttempts: number;
+  quality?: EvidenceQualityReport;
+}): ResearchStepDecision {
+  const strongEnough = strongEvidenceCount(evidence) >= 2 && hasOfficialEvidence(evidence);
+
+  if (strongEnough && shouldSearchForBetterQuality({ evidence, quality, passIndex, maxPasses })) {
+    return { action: 'search-again' };
+  }
+
+  if (strongEnough) {
+    return hasQualityConcern(evidence, quality) ? { action: 'answer-with-caveat' } : { action: 'answer' };
+  }
+
+  const headlessUrl = suggestedHeadlessUrls.find((url) => !url.includes('npmjs.com/package/'));
+  if (headlessUrl && headlessAttempts < maxHeadlessAttempts) {
+    return { action: 'headless', url: headlessUrl };
+  }
+
+  if (passIndex + 1 < maxPasses) {
+    return { action: 'search-again' };
+  }
+
+  return { action: 'answer-with-caveat' };
+}

package/dist/extensions/pi-web-agent/src/presentation/config-store.ts

@@ -0,0 +1,208 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { getAgentDir } from '@earendil-works/pi-coding-agent';
+import {
+  DEFAULT_BACKEND_CONFIG,
+  extractBackendConfigOverride,
+  mergeBackendConfigLayers,
+  type BackendConfig,
+  type BackendConfigFile,
+  type BackendConfigOverride
+} from '../backends/config.js';
+import {
+  DEFAULT_PRESENTATION_CONFIG,
+  extractPresentationConfigOverride,
+  mergePresentationConfigLayers
+} from './config.js';
+import type {
+  PresentationConfig,
+  PresentationConfigFile,
+  PresentationConfigOverride,
+  PresentationScope
+} from './types.js';
+
+export type PresentationConfigStoreOptions = {
+  homeDir?: string;
+  projectDir?: string;
+};
+
+export type PresentationConfigLayer = {
+  path: string;
+  exists: boolean;
+  rawConfig?: PresentationConfigOverride;
+  rawBackends?: BackendConfigOverride;
+  error?: string;
+};
+
+export type LoadedPresentationConfig = {
+  global: PresentationConfigLayer;
+  project: PresentationConfigLayer;
+  effectiveConfig: PresentationConfig;
+  effectiveBackends: BackendConfig;
+};
+
+export function getPresentationConfigPaths(options: PresentationConfigStoreOptions = {}) {
+  // ponytail: use selesai's getAgentDir() so the config dir respects the active
+  // CONFIG_DIR_NAME (e.g. .selesai) instead of upstream's hardcoded .pi. Ceiling:
+  // if selesai changes the extensions config layout, update here; upgrade path =
+  // upstream pi-web-agent accepting a config-dir resolver.
+  const homeDir = options.homeDir ?? process.env.USERPROFILE ?? process.env.HOME ?? '';
+  const projectDir = options.projectDir ?? process.cwd();
+  const agentDir = getAgentDir();
+  // agentDir is already <homeDir>/<CONFIG_DIR_NAME>/agent; derive the home-relative config dir.
+  const globalConfigRoot = path.join(agentDir, 'extensions', 'pi-web-agent', 'config.json');
+
+  return {
+    globalPath: globalConfigRoot,
+    projectPath: path.join(projectDir, '.pi', 'extensions', 'pi-web-agent', 'config.json')
+  };
+}
+
+type AgentConfigFile = PresentationConfigFile & BackendConfigFile;
+
+type LegacyPresentationConfigFile = NonNullable<PresentationConfigFile['presentation']>;
+
+function hasPresentationRoot(parsed: AgentConfigFile) {
+  return parsed.presentation !== undefined;
+}
+
+async function readPresentationConfigFile(filePath: string): Promise<PresentationConfigLayer> {
+  try {
+    const rawText = await readFile(filePath, 'utf8');
+    const parsed = JSON.parse(rawText) as AgentConfigFile;
+    const presentationFile: PresentationConfigFile = hasPresentationRoot(parsed)
+      ? parsed
+      : { presentation: parsed as LegacyPresentationConfigFile };
+
+    return {
+      path: filePath,
+      exists: true,
+      rawConfig: extractPresentationConfigOverride(presentationFile),
+      rawBackends: extractBackendConfigOverride(parsed)
+    };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException | undefined)?.code === 'ENOENT') {
+      return { path: filePath, exists: false };
+    }
+
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      path: filePath,
+      exists: true,
+      error: message
+    };
+  }
+}
+
+function serializePresentationConfigOverride(config: PresentationConfigOverride): PresentationConfigFile {
+  const presentation: NonNullable<PresentationConfigFile['presentation']> = {};
+
+  if (config.defaultMode) {
+    presentation.defaultMode = config.defaultMode;
+  }
+
+  if (Object.keys(config.tools).length > 0) {
+    presentation.tools = config.tools;
+  }
+
+  return { presentation };
+}
+
+function serializeBackendConfigOverride(config: BackendConfigOverride): BackendConfigFile {
+  const backends: NonNullable<BackendConfigFile['backends']> = {};
+
+  if (config.search && Object.keys(config.search).length > 0) {
+    backends.search = { ...config.search };
+  }
+
+  if (config.fetch && Object.keys(config.fetch).length > 0) {
+    const { apiKey: _apiKey, ...fetch } = config.fetch;
+    backends.fetch = { ...fetch };
+  }
+
+  if (config.headless && Object.keys(config.headless).length > 0) {
+    backends.headless = { ...config.headless };
+  }
+
+  return { backends };
+}
+
+async function readConfigFileForWrite(filePath: string): Promise<AgentConfigFile> {
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8')) as AgentConfigFile;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException | undefined)?.code === 'ENOENT') {
+      return {};
+    }
+
+    throw error;
+  }
+}
+
+async function writeConfigFile(filePath: string, config: AgentConfigFile) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+}
+
+export async function loadPresentationConfigLayers(
+  options: PresentationConfigStoreOptions = {}
+): Promise<LoadedPresentationConfig> {
+  const { globalPath, projectPath } = getPresentationConfigPaths(options);
+  const global = await readPresentationConfigFile(globalPath);
+  const project = await readPresentationConfigFile(projectPath);
+
+  return {
+    global,
+    project,
+    effectiveConfig: mergePresentationConfigLayers(
+      DEFAULT_PRESENTATION_CONFIG,
+      global.rawConfig,
+      project.rawConfig
+    ),
+    effectiveBackends: mergeBackendConfigLayers(
+      DEFAULT_BACKEND_CONFIG,
+      global.rawBackends,
+      project.rawBackends
+    )
+  };
+}
+
+export async function savePresentationConfigScope(
+  options: PresentationConfigStoreOptions,
+  scope: PresentationScope,
+  config: PresentationConfigOverride
+) {
+  const { globalPath, projectPath } = getPresentationConfigPaths(options);
+  const filePath = scope === 'global' ? globalPath : projectPath;
+  const existing = await readConfigFileForWrite(filePath);
+
+  await writeConfigFile(filePath, {
+    ...existing,
+    ...serializePresentationConfigOverride(config)
+  });
+}
+
+export async function saveBackendConfigScope(
+  options: PresentationConfigStoreOptions,
+  scope: PresentationScope,
+  config: BackendConfigOverride
+) {
+  const { globalPath, projectPath } = getPresentationConfigPaths(options);
+  const filePath = scope === 'global' ? globalPath : projectPath;
+  const existing = await readConfigFileForWrite(filePath);
+
+  await writeConfigFile(filePath, {
+    ...existing,
+    ...serializeBackendConfigOverride(config)
+  });
+}
+
+export async function resetPresentationConfigScope(
+  options: PresentationConfigStoreOptions,
+  scope: PresentationScope
+) {
+  const { globalPath, projectPath } = getPresentationConfigPaths(options);
+  const filePath = scope === 'global' ? globalPath : projectPath;
+
+  await rm(filePath, { force: true });
+}

package/dist/extensions/pi-web-agent/src/presentation/config.ts

@@ -0,0 +1,75 @@
+import {
+  PRESENTATION_MODES,
+  type PresentationConfig,
+  type PresentationConfigFile,
+  type PresentationConfigOverride,
+  type PresentationMode,
+  type PresentationToolName
+} from './types.js';
+
+const PRESENTATION_MODE_SET = new Set<string>(PRESENTATION_MODES);
+
+export const DEFAULT_PRESENTATION_CONFIG: PresentationConfig = {
+  defaultMode: 'compact',
+  tools: {}
+};
+
+export function isPresentationMode(value: unknown): value is PresentationMode {
+  return typeof value === 'string' && PRESENTATION_MODE_SET.has(value);
+}
+
+export function extractPresentationConfigOverride(
+  file: PresentationConfigFile | null | undefined
+): PresentationConfigOverride {
+  const presentation = file?.presentation;
+  const tools = Object.fromEntries(
+    Object.entries(presentation?.tools ?? {}).flatMap(([toolName, value]) => {
+      if (!value || !isPresentationMode(value.mode)) {
+        return [];
+      }
+
+      return [[toolName, { mode: value.mode }]];
+    })
+  ) as PresentationConfig['tools'];
+
+  return {
+    defaultMode: isPresentationMode(presentation?.defaultMode)
+      ? presentation.defaultMode
+      : undefined,
+    tools
+  };
+}
+
+export function normalizePresentationConfigFile(
+  file: PresentationConfigFile | null | undefined
+): PresentationConfig {
+  const override = extractPresentationConfigOverride(file);
+
+  return {
+    defaultMode: override.defaultMode ?? DEFAULT_PRESENTATION_CONFIG.defaultMode,
+    tools: override.tools
+  };
+}
+
+export function mergePresentationConfigLayers(
+  defaults: PresentationConfig,
+  globalConfig?: PresentationConfigOverride,
+  projectConfig?: PresentationConfigOverride
+): PresentationConfig {
+  return {
+    defaultMode:
+      projectConfig?.defaultMode ?? globalConfig?.defaultMode ?? defaults.defaultMode,
+    tools: {
+      ...defaults.tools,
+      ...globalConfig?.tools,
+      ...projectConfig?.tools
+    }
+  };
+}
+
+export function resolvePresentationMode(
+  toolName: PresentationToolName,
+  config: PresentationConfig = DEFAULT_PRESENTATION_CONFIG
+): PresentationMode {
+  return config.tools[toolName]?.mode ?? config.defaultMode;
+}

package/dist/extensions/pi-web-agent/src/presentation/explore-presentation.ts

@@ -0,0 +1,61 @@
+import type { WebExploreResponse } from '../types.js';
+import type { PresentationEnvelope } from './types.js';
+
+function internalReaderLabel(method?: 'http' | 'headless' | 'firecrawl') {
+  if (method === 'headless') return 'web_fetch_headless';
+  if (method === 'firecrawl') return 'firecrawl';
+  if (method === 'http') return 'web_fetch';
+  return 'web_explore';
+}
+
+export function buildExplorePresentation(result: WebExploreResponse): PresentationEnvelope {
+  if (result.status === 'error') {
+    return {
+      mode: 'compact',
+      views: {
+        compact: `Research failed: ${result.error?.message ?? 'Unknown research failure.'}`
+      }
+    };
+  }
+
+  const internalSummary = result.metadata
+    ? `Internal research: web_search ×${result.metadata.searchPasses}, web_fetch ×${result.metadata.fetchedPages}, web_fetch_headless ×${result.metadata.headlessAttempts}`
+    : undefined;
+  const hasEvidence = result.findings.length > 0 || result.sources.length > 0;
+  const evidenceLines = hasEvidence
+    ? result.findings.map((finding, index) => `- [${internalReaderLabel(result.sources[index]?.method)}] ${finding}`)
+    : ['No usable evidence found.'];
+  const preview = [
+    ...evidenceLines,
+    internalSummary ? `\n${internalSummary}` : undefined
+  ]
+    .filter((line) => line !== undefined)
+    .join('\n');
+  const verbose = [
+    'Findings',
+    ...evidenceLines,
+    '',
+    'Sources',
+    ...result.sources.map((source) => `- [${internalReaderLabel(source.method)}] ${source.title}: ${source.url}`),
+    internalSummary ? `\nInternal tools\n${internalSummary}` : undefined,
+    result.caveat ? `\nCaveat\n${result.caveat}` : undefined
+  ]
+    .filter((line) => line !== undefined)
+    .join('\n');
+
+  return {
+    mode: 'compact',
+    views: {
+      compact: hasEvidence
+        ? `Reviewed ${result.sources.length} sources · synthesized answer with ${result.findings.length} findings`
+        : 'No usable evidence found',
+      preview,
+      verbose
+    },
+    metrics: {
+      sourceCount: result.sources.length,
+      resultCount: result.findings.length
+    },
+    sources: result.sources
+  };
+}

package/dist/extensions/pi-web-agent/src/presentation/fetch-presentation.ts

@@ -0,0 +1,54 @@
+import type { WebFetchHeadlessResponse, WebFetchResponse } from '../types.js';
+import type { PresentationEnvelope } from './types.js';
+
+type FetchLike = WebFetchResponse | WebFetchHeadlessResponse;
+
+function countWords(text: string | undefined): number | undefined {
+  return text?.trim() ? text.trim().split(/\s+/).length : undefined;
+}
+
+function firstExcerpt(text: string | undefined, maxChars = 240): string | undefined {
+  if (!text) {
+    return undefined;
+  }
+
+  return text.length <= maxChars ? text : `${text.slice(0, maxChars).trimEnd()}…`;
+}
+
+export function buildFetchPresentation(result: FetchLike): PresentationEnvelope {
+  const wordCount = countWords(result.content?.text);
+  const fallbackPrefix = result.metadata.fallbackFrom
+    ? `${result.metadata.fallbackFrom} failed; used ${result.metadata.method} fallback. `
+    : '';
+  const compact =
+    result.status === 'ok'
+      ? `${fallbackPrefix}Fetched page · article extracted${wordCount ? ` · ${wordCount} words` : ''}`
+      : result.status === 'needs_headless'
+        ? `${fallbackPrefix}Needs headless rendering: ${result.error?.message ?? 'Headless rendering recommended.'}`
+        : `${fallbackPrefix}Fetch failed: ${result.error?.message ?? 'Unknown fetch failure.'}`;
+
+  return {
+    mode: 'compact',
+    views: {
+      compact,
+      preview: result.content?.title
+        ? `${result.content.title}\n${firstExcerpt(result.content.text) ?? ''}`.trim()
+        : firstExcerpt(result.content?.text),
+      verbose:
+        result.status === 'ok'
+          ? [
+              `URL: ${result.url}`,
+              result.content?.title ? `Title: ${result.content.title}` : undefined,
+              firstExcerpt(result.content?.text, 500)
+            ]
+              .filter(Boolean)
+              .join('\n')
+          : undefined
+    },
+    metrics: {
+      wordCount,
+      cacheHit: result.metadata.cacheHit
+    },
+    sources: [{ title: result.content?.title ?? result.url, url: result.url }]
+  };
+}

package/dist/extensions/pi-web-agent/src/presentation/search-presentation.ts

@@ -0,0 +1,41 @@
+import type { WebSearchResponse } from '../types.js';
+import type { PresentationEnvelope } from './types.js';
+
+function formatCompact(result: WebSearchResponse): string {
+  const fallbackPrefix = result.metadata.fallbackFrom
+    ? `${result.metadata.fallbackFrom} failed; used ${result.metadata.backend} fallback. `
+    : '';
+
+  if (result.status === 'error') {
+    return `${fallbackPrefix}Search failed: ${result.error?.message ?? 'Unknown search failure.'}`;
+  }
+
+  const suffix = result.results.length === 1 ? 'result' : 'results';
+  return `${fallbackPrefix}Found ${result.results.length} ${suffix}`;
+}
+
+export function buildSearchPresentation(result: WebSearchResponse): PresentationEnvelope {
+  const preview = result.results
+    .slice(0, 3)
+    .map((item, index) => `${index + 1}. ${item.title}`)
+    .join('\n');
+
+  const verbose = result.results
+    .slice(0, 5)
+    .map((item, index) => `${index + 1}. ${item.title}\n   ${item.url}\n   ${item.snippet}`)
+    .join('\n');
+
+  return {
+    mode: 'compact',
+    views: {
+      compact: formatCompact(result),
+      preview: preview || undefined,
+      verbose: verbose || undefined
+    },
+    metrics: {
+      resultCount: result.results.length,
+      cacheHit: result.metadata.cacheHit
+    },
+    sources: result.results.map((item) => ({ title: item.title, url: item.url }))
+  };
+}

package/dist/extensions/pi-web-agent/src/presentation/select-view.ts

@@ -0,0 +1,20 @@
+import type { PresentationEnvelope, PresentationMode } from './types.js';
+
+export function selectPresentationView(
+  envelope: PresentationEnvelope | undefined,
+  requestedMode: PresentationMode
+): string | undefined {
+  if (!envelope) {
+    return undefined;
+  }
+
+  if (requestedMode === 'preview' && envelope.views.preview) {
+    return envelope.views.preview;
+  }
+
+  if (requestedMode === 'verbose' && envelope.views.verbose) {
+    return envelope.views.verbose;
+  }
+
+  return envelope.views.compact;
+}