@gokulvenkatareddy/cortex 0.1.7

package/apps/octogent/apps/web/src/app/hooks/useTerminalCompletionNotification.ts

@@ -0,0 +1,94 @@
+import { useCallback, useEffect, useRef } from "react";
+
+import {
+  type TerminalCompletionSoundId,
+  buildTerminalCompletionSoundDataUrl,
+} from "../notificationSounds";
+import type { TerminalRuntimeStateStore } from "../terminalRuntimeStateStore";
+
+const createCompletionAudio = (soundId: TerminalCompletionSoundId): HTMLAudioElement | null => {
+  if (soundId === "silent" || typeof Audio === "undefined") {
+    return null;
+  }
+
+  if (import.meta.env.MODE === "test" && !("mock" in Audio)) {
+    return null;
+  }
+
+  const source = buildTerminalCompletionSoundDataUrl(soundId);
+  if (!source) {
+    return null;
+  }
+
+  const audio = new Audio(source);
+  audio.preload = "auto";
+  return audio;
+};
+
+export const useTerminalCompletionNotification = (
+  runtimeStateStore: TerminalRuntimeStateStore,
+  selectedSound: TerminalCompletionSoundId,
+) => {
+  const previousTerminalStatesRef = useRef(runtimeStateStore.getSnapshot());
+  const audioCacheRef = useRef<Partial<Record<TerminalCompletionSoundId, HTMLAudioElement | null>>>(
+    {},
+  );
+
+  const playCompletionSound = useCallback((soundId: TerminalCompletionSoundId) => {
+    if (soundId === "silent") {
+      return;
+    }
+
+    if (audioCacheRef.current[soundId] === undefined) {
+      audioCacheRef.current[soundId] = createCompletionAudio(soundId);
+    }
+
+    const audio = audioCacheRef.current[soundId];
+    if (!audio) {
+      return;
+    }
+
+    audio.currentTime = 0;
+    try {
+      const playResult = audio.play();
+      if (typeof playResult?.catch === "function") {
+        void playResult.catch(() => {
+          // Browsers can block untrusted audio playback; ignore and keep UI responsive.
+        });
+      }
+    } catch {
+      // Some environments throw synchronously for media playback; ignore.
+    }
+  }, []);
+
+  useEffect(() => {
+    previousTerminalStatesRef.current = runtimeStateStore.getSnapshot();
+
+    return runtimeStateStore.subscribe(() => {
+      const previousTerminalStates = previousTerminalStatesRef.current;
+      const nextTerminalStates = runtimeStateStore.getSnapshot();
+      const shouldPlayCompletionSound = Object.entries(nextTerminalStates).some(
+        ([terminalId, state]) =>
+          previousTerminalStates[terminalId]?.state === "processing" && state.state === "idle",
+      );
+
+      previousTerminalStatesRef.current = nextTerminalStates;
+      if (!shouldPlayCompletionSound) {
+        return;
+      }
+
+      playCompletionSound(selectedSound);
+    });
+  }, [playCompletionSound, runtimeStateStore, selectedSound]);
+
+  const playCompletionSoundPreview = useCallback(
+    (soundId?: TerminalCompletionSoundId) => {
+      playCompletionSound(soundId ?? selectedSound);
+    },
+    [playCompletionSound, selectedSound],
+  );
+
+  return {
+    playCompletionSoundPreview,
+  };
+};

package/apps/octogent/apps/web/src/app/hooks/useTerminalMutations.ts

@@ -0,0 +1,266 @@
+import { useCallback, useRef, useState } from "react";
+import type { Dispatch, SetStateAction } from "react";
+
+import type { TerminalAgentProvider, TerminalView, TerminalWorkspaceMode } from "../types";
+
+export type PendingDeleteTerminal = {
+  terminalId: string;
+  tentacleName: string;
+  workspaceMode: TerminalWorkspaceMode;
+  intent: "delete-terminal" | "cleanup-worktree";
+};
+
+type UseTerminalMutationsOptions = {
+  readColumns: () => Promise<TerminalView>;
+  setColumns: Dispatch<SetStateAction<TerminalView>>;
+  setLoadError: Dispatch<SetStateAction<string | null>>;
+  setMinimizedTerminalIds: Dispatch<SetStateAction<string[]>>;
+};
+
+type UseTerminalMutationsResult = {
+  editingTerminalId: string | null;
+  terminalNameDraft: string;
+  isCreatingTerminal: boolean;
+  isDeletingTerminalId: string | null;
+  pendingDeleteTerminal: PendingDeleteTerminal | null;
+  setTerminalNameDraft: Dispatch<SetStateAction<string>>;
+  setEditingTerminalId: Dispatch<SetStateAction<string | null>>;
+  beginTerminalNameEdit: (terminalId: string, currentTerminalName: string) => void;
+  submitTerminalRename: (terminalId: string, currentTerminalName: string) => Promise<void>;
+  createTerminal: (
+    workspaceMode: TerminalWorkspaceMode,
+    agentProvider?: TerminalAgentProvider,
+    tentacleId?: string,
+  ) => Promise<string | undefined>;
+  requestDeleteTerminal: (
+    terminalId: string,
+    terminalName: string,
+    options?: {
+      workspaceMode?: TerminalWorkspaceMode;
+      intent?: "delete-terminal" | "cleanup-worktree";
+    },
+  ) => void;
+  confirmDeleteTerminal: () => Promise<void>;
+  clearPendingDeleteTerminal: () => void;
+  cancelTerminalRename: () => void;
+};
+
+export const useTerminalMutations = ({
+  readColumns,
+  setColumns,
+  setLoadError,
+  setMinimizedTerminalIds,
+}: UseTerminalMutationsOptions): UseTerminalMutationsResult => {
+  const [editingTerminalId, setEditingTerminalId] = useState<string | null>(null);
+  const [terminalNameDraft, setTerminalNameDraft] = useState("");
+  const [isCreatingTerminal, setIsCreatingTerminal] = useState(false);
+  const [isDeletingTerminalId, setIsDeletingTerminalId] = useState<string | null>(null);
+  const [pendingDeleteTerminal, setPendingDeleteTerminal] = useState<PendingDeleteTerminal | null>(
+    null,
+  );
+  const cancelTerminalNameSubmitRef = useRef(false);
+
+  const beginTerminalNameEdit = useCallback(
+    (terminalId: string, currentTerminalName: string) => {
+      setLoadError(null);
+      setEditingTerminalId(terminalId);
+      setTerminalNameDraft(currentTerminalName);
+    },
+    [setLoadError],
+  );
+
+  const submitTerminalRename = useCallback(
+    async (terminalId: string, currentTerminalName: string) => {
+      if (cancelTerminalNameSubmitRef.current) {
+        cancelTerminalNameSubmitRef.current = false;
+        return;
+      }
+
+      const trimmedName = terminalNameDraft.trim();
+      if (trimmedName.length === 0) {
+        setLoadError("Terminal name cannot be empty.");
+        return;
+      }
+
+      if (trimmedName === currentTerminalName) {
+        setEditingTerminalId(null);
+        return;
+      }
+
+      try {
+        setLoadError(null);
+        const encodedTerminalId = encodeURIComponent(terminalId);
+        const response = await fetch(`/api/terminals/${encodedTerminalId}`, {
+          method: "PATCH",
+          headers: {
+            Accept: "application/json",
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({ name: trimmedName }),
+        });
+
+        if (!response.ok) {
+          throw new Error(`Unable to rename terminal (${response.status})`);
+        }
+
+        const nextColumns = await readColumns();
+        setColumns(nextColumns);
+        setEditingTerminalId(null);
+      } catch {
+        setLoadError("Unable to rename terminal.");
+      }
+    },
+    [readColumns, setColumns, setLoadError, terminalNameDraft],
+  );
+
+  const createTerminal = useCallback(
+    async (
+      workspaceMode: TerminalWorkspaceMode,
+      agentProvider?: TerminalAgentProvider,
+      tentacleId?: string,
+    ) => {
+      try {
+        setIsCreatingTerminal(true);
+        setLoadError(null);
+        const response = await fetch("/api/terminals", {
+          method: "POST",
+          headers: {
+            Accept: "application/json",
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({
+            workspaceMode,
+            agentProvider: agentProvider ?? "claude-code",
+            ...(tentacleId ? { tentacleId } : {}),
+          }),
+        });
+
+        if (!response.ok) {
+          throw new Error(`Unable to create terminal (${response.status})`);
+        }
+
+        const createdSnapshot = (await response.json()) as {
+          terminalId?: unknown;
+          tentacleName?: unknown;
+        };
+        const nextColumns = await readColumns();
+        setColumns(nextColumns);
+
+        const createdTerminalId =
+          typeof createdSnapshot.terminalId === "string" ? createdSnapshot.terminalId : null;
+        if (!createdTerminalId) {
+          return undefined;
+        }
+
+        const createdEntry = nextColumns.find((entry) => entry.terminalId === createdTerminalId);
+        const createdTerminalName =
+          createdEntry?.tentacleName ??
+          (typeof createdSnapshot.tentacleName === "string"
+            ? createdSnapshot.tentacleName
+            : createdTerminalId);
+        setMinimizedTerminalIds((current) => current.filter((id) => id !== createdTerminalId));
+        beginTerminalNameEdit(createdTerminalId, createdTerminalName);
+        return createdTerminalId;
+      } catch {
+        setLoadError("Unable to create a new terminal.");
+        return undefined;
+      } finally {
+        setIsCreatingTerminal(false);
+      }
+    },
+    [beginTerminalNameEdit, readColumns, setColumns, setLoadError, setMinimizedTerminalIds],
+  );
+
+  const requestDeleteTerminal = useCallback(
+    (
+      terminalId: string,
+      terminalName: string,
+      options?: {
+        workspaceMode?: TerminalWorkspaceMode;
+        intent?: "delete-terminal" | "cleanup-worktree";
+      },
+    ) => {
+      setLoadError(null);
+      setPendingDeleteTerminal({
+        terminalId,
+        tentacleName: terminalName,
+        workspaceMode: options?.workspaceMode ?? "shared",
+        intent: options?.intent ?? "delete-terminal",
+      });
+    },
+    [setLoadError],
+  );
+
+  const confirmDeleteTerminal = useCallback(async () => {
+    if (!pendingDeleteTerminal) {
+      return;
+    }
+
+    const { terminalId } = pendingDeleteTerminal;
+    try {
+      setLoadError(null);
+      setIsDeletingTerminalId(terminalId);
+      const encodedTerminalId = encodeURIComponent(terminalId);
+      const response = await fetch(`/api/terminals/${encodedTerminalId}`, {
+        method: "DELETE",
+        headers: {
+          Accept: "application/json",
+        },
+      });
+
+      if (!response.ok) {
+        throw new Error(`Unable to delete terminal (${response.status})`);
+      }
+
+      if (editingTerminalId === terminalId) {
+        setEditingTerminalId(null);
+        setTerminalNameDraft("");
+      }
+      setMinimizedTerminalIds((current) =>
+        current.filter((currentTerminalId) => currentTerminalId !== terminalId),
+      );
+
+      const nextColumns = await readColumns();
+      setColumns(nextColumns);
+      setPendingDeleteTerminal(null);
+    } catch {
+      setLoadError("Unable to delete terminal.");
+    } finally {
+      setIsDeletingTerminalId(null);
+    }
+  }, [
+    editingTerminalId,
+    pendingDeleteTerminal,
+    readColumns,
+    setColumns,
+    setLoadError,
+    setMinimizedTerminalIds,
+  ]);
+
+  const clearPendingDeleteTerminal = useCallback(() => {
+    setPendingDeleteTerminal(null);
+  }, []);
+
+  const cancelTerminalRename = useCallback(() => {
+    cancelTerminalNameSubmitRef.current = true;
+    setEditingTerminalId(null);
+    setTerminalNameDraft("");
+  }, []);
+
+  return {
+    editingTerminalId,
+    terminalNameDraft,
+    isCreatingTerminal,
+    isDeletingTerminalId,
+    pendingDeleteTerminal,
+    setTerminalNameDraft,
+    setEditingTerminalId,
+    beginTerminalNameEdit,
+    submitTerminalRename,
+    createTerminal,
+    requestDeleteTerminal,
+    confirmDeleteTerminal,
+    clearPendingDeleteTerminal,
+    cancelTerminalRename,
+  };
+};

package/apps/octogent/apps/web/src/app/hooks/useTerminalStateReconciliation.ts

@@ -0,0 +1,23 @@
+import { useEffect } from "react";
+import type { Dispatch, SetStateAction } from "react";
+
+import { retainActiveTerminalIds } from "../terminalState";
+import type { TerminalView } from "../types";
+
+type UseTerminalStateReconciliationOptions = {
+  columns: TerminalView;
+  setMinimizedTerminalIds: Dispatch<SetStateAction<string[]>>;
+  onActiveTerminalIdsChange?: (activeTerminalIds: ReadonlySet<string>) => void;
+};
+
+export const useTerminalStateReconciliation = ({
+  columns,
+  setMinimizedTerminalIds,
+  onActiveTerminalIdsChange,
+}: UseTerminalStateReconciliationOptions) => {
+  useEffect(() => {
+    const activeTerminalIds = new Set(columns.map((entry) => entry.terminalId));
+    setMinimizedTerminalIds((current) => retainActiveTerminalIds(current, activeTerminalIds));
+    onActiveTerminalIdsChange?.(activeTerminalIds);
+  }, [columns, onActiveTerminalIdsChange, setMinimizedTerminalIds]);
+};

package/apps/octogent/apps/web/src/app/hooks/useUsageHeatmapPolling.ts

@@ -0,0 +1,43 @@
+import { buildUsageHeatmapUrl } from "../../runtime/runtimeEndpoints";
+import { usePollingData } from "./usePollingData";
+
+export type UsageSlice = {
+  key: string;
+  tokens: number;
+};
+
+export type UsageDayEntry = {
+  date: string;
+  totalTokens: number;
+  projects: UsageSlice[];
+  models: UsageSlice[];
+  sessions: number;
+};
+
+export type UsageChartData = {
+  days: UsageDayEntry[];
+  projects: string[];
+  models: string[];
+};
+
+const POLL_INTERVAL_MS = 120_000;
+
+const normalize = (raw: unknown): UsageChartData | null => raw as UsageChartData | null;
+
+const fallback = (): UsageChartData => ({ days: [], projects: [], models: [] });
+
+export const useUsageHeatmapPolling = (options: { enabled: boolean }) => {
+  const { data, isLoading, refresh } = usePollingData<UsageChartData>({
+    fetchUrl: buildUsageHeatmapUrl("all"),
+    intervalMs: POLL_INTERVAL_MS,
+    normalize,
+    fallback,
+    enabled: options.enabled,
+  });
+
+  return {
+    heatmapData: data,
+    isLoadingHeatmap: isLoading,
+    refreshHeatmap: refresh,
+  };
+};

package/apps/octogent/apps/web/src/app/hooks/useWorkspaceSetup.ts

@@ -0,0 +1,80 @@
+import type { WorkspaceSetupSnapshot, WorkspaceSetupStepId } from "@octogent/core";
+import { useCallback, useEffect, useState } from "react";
+
+import { buildWorkspaceSetupStepUrl, buildWorkspaceSetupUrl } from "../../runtime/runtimeEndpoints";
+
+type UseWorkspaceSetupResult = {
+  workspaceSetup: WorkspaceSetupSnapshot | null;
+  isWorkspaceSetupLoading: boolean;
+  workspaceSetupError: string | null;
+  refreshWorkspaceSetup: () => Promise<WorkspaceSetupSnapshot | null>;
+  runWorkspaceSetupStep: (stepId: WorkspaceSetupStepId) => Promise<WorkspaceSetupSnapshot | null>;
+};
+
+const readErrorMessage = async (response: Response, fallback: string) => {
+  try {
+    const payload = (await response.json()) as { error?: unknown };
+    return typeof payload.error === "string" ? payload.error : fallback;
+  } catch {
+    return fallback;
+  }
+};
+
+export const useWorkspaceSetup = (): UseWorkspaceSetupResult => {
+  const [workspaceSetup, setWorkspaceSetup] = useState<WorkspaceSetupSnapshot | null>(null);
+  const [isWorkspaceSetupLoading, setIsWorkspaceSetupLoading] = useState(true);
+  const [workspaceSetupError, setWorkspaceSetupError] = useState<string | null>(null);
+
+  const refreshWorkspaceSetup = useCallback(async () => {
+    try {
+      setWorkspaceSetupError(null);
+      const response = await fetch(buildWorkspaceSetupUrl(), {
+        headers: { Accept: "application/json" },
+      });
+      if (!response.ok) {
+        throw new Error(await readErrorMessage(response, "Unable to load workspace setup."));
+      }
+      const payload = (await response.json()) as WorkspaceSetupSnapshot;
+      setWorkspaceSetup(payload);
+      return payload;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unable to load workspace setup.";
+      setWorkspaceSetupError(message);
+      return null;
+    } finally {
+      setIsWorkspaceSetupLoading(false);
+    }
+  }, []);
+
+  const runWorkspaceSetupStep = useCallback(async (stepId: WorkspaceSetupStepId) => {
+    try {
+      setWorkspaceSetupError(null);
+      const response = await fetch(buildWorkspaceSetupStepUrl(stepId), {
+        method: "POST",
+        headers: { Accept: "application/json" },
+      });
+      if (!response.ok) {
+        throw new Error(await readErrorMessage(response, `Unable to run ${stepId}.`));
+      }
+      const payload = (await response.json()) as WorkspaceSetupSnapshot;
+      setWorkspaceSetup(payload);
+      return payload;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : `Unable to run ${stepId}.`;
+      setWorkspaceSetupError(message);
+      return null;
+    }
+  }, []);
+
+  useEffect(() => {
+    void refreshWorkspaceSetup();
+  }, [refreshWorkspaceSetup]);
+
+  return {
+    workspaceSetup,
+    isWorkspaceSetupLoading,
+    workspaceSetupError,
+    refreshWorkspaceSetup,
+    runWorkspaceSetupStep,
+  };
+};

package/apps/octogent/apps/web/src/app/hotkeys.ts

@@ -0,0 +1,31 @@
+import { PRIMARY_NAV_MAX, type PrimaryNavIndex } from "./constants";
+const MAX_TICKER_QUERY_LENGTH = 16;
+const TICKER_QUERY_ALLOWED_PATTERN = /[^A-Z0-9._/-]/g;
+
+export const isEditableEventTarget = (target: EventTarget | null): boolean => {
+  if (
+    target instanceof HTMLInputElement ||
+    target instanceof HTMLTextAreaElement ||
+    target instanceof HTMLSelectElement
+  ) {
+    return true;
+  }
+
+  if (!(target instanceof HTMLElement)) {
+    return false;
+  }
+
+  return target.isContentEditable === true || target.contentEditable === "true";
+};
+
+export const parsePrimaryNavKey = (key: string): PrimaryNavIndex | null => {
+  const n = Number.parseInt(key, 10);
+  if (Number.isNaN(n) || n < 1 || n > PRIMARY_NAV_MAX) {
+    return null;
+  }
+
+  return n as PrimaryNavIndex;
+};
+
+export const normalizeTickerQueryInput = (value: string): string =>
+  value.toUpperCase().replace(TICKER_QUERY_ALLOWED_PATTERN, "").slice(0, MAX_TICKER_QUERY_LENGTH);

package/apps/octogent/apps/web/src/app/monitorNormalizers.ts

@@ -0,0 +1,145 @@
+import { asNumber, asRecord, asString } from "@octogent/core";
+
+import type {
+  MonitorConfigSnapshot,
+  MonitorFeedSnapshot,
+  MonitorPost,
+  MonitorUsageSnapshot,
+} from "./types";
+
+const normalizeMonitorUsageSnapshot = (value: unknown): MonitorUsageSnapshot | null => {
+  const record = asRecord(value);
+  if (!record) {
+    return null;
+  }
+
+  const status = record.status;
+  if (status !== "ok" && status !== "unavailable" && status !== "error") {
+    return null;
+  }
+
+  return {
+    status,
+    source: record.source === "x-api" ? "x-api" : "none",
+    fetchedAt: asString(record.fetchedAt) ?? new Date().toISOString(),
+    message: asString(record.message),
+    cap: asNumber(record.cap),
+    used: asNumber(record.used),
+    remaining: asNumber(record.remaining),
+    resetAt: asString(record.resetAt),
+  };
+};
+
+const normalizeMonitorPost = (value: unknown): MonitorPost | null => {
+  const record = asRecord(value);
+  if (!record) {
+    return null;
+  }
+
+  const id = asString(record.id);
+  const text = asString(record.text);
+  const author = asString(record.author);
+  const createdAt = asString(record.createdAt);
+  const permalink = asString(record.permalink);
+  const likeCount = asNumber(record.likeCount);
+  const matchedQueryTerm = asString(record.matchedQueryTerm);
+
+  if (!id || !text || !author || !createdAt || !permalink || likeCount === null) {
+    return null;
+  }
+
+  return {
+    source: "x",
+    id,
+    text,
+    author,
+    createdAt,
+    permalink,
+    likeCount: Math.max(0, Math.floor(likeCount)),
+    matchedQueryTerm,
+  };
+};
+
+export const normalizeMonitorConfigSnapshot = (value: unknown): MonitorConfigSnapshot | null => {
+  const record = asRecord(value);
+  if (!record || record.providerId !== "x") {
+    return null;
+  }
+
+  const queryTerms = Array.isArray(record.queryTerms)
+    ? record.queryTerms.filter((term): term is string => typeof term === "string")
+    : [];
+  const refreshPolicy = asRecord(record.refreshPolicy);
+  const searchWindowDaysRaw = asNumber(refreshPolicy?.searchWindowDays);
+  const searchWindowDays =
+    searchWindowDaysRaw === 1 || searchWindowDaysRaw === 3 || searchWindowDaysRaw === 7
+      ? searchWindowDaysRaw
+      : 7;
+  const providers = asRecord(record.providers);
+  const xProvider = providers ? asRecord(providers.x) : null;
+  const credentials = xProvider ? asRecord(xProvider.credentials) : null;
+  if (!credentials) {
+    return null;
+  }
+
+  return {
+    providerId: "x",
+    queryTerms,
+    refreshPolicy: {
+      maxCacheAgeMs: asNumber(refreshPolicy?.maxCacheAgeMs) ?? 24 * 60 * 60 * 1000,
+      maxPosts: asNumber(refreshPolicy?.maxPosts) ?? 30,
+      searchWindowDays,
+    },
+    providers: {
+      x: {
+        credentials: {
+          isConfigured: credentials.isConfigured === true,
+          bearerTokenHint: asString(credentials.bearerTokenHint),
+          apiKeyHint: asString(credentials.apiKeyHint),
+          hasApiSecret: credentials.hasApiSecret === true,
+          hasAccessToken: credentials.hasAccessToken === true,
+          hasAccessTokenSecret: credentials.hasAccessTokenSecret === true,
+          updatedAt: asString(credentials.updatedAt),
+        },
+      },
+    },
+  };
+};
+
+export const normalizeMonitorFeedSnapshot = (value: unknown): MonitorFeedSnapshot | null => {
+  const record = asRecord(value);
+  if (!record || record.providerId !== "x") {
+    return null;
+  }
+
+  const queryTerms = Array.isArray(record.queryTerms)
+    ? record.queryTerms.filter((term): term is string => typeof term === "string")
+    : [];
+  const refreshPolicy = asRecord(record.refreshPolicy);
+  const searchWindowDaysRaw = asNumber(refreshPolicy?.searchWindowDays);
+  const searchWindowDays =
+    searchWindowDaysRaw === 1 || searchWindowDaysRaw === 3 || searchWindowDaysRaw === 7
+      ? searchWindowDaysRaw
+      : 7;
+  const posts = Array.isArray(record.posts)
+    ? record.posts
+        .map((post) => normalizeMonitorPost(post))
+        .filter((post): post is MonitorPost => post !== null)
+    : [];
+
+  return {
+    providerId: "x",
+    queryTerms,
+    refreshPolicy: {
+      maxCacheAgeMs: asNumber(refreshPolicy?.maxCacheAgeMs) ?? 24 * 60 * 60 * 1000,
+      maxPosts: asNumber(refreshPolicy?.maxPosts) ?? 30,
+      searchWindowDays,
+    },
+    lastFetchedAt: asString(record.lastFetchedAt),
+    staleAfter: asString(record.staleAfter),
+    isStale: record.isStale === true,
+    lastError: asString(record.lastError),
+    posts,
+    usage: normalizeMonitorUsageSnapshot(record.usage),
+  };
+};