@gokulvenkatareddy/cortex 0.1.7

package/apps/octogent/apps/api/src/createApiServer/security.ts

@@ -0,0 +1,70 @@
+const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+
+export const withCors = (headers: Record<string, string>, corsOrigin: string | null) => {
+  const nextHeaders: Record<string, string> = {
+    ...headers,
+    "Access-Control-Allow-Methods": "GET, POST, PATCH, DELETE, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type",
+  };
+
+  if (corsOrigin) {
+    nextHeaders["Access-Control-Allow-Origin"] = corsOrigin;
+    nextHeaders.Vary = "Origin";
+  }
+
+  return nextHeaders;
+};
+
+const isLoopbackHostname = (hostname: string) => LOOPBACK_HOSTNAMES.has(hostname.toLowerCase());
+
+const parseHostname = (value: string, withScheme: boolean): string | null => {
+  try {
+    const url = new URL(withScheme ? value : `http://${value}`);
+    return url.hostname;
+  } catch {
+    return null;
+  }
+};
+
+export const isAllowedOriginHeader = (origin: string | undefined, allowRemoteAccess: boolean) => {
+  if (allowRemoteAccess || origin === undefined) {
+    return true;
+  }
+
+  const hostname = parseHostname(origin, true);
+  return hostname !== null && isLoopbackHostname(hostname);
+};
+
+export const isAllowedHostHeader = (host: string | undefined, allowRemoteAccess: boolean) => {
+  if (allowRemoteAccess) {
+    return true;
+  }
+
+  if (!host) {
+    return false;
+  }
+
+  const hostname = parseHostname(host, false);
+  return hostname !== null && isLoopbackHostname(hostname);
+};
+
+export const readHeaderValue = (header: string | string[] | undefined): string | undefined => {
+  if (typeof header !== "string") {
+    return undefined;
+  }
+
+  const trimmed = header.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+};
+
+export const getRequestCorsOrigin = (origin: string | undefined, allowRemoteAccess: boolean) => {
+  if (!origin) {
+    return null;
+  }
+
+  if (!allowRemoteAccess && !isAllowedOriginHeader(origin, allowRemoteAccess)) {
+    return null;
+  }
+
+  return origin;
+};

package/apps/octogent/apps/api/src/createApiServer/terminalParsers.ts

@@ -0,0 +1,167 @@
+import {
+  type TentacleWorkspaceMode,
+  type TerminalAgentProvider,
+  type TerminalNameOrigin,
+  isTerminalAgentProvider,
+} from "../terminalRuntime";
+
+const isTerminalNameOrigin = (value: unknown): value is TerminalNameOrigin =>
+  value === "generated" || value === "user" || value === "prompt";
+
+export const parseTerminalName = (payload: unknown) => {
+  if (payload === null || payload === undefined) {
+    return {
+      provided: false,
+      name: undefined as string | undefined,
+      error: null as string | null,
+    };
+  }
+
+  if (typeof payload !== "object") {
+    return {
+      provided: true,
+      name: undefined as string | undefined,
+      error: "Expected a JSON object body.",
+    };
+  }
+
+  const rawName = (payload as Record<string, unknown>).name;
+  if (rawName === undefined) {
+    return {
+      provided: false,
+      name: undefined as string | undefined,
+      error: null as string | null,
+    };
+  }
+
+  if (typeof rawName !== "string") {
+    return {
+      provided: true,
+      name: undefined as string | undefined,
+      error: "Terminal name must be a string.",
+    };
+  }
+
+  const trimmed = rawName.trim();
+  if (trimmed.length === 0) {
+    return {
+      provided: true,
+      name: undefined as string | undefined,
+      error: "Terminal name cannot be empty.",
+    };
+  }
+
+  return {
+    provided: true,
+    name: trimmed,
+    error: null as string | null,
+  };
+};
+
+export const parseTerminalWorkspaceMode = (payload: unknown) => {
+  if (payload === null || payload === undefined) {
+    return {
+      workspaceMode: "shared" as TentacleWorkspaceMode,
+      error: null as string | null,
+    };
+  }
+
+  if (typeof payload !== "object") {
+    return {
+      workspaceMode: "shared" as TentacleWorkspaceMode,
+      error: "Expected a JSON object body.",
+    };
+  }
+
+  const rawWorkspaceMode = (payload as Record<string, unknown>).workspaceMode;
+  if (rawWorkspaceMode === undefined) {
+    return {
+      workspaceMode: "shared" as TentacleWorkspaceMode,
+      error: null as string | null,
+    };
+  }
+
+  if (rawWorkspaceMode !== "shared" && rawWorkspaceMode !== "worktree") {
+    return {
+      workspaceMode: "shared" as TentacleWorkspaceMode,
+      error: "Terminal workspace mode must be either 'shared' or 'worktree'.",
+    };
+  }
+
+  return {
+    workspaceMode: rawWorkspaceMode as TentacleWorkspaceMode,
+    error: null as string | null,
+  };
+};
+
+export const parseTerminalAgentProvider = (payload: unknown) => {
+  if (payload === null || payload === undefined) {
+    return {
+      agentProvider: undefined as TerminalAgentProvider | undefined,
+      error: null as string | null,
+    };
+  }
+
+  if (typeof payload !== "object") {
+    return {
+      agentProvider: undefined as TerminalAgentProvider | undefined,
+      error: "Expected a JSON object body.",
+    };
+  }
+
+  const rawAgentProvider = (payload as Record<string, unknown>).agentProvider;
+  if (rawAgentProvider === undefined) {
+    return {
+      agentProvider: undefined as TerminalAgentProvider | undefined,
+      error: null as string | null,
+    };
+  }
+
+  if (!isTerminalAgentProvider(rawAgentProvider)) {
+    return {
+      agentProvider: undefined as TerminalAgentProvider | undefined,
+      error: "Terminal agent provider must be either 'codex' or 'claude-code'.",
+    };
+  }
+
+  return {
+    agentProvider: rawAgentProvider,
+    error: null as string | null,
+  };
+};
+
+export const parseTerminalNameOrigin = (payload: unknown) => {
+  if (payload === null || payload === undefined) {
+    return {
+      nameOrigin: undefined as TerminalNameOrigin | undefined,
+      error: null as string | null,
+    };
+  }
+
+  if (typeof payload !== "object") {
+    return {
+      nameOrigin: undefined as TerminalNameOrigin | undefined,
+      error: "Expected a JSON object body.",
+    };
+  }
+
+  const rawNameOrigin = (payload as Record<string, unknown>).nameOrigin;
+  if (rawNameOrigin === undefined) {
+    return {
+      nameOrigin: undefined as TerminalNameOrigin | undefined,
+      error: null as string | null,
+    };
+  }
+
+  if (!isTerminalNameOrigin(rawNameOrigin)) {
+    return {
+      nameOrigin: undefined as TerminalNameOrigin | undefined,
+      error: "Terminal name origin must be 'generated', 'user', or 'prompt'.",
+    };
+  }
+
+  return {
+    nameOrigin: rawNameOrigin,
+    error: null as string | null,
+  };
+};

package/apps/octogent/apps/api/src/createApiServer/terminalRoutes.ts

@@ -0,0 +1,315 @@
+import { join } from "node:path";
+import { readDeckTentacles } from "../deck/readDeckTentacles";
+import { resolvePrompt } from "../prompts";
+import {
+  RuntimeInputError,
+  type TentacleWorkspaceMode,
+  type TerminalAgentProvider,
+  type TerminalNameOrigin,
+} from "../terminalRuntime";
+import type { ApiRouteHandler } from "./routeHelpers";
+import {
+  readJsonBodyOrWriteError,
+  writeJson,
+  writeMethodNotAllowed,
+  writeNoContent,
+} from "./routeHelpers";
+import {
+  parseTerminalAgentProvider,
+  parseTerminalName,
+  parseTerminalNameOrigin,
+  parseTerminalWorkspaceMode,
+} from "./terminalParsers";
+
+const buildTentacleInitialPrompt = (
+  promptsDir: string,
+  workspaceCwd: string,
+  projectStateDir: string,
+  tentacleId: string,
+): Promise<string | undefined> => {
+  const tentacle = readDeckTentacles(workspaceCwd, projectStateDir).find(
+    (entry) => entry.tentacleId === tentacleId,
+  );
+  if (!tentacle) {
+    return Promise.resolve(undefined);
+  }
+
+  const tentacleFolderPath = join(".octogent", "tentacles", tentacleId);
+  return resolvePrompt(promptsDir, "tentacle-context-init", {
+    tentacleName: tentacle.displayName,
+    tentacleId,
+    tentacleContextPath: tentacleFolderPath,
+  });
+};
+
+export const handleTerminalSnapshotsRoute: ApiRouteHandler = async (
+  { request, response, requestUrl, corsOrigin },
+  { runtime },
+) => {
+  if (requestUrl.pathname !== "/api/terminal-snapshots") {
+    return false;
+  }
+
+  if (request.method !== "GET") {
+    writeMethodNotAllowed(response, corsOrigin);
+    return true;
+  }
+
+  const payload = runtime.listTerminalSnapshots();
+  writeJson(response, 200, payload, corsOrigin);
+  return true;
+};
+
+export const handleTerminalsCollectionRoute: ApiRouteHandler = async (
+  { request, response, requestUrl, corsOrigin },
+  { runtime, workspaceCwd, projectStateDir, promptsDir, userPromptsDir, getApiPort },
+) => {
+  if (requestUrl.pathname !== "/api/terminals") {
+    return false;
+  }
+
+  if (request.method !== "POST") {
+    writeMethodNotAllowed(response, corsOrigin);
+    return true;
+  }
+
+  const bodyReadResult = await readJsonBodyOrWriteError(request, response, corsOrigin);
+  if (!bodyReadResult.ok) {
+    return true;
+  }
+
+  const nameResult = parseTerminalName(bodyReadResult.payload);
+  if (nameResult.error) {
+    writeJson(response, 400, { error: nameResult.error }, corsOrigin);
+    return true;
+  }
+
+  const workspaceModeResult = parseTerminalWorkspaceMode(bodyReadResult.payload);
+  if (workspaceModeResult.error) {
+    writeJson(response, 400, { error: workspaceModeResult.error }, corsOrigin);
+    return true;
+  }
+
+  const agentProviderResult = parseTerminalAgentProvider(bodyReadResult.payload);
+  if (agentProviderResult.error) {
+    writeJson(response, 400, { error: agentProviderResult.error }, corsOrigin);
+    return true;
+  }
+
+  const nameOriginResult = parseTerminalNameOrigin(bodyReadResult.payload);
+  if (nameOriginResult.error) {
+    writeJson(response, 400, { error: nameOriginResult.error }, corsOrigin);
+    return true;
+  }
+
+  try {
+    const createTerminalInput: {
+      terminalId?: string;
+      tentacleId?: string;
+      worktreeId?: string;
+      tentacleName?: string;
+      workspaceMode: TentacleWorkspaceMode;
+      agentProvider?: TerminalAgentProvider;
+      nameOrigin?: TerminalNameOrigin;
+      initialPrompt?: string;
+      initialInputDraft?: string;
+      autoRenamePromptContext?: string;
+      parentTerminalId?: string;
+    } = {
+      workspaceMode: workspaceModeResult.workspaceMode,
+    };
+    if (nameResult.name !== undefined) {
+      createTerminalInput.tentacleName = nameResult.name;
+    }
+    if (agentProviderResult.agentProvider !== undefined) {
+      createTerminalInput.agentProvider = agentProviderResult.agentProvider;
+    }
+    if (nameOriginResult.nameOrigin !== undefined) {
+      createTerminalInput.nameOrigin = nameOriginResult.nameOrigin;
+    }
+    const bodyPayload = bodyReadResult.payload as Record<string, unknown> | null;
+    if (
+      bodyPayload &&
+      typeof bodyPayload.terminalId === "string" &&
+      bodyPayload.terminalId.trim().length > 0
+    ) {
+      createTerminalInput.terminalId = bodyPayload.terminalId.trim();
+    }
+    if (
+      bodyPayload &&
+      typeof bodyPayload.tentacleId === "string" &&
+      bodyPayload.tentacleId.trim().length > 0
+    ) {
+      createTerminalInput.tentacleId = bodyPayload.tentacleId.trim();
+    }
+    if (
+      bodyPayload &&
+      typeof bodyPayload.parentTerminalId === "string" &&
+      bodyPayload.parentTerminalId.trim().length > 0
+    ) {
+      createTerminalInput.parentTerminalId = bodyPayload.parentTerminalId.trim();
+    }
+    if (
+      bodyPayload &&
+      typeof bodyPayload.autoRenamePromptContext === "string" &&
+      bodyPayload.autoRenamePromptContext.trim().length > 0
+    ) {
+      createTerminalInput.autoRenamePromptContext = bodyPayload.autoRenamePromptContext.trim();
+    }
+    if (
+      bodyPayload &&
+      typeof bodyPayload.worktreeId === "string" &&
+      bodyPayload.worktreeId.trim().length > 0
+    ) {
+      createTerminalInput.worktreeId = bodyPayload.worktreeId.trim();
+    }
+
+    // Support prompt resolution via template name + variables, or a raw string.
+    if (
+      bodyPayload &&
+      typeof bodyPayload.promptTemplate === "string" &&
+      bodyPayload.promptTemplate.trim().length > 0
+    ) {
+      const templateName = bodyPayload.promptTemplate.trim();
+      const templateVars: Record<string, string> =
+        bodyPayload.promptVariables != null &&
+        typeof bodyPayload.promptVariables === "object" &&
+        !Array.isArray(bodyPayload.promptVariables)
+          ? Object.fromEntries(
+              Object.entries(bodyPayload.promptVariables as Record<string, unknown>)
+                .filter(([, v]) => typeof v === "string")
+                .map(([k, v]) => [k, v as string]),
+            )
+          : {};
+
+      // Auto-inject terminalId variable so callers don't have to guess it.
+      // The runtime hasn't allocated the ID yet, so we use the tentacle name
+      // when provided (sandbox always passes its name).
+      if (!templateVars.terminalId && createTerminalInput.tentacleName) {
+        templateVars.terminalId = createTerminalInput.tentacleName;
+      }
+
+      // Auto-inject apiPort so prompt templates can reference the local API.
+      if (!templateVars.apiPort) {
+        templateVars.apiPort = getApiPort();
+      }
+
+      // Auto-inject userPromptsDir so prompt templates know where to save user prompts.
+      if (!templateVars.userPromptsDir) {
+        templateVars.userPromptsDir = userPromptsDir;
+      }
+
+      // Auto-inject existingTerminals summary so planner-style prompts have context.
+      if (!templateVars.existingTerminals) {
+        const deckTentacles = readDeckTentacles(workspaceCwd, projectStateDir);
+        if (deckTentacles.length > 0) {
+          const listing = deckTentacles
+            .map(
+              (t) =>
+                `- **${t.displayName}** (\`${t.tentacleId}\`): ${t.description || "(no description)"}`,
+            )
+            .join("\n");
+          templateVars.existingTerminals = `## Existing Terminals\n\nThe following departments already exist:\n\n${listing}\n\nConsider these when proposing new departments — avoid duplicates and note any gaps.`;
+        } else {
+          templateVars.existingTerminals =
+            "## Existing Terminals\n\nNo department terminals exist yet. You are starting from scratch.";
+        }
+      }
+
+      const resolved = await resolvePrompt(promptsDir, templateName, templateVars);
+      if (resolved !== undefined) {
+        createTerminalInput.initialPrompt = resolved;
+      }
+    } else if (
+      bodyPayload &&
+      typeof bodyPayload.initialPrompt === "string" &&
+      bodyPayload.initialPrompt.trim().length > 0
+    ) {
+      createTerminalInput.initialPrompt = bodyPayload.initialPrompt.trim();
+    }
+
+    if (!createTerminalInput.initialPrompt && createTerminalInput.tentacleId) {
+      const defaultTentaclePrompt = await buildTentacleInitialPrompt(
+        promptsDir,
+        workspaceCwd,
+        projectStateDir,
+        createTerminalInput.tentacleId,
+      );
+      if (defaultTentaclePrompt) {
+        createTerminalInput.initialInputDraft = defaultTentaclePrompt;
+      }
+    }
+
+    const snapshot = runtime.createTerminal(createTerminalInput);
+    const payload: Record<string, unknown> = { ...snapshot };
+    if (createTerminalInput.initialPrompt) {
+      payload.initialPrompt = createTerminalInput.initialPrompt;
+    }
+    writeJson(response, 201, payload, corsOrigin);
+    return true;
+  } catch (error) {
+    if (error instanceof RuntimeInputError) {
+      writeJson(response, 400, { error: error.message }, corsOrigin);
+      return true;
+    }
+
+    throw error;
+  }
+};
+
+const TERMINAL_ITEM_PATH_PATTERN = /^\/api\/terminals\/([^/]+)$/;
+
+export const handleTerminalItemRoute: ApiRouteHandler = async (
+  { request, response, requestUrl, corsOrigin },
+  { runtime },
+) => {
+  const renameMatch = requestUrl.pathname.match(TERMINAL_ITEM_PATH_PATTERN);
+  if (!renameMatch) {
+    return false;
+  }
+
+  if (request.method !== "PATCH" && request.method !== "DELETE") {
+    writeMethodNotAllowed(response, corsOrigin);
+    return true;
+  }
+
+  const terminalId = decodeURIComponent(renameMatch[1] ?? "");
+  if (request.method === "DELETE") {
+    try {
+      runtime.deleteTerminal(terminalId);
+      writeNoContent(response, 204, corsOrigin);
+      return true;
+    } catch (error) {
+      if (error instanceof RuntimeInputError) {
+        writeJson(response, 409, { error: error.message }, corsOrigin);
+        return true;
+      }
+      throw error;
+    }
+  }
+
+  const bodyReadResult = await readJsonBodyOrWriteError(request, response, corsOrigin);
+  if (!bodyReadResult.ok) {
+    return true;
+  }
+
+  const nameResult = parseTerminalName(bodyReadResult.payload);
+  if (nameResult.error) {
+    writeJson(response, 400, { error: nameResult.error }, corsOrigin);
+    return true;
+  }
+
+  if (!nameResult.provided || !nameResult.name) {
+    writeJson(response, 400, { error: "Terminal name is required." }, corsOrigin);
+    return true;
+  }
+
+  const payload = runtime.renameTerminal(terminalId, nameResult.name);
+  if (!payload) {
+    writeJson(response, 404, { error: "Terminal not found." }, corsOrigin);
+    return true;
+  }
+
+  writeJson(response, 200, payload, corsOrigin);
+  return true;
+};

package/apps/octogent/apps/api/src/createApiServer/types.ts

@@ -0,0 +1,24 @@
+import type { UsageChartResponse } from "../claudeSessionScanner";
+import type { ClaudeUsageSnapshot } from "../claudeUsage";
+import type { CodexUsageSnapshot } from "../codexUsage";
+import type { GitHubRepoSummarySnapshot } from "../githubRepoSummary";
+import type { MonitorService } from "../monitor";
+import type { GitClient } from "../terminalRuntime";
+
+export type CreateApiServerOptions = {
+  workspaceCwd?: string | undefined;
+  projectStateDir?: string | undefined;
+  promptsDir?: string | undefined;
+  webDistDir?: string | undefined;
+  apiBaseUrl?: string | undefined;
+  gitClient?: GitClient;
+  readClaudeUsageSnapshot?: () => Promise<ClaudeUsageSnapshot>;
+  readClaudeOauthUsageSnapshot?: () => Promise<ClaudeUsageSnapshot>;
+  readClaudeCliUsageSnapshot?: () => Promise<ClaudeUsageSnapshot>;
+  readCodexUsageSnapshot?: () => Promise<CodexUsageSnapshot>;
+  readGithubRepoSummary?: () => Promise<GitHubRepoSummarySnapshot>;
+  scanUsageHeatmap?: (scope: "all" | "project") => Promise<UsageChartResponse>;
+  monitorService?: MonitorService;
+  invalidateClaudeUsageCache?: () => void;
+  allowRemoteAccess?: boolean;
+};