@senad-d/observme 0.1.0

package/src/commands/obs-command-support.ts

@@ -0,0 +1,43 @@
+import type { LoadSessionConfigOptions } from "../config/load-config.ts";
+import { loadSessionConfig } from "../config/load-config.ts";
+import type { ObservMeConfig } from "../config/schema.ts";
+
+export type ObsCommandNotificationType = "info" | "warning" | "error";
+
+export interface ObsCommandContext {
+  readonly cwd?: string;
+  readonly ui: {
+    notify: (message: string, type?: ObsCommandNotificationType) => Promise<void> | void;
+  };
+  readonly isProjectTrusted?: () => boolean | Promise<boolean>;
+}
+
+export type ObsCommandConfigLoader = (options: LoadSessionConfigOptions) => Promise<ObservMeConfig>;
+
+export interface ObsCommandConfigOptions {
+  readonly loadConfig?: ObsCommandConfigLoader;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly configDirName?: string;
+}
+
+export async function loadObsCommandConfig(
+  ctx: ObsCommandContext,
+  options: ObsCommandConfigOptions,
+): Promise<ObservMeConfig> {
+  const loadConfig = options.loadConfig ?? loadSessionConfig;
+  return loadConfig({ ctx, cwd: ctx.cwd, configDirName: options.configDirName, env: options.env });
+}
+
+export async function notifyObsCommand(
+  ctx: ObsCommandContext,
+  message: string,
+  type: ObsCommandNotificationType,
+): Promise<void> {
+  await ctx.ui?.notify?.(message, type);
+}
+
+export function normalizeObsCommandTimeoutMs(value: number | undefined, fallback: number, invalidFallback = fallback): number {
+  const timeoutMs = value ?? fallback;
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 1) return invalidFallback;
+  return Math.trunc(timeoutMs);
+}

package/src/commands/obs-cost.ts

@@ -0,0 +1,228 @@
+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, parseObsSubcommandArgs } from "./obs-args.ts";
+import { loadObsCommandConfig, notifyObsCommand } from "./obs-command-support.ts";
+import { appendObsRecoveryHint, formatObsCommandFailure } from "./obs-diagnostics.ts";
+
+export interface ObsCostCommandContext {
+  readonly cwd?: string;
+  readonly ui: {
+    notify: (message: string, type?: "info" | "warning" | "error") => Promise<void> | void;
+  };
+  readonly isProjectTrusted?: () => boolean | Promise<boolean>;
+}
+
+export interface ObsCostRow {
+  readonly model: string;
+  readonly provider: string;
+  readonly costUsd: number;
+  readonly timestampUnixSeconds?: string;
+}
+
+export interface ObsCostSnapshot {
+  readonly window: "24h";
+  readonly query: string;
+  readonly rows: readonly ObsCostRow[];
+}
+
+export type ObsCostConfigLoader = (options: LoadSessionConfigOptions) => Promise<ObservMeConfig>;
+export type ObsCostProvider = (ctx: ObsCostCommandContext) => Promise<ObsCostSnapshot> | ObsCostSnapshot;
+
+export interface ObsCostSnapshotOptions {
+  readonly loadConfig?: ObsCostConfigLoader;
+  readonly fetch?: PrometheusFetch;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly configDirName?: string;
+}
+
+export interface RegisterObsCostCommandOptions extends ObsCostSnapshotOptions {
+  readonly getCost?: ObsCostProvider;
+}
+
+export const OBS_COST_AGGREGATE_PROMQL = "sum(increase(observme_llm_cost_usd_total[24h])) by (model, provider)";
+
+const OBS_COMMAND_NAME = "obs";
+const OBS_COST_SUBCOMMAND = "cost";
+const OBS_COST_WINDOW = "24h";
+const OBS_COST_ERROR_NEXT_ACTION = "run /obs health and verify query.grafana.url, Grafana credentials, and the Metrics datasource UID.";
+const OBS_COST_NO_METRICS_NEXT_ACTION = "generate LLM usage, then verify the Metrics datasource with /obs health.";
+
+type ObsCostRequestStatus = "cost" | "session-disabled" | "usage";
+
+export function registerObsCostCommand(pi: ExtensionAPI, options: RegisterObsCostCommandOptions = {}): void {
+  const command = new ObsCostCommand(options);
+
+  pi.registerCommand(OBS_COMMAND_NAME, {
+    description: "Show aggregate ObservMe LLM cost. Usage: /obs cost",
+    getArgumentCompletions: getObsCostCommandArgumentCompletions,
+    handler: command.handle.bind(command),
+  });
+}
+
+export async function handleObsCostCommand(
+  args: string,
+  ctx: ObsCostCommandContext,
+  options: RegisterObsCostCommandOptions = {},
+): Promise<void> {
+  const requestStatus = parseObsCostRequest(args);
+
+  if (requestStatus === "usage") {
+    await notifyObsCommand(ctx, "Usage: /obs cost", "warning");
+    return;
+  }
+
+  if (requestStatus === "session-disabled") {
+    await notifyObsCommand(ctx, "Session-scoped Prometheus cost queries are disabled by default. Usage: /obs cost", "warning");
+    return;
+  }
+
+  try {
+    const snapshot = await resolveObsCostSnapshot(ctx, options);
+    await notifyObsCommand(ctx, renderObsCost(snapshot), "info");
+  } catch (error) {
+    await notifyObsCommand(
+      ctx,
+      formatObsCommandFailure("ObservMe cost unavailable", error, {
+        subsystem: "Prometheus",
+        nextAction: OBS_COST_ERROR_NEXT_ACTION,
+      }),
+      "error",
+    );
+  }
+}
+
+export function getObsCostCommandArgumentCompletions(prefix: string): Array<{ value: string; label: string }> | null {
+  return completeObsSubcommand(prefix, OBS_COST_SUBCOMMAND);
+}
+
+export async function getObsCostSnapshot(
+  ctx: ObsCostCommandContext,
+  options: ObsCostSnapshotOptions = {},
+): Promise<ObsCostSnapshot> {
+  const config = await loadObsCostConfig(ctx, options);
+  const result = await queryObsCost(config, options);
+
+  return {
+    window: OBS_COST_WINDOW,
+    query: OBS_COST_AGGREGATE_PROMQL,
+    rows: result.series.map(toObsCostRow).filter(isObsCostRow),
+  };
+}
+
+export function renderObsCost(snapshot: ObsCostSnapshot): string {
+  const rows = snapshot.rows.map(normalizeObsCostRow).filter(isObsCostRow);
+  const lines = [`Cost by model/provider (last ${snapshot.window})`];
+
+  if (rows.length === 0) {
+    lines.push(appendObsRecoveryHint("No cost metrics found.", OBS_COST_NO_METRICS_NEXT_ACTION));
+    return lines.join("\n");
+  }
+
+  lines.push(...rows.map(renderObsCostRow), `Total: ${formatUsd(sumObsCostRows(rows))}`);
+  return lines.join("\n");
+}
+
+class ObsCostCommand {
+  readonly #options: RegisterObsCostCommandOptions;
+
+  constructor(options: RegisterObsCostCommandOptions) {
+    this.#options = options;
+  }
+
+  async handle(args: string, ctx: ObsCostCommandContext): Promise<void> {
+    await handleObsCostCommand(args, ctx, this.#options);
+  }
+}
+
+async function resolveObsCostSnapshot(
+  ctx: ObsCostCommandContext,
+  options: RegisterObsCostCommandOptions,
+): Promise<ObsCostSnapshot> {
+  if (options.getCost) return options.getCost(ctx);
+  return getObsCostSnapshot(ctx, options);
+}
+
+async function loadObsCostConfig(ctx: ObsCostCommandContext, options: ObsCostSnapshotOptions): Promise<ObservMeConfig> {
+  return loadObsCommandConfig(ctx, options);
+}
+
+async function queryObsCost(config: ObservMeConfig, options: ObsCostSnapshotOptions): Promise<QueryResult> {
+  const client = createPrometheusQueryClient(config, { fetch: options.fetch });
+  return client.queryPrometheus(OBS_COST_AGGREGATE_PROMQL, undefined, { resultLimit: "metricSeries" });
+}
+
+function toObsCostRow(series: PrometheusMetricSeries): ObsCostRow | undefined {
+  const costUsd = parseCostUsd(series.value?.value);
+  if (costUsd === undefined) return undefined;
+
+  return {
+    model: normalizeMetricLabel(series.metric.model),
+    provider: normalizeMetricLabel(series.metric.provider),
+    costUsd,
+    timestampUnixSeconds: series.value?.timestampUnixSeconds,
+  };
+}
+
+function normalizeObsCostRow(row: ObsCostRow): ObsCostRow | undefined {
+  const costUsd = parseCostUsd(row.costUsd);
+  if (costUsd === undefined) return undefined;
+
+  return {
+    model: normalizeMetricLabel(row.model),
+    provider: normalizeMetricLabel(row.provider),
+    costUsd,
+    timestampUnixSeconds: normalizeOptionalString(row.timestampUnixSeconds),
+  };
+}
+
+function parseCostUsd(value: string | number | undefined): number | undefined {
+  if (value === undefined) return undefined;
+
+  const costUsd = Number(value);
+  if (!Number.isFinite(costUsd) || costUsd < 0) return undefined;
+  return costUsd;
+}
+
+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 renderObsCostRow(row: ObsCostRow): string {
+  return `${row.model} / ${row.provider}: ${formatUsd(row.costUsd)}`;
+}
+
+function sumObsCostRows(rows: readonly ObsCostRow[]): number {
+  return rows.reduce((total, row) => sumObsCostRow(total, row), 0);
+}
+
+function sumObsCostRow(total: number, row: ObsCostRow): number {
+  return total + row.costUsd;
+}
+
+function isObsCostRow(row: ObsCostRow | undefined): row is ObsCostRow {
+  return row !== undefined;
+}
+
+function parseObsCostRequest(args: string): ObsCostRequestStatus {
+  const parsed = parseObsSubcommandArgs(args, OBS_COST_SUBCOMMAND);
+  if (!parsed.matched) return "usage";
+  if (parsed.values.some(isSessionScopeCostToken)) return "session-disabled";
+  return parsed.values.length === 0 ? "cost" : "usage";
+}
+
+function isSessionScopeCostToken(token: string): boolean {
+  const normalizedToken = token.toLowerCase();
+  return normalizedToken === "--session" || normalizedToken.startsWith("--session=") || normalizedToken === "--current-session";
+}
+
+function formatUsd(value: number): string {
+  return `$${value.toFixed(2)}`;
+}

package/src/commands/obs-diagnostics.ts

@@ -0,0 +1,22 @@
+import { readDiagnosticMessage, sanitizeDiagnosticText } from "../diagnostics/sanitize.ts";
+
+export interface ObsCommandRecoveryHint {
+  readonly subsystem: string;
+  readonly nextAction: string;
+}
+
+export function formatObsCommandFailure(prefix: string, error: unknown, hint: ObsCommandRecoveryHint): string {
+  return `${prefix}: ${hint.subsystem}: ${sanitizeObsDiagnosticText(readObsDiagnosticMessage(error))} Next: ${hint.nextAction}`;
+}
+
+export function appendObsRecoveryHint(message: string, nextAction: string): string {
+  return `${sanitizeObsDiagnosticText(message)} Next: ${nextAction}`;
+}
+
+export function readObsDiagnosticMessage(error: unknown): string {
+  return readDiagnosticMessage(error);
+}
+
+export function sanitizeObsDiagnosticText(message: string): string {
+  return sanitizeDiagnosticText(message);
+}

package/src/commands/obs-errors.ts

@@ -0,0 +1,156 @@
+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 type { ObsLokiLogSummaryRow, ObsLokiTimeRangeOptions } from "./obs-loki-summary.ts";
+import { completeObsSubcommand, isExactObsSubcommandRequest } from "./obs-args.ts";
+import { loadObsCommandConfig, notifyObsCommand } from "./obs-command-support.ts";
+import { appendObsRecoveryHint, formatObsCommandFailure } from "./obs-diagnostics.ts";
+import {
+  createRecentObsLokiTimeRange,
+  formatObsLokiWindow,
+  normalizeObsLokiMaxLogs,
+  renderObsLokiLogSummary,
+  toObsLokiLogSummaryRow,
+} from "./obs-loki-summary.ts";
+
+export interface ObsErrorsCommandContext {
+  readonly cwd?: string;
+  readonly ui: {
+    notify: (message: string, type?: "info" | "warning" | "error") => Promise<void> | void;
+  };
+  readonly isProjectTrusted?: () => boolean | Promise<boolean>;
+}
+
+export interface ObsErrorsSnapshot {
+  readonly window: string;
+  readonly query: string;
+  readonly maxLogs: number;
+  readonly logs: readonly ObsLokiLogSummaryRow[];
+}
+
+export type ObsErrorsConfigLoader = (options: LoadSessionConfigOptions) => Promise<ObservMeConfig>;
+export type ObsErrorsProvider = (ctx: ObsErrorsCommandContext) => Promise<ObsErrorsSnapshot> | ObsErrorsSnapshot;
+
+export interface ObsErrorsSnapshotOptions extends ObsLokiTimeRangeOptions {
+  readonly loadConfig?: ObsErrorsConfigLoader;
+  readonly fetch?: LokiFetch;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly configDirName?: string;
+}
+
+export interface RegisterObsErrorsCommandOptions extends ObsErrorsSnapshotOptions {
+  readonly getErrors?: ObsErrorsProvider;
+}
+
+export const OBS_ERROR_EVENT_NAME_PATTERN = ".*[.]failed|.*[.]dropped|agent[.]orphaned";
+export const OBS_ERRORS_LOGQL = `{service_name="observme-pi-extension", event_name=~"${OBS_ERROR_EVENT_NAME_PATTERN}"}`;
+
+const OBS_COMMAND_NAME = "obs";
+const OBS_ERRORS_SUBCOMMAND = "errors";
+const OBS_ERRORS_USAGE = "Usage: /obs errors";
+const OBS_ERRORS_ERROR_NEXT_ACTION = "run /obs health and verify query.grafana.url, Grafana credentials, the Loki datasource UID, and service labels.";
+const OBS_ERRORS_NO_LOGS_NEXT_ACTION = "generate error telemetry, then verify Loki labels and datasource with /obs health.";
+
+export function registerObsErrorsCommand(pi: ExtensionAPI, options: RegisterObsErrorsCommandOptions = {}): void {
+  const command = new ObsErrorsCommand(options);
+
+  pi.registerCommand(OBS_COMMAND_NAME, {
+    description: "Show recent ObservMe error events from Loki. Usage: /obs errors",
+    getArgumentCompletions: getObsErrorsCommandArgumentCompletions,
+    handler: command.handle.bind(command),
+  });
+}
+
+export async function handleObsErrorsCommand(
+  args: string,
+  ctx: ObsErrorsCommandContext,
+  options: RegisterObsErrorsCommandOptions = {},
+): Promise<void> {
+  if (!isObsErrorsRequest(args)) {
+    await notifyObsCommand(ctx, OBS_ERRORS_USAGE, "warning");
+    return;
+  }
+
+  try {
+    const snapshot = await resolveObsErrorsSnapshot(ctx, options);
+    await notifyObsCommand(ctx, renderObsErrors(snapshot), "info");
+  } catch (error) {
+    await notifyObsCommand(
+      ctx,
+      formatObsCommandFailure("ObservMe errors unavailable", error, {
+        subsystem: "Loki",
+        nextAction: OBS_ERRORS_ERROR_NEXT_ACTION,
+      }),
+      "error",
+    );
+  }
+}
+
+export function getObsErrorsCommandArgumentCompletions(prefix: string): Array<{ value: string; label: string }> | null {
+  return completeObsSubcommand(prefix, OBS_ERRORS_SUBCOMMAND);
+}
+
+export async function getObsErrorsSnapshot(
+  ctx: ObsErrorsCommandContext,
+  options: ObsErrorsSnapshotOptions = {},
+): Promise<ObsErrorsSnapshot> {
+  const config = await loadObsErrorsConfig(ctx, options);
+  const maxLogs = normalizeObsLokiMaxLogs(config.query.maxLogs);
+  const logs = await queryObsErrors(config, options);
+
+  return {
+    window: formatObsLokiWindow(options),
+    query: OBS_ERRORS_LOGQL,
+    maxLogs,
+    logs: logs.slice(0, maxLogs).map(toObsLokiLogSummaryRow),
+  };
+}
+
+export function renderObsErrors(snapshot: ObsErrorsSnapshot): string {
+  return renderObsLokiLogSummary({
+    title: "Recent error events",
+    window: snapshot.window,
+    maxLogs: snapshot.maxLogs,
+    rows: snapshot.logs,
+    emptyMessage: appendObsRecoveryHint("No error logs found.", OBS_ERRORS_NO_LOGS_NEXT_ACTION),
+  });
+}
+
+class ObsErrorsCommand {
+  readonly #options: RegisterObsErrorsCommandOptions;
+
+  constructor(options: RegisterObsErrorsCommandOptions) {
+    this.#options = options;
+  }
+
+  async handle(args: string, ctx: ObsErrorsCommandContext): Promise<void> {
+    await handleObsErrorsCommand(args, ctx, this.#options);
+  }
+}
+
+async function resolveObsErrorsSnapshot(
+  ctx: ObsErrorsCommandContext,
+  options: RegisterObsErrorsCommandOptions,
+): Promise<ObsErrorsSnapshot> {
+  if (options.getErrors) return options.getErrors(ctx);
+  return getObsErrorsSnapshot(ctx, options);
+}
+
+async function loadObsErrorsConfig(
+  ctx: ObsErrorsCommandContext,
+  options: ObsErrorsSnapshotOptions,
+): Promise<ObservMeConfig> {
+  return loadObsCommandConfig(ctx, options);
+}
+
+async function queryObsErrors(config: ObservMeConfig, options: ObsErrorsSnapshotOptions) {
+  const client = createLokiQueryClient(config, { fetch: options.fetch });
+  return client.queryLoki(OBS_ERRORS_LOGQL, createRecentObsLokiTimeRange(options));
+}
+
+function isObsErrorsRequest(args: string): boolean {
+  return isExactObsSubcommandRequest(args, OBS_ERRORS_SUBCOMMAND);
+}
+