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

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

@@ -0,0 +1,148 @@
+import type { StudioEvent } from '../../../shared/types'
+import type { DomainHandle } from '../../domain'
+
+import { addThreadEntry, readComments, setStatus, upsertComment } from '../../state/comments'
+import { emitStudioEvent } from '../notify'
+
+interface RunBridge {
+  domainId: string
+  root: string
+  notify: (event: StudioEvent) => void
+  onReply: (commentId: string, text: string) => void
+  onProgress: (text: string) => void
+}
+
+export interface BridgeSession {
+  token: string
+  onReply(callback: (commentId: string, text: string) => void): void
+  onProgress(callback: (text: string) => void): void
+  invoke(sub: string, body: Record<string, unknown>): Promise<Response>
+  dispose(): void
+}
+
+const bridges = new Map<string, RunBridge>()
+
+function ok(data: unknown): Response {
+  return new Response(JSON.stringify(data), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  })
+}
+
+function error(message: string, status = 400): Response {
+  return new Response(JSON.stringify({ error: message }), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  })
+}
+
+/** Open the authenticated write-back session owned by one agent run. */
+export function openBridgeSession(
+  handle: DomainHandle,
+  token: string,
+  notify: (event: StudioEvent) => void,
+): BridgeSession {
+  const bridge: RunBridge = {
+    domainId: handle.id,
+    root: handle.root,
+    notify,
+    onReply: () => {},
+    onProgress: () => {},
+  }
+  bridges.set(token, bridge)
+  return {
+    token,
+    onReply: (callback) => {
+      bridge.onReply = callback
+    },
+    onProgress: (callback) => {
+      bridge.onProgress = callback
+    },
+    invoke: (sub, body) => applyBridgeCall(handle, sub, { ...body, token }),
+    dispose: () => {
+      bridges.delete(token)
+    },
+  }
+}
+
+/** Handle one token-guarded bridge route. */
+export function handleBridge(
+  handle: DomainHandle,
+  sub: string,
+  _req: Request,
+  body: any,
+): Promise<Response> {
+  return applyBridgeCall(handle, sub, body)
+}
+
+async function applyBridgeCall(handle: DomainHandle, sub: string, body: any): Promise<Response> {
+  const token = String(body?.token ?? '')
+  const bridge = bridges.get(token)
+  if (!bridge || bridge.domainId !== handle.id) return error('invalid or expired bridge token', 401)
+  const root = bridge.root
+
+  switch (sub) {
+    case 'threads': {
+      const open = readComments(root).comments.filter(
+        (comment) => comment.status === 'open' && comment.thread.at(-1)?.role !== 'author',
+      )
+      return ok({
+        threads: open.map((comment) => ({
+          id: comment.id,
+          kind: comment.kind,
+          anchor: comment.anchorRefs?.[0]?.ref ?? null,
+          file: comment.anchorRefs?.[0]?.file ?? null,
+          latest: comment.thread.at(-1)?.text ?? '',
+        })),
+      })
+    }
+    case 'reply': {
+      const commentId = String(body.commentId ?? '')
+      const text = String(body.text ?? '').trim()
+      if (!commentId || !text) return error('commentId and text are required')
+      const comment = addThreadEntry(root, commentId, {
+        role: 'author',
+        type: body.options ? 'choice' : 'text',
+        text,
+        options: body.options,
+        answer: body.answer,
+      })
+      if (!comment) return error('unknown commentId', 404)
+      if (body.resolve) setStatus(root, commentId, 'closed', body.closeNote)
+      bridge.onReply(commentId, text)
+      emitStudioEvent(bridge.notify, { type: 'comments', domainId: handle.id })
+      return ok({ ok: true, resolved: !!body.resolve })
+    }
+    case 'resolve': {
+      const commentId = String(body.commentId ?? '')
+      if (!commentId) return error('commentId is required')
+      const comment = setStatus(root, commentId, 'closed', body.closeNote)
+      if (!comment) return error('unknown commentId', 404)
+      bridge.onReply(commentId, body.closeNote ? `resolved: ${body.closeNote}` : 'resolved')
+      emitStudioEvent(bridge.notify, { type: 'comments', domainId: handle.id })
+      return ok({ ok: true })
+    }
+    case 'progress': {
+      const text = String(body.text ?? '').trim()
+      if (text) bridge.onProgress(text)
+      return ok({ ok: true })
+    }
+    case 'raise_question': {
+      const ref = String(body.ref ?? '')
+      const text = String(body.text ?? '').trim()
+      if (!ref || !text) return error('ref and text are required')
+      const comment = upsertComment(root, {
+        anchors: [body.label ?? ref],
+        anchorRefs: [{ ref, kind: (body.kind ?? 'schema') as any, file: body.file }],
+        text,
+        firstRole: 'author',
+        type: body.options ? 'choice' : 'text',
+        options: body.options,
+      })
+      emitStudioEvent(bridge.notify, { type: 'comments', domainId: handle.id })
+      return ok({ ok: true, id: comment.id })
+    }
+    default:
+      return error('unknown bridge route', 404)
+  }
+}

package/studio/server/agent/{bridge-mcp.ts → bridge/stdio.ts}

@@ -1,15 +1,31 @@
 #!/usr/bin/env bun
 /**
- * bridge-mcp.ts — a minimal stdio MCP server the harness spawns (via the
- * generated --mcp-config). It exposes the Domain Studio write-back tools and
+ * bridge/stdio.ts — the stdio MCP server spawned by local harnesses. It exposes
+ * the Domain Studio write-back tools from the generated MCP configuration and
  * forwards each call to the token-guarded HTTP bridge (api → agent/bridge/*),
  * so an agent can reply to comment threads and post progress AS IT WORKS.
  *
  * Transport: newline-delimited JSON-RPC 2.0 on stdin/stdout. Nothing but
  * protocol messages may touch stdout; diagnostics go to stderr.
  */
-const BASE = process.env.DOMAIN_STUDIO_BRIDGE_URL || ''
-const TOKEN = process.env.DOMAIN_STUDIO_BRIDGE_TOKEN || ''
+import { readFileSync } from 'node:fs'
+
+import { forwardBridgeTool } from './client'
+
+function configFromArgv(): { base?: string; token?: string } {
+  const i = process.argv.indexOf('--config')
+  const path = i >= 0 ? process.argv[i + 1] : undefined
+  if (!path) return {}
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as { base?: string; token?: string }
+  } catch {
+    return {}
+  }
+}
+
+const config = configFromArgv()
+const BASE = config.base || process.env.DOMAIN_STUDIO_BRIDGE_URL || ''
+const TOKEN = config.token || process.env.DOMAIN_STUDIO_BRIDGE_TOKEN || ''
 
 const TOOLS = [
   {
@@ -106,21 +122,6 @@ function replyError(id: unknown, code: number, message: string): void {
   send({ jsonrpc: '2.0', id, error: { code, message } })
 }
 
-async function callBridge(route: string, args: Record<string, unknown>): Promise<string> {
-  if (!BASE || !TOKEN) return 'bridge not configured'
-  try {
-    const res = await fetch(`${BASE}/${route}`, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ token: TOKEN, ...args }),
-    })
-    const text = await res.text()
-    return res.ok ? text || 'ok' : `error ${res.status}: ${text}`
-  } catch (e: any) {
-    return `bridge call failed: ${e?.message ?? e}`
-  }
-}
-
 async function handle(req: any): Promise<void> {
   const { id, method, params } = req
   switch (method) {
@@ -152,8 +153,13 @@ async function handle(req: any): Promise<void> {
         replyError(id, -32602, `unknown tool: ${params?.name}`)
         return
       }
-      const out = await callBridge(tool.route, (params?.arguments ?? {}) as Record<string, unknown>)
-      reply(id, { content: [{ type: 'text', text: out }] })
+      const result = await forwardBridgeTool(
+        BASE,
+        TOKEN,
+        tool.route,
+        (params?.arguments ?? {}) as Record<string, unknown>,
+      )
+      reply(id, result)
       return
     }
     default:

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

@@ -0,0 +1,84 @@
+import { afterEach, describe, expect, test } from 'bun:test'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { readJson, writeJson } from '../state/store'
+import {
+  clearConversation,
+  readConversation,
+  saveConversation,
+  setConversationSession,
+} from './conversation'
+
+const roots: string[] = []
+const root = () => {
+  const value = mkdtempSync(join(tmpdir(), 'studio-conversation-'))
+  roots.push(value)
+  return value
+}
+
+afterEach(() => {
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+describe('per-harness conversations', () => {
+  test('preserves independent Claude and Codex sessions', () => {
+    const dir = root()
+    saveConversation(dir, 'claude', {
+      sessionId: 'claude-session',
+      turns: 2,
+      updatedAt: 'now',
+    })
+    saveConversation(dir, 'codex', {
+      sessionId: 'codex-thread',
+      turns: 3,
+      updatedAt: 'later',
+    })
+
+    expect(readConversation(dir, 'claude')).toMatchObject({
+      sessionId: 'claude-session',
+      turns: 2,
+    })
+    expect(readConversation(dir, 'codex')).toMatchObject({
+      sessionId: 'codex-thread',
+      turns: 3,
+    })
+    clearConversation(dir, 'codex')
+    expect(readConversation(dir, 'claude').sessionId).toBe('claude-session')
+    expect(readConversation(dir, 'codex').sessionId).toBeUndefined()
+  })
+
+  test('migrates the legacy single-session shape on first write', () => {
+    const dir = root()
+    writeJson(dir, '.cache/agent/session.json', {
+      harness: 'claude',
+      sessionId: 'legacy-session',
+      turns: 4,
+      updatedAt: 'then',
+    })
+    expect(readConversation(dir, 'claude').turns).toBe(4)
+
+    setConversationSession(dir, 'codex', 'codex-thread')
+    const stored = readJson<any>(dir, '.cache/agent/session.json', {})
+    expect(stored.version).toBe(1)
+    expect(stored.conversations.claude.sessionId).toBe('legacy-session')
+    expect(stored.conversations.codex.sessionId).toBe('codex-thread')
+  })
+
+  test('fails closed without rewriting a future conversation-store version', () => {
+    const dir = root()
+    const future = {
+      version: 2,
+      conversations: {
+        codex: { sessionId: 'future-thread', turns: 9 },
+      },
+    }
+    writeJson(dir, '.cache/agent/session.json', future)
+
+    expect(() => setConversationSession(dir, 'claude', 'new-session')).toThrow(
+      'unsupported agent conversation store version: 2',
+    )
+    expect(readJson<any>(dir, '.cache/agent/session.json', {})).toEqual(future)
+  })
+})

package/studio/server/agent/conversation.ts

@@ -0,0 +1,110 @@
+import type { AgentSessionInfo, ConversationInfo } from '../../shared/types'
+
+import { readJson, removeState, writeJson } from '../state/store'
+
+const SESSION_FILE = '.cache/agent/session.json'
+
+interface HarnessConversation {
+  sessionId?: string
+  turns?: number
+  updatedAt?: string
+}
+
+interface ConversationStore {
+  version: 1
+  conversations: Record<string, HarnessConversation>
+}
+
+interface LegacySessionState extends HarnessConversation {
+  harness?: string
+}
+
+function readStore(root: string): ConversationStore {
+  const raw = readJson<ConversationStore | LegacySessionState | null>(root, SESSION_FILE, null)
+  if (!raw) return { version: 1, conversations: {} }
+  if ('conversations' in raw) {
+    if (raw.version !== 1)
+      throw new Error(`unsupported agent conversation store version: ${String(raw.version)}`)
+    if (raw.conversations) return { version: 1, conversations: { ...raw.conversations } }
+  }
+  if ('harness' in raw && raw.harness && raw.sessionId) {
+    return {
+      version: 1,
+      conversations: {
+        [raw.harness]: {
+          sessionId: raw.sessionId,
+          turns: raw.turns ?? 0,
+          updatedAt: raw.updatedAt,
+        },
+      },
+    }
+  }
+  return { version: 1, conversations: {} }
+}
+
+function writeStore(root: string, store: ConversationStore): void {
+  const entries = Object.entries(store.conversations).filter(([, c]) => !!c.sessionId)
+  if (entries.length === 0) {
+    removeState(root, SESSION_FILE)
+    return
+  }
+  writeJson(root, SESSION_FILE, {
+    version: 1,
+    conversations: Object.fromEntries(entries),
+  } satisfies ConversationStore)
+}
+
+export function readConversation(root: string, harness: string): HarnessConversation {
+  return readStore(root).conversations[harness] ?? {}
+}
+
+export function conversationInfo(root: string, harness: string): ConversationInfo {
+  const conversation = readConversation(root, harness)
+  return {
+    active: !!conversation.sessionId,
+    turns: conversation.turns ?? 0,
+    harness: conversation.sessionId ? harness : undefined,
+  }
+}
+
+export function sessionInfo(root: string, harness: string): AgentSessionInfo {
+  const conversation = readConversation(root, harness)
+  return {
+    sessionId: conversation.sessionId ?? null,
+    turns: conversation.turns ?? 0,
+    harness: conversation.sessionId ? harness : undefined,
+  }
+}
+
+export function saveConversation(
+  root: string,
+  harness: string,
+  conversation: Required<Pick<HarnessConversation, 'sessionId' | 'turns'>> &
+    Pick<HarnessConversation, 'updatedAt'>,
+): void {
+  const store = readStore(root)
+  store.conversations[harness] = conversation
+  writeStore(root, store)
+}
+
+export function setConversationSession(root: string, harness: string, sessionId: string): void {
+  const trimmed = sessionId.trim()
+  if (!trimmed) {
+    clearConversation(root, harness)
+    return
+  }
+  const store = readStore(root)
+  const previous = store.conversations[harness] ?? {}
+  store.conversations[harness] = {
+    sessionId: trimmed,
+    turns: previous.turns ?? 0,
+    updatedAt: new Date().toISOString(),
+  }
+  writeStore(root, store)
+}
+
+export function clearConversation(root: string, harness: string): void {
+  const store = readStore(root)
+  delete store.conversations[harness]
+  writeStore(root, store)
+}

package/studio/server/agent/{types.ts → harness/adapter.ts}

@@ -1,5 +1,6 @@
 /**
- * agent/types.ts — the harness-agnostic contract for "run one agent turn".
+ * harness/adapter.ts — the executable boundary implemented by each local agent
+ * harness.
  *
  * A *harness* is whatever local AI agent does the edits (Claude Code, Codex, …).
  * The studio never talks to a model API directly; it shells out to the harness
@@ -7,7 +8,13 @@
  * harness maps its native streaming output onto `AgentStreamEvent`s and returns
  * a final text blob (which carries the machine-state reply block).
  */
-import type { AgentEffort, AgentEventKind, HarnessLoadout } from '../../shared/types'
+import type {
+  AgentAccess,
+  AgentEffort,
+  AgentEventKind,
+  HarnessCapabilities,
+  HarnessLoadout,
+} from '../../../shared/types'
 
 /** A single normalized activity event emitted while the harness runs. */
 export interface AgentStreamEvent {
@@ -17,6 +24,21 @@ export interface AgentStreamEvent {
   target?: string
 }
 
+/** Harness-neutral description of one stdio MCP server. Each harness is
+ * responsible for expressing this in its native CLI/config shape. */
+export interface HarnessMcpServer {
+  name: string
+  command: string
+  args?: string[]
+  env?: Record<string, string>
+  required?: boolean
+  /** Studio's run-scoped write-back tools are user-authorized by the submit. */
+  approvalMode?: 'auto' | 'prompt' | 'writes' | 'approve'
+  enabledTools?: string[]
+  /** In-process harnesses may invoke the same grant without spawning stdio. */
+  invoke?: (tool: string, args: Record<string, unknown>) => Promise<unknown>
+}
+
 export interface AgentTurnInput {
   /** the domain repo root — the agent's working directory */
   root: string
@@ -26,13 +48,16 @@ export interface AgentTurnInput {
   appendSystemPrompt?: string
   /** prior harness session id → resume the same conversation */
   sessionId?: string
+  /** explicit model override; absent preserves the harness's native config/default */
+  model?: string
   /** harness reasoning effort for this turn */
   effort?: AgentEffort
-  /** path to a generated MCP config exposing the studio write-back bridge */
-  mcpConfigPath?: string
-  /** extra env merged into the harness CHILD process only (e.g. ANTHROPIC_BASE_URL
-   *  / ANTHROPIC_AUTH_TOKEN to route through a custom model gateway). Never touches
-   *  the studio's own env or the user's shell / global `claude`. */
+  /** authority granted to the local harness */
+  access?: AgentAccess
+  /** generated MCP servers exposing Studio write-back */
+  mcpServers?: HarnessMcpServer[]
+  /** extra env merged into the harness CHILD process only. Never touches the
+   *  studio's own env or the user's shell/global harness process. */
   env?: Record<string, string>
   /** abort the turn (user pressed Cancel) */
   signal: AbortSignal
@@ -47,7 +72,7 @@ export interface AgentTurnResult {
   finalText: string
   costUsd?: number
   numTurns?: number
-  /** total tokens processed (input + output + cache) */
+  /** total token usage reported by the harness */
   tokens?: number
   isError: boolean
   errorMessage?: string
@@ -68,9 +93,13 @@ export interface AskInput {
   appendSystemPrompt?: string
   /** the domain's live conversation session id to FORK from (undefined ⇒ fresh, no fork) */
   sessionId?: string
+  /** explicit model override; absent preserves the harness's native config/default */
+  model?: string
   /** harness reasoning effort for this side question */
   effort?: AgentEffort
-  /** extra env merged into the harness child only (custom model gateway) — see AgentTurnInput.env */
+  /** authority granted to the local harness */
+  access?: AgentAccess
+  /** extra env merged into the harness child only — see AgentTurnInput.env */
   env?: Record<string, string>
   signal: AbortSignal
   /** called with each chunk of the answer as it streams in */
@@ -93,16 +122,26 @@ export interface HarnessHealth {
   detail?: string
 }
 
+export interface HarnessLoadoutOptions {
+  /** Child-only environment overrides used while probing the harness. */
+  env?: Record<string, string>
+  /** Studio's per-domain override for the selected harness. */
+  model?: string
+  /** Bypass the adapter's short-lived probe cache for an explicit user re-probe. */
+  refresh?: boolean
+}
+
 export interface AgentHarness {
   /** stable id, e.g. 'claude' | 'mock' | 'codex' */
   id: string
   /** human label for the UI */
   label: string
+  capabilities: HarnessCapabilities
   /** is the underlying CLI/binary actually invokable here? */
-  isAvailable(): Promise<boolean>
+  isAvailable(signal?: AbortSignal): Promise<boolean>
   /** optional: a richer install probe for the UI (version + reason). Harnesses that
    *  omit it fall back to isAvailable(). */
-  health?(): Promise<HarnessHealth>
+  health?(signal?: AbortSignal): Promise<HarnessHealth>
   run(input: AgentTurnInput): Promise<AgentTurnResult>
   /** optional: answer a quick forked side question (Ask). Harnesses without a
    *  fork concept simply omit this; the studio falls back gracefully. */
@@ -111,10 +150,22 @@ export interface AgentHarness {
    *  tools, agents) — a read-only window into the agent for the Settings page.
    *  Harnesses without an introspectable loadout omit it. `env` (e.g. a custom
    *  model gateway) is merged into the probe child so the reported model reflects it. */
-  loadout?(root: string, env?: Record<string, string>): Promise<HarnessLoadout>
+  loadout?(root: string, options?: HarnessLoadoutOptions): Promise<HarnessLoadout>
   /** optional: the raw SKILL.md for a skill command, so the UI can show it. */
   skillContent?(
     root: string,
     command: string,
   ): Promise<{ command: string; content: string; path: string } | null>
 }
+
+/** Normalize optional rich health probes into one route-facing result. */
+export async function inspectHarnessHealth(
+  harness: AgentHarness,
+  signal?: AbortSignal,
+): Promise<HarnessHealth> {
+  if (harness.health) return harness.health(signal)
+  return {
+    ok: await harness.isAvailable(signal),
+    bin: harness.id,
+  }
+}