better-codex 0.1.4 → 0.2.0

package/apps/backend/README.md

@@ -3,16 +3,31 @@
 Local backend that supervises multiple `codex app-server` processes and exposes a
 WebSocket bridge for the web UI.
 
+## Requirements
+
+- Bun
+- Codex CLI available in `PATH` (or configure `CODEX_BIN`)
+
 ## Setup
 
 1. Install dependencies
    ```bash
    bun install
    ```
-2. Run the server
+2. Run the server (hot reload)
    ```bash
    bun run dev
    ```
+3. Or run a single instance
+   ```bash
+   bun run start
+   ```
+
+## Data locations
+
+- Analytics, reviews, and thread index live in `CODEX_HUB_DATA_DIR` (defaults to `~/.codex-hub`).
+- Profiles metadata stored at `CODEX_HUB_DATA_DIR/profiles.json`.
+- Per-profile Codex homes are created under `CODEX_HUB_PROFILES_DIR` (defaults to `~/.codex/profiles`).
 
 ## Protocol types
 
@@ -30,17 +45,43 @@ bun run generate:protocol
 - `CODEX_HUB_DATA_DIR` (default: `~/.codex-hub`)
 - `CODEX_HUB_PROFILES_DIR` (default: `~/.codex/profiles`)
 - `CODEX_HUB_DEFAULT_CODEX_HOME` (default: `~/.codex`)
+- `CODEX_HUB_DEFAULT_CWD` (default: workspace root or process `cwd`)
+- `CODEX_DEFAULT_CWD` (fallback for default cwd)
 - `CODEX_BIN` (default: `codex`)
 - `CODEX_FLAGS` (space-delimited)
 - `CODEX_FLAGS_JSON` (JSON array, preferred)
 - `CODEX_APP_SERVER_FLAGS`
 - `CODEX_APP_SERVER_FLAGS_JSON`
+- `CODEX_HUB_APP_SERVER_STARTUP_TIMEOUT_MS` (default: `15000`)
+- `CODEX_HUB_DEBUG_ROUTES=1` (log non-404 route errors)
+
+Notes:
+- Prefer `CODEX_FLAGS_JSON` and `CODEX_APP_SERVER_FLAGS_JSON` to avoid shell quoting issues.
+- `CODEX_HUB_TOKEN` should be set if you want a stable token across restarts.
 
 ## Endpoints
 
 - `GET /health`
+- `GET /config` (returns `{ token }` for the web UI)
+- `GET /analytics/daily?metric=turns_started&days=365&profileId=...&model=...`
+- `GET /reviews?profileId=...&limit=100&offset=0`
 - `GET /profiles`
-- `POST /profiles`
+- `POST /profiles` (optional `{ name }`)
 - `POST /profiles/:profileId/start`
 - `POST /profiles/:profileId/stop`
+- `DELETE /profiles/:profileId`
+- `GET /profiles/:profileId/prompts` (returns prompt names + optional descriptions)
+- `GET /profiles/:profileId/prompts/:name` (returns file contents)
+- `GET /profiles/:profileId/config` (returns config + parsed MCP servers)
+- `PUT /profiles/:profileId/config` (body `{ content: string }`)
+- `PUT /profiles/:profileId/mcp-servers` (body `{ servers: McpServerConfig[] }`)
+- `GET /threads/search?q=...&profileId=...&model=...&status=active|archived&createdAfter=...&createdBefore=...&limit=...&offset=...`
+- `GET /threads/active?profileId=...`
+- `POST /threads/reindex` (body `{ profileId?, limit?, autoStart? }`)
 - `WS /ws?token=...`
+
+## Troubleshooting
+
+- "Missing hub token" in the web UI: ensure the backend is running and `GET /config` is reachable.
+- "app-server startup timed out": raise `CODEX_HUB_APP_SERVER_STARTUP_TIMEOUT_MS` or run the CLI once manually to warm caches.
+- Profiles not starting: verify the Codex CLI is in `PATH` or set `CODEX_BIN`.

package/apps/backend/src/core/app-server.ts

@@ -31,12 +31,18 @@ export class CodexAppServer extends EventEmitter {
   private connection?: JsonRpcConnection
   private ready: Promise<void>
   private resolveReady?: () => void
+  private readonly startupTimeoutMs: number
+  private readonly startupStderr: string[] = []
+  private readonly maxStartupStderr = 20
+  private startupComplete = false
 
   constructor(private readonly options: CodexAppServerOptions) {
     super()
     this.ready = new Promise((resolve) => {
       this.resolveReady = resolve
     })
+    const parsed = Number(process.env.CODEX_HUB_APP_SERVER_STARTUP_TIMEOUT_MS ?? 15000)
+    this.startupTimeoutMs = Number.isFinite(parsed) ? Math.max(parsed, 0) : 15000
   }
 
   async start(): Promise<void> {
@@ -73,6 +79,12 @@ export class CodexAppServer extends EventEmitter {
       this.emit('serverRequest', message)
     })
     this.connection.on('stderr', (message) => {
+      if (!this.startupComplete) {
+        this.startupStderr.push(message)
+        if (this.startupStderr.length > this.maxStartupStderr) {
+          this.startupStderr.shift()
+        }
+      }
       this.emit('stderr', message)
     })
     this.connection.on('error', (error) => {
@@ -82,8 +94,17 @@ export class CodexAppServer extends EventEmitter {
       this.emit('exit', code)
     })
 
-    await this.initialize()
-    this.resolveReady?.()
+    try {
+      await this.initializeWithTimeout()
+      this.startupComplete = true
+      this.resolveReady?.()
+    } catch (error) {
+      this.process?.kill()
+      this.process = undefined
+      this.connection = undefined
+      this.emit('error', error instanceof Error ? error : new Error(String(error)))
+      throw error
+    }
   }
 
   async request(method: string, params?: unknown): Promise<unknown> {
@@ -126,6 +147,51 @@ export class CodexAppServer extends EventEmitter {
     })
     this.connection.sendNotification('initialized', {})
   }
+
+  private async initializeWithTimeout(): Promise<void> {
+    if (this.startupTimeoutMs <= 0) {
+      await this.initialize()
+      return
+    }
+    if (!this.process) {
+      throw new Error('missing app-server process')
+    }
+    let timeoutId: NodeJS.Timeout | null = null
+    const cleanup: Array<() => void> = []
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      timeoutId = setTimeout(() => {
+        reject(new Error(`app-server startup timed out after ${this.startupTimeoutMs}ms`))
+      }, this.startupTimeoutMs)
+    })
+    const exitPromise = new Promise<never>((_, reject) => {
+      const onExit = (code: number | null) => {
+        reject(new Error(`app-server exited before initialize${code !== null ? ` (code ${code})` : ''}`))
+      }
+      this.process?.once('exit', onExit)
+      cleanup.push(() => this.process?.removeListener('exit', onExit))
+    })
+    const errorPromise = new Promise<never>((_, reject) => {
+      const onError = (error: Error) => reject(error)
+      this.process?.once('error', onError)
+      cleanup.push(() => this.process?.removeListener('error', onError))
+    })
+    try {
+      await Promise.race([this.initialize(), timeoutPromise, exitPromise, errorPromise])
+    } catch (error) {
+      if (error instanceof Error && error.message.includes('startup timed out')) {
+        const stderr = this.startupStderr.join('\n')
+        if (stderr) {
+          throw new Error(`${error.message}\n\n${stderr}`)
+        }
+      }
+      throw error
+    } finally {
+      if (timeoutId) {
+        clearTimeout(timeoutId)
+      }
+      cleanup.forEach((fn) => fn())
+    }
+  }
 }
 
 export type CodexAppServerEventsMap = CodexAppServerEvents

package/apps/backend/src/server.ts

@@ -5,10 +5,12 @@ import { join, extname, basename } from 'node:path'
 import { loadConfig } from './config'
 import { CodexSupervisor } from './services/supervisor'
 import { ProfileStore } from './services/profile-store'
+import { readProfileConfig, updateProfileMcpServers, writeProfileConfig, type McpServerConfig } from './services/codex-config'
 import { AnalyticsStore } from './analytics/store'
 import { AnalyticsService } from './analytics/service'
 import { ThreadIndexStore } from './thread-index/store'
 import { ThreadIndexService, type ThreadListItem } from './thread-index/service'
+import { ThreadActivityService } from './thread-activity/service'
 import { ReviewService } from './reviews/service'
 import { ReviewStore } from './reviews/store'
 import type { WsEvent, WsRequest, WsResponse } from './ws/messages'
@@ -24,6 +26,7 @@ const analytics = new AnalyticsService(new AnalyticsStore(join(config.dataDir, '
 analytics.init()
 const threadIndex = new ThreadIndexService(new ThreadIndexStore(join(config.dataDir, 'threads.sqlite')))
 threadIndex.init()
+const threadActivity = new ThreadActivityService()
 const reviews = new ReviewService(new ReviewStore(join(config.dataDir, 'reviews.sqlite')))
 reviews.init()
 
@@ -36,8 +39,25 @@ const sendWsEvent = (event: WsEvent) => {
   clients.forEach((client) => client.send(payload))
 }
 
+const shouldLogRouteErrors =
+  process.env.CODEX_HUB_DEBUG_ROUTES === '1' || process.env.NODE_ENV !== 'production'
+
+const formatError = (error: unknown) => {
+  if (error instanceof Error) {
+    return error.stack ?? `${error.name}: ${error.message}`
+  }
+  return String(error)
+}
+
 const app = new Elysia()
   .use(cors({ origin: true }))
+  .onError(({ code, error, request }) => {
+    if (!shouldLogRouteErrors || code === 'NOT_FOUND') {
+      return
+    }
+    console.error(`[HubBackend] ${request.method} ${request.url} -> ${code}`)
+    console.error(formatError(error))
+  })
   .get('/health', () => ({ ok: true }))
   .get('/config', () => ({ token: config.authToken }))
   .get(
@@ -215,6 +235,94 @@ const app = new Elysia()
       }),
     }
   )
+  .get(
+    '/profiles/:profileId/config',
+    async ({ params }) => {
+      const profile = profileStore.get(params.profileId)
+      if (!profile) {
+        return new Response('Profile not found', { status: 404 })
+      }
+      const snapshot = await readProfileConfig(profile.codexHome)
+      return {
+        path: snapshot.path,
+        codexHome: profile.codexHome,
+        content: snapshot.content,
+        mcpServers: snapshot.mcpServers,
+      }
+    },
+    {
+      params: t.Object({
+        profileId: t.String(),
+      }),
+    }
+  )
+  .put(
+    '/profiles/:profileId/config',
+    async ({ params, body }) => {
+      const profile = profileStore.get(params.profileId)
+      if (!profile) {
+        return new Response('Profile not found', { status: 404 })
+      }
+      if (!body || typeof body !== 'object' || typeof (body as { content?: string }).content !== 'string') {
+        return new Response('Invalid config payload', { status: 400 })
+      }
+      const snapshot = await writeProfileConfig(profile.codexHome, (body as { content: string }).content)
+      return {
+        ok: true,
+        path: snapshot.path,
+        codexHome: profile.codexHome,
+        content: snapshot.content,
+        mcpServers: snapshot.mcpServers,
+      }
+    },
+    {
+      params: t.Object({
+        profileId: t.String(),
+      }),
+      body: t.Object({
+        content: t.String(),
+      }),
+    }
+  )
+  .put(
+    '/profiles/:profileId/mcp-servers',
+    async ({ params, body }) => {
+      const profile = profileStore.get(params.profileId)
+      if (!profile) {
+        return new Response('Profile not found', { status: 404 })
+      }
+      if (!body || typeof body !== 'object' || !Array.isArray((body as { servers?: McpServerConfig[] }).servers)) {
+        return new Response('Invalid MCP server payload', { status: 400 })
+      }
+      const servers = (body as { servers: McpServerConfig[] }).servers
+      const seenNames = new Set<string>()
+      for (const server of servers) {
+        if (!server?.name || !/^[a-zA-Z0-9_-]+$/.test(server.name)) {
+          return new Response('Invalid MCP server name', { status: 400 })
+        }
+        if (seenNames.has(server.name)) {
+          return new Response('Duplicate MCP server name', { status: 400 })
+        }
+        seenNames.add(server.name)
+      }
+      const snapshot = await updateProfileMcpServers(profile.codexHome, servers)
+      return {
+        ok: true,
+        path: snapshot.path,
+        codexHome: profile.codexHome,
+        content: snapshot.content,
+        mcpServers: snapshot.mcpServers,
+      }
+    },
+    {
+      params: t.Object({
+        profileId: t.String(),
+      }),
+      body: t.Object({
+        servers: t.Array(t.Any()),
+      }),
+    }
+  )
   .get(
     '/threads/search',
     ({ query }) => {
@@ -251,6 +359,18 @@ const app = new Elysia()
       }),
     }
   )
+  .get(
+    '/threads/active',
+    ({ query }) => {
+      const profileId = typeof query.profileId === 'string' ? query.profileId : undefined
+      return { threads: threadActivity.list(profileId) }
+    },
+    {
+      query: t.Object({
+        profileId: t.Optional(t.String()),
+      }),
+    }
+  )
   .post(
     '/threads/reindex',
     async ({ body }) => {
@@ -351,6 +471,7 @@ const app = new Elysia()
 
       if (payload.type === 'profile.stop') {
         await supervisor.stop(payload.profileId)
+        threadActivity.clearProfile(payload.profileId)
         const response: WsResponse = {
           type: 'profile.stopped',
           profileId: payload.profileId,
@@ -380,13 +501,30 @@ const app = new Elysia()
             threadIndex.recordThreadStart(payload.profileId, thread)
           }
           if (payload.method === 'thread/resume') {
-            const thread = (result as { thread?: ThreadListItem }).thread
+            const thread = (result as { thread?: ThreadListItem & { turns?: Array<{ id?: string; status?: string }> } }).thread
             threadIndex.recordThreadResume(payload.profileId, thread)
+            if (thread?.id) {
+              let activeTurnId: string | null = null
+              if (Array.isArray(thread.turns)) {
+                for (let index = thread.turns.length - 1; index >= 0; index -= 1) {
+                  if (thread.turns[index]?.status === 'inProgress') {
+                    activeTurnId = thread.turns[index]?.id ?? null
+                    break
+                  }
+                }
+              }
+              if (activeTurnId) {
+                threadActivity.markStarted(payload.profileId, thread.id, activeTurnId)
+              } else {
+                threadActivity.markCompleted(payload.profileId, thread.id)
+              }
+            }
           }
           if (payload.method === 'thread/archive') {
             const params = payload.params as { threadId?: string } | undefined
             if (params?.threadId) {
               threadIndex.recordThreadArchive(payload.profileId, params.threadId)
+              threadActivity.markCompleted(payload.profileId, params.threadId)
             }
           }
           analytics.trackRpcResponse({
@@ -424,6 +562,18 @@ const app = new Elysia()
   })
 
 supervisor.on('notification', (event) => {
+  if (event.method === 'turn/started' && event.params && typeof event.params === 'object') {
+    const { threadId, turn } = event.params as { threadId?: string; turn?: { id?: string } }
+    if (threadId) {
+      threadActivity.markStarted(event.profileId, threadId, turn?.id ?? null)
+    }
+  }
+  if (event.method === 'turn/completed' && event.params && typeof event.params === 'object') {
+    const { threadId } = event.params as { threadId?: string }
+    if (threadId) {
+      threadActivity.markCompleted(event.profileId, threadId)
+    }
+  }
   if (event.method === 'item/started' && event.params && typeof event.params === 'object') {
     const { threadId, turnId, item } = event.params as {
       threadId?: string
@@ -503,6 +653,7 @@ supervisor.on('diagnostic', (event) => {
 })
 
 supervisor.on('exit', (event) => {
+  threadActivity.clearProfile(event.profileId)
   const wsEvent: WsEvent = {
     type: 'profile.exit',
     profileId: event.profileId,
@@ -512,6 +663,10 @@ supervisor.on('exit', (event) => {
 })
 
 supervisor.on('error', (event) => {
+  if (shouldLogRouteErrors) {
+    console.error(`[HubBackend] profile ${event.profileId} error`)
+    console.error(formatError(event.error))
+  }
   const wsEvent: WsEvent = {
     type: 'profile.error',
     profileId: event.profileId,