kimi-agent-swarm-cli 0.7.0

package/src/costs.ts

@@ -0,0 +1,134 @@
+import type { BudgetOptions, CostEstimate, SearchDepth, UsageMetrics } from "./types";
+
+export interface ProviderPricing {
+  perCallUsd: number;
+  per1kTokensUsd?: number;
+}
+
+export const PROVIDER_PRICING: Record<string, ProviderPricing> = {
+  mock: { perCallUsd: 0 },
+  serper: { perCallUsd: 0.001 }, // approx $1 per 1,000 searches
+  tavily: { perCallUsd: 0.005 }, // starter tier approx
+  brave: { perCallUsd: 0.003 }, // approx based on paid tier volume
+  github: { perCallUsd: 0 }, // free tier, token raises rate limit only
+};
+
+export function maxResultsForDepth(depth: SearchDepth): number {
+  switch (depth) {
+    case "light":
+      return 10;
+    case "standard":
+      return 25;
+    case "deep":
+      return 75;
+    case "maximum":
+      return 100;
+    default:
+      return 25;
+  }
+}
+
+export function getProviderPricing(providerName: string): ProviderPricing {
+  return PROVIDER_PRICING[providerName] ?? { perCallUsd: 0 };
+}
+
+export function estimateRunCost(
+  providerName: string,
+  depth: SearchDepth = "standard",
+): CostEstimate {
+  const pricing = getProviderPricing(providerName);
+  const estimatedProviderCalls = 1;
+  const estimatedApiCalls = 1;
+  const estimatedCostUsd = pricing.perCallUsd * estimatedProviderCalls;
+
+  return {
+    providerName,
+    depth,
+    estimatedProviderCalls,
+    estimatedApiCalls,
+    estimatedCostUsd,
+  };
+}
+
+export function calculateActualCost(providerName: string, metrics: UsageMetrics): number {
+  const pricing = getProviderPricing(providerName);
+  const callCost = pricing.perCallUsd * metrics.providerCalls;
+  const tokenCost = pricing.per1kTokensUsd
+    ? (pricing.per1kTokensUsd * (metrics.estimatedTokens ?? 0)) / 1000
+    : 0;
+  return Number((callCost + tokenCost).toFixed(6));
+}
+
+export class BudgetExceededError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "BudgetExceededError";
+  }
+}
+
+export function checkBudget(
+  providerName: string,
+  metrics: UsageMetrics,
+  budget: BudgetOptions = {},
+): void {
+  const actualCost = calculateActualCost(providerName, metrics);
+
+  if (budget.maxCostUsd !== undefined && actualCost > budget.maxCostUsd) {
+    throw new BudgetExceededError(
+      `Actual cost $${actualCost.toFixed(4)} exceeds budget $${budget.maxCostUsd.toFixed(4)}`,
+    );
+  }
+
+  if (budget.maxProviderCalls !== undefined && metrics.providerCalls > budget.maxProviderCalls) {
+    throw new BudgetExceededError(
+      `Provider calls ${metrics.providerCalls} exceed budget ${budget.maxProviderCalls}`,
+    );
+  }
+
+  if (budget.maxApiCalls !== undefined && metrics.apiCalls > budget.maxApiCalls) {
+    throw new BudgetExceededError(
+      `API calls ${metrics.apiCalls} exceed budget ${budget.maxApiCalls}`,
+    );
+  }
+}
+
+export function checkEstimatedBudget(
+  estimate: CostEstimate,
+  budget: BudgetOptions = {},
+): void {
+  if (budget.maxCostUsd !== undefined && estimate.estimatedCostUsd > budget.maxCostUsd) {
+    throw new BudgetExceededError(
+      `Estimated cost $${estimate.estimatedCostUsd.toFixed(4)} exceeds budget $${budget.maxCostUsd.toFixed(4)}. Use --dry-run to inspect or raise the budget.`,
+    );
+  }
+
+  if (
+    budget.maxProviderCalls !== undefined &&
+    estimate.estimatedProviderCalls > budget.maxProviderCalls
+  ) {
+    throw new BudgetExceededError(
+      `Estimated provider calls ${estimate.estimatedProviderCalls} exceed budget ${budget.maxProviderCalls}`,
+    );
+  }
+
+  if (budget.maxApiCalls !== undefined && estimate.estimatedApiCalls > budget.maxApiCalls) {
+    throw new BudgetExceededError(
+      `Estimated API calls ${estimate.estimatedApiCalls} exceed budget ${budget.maxApiCalls}`,
+    );
+  }
+}
+
+export function formatCostReport(providerName: string, metrics: UsageMetrics): string {
+  const actualCost = calculateActualCost(providerName, metrics);
+  return [
+    `Provider: ${providerName}`,
+    `Provider calls: ${metrics.providerCalls}`,
+    `API calls: ${metrics.apiCalls}`,
+    metrics.estimatedTokens !== undefined ? `Estimated tokens: ${metrics.estimatedTokens}` : null,
+    `Estimated cost: $${metrics.estimatedCostUsd?.toFixed(4) ?? "0.0000"}`,
+    `Actual cost: $${actualCost.toFixed(4)}`,
+    metrics.notes ? `Notes: ${metrics.notes}` : null,
+  ]
+    .filter(Boolean)
+    .join("\n");
+}

package/src/distributed/memory-adapter.ts

@@ -0,0 +1,152 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import type { QueueAdapter } from "./queue-adapter";
+import type { DistributedJob, DistributedTask, WorkerResult } from "../types";
+
+export interface MemoryAdapterOptions {
+  workDir?: string;
+}
+
+export class MemoryQueueAdapter implements QueueAdapter {
+  readonly type = "memory";
+  private readonly jobs = new Map<string, DistributedJob>();
+  private readonly workDir: string;
+
+  constructor(options: MemoryAdapterOptions = {}) {
+    this.workDir = options.workDir ?? process.cwd();
+  }
+
+  private jobFilePath(jobId: string): string {
+    return join(this.workDir, ".runs", "wide-search", "jobs", `${jobId}.json`);
+  }
+
+  async createJob(
+    job: Omit<DistributedJob, "jobId" | "createdAt" | "updatedAt">,
+  ): Promise<DistributedJob> {
+    const now = new Date().toISOString();
+    const created: DistributedJob = {
+      ...job,
+      jobId: `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
+      createdAt: now,
+      updatedAt: now,
+    };
+    this.jobs.set(created.jobId, created);
+    await this.saveJob(created);
+    return created;
+  }
+
+  async getJob(jobId: string): Promise<DistributedJob | undefined> {
+    const cached = this.jobs.get(jobId);
+    if (cached) {
+      return cached;
+    }
+
+    try {
+      const text = await readFile(this.jobFilePath(jobId), "utf8");
+      const loaded = JSON.parse(text) as DistributedJob;
+      this.jobs.set(jobId, loaded);
+      return loaded;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        return undefined;
+      }
+      throw error;
+    }
+  }
+
+  async saveJob(job: DistributedJob): Promise<void> {
+    const path = this.jobFilePath(job.jobId);
+    await mkdir(join(path, ".."), { recursive: true });
+    const updated = { ...job, updatedAt: new Date().toISOString() };
+    this.jobs.set(job.jobId, updated);
+    await writeFile(path, `${JSON.stringify(updated, null, 2)}\n`);
+  }
+
+  async claimNextTask(
+    jobId: string,
+    workerId: string,
+  ): Promise<DistributedTask | undefined> {
+    const job = await this.getJob(jobId);
+    if (!job) return undefined;
+
+    const task = job.tasks.find(
+      (t) => t.status === "pending" && t.attempts < t.maxRetries,
+    );
+    if (!task) return undefined;
+
+    task.status = "running";
+    task.workerId = workerId;
+    task.attempts += 1;
+    task.startedAt = new Date().toISOString();
+    await this.saveJob(job);
+    return task;
+  }
+
+  async completeTask(taskId: string, result: WorkerResult): Promise<void> {
+    const { job, task } = await this.findTask(taskId);
+    if (!task || !job) return;
+
+    task.status = "completed";
+    task.result = result;
+    task.completedAt = new Date().toISOString();
+    task.error = undefined;
+
+    this.updateJobStatus(job);
+    await this.saveJob(job);
+  }
+
+  async failTask(taskId: string, error: string): Promise<void> {
+    const { job, task } = await this.findTask(taskId);
+    if (!task || !job) return;
+
+    task.error = error;
+    if (task.attempts >= task.maxRetries) {
+      task.status = "failed";
+      task.completedAt = new Date().toISOString();
+    } else {
+      task.status = "pending";
+      task.workerId = undefined;
+      task.startedAt = undefined;
+    }
+
+    this.updateJobStatus(job);
+    await this.saveJob(job);
+  }
+
+  async getPendingTaskCount(jobId: string): Promise<number> {
+    const job = await this.getJob(jobId);
+    if (!job) return 0;
+    return job.tasks.filter((t) => t.status === "pending").length;
+  }
+
+  async getRunningTaskCount(jobId: string): Promise<number> {
+    const job = await this.getJob(jobId);
+    if (!job) return 0;
+    return job.tasks.filter((t) => t.status === "running").length;
+  }
+
+  private async findTask(
+    taskId: string,
+  ): Promise<{ job?: DistributedJob; task?: DistributedTask }> {
+    for (const job of this.jobs.values()) {
+      const task = job.tasks.find((t) => t.taskId === taskId);
+      if (task) {
+        return { job, task };
+      }
+    }
+    return {};
+  }
+
+  private updateJobStatus(job: DistributedJob): void {
+    if (job.tasks.every((t) => t.status === "completed")) {
+      job.status = "completed";
+    } else if (job.tasks.some((t) => t.status === "running")) {
+      job.status = "running";
+    } else if (job.tasks.every((t) => t.status === "failed")) {
+      job.status = "failed";
+    } else {
+      job.status = "running";
+    }
+  }
+}

package/src/distributed/queue-adapter.ts

@@ -0,0 +1,29 @@
+import type { DistributedJob, DistributedTask, WorkerResult } from "../types";
+
+export interface QueueAdapter {
+  readonly type: string;
+
+  createJob(
+    job: Omit<DistributedJob, "jobId" | "createdAt" | "updatedAt">,
+  ): Promise<DistributedJob>;
+
+  getJob(jobId: string): Promise<DistributedJob | undefined>;
+  saveJob(job: DistributedJob): Promise<void>;
+
+  claimNextTask(jobId: string, workerId: string): Promise<DistributedTask | undefined>;
+  completeTask(taskId: string, result: WorkerResult): Promise<void>;
+  failTask(taskId: string, error: string): Promise<void>;
+
+  getPendingTaskCount(jobId: string): Promise<number>;
+  getRunningTaskCount(jobId: string): Promise<number>;
+}
+
+export function makeJobId(): string {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).slice(2, 8);
+  return `job-${timestamp}-${random}`;
+}
+
+export function makeTaskId(jobId: string, index: number): string {
+  return `${jobId}-task-${String(index + 1).padStart(4, "0")}`;
+}

package/src/distributed/redis-adapter.ts

@@ -0,0 +1,185 @@
+import type { QueueAdapter } from "./queue-adapter";
+import type { DistributedJob, DistributedTask, WorkerResult } from "../types";
+
+export interface RedisAdapterOptions {
+  redisUrl?: string;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let Redis: any;
+
+try {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  Redis = require("ioredis");
+} catch {
+  Redis = undefined;
+}
+
+export class RedisQueueAdapter implements QueueAdapter {
+  readonly type = "redis";
+  private readonly redisUrl: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private client?: any;
+
+  constructor(options: RedisAdapterOptions = {}) {
+    this.redisUrl = options.redisUrl ?? process.env.REDIS_URL ?? "redis://localhost:6379";
+    if (!Redis) {
+      throw new Error(
+        "Redis adapter requires ioredis. Install it with: bun add ioredis",
+      );
+    }
+  }
+
+  private async getClient() {
+    if (!this.client) {
+      this.client = new Redis(this.redisUrl);
+    }
+    return this.client;
+  }
+
+  private jobKey(jobId: string): string {
+    return `kasw:job:${jobId}`;
+  }
+
+  private taskKey(taskId: string): string {
+    return `kasw:task:${taskId}`;
+  }
+
+  private queueKey(jobId: string): string {
+    return `kasw:queue:${jobId}`;
+  }
+
+  async createJob(
+    job: Omit<DistributedJob, "jobId" | "createdAt" | "updatedAt">,
+  ): Promise<DistributedJob> {
+    const client = await this.getClient();
+    const now = new Date().toISOString();
+    const created: DistributedJob = {
+      ...job,
+      jobId: `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    await client.set(this.jobKey(created.jobId), JSON.stringify(created));
+    for (const task of created.tasks) {
+      await client.set(this.taskKey(task.taskId), JSON.stringify(task));
+      await client.rpush(this.queueKey(created.jobId), task.taskId);
+    }
+
+    return created;
+  }
+
+  async getJob(jobId: string): Promise<DistributedJob | undefined> {
+    const client = await this.getClient();
+    const text = await client.get(this.jobKey(jobId));
+    if (!text) return undefined;
+    return JSON.parse(text) as DistributedJob;
+  }
+
+  async saveJob(job: DistributedJob): Promise<void> {
+    const client = await this.getClient();
+    const updated = { ...job, updatedAt: new Date().toISOString() };
+    await client.set(this.jobKey(job.jobId), JSON.stringify(updated));
+    for (const task of updated.tasks) {
+      await client.set(this.taskKey(task.taskId), JSON.stringify(task));
+    }
+  }
+
+  async claimNextTask(
+    jobId: string,
+    workerId: string,
+  ): Promise<DistributedTask | undefined> {
+    const client = await this.getClient();
+    const taskId = await client.lpop(this.queueKey(jobId));
+    if (!taskId) return undefined;
+
+    const taskText = await client.get(this.taskKey(taskId));
+    if (!taskText) return undefined;
+
+    const task = JSON.parse(taskText) as DistributedTask;
+    task.status = "running";
+    task.workerId = workerId;
+    task.attempts += 1;
+    task.startedAt = new Date().toISOString();
+
+    await client.set(this.taskKey(task.taskId), JSON.stringify(task));
+    return task;
+  }
+
+  async completeTask(taskId: string, result: WorkerResult): Promise<void> {
+    const client = await this.getClient();
+    const taskText = await client.get(this.taskKey(taskId));
+    if (!taskText) return;
+
+    const task = JSON.parse(taskText) as DistributedTask;
+    task.status = "completed";
+    task.result = result;
+    task.completedAt = new Date().toISOString();
+    task.error = undefined;
+    await client.set(this.taskKey(taskId), JSON.stringify(task));
+
+    const job = await this.getJob(task.jobId);
+    if (job) {
+      const idx = job.tasks.findIndex((t) => t.taskId === taskId);
+      if (idx >= 0) {
+        job.tasks[idx] = task;
+        this.updateJobStatus(job);
+        await this.saveJob(job);
+      }
+    }
+  }
+
+  async failTask(taskId: string, error: string): Promise<void> {
+    const client = await this.getClient();
+    const taskText = await client.get(this.taskKey(taskId));
+    if (!taskText) return;
+
+    const task = JSON.parse(taskText) as DistributedTask;
+    task.error = error;
+
+    if (task.attempts >= task.maxRetries) {
+      task.status = "failed";
+      task.completedAt = new Date().toISOString();
+    } else {
+      task.status = "pending";
+      task.workerId = undefined;
+      task.startedAt = undefined;
+      await client.rpush(this.queueKey(task.jobId), task.taskId);
+    }
+
+    await client.set(this.taskKey(taskId), JSON.stringify(task));
+
+    const job = await this.getJob(task.jobId);
+    if (job) {
+      const idx = job.tasks.findIndex((t) => t.taskId === taskId);
+      if (idx >= 0) {
+        job.tasks[idx] = task;
+        this.updateJobStatus(job);
+        await this.saveJob(job);
+      }
+    }
+  }
+
+  async getPendingTaskCount(jobId: string): Promise<number> {
+    const client = await this.getClient();
+    return client.llen(this.queueKey(jobId));
+  }
+
+  async getRunningTaskCount(_jobId: string): Promise<number> {
+    // Running tasks are not tracked separately in this simple Redis adapter.
+    return 0;
+  }
+
+  private updateJobStatus(job: DistributedJob): void {
+    if (job.tasks.every((t) => t.status === "completed")) {
+      job.status = "completed";
+    } else if (job.tasks.some((t) => t.status === "running")) {
+      job.status = "running";
+    } else if (job.tasks.every((t) => t.status === "failed")) {
+      job.status = "failed";
+    } else {
+      job.status = "running";
+    }
+  }
+}