@astrale-os/cli 0.7.0-alpha.0 → 0.8.0-alpha.0

package/studio/server/agent/harness/codex/ask.ts

@@ -0,0 +1,181 @@
+import { spawn } from 'node:child_process'
+
+import type { AskInput, AskResult } from '../adapter'
+
+import { childEnvironment, terminateProcessTree } from '../process'
+
+const ASK_TIMEOUT_MS = 120_000
+
+function sandboxFor(access: AskInput['access']): 'workspace-write' | 'danger-full-access' {
+  return access === 'workspace' ? 'workspace-write' : 'danger-full-access'
+}
+
+/** Use Codex's rich-client protocol only for the capability missing from
+ * `codex exec`: fork a conversation without mutating its parent. */
+export function runCodexForkAsk(bin: string, input: AskInput): Promise<AskResult> {
+  return new Promise((resolve) => {
+    const child = spawn(bin, ['app-server', '--stdio'], {
+      cwd: input.root,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: childEnvironment(input.env),
+      detached: process.platform !== 'win32',
+    })
+    let finished = false
+    let threadId = ''
+    let turnId = ''
+    let text = ''
+    let finalText = ''
+    let stderr = ''
+    let nextId = 1
+    let timer: ReturnType<typeof setTimeout> | undefined
+
+    const send = (message: unknown) => child.stdin?.write(`${JSON.stringify(message)}\n`)
+    const request = (method: string, params: unknown, id = nextId++) => {
+      send({ method, id, params })
+      return id
+    }
+    const finish = (result: AskResult) => {
+      if (finished) return
+      finished = true
+      if (timer) clearTimeout(timer)
+      input.signal.removeEventListener('abort', onAbort)
+      try {
+        terminateProcessTree(child)
+      } catch {
+        /* already gone */
+      }
+      resolve(result)
+    }
+    const fail = (message: string) =>
+      finish({ text: finalText || text, isError: true, errorMessage: message })
+
+    const onAbort = () => {
+      if (threadId && turnId) request('turn/interrupt', { threadId, turnId }, 99)
+      finish({ text: finalText || text, isError: true, errorMessage: 'canceled' })
+    }
+    if (input.signal.aborted) return onAbort()
+    input.signal.addEventListener('abort', onAbort, { once: true })
+
+    timer = setTimeout(() => fail('Codex side question timed out'), ASK_TIMEOUT_MS)
+    const commonThread = {
+      cwd: input.root,
+      approvalPolicy: 'never',
+      sandbox: sandboxFor(input.access),
+      developerInstructions: input.appendSystemPrompt ?? null,
+      ephemeral: true,
+      model: input.model ?? null,
+      config: { 'mcp_servers.domain-studio.enabled': false },
+    }
+
+    child.stdout?.setEncoding('utf8')
+    let buffer = ''
+    child.stdout?.on('data', (chunk: string) => {
+      buffer += chunk
+      let newline: number
+      while ((newline = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, newline).trim()
+        buffer = buffer.slice(newline + 1)
+        if (!line) continue
+        let message: any
+        try {
+          message = JSON.parse(line)
+        } catch {
+          continue
+        }
+
+        if (message.id === 1) {
+          if (message.error) return fail(message.error.message ?? 'Codex app-server init failed')
+          send({ method: 'initialized', params: {} })
+          if (input.sessionId)
+            request('thread/fork', { threadId: input.sessionId, ...commonThread }, 2)
+          else request('thread/start', commonThread, 2)
+          continue
+        }
+        if (message.id === 2) {
+          if (message.error) return fail(message.error.message ?? 'Codex thread fork failed')
+          threadId = message.result?.thread?.id ?? ''
+          if (!threadId) return fail('Codex app-server returned no thread id')
+          request(
+            'turn/start',
+            {
+              threadId,
+              input: [{ type: 'text', text: input.prompt, text_elements: [] }],
+              model: input.model ?? null,
+              effort:
+                input.effort === 'max' || input.effort === 'ultracode'
+                  ? 'xhigh'
+                  : (input.effort ?? null),
+            },
+            3,
+          )
+          continue
+        }
+        if (message.id === 3) {
+          if (message.error)
+            return fail(message.error.message ?? 'Codex side question failed to start')
+          turnId = message.result?.turn?.id ?? turnId
+          continue
+        }
+        if (message.method === 'turn/started') {
+          turnId = message.params?.turn?.id ?? turnId
+          continue
+        }
+        if (message.method === 'item/agentMessage/delta') {
+          const delta = typeof message.params?.delta === 'string' ? message.params.delta : ''
+          if (delta) {
+            text += delta
+            input.onDelta(delta)
+          }
+          continue
+        }
+        if (message.method === 'item/completed') {
+          const item = message.params?.item
+          if (item?.type === 'agentMessage' && typeof item.text === 'string') {
+            finalText = item.text
+            if (!text && finalText) {
+              text = finalText
+              input.onDelta(finalText)
+            }
+          }
+          continue
+        }
+        if (message.method === 'error' && message.params?.willRetry !== true) {
+          return fail(message.params?.error?.message ?? 'Codex side question failed')
+        }
+        if (message.method === 'turn/completed') {
+          const turn = message.params?.turn
+          if (turn?.status !== 'completed')
+            return fail(
+              turn?.error?.message ??
+                `Codex side question ended with status ${turn?.status ?? 'unknown'}`,
+            )
+          finish({ text: finalText || text, isError: false })
+        }
+      }
+    })
+    child.stderr?.setEncoding('utf8')
+    child.stderr?.on('data', (chunk: string) => {
+      stderr += chunk
+    })
+    child.on('error', (error) => fail(`failed to spawn ${bin} app-server: ${error.message}`))
+    child.on('close', (code) => {
+      if (!finished)
+        fail(
+          `Codex app-server exited ${code ?? -1}${stderr ? `: ${stderr.trim().slice(-400)}` : ''}`,
+        )
+    })
+
+    request(
+      'initialize',
+      {
+        clientInfo: {
+          name: 'astrale_domain_studio',
+          title: 'Astrale Domain Studio',
+          version: '0.1.0',
+        },
+        capabilities: null,
+      },
+      1,
+    )
+  })
+}

package/studio/server/agent/harness/codex/command.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, test } from 'bun:test'
+
+import { buildCodexArgs } from './command'
+
+describe('Codex command construction', () => {
+  test('builds a new stable JSONL turn with developer instructions and approved MCP tools', () => {
+    const args = buildCodexArgs({
+      appendSystemPrompt: 'Studio protocol\nwith a newline',
+      model: 'gpt-studio',
+      effort: 'high',
+      access: 'workspace',
+      mcpServers: [
+        {
+          name: 'domain-studio',
+          command: '/opt/homebrew/bin/bun',
+          args: ['/studio/bridge/stdio.ts', '--config', '/domain/.domain-studio/bridge.json'],
+          required: true,
+          approvalMode: 'approve',
+          enabledTools: ['reply_to_thread'],
+        },
+      ],
+    })
+    expect(args).toEqual([
+      'exec',
+      '--json',
+      '--skip-git-repo-check',
+      '-c',
+      'approval_policy="never"',
+      '-c',
+      'sandbox_mode="workspace-write"',
+      '--model',
+      'gpt-studio',
+      '-c',
+      'model_reasoning_effort="high"',
+      '-c',
+      'developer_instructions="Studio protocol\\nwith a newline"',
+      '-c',
+      'mcp_servers.domain-studio.command="/opt/homebrew/bin/bun"',
+      '-c',
+      'mcp_servers.domain-studio.args=["/studio/bridge/stdio.ts","--config","/domain/.domain-studio/bridge.json"]',
+      '-c',
+      'mcp_servers.domain-studio.required=true',
+      '-c',
+      'mcp_servers.domain-studio.default_tools_approval_mode="approve"',
+      '-c',
+      'mcp_servers.domain-studio.enabled_tools=["reply_to_thread"]',
+      '-',
+    ])
+  })
+
+  test('resumes by thread id, maps Claude-only effort modes, and can be ephemeral', () => {
+    const args = buildCodexArgs(
+      {
+        sessionId: '019f-thread',
+        effort: 'max',
+        access: 'full',
+      },
+      true,
+    )
+    expect(args.slice(0, 3)).toEqual(['exec', 'resume', '019f-thread'])
+    expect(args.join(' ')).toContain('model_reasoning_effort="xhigh"')
+    expect(args.join(' ')).toContain('sandbox_mode="danger-full-access"')
+    expect(args).toContain('--ephemeral')
+
+    expect(buildCodexArgs({ effort: 'ultracode' }).join(' ')).toContain(
+      'model_reasoning_effort="xhigh"',
+    )
+  })
+})

package/studio/server/agent/harness/codex/command.ts

@@ -0,0 +1,43 @@
+import type { AgentAccess, AgentEffort } from '../../../../shared/types'
+import type { AgentTurnInput } from '../adapter'
+
+import { codexMcpConfigArgs, tomlString } from './mcp'
+
+const EXTRA_ARGS = (process.env.DOMAIN_STUDIO_CODEX_ARGS || '').split(' ').filter(Boolean)
+
+function sandbox(access?: AgentAccess): 'workspace-write' | 'danger-full-access' {
+  return access === 'workspace' ? 'workspace-write' : 'danger-full-access'
+}
+
+function normalizeEffort(effort?: AgentEffort): AgentEffort | undefined {
+  return effort === 'max' || effort === 'ultracode' ? 'xhigh' : effort
+}
+
+/** Build one `codex exec` invocation from the harness-neutral turn. */
+export function buildCodexArgs(
+  input: Pick<
+    AgentTurnInput,
+    'appendSystemPrompt' | 'sessionId' | 'model' | 'effort' | 'access' | 'mcpServers'
+  >,
+  ephemeral = false,
+): string[] {
+  const args = ['exec']
+  if (input.sessionId) args.push('resume', input.sessionId)
+  args.push(
+    '--json',
+    '--skip-git-repo-check',
+    '-c',
+    'approval_policy="never"',
+    '-c',
+    `sandbox_mode=${tomlString(sandbox(input.access))}`,
+  )
+  const effort = normalizeEffort(input.effort)
+  if (input.model) args.push('--model', input.model)
+  if (effort) args.push('-c', `model_reasoning_effort=${tomlString(effort)}`)
+  if (input.appendSystemPrompt)
+    args.push('-c', `developer_instructions=${tomlString(input.appendSystemPrompt)}`)
+  args.push(...codexMcpConfigArgs(input.mcpServers))
+  if (ephemeral) args.push('--ephemeral')
+  args.push(...EXTRA_ARGS, '-')
+  return args
+}

package/studio/server/agent/harness/codex/events.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from 'bun:test'
+
+import { handleCodexExecEvent, newCodexRunState } from './events'
+
+describe('Codex exec JSONL normalization', () => {
+  test('captures session, activity, final text, and non-duplicated token usage', () => {
+    const state = newCodexRunState()
+    const events: any[] = []
+    const onEvent = (event: any) => events.push(event)
+
+    handleCodexExecEvent({ type: 'thread.started', thread_id: '019f-test-thread' }, state, onEvent)
+    handleCodexExecEvent(
+      {
+        type: 'item.started',
+        item: { id: 'cmd-1', type: 'command_execution', command: 'pnpm typecheck' },
+      },
+      state,
+      onEvent,
+    )
+    handleCodexExecEvent(
+      {
+        type: 'item.completed',
+        item: { id: 'cmd-1', type: 'command_execution', command: 'pnpm typecheck' },
+      },
+      state,
+      onEvent,
+    )
+    handleCodexExecEvent(
+      {
+        type: 'item.completed',
+        item: { id: 'msg-1', type: 'agent_message', text: 'Done.' },
+      },
+      state,
+      onEvent,
+    )
+    handleCodexExecEvent(
+      {
+        type: 'turn.completed',
+        usage: {
+          input_tokens: 100,
+          cached_input_tokens: 70,
+          output_tokens: 20,
+          reasoning_output_tokens: 5,
+        },
+      },
+      state,
+      onEvent,
+    )
+
+    expect(state.sessionId).toBe('019f-test-thread')
+    expect(state.finalText).toBe('Done.')
+    expect(state.tokens).toBe(120)
+    expect(events).toEqual([
+      { kind: 'status', text: 'session started' },
+      {
+        kind: 'tool',
+        text: 'Shell',
+        tool: 'Shell',
+        target: 'pnpm typecheck',
+      },
+      { kind: 'message', text: 'Done.' },
+    ])
+  })
+
+  test('maps MCP calls and failures', () => {
+    const state = newCodexRunState('existing')
+    const events: any[] = []
+    handleCodexExecEvent(
+      {
+        type: 'item.started',
+        item: {
+          id: 'mcp-1',
+          type: 'mcp_tool_call',
+          server: 'domain-studio',
+          tool: 'reply_to_thread',
+        },
+      },
+      state,
+      (event) => events.push(event),
+    )
+    handleCodexExecEvent(
+      { type: 'turn.failed', error: { message: 'tool failed' } },
+      state,
+      (event) => events.push(event),
+    )
+
+    expect(events[0]).toMatchObject({
+      kind: 'tool',
+      tool: 'domain-studio:reply_to_thread',
+    })
+    expect(state.isError).toBe(true)
+    expect(state.errorMessage).toBe('tool failed')
+  })
+})

package/studio/server/agent/harness/codex/events.ts

@@ -0,0 +1,132 @@
+import type { AgentStreamEvent } from '../adapter'
+
+export interface CodexRunState {
+  sessionId?: string
+  finalText: string
+  tokens?: number
+  isError: boolean
+  errorMessage?: string
+  startedItems: Set<string>
+  terminal: boolean
+}
+
+export function newCodexRunState(sessionId?: string): CodexRunState {
+  return {
+    sessionId,
+    finalText: '',
+    isError: false,
+    startedItems: new Set(),
+    terminal: false,
+  }
+}
+
+function text(value: unknown): string {
+  return typeof value === 'string' ? value : ''
+}
+
+function fileChangeTarget(item: any): string {
+  const paths = Array.isArray(item?.changes)
+    ? item.changes
+        .map((change: any) => text(change?.path ?? change?.file ?? change?.file_path))
+        .filter(Boolean)
+    : []
+  return paths.slice(0, 3).join(', ')
+}
+
+function toolEvent(item: any): AgentStreamEvent | null {
+  switch (item?.type) {
+    case 'command_execution':
+      return {
+        kind: 'tool',
+        text: 'Shell',
+        tool: 'Shell',
+        target: text(item.command).slice(0, 200),
+      }
+    case 'file_change':
+      return {
+        kind: 'tool',
+        text: 'Edit',
+        tool: 'Edit',
+        target: fileChangeTarget(item),
+      }
+    case 'mcp_tool_call':
+      return {
+        kind: 'tool',
+        text: text(item.tool) || 'MCP',
+        tool: `${text(item.server)}:${text(item.tool)}`.replace(/^:/, ''),
+        target: text(item.tool),
+      }
+    case 'web_search':
+      return {
+        kind: 'tool',
+        text: 'Web search',
+        tool: 'WebSearch',
+        target: text(item.query),
+      }
+    case 'plan':
+      return { kind: 'status', text: text(item.text) || 'plan updated' }
+    default:
+      return null
+  }
+}
+
+/** Normalize one `codex exec --json` JSONL record into Studio's compact event
+ * contract while accumulating the final result and usage. */
+export function handleCodexExecEvent(
+  event: any,
+  state: CodexRunState,
+  onEvent: (event: AgentStreamEvent) => void,
+): void {
+  switch (event?.type) {
+    case 'thread.started':
+      if (typeof event.thread_id === 'string') state.sessionId = event.thread_id
+      onEvent({ kind: 'status', text: 'session started' })
+      return
+    case 'item.started': {
+      const normalized = toolEvent(event.item)
+      if (normalized) {
+        if (typeof event.item?.id === 'string') state.startedItems.add(event.item.id)
+        onEvent(normalized)
+      }
+      return
+    }
+    case 'item.completed': {
+      const item = event.item
+      if (item?.type === 'agent_message' && text(item.text).trim()) {
+        state.finalText = item.text
+        onEvent({ kind: 'message', text: item.text.trim() })
+      } else if (item?.type === 'reasoning') {
+        const reasoning =
+          text(item.text) ||
+          (Array.isArray(item.summary)
+            ? item.summary.filter((part: unknown) => typeof part === 'string').join('\n')
+            : '')
+        if (reasoning.trim()) onEvent({ kind: 'thinking', text: reasoning.trim() })
+      } else if (!state.startedItems.has(item?.id)) {
+        const normalized = toolEvent(item)
+        if (normalized) onEvent(normalized)
+      }
+      return
+    }
+    case 'turn.completed': {
+      state.terminal = true
+      const usage = event.usage
+      if (usage && typeof usage === 'object')
+        state.tokens = Number(usage.input_tokens ?? 0) + Number(usage.output_tokens ?? 0)
+      return
+    }
+    case 'turn.failed':
+      state.terminal = true
+      state.isError = true
+      state.errorMessage =
+        text(event.error?.message) ||
+        text(event.message) ||
+        text(event.error) ||
+        'Codex turn failed'
+      return
+    case 'error':
+      state.isError = true
+      state.errorMessage =
+        text(event.message) || text(event.error?.message) || text(event.error) || 'Codex error'
+  }
+}

package/studio/server/agent/harness/codex/exec.ts

@@ -0,0 +1,113 @@
+import { spawn } from 'node:child_process'
+
+import type { AgentTurnInput, AgentTurnResult } from '../adapter'
+
+import { childEnvironment, terminateProcessTree } from '../process'
+import { buildCodexArgs } from './command'
+import { handleCodexExecEvent, newCodexRunState, type CodexRunState } from './events'
+
+const RESUME_REJECTED =
+  /no rollout found for thread id|thread\/resume failed|thread (?:id )?.*(?:not found|does not exist|expired)|could not (?:find|load|resume) .*thread|unknown thread|invalid thread id/i
+
+/** Execute one Codex JSONL turn and normalize its result. */
+export function runCodexExec(
+  bin: string,
+  input: AgentTurnInput,
+  ephemeral = false,
+): Promise<AgentTurnResult> {
+  return new Promise((resolve) => {
+    const state = newCodexRunState(input.sessionId)
+    let stderr = ''
+    let settled = false
+    let forceKillTimer: ReturnType<typeof setTimeout> | undefined
+    let onAbort = () => {}
+    const finish = (result: AgentTurnResult) => {
+      if (settled) return
+      settled = true
+      if (forceKillTimer) clearTimeout(forceKillTimer)
+      input.signal.removeEventListener('abort', onAbort)
+      resolve(result)
+    }
+    const resultFromState = (current: CodexRunState, errorMessage?: string): AgentTurnResult => ({
+      sessionId: current.sessionId,
+      finalText: current.finalText,
+      tokens: current.tokens,
+      numTurns: 1,
+      isError: current.isError || !!errorMessage,
+      errorMessage: errorMessage ?? current.errorMessage,
+      resumeRejected:
+        !!input.sessionId &&
+        (current.isError || !!errorMessage) &&
+        RESUME_REJECTED.test(`${errorMessage ?? current.errorMessage ?? ''}\n${stderr}`),
+    })
+
+    let child: ReturnType<typeof spawn>
+    try {
+      child = spawn(bin, buildCodexArgs(input, ephemeral), {
+        cwd: input.root,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: childEnvironment(input.env),
+        detached: process.platform !== 'win32',
+      })
+    } catch (error) {
+      finish(resultFromState(state, `failed to spawn ${bin}: ${String(error)}`))
+      return
+    }
+    onAbort = () => {
+      terminateProcessTree(child)
+      forceKillTimer = setTimeout(() => terminateProcessTree(child, 'SIGKILL'), 2_000)
+      forceKillTimer.unref?.()
+    }
+    if (input.signal.aborted) onAbort()
+    else input.signal.addEventListener('abort', onAbort, { once: true })
+
+    child.stdin?.write(input.prompt)
+    child.stdin?.end()
+
+    let buffer = ''
+    const handleLine = (line: string) => {
+      let event: any
+      try {
+        event = JSON.parse(line)
+      } catch {
+        return
+      }
+      handleCodexExecEvent(event, state, input.onEvent)
+    }
+    child.stdout?.setEncoding('utf8')
+    child.stdout?.on('data', (chunk: string) => {
+      buffer += chunk
+      let newline: number
+      while ((newline = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, newline).trim()
+        buffer = buffer.slice(newline + 1)
+        if (line) handleLine(line)
+      }
+    })
+    child.stderr?.setEncoding('utf8')
+    child.stderr?.on('data', (chunk: string) => {
+      stderr += chunk
+    })
+    child.on('error', (error) =>
+      finish(resultFromState(state, `failed to spawn ${bin}: ${error.message}`)),
+    )
+    child.on('close', (code) => {
+      const trailing = buffer.trim()
+      if (trailing) handleLine(trailing)
+      if (input.signal.aborted)
+        return finish({
+          ...resultFromState(state, 'canceled'),
+          isError: true,
+          errorMessage: 'canceled',
+        })
+      const exitError =
+        code !== 0
+          ? state.errorMessage ||
+            `codex exited ${code ?? -1}${stderr ? `: ${stderr.trim().slice(-500)}` : ''}`
+          : !state.terminal && !state.isError
+            ? 'codex exited without a terminal turn event'
+            : undefined
+      finish(resultFromState(state, exitError))
+    })
+  })
+}

package/studio/server/agent/harness/codex/loadout.ts

@@ -0,0 +1,63 @@
+import type { HarnessLoadout } from '../../../../shared/types'
+import type { HarnessLoadoutOptions } from '../adapter'
+
+import { captureCommand } from '../process'
+import { probeCodexModels } from './models'
+import { scanCodexSkills, type CodexPlugin } from './skills'
+
+function parseJson<T>(text: string, fallback: T): T {
+  try {
+    return JSON.parse(text) as T
+  } catch {
+    return fallback
+  }
+}
+
+/** Inspect Codex configuration, plugins, skills, MCP servers, and models. */
+export async function loadCodexConfiguration(
+  bin: string,
+  root: string,
+  options?: HarnessLoadoutOptions,
+): Promise<HarnessLoadout> {
+  const [mcpResult, pluginResult, modelResult] = await Promise.all([
+    captureCommand(bin, ['mcp', 'list', '--json'], root),
+    captureCommand(bin, ['plugin', 'list', '--json'], root),
+    probeCodexModels(bin, root, options?.model, options?.env),
+  ])
+  const pluginWire = parseJson<any>(pluginResult.stdout, {})
+  const plugins: CodexPlugin[] = (Array.isArray(pluginWire?.installed) ? pluginWire.installed : [])
+    .map((plugin: any) => ({
+      name: String(plugin?.name ?? plugin?.pluginId?.split('@')[0] ?? ''),
+      path: String(plugin?.source?.path ?? ''),
+      enabled: plugin?.enabled === true,
+    }))
+    .filter((plugin: CodexPlugin) => !!plugin.name && !!plugin.path)
+  const mcpWire = parseJson<any[]>(mcpResult.stdout, [])
+  return {
+    ok: mcpResult.code === 0 && pluginResult.code === 0 && modelResult.ok,
+    detail:
+      mcpResult.code === 0 && pluginResult.code === 0 && modelResult.ok
+        ? `${modelResult.detail ?? 'Codex model resolved.'} Runtime tools are discovered when a turn starts.`
+        : (
+            mcpResult.stderr ||
+            pluginResult.stderr ||
+            modelResult.detail ||
+            'Codex loadout probe failed'
+          ).trim(),
+    model: modelResult.model,
+    nativeModel: modelResult.nativeModel,
+    modelSource: modelResult.modelSource,
+    models: modelResult.models,
+    cwd: root,
+    tools: [],
+    mcpServers: mcpWire.map((server) => ({
+      name: String(server?.name ?? ''),
+      status: server?.enabled === false ? 'disabled' : String(server?.auth_status ?? 'configured'),
+    })),
+    skills: scanCodexSkills(root, plugins),
+    agents: [],
+    builtinCommandCount: 0,
+    probedAt: Date.now(),
+    source: 'configured',
+  }
+}