octocode-cli 1.2.6 → 1.2.7

package/skills/octocode-research/.octocode/plans/NODE_SERVER_START_PLAN.md

@@ -0,0 +1,755 @@
+# Implementation Plan: Replace Bash Scripts with Node.js Server Start
+
+> **Goal**: Replace `install.sh` (441 lines) and `start.sh` (9 lines) with an enhanced Node.js `scripts/server.ts`
+
+---
+
+## Executive Summary
+
+| Aspect | Current (Bash) | Target (Node.js) |
+|--------|----------------|------------------|
+| Entry point | `./install.sh start` | `npm run server:start` |
+| Lines of code | 450 (bash) | ~180 (TypeScript) |
+| Cross-platform | ❌ Unix only | ✅ Windows/Mac/Linux |
+| Dependencies | bash, curl, lsof | Node.js only |
+| Token resolution | Manual gh CLI | ✅ `resolveTokenFull` from octocode-shared |
+| Session management | Manual file ops | ✅ `getOrCreateSession` from octocode-shared |
+
+---
+
+## Key Design Decision: Reuse octocode-shared
+
+Instead of re-implementing token and session logic, we leverage existing utilities:
+
+```
+octocode-shared (add as direct dependency)
+├── resolveTokenFull()     → Complete token resolution (env → storage → gh CLI)
+├── getOrCreateSession()   → Session management with deferred writes
+└── getSessionId()         → Get current session ID
+```
+
+This ensures consistency with octocode-mcp and octocode-cli.
+
+---
+
+## Phase 0: Package.json Update (REQUIRED)
+
+### Add octocode-shared as Direct Dependency
+
+```diff
+"dependencies": {
+  "express": "^4.21.2",
+  "js-yaml": "^4.1.1",
+  "octocode-mcp": "file:../../packages/octocode-mcp",
++ "octocode-shared": "file:../../packages/octocode-shared",
+  "zod": "^3.24.1"
+},
+```
+
+**Why**: `getOrCreateSession` and `getSessionId` are exported from `octocode-shared/session`, not from `octocode-mcp`.
+
+---
+
+## Phase 1: Analyze Current install.sh Functions
+
+### Features to Migrate
+
+| Function | Lines | Priority | Migration Strategy |
+|----------|-------|----------|-------------------|
+| `check_requirements()` | 98-110 | HIGH | Simple Node.js version check |
+| `is_our_server_running()` | 113-118 | HIGH | `fetch('/health')` |
+| `is_port_occupied()` | 135-147 | HIGH | `net.createServer()` check |
+| `stop_server()` | 149-172 | HIGH | `process.kill()` + force option |
+| `install_dependencies()` | 179-218 | HIGH | `execSync('npm/yarn install')` |
+| `start_server()` | 220-303 | HIGH | `spawn('node', ['dist/server.js'])` |
+| `get_or_create_session_id()` | 39-78 | LOW | ✅ Use `getOrCreateSession()` |
+| `log_skill_install()` | 81-93 | LOW | Simple fetch POST |
+| `is_monorepo()` | 174-177 | MEDIUM | Check for `../../package.json` |
+
+### Features Already Available (No Implementation Needed)
+
+| Feature | Source | Notes |
+|---------|--------|-------|
+| Token resolution | `resolveTokenFull` | Handles env + storage + gh CLI |
+| Session management | `getOrCreateSession` | Handles file + deferred writes |
+| Colors | `src/utils/colors.ts` | Already exists in project |
+
+---
+
+## Phase 2: Enhanced scripts/server.ts
+
+### New File Structure
+
+```typescript
+#!/usr/bin/env npx tsx
+/**
+ * Cross-platform server management for octocode-research
+ * Usage: npx tsx scripts/server.ts [start|stop|restart|status|health|logs|build]
+ */
+
+import { spawn, execSync } from 'child_process';
+import { writeFileSync, readFileSync, unlinkSync, existsSync, openSync, closeSync, rmSync } from 'fs';
+import { createServer } from 'net';
+import { tmpdir, homedir } from 'os';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+// Token resolution from octocode-shared (via octocode-mcp re-export)
+import { resolveTokenFull, type FullTokenResolution, type GhCliTokenGetter } from 'octocode-mcp';
+
+// Session management from octocode-shared (direct import)
+import { getOrCreateSession, getSessionId, type PersistedSession } from 'octocode-shared';
+
+// === CONSTANTS ===
+const PORT = 1987;
+const PID_FILE = join(tmpdir(), 'octocode-research.pid');
+const LOG_FILE = join(tmpdir(), 'octocode-research.log');
+const OCTOCODE_LOGS_DIR = join(homedir(), '.octocode', 'logs');
+const LOG_ENDPOINT = 'https://octocode-mcp-host.onrender.com/log';
+const SKILL_NAME = 'octocode-research';
+const SKILL_VERSION = '2.0.0';
+
+// === COLORS (inline for standalone script) ===
+const colors = {
+  green: (s: string) => `\x1b[32m${s}\x1b[0m`,
+  red: (s: string) => `\x1b[31m${s}\x1b[0m`,
+  yellow: (s: string) => `\x1b[33m${s}\x1b[0m`,
+  cyan: (s: string) => `\x1b[36m${s}\x1b[0m`,
+  dim: (s: string) => `\x1b[2m${s}\x1b[0m`,
+};
+
+// === UTILITY FUNCTIONS ===
+
+/** Get project root (where package.json lives) */
+function getProjectRoot(): string {
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  return join(__dirname, '..');
+}
+
+/** Check Node.js version >= 20 */
+function checkNodeVersion(): void {
+  const version = process.versions.node.split('.')[0];
+  if (parseInt(version, 10) < 20) {
+    console.error(colors.red(`❌ Node.js 20+ required (found: v${process.versions.node})`));
+    process.exit(1);
+  }
+}
+
+/** Check if dist/ exists and is built */
+function needsBuild(): boolean {
+  const distServer = join(getProjectRoot(), 'dist', 'server.js');
+  return !existsSync(distServer);
+}
+
+/** Check if we're in the octocode-mcp monorepo */
+function isMonorepo(): boolean {
+  const root = getProjectRoot();
+  const parentPkg = join(root, '..', '..', 'package.json');
+  if (!existsSync(parentPkg)) return false;
+  try {
+    const content = readFileSync(parentPkg, 'utf8');
+    return content.includes('"octocode-mcp"');
+  } catch {
+    return false;
+  }
+}
+
+/** Install dependencies if node_modules missing */
+function installDependencies(): void {
+  const root = getProjectRoot();
+  const nodeModules = join(root, 'node_modules');
+
+  if (existsSync(nodeModules)) {
+    return; // Already installed
+  }
+
+  console.log(colors.cyan('[INFO] Installing dependencies...'));
+
+  if (isMonorepo()) {
+    const workspaceRoot = join(root, '..', '..');
+    execSync('yarn install', { cwd: workspaceRoot, stdio: 'inherit' });
+  } else {
+    execSync('npm install --omit=dev', { cwd: root, stdio: 'inherit' });
+  }
+}
+
+/** Build project if dist/ is missing */
+function buildProject(): void {
+  if (!needsBuild()) {
+    return; // Already built
+  }
+
+  console.log(colors.cyan('[INFO] Building project...'));
+  const root = getProjectRoot();
+
+  if (isMonorepo()) {
+    execSync('yarn run build', { cwd: root, stdio: 'inherit' });
+  } else {
+    execSync('npm run build', { cwd: root, stdio: 'inherit' });
+  }
+}
+
+/** Check if server is running via health endpoint */
+async function isServerRunning(): Promise<boolean> {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 2000);
+    const res = await fetch(`http://localhost:${PORT}/health`, { signal: controller.signal });
+    clearTimeout(timeout);
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+/** Check if port is in use by ANY process (not just our server) */
+async function isPortInUse(): Promise<boolean> {
+  return new Promise((resolve) => {
+    const server = createServer()
+      .once('error', () => resolve(true))
+      .once('listening', () => {
+        server.close();
+        resolve(false);
+      })
+      .listen(PORT);
+  });
+}
+
+/** Get PID from file */
+function getPid(): number | null {
+  if (existsSync(PID_FILE)) {
+    try {
+      const pid = parseInt(readFileSync(PID_FILE, 'utf8').trim(), 10);
+      return isNaN(pid) ? null : pid;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+/** Check if a process with given PID exists */
+function isProcessRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0); // Signal 0 = check existence
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** gh CLI token getter for resolveTokenFull */
+const getGhCliToken: GhCliTokenGetter = () => {
+  try {
+    return execSync('gh auth token', { encoding: 'utf8', timeout: 5000 }).trim();
+  } catch {
+    return null;
+  }
+};
+
+/** Resolve and set GitHub/GitLab tokens in environment */
+async function resolveAndSetTokens(): Promise<void> {
+  try {
+    // GitHub token resolution (env → storage → gh CLI)
+    const result = await resolveTokenFull({ getGhCliToken });
+    if (result?.token) {
+      process.env.GITHUB_TOKEN = result.token;
+      console.log(colors.cyan(`[INFO] GitHub token resolved from: ${result.source}`));
+    }
+  } catch {
+    // Token resolution is optional - server can still start
+  }
+
+  // GitLab tokens (pass through from environment)
+  // These are already in process.env if set, no resolution needed
+  if (process.env.GITLAB_TOKEN) {
+    console.log(colors.cyan('[INFO] GitLab token found in environment'));
+  } else if (process.env.GL_TOKEN) {
+    console.log(colors.cyan('[INFO] GL_TOKEN found in environment'));
+  }
+}
+
+/** Clean up old log files */
+function cleanupLogs(): void {
+  // Clear main log file
+  writeFileSync(LOG_FILE, '');
+
+  // Clean octocode logs directory
+  if (existsSync(OCTOCODE_LOGS_DIR)) {
+    try {
+      const files = require('fs').readdirSync(OCTOCODE_LOGS_DIR);
+      for (const file of files) {
+        if (file.endsWith('.log')) {
+          rmSync(join(OCTOCODE_LOGS_DIR, file), { force: true });
+        }
+      }
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+}
+
+/** Send skill install log (async, non-blocking) */
+function logSkillInstall(sessionId: string): void {
+  const payload = {
+    sessionId,
+    intent: 'skill_install',
+    data: { skill_name: SKILL_NAME, skill_version: SKILL_VERSION },
+    timestamp: new Date().toISOString(),
+    version: SKILL_VERSION,
+  };
+
+  // Fire and forget - don't await
+  fetch(LOG_ENDPOINT, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+    signal: AbortSignal.timeout(5000),
+  }).catch(() => {}); // Ignore errors
+}
+
+/** Kill process on port (cross-platform) */
+function killProcessOnPort(): boolean {
+  try {
+    if (process.platform === 'win32') {
+      // Windows: use netstat + taskkill
+      const output = execSync(`netstat -ano | findstr :${PORT}`, { encoding: 'utf8' });
+      const match = output.match(/LISTENING\s+(\d+)/);
+      if (match) {
+        execSync(`taskkill /PID ${match[1]} /F`, { stdio: 'ignore' });
+        return true;
+      }
+    } else {
+      // Unix: use lsof
+      const pid = execSync(`lsof -ti :${PORT}`, { encoding: 'utf8' }).trim();
+      if (pid) {
+        process.kill(parseInt(pid, 10), 'SIGKILL');
+        return true;
+      }
+    }
+  } catch {
+    // No process on port
+  }
+  return false;
+}
+
+// === COMMANDS ===
+
+async function start(): Promise<void> {
+  // Step 1: Check Node version
+  checkNodeVersion();
+
+  // Step 2: Check if already running
+  if (await isServerRunning()) {
+    console.log(colors.green(`✅ Server already running on port ${PORT}`));
+    const sessionId = await getSessionId();
+    if (sessionId) logSkillInstall(sessionId);
+    return;
+  }
+
+  // Step 3: Check if port is occupied by another process
+  if (await isPortInUse()) {
+    console.error(colors.red(`❌ Port ${PORT} is already in use by another process!`));
+    console.error(colors.yellow(`   Check with: lsof -i :${PORT}`));
+    console.error(colors.cyan(`   Or use: npm run server stop --force`));
+    process.exit(1);
+  }
+
+  // Step 4: Install dependencies if needed
+  installDependencies();
+
+  // Step 5: Build if needed
+  buildProject();
+
+  // Step 6: Resolve tokens
+  await resolveAndSetTokens();
+
+  // Step 7: Clean up old logs
+  cleanupLogs();
+
+  // Step 8: Start server
+  console.log(colors.cyan(`[SERVER] Starting Octocode Research Server on port ${PORT}...`));
+
+  const root = getProjectRoot();
+  const logFd = openSync(LOG_FILE, 'a');
+  const isWindows = process.platform === 'win32';
+
+  const child = spawn('node', ['dist/server.js'], {
+    cwd: root,
+    detached: !isWindows,
+    windowsHide: true,
+    stdio: ['ignore', logFd, logFd],
+    env: process.env,
+  });
+
+  // Close log file descriptor after spawn
+  closeSync(logFd);
+
+  child.unref();
+  writeFileSync(PID_FILE, String(child.pid));
+
+  // Step 9: Wait for health check
+  for (let i = 0; i < 15; i++) {
+    await new Promise((r) => setTimeout(r, 500));
+    if (await isServerRunning()) {
+      console.log(colors.green(`✅ Server started successfully! (PID: ${child.pid})`));
+      console.log(colors.cyan(`[SERVER] Health check: http://localhost:${PORT}/health`));
+      console.log(colors.green(`\n[INFO] API ready at http://localhost:${PORT}`));
+
+      // Log analytics (non-blocking)
+      const session = await getOrCreateSession();
+      logSkillInstall(session.sessionId);
+      return;
+    }
+  }
+
+  // Failed to start
+  console.error(colors.red('❌ Server failed to start. Check logs:'));
+  console.error(colors.yellow(`   ${LOG_FILE}`));
+  process.exit(1);
+}
+
+function stop(force = false): void {
+  const pid = getPid();
+
+  // If force flag, kill whatever is on the port
+  if (force) {
+    if (killProcessOnPort()) {
+      console.log(colors.green(`✅ Killed process on port ${PORT}`));
+    } else {
+      console.log(colors.yellow(`⚠️ No process found on port ${PORT}`));
+    }
+  } else if (pid && isProcessRunning(pid)) {
+    try {
+      process.kill(pid, 'SIGTERM');
+      console.log(colors.green(`✅ Stopped server (PID: ${pid})`));
+    } catch {
+      console.log(colors.yellow('⚠️ Process already stopped'));
+    }
+  } else {
+    console.log(colors.yellow('⚠️ Server not running'));
+  }
+
+  // Clean up PID file
+  if (existsSync(PID_FILE)) {
+    try {
+      unlinkSync(PID_FILE);
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+}
+
+async function restart(): Promise<void> {
+  stop();
+  await new Promise((r) => setTimeout(r, 1000));
+  await start();
+}
+
+async function status(): Promise<void> {
+  const running = await isServerRunning();
+  const pid = getPid();
+
+  if (running) {
+    console.log(colors.green(`✅ Server running on port ${PORT}${pid ? ` (PID: ${pid})` : ''}`));
+    return;
+  }
+
+  // Server not responding - check why
+  const portInUse = await isPortInUse();
+
+  if (portInUse) {
+    console.log(colors.yellow(`⚠️ Port ${PORT} is in use, but NOT by our server!`));
+    console.log(colors.cyan(`   Check with: lsof -i :${PORT}`));
+    console.log(colors.cyan(`   Force stop: npm run server stop --force`));
+  } else if (pid && isProcessRunning(pid)) {
+    console.log(colors.yellow(`⚠️ PID ${pid} exists but server not responding`));
+    console.log(colors.cyan('   Try: npm run server restart'));
+  } else {
+    console.log(colors.red('❌ Server not running'));
+    console.log(colors.cyan('   Start with: npm run server:start'));
+  }
+}
+
+async function health(): Promise<void> {
+  try {
+    const res = await fetch(`http://localhost:${PORT}/health`);
+    const data = await res.json();
+    console.log(JSON.stringify(data, null, 2));
+  } catch {
+    console.error(colors.red('❌ Server not responding'));
+    process.exit(1);
+  }
+}
+
+function logs(follow = false): void {
+  if (!existsSync(LOG_FILE)) {
+    console.log(colors.yellow(`⚠️ No logs found at ${LOG_FILE}`));
+    return;
+  }
+
+  if (follow) {
+    // Live tail using spawn
+    const tail = spawn('tail', ['-f', LOG_FILE], { stdio: 'inherit' });
+    process.on('SIGINT', () => {
+      tail.kill();
+      process.exit(0);
+    });
+  } else {
+    const content = readFileSync(LOG_FILE, 'utf8');
+    console.log(content || colors.yellow('(empty log file)'));
+  }
+}
+
+function build(): void {
+  checkNodeVersion();
+  installDependencies();
+  buildProject();
+  console.log(colors.green('✅ Build complete'));
+}
+
+function showUsage(): void {
+  console.log(`
+🔍 Octocode Research Server - HTTP API on port ${PORT}
+
+Usage: npm run server [command] [options]
+
+Commands:
+  start       Start server (install & build if needed) [default]
+  stop        Stop running server
+  stop --force  Kill any process on port ${PORT}
+  restart     Restart server
+  status      Check server status
+  health      Health check (JSON output)
+  logs        Show server logs
+  logs -f     Follow logs (live tail)
+  build       Build without starting
+
+Quick Start:
+  npm run server:start      # Start server
+  npm run server:stop       # Stop server
+  npm run server status     # Check status
+  curl http://localhost:${PORT}/health
+
+API Endpoints:
+  GET /health               Health check
+  GET /local/*              Local filesystem tools
+  GET /lsp/*                LSP semantic tools
+  GET /github/*             GitHub API tools
+  GET /package/*            Package search
+  GET /tools/list           List available tools
+  GET /prompts/list         List available prompts
+`);
+}
+
+// === MAIN ===
+
+const commands: Record<string, () => Promise<void> | void> = {
+  start,
+  stop: () => stop(process.argv.includes('--force')),
+  restart,
+  status,
+  health,
+  logs: () => logs(process.argv.includes('-f') || process.argv.includes('--follow')),
+  build,
+  '--help': showUsage,
+  '-h': showUsage,
+  help: showUsage,
+};
+
+const cmd = process.argv[2] || 'start';
+const handler = commands[cmd];
+
+if (!handler) {
+  console.error(colors.red(`Unknown command: ${cmd}`));
+  showUsage();
+  process.exit(1);
+}
+
+Promise.resolve(handler()).catch((err) => {
+  console.error(colors.red(`Error: ${err.message}`));
+  process.exit(1);
+});
+```
+
+---
+
+## Phase 3: Update SKILL.md
+
+### Changes Required
+
+```diff
+### Phase 1: Initialization & Context (Startup)
+
+1. **Start Server** (Idempotent):
+-  ```bash
+-  ./install.sh start
+-  ```
++  ```bash
++  npm run server:start
++  ```
+   *Action*: Tell user "Starting the research server..."
+   
+-  **Fallback**: If `./install.sh` fails (e.g., bash errors, missing `lsof`, Windows), use Node.js:
+-  ```bash
+-  npm run server:start
+-  ```
++  **Alternative**: For development with hot-reload:
++  ```bash
++  npm run dev
++  ```
+```
+
+---
+
+## Phase 4: File Cleanup
+
+### Files to Delete
+
+```bash
+rm skills/octocode-research/install.sh
+rm skills/octocode-research/start.sh
+```
+
+### package.json Updates
+
+```diff
+"dependencies": {
+  "express": "^4.21.2",
+  "js-yaml": "^4.1.1",
+  "octocode-mcp": "file:../../packages/octocode-mcp",
++ "octocode-shared": "file:../../packages/octocode-shared",
+  "zod": "^3.24.1"
+},
+```
+
+```diff
+"files": [
+  "dist",
+  "src",
+- "install.sh",
+- "start.sh",
+  "SKILL.md",
+  "LICENSE",
+  "tsconfig.json"
+],
+```
+
+---
+
+## Phase 5: Testing Checklist
+
+### Manual Tests
+
+| Test | Command | Expected |
+|------|---------|----------|
+| Fresh start | `npm run server:start` | Server starts, health OK |
+| Already running | `npm run server:start` | Shows "already running" |
+| Port conflict | (start nginx on 1987) | Shows "port in use" error |
+| Force stop | `npm run server stop --force` | Kills any process on port |
+| Stop | `npm run server:stop` | Server stops |
+| Restart | `npm run server restart` | Clean restart |
+| Status (running) | `npm run server status` | Shows ✅ running |
+| Status (stopped) | `npm run server status` | Shows ❌ not running |
+| Status (port conflict) | `npm run server status` | Shows ⚠️ port in use |
+| Health | `npm run server health` | JSON response |
+| Logs | `npm run server logs` | Shows log file |
+| Logs follow | `npm run server logs -f` | Live tail |
+| Build only | `npm run server build` | Builds without starting |
+
+### Token Resolution Tests
+
+| Scenario | Expected |
+|----------|----------|
+| `GITHUB_TOKEN` set | Uses env token |
+| `GH_TOKEN` set | Uses env token |
+| `OCTOCODE_TOKEN` set | Uses env token (highest priority) |
+| `gh auth` configured | Uses gh CLI token |
+| Octocode credentials stored | Uses stored token |
+| `GITLAB_TOKEN` set | Passed through to server |
+| `GL_TOKEN` set | Passed through to server |
+| No token available | Server starts (limited functionality) |
+
+### Cross-Platform Tests
+
+- [ ] macOS (ARM64)
+- [ ] macOS (x64)
+- [ ] Linux (Ubuntu)
+- [ ] Windows (WSL)
+- [ ] Windows (native)
+
+---
+
+## Implementation Order
+
+1. **Update package.json** - Add octocode-shared dependency
+2. **Create enhanced `scripts/server.ts`** (~180 lines)
+3. **Test new script** with all commands
+4. **Update SKILL.md** documentation
+5. **Update package.json** files array
+6. **Delete bash scripts**
+7. **Final testing**
+
+---
+
+## Rollback Plan
+
+If issues arise, the original bash scripts can be restored from git:
+
+```bash
+git checkout HEAD -- skills/octocode-research/install.sh
+git checkout HEAD -- skills/octocode-research/start.sh
+```
+
+---
+
+## Timeline Estimate
+
+| Phase | Effort |
+|-------|--------|
+| Phase 0: package.json dependency | 2 min |
+| Phase 2: Enhanced server.ts | 25 min |
+| Phase 3: Update SKILL.md | 5 min |
+| Phase 4: File cleanup | 2 min |
+| Phase 5: Testing | 20 min |
+| **Total** | **~55 min** |
+
+---
+
+## Comparison: Old Plan vs Final Plan
+
+| Aspect | Old Plan | Final Plan |
+|--------|----------|------------|
+| Lines of code | ~200 | ~180 |
+| Token resolution | Manual (60 lines) | `resolveTokenFull` (5 lines) |
+| Session management | Manual (30 lines) | `getOrCreateSession` (1 line) |
+| Import source | ❌ Incorrect (octocode-mcp) | ✅ Correct (octocode-shared) |
+| gh CLI fallback | ❌ Missing | ✅ Via `getGhCliToken` option |
+| GitLab tokens | ❌ Missing | ✅ Pass-through |
+| Port conflict check | ❌ Missing | ✅ `net.createServer()` |
+| Force stop option | ❌ Missing | ✅ `--force` flag |
+| Live log tailing | ❌ Missing | ✅ `-f` / `--follow` flag |
+| Log cleanup | ❌ Missing | ✅ Clears old logs |
+| Build command | ❌ Missing | ✅ Included |
+| Status with port check | ❌ Missing | ✅ Detects "port in use by other" |
+| API routes in help | ❌ Missing | ✅ Included |
+| Error handling | ❌ Missing | ✅ Top-level catch |
+
+---
+
+## Key Imports Summary
+
+```typescript
+// Token resolution - re-exported from octocode-mcp (originally from octocode-shared)
+import { resolveTokenFull, type FullTokenResolution, type GhCliTokenGetter } from 'octocode-mcp';
+
+// Session management - direct from octocode-shared (NOT exported from octocode-mcp)
+import { getOrCreateSession, getSessionId, type PersistedSession } from 'octocode-shared';
+```
+
+**⚠️ Important**: `getOrCreateSession` and `getSessionId` are NOT exported from `octocode-mcp`. They must be imported directly from `octocode-shared`, which requires adding it as a direct dependency.
+
+---
+
+*Plan finalized: All issues addressed*
+*Status: Ready for implementation*