@excitedjs/tm 1.1.0

package/src/engines/codex/ui-ipc.ts

@@ -0,0 +1,374 @@
+import { randomUUID } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { createConnection, type Socket } from 'node:net'
+import { join } from 'node:path'
+
+export const CODEX_UI_IPC_VERSION = 0
+const INITIALIZING_CLIENT_ID = 'initializing-client'
+// Matches the Codex UI IPC method-version table in OpenAI ChatGPT VS Code extension 26.519.x.
+const METHOD_VERSIONS = new Map<string, number>([
+  ['thread-stream-state-changed', 6],
+  ['thread-read-state-changed', 1],
+  ['thread-archived', 2],
+  ['thread-unarchived', 1],
+  ['thread-follower-start-turn', 1],
+  ['thread-follower-compact-thread', 1],
+  ['thread-follower-steer-turn', 1],
+  ['thread-follower-interrupt-turn', 1],
+  ['thread-follower-set-model-and-reasoning', 1],
+  ['thread-follower-set-collaboration-mode', 1],
+  ['thread-follower-edit-last-user-turn', 1],
+  ['thread-follower-command-approval-decision', 1],
+  ['thread-follower-file-approval-decision', 1],
+  ['thread-follower-permissions-request-approval-response', 1],
+  ['thread-follower-submit-user-input', 1],
+  ['thread-follower-submit-mcp-server-elicitation-response', 1],
+  ['thread-follower-set-queued-follow-ups-state', 1],
+  ['thread-queued-followups-changed', 1],
+])
+
+type PendingResponse = {
+  readonly method: string
+  readonly resolve: (value: unknown) => void
+  readonly reject: (error: Error) => void
+}
+
+interface IpcRequestEnvelope {
+  readonly type: 'request'
+  readonly requestId: string
+  readonly sourceClientId: string
+  readonly targetClientId?: string
+  readonly version: number
+  readonly method: string
+  readonly params?: unknown
+}
+
+interface IpcBroadcastEnvelope {
+  readonly type: 'broadcast'
+  readonly sourceClientId: string
+  readonly version: number
+  readonly method: string
+  readonly params?: unknown
+}
+
+interface IpcDiscoveryRequestEnvelope {
+  readonly type: 'client-discovery-request'
+  readonly requestId: string
+  readonly request?: Partial<IpcRequestEnvelope>
+}
+
+type IpcIncomingEnvelope =
+  | IpcRequestEnvelope
+  | IpcBroadcastEnvelope
+  | IpcDiscoveryRequestEnvelope
+  | {
+      readonly type: 'response'
+      readonly requestId: string
+      readonly resultType: 'success'
+      readonly handledByClientId?: string
+      readonly method?: string
+      readonly result?: unknown
+    }
+  | {
+      readonly type: 'response'
+      readonly requestId: string
+      readonly resultType: 'error'
+      readonly handledByClientId?: string
+      readonly method?: string
+      readonly error?: unknown
+    }
+
+export interface IpcRequestContext {
+  readonly requestId: string
+  readonly sourceClientId: string
+  readonly method: string
+  readonly params: unknown
+}
+
+export interface IpcBroadcastContext {
+  readonly sourceClientId: string
+  readonly method: string
+  readonly params: unknown
+}
+
+export type IpcRequestHandler = (ctx: IpcRequestContext) => Promise<unknown>
+export type IpcCanHandle = (ctx: Omit<IpcRequestContext, 'requestId'>) => Promise<boolean>
+export type IpcBroadcastHandler = (ctx: IpcBroadcastContext) => void
+
+export function codexUiIpcSocketPath(env: NodeJS.ProcessEnv = process.env): string {
+  const uid = typeof process.getuid === 'function' ? process.getuid() : 0
+  return join(env['TMPDIR'] ?? '/tmp', 'codex-ipc', `ipc-${uid}.sock`)
+}
+
+export function codexUiIpcSocketExists(env: NodeJS.ProcessEnv = process.env): boolean {
+  return existsSync(codexUiIpcSocketPath(env))
+}
+
+export class CodexUiIpcClient {
+  private socket: Socket | null = null
+  private buffer = Buffer.alloc(0)
+  private readonly pending = new Map<string, PendingResponse>()
+  private readonly broadcastHandlers: IpcBroadcastHandler[] = []
+  private closedPromise: Promise<void> | null = null
+  private closeResolve: (() => void) | null = null
+  private clientId: string | null = null
+
+  constructor(private readonly opts: {
+    readonly socketPath: string
+    readonly clientType: string
+    readonly canHandle: IpcCanHandle
+    readonly handleRequest: IpcRequestHandler
+  }) {}
+
+  get id(): string | null {
+    return this.clientId
+  }
+
+  async connect(): Promise<string> {
+    if (this.socket !== null) throw new Error('CodexUiIpcClient already connected')
+    this.closedPromise = new Promise<void>((resolve) => {
+      this.closeResolve = resolve
+    })
+    const socket = createConnection(this.opts.socketPath)
+    this.socket = socket
+    socket.on('data', (chunk) => this.onData(chunk))
+    socket.once('close', () => this.onClose(new Error('codex UI IPC socket closed')))
+    socket.once('error', (e) => this.onClose(e instanceof Error ? e : new Error(String(e))))
+    await new Promise<void>((resolve, reject) => {
+      socket.once('connect', resolve)
+      socket.once('error', (e) => reject(e instanceof Error ? e : new Error(String(e))))
+    })
+    const result = await this.request('initialize', { clientType: this.opts.clientType }, {
+      sourceClientId: INITIALIZING_CLIENT_ID,
+    })
+    const clientId = extractClientId(result)
+    if (clientId === null) throw new Error('codex UI IPC initialize response did not include clientId')
+    this.clientId = clientId
+    return clientId
+  }
+
+  onBroadcast(handler: IpcBroadcastHandler): void {
+    this.broadcastHandlers.push(handler)
+  }
+
+  async request(
+    method: string,
+    params: unknown,
+    options: { readonly targetClientId?: string; readonly sourceClientId?: string } = {},
+  ): Promise<unknown> {
+    const socket = this.socket
+    if (socket === null) throw new Error('codex UI IPC client is not connected')
+    const requestId = randomUUID()
+    const sourceClientId = options.sourceClientId ?? this.requireClientId()
+    const envelope: IpcRequestEnvelope = {
+      type: 'request',
+      requestId,
+      sourceClientId,
+      version: ipcMethodVersion(method),
+      method,
+      params,
+      ...(options.targetClientId === undefined ? {} : { targetClientId: options.targetClientId }),
+    }
+    return new Promise((resolve, reject) => {
+      this.pending.set(requestId, { method, resolve, reject })
+      try {
+        this.send(envelope)
+      } catch (e) {
+        this.pending.delete(requestId)
+        reject(e instanceof Error ? e : new Error(String(e)))
+      }
+    })
+  }
+
+  broadcast(method: string, params: unknown): void {
+    this.send({
+      type: 'broadcast',
+      sourceClientId: this.requireClientId(),
+      version: ipcMethodVersion(method),
+      method,
+      params,
+    })
+  }
+
+  close(): void {
+    if (this.socket === null) return
+    this.socket.destroy()
+    this.onClose(new Error('codex UI IPC client closed by caller'))
+  }
+
+  closed(): Promise<void> {
+    return this.closedPromise ?? Promise.resolve()
+  }
+
+  private requireClientId(): string {
+    if (this.clientId === null) throw new Error('codex UI IPC client is not initialized')
+    return this.clientId
+  }
+
+  private onData(chunk: Buffer): void {
+    this.buffer = Buffer.concat([this.buffer, chunk])
+    while (this.buffer.length >= 4) {
+      const payloadLength = this.buffer.readUInt32LE(0)
+      if (this.buffer.length < payloadLength + 4) return
+      const payload = this.buffer.subarray(4, payloadLength + 4)
+      this.buffer = this.buffer.subarray(payloadLength + 4)
+      this.onEnvelope(payload)
+    }
+  }
+
+  private onEnvelope(payload: Buffer): void {
+    let parsed: unknown
+    const text = payload.toString('utf8')
+    if (process.env['CLAUDEMUX_DEBUG_IPC'] !== undefined) {
+      console.error(`[codex-ui-ipc] inbound ${text}`)
+    }
+    try {
+      parsed = JSON.parse(text)
+    } catch {
+      return
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return
+    const env = parsed as Partial<IpcIncomingEnvelope>
+    switch (env.type) {
+      case 'response':
+        this.onResponse(env as IpcIncomingEnvelope)
+        break
+      case 'broadcast':
+        this.onBroadcastEnvelope(env as IpcBroadcastEnvelope)
+        break
+      case 'client-discovery-request':
+        this.onDiscoveryRequest(env as IpcDiscoveryRequestEnvelope).catch(() => {})
+        break
+      case 'request':
+        this.onRequestEnvelope(env as IpcRequestEnvelope).catch(() => {})
+        break
+    }
+  }
+
+  private onResponse(env: IpcIncomingEnvelope): void {
+    if (env.type !== 'response') return
+    const pending = this.pending.get(env.requestId)
+    if (pending === undefined) return
+    this.pending.delete(env.requestId)
+    if (env.resultType === 'success') {
+      pending.resolve(env.result)
+      return
+    }
+    pending.reject(new Error(errorMessage(env.error) ?? `codex UI IPC request ${pending.method} failed`))
+  }
+
+  private onBroadcastEnvelope(env: IpcBroadcastEnvelope): void {
+    for (const handler of this.broadcastHandlers) {
+      try {
+        handler({
+          sourceClientId: env.sourceClientId,
+          method: env.method,
+          params: env.params,
+        })
+      } catch {
+        // Broadcast handlers are observers; one bad observer must not close the IPC link.
+      }
+    }
+  }
+
+  private async onDiscoveryRequest(env: IpcDiscoveryRequestEnvelope): Promise<void> {
+    const request = env.request
+    if (request === undefined || typeof request.method !== 'string') {
+      this.send({
+        type: 'client-discovery-response',
+        requestId: env.requestId,
+        response: { canHandle: false },
+      })
+      return
+    }
+    // Codex.app wraps discovery around the original request; the method
+    // version lives on request.version, not on the discovery envelope.
+    if ((request.version ?? 0) !== ipcMethodVersion(request.method)) {
+      this.send({
+        type: 'client-discovery-response',
+        requestId: env.requestId,
+        response: { canHandle: false },
+      })
+      return
+    }
+    const canHandle = await this.opts.canHandle({
+      sourceClientId: typeof request.sourceClientId === 'string' ? request.sourceClientId : '',
+      method: request.method,
+      params: request.params,
+    })
+    this.send({
+      type: 'client-discovery-response',
+      requestId: env.requestId,
+      response: { canHandle },
+    })
+  }
+
+  private async onRequestEnvelope(env: IpcRequestEnvelope): Promise<void> {
+    try {
+      const result = await this.opts.handleRequest({
+        requestId: env.requestId,
+        sourceClientId: env.sourceClientId,
+        method: env.method,
+        params: env.params,
+      })
+      this.send({
+        type: 'response',
+        requestId: env.requestId,
+        sourceClientId: this.requireClientId(),
+        handledByClientId: this.requireClientId(),
+        version: ipcMethodVersion(env.method),
+        resultType: 'success',
+        method: env.method,
+        result,
+      })
+    } catch (e) {
+      this.send({
+        type: 'response',
+        requestId: env.requestId,
+        sourceClientId: this.requireClientId(),
+        handledByClientId: this.requireClientId(),
+        version: ipcMethodVersion(env.method),
+        resultType: 'error',
+        method: env.method,
+        error: e instanceof Error ? e.message : String(e),
+      })
+    }
+  }
+
+  private send(envelope: unknown): void {
+    const socket = this.socket
+    if (socket === null) throw new Error('codex UI IPC client is not connected')
+    const payload = Buffer.from(JSON.stringify(envelope), 'utf8')
+    const header = Buffer.alloc(4)
+    header.writeUInt32LE(payload.length, 0)
+    socket.write(Buffer.concat([header, payload]))
+  }
+
+  private onClose(reason: Error): void {
+    if (this.socket === null) return
+    this.socket = null
+    this.clientId = null
+    this.buffer = Buffer.alloc(0)
+    for (const pending of this.pending.values()) pending.reject(reason)
+    this.pending.clear()
+    this.closeResolve?.()
+    this.closeResolve = null
+  }
+}
+
+function extractClientId(result: unknown): string | null {
+  if (typeof result !== 'object' || result === null) return null
+  const clientId = (result as { clientId?: unknown }).clientId
+  return typeof clientId === 'string' && clientId.length > 0 ? clientId : null
+}
+
+export function ipcMethodVersion(method: string): number {
+  return METHOD_VERSIONS.get(method) ?? CODEX_UI_IPC_VERSION
+}
+
+function errorMessage(value: unknown): string | null {
+  if (typeof value === 'string') return value
+  if (typeof value !== 'object' || value === null) return null
+  const message = (value as { message?: unknown }).message
+  return typeof message === 'string' ? message : null
+}

package/src/engines/codex/verb-common.ts

@@ -0,0 +1,34 @@
+import type { Engine } from '../engine'
+import type { EngineContext } from '../types'
+import type { TmResult } from '../../tm'
+import { validateTeammateName } from '../../identity/name.js'
+import { CodexEngine } from './engine.js'
+
+/** Per-codex-verb `die` — mirrors the `tm: <msg>` wire shape native.ts uses. */
+export function die(message: string): TmResult {
+  return { code: 1, stdout: '', stderr: `tm: ${message}\n` }
+}
+
+export function engineContext(): EngineContext {
+  return { now: () => Date.now(), env: process.env }
+}
+
+export function resolveEngine(engine: Engine | undefined): Engine {
+  return engine ?? new CodexEngine()
+}
+
+export function timeoutMsFromSeconds(timeoutSec: number | null): number | null {
+  return timeoutSec === null ? null : timeoutSec * 1000
+}
+
+function codexNameValidationError(name: string): string | null {
+  const validation = validateTeammateName(name)
+  return validation.kind === 'ok'
+    ? null
+    : `invalid codex teammate name '${name}': ${validation.reason}`
+}
+
+export function validateCodexName(name: string): TmResult | null {
+  const message = codexNameValidationError(name)
+  return message === null ? null : die(message)
+}

package/src/engines/codex/verb-lifecycle.ts

@@ -0,0 +1,94 @@
+import type { Engine } from '../engine'
+import type { TmResult } from '../../tm'
+import { formatTurn } from '../../verbs/format'
+import { readDaemonState } from './supervisor.js'
+import { readBaseRecord } from './persistence.js'
+import {
+  die,
+  engineContext,
+  resolveEngine,
+  timeoutMsFromSeconds,
+  validateCodexName,
+} from './verb-common.js'
+
+export interface CodexSpawnOptions {
+  readonly cwd?: string
+  readonly prompt?: string | null
+  readonly timeoutSec?: number | null
+  readonly displayName?: string | null
+  readonly engine?: Engine
+}
+
+/**
+ * `tm spawn <name> --engine codex` — start a per-teammate codex daemon and
+ * optionally run the first prompt through the Engine contract.
+ */
+export async function codexSpawn(
+  name: string,
+  opts: CodexSpawnOptions = {},
+): Promise<TmResult> {
+  const invalidName = validateCodexName(name)
+  if (invalidName !== null) return invalidName
+  const engine = resolveEngine(opts.engine)
+  const cwd = opts.cwd ?? process.cwd()
+  const result = await engine.spawn(
+    {
+      name,
+      repo: cwd,
+      cwd,
+      worktreeSlug: null,
+      resumeCheckpoint: null,
+      prompt: opts.prompt ?? null,
+      timeoutMs: timeoutMsFromSeconds(opts.timeoutSec ?? null),
+      displayName: opts.displayName ?? null,
+    },
+    engineContext(),
+  )
+
+  switch (result.kind) {
+    case 'spawned': {
+      const state = readDaemonState(name)
+      let stderr =
+        state === null
+          ? `spawned: ${name}\n`
+          : `spawned: ${name} (pid=${state.pid}, socket=${state.socketPath})\n`
+      if (result.firstTurn === null) return { code: 0, stdout: '', stderr }
+      const turn = formatTurn(result.firstTurn)
+      return {
+        code: turn.code,
+        stdout: turn.stdout,
+        stderr: stderr + turn.stderr,
+      }
+    }
+    case 'already-exists':
+      return die(`codex teammate '${name}' already exists (engine=${result.existingEngine})`)
+    case 'failed':
+      return die(result.message)
+  }
+}
+
+/**
+ * `tm kill <codex-name>` — SIGTERM the daemon and remove its Engine base
+ * record. The historical CLI shape is idempotent on missing teammates.
+ */
+export async function codexKill(
+  name: string,
+  opts: { readonly engine?: Engine } = {},
+): Promise<TmResult> {
+  const state = readDaemonState(name)
+  const base = readBaseRecord(name)
+  const result = await resolveEngine(opts.engine).kill({ name }, engineContext())
+  if (result.kind === 'failed') return die(result.message)
+  if (result.kind === 'not-found' || (state === null && base === null)) {
+    return {
+      code: 0,
+      stdout: '',
+      stderr: `no codex teammate '${name}' to kill (already gone)\n`,
+    }
+  }
+  return {
+    code: 0,
+    stdout: '',
+    stderr: state === null ? `killed: ${name}\n` : `killed: ${name} (was pid=${state.pid})\n`,
+  }
+}

package/src/engines/codex/verb-state.ts

@@ -0,0 +1,19 @@
+import type { Engine } from '../engine'
+import { engineContext, resolveEngine } from './verb-common.js'
+
+/** Codex rows for `tm states`, using the legacy REPO/SID/BUSY/LAST/PREVIEW columns. */
+export async function codexStateRows(
+  _nowSec: number,
+  engine?: Engine,
+): Promise<readonly string[][]> {
+  const rows = await resolveEngine(engine).list(engineContext())
+  return rows.map((row) => {
+    return [
+      row.name,
+      row.extras['sidShort'] ?? '-',
+      row.extras['busy'] ?? '-',
+      row.extras['last'] ?? '-',
+      row.extras['preview'] ?? '-',
+    ]
+  })
+}

package/src/engines/codex/verb-turns.ts

@@ -0,0 +1,49 @@
+import type { Engine } from '../engine'
+import type { TmResult } from '../../tm'
+import { formatTurn } from '../../verbs/format'
+import {
+  engineContext,
+  resolveEngine,
+  timeoutMsFromSeconds,
+  validateCodexName,
+} from './verb-common.js'
+
+/** `tm send <codex-name> --prompt ...` — atomic turn by default. */
+export async function codexSend(
+  name: string,
+  prompt: string,
+  opts: { readonly timeoutSec?: number | null; readonly engine?: Engine } = {},
+): Promise<TmResult> {
+  const invalidName = validateCodexName(name)
+  if (invalidName !== null) return invalidName
+  const result = await resolveEngine(opts.engine).send(
+    {
+      name,
+      prompt,
+      timeoutMs: timeoutMsFromSeconds(opts.timeoutSec ?? null),
+      paneQuiet: false,
+    },
+    engineContext(),
+  )
+  return formatTurn(result)
+}
+
+/** `tm wait <codex-name>` — wait for the next turn/completed notification. */
+export async function codexWait(
+  name: string,
+  opts: { readonly timeoutSec?: number | null; readonly engine?: Engine } = {},
+): Promise<TmResult> {
+  const invalidName = validateCodexName(name)
+  if (invalidName !== null) return invalidName
+  const result = await resolveEngine(opts.engine).wait(
+    {
+      name,
+      recoverFor: null,
+      timeoutMs: timeoutMsFromSeconds(opts.timeoutSec ?? null),
+      fresh: false,
+      paneQuiet: false,
+    },
+    engineContext(),
+  )
+  return formatTurn(result)
+}

package/src/engines/codex/verbs.ts

@@ -0,0 +1,15 @@
+/**
+ * Thin CLI compatibility exports for Codex-specific callers and tests.
+ *
+ * The implementation is split by behavior boundary: daemon lifecycle,
+ * turn-driving wrappers, state rows, and the `tm ask` pool-borrow path.
+ * Engine-routed production verbs go through `verbs/<v>.ts` and
+ * `CodexEngine`; this module remains a small compatibility surface.
+ */
+
+export { codexAsk } from './ask.js'
+export { codexKill, codexSpawn, type CodexSpawnOptions } from './verb-lifecycle.js'
+export { codexSend, codexWait } from './verb-turns.js'
+export { codexStateRows } from './verb-state.js'
+export { subscribeTurnCollection } from './events.js'
+export type { TurnCompletedNotification } from './events.js'

package/src/engines/engine.ts

@@ -0,0 +1,91 @@
+/**
+ * The cross-engine TUI contract. Decision multi-engine-tui-architecture §"Engine interface" sets
+ * the shape: every engine implements every method (no `?` optionals),
+ * and an operation an engine genuinely cannot perform returns a
+ * discriminated result whose `kind` says so. The verb layer formats the
+ * result; the engine never decides exit codes.
+ *
+ * Why "implement everything, discriminate the result" instead of optional
+ * methods: a caller that has to write `if (engine.foo)` once will write
+ * it twice, then forget the third time. A returned-result is one path
+ * for "this engine cannot do this", not two; the type system enforces
+ * that every caller switches on `kind` and handles the missing-case
+ * arm. Phase 2's concrete engines (Claude, Codex) consume this file
+ * unchanged; future engines (gemini, cursor, …) implement the same
+ * surface.
+ */
+
+import type {
+  CompactRequest,
+  CompactResult,
+  ContextRequest,
+  ContextResult,
+  DoctorSection,
+  EngineCapabilities,
+  EngineContext,
+  EngineKind,
+  EngineSnapshot,
+  HistoryRequest,
+  HistoryResult,
+  InspectRequest,
+  KillRequest,
+  KillResult,
+  LastRequest,
+  MemoryRequest,
+  ReloadRequest,
+  ReloadResult,
+  ResumeRequest,
+  ResumeResult,
+  SendRequest,
+  SpawnRequest,
+  SpawnResult,
+  StatusRequest,
+  TeammateListing,
+  TeammateStatus,
+  TextResult,
+  TurnResult,
+  WaitRequest,
+} from './types'
+
+/**
+ * Every `tm` engine implements this interface. The fleet-facing methods
+ * (`list`, `status`, `kill`) make `tm ls` / `tm states` / `tm status` /
+ * `tm kill` reachable for a teammate that has no tmux session — that
+ * line is the load-bearing change in decision multi-engine-tui-architecture's amend.
+ */
+export interface Engine {
+  /** Which engine this is. Mirrors the JSON-recorded identity. */
+  readonly kind: EngineKind
+  /** Structured capability report — drives verb-side conditional behavior. */
+  readonly capabilities: EngineCapabilities
+
+  // Hot path
+  spawn(req: SpawnRequest, ctx: EngineContext): Promise<SpawnResult>
+  send(req: SendRequest, ctx: EngineContext): Promise<TurnResult>
+  wait(req: WaitRequest, ctx: EngineContext): Promise<TurnResult>
+  /**
+   * Tear down the runtime process / worktree state for `req.name`. The
+   * implementation must leave the live identity JSON
+   * (`/tmp/teammate-<name>.json`) alone — `killVerb` archives + removes
+   * it once the engine returns, so a `tm resume` / `tm history` after
+   * the kill can recover the teammate's launch context.
+   */
+  kill(req: KillRequest, ctx: EngineContext): Promise<KillResult>
+
+  // Fleet visibility — decision multi-engine-tui-architecture amend §"Fleet-visibility verbs"
+  list(ctx: EngineContext): Promise<readonly TeammateListing[]>
+  status(req: StatusRequest, ctx: EngineContext): Promise<TeammateStatus>
+
+  // Session-shape verbs
+  compact(req: CompactRequest, ctx: EngineContext): Promise<CompactResult>
+  resume(req: ResumeRequest, ctx: EngineContext): Promise<ResumeResult>
+  last(req: LastRequest, ctx: EngineContext): Promise<TextResult>
+  ctx(req: ContextRequest, ctx: EngineContext): Promise<ContextResult>
+  history(req: HistoryRequest, ctx: EngineContext): Promise<HistoryResult>
+  mem(req: MemoryRequest, ctx: EngineContext): Promise<TextResult>
+  reload(req: ReloadRequest, ctx: EngineContext): Promise<ReloadResult>
+
+  // Diagnostic
+  inspect(req: InspectRequest, ctx: EngineContext): Promise<EngineSnapshot>
+  doctor(ctx: EngineContext): Promise<DoctorSection>
+}