@astrale-os/cli 1.0.0-beta.0 → 1.0.0-beta.10

package/studio/server/agent/prompts/system.test.ts

@@ -5,8 +5,9 @@ import { buildSystemPrompt } from './system'
 test('embedded agents receive the current SDK layout contract', () => {
   const prompt = buildSystemPrompt({ bridge: false })
 
-  expect(prompt).toContain('implementation.ts')
+  expect(prompt).toContain('modular Actions and Workflows')
   expect(prompt).toContain('pre-Kernel-V2 APIs or layouts')
-  expect(prompt).toContain('domain.ts/runtime only when this is already a legacy project')
+  expect(prompt).toContain('Runtime/Application entries')
+  expect(prompt).toContain('do not restore defineDomain or Interface-era layouts')
   expect(prompt).not.toContain('schema/ runtime/ views/')
 })

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

@@ -28,16 +28,17 @@ export function buildSystemPrompt(options: { bridge: boolean }): string {
     '  and **astrale-cli** when you run the `astrale` CLI. Treat those current skills and',
     '  the project itself as authoritative; do not restore pre-Kernel-V2 APIs or layouts.',
     '- Prefer the project’s existing semantic modules over inventing new structure. Current',
-    '  SDK projects compose schema, handlers, and frontend metadata in implementation.ts;',
-    '  wire new modules explicitly through their layer facades and that entry. Preserve',
-    '  domain.ts/runtime only when this is already a legacy project (no folder magic).',
+    '  SDK projects author Schema definitions, modular Actions and Workflows, a Runtime,',
+    '  and an Application. Wire modules through their semantic SDK facades and explicit',
+    '  Runtime/Application entries; do not restore defineDomain or Interface-era layouts.',
     '- 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',
+    '  already authenticated (`astrale auth`). After deploying, VERIFY:',
+    '  `curl <svc-url>/.well-known/astrale/domain.json` must publish this domain origin, 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',

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

@@ -1,12 +1,20 @@
-import type { Comment, ContextItem, DocMeta, SchemaIR, SchemaOverlay } from '../../../shared/types'
+import type {
+  Comment,
+  ContextItem,
+  DocMeta,
+  SchemaIR,
+  SchemaOverlay,
+  SchemaRevision,
+} from '../../../shared/types'
 
-import { buildCopyMarkdown } from '../../state/copy'
+import { buildCopyMarkdown } from '../../handoff/copy'
 import { resolveThreadAnchors } from './anchors'
 
 export interface TurnParts {
   origin: string
   root: string
-  schemaHash: string
+  renderFingerprint: string
+  schemaRevision?: SchemaRevision
   awaitingThreads: Comment[]
   userContext: ContextItem[]
   autoContext: ContextItem[]
@@ -22,7 +30,8 @@ export function buildTurnPrompt(parts: TurnParts): string {
   const body = buildCopyMarkdown({
     origin: parts.origin,
     root: parts.root,
-    schemaHash: parts.schemaHash,
+    renderFingerprint: parts.renderFingerprint,
+    schemaRevision: parts.schemaRevision,
     openComments: parts.awaitingThreads,
     userContext: parts.userContext,
     autoContext: parts.autoContext,

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

@@ -26,7 +26,7 @@ function fixture() {
   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, 'application.ts'), 'export default {}\n')
   writeFileSync(join(root, 'schema/index.ts'), 'export const Test = {}\n')
   const handle = registerDomain(root)!
   domainIds.push(handle.id)

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

@@ -31,7 +31,7 @@ export async function completeRun(
     settings,
     session,
     resume,
-    schemaHash,
+    renderFingerprint,
     model,
     effort,
     harnessEnv,
@@ -141,7 +141,7 @@ export async function completeRun(
       result.finalText.trim()
     ) {
       try {
-        const merged = mergeReply(root, schemaHash, result.finalText, {
+        const merged = mergeReply(root, renderFingerprint, result.finalText, {
           skipByComment: liveByComment,
         })
         run.merge = merged

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

@@ -58,7 +58,7 @@ function fixture(): DomainHandle {
   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, 'application.ts'), 'export default {}\n')
   writeFileSync(join(root, 'schema/index.ts'), 'export const Test = {}\n')
   const handle = registerDomain(root)!
   domainIds.push(handle.id)

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

@@ -13,10 +13,10 @@ import type { Bridge } from '../bridge/grant'
 import type { AgentHarness } from '../harness/adapter'
 
 import { getBundle } from '../../cache'
+import { refreshAuto } from '../../handoff/service'
 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'
@@ -36,7 +36,7 @@ export interface PreparedRun {
   settings: StudioSettings
   session: ReturnType<typeof readConversation>
   resume?: string
-  schemaHash: string
+  renderFingerprint: string
   model?: string
   effort?: AgentEffort
   harnessEnv: Record<string, string>
@@ -80,7 +80,7 @@ export async function prepareRun(
   const bundle = await getBundle(domainId)
   if (controller.signal.aborted) return { error: 'agent run canceled during setup' }
 
-  const schemaHash = bundle?.schemaHash ?? ''
+  const renderFingerprint = bundle?.renderFingerprint ?? ''
   const context = readContext(root)
   const documents = listDocuments(root)
   const configuration = await resolveHarnessConfiguration(root, harness)
@@ -96,7 +96,8 @@ export async function prepareRun(
       : buildTurnPrompt({
           origin: bundle?.overlay.origin ?? domainId,
           root,
-          schemaHash,
+          renderFingerprint,
+          schemaRevision: bundle?.schemaRevision,
           awaitingThreads: awaiting,
           userContext: context.user,
           autoContext: context.auto.filter((item) => item.includeInHandoff),
@@ -150,7 +151,7 @@ export async function prepareRun(
       settings,
       session,
       resume,
-      schemaHash,
+      renderFingerprint,
       model,
       effort,
       harnessEnv,

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

@@ -5,6 +5,7 @@ import { join } from 'node:path'
 
 import type { AgentRun } from '../../../shared/types'
 
+import { asJsonRecord } from '../../json'
 import { readJson, writeJson } from '../../state/store'
 import { currentRun, hydrateRun } from './live-state'
 import { readLastRun } from './transcript'
@@ -37,7 +38,7 @@ test('reconciles a run orphaned by restart and hydrates its terminal snapshot',
     sessionId: 'thread-1',
     error: expect.stringContaining('studio restarted'),
   })
-  expect(readJson<AgentRun>(root, '.cache/agent/last-run.json', running).status).toBe('interrupted')
+  expect(readJson(root, '.cache/agent/last-run.json', asJsonRecord, {}).status).toBe('interrupted')
 
   hydrateRun(domainId, root)
   expect(currentRun(domainId)).toMatchObject({
@@ -45,3 +46,36 @@ test('reconciles a run orphaned by restart and hydrates its terminal snapshot',
     sessionId: 'thread-1',
   })
 })
+
+test('admits future run fields but rejects malformed persisted run structure', () => {
+  const root = mkdtempSync(join(tmpdir(), 'studio-agent-transcript-boundary-'))
+  roots.push(root)
+  const domainId = `domain-${crypto.randomUUID()}`
+  writeJson(root, '.cache/agent/last-run.json', {
+    id: crypto.randomUUID(),
+    domainId,
+    harness: 'codex',
+    status: 'succeeded',
+    createdAt: '2026-08-20T00:00:00.000Z',
+    summary: 'finished work',
+    targetCommentIds: [],
+    events: [],
+    futureRunField: { version: 2 },
+  })
+  expect(readLastRun(domainId, root)).toMatchObject({
+    status: 'succeeded',
+    summary: 'finished work',
+  })
+
+  writeJson(root, '.cache/agent/last-run.json', {
+    id: crypto.randomUUID(),
+    domainId,
+    harness: 'codex',
+    status: 42,
+    createdAt: '2026-08-20T00:00:00.000Z',
+    summary: 'corrupt',
+    targetCommentIds: [],
+    events: [],
+  })
+  expect(readLastRun(domainId, root)).toBeNull()
+})

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

@@ -1,10 +1,176 @@
-import type { AgentRun } from '../../../shared/types'
-
+import {
+  AGENT_ACCESS_LEVELS,
+  AGENT_EFFORT_LEVELS,
+  type AgentEvent,
+  type AgentPromptSnapshot,
+  type AgentRun,
+  type MergeResult,
+} from '../../../shared/types'
+import { asBoolean, asFiniteNumber, asJsonRecord, asString, asStringArray } from '../../json'
 import { readJson, writeJson } from '../../state/store'
 
 const LAST_RUN_FILE = '.cache/agent/last-run.json'
 const runFile = (id: string) => `.cache/agent/runs/${id}.json`
 
+const RUN_STATUSES = new Set<AgentRun['status']>([
+  'queued',
+  'running',
+  'succeeded',
+  'failed',
+  'canceled',
+  'interrupted',
+])
+const EVENT_KINDS = new Set<AgentEvent['kind']>([
+  'status',
+  'thinking',
+  'message',
+  'tool',
+  'reply',
+  'error',
+])
+
+function decodeAgentEvent(value: unknown): AgentEvent | undefined {
+  const record = asJsonRecord(value)
+  const id = asString(record?.id)
+  const ts = asString(record?.ts)
+  const kind = asString(record?.kind)
+  const text = asString(record?.text)
+  if (!id || !ts || !kind || !EVENT_KINDS.has(kind as AgentEvent['kind']) || text === undefined)
+    return undefined
+  const tool = asString(record?.tool)
+  const target = asString(record?.target)
+  const commentId = asString(record?.commentId)
+  return {
+    id,
+    ts,
+    kind: kind as AgentEvent['kind'],
+    text,
+    ...(tool === undefined ? {} : { tool }),
+    ...(target === undefined ? {} : { target }),
+    ...(commentId === undefined ? {} : { commentId }),
+  }
+}
+
+function decodeMergeResult(value: unknown): MergeResult | undefined {
+  const record = asJsonRecord(value)
+  const merged = asFiniteNumber(record?.merged)
+  const closed = asFiniteNumber(record?.closed)
+  const unknownIds = asStringArray(record?.unknownIds)
+  const schemaMismatch = asBoolean(record?.schemaMismatch)
+  if (
+    merged === undefined ||
+    !Number.isInteger(merged) ||
+    closed === undefined ||
+    !Number.isInteger(closed) ||
+    !unknownIds ||
+    schemaMismatch === undefined
+  ) {
+    return undefined
+  }
+  const pastedSchemaVersion = asString(record?.pastedSchemaVersion)
+  return {
+    merged,
+    closed,
+    unknownIds,
+    schemaMismatch,
+    ...(pastedSchemaVersion === undefined ? {} : { pastedSchemaVersion }),
+  }
+}
+
+function decodePrompt(value: unknown): AgentPromptSnapshot | undefined {
+  const record = asJsonRecord(value)
+  const createdAt = asString(record?.createdAt)
+  const systemPrompt = asString(record?.systemPrompt)
+  const turnPrompt = asString(record?.turnPrompt)
+  const firstTurn = asBoolean(record?.firstTurn)
+  const resumed = asBoolean(record?.resumed)
+  const mcpTools = asStringArray(record?.mcpTools)
+  if (
+    !createdAt ||
+    systemPrompt === undefined ||
+    turnPrompt === undefined ||
+    firstTurn === undefined ||
+    resumed === undefined ||
+    !mcpTools
+  ) {
+    return undefined
+  }
+  const sessionId = asString(record?.sessionId)
+  const model = asString(record?.model)
+  const effort = AGENT_EFFORT_LEVELS.find((candidate) => candidate === record?.effort)
+  const access = AGENT_ACCESS_LEVELS.find((candidate) => candidate === record?.access)
+  return {
+    createdAt,
+    systemPrompt,
+    turnPrompt,
+    firstTurn,
+    resumed,
+    mcpTools,
+    ...(sessionId === undefined ? {} : { sessionId }),
+    ...(model === undefined ? {} : { model }),
+    ...(effort === undefined ? {} : { effort }),
+    ...(access === undefined ? {} : { access }),
+  }
+}
+
+function decodeAgentRun(value: unknown): AgentRun | undefined {
+  const record = asJsonRecord(value)
+  const id = asString(record?.id)
+  const domainId = asString(record?.domainId)
+  const harness = asString(record?.harness)
+  const status = asString(record?.status)
+  const createdAt = asString(record?.createdAt)
+  const summary = asString(record?.summary)
+  const targetCommentIds = asStringArray(record?.targetCommentIds)
+  if (
+    !id ||
+    !domainId ||
+    !harness ||
+    !status ||
+    !RUN_STATUSES.has(status as AgentRun['status']) ||
+    !createdAt ||
+    summary === undefined ||
+    !targetCommentIds ||
+    !Array.isArray(record?.events)
+  ) {
+    return undefined
+  }
+  const events = record.events.flatMap((event) => {
+    const decoded = decodeAgentEvent(event)
+    return decoded ? [decoded] : []
+  })
+  const finishedAt = asString(record.finishedAt)
+  const sessionId = asString(record.sessionId)
+  const resumed = asBoolean(record.resumed)
+  const costUsd = asFiniteNumber(record.costUsd)
+  const numTurns = asFiniteNumber(record.numTurns)
+  const tokens = asFiniteNumber(record.tokens)
+  const error = asString(record.error)
+  const liveReplies = asFiniteNumber(record.liveReplies)
+  const merge = decodeMergeResult(record.merge)
+  const prompt = decodePrompt(record.prompt)
+  return {
+    id,
+    domainId,
+    harness,
+    status: status as AgentRun['status'],
+    createdAt,
+    summary,
+    targetCommentIds,
+    events,
+    ...(finishedAt === undefined ? {} : { finishedAt }),
+    ...(sessionId === undefined ? {} : { sessionId }),
+    ...(resumed === undefined ? {} : { resumed }),
+    ...(costUsd === undefined ? {} : { costUsd }),
+    ...(numTurns === undefined ? {} : { numTurns }),
+    ...(tokens === undefined ? {} : { tokens }),
+    ...(error === undefined ? {} : { error }),
+    ...(liveReplies === undefined ? {} : { liveReplies }),
+    ...(merge === undefined ? {} : { merge }),
+    ...(prompt === undefined ? {} : { prompt }),
+  }
+}
+
 /** Persist the latest run pointer and, when terminal, its transcript. */
 export function persistRun(root: string, run: AgentRun, transcript = false): void {
   try {
@@ -17,7 +183,7 @@ export function persistRun(root: string, run: AgentRun, transcript = false): voi
 
 /** Rehydrate the latest run and reconcile one orphaned by a Studio restart. */
 export function readLastRun(domainId: string, root: string): AgentRun | null {
-  const last = readJson<AgentRun | null>(root, LAST_RUN_FILE, null)
+  const last = readJson(root, LAST_RUN_FILE, decodeAgentRun, null)
   if (!last || last.domainId !== domainId) return null
   if (last.status === 'running' || last.status === 'queued') {
     last.status = 'interrupted'

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

@@ -5,6 +5,7 @@ import { join } from 'node:path'
 
 import type { AgentRun } from '../../../shared/types'
 
+import { writeJson } from '../../state/store'
 import { readUsage, recordRun } from './usage'
 
 const roots: string[] = []
@@ -44,3 +45,26 @@ test('records only reported usage and accumulates domain totals', () => {
     lastCostUsd: 0.1,
   })
 })
+
+test('normalizes malformed usage fields while accepting future fields', () => {
+  const root = mkdtempSync(join(tmpdir(), 'studio-agent-usage-boundary-'))
+  roots.push(root)
+  writeJson(root, 'usage.json', {
+    runs: -2,
+    tokens: 'many',
+    costUsd: -1,
+    lastRunAt: 42,
+    lastTokens: -10,
+    futureUsageField: { version: 2 },
+  })
+
+  expect(readUsage(root)).toEqual({ runs: 0, tokens: 0, costUsd: 0 })
+
+  writeJson(root, 'usage.json', {
+    runs: 3,
+    tokens: 120,
+    costUsd: 1.25,
+    futureUsageField: { version: 2 },
+  })
+  expect(readUsage(root)).toEqual({ runs: 3, tokens: 120, costUsd: 1.25 })
+})

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

@@ -6,14 +6,39 @@
  */
 import type { AgentRun, DomainUsage } from '../../../shared/types'
 
+import { asFiniteNumber, asJsonRecord, asString } from '../../json'
 import { readJson, writeJson } from '../../state/store'
 
 const PATH = 'usage.json'
 
 const EMPTY: DomainUsage = { runs: 0, tokens: 0, costUsd: 0 }
 
+function nonNegative(value: unknown): number | undefined {
+  const number = asFiniteNumber(value)
+  return number !== undefined && number >= 0 ? number : undefined
+}
+
+function decodeUsage(value: unknown): DomainUsage | undefined {
+  const record = asJsonRecord(value)
+  if (!record) return undefined
+  const runs = nonNegative(record.runs)
+  const tokens = nonNegative(record.tokens)
+  const costUsd = nonNegative(record.costUsd)
+  const lastRunAt = asString(record.lastRunAt)
+  const lastTokens = nonNegative(record.lastTokens)
+  const lastCostUsd = nonNegative(record.lastCostUsd)
+  return {
+    runs: runs !== undefined && Number.isInteger(runs) ? runs : EMPTY.runs,
+    tokens: tokens ?? EMPTY.tokens,
+    costUsd: costUsd ?? EMPTY.costUsd,
+    ...(lastRunAt === undefined ? {} : { lastRunAt }),
+    ...(lastTokens === undefined ? {} : { lastTokens }),
+    ...(lastCostUsd === undefined ? {} : { lastCostUsd }),
+  }
+}
+
 export function readUsage(root: string): DomainUsage {
-  return { ...EMPTY, ...readJson<Partial<DomainUsage>>(root, PATH, {}) }
+  return readJson(root, PATH, decodeUsage, { ...EMPTY })
 }
 
 /** Fold a finished run into the running total. A run with no reported usage (e.g. it

package/studio/server/api/canvas.ts

@@ -0,0 +1,43 @@
+/** Persisted canvas layout and visibility preference routes. */
+import { getBundle } from '../cache'
+import { readLayout, resetLayout, saveLayout, setNodePositions } from '../state/layout'
+import { readVisibility, resetVisibility, saveVisibility } from '../state/visibility'
+import { badRequest, json, type DomainRouteContext } from './http'
+
+export async function handleCanvasRoute(context: DomainRouteContext): Promise<Response | null> {
+  const { req, rest, body, handle } = context
+  const id = handle.id
+  const root = handle.root
+
+  if (rest === '/layout') {
+    const bundle = await getBundle(id)
+    if (req.method === 'GET') return json(readLayout(root))
+    if (body.action === 'set') {
+      return json(setNodePositions(root, body.positions ?? {}, bundle?.renderFingerprint))
+    }
+    if (body.action === 'save') {
+      return json(saveLayout(root, body.positions ?? {}, bundle?.renderFingerprint))
+    }
+    if (body.action === 'reset') {
+      resetLayout(root)
+      return json({ ok: true })
+    }
+    return badRequest('unknown layout action')
+  }
+
+  if (rest === '/visibility') {
+    if (req.method === 'GET') return json(readVisibility(root))
+    if (body.action === 'set') {
+      return json(
+        saveVisibility(root, {
+          hidden: body.hidden ?? {},
+          showInheritedEdges: body.showInheritedEdges ?? true,
+        }),
+      )
+    }
+    if (body.action === 'reset') return json(resetVisibility(root))
+    return badRequest('unknown visibility action')
+  }
+
+  return null
+}

package/studio/server/api/comments.ts

@@ -0,0 +1,85 @@
+/** Schema-anchored review comment routes and agent reply merge. */
+import { getBundle } from '../cache'
+import { schemaRefs } from '../introspect/schema-refs'
+import {
+  addThreadEntry,
+  deleteComment,
+  editThreadEntry,
+  markOrphans,
+  mergeReply,
+  readComments,
+  setStatus,
+  upsertComment,
+} from '../state/comments'
+import { badRequest, json, notFound, type DomainRouteContext } from './http'
+
+export async function handleCommentRoute(context: DomainRouteContext): Promise<Response | null> {
+  const { req, rest, body, handle, notify } = context
+  const id = handle.id
+  const root = handle.root
+
+  if (rest === '/comments') {
+    if (req.method === 'GET') {
+      const bundle = await getBundle(id)
+      const valid = new Set<string>(bundle ? schemaRefs(bundle) : [])
+      for (const key of Object.keys(bundle?.overlay.sourceSpans ?? {})) valid.add(key)
+      const store = readComments(root)
+      for (const comment of store.comments) {
+        for (const anchor of comment.anchorRefs) {
+          if (anchor.kind !== 'schema') valid.add(anchor.ref)
+        }
+      }
+      return json(markOrphans(root, [...valid]))
+    }
+    if (body.action === 'create') {
+      const bundle = await getBundle(id)
+      const comment = upsertComment(root, {
+        anchors: body.anchors ?? [],
+        anchorRefs: body.anchorRefs ?? [],
+        text: body.text,
+        firstRole: body.firstRole,
+        type: body.type,
+        options: body.options,
+        schemaVersion: bundle?.renderFingerprint,
+      })
+      notify({ type: 'comments', domainId: id })
+      return json(comment)
+    }
+    if (body.action === 'reply') {
+      const comment = addThreadEntry(root, body.id, body.entry)
+      notify({ type: 'comments', domainId: id })
+      return comment ? json(comment) : notFound()
+    }
+    if (body.action === 'edit') {
+      const comment = editThreadEntry(root, body.id, body.entryId, String(body.text ?? ''))
+      notify({ type: 'comments', domainId: id })
+      return comment ? json(comment) : notFound()
+    }
+    if (body.action === 'status') {
+      const comment = setStatus(root, body.id, body.status, body.closeNote)
+      notify({ type: 'comments', domainId: id })
+      return comment ? json(comment) : notFound()
+    }
+    if (body.action === 'delete') {
+      const ok = deleteComment(root, body.id)
+      notify({ type: 'comments', domainId: id })
+      return json({ ok })
+    }
+    return badRequest('unknown comments action')
+  }
+
+  if (rest === '/comments/merge' && req.method === 'POST') {
+    const bundle = await getBundle(id)
+    try {
+      const result = mergeReply(root, bundle?.renderFingerprint ?? '', String(body.text ?? ''), {
+        dedupeAuthorText: true,
+      })
+      notify({ type: 'comments', domainId: id })
+      return json(result)
+    } catch (error: any) {
+      return badRequest(String(error?.message ?? error))
+    }
+  }
+
+  return null
+}

package/studio/server/api/context.ts

@@ -0,0 +1,61 @@
+/** Authored/automatic agent context and copy-handoff routes. */
+import { getBundle } from '../cache'
+import { buildCopyMarkdown } from '../handoff/copy'
+import { refreshAuto } from '../handoff/service'
+import { readComments } from '../state/comments'
+import {
+  addUserContext,
+  deleteContext,
+  readContext,
+  setAutoInclude,
+  updateContext,
+} from '../state/context'
+import { listDocuments } from '../state/documents'
+import { badRequest, json, notFound, type DomainRouteContext } from './http'
+
+export async function handleContextRoute(context: DomainRouteContext): Promise<Response | null> {
+  const { req, rest, body, handle, notify } = context
+  const id = handle.id
+  const root = handle.root
+
+  if (rest === '/context') {
+    if (req.method === 'GET') return json(readContext(root))
+    if (body.action === 'add') {
+      const item = addUserContext(root, body)
+      notify({ type: 'comments', domainId: id })
+      return json(item)
+    }
+    if (body.action === 'update') {
+      const item = updateContext(root, body.id, body)
+      return item ? json(item) : notFound()
+    }
+    if (body.action === 'delete') return json({ ok: deleteContext(root, body.id) })
+    if (body.action === 'include') {
+      const item = setAutoInclude(root, body.id, body.include)
+      return item ? json(item) : notFound()
+    }
+    return badRequest('unknown context action')
+  }
+
+  if (rest === '/copy-payload' && req.method === 'POST') {
+    await refreshAuto(handle)
+    const bundle = await getBundle(id)
+    const storedContext = readContext(root)
+    const openComments = readComments(root).comments.filter((comment) => comment.status === 'open')
+    const markdown = buildCopyMarkdown({
+      origin: bundle?.overlay.origin ?? id,
+      root,
+      renderFingerprint: bundle?.renderFingerprint ?? '',
+      schemaRevision: bundle?.schemaRevision,
+      openComments,
+      userContext: storedContext.user,
+      autoContext: body.includeAuto
+        ? storedContext.auto.filter((item) => item.includeInHandoff)
+        : [],
+      documents: listDocuments(root),
+    })
+    return json({ markdown, openComments: openComments.length })
+  }
+
+  return null
+}