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

package/studio/server/agent/run/coordinator.test.ts

@@ -0,0 +1,337 @@
+import { afterEach, describe, expect, test } from 'bun:test'
+import { randomUUID } from 'node:crypto'
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import type { AgentRun } from '../../../shared/types'
+
+import { registerDomain, unregisterDomain, type DomainHandle } from '../../domain'
+import { readComments, upsertComment } from '../../state/comments'
+import { updateSettings } from '../../state/settings'
+import { handleBridge } from '../bridge/routes'
+import { readConversation, saveConversation } from '../conversation'
+import { setHarnessGateway } from '../harness/gateway/config'
+import {
+  cancelRun,
+  getSnapshot,
+  isRunning,
+  resetConversation,
+  setSessionId,
+  submitRun,
+} from './coordinator'
+
+const roots: string[] = []
+const domainIds: string[] = []
+const envBefore = {
+  harness: process.env.DOMAIN_STUDIO_HARNESS,
+  mode: process.env.DOMAIN_STUDIO_MOCK_MODE,
+  delay: process.env.DOMAIN_STUDIO_MOCK_DELAY_MS,
+  model: process.env.DOMAIN_STUDIO_MOCK_EXPECT_MODEL,
+}
+
+function restoreEnv(name: keyof typeof envBefore, variable: string): void {
+  const value = envBefore[name]
+  if (value === undefined) delete process.env[variable]
+  else process.env[variable] = value
+}
+
+afterEach(() => {
+  restoreEnv('harness', 'DOMAIN_STUDIO_HARNESS')
+  restoreEnv('mode', 'DOMAIN_STUDIO_MOCK_MODE')
+  restoreEnv('delay', 'DOMAIN_STUDIO_MOCK_DELAY_MS')
+  restoreEnv('model', 'DOMAIN_STUDIO_MOCK_EXPECT_MODEL')
+  while (domainIds.length) unregisterDomain(domainIds.pop()!)
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+function fixture(): DomainHandle {
+  const root = mkdtempSync(join(tmpdir(), `studio-runner-${randomUUID()}-`))
+  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
+}
+
+function bridgeFiles(root: string): string[] {
+  const dir = join(root, '.domain-studio', '.cache', 'agent')
+  if (!existsSync(dir)) return []
+  return readdirSync(dir).filter((file) => file.startsWith('bridge-'))
+}
+
+async function waitForTerminal(domainId: string): Promise<AgentRun> {
+  for (let i = 0; i < 200; i++) {
+    const run = (await getSnapshot(domainId)).run
+    if (run && !['queued', 'running'].includes(run.status)) return run
+    await Bun.sleep(25)
+  }
+  throw new Error(`timed out waiting for ${domainId}`)
+}
+
+function useMock(mode = 'normal', delay = '0'): void {
+  process.env.DOMAIN_STUDIO_HARNESS = 'mock'
+  process.env.DOMAIN_STUDIO_MOCK_MODE = mode
+  process.env.DOMAIN_STUDIO_MOCK_DELAY_MS = delay
+}
+
+describe.serial('agent runner invariants', () => {
+  test('passes the selected harness model into the turn and its persisted prompt snapshot', async () => {
+    useMock()
+    const handle = fixture()
+    process.env.DOMAIN_STUDIO_MOCK_EXPECT_MODEL = 'mock-domain-model'
+    updateSettings(handle.root, { agentModels: { mock: 'mock-domain-model' } })
+
+    await submitRun(handle, () => {}, { message: 'use the selected model' })
+    const run = await waitForTerminal(handle.id)
+
+    expect(run.status).toBe('succeeded')
+    expect(run.prompt?.model).toBe('mock-domain-model')
+  })
+
+  test('reserves setup synchronously and starts exactly one turn', async () => {
+    useMock()
+    const handle = fixture()
+
+    const first = submitRun(handle, () => {}, { message: 'first' })
+    expect(isRunning(handle.id)).toBe(true)
+    expect(setSessionId(handle.id, 'hijack')).toBe(false)
+    expect(resetConversation(handle.id)).toBe(false)
+
+    const second = await submitRun(handle, () => {}, { message: 'second' })
+    expect(second).toEqual({ error: 'an agent run is already in progress for this domain' })
+    expect((await first).run?.status).toBe('running')
+    const completed = await waitForTerminal(handle.id)
+    expect(completed.status).toBe('succeeded')
+    expect(readConversation(handle.root, 'mock')).toMatchObject({
+      sessionId: 'mock-session',
+      turns: 1,
+    })
+    expect(isRunning(handle.id)).toBe(false)
+    expect(bridgeFiles(handle.root)).toEqual([])
+  })
+
+  test('can cancel a reserved turn before the harness launches', async () => {
+    useMock()
+    const handle = fixture()
+
+    const pending = submitRun(handle, () => {}, { message: 'cancel setup' })
+    expect(isRunning(handle.id)).toBe(true)
+    expect(cancelRun(handle.id)).toBe(true)
+    expect(await pending).toEqual({ error: 'agent run canceled during setup' })
+    expect(isRunning(handle.id)).toBe(false)
+    expect(readConversation(handle.root, 'mock').sessionId).toBeUndefined()
+    expect(bridgeFiles(handle.root)).toEqual([])
+  })
+
+  test('notification failures cannot strand a running domain lock', async () => {
+    useMock()
+    const handle = fixture()
+    const started = await submitRun(
+      handle,
+      () => {
+        throw new Error('listener failed')
+      },
+      { message: 'keep running' },
+    )
+
+    expect(started.run?.status).toBe('running')
+    expect((await waitForTerminal(handle.id)).status).toBe('succeeded')
+    expect(isRunning(handle.id)).toBe(false)
+  })
+
+  test('recovers a stale selected-harness session as one fresh first turn', async () => {
+    useMock('resumefail')
+    const handle = fixture()
+    process.env.DOMAIN_STUDIO_MOCK_EXPECT_MODEL = 'mock-recovery-model'
+    updateSettings(handle.root, { agentModels: { mock: 'mock-recovery-model' } })
+    setHarnessGateway(handle.root, {
+      scope: 'domain',
+      config: {
+        enabled: true,
+        baseUrl: 'https://gateway.invalid/v1/models/test',
+        auth: { mode: 'host' },
+      },
+    })
+    saveConversation(handle.root, 'mock', {
+      sessionId: 'stale-session',
+      turns: 7,
+      updatedAt: 'before',
+    })
+
+    const started = await submitRun(handle, () => {}, { message: 'continue safely' })
+    expect(started.run?.harness).toBe('mock')
+    const run = await waitForTerminal(handle.id)
+
+    expect(run).toMatchObject({
+      status: 'succeeded',
+      sessionId: 'mock-session',
+      resumed: false,
+    })
+    expect(run.prompt).toMatchObject({
+      firstTurn: true,
+      resumed: false,
+      sessionId: undefined,
+      model: 'mock-recovery-model',
+    })
+    expect(run.events.map((event) => event.text)).toContain(
+      'previous conversation was no longer available — started a new one',
+    )
+    expect(readConversation(handle.root, 'mock')).toMatchObject({
+      sessionId: 'mock-session',
+      turns: 1,
+    })
+    expect(bridgeFiles(handle.root)).toEqual([])
+  })
+
+  test('does not replay a rejected resume after observable activity', async () => {
+    useMock('resumefailafterevent')
+    const handle = fixture()
+    saveConversation(handle.root, 'mock', {
+      sessionId: 'stale-session',
+      turns: 2,
+      updatedAt: 'before',
+    })
+
+    await submitRun(handle, () => {}, { message: 'continue once' })
+    const run = await waitForTerminal(handle.id)
+
+    expect(run).toMatchObject({
+      status: 'failed',
+      sessionId: undefined,
+      resumed: false,
+      error:
+        'the previous conversation was rejected after observable activity — Studio did not retry automatically to avoid duplicating work',
+    })
+    expect(run.events.filter((event) => event.kind === 'tool')).toHaveLength(1)
+    expect(readConversation(handle.root, 'mock').sessionId).toBeUndefined()
+  })
+
+  test('cancellation skips partial replies, preserves the session, cleans up, and permits retry', async () => {
+    useMock('normal', '5000')
+    const handle = fixture()
+    const comment = upsertComment(handle.root, {
+      anchors: ['Test'],
+      anchorRefs: [{ ref: 'class.Test', kind: 'schema' }],
+      text: 'keep this open if canceled',
+    })
+    saveConversation(handle.root, 'mock', {
+      sessionId: 'stable-session',
+      turns: 2,
+      updatedAt: 'before',
+    })
+
+    const started = await submitRun(handle, () => {})
+    expect(started.run?.status).toBe('running')
+    const bridgeFile = bridgeFiles(handle.root)[0]!
+    const { token } = JSON.parse(
+      readFileSync(join(handle.root, '.domain-studio', '.cache', 'agent', bridgeFile), 'utf8'),
+    ) as { token: string }
+    expect(cancelRun(handle.id)).toBe(true)
+    expect(
+      (await handleBridge(handle, 'threads', new Request('http://studio.test'), { token })).status,
+    ).toBe(401)
+    const canceled = await waitForTerminal(handle.id)
+
+    expect(canceled.status).toBe('canceled')
+    expect(readConversation(handle.root, 'mock')).toMatchObject({
+      sessionId: 'stable-session',
+      turns: 2,
+    })
+    expect(readComments(handle.root).comments.find((item) => item.id === comment.id)).toMatchObject(
+      {
+        status: 'open',
+        thread: [{ role: 'user', text: 'keep this open if canceled' }],
+      },
+    )
+    expect(bridgeFiles(handle.root)).toEqual([])
+    expect(isRunning(handle.id)).toBe(false)
+
+    process.env.DOMAIN_STUDIO_MOCK_DELAY_MS = '0'
+    const retry = await submitRun(handle, () => {}, { message: 'retry' })
+    expect(retry.run?.status).toBe('running')
+    expect((await waitForTerminal(handle.id)).status).toBe('succeeded')
+  })
+
+  test('harness throws and malformed final replies fail without changing the prior session', async () => {
+    useMock('error')
+    const handle = fixture()
+    const comment = upsertComment(handle.root, {
+      anchors: ['Test'],
+      anchorRefs: [{ ref: 'class.Test', kind: 'schema' }],
+      text: 'do not merge failed output',
+    })
+    saveConversation(handle.root, 'mock', {
+      sessionId: 'stable-session',
+      turns: 4,
+      updatedAt: 'before',
+    })
+
+    await submitRun(handle, () => {})
+    const thrown = await waitForTerminal(handle.id)
+    expect(thrown).toMatchObject({
+      status: 'failed',
+      error: 'mock harness failure (test)',
+    })
+    expect(readConversation(handle.root, 'mock')).toMatchObject({
+      sessionId: 'stable-session',
+      turns: 4,
+    })
+    expect(
+      readComments(handle.root).comments.find((item) => item.id === comment.id)?.thread,
+    ).toHaveLength(1)
+    expect(bridgeFiles(handle.root)).toEqual([])
+
+    process.env.DOMAIN_STUDIO_MOCK_MODE = 'badblock'
+    await submitRun(handle, () => {})
+    const malformed = await waitForTerminal(handle.id)
+    expect(malformed.status).toBe('failed')
+    expect(malformed.error).toContain('malformed JSON')
+    expect(readConversation(handle.root, 'mock')).toMatchObject({
+      sessionId: 'stable-session',
+      turns: 4,
+    })
+    expect(
+      readComments(handle.root).comments.find((item) => item.id === comment.id)?.thread,
+    ).toHaveLength(1)
+    expect(bridgeFiles(handle.root)).toEqual([])
+  })
+
+  test('dedupes an echoed live reply while still merging distinct final detail', async () => {
+    useMock('liveandblockdifferent')
+    const handle = fixture()
+    const comment = upsertComment(handle.root, {
+      anchors: ['Test'],
+      anchorRefs: [{ ref: 'class.Test', kind: 'schema' }],
+      text: 'answer live and in the final block',
+    })
+    expect(readComments(handle.root).comments.map((item) => item.id)).toEqual([comment.id])
+
+    await submitRun(handle, () => {})
+    const run = await waitForTerminal(handle.id)
+    expect(run).toMatchObject({
+      status: 'succeeded',
+      liveReplies: 1,
+      merge: { merged: 1, closed: 0 },
+    })
+    const saved = readComments(handle.root).comments.find((item) => item.id === comment.id)!
+    expect(saved.status).toBe('closed')
+    expect(saved.thread.map((entry) => `${entry.role}:${entry.text}`)).toEqual([
+      'user:answer live and in the final block',
+      'author:Acknowledged. (mock agent)',
+      'author:Additional final detail. (mock agent)',
+    ])
+    expect(bridgeFiles(handle.root)).toEqual([])
+  })
+})

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

@@ -0,0 +1,104 @@
+import type {
+  AgentRun,
+  AgentRunSnapshot,
+  ConversationInfo,
+  StudioEvent,
+} from '../../../shared/types'
+import type { DomainHandle } from '../../domain'
+
+import { getDomain } from '../../domain'
+import {
+  clearConversation,
+  conversationInfo,
+  sessionInfo,
+  setConversationSession,
+} from '../conversation'
+import { getHarness } from '../harness/selection'
+import { emitStudioEvent } from '../notify'
+import { completeRun } from './completion'
+import {
+  attachCancellation,
+  cancelActiveRun,
+  currentRun,
+  hydrateRun,
+  isRunActive,
+  releasePreparation,
+  reserveRun,
+  setCurrentRun,
+} from './live-state'
+import { prepareRun, type SubmitOpts } from './preparation'
+import { persistRun } from './transcript'
+
+function conversationOf(root: string): ConversationInfo {
+  const harness = getHarness(root)
+  return conversationInfo(root, harness.id)
+}
+
+export function isRunning(domainId: string): boolean {
+  return isRunActive(domainId)
+}
+
+export async function getSnapshot(domainId: string): Promise<AgentRunSnapshot> {
+  const handle = getDomain(domainId)
+  const harness = getHarness(handle?.root ?? process.cwd())
+  if (handle) hydrateRun(domainId, handle.root)
+  return {
+    harness: harness.id,
+    available: await harness.isAvailable(),
+    run: currentRun(domainId) ?? null,
+    conversation: handle ? conversationOf(handle.root) : { active: false, turns: 0 },
+  }
+}
+
+export function cancelRun(domainId: string): boolean {
+  return cancelActiveRun(domainId)
+}
+
+export function resetConversation(domainId: string): boolean {
+  const handle = getDomain(domainId)
+  if (!handle || isRunActive(domainId)) return false
+  clearConversation(handle.root, getHarness(handle.root).id)
+  return true
+}
+
+export function getSessionId(domainId: string): {
+  sessionId: string | null
+  turns: number
+  harness?: string
+} {
+  const handle = getDomain(domainId)
+  if (!handle) return { sessionId: null, turns: 0 }
+  return sessionInfo(handle.root, getHarness(handle.root).id)
+}
+
+export function setSessionId(domainId: string, sessionId: string): boolean {
+  const handle = getDomain(domainId)
+  if (!handle || isRunActive(domainId)) return false
+  const harness = getHarness(handle.root)
+  const trimmed = sessionId.trim()
+  if (!trimmed) clearConversation(handle.root, harness.id)
+  else setConversationSession(handle.root, harness.id, trimmed)
+  return true
+}
+
+export async function submitRun(
+  handle: DomainHandle,
+  notify: (event: StudioEvent) => void,
+  options?: SubmitOpts,
+): Promise<{ run?: AgentRun; error?: string }> {
+  const controller = reserveRun(handle.id)
+  if (!controller) return { error: 'an agent run is already in progress for this domain' }
+  try {
+    const result = await prepareRun(handle, notify, controller, options)
+    if ('error' in result) return result
+    const { prepared } = result
+    attachCancellation(handle.id, controller, prepared.bridge.dispose)
+    setCurrentRun(prepared.run)
+    persistRun(prepared.root, prepared.run)
+    emitStudioEvent(notify, { type: 'agent-run', domainId: handle.id, run: prepared.run })
+    void completeRun(prepared, controller, notify)
+    return { run: prepared.run }
+  } finally {
+    releasePreparation(handle.id, controller)
+  }
+}

package/studio/server/agent/run/live-state.ts

@@ -0,0 +1,73 @@
+import type { AgentRun } from '../../../shared/types'
+
+import { readLastRun } from './transcript'
+
+const runs = new Map<string, AgentRun>()
+const controllers = new Map<string, AbortController>()
+const cancellation = new Map<string, () => void>()
+const starting = new Set<string>()
+const hydrated = new Set<string>()
+
+export function currentRun(domainId: string): AgentRun | undefined {
+  return runs.get(domainId)
+}
+
+export function setCurrentRun(run: AgentRun): void {
+  runs.set(run.domainId, run)
+}
+
+export function isRunActive(domainId: string): boolean {
+  const status = runs.get(domainId)?.status
+  return starting.has(domainId) || status === 'running' || status === 'queued'
+}
+
+/** Reserve a domain synchronously before asynchronous run preparation begins. */
+export function reserveRun(domainId: string): AbortController | null {
+  if (isRunActive(domainId)) return null
+  const controller = new AbortController()
+  starting.add(domainId)
+  controllers.set(domainId, controller)
+  return controller
+}
+
+export function releasePreparation(domainId: string, controller: AbortController): void {
+  starting.delete(domainId)
+  if (controllers.get(domainId) === controller && !isRunActive(domainId)) {
+    controllers.delete(domainId)
+    cancellation.delete(domainId)
+  }
+}
+
+export function attachCancellation(
+  domainId: string,
+  controller: AbortController,
+  cancel: () => void,
+): void {
+  if (controllers.get(domainId) === controller) cancellation.set(domainId, cancel)
+}
+
+export function releaseController(domainId: string, controller: AbortController): void {
+  if (controllers.get(domainId) === controller) {
+    controllers.delete(domainId)
+    cancellation.delete(domainId)
+  }
+}
+
+export function cancelActiveRun(domainId: string): boolean {
+  const controller = controllers.get(domainId)
+  if (!controller) return false
+  controller.abort()
+  try {
+    cancellation.get(domainId)?.()
+  } catch {
+    /* cancellation must still succeed */
+  }
+  return true
+}
+
+export function hydrateRun(domainId: string, root: string): void {
+  if (hydrated.has(domainId) || runs.has(domainId)) return
+  hydrated.add(domainId)
+  const last = readLastRun(domainId, root)
+  if (last) runs.set(domainId, last)
+}

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

@@ -0,0 +1,162 @@
+import { randomUUID } from 'node:crypto'
+
+import type {
+  AgentPromptSnapshot,
+  AgentRun,
+  AgentEffort,
+  Comment,
+  StudioEvent,
+  StudioSettings,
+} from '../../../shared/types'
+import type { DomainHandle } from '../../domain'
+import type { Bridge } from '../bridge/grant'
+import type { AgentHarness } from '../harness/adapter'
+
+import { getBundle } from '../../cache'
+import { readComments } from '../../state/comments'
+import { readContext } from '../../state/context'
+import { listDocuments } from '../../state/documents'
+import { refreshAuto } from '../../state/handoff'
+import { startBridge } from '../bridge/grant'
+import { readConversation } from '../conversation'
+import { getHarness, resolveHarnessConfiguration } from '../harness/selection'
+import { buildSystemPrompt } from '../prompts/system'
+import { buildResumePrompt, buildTurnPrompt } from '../prompts/turn'
+import { studioSessionId } from '../telemetry'
+
+export interface SubmitOpts {
+  message?: string
+  resume?: boolean
+}
+
+export interface PreparedRun {
+  domainId: string
+  root: string
+  harness: AgentHarness
+  settings: StudioSettings
+  session: ReturnType<typeof readConversation>
+  resume?: string
+  schemaHash: string
+  model?: string
+  effort?: AgentEffort
+  harnessEnv: Record<string, string>
+  bridge: Bridge
+  run: AgentRun
+  promptSnapshot(sessionId: string | undefined, firstTurn: boolean): AgentPromptSnapshot
+}
+
+export type PreparationResult = { prepared: PreparedRun } | { error: string }
+
+function awaitingThreads(root: string): Comment[] {
+  return readComments(root).comments.filter(
+    (comment) => comment.status === 'open' && comment.thread.at(-1)?.role !== 'author',
+  )
+}
+
+/** Gather and freeze every input required to start one agent run. */
+export async function prepareRun(
+  handle: DomainHandle,
+  notify: (event: StudioEvent) => void,
+  controller: AbortController,
+  options?: SubmitOpts,
+): Promise<PreparationResult> {
+  const domainId = handle.id
+  const root = handle.root
+  const harness = getHarness(root)
+  const available = await harness.isAvailable(controller.signal)
+  if (controller.signal.aborted) return { error: 'agent run canceled during setup' }
+  if (!available) return { error: `${harness.label} is not available on this machine` }
+
+  const session = readConversation(root, harness.id)
+  const resume = session.sessionId
+  const bareResume = options?.resume === true && !!resume
+  const awaiting = awaitingThreads(root)
+  const message = (options?.message ?? '').trim()
+  if (!bareResume && awaiting.length === 0 && !message)
+    return { error: 'nothing to send — type an instruction or open a thread' }
+
+  await refreshAuto(handle).catch(() => {})
+  if (controller.signal.aborted) return { error: 'agent run canceled during setup' }
+  const bundle = await getBundle(domainId)
+  if (controller.signal.aborted) return { error: 'agent run canceled during setup' }
+
+  const schemaHash = bundle?.schemaHash ?? ''
+  const context = readContext(root)
+  const documents = listDocuments(root)
+  const configuration = await resolveHarnessConfiguration(root, harness)
+  if (!configuration.ok) return { error: `model gateway auth failed — ${configuration.error}` }
+  const { settings, model, effort, env } = configuration.configuration
+  if (controller.signal.aborted) return { error: 'agent run canceled during setup' }
+
+  const harnessEnv = { ...env, ASTRALE_SESSION: studioSessionId(domainId) }
+  const bridge = startBridge(handle, notify)
+  const makeTurn = (firstTurn: boolean) =>
+    bareResume && !firstTurn
+      ? buildResumePrompt()
+      : buildTurnPrompt({
+          origin: bundle?.overlay.origin ?? domainId,
+          root,
+          schemaHash,
+          awaitingThreads: awaiting,
+          userContext: context.user,
+          autoContext: context.auto.filter((item) => item.includeInHandoff),
+          documents,
+          firstTurn,
+          message,
+          ir: bundle?.ir ?? null,
+          overlay: bundle?.overlay,
+        })
+  const systemPrompt = buildSystemPrompt({ bridge: bridge.enabled })
+  const promptSnapshot = (
+    sessionId: string | undefined,
+    firstTurn: boolean,
+  ): AgentPromptSnapshot => ({
+    createdAt: new Date().toISOString(),
+    systemPrompt,
+    turnPrompt: makeTurn(firstTurn),
+    firstTurn,
+    resumed: !!sessionId,
+    sessionId,
+    model,
+    effort,
+    access: settings.agentAccess,
+    mcpTools: bridge.mcpServers.flatMap((server) => server.enabledTools ?? []),
+  })
+  const run: AgentRun = {
+    id: randomUUID(),
+    domainId,
+    harness: harness.id,
+    status: 'running',
+    createdAt: new Date().toISOString(),
+    summary: bareResume
+      ? 'continuing after interruption'
+      : message
+        ? message.slice(0, 60) + (message.length > 60 ? '…' : '')
+        : awaiting.length === 1
+          ? '1 open thread'
+          : `${awaiting.length} open threads`,
+    targetCommentIds: awaiting.map((comment) => comment.id),
+    events: [],
+    sessionId: resume,
+    resumed: !!resume,
+    prompt: promptSnapshot(resume, !resume),
+  }
+
+  return {
+    prepared: {
+      domainId,
+      root,
+      harness,
+      settings,
+      session,
+      resume,
+      schemaHash,
+      model,
+      effort,
+      harnessEnv,
+      bridge,
+      run,
+      promptSnapshot,
+    },
+  }
+}