tau-coding-agent 0.1.4 → 0.1.5

package/extensions/review/index.ts

@@ -0,0 +1,232 @@
+/**
+ * Unified /review + /triage + /fix extension.
+ *
+ * What this extension does:
+ * - /review runs up to 6 parallel focuses (general, security, reuse, quality, testing, efficiency),
+ *   then emits a single findings report.
+ * - /triage fetches PR feedback from GitHub, inspects the checked-out PR diff,
+ *   and classifies each item as address, push_back, research, or ignore.
+ * - /fix applies findings from the review report. It reuses the last message only
+ *   when that message is a matching review payload, even if stale. Otherwise it
+ *   runs a fresh review first. If that fresh review becomes stale while running,
+ *   /fix shows the findings and waits for an explicit rerun before applying fixes.
+ *   context=... guides the fix pass without invalidating reusable review payloads.
+ *   /fix loop repeats review + fix until the review produces no findings.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+import { prepareFixReviewDetails, runFixLoop, runFixPassFromReview } from "./fix.js";
+import { createReviewMessageQueue, type ReviewMessageQueue } from "./message-queue.js";
+import {
+  getFixArgumentCompletions,
+  getReviewArgumentCompletions,
+  parseCommandRequest,
+  parseFixCommandRequest,
+  parseTriagePrRef,
+  showReviewHelp,
+  type ParseFailure,
+} from "./request.js";
+import { runReviewPipeline } from "./review.js";
+import {
+  acquireReviewRunLock,
+  createAgentRunTracker,
+  handleReviewSessionShutdown,
+  handleReviewSessionStart,
+  notify,
+  recordPromptEnd,
+  recordPromptStart,
+  releaseReviewRunLock,
+  type AgentEndMessages,
+} from "./runtime.js";
+import { runTriagePipeline } from "./triage.js";
+
+function handleParseFailure(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  result: ParseFailure,
+): void {
+  if (result.help) {
+    showReviewHelp(pi);
+    return;
+  }
+  if (result.error) {
+    notify(ctx, result.error, "error");
+  }
+}
+
+function stopAndFlushReviewQueue(
+  ctx: ExtensionCommandContext,
+  reviewMessageQueue: ReviewMessageQueue,
+  stopReviewQueue: () => void,
+): void {
+  stopReviewQueue();
+  reviewMessageQueue.flushAll(ctx, { forceFollowUp: true });
+}
+
+type BackgroundRunResult = { ok: true } | { ok: false; error: string };
+
+function startQueuedBackgroundRun(
+  ctx: ExtensionCommandContext,
+  reviewMessageQueue: ReviewMessageQueue,
+  options: {
+    busyMessage: string;
+    startMessage: string;
+    failurePrefix: string;
+    run: () => Promise<BackgroundRunResult>;
+  },
+): void {
+  const sessionKey = acquireReviewRunLock(ctx, options.busyMessage);
+  if (!sessionKey) return;
+
+  const stopReviewQueue = reviewMessageQueue.start(ctx);
+  notify(ctx, options.startMessage, "info");
+  void (async () => {
+    try {
+      const result = await options.run();
+      if (!result.ok) {
+        notify(ctx, result.error, "error");
+      }
+    } catch (error) {
+      notify(
+        ctx,
+        `${options.failurePrefix}: ${error instanceof Error ? error.message : String(error)}`,
+        "error",
+      );
+    } finally {
+      releaseReviewRunLock(sessionKey);
+      stopAndFlushReviewQueue(ctx, reviewMessageQueue, stopReviewQueue);
+    }
+  })();
+}
+
+export default function reviewExtension(pi: ExtensionAPI) {
+  const reviewMessageQueue = createReviewMessageQueue(pi);
+  const agentTracker = createAgentRunTracker();
+
+  pi.events.on("ui:prompt_start", () => {
+    recordPromptStart();
+  });
+
+  pi.events.on("ui:prompt_end", () => {
+    recordPromptEnd();
+  });
+
+  pi.on("input", async (event, ctx) => {
+    if (!reviewMessageQueue.handleInput(event, ctx)) return { action: "continue" };
+    return { action: "handled" };
+  });
+
+  pi.on("agent_start", async () => {
+    agentTracker.handleStart();
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    handleReviewSessionStart(ctx);
+    agentTracker.reset();
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    handleReviewSessionShutdown(ctx);
+    reviewMessageQueue.clear(ctx);
+    agentTracker.reset();
+  });
+
+  pi.on("agent_end", async (event) => {
+    agentTracker.handleEnd({
+      messages: event.messages as AgentEndMessages,
+    });
+  });
+
+  pi.on("agent_settled", async () => {
+    agentTracker.handleSettled();
+  });
+
+  pi.registerCommand("review", {
+    description:
+      "Run findings-only review across up to 6 focuses (general/security/reuse/quality/testing/efficiency). Use /review help for full usage.",
+    getArgumentCompletions: getReviewArgumentCompletions,
+    handler: async (args, ctx) => {
+      const parsed = parseCommandRequest(args);
+      if (!parsed.ok) {
+        handleParseFailure(pi, ctx, parsed);
+        return;
+      }
+
+      startQueuedBackgroundRun(ctx, reviewMessageQueue, {
+        busyMessage: "A /review run is already active in this session.",
+        startMessage: "Starting review in background...",
+        failurePrefix: "Review run failed",
+        run: () => runReviewPipeline(pi, ctx, parsed.value, "review"),
+      });
+    },
+  });
+
+  pi.registerCommand("triage", {
+    description:
+      "Fetch PR feedback from GitHub, inspect the checked-out PR diff, and classify each item as address, push_back, research, or ignore.",
+    handler: async (args, ctx) => {
+      const parsed = parseTriagePrRef(args);
+      if (!parsed.ok) {
+        handleParseFailure(pi, ctx, parsed);
+        return;
+      }
+
+      startQueuedBackgroundRun(ctx, reviewMessageQueue, {
+        busyMessage:
+          "A review-related run is already active in this session. Wait for it to finish before /triage.",
+        startMessage: "Starting PR triage in background...",
+        failurePrefix: "PR triage failed",
+        run: () => runTriagePipeline(pi, ctx, parsed.value),
+      });
+    },
+  });
+
+  pi.registerCommand("fix", {
+    description:
+      "Fix findings when the last message is a matching /review result. Otherwise, runs review first. Use /fix loop to repeat review + fix until clean. context=... guides the fix pass without forcing a fresh review. If the last review is stale, /fix warns and continues; if a /fix-started review goes stale mid-run, /fix shows the findings and applies no fixes. Use /review help for modes/options.",
+    getArgumentCompletions: getFixArgumentCompletions,
+    handler: async (args, ctx) => {
+      const parsed = parseFixCommandRequest(args);
+      if (!parsed.ok) {
+        handleParseFailure(pi, ctx, parsed);
+        return;
+      }
+
+      const { loop, request } = parsed.value;
+      if (loop && (!ctx.isIdle() || ctx.hasPendingMessages())) {
+        notify(ctx, "Wait for the agent to become idle before starting /fix loop.", "warning");
+        return;
+      }
+
+      const sessionKey = acquireReviewRunLock(
+        ctx,
+        "A /review run is active in this session. Wait for it to finish before /fix.",
+      );
+      if (!sessionKey) return;
+
+      const stopReviewQueue = reviewMessageQueue.start(ctx);
+      try {
+        if (loop) {
+          notify(ctx, "Starting fix loop...", "info");
+          await runFixLoop(pi, ctx, request, agentTracker, reviewMessageQueue);
+          return;
+        }
+
+        const reviewDetails = await prepareFixReviewDetails(pi, ctx, request);
+        if (!reviewDetails) return;
+        await runFixPassFromReview(
+          pi,
+          ctx,
+          reviewDetails,
+          request.additionalContext,
+          agentTracker,
+          reviewMessageQueue,
+        );
+      } finally {
+        releaseReviewRunLock(sessionKey);
+        stopAndFlushReviewQueue(ctx, reviewMessageQueue, stopReviewQueue);
+      }
+    },
+  });
+}

package/extensions/review/message-queue.ts

@@ -0,0 +1,249 @@
+import {
+  keyText,
+  type ExtensionAPI,
+  type ExtensionContext,
+  type InputEvent,
+} from "@earendil-works/pi-coding-agent";
+import { getKeybindings } from "@earendil-works/pi-tui";
+
+import { getReviewSessionKey } from "./runtime.js";
+
+const WIDGET_KEY = "review-message-queue";
+const PREVIEW_MAX_LENGTH = 180;
+
+type QueueMode = "steer" | "followUp";
+type FlushOptions = { forceFollowUp?: boolean };
+type QueuedReviewMessage = {
+  mode: QueueMode;
+  text: string;
+  images?: NonNullable<InputEvent["images"]>;
+};
+type QueueState = {
+  active: boolean;
+  messages: QueuedReviewMessage[];
+  unsubscribeFollowUpShortcut?: () => void;
+};
+
+export type ReviewMessageQueue = ReturnType<typeof createReviewMessageQueue>;
+
+export function createReviewMessageQueue(pi: ExtensionAPI) {
+  const states = new Map<string, QueueState>();
+
+  function start(ctx: ExtensionContext): () => void {
+    const sessionKey = getReviewSessionKey(ctx);
+    const state = getState(sessionKey);
+    state.active = true;
+
+    if (ctx.hasUI && !state.unsubscribeFollowUpShortcut) {
+      state.unsubscribeFollowUpShortcut = ctx.ui.onTerminalInput((data) => {
+        if (!isActive(sessionKey)) return undefined;
+
+        if (matchesConfiguredKey(data, "app.message.dequeue")) {
+          return restoreMessagesToEditor(ctx) ? { consume: true } : undefined;
+        }
+
+        if (!matchesConfiguredKey(data, "app.message.followUp")) return undefined;
+
+        const text = ctx.ui.getEditorText().trim();
+        if (!text) return { consume: true };
+        if (isImmediateCommand(text)) return undefined;
+
+        queueMessage(ctx, "followUp", { text });
+        ctx.ui.setEditorText("");
+        return { consume: true };
+      });
+    }
+
+    render(ctx);
+
+    let stopped = false;
+    return () => {
+      if (stopped) return;
+      stopped = true;
+      stop(ctx);
+    };
+  }
+
+  function handleInput(event: InputEvent, ctx: ExtensionContext): boolean {
+    const sessionKey = getReviewSessionKey(ctx);
+    if (!isActive(sessionKey)) return false;
+    if (event.source === "extension") return false;
+
+    // When the main agent is already streaming, Pi's built-in steering/follow-up
+    // queues are available. Only provide the review-owned queue while review work
+    // is running in the background and the main session is idle.
+    if (event.streamingBehavior) return false;
+    if (!ctx.isIdle()) return false;
+    if (isImmediateCommand(event.text)) return false;
+    if (!event.text.trim() && !event.images?.length) return false;
+
+    queueMessage(ctx, "steer", {
+      text: event.text,
+      images: event.images?.length ? [...event.images] : undefined,
+    });
+    return true;
+  }
+
+  function flushSteering(ctx: ExtensionContext, options: FlushOptions = {}): boolean {
+    return flush(ctx, (message) => message.mode === "steer", options);
+  }
+
+  function flushAll(ctx: ExtensionContext, options: FlushOptions = {}): boolean {
+    return flush(ctx, () => true, options);
+  }
+
+  function clear(ctx: ExtensionContext): void {
+    const sessionKey = getReviewSessionKey(ctx);
+    const state = states.get(sessionKey);
+    state?.unsubscribeFollowUpShortcut?.();
+    states.delete(sessionKey);
+    if (ctx.hasUI) ctx.ui.setWidget(WIDGET_KEY, undefined);
+  }
+
+  function stop(ctx: ExtensionContext): void {
+    const sessionKey = getReviewSessionKey(ctx);
+    const state = states.get(sessionKey);
+    if (!state) return;
+
+    state.active = false;
+    state.unsubscribeFollowUpShortcut?.();
+    state.unsubscribeFollowUpShortcut = undefined;
+    render(ctx);
+  }
+
+  function queueMessage(
+    ctx: ExtensionContext,
+    mode: QueueMode,
+    message: Omit<QueuedReviewMessage, "mode">,
+  ): void {
+    const sessionKey = getReviewSessionKey(ctx);
+    const state = getState(sessionKey);
+    state.messages.push({ mode, ...message });
+    render(ctx);
+  }
+
+  function restoreMessagesToEditor(ctx: ExtensionContext): boolean {
+    const state = states.get(getReviewSessionKey(ctx));
+    if (!state?.messages.length) return false;
+
+    const queuedText = state.messages.map((message) => message.text).join("\n\n");
+    const currentText = ctx.ui.getEditorText();
+    const combinedText = [queuedText, currentText].filter((text) => text.trim()).join("\n\n");
+    state.messages = [];
+    ctx.ui.setEditorText(combinedText);
+    render(ctx);
+    return true;
+  }
+
+  function flush(
+    ctx: ExtensionContext,
+    predicate: (message: QueuedReviewMessage) => boolean,
+    options: FlushOptions = {},
+  ): boolean {
+    const sessionKey = getReviewSessionKey(ctx);
+    const state = states.get(sessionKey);
+    if (!state?.messages.length) return false;
+
+    const selected: QueuedReviewMessage[] = [];
+    const remaining: QueuedReviewMessage[] = [];
+    for (const message of state.messages) {
+      if (predicate(message)) selected.push(message);
+      else remaining.push(message);
+    }
+    if (selected.length === 0) return false;
+
+    state.messages = remaining;
+    render(ctx);
+
+    const text = selected
+      .map((message) => message.text.trim())
+      .filter(Boolean)
+      .join("\n\n");
+    const images = selected.flatMap((message) => message.images ?? []);
+    const content = images.length ? [{ type: "text" as const, text }, ...images] : text;
+    const deliveryMode = options.forceFollowUp ? "followUp" : selected[0]?.mode;
+    const delivery =
+      !options.forceFollowUp && ctx.isIdle() && !ctx.hasPendingMessages()
+        ? undefined
+        : { deliverAs: deliveryMode ?? "followUp" };
+    pi.sendUserMessage(content, delivery);
+    return true;
+  }
+
+  function getState(sessionKey: string): QueueState {
+    let state = states.get(sessionKey);
+    if (!state) {
+      state = { active: false, messages: [] };
+      states.set(sessionKey, state);
+    }
+    return state;
+  }
+
+  function isActive(sessionKey: string): boolean {
+    return states.get(sessionKey)?.active ?? false;
+  }
+
+  function render(ctx: ExtensionContext): void {
+    if (!ctx.hasUI) return;
+
+    const messages = states.get(getReviewSessionKey(ctx))?.messages ?? [];
+    if (messages.length === 0) {
+      ctx.ui.setWidget(WIDGET_KEY, undefined);
+      return;
+    }
+
+    const lines = messages.map((message) => {
+      const label = message.mode === "steer" ? "Steering" : "Follow-up";
+      return ctx.ui.theme.fg("dim", `${label}: ${formatPreview(message)}`);
+    });
+    lines.push(
+      ctx.ui.theme.fg(
+        "dim",
+        `↳ ${appKeyDisplay("app.message.dequeue")} to edit all queued messages`,
+      ),
+    );
+    ctx.ui.setWidget(WIDGET_KEY, lines);
+  }
+
+  return {
+    start,
+    handleInput,
+    flushSteering,
+    flushAll,
+    clear,
+  };
+}
+
+function matchesConfiguredKey(data: string, keybinding: Parameters<typeof keyText>[0]): boolean {
+  return getKeybindings().matches(data, keybinding);
+}
+
+function isImmediateCommand(text: string): boolean {
+  return text.trimStart().startsWith("!");
+}
+
+function appKeyDisplay(keybinding: Parameters<typeof keyText>[0]): string {
+  return capitalizeKey(keyText(keybinding));
+}
+
+function capitalizeKey(key: string): string {
+  return key
+    .split("/")
+    .map((k) =>
+      k
+        .split("+")
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join("+"),
+    )
+    .join("/");
+}
+
+function formatPreview(message: QueuedReviewMessage): string {
+  const text = message.text.replace(/\s+/g, " ").trim();
+  const truncated =
+    text.length > PREVIEW_MAX_LENGTH ? `${text.slice(0, PREVIEW_MAX_LENGTH - 1)}…` : text;
+  const imageCount = message.images?.length ?? 0;
+  if (imageCount === 0) return truncated || "[empty message]";
+  const imageLabel = `${imageCount} image${imageCount === 1 ? "" : "s"}`;
+  return truncated ? `${truncated} [${imageLabel}]` : `[${imageLabel}]`;
+}