experimental-a2 0.13.0 → 0.14.1

package/src/ai-control-server.ts

@@ -0,0 +1,829 @@
+// oxlint-disable no-await-in-loop -- work acknowledgements follow the durable stream.
+import { applyControlChanges, controlCommit } from './ai-control-state.ts'
+import type { ControlChange, ControlCommit } from './ai-control.ts'
+import type { UIMessage } from 'ai'
+import type {
+  AIEventDefs,
+  AgentDefinition,
+  GenerationRequestedPayload,
+  MessageInterruptedPayload,
+} from './ai.ts'
+import {
+  aiCoordinatorReducer,
+  continuationReady,
+  foldCoordinator,
+} from './ai-coordinator.ts'
+import {
+  initialControlState,
+  type AIControlState,
+  type ControlCommand,
+  type ControlReceipt,
+  type WorkFact,
+  type WorkReport,
+} from './ai-control.ts'
+import type { AppendInput, ContractEvent, EventDefs } from './contract.ts'
+import type { HandlerContext } from './server.ts'
+import type { Reducer } from './reducer.ts'
+import type { AICoordinatorState, CoordinatorCall } from './ai-coordinator.ts'
+import { validateSync } from './validate.ts'
+import type { StandardSchemaV1 } from './standard-schema.ts'
+import { A2Error } from './errors.ts'
+
+export class ControlCancelled extends Error {}
+
+const callReadyForModel = (call: CoordinatorCall): boolean =>
+  call.terminal ||
+  (call.call.providerExecuted === true &&
+    !call.call.supportsDeferredResults &&
+    call.response !== undefined)
+
+const approvalBlocksExecution = (call: CoordinatorCall): boolean =>
+  call.approval !== undefined && call.response?.approved !== true
+
+export type AIControlRuntime<
+  M extends UIMessage,
+  D extends AIEventDefs<M> & EventDefs,
+> = {
+  handler(
+    ctx: HandlerContext<
+      D,
+      'ai.control.requested' | 'ai.work.reported' | 'ai.session.closed'
+    >,
+  ): Promise<AppendInput<D>[]>
+  append(options: {
+    ctx: HandlerContext<D>
+    name: string
+    events: AppendInput<D>[]
+  }): Promise<ContractEvent<D>[]>
+  settled(options: {
+    ctx: HandlerContext<D>
+    events: void | AppendInput<D> | readonly AppendInput<D>[]
+  }): AppendInput<D>
+  cancelled(options: { error: unknown; signal: AbortSignal }): boolean
+  reducer: Reducer<D, AIControlState<M>>
+  coordinator: Reducer<D, AICoordinatorState>
+}
+
+export const createControlRuntime = <
+  M extends UIMessage,
+  D extends AIEventDefs<M> & EventDefs,
+>(options: {
+  agent: AgentDefinition<M, D>
+}): AIControlRuntime<M, D> => {
+  const reducer = options.agent.contract
+    .reducer({
+      name: 'a2.ai.control.v1',
+      initialState: initialControlState<M>(),
+    })
+    .fold((state, event) =>
+      event.type === 'ai.control.committed'
+        ? applyControlChanges({
+            state,
+            changes: (event.payload as ControlCommit).changes,
+          })
+        : state,
+    )
+  const coordinator = aiCoordinatorReducer(options.agent.contract)
+
+  const handler = async (
+    ctx: HandlerContext<
+      D,
+      'ai.control.requested' | 'ai.work.reported' | 'ai.session.closed'
+    >,
+  ): Promise<AppendInput<D>[]> => {
+    const snapshot = await ctx.session.state(reducer, { through: 'latest' })
+    const before = structuredClone(snapshot.state)
+    const moves: ControlChange[] = []
+    const state = structuredClone(snapshot.state)
+    const facts: WorkFact[] = []
+    const jobs: AppendInput<D>[] = []
+    const emit = ({
+      type,
+      payload,
+      id = `${ctx.event.id}:fact:${facts.length}`,
+    }: {
+      type: string
+      payload: unknown
+      id?: string
+    }): void => {
+      const fact = { type, payload, id }
+      facts.push(fact)
+      state.coordinator = foldCoordinator<M, D>(state.coordinator, {
+        ...ctx.event,
+        ...fact,
+      } as ContractEvent<D>)
+    }
+    let reason: ControlReceipt['reason']
+    const end = ({
+      lastSeenIndex,
+      reason: interruptionReason,
+    }: {
+      lastSeenIndex: number | undefined
+      reason: string | undefined
+    }): void => {
+      const response = state.coordinator.response
+      if (response === undefined) return
+      const owner =
+        response.generation === undefined
+          ? { requestId: response.activeRequestId! }
+          : { generationId: response.generation.generationId }
+      emit({
+        type: 'ai.message.interrupted',
+        payload: {
+          messageId: response.responseMessageId,
+          ...owner,
+          ...(interruptionReason === undefined
+            ? {}
+            : { reason: interruptionReason }),
+          ...(lastSeenIndex === undefined ? {} : { lastSeenIndex }),
+        } satisfies MessageInterruptedPayload,
+      })
+      state.active = null
+    }
+    const knownInput = (id: string): boolean =>
+      state.inbox.items.some((candidate) => candidate.id === id) ||
+      Object.hasOwn(state.reservedIds, id)
+    const missingInputReason = (id: string): ControlReceipt['reason'] =>
+      state.reservedIds[id] === 'removed' || !knownInput(id)
+        ? 'not-found'
+        : 'already-active'
+    const inputTaken = ({
+      message,
+      generate = true,
+    }: {
+      message: M
+      generate?: boolean
+    }): boolean =>
+      knownInput(message.id) ||
+      (generate &&
+        message.role === 'user' &&
+        knownInput(`${message.id}:assistant`))
+    const insert = ({
+      message,
+      generate = true,
+      first = false,
+      afterStepOf,
+    }: {
+      message: M
+      generate?: boolean
+      first?: boolean
+      afterStepOf?: string
+    }): void => {
+      const candidate = {
+        id: message.id,
+        revision: 0,
+        message,
+        generate: generate && message.role === 'user',
+        ...(afterStepOf === undefined ? {} : { afterStepOf }),
+      }
+      state.reservedIds = {
+        ...state.reservedIds,
+        [candidate.id]: true,
+        ...(candidate.generate
+          ? { [`${candidate.id}:assistant`]: true as const }
+          : {}),
+      }
+      if (first) state.inbox.items.unshift(candidate)
+      else state.inbox.items.push(candidate)
+    }
+    const moveInput = ({ from, to }: { from: number; to: number }): void => {
+      if (from === to) return
+      const [moved] = state.inbox.items.splice(from, 1)
+      state.inbox.items.splice(to, 0, moved!)
+      const [previous] = before.inbox.items.splice(from, 1)
+      before.inbox.items.splice(to, 0, previous!)
+      moves.push({ path: ['inbox', 'items'], move: { from, to } })
+    }
+    const requestModel = ({
+      request,
+      id,
+    }: {
+      request: GenerationRequestedPayload
+      id: string
+    }): void => {
+      const active = state.active!
+      const payload = {
+        ...request,
+        control: { turnId: active.turnId, version: active.version },
+      }
+      state.coordinator = foldCoordinator<M, D>(state.coordinator, {
+        ...ctx.event,
+        type: 'ai.generation.requested',
+        id,
+        payload,
+      } as ContractEvent<D>)
+      active.model = { id, version: active.version, settled: false }
+      active.phase = 'starting'
+      jobs.push({
+        type: 'ai.generation.requested',
+        id,
+        payload,
+      } as AppendInput<D>)
+    }
+    if (ctx.event.type === 'ai.session.closed') {
+      state.coordinator = { closed: true, queued: [] }
+      state.active = null
+      state.inbox.items = []
+    } else if (ctx.event.type === 'ai.control.requested') {
+      const command = ctx.event.payload as ControlCommand<M>
+      if (state.coordinator.closed) reason = 'closed'
+      else
+        switch (command.action) {
+          case 'send':
+            if (
+              inputTaken({
+                message: command.message,
+                generate: command.generate !== false,
+              })
+            )
+              reason = 'duplicate-input'
+            else
+              insert({
+                message: command.message,
+                generate: command.generate !== false,
+              })
+            break
+          case 'edit': {
+            const item = state.inbox.items.find(
+              (candidate) => candidate.id === command.message.id,
+            )
+            if (item === undefined)
+              reason = missingInputReason(command.message.id)
+            else if (item.revision !== command.expectedRevision)
+              reason = 'revision-conflict'
+            else if (item.message.role !== command.message.role)
+              reason = 'revision-conflict'
+            else {
+              item.message = command.message
+              item.revision += 1
+            }
+            break
+          }
+          case 'remove': {
+            const position = state.inbox.items.findIndex(
+              (item) => item.id === command.inputId,
+            )
+            if (position < 0) reason = missingInputReason(command.inputId)
+            else {
+              state.inbox.items.splice(position, 1)
+              state.reservedIds = {
+                ...state.reservedIds,
+                [command.inputId]: 'removed',
+              }
+            }
+            break
+          }
+          case 'move': {
+            const index = state.inbox.items.findIndex(
+              (candidate) => candidate.id === command.inputId,
+            )
+            if (index < 0) reason = missingInputReason(command.inputId)
+            else if (
+              command.beforeId !== null &&
+              !state.inbox.items.some(
+                (candidate) => candidate.id === command.beforeId,
+              )
+            )
+              reason = 'not-found'
+            else {
+              const destination =
+                command.beforeId === null
+                  ? state.inbox.items.length
+                  : state.inbox.items.findIndex(
+                      (item) => item.id === command.beforeId,
+                    )
+              moveInput({
+                from: index,
+                to: destination > index ? destination - 1 : destination,
+              })
+            }
+            break
+          }
+          case 'send-now': {
+            const position = state.inbox.items.findIndex(
+              (item) => item.id === command.inputId,
+            )
+            const selected = state.inbox.items[position]
+            if (!selected) reason = missingInputReason(command.inputId)
+            else if ((state.active?.turnId ?? null) !== command.turnId)
+              reason = 'stale-turn'
+            else if (selected.message.role !== 'user') reason = 'not-user-input'
+            else if (
+              !selected.generate &&
+              knownInput(`${selected.id}:assistant`)
+            )
+              reason = 'duplicate-input'
+            else {
+              if (!selected.generate) {
+                state.reservedIds = {
+                  ...state.reservedIds,
+                  [`${selected.id}:assistant`]: true,
+                }
+                selected.generate = true
+              }
+              if (state.active) selected.afterStepOf = state.active.turnId
+              else delete selected.afterStepOf
+              moveInput({ from: position, to: 0 })
+            }
+            break
+          }
+          case 'stop':
+            if (state.active?.turnId !== command.turnId) reason = 'stale-turn'
+            else
+              end({ lastSeenIndex: command.lastSeenIndex, reason: undefined })
+            break
+          case 'steer':
+            if (inputTaken({ message: command.message }))
+              reason = 'duplicate-input'
+            else {
+              insert({
+                message: command.message,
+                generate: true,
+                first: true,
+                afterStepOf: command.turnId,
+              })
+            }
+            break
+          case 'interrupt': {
+            const response = state.coordinator.response
+            if (
+              !response ||
+              response.responseMessageId !== command.request.messageId ||
+              (command.request.generationId !==
+                response.generation?.generationId &&
+                command.request.requestId !== response.activeRequestId)
+            )
+              reason = 'stale-turn'
+            else
+              end({
+                lastSeenIndex: command.request.lastSeenIndex,
+                reason: command.request.reason,
+              })
+            break
+          }
+          case 'pause': {
+            state.inbox.paused = true
+            const active = state.active
+            if (
+              command.when === 'now' &&
+              active !== null &&
+              !active.suspended
+            ) {
+              active.suspended = true
+              active.version += 1
+              const generation = state.coordinator.response?.generation
+              if (generation)
+                emit({
+                  type: 'ai.generation.paused',
+                  payload: {
+                    generationId: generation.generationId,
+                    messageId: generation.responseMessageId,
+                  },
+                })
+            }
+            break
+          }
+          case 'resume':
+            state.inbox.paused = false
+            break
+          case 'tool-result': {
+            const call = state.coordinator.response?.calls.find(
+              (candidate) =>
+                candidate.call.generationId === command.result.generationId &&
+                candidate.call.messageId === command.result.messageId &&
+                candidate.call.toolCallId === command.result.toolCallId &&
+                candidate.call.providerExecuted === true &&
+                !candidate.terminal,
+            )
+            if (!call) reason = 'not-found'
+            else emit({ type: 'ai.tool.result', payload: command.result })
+            break
+          }
+          case 'approval': {
+            const response = state.coordinator.response
+            const call = response?.calls.find(
+              (candidate) =>
+                candidate.approval?.approvalId ===
+                  command.response.approvalId &&
+                candidate.approval.generationId ===
+                  command.response.generationId &&
+                candidate.approval.messageId === command.response.messageId,
+            )
+            if (response?.failure) reason = 'stale-turn'
+            else if (!call || call.response || call.terminal)
+              reason = 'not-found'
+            else
+              emit({ type: 'ai.approval.responded', payload: command.response })
+            break
+          }
+          case 'request-input':
+          case 'input': {
+            const payload =
+              command.action === 'input' ? command.response : command.request
+            const response = state.coordinator.response
+            if (
+              response?.failure !== undefined ||
+              response?.generation?.generationId !== payload.generationId ||
+              response.responseMessageId !== payload.messageId ||
+              (command.action === 'input' &&
+                !response.inputs.some(
+                  (input) =>
+                    input.inputId === payload.inputId &&
+                    input.name === payload.name,
+                ))
+            )
+              reason = 'not-found'
+            else
+              emit({
+                type:
+                  command.action === 'input'
+                    ? 'ai.input.responded'
+                    : 'ai.input.requested',
+                payload,
+              })
+            break
+          }
+          case 'retry': {
+            const response = state.coordinator.response
+            if (
+              !state.active ||
+              response?.status !== 'failed' ||
+              response.rootMessageId !== command.request.messageId ||
+              response.responseMessageId !== command.request.responseMessageId
+            )
+              reason = 'stale-turn'
+            else if (!state.inbox.paused && !state.active.suspended) {
+              emit({ type: 'ai.retry.requested', payload: command.request })
+              requestModel({
+                request: {
+                  messageId: response.rootMessageId,
+                  responseMessageId: response.responseMessageId,
+                  reason: 'retry',
+                },
+                id: `ai.generate:retry:${command.request.retryId}`,
+              })
+            } else reason = 'stale-turn'
+            break
+          }
+        }
+    } else {
+      const report = ctx.event.payload as WorkReport
+      const active = state.active
+      const response = state.coordinator.response
+      const call = response?.calls.find(
+        (candidate) => candidate.work?.id === report.workId,
+      )
+      const work = report.kind === 'model' ? active?.model : call?.work
+      const current =
+        active?.turnId === report.turnId &&
+        work?.id === report.workId &&
+        work.version === report.version &&
+        !work.settled &&
+        report.attempt >= (work.attempt ?? 0)
+      if (!current) {
+        reason = 'stale-work'
+      } else {
+        work.attempt = report.attempt
+        const authorized =
+          !active.suspended && active.version === report.version
+        for (const event of report.events) {
+          if (work.facts?.includes(event.id)) continue
+          if (
+            authorized ||
+            (report.kind === 'tool' && event.type === 'ai.tool.result')
+          ) {
+            emit({ type: event.type, payload: event.payload, id: event.id })
+            work.facts = [...(work.facts ?? []), event.id]
+          }
+        }
+        if (report.settled) work.settled = true
+        if (!authorized) reason = 'stale-work'
+      }
+    }
+
+    let active = state.active
+    let response = state.coordinator.response
+    if (active && response === undefined) {
+      state.active = null
+      active = null
+    }
+    if (active && response) {
+      const handoff = state.inbox.items.some(
+        (item) => item.afterStepOf === active.turnId,
+      )
+      const outstanding =
+        (active.model !== null && !active.model.settled) ||
+        response.calls.some(
+          (candidate) =>
+            candidate.work !== undefined && !candidate.work.settled,
+        )
+      if (active.suspended) {
+        active.phase = outstanding ? 'pausing' : 'paused'
+        if (!state.inbox.paused && !outstanding && !handoff)
+          active.suspended = false
+      }
+      if (!active.suspended && response.failure) active.phase = 'failed'
+      if (!active.suspended && response.failure === undefined) {
+        for (const call of response.calls) {
+          if (
+            call.terminal ||
+            (call.work !== undefined &&
+              (!call.work.settled || call.work.version === active.version)) ||
+            call.call.providerExecuted === true ||
+            (call.approval && !call.response)
+          )
+            continue
+          if (call.response?.approved === false) {
+            emit({
+              type: 'ai.tool.result',
+              payload: {
+                ...call.call,
+                denied: true,
+                phase: 'execution',
+              },
+            })
+            continue
+          }
+          const id = `${ctx.event.id}:tool:${call.call.toolCallId}`
+          call.work = { id, version: active.version, settled: false }
+          jobs.push({
+            type: 'ai.tool.execution.requested',
+            id,
+            payload: {
+              turnId: active.turnId,
+              version: active.version,
+              call: call.call,
+              generation: response.generation!,
+            },
+          } as AppendInput<D>)
+        }
+      }
+      response = state.coordinator.response!
+      const callsDone = response.calls.every(callReadyForModel)
+      const modelDone = active.model === null || active.model.settled
+      const workSettled =
+        modelDone &&
+        response.calls.every(
+          (call) => call.work === undefined || call.work.settled,
+        )
+      const externalPending = response.calls.some(
+        (call) =>
+          call.call.providerExecuted &&
+          call.call.supportsDeferredResults &&
+          !call.terminal &&
+          !approvalBlocksExecution(call),
+      )
+      const handoffReady =
+        handoff &&
+        workSettled &&
+        !externalPending &&
+        (active.suspended ||
+          response.failure !== undefined ||
+          response.calls.every(
+            (call) => callReadyForModel(call) || approvalBlocksExecution(call),
+          ))
+      const readyForModel =
+        !active.suspended &&
+        response.failure === undefined &&
+        modelDone &&
+        callsDone &&
+        response.inputs.length === 0
+      const naturalCompletion =
+        readyForModel &&
+        response.completion !== undefined &&
+        response.completion.finishReason !== 'tool-calls'
+      if (handoffReady && !naturalCompletion) {
+        end({ lastSeenIndex: undefined, reason: 'steered after step' })
+      } else if (readyForModel && (!handoff || handoffReady)) {
+        const resume =
+          active.model !== null && active.model.version !== active.version
+        const input = response.inputResponse
+        if (
+          !handoff &&
+          (resume ||
+            continuationReady(state.coordinator) ||
+            (response.completion && input))
+        ) {
+          const nextReason = resume ? 'resume' : input ? 'input' : 'tool'
+          const id =
+            nextReason === 'tool'
+              ? `ai.generate:tools:${response.generation!.generationId}`
+              : `${ctx.event.id}:generate:${nextReason}`
+          requestModel({
+            request: {
+              messageId: response.responseMessageId,
+              responseMessageId: response.responseMessageId,
+              reason: nextReason,
+            },
+            id,
+          })
+        } else if (naturalCompletion) {
+          emit({
+            type: 'ai.message.completed',
+            payload: {
+              messageId: response.responseMessageId,
+            },
+          })
+          state.active = null
+        }
+      }
+      if (
+        !active.suspended &&
+        state.active &&
+        jobs.every((job) => job.type !== 'ai.generation.requested')
+      )
+        state.active.phase = response.failure
+          ? 'failed'
+          : !modelDone
+            ? 'generating'
+            : !callsDone
+              ? 'tools'
+              : 'waiting'
+    }
+    if (
+      state.active === null &&
+      !state.inbox.paused &&
+      !state.coordinator.closed
+    ) {
+      while (state.inbox.items.length > 0) {
+        const item = state.inbox.items.shift()!
+        delete item.afterStepOf
+        emit({
+          type: 'ai.message.created',
+          payload: { message: item.message, generate: item.generate },
+          id: `ai.admitted:${item.id}`,
+        })
+        if (!item.generate) continue
+        state.active = {
+          turnId: item.id,
+          input: item,
+          phase: 'starting',
+          version: 0,
+          suspended: false,
+          model: null,
+        }
+        requestModel({
+          request: { messageId: item.id, reason: 'message' },
+          id: `ai.generate:message:${item.id}`,
+        })
+        break
+      }
+    }
+    const receipt: ControlReceipt = {
+      commandId: ctx.event.id,
+      ...(ctx.event.type === 'ai.work.reported' ? { work: true as const } : {}),
+      outcome: reason === undefined ? 'applied' : 'rejected',
+      ...(reason === undefined ? {} : { reason }),
+    }
+    return [
+      ...(facts as AppendInput<D>[]),
+      {
+        type: 'ai.control.committed',
+        payload: controlCommit({ before, after: state, moves }),
+      } as AppendInput<D>,
+      ...jobs,
+      { type: 'ai.control.decided', payload: receipt } as AppendInput<D>,
+    ]
+  }
+
+  const report = ({
+    ctx,
+    events,
+    settled,
+    name,
+  }: {
+    ctx: HandlerContext<D>
+    events: readonly AppendInput<D>[]
+    settled: boolean
+    name: string
+  }): AppendInput<D> => {
+    const payload = ctx.event.payload as
+      GenerationRequestedPayload | { turnId: string; version: number }
+    const { turnId, version } = 'turnId' in payload ? payload : payload.control!
+    for (const event of events) {
+      const schema = options.agent.contract.events[
+        event.type
+      ] as StandardSchemaV1<unknown>
+      const result = validateSync(
+        schema,
+        event.payload,
+        `AI worker ${event.type}`,
+      )
+      if (result.issues)
+        throw new TypeError(
+          result.issues.map((issue) => issue.message).join('; '),
+        )
+    }
+    return {
+      type: 'ai.work.reported',
+      id: `${ctx.event.id}:report:${ctx.attempt}:${name}`,
+      payload: {
+        workId: ctx.event.id,
+        attempt: ctx.attempt,
+        turnId,
+        version,
+        kind: ctx.event.type === 'ai.generation.requested' ? 'model' : 'tool',
+        settled,
+        events: events
+          .filter(
+            (event) =>
+              event.type !== 'ai.message.completed' &&
+              event.type !== 'ai.message.interrupted',
+          )
+          .map((event, index) => ({
+            type: event.type,
+            payload: event.payload,
+            id:
+              event.id ??
+              `${ctx.event.id}:fact:${ctx.attempt}:${name}:${index}`,
+          })),
+      },
+    } as AppendInput<D>
+  }
+
+  const append = async ({
+    ctx,
+    name,
+    events,
+  }: {
+    ctx: HandlerContext<D>
+    name: string
+    events: AppendInput<D>[]
+  }): Promise<ContractEvent<D>[]> => {
+    const progress = events.filter(
+      (event) => event.type === 'ai.generation.progress',
+    )
+    const lifecycle = events.filter(
+      (event) => event.type !== 'ai.generation.progress',
+    )
+    if (lifecycle.length === 0) return ctx.session.append(name, ...progress)
+    const input = report({ ctx, events: lifecycle, settled: false, name })
+    const persisted = await ctx.session.append(name, ...progress, input)
+    const index = persisted.at(-1)!.index
+    const feed = ctx.session.stream({ startAfter: index })
+    const stream = feed[Symbol.asyncIterator]()
+    const canonical: ContractEvent<D>[] = []
+    const wanted = new Set(lifecycle.map((event) => event.id))
+    let rejectAbort!: (error: unknown) => void
+    const aborted = new Promise<never>((_, reject) => {
+      rejectAbort = reject
+    })
+    const onAbort = (): void => {
+      rejectAbort(ctx.signal.reason)
+    }
+    ctx.signal.addEventListener('abort', onAbort, { once: true })
+    try {
+      ctx.signal.throwIfAborted()
+      for (;;) {
+        const item = await Promise.race([stream.next(), aborted])
+        if (item.done)
+          throw new Error('AI control acknowledgement stream ended')
+        if (wanted.has(item.value.id)) canonical.push(item.value)
+        if (
+          item.value.type === 'ai.control.decided' &&
+          (item.value.payload as ControlReceipt).commandId === input.id
+        ) {
+          if ((item.value.payload as ControlReceipt).outcome === 'rejected')
+            throw new ControlCancelled('stale AI work')
+          return [
+            ...persisted.filter((event) => event.type !== 'ai.work.reported'),
+            ...canonical,
+          ]
+        }
+      }
+    } finally {
+      ctx.signal.removeEventListener('abort', onAbort)
+      await stream.return?.()
+    }
+  }
+
+  const settled = ({
+    ctx,
+    events,
+  }: {
+    ctx: HandlerContext<D>
+    events: void | AppendInput<D> | readonly AppendInput<D>[]
+  }): AppendInput<D> =>
+    report({
+      ctx,
+      events:
+        events === undefined
+          ? []
+          : Array.isArray(events)
+            ? events
+            : [events as AppendInput<D>],
+      settled: true,
+      name: 'settled',
+    })
+  const cancelled = ({
+    error,
+    signal,
+  }: {
+    error: unknown
+    signal: AbortSignal
+  }): boolean => {
+    if (signal.reason instanceof A2Error) throw signal.reason
+    return error instanceof ControlCancelled || signal.aborted
+  }
+  return { handler, append, settled, cancelled, reducer, coordinator }
+}