@locusai/sdk 0.2.1

package/src/agent/task-executor.ts

@@ -0,0 +1,77 @@
+import type { Task } from "@locusai/shared";
+import type { AnthropicClient } from "../ai/anthropic-client";
+import type { ClaudeRunner } from "../ai/claude-runner";
+import { PromptBuilder } from "../core/prompt-builder";
+
+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 {
+        // Phase 1: Planning (using Claude CLI)
+        this.deps.log("Phase 1: Planning (Claude CLI)...", "info");
+        const planningPrompt = `${basePrompt}\n\n## Phase 1: Planning\nAnalyze and create a detailed plan for THIS SPECIFIC TASK. Do NOT execute changes yet.`;
+        plan = await this.deps.claudeRunner.run(planningPrompt, true);
+      }
+
+      // Phase 2: Execution (always using Claude CLI for agentic tools)
+      this.deps.log("Plan generated. Starting Phase 2: Execution...", "info");
+      const executionPrompt = `${basePrompt}\n\n## Phase 2: Execution\nBased on the plan, execute the task:\n\n${plan}\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

@@ -0,0 +1,299 @@
+import type { Sprint, Task, TaskStatus } from "@locusai/shared";
+import { AnthropicClient } from "../ai/anthropic-client";
+import { ClaudeRunner } from "../ai/claude-runner";
+import { LocusClient } from "../index";
+import { ArtifactSyncer } from "./artifact-syncer";
+import { CodebaseIndexerService } from "./codebase-indexer-service";
+import { SprintPlanner } from "./sprint-planner";
+import { TaskExecutor } from "./task-executor";
+
+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,
+    });
+
+    // 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 prefix = { info: "ℹ", success: "✓", warn: "⚠", error: "✗" }[level];
+    console.log(
+      `[${timestamp}] [${this.config.agentId.slice(-8)}] ${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 }> {
+    // Reindex codebase before execution to ensure fresh context
+    await this.indexerService.reindex();
+
+    // 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);
+
+    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);
+
+      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

@@ -0,0 +1,93 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { DEFAULT_MODEL } from "../core/config";
+
+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

@@ -0,0 +1,49 @@
+import { spawn } from "node:child_process";
+import { DEFAULT_MODEL } from "../core/config";
+
+export class ClaudeRunner {
+  constructor(
+    private projectPath: string,
+    private model: string = DEFAULT_MODEL
+  ) {}
+
+  run(prompt: string, _isPlanning = false): 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"],
+      });
+
+      let output = "";
+      let errorOutput = "";
+
+      claude.stdout.on("data", (data) => {
+        output += data.toString();
+        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: ${err.message}`))
+      );
+      claude.on("close", (code) => {
+        if (code === 0) resolve(output);
+        else
+          reject(new Error(`Claude exited with code ${code}: ${errorOutput}`));
+      });
+
+      claude.stdin.write(prompt);
+      claude.stdin.end();
+    });
+  }
+}

package/src/ai/index.ts

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

package/src/core/config.ts

@@ -0,0 +1,21 @@
+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

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

package/src/core/indexer.ts

@@ -0,0 +1,91 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { globby } from "globby";
+
+export interface CodebaseIndex {
+  symbols: Record<string, string[]>; // symbol -> file paths
+  responsibilities: Record<string, string>; // file path -> brief summary
+  lastIndexed: string;
+}
+
+export class CodebaseIndexer {
+  private projectPath: string;
+  private indexPath: string;
+
+  constructor(projectPath: string) {
+    this.projectPath = projectPath;
+    this.indexPath = join(projectPath, ".locus", "codebase-index.json");
+  }
+
+  /**
+   * Generates a codebase index by providing the entire file tree to an AI summarizer.
+   * This is much more efficient than per-file indexing for large projects.
+   */
+  async index(
+    onProgress?: (message: string) => void,
+    treeSummarizer?: (tree: string) => Promise<CodebaseIndex>
+  ): Promise<CodebaseIndex> {
+    if (!treeSummarizer) {
+      throw new Error("A treeSummarizer is required for this indexing method.");
+    }
+
+    if (onProgress) onProgress("Generating file tree...");
+
+    // 1. Get a comprehensive but clean file tree
+    const files = await globby(["**/*"], {
+      cwd: this.projectPath,
+      ignore: [
+        "**/node_modules/**",
+        "**/dist/**",
+        "**/build/**",
+        "**/.next/**",
+        "**/out/**",
+        "**/__tests__/**",
+        "**/*.test.*",
+        "**/*.spec.*",
+        "**/*.d.ts",
+        "**/tsconfig.tsbuildinfo",
+        "**/.locus/*.json", // Ignore index and other system JSONs
+        "**/.locus/*.md", // Ignore system MDs if any (except artifacts handled below)
+        "**/.locus/!(artifacts)/**", // Ignore everything in .locus EXCEPT artifacts
+        "bun.lock",
+        "package-lock.json",
+        "yarn.lock",
+      ],
+    });
+
+    // Format the tree for the AI
+    const treeString = files.join("\n");
+
+    if (onProgress) onProgress("AI is analyzing codebase structure...");
+
+    // 2. Ask AI to generate the index based on the tree
+    const index = await treeSummarizer(treeString);
+
+    // 3. Post-process: Ensure symbols are extracted for core files if not provided by AI
+    // (AI is good at structure, but might miss specific exports unless it reads the files)
+    // For now, we trust the AI's structural summary and can supplement symbols later if needed.
+
+    index.lastIndexed = new Date().toISOString();
+    return index;
+  }
+
+  loadIndex(): CodebaseIndex | null {
+    if (existsSync(this.indexPath)) {
+      try {
+        return JSON.parse(readFileSync(this.indexPath, "utf-8"));
+      } catch {
+        return null;
+      }
+    }
+    return null;
+  }
+
+  saveIndex(index: CodebaseIndex): void {
+    const dir = dirname(this.indexPath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(this.indexPath, JSON.stringify(index, null, 2));
+  }
+}