ax-agents 0.0.1-alpha.10 → 0.0.1-alpha.12

package/ax.js

@@ -75,6 +75,10 @@ const VERSION = packageJson.version;
  * @property {string[]} files
  * @property {string} [summary]
  * @property {string} [message]
+ * @property {string} [rfpId]
+ * @property {string} [prompt]
+ * @property {string} [archangel]
+ * @property {string} [requestedBy]
  */
 
 /**
@@ -158,6 +162,7 @@ const PROJECT_ROOT = findProjectRoot();
 const AI_DIR = path.join(PROJECT_ROOT, ".ai");
 const AGENTS_DIR = path.join(AI_DIR, "agents");
 const HOOKS_DIR = path.join(AI_DIR, "hooks");
+const RFP_DIR = path.join(AI_DIR, "rfps");
 
 // =============================================================================
 // Helpers - tmux
@@ -316,6 +321,22 @@ const ARCHANGEL_PREAMBLE = `## Guidelines
 - 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.`;
+const RFP_PREAMBLE = `## Guidelines
+
+- Your only task is to propose a single idea in response to this RFP. This overrides any other goals or habits.
+- Provide exactly one proposal.
+- Make a persuasive case for why this is a strong idea.
+- Think deeply before you answer; avoid first-impression responses.
+- Aim for 3–4 clear paragraphs.
+- Ground the idea in the actual context you were given; don’t ignore it.
+- If you need context, read the existing project or conversation before proposing.
+- Structure: (1) core insight/value, (2) who benefits & why now, (3) risks/tradeoffs (brief), (4) closing case.
+- Focus on value: what improves, for whom, and why now.
+- Do NOT review code or report bugs.
+- Do NOT describe scope, implementation approach, or plan.
+- You may briefly note tradeoffs, but they are not the focus.
+- Prioritize clarity over brevity.
+- If you have nothing to propose, respond with ONLY "EMPTY_RESPONSE".`;
 
 /**
  * @param {string} session
@@ -378,7 +399,9 @@ function findCallerPid() {
  * @returns {{pid: string, command: string}[]}
  */
 function findOrphanedProcesses() {
-  const result = spawnSync("ps", ["-eo", "pid=,ppid=,args="], { encoding: "utf-8" });
+  const result = spawnSync("ps", ["-eo", "pid=,ppid=,args="], {
+    encoding: "utf-8",
+  });
 
   if (result.status !== 0 || !result.stdout.trim()) {
     return [];
@@ -432,6 +455,17 @@ async function readStdin() {
   });
 }
 
+/**
+ * @param {string | null | undefined} value
+ * @returns {Promise<string | undefined>}
+ */
+async function readStdinIfNeeded(value) {
+  if (value && value !== "-") return value;
+  if (!hasStdinData()) return undefined;
+  const stdinText = await readStdin();
+  return stdinText || undefined;
+}
+
 // =============================================================================
 // =============================================================================
 // Helpers - CLI argument parsing
@@ -460,6 +494,7 @@ async function readStdin() {
  * @property {number} [tail]
  * @property {number} [limit]
  * @property {string} [branch]
+ * @property {string} [archangels]
  */
 function parseCliArgs(args) {
   const { values, positionals } = parseArgs({
@@ -484,6 +519,7 @@ function parseCliArgs(args) {
       tail: { type: "string" },
       limit: { type: "string" },
       branch: { type: "string" },
+      archangels: { type: "string" },
     },
     allowPositionals: true,
     strict: false, // Don't error on unknown flags
@@ -508,6 +544,7 @@ function parseCliArgs(args) {
       tail: values.tail !== undefined ? Number(values.tail) : undefined,
       limit: values.limit !== undefined ? Number(values.limit) : undefined,
       branch: /** @type {string | undefined} */ (values.branch),
+      archangels: /** @type {string | undefined} */ (values.archangels),
     },
     positionals,
   };
@@ -1150,6 +1187,54 @@ function getArchangelSessionPattern(config) {
   return `${config.tool}-archangel-${config.name}`;
 }
 
+/**
+ * @param {string} rfpId
+ * @param {string} prompt
+ */
+function writeRfpRecord(rfpId, prompt) {
+  ensureRfpDir();
+  const p = path.join(RFP_DIR, `${rfpId}.md`);
+  const block = [`### ${rfpId}`, "", prompt.trim(), ""].join("\n");
+  writeFileSync(p, block, "utf-8");
+}
+
+/**
+ * @param {string} input
+ * @returns {string}
+ */
+function resolveRfpId(input) {
+  ensureRfpDir();
+  if (!existsSync(RFP_DIR)) return input;
+  const files = readdirSync(RFP_DIR).filter((f) => f.endsWith(".md"));
+  const ids = files.map((f) => f.replace(/\.md$/, ""));
+  const matches = ids.filter((id) => id.startsWith(input));
+  if (matches.length === 1) return matches[0];
+  if (matches.length > 1) {
+    console.log("ERROR: ambiguous rfp id. Matches:");
+    for (const m of matches) console.log(`  ${m}`);
+    process.exit(1);
+  }
+  return input;
+}
+
+/**
+ * @param {ParentSession | null} parent
+ * @returns {string}
+ */
+function generateRfpId(parent) {
+  const now = new Date();
+  const y = now.getFullYear();
+  const mo = String(now.getMonth() + 1).padStart(2, "0");
+  const d = String(now.getDate()).padStart(2, "0");
+  const h = String(now.getHours()).padStart(2, "0");
+  const mi = String(now.getMinutes()).padStart(2, "0");
+  const s = String(now.getSeconds()).padStart(2, "0");
+  const ts = `${y}-${mo}-${d}-${h}-${mi}-${s}`;
+  const base = parent?.uuid ? parent.uuid.split("-")[0] : randomUUID().split("-")[0];
+  const suffix = randomUUID().split("-")[0].slice(0, 4);
+  return `rfp-${base}-${ts}-${suffix}`.toLowerCase();
+}
+
 // =============================================================================
 // Helpers - mailbox
 // =============================================================================
@@ -1166,15 +1251,25 @@ function ensureMailboxDir() {
   }
 }
 
+/**
+ * @returns {void}
+ */
+function ensureRfpDir() {
+  if (!existsSync(RFP_DIR)) {
+    mkdirSync(RFP_DIR, { recursive: true });
+  }
+}
+
 /**
  * @param {MailboxPayload} payload
+ * @param {string} [type]
  * @returns {void}
  */
-function writeToMailbox(payload) {
+function writeToMailbox(payload, type = "observation") {
   ensureMailboxDir();
   const entry = {
     timestamp: new Date().toISOString(),
-    type: "observation",
+    type,
     payload,
   };
   appendFileSync(MAILBOX_PATH, JSON.stringify(entry) + "\n");
@@ -2703,11 +2798,29 @@ function startArchangel(config, parentSession = null) {
     env,
   });
   child.unref();
+  const watchingLabel = parentSession
+    ? parentSession.session || parentSession.uuid?.slice(0, 8)
+    : null;
   console.log(
-    `Summoning: ${config.name} (pid ${child.pid})${parentSession ? ` [parent: ${parentSession.session}]` : ""}`,
+    `Summoning: ${config.name} (pid ${child.pid})${watchingLabel ? ` [watching: ${watchingLabel}]` : ""}`,
   );
 }
 
+/**
+ * @param {string} pattern
+ * @param {number} [timeoutMs]
+ * @returns {Promise<string | undefined>}
+ */
+async function waitForArchangelSession(pattern, timeoutMs = ARCHANGEL_STARTUP_TIMEOUT_MS) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const session = findArchangelSession(pattern);
+    if (session) return session;
+    await sleep(200);
+  }
+  return undefined;
+}
+
 // =============================================================================
 // Command: archangel (runs as the archangel process itself)
 // =============================================================================
@@ -3710,7 +3823,13 @@ function cmdMailbox({ limit = 20, branch = null, all = false } = {}) {
       console.log(`**Branch**: ${p.branch || "?"} @ ${p.commit || "?"}\n`);
     }
 
-    if (p.message) {
+    if (p.rfpId) {
+      console.log(`**RFP**: ${p.rfpId}\n`);
+    }
+
+    if (entry.type === "proposal") {
+      console.log(`**Proposal**: ${p.message || ""}\n`);
+    } else if (p.message) {
       console.log(`**Assistant**: ${p.message}\n`);
     }
 
@@ -3724,13 +3843,229 @@ function cmdMailbox({ limit = 20, branch = null, all = false } = {}) {
   }
 }
 
+/**
+ * @param {string} rfpId
+ * @param {string} archangel
+ * @returns {string | null}
+ */
+function getProposalFromMailbox(rfpId, archangel) {
+  if (!existsSync(MAILBOX_PATH)) return null;
+  let result = null;
+  try {
+    const lines = readFileSync(MAILBOX_PATH, "utf-8").trim().split("\n").filter(Boolean);
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        if (entry?.type !== "proposal") continue;
+        const p = entry.payload || {};
+        if (p.rfpId === rfpId && p.archangel === archangel) {
+          result = p.message || "";
+        }
+      } catch {
+        // Skip malformed lines
+      }
+    }
+  } catch (err) {
+    debugError("getProposalFromMailbox", err);
+  }
+  return result;
+}
+
+/**
+ * @param {string} prompt
+ * @param {{archangels?: string, fresh?: boolean, noWait?: boolean}} [options]
+ */
+async function cmdRfp(prompt, { archangels, fresh = false, noWait = false } = {}) {
+  const configs = loadAgentConfigs();
+  if (configs.length === 0) {
+    console.log(`No archangels found in ${AGENTS_DIR}/`);
+    process.exit(1);
+  }
+
+  const requested = archangels
+    ? archangels
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : configs.map((c) => c.name);
+
+  if (requested.length === 0) {
+    console.log("ERROR: no archangels specified");
+    process.exit(1);
+  }
+
+  const missing = requested.filter((name) => !configs.some((c) => c.name === name));
+  if (missing.length > 0) {
+    console.log(`ERROR: unknown archangel(s): ${missing.join(", ")}`);
+    process.exit(1);
+  }
+
+  const parent = findParentSession();
+  const rfpId = generateRfpId(parent);
+
+  for (const name of requested) {
+    const config = configs.find((c) => c.name === name);
+    if (!config) continue;
+
+    const pattern = getArchangelSessionPattern(config);
+    let session = findArchangelSession(pattern);
+    if (!session) {
+      startArchangel(config, parent);
+      session = await waitForArchangelSession(pattern);
+    }
+
+    if (!session) {
+      console.log(`ERROR: failed to start archangel '${name}'`);
+      continue;
+    }
+
+    const { agent } = resolveAgent({ sessionName: session });
+
+    if (fresh) {
+      tmuxSendLiteral(session, "/new");
+      await sleep(50);
+      tmuxSend(session, "Enter");
+    }
+
+    const ready = await waitUntilReady(agent, session, ARCHANGEL_STARTUP_TIMEOUT_MS);
+    if (ready.state !== State.READY) {
+      console.log(`[rfp] ${name} not ready (${ready.state}), skipping`);
+      continue;
+    }
+
+    const rfpPrompt = `## RFP ${rfpId}\n\n${RFP_PREAMBLE}\n\n${prompt}\n\nReturn exactly one proposal.`;
+    tmuxSendLiteral(session, rfpPrompt);
+    await sleep(200);
+    tmuxSend(session, "Enter");
+  }
+
+  writeRfpRecord(rfpId, prompt);
+  const archangelList = requested.join(",");
+  console.log(`rfp: ${rfpId} (${archangelList})`);
+  if (noWait) {
+    const cli = path.basename(process.argv[1], ".js");
+    const base = rfpId.split("-")[1];
+    const shortId = `rfp-${base}`;
+    console.log(`e.g.\n  ${cli} rfp wait ${shortId} --archangels=${archangelList}`);
+  }
+}
+
+/**
+ * @param {string} rfpId
+ * @param {{archangels?: string, timeoutMs?: number}} [options]
+ */
+async function cmdRfpWait(rfpId, { archangels, timeoutMs = ARCHANGEL_RESPONSE_TIMEOUT_MS } = {}) {
+  const resolvedRfpId = resolveRfpId(rfpId);
+  const configs = loadAgentConfigs();
+  if (configs.length === 0) {
+    console.log(`No archangels found in ${AGENTS_DIR}/`);
+    process.exit(1);
+  }
+
+  const requested = archangels
+    ? archangels
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : configs.map((c) => c.name);
+
+  if (requested.length === 0) {
+    console.log("ERROR: no archangels specified");
+    process.exit(1);
+  }
+
+  const missing = requested.filter((name) => !configs.some((c) => c.name === name));
+  if (missing.length > 0) {
+    console.log(`ERROR: unknown archangel(s): ${missing.join(", ")}`);
+    process.exit(1);
+  }
+
+  let wroteAny = false;
+  let printedAny = false;
+
+  for (const name of requested) {
+    const config = configs.find((c) => c.name === name);
+    if (!config) continue;
+
+    const pattern = getArchangelSessionPattern(config);
+    const session = findArchangelSession(pattern);
+    if (!session) {
+      console.log(`[rfp] ${name} session not found, skipping`);
+      continue;
+    }
+
+    const existing = getProposalFromMailbox(resolvedRfpId, name);
+    if (existing !== null) {
+      if (printedAny) console.log("");
+      console.log(`[${name}]`);
+      console.log(existing);
+      wroteAny = true;
+      printedAny = true;
+      continue;
+    }
+
+    const { agent } = resolveAgent({ sessionName: session });
+    let result;
+    try {
+      result = await waitUntilReady(agent, session, timeoutMs);
+    } catch (err) {
+      if (err instanceof TimeoutError) {
+        console.log(`[rfp] ${name} timed out`);
+      } else {
+        console.log(`[rfp] ${name} error: ${err instanceof Error ? err.message : err}`);
+      }
+      continue;
+    }
+
+    if (result.state === State.RATE_LIMITED) {
+      console.log(`[rfp] ${name} rate limited`);
+      continue;
+    }
+    if (result.state === State.CONFIRMING) {
+      console.log(`[rfp] ${name} awaiting confirmation`);
+      continue;
+    }
+
+    const response = agent.getResponse(session, result.screen) || "";
+    if (!response || response.trim() === "EMPTY_RESPONSE") {
+      continue;
+    }
+
+    writeToMailbox(
+      {
+        agent: name,
+        session,
+        branch: getCurrentBranch(),
+        commit: getCurrentCommit(),
+        files: [],
+        message: response,
+        rfpId: resolvedRfpId,
+        archangel: name,
+      },
+      "proposal",
+    );
+    if (printedAny) console.log("");
+    console.log(`[${name}]`);
+    console.log(response);
+    wroteAny = true;
+    printedAny = true;
+  }
+
+  if (!wroteAny) process.exit(1);
+}
+
 /**
  * @param {Agent} agent
  * @param {string | null | undefined} session
  * @param {string} message
  * @param {{noWait?: boolean, yolo?: boolean, timeoutMs?: number}} [options]
  */
-async function cmdAsk(agent, session, message, { noWait = false, yolo = false, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+async function cmdAsk(
+  agent,
+  session,
+  message,
+  { noWait = false, yolo = false, timeoutMs = DEFAULT_TIMEOUT_MS } = {},
+) {
   const sessionExists = session != null && tmuxHasSession(session);
   const nativeYolo = sessionExists && isYoloSession(/** @type {string} */ (session));
 
@@ -4194,72 +4529,62 @@ function resolveAgent({ toolFlag, sessionName } = {}) {
 function printHelp(agent, cliName) {
   const name = cliName;
   const backendName = agent.displayName;
-  const hasReview = !!agent.reviewOptions;
 
   console.log(`${name} v${VERSION} - agentic assistant CLI (${backendName})
 
 Usage: ${name} [OPTIONS] <command|message> [ARGS...]
 
-Commands:
-  agents                    List all running agents with state and log paths
+Messaging/State:
+  <message>                 Send message to ${name}
+  review [TYPE]             Review code: pr, uncommitted, commit, custom
+  status                    Exit code: ready=0 rate_limit=2 confirm=3 thinking=4
+  output [-N]               Show response (0=last, -1=prev, -2=older)
+  compact                   Summarise session to shrink context size
+  reset                     Start fresh conversation
+
+Sessions:
+  agents                    List all running agents
   target                    Show default target session for current tool
   attach [SESSION]          Attach to agent session interactively
-  log SESSION               View conversation log (--tail=N, --follow, --reasoning)
-  mailbox                   View archangel observations (--limit=N, --branch=X, --all)
+  kill                      Kill sessions (--all, --session=NAME, --orphans [--force])
+
+Archangels:
   summon [name]             Summon archangels (all, or by name)
   recall [name]             Recall archangels (all, or by name)
-  kill                      Kill sessions (--all, --session=NAME, --orphans [--force])
-  status                    Check state (exit: 0=ready, 2=rate_limited, 3=confirming, 4=thinking)
-  output [-N]               Show response (0=last, -1=prev, -2=older)
-  debug                     Show raw screen output and detected state${
-    hasReview
-      ? `
-  review [TYPE]             Review code: pr, uncommitted, commit, custom`
-      : ""
-  }
-  select N                  Select menu option N
+  mailbox                   Archangel notes (filters: --branch=git, --all)
+  rfp <prompt>              Request proposals (--archangels=a,b)
+  rfp wait <id>             Wait for proposals (--archangels=a,b)
+
+Recovery:
+  debug                     Show raw screen output and detected state
   approve                   Approve pending action (send 'y')
   reject                    Reject pending action (send 'n')
+  select N                  Select menu option N
   send KEYS                 Send key sequence (e.g. "1[Enter]", "[Escape]")
-  compact                   Summarize conversation (when context is full)
-  reset                     Start fresh conversation
-  <message>                 Send message to ${name}
+  log SESSION               View conversation log (--tail=N, --follow, --reasoning)
 
 Flags:
   --tool=NAME               Use specific agent (codex, claude)
-  --session=NAME            Target session by name, archangel name, or UUID prefix (self = current)
+  --session=ID              name | archangel | uuid-prefix | self
+  --fresh                   Reset conversation before review
+  --yolo                    Skip all confirmations (dangerous)
   --wait                    Wait for response (default for messages; required for approve/reject)
   --no-wait                 Fire-and-forget: send message, print session ID, exit immediately
   --timeout=N               Set timeout in seconds (default: ${DEFAULT_TIMEOUT_MS / 1000}, reviews: ${REVIEW_TIMEOUT_MS / 1000})
-  --yolo                    Skip all confirmations (dangerous)
-  --fresh                   Reset conversation before review
-  --orphans                 Kill orphaned claude/codex processes (PPID=1)
-  --force                   Use SIGKILL instead of SIGTERM (with --orphans)
-
-Environment:
-  AX_DEFAULT_TOOL           Default agent when using 'ax' (claude or codex, default: codex)
-  ${agent.envVar}           Override default session name
-  AX_CLAUDE_CONFIG_DIR      Override Claude config directory (default: ~/.claude)
-  AX_CODEX_CONFIG_DIR       Override Codex config directory (default: ~/.codex)
-  AX_REVIEW_MODE=exec       Bypass /review, send instructions directly (codex only)
-  AX_DEBUG=1                Enable debug logging
 
 Examples:
   ${name} "explain this codebase"
   ${name} "review the error handling"           # Auto custom review (${REVIEW_TIMEOUT_MS / 60000}min timeout)
   ${name} "FYI: auth was refactored" --no-wait  # Send context to a working session (no response needed)
   ${name} review uncommitted --wait
-  ${name} approve --wait
-  ${name} kill                                 # Kill agents in current project
-  ${name} kill --all                           # Kill all agents across all projects
-  ${name} kill --session=NAME                  # Kill specific session
-  ${name} send "1[Enter]"                      # Recovery: select option 1 and press Enter
-  ${name} send "[Escape][Escape]"              # Recovery: escape out of a dialog
-  ${name} summon                               # Summon all archangels from .ai/agents/*.md
-  ${name} summon reviewer                      # Summon by name (creates config if new)
-  ${name} recall                               # Recall all archangels
-  ${name} recall reviewer                      # Recall one by name
-  ${name} agents                               # List all agents (shows TYPE=archangel)
+  ${name} kill                                  # Kill agents in current project
+  ${name} kill --all                            # Kill all agents across all projects
+  ${name} kill --session=NAME                   # Kill specific session
+  ${name} summon                                # Summon all archangels from .ai/agents/*.md
+  ${name} summon reviewer                       # Summon by name (creates config if new)
+  ${name} recall                                # Recall all archangels
+  ${name} recall reviewer                       # Recall one by name
+  ${name} agents                                # List all agents (shows TYPE=archangel)
 
 Note: Reviews and complex tasks may take several minutes.
       Use Bash run_in_background for long operations (not --no-wait).`);
@@ -4305,7 +4630,10 @@ async function main() {
   }
 
   // Agent resolution (considers --tool flag, session name, invocation, and env vars)
-  const { agent, error: agentError } = resolveAgent({ toolFlag: flags.tool, sessionName: session });
+  const { agent, error: agentError } = resolveAgent({
+    toolFlag: flags.tool,
+    sessionName: session,
+  });
   if (agentError) {
     console.log(`ERROR: ${agentError}`);
     process.exit(1);
@@ -4357,14 +4685,33 @@ async function main() {
   if (cmd === "attach") return cmdAttach(positionals[1] || session);
   if (cmd === "log") return cmdLog(positionals[1] || session, { tail, reasoning, follow });
   if (cmd === "mailbox") return cmdMailbox({ limit, branch, all });
+  if (cmd === "rfp") {
+    if (positionals[1] === "wait") {
+      const rfpId = positionals[2];
+      if (!rfpId) {
+        console.log("ERROR: missing rfp id");
+        process.exit(1);
+      }
+      return cmdRfpWait(rfpId, { archangels: flags.archangels, timeoutMs });
+    }
+    const rawPrompt = positionals.slice(1).join(" ");
+    const prompt = await readStdinIfNeeded(rawPrompt);
+    if (!prompt) {
+      console.log("ERROR: missing prompt for rfp");
+      process.exit(1);
+    }
+    return cmdRfp(prompt, { archangels: flags.archangels, fresh, noWait });
+  }
   if (cmd === "approve") return cmdApprove(agent, session, { wait, timeoutMs });
   if (cmd === "reject") return cmdReject(agent, session, { wait, timeoutMs });
-  if (cmd === "review")
-    return cmdReview(agent, session, positionals[1], positionals[2], {
+  if (cmd === "review") {
+    const customInstructions = await readStdinIfNeeded(positionals[2]);
+    return cmdReview(agent, session, positionals[1], customInstructions ?? undefined, {
       wait,
       fresh,
       timeoutMs,
     });
+  }
   if (cmd === "status") return cmdStatus(agent, session);
   if (cmd === "debug") return cmdDebug(agent, session);
   if (cmd === "output") {
@@ -4380,18 +4727,17 @@ async function main() {
     return cmdSelect(agent, session, positionals[1], { wait, timeoutMs });
 
   // Default: send message
-  let message = positionals.join(" ");
-  if (!message && hasStdinData()) {
-    message = await readStdin();
-  }
+  const rawMessage = positionals.join(" ");
+  let message = await readStdinIfNeeded(rawMessage);
 
   if (!message || flags.help) {
     printHelp(agent, cliName);
     process.exit(0);
   }
+  const messageText = message;
 
   // Detect "review ..." or "please review ..." and route to custom review mode
-  const reviewMatch = message.match(/^(?:please )?review\s*(.*)/i);
+  const reviewMatch = messageText.match(/^(?:please )?review\s*(.*)/i);
   if (reviewMatch && agent.reviewOptions) {
     const customInstructions = reviewMatch[1].trim() || null;
     return cmdReview(agent, session, "custom", customInstructions, {
@@ -4401,7 +4747,7 @@ async function main() {
     });
   }
 
-  return cmdAsk(agent, session, message, { noWait, yolo, timeoutMs });
+  return cmdAsk(agent, session, messageText, { noWait, yolo, timeoutMs });
 }
 
 // Run main() only when executed directly (not when imported for testing)

package/package.json

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