@m8i-51/shoal 0.1.0

package/framework/report.ts

@@ -0,0 +1,276 @@
+import * as fs from "fs";
+import * as path from "path";
+import type { Finding, RunLog } from "./types";
+import type { ProductSpec } from "./product-discovery";
+import type { TriageResult } from "./triage";
+import type { Scenario, ScenarioOutcome } from "./scenario-designer";
+
+function esc(s: string): string {
+  return s
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function embedImage(filePath: string | undefined): string | null {
+  if (!filePath) return null;
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    const data = fs.readFileSync(filePath);
+    return `data:image/png;base64,${data.toString("base64")}`;
+  } catch {
+    return null;
+  }
+}
+
+function formatDuration(startedAt: string, completedAt: string | null): string {
+  if (!completedAt) return "—";
+  const ms = new Date(completedAt).getTime() - new Date(startedAt).getTime();
+  const s = Math.round(ms / 1000);
+  return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m ${s % 60}s`;
+}
+
+function categoryColor(cat: string): string {
+  switch (cat) {
+    case "bug": return "#ef4444";
+    case "ux": return "#f97316";
+    case "feature-request": return "#3b82f6";
+    default: return "#6b7280";
+  }
+}
+
+export function generateReport(
+  runLog: RunLog,
+  findings: Finding[],
+  triageResult: TriageResult,
+  productSpec: ProductSpec,
+  scenarios: Scenario[],
+  agentAssignments: Map<string, { scenario?: Scenario; lens?: string }>,
+  scenarioOutcomes: ScenarioOutcome[] = [],
+): string {
+  const reportPath = path.join(process.cwd(), "logs", `report_${runLog.runId}.html`);
+
+  const issuedSet = new Set(triageResult.issued);
+  const skippedSet = new Set(triageResult.skipped);
+
+  // issued → unprocessed → skipped の順に並べる
+  const sortedFindings = [...findings].sort((a, b) => {
+    const rank = (f: Finding) => (issuedSet.has(f.id) ? 0 : !skippedSet.has(f.id) ? 1 : 2);
+    return rank(a) - rank(b);
+  });
+
+  const categoryCounts: Record<string, number> = {};
+  for (const f of findings) {
+    categoryCounts[f.category] = (categoryCounts[f.category] ?? 0) + 1;
+  }
+
+  const duration = formatDuration(runLog.startedAt, runLog.completedAt);
+  const date = new Date(runLog.startedAt).toLocaleString("ja-JP", { timeZone: "Asia/Tokyo" });
+
+  // ----------------------------------------------------------------
+  // Finding cards
+  // ----------------------------------------------------------------
+
+  const findingCards = sortedFindings.map((f) => {
+    const status = issuedSet.has(f.id) ? "issued" : skippedSet.has(f.id) ? "skipped" : "unprocessed";
+    const statusLabel = { issued: "→ Issue", skipped: "skipped", unprocessed: "pending" }[status];
+    const statusColor = { issued: "#22c55e", skipped: "#9ca3af", unprocessed: "#f59e0b" }[status];
+    const imgData = embedImage(f.screenshotPath);
+    const assignment = agentAssignments.get(f.agentId);
+    const assignmentTag = assignment?.scenario
+      ? `<span class="assignment-tag scenario">scenario: ${esc(assignment.scenario.title)}</span>`
+      : assignment?.lens
+      ? `<span class="assignment-tag lens">lens: ${esc(assignment.lens.split(":")[0].trim())}</span>`
+      : "";
+
+    return `
+<div class="finding ${esc(status)}">
+  <div class="finding-header">
+    <span class="badge" style="background:${categoryColor(f.category)}">${esc(f.category)}</span>
+    <span class="badge" style="background:${statusColor}">${statusLabel}</span>
+    ${assignmentTag}
+    <span class="agent-name">${esc(f.agentName)}</span>
+  </div>
+  <h3 class="finding-title">${esc(f.title)}</h3>
+  <p class="finding-body">${esc(f.body).replace(/\n/g, "<br>")}</p>
+  ${imgData ? `<details class="screenshot-toggle"><summary>スクリーンショット</summary><img src="${imgData}" alt="screenshot" class="screenshot"></details>` : ""}
+</div>`;
+  }).join("\n");
+
+  // ----------------------------------------------------------------
+  // Agent table rows
+  // ----------------------------------------------------------------
+
+  const agentRows = runLog.agents.map((a) => {
+    const assignment = agentAssignments.get(a.agentId);
+    const assignmentCell = assignment?.scenario
+      ? `<span class="badge" style="background:#8b5cf6">scenario</span>&nbsp;${esc(assignment.scenario.title)}`
+      : assignment?.lens
+      ? `<span class="badge" style="background:#0ea5e9">lens</span>&nbsp;${esc(assignment.lens.split(":")[0].trim())}`
+      : `<span class="badge" style="background:#9ca3af">${a.agentType === "regression" ? "regression" : "—"}</span>`;
+    const statusColor = a.status === "completed" ? "#22c55e" : "#ef4444";
+    return `<tr>
+  <td>${esc(a.agentName)}</td>
+  <td><span class="badge" style="background:#475569">${esc(a.agentType)}</span></td>
+  <td style="font-size:0.8rem">${assignmentCell}</td>
+  <td style="text-align:center">${a.iterations}</td>
+  <td><span class="badge" style="background:${statusColor}">${esc(a.status)}</span></td>
+</tr>`;
+  }).join("\n");
+
+  // ----------------------------------------------------------------
+  // ----------------------------------------------------------------
+  // Scenario outcomes
+  // ----------------------------------------------------------------
+
+  const outcomesSection = scenarioOutcomes.length > 0 ? (() => {
+    const achieved = scenarioOutcomes.filter((o) => o.achieved).length;
+    const total = scenarioOutcomes.length;
+    const allPassed = achieved === total;
+    const headerColor = allPassed ? "#22c55e" : achieved === 0 ? "#ef4444" : "#f59e0b";
+    const rows = scenarioOutcomes.map((o) => `<tr>
+  <td>${esc(o.scenarioTitle)}</td>
+  <td>${esc(o.agentName)}</td>
+  <td><span class="badge" style="background:${o.achieved ? "#22c55e" : "#ef4444"}">${o.achieved ? "achieved" : "failed"}</span></td>
+  <td style="font-size:.8rem;color:#475569">${esc(o.reason)}</td>
+</tr>`).join("\n");
+    return `
+<section>
+  <h2>Scenario Outcomes <span style="font-size:.85rem;color:${headerColor};text-transform:none;letter-spacing:0;font-weight:600">${achieved}/${total} achieved</span></h2>
+  <table>
+    <thead><tr><th>Scenario</th><th>Agent</th><th>Result</th><th>Reason</th></tr></thead>
+    <tbody>${rows}</tbody>
+  </table>
+</section>`;
+  })() : "";
+
+  // ----------------------------------------------------------------
+  // Scenario cards
+  // ----------------------------------------------------------------
+
+  const scenarioSection = scenarios.length > 0 ? `
+<section>
+  <h2>Scenarios (${scenarios.length})</h2>
+  <div class="scenarios">
+    ${scenarios.map((s) => `
+    <div class="scenario-card">
+      <div class="scenario-id">${esc(s.id)}</div>
+      <h3>${esc(s.title)}</h3>
+      <p><strong>Context:</strong> ${esc(s.context)}</p>
+      <p><strong>Goal:</strong> ${esc(s.goal)}</p>
+      <p><strong>Constraints:</strong> ${esc(s.constraints)}</p>
+    </div>`).join("")}
+  </div>
+</section>` : "";
+
+  // ----------------------------------------------------------------
+  // Category bar
+  // ----------------------------------------------------------------
+
+  const totalFindings = findings.length;
+  const categoryBar = ["bug", "ux", "feature-request"]
+    .filter((cat) => categoryCounts[cat])
+    .map((cat) => {
+      const count = categoryCounts[cat] ?? 0;
+      const pct = totalFindings > 0 ? Math.max(Math.round((count / totalFindings) * 100), 8) : 0;
+      return `<div class="bar-segment" style="width:${pct}%;background:${categoryColor(cat)}" title="${cat}: ${count}">
+  <span>${esc(cat)} ${count}</span>
+</div>`;
+    }).join("");
+
+  // ----------------------------------------------------------------
+  // Full HTML
+  // ----------------------------------------------------------------
+
+  const html = `<!DOCTYPE html>
+<html lang="ja">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>shoal — ${esc(productSpec.appName)}</title>
+  <style>
+    *{box-sizing:border-box;margin:0;padding:0}
+    body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;background:#f8fafc;color:#1e293b;line-height:1.5}
+    header{background:#1e293b;color:#f8fafc;padding:1.5rem 2rem}
+    header h1{font-size:1.25rem;font-weight:700;margin-bottom:.25rem}
+    header .meta{font-size:.875rem;color:#94a3b8}
+    main{max-width:960px;margin:0 auto;padding:2rem}
+    section{margin-bottom:2.5rem}
+    h2{font-size:.75rem;font-weight:700;text-transform:uppercase;letter-spacing:.08em;color:#64748b;margin-bottom:1rem;padding-bottom:.5rem;border-bottom:1px solid #e2e8f0}
+    .summary-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(110px,1fr));gap:1rem;margin-bottom:1.25rem}
+    .stat-card{background:#fff;border:1px solid #e2e8f0;border-radius:8px;padding:1rem;text-align:center}
+    .stat-card .number{font-size:2rem;font-weight:700;color:#1e293b}
+    .stat-card .label{font-size:.7rem;color:#64748b;margin-top:.25rem;text-transform:uppercase;letter-spacing:.05em}
+    .category-bar{display:flex;height:28px;border-radius:6px;overflow:hidden;background:#e2e8f0;margin-bottom:0}
+    .bar-segment{display:flex;align-items:center;padding:0 .5rem;min-width:60px}
+    .bar-segment span{font-size:.7rem;color:#fff;font-weight:700;white-space:nowrap}
+    .badge{display:inline-block;padding:.15rem .5rem;border-radius:9999px;font-size:.65rem;font-weight:700;color:#fff;white-space:nowrap}
+    .finding{background:#fff;border:1px solid #e2e8f0;border-radius:8px;padding:1rem 1.25rem;margin-bottom:.75rem}
+    .finding.skipped{opacity:.55}
+    .finding-header{display:flex;align-items:center;gap:.4rem;margin-bottom:.5rem;flex-wrap:wrap}
+    .agent-name{font-size:.75rem;color:#94a3b8;margin-left:auto}
+    .assignment-tag{font-size:.7rem;padding:.1rem .45rem;border-radius:4px;white-space:nowrap}
+    .assignment-tag.scenario{color:#7c3aed;background:#ede9fe}
+    .assignment-tag.lens{color:#0369a1;background:#e0f2fe}
+    .finding-title{font-size:.95rem;font-weight:600;margin-bottom:.35rem}
+    .finding-body{font-size:.85rem;color:#475569}
+    .screenshot-toggle{margin-top:.75rem}
+    .screenshot-toggle summary{font-size:.8rem;color:#64748b;cursor:pointer;user-select:none}
+    .screenshot{max-width:100%;max-height:400px;object-fit:contain;border:1px solid #e2e8f0;border-radius:4px;margin-top:.5rem;display:block}
+    table{width:100%;border-collapse:collapse;background:#fff;border:1px solid #e2e8f0;border-radius:8px;overflow:hidden;font-size:.85rem}
+    th{background:#f1f5f9;padding:.6rem 1rem;text-align:left;font-weight:700;color:#64748b;font-size:.7rem;text-transform:uppercase;letter-spacing:.05em}
+    td{padding:.6rem 1rem;border-top:1px solid #e2e8f0;vertical-align:middle}
+    .scenarios{display:grid;grid-template-columns:repeat(auto-fit,minmax(260px,1fr));gap:1rem}
+    .scenario-card{background:#fff;border:1px solid #e2e8f0;border-radius:8px;padding:1rem}
+    .scenario-id{font-size:.65rem;font-weight:700;color:#8b5cf6;text-transform:uppercase;letter-spacing:.08em;margin-bottom:.25rem}
+    .scenario-card h3{font-size:.875rem;font-weight:600;margin-bottom:.5rem}
+    .scenario-card p{font-size:.8rem;color:#475569;margin-top:.2rem}
+  </style>
+</head>
+<body>
+<header>
+  <h1>shoal &mdash; ${esc(productSpec.appName)}</h1>
+  <p class="meta">${esc(date)}&nbsp;&nbsp;&middot;&nbsp;&nbsp;${esc(duration)}&nbsp;&nbsp;&middot;&nbsp;&nbsp;${esc(runLog.runId)}</p>
+</header>
+<main>
+  <section>
+    <h2>Summary</h2>
+    <div class="summary-grid">
+      <div class="stat-card"><div class="number">${findings.length}</div><div class="label">findings</div></div>
+      <div class="stat-card"><div class="number">${triageResult.issued.length}</div><div class="label">→ Issues</div></div>
+      <div class="stat-card"><div class="number">${triageResult.skipped.length}</div><div class="label">skipped</div></div>
+      <div class="stat-card"><div class="number">${triageResult.unprocessed.length}</div><div class="label">pending</div></div>
+      <div class="stat-card"><div class="number">${runLog.agents.length}</div><div class="label">agents</div></div>
+    </div>
+    <div class="category-bar">${categoryBar || '<div style="width:100%;display:flex;align-items:center;padding:0 .75rem;font-size:.75rem;color:#94a3b8">no findings</div>'}</div>
+  </section>
+
+  <section>
+    <h2>Findings (${findings.length})</h2>
+    ${sortedFindings.length > 0 ? findingCards : "<p style='color:#94a3b8;font-size:.875rem'>No findings collected.</p>"}
+  </section>
+
+  ${outcomesSection}
+
+  ${scenarioSection}
+
+  <section>
+    <h2>Agents (${runLog.agents.length})</h2>
+    <table>
+      <thead>
+        <tr><th>Name</th><th>Type</th><th>Assignment</th><th style="text-align:center">Iter.</th><th>Status</th></tr>
+      </thead>
+      <tbody>
+        ${agentRows}
+      </tbody>
+    </table>
+  </section>
+</main>
+</body>
+</html>`;
+
+  fs.mkdirSync(path.dirname(reportPath), { recursive: true });
+  fs.writeFileSync(reportPath, html, "utf-8");
+  return reportPath;
+}

package/framework/scenario-designer.ts

@@ -0,0 +1,141 @@
+import Anthropic from "@anthropic-ai/sdk";
+import type { LLMClient } from "./llm-client";
+import { createMessageWithRetry } from "./agent-loop";
+import type { ProductSpec } from "./product-discovery";
+
+export interface Scenario {
+  id: string;
+  title: string;
+  context: string;    // Who the user is and their situation
+  goal: string;       // What they want to accomplish
+  constraints: string; // Special conditions (first-time user, under pressure, etc.)
+}
+
+export interface ScenarioOutcome {
+  scenarioId: string;
+  scenarioTitle: string;
+  agentId: string;
+  agentName: string;
+  achieved: boolean;
+  reason: string;
+}
+
+const OUTPUT_SCENARIOS_TOOL: Anthropic.Tool = {
+  name: "output_scenarios",
+  description: "Output the generated test scenarios / 生成したテストシナリオを出力する",
+  input_schema: {
+    type: "object",
+    properties: {
+      scenarios: {
+        type: "array",
+        description: "List of user test scenarios",
+        items: {
+          type: "object",
+          properties: {
+            title: {
+              type: "string",
+              description: "Short scenario title (e.g. 'New employee submitting first purchase request')",
+            },
+            context: {
+              type: "string",
+              description: "Who is this user and what is their situation? (1-2 sentences)",
+            },
+            goal: {
+              type: "string",
+              description: "What does the user want to accomplish? (specific and actionable)",
+            },
+            constraints: {
+              type: "string",
+              description: "Special conditions: e.g. first time using this feature, in a hurry, unfamiliar with the approval flow, etc.",
+            },
+          },
+          required: ["title", "context", "goal", "constraints"],
+        },
+      },
+    },
+    required: ["scenarios"],
+  },
+};
+
+export async function designScenarios(
+  spec: ProductSpec,
+  openIssues: { number: number; title: string; labels: string[] }[],
+  client: LLMClient,
+  model: string,
+  count: number = 5,
+  coverageSummary?: string,
+): Promise<Scenario[]> {
+  console.log("\n[scenario-designer] generating scenarios...");
+
+  const issueHints = openIssues.length > 0
+    ? `\n[Known Open Issues — risky areas to naturally route scenarios through]\n${openIssues.slice(0, 15).map((i) => `- ${i.title} [${i.labels.join(", ")}]`).join("\n")}`
+    : "";
+
+  const coverageHints = coverageSummary
+    ? `\n[Coverage History — adjust scenarios to explore underrepresented areas]\n${coverageSummary}`
+    : "";
+
+  const response = await createMessageWithRetry(client, {
+    model,
+    max_tokens: 2048,
+    system: `You are a QA scenario designer. Generate realistic user test scenarios for a web app.
+Each scenario represents a believable task a real user would attempt — not a bug hunt, but a natural user journey.
+Scenarios should collectively cover different user types, app areas, and workflows.`,
+    tools: [OUTPUT_SCENARIOS_TOOL],
+    messages: [
+      {
+        role: "user",
+        content: `Generate exactly ${count} test scenarios for this app.
+
+[App Overview]
+${spec.appDescription}
+
+[Target Users]
+${spec.targetUsers}
+
+[Implemented Features]
+${spec.features}${spec.uiFeatures ? `\n\n[UI-Only Features]\n${spec.uiFeatures}` : ""}${issueHints}${coverageHints}
+
+Guidelines:
+- Each scenario should be a realistic user task (not "find the bug")
+- Cover different user types: power user, new user, occasional user, manager, etc.
+- Cover different app areas and user journeys
+- Make goals specific and actionable (not vague like "use the app")
+- If open issues hint at risky areas, design natural scenarios that pass through those areas
+- If coverage history shows underrepresented areas or lenses, bias scenarios toward those gaps
+- Constraints should reflect realistic user states (first time, in a hurry, confused, etc.)
+
+Call output_scenarios with exactly ${count} scenarios.`,
+      },
+    ],
+  });
+
+  const toolUse = response.content.find(
+    (b): b is Anthropic.ToolUseBlock => b.type === "tool_use" && b.name === "output_scenarios"
+  );
+
+  if (!toolUse) {
+    console.warn("[scenario-designer] LLM did not call output_scenarios — falling back to lens-only mode");
+    return [];
+  }
+
+  const raw = toolUse.input as { scenarios: { title: string; context: string; goal: string; constraints: string }[] };
+
+  if (!Array.isArray(raw.scenarios) || raw.scenarios.length === 0) {
+    console.warn("[scenario-designer] empty scenarios array returned");
+    return [];
+  }
+
+  const scenarios: Scenario[] = raw.scenarios.map((s, i) => ({
+    id: `scenario_${i + 1}`,
+    title: String(s.title),
+    context: String(s.context),
+    goal: String(s.goal),
+    constraints: String(s.constraints),
+  }));
+
+  console.log(`[scenario-designer] generated ${scenarios.length} scenarios:`);
+  scenarios.forEach((s) => console.log(`  - [${s.id}] ${s.title}`));
+
+  return scenarios;
+}

package/framework/triage.ts

@@ -0,0 +1,208 @@
+import Anthropic from "@anthropic-ai/sdk";
+import * as fs from "fs";
+import * as path from "path";
+import type { LLMClient } from "./llm-client";
+import type { Finding } from "./types";
+import { createMessageWithRetry } from "./agent-loop";
+import { postGitHubIssue, fetchOpenIssues } from "./github";
+
+const TRIAGE_TOOLS: Anthropic.Tool[] = [
+  {
+    name: "get_all_findings",
+    description: "Get all feedback collected by agents / 全エージェントが収集したフィードバック一覧を取得する",
+    input_schema: { type: "object", properties: {}, required: [] },
+  },
+  {
+    name: "create_issue",
+    description: "Post feedback as a GitHub Issue; multiple related findings can be merged into one / フィードバックをGitHub Issueとして投稿する。類似フィードバックをまとめて1件にできる",
+    input_schema: {
+      type: "object",
+      properties: {
+        title: { type: "string", description: "Issue title (concise)" },
+        body: { type: "string", description: "Issue body with details from multiple perspectives" },
+        category: { type: "string", enum: ["ux", "feature-request", "bug", "goal-gap"] },
+        merged_finding_ids: {
+          type: "array",
+          items: { type: "string" },
+          description: "IDs of the findings merged into this Issue",
+        },
+      },
+      required: ["title", "body", "category", "merged_finding_ids"],
+    },
+  },
+  {
+    name: "skip_finding",
+    description: "Skip a finding that duplicates an existing open GitHub Issue / 既存のOpenなGitHub Issueと重複するためスキップする",
+    input_schema: {
+      type: "object",
+      properties: {
+        finding_id: { type: "string", description: "ID of the finding to skip" },
+        reason: { type: "string", description: "Reason for skipping" },
+      },
+      required: ["finding_id", "reason"],
+    },
+  },
+];
+
+export interface TriageResult {
+  issued: string[];
+  skipped: string[];
+  unprocessed: string[];
+  issuesCreated: number;
+}
+
+export async function runTriageAgent(
+  findings: Finding[],
+  client: LLMClient,
+  model: string,
+  githubOptions: { token: string; repo: string }
+): Promise<TriageResult> {
+  if (findings.length === 0) {
+    console.log("\n[triage] no findings, skipping");
+    return { issued: [], skipped: [], unprocessed: [], issuesCreated: 0 };
+  }
+
+  console.log(`\n[triage] starting (findings: ${findings.length})`);
+
+  const openIssues = await fetchOpenIssues(githubOptions);
+  const pendingIds = new Set(findings.map((f) => f.id));
+  const issuedIds: string[] = [];
+  const skippedIds: string[] = [];
+  let issuesCreated = 0;
+  let skipped = 0;
+
+  const openIssueList = openIssues.length > 0
+    ? `\n\n[Existing open Issues (for deduplication)]\n${openIssues.map((i) => `- #${i.number}: ${i.title}`).join("\n")}`
+    : "";
+
+  const systemPrompt = `You are a feedback triage AI.
+Organize feedback collected by multiple agents and post it as GitHub Issues.
+
+[Steps]
+1. Call get_all_findings to review collected feedback
+2. Merge similar/duplicate feedback into a single Issue
+3. Skip feedback that duplicates an existing open Issue using skip_finding
+4. Post the rest with create_issue (no duplicates, only valuable findings)
+5. Finish after processing all items${openIssueList}
+
+[Category Guide]
+- bug: incorrect or broken behavior
+- ux: usability, interaction, or visual design issue
+- feature-request: missing capability users would expect
+- goal-gap: the app fails to meet one of its stated goals — use only when a finding directly undermines a specific app goal
+
+[Merging Guidelines]
+- Multiple reports about the same screen/feature can be merged into one Issue
+- Merge into one Issue even across categories if it's the same underlying problem
+- Include multiple perspectives in the body when merging
+- Only post clearly valuable findings (skip operation errors or misunderstandings)
+
+[Important Constraints]
+- merged_finding_ids must contain at least one ID
+- If a finding cannot be linked to any feedback, use skip_finding instead of create_issue`;
+
+  const messages: Anthropic.MessageParam[] = [
+    { role: "user", content: "Triage the feedback and create GitHub Issues." },
+  ];
+
+  let iterations = 0;
+  while (iterations < 15) {
+    iterations++;
+
+    const response = await createMessageWithRetry(client, {
+      model,
+      max_tokens: 2048,
+      system: systemPrompt,
+      tools: TRIAGE_TOOLS,
+      messages,
+    });
+
+    messages.push({ role: "assistant", content: response.content });
+
+    const toolUses = response.content.filter(
+      (b): b is Anthropic.ToolUseBlock => b.type === "tool_use"
+    );
+    if (toolUses.length === 0 || response.stop_reason === "end_turn") break;
+
+    const toolResults: Anthropic.ToolResultBlockParam[] = [];
+    for (const toolUse of toolUses) {
+      let result: unknown;
+
+      if (toolUse.name === "get_all_findings") {
+        result = findings.map((f) => ({
+          id: f.id,
+          agentName: f.agentName,
+          role: f.role,
+          title: f.title,
+          body: f.body,
+          category: f.category,
+          timestamp: f.timestamp,
+          pending: pendingIds.has(f.id),
+        }));
+        console.log(`  [triage] fetched findings (${findings.length})`);
+
+      } else if (toolUse.name === "create_issue") {
+        const { title, body, category, merged_finding_ids } = toolUse.input as {
+          title: string;
+          body: string;
+          category: string;
+          merged_finding_ids: string[] | undefined;
+        };
+        const mergedIds = merged_finding_ids ?? [];
+        if (mergedIds.length === 0) {
+          result = { error: "merged_finding_ids must contain at least one ID" };
+          toolResults.push({ type: "tool_result", tool_use_id: toolUse.id, content: JSON.stringify(result) });
+          continue;
+        }
+        const mergedFindings = findings.filter((f) => mergedIds.includes(f.id));
+        const mergedAgents = mergedFindings.map((f) => `${f.agentName} (${f.role})`);
+        const screenshots = mergedFindings
+          .filter((f) => f.screenshotPath)
+          .map((f) => `- ${f.agentName}: ${f.screenshotPath}`);
+        const screenshotSection = screenshots.length > 0
+          ? `\n\n**Screenshots:**\n${screenshots.join("\n")}`
+          : "";
+        const fullBody = `**Category:** ${category}\n\n${body}${screenshotSection}\n\n---\n**Reported by:** ${mergedAgents.join(", ")}\n*This Issue was auto-generated by an AI triage agent*`;
+        const url = await postGitHubIssue(`[${category}] ${title}`, fullBody, [category, "feedback-agent"], githubOptions);
+        mergedIds.forEach((id) => { pendingIds.delete(id); issuedIds.push(id); });
+        issuesCreated++;
+        result = { created: true, url, mergedCount: mergedIds.length };
+        console.log(`  [triage] issue created: "${title}" (merged ${mergedIds.length})`);
+
+      } else if (toolUse.name === "skip_finding") {
+        const { finding_id, reason } = toolUse.input as { finding_id: string; reason: string };
+        pendingIds.delete(finding_id);
+        skippedIds.push(finding_id);
+        skipped++;
+        result = { skipped: true };
+        console.log(`  [triage] skipped: ${finding_id} — ${reason}`);
+
+      } else {
+        result = { error: "unknown tool" };
+      }
+
+      toolResults.push({ type: "tool_result", tool_use_id: toolUse.id, content: JSON.stringify(result) });
+    }
+
+    messages.push({ role: "user", content: toolResults });
+  }
+
+  if (findings.length > 0) {
+    const runId = findings[0].runId;
+    const findingsDir = path.join(process.cwd(), "findings", runId);
+    fs.writeFileSync(
+      path.join(findingsDir, "triage_result.json"),
+      JSON.stringify({
+        runId,
+        completedAt: new Date().toISOString(),
+        issued: issuedIds,
+        skipped: skippedIds,
+        unprocessed: Array.from(pendingIds),
+      }, null, 2),
+      "utf-8"
+    );
+  }
+
+  console.log(`[triage] done (issues created: ${issuesCreated} / skipped: ${skipped})`);
+  return { issued: issuedIds, skipped: skippedIds, unprocessed: Array.from(pendingIds), issuesCreated };
+}