@senad-d/observme 0.1.0

package/src/commands/obs-status.ts

@@ -0,0 +1,359 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { LoadSessionConfigOptions, SessionConfigDiagnostics, SessionConfigEffectiveSource } from "../config/load-config.ts";
+import { loadSessionConfigWithDiagnostics } from "../config/load-config.ts";
+import type { CaptureConfig, ObservMeConfig } from "../config/schema.ts";
+import { getGrafanaQueryReadiness } from "../query/grafana-readiness.ts";
+import { completeObsSubcommand, isExactObsSubcommandRequest } from "./obs-args.ts";
+import { sanitizeObsDiagnosticText } from "./obs-diagnostics.ts";
+
+export interface ObsStatusCommandContext {
+  readonly cwd?: string;
+  readonly ui: {
+    notify: (message: string, type?: "info" | "warning" | "error") => Promise<void> | void;
+  };
+  readonly isProjectTrusted?: () => boolean | Promise<boolean>;
+}
+
+export interface ObsStatusSnapshot {
+  readonly config: ObservMeConfig;
+  readonly queueDrops: number;
+  readonly lastExportError?: string;
+  readonly configDiagnostics?: SessionConfigDiagnostics;
+}
+
+export interface ObsStatusRuntimeStatePatch {
+  readonly config?: ObservMeConfig;
+  readonly queueDrops?: number;
+  readonly lastExportError?: string;
+  readonly configDiagnostics?: SessionConfigDiagnostics;
+}
+
+export interface ObsStatusRuntimeState {
+  readonly config?: ObservMeConfig;
+  readonly queueDrops: number;
+  readonly lastExportError?: string;
+  readonly configDiagnostics?: SessionConfigDiagnostics;
+}
+
+export interface ObsStatusOperationResult {
+  readonly operation: string;
+  readonly completed?: boolean;
+  readonly timedOut?: boolean;
+  readonly error?: unknown;
+}
+
+export type ObsStatusConfigLoader = (options: LoadSessionConfigOptions) => Promise<ObservMeConfig>;
+export type ObsStatusProvider = (ctx: ObsStatusCommandContext) => Promise<ObsStatusSnapshot> | ObsStatusSnapshot;
+type ObsStatusReadText = NonNullable<LoadSessionConfigOptions["readText"]>;
+type ObsStatusRuntimeOptions = NonNullable<LoadSessionConfigOptions["runtimeOptions"]>;
+type ObsStatusLogger = NonNullable<LoadSessionConfigOptions["logger"]>;
+
+export interface ObsStatusSnapshotOptions {
+  readonly loadConfig?: ObsStatusConfigLoader;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly configDirName?: string;
+  readonly globalConfigPath?: string;
+  readonly projectConfigPath?: string;
+  readonly readText?: ObsStatusReadText;
+  readonly runtimeOptions?: ObsStatusRuntimeOptions;
+  readonly logger?: ObsStatusLogger;
+}
+
+export interface RegisterObsStatusCommandOptions extends ObsStatusSnapshotOptions {
+  readonly getStatus?: ObsStatusProvider;
+}
+
+const OBS_COMMAND_NAME = "obs";
+const OBS_STATUS_SUBCOMMAND = "status";
+
+interface MutableObsStatusRuntimeState {
+  config?: ObservMeConfig;
+  queueDrops: number;
+  lastExportError?: string;
+  configDiagnostics?: SessionConfigDiagnostics;
+}
+
+const runtimeStatusState: MutableObsStatusRuntimeState = {
+  queueDrops: 0,
+};
+
+export function registerObsStatusCommand(pi: ExtensionAPI, options: RegisterObsStatusCommandOptions = {}): void {
+  const command = new ObsStatusCommand(options);
+
+  pi.registerCommand(OBS_COMMAND_NAME, {
+    description: "Show local ObservMe status. Usage: /obs status",
+    getArgumentCompletions: getObsCommandArgumentCompletions,
+    handler: command.handle.bind(command),
+  });
+}
+
+export async function handleObsStatusCommand(
+  args: string,
+  ctx: ObsStatusCommandContext,
+  options: RegisterObsStatusCommandOptions = {},
+): Promise<void> {
+  if (!isObsStatusRequest(args)) {
+    await notifyStatus(ctx, "Usage: /obs status", "warning");
+    return;
+  }
+
+  try {
+    const snapshot = await resolveObsStatusSnapshot(ctx, options);
+    await notifyStatus(ctx, renderObsStatus(snapshot), "info");
+  } catch (error) {
+    await notifyStatus(ctx, `ObservMe status unavailable: ${sanitizeObsDiagnosticText(formatError(error))}`, "error");
+  }
+}
+
+export function getObsCommandArgumentCompletions(prefix: string): Array<{ value: string; label: string }> | null {
+  return completeObsSubcommand(prefix, OBS_STATUS_SUBCOMMAND);
+}
+
+export async function getLocalObsStatusSnapshot(
+  ctx: ObsStatusCommandContext,
+  options: ObsStatusSnapshotOptions = {},
+): Promise<ObsStatusSnapshot> {
+  const state = getObsStatusRuntimeState();
+  const loaded = state.config ? { config: state.config, diagnostics: state.configDiagnostics } : await loadObsStatusConfig(ctx, options);
+
+  return {
+    config: loaded.config,
+    queueDrops: normalizeQueueDrops(state.queueDrops),
+    lastExportError: normalizeLastExportError(state.lastExportError),
+    configDiagnostics: loaded.diagnostics,
+  };
+}
+
+export function renderObsStatus(snapshot: ObsStatusSnapshot): string {
+  const config = snapshot.config;
+  const lines = [
+    `ObservMe: ${formatEnabled(config.enabled)}`,
+    `OTLP endpoint: ${formatSafeConfiguredEndpoint(config.otlp.endpoint)}`,
+    ...formatConfigDiagnosticsLines(snapshot.configDiagnostics),
+    `Grafana URL: ${formatSafeConfiguredUrl(config.query.grafana.url)}`,
+    `Grafana query readiness: ${formatGrafanaQueryReadiness(config)}`,
+    `Traces: ${formatEnabled(signalEnabled(config, config.traces.enabled))}`,
+    `Metrics: ${formatEnabled(signalEnabled(config, config.metrics.enabled))}`,
+    `Logs: ${formatEnabled(signalEnabled(config, config.logs.enabled))}`,
+    ...formatCaptureLines(config.capture),
+    `Queue drops: ${normalizeQueueDrops(snapshot.queueDrops)}`,
+    `Last export error: ${normalizeLastExportError(snapshot.lastExportError) ?? "none"}`,
+  ];
+
+  return lines.join("\n");
+}
+
+export function updateObsStatusRuntimeState(patch: ObsStatusRuntimeStatePatch): void {
+  if (patch.config) {
+    runtimeStatusState.config = structuredClone(patch.config);
+    delete runtimeStatusState.configDiagnostics;
+  }
+  if (patch.configDiagnostics) runtimeStatusState.configDiagnostics = structuredClone(patch.configDiagnostics);
+  if (patch.queueDrops !== undefined) runtimeStatusState.queueDrops = normalizeQueueDrops(patch.queueDrops);
+  if (patch.lastExportError !== undefined) runtimeStatusState.lastExportError = normalizeLastExportError(patch.lastExportError);
+}
+
+export function resetObsStatusRuntimeState(): void {
+  delete runtimeStatusState.config;
+  delete runtimeStatusState.lastExportError;
+  delete runtimeStatusState.configDiagnostics;
+  runtimeStatusState.queueDrops = 0;
+}
+
+export function getObsStatusRuntimeState(): ObsStatusRuntimeState {
+  return {
+    config: runtimeStatusState.config ? structuredClone(runtimeStatusState.config) : undefined,
+    queueDrops: normalizeQueueDrops(runtimeStatusState.queueDrops),
+    lastExportError: normalizeLastExportError(runtimeStatusState.lastExportError),
+    configDiagnostics: runtimeStatusState.configDiagnostics ? structuredClone(runtimeStatusState.configDiagnostics) : undefined,
+  };
+}
+
+export function recordObsStatusQueueDrop(count = 1): void {
+  runtimeStatusState.queueDrops = normalizeQueueDrops(runtimeStatusState.queueDrops) + normalizeQueueDrops(count);
+}
+
+export function recordObsStatusExportResult(result: ObsStatusOperationResult): void {
+  if (result.timedOut) {
+    runtimeStatusState.lastExportError = `${result.operation} timed out`;
+    return;
+  }
+
+  if (result.error) runtimeStatusState.lastExportError = sanitizeObsDiagnosticText(`${result.operation} failed: ${formatError(result.error)}`);
+}
+
+export function clearObsStatusExportError(): void {
+  delete runtimeStatusState.lastExportError;
+}
+
+class ObsStatusCommand {
+  readonly #options: RegisterObsStatusCommandOptions;
+
+  constructor(options: RegisterObsStatusCommandOptions) {
+    this.#options = options;
+  }
+
+  async handle(args: string, ctx: ObsStatusCommandContext): Promise<void> {
+    await handleObsStatusCommand(args, ctx, this.#options);
+  }
+}
+
+async function resolveObsStatusSnapshot(
+  ctx: ObsStatusCommandContext,
+  options: RegisterObsStatusCommandOptions,
+): Promise<ObsStatusSnapshot> {
+  if (options.getStatus) return options.getStatus(ctx);
+  return getLocalObsStatusSnapshot(ctx, options);
+}
+
+async function loadObsStatusConfig(
+  ctx: ObsStatusCommandContext,
+  options: ObsStatusSnapshotOptions,
+): Promise<{ config: ObservMeConfig; diagnostics?: SessionConfigDiagnostics }> {
+  const loadOptions = createObsStatusLoadOptions(ctx, options);
+
+  if (options.loadConfig) return { config: await options.loadConfig(loadOptions) };
+  return loadSessionConfigWithDiagnostics(loadOptions);
+}
+
+function createObsStatusLoadOptions(
+  ctx: ObsStatusCommandContext,
+  options: ObsStatusSnapshotOptions,
+): LoadSessionConfigOptions {
+  return {
+    ctx,
+    cwd: ctx.cwd,
+    configDirName: options.configDirName,
+    env: options.env,
+    globalConfigPath: options.globalConfigPath,
+    projectConfigPath: options.projectConfigPath,
+    readText: options.readText,
+    runtimeOptions: options.runtimeOptions,
+    logger: options.logger,
+  };
+}
+
+function isObsStatusRequest(args: string): boolean {
+  return isExactObsSubcommandRequest(args, OBS_STATUS_SUBCOMMAND, { allowEmpty: true });
+}
+
+async function notifyStatus(ctx: ObsStatusCommandContext, message: string, type: "info" | "warning" | "error"): Promise<void> {
+  await ctx.ui?.notify?.(message, type);
+}
+
+function formatCaptureLines(capture: CaptureConfig): string[] {
+  return [
+    `Prompt capture: ${formatEnabled(capture.prompts)}`,
+    `Response capture: ${formatEnabled(capture.responses)}`,
+    `Thinking capture: ${formatEnabled(capture.thinking)}`,
+    `Tool argument capture: ${formatEnabled(capture.toolArguments)}`,
+    `Tool result capture: ${formatEnabled(capture.toolResults)}`,
+    `Bash command capture: ${formatEnabled(capture.bashCommands)}`,
+    `Bash output capture: ${formatEnabled(capture.bashOutput)}`,
+    `File path capture: ${formatEnabled(capture.filePaths)}`,
+  ];
+}
+
+function formatConfigDiagnosticsLines(diagnostics: SessionConfigDiagnostics | undefined): string[] {
+  if (!diagnostics) return [];
+
+  return [
+    `Config source: ${formatConfigEffectiveSource(diagnostics.effectiveSource)}`,
+    `Project config: ${formatProjectConfigStatus(diagnostics)}`,
+    ...formatConfigRejectionLines(diagnostics),
+  ];
+}
+
+function formatConfigRejectionLines(diagnostics: SessionConfigDiagnostics): string[] {
+  const rejection = diagnostics.rejection;
+  if (!rejection) return [];
+
+  return [
+    `Config rejection: safe defaults applied (${rejection.issueCount} issue(s): ${rejection.issueCodes.join(", ")})`,
+  ];
+}
+
+function formatConfigEffectiveSource(source: SessionConfigEffectiveSource): string {
+  if (source === "runtime_options") return "runtime options";
+  if (source === "environment") return "environment overrides";
+  if (source === "trusted_project") return "trusted project config (.pi/observme.yaml)";
+  if (source === "global") return "global config";
+  return "defaults";
+}
+
+function formatProjectConfigStatus(diagnostics: SessionConfigDiagnostics): string {
+  if (diagnostics.projectConfigStatus === "loaded") return "loaded (trusted .pi/observme.yaml)";
+  if (diagnostics.projectConfigStatus === "skipped_untrusted") {
+    return "skipped (project is untrusted; safe defaults/global/env only)";
+  }
+
+  return "missing (trusted project has no .pi/observme.yaml)";
+}
+
+function formatGrafanaQueryReadiness(config: ObservMeConfig): string {
+  const readiness = getGrafanaQueryReadiness(config);
+  const issueCodes = readiness.issues.map(issue => issue.code).join(", ");
+  return issueCodes ? `${readiness.status} (${issueCodes})` : readiness.status;
+}
+
+function formatSafeConfiguredUrl(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) return "not configured";
+
+  try {
+    const parsed = new URL(trimmed);
+    parsed.username = "";
+    parsed.password = "";
+    parsed.search = "";
+    parsed.hash = "";
+    return parsed.toString();
+  } catch (error) {
+    return formatInvalidConfiguredUrl(error);
+  }
+}
+
+function signalEnabled(config: ObservMeConfig, enabled: boolean): boolean {
+  return config.enabled && enabled;
+}
+
+function formatEnabled(enabled: boolean): "enabled" | "disabled" {
+  return enabled ? "enabled" : "disabled";
+}
+
+function normalizeQueueDrops(value: number | undefined): number {
+  if (value === undefined || !Number.isFinite(value) || value < 0) return 0;
+  return Math.trunc(value);
+}
+
+function normalizeLastExportError(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? sanitizeObsDiagnosticText(trimmed) : undefined;
+}
+
+function formatSafeConfiguredEndpoint(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) return "not configured";
+
+  try {
+    const parsed = new URL(trimmed);
+    const hasExplicitRootPath = trimmed.endsWith("/");
+    parsed.username = "";
+    parsed.password = "";
+    parsed.search = "";
+    parsed.hash = "";
+    const formatted = parsed.toString();
+    if (parsed.pathname === "/" && !hasExplicitRootPath) return formatted.replace(/\/$/u, "");
+    return formatted;
+  } catch (error) {
+    return formatInvalidConfiguredUrl(error);
+  }
+}
+
+function formatInvalidConfiguredUrl(error: unknown): string {
+  const failureKind = error instanceof Error ? error.name : "unknown parser failure";
+  return `invalid configured URL (${failureKind})`;
+}
+
+function formatError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/commands/obs-tools.ts

@@ -0,0 +1,274 @@
+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 { PrometheusFetch, PrometheusMetricSeries, QueryResult } from "../query/prometheus.ts";
+import { createPrometheusQueryClient } from "../query/prometheus.ts";
+import { completeObsSubcommand, isExactObsSubcommandRequest } from "./obs-args.ts";
+import { loadObsCommandConfig, notifyObsCommand } from "./obs-command-support.ts";
+import { appendObsRecoveryHint, formatObsCommandFailure } from "./obs-diagnostics.ts";
+
+export interface ObsToolsCommandContext {
+  readonly cwd?: string;
+  readonly ui: {
+    notify: (message: string, type?: "info" | "warning" | "error") => Promise<void> | void;
+  };
+  readonly isProjectTrusted?: () => boolean | Promise<boolean>;
+}
+
+export interface ObsToolCallRow {
+  readonly toolName: string;
+  readonly ratePerSecond: number;
+  readonly timestampUnixSeconds?: string;
+}
+
+export interface ObsToolFailureRow {
+  readonly toolName: string;
+  readonly errorClass: string;
+  readonly ratePerSecond: number;
+  readonly timestampUnixSeconds?: string;
+}
+
+export interface ObsToolsSnapshot {
+  readonly window: "1h";
+  readonly callQuery: string;
+  readonly failureQuery: string;
+  readonly calls: readonly ObsToolCallRow[];
+  readonly failures: readonly ObsToolFailureRow[];
+}
+
+export type ObsToolsConfigLoader = (options: LoadSessionConfigOptions) => Promise<ObservMeConfig>;
+export type ObsToolsProvider = (ctx: ObsToolsCommandContext) => Promise<ObsToolsSnapshot> | ObsToolsSnapshot;
+
+export interface ObsToolsSnapshotOptions {
+  readonly loadConfig?: ObsToolsConfigLoader;
+  readonly fetch?: PrometheusFetch;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly configDirName?: string;
+}
+
+export interface RegisterObsToolsCommandOptions extends ObsToolsSnapshotOptions {
+  readonly getTools?: ObsToolsProvider;
+}
+
+export const OBS_TOOLS_CALLS_PROMQL = "topk(10, sum(rate(observme_tool_calls_total[1h])) by (tool_name))";
+export const OBS_TOOLS_FAILURES_PROMQL = "sum(rate(observme_tool_failures_total[1h])) by (tool_name, error_class)";
+
+const OBS_COMMAND_NAME = "obs";
+const OBS_TOOLS_SUBCOMMAND = "tools";
+const OBS_TOOLS_WINDOW = "1h";
+const OBS_TOOLS_USAGE = "Usage: /obs tools";
+const OBS_TOOLS_ERROR_NEXT_ACTION = "run /obs health and verify query.grafana.url, Grafana credentials, and the Metrics datasource UID.";
+const OBS_TOOLS_NO_CALLS_NEXT_ACTION = "run tool activity, then verify the Metrics datasource with /obs health.";
+const OBS_TOOLS_NO_FAILURES_NEXT_ACTION = "check after a failing tool call, then verify Metrics labels with /obs health.";
+
+type ObsToolsRequestStatus = "tools" | "usage";
+
+interface ObsToolsQueryResults {
+  readonly calls: QueryResult;
+  readonly failures: QueryResult;
+}
+
+export function registerObsToolsCommand(pi: ExtensionAPI, options: RegisterObsToolsCommandOptions = {}): void {
+  const command = new ObsToolsCommand(options);
+
+  pi.registerCommand(OBS_COMMAND_NAME, {
+    description: "Show aggregate ObservMe tool call and failure rates. Usage: /obs tools",
+    getArgumentCompletions: getObsToolsCommandArgumentCompletions,
+    handler: command.handle.bind(command),
+  });
+}
+
+export async function handleObsToolsCommand(
+  args: string,
+  ctx: ObsToolsCommandContext,
+  options: RegisterObsToolsCommandOptions = {},
+): Promise<void> {
+  if (parseObsToolsRequest(args) === "usage") {
+    await notifyObsCommand(ctx, OBS_TOOLS_USAGE, "warning");
+    return;
+  }
+
+  try {
+    const snapshot = await resolveObsToolsSnapshot(ctx, options);
+    await notifyObsCommand(ctx, renderObsTools(snapshot), "info");
+  } catch (error) {
+    await notifyObsCommand(
+      ctx,
+      formatObsCommandFailure("ObservMe tools unavailable", error, {
+        subsystem: "Prometheus",
+        nextAction: OBS_TOOLS_ERROR_NEXT_ACTION,
+      }),
+      "error",
+    );
+  }
+}
+
+export function getObsToolsCommandArgumentCompletions(prefix: string): Array<{ value: string; label: string }> | null {
+  return completeObsSubcommand(prefix, OBS_TOOLS_SUBCOMMAND);
+}
+
+export async function getObsToolsSnapshot(
+  ctx: ObsToolsCommandContext,
+  options: ObsToolsSnapshotOptions = {},
+): Promise<ObsToolsSnapshot> {
+  const config = await loadObsToolsConfig(ctx, options);
+  const result = await queryObsTools(config, options);
+
+  return {
+    window: OBS_TOOLS_WINDOW,
+    callQuery: OBS_TOOLS_CALLS_PROMQL,
+    failureQuery: OBS_TOOLS_FAILURES_PROMQL,
+    calls: result.calls.series.map(toObsToolCallRow).filter(isObsToolCallRow),
+    failures: result.failures.series.map(toObsToolFailureRow).filter(isObsToolFailureRow),
+  };
+}
+
+export function renderObsTools(snapshot: ObsToolsSnapshot): string {
+  const calls = snapshot.calls.map(normalizeObsToolCallRow).filter(isObsToolCallRow);
+  const failures = snapshot.failures.map(normalizeObsToolFailureRow).filter(isObsToolFailureRow);
+  const lines = [`Tool calls by tool (last ${snapshot.window})`];
+
+  if (calls.length === 0) {
+    lines.push(appendObsRecoveryHint("No tool call metrics found.", OBS_TOOLS_NO_CALLS_NEXT_ACTION));
+  } else {
+    lines.push(...calls.map(renderObsToolCallRow));
+  }
+
+  lines.push(`Tool failures by tool/error (last ${snapshot.window})`);
+  if (failures.length === 0) {
+    lines.push(appendObsRecoveryHint("No tool failure metrics found.", OBS_TOOLS_NO_FAILURES_NEXT_ACTION));
+  } else {
+    lines.push(...failures.map(renderObsToolFailureRow));
+  }
+
+  return lines.join("\n");
+}
+
+class ObsToolsCommand {
+  readonly #options: RegisterObsToolsCommandOptions;
+
+  constructor(options: RegisterObsToolsCommandOptions) {
+    this.#options = options;
+  }
+
+  async handle(args: string, ctx: ObsToolsCommandContext): Promise<void> {
+    await handleObsToolsCommand(args, ctx, this.#options);
+  }
+}
+
+async function resolveObsToolsSnapshot(
+  ctx: ObsToolsCommandContext,
+  options: RegisterObsToolsCommandOptions,
+): Promise<ObsToolsSnapshot> {
+  if (options.getTools) return options.getTools(ctx);
+  return getObsToolsSnapshot(ctx, options);
+}
+
+async function loadObsToolsConfig(ctx: ObsToolsCommandContext, options: ObsToolsSnapshotOptions): Promise<ObservMeConfig> {
+  return loadObsCommandConfig(ctx, options);
+}
+
+async function queryObsTools(config: ObservMeConfig, options: ObsToolsSnapshotOptions): Promise<ObsToolsQueryResults> {
+  const client = createPrometheusQueryClient(config, { fetch: options.fetch });
+  const calls = await client.queryPrometheus(OBS_TOOLS_CALLS_PROMQL, undefined, { resultLimit: "metricSeries" });
+  const failures = await client.queryPrometheus(OBS_TOOLS_FAILURES_PROMQL, undefined, { resultLimit: "metricSeries" });
+
+  return { calls, failures };
+}
+
+function toObsToolCallRow(series: PrometheusMetricSeries): ObsToolCallRow | undefined {
+  const ratePerSecond = parseRatePerSecond(series.value?.value);
+  if (ratePerSecond === undefined) return undefined;
+
+  return {
+    toolName: normalizeMetricLabel(series.metric.tool_name),
+    ratePerSecond,
+    timestampUnixSeconds: series.value?.timestampUnixSeconds,
+  };
+}
+
+function toObsToolFailureRow(series: PrometheusMetricSeries): ObsToolFailureRow | undefined {
+  const ratePerSecond = parseRatePerSecond(series.value?.value);
+  if (ratePerSecond === undefined) return undefined;
+
+  return {
+    toolName: normalizeMetricLabel(series.metric.tool_name),
+    errorClass: normalizeMetricLabel(series.metric.error_class),
+    ratePerSecond,
+    timestampUnixSeconds: series.value?.timestampUnixSeconds,
+  };
+}
+
+function normalizeObsToolCallRow(row: ObsToolCallRow): ObsToolCallRow | undefined {
+  const ratePerSecond = parseRatePerSecond(row.ratePerSecond);
+  if (ratePerSecond === undefined) return undefined;
+
+  return {
+    toolName: normalizeMetricLabel(row.toolName),
+    ratePerSecond,
+    timestampUnixSeconds: normalizeOptionalString(row.timestampUnixSeconds),
+  };
+}
+
+function normalizeObsToolFailureRow(row: ObsToolFailureRow): ObsToolFailureRow | undefined {
+  const ratePerSecond = parseRatePerSecond(row.ratePerSecond);
+  if (ratePerSecond === undefined) return undefined;
+
+  return {
+    toolName: normalizeMetricLabel(row.toolName),
+    errorClass: normalizeMetricLabel(row.errorClass),
+    ratePerSecond,
+    timestampUnixSeconds: normalizeOptionalString(row.timestampUnixSeconds),
+  };
+}
+
+function parseRatePerSecond(value: string | number | undefined): number | undefined {
+  if (value === undefined) return undefined;
+
+  const ratePerSecond = Number(value);
+  if (!Number.isFinite(ratePerSecond) || ratePerSecond < 0) return undefined;
+  return ratePerSecond;
+}
+
+function normalizeMetricLabel(value: string | undefined): string {
+  return normalizeOptionalString(value) ?? "unknown";
+}
+
+function normalizeOptionalString(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed || undefined;
+}
+
+function renderObsToolCallRow(row: ObsToolCallRow): string {
+  return `${row.toolName}: ${formatRatePerSecond(row.ratePerSecond)}`;
+}
+
+function renderObsToolFailureRow(row: ObsToolFailureRow): string {
+  return `${row.toolName} / ${row.errorClass}: ${formatRatePerSecond(row.ratePerSecond)}`;
+}
+
+function isObsToolCallRow(row: ObsToolCallRow | undefined): row is ObsToolCallRow {
+  return row !== undefined;
+}
+
+function isObsToolFailureRow(row: ObsToolFailureRow | undefined): row is ObsToolFailureRow {
+  return row !== undefined;
+}
+
+function parseObsToolsRequest(args: string): ObsToolsRequestStatus {
+  return isExactObsSubcommandRequest(args, OBS_TOOLS_SUBCOMMAND) ? "tools" : "usage";
+}
+
+function formatRatePerSecond(value: number): string {
+  return `${trimTrailingFractionZeros(value.toFixed(4))}/s`;
+}
+
+function trimTrailingFractionZeros(value: string): string {
+  if (!value.includes(".")) return value;
+
+  let end = value.length;
+  while (end > 0 && value[end - 1] === "0") end -= 1;
+
+  const withoutTrailingZeros = value.slice(0, end);
+  return withoutTrailingZeros.endsWith(".") ? withoutTrailingZeros.slice(0, -1) : withoutTrailingZeros;
+}