@cursor/july 0.1.54 → 0.1.61

package/templates/triage/agent/lib/actuate.ts

@@ -0,0 +1,759 @@
+import type {
+  HostMcpCallResult,
+  HostMcpRegistry,
+  HostMcpToolInfo,
+} from "@cursor/july";
+import {
+  ISSUE_ID,
+  JIRA_URL,
+  LINEAR_URL,
+  pinIssueIdentifier,
+  richTextValue,
+} from "./parse-queue-event.js";
+import type {
+  QueueAction,
+  RecordTriageResult,
+  TrackerConfig,
+  TrackerIssue,
+  TrackerResult,
+  TriageSeverity,
+  TriageVerdict,
+} from "./types.js";
+
+const CONNECTION_NAME = "tracker";
+
+const SEARCH_ISSUE_TOOL = /(?:search|list|find)[_-]?issues?$/i;
+const COMMENT_TOOL = /(?:add|create|save)[_-]?comment$/i;
+const LIST_COMMENT_TOOL = /(?:list|get|read)[_-]?comments?$/i;
+const SAVE_OR_UPDATE_ISSUE_TOOL = /(?:save|update)[_-]?issue$/i;
+const UPDATE_ISSUE_TOOL = /update[_-]?issue$/i;
+
+const FIELD_ALIASES = {
+  title: ["title", "name", "issueTitle", "summary"],
+  query: ["query", "q", "search", "term", "jql", "text"],
+  comment: ["comment", "body", "text", "message"],
+  issue: ["id", "issueId", "issue_id", "issueKey", "issue_key", "identifier"],
+  commentIssue: [
+    "issueId",
+    "issue_id",
+    "issueKey",
+    "issue_key",
+    "identifier",
+  ],
+  priority: ["priority", "priorityId", "priority_id"],
+} as const;
+
+const PRIORITY_BY_SEVERITY: Record<TriageSeverity, number> = {
+  urgent: 1,
+  high: 2,
+  medium: 3,
+  low: 4,
+};
+
+export interface ActuateInput {
+  verdict: TriageVerdict;
+  mcp: HostMcpRegistry;
+  tracker: TrackerConfig;
+  purpose?: "live" | "eval";
+  now?: () => string;
+  issueKey?: string | null;
+  /**
+   * Host-trusted inbound title. Live `record_triage` omits this and looks
+   * up the pinned issue. `session.title` is the harness display title and
+   * is overwritten by the turn summary.
+   */
+  issueTitle?: string | null;
+}
+
+export async function actuate(input: ActuateInput): Promise<RecordTriageResult> {
+  const evaluatedAt = (input.now ?? (() => new Date().toISOString()))();
+  const verdict: TriageVerdict = {
+    ...input.verdict,
+    identifier: pinIssueIdentifier(input.issueKey, input.verdict.identifier),
+  };
+  const tracker = await resolveTracker({ ...input, verdict });
+  return { verdict, evaluatedAt, tracker };
+}
+
+async function resolveTracker(input: ActuateInput): Promise<TrackerResult> {
+  if (input.purpose === "eval") {
+    return { status: "skipped", reason: "eval" };
+  }
+  if (input.tracker.kind === "none") {
+    return { status: "not_connected" };
+  }
+
+  const connectionName = input.tracker.connectionName || CONNECTION_NAME;
+  if (!input.mcp.names().includes(connectionName)) {
+    return { status: "not_connected" };
+  }
+
+  let tools: HostMcpToolInfo[];
+  try {
+    tools = await input.mcp.listTools(connectionName);
+  } catch (error) {
+    return { status: "failed", message: errorText(error) };
+  }
+  if (tools.length === 0) {
+    return { status: "not_connected" };
+  }
+
+  const issue: TrackerIssue = {
+    identifier: input.verdict.identifier,
+    url: "",
+  };
+  const searchTool = tools.find((tool) => SEARCH_ISSUE_TOOL.test(tool.name));
+  let search: SearchResult = {
+    candidates: [],
+  };
+  if (searchTool !== undefined) {
+    const hostTitle = await resolveHostTitle({
+      mcp: input.mcp,
+      connectionName,
+      tool: searchTool,
+      identifier: issue.identifier,
+      issueTitle: input.issueTitle,
+    });
+    if (hostTitle !== "") {
+      search = await searchExisting({
+        mcp: input.mcp,
+        connectionName,
+        tool: searchTool,
+        query: hostTitle,
+        matchTitle: hostTitle,
+        excludeIdentifier: issue.identifier,
+      });
+    }
+  }
+
+  const duplicate = search.duplicate;
+  const commentTool = tools.find((tool) => COMMENT_TOOL.test(tool.name));
+  if (commentTool === undefined) {
+    return {
+      status: "failed",
+      message: "the tracker connector exposes no comment tool",
+    };
+  }
+
+  const listed = await loadComments({
+    mcp: input.mcp,
+    connectionName,
+    tools,
+    identifier: issue.identifier,
+  });
+
+  const actions: QueueAction[] = [];
+  if (listed.status !== "failed") {
+    if (
+      !alreadyCommented(
+        listed,
+        search.candidates,
+        issue.identifier,
+        "Triage:"
+      )
+    ) {
+      const comment = await commentOn({
+        mcp: input.mcp,
+        connectionName,
+        tool: commentTool,
+        issue,
+        body: triageComment(input.verdict, duplicate),
+      });
+      if (!comment.ok) {
+        return { status: "failed", message: comment.message };
+      }
+    }
+    actions.push({ op: "commented" });
+  }
+  if (input.verdict.needsInfo === true) {
+    actions.push({ op: "needs_info" });
+  }
+
+  if (duplicate !== undefined) {
+    const duplicateComment = `Triage: duplicate inbound ${issue.identifier}`;
+    const duplicateListed = await loadComments({
+      mcp: input.mcp,
+      connectionName,
+      tools,
+      identifier: duplicate.identifier,
+    });
+    if (duplicateListed.status !== "failed") {
+      if (
+        !alreadyCommented(
+          duplicateListed,
+          search.candidates,
+          duplicate.identifier,
+          duplicateComment
+        )
+      ) {
+        const comment = await commentOn({
+          mcp: input.mcp,
+          connectionName,
+          tool: commentTool,
+          issue: duplicate,
+          body: duplicateComment,
+        });
+        if (!comment.ok) {
+          return { status: "failed", message: comment.message };
+        }
+      }
+      actions.push({ op: "duplicate_of", of: duplicate.identifier });
+    }
+  }
+
+  if (input.verdict.kind === "bug") {
+    let updateTool: HostMcpToolInfo | undefined;
+    let updateArgs: Record<string, unknown> | undefined;
+    for (const tool of tools) {
+      if (!SAVE_OR_UPDATE_ISSUE_TOOL.test(tool.name)) {
+        continue;
+      }
+      const args = buildPriorityArgs(
+        input.verdict,
+        tool,
+        input.tracker.kind
+      );
+      if (args !== undefined) {
+        updateTool = tool;
+        updateArgs = args;
+        break;
+      }
+    }
+    if (updateTool !== undefined && updateArgs !== undefined) {
+      const update = await callTool({
+        mcp: input.mcp,
+        connectionName,
+        tool: updateTool.name,
+        args: updateArgs,
+      });
+      if (!update.ok) {
+        return { status: "failed", message: update.message };
+      }
+      actions.push({
+        op: "prioritized",
+        severity: input.verdict.severity,
+      });
+    }
+  }
+
+  return { status: "acted", issue, actions };
+}
+
+type SearchResult = {
+  candidates: CandidateIssue[];
+  duplicate?: TrackerIssue;
+};
+
+async function resolveHostTitle(input: {
+  mcp: HostMcpRegistry;
+  connectionName: string;
+  tool: HostMcpToolInfo;
+  identifier: string;
+  issueTitle?: string | null;
+}): Promise<string> {
+  if (typeof input.issueTitle === "string") {
+    const title = input.issueTitle.trim();
+    if (title !== "") {
+      return title;
+    }
+  }
+  const listed = await searchIssues({
+    mcp: input.mcp,
+    connectionName: input.connectionName,
+    tool: input.tool,
+    query: input.identifier,
+  });
+  const self = listed.find(
+    (candidate) => issueIdentifier(candidate) === input.identifier
+  );
+  return self?.title.trim() ?? "";
+}
+
+async function searchExisting(input: {
+  mcp: HostMcpRegistry;
+  connectionName: string;
+  tool: HostMcpToolInfo;
+  query: string;
+  matchTitle: string;
+  excludeIdentifier: string;
+}): Promise<SearchResult> {
+  const candidates = await searchIssues({
+    mcp: input.mcp,
+    connectionName: input.connectionName,
+    tool: input.tool,
+    query: input.query,
+  });
+  return {
+    candidates,
+    duplicate: matchingIssue(
+      candidates,
+      input.matchTitle,
+      input.excludeIdentifier
+    ),
+  };
+}
+
+async function searchIssues(input: {
+  mcp: HostMcpRegistry;
+  connectionName: string;
+  tool: HostMcpToolInfo;
+  query: string;
+}): Promise<CandidateIssue[]> {
+  try {
+    const result = await input.mcp.callTool(
+      input.connectionName,
+      input.tool.name,
+      buildSearchArgs(input.query, input.tool)
+    );
+    if (result.isError === true) {
+      return [];
+    }
+    return issuesFromSearch(result);
+  } catch {
+    return [];
+  }
+}
+
+type ListedComments =
+  | { status: "listed"; bodies: string[] }
+  | { status: "unavailable" }
+  | { status: "failed" };
+
+async function loadComments(input: {
+  mcp: HostMcpRegistry;
+  connectionName: string;
+  tools: HostMcpToolInfo[];
+  identifier: string;
+}): Promise<ListedComments> {
+  const tool = input.tools.find((candidate) =>
+    LIST_COMMENT_TOOL.test(candidate.name)
+  );
+  if (tool === undefined) {
+    return { status: "unavailable" };
+  }
+  try {
+    const result = await input.mcp.callTool(
+      input.connectionName,
+      tool.name,
+      {
+        [pickProperty(tool, FIELD_ALIASES.commentIssue)]: input.identifier,
+      }
+    );
+    if (result.isError === true) {
+      return { status: "failed" };
+    }
+    return { status: "listed", bodies: commentBodiesFrom(result) };
+  } catch {
+    return { status: "failed" };
+  }
+}
+
+function commentBodiesFrom(result: HostMcpCallResult): string[] {
+  const fromStructured = collectCommentBodies(result.structuredContent);
+  if (fromStructured.length > 0) {
+    return fromStructured;
+  }
+  const text = resultText(result);
+  const fromJson = collectCommentBodies(tryParseJson(text));
+  if (fromJson.length > 0) {
+    return fromJson;
+  }
+  return text === "" ? [] : [text];
+}
+
+function alreadyCommented(
+  listed: ListedComments,
+  candidates: CandidateIssue[],
+  identifier: string,
+  prefix: string
+): boolean {
+  if (listed.status === "listed") {
+    return listed.bodies.some((comment) => hasSentinel(comment, prefix));
+  }
+  return hasCommentStarting(candidates, identifier, prefix);
+}
+
+async function commentOn(input: {
+  mcp: HostMcpRegistry;
+  connectionName: string;
+  tool: HostMcpToolInfo;
+  issue: TrackerIssue;
+  body: string;
+}): Promise<{ ok: true } | { ok: false; message: string }> {
+  const result = await callTool({
+    mcp: input.mcp,
+    connectionName: input.connectionName,
+    tool: input.tool.name,
+    args: buildCommentArgs(input.issue, input.body, input.tool),
+  });
+  if (!result.ok) {
+    return {
+      ok: false,
+      message: `could not comment on ${input.issue.identifier}: ${result.message}`,
+    };
+  }
+  return result;
+}
+
+async function callTool(input: {
+  mcp: HostMcpRegistry;
+  connectionName: string;
+  tool: string;
+  args: Record<string, unknown>;
+}): Promise<{ ok: true } | { ok: false; message: string }> {
+  try {
+    const result = await input.mcp.callTool(
+      input.connectionName,
+      input.tool,
+      input.args
+    );
+    if (result.isError === true) {
+      return { ok: false, message: resultText(result) };
+    }
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, message: errorText(error) };
+  }
+}
+
+function buildSearchArgs(
+  query: string,
+  tool: HostMcpToolInfo
+): Record<string, unknown> {
+  return {
+    [pickProperty(tool, FIELD_ALIASES.query)]: query,
+  };
+}
+
+function buildCommentArgs(
+  issue: TrackerIssue,
+  body: string,
+  tool: HostMcpToolInfo
+): Record<string, unknown> {
+  return {
+    [pickProperty(tool, FIELD_ALIASES.commentIssue)]: issue.identifier,
+    [pickProperty(tool, FIELD_ALIASES.comment)]: body,
+  };
+}
+
+function buildPriorityArgs(
+  verdict: TriageVerdict,
+  tool: HostMcpToolInfo,
+  kind: TrackerConfig["kind"]
+): Record<string, unknown> | undefined {
+  if (kind !== "linear") {
+    return undefined;
+  }
+  const known = propertyNames(tool);
+  const issueProperty =
+    FIELD_ALIASES.issue.find((alias) => known.has(alias)) ??
+    (UPDATE_ISSUE_TOOL.test(tool.name) ? "id" : undefined);
+  if (issueProperty === undefined) {
+    return undefined;
+  }
+  const priorityProperty = FIELD_ALIASES.priority.find((alias) =>
+    known.has(alias)
+  );
+  if (priorityProperty === undefined) {
+    return undefined;
+  }
+  return {
+    [issueProperty]: verdict.identifier,
+    [priorityProperty]: PRIORITY_BY_SEVERITY[verdict.severity],
+  };
+}
+
+function pickProperty(
+  tool: HostMcpToolInfo,
+  aliases: readonly string[]
+): string {
+  const known = propertyNames(tool);
+  return aliases.find((alias) => known.has(alias)) ?? aliases[0]!;
+}
+
+function propertyNames(tool: HostMcpToolInfo): Set<string> {
+  const properties = tool.inputSchema?.["properties"];
+  if (!isRecord(properties)) {
+    return new Set();
+  }
+  return new Set(Object.keys(properties));
+}
+
+function triageComment(
+  verdict: TriageVerdict,
+  duplicate: TrackerIssue | undefined
+): string {
+  const lines = [
+    `Triage: ${verdict.kind}`,
+    `Severity: ${verdict.severity}`,
+    `Summary: ${verdict.summary}`,
+    `Next step: ${verdict.nextStep}`,
+  ];
+  if (duplicate !== undefined) {
+    lines.push(`Duplicate of: ${duplicate.identifier}`);
+  }
+  if (verdict.needsInfo === true) {
+    lines.push(`Needs info: ${verdict.nextStep}`);
+  }
+  if (verdict.reporter !== undefined && verdict.reporter !== "") {
+    lines.push(`Reported by: ${verdict.reporter}`);
+  }
+  return lines.join("\n");
+}
+
+interface CandidateIssue {
+  identifier: string;
+  url: string;
+  title: string;
+  comments: string[];
+}
+
+function matchingIssue(
+  candidates: CandidateIssue[],
+  title: string,
+  excludeIdentifier: string
+): TrackerIssue | undefined {
+  const match = candidates.find(
+    (candidate) =>
+      issueIdentifier(candidate) !== excludeIdentifier &&
+      titlesMatch(candidate.title, title)
+  );
+  if (match === undefined) {
+    return undefined;
+  }
+  const identifier = issueIdentifier(match);
+  if (identifier === "") {
+    return undefined;
+  }
+  return { identifier, url: match.url };
+}
+
+function issuesFromSearch(result: HostMcpCallResult): CandidateIssue[] {
+  const fromStructured = collectIssues(result.structuredContent);
+  if (fromStructured.length > 0) {
+    return fromStructured;
+  }
+  const text = resultText(result);
+  const fromJson = collectIssues(tryParseJson(text));
+  return fromJson.length > 0 ? fromJson : issuesFromLines(text);
+}
+
+function collectIssues(
+  value: unknown,
+  found: CandidateIssue[] = []
+): CandidateIssue[] {
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      collectIssues(entry, found);
+    }
+    return found;
+  }
+  if (!isRecord(value)) {
+    return found;
+  }
+  const url = firstIssueUrl(value);
+  const identifier = firstIssueId(value) || issueKeyIn(url);
+  const title = firstString(value, FIELD_ALIASES.title);
+  if (identifier !== "" || url !== "") {
+    found.push({
+      identifier,
+      url,
+      title,
+      comments: [
+        ...collectCommentBodies(value["comments"]),
+        ...collectCommentBodies(value["comment"]),
+      ],
+    });
+    return found;
+  }
+  for (const nested of Object.values(value)) {
+    if (typeof nested === "object" && nested !== null) {
+      collectIssues(nested, found);
+    }
+  }
+  return found;
+}
+
+function issuesFromLines(text: string): CandidateIssue[] {
+  return text.split(/\n/).flatMap((line) => {
+    const identifier = line.match(ISSUE_ID)?.[0] ?? "";
+    const url = line.match(LINEAR_URL)?.[0] ?? line.match(JIRA_URL)?.[0] ?? "";
+    if (identifier === "" && url === "") {
+      return [];
+    }
+    const title = line
+      .replace(LINEAR_URL, "")
+      .replace(JIRA_URL, "")
+      .replace(ISSUE_ID, "")
+      .replace(/\s+/g, " ")
+      .trim();
+    const triage = line.indexOf("Triage:");
+    return [
+      {
+        identifier,
+        url,
+        title,
+        comments: triage === -1 ? [] : [line.slice(triage)],
+      },
+    ];
+  });
+}
+
+function hasCommentStarting(
+  candidates: CandidateIssue[],
+  identifier: string,
+  prefix: string
+): boolean {
+  return candidates.some(
+    (candidate) =>
+      issueIdentifier(candidate) === identifier &&
+      candidate.comments.some((comment) => hasSentinel(comment, prefix))
+  );
+}
+
+function hasSentinel(text: string, prefix: string): boolean {
+  return text.split(/\n/).some((line) => {
+    const trimmed = line
+      .trimStart()
+      .replace(/^[-*]\s+/, "")
+      .replace(/^\d+\.\s+/, "");
+    return trimmed.startsWith(prefix);
+  });
+}
+
+const COMMENT_WRAP_KEYS = [
+  "comments",
+  "comment",
+  "nodes",
+  "items",
+  "results",
+  "data",
+  "content",
+  "replies",
+] as const;
+
+function collectCommentBodies(value: unknown, found: string[] = []): string[] {
+  if (typeof value === "string") {
+    if (value.trim() !== "") {
+      found.push(value);
+    }
+    return found;
+  }
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      collectCommentBodies(entry, found);
+    }
+    return found;
+  }
+  if (!isRecord(value)) {
+    return found;
+  }
+  const body = firstString(value, FIELD_ALIASES.comment);
+  if (body !== "") {
+    found.push(body);
+    collectCommentBodies(value["comments"], found);
+    collectCommentBodies(value["replies"], found);
+    return found;
+  }
+  for (const key of FIELD_ALIASES.comment) {
+    const nested = value[key];
+    if (nested === undefined || typeof nested === "string") {
+      continue;
+    }
+    const flattened = richTextValue(nested);
+    if (flattened !== "") {
+      found.push(flattened);
+      collectCommentBodies(value["comments"], found);
+      collectCommentBodies(value["replies"], found);
+      return found;
+    }
+  }
+  for (const key of COMMENT_WRAP_KEYS) {
+    if (value[key] !== undefined) {
+      collectCommentBodies(value[key], found);
+    }
+  }
+  return found;
+}
+
+function issueIdentifier(issue: CandidateIssue): string {
+  return issue.identifier || issueKeyIn(issue.url);
+}
+
+function issueKeyIn(value: string): string {
+  return value.match(ISSUE_ID)?.[0] ?? "";
+}
+
+function firstIssueId(record: Record<string, unknown>): string {
+  for (const key of ["identifier", "issueKey", "issue_key", "key", "id"]) {
+    const value = record[key];
+    if (typeof value === "string") {
+      const match = value.match(ISSUE_ID);
+      if (match !== null) {
+        return match[0];
+      }
+    }
+  }
+  return "";
+}
+
+function firstIssueUrl(record: Record<string, unknown>): string {
+  for (const key of ["url", "htmlUrl", "issueUrl", "link"]) {
+    const value = record[key];
+    if (typeof value === "string") {
+      const url =
+        value.match(LINEAR_URL)?.[0] ?? value.match(JIRA_URL)?.[0] ?? "";
+      if (url !== "") {
+        return url;
+      }
+    }
+  }
+  return "";
+}
+
+function firstString(
+  record: Record<string, unknown>,
+  keys: readonly string[]
+): string {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim() !== "") {
+      return value;
+    }
+  }
+  return "";
+}
+
+function titlesMatch(candidate: string, title: string): boolean {
+  const hay = normalizeTitle(candidate);
+  const needle = normalizeTitle(title);
+  return hay !== "" && hay === needle;
+}
+
+function normalizeTitle(value: string): string {
+  return value.toLowerCase().replace(/\s+/g, " ").trim();
+}
+
+function tryParseJson(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+function resultText(result: HostMcpCallResult): string {
+  return result.content
+    .map((part) => ("text" in part && typeof part.text === "string" ? part.text : ""))
+    .filter((part) => part !== "")
+    .join("\n")
+    .trim();
+}
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}