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

package/studio/server/agent/harness/gateway/token.test.ts

@@ -0,0 +1,133 @@
+import { expect, test } from 'bun:test'
+
+import { HarnessTokenBroker, HarnessTokenError } from './token'
+
+function jwt(audience: string, expiresAtMs = Date.now() + 3_600_000): string {
+  const header = Buffer.from(JSON.stringify({ alg: 'none' })).toString('base64url')
+  const payload = Buffer.from(
+    JSON.stringify({ aud: audience, exp: Math.floor(expiresAtMs / 1000) }),
+  ).toString('base64url')
+  return `${header}.${payload}.signature`
+}
+
+test('resolves static and audience-bound host-relayed gateway tokens', async () => {
+  const broker = new HarnessTokenBroker()
+  expect(
+    await broker.acquireGatewayToken(
+      {
+        enabled: true,
+        baseUrl: 'https://gateway.example',
+        auth: { mode: 'token', token: ' x ' },
+      },
+      'https://gateway.example',
+    ),
+  ).toBe('x')
+
+  const audience = 'https://host.example'
+  const token = jwt(audience)
+  expect(broker.setHostToken(audience, token)).toBe(true)
+  expect(broker.setHostToken(audience, jwt('https://other.example'))).toBe(false)
+  expect(
+    await broker.acquireGatewayToken(
+      { enabled: true, baseUrl: audience, auth: { mode: 'host' } },
+      audience,
+    ),
+  ).toBe(token)
+})
+
+test('reports a missing host relay as the concrete typed failure', async () => {
+  expect.assertions(2)
+  const broker = new HarnessTokenBroker()
+  try {
+    await broker.acquireGatewayToken(
+      {
+        enabled: true,
+        baseUrl: 'https://missing.example',
+        auth: { mode: 'host' },
+      },
+      'https://missing.example',
+    )
+  } catch (error) {
+    expect(error).toBeInstanceOf(HarnessTokenError)
+    expect((error as HarnessTokenError).kind).toBe('host-token-needed')
+  }
+})
+
+test('mints with the exact audience and instance, caches, and coalesces concurrent callers', async () => {
+  const calls: { args: string[]; timeoutMs?: number }[] = []
+  const audience = 'https://gateway.example'
+  const token = jwt(audience)
+  const broker = new HarnessTokenBroker({
+    capture: async (_bin, args, _cwd, options) => {
+      calls.push({ args, timeoutMs: options?.timeoutMs })
+      await Promise.resolve()
+      return { code: 0, stdout: `${token}\n`, stderr: '' }
+    },
+  })
+  const config = {
+    enabled: true,
+    baseUrl: audience,
+    auth: { mode: 'mint' as const, instance: 'prod' },
+  }
+
+  expect(
+    await Promise.all([
+      broker.acquireGatewayToken(config, audience),
+      broker.acquireGatewayToken(config, audience),
+    ]),
+  ).toEqual([token, token])
+  expect(await broker.acquireGatewayToken(config, audience)).toBe(token)
+  expect(calls).toEqual([
+    {
+      args: ['token', '--audience', audience, '--ttl', '3600', '--raw', '-i', 'prod'],
+      timeoutMs: 12_000,
+    },
+  ])
+})
+
+test('isolates mint caches by audience and instance', async () => {
+  let calls = 0
+  const broker = new HarnessTokenBroker({
+    capture: async (_bin, args) => {
+      calls++
+      const audience = args[args.indexOf('--audience') + 1]
+      return { code: 0, stdout: jwt(audience), stderr: '' }
+    },
+  })
+
+  for (const [audience, instance] of [
+    ['https://one.example', 'a'],
+    ['https://one.example', 'b'],
+    ['https://two.example', 'a'],
+  ] as const)
+    await broker.acquireGatewayToken(
+      { enabled: true, baseUrl: audience, auth: { mode: 'mint', instance } },
+      audience,
+    )
+
+  expect(calls).toBe(3)
+})
+
+test('turns failed, blank, or wrong-audience mint output into a typed failure', async () => {
+  expect.assertions(6)
+  for (const result of [
+    { code: 7, stdout: '', stderr: 'not signed in' },
+    { code: 0, stdout: ' ', stderr: '' },
+    { code: 0, stdout: jwt('https://other.example'), stderr: '' },
+  ]) {
+    const broker = new HarnessTokenBroker({ capture: async () => result })
+    try {
+      await broker.acquireGatewayToken(
+        {
+          enabled: true,
+          baseUrl: 'https://gateway.example',
+          auth: { mode: 'mint' },
+        },
+        'https://gateway.example',
+      )
+    } catch (error) {
+      expect(error).toBeInstanceOf(HarnessTokenError)
+      expect((error as HarnessTokenError).kind).toBe('mint-failed')
+    }
+  }
+})

package/studio/server/agent/harness/gateway/token.ts

@@ -0,0 +1,166 @@
+/**
+ * Acquire bearer tokens for a harness model gateway.
+ *
+ * - mint: shell out to `astrale token`, cache the short-lived delegation, and
+ *   coalesce concurrent requests for the same audience/instance
+ * - token: use the manually configured bearer
+ * - host: consume a token relayed by the embedding Astrale application
+ *
+ * Tokens only flow into the spawned harness child environment.
+ */
+import type { HarnessGatewayConfig } from '../../../../shared/types'
+
+import { captureCommand, type CapturedCommand, type CaptureOptions } from '../process'
+
+const MINT_TTL_SECONDS = 3600
+const REFRESH_SKEW_MS = 5 * 60_000
+
+interface CachedToken {
+  token: string
+  expiresAtMs: number
+}
+
+type CaptureHarnessCommand = (
+  bin: string,
+  args: string[],
+  cwd: string,
+  options?: CaptureOptions,
+) => Promise<CapturedCommand>
+
+export interface HarnessTokenBrokerOptions {
+  capture?: CaptureHarnessCommand
+  now?: () => number
+}
+
+export class HarnessTokenError extends Error {
+  constructor(
+    message: string,
+    readonly kind: 'mint-failed' | 'host-token-needed' | 'config',
+  ) {
+    super(message)
+    this.name = 'HarnessTokenError'
+  }
+}
+
+function jwtClaims(jwt: string): { audience?: string | string[]; expiresAtMs?: number } | null {
+  try {
+    const payload = Buffer.from(jwt.split('.')[1], 'base64url').toString('utf8')
+    const claims = JSON.parse(payload)
+    return {
+      audience:
+        typeof claims?.aud === 'string' ||
+        (Array.isArray(claims?.aud) &&
+          claims.aud.every((item: unknown) => typeof item === 'string'))
+          ? claims.aud
+          : undefined,
+      expiresAtMs: typeof claims?.exp === 'number' ? claims.exp * 1000 : undefined,
+    }
+  } catch {
+    return null
+  }
+}
+
+function audienceMatches(actual: string | string[] | undefined, expected: string): boolean {
+  return actual === expected || (Array.isArray(actual) && actual.includes(expected))
+}
+
+export class HarnessTokenBroker {
+  private readonly mintCache = new Map<string, CachedToken>()
+  private readonly hostTokens = new Map<string, CachedToken>()
+  private readonly inFlightMints = new Map<string, Promise<string>>()
+  private readonly capture: CaptureHarnessCommand
+  private readonly now: () => number
+
+  constructor(options: HarnessTokenBrokerOptions = {}) {
+    this.capture = options.capture ?? captureCommand
+    this.now = options.now ?? Date.now
+  }
+
+  /** Relay a host-owned delegation token into the embedded Studio process. */
+  setHostToken(audience: string, token: string): boolean {
+    if (!audience || !token || token.split('.').length !== 3) return false
+    const claims = jwtClaims(token)
+    if (!claims || !audienceMatches(claims.audience, audience)) return false
+    const expiresAtMs = claims.expiresAtMs ?? this.now() + MINT_TTL_SECONDS * 1000
+    if (expiresAtMs <= this.now()) return false
+    this.hostTokens.set(audience, { token, expiresAtMs })
+    return true
+  }
+
+  /** Acquire the configured gateway bearer for one child-process invocation. */
+  async acquireGatewayToken(config: HarnessGatewayConfig, audience: string): Promise<string> {
+    switch (config.auth.mode) {
+      case 'token': {
+        const token = config.auth.token.trim()
+        if (!token) throw new HarnessTokenError('no token set for this gateway', 'config')
+        return token
+      }
+      case 'host':
+        return this.readHostToken(audience)
+      default:
+        return this.mintToken(audience, config.auth.instance)
+    }
+  }
+
+  private readHostToken(audience: string): string {
+    const cached = this.hostTokens.get(audience)
+    if (!cached || cached.expiresAtMs <= this.now())
+      throw new HarnessTokenError(
+        'no valid host-supplied token — the embedding Astrale app must provide one',
+        'host-token-needed',
+      )
+    return cached.token
+  }
+
+  private mintToken(audience: string, instance?: string): Promise<string> {
+    const key = `${audience}\u0000${instance ?? ''}`
+    const cached = this.mintCache.get(key)
+    if (cached && cached.expiresAtMs - this.now() > REFRESH_SKEW_MS)
+      return Promise.resolve(cached.token)
+
+    const pending = this.inFlightMints.get(key)
+    if (pending) return pending
+
+    let mint!: Promise<string>
+    mint = this.mintAndCache(key, audience, instance).finally(() => {
+      if (this.inFlightMints.get(key) === mint) this.inFlightMints.delete(key)
+    })
+    this.inFlightMints.set(key, mint)
+    return mint
+  }
+
+  private async mintAndCache(key: string, audience: string, instance?: string): Promise<string> {
+    const args = ['token', '--audience', audience, '--ttl', String(MINT_TTL_SECONDS), '--raw']
+    if (instance) args.push('-i', instance)
+    const result = await this.capture('astrale', args, process.cwd(), { timeoutMs: 12_000 })
+    const token = result.code === 0 ? result.stdout.trim() : ''
+    const claims = token && token.split('.').length === 3 ? jwtClaims(token) : null
+    if (
+      !claims ||
+      !audienceMatches(claims.audience, audience) ||
+      (claims.expiresAtMs !== undefined && claims.expiresAtMs <= this.now())
+    )
+      throw new HarnessTokenError(
+        'could not mint a delegation token — is the instance reachable and are you signed in? (try `astrale login` / `astrale use <instance>`)',
+        'mint-failed',
+      )
+    this.mintCache.set(key, {
+      token,
+      expiresAtMs: claims.expiresAtMs ?? this.now() + MINT_TTL_SECONDS * 1000,
+    })
+    return token
+  }
+}
+
+const defaultBroker = new HarnessTokenBroker()
+
+export function setHostToken(audience: string, token: string): boolean {
+  return defaultBroker.setHostToken(audience, token)
+}
+
+export function acquireGatewayToken(
+  config: HarnessGatewayConfig,
+  audience: string,
+): Promise<string> {
+  return defaultBroker.acquireGatewayToken(config, audience)
+}

package/studio/server/agent/harness/mock/adapter.ts

@@ -0,0 +1,190 @@
+import type { Comment } from '../../../../shared/types'
+import type { AgentHarness, AgentTurnInput, AgentTurnResult, AskInput, AskResult } from '../adapter'
+
+import { readComments } from '../../../state/comments'
+import { applyMockDomainEdit } from './domain-edit'
+
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  if (signal.aborted) return Promise.resolve()
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms)
+    signal.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(timer)
+        resolve()
+      },
+      { once: true },
+    )
+  })
+}
+
+export class MockHarness implements AgentHarness {
+  id = 'mock'
+  label = 'Mock agent (free)'
+  capabilities = {
+    effortLevels: ['low', 'medium', 'high'],
+    accessLevels: ['workspace', 'full'],
+    ask: true,
+    loadout: false,
+    gateway: 'none',
+  } as const
+
+  async isAvailable(): Promise<boolean> {
+    return true
+  }
+
+  async run(input: AgentTurnInput): Promise<AgentTurnResult> {
+    const expectedModel = process.env.DOMAIN_STUDIO_MOCK_EXPECT_MODEL
+    if (expectedModel && input.model !== expectedModel)
+      throw new Error(
+        `mock expected model ${expectedModel}, received ${input.model ?? '(default)'}`,
+      )
+    const mode = process.env.DOMAIN_STUDIO_MOCK_MODE || 'normal'
+    const extraDelay = Number(process.env.DOMAIN_STUDIO_MOCK_DELAY_MS || 0)
+    if ((mode === 'resumefail' || mode === 'resumefailafterevent') && input.sessionId) {
+      input.onEvent({ kind: 'status', text: 'resuming…' })
+      if (mode === 'resumefailafterevent')
+        input.onEvent({
+          kind: 'tool',
+          text: 'Edit',
+          tool: 'Edit',
+          target: 'schema/test.ts',
+        })
+      return {
+        sessionId: input.sessionId,
+        finalText: '',
+        isError: true,
+        errorMessage: 'mock: no conversation found with session id',
+        resumeRejected: true,
+      }
+    }
+    const store = readComments(input.root)
+    const open = store.comments.filter(
+      (comment) => comment.status === 'open' && comment.thread.at(-1)?.role !== 'author',
+    )
+
+    input.onEvent({ kind: 'status', text: 'session started' })
+    await sleep(250, input.signal)
+    if (extraDelay > 0) await sleep(extraDelay, input.signal)
+    if (mode === 'error') throw new Error('mock harness failure (test)')
+    input.onEvent({
+      kind: 'thinking',
+      text: `Reviewing ${open.length} open thread(s) and the current schema.`,
+    })
+    await sleep(300, input.signal)
+    input.onEvent({
+      kind: 'tool',
+      text: 'Read',
+      tool: 'Read',
+      target: '.domain-studio/comments.json',
+    })
+    await sleep(250, input.signal)
+
+    const seed = open[0]?.thread.at(-1)?.text ?? 'note'
+    const edit = input.signal.aborted ? null : applyMockDomainEdit(input.root, seed)
+    if (edit) {
+      input.onEvent({ kind: 'tool', text: 'Edit', tool: 'Edit', target: edit.file })
+      await sleep(300, input.signal)
+    }
+    input.onEvent({
+      kind: 'message',
+      text: edit
+        ? `Added a \`${edit.prop}\` property to \`${edit.file}\` and answered the open threads.`
+        : 'Answered the open threads.',
+    })
+
+    const replyText = edit
+      ? `Done — implemented this by adding \`${edit.prop}\` to \`${edit.file}\`. (mock agent)`
+      : 'Acknowledged. (mock agent)'
+
+    if ((mode === 'liveandblock' || mode === 'liveandblockdifferent') && open[0]) {
+      const bridge = input.mcpServers?.find((server) => server.name === 'domain-studio')
+      if (!bridge?.invoke) throw new Error('mock bridge grant is not invokable')
+      await bridge.invoke('reply_to_thread', {
+        commentId: open[0].id,
+        text: replyText,
+        resolve: true,
+        closeNote: 'mock live reply',
+      })
+    }
+
+    const replied: Comment[] = open.map((comment) => ({
+      ...comment,
+      status: 'closed',
+      thread: [
+        ...comment.thread,
+        {
+          id: crypto.randomUUID(),
+          role: 'author' as const,
+          type: 'text' as const,
+          text: replyText,
+        },
+        ...(mode === 'liveandblockdifferent'
+          ? [
+              {
+                id: crypto.randomUUID(),
+                role: 'author' as const,
+                type: 'text' as const,
+                text: 'Additional final detail. (mock agent)',
+              },
+            ]
+          : []),
+      ],
+    }))
+    const machine = {
+      schemaVersion: store.schemaVersion,
+      comments: replied.map((comment) => ({
+        id: comment.id,
+        anchors: comment.anchors,
+        status: mode === 'openreply' ? 'open' : comment.status,
+        thread: comment.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'
+          : `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,
+    }
+  }
+
+  async ask(input: AskInput): Promise<AskResult> {
+    const expectedModel = process.env.DOMAIN_STUDIO_MOCK_EXPECT_MODEL
+    if (expectedModel && input.model !== expectedModel)
+      return {
+        text: '',
+        isError: true,
+        errorMessage: `mock expected model ${expectedModel}, received ${input.model ?? '(default)'}`,
+      }
+    const expectedSession = process.env.DOMAIN_STUDIO_MOCK_EXPECT_SESSION
+    if (expectedSession && input.sessionId !== expectedSession)
+      return {
+        text: '',
+        isError: true,
+        errorMessage: `mock expected session ${expectedSession}, received ${input.sessionId ?? '(fresh)'}`,
+      }
+    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, the selected harness would answer from the inherited conversation context.',
+    ]
+    let text = ''
+    for (const part of parts) {
+      if (input.signal.aborted) break
+      text += part
+      input.onDelta(part)
+      await sleep(180, input.signal)
+    }
+    return { text, isError: false }
+  }
+}

package/studio/server/agent/harness/mock/domain-edit.ts

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+function identifier(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((word, index) => (index === 0 ? word : word[0].toUpperCase() + word.slice(1)))
+    .join('')
+}
+
+/** Apply the deterministic schema edit used by the local mock harness. */
+export function applyMockDomainEdit(
+  root: string,
+  instruction: string,
+): { file: string; prop: string } | null {
+  const schemaDir = join(root, 'schema')
+  if (!existsSync(schemaDir)) return null
+  const files = readdirSync(schemaDir).filter((file) => file.endsWith('.ts') && file !== 'index.ts')
+  const propName = identifier(instruction, 'agentNote')
+  for (const file of files) {
+    const absolute = join(schemaDir, file)
+    const source = readFileSync(absolute, 'utf8')
+    const props = source.indexOf('props: {')
+    if (props < 0) continue
+    let prop = propName
+    let suffix = 2
+    while (new RegExp(`\\b${prop}\\b\\s*:`).test(source)) prop = `${propName}${suffix++}`
+    const insertAt = props + 'props: {'.length
+    const line = `\n    /** Added by the agent in response to a studio comment. */\n    ${prop}: z.string().optional(),`
+    writeFileSync(absolute, source.slice(0, insertAt) + line + source.slice(insertAt))
+    return { file: `schema/${file}`, prop }
+  }
+  return null
+}

package/studio/server/agent/harness/process.test.ts

@@ -0,0 +1,46 @@
+import { afterEach, expect, test } from 'bun:test'
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { captureCommand } from './process'
+
+const roots: string[] = []
+
+afterEach(() => {
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+function hangingCommand(root: string): string {
+  const file = join(root, 'hang')
+  writeFileSync(file, '#!/usr/bin/env bun\nsetInterval(() => {}, 1000)\n')
+  chmodSync(file, 0o755)
+  return file
+}
+
+test('bounds hanging probes with a timeout', async () => {
+  const root = mkdtempSync(join(tmpdir(), 'studio-harness-process-timeout-'))
+  roots.push(root)
+  const result = await captureCommand(hangingCommand(root), [], root, { timeoutMs: 30 })
+  expect(result).toMatchObject({
+    code: -1,
+    timedOut: true,
+    stderr: 'command timed out after 30ms',
+  })
+})
+
+test('lets setup cancellation abort an in-flight probe', async () => {
+  const root = mkdtempSync(join(tmpdir(), 'studio-harness-process-abort-'))
+  roots.push(root)
+  const controller = new AbortController()
+  const pending = captureCommand(hangingCommand(root), [], root, {
+    signal: controller.signal,
+    timeoutMs: 5_000,
+  })
+  controller.abort()
+  expect(await pending).toMatchObject({
+    code: -1,
+    aborted: true,
+    stderr: 'canceled',
+  })
+})

package/studio/server/agent/harness/process.ts

@@ -0,0 +1,104 @@
+import { spawn } from 'node:child_process'
+
+export interface CapturedCommand {
+  code: number
+  stdout: string
+  stderr: string
+  aborted?: boolean
+  timedOut?: boolean
+}
+
+export interface CaptureOptions {
+  env?: Record<string, string>
+  signal?: AbortSignal
+  timeoutMs?: number
+}
+
+/** Merge overrides into the spawned harness only. */
+export function childEnvironment(extra?: Record<string, string>): NodeJS.ProcessEnv | undefined {
+  return extra && Object.keys(extra).length ? { ...process.env, ...extra } : undefined
+}
+
+/** Capture a short-lived harness command such as version or loadout discovery. */
+export function captureCommand(
+  bin: string,
+  args: string[],
+  cwd: string,
+  options: CaptureOptions = {},
+): Promise<CapturedCommand> {
+  return new Promise((resolve) => {
+    let stdout = ''
+    let stderr = ''
+    let settled = false
+    let timer: ReturnType<typeof setTimeout> | undefined
+    let onAbort = () => {}
+    const finish = (result: CapturedCommand) => {
+      if (settled) return
+      settled = true
+      if (timer) clearTimeout(timer)
+      options.signal?.removeEventListener('abort', onAbort)
+      resolve(result)
+    }
+    if (options.signal?.aborted) {
+      finish({ code: -1, stdout, stderr: 'canceled', aborted: true })
+      return
+    }
+    let child: ReturnType<typeof spawn>
+    try {
+      child = spawn(bin, args, {
+        cwd,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: childEnvironment(options.env),
+        detached: process.platform !== 'win32',
+      })
+    } catch (error) {
+      finish({ code: -1, stdout, stderr: String(error) })
+      return
+    }
+    onAbort = () => {
+      terminateProcessTree(child, 'SIGKILL')
+      finish({ code: -1, stdout, stderr: 'canceled', aborted: true })
+    }
+    options.signal?.addEventListener('abort', onAbort, { once: true })
+    const timeoutMs = options.timeoutMs ?? 15_000
+    if (timeoutMs > 0) {
+      timer = setTimeout(() => {
+        terminateProcessTree(child, 'SIGKILL')
+        finish({
+          code: -1,
+          stdout,
+          stderr: `command timed out after ${timeoutMs}ms`,
+          timedOut: true,
+        })
+      }, timeoutMs)
+      timer.unref?.()
+    }
+    child.stdout?.setEncoding('utf8')
+    child.stderr?.setEncoding('utf8')
+    child.stdout?.on('data', (chunk: string) => {
+      stdout += chunk
+    })
+    child.stderr?.on('data', (chunk: string) => {
+      stderr += chunk
+    })
+    child.on('error', (error) => finish({ code: -1, stdout, stderr: error.message }))
+    child.on('close', (code) => finish({ code: code ?? -1, stdout, stderr }))
+  })
+}
+
+/** Terminate the whole harness process group so child commands cannot leak. */
+export function terminateProcessTree(
+  child: ReturnType<typeof spawn>,
+  signal: NodeJS.Signals = 'SIGTERM',
+): void {
+  try {
+    if (process.platform !== 'win32' && child.pid) process.kill(-child.pid, signal)
+    else child.kill(signal)
+  } catch {
+    try {
+      child.kill(signal)
+    } catch {
+      /* already gone */
+    }
+  }
+}