window.api.acp — ACP Agent Runtime API Reference

import { useEffect, useState } from 'react'
import type { AcpStateSnapshot, AcpRuntimeEvent } from '../../../../shared/acp'

async function startAgentSession(projectName: string) {
  // 1. Connect the agent subprocess
  await window.api.acp.connect()

  // 2. Subscribe to state changes before creating a session
  const unsubState = window.api.acp.onState((snapshot: AcpStateSnapshot) => {
    console.log('Connection status:', snapshot.status)
    console.log('Prompt in flight:', snapshot.promptInFlight)
  })

  // 3. Subscribe to individual events for live transcript updates
  const unsubEvents = window.api.acp.onEvent((event: AcpRuntimeEvent) => {
    if (event.kind === 'message') {
      console.log('Agent message:', event.text)
    }
    if (event.kind === 'artifact') {
      console.log('Artifact produced:', event.artifacts)
    }
    if (event.kind === 'stop') {
      console.log('Turn complete')
    }
  })

  // 4. Subscribe to permission requests
  const unsubPermissions = window.api.acp.onPermissionRequest((request) => {
    // Present request.options to the user, then:
    window.api.acp.respondToPermission({
      requestId: request.requestId,
      optionId: request.options[0].optionId
    })
  })

  // 5. Create a session scoped to the project
  const { sessionId } = await window.api.acp.createSession({ projectName })

  // 6. Send a prompt
  await window.api.acp.sendPrompt({
    sessionId,
    text: 'Analyse the dataset and produce a summary plot.'
  })

  // 7. Cleanup
  return () => {
    unsubState()
    unsubEvents()
    unsubPermissions()
  }
}