asyncapi: 3.0.0
info:
  title: Neotask Agent Events
  version: 1.0.0
  description: "Generated from the Neotask Agent API event channel registry.
    Launch state: Live."
servers:
  production:
    host: neotask.ai
    protocol: https
    description: Canonical Neotask origin.
defaultContentType: application/json
channels:
  neotask_agent_v1_runs_runRef_events:
    address: neotask.agent.v1.runs.{runRef}.events
    description: chat events. Read the JSON recovery path before reconnecting an SSE client.
    parameters:
      runRef:
        description: Tenant-scoped opaque reference supplied by the authenticated agent.
        schema:
          type: string
          minLength: 1
          maxLength: 256
    messages:
      neotask_agent_v1_runs_runRef_eventsEvent:
        $ref: "#/components/messages/neotask_agent_v1_runs_runRef_eventsEvent"
    x-neotask-status: implemented
    x-neotask-launch-state: live
    x-neotask-event-types:
      - run.queued
      - run.started
      - run.progress
      - run.steered
      - run.awaiting_input
      - run.resumed
      - run.completed
      - run.failed
      - run.cancelled
      - run.lease_lost
      - run.event
    x-neotask-json-recovery-path: /api/agent/v1/runs/{runRef}/events
    x-neotask-sse-path: /api/agent/v1/runs/{runRef}/events/stream
    x-neotask-mcp-resource: neotask://agent/v1/runs/{runRef}/events
    x-neotask-source-of-truth: site_run_event_log
    x-neotask-cursor:
      mode: opaque
      replayWindow: 24h
      deduplicationKey: eventRef
  neotask_agent_v1_conversations_conversationRef_turns_turnRef_events:
    address: neotask.agent.v1.conversations.{conversationRef}.turns.{turnRef}.events
    description: chat events. Read the JSON recovery path before reconnecting an SSE client.
    parameters:
      conversationRef:
        description: Tenant-scoped opaque reference supplied by the authenticated agent.
        schema:
          type: string
          minLength: 1
          maxLength: 256
      turnRef:
        description: Tenant-scoped opaque reference supplied by the authenticated agent.
        schema:
          type: string
          minLength: 1
          maxLength: 256
    messages:
      neotask_agent_v1_conversations_conversationRef_turns_turnRef_eventsEvent:
        $ref: "#/components/messages/neotask_agent_v1_conversations_conversationRef_tur\
          ns_turnRef_eventsEvent"
    x-neotask-status: implemented
    x-neotask-launch-state: live
    x-neotask-event-types:
      - turn.queued
      - turn.running
      - turn.completed
      - turn.failed
      - turn.execution_unknown
      - turn.cancel_requested
    x-neotask-json-recovery-path: /api/agent/v1/conversations/{conversationRef}/turns/{turnRef}/events
    x-neotask-sse-path: /api/agent/v1/conversations/{conversationRef}/turns/{turnRef}/events/stream
    x-neotask-mcp-resource: neotask://agent/v1/conversations/{conversationRef}/turns/{turnRef}/events
    x-neotask-source-of-truth: site_conversation_event_log
    x-neotask-cursor:
      mode: opaque
      replayWindow: 24h
      deduplicationKey: eventRef
  neotask_agent_v1_approvals_approvalRef_events:
    address: neotask.agent.v1.approvals.{approvalRef}.events
    description: approvals events. Read the JSON recovery path before reconnecting
      an SSE client.
    parameters:
      approvalRef:
        description: Tenant-scoped opaque reference supplied by the authenticated agent.
        schema:
          type: string
          minLength: 1
          maxLength: 256
    messages:
      neotask_agent_v1_approvals_approvalRef_eventsEvent:
        $ref: "#/components/messages/neotask_agent_v1_approvals_approvalRef_eventsEvent"
    x-neotask-status: implemented
    x-neotask-launch-state: live
    x-neotask-event-types:
      - approval.requested
      - approval.approved
      - approval.denied
      - approval.expired
      - approval.cancelled
    x-neotask-json-recovery-path: /api/agent/v1/approvals/{approvalRef}/events
    x-neotask-sse-path: /api/agent/v1/approvals/{approvalRef}/events/stream
    x-neotask-mcp-resource: neotask://agent/v1/approvals/{approvalRef}/events
    x-neotask-source-of-truth: site_approval_event_log
    x-neotask-cursor:
      mode: opaque
      replayWindow: 8h
      deduplicationKey: eventRef
  neotask_agent_v1_runners_runnerRef_events:
    address: neotask.agent.v1.runners.{runnerRef}.events
    description: runner events. Read the JSON recovery path before reconnecting an
      SSE client.
    parameters:
      runnerRef:
        description: Tenant-scoped opaque reference supplied by the authenticated agent.
        schema:
          type: string
          minLength: 1
          maxLength: 256
    messages:
      neotask_agent_v1_runners_runnerRef_eventsEvent:
        $ref: "#/components/messages/neotask_agent_v1_runners_runnerRef_eventsEvent"
    x-neotask-status: planned
    x-neotask-launch-state: live
    x-neotask-event-types:
      - runner.enrolling
      - runner.confirmed
      - runner.heartbeat
      - runner.offline
      - runner.rotated
      - runner.revoked
    x-neotask-json-recovery-path: /api/agent/v1/runners/{runnerRef}/events
    x-neotask-sse-path: /api/agent/v1/runners/{runnerRef}/events/stream
    x-neotask-mcp-resource: neotask://agent/v1/runners/{runnerRef}/events
    x-neotask-source-of-truth: site_runner_event_log
    x-neotask-cursor:
      mode: opaque
      replayWindow: 24h
      deduplicationKey: eventRef
  neotask_agent_v1_integrations_connectionRef_events:
    address: neotask.agent.v1.integrations.{connectionRef}.events
    description: integration events. Read the JSON recovery path before reconnecting
      an SSE client.
    parameters:
      connectionRef:
        description: Tenant-scoped opaque reference supplied by the authenticated agent.
        schema:
          type: string
          minLength: 1
          maxLength: 256
    messages:
      neotask_agent_v1_integrations_connectionRef_eventsEvent:
        $ref: "#/components/messages/neotask_agent_v1_integrations_connectionRef_events\
          Event"
    x-neotask-status: planned
    x-neotask-launch-state: live
    x-neotask-event-types:
      - integration.attempt_created
      - integration.connected
      - integration.attached
      - integration.reconnect_required
      - integration.revoked
    x-neotask-json-recovery-path: /api/agent/v1/integrations/connections/{connectionRef}/events
    x-neotask-sse-path: /api/agent/v1/integrations/connections/{connectionRef}/events/stream
    x-neotask-mcp-resource: neotask://agent/v1/integrations/{connectionRef}/events
    x-neotask-source-of-truth: site_integration_event_log
    x-neotask-cursor:
      mode: opaque
      replayWindow: 24h
      deduplicationKey: eventRef
  neotask_agent_v1_automations_automationRef_events:
    address: neotask.agent.v1.automations.{automationRef}.events
    description: automation events. Read the JSON recovery path before reconnecting
      an SSE client.
    parameters:
      automationRef:
        description: Tenant-scoped opaque reference supplied by the authenticated agent.
        schema:
          type: string
          minLength: 1
          maxLength: 256
    messages:
      neotask_agent_v1_automations_automationRef_eventsEvent:
        $ref: "#/components/messages/neotask_agent_v1_automations_automationRef_eventsE\
          vent"
    x-neotask-status: planned
    x-neotask-launch-state: live
    x-neotask-event-types:
      - automation.created
      - automation.updated
      - automation.run_started
      - automation.run_completed
      - automation.failed
    x-neotask-json-recovery-path: /api/agent/v1/automations/{automationRef}/events
    x-neotask-sse-path: /api/agent/v1/automations/{automationRef}/events/stream
    x-neotask-mcp-resource: neotask://agent/v1/automations/{automationRef}/events
    x-neotask-source-of-truth: site_automation_event_log
    x-neotask-cursor:
      mode: opaque
      replayWindow: 24h
      deduplicationKey: eventRef
  neotask_agent_v1_mail_companyRef_events:
    address: neotask.agent.v1.mail.{companyRef}.events
    description: coordination_mail events. Read the JSON recovery path before
      reconnecting an SSE client.
    parameters:
      companyRef:
        description: Tenant-scoped opaque reference supplied by the authenticated agent.
        schema:
          type: string
          minLength: 1
          maxLength: 256
    messages:
      neotask_agent_v1_mail_companyRef_eventsEvent:
        $ref: "#/components/messages/neotask_agent_v1_mail_companyRef_eventsEvent"
    x-neotask-status: planned
    x-neotask-launch-state: live
    x-neotask-event-types:
      - mail.membership_requested
      - mail.identity_bound
      - mail.message_sent
      - mail.message_delivered
      - mail.message_read
      - mail.handoff_sent
      - mail.identity_revoked
    x-neotask-json-recovery-path: /api/agent/v1/mail/events
    x-neotask-sse-path: /api/agent/v1/mail/events/stream
    x-neotask-mcp-resource: neotask://agent/v1/mail/{companyRef}/events
    x-neotask-source-of-truth: site_mail_event_log
    x-neotask-cursor:
      mode: opaque
      replayWindow: 24h
      deduplicationKey: eventRef
operations:
  neotask_agent_v1_runs_runRef_eventsReceive:
    action: receive
    channel:
      $ref: "#/channels/neotask_agent_v1_runs_runRef_events"
    summary: Receive chat events
    description: Receive chat events. Reconnect with the same opaque cursor
      namespace using Last-Event-ID, or recover through
      /api/agent/v1/runs/{runRef}/events.
    messages:
      - $ref: "#/components/messages/neotask_agent_v1_runs_runRef_eventsEvent"
    x-neotask-json-recovery-path: /api/agent/v1/runs/{runRef}/events
    x-neotask-sse-path: /api/agent/v1/runs/{runRef}/events/stream
    x-neotask-last-event-id: The same opaque after-exclusive cursor namespace is
      used for JSON recovery and SSE event ids.
  neotask_agent_v1_conversations_conversationRef_turns_turnRef_eventsReceive:
    action: receive
    channel:
      $ref: "#/channels/neotask_agent_v1_conversations_conversationRef_turns_turnRef_\
        events"
    summary: Receive chat events
    description: Receive chat events. Reconnect with the same opaque cursor
      namespace using Last-Event-ID, or recover through
      /api/agent/v1/conversations/{conversationRef}/turns/{turnRef}/events.
    messages:
      - $ref: "#/components/messages/neotask_agent_v1_conversations_conversationRef_tur\
          ns_turnRef_eventsEvent"
    x-neotask-json-recovery-path: /api/agent/v1/conversations/{conversationRef}/turns/{turnRef}/events
    x-neotask-sse-path: /api/agent/v1/conversations/{conversationRef}/turns/{turnRef}/events/stream
    x-neotask-last-event-id: The same opaque after-exclusive cursor namespace is
      used for JSON recovery and SSE event ids.
  neotask_agent_v1_approvals_approvalRef_eventsReceive:
    action: receive
    channel:
      $ref: "#/channels/neotask_agent_v1_approvals_approvalRef_events"
    summary: Receive approvals events
    description: Receive approvals events. Reconnect with the same opaque cursor
      namespace using Last-Event-ID, or recover through
      /api/agent/v1/approvals/{approvalRef}/events.
    messages:
      - $ref: "#/components/messages/neotask_agent_v1_approvals_approvalRef_eventsEvent"
    x-neotask-json-recovery-path: /api/agent/v1/approvals/{approvalRef}/events
    x-neotask-sse-path: /api/agent/v1/approvals/{approvalRef}/events/stream
    x-neotask-last-event-id: The same opaque after-exclusive cursor namespace is
      used for JSON recovery and SSE event ids.
components:
  messages:
    neotask_agent_v1_runs_runRef_eventsEvent:
      name: neotask_agent_v1_runs_runRef_eventsEvent
      title: chat event
      summary: An ordered chat event envelope.
      contentType: application/json
      payload:
        $ref: "#/components/schemas/AgentEventEnvelope"
    neotask_agent_v1_conversations_conversationRef_turns_turnRef_eventsEvent:
      name: neotask_agent_v1_conversations_conversationRef_turns_turnRef_eventsEvent
      title: chat event
      summary: An ordered chat event envelope.
      contentType: application/json
      payload:
        $ref: "#/components/schemas/AgentEventEnvelope"
    neotask_agent_v1_approvals_approvalRef_eventsEvent:
      name: neotask_agent_v1_approvals_approvalRef_eventsEvent
      title: approvals event
      summary: An ordered approvals event envelope.
      contentType: application/json
      payload:
        $ref: "#/components/schemas/AgentEventEnvelope"
    neotask_agent_v1_runners_runnerRef_eventsEvent:
      name: neotask_agent_v1_runners_runnerRef_eventsEvent
      title: runner event
      summary: An ordered runner event envelope.
      contentType: application/json
      payload:
        $ref: "#/components/schemas/AgentEventEnvelope"
    neotask_agent_v1_integrations_connectionRef_eventsEvent:
      name: neotask_agent_v1_integrations_connectionRef_eventsEvent
      title: integration event
      summary: An ordered integration event envelope.
      contentType: application/json
      payload:
        $ref: "#/components/schemas/AgentEventEnvelope"
    neotask_agent_v1_automations_automationRef_eventsEvent:
      name: neotask_agent_v1_automations_automationRef_eventsEvent
      title: automation event
      summary: An ordered automation event envelope.
      contentType: application/json
      payload:
        $ref: "#/components/schemas/AgentEventEnvelope"
    neotask_agent_v1_mail_companyRef_eventsEvent:
      name: neotask_agent_v1_mail_companyRef_eventsEvent
      title: coordination_mail event
      summary: An ordered coordination_mail event envelope.
      contentType: application/json
      payload:
        $ref: "#/components/schemas/AgentEventEnvelope"
  schemas:
    AgentEventEnvelope:
      type: object
      additionalProperties: false
      required:
        - channel
        - eventVersion
        - eventRef
        - sequence
        - cursor
        - type
        - occurredAt
        - resourceGeneration
        - data
      properties:
        channel:
          type: string
          minLength: 1
          maxLength: 512
        eventVersion:
          type: integer
          const: 1
        eventRef:
          type: string
          minLength: 1
          maxLength: 256
        sequence:
          type: integer
          minimum: 1
        cursor:
          type: string
          minLength: 1
          maxLength: 1024
        runRef:
          type:
            - string
            - "null"
        conversationRef:
          type:
            - string
            - "null"
        turnRef:
          type:
            - string
            - "null"
        approvalRef:
          type:
            - string
            - "null"
        actorRef:
          type:
            - string
            - "null"
        type:
          type: string
          minLength: 1
          maxLength: 128
        occurredAt:
          type: string
          format: date-time
        resourceGeneration:
          type: integer
          minimum: 0
        data:
          type: object
          additionalProperties: true
x-neotask-source-of-truth: The durable Site owner named by each channel;
  approval events are projected from durable approval truth.
x-neotask-json-recovery: Every implemented stream has a bounded JSON recovery
  endpoint in the same opaque cursor namespace.
x-neotask-launch-state: live