@senad-d/observme 0.1.0

package/src/commands/obs-health.ts

@@ -0,0 +1,301 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { LoadSessionConfigOptions } from "../config/load-config.ts";
+import type { ObservMeConfig } from "../config/schema.ts";
+import { readDiagnosticMessage, sanitizeDiagnosticText } from "../diagnostics/sanitize.ts";
+import { getGrafanaHealth, type GrafanaFetch } from "../query/grafana.ts";
+import { completeObsSubcommand, isExactObsSubcommandRequest } from "./obs-args.ts";
+import { loadObsCommandConfig, normalizeObsCommandTimeoutMs, notifyObsCommand } from "./obs-command-support.ts";
+import { appendObsRecoveryHint, formatObsCommandFailure } from "./obs-diagnostics.ts";
+
+export interface ObsHealthCommandContext {
+  readonly cwd?: string;
+  readonly ui: {
+    notify: (message: string, type?: "info" | "warning" | "error") => Promise<void> | void;
+  };
+  readonly isProjectTrusted?: () => boolean | Promise<boolean>;
+}
+
+export type ObsHealthCheckKind = "service" | "datasource";
+export type ObsHealthCheckStatus = "ok" | "failed" | "skipped";
+export type ObsHealthFetch = GrafanaFetch;
+export type ObsHealthConfigLoader = (options: LoadSessionConfigOptions) => Promise<ObservMeConfig>;
+export type ObsHealthProvider = (ctx: ObsHealthCommandContext) => Promise<ObsHealthSnapshot> | ObsHealthSnapshot;
+
+export interface ObsHealthCheckResult {
+  readonly label: string;
+  readonly kind: ObsHealthCheckKind;
+  readonly status: ObsHealthCheckStatus;
+  readonly detail?: string;
+}
+
+export interface ObsHealthSnapshot {
+  readonly timeoutMs: number;
+  readonly checks: readonly ObsHealthCheckResult[];
+}
+
+export interface ObsHealthSnapshotOptions {
+  readonly loadConfig?: ObsHealthConfigLoader;
+  readonly fetch?: ObsHealthFetch;
+  readonly timeoutMs?: number;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly configDirName?: string;
+}
+
+export interface RegisterObsHealthCommandOptions extends ObsHealthSnapshotOptions {
+  readonly getHealth?: ObsHealthProvider;
+}
+
+interface HttpHealthTarget {
+  readonly label: string;
+  readonly kind: ObsHealthCheckKind;
+  readonly url: string;
+  readonly headers?: Record<string, string>;
+  readonly successMode: "ok" | "reachable";
+}
+
+const OBS_COMMAND_NAME = "obs";
+const OBS_HEALTH_SUBCOMMAND = "health";
+const OBS_HEALTH_CONFIG_NEXT_ACTION = "fix ObservMe config, then rerun /obs health.";
+const OBS_HEALTH_COLLECTOR_NEXT_ACTION = "verify the Collector is running and otlp.endpoint is reachable.";
+const OBS_HEALTH_GRAFANA_NEXT_ACTION = "check query.grafana.url and credentials, then rerun /obs health.";
+const OBS_HEALTH_TEMPO_NEXT_ACTION = "check Grafana credentials and query.grafana.datasourceUids.tempo, then rerun /obs health.";
+const OBS_HEALTH_LOKI_NEXT_ACTION = "check Grafana credentials and query.grafana.datasourceUids.loki, then rerun /obs health.";
+const OBS_HEALTH_METRICS_NEXT_ACTION = "check Grafana credentials and query.grafana.datasourceUids.prometheus, then rerun /obs health.";
+export function registerObsHealthCommand(pi: ExtensionAPI, options: RegisterObsHealthCommandOptions = {}): void {
+  const command = new ObsHealthCommand(options);
+
+  pi.registerCommand(OBS_COMMAND_NAME, {
+    description: "Check ObservMe backend health. Usage: /obs health",
+    getArgumentCompletions: getObsHealthCommandArgumentCompletions,
+    handler: command.handle.bind(command),
+  });
+}
+
+export async function handleObsHealthCommand(
+  args: string,
+  ctx: ObsHealthCommandContext,
+  options: RegisterObsHealthCommandOptions = {},
+): Promise<void> {
+  if (!isObsHealthRequest(args)) {
+    await notifyObsCommand(ctx, "Usage: /obs health", "warning");
+    return;
+  }
+
+  try {
+    const snapshot = await resolveObsHealthSnapshot(ctx, options);
+    await notifyObsCommand(ctx, renderObsHealth(snapshot), resolveObsHealthNotificationType(snapshot));
+  } catch (error) {
+    await notifyObsCommand(
+      ctx,
+      formatObsCommandFailure("ObservMe health unavailable", error, {
+        subsystem: "Health configuration",
+        nextAction: OBS_HEALTH_CONFIG_NEXT_ACTION,
+      }),
+      "error",
+    );
+  }
+}
+
+export function getObsHealthCommandArgumentCompletions(prefix: string): Array<{ value: string; label: string }> | null {
+  return completeObsSubcommand(prefix, OBS_HEALTH_SUBCOMMAND);
+}
+
+export async function getObsHealthSnapshot(
+  ctx: ObsHealthCommandContext,
+  options: ObsHealthSnapshotOptions = {},
+): Promise<ObsHealthSnapshot> {
+  const config = await loadObsHealthConfig(ctx, options);
+  const timeoutMs = resolveObsHealthTimeout(config, options);
+  const collectorFetcher = resolveCollectorHealthFetch(options.fetch);
+  const [collectorCheck, grafanaHealth] = await Promise.all([
+    checkCollectorReachability(config, collectorFetcher, timeoutMs),
+    getGrafanaHealth(config, { fetch: options.fetch, timeoutMs }),
+  ]);
+
+  return { timeoutMs, checks: [collectorCheck, ...grafanaHealth.checks] };
+}
+
+export function renderObsHealth(snapshot: ObsHealthSnapshot): string {
+  return snapshot.checks.map(renderObsHealthCheck).join("\n");
+}
+
+class ObsHealthCommand {
+  readonly #options: RegisterObsHealthCommandOptions;
+
+  constructor(options: RegisterObsHealthCommandOptions) {
+    this.#options = options;
+  }
+
+  async handle(args: string, ctx: ObsHealthCommandContext): Promise<void> {
+    await handleObsHealthCommand(args, ctx, this.#options);
+  }
+}
+
+async function resolveObsHealthSnapshot(
+  ctx: ObsHealthCommandContext,
+  options: RegisterObsHealthCommandOptions,
+): Promise<ObsHealthSnapshot> {
+  if (options.getHealth) return options.getHealth(ctx);
+  return getObsHealthSnapshot(ctx, options);
+}
+
+async function loadObsHealthConfig(
+  ctx: ObsHealthCommandContext,
+  options: ObsHealthSnapshotOptions,
+): Promise<ObservMeConfig> {
+  return loadObsCommandConfig(ctx, options);
+}
+
+async function checkCollectorReachability(
+  config: ObservMeConfig,
+  fetcher: ObsHealthFetch,
+  timeoutMs: number,
+): Promise<ObsHealthCheckResult> {
+  const target = {
+    label: "Collector",
+    kind: "service" as const,
+    url: config.otlp.endpoint,
+    headers: filterConfiguredHeaders(config.otlp.headers),
+    successMode: "reachable" as const,
+  };
+
+  return checkHttpHealthTarget(target, fetcher, timeoutMs);
+}
+
+async function checkHttpHealthTarget(
+  target: HttpHealthTarget,
+  fetcher: ObsHealthFetch,
+  timeoutMs: number,
+): Promise<ObsHealthCheckResult> {
+  try {
+    return responseToHealthResult(target, await fetchWithTimeout(target, fetcher, timeoutMs));
+  } catch (error) {
+    return failedHealthResult(target.label, target.kind, error);
+  }
+}
+
+async function fetchWithTimeout(target: HttpHealthTarget, fetcher: ObsHealthFetch, timeoutMs: number): Promise<Response> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    return await fetcher(target.url, {
+      method: "GET",
+      headers: target.headers,
+      signal: controller.signal,
+    });
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function filterConfiguredHeaders(headers: Record<string, string>): Record<string, string> | undefined {
+  const filtered: Record<string, string> = {};
+
+  for (const [name, value] of Object.entries(headers)) {
+    const trimmed = value.trim();
+    if (trimmed && !hasUnresolvedEnvironmentPlaceholder(trimmed)) filtered[name] = trimmed;
+  }
+
+  return Object.keys(filtered).length > 0 ? filtered : undefined;
+}
+
+function hasUnresolvedEnvironmentPlaceholder(value: string): boolean {
+  return /\$\{[A-Z0-9_]+\}/u.test(value);
+}
+
+function responseToHealthResult(target: HttpHealthTarget, response: Response): ObsHealthCheckResult {
+  if (responseMatchesSuccessMode(target, response)) return { label: target.label, kind: target.kind, status: "ok" };
+
+  return {
+    label: target.label,
+    kind: target.kind,
+    status: "failed",
+    detail: formatHttpFailure(response),
+  };
+}
+
+function responseMatchesSuccessMode(target: HttpHealthTarget, response: Response): boolean {
+  if (target.successMode === "reachable") return response.status < 500;
+  return response.ok;
+}
+
+function failedHealthResult(label: string, kind: ObsHealthCheckKind, error: unknown): ObsHealthCheckResult {
+  return {
+    label,
+    kind,
+    status: "failed",
+    detail: formatHealthFailure(error),
+  };
+}
+
+function renderObsHealthCheck(check: ObsHealthCheckResult): string {
+  const status = formatObsHealthStatus(check);
+  const detail = formatObsHealthDetail(check);
+  const detailText = detail ? ` (${detail})` : "";
+  return `${check.label}: ${status}${detailText}`;
+}
+
+function formatObsHealthStatus(check: ObsHealthCheckResult): string {
+  if (check.status === "ok") return check.kind === "datasource" ? "ok" : "reachable";
+  if (check.status === "skipped") return "skipped";
+  return check.kind === "datasource" ? "failed" : "unreachable";
+}
+
+function formatObsHealthDetail(check: ObsHealthCheckResult): string | undefined {
+  if (!check.detail) return undefined;
+  if (check.status !== "failed") return check.detail;
+  return appendObsRecoveryHint(check.detail, resolveObsHealthNextAction(check));
+}
+
+function resolveObsHealthNextAction(check: ObsHealthCheckResult): string {
+  if (check.label === "Collector") return OBS_HEALTH_COLLECTOR_NEXT_ACTION;
+  if (check.label === "Grafana") return OBS_HEALTH_GRAFANA_NEXT_ACTION;
+  if (check.label === "Tempo datasource") return OBS_HEALTH_TEMPO_NEXT_ACTION;
+  if (check.label === "Loki datasource") return OBS_HEALTH_LOKI_NEXT_ACTION;
+  if (check.label === "Metrics datasource") return OBS_HEALTH_METRICS_NEXT_ACTION;
+  return OBS_HEALTH_CONFIG_NEXT_ACTION;
+}
+
+function resolveObsHealthNotificationType(snapshot: ObsHealthSnapshot): "info" | "warning" {
+  return snapshot.checks.some(check => check.status === "failed") ? "warning" : "info";
+}
+
+function resolveObsHealthTimeout(config: ObservMeConfig, options: ObsHealthSnapshotOptions): number {
+  return normalizeObsCommandTimeoutMs(options.timeoutMs, config.query.timeoutMs, 1);
+}
+
+
+function resolveCollectorHealthFetch(fetcher: ObsHealthFetch | undefined): ObsHealthFetch {
+  return fetcher ?? globalThis.fetch.bind(globalThis);
+}
+
+function isObsHealthRequest(args: string): boolean {
+  return isExactObsSubcommandRequest(args, OBS_HEALTH_SUBCOMMAND);
+}
+
+function formatHttpFailure(response: Response): string {
+  return formatHttpStatus(response);
+}
+
+function formatHttpStatus(response: Response): string {
+  const statusText = response.statusText.trim();
+  return statusText ? `HTTP ${response.status} ${statusText}` : `HTTP ${response.status}`;
+}
+
+function formatHealthFailure(error: unknown): string {
+  if (isAbortError(error)) return "timed out";
+  return formatError(error);
+}
+
+function isAbortError(error: unknown): boolean {
+  return isNamedError(error) && error.name === "AbortError";
+}
+
+function isNamedError(error: unknown): error is { name: string } {
+  return typeof error === "object" && error !== null && "name" in error && typeof error.name === "string";
+}
+
+function formatError(error: unknown): string {
+  return sanitizeDiagnosticText(readDiagnosticMessage(error));
+}

package/src/commands/obs-link.ts

@@ -0,0 +1,90 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type {
+  ObsTraceCommandContext,
+  ObsTraceProvider,
+  ObsTraceRequest,
+  ObsTraceSnapshot,
+  ObsTraceSnapshotOptions,
+} from "./obs-trace.ts";
+import { completeObsSubcommand, obsUsageWithError } from "./obs-args.ts";
+import { notifyObsCommand } from "./obs-command-support.ts";
+import { formatObsCommandFailure } from "./obs-diagnostics.ts";
+import {
+  getObsTraceSnapshot,
+  parseObsTraceArgsForSubcommand,
+  renderObsTraceWithTitle,
+  resolveObsTraceDiagnostic,
+} from "./obs-trace.ts";
+
+export type ObsLinkCommandContext = ObsTraceCommandContext;
+export type ObsLinkProvider = ObsTraceProvider;
+
+export interface RegisterObsLinkCommandOptions extends ObsTraceSnapshotOptions {
+  readonly getLink?: ObsLinkProvider;
+}
+
+const OBS_COMMAND_NAME = "obs";
+const OBS_LINK_SUBCOMMAND = "link";
+const OBS_LINK_USAGE = "Usage: /obs link [--last-turn|--session <session-id>]";
+
+export function registerObsLinkCommand(pi: ExtensionAPI, options: RegisterObsLinkCommandOptions = {}): void {
+  const command = new ObsLinkCommand(options);
+
+  pi.registerCommand(OBS_COMMAND_NAME, {
+    description: "Show an ObservMe Grafana link. Usage: /obs link [--last-turn|--session <session-id>]",
+    getArgumentCompletions: getObsLinkCommandArgumentCompletions,
+    handler: command.handle.bind(command),
+  });
+}
+
+export async function handleObsLinkCommand(
+  args: string,
+  ctx: ObsLinkCommandContext,
+  options: RegisterObsLinkCommandOptions = {},
+): Promise<void> {
+  const parsed = parseObsTraceArgsForSubcommand(args, OBS_LINK_SUBCOMMAND);
+
+  if (!parsed.request) {
+    await notifyObsCommand(ctx, obsUsageWithError(OBS_LINK_USAGE, parsed.error), "warning");
+    return;
+  }
+
+  const request = parsed.request;
+
+  try {
+    const snapshot = await resolveObsLinkSnapshot(ctx, request, options);
+    await notifyObsCommand(ctx, renderObsLink(snapshot), "info");
+  } catch (error) {
+    await notifyObsCommand(ctx, formatObsCommandFailure("ObservMe link unavailable", error, resolveObsTraceDiagnostic(error)), "error");
+  }
+}
+
+export function getObsLinkCommandArgumentCompletions(prefix: string): Array<{ value: string; label: string }> | null {
+  return completeObsSubcommand(prefix, OBS_LINK_SUBCOMMAND);
+}
+
+export function renderObsLink(snapshot: ObsTraceSnapshot): string {
+  return renderObsTraceWithTitle(snapshot, "Grafana link");
+}
+
+class ObsLinkCommand {
+  readonly #options: RegisterObsLinkCommandOptions;
+
+  constructor(options: RegisterObsLinkCommandOptions) {
+    this.#options = options;
+  }
+
+  async handle(args: string, ctx: ObsLinkCommandContext): Promise<void> {
+    await handleObsLinkCommand(args, ctx, this.#options);
+  }
+}
+
+async function resolveObsLinkSnapshot(
+  ctx: ObsLinkCommandContext,
+  request: ObsTraceRequest,
+  options: RegisterObsLinkCommandOptions,
+): Promise<ObsTraceSnapshot> {
+  if (options.getLink) return options.getLink(ctx, request);
+  return getObsTraceSnapshot(ctx, request, options);
+}
+

package/src/commands/obs-logs.ts

@@ -0,0 +1,194 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { LoadSessionConfigOptions } from "../config/load-config.ts";
+import type { ObservMeConfig } from "../config/schema.ts";
+import type { LokiFetch } from "../query/loki.ts";
+import { createLokiQueryClient } from "../query/loki.ts";
+import { normalizeObservMeSessionId } from "../safety/sensitive-input.ts";
+import { completeObsSubcommand, isExactObsSubcommandRequest } from "./obs-args.ts";
+import { loadObsCommandConfig, notifyObsCommand } from "./obs-command-support.ts";
+import { appendObsRecoveryHint, formatObsCommandFailure, readObsDiagnosticMessage, type ObsCommandRecoveryHint } from "./obs-diagnostics.ts";
+import type { ObsLokiLogSummaryRow, ObsLokiTimeRangeOptions } from "./obs-loki-summary.ts";
+import {
+  createRecentObsLokiTimeRange,
+  formatObsLokiWindow,
+  normalizeObsLokiMaxLogs,
+  renderObsLokiLogSummary,
+  toObsLokiLogSummaryRow,
+} from "./obs-loki-summary.ts";
+import type { ObsSessionSnapshot } from "./obs-session.ts";
+import { getLocalObsSessionSnapshot } from "./obs-session.ts";
+
+export interface ObsLogsCommandContext {
+  readonly cwd?: string;
+  readonly ui: {
+    notify: (message: string, type?: "info" | "warning" | "error") => Promise<void> | void;
+  };
+  readonly isProjectTrusted?: () => boolean | Promise<boolean>;
+}
+
+export type ObsLogsSessionSnapshot = Pick<ObsSessionSnapshot, "sessionId">;
+export type ObsLogsSessionProvider = (ctx: ObsLogsCommandContext) => Promise<ObsLogsSessionSnapshot> | ObsLogsSessionSnapshot;
+
+export interface ObsLogsSnapshot {
+  readonly sessionId: string;
+  readonly window: string;
+  readonly query: string;
+  readonly maxLogs: number;
+  readonly logs: readonly ObsLokiLogSummaryRow[];
+}
+
+export type ObsLogsConfigLoader = (options: LoadSessionConfigOptions) => Promise<ObservMeConfig>;
+export type ObsLogsProvider = (ctx: ObsLogsCommandContext) => Promise<ObsLogsSnapshot> | ObsLogsSnapshot;
+
+export interface ObsLogsSnapshotOptions extends ObsLokiTimeRangeOptions {
+  readonly loadConfig?: ObsLogsConfigLoader;
+  readonly fetch?: LokiFetch;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly configDirName?: string;
+  readonly getSession?: ObsLogsSessionProvider;
+}
+
+export interface RegisterObsLogsCommandOptions extends ObsLogsSnapshotOptions {
+  readonly getLogs?: ObsLogsProvider;
+}
+
+export const OBS_LOGS_LOGQL_PREFIX = '{service_name="observme-pi-extension", event_category!~"llm_content|tool_content", pi_session_id=';
+
+const OBS_COMMAND_NAME = "obs";
+const OBS_LOGS_SUBCOMMAND = "logs";
+const OBS_LOGS_USAGE = "Usage: /obs logs";
+const OBS_LOGS_LOKI_ERROR_NEXT_ACTION = "run /obs health and verify query.grafana.url, Grafana credentials, the Loki datasource UID, and service labels.";
+const OBS_LOGS_SESSION_ERROR_NEXT_ACTION = "run /obs session to confirm a current session before /obs logs.";
+const OBS_LOGS_NO_LOGS_NEXT_ACTION = "wait for telemetry export, then verify Loki labels and datasource with /obs health.";
+const logQlBackslash = String.fromCodePoint(92);
+
+export function registerObsLogsCommand(pi: ExtensionAPI, options: RegisterObsLogsCommandOptions = {}): void {
+  const command = new ObsLogsCommand(options);
+
+  pi.registerCommand(OBS_COMMAND_NAME, {
+    description: "Show current-session ObservMe logs from Loki. Usage: /obs logs",
+    getArgumentCompletions: getObsLogsCommandArgumentCompletions,
+    handler: command.handle.bind(command),
+  });
+}
+
+export async function handleObsLogsCommand(
+  args: string,
+  ctx: ObsLogsCommandContext,
+  options: RegisterObsLogsCommandOptions = {},
+): Promise<void> {
+  if (!isObsLogsRequest(args)) {
+    await notifyObsCommand(ctx, OBS_LOGS_USAGE, "warning");
+    return;
+  }
+
+  try {
+    const snapshot = await resolveObsLogsSnapshot(ctx, options);
+    await notifyObsCommand(ctx, renderObsLogs(snapshot), "info");
+  } catch (error) {
+    await notifyObsCommand(ctx, formatObsCommandFailure("ObservMe logs unavailable", error, resolveObsLogsDiagnostic(error)), "error");
+  }
+}
+
+export function getObsLogsCommandArgumentCompletions(prefix: string): Array<{ value: string; label: string }> | null {
+  return completeObsSubcommand(prefix, OBS_LOGS_SUBCOMMAND);
+}
+
+export async function getObsLogsSnapshot(
+  ctx: ObsLogsCommandContext,
+  options: ObsLogsSnapshotOptions = {},
+): Promise<ObsLogsSnapshot> {
+  const sessionId = await resolveObsLogsSessionId(ctx, options);
+  const config = await loadObsLogsConfig(ctx, options);
+  const maxLogs = normalizeObsLokiMaxLogs(config.query.maxLogs);
+  const query = buildObsLogsLogQl(sessionId);
+  const logs = await queryObsLogs(config, query, options);
+
+  return {
+    sessionId,
+    window: formatObsLokiWindow(options),
+    query,
+    maxLogs,
+    logs: logs.slice(0, maxLogs).map(toObsLokiLogSummaryRow),
+  };
+}
+
+export function buildObsLogsLogQl(sessionId: string): string {
+  return `${OBS_LOGS_LOGQL_PREFIX}"${escapeLogQlString(normalizeObsLogsSessionId(sessionId))}"}`;
+}
+
+export function renderObsLogs(snapshot: ObsLogsSnapshot): string {
+  return renderObsLokiLogSummary({
+    title: `Session logs for ${snapshot.sessionId}`,
+    window: snapshot.window,
+    maxLogs: snapshot.maxLogs,
+    rows: snapshot.logs,
+    emptyMessage: appendObsRecoveryHint("No session logs found.", OBS_LOGS_NO_LOGS_NEXT_ACTION),
+  });
+}
+
+class ObsLogsCommand {
+  readonly #options: RegisterObsLogsCommandOptions;
+
+  constructor(options: RegisterObsLogsCommandOptions) {
+    this.#options = options;
+  }
+
+  async handle(args: string, ctx: ObsLogsCommandContext): Promise<void> {
+    await handleObsLogsCommand(args, ctx, this.#options);
+  }
+}
+
+async function resolveObsLogsSnapshot(
+  ctx: ObsLogsCommandContext,
+  options: RegisterObsLogsCommandOptions,
+): Promise<ObsLogsSnapshot> {
+  if (options.getLogs) return options.getLogs(ctx);
+  return getObsLogsSnapshot(ctx, options);
+}
+
+async function resolveObsLogsSessionId(ctx: ObsLogsCommandContext, options: ObsLogsSnapshotOptions): Promise<string> {
+  const session = await resolveObsLogsSession(ctx, options);
+  return normalizeObsLogsSessionId(session.sessionId);
+}
+
+async function resolveObsLogsSession(
+  ctx: ObsLogsCommandContext,
+  options: ObsLogsSnapshotOptions,
+): Promise<ObsLogsSessionSnapshot> {
+  if (options.getSession) return options.getSession(ctx);
+  return getLocalObsSessionSnapshot();
+}
+
+async function loadObsLogsConfig(ctx: ObsLogsCommandContext, options: ObsLogsSnapshotOptions): Promise<ObservMeConfig> {
+  return loadObsCommandConfig(ctx, options);
+}
+
+async function queryObsLogs(config: ObservMeConfig, query: string, options: ObsLogsSnapshotOptions) {
+  const client = createLokiQueryClient(config, { fetch: options.fetch });
+  return client.queryLoki(query, createRecentObsLokiTimeRange(options));
+}
+
+function normalizeObsLogsSessionId(value: string | undefined): string {
+  return normalizeObservMeSessionId(value, { emptyMessage: "No current ObservMe session id is available." });
+}
+
+function escapeLogQlString(value: string): string {
+  return value.replaceAll(logQlBackslash, String.raw`\\`).replaceAll('"', String.raw`\"`);
+}
+
+function isObsLogsRequest(args: string): boolean {
+  return isExactObsSubcommandRequest(args, OBS_LOGS_SUBCOMMAND);
+}
+
+function resolveObsLogsDiagnostic(error: unknown): ObsCommandRecoveryHint {
+  if (isObsLogsSessionErrorMessage(readObsDiagnosticMessage(error))) {
+    return { subsystem: "Session", nextAction: OBS_LOGS_SESSION_ERROR_NEXT_ACTION };
+  }
+
+  return { subsystem: "Loki", nextAction: OBS_LOGS_LOKI_ERROR_NEXT_ACTION };
+}
+
+function isObsLogsSessionErrorMessage(message: string): boolean {
+  return /current ObservMe session id|Unsafe ObservMe session id/u.test(message);
+}