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

package/studio/server/agent/prompts/turn.ts

@@ -0,0 +1,57 @@
+import type { Comment, ContextItem, DocMeta, SchemaIR, SchemaOverlay } from '../../../shared/types'
+
+import { buildCopyMarkdown } from '../../state/copy'
+import { resolveThreadAnchors } from './anchors'
+
+export interface TurnParts {
+  origin: string
+  root: string
+  schemaHash: string
+  awaitingThreads: Comment[]
+  userContext: ContextItem[]
+  autoContext: ContextItem[]
+  documents: DocMeta[]
+  firstTurn: boolean
+  message?: string
+  ir: SchemaIR | null
+  overlay?: SchemaOverlay
+}
+
+/** Build the handoff payload for one new or follow-up turn. */
+export function buildTurnPrompt(parts: TurnParts): string {
+  const body = buildCopyMarkdown({
+    origin: parts.origin,
+    root: parts.root,
+    schemaHash: parts.schemaHash,
+    openComments: parts.awaitingThreads,
+    userContext: parts.userContext,
+    autoContext: parts.autoContext,
+    documents: parts.documents,
+  })
+  const hasThreads = parts.awaitingThreads.length > 0
+  const header = parts.firstTurn
+    ? hasThreads
+      ? '> New session. The thread pointers and context below are your orientation — implement the open threads and reply by id.'
+      : '> New session. Follow the direct instruction below; use the context below and read schema/ when needed.'
+    : hasThreads
+      ? '> Follow-up turn in the SAME session. The schema files are current (incl. your prior edits); the threads below were added or updated since your last reply — implement and answer them.'
+      : '> Follow-up turn in the SAME session. The schema files are current (incl. your prior edits). Follow the direct instruction below.'
+  const anchors = resolveThreadAnchors(parts.awaitingThreads, parts.overlay)
+  const message = parts.message?.trim()
+  const instruction = message ? ['', '## Direct instruction', '', message] : []
+  return [header, ...instruction, '', anchors, '', body]
+    .filter((part) => part !== undefined)
+    .join('\n')
+}
+
+/** Build the minimal nudge for a surviving interrupted conversation. */
+export function buildResumePrompt(): string {
+  return [
+    '> Resuming the SAME session. Your previous turn was cut off when Domain Studio',
+    '> restarted — nothing else has changed. Pick up exactly where you left off.',
+    '',
+    'Continue and finish what you were doing, then make sure every open thread gets an',
+    'answer through the usual channel (the domain-studio MCP tools, or the final',
+    'machine-state ```json``` block). Keep going from where you stopped — do not restart.',
+  ].join('\n')
+}

package/studio/server/agent/routes.test.ts

@@ -0,0 +1,176 @@
+import { afterEach, expect, test } from 'bun:test'
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import type { AskResult } from './harness/adapter'
+
+import { registerDomain, unregisterDomain } from '../domain'
+import { getHarnessById } from './harness/registry'
+import { handleAgentRoute } from './routes'
+import { NdjsonChannel } from './stream'
+
+const roots: string[] = []
+const domainIds: string[] = []
+const previousHarness = process.env.DOMAIN_STUDIO_HARNESS
+
+afterEach(() => {
+  if (previousHarness === undefined) delete process.env.DOMAIN_STUDIO_HARNESS
+  else process.env.DOMAIN_STUDIO_HARNESS = previousHarness
+  while (domainIds.length) unregisterDomain(domainIds.pop()!)
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+function fixture() {
+  const root = mkdtempSync(join(tmpdir(), 'studio-agent-routes-'))
+  roots.push(root)
+  mkdirSync(join(root, 'schema'))
+  writeFileSync(join(root, 'astrale.config.ts'), 'export default {}\n')
+  writeFileSync(join(root, 'domain.ts'), 'export default {}\n')
+  writeFileSync(join(root, 'schema/index.ts'), 'export const Test = {}\n')
+  const handle = registerDomain(root)!
+  domainIds.push(handle.id)
+  return handle
+}
+
+async function route(rest: string, method = 'GET', body: any = {}, search = '') {
+  const handle = fixture()
+  const url = new URL(`http://127.0.0.1/api/domain/${handle.id}${rest}${search}`)
+  const req = new Request(url, {
+    method,
+    ...(method === 'POST'
+      ? {
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify(body),
+        }
+      : {}),
+  })
+  return handleAgentRoute({ req, url, rest, body, handle, notify: () => {} })
+}
+
+test('owns harness status and prompt routes behind one agent boundary', async () => {
+  process.env.DOMAIN_STUDIO_HARNESS = 'mock'
+
+  const harness = await route('/agent/harness')
+  expect(harness?.status).toBe(200)
+  expect(await harness?.json()).toMatchObject({
+    id: 'mock',
+    label: 'Mock agent (free)',
+    ok: true,
+    locked: true,
+    source: 'environment',
+  })
+
+  const prompt = await route('/agent/prompt/system')
+  expect(await prompt?.json()).toMatchObject({
+    bridge: true,
+  })
+})
+
+test('ignores non-agent routes and rejects unknown agent routes', async () => {
+  process.env.DOMAIN_STUDIO_HARNESS = 'mock'
+  expect(await route('/context')).toBeNull()
+  expect((await route('/agent/unknown'))?.status).toBe(404)
+})
+
+test('rejects stale session ownership and invalid gateway writes at the route boundary', async () => {
+  process.env.DOMAIN_STUDIO_HARNESS = 'mock'
+
+  const staleSession = await route('/agent/session', 'POST', {
+    harness: 'codex',
+    sessionId: 'wrong-owner',
+  })
+  expect(staleSession?.status).toBe(400)
+  expect(await staleSession?.json()).toEqual({
+    error: 'selected harness changed from codex to mock',
+  })
+
+  const invalidGateway = await route('/agent/harness-gateway', 'POST', {
+    action: 'set',
+    scope: 'domain',
+    config: { enabled: true, baseUrl: '', auth: { mode: 'mint' } },
+  })
+  expect(invalidGateway?.status).toBe(400)
+  expect(await invalidGateway?.json()).toEqual({
+    error: 'gateway base URL is required while enabled',
+  })
+})
+
+test('threads an explicit loadout refresh through to the selected harness', async () => {
+  process.env.DOMAIN_STUDIO_HARNESS = 'claude'
+  const harness = getHarnessById('claude')
+  const originalLoadout = harness.loadout
+  let refresh: boolean | undefined
+  harness.loadout = async (_root, options) => {
+    refresh = options?.refresh
+    return {
+      ok: true,
+      tools: [],
+      mcpServers: [],
+      skills: [],
+      agents: [],
+      builtinCommandCount: 0,
+      probedAt: Date.now(),
+    }
+  }
+
+  try {
+    const response = await route('/agent/loadout', 'GET', {}, '?refresh=1')
+    expect(response?.status).toBe(200)
+    expect(refresh).toBe(true)
+  } finally {
+    harness.loadout = originalLoadout
+  }
+})
+
+test('cancels an Ask stream without enqueueing after the client closes it', async () => {
+  process.env.DOMAIN_STUDIO_HARNESS = 'mock'
+  const harness = getHarnessById('mock')
+  const originalAsk = harness.ask
+  let finishAsk!: () => void
+  const askFinished = new Promise<void>((resolve) => (finishAsk = resolve))
+  let receivedAbort = false
+  harness.ask = async (input): Promise<AskResult> => {
+    input.onDelta('first')
+    await new Promise<void>((resolve) => {
+      input.signal.addEventListener(
+        'abort',
+        () => {
+          receivedAbort = true
+          resolve()
+        },
+        { once: true },
+      )
+    })
+    input.onDelta('late')
+    finishAsk()
+    return { text: 'firstlate', isError: false }
+  }
+
+  try {
+    const response = await route('/agent/ask', 'POST', { question: 'stream briefly' })
+    const reader = response!.body!.getReader()
+    expect(new TextDecoder().decode((await reader.read()).value)).toContain('"delta":"first"')
+    await reader.cancel()
+    await askFinished
+    expect(receivedAbort).toBe(true)
+  } finally {
+    harness.ask = originalAsk
+  }
+})
+
+test('an NDJSON channel never enqueues after cancellation', () => {
+  const abortController = new AbortController()
+  const chunks: Uint8Array[] = []
+  const target = {
+    enqueue: (chunk: Uint8Array) => chunks.push(chunk),
+    close: () => {},
+  } as unknown as ReadableStreamDefaultController<Uint8Array>
+  const channel = new NdjsonChannel(target, abortController)
+
+  expect(channel.send({ delta: 'first' })).toBe(true)
+  channel.cancel()
+  expect(abortController.signal.aborted).toBe(true)
+  expect(channel.send({ delta: 'late' })).toBe(false)
+  expect(chunks).toHaveLength(1)
+})

package/studio/server/agent/routes.ts

@@ -0,0 +1,214 @@
+import type { HarnessStatus, StudioEvent } from '../../shared/types'
+import type { DomainHandle } from '../domain'
+
+import { runAsk } from './ask'
+import { handleBridge } from './bridge/routes'
+import { inspectHarnessHealth } from './harness/adapter'
+import {
+  clearHarnessGateway,
+  gatewayAudience,
+  getHarnessGatewayState,
+  setHarnessGateway,
+} from './harness/gateway/config'
+import { setHostToken } from './harness/gateway/token'
+import { listHarnesses } from './harness/registry'
+import {
+  getHarness,
+  getHarnessSelection,
+  resolveHarnessConfiguration,
+  setHarnessSelection,
+} from './harness/selection'
+import { buildSystemPrompt } from './prompts/system'
+import {
+  cancelRun,
+  getSessionId,
+  getSnapshot,
+  isRunning,
+  resetConversation,
+  setSessionId,
+  submitRun,
+} from './run/coordinator'
+import { readUsage } from './run/usage'
+import { NdjsonChannel } from './stream'
+
+function json(data: unknown, status = 200): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  })
+}
+
+const badRequest = (message: string) => json({ error: message }, 400)
+const notFound = () => json({ error: 'not found' }, 404)
+
+async function harnessStatus(root: string, selected = false): Promise<HarnessStatus> {
+  const selection = getHarnessSelection(root)
+  const harness = getHarness(root)
+  const health = await inspectHarnessHealth(harness)
+  return {
+    id: harness.id,
+    label: harness.label,
+    bin: health.bin ?? harness.id,
+    ok: health.ok,
+    version: health.version,
+    message: health.ok
+      ? `${selected ? `Selected ${harness.label}` : 'Detected'}${health.version ? ` — ${health.version}` : ''}`
+      : (health.detail ?? `${harness.label} is not detected. Is it installed and on your PATH?`),
+    options: listHarnesses(harness.id),
+    locked: selection.locked,
+    source: selection.source,
+    capabilities: harness.capabilities,
+  }
+}
+
+export interface AgentRouteInput {
+  req: Request
+  url: URL
+  rest: string
+  body: any
+  handle: DomainHandle
+  notify: (event: StudioEvent) => void
+}
+
+/** Own every `/agent/*` HTTP route for one Studio domain. */
+export async function handleAgentRoute(input: AgentRouteInput): Promise<Response | null> {
+  const { req, url, rest, body, handle, notify } = input
+  if (rest !== '/agent' && !rest.startsWith('/agent/')) return null
+  const id = handle.id
+  const root = handle.root
+
+  if (rest === '/agent') {
+    if (req.method === 'GET') return json(await getSnapshot(id))
+    return badRequest('use /agent/submit or /agent/cancel')
+  }
+  if (rest === '/agent/submit' && req.method === 'POST') {
+    const result = await submitRun(handle, notify, {
+      message: typeof body.message === 'string' ? body.message : undefined,
+      resume: body.resume === true,
+    })
+    return result.error ? json({ error: result.error }) : json(result.run)
+  }
+  if (rest === '/agent/cancel' && req.method === 'POST') return json({ ok: cancelRun(id) })
+  if (rest === '/agent/reset' && req.method === 'POST') return json({ ok: resetConversation(id) })
+  if (rest === '/agent/session') {
+    if (req.method === 'GET') return json(getSessionId(id))
+    if (req.method === 'POST') {
+      const harness = getHarness(root)
+      if (body.harness !== harness.id)
+        return badRequest(
+          `selected harness changed from ${String(body.harness ?? '(unknown)')} to ${harness.id}`,
+        )
+      const ok = setSessionId(id, typeof body.sessionId === 'string' ? body.sessionId : '')
+      if (!ok) return badRequest('the session id cannot be changed while a turn is running')
+      return json(getSessionId(id))
+    }
+    return badRequest('GET or POST')
+  }
+  if (rest === '/agent/prompt/system' && req.method === 'GET')
+    return json({ bridge: true, systemPrompt: buildSystemPrompt({ bridge: true }) })
+  if (rest === '/agent/harness' && req.method === 'GET') return json(await harnessStatus(root))
+  if (rest === '/agent/harness' && req.method === 'POST') {
+    if (isRunning(id)) return badRequest('the harness cannot be changed while a turn is running')
+    try {
+      setHarnessSelection(root, String(body.id ?? ''))
+      return json(await harnessStatus(root, true))
+    } catch (error) {
+      return badRequest(String((error as Error)?.message ?? error))
+    }
+  }
+  if (rest === '/agent/loadout' && req.method === 'GET') {
+    const harness = getHarness(root)
+    if (!harness.loadout)
+      return json({
+        ok: false,
+        detail: `${harness.label} does not expose a loadout`,
+        tools: [],
+        mcpServers: [],
+        skills: [],
+        agents: [],
+        builtinCommandCount: 0,
+        probedAt: Date.now(),
+      })
+    const configuration = await resolveHarnessConfiguration(root, harness)
+    if (!configuration.ok)
+      return json({
+        ok: false,
+        detail: `model gateway auth failed — ${configuration.error}`,
+        tools: [],
+        mcpServers: [],
+        skills: [],
+        agents: [],
+        builtinCommandCount: 0,
+        probedAt: Date.now(),
+      })
+    const { env, model } = configuration.configuration
+    return json(
+      await harness.loadout(root, {
+        env,
+        model,
+        refresh: url.searchParams.get('refresh') === '1',
+      }),
+    )
+  }
+  if (rest === '/agent/harness-gateway') {
+    if (req.method === 'GET') return json(getHarnessGatewayState(root))
+    if (req.method === 'POST') {
+      const scope = body.scope === 'global' ? 'global' : 'domain'
+      if (body.action === 'set') {
+        try {
+          return json(setHarnessGateway(root, { scope, config: body.config ?? {} }))
+        } catch (error) {
+          return badRequest(String((error as Error)?.message ?? error))
+        }
+      }
+      if (body.action === 'clear') return json(clearHarnessGateway(root, scope))
+      return badRequest('unknown harness-gateway action')
+    }
+  }
+  if (rest === '/agent/harness-gateway/host-token' && req.method === 'POST') {
+    const audience = gatewayAudience(root)
+    if (!audience) return badRequest('no gateway base URL configured for this domain')
+    return json({ ok: setHostToken(audience, String(body.token ?? '')) })
+  }
+  if (rest === '/agent/usage' && req.method === 'GET') return json(readUsage(root))
+  if (rest === '/agent/skill' && req.method === 'GET') {
+    const command = url.searchParams.get('command')
+    const harness = getHarness(root)
+    if (!command || !harness.skillContent) return notFound()
+    const content = await harness.skillContent(root, command)
+    return content ? json(content) : notFound()
+  }
+  if (rest === '/agent/ask' && req.method === 'POST') {
+    const controller = new AbortController()
+    req.signal?.addEventListener('abort', () => controller.abort(), { once: true })
+    let channel: NdjsonChannel | undefined
+    const stream = new ReadableStream<Uint8Array>({
+      async start(target) {
+        channel = new NdjsonChannel(target, controller)
+        try {
+          const result = await runAsk(handle, body, controller.signal, (delta) =>
+            channel!.send({ delta }),
+          )
+          channel.send(
+            result.isError ? { error: result.errorMessage || 'ask failed' } : { done: result.text },
+          )
+        } catch (error: any) {
+          channel.send({ error: String(error?.message ?? error) })
+        } finally {
+          channel.close()
+        }
+      },
+      cancel() {
+        channel?.cancel()
+        if (!channel) controller.abort()
+      },
+    })
+    return new Response(stream, {
+      headers: { 'content-type': 'application/x-ndjson', 'cache-control': 'no-cache' },
+    })
+  }
+  if (rest.startsWith('/agent/bridge/'))
+    return handleBridge(handle, rest.slice('/agent/bridge/'.length), req, body)
+
+  return notFound()
+}

package/studio/server/agent/run/completion.ts

@@ -0,0 +1,193 @@
+import { randomUUID } from 'node:crypto'
+
+import type { AgentEvent, StudioEvent } from '../../../shared/types'
+import type { PreparedRun } from './preparation'
+
+import { mergeReply } from '../../state/comments'
+import { clearConversation, saveConversation } from '../conversation'
+import { emitStudioEvent } from '../notify'
+import { releaseController } from './live-state'
+import { persistRun } from './transcript'
+import { recordRun } from './usage'
+
+function stripMachineState(text: string): string {
+  return text
+    .replace(/```(?:json)?\s*[\s\S]*?```/g, (block) =>
+      /"comments"|"schemaVersion"/.test(block) ? '' : block,
+    )
+    .trim()
+}
+
+/** Execute and settle one prepared agent run. */
+export async function completeRun(
+  prepared: PreparedRun,
+  controller: AbortController,
+  notify: (event: StudioEvent) => void,
+): Promise<void> {
+  const {
+    domainId,
+    root,
+    harness,
+    settings,
+    session,
+    resume,
+    schemaHash,
+    model,
+    effort,
+    harnessEnv,
+    bridge,
+    run,
+    promptSnapshot,
+  } = prepared
+  const pushEvent = (event: Omit<AgentEvent, 'id' | 'ts'>) => {
+    let text = event.text
+    if (event.kind === 'message') {
+      text = stripMachineState(text)
+      if (!text) return
+    }
+    const stored: AgentEvent = {
+      id: randomUUID(),
+      ts: new Date().toISOString(),
+      ...event,
+      text,
+    }
+    run.events.push(stored)
+    emitStudioEvent(notify, { type: 'agent-event', domainId, runId: run.id, event: stored })
+  }
+
+  let bridgeReplies = 0
+  const liveByComment = new Map<string, Set<string>>()
+  bridge.onReply((commentId, text) => {
+    bridgeReplies += 1
+    if (!liveByComment.has(commentId)) liveByComment.set(commentId, new Set())
+    liveByComment.get(commentId)!.add(text.trim())
+    pushEvent({ kind: 'reply', text, commentId })
+  })
+  bridge.onProgress((text) => pushEvent({ kind: 'status', text }))
+
+  try {
+    const runTurn = (sessionId: string | undefined, firstTurn: boolean) => {
+      const prompt = promptSnapshot(sessionId, firstTurn)
+      run.prompt = prompt
+      emitStudioEvent(notify, { type: 'agent-run', domainId, run })
+      return harness.run({
+        root,
+        prompt: prompt.turnPrompt,
+        appendSystemPrompt: prompt.systemPrompt,
+        sessionId,
+        model,
+        effort,
+        access: settings.agentAccess,
+        mcpServers: bridge.mcpServers,
+        env: harnessEnv,
+        signal: controller.signal,
+        onEvent: pushEvent,
+      })
+    }
+
+    const resumeEventStart = run.events.length
+    const resumeBridgeReplies = bridgeReplies
+    let result = await runTurn(resume, !resume)
+    let conversationTurns = resume ? (session.turns ?? 0) : 0
+    if (resume && result.resumeRejected && !controller.signal.aborted) {
+      clearConversation(root, harness.id)
+      conversationTurns = 0
+      run.sessionId = undefined
+      run.resumed = false
+      const observableActivity =
+        bridgeReplies > resumeBridgeReplies ||
+        run.events
+          .slice(resumeEventStart)
+          .some(
+            (event) => event.kind === 'message' || event.kind === 'tool' || event.kind === 'reply',
+          )
+      if (observableActivity) {
+        result = {
+          ...result,
+          sessionId: undefined,
+          isError: true,
+          errorMessage:
+            'the previous conversation was rejected after observable activity — Studio did not retry automatically to avoid duplicating work',
+        }
+        pushEvent({
+          kind: 'status',
+          text: 'resume was not retried because the rejected attempt had already produced observable activity',
+        })
+      } else {
+        pushEvent({
+          kind: 'status',
+          text: 'previous conversation was no longer available — started a new one',
+        })
+        result = await runTurn(undefined, true)
+      }
+    }
+
+    run.sessionId = result.sessionId ?? run.sessionId
+    run.costUsd = result.costUsd
+    run.tokens = result.tokens
+    run.numTurns = result.numTurns
+    run.liveReplies = bridgeReplies
+    if (bridgeReplies > 0 && !controller.signal.aborted)
+      pushEvent({
+        kind: 'status',
+        text: `replied to ${bridgeReplies} thread${bridgeReplies === 1 ? '' : 's'} live`,
+      })
+
+    let replyError: string | undefined
+    if (
+      !controller.signal.aborted &&
+      !result.isError &&
+      result.finalText &&
+      result.finalText.trim()
+    ) {
+      try {
+        const merged = mergeReply(root, schemaHash, result.finalText, {
+          skipByComment: liveByComment,
+        })
+        run.merge = merged
+        if (merged.merged || merged.closed)
+          pushEvent({
+            kind: 'status',
+            text: `merged ${merged.merged} repl${merged.merged === 1 ? 'y' : 'ies'}, closed ${merged.closed}`,
+          })
+        emitStudioEvent(notify, { type: 'comments', domainId })
+      } catch (error: any) {
+        if (/```json/i.test(result.finalText)) {
+          replyError = `agent reply block was malformed JSON — reply not merged (${String(error?.message ?? error).slice(0, 80)})`
+          pushEvent({ kind: 'error', text: replyError })
+        } else if (bridgeReplies === 0) {
+          pushEvent({ kind: 'status', text: 'no machine-state reply block in the final message' })
+        }
+      }
+    }
+
+    if (controller.signal.aborted) run.status = 'canceled'
+    else if (result.isError) {
+      run.status = 'failed'
+      run.error = result.errorMessage
+      pushEvent({ kind: 'error', text: result.errorMessage ?? 'agent error' })
+    } else if (replyError) {
+      run.status = 'failed'
+      run.error = replyError
+    } else run.status = 'succeeded'
+
+    if (run.status === 'succeeded' && result.sessionId)
+      saveConversation(root, harness.id, {
+        sessionId: result.sessionId,
+        turns: conversationTurns + 1,
+        updatedAt: new Date().toISOString(),
+      })
+  } catch (error: any) {
+    run.status = controller.signal.aborted ? 'canceled' : 'failed'
+    run.error = String(error?.message ?? error)
+    pushEvent({ kind: 'error', text: run.error })
+  } finally {
+    run.finishedAt = new Date().toISOString()
+    releaseController(domainId, controller)
+    bridge.dispose()
+    recordRun(root, run)
+    persistRun(root, run, true)
+    emitStudioEvent(notify, { type: 'agent-run', domainId, run })
+    emitStudioEvent(notify, { type: 'comments', domainId })
+  }
+}