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

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

@@ -0,0 +1,63 @@
+import type { AgentTurnInput, AskInput } from '../adapter'
+
+const PERMISSION_MODE = process.env.DOMAIN_STUDIO_AGENT_PERMISSION || 'bypassPermissions'
+const EXTRA_ARGS = (process.env.DOMAIN_STUDIO_CLAUDE_ARGS || '').split(' ').filter(Boolean)
+const ULTRACODE_SETTINGS = JSON.stringify({ ultracode: true })
+
+function permissionMode(access?: AgentTurnInput['access']): string {
+  return (
+    process.env.DOMAIN_STUDIO_AGENT_PERMISSION ||
+    (access === 'workspace' ? 'acceptEdits' : PERMISSION_MODE)
+  )
+}
+
+function appendEffort(args: string[], effort?: AgentTurnInput['effort']): void {
+  if (!effort) return
+  if (effort === 'ultracode') {
+    args.push('--effort', 'xhigh', '--settings', ULTRACODE_SETTINGS)
+    return
+  }
+  args.push('--effort', effort)
+}
+
+export function buildClaudeProbeArgs(model?: string): string[] {
+  const args = ['-p', '--output-format', 'stream-json', '--verbose', ...EXTRA_ARGS]
+  if (model) args.push('--model', model)
+  return args
+}
+
+export function buildClaudeTurnArgs(input: AgentTurnInput, mcpPath?: string): string[] {
+  const args = [
+    '-p',
+    '--output-format',
+    'stream-json',
+    '--verbose',
+    '--permission-mode',
+    permissionMode(input.access),
+  ]
+  if (input.sessionId) args.push('--resume', input.sessionId)
+  if (input.model) args.push('--model', input.model)
+  appendEffort(args, input.effort)
+  if (mcpPath) args.push('--mcp-config', mcpPath)
+  if (input.appendSystemPrompt) args.push('--append-system-prompt', input.appendSystemPrompt)
+  args.push(...EXTRA_ARGS)
+  return args
+}
+
+export function buildClaudeAskArgs(input: AskInput): string[] {
+  const args = [
+    '-p',
+    '--output-format',
+    'stream-json',
+    '--verbose',
+    '--permission-mode',
+    permissionMode(input.access),
+  ]
+  if (input.model) args.push('--model', input.model)
+  appendEffort(args, input.effort)
+  if (input.sessionId) args.push('--resume', input.sessionId, '--fork-session')
+  args.push('--no-session-persistence')
+  if (input.appendSystemPrompt) args.push('--append-system-prompt', input.appendSystemPrompt)
+  args.push(...EXTRA_ARGS)
+  return args
+}

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

@@ -0,0 +1,215 @@
+import { spawn } from 'node:child_process'
+
+import type { AgentTurnInput, AgentTurnResult } from '../adapter'
+
+import { childEnvironment, terminateProcessTree } from '../process'
+import { buildClaudeTurnArgs } from './command'
+import { writeClaudeMcpConfig } from './mcp'
+
+const RESUME_REJECTED =
+  /no conversation found|session (?:id .*)?(?:not found|does not exist|no longer exists|expired)|could not (?:find|load|resume) .*session|unknown session|invalid session id/i
+
+function toolTarget(name: string, input: Record<string, unknown> | undefined): string {
+  if (!input) return ''
+  const text = (value: unknown) =>
+    typeof value === 'string' ? value : value == null ? '' : JSON.stringify(value)
+  switch (name) {
+    case 'Edit':
+    case 'Write':
+    case 'MultiEdit':
+    case 'NotebookEdit':
+      return text(input.file_path ?? input.path ?? input.notebook_path)
+    case 'Read':
+      return text(input.file_path)
+    case 'Bash':
+      return text(input.command).slice(0, 200)
+    case 'Grep':
+    case 'Glob':
+      return text(input.pattern)
+    case 'Task':
+      return text(input.description)
+    default:
+      return text(Object.values(input)[0]).slice(0, 200)
+  }
+}
+
+/** Execute one Claude stream-json turn and normalize its result. */
+export function runClaudeTurn(bin: string, input: AgentTurnInput): Promise<AgentTurnResult> {
+  const mcp = writeClaudeMcpConfig(input.root, input.mcpServers)
+  return new Promise((resolve) => {
+    let resolvedSession = input.sessionId
+    let finalText = ''
+    let costUsd: number | undefined
+    let numTurns: number | undefined
+    let tokens: number | undefined
+    let isError = false
+    let errorMessage: string | undefined
+    let sawResult = false
+    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)
+      mcp.dispose()
+      resolve(result)
+    }
+
+    let child: ReturnType<typeof spawn>
+    try {
+      child = spawn(bin, buildClaudeTurnArgs(input, mcp.path), {
+        cwd: input.root,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: childEnvironment(input.env),
+        detached: process.platform !== 'win32',
+      })
+    } catch (error) {
+      finish({
+        sessionId: resolvedSession,
+        finalText,
+        isError: true,
+        errorMessage: `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()
+
+    const handleLine = (line: string) => {
+      let event: any
+      try {
+        event = JSON.parse(line)
+      } catch {
+        return
+      }
+      switch (event.type) {
+        case 'system':
+          if (event.subtype === 'init') {
+            if (event.session_id) resolvedSession = event.session_id
+            input.onEvent({ kind: 'status', text: 'session started' })
+          }
+          return
+        case 'assistant':
+          if (!Array.isArray(event.message?.content)) return
+          for (const block of event.message.content) {
+            if (block.type === 'text' && block.text?.trim())
+              input.onEvent({ kind: 'message', text: block.text.trim() })
+            else if (block.type === 'thinking' && block.thinking?.trim())
+              input.onEvent({ kind: 'thinking', text: block.thinking.trim() })
+            else if (block.type === 'tool_use')
+              input.onEvent({
+                kind: 'tool',
+                text: block.name,
+                tool: block.name,
+                target: toolTarget(block.name, block.input),
+              })
+          }
+          return
+        case 'result': {
+          sawResult = true
+          if (typeof event.result === 'string') finalText = event.result
+          if (typeof event.total_cost_usd === 'number') costUsd = event.total_cost_usd
+          if (typeof event.num_turns === 'number') numTurns = event.num_turns
+          if (event.usage && typeof event.usage === 'object') {
+            const usage = event.usage as Record<string, number | undefined>
+            tokens =
+              (usage.input_tokens ?? 0) +
+              (usage.output_tokens ?? 0) +
+              (usage.cache_read_input_tokens ?? 0) +
+              (usage.cache_creation_input_tokens ?? 0)
+          }
+          if (event.session_id) resolvedSession = event.session_id
+          if (
+            event.is_error ||
+            event.subtype === 'error_during_execution' ||
+            event.subtype === 'error_max_turns'
+          ) {
+            isError = true
+            errorMessage = event.subtype || 'agent error'
+          }
+          return
+        }
+        case 'rate_limit_event':
+          if (event.rate_limit_info?.status && event.rate_limit_info.status !== 'allowed')
+            input.onEvent({
+              kind: 'status',
+              text: `rate limit: ${event.rate_limit_info.status}`,
+            })
+      }
+    }
+
+    let buffer = ''
+    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({
+        sessionId: resolvedSession,
+        finalText,
+        costUsd,
+        numTurns,
+        tokens,
+        isError: true,
+        errorMessage: `failed to spawn ${bin}: ${error.message}`,
+      }),
+    )
+    child.on('close', (code) => {
+      const trailing = buffer.trim()
+      if (trailing) handleLine(trailing)
+      if (input.signal.aborted)
+        return finish({
+          sessionId: resolvedSession,
+          finalText,
+          costUsd,
+          numTurns,
+          tokens,
+          isError: true,
+          errorMessage: 'canceled',
+        })
+      if (code !== 0) {
+        isError = true
+        errorMessage =
+          errorMessage || `claude exited ${code}${stderr ? `: ${stderr.slice(-400)}` : ''}`
+      } else if (!sawResult) {
+        isError = true
+        errorMessage = 'claude exited without a result event'
+      }
+      finish({
+        sessionId: resolvedSession,
+        finalText,
+        costUsd,
+        numTurns,
+        tokens,
+        isError,
+        errorMessage,
+        resumeRejected:
+          !!input.sessionId &&
+          (isError || code !== 0) &&
+          RESUME_REJECTED.test(`${errorMessage ?? ''}\n${stderr}`),
+      })
+    })
+  })
+}

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

@@ -0,0 +1,132 @@
+import { spawn } from 'node:child_process'
+
+import type { HarnessLoadout } from '../../../../shared/types'
+import type { HarnessHealth, HarnessLoadoutOptions } from '../adapter'
+
+import { captureCommand, childEnvironment, terminateProcessTree } from '../process'
+import { reconcileLoadedSkills } from '../skills'
+import { buildClaudeProbeArgs } from './command'
+import { scanClaudeSkills } from './skills'
+
+interface InitProbe {
+  ok: boolean
+  detail?: string
+  init?: any
+}
+
+/** Probe the installed Claude binary and version. */
+export async function probeClaudeHealth(bin: string, signal?: AbortSignal): Promise<HarnessHealth> {
+  const result = await captureCommand(bin, ['--version'], process.cwd(), { signal })
+  return {
+    ok: result.code === 0,
+    version: result.code === 0 ? result.stdout.trim() || undefined : undefined,
+    bin,
+    detail:
+      result.code === 0 ? undefined : result.stderr.trim() || `\`${bin}\` was not found on PATH`,
+  }
+}
+
+/** Inspect Claude's authoritative runtime initialization event. */
+export async function loadClaudeConfiguration(
+  bin: string,
+  root: string,
+  options?: HarnessLoadoutOptions,
+): Promise<HarnessLoadout> {
+  const now = Date.now()
+  const probe = await probeClaudeInit(bin, root, options)
+  if (!probe.ok || !probe.init)
+    return {
+      ok: false,
+      detail: probe.detail,
+      tools: [],
+      mcpServers: [],
+      skills: [],
+      agents: [],
+      builtinCommandCount: 0,
+      probedAt: now,
+    }
+
+  const init = probe.init
+  const slash: string[] = Array.isArray(init.slash_commands) ? init.slash_commands : []
+  const installed = scanClaudeSkills(root)
+  const skillCommands = new Set(installed.map((skill) => skill.command))
+  return {
+    ok: true,
+    model: init.model,
+    nativeModel: options?.model ? undefined : init.model,
+    modelSource: options?.model ? 'studio' : 'runtime',
+    permissionMode: init.permissionMode,
+    apiKeySource: init.apiKeySource,
+    cwd: init.cwd,
+    tools: Array.isArray(init.tools) ? init.tools : [],
+    mcpServers: Array.isArray(init.mcp_servers)
+      ? init.mcp_servers.map((server: any) => ({
+          name: String(server?.name ?? ''),
+          status: String(server?.status ?? 'unknown'),
+        }))
+      : [],
+    skills: reconcileLoadedSkills(installed, slash),
+    agents: Array.isArray(init.agents) ? init.agents : [],
+    builtinCommandCount: slash.filter((command) => !skillCommands.has(command)).length,
+    probedAt: now,
+    source: 'runtime',
+  }
+}
+
+function probeClaudeInit(
+  bin: string,
+  root: string,
+  options?: HarnessLoadoutOptions,
+): Promise<InitProbe> {
+  return new Promise((resolve) => {
+    let child: ReturnType<typeof spawn>
+    try {
+      child = spawn(bin, buildClaudeProbeArgs(options?.model), {
+        cwd: root,
+        stdio: ['pipe', 'pipe', 'ignore'],
+        env: childEnvironment(options?.env),
+        detached: process.platform !== 'win32',
+      })
+    } catch (error) {
+      resolve({ ok: false, detail: `failed to spawn ${bin}: ${String(error)}` })
+      return
+    }
+    let done = false
+    const finish = (result: InitProbe) => {
+      if (done) return
+      done = true
+      clearTimeout(timer)
+      terminateProcessTree(child, 'SIGKILL')
+      resolve(result)
+    }
+    const timer = setTimeout(() => finish({ ok: false, detail: 'loadout probe timed out' }), 15_000)
+    child.on('error', (error) =>
+      finish({ ok: false, detail: `failed to spawn ${bin}: ${error.message}` }),
+    )
+    child.on('close', () => finish({ ok: false, detail: 'probe ended before an init event' }))
+    child.stdin?.write('.')
+    child.stdin?.end()
+
+    let buffer = ''
+    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) continue
+        let event: any
+        try {
+          event = JSON.parse(line)
+        } catch {
+          continue
+        }
+        if (event.type === 'system' && event.subtype === 'init') {
+          finish({ ok: true, init: event })
+          return
+        }
+      }
+    })
+  })
+}

package/studio/server/agent/harness/claude/mcp.test.ts

@@ -0,0 +1,36 @@
+import { afterEach, expect, test } from 'bun:test'
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { writeClaudeMcpConfig } from './mcp'
+
+const roots: string[] = []
+
+afterEach(() => {
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+test('serializes a structured MCP grant into Claude JSON', () => {
+  const root = mkdtempSync(join(tmpdir(), 'studio-claude-mcp-'))
+  roots.push(root)
+  const config = writeClaudeMcpConfig(root, [
+    {
+      name: 'domain-studio',
+      command: '/opt/bun',
+      args: ['/studio/bridge/stdio.ts', '--config', '/domain/bridge.json'],
+      env: { MODE: 'test value' },
+    },
+  ])
+  expect(JSON.parse(readFileSync(config.path!, 'utf8'))).toEqual({
+    mcpServers: {
+      'domain-studio': {
+        command: '/opt/bun',
+        args: ['/studio/bridge/stdio.ts', '--config', '/domain/bridge.json'],
+        env: { MODE: 'test value' },
+      },
+    },
+  })
+  config.dispose()
+  expect(existsSync(config.path!)).toBe(false)
+})

package/studio/server/agent/harness/claude/mcp.ts

@@ -0,0 +1,41 @@
+import { randomUUID } from 'node:crypto'
+
+import type { HarnessMcpServer } from '../adapter'
+
+import { removeState, statePath, writeJson } from '../../../state/store'
+
+export interface TemporaryMcpConfig {
+  path?: string
+  dispose(): void
+}
+
+/** Serialize Studio MCP grants into Claude Code's temporary JSON format. */
+export function writeClaudeMcpConfig(
+  root: string,
+  servers: HarnessMcpServer[] | undefined,
+): TemporaryMcpConfig {
+  if (!servers?.length) return { dispose: () => {} }
+  const rel = `.cache/agent/claude-mcp-${randomUUID()}.json`
+  writeJson(root, rel, {
+    mcpServers: Object.fromEntries(
+      servers.map((server) => [
+        server.name,
+        {
+          command: server.command,
+          ...(server.args?.length ? { args: server.args } : {}),
+          ...(server.env && Object.keys(server.env).length ? { env: server.env } : {}),
+        },
+      ]),
+    ),
+  })
+  return {
+    path: statePath(root, rel),
+    dispose: () => {
+      try {
+        removeState(root, rel)
+      } catch {
+        /* best-effort temp cleanup */
+      }
+    },
+  }
+}

package/studio/server/agent/harness/claude/skills.ts

@@ -0,0 +1,43 @@
+import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+import type { LoadoutSkill } from '../../../../shared/types'
+
+import { scanAncestors, scanSkillDir } from '../skills'
+
+function installedPluginDirs(): { plugin: string; installPath: string }[] {
+  const file = join(homedir(), '.claude', 'plugins', 'installed_plugins.json')
+  let parsed: any
+  try {
+    parsed = JSON.parse(readFileSync(file, 'utf8'))
+  } catch {
+    return []
+  }
+  const out: { plugin: string; installPath: string }[] = []
+  const seen = new Set<string>()
+  for (const [key, entries] of Object.entries(parsed?.plugins ?? {})) {
+    const plugin = String(key).split('@')[0]
+    for (const entry of Array.isArray(entries) ? entries : []) {
+      const installPath = (entry as any)?.installPath
+      if (typeof installPath === 'string' && !seen.has(installPath)) {
+        seen.add(installPath)
+        out.push({ plugin, installPath })
+      }
+    }
+  }
+  return out
+}
+
+/** Discover the skills visible to Claude Code for one domain root. */
+export function scanClaudeSkills(root: string): LoadoutSkill[] {
+  const out: LoadoutSkill[] = []
+  const seen = new Set<string>()
+  const home = homedir()
+  scanAncestors(root, ['.claude/skills', '.agents/skills'], out, seen)
+  scanSkillDir(join(home, '.claude', 'skills'), 'user', undefined, '', true, out, seen)
+  scanSkillDir(join(home, '.agents', 'skills'), 'user', undefined, '', true, out, seen)
+  for (const { plugin, installPath } of installedPluginDirs())
+    scanSkillDir(join(installPath, 'skills'), 'plugin', plugin, `${plugin}:`, true, out, seen)
+  return out
+}