@locusai/sdk 0.4.5 → 0.4.9

package/src/agent/sprint-planner.ts

@@ -1,86 +0,0 @@
-import type { Sprint, Task } from "@locusai/shared";
-import type { AnthropicClient } from "../ai/anthropic-client.js";
-import type { ClaudeRunner } from "../ai/claude-runner.js";
-
-export interface SprintPlannerDeps {
-  anthropicClient: AnthropicClient | null;
-  claudeRunner: ClaudeRunner;
-  log: (message: string, level?: "info" | "success" | "warn" | "error") => void;
-}
-
-/**
- * Handles sprint planning and mindmap generation
- */
-export class SprintPlanner {
-  constructor(private deps: SprintPlannerDeps) {}
-
-  async planSprint(sprint: Sprint, tasks: Task[]): Promise<string> {
-    this.deps.log(`Planning sprint: ${sprint.name}`, "info");
-
-    try {
-      const taskList = tasks
-        .map(
-          (t) => `- [${t.id}] ${t.title}: ${t.description || "No description"}`
-        )
-        .join("\n");
-
-      let plan: string;
-
-      if (this.deps.anthropicClient) {
-        // Use Anthropic SDK with caching for faster planning
-        const systemPrompt = `You are an expert project manager and lead engineer specialized in sprint planning and task prioritization.`;
-
-        const userPrompt = `# Sprint Planning: ${sprint.name}
-
-## Tasks
-${taskList}
-
-## Instructions
-1. Analyze dependencies between these tasks.
-2. Prioritize them for the most efficient execution.
-3. Create a mindmap (in Markdown or Mermaid format) that visualizes the sprint structure.
-4. Output your final plan. The plan should clearly state the order of execution.
-
-**IMPORTANT**: 
-- Do NOT create any files on the filesystem during this planning phase. 
-- Avoid using absolute local paths (e.g., /Users/...) in your output. Use relative paths starting from the project root if necessary.
-- Your output will be saved as the official sprint mindmap on the server.`;
-
-        plan = await this.deps.anthropicClient.run({
-          systemPrompt,
-          userPrompt,
-        });
-      } else {
-        // Fallback to Claude CLI
-        const planningPrompt = `# Sprint Planning: ${sprint.name}
-
-You are an expert project manager and lead engineer. You need to create a mindmap and execution plan for the following tasks in this sprint.
-
-## Tasks
-${taskList}
-
-## Instructions
-1. Analyze dependencies between these tasks.
-2. Prioritize them for the most efficient execution.
-3. Create a mindmap (in Markdown or Mermaid format) that visualizes the sprint structure.
-4. Output your final plan. The plan should clearly state the order of execution.
-
-**IMPORTANT**: 
-- Do NOT create any files on the filesystem during this planning phase. 
-- Avoid using absolute local paths (e.g., /Users/...) in your output. Use relative paths starting from the project root if necessary.
-- Your output will be saved as the official sprint mindmap on the server.`;
-
-        plan = await this.deps.claudeRunner.run(planningPrompt, true);
-      }
-
-      this.deps.log(
-        "Sprint mindmap generated and posted to server.",
-        "success"
-      );
-      return plan;
-    } catch (error) {
-      this.deps.log(`Sprint planning failed: ${error}`, "error");
-      return sprint.mindmap || "";
-    }
-  }
-}

package/src/agent/task-executor.ts

@@ -1,85 +0,0 @@
-import type { Task } from "@locusai/shared";
-import type { AnthropicClient } from "../ai/anthropic-client.js";
-import type { ClaudeRunner } from "../ai/claude-runner.js";
-import { PromptBuilder } from "../core/prompt-builder.js";
-
-export interface TaskExecutorDeps {
-  anthropicClient: AnthropicClient | null;
-  claudeRunner: ClaudeRunner;
-  projectPath: string;
-  sprintPlan: string | null;
-  log: (message: string, level?: "info" | "success" | "warn" | "error") => void;
-}
-
-/**
- * Handles task execution with two-phase approach (planning + execution)
- */
-export class TaskExecutor {
-  private promptBuilder: PromptBuilder;
-
-  constructor(private deps: TaskExecutorDeps) {
-    this.promptBuilder = new PromptBuilder(deps.projectPath);
-  }
-
-  updateSprintPlan(sprintPlan: string | null) {
-    this.deps.sprintPlan = sprintPlan;
-  }
-
-  async execute(task: Task): Promise<{ success: boolean; summary: string }> {
-    this.deps.log(`Executing: ${task.title}`, "info");
-    let basePrompt = await this.promptBuilder.build(task);
-
-    if (this.deps.sprintPlan) {
-      basePrompt = `## Sprint Context\n${this.deps.sprintPlan}\n\n${basePrompt}`;
-    }
-
-    try {
-      let plan: string = "";
-
-      if (this.deps.anthropicClient) {
-        // Phase 1: Planning (using Anthropic SDK with caching)
-        this.deps.log("Phase 1: Planning (Anthropic SDK)...", "info");
-
-        // Build cacheable context blocks
-        const cacheableContext: string[] = [basePrompt];
-
-        plan = await this.deps.anthropicClient.run({
-          systemPrompt:
-            "You are an expert software engineer. Analyze the task carefully and create a detailed implementation plan.",
-          cacheableContext,
-          userPrompt:
-            "## Phase 1: Planning\nAnalyze and create a detailed plan for THIS SPECIFIC TASK. Do NOT execute changes yet.",
-        });
-      } else {
-        this.deps.log(
-          "Skipping Phase 1: Planning (No Anthropic API Key)...",
-          "info"
-        );
-      }
-
-      // Phase 2: Execution (always using Claude CLI for agentic tools)
-      this.deps.log("Starting Execution...", "info");
-
-      let executionPrompt = basePrompt;
-      if (plan) {
-        executionPrompt += `\n\n## Phase 2: Execution\nBased on the plan, execute the task:\n\n${plan}`;
-      } else {
-        executionPrompt += `\n\n## Execution\nExecute the task directly.`;
-      }
-
-      executionPrompt += `\n\nWhen finished, output: <promise>COMPLETE</promise>`;
-      const output = await this.deps.claudeRunner.run(executionPrompt);
-
-      const success = output.includes("<promise>COMPLETE</promise>");
-
-      return {
-        success,
-        summary: success
-          ? "Task completed by Claude"
-          : "Claude did not signal completion",
-      };
-    } catch (error) {
-      return { success: false, summary: `Error: ${error}` };
-    }
-  }
-}

package/src/agent/worker.ts

@@ -1,322 +0,0 @@
-import type { Sprint, Task, TaskStatus } from "@locusai/shared";
-import { AnthropicClient } from "../ai/anthropic-client.js";
-import { ClaudeRunner } from "../ai/claude-runner.js";
-import { LocusClient } from "../index.js";
-import { c } from "../utils/colors.js";
-import { ArtifactSyncer } from "./artifact-syncer.js";
-import { CodebaseIndexerService } from "./codebase-indexer-service.js";
-import { SprintPlanner } from "./sprint-planner.js";
-import { TaskExecutor } from "./task-executor.js";
-
-export interface WorkerConfig {
-  agentId: string;
-  workspaceId: string;
-  sprintId?: string;
-  apiBase: string;
-  projectPath: string;
-  apiKey: string;
-  anthropicApiKey?: string;
-  model?: string;
-}
-
-/**
- * Main agent worker that orchestrates task execution
- * Delegates responsibilities to specialized services
- */
-export class AgentWorker {
-  private client: LocusClient;
-  private claudeRunner: ClaudeRunner;
-  private anthropicClient: AnthropicClient | null;
-
-  // Services
-  private sprintPlanner: SprintPlanner;
-  private indexerService: CodebaseIndexerService;
-  private artifactSyncer: ArtifactSyncer;
-  private taskExecutor: TaskExecutor;
-
-  // State
-  private consecutiveEmpty = 0;
-  private maxEmpty = 10;
-  private maxTasks = 50;
-  private tasksCompleted = 0;
-  private pollInterval = 10_000;
-  private sprintPlan: string | null = null;
-
-  constructor(private config: WorkerConfig) {
-    const projectPath = config.projectPath || process.cwd();
-
-    // Initialize API client
-    this.client = new LocusClient({
-      baseUrl: config.apiBase,
-      token: config.apiKey,
-      retryOptions: {
-        maxRetries: 3,
-        initialDelay: 1000,
-        maxDelay: 5000,
-        factor: 2,
-      },
-    });
-
-    // Initialize AI clients
-    this.claudeRunner = new ClaudeRunner(projectPath, config.model);
-    this.anthropicClient = config.anthropicApiKey
-      ? new AnthropicClient({
-          apiKey: config.anthropicApiKey,
-          model: config.model,
-        })
-      : null;
-
-    // Initialize services with dependencies
-    const logFn = this.log.bind(this);
-
-    this.sprintPlanner = new SprintPlanner({
-      anthropicClient: this.anthropicClient,
-      claudeRunner: this.claudeRunner,
-      log: logFn,
-    });
-
-    this.indexerService = new CodebaseIndexerService({
-      anthropicClient: this.anthropicClient,
-      claudeRunner: this.claudeRunner,
-      projectPath,
-      log: logFn,
-    });
-
-    this.artifactSyncer = new ArtifactSyncer({
-      client: this.client,
-      workspaceId: config.workspaceId,
-      projectPath,
-      log: logFn,
-    });
-
-    this.taskExecutor = new TaskExecutor({
-      anthropicClient: this.anthropicClient,
-      claudeRunner: this.claudeRunner,
-      projectPath,
-      sprintPlan: null, // Will be set after sprint planning
-      log: logFn,
-    });
-
-    // Log initialization
-    if (this.anthropicClient) {
-      this.log(
-        "Using Anthropic SDK with prompt caching for planning phases",
-        "info"
-      );
-    } else {
-      this.log(
-        "Using Claude CLI for all phases (no Anthropic API key provided)",
-        "info"
-      );
-    }
-  }
-
-  log(message: string, level: "info" | "success" | "warn" | "error" = "info") {
-    const timestamp = new Date().toISOString().split("T")[1]?.slice(0, 8) ?? "";
-    const colorFn = {
-      info: c.cyan,
-      success: c.green,
-      warn: c.yellow,
-      error: c.red,
-    }[level];
-    const prefix = { info: "ℹ", success: "✓", warn: "⚠", error: "✗" }[level];
-
-    console.log(
-      `${c.dim(`[${timestamp}]`)} ${c.bold(`[${this.config.agentId.slice(-8)}]`)} ${colorFn(`${prefix} ${message}`)}`
-    );
-  }
-
-  private async getActiveSprint(): Promise<Sprint | null> {
-    try {
-      if (this.config.sprintId) {
-        return await this.client.sprints.getById(
-          this.config.sprintId,
-          this.config.workspaceId
-        );
-      }
-      return await this.client.sprints.getActive(this.config.workspaceId);
-    } catch (_error) {
-      return null;
-    }
-  }
-
-  private async getNextTask(): Promise<Task | null> {
-    try {
-      const task = await this.client.workspaces.dispatch(
-        this.config.workspaceId,
-        this.config.agentId,
-        this.config.sprintId
-      );
-      return task;
-    } catch (error) {
-      this.log(
-        `No task dispatched: ${error instanceof Error ? error.message : String(error)}`,
-        "info"
-      );
-      return null;
-    }
-  }
-
-  private async executeTask(
-    task: Task
-  ): Promise<{ success: boolean; summary: string }> {
-    // Fetch full task details to get comments/feedback
-    const fullTask = await this.client.tasks.getById(
-      task.id,
-      this.config.workspaceId
-    );
-
-    // Update task executor with current sprint plan
-    this.taskExecutor.updateSprintPlan(this.sprintPlan);
-
-    // Execute the task
-    const result = await this.taskExecutor.execute(fullTask);
-
-    // Reindex codebase after execution to ensure fresh context
-    await this.indexerService.reindex();
-
-    return result;
-  }
-
-  async run(): Promise<void> {
-    this.log(
-      `Agent started in ${this.config.projectPath || process.cwd()}`,
-      "success"
-    );
-
-    // Initial Sprint Planning Phase
-    const sprint = await this.getActiveSprint();
-    if (sprint) {
-      this.log(`Found active sprint: ${sprint.name} (${sprint.id})`, "info");
-      const tasks = await this.client.tasks.list(this.config.workspaceId, {
-        sprintId: sprint.id,
-      });
-
-      this.log(`Sprint tasks found: ${tasks.length}`, "info");
-
-      const latestTaskCreation = tasks.reduce((latest, task) => {
-        const taskDate = new Date(task.createdAt);
-        return taskDate > latest ? taskDate : latest;
-      }, new Date(0));
-
-      const mindmapDate = sprint.mindmapUpdatedAt
-        ? new Date(sprint.mindmapUpdatedAt)
-        : new Date(0);
-
-      // Skip mindmap generation if there's only one task
-      if (tasks.length <= 1) {
-        this.log(
-          "Skipping mindmap generation (only one task in sprint).",
-          "info"
-        );
-        this.sprintPlan = null;
-      } else {
-        const needsPlanning =
-          !sprint.mindmap ||
-          sprint.mindmap.trim() === "" ||
-          latestTaskCreation > mindmapDate;
-
-        if (needsPlanning) {
-          if (sprint.mindmap && latestTaskCreation > mindmapDate) {
-            this.log(
-              "New tasks have been added to the sprint since last mindmap. Regenerating...",
-              "warn"
-            );
-          }
-          this.sprintPlan = await this.sprintPlanner.planSprint(sprint, tasks);
-
-          // Save mindmap to server
-          await this.client.sprints.update(sprint.id, this.config.workspaceId, {
-            mindmap: this.sprintPlan,
-            mindmapUpdatedAt: new Date(),
-          });
-        } else {
-          this.log("Using existing sprint mindmap.", "info");
-          this.sprintPlan = sprint.mindmap ?? null;
-        }
-      }
-    } else {
-      this.log("No active sprint found for planning.", "warn");
-    }
-
-    // Main task execution loop
-    while (
-      this.tasksCompleted < this.maxTasks &&
-      this.consecutiveEmpty < this.maxEmpty
-    ) {
-      const task = await this.getNextTask();
-      if (!task) {
-        this.consecutiveEmpty++;
-        if (this.consecutiveEmpty >= this.maxEmpty) break;
-        await new Promise((r) => setTimeout(r, this.pollInterval));
-        continue;
-      }
-
-      this.consecutiveEmpty = 0;
-      this.log(`Claimed: ${task.title}`, "success");
-
-      const result = await this.executeTask(task);
-
-      // Sync artifacts after task execution
-      await this.artifactSyncer.sync();
-
-      if (result.success) {
-        await this.client.tasks.update(task.id, this.config.workspaceId, {
-          status: "VERIFICATION" as TaskStatus,
-        });
-        await this.client.tasks.addComment(task.id, this.config.workspaceId, {
-          author: this.config.agentId,
-          text: `✅ ${result.summary}`,
-        });
-        this.tasksCompleted++;
-      } else {
-        await this.client.tasks.update(task.id, this.config.workspaceId, {
-          status: "BACKLOG" as TaskStatus,
-          assignedTo: null,
-        });
-        await this.client.tasks.addComment(task.id, this.config.workspaceId, {
-          author: this.config.agentId,
-          text: `❌ ${result.summary}`,
-        });
-      }
-    }
-    process.exit(0);
-  }
-}
-
-// CLI entry point
-if (
-  process.argv[1]?.includes("agent-worker") ||
-  process.argv[1]?.includes("worker")
-) {
-  const args = process.argv.slice(2);
-  const config: Partial<WorkerConfig> = {};
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "--agent-id") config.agentId = args[++i];
-    else if (arg === "--workspace-id") config.workspaceId = args[++i];
-    else if (arg === "--sprint-id") config.sprintId = args[++i];
-    else if (arg === "--api-base") config.apiBase = args[++i];
-    else if (arg === "--api-key") config.apiKey = args[++i];
-    else if (arg === "--anthropic-api-key") config.anthropicApiKey = args[++i];
-    else if (arg === "--project-path") config.projectPath = args[++i];
-    else if (arg === "--model") config.model = args[++i];
-  }
-
-  if (
-    !config.agentId ||
-    !config.workspaceId ||
-    !config.apiBase ||
-    !config.apiKey ||
-    !config.projectPath
-  ) {
-    console.error("Missing required arguments");
-    process.exit(1);
-  }
-
-  const worker = new AgentWorker(config as WorkerConfig);
-  worker.run().catch((err) => {
-    console.error("Fatal worker error:", err);
-    process.exit(1);
-  });
-}

package/src/ai/anthropic-client.ts

@@ -1,93 +0,0 @@
-import Anthropic from "@anthropic-ai/sdk";
-import { DEFAULT_MODEL } from "../core/config.js";
-
-export interface AnthropicClientConfig {
-  apiKey: string;
-  model?: string;
-}
-
-export interface CachedPromptOptions {
-  systemPrompt?: string;
-  cacheableContext?: string[];
-  userPrompt: string;
-}
-
-/**
- * Anthropic Client with Prompt Caching Support
- *
- * This client wraps the official Anthropic SDK and adds support for
- * prompt caching to dramatically reduce latency and costs for repeated
- * context (like codebase indexes, CLAUDE.md, etc.)
- */
-export class AnthropicClient {
-  private client: Anthropic;
-  private model: string;
-
-  constructor(config: AnthropicClientConfig) {
-    this.client = new Anthropic({
-      apiKey: config.apiKey,
-    });
-    this.model = config.model || DEFAULT_MODEL;
-  }
-
-  /**
-   * Run a prompt with optional caching for large context blocks
-   *
-   * @param options - Prompt configuration with cacheable context
-   * @returns The generated text response
-   */
-  async run(options: CachedPromptOptions): Promise<string> {
-    const { systemPrompt, cacheableContext = [], userPrompt } = options;
-
-    // Build system message with cache breakpoints
-    const systemContent: Anthropic.Messages.TextBlockParam[] = [];
-
-    if (systemPrompt) {
-      systemContent.push({
-        type: "text",
-        text: systemPrompt,
-      });
-    }
-
-    // Add each cacheable context block with cache_control
-    for (let i = 0; i < cacheableContext.length; i++) {
-      const isLast = i === cacheableContext.length - 1;
-      systemContent.push({
-        type: "text",
-        text: cacheableContext[i],
-        // Only the last block gets the cache breakpoint
-        ...(isLast && {
-          cache_control: { type: "ephemeral" as const },
-        }),
-      });
-    }
-
-    const response = await this.client.messages.create({
-      model: this.model,
-      max_tokens: 8000,
-      system: systemContent,
-      messages: [
-        {
-          role: "user",
-          content: userPrompt,
-        },
-      ],
-    });
-
-    // Extract text from response
-    const textBlocks = response.content.filter(
-      (block): block is Anthropic.Messages.TextBlock => block.type === "text"
-    );
-
-    return textBlocks.map((block) => block.text).join("\n");
-  }
-
-  /**
-   * Simple run without caching (for short prompts)
-   */
-  async runSimple(prompt: string): Promise<string> {
-    return this.run({
-      userPrompt: prompt,
-    });
-  }
-}

package/src/ai/claude-runner.ts

@@ -1,86 +0,0 @@
-import { spawn } from "node:child_process";
-import { DEFAULT_MODEL } from "../core/config.js";
-
-export class ClaudeRunner {
-  constructor(
-    private projectPath: string,
-    private model: string = DEFAULT_MODEL
-  ) {}
-
-  async run(prompt: string, _isPlanning = false): Promise<string> {
-    const maxRetries = 3;
-    let lastError: Error | null = null;
-
-    for (let attempt = 1; attempt <= maxRetries; attempt++) {
-      try {
-        return await this.executeRun(prompt);
-      } catch (error) {
-        const err = error as Error;
-        lastError = err;
-        const isLastAttempt = attempt === maxRetries;
-
-        if (!isLastAttempt) {
-          const delay = Math.pow(2, attempt) * 1000; // 2s, 4s, 8s
-          console.warn(
-            `Claude CLI attempt ${attempt} failed: ${err.message}. Retrying in ${delay}ms...`
-          );
-          await new Promise((resolve) => setTimeout(resolve, delay));
-        }
-      }
-    }
-
-    throw lastError || new Error("Claude CLI failed after multiple attempts");
-  }
-
-  private executeRun(prompt: string): Promise<string> {
-    return new Promise((resolve, reject) => {
-      const args = [
-        "--dangerously-skip-permissions",
-        "--print",
-        "--model",
-        this.model,
-      ];
-
-      const claude = spawn("claude", args, {
-        cwd: this.projectPath,
-        stdio: ["pipe", "pipe", "pipe"],
-        env: process.env,
-        shell: true,
-      });
-
-      let output = "";
-      let errorOutput = "";
-
-      claude.stdout.on("data", (data) => {
-        output += data.toString();
-        // Only write to stdout if we're not retrying or if logic dictates
-        // process.stdout.write(data.toString());
-      });
-      claude.stderr.on("data", (data) => {
-        errorOutput += data.toString();
-        // process.stderr.write(data.toString());
-      });
-
-      claude.on("error", (err) =>
-        reject(
-          new Error(
-            `Failed to start Claude CLI (shell: true): ${err.message}. Please ensure the 'claude' command is available in your PATH.`
-          )
-        )
-      );
-      claude.on("close", (code) => {
-        if (code === 0) resolve(output);
-        else {
-          const detail = errorOutput.trim();
-          const message = detail
-            ? `Claude CLI error (exit code ${code}): ${detail}`
-            : `Claude CLI exited with code ${code}. Please ensure the Claude CLI is installed and you are logged in (run 'claude' manually to check).`;
-          reject(new Error(message));
-        }
-      });
-
-      claude.stdin.write(prompt);
-      claude.stdin.end();
-    });
-  }
-}

package/src/ai/index.ts

@@ -1,2 +0,0 @@
-export { AnthropicClient } from "./anthropic-client.js";
-export { ClaudeRunner } from "./claude-runner.js";

package/src/core/config.ts

@@ -1,21 +0,0 @@
-import { join } from "node:path";
-
-export const DEFAULT_MODEL = "sonnet";
-
-export const LOCUS_CONFIG = {
-  dir: ".locus",
-  configFile: "config.json",
-  indexFile: "codebase-index.json",
-  contextFile: "CLAUDE.md",
-  artifactsDir: "artifacts",
-};
-
-export function getLocusPath(
-  projectPath: string,
-  fileName: keyof typeof LOCUS_CONFIG
-): string {
-  if (fileName === "contextFile") {
-    return join(projectPath, LOCUS_CONFIG.contextFile);
-  }
-  return join(projectPath, LOCUS_CONFIG.dir, LOCUS_CONFIG[fileName]);
-}

package/src/core/index.ts

@@ -1,3 +0,0 @@
-export { DEFAULT_MODEL, getLocusPath, LOCUS_CONFIG } from "./config.js";
-export { type CodebaseIndex, CodebaseIndexer } from "./indexer.js";
-export { PromptBuilder } from "./prompt-builder.js";