tau-coding-agent 0.1.4 → 0.1.6

package/extensions/review/runtime.ts

@@ -0,0 +1,275 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { matchesKey } from "@earendil-works/pi-tui";
+import type { ChildProcess } from "node:child_process";
+
+import type { ReviewRunOutcome, ReviewRunSource } from "./schema.js";
+
+export const REVIEW_CANCELLED_ERROR = "Review aborted";
+
+export const REVIEW_EVENT_START = "review:start";
+export const REVIEW_EVENT_END = "review:end";
+
+export const REVIEW_STATUS_KEY = "0-review";
+
+export const STATUS_SPINNER_INTERVAL_MS = 80;
+
+export const STATUS_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+export type ReviewExecutionControl = {
+  isCancelled: () => boolean;
+  registerProcess: (proc: ChildProcess) => () => void;
+};
+
+export type ManagedReviewRun = {
+  control: ReviewExecutionControl;
+  markSuccessful: () => void;
+  markCancelled: () => void;
+};
+
+export type AgentEndMessage = {
+  role?: string;
+  stopReason?: string;
+  errorMessage?: string;
+};
+
+export type AgentEndMessages = AgentEndMessage[];
+
+export type AgentEndState = {
+  messages: AgentEndMessages;
+};
+
+export type FixPassAgentTracker = {
+  waitForNextSettled: () => Promise<void>;
+  waitForStartAfter: (lastSeenStartCount: number, timeoutMs: number) => Promise<boolean>;
+  getStartCount: () => number;
+  getLastEnd: () => AgentEndState | undefined;
+};
+
+export type AgentRunTracker = FixPassAgentTracker & {
+  handleStart: () => void;
+  handleEnd: (state: AgentEndState) => void;
+  handleSettled: () => void;
+  reset: () => void;
+};
+
+const runtimeState = {
+  activeReviewRuns: new Set<string>(),
+  activeReviewCancels: new Map<string, () => void>(),
+  activePromptCount: 0,
+};
+
+export async function withManagedReviewRun<T>(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  source: ReviewRunSource,
+  run: (managed: ManagedReviewRun) => Promise<T>,
+): Promise<T> {
+  const sessionKey = getReviewSessionKey(ctx);
+  const activeProcesses = new Set<ChildProcess>();
+  let cancelRequested = false;
+  let outcome: ReviewRunOutcome = "failed";
+
+  const cancelActiveProcesses = () => {
+    for (const proc of activeProcesses) {
+      try {
+        proc.kill("SIGKILL");
+      } catch {
+        // Best effort.
+      }
+    }
+    activeProcesses.clear();
+  };
+
+  const requestCancellation = () => {
+    if (cancelRequested) return;
+    cancelRequested = true;
+    cancelActiveProcesses();
+  };
+
+  const control: ReviewExecutionControl = {
+    isCancelled: () => cancelRequested,
+    registerProcess: (proc) => {
+      activeProcesses.add(proc);
+      return () => {
+        activeProcesses.delete(proc);
+      };
+    },
+  };
+
+  pi.events.emit(REVIEW_EVENT_START, { sessionKey, source });
+  runtimeState.activeReviewCancels.set(sessionKey, requestCancellation);
+  const unsubscribeInterrupt = ctx.hasUI
+    ? ctx.ui.onTerminalInput((data) => {
+        if (!matchesKey(data, "escape")) return undefined;
+        if (runtimeState.activePromptCount > 0) return undefined;
+        requestCancellation();
+        return { consume: true };
+      })
+    : undefined;
+
+  try {
+    return await run({
+      control,
+      markSuccessful: () => {
+        outcome = "success";
+      },
+      markCancelled: () => {
+        outcome = "cancelled";
+      },
+    });
+  } finally {
+    unsubscribeInterrupt?.();
+    cancelActiveProcesses();
+    if (runtimeState.activeReviewCancels.get(sessionKey) === requestCancellation) {
+      runtimeState.activeReviewCancels.delete(sessionKey);
+    }
+    pi.events.emit(REVIEW_EVENT_END, { sessionKey, source, outcome });
+  }
+}
+
+export function notify(
+  ctx: ExtensionContext,
+  message: string,
+  type: "info" | "warning" | "error" = "info",
+) {
+  if (!ctx.hasUI) return;
+  ctx.ui.notify(message, type);
+}
+
+export function getReviewSessionKey(ctx: ExtensionContext): string {
+  return ctx.sessionManager.getSessionFile() ?? `session:${ctx.sessionManager.getSessionId()}`;
+}
+
+export async function withSpinner<T>(
+  ctx: ExtensionContext,
+  buildStatusText: () => string,
+  run: () => Promise<T>,
+): Promise<T> {
+  if (!ctx.hasUI) return run();
+
+  let frame = 0;
+  const render = () => {
+    const spinner = STATUS_SPINNER_FRAMES[frame % STATUS_SPINNER_FRAMES.length];
+    ctx.ui.setStatus(REVIEW_STATUS_KEY, `${spinner} ${buildStatusText()}`);
+  };
+
+  render();
+  const timer = setInterval(() => {
+    frame = (frame + 1) % STATUS_SPINNER_FRAMES.length;
+    render();
+  }, STATUS_SPINNER_INTERVAL_MS);
+
+  try {
+    return await run();
+  } finally {
+    clearInterval(timer);
+    ctx.ui.setStatus(REVIEW_STATUS_KEY, undefined);
+  }
+}
+
+export function acquireReviewRunLock(ctx: ExtensionContext, busyMessage: string): string | null {
+  const sessionKey = getReviewSessionKey(ctx);
+  if (runtimeState.activeReviewRuns.has(sessionKey)) {
+    notify(ctx, busyMessage, "warning");
+    return null;
+  }
+
+  runtimeState.activeReviewRuns.add(sessionKey);
+  return sessionKey;
+}
+
+export function releaseReviewRunLock(sessionKey: string): void {
+  runtimeState.activeReviewRuns.delete(sessionKey);
+}
+
+export function createAgentRunTracker(): AgentRunTracker {
+  let resolveNextAgentSettled: (() => void) | undefined;
+  let resolveNextAgentStart: (() => void) | undefined;
+  let lastAgentEnd: AgentEndState | undefined;
+  let agentStartCount = 0;
+
+  function waitForNextSettled(): Promise<void> {
+    return new Promise((resolve) => {
+      resolveNextAgentSettled = resolve;
+    });
+  }
+
+  function waitForStartAfter(lastSeenStartCount: number, timeoutMs: number): Promise<boolean> {
+    if (agentStartCount > lastSeenStartCount) return Promise.resolve(true);
+
+    return new Promise((resolve) => {
+      let settled = false;
+      let timeoutId: ReturnType<typeof setTimeout> | undefined;
+      let onStart: (() => void) | undefined;
+
+      const finish = (started: boolean) => {
+        if (settled) return;
+        settled = true;
+        if (timeoutId) clearTimeout(timeoutId);
+        if (resolveNextAgentStart === onStart) resolveNextAgentStart = undefined;
+        resolve(started);
+      };
+
+      onStart = () => finish(true);
+      timeoutId = setTimeout(() => finish(false), Math.max(0, timeoutMs));
+      resolveNextAgentStart = onStart;
+    });
+  }
+
+  return {
+    waitForNextSettled,
+    waitForStartAfter,
+    getStartCount: () => agentStartCount,
+    getLastEnd: () => lastAgentEnd,
+    handleStart: () => {
+      agentStartCount += 1;
+      const resolve = resolveNextAgentStart;
+      if (!resolve) return;
+      resolveNextAgentStart = undefined;
+      resolve();
+    },
+    handleEnd: (state) => {
+      lastAgentEnd = state;
+    },
+    handleSettled: () => {
+      const resolve = resolveNextAgentSettled;
+      if (!resolve) return;
+      resolveNextAgentSettled = undefined;
+      resolve();
+    },
+    reset: () => {
+      resolveNextAgentSettled = undefined;
+      resolveNextAgentStart = undefined;
+      lastAgentEnd = undefined;
+      agentStartCount = 0;
+    },
+  };
+}
+
+export function recordPromptStart(): void {
+  runtimeState.activePromptCount += 1;
+}
+
+export function recordPromptEnd(): void {
+  runtimeState.activePromptCount = Math.max(0, runtimeState.activePromptCount - 1);
+}
+
+export function handleReviewSessionStart(ctx: ExtensionContext): void {
+  runtimeState.activePromptCount = 0;
+  const sessionKey = getReviewSessionKey(ctx);
+  for (const [key, cancel] of runtimeState.activeReviewCancels) {
+    if (key !== sessionKey) cancel();
+  }
+}
+
+export function handleReviewSessionShutdown(ctx: ExtensionContext): void {
+  const sessionKey = getReviewSessionKey(ctx);
+  runtimeState.activeReviewCancels.get(sessionKey)?.();
+  runtimeState.activeReviewCancels.delete(sessionKey);
+  runtimeState.activeReviewRuns.delete(sessionKey);
+  runtimeState.activePromptCount = 0;
+}

package/extensions/review/schema.ts

@@ -0,0 +1,160 @@
+export const REVIEW_COMMENT_SCHEMA = "pi.review.comment.v1" as const;
+
+export const REVIEW_OUTPUT_FORMATS = ["inline", "jsonl", "html"] as const;
+
+export type ReviewOutputFormat = (typeof REVIEW_OUTPUT_FORMATS)[number];
+
+export type Priority = "P0" | "P1" | "P2" | "P3";
+
+export const REVIEW_FOCUS_NAMES = [
+  "general",
+  "security",
+  "reuse",
+  "quality",
+  "testing",
+  "efficiency",
+] as const;
+
+export type ReviewFocus = (typeof REVIEW_FOCUS_NAMES)[number];
+export type ReviewRunSource = "review" | "fix" | "triage";
+export type ReviewRunOutcome = "success" | "failed" | "cancelled";
+
+export type ReviewTarget =
+  | { type: "auto" }
+  | { type: "uncommitted" }
+  | { type: "branch"; branch: string }
+  | { type: "commit"; sha: string }
+  | { type: "pr"; ref: string }
+  | { type: "folder"; paths: string[] }
+  | { type: "custom"; instructions: string };
+
+export type ReviewRequestMode =
+  | "auto"
+  | "uncommitted"
+  | `branch:${string}`
+  | `commit:${string}`
+  | `pr:${string}`
+  | `folder:${string}`
+  | "custom";
+
+export type ParsedRequest = {
+  target: ReviewTarget;
+  mode: ReviewRequestMode;
+  models: string[];
+  focuses: ReviewFocus[];
+  targetExplicit: boolean;
+  focusExplicit: boolean;
+  additionalContext?: string;
+};
+
+export type RequestSignaturePayload = {
+  target: unknown;
+  models: string[];
+  focuses: ReviewFocus[];
+  additionalContext?: string | null;
+};
+
+export type ReviewFingerprint = {
+  headSha: string;
+  branch: string;
+  trackedDiffHash: string;
+  untrackedHash: string;
+};
+
+export type FocusFinding = {
+  priority: Priority;
+  location: string;
+  finding: string;
+  suggestion: string;
+};
+
+export type FocusOutput = {
+  focus: ReviewFocus;
+  model: string;
+  findings: FocusFinding[];
+};
+
+export type ReviewReportFinding = {
+  priority: Priority;
+  location: string;
+  finding: string;
+  suggestion: string;
+  focus: string;
+  model: string;
+};
+
+export type ReviewDedupGroup = {
+  ids: number[];
+};
+
+export type ReviewStaleness = {
+  status: "stale";
+  warning: string;
+  nextStep: string;
+};
+
+export type ReviewScopeMode = "working-tree" | "branch-diff" | "commit" | "folder" | "custom";
+
+export type ReviewMessageKind = "report" | "failure" | "triage" | "help";
+
+export type ReviewMessageDetails = {
+  kind?: "report";
+  request: {
+    mode: ReviewRequestMode;
+    signature: string;
+  };
+  scope: {
+    mode: ReviewScopeMode;
+    description: string;
+  };
+  fingerprint: ReviewFingerprint;
+  staleness?: ReviewStaleness;
+  focusStatus: Array<{
+    focus: ReviewFocus;
+    model: string;
+    ok: boolean;
+    error?: string;
+  }>;
+  findings: ReviewReportFinding[];
+};
+
+export type ReviewRunResult =
+  | { ok: false; error: string }
+  | { ok: true; details: ReviewMessageDetails };
+
+export type ReviewCommentSide = "old" | "new" | "snapshot";
+export type ReviewCommentAuthor = "pi" | "user" | string;
+export type ReviewCommentStatus = "open" | "resolved";
+
+export type ReviewCommentRange = {
+  startLine: number;
+  endLine?: number;
+  startColumn?: number;
+  endColumn?: number;
+};
+
+export type ReviewCommentAnchor = {
+  fileHash?: string;
+  selectedText?: string;
+  prefix?: string[];
+  suffix?: string[];
+  diffHunk?: string;
+};
+
+export type ReviewComment = {
+  schema: typeof REVIEW_COMMENT_SCHEMA;
+  id: string;
+  reviewId: string;
+  author: ReviewCommentAuthor;
+  origin: string;
+  createdAt: string;
+  path: string;
+  side: ReviewCommentSide;
+  range?: ReviewCommentRange;
+  priority?: Priority;
+  severity?: "error" | "warning" | "information" | "hint";
+  status: ReviewCommentStatus;
+  body: string;
+  suggestion?: string;
+  anchor?: ReviewCommentAnchor;
+};

package/extensions/review/submit-review-tool.ts

@@ -0,0 +1,62 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { fileURLToPath } from "node:url";
+import { Type } from "typebox";
+
+const PRIORITIES = ["P0", "P1", "P2", "P3"] as const;
+
+export const SUBMIT_REVIEW_EXTENSION_PATH = fileURLToPath(import.meta.url);
+
+const SUBMIT_REVIEW_PARAMS = Type.Object(
+  {
+    findings: Type.Array(
+      Type.Object(
+        {
+          priority: StringEnum(PRIORITIES, {
+            description:
+              "Priority level: P0 critical/blocking, P1 urgent, P2 normal, P3 low/nice-to-have.",
+          }),
+          location: Type.String({
+            minLength: 1,
+            description:
+              "File path and line for the finding, e.g. src/file.ts:42. Use path only if no single line applies.",
+          }),
+          finding: Type.String({
+            minLength: 1,
+            description:
+              "Concise explanation of what is wrong, why it matters, and the concrete scenario where it fails.",
+          }),
+          suggestion: Type.String({
+            minLength: 1,
+            description: "Specific, actionable fix for this finding.",
+          }),
+        },
+        { additionalProperties: false },
+      ),
+      { description: "Final review findings" },
+    ),
+  },
+  { additionalProperties: false },
+);
+
+const submitReviewTool = defineTool({
+  name: "submit_review",
+  label: "Submit Review",
+  description: "Submit the final review findings. Use exactly once as your final action.",
+  promptSnippet: "Submit the final review findings",
+  promptGuidelines: ["Use submit_review exactly once as your final action."],
+  parameters: SUBMIT_REVIEW_PARAMS,
+  constrainedSampling: { type: "json_schema", strict: "prefer" },
+
+  async execute(_toolCallId, params) {
+    return {
+      content: [{ type: "text", text: "Review submitted." }],
+      details: params,
+      terminate: true,
+    };
+  },
+});
+
+export default function reviewSubmitExtension(pi: ExtensionAPI): void {
+  pi.registerTool(submitReviewTool);
+}

package/extensions/review/submit-triage-tool.ts

@@ -0,0 +1,60 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { fileURLToPath } from "node:url";
+import { Type } from "typebox";
+
+const TRIAGE_DECISIONS = ["address", "push_back", "research", "ignore"] as const;
+
+export const SUBMIT_TRIAGE_EXTENSION_PATH = fileURLToPath(import.meta.url);
+
+const SUBMIT_TRIAGE_PARAMS = Type.Object(
+  {
+    items: Type.Array(
+      Type.Object(
+        {
+          id: Type.String({ minLength: 1, description: "Input feedback id being triaged." }),
+          decision: StringEnum(TRIAGE_DECISIONS, {
+            description: "Triage decision: address, push_back, research, or ignore.",
+          }),
+          summary: Type.String({
+            minLength: 1,
+            description: "Brief description of the feedback item.",
+          }),
+          rationale: Type.String({
+            minLength: 1,
+            description: "Why this triage decision is correct.",
+          }),
+          action: Type.String({
+            minLength: 1,
+            description: "What to do next for this feedback item.",
+          }),
+        },
+        { additionalProperties: false },
+      ),
+      { description: "Final triage items" },
+    ),
+  },
+  { additionalProperties: false },
+);
+
+const submitTriageTool = defineTool({
+  name: "submit_triage",
+  label: "Submit Triage",
+  description: "Submit the final PR feedback triage. Use exactly once as your final action.",
+  promptSnippet: "Submit the final PR feedback triage",
+  promptGuidelines: ["Use submit_triage exactly once as your final action."],
+  parameters: SUBMIT_TRIAGE_PARAMS,
+  constrainedSampling: { type: "json_schema", strict: "prefer" },
+
+  async execute(_toolCallId, params) {
+    return {
+      content: [{ type: "text", text: "Triage submitted." }],
+      details: params,
+      terminate: true,
+    };
+  },
+});
+
+export default function triageSubmitExtension(pi: ExtensionAPI): void {
+  pi.registerTool(submitTriageTool);
+}