@omercnet/paseo-omp 0.3.0-next.108.1 → 0.3.0-next.111.1

package/server/provider/profile-providers.ts

@@ -43,7 +43,7 @@ function profileDirectory(environment: NodeJS.ProcessEnv): string {
   );
 }
 
-/** Paseo 0.8 contribution registration is synchronous; inspect directory names only. */
+/** Contribution registration is synchronous; inspect directory names only. */
 export function discoverOmpProfilesSync(environment: NodeJS.ProcessEnv = process.env): string[] {
   let directory: Dir;
   try {
@@ -151,7 +151,12 @@ export function createProfileOmpProvider(profile: string, options: OmpProviderOp
   const id = profileProviderId(profile);
   const environment = fixedEnvironment(profile, options.environment ?? process.env);
   const sessionDir = resolve(ompSessionDir(environment));
-  const runtime = options.runtime ?? new OmpRpcRuntime({ environment });
+  const runtime =
+    options.runtime ??
+    new OmpRpcRuntime({
+      environment,
+      reportProtocolViolation: options.reportProtocolViolation,
+    });
   const readPersistedSessionTranscript = runtime.readPersistedSessionTranscript?.bind(runtime);
   const assertSessionDir = (requested?: string) => {
     if (requested !== undefined && resolve(requested) !== sessionDir) {

package/server/provider/registration.ts

@@ -3,10 +3,11 @@ import { homedir } from "node:os";
 import type { ProviderRegistration } from "@getpaseo/plugin/server/provider";
 import { z } from "zod";
 import type { OmpBrowserAuthorizationRegistry } from "../mcp-browser";
+import type { OmpOperationalFailureReporter } from "../operational-failure-diagnostics";
 import { probeOmpAvailability } from "../provider-diagnostics";
 import { createOmpConnection, OmpNativeSessionReservations } from "./connection";
 import type { OmpMcpConnector } from "./host-tools";
-import { OmpRpcRuntime, type OmpRuntime } from "./omp-rpc";
+import { type OmpProtocolViolationDiagnostic, OmpRpcRuntime, type OmpRuntime } from "./omp-rpc";
 import { parseOmpProviderOptions } from "./provider-options";
 import { boundedJsonBytes } from "./security";
 import { OmpProviderOptionsSchema } from "./settings";
@@ -66,6 +67,8 @@ export interface OmpProviderOptions {
   mcpInitializationTimeoutMs?: number;
   mcpConnector?: OmpMcpConnector;
   browserAuthorizationRegistry?: OmpBrowserAuthorizationRegistry;
+  reportProtocolViolation?: (diagnostic: OmpProtocolViolationDiagnostic) => void | Promise<void>;
+  reportOperationalFailure?: OmpOperationalFailureReporter;
   availabilityProbe?: (
     options: ProviderCatalogOptionsCompat,
     timeoutMs: number | undefined,
@@ -85,7 +88,12 @@ function stableJson(value: unknown): string {
 }
 
 export function createOmpProvider(options: OmpProviderOptions = {}): ProviderRegistrationCompat {
-  const runtime = options.runtime ?? new OmpRpcRuntime({ environment: options.environment });
+  const runtime =
+    options.runtime ??
+    new OmpRpcRuntime({
+      environment: options.environment,
+      reportProtocolViolation: options.reportProtocolViolation,
+    });
   const nativeReservations = new OmpNativeSessionReservations();
   return {
     id: "omp-plugin",
@@ -156,6 +164,8 @@ export function createOmpProvider(options: OmpProviderOptions = {}): ProviderReg
         options.mcpInitializationTimeoutMs,
         options.replayTimeoutMs,
         options.browserAuthorizationRegistry,
+        undefined,
+        options.reportOperationalFailure,
       );
     },
   };

package/server/provider/session.ts

@@ -11,6 +11,10 @@ import type {
   ProviderUsage,
 } from "@getpaseo/plugin/server/provider";
 import { getForgeDefinitionOrNeutral } from "@getpaseo/protocol/forge-manifest";
+import type {
+  OmpOperationalFailure,
+  OmpOperationalFailureReporter,
+} from "../operational-failure-diagnostics";
 import {
   mapOmpModels,
   nativeOmpModelId,
@@ -292,6 +296,7 @@ type ActiveTurn = {
   terminalizing: boolean;
   terminalization?: Promise<void>;
   terminalOutcome?: TurnOutcome;
+  operationalTerminalStage?: "failed" | "unresolved";
   terminalWake?: VoidDeferred;
   steerReady: VoidDeferred;
   steersInFlight: number;
@@ -973,6 +978,7 @@ export class OmpProviderSession {
     private readonly transitionNativeSession: NativeSessionTransition,
     private readonly quarantineRewindCleanup: RewindCleanupQuarantine,
     private readonly retireRewindSession: RewindSessionRetirement,
+    private readonly reportOperationalFailure: OmpOperationalFailureReporter,
     scheduler: OmpTimelineScheduler = defaultOmpTimelineScheduler,
   ) {
     this.id = id;
@@ -1006,6 +1012,13 @@ export class OmpProviderSession {
       : null;
     this.bindRuntime(runtime);
   }
+  private recordOperationalFailure(failure: OmpOperationalFailure): void {
+    try {
+      this.reportOperationalFailure(failure);
+    } catch {
+      // Diagnostics must never affect provider or session flow.
+    }
+  }
   get persistenceSessionId(): string | undefined {
     return this.persistSession ? this.nativeSessionId : undefined;
   }
@@ -1032,6 +1045,7 @@ export class OmpProviderSession {
     environment?: NodeJS.ProcessEnv,
     mcpConnector?: OmpMcpConnector,
     mcpInitializationTimeoutMs?: number,
+    reportOperationalFailure: OmpOperationalFailureReporter = () => {},
   ): Promise<OmpProviderSession> {
     const resumeSessionId = ompPersistenceSessionId(input);
     if (resumeSessionId && !input.config.persist) {
@@ -1078,6 +1092,7 @@ export class OmpProviderSession {
       connectMcp: mcpConnector,
       signal,
       initializationTimeoutMs: mcpInitializationTimeoutMs,
+      reportOperationalFailure,
     });
     let native: OmpRuntimeSession | undefined;
     let cleanupNativeSessionId: string | undefined;
@@ -1236,6 +1251,7 @@ export class OmpProviderSession {
         transitionNativeSession,
         quarantineRewindCleanup,
         retireRewindSession,
+        reportOperationalFailure,
         scheduler,
       );
       session.unsupportedThinkingNoticePending = unsupportedThinkingLevel;
@@ -1653,6 +1669,10 @@ export class OmpProviderSession {
           }
         } catch (error) {
           if (replay.signal.aborted) throw error;
+          this.recordOperationalFailure({
+            category: "replay-recovery",
+            stage: "persisted-replay",
+          });
           this.emit({
             type: "timeline.item",
             sessionId: this.id,
@@ -1807,6 +1827,7 @@ export class OmpProviderSession {
       this.publishCommittedConfig(state, runtime, generation);
       this.emit({ type: "request.completed", requestId: input.requestId });
     } catch (error) {
+      this.recordOperationalFailure({ category: "replay-recovery", stage: "rewind" });
       const failure = branchMutationPossible
         ? { message: "OMP conversation rewind left native state indeterminate" }
         : providerError(error, "OMP conversation rewind failed");
@@ -2924,7 +2945,13 @@ export class OmpProviderSession {
 
   private async recoverRuntime(): Promise<void> {
     if (!this.runtimeDead) return;
-    this.recoveryPromise ??= this.startRecovery();
+    this.recoveryPromise ??= this.startRecovery().catch((error) => {
+      this.recordOperationalFailure({
+        category: "replay-recovery",
+        stage: "runtime-recovery",
+      });
+      throw error;
+    });
     try {
       await this.recoveryPromise;
     } finally {
@@ -3147,6 +3174,10 @@ export class OmpProviderSession {
       try {
         this.subsessions?.handle(event);
       } catch {
+        this.recordOperationalFailure({
+          category: "tool-projector",
+          stage: "subsession-projector",
+        });
         this.handleRuntimeFailure("OMP subagent event processing failed");
       }
       return;
@@ -3381,6 +3412,10 @@ export class OmpProviderSession {
       try {
         this.subsessions?.observeSessionEvent(this.id, event);
       } catch {
+        this.recordOperationalFailure({
+          category: "tool-projector",
+          stage: "subsession-projector",
+        });
         this.handleRuntimeFailure("OMP subagent dispatch tracking failed");
         return;
       }
@@ -3437,7 +3472,15 @@ export class OmpProviderSession {
       }
     }
     if (isNativeTurnActivity(event)) this.markAgentEvidence(turn);
-    this.projector.project(event, turn.turnId);
+    try {
+      this.projector.project(event, turn.turnId);
+    } catch (error) {
+      this.recordOperationalFailure({
+        category: "tool-projector",
+        stage: "timeline-projector",
+      });
+      throw error;
+    }
     if (event.type === "tool_execution_end") this.resumeDeferredAgentEnd();
   }
 
@@ -4506,11 +4549,13 @@ export class OmpProviderSession {
     const state = await this.boundedTerminalState(turn, FINAL_USAGE_WAIT_MS);
     if (turn.terminal || this.activeTurn !== turn || turn.deferredAgentEnd !== candidate) return;
     if (!state) {
+      turn.operationalTerminalStage = "unresolved";
       this.handleRuntimeFailure("OMP agent_end state could not be confirmed");
       return;
     }
     turn.deferredAgentEnd = undefined;
     if (state.isStreaming || state.isCompacting) return;
+    turn.operationalTerminalStage = "unresolved";
     await this.finishTurn(turn, "failed", {
       message: "OMP unkeyed agent_end could not be correlated to the current prompt",
     });
@@ -4591,6 +4636,7 @@ export class OmpProviderSession {
       ) {
         void this.completeAgentEnd(turn, candidate.event);
       } else {
+        turn.operationalTerminalStage = "unresolved";
         this.handleRuntimeFailure("OMP agent_end state could not be confirmed");
       }
     }, AGENT_END_SETTLE_MS);
@@ -4615,6 +4661,10 @@ export class OmpProviderSession {
     turn.terminalizing = false;
     turn.deferredAgentEnd = candidate;
     void this.subsessions.reconcile(this.runtime).catch(() => {
+      this.recordOperationalFailure({
+        category: "tool-projector",
+        stage: "subsession-projector",
+      });
       if (!turn.terminal && this.activeTurn === turn) {
         this.subsessions?.terminalize("failed");
         this.resumeDeferredAgentEnd();
@@ -4700,6 +4750,7 @@ export class OmpProviderSession {
       return;
     }
     if (turn.userEchoObserved) {
+      turn.operationalTerminalStage = "unresolved";
       this.handleRuntimeFailure("OMP agent_end state could not be confirmed");
       return;
     }
@@ -4759,6 +4810,7 @@ export class OmpProviderSession {
       await this.finishTurn(turn, "completed");
       return;
     }
+    turn.operationalTerminalStage = outcome === "failed" ? "failed" : "unresolved";
     const error =
       outcome === "failed" ? "OMP assistant turn failed" : unknownTerminalOutcomeError(event, turn);
     this.subsessions?.terminalize("failed");
@@ -4901,6 +4953,12 @@ export class OmpProviderSession {
           usageSampled: true,
         };
       }
+      if (outcome.state === "failed") {
+        this.recordOperationalFailure({
+          category: "terminal-outcome",
+          stage: turn.operationalTerminalStage ?? "failed",
+        });
+      }
       this.imageMaterializer.clear();
       turn.terminal = true;
       if (this.usageSample?.turn === turn) this.usageSample = null;
@@ -4914,7 +4972,15 @@ export class OmpProviderSession {
       }
       this.publishPendingUsers(turn);
       this.resolveTurnPermissions(turn.turnId);
-      this.projector.finishTurn(turn.turnId, preserveCompactions);
+      try {
+        this.projector.finishTurn(turn.turnId, preserveCompactions);
+      } catch (error) {
+        this.recordOperationalFailure({
+          category: "tool-projector",
+          stage: "timeline-projector",
+        });
+        throw error;
+      }
       this.unclaimedBranchEntries.length = 0;
       this.emit({
         type: "session.turn",
@@ -4972,6 +5038,7 @@ export class OmpProviderSession {
     this.publishPromptResult(turn, { type: "failed", error: { message } });
     if (turn.started) void this.finishTurn(turn, "failed", { message }, true, true);
     else {
+      this.recordOperationalFailure({ category: "terminal-outcome", stage: "failed" });
       turn.steerReady.resolve();
       turn.terminal = true;
       this.projector.finishTurn(turn.turnId);

package/server/support-diagnostics.ts

@@ -0,0 +1,284 @@
+import { arch, platform } from "node:os";
+import type { RpcInput } from "@getpaseo/plugin";
+import { z } from "zod";
+import type { OmpProviderHealth, OmpVersion } from "../shared/provider-diagnostics";
+import {
+  type getOmpSupportReport,
+  OMP_SUPPORT_REPORT_MAX_BYTES,
+  OMP_SUPPORT_REPORT_SCHEMA_VERSION,
+  supportReportByteLength,
+} from "../shared/support-diagnostics";
+import type {
+  OmpOperationalFailureCollector,
+  OmpOperationalFailureSummary,
+} from "./operational-failure-diagnostics";
+import { PASEO_OMP_PACKAGE_VERSION } from "./package-version";
+import type {
+  OmpProtocolViolationCollector,
+  OmpProtocolViolationSummary,
+} from "./protocol-violation-diagnostics";
+import { resolveGetOmpProviderHealth } from "./provider-diagnostics";
+
+const PACKAGE_VERSION = z
+  .string()
+  .regex(/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]{1,48})?$/u)
+  .max(64);
+const NODE_VERSION = z
+  .string()
+  .regex(/^v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]{1,48})?$/u)
+  .max(64);
+const KNOWN_PLATFORMS: Record<string, true> = {
+  aix: true,
+  android: true,
+  darwin: true,
+  freebsd: true,
+  linux: true,
+  openbsd: true,
+  sunos: true,
+  win32: true,
+};
+const KNOWN_ARCHITECTURES: Record<string, true> = {
+  arm: true,
+  arm64: true,
+  ia32: true,
+  loong64: true,
+  mips: true,
+  mipsel: true,
+  ppc: true,
+  ppc64: true,
+  riscv64: true,
+  s390: true,
+  s390x: true,
+  x64: true,
+};
+
+export interface OmpSupportReportData {
+  collectedAt: string;
+  pluginVersion: string;
+  platform: string;
+  architecture: string;
+  nodeVersion: string;
+  scope: "global" | "workspace";
+  store: "default" | "named-profile" | "custom-directory";
+  health: OmpProviderHealth | null;
+  violations: readonly OmpProtocolViolationSummary[];
+  operationalFailures: readonly OmpOperationalFailureSummary[];
+}
+
+const EXPECTATION_LABELS: Record<
+  NonNullable<OmpProtocolViolationSummary["latestExpected"]>,
+  string
+> = {
+  "complete-json-line": "newline-terminated JSON frame",
+  "within-byte-limit": "byte length within negotiated limit",
+  "valid-json": "valid UTF-8 JSON",
+  "object-envelope": "JSON object envelope",
+  "bounded-frame-type": "frame type string up to 64 bytes",
+  "valid-response-frame": "valid response envelope",
+  "valid-ready-frame": "valid ready handshake",
+  "single-ready-frame": "one ready handshake",
+  "valid-event-frame": "valid event payload",
+  "valid-event-state-transition": "event valid for current stream state",
+  "valid-message-event": "valid message event payload",
+  "valid-tool-event": "valid tool event payload",
+  "valid-lifecycle-event": "valid lifecycle event payload",
+  "valid-subagent-event": "valid subagent event payload",
+  "valid-configuration-event": "valid configuration event payload",
+  "valid-extension-ui-event": "valid extension UI event payload",
+  "known-event-type": "supported event type",
+  "notice-level-enum": "info, warning, or error",
+  "notice-message-string": "bounded string",
+  "valid-chunk-frame": "valid chunk metadata",
+  "valid-base64-chunk": "valid base64 chunk",
+  "first-chunk-index-zero": "first chunk index 0",
+  "contiguous-chunk-sequence": "contiguous chunk sequence",
+  "declared-chunk-byte-count": "decoded bytes equal declared byte length",
+  "chunk-before-deadline": "next chunk before timeout",
+  "no-interleaved-frame": "no interleaved frame during chunk assembly",
+  "no-remote-frame-error": "no remote frame error",
+};
+
+function finiteCount(value: number | null | undefined, maximum = Number.MAX_SAFE_INTEGER): string {
+  return value !== null && value !== undefined && Number.isSafeInteger(value) && value >= 0
+    ? String(Math.min(value, maximum))
+    : "unknown";
+}
+
+function usefulReportLine(line: string): boolean {
+  return !line.endsWith(": unavailable") && !line.endsWith(": unknown") && !line.endsWith(": 0");
+}
+
+function formatVersion(version: OmpVersion | null): string {
+  if (!version) return "unavailable";
+  const core = `${version.major}.${version.minor}.${version.patch}`;
+  return version.prerelease ? `${core}-${version.prerelease}` : core;
+}
+
+function formatHealth(health: OmpProviderHealth | null): string[] {
+  if (!health) return ["collection.provider_health: failed"];
+  return [
+    "collection.provider_health: complete",
+    `omp.installed: ${health.binary.installed}`,
+    `omp.version: ${formatVersion(health.binary.version)}`,
+    `omp.version_probe: ${health.binary.versionStatus}`,
+    `omp.process_cleanup: ${health.binary.processCleanupFailed ? "failed" : "ok"}`,
+    `compatibility.rpc_ui: ${!health.rpcUi.checked || health.rpcUi.supported === null ? "unknown" : health.rpcUi.supported ? "supported" : "not-advertised"}`,
+    `compatibility.lsp: ${health.lsp.status}`,
+    `mcp.status: ${health.mcp.status}`,
+    `mcp.server_count: ${finiteCount(health.mcp.serverCount, 4_096)}`,
+    `mcp.reason: ${health.mcp.reason ?? "unknown"}`,
+    `storage.agent_root: ${health.roots.agentRootState}`,
+    `storage.config: ${health.roots.configState}`,
+    `storage.session_root: ${health.roots.sessionRootState}`,
+    `storage.agent_database: ${health.databases.agentDbState}`,
+    `storage.history_database: ${health.databases.historyDbState}`,
+    `storage.memory_backend: ${health.memoryBackend ?? "unknown"}`,
+    `hub.status: ${health.process.status}`,
+    `hub.tracked_count: ${finiteCount(health.process.trackedCount, 100_000)}`,
+    `hub.active_count: ${finiteCount(health.process.activeCount, 100_000)}`,
+    `hub.historical_count: ${finiteCount(health.process.historicalCount, 100_000)}`,
+    `hub.unknown_count: ${finiteCount(health.process.unknownCount, 100_000)}`,
+  ];
+}
+
+/** Stable line ordering is part of the pasted support-report contract. */
+export function formatOmpSupportReport(data: OmpSupportReportData): string {
+  const lines = [
+    "OMP support diagnostics",
+    `schema_version: ${OMP_SUPPORT_REPORT_SCHEMA_VERSION}`,
+    `collected_at_utc: ${data.collectedAt}`,
+    `paseo_omp.version: ${data.pluginVersion}`,
+    `runtime.platform: ${data.platform}`,
+    `runtime.architecture: ${data.architecture}`,
+    `runtime.node: ${data.nodeVersion}`,
+    `selection.scope: ${data.scope}`,
+    `selection.store: ${data.store}`,
+    "selection.applies_to: provider-health",
+    "diagnostic_counters.scope: plugin-process-all-stores-workspaces",
+    "diagnostic_counters.lifetime: since-plugin-load",
+    ...formatHealth(data.health),
+  ];
+  for (const violation of data.violations) {
+    if (violation.occurrenceCount === 0) continue;
+    const prefix = `protocol.${violation.category}`;
+    lines.push(
+      `${prefix}.occurrence_count: ${finiteCount(violation.occurrenceCount)}`,
+      `${prefix}.batch_count: ${finiteCount(violation.batchCount)}`,
+      `${prefix}.max_batch_count: ${finiteCount(violation.maxOccurrenceCount)}`,
+    );
+    for (const [reason, count] of Object.entries(violation.reasonCounts)) {
+      if (count > 0) lines.push(`${prefix}.reason.${reason}.occurrence_count: ${count}`);
+    }
+    lines.push(
+      `${prefix}.latest_reason: ${violation.latestReason ?? "unknown"}`,
+      `${prefix}.latest_phase: ${violation.latestPhase ?? "unknown"}`,
+      `${prefix}.latest_event_type: ${violation.latestEventType ?? "unknown"}`,
+      `${prefix}.first_at_utc: ${violation.firstAt ?? "unavailable"}`,
+      `${prefix}.last_at_utc: ${violation.lastAt ?? "unavailable"}`,
+      `${prefix}.latest_frame_type: ${violation.latestFrameType ?? "unknown"}`,
+      `${prefix}.latest_field: ${violation.latestField ?? "unknown"}`,
+      `${prefix}.latest_expected: ${violation.latestExpected ? EXPECTATION_LABELS[violation.latestExpected] : "unknown"}`,
+      `${prefix}.latest_actual_type: ${violation.latestActualType ?? "unknown"}`,
+      `${prefix}.max_byte_size: ${finiteCount(violation.maxByteSize)}`,
+      `${prefix}.latest_limit_bytes: ${finiteCount(violation.latestLimitBytes)}`,
+    );
+  }
+  for (const failure of data.operationalFailures) {
+    if (failure.occurrenceCount === 0) continue;
+    const prefix = `operational.${failure.category}.${failure.stage}`;
+    lines.push(
+      `${prefix}.occurrence_count: ${finiteCount(failure.occurrenceCount)}`,
+      `${prefix}.first_at_utc: ${failure.firstAt ?? "unavailable"}`,
+      `${prefix}.last_at_utc: ${failure.lastAt ?? "unavailable"}`,
+    );
+  }
+  const report = `${lines.filter(usefulReportLine).join("\n")}\n`;
+  if (supportReportByteLength(report) > OMP_SUPPORT_REPORT_MAX_BYTES) {
+    return [
+      "OMP support diagnostics",
+      `schema_version: ${OMP_SUPPORT_REPORT_SCHEMA_VERSION}`,
+      `collected_at_utc: ${data.collectedAt}`,
+      "collection_status: failed",
+      "collection_error: report-size-limit",
+      "",
+    ].join("\n");
+  }
+  return report;
+}
+
+function collectedAt(now: () => Date): string {
+  try {
+    const value = now();
+    return Number.isFinite(value.getTime()) ? value.toISOString() : "unavailable";
+  } catch {
+    return "unavailable";
+  }
+}
+
+export async function resolveGetOmpSupportReport(
+  input: RpcInput<typeof getOmpSupportReport>,
+  violations: OmpProtocolViolationCollector,
+  operationalFailures: OmpOperationalFailureCollector,
+  dependencies: {
+    loadHealth?: typeof resolveGetOmpProviderHealth;
+    loadPluginVersion?: () => Promise<string>;
+    now?: () => Date;
+    platform?: () => string;
+    architecture?: () => string;
+    nodeVersion?: string;
+  } = {},
+): Promise<{ report: string }> {
+  const timestamp = collectedAt(dependencies.now ?? (() => new Date()));
+  try {
+    const [healthResult, pluginVersionResult] = await Promise.allSettled([
+      (dependencies.loadHealth ?? resolveGetOmpProviderHealth)(input),
+      (dependencies.loadPluginVersion ?? (() => Promise.resolve(PASEO_OMP_PACKAGE_VERSION)))(),
+    ]);
+    const platformValue = (dependencies.platform ?? platform)();
+    const architectureValue = (dependencies.architecture ?? arch)();
+    const nodeVersionValue = dependencies.nodeVersion ?? process.version;
+    return {
+      report: formatOmpSupportReport({
+        collectedAt: timestamp,
+        pluginVersion:
+          pluginVersionResult.status === "fulfilled" &&
+          PACKAGE_VERSION.safeParse(pluginVersionResult.value).success
+            ? pluginVersionResult.value
+            : "unavailable",
+        platform: KNOWN_PLATFORMS[platformValue] ? platformValue : "unknown",
+        architecture: KNOWN_ARCHITECTURES[architectureValue] ? architectureValue : "unknown",
+        nodeVersion: NODE_VERSION.safeParse(nodeVersionValue).success
+          ? nodeVersionValue
+          : "unavailable",
+        scope: input.cwd ? "workspace" : "global",
+        store: input.store?.profile
+          ? "named-profile"
+          : input.store?.agentDir
+            ? "custom-directory"
+            : "default",
+        health: healthResult.status === "fulfilled" ? healthResult.value : null,
+        violations: violations.snapshot(),
+        operationalFailures: operationalFailures.snapshot(),
+      }),
+    };
+  } catch {
+    return {
+      report: formatOmpSupportReport({
+        collectedAt: timestamp,
+        pluginVersion: "unavailable",
+        platform: "unknown",
+        architecture: "unknown",
+        nodeVersion: "unavailable",
+        scope: input.cwd ? "workspace" : "global",
+        store: input.store?.profile
+          ? "named-profile"
+          : input.store?.agentDir
+            ? "custom-directory"
+            : "default",
+        health: null,
+        violations: violations.snapshot(),
+        operationalFailures: operationalFailures.snapshot(),
+      }),
+    };
+  }
+}

package/shared/support-diagnostics.ts

@@ -0,0 +1,32 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+import { OmpWorkspaceCwdSchema } from "./hub";
+import { OmpStoreSchema } from "./omp-store";
+
+export const OMP_SUPPORT_REPORT_SCHEMA_VERSION = 1 as const;
+export const OMP_SUPPORT_REPORT_MAX_BYTES = 64 * 1024;
+export const OMP_SUPPORT_ISSUE_URL =
+  "https://github.com/omercnet/paseo-plugins/issues/new?template=omp-plugin.yml";
+
+export function supportReportByteLength(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+export const OmpSupportReportTextSchema = z
+  .string()
+  .min(1)
+  .refine((value) => supportReportByteLength(value) <= OMP_SUPPORT_REPORT_MAX_BYTES, {
+    message: "OMP support report exceeds 64 KiB",
+  });
+
+export const getOmpSupportReport = defineRpc({
+  name: "paseo-omp.get-support-report",
+  input: z
+    .object({
+      store: OmpStoreSchema.optional(),
+      force: z.boolean().optional(),
+      cwd: OmpWorkspaceCwdSchema.optional(),
+    })
+    .strict(),
+  output: z.object({ report: OmpSupportReportTextSchema }).strict(),
+});