aidevops 3.29.40 → 3.30.0

package/packages/gui-api/src/status-pulse-workers.ts

@@ -1,23 +1,22 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import {
-  type GuiPulseAuthorAssociation,
-  type GuiPulseIssueOrigin,
-  type GuiPulseProviderId,
   type GuiPulseResourceKind,
   type GuiPulseResourceSnapshot,
+  type GuiPulseSystemicFinding,
+  type GuiPulseWorkerActionSummary,
   type GuiPulseWorkerActivityEvent,
   type GuiPulseWorkerChartSeries,
   type GuiPulseWorkerKpiCard,
-  type GuiPulseWorkerOutcome,
-  type GuiPulseWorkerSeverity,
-  type GuiPulseWorkerStatus,
   type GuiPulseWorkerSummary,
   type GuiPulseWorkerUsageSnapshot,
   type GuiPulsePeriodBucket,
   pulseWorkersFixture,
 } from "../../gui-shared/src";
 import { collapseHome, expandHome, formatEpochField, isRecord, readJsonObject, stringField } from "./status-adapter-utils";
+import { buildAttention } from "./status-pulse-workers-attention";
+import { authorAssociationFromRecord, isHealthyOutcome, issueOriginFromRecord, outcomeFromRecord, providerFromString, severityFromStatus, statusFromOutcome } from "./status-pulse-workers-classifiers";
+import { costRef, countOptions, durationMsFromRecord, type MetricRecord, numberValue, recordTimeMs, stringOrNumber, summaryFromRecord } from "./status-pulse-workers-values";
 
 export interface PulseWorkersAdapterOptions {
   metricsPath?: string;
@@ -35,8 +34,6 @@ interface SourceState {
   observed_at: string;
 }
 
-type MetricRecord = Record<string, unknown>;
-
 const DAY_MS = 86_400_000;
 const WEEK_MS = 7 * DAY_MS;
 const DEFAULT_SCOPE = "local aidevops telemetry";
@@ -44,11 +41,7 @@ const DEFAULT_METRICS_PATH_REF = "~/.aidevops/logs/headless-runtime-metrics.json
 const DEFAULT_PULSE_STATS_PATH_REF = "~/.aidevops/logs/pulse-stats.json";
 const DEFAULT_RESOURCE_METRICS_PATH_REF = "~/.aidevops/logs/resource-metrics.jsonl";
 const DEFAULT_TOKEN_REPORTS_ROOT_REF = "~/.aidevops/_reports/token-use";
-const DIRECT_WORKER_OUTCOMES = new Set<string>(["merged", "closed", "in_progress", "needs_maintainer_review", "blocked", "failed", "deferred", "created_followup"]);
-const WORKER_OUTCOME_KEYWORDS: Array<[string, GuiPulseWorkerOutcome]> = [["success", "merged"], ["complete", "merged"], ["follow", "created_followup"], ["defer", "deferred"], ["block", "blocked"], ["fail", "failed"], ["kill", "failed"]];
-const DIRECT_ISSUE_ORIGINS = new Set<string>(["aidevops_created", "maintainer_created", "origin_interactive", "third_party", "unknown"]);
-const ISSUE_ORIGIN_KEYWORDS: Array<[string, GuiPulseIssueOrigin]> = [["interactive", "origin_interactive"], ["third", "third_party"], ["community", "third_party"], ["maintainer", "maintainer_created"], ["aidevops", "aidevops_created"]];
-const KNOWN_PROVIDER_IDS: readonly GuiPulseProviderId[] = ["anthropic", "openai", "cursor", "google", "local"];
+const PULSE_WORKER_ACTIONS: GuiPulseWorkerActionSummary[] = pulseWorkersFixture.actions;
 
 export function readPulseWorkersSummary(options: PulseWorkersAdapterOptions = {}): { summary: GuiPulseWorkerSummary; source_path_refs: string[] } {
   const nowMs = options.nowMs ?? Date.parse(options.observedAt ?? new Date().toISOString());
@@ -73,12 +66,14 @@ export function readPulseWorkersSummary(options: PulseWorkersAdapterOptions = {}
   ];
 
   const dayMetrics = filterWindow(metrics.records, nowMs, DAY_MS);
+  const previousDayMetrics = filterWindowBetween(metrics.records, nowMs - (2 * DAY_MS), nowMs - DAY_MS);
   const weekMetrics = filterWindow(metrics.records, nowMs, WEEK_MS);
   const pulseCounters = extractPulseCounters(pulseStats.value, nowMs);
   const resourceSnapshots = resourceMetricsToSnapshots(resources.records, observedAt);
   const usageSamples = collectUsageSamples([...dayMetrics, ...tokenReports.records]);
   const events = buildEvents(dayMetrics, resourceSnapshots, usageSamples, observedAt);
-  const warnings = buildAttention(sourceStates, pulseCounters, resourceSnapshots, oauthPool.value);
+  const insights = buildInsights(events, dayMetrics, previousDayMetrics, resourceSnapshots);
+  const warnings = [...buildAttention(sourceStates, pulseCounters, resourceSnapshots, oauthPool.value), ...insights.map((finding) => ({ id: finding.id, severity: finding.severity, title: finding.title, detail: `${finding.detail} Recommended fix: ${finding.recommendation}`, event_ref: finding.event_refs[0] ?? null }))].slice(0, 12);
 
   const summary: GuiPulseWorkerSummary = {
     value_policy: "metadata_only_no_prompt_payloads_no_secrets",
@@ -89,9 +84,11 @@ export function readPulseWorkersSummary(options: PulseWorkersAdapterOptions = {}
     updated_at: observedAt,
     kpis: buildKpis(dayMetrics, weekMetrics, pulseCounters, usageSamples, resourceSnapshots),
     attention: warnings,
+    insights,
     filters: buildFilters(events),
     charts: buildCharts(metrics.records, pulseCounters, nowMs),
     events,
+    actions: PULSE_WORKER_ACTIONS,
   };
 
   return { summary, source_path_refs: sourceStates.map((source) => source.path_ref) };
@@ -144,20 +141,11 @@ function filterWindow(records: MetricRecord[], nowMs: number, windowMs: number):
   });
 }
 
-function recordTimeMs(record: MetricRecord): number | null {
-  for (const key of ["ts", "timestamp", "started_at", "finished_at", "created_at", "updated_at"]) {
-    const value = record[key];
-    if (typeof value === "number" && Number.isFinite(value)) {
-      return value > 9_999_999_999 ? value : value * 1000;
-    }
-    if (typeof value === "string" && value.length > 0) {
-      const parsed = Date.parse(value);
-      if (Number.isFinite(parsed)) {
-        return parsed;
-      }
-    }
-  }
-  return null;
+function filterWindowBetween(records: MetricRecord[], startMs: number, endMs: number): MetricRecord[] {
+  return records.filter((record) => {
+    const time = recordTimeMs(record);
+    return time !== null && time >= startMs && time < endMs;
+  });
 }
 
 function extractPulseCounters(value: Record<string, unknown>, nowMs: number): Record<string, number> {
@@ -192,21 +180,6 @@ function buildKpis(dayMetrics: MetricRecord[], weekMetrics: MetricRecord[], coun
   ];
 }
 
-function buildAttention(sources: SourceState[], counters: Record<string, number>, resources: GuiPulseResourceSnapshot[], oauthPool: Record<string, unknown>): GuiPulseWorkerSummary["attention"] {
-  const missing = sources.filter((source) => source.health !== "present");
-  const attention: GuiPulseWorkerSummary["attention"] = missing.map((source) => ({ id: `source-${source.health}-${slug(source.path_ref)}`, severity: source.health === "invalid" ? "warning" : "info", title: `Telemetry source ${source.health}`, detail: `${source.path_ref} was ${source.health}; the GUI used safe empty summaries for that source.`, event_ref: null }));
-  for (const [name, count] of Object.entries(counters).filter(([, count]) => count > 0)) {
-    attention.push({ id: `pulse-counter-${slug(name)}`, severity: "warning", title: `Pulse counter active: ${name}`, detail: `${count} events observed in the selected local period.`, event_ref: null });
-  }
-  for (const resource of resources.filter((item) => item.pressure === "medium" || item.pressure === "high")) {
-    attention.push({ id: `resource-${slug(resource.kind)}-${slug(resource.label)}`, severity: resource.pressure === "high" ? "critical" : "warning", title: `${resource.label} pressure ${resource.pressure}`, detail: resource.available_label, event_ref: null });
-  }
-  if (!hasAvailableProvider(oauthPool)) {
-    attention.push({ id: "provider-availability-unknown", severity: "info", title: "Provider availability unknown", detail: "OAuth pool metadata did not expose an available provider account count; the GUI marks provider capacity as unknown.", event_ref: null });
-  }
-  return attention.slice(0, 12);
-}
-
 function buildEvents(records: MetricRecord[], resources: GuiPulseResourceSnapshot[], usage: GuiPulseWorkerUsageSnapshot[], observedAt: string): GuiPulseWorkerActivityEvent[] {
   return records.slice(-25).sort((left, right) => (recordTimeMs(right) ?? 0) - (recordTimeMs(left) ?? 0)).map((record, index) => {
     const outcome = outcomeFromRecord(record);
@@ -238,11 +211,87 @@ function buildEvents(records: MetricRecord[], resources: GuiPulseResourceSnapsho
       drilldown_sections: [
         { label: "Evidence", body: "Derived from local worker outcome/resource metadata; prompt text and command payloads are not exposed." },
         { label: "Outcome", body: outcome },
+        { label: "Verification", body: verificationSummary(record) },
+        { label: "Systemic fix", body: systemicFixRecommendation(record, outcome) },
       ],
     };
   });
 }
 
+function buildInsights(events: GuiPulseWorkerActivityEvent[], dayMetrics: MetricRecord[], previousDayMetrics: MetricRecord[], resources: GuiPulseResourceSnapshot[]): GuiPulseSystemicFinding[] {
+  const findings: GuiPulseSystemicFinding[] = [];
+  const thirdPartyWaiting = events.filter((event) => event.issue_origin === "third_party" && (event.outcome === "needs_maintainer_review" || event.outcome === "blocked" || event.outcome === "in_progress"));
+  if (thirdPartyWaiting.length > 0) {
+    findings.push(finding("third-party-waiting", "third_party_waiting", "warning", "Third-party issues waiting", `${thirdPartyWaiting.length} community-origin issue events need triage or resolution in the selected period.`, "Community reports are separated from aidevops-created task handling and may need a maintainer decision before dispatch.", thirdPartyWaiting, "Create a systemic triage task that preserves non-collaborator trust boundaries and adds first-response thresholds.", "community waiting count", thirdPartyWaiting.length, "high"));
+  }
+
+  const failedOrBlocked = events.filter((event) => event.outcome === "failed" || event.outcome === "blocked");
+  for (const [key, group] of groupEvents(failedOrBlocked, (event) => [event.repo_ref ?? "repo:unknown", event.usage?.provider ?? "provider:unknown", event.resources[0]?.kind ?? "resource:unknown"].join("|"))) {
+    if (group.length > 1) {
+      findings.push(finding(`repeated-${key}`, "repeated_failure", "critical", "Repeated failure pattern", `${group.length} failed or blocked runs share repo/provider/resource context.`, "A repeated worker blindspot is likely being retried as individual failures instead of being converted into a shared guardrail or helper fix.", group, "Create a systemic fix task with grouped evidence, affected repo/provider/resource, and a focused verification command.", key.replaceAll("|", " · "), group.length, "medium"));
+    }
+  }
+
+  const weakVerification = events.filter((event) => event.drilldown_sections.some((section) => section.label === "Verification" && /missing|weak|not recorded/i.test(section.body)));
+  if (weakVerification.length > 0) {
+    findings.push(finding("weak-verification", "weak_verification", "warning", "No-verification outcomes", `${weakVerification.length} events lack strong verification metadata.`, "Workers may be completing or blocking without durable command evidence in the telemetry stream.", weakVerification, "Create a systemic fix task to require verification command capture in worker outcome records.", "verification coverage", weakVerification.length, "medium"));
+  }
+
+  const pressureEvents = events.filter((event) => event.resources.some((resource) => resource.pressure === "medium" || resource.pressure === "high"));
+  if (pressureEvents.length > 0 || resources.some((resource) => resource.pressure === "medium" || resource.pressure === "high")) {
+    findings.push(finding("resource-pressure", "resource_pressure", resources.some((resource) => resource.pressure === "high") ? "critical" : "warning", "Resource allowance pressure", `${pressureEvents.length} events overlapped medium/high resource pressure; ${resources.length} resource samples are in scope.`, "Provider quota, GitHub API, queue, CI, or local resource pressure can inflate retry cost and slow dispatch-to-merge cycles.", pressureEvents, "Create a systemic capacity task that records allowance snapshots before redispatching failed workers.", "resource pressure", Math.max(pressureEvents.length, resources.length), "medium"));
+  }
+
+  const currentCost = sumCost(dayMetrics);
+  const previousCost = sumCost(previousDayMetrics);
+  const failedCostEvents = events.filter((event) => (event.outcome === "failed" || event.outcome === "blocked") && event.usage?.estimated_cost_ref != null);
+  if (currentCost > 0 && previousCost > 0 && currentCost >= previousCost * 1.5) {
+    findings.push(finding("cost-spike", "cost_spike", "warning", "Cost spike versus previous period", `Estimated selected-period cost is ${currentCost.toFixed(2)} versus ${previousCost.toFixed(2)} in the previous equivalent window.`, "Retry loops or expensive models may be consuming allowance faster than successful outcomes justify.", events, "Create a systemic cost-control task that ties model/provider selection to outcome quality and retry count.", "estimated USD", dayMetrics.length, "medium", `previous equivalent period: ${previousCost.toFixed(2)}`));
+  } else if (failedCostEvents.length > 0) {
+    findings.push(finding("failed-run-cost", "high_retry_cost", "warning", "Failed-run cost attached to outcomes", `${failedCostEvents.length} failed or blocked events include token/cost metadata.`, "Cost is being spent on outcomes that did not merge, close, defer, or create follow-up work.", failedCostEvents, "Create a systemic retry-budget task that escalates or changes strategy before another costly rerun.", "failed-run cost samples", failedCostEvents.length, "medium"));
+  }
+
+  const slowEvents = events.filter((event) => (event.duration_ms ?? 0) >= 1_800_000);
+  if (slowEvents.length > 0) {
+    findings.push(finding("slow-bottlenecks", "slow_bottleneck", "warning", "Slow dispatch-to-outcome bottlenecks", `${slowEvents.length} events exceeded 30 minutes.`, "Long-running dispatch, review, or merge gates can hide queue/concurrency or CI runner bottlenecks.", slowEvents, "Create a systemic bottleneck task that separates dispatch-to-PR and PR-to-merge timing evidence.", "duration >=30m", slowEvents.length, "medium"));
+  }
+
+  return findings.slice(0, 8);
+}
+
+function finding(id: string, kind: GuiPulseSystemicFinding["kind"], severity: GuiPulseSystemicFinding["severity"], title: string, detail: string, likelyCause: string, events: GuiPulseWorkerActivityEvent[], recommendation: string, metricLabel: string, sampleSize: number, confidence: GuiPulseSystemicFinding["confidence"], comparisonLabel = "selected period scoped to active filters"): GuiPulseSystemicFinding {
+  return { id: `insight-${id.replace(/[^a-z0-9-]+/gi, "-").toLowerCase()}`, kind, severity, title, detail, likely_cause: likelyCause, evidence_refs: evidenceRefs(events), event_refs: events.map((event) => event.id).slice(0, 6), confidence, recommendation, metric_label: metricLabel, period_label: "Last 24h", scope_label: DEFAULT_SCOPE, comparison_label: comparisonLabel, sample_size: sampleSize, primary_action: "create_systemic_fix" };
+}
+
+function groupEvents(events: GuiPulseWorkerActivityEvent[], keyFor: (event: GuiPulseWorkerActivityEvent) => string): Map<string, GuiPulseWorkerActivityEvent[]> {
+  const groups = new Map<string, GuiPulseWorkerActivityEvent[]>();
+  for (const event of events) {
+    const key = keyFor(event);
+    groups.set(key, [...(groups.get(key) ?? []), event]);
+  }
+  return groups;
+}
+
+function evidenceRefs(events: GuiPulseWorkerActivityEvent[]): string[] {
+  return events.flatMap((event) => [event.repo_ref, event.issue_ref, event.pull_request_ref, event.worker_session_ref, event.command_job_ref].filter(Boolean) as string[]).slice(0, 8);
+}
+
+function verificationSummary(record: MetricRecord): string {
+  const value = stringField(record, "verification") ?? stringField(record, "testing") ?? stringField(record, "verification_status");
+  if (typeof value === "string" && value.length > 0) return value;
+  return "Verification missing or weak in local telemetry; outcome should carry command evidence before completion claims.";
+}
+
+function systemicFixRecommendation(record: MetricRecord, outcome: string): string {
+  if (/missing|weak|none/i.test(verificationSummary(record))) return "Require worker outcome telemetry to include verification commands and results.";
+  if (outcome === "failed" || outcome === "blocked") return "Group repeated failure evidence and create a worker-ready helper or validator fix.";
+  return "Create follow-up only when the same blindspot repeats across events in the selected period.";
+}
+
+function sumCost(records: MetricRecord[]): number {
+  return records.reduce((sum, record) => sum + (numberValue(record.estimated_cost_usd ?? record.cost_usd) ?? 0), 0);
+}
+
 function buildFilters(events: GuiPulseWorkerActivityEvent[]): GuiPulseWorkerSummary["filters"] {
   return {
     repos: countOptions(events.map((event) => event.repo_ref).filter(Boolean) as string[], "repo:"),
@@ -284,93 +333,3 @@ function usageFromRecord(record: MetricRecord): GuiPulseWorkerUsageSnapshot | nu
   const model = stringField(record, "model") ?? stringField(record, "model_ref") ?? null;
   return { provider, provider_ref: `provider:${provider}`, model_ref: model, input_tokens: input ?? 0, output_tokens: output ?? 0, cached_tokens: numberValue(record.cached_tokens) ?? 0, total_tokens: total, cost_ref: costRef(record), estimated_cost_ref: costRef(record), wall_time_ms: numberValue(record.wall_time_ms ?? record.duration_ms) ?? 0 };
 }
-
-function outcomeFromRecord(record: MetricRecord): GuiPulseWorkerOutcome {
-  const raw = String(record.outcome ?? record.result ?? record.status ?? "in_progress").toLowerCase();
-  if (DIRECT_WORKER_OUTCOMES.has(raw)) {
-    return raw as GuiPulseWorkerOutcome;
-  }
-  const match = WORKER_OUTCOME_KEYWORDS.find(([keyword]) => raw.includes(keyword));
-  return match?.[1] ?? "in_progress";
-}
-
-function statusFromOutcome(outcome: GuiPulseWorkerOutcome): GuiPulseWorkerStatus {
-  if (outcome === "failed") return "failed";
-  if (outcome === "blocked" || outcome === "needs_maintainer_review") return "blocked";
-  if (outcome === "in_progress") return "running";
-  if (outcome === "deferred") return "deferred";
-  return "completed";
-}
-
-function severityFromStatus(status: GuiPulseWorkerStatus): GuiPulseWorkerSeverity {
-  if (status === "failed" || status === "blocked") return "critical";
-  if (status === "attention" || status === "deferred") return "warning";
-  if (status === "completed" || status === "healthy") return "success";
-  return "info";
-}
-
-function isHealthyOutcome(outcome: GuiPulseWorkerOutcome): boolean {
-  return ["merged", "closed", "deferred", "created_followup"].includes(outcome);
-}
-
-function issueOriginFromRecord(record: MetricRecord): GuiPulseIssueOrigin {
-  const raw = String(record.issue_origin ?? record.origin ?? "unknown").toLowerCase();
-  if (DIRECT_ISSUE_ORIGINS.has(raw)) return raw as GuiPulseIssueOrigin;
-  const match = ISSUE_ORIGIN_KEYWORDS.find(([keyword]) => raw.includes(keyword));
-  return match?.[1] ?? "unknown";
-}
-
-function authorAssociationFromRecord(record: MetricRecord): GuiPulseAuthorAssociation {
-  const raw = String(record.author_association ?? "UNKNOWN").toUpperCase();
-  if (["OWNER", "MEMBER", "COLLABORATOR", "CONTRIBUTOR", "FIRST_TIME_CONTRIBUTOR", "NONE", "UNKNOWN"].includes(raw)) return raw as GuiPulseAuthorAssociation;
-  return "UNKNOWN";
-}
-
-function durationMsFromRecord(record: MetricRecord): number | null {
-  const duration = numberValue(record.duration_ms ?? record.wall_time_ms);
-  if (duration !== null) return duration;
-  const elapsed = numberValue(record.elapsed_s);
-  return elapsed === null ? null : elapsed * 1000;
-}
-
-function summaryFromRecord(record: MetricRecord, outcome: GuiPulseWorkerOutcome): string {
-  const issue = stringOrNumber(record.issue ?? record.issue_number);
-  return issue === null ? `Worker outcome: ${outcome}.` : `Worker outcome for #${issue.replace(/^#/, "")}: ${outcome}.`;
-}
-
-function countOptions(values: string[], prefix = ""): Array<{ id: string; label: string; count: number }> {
-  const counts = new Map<string, number>();
-  for (const value of values) counts.set(value, (counts.get(value) ?? 0) + 1);
-  return [...counts.entries()].map(([label, count]) => ({ id: `${prefix}${slug(label)}`, label, count })).sort((a, b) => b.count - a.count || a.label.localeCompare(b.label));
-}
-
-function hasAvailableProvider(value: Record<string, unknown>): boolean {
-  const providers = Array.isArray(value.providers) ? value.providers : [];
-  return providers.some((provider) => isRecord(provider) && (numberValue(provider.available) ?? 0) > 0);
-}
-
-function costRef(record: MetricRecord): string | null {
-  const cost = record.estimated_cost_ref ?? record.cost_ref;
-  if (typeof cost === "string" && cost.length > 0 && !cost.includes("/")) return cost;
-  const amount = numberValue(record.estimated_cost_usd ?? record.cost_usd);
-  return amount === null ? null : `$${amount.toFixed(2)} estimated`;
-}
-
-function providerFromString(value: string | undefined): GuiPulseProviderId {
-  if (KNOWN_PROVIDER_IDS.includes(value as GuiPulseProviderId)) return value as GuiPulseProviderId;
-  return "unknown";
-}
-
-function stringOrNumber(value: unknown): string | null {
-  if (typeof value === "string" && value.length > 0) return value;
-  if (typeof value === "number" && Number.isFinite(value)) return String(value);
-  return null;
-}
-
-function numberValue(value: unknown): number | null {
-  return typeof value === "number" && Number.isFinite(value) ? value : null;
-}
-
-function slug(value: string): string {
-  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "unknown";
-}

package/packages/gui-desktop/scripts/install-macos-app.sh

@@ -341,6 +341,7 @@ final class DraggableTitlebarView: NSView {
 final class AppDelegate: NSObject, NSApplicationDelegate, WKNavigationDelegate, WKUIDelegate, WKScriptMessageHandler, NSMenuItemValidation, NSWindowDelegate {
     private var window: NSWindow!
     private var aboutWindow: NSWindow?
+    private var titlebarCameraButton: NSButton?
     private var titlebarToggleButton: NSButton?
     private var webView: WKWebView!
     private let apiPort = ProcessInfo.processInfo.environment["AIDEVOPS_GUI_API_PORT"] ?? "8787"
@@ -408,9 +409,22 @@ final class AppDelegate: NSObject, NSApplicationDelegate, WKNavigationDelegate,
             return
         }
 
+        if revealFileURL(url) {
+            return
+        }
+
         _ = openExternalURL(url)
     }
 
+    private func revealFileURL(_ url: URL) -> Bool {
+        guard url.isFileURL else {
+            return false
+        }
+
+        NSWorkspace.shared.activateFileViewerSelecting([url])
+        return true
+    }
+
     func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
         guard let url = navigationAction.request.url else {
             decisionHandler(.allow)
@@ -552,7 +566,7 @@ final class AppDelegate: NSObject, NSApplicationDelegate, WKNavigationDelegate,
             return webView?.canGoBack ?? false
         case #selector(goForward(_:)):
             return webView?.canGoForward ?? false
-        case #selector(reloadPage(_:)), #selector(stopLoading(_:)), #selector(resetZoom(_:)), #selector(zoomIn(_:)), #selector(zoomOut(_:)):
+        case #selector(reloadPage(_:)), #selector(stopLoading(_:)), #selector(resetZoom(_:)), #selector(zoomIn(_:)), #selector(zoomOut(_:)), #selector(captureAppScreenshot(_:)), #selector(capturePageScreenshot(_:)):
             return webView != nil
         default:
             return true
@@ -779,11 +793,30 @@ final class AppDelegate: NSObject, NSApplicationDelegate, WKNavigationDelegate,
 
         overlay.addSubview(toggleButton)
         titlebarToggleButton = toggleButton
+
+        let cameraButton = NSButton(frame: .zero)
+        cameraButton.action = #selector(showScreenshotMenu(_:))
+        cameraButton.bezelStyle = .regularSquare
+        cameraButton.contentTintColor = defaultButtonAccent
+        cameraButton.image = cameraImage()
+        cameraButton.imagePosition = .imageOnly
+        cameraButton.isBordered = false
+        cameraButton.setButtonType(.momentaryChange)
+        cameraButton.target = self
+        cameraButton.toolTip = "Capture an aidevops screenshot"
+        cameraButton.translatesAutoresizingMaskIntoConstraints = false
+
+        overlay.addSubview(cameraButton)
+        titlebarCameraButton = cameraButton
         NSLayoutConstraint.activate([
             toggleButton.leadingAnchor.constraint(equalTo: overlay.leadingAnchor, constant: 92),
             toggleButton.centerYAnchor.constraint(equalTo: overlay.centerYAnchor, constant: 3.5),
             toggleButton.heightAnchor.constraint(equalToConstant: 22),
-            toggleButton.widthAnchor.constraint(equalToConstant: 22)
+            toggleButton.widthAnchor.constraint(equalToConstant: 22),
+            cameraButton.trailingAnchor.constraint(equalTo: overlay.trailingAnchor, constant: -92),
+            cameraButton.centerYAnchor.constraint(equalTo: overlay.centerYAnchor, constant: 3.5),
+            cameraButton.heightAnchor.constraint(equalToConstant: 22),
+            cameraButton.widthAnchor.constraint(equalToConstant: 22)
         ])
 
         return overlay
@@ -791,6 +824,7 @@ final class AppDelegate: NSObject, NSApplicationDelegate, WKNavigationDelegate,
 
     private func updateTitlebarAccent(hue: CGFloat) {
         let normalizedHue = min(359, max(0, hue))
+        titlebarCameraButton?.contentTintColor = accentColor(hueDegrees: normalizedHue, alpha: 0.9)
         titlebarToggleButton?.contentTintColor = accentColor(hueDegrees: normalizedHue, alpha: 0.9)
     }
 
@@ -866,10 +900,191 @@ final class AppDelegate: NSObject, NSApplicationDelegate, WKNavigationDelegate,
         return image
     }
 
+    private func cameraImage() -> NSImage {
+        let image = NSImage(size: NSSize(width: 20, height: 20), flipped: false) { _ in
+            let body = NSBezierPath(roundedRect: NSRect(x: 3, y: 6, width: 14, height: 10), xRadius: 2.7, yRadius: 2.7)
+            body.lineWidth = 2
+            NSColor.labelColor.setStroke()
+            body.stroke()
+
+            let prism = NSBezierPath(roundedRect: NSRect(x: 6, y: 14, width: 5, height: 2.3), xRadius: 1, yRadius: 1)
+            prism.lineWidth = 1.8
+            prism.stroke()
+
+            let lens = NSBezierPath(ovalIn: NSRect(x: 7.1, y: 8.1, width: 5.8, height: 5.8))
+            lens.lineWidth = 1.8
+            lens.stroke()
+
+            return true
+        }
+        image.isTemplate = true
+        return image
+    }
+
     @objc private func toggleMachineRail(_ sender: Any?) {
         webView.evaluateJavaScript("window.dispatchEvent(new CustomEvent('aidevops:toggle-machine-rail')); true;", completionHandler: nil)
     }
 
+    @objc private func showScreenshotMenu(_ sender: Any?) {
+        guard let button = sender as? NSButton else {
+            return
+        }
+
+        let menu = NSMenu(title: "Screenshots")
+        menu.addItem(menuItem("Screenshot App", action: #selector(captureAppScreenshot(_:)), target: self))
+        menu.addItem(menuItem("Screenshot Page", action: #selector(capturePageScreenshot(_:)), target: self))
+        menu.popUp(positioning: nil, at: NSPoint(x: 0, y: button.bounds.height + 3), in: button)
+    }
+
+    @objc private func captureAppScreenshot(_ sender: Any?) {
+        guard let contentView = window.contentView else {
+            return
+        }
+
+        let bounds = contentView.bounds
+        guard let representation = contentView.bitmapImageRepForCachingDisplay(in: bounds) else {
+            return
+        }
+
+        contentView.cacheDisplay(in: bounds, to: representation)
+        let image = NSImage(size: bounds.size)
+        image.addRepresentation(representation)
+        saveScreenshot(image: image, nameComponent: "window")
+    }
+
+    @objc private func capturePageScreenshot(_ sender: Any?) {
+        let script = """
+        (() => {
+          const el = document.querySelector('.workspace-scroll');
+          const title = document.querySelector('.header-title h1')?.textContent || document.title || 'page';
+          if (!el) return null;
+          const rect = el.getBoundingClientRect();
+          return { x: rect.left, y: rect.top, width: rect.width, height: rect.height, scrollHeight: el.scrollHeight, title, originalScrollTop: el.scrollTop };
+        })();
+        """
+
+        webView.evaluateJavaScript(script) { [weak self] result, _ in
+            guard let self = self, let info = result as? [String: Any] else {
+                return
+            }
+
+            self.captureScrollableWorkspace(info: info)
+        }
+    }
+
+    private func captureScrollableWorkspace(info: [String: Any]) {
+        guard let x = info["x"] as? NSNumber,
+              let y = info["y"] as? NSNumber,
+              let width = info["width"] as? NSNumber,
+              let height = info["height"] as? NSNumber,
+              let scrollHeight = info["scrollHeight"] as? NSNumber else {
+            return
+        }
+
+        let viewportHeight = max(1, CGFloat(height.doubleValue))
+        let contentHeight = max(viewportHeight, CGFloat(scrollHeight.doubleValue))
+        let contentWidth = max(1, CGFloat(width.doubleValue))
+        let captureRect = CGRect(x: CGFloat(x.doubleValue), y: CGFloat(y.doubleValue), width: contentWidth, height: viewportHeight)
+        let pageName = sanitizeFilenameComponent((info["title"] as? String) ?? "page")
+        let originalScrollTop = CGFloat((info["originalScrollTop"] as? NSNumber)?.doubleValue ?? 0)
+        let composite = NSImage(size: NSSize(width: contentWidth, height: contentHeight))
+        captureWorkspaceChunk(rect: captureRect, contentHeight: contentHeight, viewportHeight: viewportHeight, originalScrollTop: originalScrollTop, targetOffset: 0, pageName: pageName, composite: composite, capturedOffsets: Set<Int>())
+    }
+
+    private func captureWorkspaceChunk(rect: CGRect, contentHeight: CGFloat, viewportHeight: CGFloat, originalScrollTop: CGFloat, targetOffset: CGFloat, pageName: String, composite: NSImage, capturedOffsets: Set<Int>) {
+        let scrollScript = """
+        (() => {
+          const el = document.querySelector('.workspace-scroll');
+          if (!el) return null;
+          el.scrollTop = \(Int(targetOffset));
+          return el.scrollTop;
+        })();
+        """
+
+        webView.evaluateJavaScript(scrollScript) { [weak self] result, _ in
+            guard let self = self else {
+                return
+            }
+
+            let actualOffset = CGFloat((result as? NSNumber)?.doubleValue ?? Double(targetOffset))
+            let offsetKey = Int(actualOffset.rounded())
+            var nextCapturedOffsets = capturedOffsets
+            if capturedOffsets.contains(offsetKey) {
+                self.restoreWorkspaceScroll(originalScrollTop)
+                self.saveScreenshot(image: composite, nameComponent: pageName)
+                return
+            }
+            nextCapturedOffsets.insert(offsetKey)
+
+            DispatchQueue.main.asyncAfter(deadline: .now() + 0.08) {
+                let configuration = WKSnapshotConfiguration()
+                configuration.rect = rect
+                self.webView.takeSnapshot(with: configuration) { snapshot, _ in
+                    if let snapshot = snapshot {
+                        composite.lockFocus()
+                        snapshot.draw(in: NSRect(x: 0, y: contentHeight - actualOffset - viewportHeight, width: rect.width, height: viewportHeight), from: .zero, operation: .copy, fraction: 1)
+                        composite.unlockFocus()
+                    }
+
+                    if actualOffset + viewportHeight >= contentHeight - 1 {
+                        self.restoreWorkspaceScroll(originalScrollTop)
+                        self.saveScreenshot(image: composite, nameComponent: pageName)
+                    } else {
+                        let nextOffset = min(contentHeight - viewportHeight, actualOffset + viewportHeight)
+                        self.captureWorkspaceChunk(rect: rect, contentHeight: contentHeight, viewportHeight: viewportHeight, originalScrollTop: originalScrollTop, targetOffset: nextOffset, pageName: pageName, composite: composite, capturedOffsets: nextCapturedOffsets)
+                    }
+                }
+            }
+        }
+    }
+
+    private func restoreWorkspaceScroll(_ scrollTop: CGFloat) {
+        webView.evaluateJavaScript("document.querySelector('.workspace-scroll')?.scrollTo({ top: \(Int(scrollTop)), behavior: 'instant' }); true;", completionHandler: nil)
+    }
+
+    private func saveScreenshot(image: NSImage, nameComponent: String) {
+        guard let tiff = image.tiffRepresentation,
+              let bitmap = NSBitmapImageRep(data: tiff),
+              let data = bitmap.representation(using: .png, properties: [:]) else {
+            return
+        }
+
+        let directory = FileManager.default.homeDirectoryForCurrentUser.appendingPathComponent("Screenshots", isDirectory: true)
+        do {
+            try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+            let fileURL = directory.appendingPathComponent("aidevops-app-screenshot-\(sanitizeFilenameComponent(nameComponent))-\(screenshotTimestamp()).png")
+            try data.write(to: fileURL, options: .atomic)
+            NSPasteboard.general.clearContents()
+            NSPasteboard.general.setString(fileURL.path, forType: .string)
+            notifyScreenshotCaptured(fileURL: fileURL)
+        } catch {
+            NSSound.beep()
+        }
+    }
+
+    private func screenshotTimestamp() -> String {
+        let formatter = DateFormatter()
+        formatter.dateFormat = "yyMMdd-HHmmss"
+        return formatter.string(from: Date())
+    }
+
+    private func sanitizeFilenameComponent(_ value: String) -> String {
+        let allowed = CharacterSet.alphanumerics.union(CharacterSet(charactersIn: "-_"))
+        let mapped = value.lowercased().unicodeScalars.map { allowed.contains($0) ? String($0) : "-" }.joined()
+        let collapsed = mapped.split(separator: "-").joined(separator: "-")
+        return collapsed.isEmpty ? "page" : collapsed
+    }
+
+    private func notifyScreenshotCaptured(fileURL: URL) {
+        guard let payloadData = try? JSONSerialization.data(withJSONObject: ["path": fileURL.path, "url": fileURL.absoluteString], options: []),
+              let payload = String(data: payloadData, encoding: .utf8) else {
+            return
+        }
+
+        let script = "window.dispatchEvent(new CustomEvent('aidevops:screenshot-captured', { detail: \(payload) })); true;"
+        webView.evaluateJavaScript(script, completionHandler: nil)
+    }
+
     private func saveMainWindowFrame() {
         guard window != nil else {
             return