@astrale-os/cli 0.4.0-alpha.13

package/studio/server/agent/mock.ts

@@ -0,0 +1,186 @@
+/**
+ * agent/mock.ts — a free, deterministic stand-in for a real harness. It exists
+ * so the whole live loop (submit → stream events → edit → re-render → reply →
+ * merge) can be exercised end-to-end without spending real agent credits.
+ *
+ * It behaves like a minimal real agent: reads the open threads, makes ONE real
+ * edit to the domain schema (so the studio's watch→re-render fires), narrates a
+ * few activity events, then returns a final message carrying the same
+ * machine-state ```json``` reply block a real agent would emit (so the runner's
+ * existing mergeReply path is exercised identically). It writes domain source
+ * directly — it is standing in for the external agent actor, not the studio.
+ */
+import { readFileSync, writeFileSync, readdirSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { Comment } from '../../shared/types'
+import type { AgentHarness, AgentTurnInput, AgentTurnResult, AskInput, AskResult } from './types'
+
+import { readComments } from '../state/comments'
+
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const t = setTimeout(resolve, ms)
+    signal.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(t)
+        resolve()
+      },
+      { once: true },
+    )
+  })
+}
+
+/** A camelCase identifier derived from free text, for a synthesized prop name. */
+function identFromText(text: string, fallback: string): string {
+  const words = text
+    .toLowerCase()
+    .replace(/[^a-z0-9 ]+/g, ' ')
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+    .slice(0, 3)
+  if (words.length === 0) return fallback
+  return words.map((w, i) => (i === 0 ? w : w[0].toUpperCase() + w.slice(1))).join('')
+}
+
+/** Insert a new optional prop into the first `props: {` block of the first
+ *  non-index schema file. Returns the edited file (relative) + prop name. */
+function applyMockEdit(root: string, propName: string): { file: string; prop: string } | null {
+  const schemaDir = join(root, 'schema')
+  if (!existsSync(schemaDir)) return null
+  const files = readdirSync(schemaDir).filter((f) => f.endsWith('.ts') && f !== 'index.ts')
+  for (const f of files) {
+    const abs = join(schemaDir, f)
+    const src = readFileSync(abs, 'utf8')
+    const idx = src.indexOf('props: {')
+    if (idx < 0) continue
+    let prop = propName
+    let n = 2
+    while (new RegExp(`\\b${prop}\\b\\s*:`).test(src)) prop = `${propName}${n++}`
+    const insertAt = idx + 'props: {'.length
+    const line = `\n    /** Added by the agent in response to a studio comment. */\n    ${prop}: z.string().optional(),`
+    const next = src.slice(0, insertAt) + line + src.slice(insertAt)
+    writeFileSync(abs, next)
+    return { file: `schema/${f}`, prop }
+  }
+  return null
+}
+
+export class MockHarness implements AgentHarness {
+  id = 'mock'
+  label = 'Mock agent (free)'
+
+  async isAvailable(): Promise<boolean> {
+    return true
+  }
+
+  async run(input: AgentTurnInput): Promise<AgentTurnResult> {
+    const { root, signal, onEvent } = input
+    // test knobs (env): MODE=error|noblock|openreply|badblock|resumefail, DELAY_MS=extra latency for cancel/concurrency tests
+    const mode = process.env.DOMAIN_STUDIO_MOCK_MODE || 'normal'
+    const extraDelay = Number(process.env.DOMAIN_STUDIO_MOCK_DELAY_MS || 0)
+    // 'resumefail' rejects a RESUME (only when a sessionId is passed) so the runner's
+    // auto-restart-fresh path can be exercised; the fresh retry (no sessionId) proceeds.
+    if (mode === 'resumefail' && input.sessionId) {
+      onEvent({ kind: 'status', text: 'resuming…' })
+      return {
+        sessionId: input.sessionId,
+        finalText: '',
+        isError: true,
+        errorMessage: 'mock: no conversation found with session id',
+        resumeRejected: true,
+      }
+    }
+    const store = readComments(root)
+    const open = store.comments.filter(
+      (c) => c.status === 'open' && c.thread.at(-1)?.role !== 'author',
+    )
+
+    onEvent({ kind: 'status', text: 'session started' })
+    await sleep(250, signal)
+    if (extraDelay > 0) await sleep(extraDelay, signal)
+    if (mode === 'error') throw new Error('mock harness failure (test)')
+    onEvent({
+      kind: 'thinking',
+      text: `Reviewing ${open.length} open thread(s) and the current schema.`,
+    })
+    await sleep(300, signal)
+    onEvent({ kind: 'tool', text: 'Read', tool: 'Read', target: '.domain-studio/comments.json' })
+    await sleep(250, signal)
+
+    // one real edit so the studio re-renders
+    const seed = open[0]?.thread.at(-1)?.text ?? 'note'
+    const editRes = signal.aborted ? null : applyMockEdit(root, identFromText(seed, 'agentNote'))
+    if (editRes) {
+      onEvent({ kind: 'tool', text: 'Edit', tool: 'Edit', target: editRes.file })
+      await sleep(300, signal)
+    }
+    onEvent({
+      kind: 'message',
+      text: editRes
+        ? `Added a \`${editRes.prop}\` property to \`${editRes.file}\` and answered the open threads.`
+        : 'Answered the open threads.',
+    })
+
+    // final machine-state block (identical shape to a real agent reply)
+    const replied: Comment[] = open.map((c) => ({
+      ...c,
+      status: 'closed',
+      thread: [
+        ...c.thread,
+        {
+          id: crypto.randomUUID(),
+          role: 'author' as const,
+          type: 'text' as const,
+          text: editRes
+            ? `Done — implemented this by adding \`${editRes.prop}\` to \`${editRes.file}\`. (mock agent)`
+            : 'Acknowledged. (mock agent)',
+        },
+      ],
+    }))
+    const machine = {
+      schemaVersion: store.schemaVersion,
+      // 'openreply' leaves threads OPEN with an author entry (clarifying-question loop test)
+      comments: replied.map((c) => ({
+        id: c.id,
+        anchors: c.anchors,
+        status: mode === 'openreply' ? 'open' : c.status,
+        thread: c.thread,
+      })),
+    }
+    const finalText =
+      mode === 'noblock'
+        ? 'I reviewed the open threads and made the edit. (no machine-state block — resilience test)'
+        : mode === 'badblock'
+          ? 'I made the edit.\n\n```json\n{ this is : not valid json, ]\n```\n' // malformed-block resilience test
+          : `I reviewed the open threads and made the edit.\n\n\`\`\`json\n${JSON.stringify(machine, null, 2)}\n\`\`\`\n`
+
+    return {
+      sessionId: input.sessionId ?? 'mock-session',
+      finalText,
+      costUsd: 0,
+      numTurns: 1,
+      isError: false,
+    }
+  }
+
+  /** Fake streamed answer for a side-question (free plumbing test of the Ask loop). */
+  async ask(input: AskInput): Promise<AskResult> {
+    const forked = input.sessionId ? `(forked from ${input.sessionId.slice(0, 8)}…) ` : '(fresh) '
+    const parts = [
+      forked,
+      'This is a mock answer to your side question. ',
+      'In a real run, Haiku would answer here from the inherited conversation context.',
+    ]
+    let text = ''
+    for (const p of parts) {
+      if (input.signal.aborted) break
+      text += p
+      input.onDelta(p)
+      await sleep(180, input.signal)
+    }
+    return { text, isError: false }
+  }
+}

package/studio/server/agent/prompt.ts

@@ -0,0 +1,202 @@
+/**
+ * agent/prompt.ts — the scaffolding that tells a harness-agnostic agent who it
+ * is and exactly how to answer. Two pieces:
+ *   - the SYSTEM prompt (appended to the harness default) = the durable protocol.
+ *   - the TURN prompt = the handoff data (context + changes + the threads
+ *     awaiting a reply + the machine-state block). Reuses buildCopyMarkdown so
+ *     the live loop and the copy/paste flow stay byte-for-byte consistent.
+ */
+import type { Comment, ContextItem, DocMeta, SchemaIR, SchemaOverlay } from '../../shared/types'
+
+import { buildCopyMarkdown } from '../state/copy'
+import { describeAnchor, resolveThreadAnchors } from './schema-map'
+
+/** The reply protocol — appended to the harness's own system prompt. */
+export function buildSystemPrompt(opts: { bridge: boolean }): string {
+  const lines: string[] = [
+    'You are the build agent for an Astrale domain, driven from **Domain Studio** — a local',
+    'GUI where the user pins comment threads onto schema classes, methods, views, data, etc.',
+    'Each thread is a conversation. Your working directory IS the domain repo root.',
+    '',
+    'FIRST, read each open thread and judge what it actually wants — editing code is ONE possible',
+    'response, not the default. Match the intent:',
+    '- A REQUEST to change something ("add a status enum", "rename X", "implement reservations")',
+    '  → make the smallest correct change in code, then reply with what you did.',
+    '- A QUESTION or open discussion ("what could we add here?", "should we split this?",',
+    '  "is X better than Y?", "thoughts?", "why is …?") → DO NOT touch code. Reply with your',
+    '  analysis. When there are a few concrete directions, offer them as OPTIONS (below) so the',
+    '  user can choose, then WAIT for their answer before implementing anything.',
+    '- AMBIGUOUS, or several reasonable approaches → ask before acting: reply with options rather',
+    '  than guessing and editing. Answering now and implementing on a later turn is always fine.',
+    'A comment that asks a question wants a conversation, not a commit. When in doubt, reply first.',
+    '',
+    'OFFERING OPTIONS (multiple-choice): when a decision is the user’s to make, give a short menu',
+    'instead of a wall of prose. Pass an `options` array (2–5 short, concrete choices) to',
+    'reply_to_thread (to answer their thread) or raise_question (to open a new one). The user picks',
+    'one or types their own; you see their choice next turn. Keep the surrounding text to one framing line.',
+    '',
+    'Operating rules (when a thread genuinely calls for a code change):',
+    '- Read the skills under `.agents/skills/` FIRST and follow them: **astrale-domain**',
+    '  (schema modeling, handlers, views, deploy/install) before editing schema/handlers,',
+    '  and **astrale-cli** when you run the `astrale` CLI. Honor their conventions (edges',
+    '  snake_case, compiled key accessors, `::update` drops `z.enum()`, ports/adapters for',
+    '  external APIs, idempotent postInstall, colon MethodPaths in postInstall).',
+    '- Prefer editing existing',
+    '  schema/ runtime/ views/ files over inventing new structure; wire new modules',
+    '  EXPLICITLY in domain.ts / schema/index.ts (no folder magic).',
+    '- The studio re-renders automatically as you save files — never start, build, or refresh',
+    '  anything for the UI to update.',
+    '- Sanity-check schema/handler edits with `pnpm typecheck` (or `tsgo --noEmit`).',
+    '- You ARE allowed to run the shell. When a thread asks you to **deploy or install**, do',
+    '  it yourself: `pnpm prod` (managed deploy + install) or the `astrale` CLI. The user is',
+    '  already authenticated (`astrale auth`). After deploying, VERIFY: `curl <svc-url>/meta`',
+    '  must name this domain, and a live smoke call (create a node, call a method) should work',
+    '  — report the URL and what you verified. Long-running commands are fine.',
+    '- SINGLE HEADLESS TURN — you are not a resident session: there is NO background loop and NO',
+    '  wake-on-completion. A shell started with run_in_background (or any “notify me when it',
+    '  finishes” task) is KILLED a few seconds after this turn ends, and you will NOT be re-invoked',
+    '  when it completes. So whenever you must WAIT — a deploy to finish, a service to come up, a',
+    '  long build, or polling an endpoint until it is ready — do it SYNCHRONOUSLY in the FOREGROUND',
+    '  in THIS turn: block on the command, or run a foreground `until …; do sleep N; done` loop',
+    '  (with a sane overall timeout), then act on the result. Never background a wait-and-react task',
+    '  and end your turn expecting to be woken — you won’t be.',
+    '- Do NOT hand-edit anything under .domain-studio/ (that is the studio’s own state).',
+    '',
+    'RAISE DX ISSUES — Astrale runs an in-graph issue tracker (the primary feedback channel). If',
+    'working in this domain costs YOU friction — a confusing or missing Astrale API/error, stale',
+    'docs or skills, or a bug that forced a workaround — FILE a DX issue as part of the task, per',
+    'the **astrale-cli** skill’s “Reporting DX Issues” section: dedup against open issues first, then',
+    '`astrale call /:admin.astrale.ai:class.Issue:report kind=<bug|friction|feature> title=… body=…`.',
+    'It is best-effort and non-blocking — never let filing one derail the user’s task — and mention',
+    'the returned id in your reply when you file one.',
+    '',
+    'REPLY PROTOCOL — this is how the user sees your answers (they are NOT watching your terminal):',
+    '- For EVERY open thread, append exactly one concise {role:"author"} reply: what you changed,',
+    '  your answer (with `options` when it is a decision), or a clarifying question.',
+    '- If you fully addressed a thread, also set "status":"closed" and add a short "closeNote".',
+    '- You MUST end your final message with a fenced ```json``` machine-state block of the SAME',
+    '  shape you were given: { "schemaVersion", "comments":[ { "id", "anchors", "status",',
+    '  "thread":[ ...every existing entry PLUS your new author entries... ] } ] }. Merge is by id;',
+    '  a thread whose last entry is not yours is resent next turn, so always answer every thread.',
+  ]
+  if (opts.bridge) {
+    lines.push(
+      '',
+      'PREFERRED CHANNEL — the **domain-studio** MCP tools are connected. Use them as your',
+      'PRIMARY way to reply, so the user sees answers appear live in the threads:',
+      '  • list_open_threads — see what to address (ids + anchors).',
+      '  • reply_to_thread { commentId, text, resolve?, closeNote?, options? } — answer one thread.',
+      '    Pass `options` (2–5 short strings) to offer a multiple-choice decision. Set resolve=true',
+      '    ONLY when fully handled — never resolve a question you just asked; wait for the answer.',
+      '  • raise_question { ref, text, options? } — open a NEW question thread, optionally with choices.',
+      '  • resolve_thread / post_progress — close or narrate.',
+      'When you reply through these tools you do NOT need the final json block — it is only a',
+      'fallback for if a tool call fails. Still answer EVERY open thread one way or the other.',
+    )
+  }
+  lines.push(
+    '',
+    'WRITING / VOICE — your reader is usually a BUSINESS user, not an engineer. Write the way',
+    'you would brief a smart colleague who does not code:',
+    '- Lead with the outcome in plain language — what now works, what it means for them — not',
+    '  the mechanism. Keep sentences short and concrete; one idea per sentence.',
+    '- Default to business framing over technical detail. Skip jargon,',
+    '  file paths and code unless they are the point. If a technical term is unavoidable, gloss it',
+    '  in a few plain words.',
+    '- Only go technical when the user does first — match their level. Even then, stay crisp:',
+    '  precise and direct, never vague, hand-wavy or padded. No filler, no hedging, no buzzwords.',
+    'Keep prose short. The substance goes in the thread replies and the code.',
+  )
+  return lines.join('\n')
+}
+
+export interface TurnParts {
+  origin: string
+  root: string
+  schemaHash: string
+  /** only the threads awaiting an author reply (open, last entry not author) */
+  awaitingThreads: Comment[]
+  userContext: ContextItem[]
+  autoContext: ContextItem[]
+  documents: DocMeta[]
+  firstTurn: boolean
+  /** optional free-text instruction the user typed in the Context composer */
+  message?: string
+  /** current schema IR (null when deps aren't installed → static fallback) */
+  ir: SchemaIR | null
+  overlay?: SchemaOverlay
+}
+
+/** The per-turn message piped to the harness. */
+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.'
+  // Inject only precise thread-anchor pointers. The schema overview is not embedded;
+  // the system prompt tells the agent to read/edit schema/ directly when needed.
+  const anchors = resolveThreadAnchors(parts.awaitingThreads, parts.overlay)
+  const msg = parts.message?.trim()
+  const instruction = msg ? ['', '## Direct instruction', '', msg] : []
+  return [header, ...instruction, '', anchors, '', body].filter((s) => s !== undefined).join('\n')
+}
+
+/** A bare "pick up where you left off" nudge for resuming an interrupted turn.
+ *  Deliberately empty of handoff data: the resumed session already holds the
+ *  threads, context and prior edits, so re-sending them would be pure noise — the
+ *  point of Resume is a seamless continue, not a fresh briefing. */
+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')
+}
+
+/** The system prompt for a quick Ask side-question — capable, concise, ephemeral. */
+export function buildAskSystemPrompt(): string {
+  return [
+    'You are answering a QUICK side question from inside Domain Studio about ONE element',
+    'of an Astrale domain. This is an ephemeral aside, shown in a small popover and then',
+    'discarded — it is NOT part of the main build conversation.',
+    '- Answer directly and concisely (usually 1–4 sentences). Lead with the answer.',
+    '- You have the same local tool surface and permission mode as the main agent. You may',
+    '  inspect files, run commands, use web/search tools if available, and edit files when',
+    '  the user explicitly asks for a change. Keep any edits tightly scoped and say what changed.',
+    '- No preamble, no machine-state/JSON block, no thread protocol — just the answer.',
+  ].join('\n')
+}
+
+export interface AskParts {
+  anchorRef: string
+  excerpt: string
+  question: string
+  ir: SchemaIR | null
+  overlay?: SchemaOverlay
+}
+
+/** Compose the Ask turn: a friendly prefix + the injected target context + the question. */
+export function buildAskPrompt(parts: AskParts): string {
+  const target = describeAnchor(parts.anchorRef, parts.ir, parts.overlay)
+  const named = parts.excerpt && parts.excerpt !== parts.anchorRef ? ` (${parts.excerpt})` : ''
+  const lines = [`Quick question about \`${parts.anchorRef}\`${named} in this domain.`]
+  if (target) lines.push('', 'Target:', target)
+  lines.push('', `Question: ${parts.question.trim()}`)
+  return lines.join('\n')
+}

package/studio/server/agent/registry.ts

@@ -0,0 +1,29 @@
+import type { AgentHarness } from './types'
+
+/**
+ * agent/registry.ts — picks the active harness. Default is Claude Code; set
+ * DOMAIN_STUDIO_HARNESS=mock for the free deterministic stand-in (tests/dev),
+ * or =claude explicitly. New harnesses (codex, …) register here.
+ */
+import { ClaudeCodeHarness } from './claude'
+import { MockHarness } from './mock'
+
+const harnesses: Record<string, () => AgentHarness> = {
+  claude: () => new ClaudeCodeHarness(),
+  mock: () => new MockHarness(),
+}
+
+let active: AgentHarness | null = null
+
+export function getHarness(): AgentHarness {
+  if (active) return active
+  const want = (process.env.DOMAIN_STUDIO_HARNESS || 'claude').toLowerCase()
+  const make = harnesses[want] ?? harnesses.claude
+  active = make()
+  return active
+}
+
+/** All registered harnesses (id + label) — for the (currently locked) UI selector. */
+export function listHarnesses(): { id: string; label: string }[] {
+  return Object.entries(harnesses).map(([id, make]) => ({ id, label: make().label }))
+}