@autumn-dev/autumn-bus 0.1.0-next.2

package/src/client.ts

@@ -0,0 +1,255 @@
+import { BusError } from './errors.js'
+import type { BusErrorCode } from './errors.js'
+import type {
+  Agent,
+  AgentLifecycle,
+  AskHumanInput,
+  BusHealth,
+  BusMessage,
+  BusTask,
+  CreateScopeInput,
+  CreateScopeResult,
+  DeliveryReceipt,
+  HumanEscalation,
+  InboxReservation,
+  RegisterAgentInput,
+  RegisterAgentResult,
+  SendMessageInput
+} from './protocol.js'
+
+interface Success<T> {
+  ok: true
+  result: T
+}
+
+interface Failure {
+  ok: false
+  error: { code: BusErrorCode; message: string; details?: Record<string, unknown> }
+}
+
+export interface OperationOptions {
+  signal?: AbortSignal
+  timeoutMs?: number
+}
+
+async function request<T>(
+  address: string,
+  token: string | undefined,
+  method: string,
+  path: string,
+  value?: unknown,
+  options: OperationOptions = {}
+): Promise<T> {
+  const timeoutMs = options.timeoutMs ?? 30_000
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new BusError('INVALID_ARGUMENT', 'timeoutMs must be a positive finite number')
+  }
+  const controller = new AbortController()
+  const onAbort = () => controller.abort(options.signal?.reason ?? new Error('Operation aborted'))
+  if (options.signal?.aborted) onAbort()
+  else options.signal?.addEventListener('abort', onAbort, { once: true })
+  const timeout = setTimeout(
+    () => controller.abort(new Error(`Autumn Bus request timed out after ${timeoutMs}ms`)),
+    timeoutMs
+  )
+  let response: Response
+  let text: string
+  try {
+    response = await fetch(`${address}${path}`, {
+      method,
+      headers: {
+        accept: 'application/json',
+        ...(value === undefined ? {} : { 'content-type': 'application/json' }),
+        ...(token === undefined ? {} : { authorization: `Bearer ${token}` })
+      },
+      ...(value === undefined ? {} : { body: JSON.stringify(value) }),
+      signal: controller.signal
+    })
+    text = await response.text()
+  } catch (error) {
+    const cause = controller.signal.aborted ? controller.signal.reason : error
+    const message = cause instanceof Error ? cause.message : 'Network request failed'
+    throw new BusError('INTERNAL', `Autumn Bus request failed: ${message}`)
+  } finally {
+    clearTimeout(timeout)
+    options.signal?.removeEventListener('abort', onAbort)
+  }
+  let payload: Success<T> | Failure | T
+  try {
+    payload = JSON.parse(text) as Success<T> | Failure | T
+  } catch {
+    throw new BusError('INTERNAL', `Autumn Bus returned a non-JSON response with HTTP ${response.status}`)
+  }
+  if (response.ok) {
+    if (payload && typeof payload === 'object' && 'ok' in payload && payload.ok === true)
+      return (payload as Success<T>).result
+    return payload as T
+  }
+  if (
+    payload &&
+    typeof payload === 'object' &&
+    'ok' in payload &&
+    payload.ok === false &&
+    'error' in payload &&
+    payload.error &&
+    typeof payload.error === 'object' &&
+    'code' in payload.error &&
+    'message' in payload.error
+  ) {
+    const failure = payload as Failure
+    throw new BusError(failure.error.code, failure.error.message, failure.error.details)
+  }
+  throw new BusError('INTERNAL', `Autumn Bus request failed with HTTP ${response.status}`)
+}
+
+export class AutumnBusAdminClient {
+  constructor(
+    readonly address: string,
+    private readonly adminToken: string
+  ) {}
+
+  health(options?: OperationOptions): Promise<BusHealth> {
+    return request(this.address, undefined, 'GET', '/health', undefined, options)
+  }
+
+  createScope(input: CreateScopeInput = {}, options?: OperationOptions): Promise<CreateScopeResult> {
+    return request(this.address, this.adminToken, 'POST', '/v1/scopes', input, options)
+  }
+
+  async shutdown(options?: OperationOptions): Promise<void> {
+    await request(this.address, this.adminToken, 'POST', '/v1/admin/shutdown', {}, options)
+  }
+}
+
+export class AutumnBusScopeClient {
+  constructor(
+    readonly address: string,
+    readonly scopeToken: string
+  ) {}
+
+  registerAgent(input: RegisterAgentInput, options?: OperationOptions): Promise<RegisterAgentResult> {
+    return request(this.address, this.scopeToken, 'POST', '/v1/agents', input, options)
+  }
+
+  listAgents(options?: OperationOptions): Promise<Agent[]> {
+    return request(this.address, this.scopeToken, 'GET', '/v1/agents', undefined, options)
+  }
+
+  async linkAgents(left: string, right: string, options?: OperationOptions): Promise<void> {
+    await request(this.address, this.scopeToken, 'POST', '/v1/links', { left, right }, options)
+  }
+
+  listEscalations(options?: OperationOptions): Promise<HumanEscalation[]> {
+    return request(this.address, this.scopeToken, 'GET', '/v1/scope/escalations', undefined, options)
+  }
+
+  resolveEscalation(id: string, answer: string, options?: OperationOptions): Promise<HumanEscalation> {
+    return request(this.address, this.scopeToken, 'POST', `/v1/scope/escalations/${encodeURIComponent(id)}/resolve`, {
+      answer
+    }, options)
+  }
+}
+
+export class AutumnBusClient {
+  constructor(
+    readonly address: string,
+    readonly agentToken: string
+  ) {}
+
+  heartbeat(lifecycle: AgentLifecycle, ready = true, leaseMs?: number, options?: OperationOptions): Promise<Agent> {
+    return request(this.address, this.agentToken, 'PATCH', '/v1/me/heartbeat', {
+      lifecycle,
+      ready,
+      ...(leaseMs === undefined ? {} : { leaseMs })
+    }, options)
+  }
+
+  listPeers(options?: OperationOptions): Promise<Agent[]> {
+    return request(this.address, this.agentToken, 'GET', '/v1/peers', undefined, options)
+  }
+
+  sendMessage(input: SendMessageInput, options?: OperationOptions): Promise<DeliveryReceipt> {
+    return request(this.address, this.agentToken, 'POST', '/v1/messages', input, options)
+  }
+
+  receipt(messageId: string, options?: OperationOptions): Promise<DeliveryReceipt> {
+    return request(this.address, this.agentToken, 'GET', `/v1/messages/${encodeURIComponent(messageId)}`, undefined, options)
+  }
+
+  reserveInbox(limit = 50, options?: OperationOptions): Promise<InboxReservation | null> {
+    return request(this.address, this.agentToken, 'POST', '/v1/inbox/reserve', { limit }, options)
+  }
+
+  commitInbox(reservationId: string, options?: OperationOptions): Promise<BusMessage[]> {
+    return request(
+      this.address,
+      this.agentToken,
+      'POST',
+      `/v1/inbox/${encodeURIComponent(reservationId)}/commit`,
+      {},
+      options
+    )
+  }
+
+  async releaseInbox(reservationId: string, options?: OperationOptions): Promise<void> {
+    await request(
+      this.address,
+      this.agentToken,
+      'POST',
+      `/v1/inbox/${encodeURIComponent(reservationId)}/release`,
+      {},
+      options
+    )
+  }
+
+  async pullInbox(limit = 50, options?: OperationOptions): Promise<BusMessage[]> {
+    const reservation = await this.reserveInbox(limit, options)
+    return reservation ? this.commitInbox(reservation.id, options) : []
+  }
+
+  async acknowledgeMessages(messageIds: string[], options?: OperationOptions): Promise<number> {
+    const result = await request<{ acknowledged: number }>(
+      this.address,
+      this.agentToken,
+      'POST',
+      '/v1/messages/ack',
+      { messageIds },
+      options
+    )
+    return result.acknowledged
+  }
+
+  addTask(description: string, dependencies: string[] = [], options?: OperationOptions): Promise<BusTask> {
+    return request(this.address, this.agentToken, 'POST', '/v1/tasks', { description, dependencies }, options)
+  }
+
+  listTasks(options?: OperationOptions): Promise<BusTask[]> {
+    return request(this.address, this.agentToken, 'GET', '/v1/tasks', undefined, options)
+  }
+
+  claimTask(taskId: string, options?: OperationOptions): Promise<BusTask> {
+    return request(this.address, this.agentToken, 'POST', `/v1/tasks/${encodeURIComponent(taskId)}/claim`, {}, options)
+  }
+
+  releaseTask(taskId: string, options?: OperationOptions): Promise<BusTask> {
+    return request(this.address, this.agentToken, 'POST', `/v1/tasks/${encodeURIComponent(taskId)}/release`, {}, options)
+  }
+
+  completeTask(taskId: string, note?: string, options?: OperationOptions): Promise<BusTask> {
+    return request(this.address, this.agentToken, 'POST', `/v1/tasks/${encodeURIComponent(taskId)}/complete`, {
+      ...(note === undefined ? {} : { note })
+    }, options)
+  }
+
+  askHuman(input: AskHumanInput, options?: OperationOptions): Promise<HumanEscalation> {
+    return request(this.address, this.agentToken, 'POST', '/v1/escalations', input, options)
+  }
+
+  escalation(id: string, options?: OperationOptions): Promise<HumanEscalation> {
+    return request(this.address, this.agentToken, 'GET', `/v1/escalations/${encodeURIComponent(id)}`, undefined, options)
+  }
+
+  mcpEndpoint(): { url: string; headers: Record<string, string> } {
+    return { url: `${this.address}/mcp`, headers: { Authorization: `Bearer ${this.agentToken}` } }
+  }
+}

package/src/errors.ts

@@ -0,0 +1,38 @@
+export type BusErrorCode =
+  | 'INVALID_ARGUMENT'
+  | 'UNAUTHENTICATED'
+  | 'PERMISSION_DENIED'
+  | 'NOT_FOUND'
+  | 'METHOD_NOT_ALLOWED'
+  | 'CONFLICT'
+  | 'BACKPRESSURE'
+  | 'INTERNAL'
+
+const STATUS_BY_CODE: Readonly<Record<BusErrorCode, number>> = {
+  INVALID_ARGUMENT: 400,
+  UNAUTHENTICATED: 401,
+  PERMISSION_DENIED: 403,
+  NOT_FOUND: 404,
+  METHOD_NOT_ALLOWED: 405,
+  CONFLICT: 409,
+  BACKPRESSURE: 429,
+  INTERNAL: 500
+}
+
+export class BusError extends Error {
+  readonly status: number
+
+  constructor(
+    readonly code: BusErrorCode,
+    message: string,
+    readonly details?: Record<string, unknown>
+  ) {
+    super(message)
+    this.name = 'BusError'
+    this.status = STATUS_BY_CODE[code]
+  }
+}
+
+export function asBusError(error: unknown): BusError {
+  return error instanceof BusError ? error : new BusError('INTERNAL', 'Internal Autumn Bus error')
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './client.js'
+export * from './errors.js'
+export * from './protocol.js'
+export * from './session.js'

package/src/protocol.ts

@@ -0,0 +1,161 @@
+export const AUTUMN_BUS_PROTOCOL_VERSION = '0.1' as const
+
+export type ScopeId = string
+export type AgentId = string
+export type ExecutionId = string
+export type MessageId = string
+export type TaskId = string
+
+export type AgentLifecycle = 'starting' | 'ready' | 'working' | 'idle' | 'needs_input' | 'offline'
+export type MessageMode = 'notify' | 'request' | 'response'
+export type DeliveryState = 'queued' | 'reserved' | 'delivered' | 'acknowledged' | 'expired'
+export type TaskStatus = 'open' | 'claimed' | 'done'
+export type EscalationStatus = 'pending' | 'resolved'
+
+export interface AgentCapability {
+  name: string
+  description?: string
+}
+
+export interface AgentIdentity {
+  scopeId: ScopeId
+  agentId: AgentId
+  executionId: ExecutionId
+}
+
+export interface Agent {
+  id: AgentId
+  displayName: string
+  capabilities: AgentCapability[]
+  lifecycle: AgentLifecycle
+  ready: boolean
+  reachable: boolean
+  executionId: ExecutionId
+  registeredAt: string
+  updatedAt: string
+}
+
+export interface ContextItem {
+  kind: 'text' | 'file' | 'url' | 'reference'
+  title: string
+  text?: string
+  uri?: string
+  mediaType?: string
+}
+
+export interface BusMessage {
+  id: MessageId
+  scopeId: ScopeId
+  from: AgentId
+  to: AgentId
+  mode: MessageMode
+  body: string
+  context: ContextItem[]
+  responseTo?: MessageId
+  state: DeliveryState
+  createdAt: string
+  expiresAt?: string
+  deliveredAt?: string
+  acknowledgedAt?: string
+  repliedAt?: string
+  responseMessageId?: MessageId
+}
+
+export interface DeliveryReceipt {
+  messageId: MessageId
+  state: DeliveryState
+  acceptedAt: string
+  deliveredAt?: string
+  acknowledgedAt?: string
+  repliedAt?: string
+  responseMessageId?: MessageId
+}
+
+export interface InboxReservation {
+  id: string
+  expiresAt: string
+  messages: BusMessage[]
+}
+
+export interface BusTask {
+  id: TaskId
+  scopeId: ScopeId
+  description: string
+  createdBy: AgentId
+  claimedBy?: AgentId
+  status: TaskStatus
+  dependencies: TaskId[]
+  note?: string
+  createdAt: string
+  updatedAt: string
+}
+
+export interface HumanEscalation {
+  id: string
+  scopeId: ScopeId
+  agentId: AgentId
+  question: string
+  options: string[]
+  status: EscalationStatus
+  answer?: string
+  createdAt: string
+  resolvedAt?: string
+}
+
+export interface CreateScopeInput {
+  id?: ScopeId
+}
+
+export interface CreateScopeResult {
+  scopeId: ScopeId
+  scopeToken: string
+}
+
+export interface RegisterAgentInput {
+  id?: AgentId
+  displayName: string
+  capabilities?: AgentCapability[]
+  connectTo?: AgentId[]
+  leaseMs?: number
+}
+
+export interface RegisterAgentResult extends AgentIdentity {
+  agentToken: string
+  leaseExpiresAt: string
+}
+
+export interface SendMessageInput {
+  to: AgentId
+  body: string
+  mode?: MessageMode
+  responseTo?: MessageId
+  idempotencyKey?: string
+  expiresInMs?: number
+  context?: ContextItem[]
+}
+
+export interface AddTaskInput {
+  description: string
+  dependencies?: TaskId[]
+}
+
+export interface AskHumanInput {
+  question: string
+  options?: string[]
+}
+
+export interface BusRunFile {
+  protocolVersion: string
+  address: string
+  pid: number
+  startedAt: string
+  adminToken: string
+}
+
+export interface BusHealth {
+  name: 'autumn-bus'
+  protocolVersion: string
+  runtimeVersion: string
+  status: 'ready'
+  startedAt: string
+}

package/src/session.ts

@@ -0,0 +1,216 @@
+import { AutumnBusClient, AutumnBusScopeClient } from './client.js'
+import type {
+  Agent,
+  AgentLifecycle,
+  BusMessage,
+  BusTask,
+  RegisterAgentInput,
+  RegisterAgentResult
+} from './protocol.js'
+
+export interface AgentSessionOptions {
+  address: string
+  scopeToken: string
+  registration: RegisterAgentInput
+  heartbeatIntervalMs?: number
+  initialLifecycle?: AgentLifecycle
+  initialReady?: boolean
+  signal?: AbortSignal
+}
+
+export interface InboxPollingOptions {
+  limit?: number
+  intervalMs?: number
+  maxIntervalMs?: number
+  backoffFactor?: number
+  signal?: AbortSignal
+}
+
+export interface ClaimedTaskResult<T> {
+  task: BusTask
+  value: T
+}
+
+function delay(milliseconds: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new Error('Operation aborted'))
+      return
+    }
+    const onAbort = () => {
+      clearTimeout(timer)
+      reject(signal?.reason ?? new Error('Operation aborted'))
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort)
+      resolve()
+    }, milliseconds)
+    signal?.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+export function requiredEnvironmentValue(
+  environment: Readonly<Record<string, string | undefined>>,
+  name: string
+): string {
+  const value = environment[name]
+  if (!value) throw new Error(`${name} is required`)
+  return value
+}
+
+export function newIdempotencyKey(): string {
+  return crypto.randomUUID()
+}
+
+export class AutumnBusAgentSession {
+  readonly client: AutumnBusClient
+  readonly registration: RegisterAgentResult
+  readonly done: Promise<void>
+
+  private readonly leaseMs: number
+  private readonly heartbeatIntervalMs: number
+  private lifecycle: AgentLifecycle
+  private ready: boolean
+  private timer: ReturnType<typeof setTimeout> | undefined
+  private pendingHeartbeat: Promise<Agent> | undefined
+  private resolveDone!: () => void
+  private closed = false
+  private sessionError: unknown
+
+  private constructor(options: AgentSessionOptions, registration: RegisterAgentResult) {
+    this.registration = registration
+    this.client = new AutumnBusClient(options.address, registration.agentToken)
+    this.leaseMs = options.registration.leaseMs || 300_000
+    this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? Math.floor(this.leaseMs / 3)
+    this.lifecycle = options.initialLifecycle ?? 'starting'
+    this.ready = options.initialReady ?? false
+    this.done = new Promise((resolve) => {
+      this.resolveDone = resolve
+    })
+    options.signal?.addEventListener('abort', () => void this.close(), { once: true })
+  }
+
+  static async start(options: AgentSessionOptions): Promise<AutumnBusAgentSession> {
+    if (options.signal?.aborted) {
+      throw options.signal.reason ?? new Error('Operation aborted')
+    }
+    const leaseMs = options.registration.leaseMs || 300_000
+    const interval = options.heartbeatIntervalMs ?? Math.floor(leaseMs / 3)
+    const lifecycle = options.initialLifecycle ?? 'starting'
+    const ready = options.initialReady ?? false
+    if (interval <= 0 || interval >= leaseMs) {
+      throw new Error('heartbeatIntervalMs must be shorter than the execution lease')
+    }
+    if (lifecycle === 'offline' && ready) {
+      throw new Error('offline agents cannot be ready')
+    }
+    const scope = new AutumnBusScopeClient(options.address, options.scopeToken)
+    const registration = await scope.registerAgent({ ...options.registration, leaseMs })
+    if (options.signal?.aborted) {
+      const client = new AutumnBusClient(options.address, registration.agentToken)
+      try {
+        await client.heartbeat('offline', false, leaseMs)
+      } catch {
+        // The lease remains the cleanup fallback if the execution was replaced.
+      }
+      throw options.signal.reason ?? new Error('Operation aborted')
+    }
+    const session = new AutumnBusAgentSession(options, registration)
+    await session.client.heartbeat(session.lifecycle, session.ready, session.leaseMs)
+    session.scheduleHeartbeat()
+    return session
+  }
+
+  get error(): unknown {
+    return this.sessionError
+  }
+
+  async setState(lifecycle: AgentLifecycle, ready: boolean): Promise<Agent> {
+    if (this.closed) throw new Error('agent session is closed')
+    if (lifecycle === 'offline' && ready) throw new Error('offline agents cannot be ready')
+    this.lifecycle = lifecycle
+    this.ready = ready
+    return this.client.heartbeat(lifecycle, ready, this.leaseMs)
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return
+    this.closed = true
+    if (this.timer !== undefined) clearTimeout(this.timer)
+    try {
+      await this.pendingHeartbeat
+      await this.client.heartbeat('offline', false, this.leaseMs)
+    } catch (error) {
+      if (this.sessionError === undefined) this.sessionError = error
+    } finally {
+      this.resolveDone()
+    }
+  }
+
+  private scheduleHeartbeat(): void {
+    if (this.closed) return
+    this.timer = setTimeout(() => {
+      this.pendingHeartbeat = this.client.heartbeat(this.lifecycle, this.ready, this.leaseMs)
+      void this.pendingHeartbeat.then(
+        () => {
+          this.pendingHeartbeat = undefined
+          this.scheduleHeartbeat()
+        },
+        (error: unknown) => {
+          this.pendingHeartbeat = undefined
+          this.sessionError = error
+          this.closed = true
+          this.resolveDone()
+        }
+      )
+    }, this.heartbeatIntervalMs)
+  }
+}
+
+export async function* pollInbox(
+  client: AutumnBusClient,
+  options: InboxPollingOptions = {}
+): AsyncGenerator<BusMessage[]> {
+  const limit = options.limit ?? 50
+  const intervalMs = options.intervalMs ?? 1_000
+  const maxIntervalMs = options.maxIntervalMs ?? 10_000
+  const backoffFactor = options.backoffFactor ?? 1.5
+  if (limit < 1 || limit > 100) throw new Error('limit must be between 1 and 100')
+  if (intervalMs < 1) throw new Error('intervalMs must be positive')
+  if (maxIntervalMs < intervalMs) throw new Error('maxIntervalMs must not be shorter than intervalMs')
+  if (backoffFactor < 1 || !Number.isFinite(backoffFactor)) {
+    throw new Error('backoffFactor must be a finite number of at least 1')
+  }
+  let nextIntervalMs = intervalMs
+  while (!options.signal?.aborted) {
+    const messages = await client.pullInbox(limit, options.signal ? { signal: options.signal } : undefined)
+    if (messages.length > 0) {
+      nextIntervalMs = intervalMs
+      yield messages
+    } else {
+      nextIntervalMs = Math.min(maxIntervalMs, Math.ceil(nextIntervalMs * backoffFactor))
+    }
+    if (!options.signal?.aborted) await delay(nextIntervalMs, options.signal)
+  }
+}
+
+export async function withClaimedTask<T>(
+  client: AutumnBusClient,
+  taskId: string,
+  work: (task: BusTask) => Promise<T>,
+  completionNote?: (value: T) => string | undefined
+): Promise<ClaimedTaskResult<T>> {
+  const claimed = await client.claimTask(taskId)
+  try {
+    const value = await work(claimed)
+    const task = await client.completeTask(taskId, completionNote?.(value))
+    return { task, value }
+  } catch (error) {
+    try {
+      await client.releaseTask(taskId)
+    } catch {
+      // Preserve the work error. Lease recovery remains the final fallback.
+    }
+    throw error
+  }
+}