@locusai/cli 0.17.13 → 0.17.15

package/bin/locus.js

@@ -105,20 +105,11 @@ function padEnd(str, width) {
     return str;
   return str + " ".repeat(width - currentWidth);
 }
-function clearLine() {
-  if (getCapabilities().isTTY) {
-    process.stdout.write("\x1B[2K\r");
-  }
-}
-function hideCursor() {
-  if (getCapabilities().isTTY) {
-    process.stdout.write("\x1B[?25l");
-  }
-}
-function showCursor() {
-  if (getCapabilities().isTTY) {
-    process.stdout.write("\x1B[?25h");
-  }
+function truncate(str, maxWidth) {
+  const stripped = stripAnsi(str);
+  if (stripped.length <= maxWidth)
+    return str;
+  return `${stripped.slice(0, maxWidth - 1)}…`;
 }
 function beginSync() {
   if (getCapabilities().isTTY) {
@@ -821,9 +812,10 @@ class Spinner {
     this.message = message;
     this.frame = 0;
     this.timer = setInterval(() => {
+      if (!process.stderr.isTTY)
+        return;
       const char = cyan(SPINNER_FRAMES[this.frame % SPINNER_FRAMES.length]);
-      clearLine();
-      process.stderr.write(`${char} ${this.message}`);
+      process.stderr.write(`\x1B[2K\r${char} ${this.message}`);
       this.frame++;
     }, 80);
     if (this.timer.unref) {
@@ -838,7 +830,9 @@ class Spinner {
       clearInterval(this.timer);
       this.timer = null;
     }
-    clearLine();
+    if (process.stderr.isTTY) {
+      process.stderr.write("\x1B[2K\r");
+    }
     if (finalMessage) {
       process.stderr.write(`${finalMessage}
 `);
@@ -1640,9 +1634,103 @@ ${bold(green("Locus initialized!"))}
     reInit: isReInit
   });
 }
-var LOCUS_MD_TEMPLATE = `# Locus — Project Instructions
+var LOCUS_MD_TEMPLATE = `## Planning First
+
+Complex tasks must be planned before writing code. Create ".locus/plans/<task-name>.md" with:
+- **Goal**: What we're trying to achieve and why
+- **Approach**: Step-by-step strategy with technical decisions
+- **Affected files**: List of files to create/modify/delete
+- **Acceptance criteria**: Specific, testable conditions for completion
+- **Dependencies**: Required packages, APIs, or external services
+
+Delete the planning .md files after successful execution.
+
+## Code Quality
+
+- **Follow existing patterns**: Run formatters and linters before finishing (check "package.json" scripts or project config)
+- **Minimize changes**: Keep modifications atomic. Separate refactors from behavioral changes into different tasks
+- **Never commit secrets**: No API keys, passwords, or credentials in code. Use environment variables or secret management
+- **Test as you go**: If tests exist, run relevant ones. If breaking changes occur, update tests accordingly
+- **Comment complex logic**: Explain *why*, not *what*. Focus on business logic and non-obvious decisions
+
+## Artifacts
+
+When a task produces knowledge, analysis, or research output rather than (or in addition to) code changes, you **must** save results as Markdown in ".locus/artifacts/<descriptive-name>.md":
+
+**Always create artifacts for:**
+- Code quality audits, security reviews, vulnerability assessments
+- Architecture analyses, system design proposals, or recommendations
+- Dependency reports, performance profiling, benchmarking results
+- Research summaries, technology comparisons, or feasibility studies
+- Migration plans, deployment strategies, or rollback procedures
+- Post-mortems, incident analysis, or debugging investigations
+
+**Artifact structure:**
+- Clear title and date
+- Executive summary (2-3 sentences)
+- Detailed findings/analysis
+- Actionable recommendations (if applicable)
+
+## Git Operations
+
+- **Do NOT run**: git add, git commit, git push, git checkout, git branch, or any git commands
+- **Why**: The Locus orchestrator handles all version control automatically after execution
+- **Your role**: Focus solely on making file changes. The system commits, pushes, and creates PRs
+
+## Continuous Learning
+
+Read ".locus/LEARNINGS.md" **before starting any task** to avoid repeating mistakes.
+
+**The quality bar:** Ask yourself — "Would a new agent working on a completely different task benefit from knowing this?" If yes, record it. If it only matters for the current task or file, skip it.
+
+**When to update:**
+- User corrects your approach, rejects a choice, or states a preference explicitly
+- You discover where something lives architecturally (e.g., which package owns shared types)
+- A structural or design decision would not be obvious from reading the code
+- You encounter a non-obvious constraint that applies project-wide
+
+**What to record (high-value):**
+- Where things live: package ownership, shared utilities, config locations
+- Architectural decisions and their rationale ("we use X not Y because Z")
+- Explicit user preference overrides — when the user corrects or rejects an approach
+- Project-wide conventions that aren't visible from a single file
 
-This file provides context to AI agents when executing tasks.
+**What NOT to record (low-value):**
+- One-time fixes or workarounds specific to a single file or function
+- Implementation details that are obvious from reading the code
+- Startup sequences, signal handlers, or local patterns — unless they represent a project-wide rule
+- Anything the next agent could discover in 30 seconds by reading the relevant file
+
+**Good examples:**
+- \`[Architecture]\`: Shared types for all packages live in \`@locusai/shared\` — never redefine them locally in CLI or API packages.
+- \`[User Preferences]\`: User prefers not to track low-level interrupt/signal handling patterns in learnings — focus on architectural and decision-level entries.
+- \`[Packages]\`: Validation uses Zod throughout — do not introduce a second validation library.
+
+**Bad examples (do not write these):**
+- \`[Patterns]\`: \`run.ts\` must call \`registerShutdownHandlers()\` at startup. ← too local, obvious from the file.
+- \`[Debugging]\`: Fixed a regex bug in \`image-detect.ts\`. ← one-time fix, irrelevant to future tasks.
+
+**Format (append-only, never delete):**
+
+\`\`\`
+- **[Category]**: Concise description (1-2 lines max). *Rationale if non-obvious.*
+\`\`\`
+
+**Categories:** Architecture, Packages, User Preferences, Conventions, Debugging
+
+## Error Handling
+
+- **Read error messages carefully**: Don't guess. Parse the actual error before proposing fixes
+- **Check dependencies first**: Missing packages, wrong versions, and environment issues are common
+- **Verify assumptions**: If something "should work," confirm it actually does in this environment
+- **Ask for context**: If you need environment details, configuration, or logs, request them explicitly
+
+## Communication
+
+- **Be precise**: When uncertain, state what you know and what you're assuming
+- **Show your work**: For complex changes, briefly explain the approach before executing
+- **Highlight trade-offs**: If multiple approaches exist, note why you chose one over others
+- **Request feedback**: For ambiguous requirements, propose an approach and ask for confirmation
 
 ## Project Overview
 
@@ -1655,16 +1743,13 @@ This file provides context to AI agents when executing tasks.
 ## Development Workflow
 
 <!-- How to run, test, build, and deploy the project -->
-
-## Important Notes
-
-<!-- Anything the AI agent should know: gotchas, design decisions, constraints -->
 `, LEARNINGS_MD_TEMPLATE = `# Learnings
 
 This file captures important lessons, decisions, and corrections made during development.
 It is read by AI agents before every task to avoid repeating mistakes and to follow established patterns.
 
 <!-- Add learnings below this line. Format: - **[Category]**: Description -->
+- **[User Preferences]**: Do not record low-level implementation details or one-time fixes in learnings. Focus on architectural decisions, package ownership, and explicit user preference overrides — entries that help any future agent on any task, not just the current one.
 `, GITIGNORE_ENTRIES;
 var init_init = __esm(() => {
   init_config();
@@ -2533,7 +2618,9 @@ var init_status_indicator = __esm(() => {
       this.startTime = Date.now();
       this.activity = options?.activity ?? "";
       this.frame = 0;
-      hideCursor();
+      if (process.stderr.isTTY) {
+        process.stderr.write("\x1B[?25l");
+      }
       this.timer = setInterval(() => {
         this.render(message);
         this.frame++;
@@ -2547,8 +2634,9 @@ var init_status_indicator = __esm(() => {
         clearInterval(this.timer);
         this.timer = null;
       }
-      clearLine();
-      showCursor();
+      if (process.stderr.isTTY) {
+        process.stderr.write("\x1B[2K\r\x1B[?25h");
+      }
     }
     isActive() {
       return this.timer !== null;
@@ -2569,12 +2657,13 @@ var init_status_indicator = __esm(() => {
         line += ` ${dim("—")} ${dim(this.activity)}`;
       }
       line += ` ${dim("— esc to interrupt")}`;
-      const maxWidth = caps.columns - 1;
-      if (line.length > maxWidth + 50) {
-        line = line.slice(0, maxWidth + 50);
+      const cols = process.stderr.columns ?? process.stdout.columns ?? 80;
+      if (visualWidth(line) > cols - 1) {
+        line = truncate(line, cols - 1);
       }
-      clearLine();
-      process.stderr.write(line);
+      if (!process.stderr.isTTY)
+        return;
+      process.stderr.write("\x1B[2K\r" + line);
     }
     renderShimmer() {
       const t = Date.now() / 1000;
@@ -2959,8 +3048,6 @@ class InputHandler {
   isLocked() {
     return this.locked;
   }
-  enableProtocols() {}
-  disableProtocols() {}
   async readline() {
     await this.waitUntilUnlocked();
     return new Promise((resolve2) => {
@@ -3739,6 +3826,9 @@ class ClaudeRunner {
     if (options.model) {
       args.push("--model", options.model);
     }
+    if (options.verbose) {
+      args.push("--verbose", "--output-format", "stream-json");
+    }
     log.debug("Spawning claude", { args: args.join(" "), cwd: options.cwd });
     return new Promise((resolve2) => {
       let output = "";
@@ -3751,11 +3841,46 @@ class ClaudeRunner {
         stdio: ["pipe", "pipe", "pipe"],
         env
       });
-      this.process.stdout?.on("data", (chunk) => {
-        const text = chunk.toString();
-        output += text;
-        options.onOutput?.(text);
-      });
+      if (options.verbose) {
+        let lineBuffer = "";
+        const seenToolIds = new Set;
+        this.process.stdout?.on("data", (chunk) => {
+          lineBuffer += chunk.toString();
+          const lines = lineBuffer.split(`
+`);
+          lineBuffer = lines.pop() ?? "";
+          for (const line of lines) {
+            if (!line.trim())
+              continue;
+            try {
+              const event = JSON.parse(line);
+              if (event.type === "assistant" && event.message?.content) {
+                for (const item of event.message.content) {
+                  if (item.type === "tool_use" && item.id && !seenToolIds.has(item.id)) {
+                    seenToolIds.add(item.id);
+                    options.onToolActivity?.(formatToolCall(item.name ?? "", item.input ?? {}));
+                  }
+                }
+              } else if (event.type === "result") {
+                const text = event.result ?? "";
+                output = text;
+                options.onOutput?.(text);
+              }
+            } catch {
+              const newLine = `${line}
+`;
+              output += newLine;
+              options.onOutput?.(newLine);
+            }
+          }
+        });
+      } else {
+        this.process.stdout?.on("data", (chunk) => {
+          const text = chunk.toString();
+          output += text;
+          options.onOutput?.(text);
+        });
+      }
       this.process.stderr?.on("data", (chunk) => {
         const text = chunk.toString();
         errorOutput += text;
@@ -3823,6 +3948,33 @@ class ClaudeRunner {
     }
   }
 }
+function formatToolCall(name, input) {
+  switch (name) {
+    case "Read":
+      return `reading ${input.file_path ?? ""}`;
+    case "Write":
+      return `writing ${input.file_path ?? ""}`;
+    case "Edit":
+    case "MultiEdit":
+      return `editing ${input.file_path ?? ""}`;
+    case "Bash":
+      return `running: ${String(input.command ?? "").slice(0, 60)}`;
+    case "Glob":
+      return `glob ${input.pattern ?? ""}`;
+    case "Grep":
+      return `grep ${input.pattern ?? ""}`;
+    case "LS":
+      return `ls ${input.path ?? ""}`;
+    case "WebFetch":
+      return `fetching ${String(input.url ?? "").slice(0, 50)}`;
+    case "WebSearch":
+      return `searching: ${input.query ?? ""}`;
+    case "Task":
+      return `spawning agent`;
+    default:
+      return name;
+  }
+}
 var init_claude = __esm(() => {
   init_logger();
 });
@@ -3830,7 +3982,7 @@ var init_claude = __esm(() => {
 // src/ai/codex.ts
 import { execSync as execSync5, spawn as spawn3 } from "node:child_process";
 function buildCodexArgs(model) {
-  const args = ["exec", "--full-auto", "--skip-git-repo-check"];
+  const args = ["exec", "--full-auto", "--skip-git-repo-check", "--json"];
   if (model) {
     args.push("--model", model);
   }
@@ -3870,17 +4022,65 @@ class CodexRunner {
     const args = buildCodexArgs(options.model);
     log.debug("Spawning codex", { args: args.join(" "), cwd: options.cwd });
     return new Promise((resolve2) => {
-      let output = "";
+      let rawOutput = "";
       let errorOutput = "";
       this.process = spawn3("codex", args, {
         cwd: options.cwd,
         stdio: ["pipe", "pipe", "pipe"],
         env: { ...process.env }
       });
+      let agentMessages = [];
+      const flushAgentMessages = () => {
+        if (agentMessages.length > 0) {
+          options.onOutput?.(agentMessages.join(`
+
+`));
+          agentMessages = [];
+        }
+      };
+      let lineBuffer = "";
       this.process.stdout?.on("data", (chunk) => {
-        const text = chunk.toString();
-        output += text;
-        options.onOutput?.(text);
+        lineBuffer += chunk.toString();
+        const lines = lineBuffer.split(`
+`);
+        lineBuffer = lines.pop() ?? "";
+        for (const line of lines) {
+          if (!line.trim())
+            continue;
+          rawOutput += `${line}
+`;
+          log.debug("codex stdout line", { line });
+          try {
+            const event = JSON.parse(line);
+            const { type, item } = event;
+            if (type === "item.started" && item?.type === "command_execution") {
+              const cmd = (item.command ?? "").split(`
+`)[0].slice(0, 80);
+              options.onToolActivity?.(`running: ${cmd}`);
+            } else if (type === "item.completed" && item?.type === "command_execution") {
+              const code = item.exit_code;
+              options.onToolActivity?.(code === 0 ? "done" : `exit ${code}`);
+            } else if (type === "item.completed" && item?.type === "reasoning") {
+              const text = (item.text ?? "").trim().replace(/\*\*([^*]+)\*\*/g, "$1").replace(/(?<!\*)\*([^*]+)\*(?!\*)/g, "$1");
+              if (text)
+                options.onToolActivity?.(text);
+            } else if (type === "item.completed" && item?.type === "agent_message") {
+              const text = item.text ?? "";
+              if (text) {
+                agentMessages.push(text);
+                options.onToolActivity?.(text.split(`
+`)[0].slice(0, 80));
+              }
+            } else if (type === "turn.completed") {
+              flushAgentMessages();
+            }
+          } catch {
+            const newLine = `${line}
+`;
+            rawOutput += newLine;
+            options.onOutput?.(newLine);
+          }
+        }
       });
       this.process.stderr?.on("data", (chunk) => {
         const text = chunk.toString();
@@ -3889,10 +4089,11 @@ class CodexRunner {
       });
       this.process.on("close", (code) => {
         this.process = null;
+        flushAgentMessages();
         if (this.aborted) {
           resolve2({
             success: false,
-            output,
+            output: rawOutput,
             error: "Aborted by user",
             exitCode: code ?? 143
           });
@@ -3901,13 +4102,13 @@ class CodexRunner {
         if (code === 0) {
           resolve2({
             success: true,
-            output,
+            output: rawOutput,
             exitCode: 0
           });
         } else {
           resolve2({
             success: false,
-            output,
+            output: rawOutput,
             error: errorOutput || `codex exited with code ${code}`,
             exitCode: code ?? 1
           });
@@ -3917,7 +4118,7 @@ class CodexRunner {
         this.process = null;
         resolve2({
           success: false,
-          output,
+          output: rawOutput,
           error: `Failed to spawn codex: ${err.message}`,
           exitCode: 1
         });
@@ -4025,6 +4226,7 @@ ${red("✗")} ${dim("Force exit.")}\r
       model: options.model,
       cwd: options.cwd,
       signal: abortController.signal,
+      verbose: options.verbose,
       onOutput: (chunk) => {
         if (wasAborted)
           return;
@@ -4034,7 +4236,19 @@ ${red("✗")} ${dim("Force exit.")}\r
         }
         renderer?.push(chunk);
         output += chunk;
-      }
+      },
+      onToolActivity: (() => {
+        let lastActivityTime = 0;
+        return (summary) => {
+          if (wasAborted)
+            return;
+          const now = Date.now();
+          if (now - lastActivityTime >= 2000) {
+            lastActivityTime = now;
+            indicator.setActivity(summary);
+          }
+        };
+      })()
     });
     renderer?.stop();
     indicator.stop();
@@ -5939,6 +6153,12 @@ function getSlashCommands() {
       description: "Force-save current session",
       handler: cmdSave
     },
+    {
+      name: "/verbose",
+      aliases: ["/v"],
+      description: "Toggle verbose mode (show agent stderr streams)",
+      handler: cmdVerbose
+    },
     {
       name: "/exit",
       aliases: ["/quit", "/q"],
@@ -5999,8 +6219,30 @@ function cmdReset(_args, ctx) {
   process.stderr.write(`${green("✓")} Conversation context reset.
 `);
 }
-function cmdHistory(_args, _ctx) {
-  process.stderr.write(`${dim("Recent input history is shown above the prompt.")}
+function cmdHistory(_args, ctx) {
+  const entries = ctx.getHistory();
+  if (entries.length === 0) {
+    process.stderr.write(`${dim("No input history.")}
+`);
+    return;
+  }
+  process.stderr.write(`
+${bold("Input History:")} ${dim(`(${entries.length} entries)`)}
+
+`);
+  const display = entries.slice(0, 50);
+  for (let i = 0;i < display.length; i++) {
+    const num = dim(`${String(i + 1).padStart(3)}.`);
+    const entry = display[i].replace(/\n/g, dim("↵"));
+    process.stderr.write(`  ${num} ${entry}
+`);
+  }
+  if (entries.length > 50) {
+    process.stderr.write(`
+  ${dim(`… and ${entries.length - 50} more`)}
+`);
+  }
+  process.stderr.write(`
 `);
 }
 function cmdSession(_args, ctx) {
@@ -6109,6 +6351,12 @@ function cmdSave(_args, ctx) {
   process.stderr.write(`${green("✓")} Session saved.
 `);
 }
+function cmdVerbose(_args, ctx) {
+  ctx.onVerboseToggle();
+  const isOn = ctx.getVerbose();
+  process.stderr.write(`${isOn ? green("✓") : dim("○")} Verbose mode ${isOn ? bold("on") : "off"} — agent streams ${isOn ? "visible" : "hidden"}.
+`);
+}
 function cmdExit(_args, ctx) {
   ctx.onExit();
 }
@@ -6526,11 +6774,11 @@ async function runInteractiveRepl(session, sessionManager, options) {
     getHistory: () => history.getEntries(),
     onTab: (text) => completion.complete(text)
   });
-  input.enableProtocols();
   printWelcome(session);
   let shouldExit = false;
   let currentProvider = inferProviderFromModel(config.ai.model) || config.ai.provider;
   let currentModel = config.ai.model;
+  let verbose = true;
   const slashCtx = {
     projectRoot,
     session,
@@ -6556,7 +6804,12 @@ async function runInteractiveRepl(session, sessionManager, options) {
     },
     onExit: () => {
       shouldExit = true;
-    }
+    },
+    getHistory: () => history.getEntries(),
+    onVerboseToggle: () => {
+      verbose = !verbose;
+    },
+    getVerbose: () => verbose
   };
   while (!shouldExit) {
     const result = await input.readline();
@@ -6586,7 +6839,7 @@ async function runInteractiveRepl(session, sessionManager, options) {
               ...config,
               ai: { provider: currentProvider, model: currentModel }
             }
-          });
+          }, verbose);
           sessionManager.addMessage(session, {
             role: "assistant",
             content: response,
@@ -6611,7 +6864,6 @@ ${red("✗")} ${msg}
         break;
     }
   }
-  input.disableProtocols();
   const shouldPersistOnExit = session.messages.length > 0 || sessionManager.isPersisted(session);
   if (shouldPersistOnExit) {
     sessionManager.save(session);
@@ -6627,13 +6879,14 @@ ${red("✗")} ${msg}
   process.stdin.pause();
   process.exit(0);
 }
-async function executeAITurn(prompt, session, options) {
+async function executeAITurn(prompt, session, options, verbose = false) {
   const { config, projectRoot } = options;
   const aiResult = await runAI({
     prompt,
     provider: config.ai.provider,
     model: config.ai.model,
-    cwd: projectRoot
+    cwd: projectRoot,
+    verbose
   });
   if (aiResult.interrupted) {
     if (aiResult.output) {
@@ -8534,7 +8787,7 @@ ${bold("Plan saved:")} ${cyan(id)}
 `);
     return;
   }
-  process.stderr.write(`  To create these issues: ${bold(`locus plan approve ${id.slice(0, 8)}`)}
+  process.stderr.write(`  To create these issues: ${bold(`locus plan approve ${id.slice(0, 8)} --sprint <sprint name>`)}
 
 `);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@locusai/cli",
-  "version": "0.17.13",
+  "version": "0.17.15",
   "description": "GitHub-native AI engineering assistant",
   "type": "module",
   "bin": {