@senad-d/observme 0.1.0

package/src/commands/obs-loki-summary.ts

@@ -0,0 +1,184 @@
+import type { LogResult, TimeRange } from "../query/loki.ts";
+import { LOG_ATTRIBUTES } from "../semconv/attributes.ts";
+
+export interface ObsLokiLogSummaryRow {
+  readonly timestamp: string;
+  readonly eventName: string;
+  readonly category?: string;
+  readonly severity?: string;
+  readonly errorType?: string;
+  readonly sessionId?: string;
+  readonly traceId?: string;
+}
+
+export interface ObsLokiLogSummaryRenderOptions {
+  readonly title: string;
+  readonly window: string;
+  readonly maxLogs: number;
+  readonly rows: readonly ObsLokiLogSummaryRow[];
+  readonly emptyMessage: string;
+}
+
+export interface ObsLokiTimeRangeOptions {
+  readonly now?: () => Date;
+  readonly queryRangeHours?: number;
+}
+
+const defaultRangeHours = 1;
+const minimumMaxLogs = 1;
+const millisecondsPerHour = 60 * 60 * 1000;
+const nanosecondsPerMillisecond = 1_000_000n;
+const maximumDisplayValueLength = 96;
+const safeEventBodyPattern = /^[A-Za-z0-9_.:-]{1,96}$/u;
+const integerNanosecondsPattern = /^-?\d+$/u;
+const unknownTimestamp = "unknown-time";
+const unknownEventName = "structured-log";
+const eventNameAliases = ["event_name", LOG_ATTRIBUTES.EVENT_NAME] as const;
+const eventCategoryAliases = ["event_category", LOG_ATTRIBUTES.EVENT_CATEGORY] as const;
+const severityAliases = [LOG_ATTRIBUTES.SEVERITY, "severity_text", "level"] as const;
+const errorTypeAliases = ["error_type", LOG_ATTRIBUTES.ERROR_TYPE, "error_class"] as const;
+const sessionIdAliases = ["pi_session_id", LOG_ATTRIBUTES.PI_SESSION_ID] as const;
+const traceIdAliases = [LOG_ATTRIBUTES.TRACE_ID, "trace.id"] as const;
+
+export function createRecentObsLokiTimeRange(options: ObsLokiTimeRangeOptions = {}): TimeRange {
+  const to = normalizeDate(options.now?.() ?? new Date());
+  const rangeHours = normalizeRangeHours(options.queryRangeHours);
+  return { from: new Date(to.getTime() - rangeHours * millisecondsPerHour), to };
+}
+
+export function formatObsLokiWindow(options: ObsLokiTimeRangeOptions = {}): string {
+  return `${trimTrailingFractionZeros(String(normalizeRangeHours(options.queryRangeHours)))}h`;
+}
+
+export function normalizeObsLokiMaxLogs(value: number | undefined): number {
+  if (value === undefined || !Number.isFinite(value) || value < minimumMaxLogs) return minimumMaxLogs;
+  return Math.trunc(value);
+}
+
+export function toObsLokiLogSummaryRow(log: LogResult): ObsLokiLogSummaryRow {
+  return {
+    timestamp: formatLogTimestamp(log.timestampUnixNano),
+    eventName: resolveLogEventName(log),
+    category: readFirstLogField(log, eventCategoryAliases),
+    severity: readFirstLogField(log, severityAliases),
+    errorType: readFirstLogField(log, errorTypeAliases),
+    sessionId: readFirstLogField(log, sessionIdAliases),
+    traceId: readFirstLogField(log, traceIdAliases),
+  };
+}
+
+export function renderObsLokiLogSummary(options: ObsLokiLogSummaryRenderOptions): string {
+  const maxLogs = normalizeObsLokiMaxLogs(options.maxLogs);
+  const rows = options.rows.map(normalizeObsLokiLogSummaryRow).filter(isObsLokiLogSummaryRow).slice(0, maxLogs);
+  const lines = [`${options.title} (last ${options.window}, max ${maxLogs})`];
+
+  if (rows.length === 0) {
+    lines.push(options.emptyMessage);
+    return lines.join("\n");
+  }
+
+  lines.push(...rows.map(renderObsLokiLogSummaryRow));
+  return lines.join("\n");
+}
+
+function normalizeDate(value: Date): Date {
+  if (value instanceof Date && Number.isFinite(value.getTime())) return value;
+  return new Date();
+}
+
+function normalizeRangeHours(value: number | undefined): number {
+  if (value === undefined || !Number.isFinite(value) || value <= 0) return defaultRangeHours;
+  return value;
+}
+
+function formatLogTimestamp(timestampUnixNano: string): string {
+  const timestamp = timestampUnixNano.trim();
+  if (!timestamp) return unknownTimestamp;
+
+  if (!integerNanosecondsPattern.test(timestamp)) return timestamp;
+
+  const milliseconds = BigInt(timestamp) / nanosecondsPerMillisecond;
+  if (milliseconds < 0n || milliseconds > BigInt(Number.MAX_SAFE_INTEGER)) return timestamp;
+  return new Date(Number(milliseconds)).toISOString();
+}
+
+function resolveLogEventName(log: LogResult): string {
+  return readFirstLogField(log, eventNameAliases) ?? readSafeLogLineEventName(log.line) ?? unknownEventName;
+}
+
+function readSafeLogLineEventName(line: string): string | undefined {
+  const value = normalizeDisplayValue(line);
+  if (!value || !safeEventBodyPattern.test(value)) return undefined;
+  return value;
+}
+
+function readFirstLogField(log: LogResult, aliases: readonly string[]): string | undefined {
+  for (const alias of aliases) {
+    const metadataValue = normalizeDisplayValue(log.metadata?.[alias]);
+    if (metadataValue) return metadataValue;
+
+    const labelValue = normalizeDisplayValue(log.labels[alias]);
+    if (labelValue) return labelValue;
+  }
+
+  return undefined;
+}
+
+function normalizeObsLokiLogSummaryRow(row: ObsLokiLogSummaryRow): ObsLokiLogSummaryRow | undefined {
+  const timestamp = normalizeDisplayValue(row.timestamp) ?? unknownTimestamp;
+  const eventName = normalizeDisplayValue(row.eventName) ?? unknownEventName;
+
+  return {
+    timestamp,
+    eventName,
+    category: normalizeDisplayValue(row.category),
+    severity: normalizeDisplayValue(row.severity),
+    errorType: normalizeDisplayValue(row.errorType),
+    sessionId: normalizeDisplayValue(row.sessionId),
+    traceId: normalizeDisplayValue(row.traceId),
+  };
+}
+
+function normalizeDisplayValue(value: string | undefined): string | undefined {
+  const normalized = value?.replace(/\s+/gu, " ").trim();
+  if (!normalized) return undefined;
+  if (normalized.length <= maximumDisplayValueLength) return normalized;
+  return `${normalized.slice(0, maximumDisplayValueLength - 1)}…`;
+}
+
+function renderObsLokiLogSummaryRow(row: ObsLokiLogSummaryRow): string {
+  return [
+    row.timestamp,
+    row.eventName,
+    renderOptionalField("category", row.category),
+    renderOptionalField(LOG_ATTRIBUTES.SEVERITY, row.severity),
+    renderOptionalField("error", row.errorType),
+    renderOptionalField("session", row.sessionId),
+    renderOptionalField("trace", row.traceId),
+  ]
+    .filter(isString)
+    .join(" ");
+}
+
+function renderOptionalField(label: string, value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  return `${label}=${value}`;
+}
+
+function isObsLokiLogSummaryRow(row: ObsLokiLogSummaryRow | undefined): row is ObsLokiLogSummaryRow {
+  return row !== undefined;
+}
+
+function isString(value: string | undefined): value is string {
+  return value !== undefined && value.length > 0;
+}
+
+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;
+}

package/src/commands/obs-session.ts

@@ -0,0 +1,259 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { completeObsSubcommand, isExactObsSubcommandRequest } from "./obs-args.ts";
+
+export interface ObsSessionCommandContext {
+  readonly ui: {
+    notify: (message: string, type?: "info" | "warning" | "error") => Promise<void> | void;
+  };
+}
+
+export interface ObsSessionSnapshot {
+  readonly sessionId?: string;
+  readonly traceId?: string;
+  readonly turns: number;
+  readonly llmCalls: number;
+  readonly toolCalls: number;
+  readonly costUsd: number;
+  readonly traceLink?: string;
+}
+
+export interface ObsSessionRuntimeStatePatch {
+  readonly sessionId?: string;
+  readonly traceId?: string;
+  readonly turns?: number;
+  readonly llmCalls?: number;
+  readonly toolCalls?: number;
+  readonly costUsd?: number;
+  readonly traceLink?: string;
+}
+
+export interface StartObsSessionRuntimeStateOptions {
+  readonly sessionId?: string;
+  readonly traceId?: string;
+  readonly traceUrlTemplate?: string;
+}
+
+export type ObsSessionProvider = (ctx: ObsSessionCommandContext) => Promise<ObsSessionSnapshot> | ObsSessionSnapshot;
+
+export interface RegisterObsSessionCommandOptions {
+  readonly getSession?: ObsSessionProvider;
+}
+
+interface MutableObsSessionRuntimeState {
+  sessionId?: string;
+  traceId?: string;
+  turns: number;
+  llmCalls: number;
+  toolCalls: number;
+  costUsd: number;
+  traceLink?: string;
+}
+
+const OBS_COMMAND_NAME = "obs";
+const OBS_SESSION_SUBCOMMAND = "session";
+const traceIdPattern = /^[a-f0-9]{32}$/iu;
+
+const runtimeSessionState: MutableObsSessionRuntimeState = createEmptyObsSessionRuntimeState();
+
+export function registerObsSessionCommand(pi: ExtensionAPI, options: RegisterObsSessionCommandOptions = {}): void {
+  const command = new ObsSessionCommand(options);
+
+  pi.registerCommand(OBS_COMMAND_NAME, {
+    description: "Show current ObservMe session telemetry. Usage: /obs session",
+    getArgumentCompletions: getObsSessionCommandArgumentCompletions,
+    handler: command.handle.bind(command),
+  });
+}
+
+export async function handleObsSessionCommand(
+  args: string,
+  ctx: ObsSessionCommandContext,
+  options: RegisterObsSessionCommandOptions = {},
+): Promise<void> {
+  if (!isObsSessionRequest(args)) {
+    await notifySession(ctx, "Usage: /obs session", "warning");
+    return;
+  }
+
+  try {
+    const snapshot = await resolveObsSessionSnapshot(ctx, options);
+    await notifySession(ctx, renderObsSession(snapshot), "info");
+  } catch (error) {
+    await notifySession(ctx, `ObservMe session unavailable: ${formatError(error)}`, "error");
+  }
+}
+
+export function getObsSessionCommandArgumentCompletions(prefix: string): Array<{ value: string; label: string }> | null {
+  return completeObsSubcommand(prefix, OBS_SESSION_SUBCOMMAND);
+}
+
+export function getLocalObsSessionSnapshot(): ObsSessionSnapshot {
+  return normalizeObsSessionSnapshot(runtimeSessionState);
+}
+
+export function renderObsSession(snapshot: ObsSessionSnapshot): string {
+  const normalized = normalizeObsSessionSnapshot(snapshot);
+  const lines = [
+    `Session: ${normalized.sessionId ?? "unknown"}`,
+    `Trace: ${normalized.traceId ?? "unavailable"}`,
+    `Turns: ${normalized.turns}`,
+    `LLM calls: ${normalized.llmCalls}`,
+    `Tool calls: ${normalized.toolCalls}`,
+    `Cost: ${formatUsd(normalized.costUsd)}`,
+  ];
+
+  if (normalized.traceLink) lines.push(`Open trace: ${normalized.traceLink}`);
+  return lines.join("\n");
+}
+
+export function startObsSessionRuntimeState(options: StartObsSessionRuntimeStateOptions): void {
+  const traceId = normalizeTraceId(options.traceId);
+  const traceLink = buildObsSessionTraceLink(traceId, options.traceUrlTemplate);
+
+  replaceObsSessionRuntimeState({
+    sessionId: normalizeString(options.sessionId),
+    traceId,
+    turns: 0,
+    llmCalls: 0,
+    toolCalls: 0,
+    costUsd: 0,
+    traceLink,
+  });
+}
+
+export function updateObsSessionRuntimeState(patch: ObsSessionRuntimeStatePatch): void {
+  if (patch.sessionId !== undefined) runtimeSessionState.sessionId = normalizeString(patch.sessionId);
+  if (patch.traceId !== undefined) runtimeSessionState.traceId = normalizeTraceId(patch.traceId);
+  if (patch.turns !== undefined) runtimeSessionState.turns = normalizeCount(patch.turns);
+  if (patch.llmCalls !== undefined) runtimeSessionState.llmCalls = normalizeCount(patch.llmCalls);
+  if (patch.toolCalls !== undefined) runtimeSessionState.toolCalls = normalizeCount(patch.toolCalls);
+  if (patch.costUsd !== undefined) runtimeSessionState.costUsd = normalizeCost(patch.costUsd);
+  if (patch.traceLink !== undefined) runtimeSessionState.traceLink = normalizeString(patch.traceLink);
+}
+
+export function recordObsSessionTurn(count = 1): void {
+  runtimeSessionState.turns += normalizeCount(count);
+}
+
+export function recordObsSessionLlmCall(count = 1): void {
+  runtimeSessionState.llmCalls += normalizeCount(count);
+}
+
+export function recordObsSessionToolCall(count = 1): void {
+  runtimeSessionState.toolCalls += normalizeCount(count);
+}
+
+export function recordObsSessionCost(costUsd: number | undefined): void {
+  if (costUsd === undefined) return;
+  runtimeSessionState.costUsd = normalizeCost(runtimeSessionState.costUsd + normalizeCost(costUsd));
+}
+
+export function clearObsSessionRuntimeState(): void {
+  replaceObsSessionRuntimeState(createEmptyObsSessionRuntimeState());
+}
+
+export function buildObsSessionTraceLink(traceId: string | undefined, traceUrlTemplate: string | undefined): string | undefined {
+  const template = normalizeString(traceUrlTemplate);
+  if (!traceId || !template) return undefined;
+
+  if (template.includes("{{traceId}}")) return template.replaceAll("{{traceId}}", encodeURIComponent(traceId));
+  if (template.includes("${traceId}")) return template.replaceAll("${traceId}", encodeURIComponent(traceId));
+  if (template.includes("{traceId}")) return template.replaceAll("{traceId}", encodeURIComponent(traceId));
+  if (template.includes("$traceId")) return template.replaceAll("$traceId", encodeURIComponent(traceId));
+  if (template.includes("%TRACE_ID%")) return template.replaceAll("%TRACE_ID%", encodeURIComponent(traceId));
+  if (template.includes("__TRACE_ID__")) return template.replaceAll("__TRACE_ID__", encodeURIComponent(traceId));
+  if (template.includes("...")) return template.replaceAll("...", encodeURIComponent(traceId));
+  return undefined;
+}
+
+class ObsSessionCommand {
+  readonly #options: RegisterObsSessionCommandOptions;
+
+  constructor(options: RegisterObsSessionCommandOptions) {
+    this.#options = options;
+  }
+
+  async handle(args: string, ctx: ObsSessionCommandContext): Promise<void> {
+    await handleObsSessionCommand(args, ctx, this.#options);
+  }
+}
+
+async function resolveObsSessionSnapshot(
+  ctx: ObsSessionCommandContext,
+  options: RegisterObsSessionCommandOptions,
+): Promise<ObsSessionSnapshot> {
+  if (options.getSession) return options.getSession(ctx);
+  return getLocalObsSessionSnapshot();
+}
+
+function replaceObsSessionRuntimeState(state: MutableObsSessionRuntimeState): void {
+  runtimeSessionState.sessionId = state.sessionId;
+  runtimeSessionState.traceId = state.traceId;
+  runtimeSessionState.turns = state.turns;
+  runtimeSessionState.llmCalls = state.llmCalls;
+  runtimeSessionState.toolCalls = state.toolCalls;
+  runtimeSessionState.costUsd = state.costUsd;
+  runtimeSessionState.traceLink = state.traceLink;
+}
+
+function createEmptyObsSessionRuntimeState(): MutableObsSessionRuntimeState {
+  return {
+    turns: 0,
+    llmCalls: 0,
+    toolCalls: 0,
+    costUsd: 0,
+  };
+}
+
+function normalizeObsSessionSnapshot(snapshot: ObsSessionSnapshot): ObsSessionSnapshot {
+  return {
+    sessionId: normalizeString(snapshot.sessionId),
+    traceId: normalizeTraceId(snapshot.traceId),
+    turns: normalizeCount(snapshot.turns),
+    llmCalls: normalizeCount(snapshot.llmCalls),
+    toolCalls: normalizeCount(snapshot.toolCalls),
+    costUsd: normalizeCost(snapshot.costUsd),
+    traceLink: normalizeString(snapshot.traceLink),
+  };
+}
+
+function normalizeString(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed || undefined;
+}
+
+function normalizeTraceId(value: string | undefined): string | undefined {
+  const trimmed = normalizeString(value);
+  if (!trimmed || !traceIdPattern.test(trimmed) || /^0+$/u.test(trimmed)) return undefined;
+  return trimmed.toLowerCase();
+}
+
+function normalizeCount(value: number | undefined): number {
+  if (value === undefined || !Number.isFinite(value) || value < 0) return 0;
+  return Math.trunc(value);
+}
+
+function normalizeCost(value: number | undefined): number {
+  if (value === undefined || !Number.isFinite(value) || value < 0) return 0;
+  return value;
+}
+
+function formatUsd(value: number): string {
+  return `$${normalizeCost(value).toFixed(2)}`;
+}
+
+function isObsSessionRequest(args: string): boolean {
+  return isExactObsSubcommandRequest(args, OBS_SESSION_SUBCOMMAND);
+}
+
+async function notifySession(
+  ctx: ObsSessionCommandContext,
+  message: string,
+  type: "info" | "warning" | "error",
+): Promise<void> {
+  await ctx.ui?.notify?.(message, type);
+}
+
+function formatError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}