@locusai/sdk 0.2.1

package/dist/orchestrator.js

@@ -0,0 +1,326 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { TaskPriority, TaskStatus } from "@locusai/shared";
+import { EventEmitter } from "events";
+import { LocusClient } from "./index";
+export class AgentOrchestrator extends EventEmitter {
+    client;
+    config;
+    agents = new Map();
+    isRunning = false;
+    processedTasks = new Set();
+    resolvedSprintId = null;
+    constructor(config) {
+        super();
+        this.config = config;
+        this.client = new LocusClient({
+            baseUrl: config.apiBase,
+            token: config.apiKey,
+        });
+    }
+    /**
+     * Resolve the sprint ID - use provided or find active sprint
+     */
+    async resolveSprintId() {
+        if (this.config.sprintId) {
+            return this.config.sprintId;
+        }
+        // Try to find active sprint in workspace
+        try {
+            const sprint = await this.client.sprints.getActive(this.config.workspaceId);
+            if (sprint?.id) {
+                console.log(`📋 Using active sprint: ${sprint.name}`);
+                return sprint.id;
+            }
+        }
+        catch {
+            // No active sprint found, will work with all tasks
+        }
+        console.log("ℹ  No sprint specified, working with all workspace tasks");
+        return "";
+    }
+    /**
+     * Start the orchestrator with N agents
+     */
+    async start() {
+        if (this.isRunning) {
+            throw new Error("Orchestrator is already running");
+        }
+        this.isRunning = true;
+        this.processedTasks.clear();
+        try {
+            await this.orchestrationLoop();
+        }
+        catch (error) {
+            this.emit("error", error);
+            throw error;
+        }
+        finally {
+            await this.cleanup();
+        }
+    }
+    /**
+     * Main orchestration loop - runs 1 agent continuously
+     */
+    async orchestrationLoop() {
+        // Resolve sprint ID first
+        this.resolvedSprintId = await this.resolveSprintId();
+        this.emit("started", {
+            timestamp: new Date(),
+            config: this.config,
+            sprintId: this.resolvedSprintId,
+        });
+        console.log("\n🤖 Locus Agent Orchestrator");
+        console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+        console.log(`Workspace: ${this.config.workspaceId}`);
+        if (this.resolvedSprintId) {
+            console.log(`Sprint: ${this.resolvedSprintId}`);
+        }
+        console.log(`API Base: ${this.config.apiBase}`);
+        console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");
+        // Check if there are tasks to work on before spawning
+        const tasks = await this.getAvailableTasks();
+        if (tasks.length === 0) {
+            console.log("ℹ  No available tasks found in the backlog.");
+            return;
+        }
+        // Spawn single agent
+        await this.spawnAgent();
+        // Wait for agent to complete
+        while (this.agents.size > 0 && this.isRunning) {
+            await this.reapAgents();
+            if (this.agents.size === 0) {
+                break;
+            }
+            await this.sleep(2000);
+        }
+        console.log("\n✅ Orchestrator finished");
+    }
+    /**
+     * Spawn a single agent process
+     */
+    async spawnAgent() {
+        const agentId = `agent-${Date.now()}-${Math.random()
+            .toString(36)
+            .slice(2, 9)}`;
+        const agentState = {
+            id: agentId,
+            status: "IDLE",
+            currentTaskId: null,
+            tasksCompleted: 0,
+            tasksFailed: 0,
+            lastHeartbeat: new Date(),
+        };
+        this.agents.set(agentId, agentState);
+        console.log(`🚀 Agent started: ${agentId}\n`);
+        // Build arguments for agent worker
+        // Resolve path relative to this file's location (works in both dev and production)
+        const workerPath = join(__dirname, "agent", "worker.js");
+        // Verify worker file exists
+        if (!existsSync(workerPath)) {
+            throw new Error(`Worker file not found at ${workerPath}. ` +
+                `Make sure the SDK is properly built. __dirname: ${__dirname}`);
+        }
+        const workerArgs = [
+            "--agent-id",
+            agentId,
+            "--workspace-id",
+            this.config.workspaceId,
+            "--api-base",
+            this.config.apiBase,
+            "--api-key",
+            this.config.apiKey,
+            "--project-path",
+            this.config.projectPath,
+        ];
+        // Add anthropic API key if provided
+        if (this.config.anthropicApiKey) {
+            workerArgs.push("--anthropic-api-key", this.config.anthropicApiKey);
+        }
+        // Add model if specified
+        if (this.config.model) {
+            workerArgs.push("--model", this.config.model);
+        }
+        // Add sprint ID if resolved
+        if (this.resolvedSprintId) {
+            workerArgs.push("--sprint-id", this.resolvedSprintId);
+        }
+        // Use bun to run TypeScript files directly
+        const workerTsPath = workerPath.replace(/\.js$/, ".ts");
+        const agentProcess = spawn("bun", ["run", workerTsPath, ...workerArgs]);
+        agentState.process = agentProcess;
+        agentProcess.on("message", (msg) => {
+            if (msg.type === "stats") {
+                agentState.tasksCompleted = msg.tasksCompleted || 0;
+                agentState.tasksFailed = msg.tasksFailed || 0;
+            }
+        });
+        agentProcess.stdout?.on("data", (data) => {
+            process.stdout.write(data.toString());
+        });
+        agentProcess.stderr?.on("data", (data) => {
+            process.stderr.write(`[${agentId}] ERR: ${data.toString()}`);
+        });
+        agentProcess.on("exit", (code) => {
+            console.log(`\n${agentId} finished (exit code: ${code})`);
+            const agent = this.agents.get(agentId);
+            if (agent) {
+                agent.status = code === 0 ? "COMPLETED" : "FAILED";
+                // Ensure CLI gets the absolute latest stats
+                this.emit("agent:completed", {
+                    agentId,
+                    status: agent.status,
+                    tasksCompleted: agent.tasksCompleted,
+                    tasksFailed: agent.tasksFailed,
+                });
+                // Remove from active tracking after emitting
+                this.agents.delete(agentId);
+            }
+        });
+        this.emit("agent:spawned", { agentId });
+    }
+    /**
+     * Reap completed agents
+     */
+    async reapAgents() {
+        // No-op: agents now remove themselves in the 'exit' listener
+        // to ensure events are emitted with correct stats before deletion.
+    }
+    /**
+     * Get available tasks in sprint
+     */
+    async getAvailableTasks() {
+        try {
+            const tasks = await this.client.tasks.getAvailable(this.config.workspaceId, this.resolvedSprintId || undefined);
+            return tasks.filter((task) => !this.processedTasks.has(task.id));
+        }
+        catch (error) {
+            this.emit("error", error);
+            return [];
+        }
+    }
+    /**
+     * Assign task to agent
+     */
+    async assignTaskToAgent(agentId) {
+        const agent = this.agents.get(agentId);
+        if (!agent)
+            return null;
+        try {
+            const tasks = await this.getAvailableTasks();
+            const priorityOrder = [
+                TaskPriority.CRITICAL,
+                TaskPriority.HIGH,
+                TaskPriority.MEDIUM,
+                TaskPriority.LOW,
+            ];
+            // Find task with highest priority
+            let task = tasks.sort((a, b) => priorityOrder.indexOf(a.priority) - priorityOrder.indexOf(b.priority))[0];
+            // Fallback: any available task
+            if (!task && tasks.length > 0) {
+                task = tasks[0];
+            }
+            if (!task)
+                return null;
+            agent.currentTaskId = task.id;
+            agent.status = "WORKING";
+            this.emit("task:assigned", {
+                agentId,
+                taskId: task.id,
+                title: task.title,
+            });
+            return task;
+        }
+        catch (error) {
+            this.emit("error", error);
+            return null;
+        }
+    }
+    /**
+     * Mark task as completed by agent
+     */
+    async completeTask(taskId, agentId, summary) {
+        try {
+            await this.client.tasks.update(taskId, this.config.workspaceId, {
+                status: TaskStatus.VERIFICATION,
+            });
+            if (summary) {
+                await this.client.tasks.addComment(taskId, this.config.workspaceId, {
+                    author: agentId,
+                    text: `✅ Task completed\n\n${summary}`,
+                });
+            }
+            this.processedTasks.add(taskId);
+            const agent = this.agents.get(agentId);
+            if (agent) {
+                agent.tasksCompleted += 1;
+                agent.currentTaskId = null;
+                agent.status = "IDLE";
+            }
+            this.emit("task:completed", { agentId, taskId });
+        }
+        catch (error) {
+            this.emit("error", error);
+        }
+    }
+    /**
+     * Mark task as failed
+     */
+    async failTask(taskId, agentId, error) {
+        try {
+            await this.client.tasks.update(taskId, this.config.workspaceId, {
+                status: TaskStatus.BACKLOG,
+                assignedTo: null,
+            });
+            await this.client.tasks.addComment(taskId, this.config.workspaceId, {
+                author: agentId,
+                text: `❌ Agent failed: ${error}`,
+            });
+            const agent = this.agents.get(agentId);
+            if (agent) {
+                agent.tasksFailed += 1;
+                agent.currentTaskId = null;
+                agent.status = "IDLE";
+            }
+            this.emit("task:failed", { agentId, taskId, error });
+        }
+        catch (error) {
+            this.emit("error", error);
+        }
+    }
+    /**
+     * Stop orchestrator
+     */
+    async stop() {
+        this.isRunning = false;
+        await this.cleanup();
+        this.emit("stopped", { timestamp: new Date() });
+    }
+    /**
+     * Cleanup - kill all agent processes
+     */
+    async cleanup() {
+        for (const [agentId, agent] of this.agents.entries()) {
+            if (agent.process && !agent.process.killed) {
+                console.log(`Killing agent: ${agentId}`);
+                agent.process.kill();
+            }
+        }
+        this.agents.clear();
+    }
+    /**
+     * Get orchestrator stats
+     */
+    getStats() {
+        return {
+            activeAgents: this.agents.size,
+            processedTasks: this.processedTasks.size,
+            totalTasksCompleted: Array.from(this.agents.values()).reduce((sum, agent) => sum + agent.tasksCompleted, 0),
+            totalTasksFailed: Array.from(this.agents.values()).reduce((sum, agent) => sum + agent.tasksFailed, 0),
+        };
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@locusai/sdk",
+  "version": "0.2.1",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./node": {
+      "types": "./src/index-node.ts",
+      "default": "./src/index-node.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "./node": {
+        "types": "./dist/index-node.d.ts",
+        "default": "./dist/index-node.js"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "lint": "biome lint .",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.71.2",
+    "@locusai/shared": "workspace:*",
+    "axios": "^1.13.2",
+    "events": "^3.3.0",
+    "globby": "^14.0.2"
+  },
+  "devDependencies": {
+    "typescript": "5.8.3",
+    "@types/node": "^22.10.7"
+  }
+}

package/src/agent/artifact-syncer.ts

@@ -0,0 +1,111 @@
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+} from "node:fs";
+import { join } from "node:path";
+import { getLocusPath } from "../core/config";
+import type { LocusClient } from "../index";
+
+export interface ArtifactSyncerDeps {
+  client: LocusClient;
+  workspaceId: string;
+  projectPath: string;
+  log: (message: string, level?: "info" | "success" | "warn" | "error") => void;
+}
+
+/**
+ * Handles syncing local artifacts to the platform
+ */
+export class ArtifactSyncer {
+  constructor(private deps: ArtifactSyncerDeps) {}
+
+  private async getOrCreateArtifactsGroup(): Promise<string> {
+    try {
+      const groups = await this.deps.client.docs.listGroups(
+        this.deps.workspaceId
+      );
+      const artifactsGroup = groups.find((g) => g.name === "Artifacts");
+
+      if (artifactsGroup) {
+        return artifactsGroup.id;
+      }
+
+      // Create the Artifacts group
+      const newGroup = await this.deps.client.docs.createGroup(
+        this.deps.workspaceId,
+        {
+          name: "Artifacts",
+          order: 999, // Place at the end
+        }
+      );
+      this.deps.log(
+        "Created 'Artifacts' group for agent-generated docs",
+        "info"
+      );
+      return newGroup.id;
+    } catch (error) {
+      this.deps.log(`Failed to get/create Artifacts group: ${error}`, "error");
+      throw error;
+    }
+  }
+
+  async sync(): Promise<void> {
+    const artifactsDir = getLocusPath(this.deps.projectPath, "artifactsDir");
+    if (!existsSync(artifactsDir)) {
+      mkdirSync(artifactsDir, { recursive: true });
+      return;
+    }
+
+    try {
+      const files = readdirSync(artifactsDir);
+      if (files.length === 0) return;
+
+      this.deps.log(`Syncing ${files.length} artifacts to server...`, "info");
+
+      // Get or create the Artifacts group
+      const artifactsGroupId = await this.getOrCreateArtifactsGroup();
+
+      // Get existing docs to check for updates
+      const existingDocs = await this.deps.client.docs.list(
+        this.deps.workspaceId
+      );
+
+      for (const file of files) {
+        const filePath = join(artifactsDir, file);
+        if (statSync(filePath).isFile()) {
+          const content = readFileSync(filePath, "utf-8");
+          const title = file.replace(/\.md$/, "").trim();
+          if (!title) continue;
+
+          const existing = existingDocs.find((d) => d.title === title);
+
+          if (existing) {
+            if (
+              existing.content !== content ||
+              existing.groupId !== artifactsGroupId
+            ) {
+              await this.deps.client.docs.update(
+                existing.id,
+                this.deps.workspaceId,
+                { content, groupId: artifactsGroupId }
+              );
+              this.deps.log(`Updated artifact: ${file}`, "success");
+            }
+          } else {
+            await this.deps.client.docs.create(this.deps.workspaceId, {
+              title,
+              content,
+              groupId: artifactsGroupId,
+            });
+            this.deps.log(`Created artifact: ${file}`, "success");
+          }
+        }
+      }
+    } catch (error) {
+      this.deps.log(`Failed to sync artifacts: ${error}`, "error");
+    }
+  }
+}

package/src/agent/codebase-indexer-service.ts

@@ -0,0 +1,71 @@
+import type { AnthropicClient } from "../ai/anthropic-client";
+import type { ClaudeRunner } from "../ai/claude-runner";
+import { CodebaseIndexer } from "../core/indexer";
+
+export interface CodebaseIndexerServiceDeps {
+  anthropicClient: AnthropicClient | null;
+  claudeRunner: ClaudeRunner;
+  projectPath: string;
+  log: (message: string, level?: "info" | "success" | "warn" | "error") => void;
+}
+
+/**
+ * Handles codebase indexing with AI analysis
+ */
+export class CodebaseIndexerService {
+  private indexer: CodebaseIndexer;
+
+  constructor(private deps: CodebaseIndexerServiceDeps) {
+    this.indexer = new CodebaseIndexer(deps.projectPath);
+  }
+
+  async reindex(): Promise<void> {
+    try {
+      this.deps.log("Reindexing codebase...", "info");
+
+      const index = await this.indexer.index(
+        (msg) => this.deps.log(msg, "info"),
+        async (tree: string) => {
+          const prompt = `You are a codebase analysis expert. Analyze the file tree and extract:
+1. Key symbols (classes, functions, types) and their locations
+2. Responsibilities of each directory/file
+3. Overall project structure
+
+Analyze this file tree and provide a JSON response with:
+- "symbols": object mapping symbol names to file paths (array)
+- "responsibilities": object mapping paths to brief descriptions
+
+File tree:
+${tree}
+
+Return ONLY valid JSON, no markdown formatting.`;
+
+          let response: string;
+
+          if (this.deps.anthropicClient) {
+            // Use Anthropic SDK with caching for faster indexing
+            response = await this.deps.anthropicClient.run({
+              systemPrompt:
+                "You are a codebase analysis expert specialized in extracting structure and symbols from file trees.",
+              userPrompt: prompt,
+            });
+          } else {
+            // Fallback to Claude CLI
+            response = await this.deps.claudeRunner.run(prompt, true);
+          }
+
+          // Extract JSON from response (handle markdown code blocks)
+          const jsonMatch = response.match(/\{[\s\S]*\}/);
+          if (jsonMatch) {
+            return JSON.parse(jsonMatch[0]);
+          }
+          return { symbols: {}, responsibilities: {}, lastIndexed: "" };
+        }
+      );
+      this.indexer.saveIndex(index);
+      this.deps.log("Codebase reindexed successfully", "success");
+    } catch (error) {
+      this.deps.log(`Failed to reindex codebase: ${error}`, "error");
+    }
+  }
+}

package/src/agent/index.ts

@@ -0,0 +1,5 @@
+export { ArtifactSyncer } from "./artifact-syncer";
+export { CodebaseIndexerService } from "./codebase-indexer-service";
+export { SprintPlanner } from "./sprint-planner";
+export { TaskExecutor } from "./task-executor";
+export { AgentWorker, type WorkerConfig } from "./worker";

package/src/agent/sprint-planner.ts

@@ -0,0 +1,78 @@
+import type { Sprint, Task } from "@locusai/shared";
+import type { AnthropicClient } from "../ai/anthropic-client";
+import type { ClaudeRunner } from "../ai/claude-runner";
+
+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");
+
+    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;
+  }
+}