queue

type QueueFactory func(url string, maxRetries int) (TaskQueue, error)

type StreamChannel interface {
	// Publish appends a token chunk to the named channel.
	// Returns an error if the backend write fails — callers should log and continue.
	Publish(key, chunk string) error

	// Done signals end-of-stream and schedules cleanup on the named channel.
	// Returns an error if the backend write fails.
	Done(key string) error

	// Read blocks briefly for the next token chunk on the named channel.
	// Returns ("", nil) when no chunk is available yet, (StreamDone, nil) at end-of-stream.
	Read(ctx context.Context, key string) (string, error)
}

type StreamFactory func(url string) (StreamChannel, error)

type Task struct {
	ID     string
	Prompt string
	Meta   map[string]string // arbitrary key-value pairs (e.g. stream_key, attempt)
}

type TaskQueue interface {
	// Submit enqueues a task. meta carries optional key-value metadata
	// (e.g. "stream_key" for SSE streaming). Returns the assigned task ID.
	Submit(ctx context.Context, prompt string, meta map[string]string) (string, error)

	// Poll blocks briefly for the next available task.
	// Returns (nil, nil) when the queue is empty so callers can check ctx.Done().
	Poll(ctx context.Context) (*Task, error)

	// Ack marks a task as successfully completed and stores the result with token usage.
	// The full Task is required so implementations can store the result under the original
	// task ID when the task was retried (preserving the ID the flow controller tracks).
	// Returns an error if the backend operation fails — callers should log and handle it.
	Ack(task Task, result string, usage TokenUsage) error

	// Nack marks a task as failed. Implementations handle retry and dead-letter logic.
	// Returns an error if the backend operation fails — callers should log and handle it.
	Nack(task Task, reason string) error

	// Results returns completed task results for the given set of task IDs.
	// Used by the operator to check whether running flow steps have finished.
	Results(ctx context.Context, taskIDs []string) ([]TaskResult, error)

	// Cancel abandons the given tasks. For each task ID the implementation should:
	//   - XDEL the stream entry (prevents unpolled tasks from being picked up)
	//   - XACK the entry (removes it from the PEL if already polled)
	//   - Store a "run cancelled" error result so collectResults doesn't hang
	// Best-effort: errors are logged but do not fail the caller.
	Cancel(ctx context.Context, taskIDs []string) error

	// Close releases any resources held by the implementation.
	Close()
}

type TaskResult struct {
	TaskID string
	Output string
	Error  string // non-empty when the task reached the dead-letter queue
	Usage  TokenUsage
}

type TokenUsage struct {
	InputTokens  int64
	OutputTokens int64
}