nativeturn

type Config struct {
	// TurnDeadline is the hard wall-clock ceiling on a single turn (belt 2),
	// terminating a still-running turn with a context deadline; must be > 0.
	TurnDeadline time.Duration
	// GraceWindow is how long an in-flight turn survives with no viewer attached
	// before it is cancelled (belt 1); a reattach inside the window keeps it
	// alive, and it must be > 0.
	GraceWindow time.Duration
	// JournalSize bounds the per-session replay journal (belt 3) to the most
	// recent events, oldest dropped first; zero or negative resolves to
	// DefaultJournalSize in New.
	JournalSize int
}

type Event struct {
	// Seq is the 1-based monotonic id of this event within its session's turn.
	Seq uint64
	// Update is the session/update notification as emitted by the turn, before any
	// per-viewer normalization.
	Update libacp.SessionNotification
}

type Registry struct {
	// contains filtered or unexported fields
}

type Result struct {
	// StopReason is the ACP stop reason the connected client's prompt resolves with.
	StopReason libacp.StopReason
	// Err is a genuine execution failure the client must see as a JSON-RPC error; nil
	// for a clean end or a cancellation (which resolves as StopReasonCancelled with no
	// error).
	Err error
	// Suspended marks a turn whose chain parked on a pending human approval:
	// not a failure (Err is nil), and status reads StateSuspended instead of
	// StateFinished until reaped.
	Suspended bool
	// ApprovalID is the durable approval a Suspended turn is parked on, communicated to
	// the client since StopReason cannot express it; empty unless Suspended.
	ApprovalID string
	// DroppedContentKinds are the prompt content kinds the turn could not forward to
	// the model, ridden on Result so a reattaching client still sees them.
	DroppedContentKinds []string
}

type Turn struct {
	// contains filtered or unexported fields
}

type TurnFunc func(ctx context.Context, emit func(ctx context.Context, n libacp.SessionNotification)) Result

type TurnStatus struct {
	SessionID libacp.SessionID `json:"sessionId"`
	StartedAt time.Time        `json:"startedAt"`
	// Deadline is the hard wall-clock time this turn is terminated at (belt 2).
	Deadline time.Time `json:"deadline"`
	// Viewers is how many viewers are attached right now (0 in StateGrace).
	Viewers int `json:"viewers"`
	// State is one of StateRunning / StateGrace / StateFinished.
	State string `json:"state"`
}

type Viewer interface {
	// ID uniquely identifies this viewer within a session; two viewers on one session
	// must not share an ID.
	ID() string

	// Deliver receives one turn event, in order (replayed backlog then live); it must
	// not block since it runs under the session lock, and its returned error is
	// advisory only.
	Deliver(ctx context.Context, ev Event) error
}