@gokulvenkatareddy/cortex 0.1.7

package/apps/octogent/apps/api/src/setupState.ts

@@ -0,0 +1,80 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { WorkspaceSetupStepId } from "@octogent/core";
+
+const SETUP_STATE_RELATIVE_PATH = join("state", "setup.json");
+const VERIFIED_SETUP_STEP_IDS = ["check-claude", "check-git", "check-curl"] as const;
+
+type VerifiedSetupStepId = (typeof VERIFIED_SETUP_STEP_IDS)[number];
+
+export type SetupState = {
+  version: 1;
+  tentaclesInitializedAt?: string;
+  verifiedSteps?: Partial<Record<VerifiedSetupStepId, string>>;
+};
+
+const isVerifiedSetupStepId = (value: WorkspaceSetupStepId): value is VerifiedSetupStepId =>
+  VERIFIED_SETUP_STEP_IDS.includes(value as VerifiedSetupStepId);
+
+export const readSetupState = (stateDir: string): SetupState => {
+  const filePath = join(stateDir, SETUP_STATE_RELATIVE_PATH);
+  if (!existsSync(filePath)) {
+    return { version: 1 };
+  }
+
+  try {
+    const raw = JSON.parse(readFileSync(filePath, "utf-8")) as Partial<SetupState>;
+    const verifiedSteps: Partial<Record<VerifiedSetupStepId, string>> = {};
+    const rawVerifiedSteps = raw.verifiedSteps;
+    if (rawVerifiedSteps && typeof rawVerifiedSteps === "object") {
+      for (const stepId of VERIFIED_SETUP_STEP_IDS) {
+        const checkedAt = rawVerifiedSteps[stepId];
+        if (typeof checkedAt === "string") {
+          verifiedSteps[stepId] = checkedAt;
+        }
+      }
+    }
+
+    return {
+      version: 1,
+      ...(typeof raw.tentaclesInitializedAt === "string"
+        ? { tentaclesInitializedAt: raw.tentaclesInitializedAt }
+        : {}),
+      ...(Object.keys(verifiedSteps).length > 0 ? { verifiedSteps } : {}),
+    };
+  } catch {
+    return { version: 1 };
+  }
+};
+
+export const writeSetupState = (stateDir: string, state: SetupState) => {
+  mkdirSync(join(stateDir, "state"), { recursive: true });
+  writeFileSync(join(stateDir, SETUP_STATE_RELATIVE_PATH), `${JSON.stringify(state, null, 2)}\n`);
+};
+
+export const markSetupStepVerified = (stateDir: string, stepId: WorkspaceSetupStepId) => {
+  if (!isVerifiedSetupStepId(stepId)) {
+    return;
+  }
+
+  const currentState = readSetupState(stateDir);
+  writeSetupState(stateDir, {
+    ...currentState,
+    verifiedSteps: {
+      ...currentState.verifiedSteps,
+      [stepId]: new Date().toISOString(),
+    },
+  });
+};
+
+export const markTentaclesInitialized = (stateDir: string) => {
+  const currentState = readSetupState(stateDir);
+  if (currentState.tentaclesInitializedAt) {
+    return;
+  }
+
+  writeSetupState(stateDir, {
+    ...currentState,
+    tentaclesInitializedAt: new Date().toISOString(),
+  });
+};

package/apps/octogent/apps/api/src/setupStatus.ts

@@ -0,0 +1,174 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+import type { WorkspaceSetupSnapshot, WorkspaceSetupStep } from "@octogent/core";
+
+import { readDeckTentacles } from "./deck/readDeckTentacles";
+import {
+  deriveProjectIdFromWorkspace,
+  ensureOctogentGitignoreEntry,
+  ensureProjectScaffold,
+  hasOctogentGitignoreEntry,
+  loadProjectConfig,
+  migrateStateToGlobal,
+  registerProject,
+} from "./projectPersistence";
+import { readSetupState } from "./setupState";
+import { collectStartupPrerequisiteReport } from "./startupPrerequisites";
+
+export const initializeWorkspaceFiles = (workspaceCwd: string, projectStateDir: string) => {
+  const projectName = loadProjectConfig(workspaceCwd)?.displayName;
+  const projectConfig = ensureProjectScaffold(
+    workspaceCwd,
+    projectName,
+    deriveProjectIdFromWorkspace(workspaceCwd),
+  );
+  registerProject(workspaceCwd, projectConfig.displayName);
+  mkdirSync(join(projectStateDir, "state"), { recursive: true });
+  migrateStateToGlobal(workspaceCwd, projectStateDir);
+
+  return { projectConfig, projectStateDir };
+};
+
+export const ensureWorkspaceGitignore = (workspaceCwd: string) =>
+  ensureOctogentGitignoreEntry(workspaceCwd);
+
+export const readWorkspaceSetupSnapshot = (
+  workspaceCwd: string,
+  projectStateDir: string,
+): WorkspaceSetupSnapshot => {
+  const prerequisites = collectStartupPrerequisiteReport();
+  const projectConfig = loadProjectConfig(workspaceCwd);
+  const octogentDir = join(workspaceCwd, ".octogent");
+  const hasProjectScaffold =
+    projectConfig !== null &&
+    existsSync(join(octogentDir, "tentacles")) &&
+    existsSync(join(octogentDir, "worktrees")) &&
+    existsSync(join(projectStateDir, "state"));
+  const hasGitignore = hasOctogentGitignoreEntry(workspaceCwd);
+  const tentacles = readDeckTentacles(workspaceCwd, projectStateDir);
+  const tentacleCount = tentacles.length;
+  const hasAnyTentacles = tentacleCount > 0;
+  const setupState = readSetupState(projectStateDir);
+  const isFirstRun = !hasAnyTentacles && !setupState.tentaclesInitializedAt;
+  const verifiedSteps = setupState.verifiedSteps ?? {};
+  const isClaudeVerified = Boolean(verifiedSteps["check-claude"]);
+  const isGitVerified = Boolean(verifiedSteps["check-git"]);
+  const isCurlVerified = Boolean(verifiedSteps["check-curl"]);
+  const hasClaudeCode = prerequisites.availability.claude;
+  const hasGit = prerequisites.availability.git;
+  const hasCurl = prerequisites.availability.curl;
+
+  const steps: WorkspaceSetupStep[] = [
+    {
+      id: "initialize-workspace",
+      title: "Initialize workspace",
+      description: "Create Octogent project files and runtime directories.",
+      complete: hasProjectScaffold,
+      required: true,
+      actionLabel: "Initialize workspace",
+      statusText: hasProjectScaffold
+        ? "Workspace files are ready."
+        : "Create .octogent project files before continuing.",
+      guidance: hasProjectScaffold
+        ? null
+        : "Workspace initialization failed. Run the Octogent initializer in this repository.",
+      command: hasProjectScaffold ? null : "octogent init",
+    },
+    {
+      id: "ensure-gitignore",
+      title: "Ignore .octogent",
+      description: "Add .octogent to .gitignore, or create .gitignore when it is missing.",
+      complete: hasGitignore,
+      required: true,
+      actionLabel: "Update .gitignore",
+      statusText: hasGitignore
+        ? ".gitignore covers .octogent."
+        : "Add .octogent to .gitignore before creating tentacles.",
+      guidance: hasGitignore
+        ? null
+        : "Git ignore entry is missing. Create or update .gitignore with the Octogent workspace path.",
+      command: hasGitignore ? null : "printf '.octogent\\n' >> .gitignore",
+    },
+    {
+      id: "check-claude",
+      title: "Check Claude Code",
+      description: "Verify the default Claude Code workflow is available on this machine.",
+      complete: hasClaudeCode && isClaudeVerified,
+      required: false,
+      actionLabel: "Check Claude Code",
+      statusText: hasClaudeCode
+        ? isClaudeVerified
+          ? "Claude Code is available."
+          : "Confirm Claude Code before using the planner."
+        : "Claude Code is unavailable.",
+      guidance: hasClaudeCode
+        ? isClaudeVerified
+          ? null
+          : "Click to verify the Claude Code workflow on this machine."
+        : "Install Claude Code and log in before using the default Claude workflow.",
+      command: hasClaudeCode ? null : "claude login",
+    },
+    {
+      id: "check-git",
+      title: "Check Git",
+      description: "Verify Git is available for worktree-backed tentacles.",
+      complete: hasGit && isGitVerified,
+      required: false,
+      actionLabel: "Check Git",
+      statusText: hasGit
+        ? isGitVerified
+          ? "Git is available."
+          : "Confirm Git before launching worktree-backed tentacles."
+        : "Git is unavailable.",
+      guidance: hasGit
+        ? isGitVerified
+          ? null
+          : "Click to verify Git support for worktree terminal flows."
+        : "Install Git to enable worktree terminals and branch flows.",
+      command: hasGit ? null : "git --version",
+    },
+    {
+      id: "check-curl",
+      title: "Check curl",
+      description: "Verify curl is available for Claude hook callbacks.",
+      complete: hasCurl && isCurlVerified,
+      required: false,
+      actionLabel: "Check curl",
+      statusText: hasCurl
+        ? isCurlVerified
+          ? "curl is available."
+          : "Confirm curl before using Claude hook callbacks."
+        : "curl is unavailable.",
+      guidance: hasCurl
+        ? isCurlVerified
+          ? null
+          : "Click to verify hook callback support on this machine."
+        : "Install curl to restore Claude hook callbacks.",
+      command: hasCurl ? null : "curl --version",
+    },
+    {
+      id: "create-tentacles",
+      title: "Create tentacles",
+      description: "Create at least one tentacle before launching a coding agent.",
+      complete: hasAnyTentacles,
+      required: true,
+      actionLabel: null,
+      statusText: hasAnyTentacles
+        ? `${tentacleCount} tentacle${tentacleCount === 1 ? "" : "s"} ready.`
+        : "Create your first tentacle to continue.",
+      guidance: hasAnyTentacles
+        ? null
+        : "Use the planner or manual creation to add at least one tentacle.",
+      command: null,
+    },
+  ];
+
+  return {
+    isFirstRun,
+    shouldShowSetupCard: isFirstRun || (!hasAnyTentacles && (!hasProjectScaffold || !hasGitignore)),
+    hasAnyTentacles,
+    tentacleCount,
+    steps,
+  };
+};

package/apps/octogent/apps/api/src/startupPrerequisites.ts

@@ -0,0 +1,146 @@
+import { execFileSync } from "node:child_process";
+
+export type StartupPrerequisiteSeverity = "error" | "warning";
+
+export type StartupPrerequisiteIssue = {
+  command: string;
+  severity: StartupPrerequisiteSeverity;
+  summary: string;
+  guidance: string;
+};
+
+export type StartupPrerequisiteAvailability = Record<
+  "claude" | "codex" | "git" | "gh" | "curl",
+  boolean
+>;
+
+export type StartupPrerequisiteReport = {
+  availability: StartupPrerequisiteAvailability;
+  errors: StartupPrerequisiteIssue[];
+  warnings: StartupPrerequisiteIssue[];
+};
+
+type CommandAvailabilityChecker = (command: string) => boolean;
+
+type CommandAvailabilityOptions = {
+  platform?: NodeJS.Platform;
+  execFileSyncImpl?: typeof execFileSync;
+};
+
+const resolveLookupCommand = (platform: NodeJS.Platform) =>
+  platform === "win32"
+    ? { file: "where", args: [] as string[] }
+    : { file: "which", args: [] as string[] };
+
+export const isCommandAvailable = (
+  command: string,
+  options: CommandAvailabilityOptions = {},
+): boolean => {
+  const lookup = resolveLookupCommand(options.platform ?? process.platform);
+
+  try {
+    (options.execFileSyncImpl ?? execFileSync)(lookup.file, [...lookup.args, command], {
+      stdio: "ignore",
+    });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export const collectStartupPrerequisiteReport = (
+  isAvailable: CommandAvailabilityChecker = (command) => isCommandAvailable(command),
+): StartupPrerequisiteReport => {
+  const availability: StartupPrerequisiteAvailability = {
+    claude: isAvailable("claude"),
+    codex: isAvailable("codex"),
+    git: isAvailable("git"),
+    gh: isAvailable("gh"),
+    curl: isAvailable("curl"),
+  };
+
+  const errors: StartupPrerequisiteIssue[] = [];
+  const warnings: StartupPrerequisiteIssue[] = [];
+
+  if (!availability.claude && !availability.codex) {
+    errors.push({
+      command: "claude/codex",
+      severity: "error",
+      summary: "Neither `claude` nor `codex` is installed.",
+      guidance:
+        "Install at least one agent CLI before starting Octogent. Claude-backed terminals use `claude`; Codex-backed terminals use `codex`.",
+    });
+  } else {
+    if (!availability.claude) {
+      warnings.push({
+        command: "claude",
+        severity: "warning",
+        summary: "`claude` is not installed.",
+        guidance:
+          "Claude-backed terminals are unavailable. Install Claude Code and run `claude login` if you want the default Claude provider.",
+      });
+    }
+
+    if (!availability.codex) {
+      warnings.push({
+        command: "codex",
+        severity: "warning",
+        summary: "`codex` is not installed.",
+        guidance:
+          "Codex-backed terminals and Codex usage telemetry are unavailable. Install Codex CLI and run `codex login` if you want Codex terminals.",
+      });
+    }
+  }
+
+  if (!availability.git) {
+    warnings.push({
+      command: "git",
+      severity: "warning",
+      summary: "`git` is not installed.",
+      guidance:
+        "Worktree terminals and git lifecycle actions are unavailable. Install Git to enable branch/worktree flows.",
+    });
+  }
+
+  if (!availability.gh) {
+    warnings.push({
+      command: "gh",
+      severity: "warning",
+      summary: "`gh` is not installed.",
+      guidance:
+        "GitHub pull request features are unavailable. Install GitHub CLI and run `gh auth login` to enable PR actions.",
+    });
+  }
+
+  if (!availability.curl) {
+    warnings.push({
+      command: "curl",
+      severity: "warning",
+      summary: "`curl` is not installed.",
+      guidance:
+        "Claude hook command callbacks for SessionStart, UserPromptSubmit, and Stop are unavailable. Install curl to restore full Claude hook delivery.",
+    });
+  }
+
+  return { availability, errors, warnings };
+};
+
+export const formatStartupPrerequisiteReport = (report: StartupPrerequisiteReport): string[] => {
+  if (report.errors.length === 0 && report.warnings.length === 0) {
+    return [];
+  }
+
+  const lines = ["Octogent startup preflight:"];
+
+  for (const issue of report.errors) {
+    lines.push(`  Error: ${issue.summary}`);
+    lines.push(`    ${issue.guidance}`);
+  }
+
+  for (const issue of report.warnings) {
+    lines.push(`  Warning: ${issue.summary}`);
+    lines.push(`    ${issue.guidance}`);
+  }
+
+  return lines;
+};

package/apps/octogent/apps/api/src/terminalRuntime/channelMessaging.ts

@@ -0,0 +1,87 @@
+import { logVerbose } from "../logging";
+import type { ChannelMessage, PersistedTerminal, TerminalSession } from "./types";
+
+export const createChannelMessaging = (deps: {
+  terminals: Map<string, PersistedTerminal>;
+  sessions: Map<string, TerminalSession>;
+  writeInput: (terminalId: string, data: string) => boolean;
+}) => {
+  const { terminals, sessions, writeInput } = deps;
+  const channelQueues = new Map<string, ChannelMessage[]>();
+  let channelMessageCounter = 0;
+
+  const deliverChannelMessages = (terminalId: string): void => {
+    const queue = channelQueues.get(terminalId);
+    if (!queue || queue.length === 0) {
+      return;
+    }
+
+    const session = sessions.get(terminalId);
+    if (!session) {
+      return;
+    }
+
+    const undelivered = queue.filter((m) => !m.delivered);
+    if (undelivered.length === 0) {
+      return;
+    }
+
+    // Compose all pending messages into a single prompt injection.
+    const lines = undelivered.map(
+      (m) => `[Channel message from ${m.fromTerminalId}]: ${m.content}`,
+    );
+    const prompt = `${lines.join("\n")}\r`;
+
+    logVerbose(`[Channel] Delivering ${undelivered.length} message(s) to ${terminalId}`);
+
+    for (const m of undelivered) {
+      m.delivered = true;
+    }
+
+    writeInput(terminalId, prompt);
+  };
+
+  return {
+    sendChannelMessage(
+      toTerminalId: string,
+      fromTerminalId: string,
+      content: string,
+    ): ChannelMessage | null {
+      if (!terminals.has(toTerminalId)) {
+        return null;
+      }
+
+      channelMessageCounter += 1;
+      const message: ChannelMessage = {
+        messageId: `msg-${channelMessageCounter}`,
+        fromTerminalId,
+        toTerminalId,
+        content,
+        timestamp: new Date().toISOString(),
+        delivered: false,
+      };
+
+      const queue = channelQueues.get(toTerminalId) ?? [];
+      queue.push(message);
+      channelQueues.set(toTerminalId, queue);
+
+      logVerbose(
+        `[Channel] Queued message ${message.messageId} from=${fromTerminalId} to=${toTerminalId}`,
+      );
+
+      // If the target session is idle, deliver immediately.
+      const targetSession = sessions.get(toTerminalId);
+      if (targetSession && targetSession.agentState === "idle") {
+        deliverChannelMessages(toTerminalId);
+      }
+
+      return message;
+    },
+
+    listChannelMessages(terminalId: string): ChannelMessage[] {
+      return channelQueues.get(terminalId) ?? [];
+    },
+
+    deliverChannelMessages,
+  };
+};