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

package/README.md

@@ -4,16 +4,30 @@ Community OMP integration for Paseo. The plugin registers the distinct `omp-plug
 
 > **Alpha preview:** persistence and protocol contracts are tested, but upgrades may still require re-importing sessions created by an earlier preview.
 
+## Screenshots
+
+Both PNGs come from the plugin's isolated Paseo development daemon at 2× pixel density. Browser
+DevTools rewrites local filesystem paths and verifies that no private organization names remain
+before capture.
+
+### Native plugin manager
+
+![OMP native plugin manager](https://raw.githubusercontent.com/omercnet/paseo-plugins/main/paseo-omp/docs/images/plugin-manager.png)
+
+### Typed OMP configuration
+
+![OMP typed configuration editor](https://raw.githubusercontent.com/omercnet/paseo-plugins/main/paseo-omp/docs/images/workspace-settings.png)
+
 ## Quick start
 
-Requirements: Paseo `>=0.8.0 <0.10.0`, OMP `18.1.15` or newer, and OMP RPC protocol v2. Paseo `0.9.0-beta.1` or newer is required for nested provider-subagent ancestry and spawning-tool links, and is recommended for npm-managed installation and the complete client integration.
+Requirements: Paseo `>=0.9.0-beta.1 <0.10.0`, OMP `18.1.15` or newer, and OMP RPC protocol v2. Paseo 0.9 is required for the Help report's supported copy and external-link APIs, nested provider-subagent ancestry, spawning-tool links, npm-managed installation, and the complete client integration.
 
 ```bash
 paseo plugin install npm:@omercnet/paseo-omp@<version>
 paseo plugin ls paseo-omp
 ```
 
-Open the **OMP** sidebar to review the provider-profile contract, choose which composer pills appear, browse and edit native scalar settings, manage OMP-native plugins, verify runtime health, and inspect storage and process diagnostics. Then create an agent and select **OMP Plugin**. Its optional **MCP** composer control runs OMP-native management commands in the current session; setup questions and authorization stay in that chat timeline, where OAuth can open in a workspace-scoped Paseo Browser or on the current device. Composer pill preferences are shared by clients connected to the same host; normal use requires no other plugin-specific settings.
+Open the **OMP** sidebar to review the provider-profile contract, choose which composer pills appear, browse and edit native scalar settings, manage OMP-native plugins, verify runtime health, and generate a bounded support report under **Help**. The same tabs are available in the workspace OMP panel, except for the global Composer preference tab. Then create an agent and select **OMP Plugin**. Its optional **MCP** composer control runs OMP-native management commands in the current session; setup questions and authorization stay in that chat timeline, where OAuth can open in a workspace-scoped Paseo Browser or on the current device. Composer pill preferences are shared by clients connected to the same host; normal use requires no other plugin-specific settings.
 
 - [Install, update, rollback, and local development](docs/installation.md)
 - [Configuration and every provider option](docs/configuration.md)
@@ -22,13 +36,13 @@ Open the **OMP** sidebar to review the provider-profile contract, choose which c
 - [Core-provider issue and parity audit](docs/core-provider-issue-audit.md)
 - [Alpha release checklist](docs/alpha-release-checklist.md)
 
-The plugin uses public Paseo 0.8 and 0.9 beta provider contracts and registers distinct `omp-plugin` and `omp-plugin-<profile>` identities; it does not modify the bundled `omp` provider.
+The plugin uses public Paseo 0.9 beta provider and client contracts and registers distinct `omp-plugin` and `omp-plugin-<profile>` identities; it does not modify the bundled `omp` provider.
 
 ## Named OMP profiles
 
 At startup the plugin discovers directory names under `~/.omp/profiles/` (or `PI_CONFIG_DIR`) and registers **OMP · <profile>** for each valid lowercase name. Select that provider when creating a profile-backed agent. Discovery, launch, recovery and persisted session listing share its fixed profile and session root. Matching command wrappers, including Doppler, remain supported; conflicting profile or session-directory overrides fail before launch. Plain `env NAME=value omp` wrappers are supported, but environment-control flags such as `env -i` and `env -u` are rejected because they can discard the selected store. Profile-specific XDG roots cannot be overridden by per-launch environment values. Reload the plugin after adding a profile.
 
-Paseo 0.8 does not pass agent launch options to its model picker. Separate provider identities let the picker request the correct profile catalog before an agent exists. Existing `omp-plugin` and bundled `omp` agents retain their provider; they are not migrated automatically. Profile names use OMP's lowercase grammar, including dotted names such as `team.prod`.
+Separate provider identities let the model picker request the correct profile catalog before an agent exists. Existing `omp-plugin` and bundled `omp` agents retain their provider; they are not migrated automatically. Profile names use OMP's lowercase grammar, including dotted names such as `team.prod`.
 
 The OMP sidebar and memory panel expose an explicit store selector. Settings, plugins, quota, history, memory and diagnostics use that selection, and profile-agent popovers derive it from the provider ID. OMP-compatible XDG data and state roots are honored when a migrated profile uses them. Default-provider views are labelled **Daemon default store**; changing `providerOptions.command` on the default provider does not make those views profile-aware. Workspace configuration remains project-scoped, with the selected profile supplying inherited settings. Hub records are daemon-wide. The RPCs also accept an explicit absolute `store.agentDir` for custom stores; it is mutually exclusive with `store.profile`.
 
@@ -99,7 +113,7 @@ Existing agents whose provider is `omp` remain owned by the bundled provider. Ne
 
 OMP `18.1.15` is the oldest version tested end to end. The direct provider's hard compatibility gate is `rpc-ui` protocol v2: metadata-free legacy ready frames and v1-only runtimes are rejected before a provider session opens because they cannot support the advertised persistence and conversation-rewind capabilities. Typed tool approvals remain capability-gated and fall back as described above. For terminal completion, a matching `agent_end.requestId` is authoritative and mismatches are ignored before state changes. Released OMP 18.2.x builds that omit that field use an ordered fallback requiring a fresh correlated native user entry followed by current-turn assistant activity, an idle non-compacting runtime, and no conflicting permission, tool, steer, or child-session work. Ambiguous events while OMP is active are ignored; unresolved ambiguity after confirmed idle fails only the Paseo turn. This trades a bounded residual same-agent stale-event risk for compatibility with released OMP instead of terminating and lazily restarting the runtime after every later prompt. Paseo clients, including mobile clients inside reconnect grace, do not own or terminate the daemon-managed OMP session.
 
-Paseo 0.9.0-beta.1 is the verified canary target and the first release that preserves nested provider-subagent ancestry and spawning-tool links. The required full Docker canary passes there with OMP 18.1.15 and 18.2.0. Paseo 0.9 also provides npm-managed plugin sources, platform-owned external URL opening, and whole-item timeline transforms before Overview grouping. Paseo 0.8.x remains supported for other provider operations and Git or directory installation; its clients do not provide the external URL opener, retain their older timeline presentation semantics, and flatten nested provider subagents.
+Paseo 0.9.0-beta.1 is the verified canary target and minimum supported release. It preserves nested provider-subagent ancestry and spawning-tool links, and provides npm-managed plugin sources, platform-owned external URL opening, and whole-item timeline transforms before Overview grouping. The required full Docker canary passes there with OMP 18.1.15 and 18.2.0.
 
 Install, update, disable, or remove `paseo-omp` independently of the bundled provider. Verify the provider snapshot contains `omp-plugin` after installation; a bundled `omp` entry may remain present and is not modified by this plugin.
 

package/client/omp-config-surface.tsx

@@ -5,7 +5,8 @@ import {
   useRpc,
   useWorkspace,
 } from "@getpaseo/plugin/client";
-import { Icon, TextInput } from "@getpaseo/plugin/client/react-native";
+import { copyText, Icon, TextInput } from "@getpaseo/plugin/client/react-native";
+import { ExternalLink } from "@getpaseo/plugin/client/ui";
 import { useIsMutating, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import type { ReactNode } from "react";
 import { useCallback, useMemo, useState } from "react";
@@ -27,8 +28,10 @@ import {
 } from "../shared/omp-settings";
 import { type OmpStore, storeLabel } from "../shared/omp-store";
 import { getOmpProviderHealth, type OmpProviderHealth } from "../shared/provider-diagnostics";
+import { getOmpSupportReport, OMP_SUPPORT_ISSUE_URL } from "../shared/support-diagnostics";
 import { ComposerPillSettingsSection } from "./composer-pill-settings";
 import { openOmpExternalUrl } from "./external-url";
+import { type OmpConfigSurfaceView as SurfaceView, surfaceViewsForScope } from "./omp-config-views";
 import {
   documentationForSettingCategory,
   documentationForSettingPath,
@@ -60,6 +63,11 @@ import {
   summarizeProviderStatus,
   summarizeRpcUiSupport,
 } from "./provider-diagnostics-state";
+import {
+  refreshSupportReport,
+  type SupportReportCopyState,
+  supportDiagnosticsViewState,
+} from "./support-diagnostics-state";
 
 const SETTINGS_QUERY_KEY = ["paseo-omp", "settings"] as const;
 const CONFIG_POLL_MS = 30_000;
@@ -95,6 +103,10 @@ export interface OmpConfigStyles {
   docLinkPressed: ViewStyle;
   docLinkText: TextStyle;
   refreshLabel: TextStyle;
+  helpActions: ViewStyle;
+  helpReport: ViewStyle;
+  helpReportText: TextStyle;
+  helpLinkText: TextStyle;
   card: ViewStyle;
   cardHeader: ViewStyle;
   cardTitle: TextStyle;
@@ -219,6 +231,26 @@ function useConfigStyles(theme: PluginSurfaceProps["theme"], compact: boolean):
         backgroundColor: theme.colors.surface1,
       },
       refreshLabel: { color: theme.colors.foreground, fontSize: 13 },
+      helpActions: {
+        flexDirection: "row",
+        alignItems: "center",
+        flexWrap: "wrap",
+        gap: 8,
+      },
+      helpReport: {
+        maxWidth: "100%",
+        padding: compact ? 10 : 12,
+        borderWidth: 1,
+        borderColor: theme.colors.border,
+        borderRadius: 10,
+        backgroundColor: theme.colors.surface1,
+      },
+      helpReportText: {
+        color: theme.colors.foreground,
+        fontSize: compact ? 11 : 12,
+        lineHeight: compact ? 16 : 18,
+      },
+      helpLinkText: { color: theme.colors.accent, fontSize: 13, fontWeight: "600" },
       cardHeader: {
         flexDirection: "row",
         alignItems: "center",
@@ -695,6 +727,131 @@ function ProviderHealthSection({
   );
 }
 
+function SupportDiagnosticsSection({
+  theme,
+  styles,
+  cwd,
+  store,
+}: {
+  theme: PluginSurfaceProps["theme"];
+  styles: OmpConfigStyles;
+  cwd?: string;
+  store?: OmpStore;
+}) {
+  const loadReport = useRpc(getOmpSupportReport);
+  const queryClient = useQueryClient();
+  const context = { store, ...(cwd ? { cwd } : {}) };
+  const queryKey = ["paseo-omp", "support-report", ompStoreKey(store), cwd ?? "global"];
+  const report = useQuery({
+    queryKey,
+    queryFn: () => loadReport(context),
+    staleTime: Number.POSITIVE_INFINITY,
+    retry: false,
+  });
+  const refreshReport = useMutation({
+    mutationFn: () => refreshSupportReport(loadReport, context),
+    onSuccess: (value) => queryClient.setQueryData(queryKey, value),
+  });
+  const [copyState, setCopyState] = useState<SupportReportCopyState>("idle");
+  const [linkError, setLinkError] = useState(false);
+  const viewState = supportDiagnosticsViewState({
+    loading: report.isLoading,
+    refreshing: refreshReport.isPending || (report.isFetching && !report.isLoading),
+    hasReport: Boolean(report.data?.report),
+    reportFailed: Boolean(report.error || refreshReport.error),
+    copyState,
+  });
+
+  const refresh = () => {
+    setCopyState("idle");
+    refreshReport.mutate();
+  };
+  const copyReport = async () => {
+    if (!report.data?.report) return;
+    setCopyState("copying");
+    try {
+      await copyText(report.data.report);
+      setCopyState("copied");
+    } catch {
+      setCopyState("error");
+    }
+  };
+
+  return (
+    <>
+      <View style={styles.sectionHeader}>
+        <Text style={styles.sectionTitle}>Support diagnostics</Text>
+        <Text style={styles.muted}>
+          Safe OMP runtime, compatibility, storage-state, and protocol counters for maintainers.
+        </Text>
+      </View>
+      <View style={styles.helpActions}>
+        <Pressable
+          accessibilityRole="button"
+          accessibilityLabel="Refresh OMP support report"
+          disabled={report.isFetching || refreshReport.isPending}
+          onPress={refresh}
+          style={styles.refresh}
+        >
+          <Icon name="RefreshCw" size={14} color={theme.colors.foreground} />
+          <Text style={styles.refreshLabel}>{viewState.refreshLabel}</Text>
+        </Pressable>
+        <Pressable
+          accessibilityRole="button"
+          accessibilityLabel="Copy OMP support report"
+          disabled={viewState.copyDisabled}
+          onPress={() => void copyReport()}
+          style={[styles.refresh, viewState.copyDisabled ? { opacity: 0.55 } : null]}
+        >
+          <Icon name="Copy" size={14} color={theme.colors.foreground} />
+          <Text style={styles.refreshLabel}>{viewState.copyLabel}</Text>
+        </Pressable>
+        <ExternalLink
+          href={OMP_SUPPORT_ISSUE_URL}
+          accessibilityLabel="Create paseo-omp GitHub issue"
+          onError={() => setLinkError(true)}
+        >
+          <Text style={styles.helpLinkText}>Create GitHub issue</Text>
+        </ExternalLink>
+      </View>
+      <Text style={styles.muted}>
+        Review before sharing. The report excludes prompts, transcripts, credentials, commands,
+        URLs, repository names, and private paths.
+      </Text>
+      {viewState.loadingMessage ? (
+        <Text accessibilityLiveRegion="polite" style={styles.muted}>
+          {viewState.loadingMessage}
+        </Text>
+      ) : null}
+      {viewState.reportError ? (
+        <Text accessibilityRole="alert" style={styles.error}>
+          {viewState.reportError}
+        </Text>
+      ) : null}
+      {viewState.copyFeedback ? (
+        <Text
+          accessibilityLiveRegion="polite"
+          style={copyState === "error" ? styles.error : styles.muted}
+        >
+          {viewState.copyFeedback}
+        </Text>
+      ) : null}
+      {linkError ? (
+        <Text accessibilityRole="alert" style={styles.error}>
+          Could not open GitHub. Copy the report and open the issue tracker manually.
+        </Text>
+      ) : null}
+      {report.data?.report ? (
+        <View style={styles.helpReport}>
+          <Text selectable style={styles.helpReportText}>
+            {report.data.report}
+          </Text>
+        </View>
+      ) : null}
+    </>
+  );
+}
+
 const CATEGORY_LABELS: Record<OmpSettingCategory, string> = {
   appearance: "Appearance",
   model: "Model",
@@ -740,16 +897,6 @@ function fallbackSettingsFromConfig(config: OmpConfig | null | undefined): OmpSe
   return settings;
 }
 
-type SurfaceView = "overview" | "plugin" | "plugins" | "composer" | "configuration" | "diagnostics";
-const SURFACE_VIEWS: readonly { id: SurfaceView; label: string }[] = [
-  { id: "overview", label: "Overview" },
-  { id: "plugin", label: "Plugin" },
-  { id: "plugins", label: "OMP plugins" },
-  { id: "composer", label: "Composer" },
-  { id: "configuration", label: "Configuration" },
-  { id: "diagnostics", label: "Diagnostics" },
-];
-
 function formatScalarValue(value: unknown): string {
   if (value === undefined || value === null) return "Not set";
   if (typeof value === "boolean") return value ? "Enabled" : "Disabled";
@@ -1079,9 +1226,7 @@ function OmpConfigContent({
   const [documentationError, setDocumentationError] = useState<string | null>(null);
   const styles = useConfigStyles(theme, layout.compact);
   const normalizedSearch = search.trim().toLocaleLowerCase();
-  const surfaceViews = cwd
-    ? SURFACE_VIEWS.filter((candidate) => candidate.id !== "composer")
-    : SURFACE_VIEWS;
+  const surfaceViews = surfaceViewsForScope(cwd !== undefined);
   const catalog = useMemo(() => {
     const sourceSettings = settingsQuery.data?.available
       ? settingsQuery.data.settings
@@ -1271,6 +1416,10 @@ function OmpConfigContent({
         <ProviderHealthSection theme={theme} styles={styles} cwd={cwd} store={store} />
       ) : null}
 
+      {view === "help" ? (
+        <SupportDiagnosticsSection theme={theme} styles={styles} cwd={cwd} store={store} />
+      ) : null}
+
       {view === "configuration" ? (
         <>
           <View style={styles.sectionHeader}>

package/client/omp-config-views.ts

@@ -0,0 +1,24 @@
+export type OmpConfigSurfaceView =
+  | "overview"
+  | "plugin"
+  | "plugins"
+  | "composer"
+  | "configuration"
+  | "diagnostics"
+  | "help";
+
+const SURFACE_VIEWS: readonly { id: OmpConfigSurfaceView; label: string }[] = [
+  { id: "overview", label: "Overview" },
+  { id: "plugin", label: "Plugin" },
+  { id: "plugins", label: "OMP plugins" },
+  { id: "composer", label: "Composer" },
+  { id: "configuration", label: "Configuration" },
+  { id: "diagnostics", label: "Diagnostics" },
+  { id: "help", label: "Help" },
+];
+
+export function surfaceViewsForScope(workspaceScoped: boolean) {
+  return workspaceScoped
+    ? SURFACE_VIEWS.filter((candidate) => candidate.id !== "composer")
+    : SURFACE_VIEWS;
+}

package/client/support-diagnostics-state.ts

@@ -0,0 +1,45 @@
+import type { OmpStore } from "../shared/omp-store";
+
+type SupportReportInput = { store?: OmpStore; cwd?: string; force?: boolean };
+type SupportReportOutput = { report: string };
+
+export async function refreshSupportReport(
+  loadReport: (input: SupportReportInput) => Promise<SupportReportOutput>,
+  input: Omit<SupportReportInput, "force">,
+): Promise<SupportReportOutput> {
+  return await loadReport({ ...input, force: true });
+}
+
+export type SupportReportCopyState = "idle" | "copying" | "copied" | "error";
+
+export interface SupportDiagnosticsViewState {
+  refreshLabel: string;
+  copyLabel: string;
+  copyDisabled: boolean;
+  loadingMessage: string | null;
+  reportError: string | null;
+  copyFeedback: string | null;
+}
+
+/** Maps request and copy state to the exact accessible feedback rendered by the Help tab. */
+export function supportDiagnosticsViewState(input: {
+  loading: boolean;
+  refreshing: boolean;
+  hasReport: boolean;
+  reportFailed: boolean;
+  copyState: SupportReportCopyState;
+}): SupportDiagnosticsViewState {
+  return {
+    refreshLabel: input.refreshing ? "Refreshing…" : "Refresh",
+    copyLabel: input.copyState === "copying" ? "Copying…" : "Copy report",
+    copyDisabled: !input.hasReport || input.copyState === "copying",
+    loadingMessage: input.loading ? "Collecting OMP diagnostics…" : null,
+    reportError: input.reportFailed ? "Could not collect OMP diagnostics." : null,
+    copyFeedback:
+      input.copyState === "copied"
+        ? "Report copied."
+        : input.copyState === "error"
+          ? "Could not copy. Select the report text and copy it manually."
+          : null,
+  };
+}

package/index.server.ts

@@ -14,7 +14,9 @@ import {
   resolveMutateOmpPluginConfig,
 } from "./server/omp-plugins";
 import { resolveListOmpSettings, resolveUpdateOmpSettings } from "./server/omp-settings";
+import { OmpOperationalFailureCollector } from "./server/operational-failure-diagnostics";
 import { withOmpStore } from "./server/paths";
+import { OmpProtocolViolationCollector } from "./server/protocol-violation-diagnostics";
 import { withOmpWorkspaceIdentity } from "./server/provider/host-tools";
 import {
   createProfileOmpProvider,
@@ -25,6 +27,7 @@ import { createOmpProvider } from "./server/provider/registration";
 import { resolveGetOmpProviderHealth } from "./server/provider-diagnostics";
 import { resolveListOmpQuotas } from "./server/quota";
 import { resolveListOmpSessions } from "./server/sessions";
+import { resolveGetOmpSupportReport } from "./server/support-diagnostics";
 import { composerPillSettings } from "./shared/composer-pill-settings";
 import { listHubProcesses, tailHubLog } from "./shared/hub";
 import { openOmpMcpAuthorizationInPaseoBrowser } from "./shared/mcp";
@@ -42,6 +45,7 @@ import { listOmpStores, type OmpStore } from "./shared/omp-store";
 import { getOmpProviderHealth } from "./shared/provider-diagnostics";
 import { listOmpQuotas } from "./shared/quota";
 import { listOmpSessions } from "./shared/sessions";
+import { getOmpSupportReport } from "./shared/support-diagnostics";
 
 function scoped<T extends { store?: OmpStore }, R>(handler: (input: T) => R) {
   return (input: T): R => withOmpStore(input.store, () => handler(input));
@@ -50,10 +54,18 @@ function scoped<T extends { store?: OmpStore }, R>(handler: (input: T) => R) {
 export default function contribute(server: PluginServerContext) {
   server.registerSettings(composerPillSettings);
   const browserAuthorizationRegistry = new OmpBrowserAuthorizationRegistry();
+  const protocolViolations = new OmpProtocolViolationCollector();
+  const operationalFailures = new OmpOperationalFailureCollector();
   const profiles = discoverOmpProfilesSync();
   server.handle(listOmpStores, async () => ({ profiles: await discoverOmpProfiles() }));
   for (const profile of profiles) {
-    server.registerProvider(createProfileOmpProvider(profile, { browserAuthorizationRegistry }));
+    server.registerProvider(
+      createProfileOmpProvider(profile, {
+        browserAuthorizationRegistry,
+        reportProtocolViolation: protocolViolations.report,
+        reportOperationalFailure: operationalFailures.report,
+      }),
+    );
   }
   server.handle(listHubProcesses, resolveListHubProcesses);
   server.handle(tailHubLog, resolveTailHubLog);
@@ -69,6 +81,10 @@ export default function contribute(server: PluginServerContext) {
   server.handle(listOmpSettings, scoped(resolveListOmpSettings));
   server.handle(updateOmpSettings, scoped(resolveUpdateOmpSettings));
   server.handle(getOmpProviderHealth, scoped(resolveGetOmpProviderHealth));
+  server.handle(
+    getOmpSupportReport,
+    scoped((input) => resolveGetOmpSupportReport(input, protocolViolations, operationalFailures)),
+  );
   server.handle(openOmpMcpAuthorizationInPaseoBrowser, (input) =>
     resolveOpenOmpMcpAuthorizationInPaseoBrowser(input, browserAuthorizationRegistry),
   );
@@ -76,7 +92,13 @@ export default function contribute(server: PluginServerContext) {
     if (request.provider !== "omp-plugin" && !request.provider.startsWith("omp-plugin-")) return;
     return withOmpWorkspaceIdentity(request);
   });
-  server.registerProvider(createOmpProvider({ browserAuthorizationRegistry }));
+  server.registerProvider(
+    createOmpProvider({
+      browserAuthorizationRegistry,
+      reportProtocolViolation: protocolViolations.report,
+      reportOperationalFailure: operationalFailures.report,
+    }),
+  );
   return () => {
     browserAuthorizationRegistry.clear();
     removeIdentityHook();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omercnet/paseo-omp",
-  "version": "0.3.0-next.108.1",
+  "version": "0.3.0-next.111.1",
   "type": "module",
   "description": "Paseo integration for OMP, including its direct provider and workspace tooling.",
   "license": "MIT",
@@ -29,21 +29,15 @@
     "coding-agents"
   ],
   "files": [
-    "package-lock.json",
-    "CHANGELOG.md",
     "LICENSE",
     "README.md",
-    "SUPPORT.md",
-    "TESTING.md",
-    "docs",
     "scripts/prepare-dependencies.mjs",
     "index.client.tsx",
     "index.server.ts",
     "client",
     "server",
     "shared",
-    "paseo-plugin.json",
-    "tsconfig.json"
+    "paseo-plugin.json"
   ],
   "scripts": {
     "check": "biome check .",

package/paseo-plugin.json

@@ -1,5 +1,5 @@
 {
   "id": "paseo-omp",
-  "requirements": { "paseo": ">=0.8.0 <0.10.0" },
+  "requirements": { "paseo": ">=0.9.0-beta.1 <0.10.0" },
   "build": [["node", "scripts/prepare-dependencies.mjs"]]
 }

package/server/operational-failure-diagnostics.ts

@@ -0,0 +1,76 @@
+export const OMP_OPERATIONAL_FAILURES = [
+  { category: "session-open", stage: "startup" },
+  { category: "session-open", stage: "catalog" },
+  { category: "replay-recovery", stage: "persisted-replay" },
+  { category: "replay-recovery", stage: "runtime-recovery" },
+  { category: "replay-recovery", stage: "rewind" },
+  { category: "tool-projector", stage: "host-tool-unknown" },
+  { category: "tool-projector", stage: "host-tool-capacity" },
+  { category: "tool-projector", stage: "host-tool-normalization" },
+  { category: "tool-projector", stage: "host-tool-call" },
+  { category: "tool-projector", stage: "host-tool-timeout" },
+  { category: "tool-projector", stage: "host-tool-delivery" },
+  { category: "tool-projector", stage: "timeline-projector" },
+  { category: "tool-projector", stage: "subsession-projector" },
+  { category: "terminal-outcome", stage: "failed" },
+  { category: "terminal-outcome", stage: "unresolved" },
+] as const;
+
+export type OmpOperationalFailure = (typeof OMP_OPERATIONAL_FAILURES)[number];
+export type OmpOperationalFailureCategory = OmpOperationalFailure["category"];
+export type OmpOperationalFailureStage = OmpOperationalFailure["stage"];
+export type OmpOperationalFailureReporter = (failure: OmpOperationalFailure) => void;
+
+export type OmpOperationalFailureSummary = OmpOperationalFailure & {
+  occurrenceCount: number;
+  firstAt: string | null;
+  lastAt: string | null;
+};
+
+const FAILURE_KEYS: Readonly<Record<string, true>> = Object.fromEntries(
+  OMP_OPERATIONAL_FAILURES.map(({ category, stage }) => [`${category}:${stage}`, true]),
+);
+
+function timestamp(now: () => Date): string | null {
+  try {
+    const value = now();
+    return Number.isFinite(value.getTime()) ? value.toISOString() : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Fixed category/stage cells make aggregation constant-space for one plugin subprocess lifetime. */
+export class OmpOperationalFailureCollector {
+  private readonly summaries = Object.fromEntries(
+    OMP_OPERATIONAL_FAILURES.map(({ category, stage }) => [
+      `${category}:${stage}`,
+      { category, stage, occurrenceCount: 0, firstAt: null, lastAt: null },
+    ]),
+  ) as Record<string, OmpOperationalFailureSummary>;
+
+  constructor(private readonly now: () => Date = () => new Date()) {}
+
+  report: OmpOperationalFailureReporter = (failure) => {
+    try {
+      const key = `${failure.category}:${failure.stage}`;
+      if (!FAILURE_KEYS[key]) return;
+      const summary = this.summaries[key];
+      if (!summary) return;
+      summary.occurrenceCount = Math.min(Number.MAX_SAFE_INTEGER, summary.occurrenceCount + 1);
+      const recordedAt = timestamp(this.now);
+      if (recordedAt) {
+        summary.firstAt ??= recordedAt;
+        summary.lastAt = recordedAt;
+      }
+    } catch {
+      // Diagnostics must never affect provider or session flow.
+    }
+  };
+
+  snapshot(): OmpOperationalFailureSummary[] {
+    return OMP_OPERATIONAL_FAILURES.map(({ category, stage }) => ({
+      ...this.summaries[`${category}:${stage}`],
+    }));
+  }
+}

package/server/package-version.ts

@@ -0,0 +1,2 @@
+/** Release Please keeps this bundle-safe constant aligned with package.json. */
+export const PASEO_OMP_PACKAGE_VERSION = "0.3.0-next.111.1"; // x-release-please-version