@senad-d/observme 0.1.0

package/src/commands/obs-trace.ts

@@ -0,0 +1,411 @@
+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 { createGrafanaQueryClient, type GrafanaFetch } from "../query/grafana.ts";
+import { normalizeObservMeSessionId } from "../safety/sensitive-input.ts";
+import type { TimeRange, TraceSummary } from "../query/tempo.ts";
+import {
+  completeObsSubcommand,
+  missingObsOptionValueMessage,
+  obsUsageWithError,
+  parseObsSubcommandArgs,
+  unknownObsOptionMessage,
+} from "./obs-args.ts";
+import { loadObsCommandConfig, notifyObsCommand } from "./obs-command-support.ts";
+import { formatObsCommandFailure, readObsDiagnosticMessage, type ObsCommandRecoveryHint } from "./obs-diagnostics.ts";
+import { searchTempo } from "../query/tempo.ts";
+import { COMMON_SPAN_ATTRIBUTES } from "../semconv/attributes.ts";
+import type { ObsSessionSnapshot } from "./obs-session.ts";
+import { getLocalObsSessionSnapshot } from "./obs-session.ts";
+
+export interface ObsTraceCommandContext {
+  readonly cwd?: string;
+  readonly ui: {
+    notify: (message: string, type?: "info" | "warning" | "error") => Promise<void> | void;
+  };
+  readonly isProjectTrusted?: () => boolean | Promise<boolean>;
+}
+
+export type ObsTraceScope = "current-session" | "last-turn" | "session";
+export type ObsTraceSource = "runtime" | "tempo";
+export type ObsTraceConfigLoader = (options: LoadSessionConfigOptions) => Promise<ObservMeConfig>;
+export type ObsTraceSessionSnapshot = Pick<ObsSessionSnapshot, "sessionId" | "traceId" | "turns">;
+export type ObsTraceSessionProvider = (
+  ctx: ObsTraceCommandContext,
+) => Promise<ObsTraceSessionSnapshot> | ObsTraceSessionSnapshot;
+export type ObsTraceSessionTraceResolver = (
+  sessionId: string,
+  ctx: ObsTraceCommandContext,
+  config: ObservMeConfig,
+) => Promise<string | undefined> | string | undefined;
+export type ObsTraceProvider = (
+  ctx: ObsTraceCommandContext,
+  request: ObsTraceRequest,
+) => Promise<ObsTraceSnapshot> | ObsTraceSnapshot;
+
+export interface ObsTraceRequest {
+  readonly scope: ObsTraceScope;
+  readonly sessionId?: string;
+}
+
+export interface ObsTraceSnapshot {
+  readonly scope: ObsTraceScope;
+  readonly source: ObsTraceSource;
+  readonly traceId: string;
+  readonly traceLink: string;
+  readonly sessionId?: string;
+}
+
+export interface ObsTraceSnapshotOptions {
+  readonly loadConfig?: ObsTraceConfigLoader;
+  readonly fetch?: GrafanaFetch;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly configDirName?: string;
+  readonly getSession?: ObsTraceSessionProvider;
+  readonly resolveSessionTraceId?: ObsTraceSessionTraceResolver;
+  readonly searchRangeHours?: number;
+  readonly now?: () => Date;
+}
+
+export interface RegisterObsTraceCommandOptions extends ObsTraceSnapshotOptions {
+  readonly getTrace?: ObsTraceProvider;
+}
+
+interface ObsTraceTarget {
+  readonly scope: ObsTraceScope;
+  readonly source: ObsTraceSource;
+  readonly traceId: string;
+  readonly sessionId?: string;
+}
+
+export interface ParsedObsTraceRequest {
+  readonly request?: ObsTraceRequest;
+  readonly error?: string;
+}
+
+interface ObsTraceParseState {
+  request?: ObsTraceRequest;
+  index: number;
+}
+
+const OBS_COMMAND_NAME = "obs";
+const OBS_TRACE_SUBCOMMAND = "trace";
+const OBS_TRACE_USAGE = "Usage: /obs trace [--last-turn|--session <session-id>]";
+const OBS_TRACE_TEMPO_ERROR_NEXT_ACTION = "run /obs health and verify query.grafana.url, Grafana credentials, and the Tempo datasource UID.";
+const OBS_TRACE_SESSION_ERROR_NEXT_ACTION = "wait for a Pi turn or query a generated session id with /obs trace --session <session-id>.";
+const OBS_TRACE_NOT_FOUND_NEXT_ACTION = "check the session id, wait for trace export, then verify Tempo datasource with /obs health.";
+const OBS_TRACE_ACTIVE_SESSION_NOTE = "Trace visibility: active sessions may show ended child spans before the root pi.session span; the root is exported after session_shutdown.";
+const DEFAULT_TRACE_SEARCH_RANGE_HOURS = 24;
+const millisecondsPerHour = 60 * 60 * 1000;
+const defaultObsTraceRequest = { scope: "current-session" } as const satisfies ObsTraceRequest;
+
+export function registerObsTraceCommand(pi: ExtensionAPI, options: RegisterObsTraceCommandOptions = {}): void {
+  const command = new ObsTraceCommand(options);
+
+  pi.registerCommand(OBS_COMMAND_NAME, {
+    description: "Show an ObservMe Grafana trace link. Usage: /obs trace [--last-turn|--session <session-id>]",
+    getArgumentCompletions: getObsTraceCommandArgumentCompletions,
+    handler: command.handle.bind(command),
+  });
+}
+
+export async function handleObsTraceCommand(
+  args: string,
+  ctx: ObsTraceCommandContext,
+  options: RegisterObsTraceCommandOptions = {},
+): Promise<void> {
+  const parsed = parseObsTraceArgsForSubcommand(args, OBS_TRACE_SUBCOMMAND);
+
+  if (!parsed.request) {
+    await notifyObsCommand(ctx, obsUsageWithError(OBS_TRACE_USAGE, parsed.error), "warning");
+    return;
+  }
+
+  const request = parsed.request;
+
+  try {
+    const snapshot = await resolveObsTraceSnapshot(ctx, request, options);
+    await notifyObsCommand(ctx, renderObsTrace(snapshot), "info");
+  } catch (error) {
+    await notifyObsCommand(ctx, formatObsCommandFailure("ObservMe trace unavailable", error, resolveObsTraceDiagnostic(error)), "error");
+  }
+}
+
+export function getObsTraceCommandArgumentCompletions(prefix: string): Array<{ value: string; label: string }> | null {
+  return completeObsSubcommand(prefix, OBS_TRACE_SUBCOMMAND);
+}
+
+export async function getObsTraceSnapshot(
+  ctx: ObsTraceCommandContext,
+  request: ObsTraceRequest = defaultObsTraceRequest,
+  options: ObsTraceSnapshotOptions = {},
+): Promise<ObsTraceSnapshot> {
+  const config = await loadObsTraceConfig(ctx, options);
+  const target = await resolveObsTraceTarget(ctx, request, config, options);
+  const client = createGrafanaQueryClient(config, { fetch: options.fetch });
+  const traceLink = client.getTraceLink(target.traceId);
+
+  return { ...target, traceLink };
+}
+
+export async function resolveObsTraceSnapshot(
+  ctx: ObsTraceCommandContext,
+  request: ObsTraceRequest,
+  options: RegisterObsTraceCommandOptions,
+): Promise<ObsTraceSnapshot> {
+  if (options.getTrace) return options.getTrace(ctx, request);
+  return getObsTraceSnapshot(ctx, request, options);
+}
+
+export function renderObsTrace(snapshot: ObsTraceSnapshot): string {
+  return renderObsTraceWithTitle(snapshot, "Trace link");
+}
+
+export function renderObsTraceWithTitle(snapshot: ObsTraceSnapshot, title: string): string {
+  const lines = [`${title} (${formatObsTraceScope(snapshot.scope)})`];
+  const sessionId = normalizeOptionalString(snapshot.sessionId);
+
+  if (sessionId) lines.push(`Session: ${sessionId}`);
+  lines.push(`Trace: ${snapshot.traceId}`, `Open trace: ${snapshot.traceLink}`);
+  const visibilityNote = formatObsTraceVisibilityNote(snapshot);
+  if (visibilityNote) lines.push(visibilityNote);
+  return lines.join("\n");
+}
+
+export function parseObsTraceRequestForSubcommand(args: string, subcommand: string): ObsTraceRequest | undefined {
+  return parseObsTraceArgsForSubcommand(args, subcommand).request;
+}
+
+export function parseObsTraceArgsForSubcommand(args: string, subcommand: string): ParsedObsTraceRequest {
+  const parsed = parseObsSubcommandArgs(args, subcommand);
+  if (!parsed.matched) return {};
+  return parseObsTraceOptions(parsed.values);
+}
+
+class ObsTraceCommand {
+  readonly #options: RegisterObsTraceCommandOptions;
+
+  constructor(options: RegisterObsTraceCommandOptions) {
+    this.#options = options;
+  }
+
+  async handle(args: string, ctx: ObsTraceCommandContext): Promise<void> {
+    await handleObsTraceCommand(args, ctx, this.#options);
+  }
+}
+
+async function loadObsTraceConfig(
+  ctx: ObsTraceCommandContext,
+  options: ObsTraceSnapshotOptions,
+): Promise<ObservMeConfig> {
+  return loadObsCommandConfig(ctx, options);
+}
+
+async function resolveObsTraceTarget(
+  ctx: ObsTraceCommandContext,
+  request: ObsTraceRequest,
+  config: ObservMeConfig,
+  options: ObsTraceSnapshotOptions,
+): Promise<ObsTraceTarget> {
+  const session = await resolveObsTraceSession(ctx, options);
+
+  if (request.scope === "current-session") return resolveCurrentSessionTraceTarget(session);
+  if (request.scope === "last-turn") return resolveLastTurnTraceTarget(session);
+  return resolveRequestedSessionTraceTarget(ctx, request, session, config, options);
+}
+
+async function resolveObsTraceSession(
+  ctx: ObsTraceCommandContext,
+  options: ObsTraceSnapshotOptions,
+): Promise<ObsTraceSessionSnapshot> {
+  if (options.getSession) return options.getSession(ctx);
+  return getLocalObsSessionSnapshot();
+}
+
+function resolveCurrentSessionTraceTarget(session: ObsTraceSessionSnapshot): ObsTraceTarget {
+  const traceId = normalizeOptionalString(session.traceId);
+  if (!traceId) throw new Error("No current ObservMe session trace is available.");
+
+  return {
+    scope: "current-session",
+    source: "runtime",
+    sessionId: normalizeOptionalString(session.sessionId),
+    traceId,
+  };
+}
+
+function resolveLastTurnTraceTarget(session: ObsTraceSessionSnapshot): ObsTraceTarget {
+  const traceId = normalizeOptionalString(session.traceId);
+
+  if (normalizeTurnCount(session.turns) < 1) throw new Error("No last-turn ObservMe trace is available yet.");
+  if (!traceId) throw new Error("No last-turn ObservMe trace is available yet.");
+
+  return {
+    scope: "last-turn",
+    source: "runtime",
+    sessionId: normalizeOptionalString(session.sessionId),
+    traceId,
+  };
+}
+
+async function resolveRequestedSessionTraceTarget(
+  ctx: ObsTraceCommandContext,
+  request: ObsTraceRequest,
+  session: ObsTraceSessionSnapshot,
+  config: ObservMeConfig,
+  options: ObsTraceSnapshotOptions,
+): Promise<ObsTraceTarget> {
+  const sessionId = normalizeObsTraceSessionId(request.sessionId);
+  const localTraceId = resolveLocalTraceIdForSession(sessionId, session);
+
+  if (localTraceId) return { scope: "session", source: "runtime", sessionId, traceId: localTraceId };
+
+  const traceId = await resolveSessionTraceId(sessionId, ctx, config, options);
+  if (!traceId) throw new Error("No trace was found for the requested ObservMe session id.");
+  return { scope: "session", source: "tempo", sessionId, traceId };
+}
+
+async function resolveSessionTraceId(
+  sessionId: string,
+  ctx: ObsTraceCommandContext,
+  config: ObservMeConfig,
+  options: ObsTraceSnapshotOptions,
+): Promise<string | undefined> {
+  if (options.resolveSessionTraceId) return normalizeOptionalString(await options.resolveSessionTraceId(sessionId, ctx, config));
+  return searchSessionTraceId(config, sessionId, options);
+}
+
+async function searchSessionTraceId(
+  config: ObservMeConfig,
+  sessionId: string,
+  options: ObsTraceSnapshotOptions,
+): Promise<string | undefined> {
+  const traces = await searchTempo(
+    config,
+    { [COMMON_SPAN_ATTRIBUTES.PI_SESSION_ID]: sessionId },
+    createObsTraceSearchRange(options),
+    { fetch: options.fetch },
+  );
+
+  return readFirstTraceId(traces);
+}
+
+function readFirstTraceId(traces: readonly TraceSummary[]): string | undefined {
+  return traces.map(trace => normalizeOptionalString(trace.traceId)).find(isString);
+}
+
+function createObsTraceSearchRange(options: ObsTraceSnapshotOptions): TimeRange {
+  const to = options.now?.() ?? new Date();
+  const rangeHours = normalizeSearchRangeHours(options.searchRangeHours);
+  return { from: new Date(to.getTime() - rangeHours * millisecondsPerHour), to };
+}
+
+function normalizeSearchRangeHours(value: number | undefined): number {
+  if (value === undefined || !Number.isFinite(value) || value <= 0) return DEFAULT_TRACE_SEARCH_RANGE_HOURS;
+  return value;
+}
+
+function resolveLocalTraceIdForSession(sessionId: string, session: ObsTraceSessionSnapshot): string | undefined {
+  const currentSessionId = normalizeOptionalString(session.sessionId);
+  const traceId = normalizeOptionalString(session.traceId);
+
+  if (!currentSessionId || currentSessionId !== sessionId) return undefined;
+  return traceId;
+}
+
+function normalizeObsTraceSessionId(value: string | undefined): string {
+  return normalizeObservMeSessionId(value, { emptyMessage: "Unsafe ObservMe session id: empty values are not query inputs." });
+}
+
+function normalizeOptionalString(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed || undefined;
+}
+
+function normalizeTurnCount(value: number | undefined): number {
+  if (value === undefined || !Number.isFinite(value) || value < 0) return 0;
+  return Math.trunc(value);
+}
+
+function parseObsTraceOptions(tokens: readonly string[]): ParsedObsTraceRequest {
+  if (tokens.length === 0) return { request: defaultObsTraceRequest };
+
+  const state: ObsTraceParseState = { index: 0 };
+
+  while (state.index < tokens.length) {
+    const result = parseObsTraceOption(tokens, state);
+    if (result.error) return result;
+  }
+
+  return { request: state.request ?? defaultObsTraceRequest };
+}
+
+function parseObsTraceOption(tokens: readonly string[], state: ObsTraceParseState): ParsedObsTraceRequest {
+  const token = tokens[state.index];
+  const normalizedToken = token.toLowerCase();
+
+  if (isCurrentSessionToken(normalizedToken)) return setObsTraceRequest(state, token, defaultObsTraceRequest, state.index + 1);
+  if (normalizedToken === "--last-turn") return setObsTraceRequest(state, token, { scope: "last-turn" }, state.index + 1);
+  if (normalizedToken === "--session") return parseSeparateSessionTraceOption(tokens, state, token);
+  if (normalizedToken.startsWith("--session=")) return parseInlineSessionTraceOption(state, token);
+  return { error: unknownObsOptionMessage(token) };
+}
+
+function parseSeparateSessionTraceOption(tokens: readonly string[], state: ObsTraceParseState, token: string): ParsedObsTraceRequest {
+  const sessionId = tokens[state.index + 1];
+  if (!sessionId || sessionId.startsWith("--")) return { error: missingObsOptionValueMessage("--session") };
+  return setObsTraceRequest(state, token, { scope: "session", sessionId }, state.index + 2);
+}
+
+function parseInlineSessionTraceOption(state: ObsTraceParseState, token: string): ParsedObsTraceRequest {
+  const sessionId = token.slice("--session=".length);
+  if (!sessionId) return { error: missingObsOptionValueMessage("--session") };
+  return setObsTraceRequest(state, "--session", { scope: "session", sessionId }, state.index + 1);
+}
+
+function setObsTraceRequest(
+  state: ObsTraceParseState,
+  token: string,
+  request: ObsTraceRequest,
+  nextIndex: number,
+): ParsedObsTraceRequest {
+  if (state.request) return { error: `Repeated or conflicting option: ${token}.` };
+  state.request = request;
+  state.index = nextIndex;
+  return {};
+}
+
+function isCurrentSessionToken(token: string): boolean {
+  return token === "--current-session";
+}
+
+function formatObsTraceScope(scope: ObsTraceScope): string {
+  if (scope === "current-session") return "current session";
+  if (scope === "last-turn") return "last turn";
+  return "session";
+}
+
+function formatObsTraceVisibilityNote(snapshot: ObsTraceSnapshot): string | undefined {
+  if (snapshot.source !== "runtime") return undefined;
+  return OBS_TRACE_ACTIVE_SESSION_NOTE;
+}
+
+function isString(value: string | undefined): value is string {
+  return value !== undefined && value.length > 0;
+}
+
+export function resolveObsTraceDiagnostic(error: unknown): ObsCommandRecoveryHint {
+  const message = readObsDiagnosticMessage(error);
+
+  if (isObsTraceSessionErrorMessage(message)) return { subsystem: "Session trace", nextAction: OBS_TRACE_SESSION_ERROR_NEXT_ACTION };
+  if (isObsTraceNotFoundMessage(message)) return { subsystem: "Tempo", nextAction: OBS_TRACE_NOT_FOUND_NEXT_ACTION };
+  return { subsystem: "Tempo", nextAction: OBS_TRACE_TEMPO_ERROR_NEXT_ACTION };
+}
+
+function isObsTraceSessionErrorMessage(message: string): boolean {
+  return /No current ObservMe session trace|No last-turn ObservMe trace|Unsafe ObservMe session id/u.test(message);
+}
+
+function isObsTraceNotFoundMessage(message: string): boolean {
+  return /No trace was found/u.test(message);
+}

package/src/commands/obs.ts

@@ -0,0 +1,211 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { RegisterObsBackfillCommandOptions } from "./obs-backfill.ts";
+import { handleObsBackfillCommand } from "./obs-backfill.ts";
+import type { ObsAgentsCommandContext, RegisterObsAgentsCommandOptions } from "./obs-agents.ts";
+import { handleObsAgentsCommand } from "./obs-agents.ts";
+import type { ObsCostCommandContext, RegisterObsCostCommandOptions } from "./obs-cost.ts";
+import { handleObsCostCommand } from "./obs-cost.ts";
+import type { ObsErrorsCommandContext, RegisterObsErrorsCommandOptions } from "./obs-errors.ts";
+import { handleObsErrorsCommand } from "./obs-errors.ts";
+import type { ObsHealthCommandContext, RegisterObsHealthCommandOptions } from "./obs-health.ts";
+import { handleObsHealthCommand } from "./obs-health.ts";
+import type { ObsLinkCommandContext, RegisterObsLinkCommandOptions } from "./obs-link.ts";
+import { handleObsLinkCommand } from "./obs-link.ts";
+import type { ObsLogsCommandContext, RegisterObsLogsCommandOptions } from "./obs-logs.ts";
+import { handleObsLogsCommand } from "./obs-logs.ts";
+import type { ObsSessionCommandContext, RegisterObsSessionCommandOptions } from "./obs-session.ts";
+import { handleObsSessionCommand } from "./obs-session.ts";
+import type { ObsStatusCommandContext, RegisterObsStatusCommandOptions } from "./obs-status.ts";
+import { handleObsStatusCommand } from "./obs-status.ts";
+import type { ObsToolsCommandContext, RegisterObsToolsCommandOptions } from "./obs-tools.ts";
+import { handleObsToolsCommand } from "./obs-tools.ts";
+import type { ObsTraceCommandContext, RegisterObsTraceCommandOptions } from "./obs-trace.ts";
+import { handleObsTraceCommand } from "./obs-trace.ts";
+import { completeObsSubcommands, firstObsCommandToken, obsUsageWithError } from "./obs-args.ts";
+
+export interface ObsCommandContext
+  extends ObsStatusCommandContext,
+    ObsHealthCommandContext,
+    ObsSessionCommandContext,
+    ObsCostCommandContext,
+    ObsTraceCommandContext,
+    ObsToolsCommandContext,
+    ObsAgentsCommandContext,
+    ObsErrorsCommandContext,
+    ObsLogsCommandContext,
+    ObsLinkCommandContext {}
+
+export interface RegisterObsCommandOptions {
+  readonly status?: RegisterObsStatusCommandOptions;
+  readonly health?: RegisterObsHealthCommandOptions;
+  readonly session?: RegisterObsSessionCommandOptions;
+  readonly cost?: RegisterObsCostCommandOptions;
+  readonly trace?: RegisterObsTraceCommandOptions;
+  readonly tools?: RegisterObsToolsCommandOptions;
+  readonly agents?: RegisterObsAgentsCommandOptions;
+  readonly backfill?: RegisterObsBackfillCommandOptions;
+  readonly errors?: RegisterObsErrorsCommandOptions;
+  readonly logs?: RegisterObsLogsCommandOptions;
+  readonly link?: RegisterObsLinkCommandOptions;
+}
+
+const OBS_COMMAND_NAME = "obs";
+const OBS_DEFAULT_SUBCOMMAND = "status" satisfies ObsRootSubcommandName;
+
+type ObsRootArgsMode = "raw" | "subcommand";
+export type ObsRootSubcommandName = keyof RegisterObsCommandOptions;
+
+type ObsSubcommandHandler<Options> = (
+  args: string,
+  ctx: ObsCommandContext,
+  options?: Options,
+) => Promise<void>;
+
+type ObsSubcommandRegistry = {
+  readonly [Name in ObsRootSubcommandName]: {
+    readonly rootArgs: ObsRootArgsMode;
+    readonly handle: ObsSubcommandHandler<RegisterObsCommandOptions[Name]>;
+    readonly selectOptions: (options: RegisterObsCommandOptions) => RegisterObsCommandOptions[Name];
+  };
+};
+
+const obsSubcommandRegistry = {
+  status: {
+    rootArgs: "subcommand",
+    handle: handleObsStatusCommand,
+    selectOptions: options => options.status,
+  },
+  health: {
+    rootArgs: "subcommand",
+    handle: handleObsHealthCommand,
+    selectOptions: options => options.health,
+  },
+  session: {
+    rootArgs: "subcommand",
+    handle: handleObsSessionCommand,
+    selectOptions: options => options.session,
+  },
+  cost: {
+    rootArgs: "raw",
+    handle: handleObsCostCommand,
+    selectOptions: options => options.cost,
+  },
+  trace: {
+    rootArgs: "raw",
+    handle: handleObsTraceCommand,
+    selectOptions: options => options.trace,
+  },
+  tools: {
+    rootArgs: "raw",
+    handle: handleObsToolsCommand,
+    selectOptions: options => options.tools,
+  },
+  agents: {
+    rootArgs: "raw",
+    handle: handleObsAgentsCommand,
+    selectOptions: options => options.agents,
+  },
+  backfill: {
+    rootArgs: "raw",
+    handle: handleObsBackfillCommand,
+    selectOptions: options => options.backfill,
+  },
+  errors: {
+    rootArgs: "raw",
+    handle: handleObsErrorsCommand,
+    selectOptions: options => options.errors,
+  },
+  logs: {
+    rootArgs: "raw",
+    handle: handleObsLogsCommand,
+    selectOptions: options => options.logs,
+  },
+  link: {
+    rootArgs: "raw",
+    handle: handleObsLinkCommand,
+    selectOptions: options => options.link,
+  },
+} as const satisfies ObsSubcommandRegistry;
+
+const obsSubcommands = Object.keys(obsSubcommandRegistry) as ObsRootSubcommandName[];
+const OBS_ROOT_USAGE = buildObsRootUsage(obsSubcommands);
+
+export function registerObsCommand(pi: ExtensionAPI, options: RegisterObsCommandOptions = {}): void {
+  const command = new ObsCommand(options);
+
+  pi.registerCommand(OBS_COMMAND_NAME, {
+    description: `Run ObservMe commands. ${OBS_ROOT_USAGE}`,
+    getArgumentCompletions: getObsRootCommandArgumentCompletions,
+    handler: command.handle.bind(command),
+  });
+}
+
+export async function handleObsCommand(
+  args: string,
+  ctx: ObsCommandContext,
+  options: RegisterObsCommandOptions = {},
+): Promise<void> {
+  const subcommand = firstObsCommandToken(args);
+  const rootSubcommand = resolveObsRootSubcommand(subcommand);
+
+  if (rootSubcommand) {
+    await dispatchObsRootSubcommand(rootSubcommand, args, ctx, options);
+    return;
+  }
+
+  await ctx.ui?.notify?.(obsUsageWithError(OBS_ROOT_USAGE, subcommand ? `Unknown subcommand: ${subcommand}.` : undefined), "warning");
+}
+
+export function getObsRootCommandArgumentCompletions(prefix: string): Array<{ value: string; label: string }> | null {
+  return completeObsSubcommands(prefix, obsSubcommands);
+}
+
+export function getObsRootSubcommands(): readonly ObsRootSubcommandName[] {
+  return [...obsSubcommands];
+}
+
+export function getObsRootUsage(): string {
+  return OBS_ROOT_USAGE;
+}
+
+function buildObsRootUsage(subcommands: readonly ObsRootSubcommandName[]): string {
+  return `Usage: /obs <${subcommands.join("|")}>`;
+}
+
+function resolveObsRootSubcommand(subcommand: string | undefined): ObsRootSubcommandName | undefined {
+  if (!subcommand) return OBS_DEFAULT_SUBCOMMAND;
+  if (isObsRootSubcommandName(subcommand)) return subcommand;
+  return undefined;
+}
+
+function isObsRootSubcommandName(value: string): value is ObsRootSubcommandName {
+  return Object.hasOwn(obsSubcommandRegistry, value);
+}
+
+async function dispatchObsRootSubcommand<Name extends ObsRootSubcommandName>(
+  subcommand: Name,
+  args: string,
+  ctx: ObsCommandContext,
+  options: RegisterObsCommandOptions,
+): Promise<void> {
+  const registration: ObsSubcommandRegistry[Name] = obsSubcommandRegistry[subcommand];
+  const handlerArgs = getObsRootHandlerArgs(subcommand, args, registration.rootArgs);
+  await registration.handle(handlerArgs, ctx, registration.selectOptions(options));
+}
+
+function getObsRootHandlerArgs(subcommand: ObsRootSubcommandName, args: string, rootArgs: ObsRootArgsMode): string {
+  if (rootArgs === "subcommand") return subcommand;
+  return args;
+}
+
+class ObsCommand {
+  readonly #options: RegisterObsCommandOptions;
+
+  constructor(options: RegisterObsCommandOptions) {
+    this.#options = options;
+  }
+
+  async handle(args: string, ctx: ObsCommandContext): Promise<void> {
+    await handleObsCommand(args, ctx, this.#options);
+  }
+}