kimi-agent-swarm-cli 0.7.0

package/src/providers/serper-provider.ts

@@ -0,0 +1,154 @@
+import type { SearchOptions, SearchProvider } from "./search-provider";
+import type { Source, SourceScores, UsageMetrics } from "../types";
+
+interface SerperOrganicResult {
+  title: string;
+  link: string;
+  snippet: string;
+  date?: string;
+}
+
+interface SerperResponse {
+  organic?: SerperOrganicResult[];
+  searchParameters?: {
+    q: string;
+  };
+}
+
+function parseRelativeDate(dateText: string): string | undefined {
+  const normalized = dateText.toLowerCase().trim();
+  const now = new Date();
+
+  const dayMatch = normalized.match(/^(\d+)\s+day(?:s)?\s+ago$/);
+  if (dayMatch) {
+    const days = Number.parseInt(dayMatch[1], 10);
+    const date = new Date(now.getTime() - days * 24 * 60 * 60 * 1000);
+    return date.toISOString().split("T")[0];
+  }
+
+  const monthMatch = normalized.match(/^(\d+)\s+month(?:s)?\s+ago$/);
+  if (monthMatch) {
+    const months = Number.parseInt(monthMatch[1], 10);
+    const date = new Date(now.getFullYear(), now.getMonth() - months, now.getDate());
+    return date.toISOString().split("T")[0];
+  }
+
+  const yearMatch = normalized.match(/^(\d+)\s+year(?:s)?\s+ago$/);
+  if (yearMatch) {
+    const years = Number.parseInt(yearMatch[1], 10);
+    const date = new Date(now.getFullYear() - years, now.getMonth(), now.getDate());
+    return date.toISOString().split("T")[0];
+  }
+
+  return undefined;
+}
+
+function parsePublishedAt(dateText: string): string {
+  if (!dateText) return new Date().toISOString().split("T")[0];
+
+  // ISO date
+  if (/^\d{4}-\d{2}-\d{2}$/.test(dateText)) {
+    return dateText;
+  }
+
+  // Relative date
+  const relative = parseRelativeDate(dateText);
+  if (relative) return relative;
+
+  // Month Day, Year (e.g., "May 14, 2026")
+  const parsed = new Date(dateText);
+  if (!Number.isNaN(parsed.getTime())) {
+    return parsed.toISOString().split("T")[0];
+  }
+
+  return new Date().toISOString().split("T")[0];
+}
+
+function inferSourceClass(url: string): "primary" | "secondary" {
+  try {
+    const hostname = new URL(url).hostname.toLowerCase();
+    // Treat official code repos, major docs, and government/regulator sites as primary-ish
+    if (
+      hostname === "github.com" ||
+      hostname.endsWith(".github.io") ||
+      hostname === "arxiv.org" ||
+      hostname.endsWith(".gov")
+    ) {
+      return "primary";
+    }
+  } catch {
+    // invalid URL, fall through to secondary
+  }
+  return "secondary";
+}
+
+function buildScores(sourceClass: "primary" | "secondary"): SourceScores {
+  return {
+    relevance: 4,
+    authority: sourceClass === "primary" ? 4 : 3,
+    freshness: 4,
+    diversity: 3,
+    extractionValue: sourceClass === "primary" ? 4 : 3,
+  };
+}
+
+export class SerperSearchProvider implements SearchProvider {
+  readonly name = "serper";
+  private readonly apiKey: string;
+  private readonly metrics?: UsageMetrics;
+
+  constructor(apiKey: string, metrics?: UsageMetrics) {
+    if (!apiKey) {
+      throw new Error("SerperSearchProvider requires a non-empty API key");
+    }
+    this.apiKey = apiKey;
+    this.metrics = metrics;
+  }
+
+  async search({ objective, maxResults }: SearchOptions): Promise<Source[]> {
+    if (this.metrics) {
+      this.metrics.providerCalls += 1;
+      this.metrics.apiCalls += 1;
+    }
+
+    const response = await fetch("https://google.serper.dev/search", {
+      method: "POST",
+      headers: {
+        "X-API-KEY": this.apiKey,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        q: objective,
+        num: Math.min(Math.max(maxResults, 1), 100),
+      }),
+    });
+
+    if (!response.ok) {
+      const body = await response.text().catch(() => "unknown");
+      if (response.status === 429) {
+        throw new Error(`Serper API rate limit exceeded (429): ${body}`);
+      }
+      if (response.status === 401) {
+        throw new Error(`Serper API unauthorized (401): check SERPER_API_KEY`);
+      }
+      throw new Error(`Serper API error: ${response.status} ${body}`);
+    }
+
+    const data = (await response.json()) as SerperResponse;
+    const results = data.organic ?? [];
+
+    return results.slice(0, maxResults).map((result, index) => {
+      const sourceClass = inferSourceClass(result.link);
+      return {
+        id: `SERPER-${String(index + 1).padStart(3, "0")}`,
+        url: result.link,
+        title: result.title,
+        sourceClass,
+        publishedAt: parsePublishedAt(result.date ?? ""),
+        discoveredBy: "serper-search-provider",
+        scores: buildScores(sourceClass),
+        claims: [result.snippet],
+      };
+    });
+  }
+}

package/src/providers/tavily-provider.ts

@@ -0,0 +1,158 @@
+import type { SearchOptions, SearchProvider } from "./search-provider";
+import type { Source, SourceScores, UsageMetrics } from "../types";
+
+interface TavilyResult {
+  title: string;
+  url: string;
+  content: string;
+  score: number;
+  published_date?: string;
+}
+
+interface TavilyResponse {
+  query?: string;
+  answer?: string;
+  results?: TavilyResult[];
+}
+
+function inferSourceClass(url: string): "primary" | "secondary" {
+  try {
+    const hostname = new URL(url).hostname.toLowerCase();
+    if (
+      hostname === "github.com" ||
+      hostname.endsWith(".github.io") ||
+      hostname === "arxiv.org" ||
+      hostname.endsWith(".gov") ||
+      hostname.endsWith(".edu") ||
+      hostname.endsWith(".ac.uk")
+    ) {
+      return "primary";
+    }
+  } catch {
+    // invalid URL, fall through to secondary
+  }
+  return "secondary";
+}
+
+function parsePublishedAt(dateText?: string): string {
+  if (!dateText) return new Date().toISOString().split("T")[0];
+
+  if (/^\d{4}-\d{2}-\d{2}$/.test(dateText)) {
+    return dateText;
+  }
+
+  const parsed = new Date(dateText);
+  if (!Number.isNaN(parsed.getTime())) {
+    return parsed.toISOString().split("T")[0];
+  }
+
+  return new Date().toISOString().split("T")[0];
+}
+
+function buildScores(tavilyScore: number, sourceClass: "primary" | "secondary"): SourceScores {
+  const scaledRelevance = Math.max(1, Math.min(5, Math.round(tavilyScore * 5)));
+  return {
+    relevance: scaledRelevance,
+    authority: sourceClass === "primary" ? 4 : 3,
+    freshness: 4,
+    diversity: 3,
+    extractionValue: sourceClass === "primary" ? 4 : 3,
+  };
+}
+
+function mockResults(objective: string): Source[] {
+  const now = new Date().toISOString().split("T")[0];
+  return [
+    {
+      id: "TAVILY-001",
+      url: "https://example.com/mock/tavily-result-1",
+      title: `Tavily mock result for: ${objective}`,
+      sourceClass: "primary",
+      publishedAt: now,
+      discoveredBy: "tavily-search-provider-mock",
+      scores: { relevance: 5, authority: 4, freshness: 5, diversity: 3, extractionValue: 4 },
+      claims: [
+        "Tavily mock search returned a high-relevance primary source.",
+        "This is a deterministic fixture for CI and development.",
+      ],
+    },
+    {
+      id: "TAVILY-002",
+      url: "https://example.com/mock/tavily-result-2",
+      title: "Tavily mock secondary perspective",
+      sourceClass: "secondary",
+      publishedAt: now,
+      discoveredBy: "tavily-search-provider-mock",
+      scores: { relevance: 3, authority: 3, freshness: 4, diversity: 4, extractionValue: 3 },
+      claims: ["Secondary sources broaden coverage in a wide search."],
+    },
+  ];
+}
+
+export class TavilySearchProvider implements SearchProvider {
+  readonly name = "tavily";
+  private readonly apiKey: string;
+  private readonly metrics?: UsageMetrics;
+
+  constructor(apiKey: string, metrics?: UsageMetrics) {
+    this.apiKey = apiKey;
+    this.metrics = metrics;
+  }
+
+  async search({ objective, maxResults }: SearchOptions): Promise<Source[]> {
+    if (this.metrics) {
+      this.metrics.providerCalls += 1;
+      this.metrics.apiCalls += 1;
+    }
+
+    if (!this.apiKey) {
+      if (process.env.TAVILY_MOCK === "1") {
+        return mockResults(objective).slice(0, maxResults);
+      }
+      throw new Error(
+        "TAVILY_API_KEY environment variable is required for the tavily provider (or set TAVILY_MOCK=1 for CI)",
+      );
+    }
+
+    const response = await fetch("https://api.tavily.com/search", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        api_key: this.apiKey,
+        query: objective,
+        max_results: Math.min(Math.max(maxResults, 1), 100),
+        include_answer: false,
+      }),
+    });
+
+    if (!response.ok) {
+      const body = await response.text().catch(() => "unknown");
+      if (response.status === 429) {
+        throw new Error(`Tavily API rate limit exceeded (429): ${body}`);
+      }
+      if (response.status === 401) {
+        throw new Error(`Tavily API unauthorized (401): check TAVILY_API_KEY`);
+      }
+      throw new Error(`Tavily API error: ${response.status} ${body}`);
+    }
+
+    const data = (await response.json()) as TavilyResponse;
+    const results = data.results ?? [];
+
+    return results.slice(0, maxResults).map((result, index) => {
+      const sourceClass = inferSourceClass(result.url);
+      return {
+        id: `TAVILY-${String(index + 1).padStart(3, "0")}`,
+        url: result.url,
+        title: result.title,
+        sourceClass,
+        publishedAt: parsePublishedAt(result.published_date),
+        discoveredBy: "tavily-search-provider",
+        scores: buildScores(result.score, sourceClass),
+        claims: [result.content],
+      };
+    });
+  }
+}

package/src/runtime.ts

@@ -0,0 +1,349 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { getCachedSources, setCachedSources } from "./cache";
+import { loadCommandSources } from "./command-provider";
+import { loadConfig, resolveProviderCredential } from "./config";
+import {
+  calculateActualCost,
+  checkBudget,
+  checkEstimatedBudget,
+  estimateRunCost,
+  formatCostReport,
+  maxResultsForDepth,
+} from "./costs";
+import { runDistributedWideSearch } from "./distributed/runner";
+import { createSearchProvider } from "./providers";
+import { scoreSource } from "./scorer";
+import { verifyRun } from "./verifier";
+import type {
+  BudgetOptions,
+  Claim,
+  ClaimConfidence,
+  ClaimFreshness,
+  EnrichedSource,
+  ExecutionProfile,
+  LoadSourcesOptions,
+  ResearchPlan,
+  Run,
+  RunWideSearchOptions,
+  RunWideSearchResult,
+  SearchDepth,
+  Source,
+  UsageMetrics,
+  VerificationReport,
+} from "./types";
+
+function makeRunId(): string {
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const suffix = Math.random().toString(36).slice(2, 8);
+  return `${stamp}-${suffix}`;
+}
+
+function claimConfidence(source: Source): ClaimConfidence {
+  const authority = source.scores?.authority ?? 0;
+  if (authority >= 4) return "high";
+  if (authority >= 2) return "medium";
+  return "low";
+}
+
+function claimFreshness(source: Source): ClaimFreshness {
+  if (!source.publishedAt || source.publishedAt === "unknown") return "unknown";
+
+  const now = new Date();
+  const oneYearAgo = new Date(now.getFullYear() - 1, now.getMonth(), now.getDate())
+    .toISOString()
+    .split("T")[0];
+
+  return source.publishedAt >= oneYearAgo ? "current" : "stale";
+}
+
+const FIXTURE_FILE_MAP: Record<string, string> = {
+  fixture: "basic-sources.json",
+  "fixture-asset-mgmt": "asset-mgmt-roles.json",
+  "fixture-sellside-research": "sellside-research-roles.json",
+  "fixture-youtube-niche": "youtube-niche.json",
+  "fixture-paul-graham-corpus": "paul-graham-corpus.json",
+  "fixture-github-repo-landscape": "github-repo-landscape.json",
+  "fixture-market-scan": "market-scan.json",
+};
+
+async function loadFixtureSources(profile: ExecutionProfile): Promise<Source[]> {
+  const fileName = FIXTURE_FILE_MAP[profile];
+  if (fileName === undefined) {
+    throw new Error(`unknown fixture profile: ${profile}`);
+  }
+  const fixtureUrl = new URL(`../fixtures/${fileName}`, import.meta.url);
+  const fixture = JSON.parse(await readFile(fixtureUrl, "utf8")) as { sources: Source[] };
+  return fixture.sources;
+}
+
+async function loadSources({
+  profile,
+  objective,
+  providerCommand,
+  providerArgs,
+  providerName,
+  searchDepth,
+  metrics,
+  useCache,
+}: LoadSourcesOptions): Promise<Source[]> {
+  if (profile.startsWith("fixture")) {
+    return loadFixtureSources(profile);
+  }
+
+  if (profile === "local-command") {
+    return loadCommandSources({ providerCommand, providerArgs, objective });
+  }
+
+  if (profile === "web-search") {
+    const depth = searchDepth ?? "standard";
+    const maxResults = maxResultsForDepth(depth);
+    const cacheKey = { provider: providerName ?? "mock", objective, depth, maxResults };
+
+    if (useCache && providerName && providerName !== "mock") {
+      const cached = await getCachedSources(cacheKey);
+      if (cached) {
+        if (metrics) {
+          metrics.notes = metrics.notes ? `${metrics.notes}; cache hit` : "cache hit";
+        }
+        return cached;
+      }
+    }
+
+    const config = await loadConfig();
+    const credential = resolveProviderCredential(config, providerName ?? "mock");
+    const provider = createSearchProvider(providerName ?? "mock", { credential, metrics });
+    const sources = await provider.search({
+      objective,
+      depth,
+      maxResults,
+    });
+
+    if (useCache && providerName && providerName !== "mock") {
+      await setCachedSources(cacheKey, sources);
+    }
+
+    return sources;
+  }
+
+  throw new Error(`unsupported execution profile: ${profile}`);
+}
+
+
+function renderSynthesis({
+  objective,
+  profile,
+  sources,
+  claims,
+  verification,
+}: {
+  objective: string;
+  profile: ExecutionProfile;
+  sources: EnrichedSource[];
+  claims: Claim[];
+  verification: VerificationReport;
+}): string {
+  const accepted = sources.filter((source) => source.decision === "accepted");
+  const rejected = sources.filter((source) => source.decision === "rejected");
+  const topRows = claims
+    .map(
+      (claim) =>
+        `| ${claim.claim} | ${claim.sourceIds.join(", ")} | ${claim.confidence} |`,
+    )
+    .join("\n");
+
+  return `# Wide-Search Synthesis
+
+## Answer
+${objective}
+
+The ${profile} run found ${accepted.length} accepted source(s) and ${rejected.length} rejected source(s). The accepted evidence supports ${claims.length} claim(s).
+
+## Top Findings
+| Finding | Evidence | Confidence |
+| --- | --- | --- |
+${topRows}
+
+## Source Coverage
+- Accepted sources: ${accepted.length}
+- Rejected sources: ${rejected.length}
+- Verification status: ${verification.status}
+
+## Evidence
+- Source ledger: source-ledger.jsonl
+- Claim ledger: claim-ledger.jsonl
+- Verification: verification-report.json
+
+## Next Human Check
+- Review the accepted sources and rerun with a broader search profile before making production decisions.
+`;
+}
+
+function resolveProviderName(profile: ExecutionProfile, providerName?: string): string {
+  if (profile === "web-search") {
+    return providerName ?? "mock";
+  }
+  return "mock";
+}
+
+export async function runWideSearch({
+  objective,
+  profile = "fixture",
+  providerCommand,
+  providerArgs = [],
+  providerName,
+  searchDepth = "standard",
+  workDir = process.cwd(),
+  budget = {},
+  useCache = false,
+  replayRunId,
+  distributed,
+}: RunWideSearchOptions = {}): Promise<RunWideSearchResult> {
+  let replayedFrom: string | undefined;
+
+  if (replayRunId) {
+    const previousRunDir = join(workDir, ".runs", "wide-search", replayRunId);
+    const previousRun = JSON.parse(await readFile(join(previousRunDir, "run.json"), "utf8")) as Run;
+    const previousPlan = JSON.parse(
+      await readFile(join(previousRunDir, "research-plan.json"), "utf8"),
+    ) as ResearchPlan;
+    objective = objective ?? previousRun.objective;
+    profile = previousRun.executionProfile;
+    providerName = providerName ?? resolveProviderName(previousRun.executionProfile);
+    searchDepth = previousPlan.searchDepth ?? searchDepth;
+    replayedFrom = replayRunId;
+  }
+
+  if (!objective) {
+    throw new Error("runWideSearch requires objective");
+  }
+
+  if (distributed?.enabled) {
+    return runDistributedWideSearch({
+      objective,
+      profile,
+      providerName,
+      searchDepth,
+      workDir,
+      distributed,
+    });
+  }
+
+  const runId = makeRunId();
+  const runDir = join(workDir, ".runs", "wide-search", runId);
+  await mkdir(runDir, { recursive: true });
+
+  const effectiveProviderName = resolveProviderName(profile, providerName);
+  const estimate = estimateRunCost(effectiveProviderName, searchDepth);
+
+  const usageMetrics: UsageMetrics = {
+    providerCalls: 0,
+    apiCalls: 0,
+    estimatedCostUsd: estimate.estimatedCostUsd,
+  };
+
+  checkEstimatedBudget(estimate, budget);
+
+  if (budget.dryRun) {
+    usageMetrics.notes = "Dry run: no provider executed.";
+    const dryRun: Run = {
+      runId,
+      objective,
+      executionProfile: profile,
+      status: "completed",
+      createdAt: new Date().toISOString(),
+      usageMetrics,
+    };
+    await writeFile(join(runDir, "run.json"), `${JSON.stringify(dryRun, null, 2)}\n`);
+    return {
+      runId,
+      runDir,
+      verification: {
+        status: "passed",
+        acceptedSources: 0,
+        rejectedSources: 0,
+        unsupportedClaims: 0,
+        staleClaims: 0,
+        unknownFreshnessClaims: 0,
+        lowConfidenceClaims: 0,
+        duplicateClaimGroups: [],
+        conflictingClaimPairs: [],
+        coverageGaps: [],
+        failures: [],
+        warnings: ["dry-run: no sources or claims evaluated"],
+      },
+    };
+  }
+
+  const rawSources = await loadSources({
+    profile,
+    objective,
+    providerCommand,
+    providerArgs,
+    providerName,
+    searchDepth,
+    metrics: usageMetrics,
+    useCache,
+  });
+  const sources: EnrichedSource[] = rawSources.map((source) => scoreSource(source));
+
+  usageMetrics.actualCostUsd = calculateActualCost(effectiveProviderName, usageMetrics);
+  checkBudget(effectiveProviderName, usageMetrics, budget);
+
+  const claims: Claim[] = [];
+  for (const source of sources.filter((item) => item.decision === "accepted")) {
+    for (const claim of source.claims ?? []) {
+      claims.push({
+        id: `C${String(claims.length + 1).padStart(3, "0")}`,
+        claim,
+        sourceIds: [source.id],
+        confidence: claimConfidence(source),
+        freshness: claimFreshness(source),
+      });
+    }
+  }
+
+  const run: Run = {
+    runId,
+    objective,
+    executionProfile: profile,
+    status: "completed",
+    createdAt: new Date().toISOString(),
+    usageMetrics,
+    replayedFrom,
+    cached: useCache && profile === "web-search" && effectiveProviderName !== "mock",
+  };
+
+  const researchPlan: ResearchPlan = {
+    objective,
+    searchDepth,
+    executionProfile: profile,
+    queryFamilies: [profile.startsWith("fixture") ? `fixture:${profile}` : "local-command provider"],
+    sourceTargets: ["official", "community", "secondary"],
+    stopConditions: [profile.startsWith("fixture") ? "fixture source set exhausted" : "provider output exhausted"],
+  };
+
+  await writeFile(join(runDir, "run.json"), `${JSON.stringify(run, null, 2)}\n`);
+  await writeFile(join(runDir, "research-plan.json"), `${JSON.stringify(researchPlan, null, 2)}\n`);
+  await writeFile(
+    join(runDir, "source-ledger.jsonl"),
+    `${sources.map((source) => JSON.stringify(source)).join("\n")}\n`,
+  );
+  await writeFile(
+    join(runDir, "claim-ledger.jsonl"),
+    `${claims.map((claim) => JSON.stringify(claim)).join("\n")}\n`,
+  );
+
+  const verification = await verifyRun({ runDir, minAcceptedSources: 1 });
+  const synthesis = renderSynthesis({ objective, profile, sources, claims, verification });
+  await writeFile(join(runDir, "synthesis.md"), synthesis);
+
+  console.log(formatCostReport(effectiveProviderName, usageMetrics));
+
+  return {
+    runId,
+    runDir,
+    verification,
+  };
+}