ax-agents 0.0.1-alpha.7 → 0.0.1-alpha.9

package/ax.js

@@ -27,7 +27,7 @@ import {
   readSync,
   closeSync,
 } from "node:fs";
-import { randomUUID } from "node:crypto";
+import { randomUUID, createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
 import os from "node:os";
@@ -305,6 +305,18 @@ const TRUNCATE_THINKING_LEN = 300;
 const ARCHANGEL_GIT_CONTEXT_HOURS = 4;
 const ARCHANGEL_GIT_CONTEXT_MAX_LINES = 200;
 const ARCHANGEL_PARENT_CONTEXT_ENTRIES = 10;
+const ARCHANGEL_PREAMBLE = `## Guidelines
+
+- Investigate before speaking. If uncertain, read more code and trace the logic until you're confident.
+- Explain WHY something is an issue, not just that it is.
+- Focus on your area of expertise.
+- Calibrate to the task or plan. Don't suggest refactors during a bug fix.
+- Be clear. Brief is fine, but never sacrifice clarity.
+- For critical issues, request for them to be added to the todo list.
+- Don't repeat observations you've already made unless you have more to say or better clarity.
+- Make judgment calls - don't ask questions.
+
+"No issues found." is a valid response when there's nothing significant to report.`;
 
 /**
  * @param {string} session
@@ -544,6 +556,16 @@ function generateSessionName(tool) {
   return `${tool}-partner-${randomUUID()}`;
 }
 
+/**
+ * Quick hash for change detection (not cryptographic).
+ * @param {string | null | undefined} str
+ * @returns {string | null}
+ */
+function quickHash(str) {
+  if (!str) return null;
+  return createHash("md5").update(str).digest("hex").slice(0, 8);
+}
+
 /**
  * @param {string} cwd
  * @returns {string}
@@ -671,6 +693,93 @@ function findCodexLogPath(sessionName) {
   }
 }
 
+/**
+ * @typedef {Object} SessionMeta
+ * @property {string | null} slug - Plan identifier (if plan is active)
+ * @property {Array<{content: string, status: string, id?: string}> | null} todos - Current todos
+ * @property {string | null} permissionMode - "default", "acceptEdits", "plan"
+ * @property {string | null} gitBranch - Current git branch
+ * @property {string | null} cwd - Working directory
+ */
+
+/**
+ * Get metadata from a Claude session's JSONL file.
+ * Returns null for Codex sessions (different format, no equivalent metadata).
+ * @param {string} sessionName - The tmux session name
+ * @returns {SessionMeta | null}
+ */
+function getSessionMeta(sessionName) {
+  const parsed = parseSessionName(sessionName);
+  if (!parsed) return null;
+
+  // Only Claude sessions have this metadata
+  if (parsed.tool !== "claude") return null;
+  if (!parsed.uuid) return null;
+
+  const logPath = findClaudeLogPath(parsed.uuid, sessionName);
+  if (!logPath || !existsSync(logPath)) return null;
+
+  try {
+    const content = readFileSync(logPath, "utf-8");
+    const lines = content.trim().split("\n").filter(Boolean);
+
+    // Read from end to find most recent entry with metadata
+    for (let i = lines.length - 1; i >= 0; i--) {
+      try {
+        const entry = JSON.parse(lines[i]);
+        // User entries typically have the metadata fields
+        if (entry.type === "user" || entry.slug || entry.gitBranch) {
+          return {
+            slug: entry.slug || null,
+            todos: entry.todos || null,
+            permissionMode: entry.permissionMode || null,
+            gitBranch: entry.gitBranch || null,
+            cwd: entry.cwd || null,
+          };
+        }
+      } catch {
+        // Skip malformed lines
+      }
+    }
+    return null;
+  } catch (err) {
+    debugError("getSessionMeta", err);
+    return null;
+  }
+}
+
+/**
+ * Read a plan file by its slug.
+ * @param {string} slug - The plan slug (e.g., "curious-roaming-pascal")
+ * @returns {string | null} The plan content or null if not found
+ */
+function readPlanFile(slug) {
+  const planPath = path.join(CLAUDE_CONFIG_DIR, "plans", `${slug}.md`);
+  try {
+    if (existsSync(planPath)) {
+      return readFileSync(planPath, "utf-8");
+    }
+  } catch (err) {
+    debugError("readPlanFile", err);
+  }
+  return null;
+}
+
+/**
+ * Format todos for display in a prompt.
+ * @param {Array<{content: string, status: string, id?: string}>} todos
+ * @returns {string}
+ */
+function formatTodos(todos) {
+  if (!todos || todos.length === 0) return "";
+  return todos
+    .map((t) => {
+      const status = t.status === "completed" ? "[x]" : t.status === "in_progress" ? "[>]" : "[ ]";
+      return `${status} ${t.content || "(no content)"}`;
+    })
+    .join("\n");
+}
+
 /**
  * Extract assistant text responses from a JSONL log file.
  * This provides clean text without screen-scraped artifacts.
@@ -1725,8 +1834,8 @@ function detectState(screen, config) {
   // Larger range for confirmation detection (catches dialogs that scrolled slightly)
   const recentLines = lines.slice(-15).join("\n");
 
-  // Rate limited - check full screen (rate limit messages can appear anywhere)
-  if (config.rateLimitPattern && config.rateLimitPattern.test(screen)) {
+  // Rate limited - check recent lines (not full screen to avoid matching historical output)
+  if (config.rateLimitPattern && config.rateLimitPattern.test(recentLines)) {
     return State.RATE_LIMITED;
   }
 
@@ -1743,7 +1852,22 @@ function detectState(screen, config) {
     }
   }
 
-  // Thinking - spinners (check last lines only to avoid false positives from timing messages like "✻ Crunched for 32s")
+  // Ready - check BEFORE thinking to avoid false positives from timing messages like "✻ Worked for 45s"
+  // If the prompt symbol is visible, the agent is ready regardless of spinner characters in timing messages
+  if (lastLines.includes(config.promptSymbol)) {
+    // Check if any line has the prompt followed by pasted content indicator
+    // "[Pasted text" indicates user has pasted content and Claude is still processing
+    const linesArray = lastLines.split("\n");
+    const promptWithPaste = linesArray.some(
+      (l) => l.includes(config.promptSymbol) && l.includes("[Pasted text"),
+    );
+    if (!promptWithPaste) {
+      return State.READY;
+    }
+    // If prompt has pasted content, Claude is still processing - not ready yet
+  }
+
+  // Thinking - spinners (check last lines only)
   const spinners = config.spinners || [];
   if (spinners.some((s) => lastLines.includes(s))) {
     return State.THINKING;
@@ -1768,20 +1892,6 @@ function detectState(screen, config) {
     }
   }
 
-  // Ready - only if prompt symbol is visible AND not followed by pasted content
-  // "[Pasted text" indicates user has pasted content and Claude is still processing
-  if (lastLines.includes(config.promptSymbol)) {
-    // Check if any line has the prompt followed by pasted content indicator
-    const linesArray = lastLines.split("\n");
-    const promptWithPaste = linesArray.some(
-      (l) => l.includes(config.promptSymbol) && l.includes("[Pasted text"),
-    );
-    if (!promptWithPaste) {
-      return State.READY;
-    }
-    // If prompt has pasted content, Claude is still processing - not ready yet
-  }
-
   return State.STARTING;
 }
 
@@ -2508,19 +2618,22 @@ function cmdAgents() {
     const agent = parsed.tool === "claude" ? ClaudeAgent : CodexAgent;
     const screen = tmuxCapture(session);
     const state = agent.getState(screen);
-    const logPath = agent.findLogPath(session);
     const type = parsed.archangelName ? "archangel" : "-";
     const isDefault =
       (parsed.tool === "claude" && session === claudeDefault) ||
       (parsed.tool === "codex" && session === codexDefault);
 
+    // Get session metadata (Claude only)
+    const meta = getSessionMeta(session);
+
     return {
       session,
       tool: parsed.tool,
       state: state || "unknown",
       target: isDefault ? "*" : "",
       type,
-      log: logPath || "-",
+      plan: meta?.slug || "-",
+      branch: meta?.gitBranch || "-",
     };
   });
 
@@ -2530,13 +2643,14 @@ function cmdAgents() {
   const maxState = Math.max(5, ...agents.map((a) => a.state.length));
   const maxTarget = Math.max(6, ...agents.map((a) => a.target.length));
   const maxType = Math.max(4, ...agents.map((a) => a.type.length));
+  const maxPlan = Math.max(4, ...agents.map((a) => a.plan.length));
 
   console.log(
-    `${"SESSION".padEnd(maxSession)}  ${"TOOL".padEnd(maxTool)}  ${"STATE".padEnd(maxState)}  ${"TARGET".padEnd(maxTarget)}  ${"TYPE".padEnd(maxType)}  LOG`,
+    `${"SESSION".padEnd(maxSession)}  ${"TOOL".padEnd(maxTool)}  ${"STATE".padEnd(maxState)}  ${"TARGET".padEnd(maxTarget)}  ${"TYPE".padEnd(maxType)}  ${"PLAN".padEnd(maxPlan)}  BRANCH`,
   );
   for (const a of agents) {
     console.log(
-      `${a.session.padEnd(maxSession)}  ${a.tool.padEnd(maxTool)}  ${a.state.padEnd(maxState)}  ${a.target.padEnd(maxTarget)}  ${a.type.padEnd(maxType)}  ${a.log}`,
+      `${a.session.padEnd(maxSession)}  ${a.tool.padEnd(maxTool)}  ${a.state.padEnd(maxState)}  ${a.target.padEnd(maxTarget)}  ${a.type.padEnd(maxType)}  ${a.plan.padEnd(maxPlan)}  ${a.branch}`,
     );
   }
 
@@ -2685,6 +2799,13 @@ async function cmdArchangel(agentName) {
   let isProcessing = false;
   const intervalMs = config.interval * 1000;
 
+  // Hash tracking for incremental context updates
+  /** @type {string | null} */
+  let lastPlanHash = null;
+  /** @type {string | null} */
+  let lastTodosHash = null;
+  let isFirstTrigger = true;
+
   async function processChanges() {
     clearTimeout(debounceTimer);
     clearTimeout(maxWaitTimer);
@@ -2702,6 +2823,21 @@ async function cmdArchangel(agentName) {
       const parent = findParentSession();
       const logPath = parent ? findClaudeLogPath(parent.uuid, parent.session) : null;
 
+      // Get orientation context (plan and todos) from parent session
+      const meta = parent?.session ? getSessionMeta(parent.session) : null;
+      const planContent = meta?.slug ? readPlanFile(meta.slug) : null;
+      const todosContent = meta?.todos?.length ? formatTodos(meta.todos) : null;
+
+      // Check if plan/todos have changed since last trigger
+      const planHash = quickHash(planContent);
+      const todosHash = quickHash(todosContent);
+      const includePlan = planHash !== lastPlanHash;
+      const includeTodos = todosHash !== lastTodosHash;
+
+      // Update tracking for next trigger
+      lastPlanHash = planHash;
+      lastTodosHash = todosHash;
+
       // Build file-specific context from JSONL
       const fileContexts = [];
       for (const file of files.slice(0, 5)) {
@@ -2713,7 +2849,18 @@ async function cmdArchangel(agentName) {
       }
 
       // Build the prompt
-      let prompt = basePrompt;
+      // First trigger: include intro, guidelines, and focus (archangel has memory)
+      let prompt = isFirstTrigger
+        ? `You are the archangel of ${agentName}.\n\n${ARCHANGEL_PREAMBLE}\n\n## Focus\n\n${basePrompt}\n\n---`
+        : "";
+
+      // Add orientation context (plan and todos) only if changed since last trigger
+      if (includePlan && planContent) {
+        prompt += (prompt ? "\n\n" : "") + "## Current Plan\n\n" + planContent;
+      }
+      if (includeTodos && todosContent) {
+        prompt += (prompt ? "\n\n" : "") + "## Current Todos\n\n" + todosContent;
+      }
 
       if (fileContexts.length > 0) {
         prompt += "\n\n## Recent Edits (from parent session)\n";
@@ -2747,8 +2894,7 @@ async function cmdArchangel(agentName) {
           prompt += "\n\n## Git Context\n\n" + gitContext;
         }
 
-        prompt +=
-          '\n\nReview these changes in the context of what the user is working on. Report any issues found. Keep your response concise.\nIf there are no significant issues, respond with just "No issues found."';
+        prompt += "\n\nReview these changes.";
       } else {
         // Fallback: no JSONL context available, use conversation + git context
         const parentContext = getParentSessionContext(ARCHANGEL_PARENT_CONTEXT_ENTRIES);
@@ -2768,8 +2914,7 @@ async function cmdArchangel(agentName) {
           prompt += "\n\n## Git Context\n\n" + gitContext;
         }
 
-        prompt +=
-          '\n\nReview these changes in the context of what the user is working on. Report any issues found. Keep your response concise.\nIf there are no significant issues, respond with just "No issues found."';
+        prompt += "\n\nReview these changes.";
       }
 
       // Check session still exists
@@ -2798,6 +2943,7 @@ async function cmdArchangel(agentName) {
       await sleep(200); // Allow time for large prompts to be processed
       tmuxSend(sessionName, "Enter");
       await sleep(100); // Ensure Enter is processed
+      isFirstTrigger = false;
 
       // Wait for response
       const { state: endState, screen: afterScreen } = await waitForResponse(
@@ -4016,20 +4162,43 @@ async function cmdSelect(agent, session, n, { wait = false, timeoutMs } = {}) {
 // =============================================================================
 
 /**
- * @returns {Agent}
+ * Resolve the agent to use based on (in priority order):
+ * 1. Explicit --tool flag
+ * 2. Session name (e.g., "claude-archangel-..." → ClaudeAgent)
+ * 3. CLI invocation name (axclaude, axcodex)
+ * 4. AX_DEFAULT_TOOL environment variable
+ * 5. Default to CodexAgent
+ *
+ * @param {{toolFlag?: string, sessionName?: string | null}} options
+ * @returns {{agent: Agent, error?: string}}
  */
-function getAgentFromInvocation() {
+function resolveAgent({ toolFlag, sessionName } = {}) {
+  // 1. Explicit --tool flag takes highest priority
+  if (toolFlag) {
+    if (toolFlag === "claude") return { agent: ClaudeAgent };
+    if (toolFlag === "codex") return { agent: CodexAgent };
+    return { agent: CodexAgent, error: `unknown tool '${toolFlag}'` };
+  }
+
+  // 2. Infer from session name (e.g., "claude-archangel-..." or "codex-partner-...")
+  if (sessionName) {
+    const parsed = parseSessionName(sessionName);
+    if (parsed?.tool === "claude") return { agent: ClaudeAgent };
+    if (parsed?.tool === "codex") return { agent: CodexAgent };
+  }
+
+  // 3. CLI invocation name
   const invoked = path.basename(process.argv[1], ".js");
-  if (invoked === "axclaude" || invoked === "claude") return ClaudeAgent;
-  if (invoked === "axcodex" || invoked === "codex") return CodexAgent;
+  if (invoked === "axclaude" || invoked === "claude") return { agent: ClaudeAgent };
+  if (invoked === "axcodex" || invoked === "codex") return { agent: CodexAgent };
 
-  // Default based on AX_DEFAULT_TOOL env var, or codex if not set
+  // 4. AX_DEFAULT_TOOL environment variable
   const defaultTool = process.env.AX_DEFAULT_TOOL;
-  if (defaultTool === "claude") return ClaudeAgent;
-  if (defaultTool === "codex" || !defaultTool) return CodexAgent;
+  if (defaultTool === "claude") return { agent: ClaudeAgent };
+  if (defaultTool === "codex" || !defaultTool) return { agent: CodexAgent };
 
   console.error(`WARNING: invalid AX_DEFAULT_TOOL="${defaultTool}", using codex`);
-  return CodexAgent;
+  return { agent: CodexAgent };
 }
 
 /**
@@ -4133,19 +4302,8 @@ async function main() {
   // Extract flags into local variables for convenience
   const { wait, noWait, yolo, fresh, reasoning, follow, all, orphans, force } = flags;
 
-  // Agent selection
-  let agent = getAgentFromInvocation();
-  if (flags.tool) {
-    if (flags.tool === "claude") agent = ClaudeAgent;
-    else if (flags.tool === "codex") agent = CodexAgent;
-    else {
-      console.log(`ERROR: unknown tool '${flags.tool}'`);
-      process.exit(1);
-    }
-  }
-
-  // Session resolution
-  let session = agent.getDefaultSession();
+  // Session resolution (must happen before agent resolution so we can infer tool from session name)
+  let session = null;
   if (flags.session) {
     if (flags.session === "self") {
       const current = tmuxCurrentSession();
@@ -4160,6 +4318,18 @@ async function main() {
     }
   }
 
+  // Agent resolution (considers --tool flag, session name, invocation, and env vars)
+  const { agent, error: agentError } = resolveAgent({ toolFlag: flags.tool, sessionName: session });
+  if (agentError) {
+    console.log(`ERROR: ${agentError}`);
+    process.exit(1);
+  }
+
+  // If no explicit session, use agent's default
+  if (!session) {
+    session = agent.getDefaultSession();
+  }
+
   // Timeout (convert seconds to milliseconds)
   let timeoutMs = DEFAULT_TIMEOUT_MS;
   if (flags.timeout !== undefined) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ax-agents",
-  "version": "0.0.1-alpha.7",
+  "version": "0.0.1-alpha.9",
   "description": "A CLI for orchestrating AI coding agents via tmux",
   "bin": {
     "ax": "ax.js",