✦
┌──────────┐ │ created │ └────┬─────┘ │ ┌────▼─────┐ │ running │ └────┬─────┘ │ ┌────▼──────────────┐ │ completed │ failed │ └───────────┘────────┘

Tasks API

Task lifecycle, events, polling, and cancellation.

┌────────────┐ │ ArchonTask │ ├────────────┤ │ id: UUID │ │ status: │ │ enum │ │ events: [] │ │ steps: [] │ └────────────┘
Developer Docs Archon iOS · Swift · SwiftUI API v1

Tasks API

Task lifecycle, events, polling, and cancellation.

Task Lifecycle

Each AI-generated action creates a task that progresses through a defined state machine:

┌──────────┐
│ created  │  ← Task instantiated, waiting to start
└────┬─────┘
     │ start()
┌────▼─────┐
│ running  │  ← AI is actively processing
└────┬─────┘
     │
     ├── complete() ──▶ ┌───────────┐
     │                  │ completed │  ← All steps finished
     │                  └───────────┘
     │
     ├── fail() ───────▶ ┌────────┐
     │                   │ failed │  ← Error occurred
     │                   └────────┘
     │
     └── cancel() ─────▶ ┌──────────┐
                         │ cancelled │  ← User cancelled
                         └──────────┘

Task States

📋
created
Task has been created and queued. The AI hasn't started processing yet. Duration: typically <100ms.
⚡
running
AI is actively working. The task has a list of steps that progress as work is done. Events stream in real time.
✅
completed
All steps finished successfully. The task's result is stored and accessible via the project's file tree.
❌
failed
An error occurred during processing. The errorMessage field contains details. Partial results may still be available.

Endpoints

Base Path: /rest/v1/tasks

GET /tasks?project_id=eq.{id}
List all tasks for a project. Returns an array of ArchonTask with nested events. Order by created_at.desc.
GET /tasks/:id
Fetch a single task with all events. Used to check status after reconnection.
POST /tasks/:id/cancel
Cancel a running task. The AI stops processing and the task moves to cancelled state. Partial results are preserved.

Task Events

Each task produces a stream of events that describe its progress:

struct TaskEvent: Codable, Identifiable {
    let id: UUID
    let taskId: UUID
    let type: EventType
    let message: String
    let metadata: [String: String]?
    let createdAt: Date
}

enum EventType: String, Codable {
    case stepStarted
    case stepCompleted
    case fileCreated
    case fileModified
    case error
    case info
}

Event Types

stepStarted
A new step in the task has begun. Includes step name in the message field (e.g., "Creating project structure").
stepCompleted
A step has finished. The task's progress counter increments.
fileCreated / fileModified
A file was created or modified. Metadata includes the file path and language.
error
An error occurred during this step. The task may continue or fail depending on severity.

Polling & Realtime

The app uses two strategies to track task progress:

SSE Streaming (Primary)
During active chat, task events arrive via the SSE stream from the chat endpoint. No polling needed.
Polling (Fallback)
If the SSE connection drops, the app polls GET /tasks/:id every 2 seconds until the task reaches a terminal state.
Supabase Realtime (Future)
WebSocket subscriptions on the tasks table for push-based updates without polling.

Cancellation

Users can cancel a running task from the UI. The cancel flow:

1. User taps Cancel
The app sends POST /tasks/:id/cancel.
2. Server signals AI
The Edge Function sends an interrupt to the AI model and stops processing.
3. Task moves to cancelled
The task status updates to cancelled. Any files already created are preserved in the project.